codearbiter
When you can't trust yourself with your code base, trust Arbiter.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026. Its scripts were only partly scanned.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/arbiterForge/codeArbiter with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/arbiterForge/codeArbiter'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/arbiterforge-codearbiter)HTML
<a href="/listings/arbiterforge-codearbiter"><img src="/api/listings/arbiterforge-codearbiter/badge.svg" alt="findsafeskills safety rating" /></a>Install
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/marketplace.json · Manifest · 22 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- {
- "name": "codearbiter",
- "owner": { "name": "arbiterForge" },
- "metadata": {
- "description": "codeArbiter: a marketplace of two sibling plugins — the ca governance/orchestration layer for Claude Code, plus ca-sandbox, an infrastructure plugin that runs untrusted repos in ephemeral isolated containers."
- },
- "plugins": [
- {
- "name": "ca",
- "source": {
- "source": "git-subdir",
- "url": "https://github.com/arbiterForge/codeArbiter.git",
- "path": "plugins/ca",
- "ref": "ca-marketplace"
- }
- },
- {
- "name": "ca-sandbox",
- "source": "./plugins/ca-sandbox"
- }
- ]
- }
README.md · README · 529 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- <div align="center">
- <img src="docs/readme-hero.webp" alt="codeArbiter. Hard gates for agentic coding." width="100%">
- **Open-source governance and hard gates for AI coding agents across Claude Code, Codex CLI, and Pi.**
- codeArbiter is a repository-owned governance layer for tests, reviews, security checks, decisions,
- and durable project context. You decide. codeArbiter enforces.
- <img alt="Claude Code plugin" src="https://img.shields.io/badge/Claude_Code-plugin-d97757">
- <img alt="Codex plugin" src="https://img.shields.io/badge/OpenAI_Codex-plugin-10a37f">
- <img alt="Pi Feature Forge preview" src="https://img.shields.io/badge/ca--pi-Feature_Forge_preview-d97757">
- <img alt="version 3.8.9" src="https://img.shields.io/badge/version-3.8.9-2b7489">
- <img alt="core lanes" src="https://img.shields.io/badge/core_lanes-17-555">
- <img alt="skills" src="https://img.shields.io/badge/skills-22-555">
- <img alt="agents" src="https://img.shields.io/badge/agents-20-555">
- <img alt="license AGPL v3" src="https://img.shields.io/badge/license-AGPL_v3-3da639">
- [Start learning](https://codearbiter.dev/learn/)
- ·
- [Install](https://codearbiter.dev/getting-started/install/)
- ·
- [Browse the reference](https://codearbiter.dev/reference/)
- <sub>Install it globally. It stays dormant until a repository explicitly opts in.</sub>
- </div>
- ## Agentic coding, with a record
- codeArbiter is for teams and power users who let coding agents do consequential work and need more
- than “the model said it passed.” Every request enters a named lane. The lane defines the evidence it
- must produce, the reviewers it must dispatch, and the conditions that stop it.
- This repository contains four sibling plugins:
- - `ca` for Claude Code, `ca-codex` for Codex CLI, and `ca-pi` for Pi are the three governance hosts.
- - `ca-sandbox` is the isolated local-Codespace infrastructure plugin.
- The three governance hosts are generated from one shared surface and use one checked-in
- `.codearbiter/` project store. A repository can move between hosts without losing its specs, plans,
- ADRs, tasks, decisions, or audit history.
- codeArbiter will not:
- - write feature code before the required failing test exists;
- - commit on a red suite or outside the commit gate;
- - resolve a `[CONFIRM-NN]` question by guessing;
- - silently reconcile a conflict between the rules, the docs, and the code; or
- - push directly to the default branch or merge without the user.
- The gates scale to the work. A prose edit takes the small docs lane. A security-sensitive feature
- takes the full spec, test-first, review, and PR path.
- The Codex path was live-verified on **Codex CLI 0.144.1** with trusted SessionStart injection and a
- real `[H-03]` PreToolUse block. The dated
- [Claude Code + Codex evidence](https://codearbiter.dev/getting-started/claude-code-and-codex/)
- separates continuously verified packaging from the live checks that require a model-backed turn.
- ## See it catch something
- The landing page includes a
- [faithful replay of a shipped hook invocation](https://codearbiter.dev/#proof).
- It invokes the real `pre-bash.py` guard, records the source digest, proves the blocked command never
- ran, and preserves the exact stderr and audit effect. It does not pretend that a direct hook replay
- proves host discovery or trust.
- The operating loop looks like this:
- ```text
- you /ca:fix the statusline keeps running the old version after an update
- arbiter route to the regression-test-first fix lane
- failing test -> minimal fix -> focused proof -> full verification
- you /ca:commit
- arbiter permission -> branch -> tests -> behavioral proof -> diff review
- selective stage -> commit
- you /ca:pr
- arbiter reviewer fleet challenges the exact diff
- BLOCK findings are resolved before the draft PR can advance
- ```
- The user owns the decision. The repository keeps the evidence.
- ## Get running
- Choose the adapter for the coding host you already use. The
- [host chooser](https://codearbiter.dev/getting-started/choose-your-host/) covers
- stability, command syntax, trust, and platform differences.
- | Host | Adapter | Command form | Status |
- |---|---|---|---|
- | Claude Code | `ca` | `/ca:feature` | Stable |
- | Codex CLI | `ca-codex` | `$ca-feature` | Stable |
- | Pi | `ca-pi` | `/ca-feature` | Feature Forge `preview` |
- **Prerequisites:** Python 3 on `PATH` and `git config user.email` set. ADR lifecycle proof requires
- Git 2.45.0+ with `--no-lazy-fetch` on all three governance hosts; unavailable flag support blocks
- verification with an upgrade prerequisite, never an implicit fetch fallback. Pi also requires Node.js
- 22.19+. If Python is missing, Pi installs its final wrappers but blocks mutating calls and points to
- `/ca-doctor`; Claude Code and Codex surface an interpreter breadcrumb instead of silently claiming
- governance is active. The [compatibility matrix](https://codearbiter.dev/getting-started/compatibility/)
- defines the supported native Git/runtime and linked-worktree boundary; mixed Windows Git and WSL Git
- over one shared repository are not supported.
- ### Claude Code
- ```text
- /plugin marketplace add arbiterForge/codeArbiter
- /plugin install ca@codearbiter
- ```
- Approve the normal plugin trust prompt, open the target repository, and continue with
- `/ca:init`.
- ### Codex CLI
- The public GitHub-slug flow is **available now**.
- The current adapter version is read from `plugins/ca-codex/.codex-plugin/plugin.json`.
- The dated end-to-end public-install record discovered `ca-codex 0.2.4` from release `v2.8.13`.
- Current packaging and shared-core parity are continuously verified, while that historical record
- stays labeled rather than being promoted to evidence for a newer adapter:
- ```text
- codex plugin marketplace add arbiterForge/codeArbiter --ref ca-codex-marketplace
- codex plugin add ca-codex@codearbiter
- ```
- The `ca-codex-marketplace` branch is the promoted catalog. Its entry pins an
- immutable `ca-codex-dist-v<version>` Git tag holding the exact qualified release
- archive, including the native artifact engine; `main` remains the development
- source tree and is not a substitute for the promoted binary-bearing
- distribution. (An `@arbiterforge/ca-codex` npm channel is planned but deferred,
- ADR-0040.)
- If `codearbiter` was previously registered without
- `--ref ca-codex-marketplace`, `marketplace upgrade` keeps that default-branch
- registration and does not migrate it to the promoted binary-bearing channel. Remove and
- re-add the marketplace once, then reinstall the plugin:
- ```text
- codex plugin remove ca-codex@codearbiter
- codex plugin marketplace remove codearbiter
- codex plugin marketplace add arbiterForge/codeArbiter --ref ca-codex-marketplace
- codex plugin add ca-codex@codearbiter
- ```
- Open `/hooks`, review and trust the `ca-codex` handlers, then start a fresh task. Run `$ca-init` and
- `$ca-doctor`.
- For development against an unpublished checkout:
- ```text
- git clone https://github.com/arbiterForge/codeArbiter
- cd codeArbiter
- codex plugin marketplace add .
- codex plugin add ca-codex@codearbiter
- ```
- ### Pi
- > [!NOTE]
- > `ca-pi` is a Feature Forge `preview`. It is available for real use now, and you are welcome to
- > install it, use it in repositories, and report what you find. Its automated and hosted promotion
- > matrix is green; broader real-world evidence is still required before codeArbiter claims
- > 100% validation or stable status.
- The quickest install is the npm channel: `pi install npm:@arbiterforge/ca-pi` (ADR-0029). For the
- reproducible pinned install, list the independently versioned tags, choose one exact result, then
- inspect the installed package, grant project trust, and start a fresh session:
- ```sh
- git ls-remote --tags --refs https://github.com/arbiterForge/codeArbiter.git "ca-pi-v*"
- pi install git:github.com/arbiterForge/codeArbiter@ca-pi-v<version>
- pi list
- pi config
- ```
- Replace `<version>` with the numeric suffix from the chosen tag while retaining the full
- `ca-pi-v...` tag in the install source. The Git-tag install carries no native artifact engine, so
- it is a partial install that cannot author typed HTML specs and plans; use the npm channel for
- that.
- Pi 1.5.0 is the supported host for this release line. Generated aliases use `/ca-*`;
- `/skill:ca-*` is the host-native fallback. Every `ca-pi-v*` tag is also published to npm as
- `npm:@arbiterforge/ca-pi` with provenance (ADR-0029); the pinned Git tag remains the reproducible
- install. The [Pi runbook](./docs/pi-parity-testing.md) covers isolated install, trust, verification,
- shared-state continuity, and uninstall.
- ### Protect the first repository
- Use a disposable Git repository for the first run. Add at least one meaningful source file, then
- invoke the host-native forms below:
- | Outcome | Claude Code | Codex CLI | Pi |
- |---|---|---|---|
- | Scaffold project state | `/ca:init` | `$ca-init` | `/ca-init` |
- | Prove enforcement | `/ca:doctor` | `$ca-doctor` | `/ca-doctor` |
- | Read live state | `/ca:status` | `$ca-status` | `/ca-status` |
- `init` creates `.codearbiter/` and routes an existing codebase to `create-context` or a greenfield
- project to `decompose`. `doctor` must report a healthy interpreter, current payload, and H-03
- live-fire probe before you treat the repository as governed.
- Follow the complete
- [first-repository walkthrough](https://codearbiter.dev/getting-started/quickstart/)
- for expected output, proof, and recovery.
- ## Practice before using your own repository
- [Arbiter Academy](https://arbiterforge.github.io/arbiter-academy/) is an optional practice course for
- codeArbiter. It starts in a personal fork of the Academy repository, so you can make real commits,
- inspect governed evidence, and recover from a failed attempt without placing your own project at risk.
- The Academy website is the lesson surface. Each published lesson identifies whether an action belongs
- in the browser, native terminal, active harness, or with the agent, then provides a copyable command,
- the result to expect, the evidence to inspect, and a safe recovery path. Start there when you want to
- learn the workflow before protecting a production repository.
- ## The docs are the operating manual
- The site is designed as a continuous path from first contact to source-backed operation:
- | Need | Start here | You finish able to... |
- |---|---|---|
- | Understand the promise | [What is codeArbiter](https://codearbiter.dev/overview/) | explain command, route, dispatch, gate, and ship |
- | Choose and install a host | [Start](https://codearbiter.dev/getting-started/choose-your-host/) | install, trust, activate, and verify one adapter |
- | Learn in order | [Learning path](https://codearbiter.dev/learn/) | progress from foundation through the power-user capstone |
- | Run daily work | [Workflows](https://codearbiter.dev/guides/feature-lane/) | select and complete the smallest correct lane |
- | Understand the model | [Concept map](https://codearbiter.dev/concepts/) | trace routing, decisions, context, review, and audit evidence |
- | Diagnose a problem | [Troubleshooting](https://codearbiter.dev/guides/troubleshooting/) | follow a symptom to a deterministic recovery |
- | Look up exact behavior | [Reference](https://codearbiter.dev/reference/) | inspect generated commands, skills, agents, hooks, and configuration |
- | Evaluate preview work | [Feature Forge](https://codearbiter.dev/feature-forge/overview/) | opt in, verify the off switch, and understand the promotion bar |
- Command, skill, agent, and hook-gate reference pages are generated from shipped source on every site
- build. Hand-authored guides teach the workflow; generated pages define the exact current surface.
- ## How governance works
- ```mermaid
- flowchart LR
- I["host-native command"] --> R["owning skill"]
- R --> A["author or operator action"]
- A --> V["tests + focused proof"]
- V --> F["matched reviewer fleet"]
- F --> G{"gate clear?"}
- G -->|no| X["named finding or user decision"]
- X --> A
- G -->|yes| P["selective commit + draft PR"]
- ```
- Activation is explicit and per repository. Claude Code and Codex check
- `.codearbiter/CONTEXT.md` at SessionStart. Pi checks the same file through its `session_start`
- extension event and also requires affirmative project trust. Without `arbiter: enabled`, the global
- install is dormant: no repository persona, no repository gates, and no governance row.
- The project record lives beside the code:
- ```text
- .codearbiter/
- ├── CONTEXT.md activation, vocabulary, maturity, current objective
- ├── context/ native HTML knowledge (new default)
- ├── work/ portable project ID and native work items (new default)
- ├── tech-stack.md legacy Markdown knowledge
- ├── coding-standards.md legacy Markdown knowledge
- ├── security-controls.md security policy; scope blocks persist after conversion
- ├── open-tasks.md legacy work board (existing or explicit Markdown)
- ├── open-questions.md unresolved [CONFIRM-NN] decisions
- ├── decisions/ numbered ADRs
- ├── specs/ and plans/ approved intent and execution
- ├── sprint-log.md SMARTS-scored autonomous decisions
- ├── checkpoints/ periodic reviewer sweeps
- ├── audits/ and reports/ assembled evidence
- └── overrides.log append-only sanctioned bypass record
- ```
- The [.codearbiter directory reference](https://codearbiter.dev/codearbiter-directory/)
- explains who creates, reads, and updates every artifact, plus its recovery rules.
- ### The hard gates
- - No feature code before `tdd` Phase 1 completes.
- - No commit outside `commit-gate`, and never with a red suite.
- - No `[CONFIRM-NN]` resolved by guessing.
- - No silent reconciliation of rule conflicts; route to `/ca:conflict`.
- - No raw secret stored in the repository, logs, images, or prompts.
- - No direct write to the default branch and no force-push.
- - No ADR outside `/ca:adr`, with explicit user attribution.
- - Every `/ca:override`, `mode --dangerous`/`mode --ops` entry/exit, and sprint auto-decision is durable and attributable.
- - H-18 activation protection has no in-session override path; disabling a repository requires an
- external editor and an explicit audit record.
- Security and audit-trail correctness outrank data integrity, maintainability, performance, and
- velocity. A non-obvious tradeoff cites the level at which it was made.
- ### SMARTS: bounded autonomy, explicit reasoning
- SMARTS evaluates Scalable, Maintainable, Available, Reliable, Testable, and Securable properties.
- Each option gets a concrete verdict and evidence, followed by a `strong`, `moderate`, or `tied`
- recommendation. The user still decides.
- `/ca:sprint` uses the same lenses for bounded non-hard decisions and writes every call to
- `.codearbiter/sprint-log.md` with a confidence flag. Security boundaries, irreversible operations,
- gate bypasses, merges, and unresolved questions remain true stops. See
- [SMARTS](https://codearbiter.dev/concepts/smarts/) and
- [autonomous sprints](https://codearbiter.dev/guides/autonomous-sprints/).
- ## Core lanes
- Choose the workflow first. The canonical lanes keep daily work compact; advanced operations and
- compatibility routes remain available in the complete reference.
- <!-- core-lane-chooser:start -->
- | Workflow | Choose | Use it for |
- |---|---|---|
- | Initialize | `/ca:init` | Create or inspect the repository-owned state store |
- | Change | `/ca:feature`, `/ca:sprint`, `/ca:fix`, `/ca:refactor`, `/ca:chore`, `/ca:spike`, `/ca:add-dep` | Build, repair, restructure, explore, or change the supply chain through the owning gate |
- | Review | `/ca:review` | Run the reviewer fleet over a diff or bounded path |
- | Decide | `/ca:adr` | Record a numbered, user-attributed architecture decision |
- | Ship | `/ca:commit`, `/ca:pr`, `/ca:release` | Commit, stage a pull request, or prepare an authorized release |
- | Operate | `/ca:status`, `/ca:task`, `/ca:doctor`, `/ca:override` | Inspect state, manage the task board, verify enforcement, or log an allowed bypass |
- <!-- core-lane-chooser:end -->
- [Complete command reference](https://codearbiter.dev/reference/commands/) includes
- advanced operations, compatibility routes, internal protocols, deprecation guidance, and host
- availability. The generated host catalogs remain inspectable in
- [`plugins/ca/COMMANDS.md`](./plugins/ca/COMMANDS.md),
- [`plugins/ca-codex/COMMANDS.md`](./plugins/ca-codex/COMMANDS.md), and
- [`plugins/ca-pi/COMMANDS.md`](./plugins/ca-pi/COMMANDS.md). Claude Code includes `statusline` and
- `prune`; Codex intentionally omits both. Pi omits `statusline` and uses native compaction through
- its `prune` route.
- ## Trust and host boundaries
- The blocking enforcement core is local and Python-stdlib-only. It reads repository files and local
- Git state. It does not send repository content to a codeArbiter account; there is no hosted
- codeArbiter control plane.
- Two background reads are separate from blocking evaluation:
- - SessionStart may run a detached, read-only `git fetch` against the repository's configured remote
- to report hygiene state.
- - A once-daily, fail-silent update check reads the public GitHub Releases API. It sends no repository
- content and never applies an update.
- The optional `/ca:sprint --farm` preview is a distinct opt-in network feature. It sends byte-capped,
- secret-redacted task context to the OpenAI-compatible endpoint you configure and is inert without
- the flag and provider key.
- See [Enforcement and Security](https://codearbiter.dev/enforcement/) and the
- [Hooks Reference](https://codearbiter.dev/hooks/) for the exact event, read,
- write, block, and network contract.
- ### Pi operational contract
- `ca-pi` installs a rich footer in interactive parent sessions. The governance row appears only when
- the repository is enabled and affirmatively trusted; rate-window telemetry is omitted rather than
- fabricated. Execute mode asks before governed mutations and external side effects. Plan mode is
- read-only except for the current canonical spec, plan, and plan ledger.
- Background jobs are bounded and session-only, and are never restored from Pi session entries.
- Unverified cleanup marks the manager unhealthy, blocks later launches, and points to `/ca-doctor`.
- Footer, permission, plan, and background surfaces are parent-interactive only and never recurse into
- hardened children.
- The human-readable generated catalog is `plugins/ca-pi/SKILLS.md`. On a cold checkout, the platform
- aggregate reports `missing_prerequisite` and directs the operator to
- `npm --prefix plugins/ca-pi/tools ci --ignore-scripts`; it never installs dependencies on the
- verification path.
- ## Feature Forge
- <div align="center">
- <img src="docs/feature-forge.webp" alt="A dark machined gate under controlled amber heat: preview work accumulating evidence before promotion." width="100%">
- </div>
- Preview features are built, tested, and shipping, but they remain opt-in and dormant until
- real-world evidence earns stable status. A preview label never weakens a hard gate and never hides
- spending or trust requirements.
- | Feature | Opt-in | Promotion evidence still needed |
- |---|---|---|
- | `ca-pi` | install a pinned `ca-pi-v*` Git tag | diverse real repositories, providers, terminals, and workflows |
- | Live transcript pruning | `CODEARBITER_PRUNE=dry` | real-session context savings and false-positive data |
- | Pluggable execution farm | `/ca:sprint --farm` | per-task pass rates, cost, and gate-escape evidence |
- | `ca-sandbox` | install the sibling plugin | real untrusted repositories and interactive `--with-claude` use |
- The source-backed
- [live Forge catalog](https://codearbiter.dev/feature-forge/whats-in-the-forge/)
- names every opt-in, off switch, dependency, trust boundary, and promotion signal.
- The farm preview uses one checked-in `farm.js` backend across supported hosts. A Pi-native embedded
- farm worker is a future spike, not a shipping dependency or second engine. `ca-pi` distributes as
- the pinned Git tag plus the CI-published `npm:@arbiterforge/ca-pi` package (ADR-0029).
- ## Operator details
- <details>
- <summary><strong>Claude Code statusline</strong></summary>
- Run `/ca:statusline` to install the optional token-aware statusline.
- <div align="center">
- <img alt="Annotated codeArbiter statusline" src="./site/public/diagrams/statusline.png" width="880">
- </div>
- Folder, Git state, rate limits, token use, cost, context headroom, model, effort, and session age
- render globally. The governance row activates only in an enabled repository.
- Run `/ca:statusline uninstall` to restore the previous statusline, or remove the
- codeArbiter setting when no previous line existed. Running `/ca:statusline install`
- again refreshes the installed path and preserves the backup; it does not uninstall.
- </details>
- <details>
- <summary><strong>Updates and configuration</strong></summary>
- Update the Claude marketplace explicitly:
- ```text
- /plugin marketplace update codearbiter
- ```
- The operator-facing environment-variable catalog, defaults, accepted values, safety boundaries,
- and verification steps live in the
- [Configuration Reference](https://codearbiter.dev/reference/configuration/).
- Release notes are in the [Changelog](https://codearbiter.dev/changelog/).
- </details>
- <details>
- <summary><strong>Turn it off or uninstall it</strong></summary>
- A repository without `.codearbiter/CONTEXT.md` carrying `arbiter: enabled` is dormant. Remove `ca`
- with Claude Code's plugin manager, run `codex plugin remove ca-codex@codearbiter` for Codex, or use
- `pi remove` with the pinned Git source for Pi. The repository-owned `.codearbiter/` record survives,
- so another supported host can keep using it.
- Follow [Uninstall and Disable](https://codearbiter.dev/guides/uninstalling/) for
- host-specific removal, pinning, and verification.
- </details>
- ## Repository map
- ```text
- .claude-plugin/marketplace.json Claude marketplace
- .agents/plugins/marketplace.json Codex marketplace
- core/ canonical shared policy and generated surface
- plugins/ca/ Claude Code governance host
- plugins/ca-codex/ Codex governance host
- plugins/ca-pi/ Pi governance host (Feature Forge preview)
- plugins/ca-sandbox/ isolated local-Codespace plugin
- site/ Astro/Starlight documentation product
- docs/ architecture, parity runbooks, reports, and media
- .codearbiter/ this repository's own governed project state
- ```
- `plugins/ca/` contains the always-on orchestrator, public commands, gated skills, dispatched agents,
- hooks, and farm tooling. The [architecture docs](./docs/architecture.md), [parity ledger](./docs/parity.md),
- and [full hook contract](./docs/hooks.md) are the maintainer entry points.
- <details>
- <summary><strong>OpenAI Build Week submission record</strong></summary>
- codeArbiter predates OpenAI Build Week. The submitted work, added July 13 through July 21, 2026,
- delivered the Pi host plus a corrective campaign over the shared governance core. It is consolidated
- in [PR #313](https://github.com/arbiterForge/codeArbiter/pull/313) at verified implementation head
- `ec64809c1b6c32f69e3d9787ab205f7bbd563d50`.
- Codex was the primary development and orchestration environment. GPT-5.6 was used to design and
- implement the Pi adapter, investigate live failures, review older paths, and consolidate corrections
- across permissions, Windows process-tree cleanup, provenance, audit integrity, generated-source
- drift, CI contracts, and documentation.
- The final candidate passed the six Pi platform cells — both then-supported Pi versions on Windows,
- macOS, and Linux (versions recorded in the linked artifacts), plus security analysis, CodeQL, shared-core contracts, generated-surface contracts, and
- the repository's final verifier. Sanitized evidence:
- - [`docs/reports/pi-support/promotion.md`](docs/reports/pi-support/promotion.md)
- - [`docs/reports/pi-support/promotion.json`](docs/reports/pi-support/promotion.json)
- - [`docs/pi-parity-testing.md`](docs/pi-parity-testing.md)
- Judge quick start for the immutable candidate:
- ```text
- pi install git:github.com/arbiterForge/codeArbiter@ec64809c1b6c32f69e3d9787ab205f7bbd563d50
- pi list
- pi config
- ```
- Inspect the repository, grant project trust, start a fresh Pi session, then run `/ca-init` and
- `/ca-doctor`.
- </details>
- ## Project history
- codeArbiter v2 is a ground-up rebuild of the earlier vendored `.agents/` framework as a native,
- multi-host plugin system. The complete record is in [`CHANGELOG.md`](./CHANGELOG.md) and the
- [site changelog](https://codearbiter.dev/changelog/). The v1 implementation
- remains available in early repository history.
- ## License and contributions
- codeArbiter is licensed under the
- [GNU Affero General Public License v3.0](./LICENSE) (AGPLv3). You may use, study, modify, and
- redistribute it under those terms. AGPLv3 section 13 also applies when a modified version is run as a
- network service.
- The AGPLv3 transition applies from v2.6.0 forward. Earlier releases remain under the license they
- shipped with.
- **Open source.** codeArbiter is available under AGPLv3 for open-source use, free of charge.
- **Commercial licensing.** SUaDtL retains the copyright and reserves the right to offer the project
- under separate proprietary terms. Commercial licenses are not being offered at this time. Inquiries
- may be made through GitHub if AGPLv3 does not fit a use case.
- **Contributions.** No Contributor License Agreement is currently in force. See
- [`CLA.md`](./CLA.md) for its status and maintainer handling. A future agreement
- requires legal review and separate explicit assent; maintainers must not infer
- additional proprietary relicensing rights from the retired template.
- <div align="center">
- <sub>Built for Claude Code, Codex CLI, and Pi.</sub>
- </div>
plugins/ca-sandbox/tools/supply-chain.test.ts · Bundled script · 381 lines · 1 finding marked
- /**
- * supply-chain.test.ts — structural supply-chain guards for the ca-sandbox driver.
- *
- * Two tribunal findings are locked down here, both about EXTERNAL BYTES that
- * ca-sandbox would otherwise pull in unpinned:
- *
- * #401 (secrets-supply-002) — no ca-sandbox runtime path may pipe
- * network-fetched bytes into a shell. `defaultEnsureNixpacks` used to run
- * `bash -c "curl -fsSL https://nixpacks.com/install.sh | bash"` on the
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 9 on GitHub
- * developer host, BEFORE any container boundary exists. nixpacks is a
- * documented prerequisite (README / SKILL / command description all say so),
- * so the missing-prerequisite path now FAILS CLOSED to the pre-existing
- * generated-Dockerfile fallback and tells the user to install nixpacks.
- *
- * #402 (secrets-supply-004) — every external container image reference must be
- * bound to a reviewed content digest (`name:tag@sha256:<64 hex>`), so a retag
- * or registry compromise cannot silently swap executable code into a sandbox
- * build — least of all into the `--with-claude` box, which co-runs the base
- * image with CLAUDE_CODE_OAUTH_TOKEN.
- *
- * These are STRUCTURAL tests on purpose: `defaultEnsureNixpacks` and the image
- * constants are defaults that every other suite stubs out, so the real path had
- * ZERO coverage. A structural scan cannot be stubbed past — it reads the shipped
- * bytes. Test files are exempt from the scan (lifecycle.test.ts deliberately
- * hardcodes `alpine/git:latest` when driving docker directly), which is why the
- * scan enumerates production sources explicitly rather than globbing everything.
- */
- import { describe, it, expect } from "vitest";
- import { readFileSync, readdirSync } from "node:fs";
- import path from "node:path";
- import { fileURLToPath } from "node:url";
- import {
- defaultEnsureNixpacks,
- generateDockerfile,
- type RunResult,
- } from "./build.ts";
- import { CLONE_IMAGE } from "./create.ts";
- import { CLAUDE_BASE_IMAGE, buildClaudeImageDockerfile } from "./claude-inside.ts";
- const TOOLS_DIR = path.dirname(fileURLToPath(import.meta.url));
- /**
- * The production surface of the driver: every shipped source file plus the
- * committed esbuild bundle (`sandbox.js` — the bytes that actually run on a
- * user's machine). Test files, fixtures and the vitest config are NOT production
- * code and are deliberately excluded.
- */
- function productionFiles(): string[] {
- const entries = readdirSync(TOOLS_DIR, { withFileTypes: true });
- const files = entries
- .filter((e) => e.isFile())
- .map((e) => e.name)
- .filter((n) => n.endsWith(".ts") || n === "sandbox.js")
- .filter((n) => !n.endsWith(".test.ts"))
- .filter((n) => n !== "vitest.config.ts");
- return files.sort().map((n) => path.join(TOOLS_DIR, n));
- }
- function rel(file: string): string {
- return path.relative(TOOLS_DIR, file).replace(/\\/g, "/");
- }
- /** A `sha256:<64 hex>` digest binding, optionally preceded by a tag. */
- const DIGEST_PINNED = /@sha256:[0-9a-f]{64}\b/;
- /**
- * Does this string name an image PULLED FROM A REGISTRY (and therefore in need
- * of a digest pin), as opposed to a locally built one? An external ref carries a
- * registry namespace (`alpine/git`) or a tag (`node:22-slim`); the driver's own
- * `ca-sbx` tag prefix carries neither and has nothing upstream to pin.
- */
- function isExternalImageRef(ref: string): boolean {
- return ref.includes("/") || ref.includes(":");
- }
- // --------------------------------------------------------------------------
- // the digest scanner (#402 AC-2)
- // --------------------------------------------------------------------------
- //
- // This scanner reads JOINED FILE TEXT, never line-by-line. That is load-bearing:
- // every image constant in this driver is written with the value on its own
- // continuation line —
- //
- // export const CLONE_IMAGE =
- // "alpine/git:latest@sha256:...";
- //
- // — so a per-line rule that expects `const NAME = "<ref>"` on ONE line matches
- // none of the shipped declarations and is silently inert. `scannerSelfTest`
- // below locks that in: it runs these same rules against synthetic multi-line
- // sources and asserts they actually fire.
- /** 1-based line number of `index` within `src`. */
- function lineOf(src: string, index: number): number {
- return src.slice(0, index).split(/\r?\n/).length;
- }
- /**
- * A named image constant — `export const CLONE_IMAGE = "<ref>"`, the bundled
- * `var CLONE_IMAGE = "<ref>"` form, and (critically) the multi-line form where
- * the literal sits on the next line. `\s*` spans the newline; the value class
- * does not, so the literal itself is still single-line.
- */
- const IMAGE_CONST = /\b(?:const|let|var)\s+(\w*IMAGE\w*)\s*=\s*(["'`])([^"'`\n]*)\2/g;
- /**
- * A string literal that IS a namespaced registry reference (`ns/name:tag`) —
- * name-independent, so `const TRIVY = "aquasec/trivy:0.50.0"` and a bare argv
- * element `"alpine/git:latest"` are both caught even though neither is named
- * `*IMAGE*`. Requiring the `/` namespace is what keeps this free of false
- * positives: node builtin specifiers (`node:path`, `node:fs/promises`) and
- * docs placeholders (`host:container`, `1000:1000`) never match.
- *
- * Residual, accepted: an official-library image with no namespace and a
- * non-`latest` tag (`"node:22-slim"`) bound to a constant NOT named `*IMAGE*`
- * would evade this rule — `node:<builtin>` import specifiers are structurally
- * identical to it. Today's two such images are both `*IMAGE*`-named (caught by
- * IMAGE_CONST) and additionally asserted by name in the tests below.
- */
- const NAMESPACED_IMAGE_LITERAL =
- /(["'`])([a-z0-9]+(?:[._-][a-z0-9]+)*(?:\/[a-z0-9]+(?:[._-][a-z0-9]+)*)+:[A-Za-z0-9][A-Za-z0-9._-]*(?:@sha256:[0-9a-f]{64})?)\1/g;
- /** `FROM <ref>` inside emitted Dockerfile text. */
- const FROM_REF = /\bFROM\s+([^\s"'`\\]+)/g;
- /** `const <name> = <initializer>` — used to follow a FROM interpolation home. */
- const ANY_BINDING = /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*([^;\n]*)/g;
- /**
- * Names that provably carry a digest-pinned image in this file: the pinned image
- * constants themselves, plus bindings initialized from one (`const base =
- * opts.baseImage ?? CLAUDE_BASE_IMAGE`). Anything else interpolated into a
- * `FROM` is unproven and is reported.
- */
- function pinnedNames(src: string, pinnedConsts: Set<string>): Set<string> {
- const names = new Set(pinnedConsts);
- // Iterate to a fixed point so an alias of an alias still resolves.
- for (let pass = 0; pass < 3; pass++) {
- const before = names.size;
- for (const m of src.matchAll(ANY_BINDING)) {
- const [, name, init] = m;
- const ids = init.match(/[A-Za-z_$][\w$]*/g) ?? [];
- if (ids.some((id) => names.has(id))) names.add(name);
- }
- if (names.size === before) break;
- }
- return names;
- }
- /**
- * Report every external image reference in `src` that is not bound to a reviewed
- * sha256 digest. `label` prefixes each hit so failures name the file and line.
- */
- function scanUnpinnedImages(src: string, label: string): string[] {
- const hits: string[] = [];
- const pinnedConsts = new Set<string>();
- // Literal offsets already reported, so the namespaced-literal pass does not
- // double-report a constant the named-constant pass just flagged.
- const reported = new Set<number>();
- // (a) named image constants, single- OR multi-line. Only refs that name an
- // EXTERNAL registry image are in scope — a bare local tag prefix like
- // `ca-sbx` (IMAGE_PREFIX, images this driver builds itself) has no
- // registry namespace or tag and nothing upstream to pin.
- for (const m of src.matchAll(IMAGE_CONST)) {
- const [, name, , value] = m;
- if (!isExternalImageRef(value)) continue;
- if (DIGEST_PINNED.test(value)) {
- pinnedConsts.add(name);
- continue;
- }
- const quoteAt = m.index + m[0].length - value.length - 2;
- reported.add(quoteAt);
- hits.push(`${label}:${lineOf(src, quoteAt)}: unpinned image constant: ${name} = ${value}`);
- }
- // (b) any namespaced registry ref, whatever it is bound to.
- for (const m of src.matchAll(NAMESPACED_IMAGE_LITERAL)) {
- if (DIGEST_PINNED.test(m[2]) || reported.has(m.index)) continue;
- hits.push(`${label}:${lineOf(src, m.index)}: unpinned image reference: ${m[2]}`);
- }
- // (c) `FROM <ref>` in emitted Dockerfile text. An interpolation is allowed
- // ONLY when it demonstrably reads a digest-pinned constant from this file;
- // a blanket `${...}` pass would let an unpinned constant through (a) via
- // the Dockerfile it emits.
- const resolvable = pinnedNames(src, pinnedConsts);
- for (const m of src.matchAll(FROM_REF)) {
- const ref = m[1];
- const at = `${label}:${lineOf(src, m.index)}`;
- const interpolated = ref.match(/^\$\{(.*)\}$/);
- if (interpolated) {
- const ids = interpolated[1].match(/[A-Za-z_$][\w$]*/g) ?? [];
- if (!ids.some((id) => resolvable.has(id))) {
- hits.push(`${at}: FROM ${ref} does not resolve to a digest-pinned image constant`);
- }
- continue;
- }
- if (!DIGEST_PINNED.test(ref)) hits.push(`${at}: unpinned FROM: ${ref}`);
- }
- return hits;
- }
- describe("supply chain: no remote-fetch-and-execute in production code (#401)", () => {
- it("has at least one production file to scan (guards the scanner itself)", async () => {
- const files = productionFiles();
- expect(files.length).toBeGreaterThan(5);
- expect(files.map(rel)).toContain("build.ts");
- expect(files.map(rel)).toContain("sandbox.js");
- });
- it("never pipes network-fetched bytes into a shell or interpreter", async () => {
- // A downloader (curl/wget/Invoke-WebRequest) whose output flows into a shell,
- // an interpreter, or `source`/`eval` — in any order, on one line.
- const PIPE_TO_SHELL = [
- /\b(curl|wget|iwr|Invoke-WebRequest)\b[^\n]*\|[^\n]*\b(ba|z|da|k)?sh\b/i,
- /\b(curl|wget|iwr|Invoke-WebRequest)\b[^\n]*\|[^\n]*\b(python3?|node|perl|ruby)\b/i,
- /\b(eval|source)\b[^\n]*\$\([^\n]*\b(curl|wget)\b/i,
- /\b(ba|z)?sh\b[^\n]*<\(\s*(curl|wget)\b/i,
- ];
- const hits: string[] = [];
- for (const file of productionFiles()) {
- const lines = readFileSync(file, "utf8").split(/\r?\n/);
- lines.forEach((line, i) => {
- if (PIPE_TO_SHELL.some((re) => re.test(line))) {
- hits.push(`${rel(file)}:${i + 1}: ${line.trim()}`);
- }
- });
- }
- expect(
- hits,
- "ca-sandbox production code must never execute network-fetched bytes " +
- "(no `curl | bash`): remote code would run with the developer's privileges " +
- "BEFORE any container boundary exists. Declare the tool a prerequisite and " +
- "fail closed to the generated-Dockerfile fallback instead.",
- ).toEqual([]);
- });
- it("ships no remote-installer endpoint constant", async () => {
- const build = (await import("./build.ts")) as Record<string, unknown>;
- expect(Object.keys(build)).not.toContain("NIXPACKS_INSTALL_URL");
- const src = readFileSync(path.join(TOOLS_DIR, "build.ts"), "utf8");
- expect(src).not.toMatch(/nixpacks\.com\/install\.sh/);
- });
- it("fails closed when nixpacks is absent: probes only, no host mutation", async () => {
- const calls: Array<{ cmd: string; args: string[] }> = [];
- const absent: RunResult = { code: 127, out: "not found", stdout: "", stderr: "not found" };
- const probe = async (cmd: string, args: string[]): Promise<RunResult> => {
- calls.push({ cmd, args });
- return absent;
- };
- const res = await defaultEnsureNixpacks(probe);
- // Fails CLOSED to the documented fallback, with an actionable note.
- expect(res.available).toBe(false);
- expect(res.via).toBeUndefined();
- expect(res.note).toMatch(/install nixpacks/i);
- // And it mutated NOTHING on the host: every command spawned is a read-only
- // version/location probe of an already-installed tool.
- const argv = calls.map((c) => [c.cmd, ...c.args].join(" "));
- const installerish = argv.filter((s) =>
- /\b(curl|wget|Invoke-WebRequest)\b|\binstall\b|\|\s*(ba)?sh\b/i.test(s),
- );
- expect(
- installerish,
- "a missing nixpacks prerequisite must not fetch or install anything",
- ).toEqual([]);
- expect(calls.map((c) => c.cmd).every((c) => c === "nixpacks" || c === "wsl.exe")).toBe(true);
- });
- });
- describe("supply chain: container inputs are digest-pinned (#402)", () => {
- it("pins the throwaway clone image by digest", async () => {
- expect(CLONE_IMAGE).toMatch(DIGEST_PINNED);
- });
- it("pins the --with-claude base image by digest (token co-runs with it)", async () => {
- expect(CLAUDE_BASE_IMAGE).toMatch(DIGEST_PINNED);
- });
- it("emits only digest-pinned FROM lines from every generated Dockerfile", async () => {
- const dockerfiles = [
- generateDockerfile({ node: false, python: false }),
- generateDockerfile({ node: true, python: true }),
- buildClaudeImageDockerfile(),
- ];
- for (const df of dockerfiles) {
- const froms = df.split(/\r?\n/).filter((l) => /^\s*FROM\s/i.test(l));
- expect(froms.length).toBeGreaterThan(0);
- for (const line of froms) {
- expect(line, `unpinned base image: ${line}`).toMatch(DIGEST_PINNED);
- }
- }
- });
- it("references no floating `:latest` tag in production code", async () => {
- const hits: string[] = [];
- for (const file of productionFiles()) {
- const lines = readFileSync(file, "utf8").split(/\r?\n/);
- lines.forEach((line, i) => {
- // `:latest` is tolerated ONLY when immediately bound to a digest.
- for (const m of line.matchAll(/:latest\b(@sha256:[0-9a-f]{64})?/g)) {
- if (!m[1]) hits.push(`${rel(file)}:${i + 1}: ${line.trim()}`);
- }
- });
- }
- expect(
- hits,
- "a floating `:latest` tag lets a retag or registry compromise swap " +
- "executable code into a sandbox build; bind it as name:tag@sha256:<digest>",
- ).toEqual([]);
- });
- it("digest-pins every image constant and literal FROM in production code", async () => {
- const hits: string[] = [];
- for (const file of productionFiles()) {
- hits.push(...scanUnpinnedImages(readFileSync(file, "utf8"), rel(file)));
- }
- expect(
- hits,
- "every external container image reference must be bound to a reviewed " +
- "sha256 digest (name:tag@sha256:<digest>)",
- ).toEqual([]);
- });
- });
- /**
- * The scanner's own regression suite. The rules above are only worth the bytes
- * they occupy if they FIRE, and a scanner that quietly matches nothing looks
- * exactly like a clean codebase. The previous per-line version of this scanner
- * shipped inert against the multi-line declaration style every image constant in
- * this driver uses; these cases make that failure mode loud.
- */
- describe("supply chain: the digest scanner itself fires (#402)", () => {
- it("catches an unpinned image constant declared across two lines", async () => {
- const src = ["export const PROBE_HELPER_IMAGE =", ' "aquasec/trivy:0.50.0";'].join("\n");
- expect(scanUnpinnedImages(src, "probe.ts")).toEqual([
- "probe.ts:2: unpinned image constant: PROBE_HELPER_IMAGE = aquasec/trivy:0.50.0",
- ]);
- });
- it("catches an unpinned namespaced ref bound to a constant not named *IMAGE*", async () => {
- const src = 'const scanner =\n "aquasec/trivy:0.50.0";';
- expect(scanUnpinnedImages(src, "probe.ts")).toEqual([
- "probe.ts:2: unpinned image reference: aquasec/trivy:0.50.0",
- ]);
- });
- it("catches a literal FROM and a FROM interpolating an unproven binding", async () => {
- const src = [
- "const other = opts.baseImage;",
- "lines.push(`FROM ${other}`);",
- "lines.push(`FROM debian:bookworm`);",
- ].join("\n");
- expect(scanUnpinnedImages(src, "probe.ts")).toEqual([
- "probe.ts:2: FROM ${other} does not resolve to a digest-pinned image constant",
- "probe.ts:3: unpinned FROM: debian:bookworm",
- ]);
- });
- it("reports an unpinned constant exactly once, not once per rule", async () => {
- const src = 'export const CLONE_IMAGE =\n "alpine/git:latest";';
- expect(scanUnpinnedImages(src, "probe.ts")).toHaveLength(1);
- });
- it("stays silent on the pinned multi-line form the driver actually ships", async () => {
- const pinned = `alpine/git:latest@sha256:${"0".repeat(64)}`;
- const src = [
- "export const CLONE_IMAGE =",
- ` "${pinned}";`,
- "const base = opts.baseImage ?? CLONE_IMAGE;",
- "lines.push(`FROM ${base}`);",
- 'const IMAGE_PREFIX = "ca-sbx";',
- 'import { x } from "node:fs/promises";',
- ].join("\n");
- expect(scanUnpinnedImages(src, "probe.ts")).toEqual([]);
- });
- });
plugins/ca/hooks/_modelib.py · Bundled script · 777 lines · 1 finding marked
- #!/usr/bin/env python3
- # codeArbiter — mode plane: the three-value runtime posture (arbiter/dangerous/
- # ops), its deterministic token flip, and the write-ahead audit-close ledger
- # that backs it (#437, mode-plane-deterministic-flip).
- #
- # T-06 (pure refactor, no behavior change): the write-ahead ledger machinery —
- # `_settle_dev_close` and its pending-close record — moved here verbatim from
- # `core/pysrc/session-start.py` (formerly ~lines 551-810). `session-start.py`
- # now imports `_settle_dev_close` (and the `_DEV_PENDING_CLOSE_MAX` constant,
- # which a pre-existing test reads off the session-start module) from here;
- # `clear_dev_marker` itself stays in session-start.py — this module owns the
- # ledger MECHANISM, not the SessionStart-specific policy of when to invoke it.
- #
- # The proof this introduced no behavior change: the pre-existing
- # `TestDevExitRetryablePendingClose` cases in
- # `plugins/ca/hooks/tests/test_session_start.py` pass UNMODIFIED against the
- # regenerated (sync-core.py) vendored copy, which now imports from this file.
- from __future__ import annotations
- import datetime
- import hashlib
- import json
- import os
- import re
- from _activationlib import marker_root
- from _hooklib import acquire_lock, audit_lock_key, release_lock, write_text_atomic
- # ---------------------------------------------------------------------------
- # T-16 — PERSONA_SENTINEL: a single stable literal embedded in every composed
- # persona injection (T-31, Lane B), so a later transcript-pruning pass
- # (`_prunelib`/`_prunepolicy`, T-49/T-50, R-5) can recognize an injected-
- # persona line and mark it `pinned=True` — protected from folding,
- # condensing, and eviction at EVERY tier, including aggressive (AC-26).
- #
- # Deliberately shaped as an HTML comment (renders invisibly in the persona
- # markdown) and deliberately distinct from `_prunepolicy.MARKER_PREFIX`
- # ("[ca-condensed ") — the two must never collide: one marks "this content
- # was ELIDED by a prior prune pass", the other marks "this content must
- # NEVER be elided". Exported here, not in `_prunelib`/`_prunepolicy`,
- # because the INJECTOR (this module's consumers) is the single source that
- # must emit it — a value redefined in two places is a value that can drift.
- PERSONA_SENTINEL = "<!-- codearbiter:persona-sentinel -->"
- Note: Quoted as data in code: Gives the agent orders in an HTML comment, which the rendered page hides from a reader
- Line 45 on GitHub
- # ---------------------------------------------------------------------------
- # T-07 — the mode plane: three-value posture, resolved through marker_root
- # ---------------------------------------------------------------------------
- # `MODES` is the ONLY legal-value tuple; `dev` is retired (superseded by
- # `dangerous`, R-3/ADR-0022 supersession). Index 0 is deliberately the safe
- # default every anomaly falls back to.
- MODES = ("arbiter", "dangerous", "ops")
- # [[never-fold-unreadable-into-absent]] — the house rule this constant set
- # exists to satisfy: a marker file that genuinely does not exist and one that
- # exists but could not be read/parsed are DIFFERENT failure classes and must
- # never collapse onto one diagnostic string. Every non-None diagnostic below
- # still resolves the mode to MODES[0] ("arbiter") — these strings distinguish
- # WHY, not WHAT the fallback is.
- MODE_DIAG_ABSENT = "mode-marker-absent"
- MODE_DIAG_UNREADABLE = "mode-marker-unreadable"
- MODE_DIAG_UNRECOGNIZED = "mode-marker-unrecognized"
- def mode_marker_path(root=None, payload=None):
- """Absolute path of the mode marker: `<root>/.codearbiter/.markers/mode`.
- `root` defaults to `_activationlib.marker_root(payload)` — deliberately
- NOT `project_root(payload)`: `marker_root` exists precisely because
- `project_root` splits marker state across linked worktrees (#604), and
- every other `.codearbiter/.markers/` writer (security-pass.py,
- migration-pass.py, the H-09b/H-10b/H-14 guards) already resolves through
- it. An explicit `root` is accepted as a test-only escape hatch for
- fixture isolation — production callers pass neither and let this resolve
- via the host seam."""
- if root is None:
- root = marker_root(payload)
- return os.path.join(root, ".codearbiter", ".markers", "mode")
- def mode_entry_dir(root=None, payload=None):
- """Absolute path of the per-session entry directory:
- `<root>/.codearbiter/.markers/mode.d`.
- One file per session, never a shared cell. The single-file
- `{session_id: mode}` map this replaces made every flip a read-modify-write
- over state other sessions also own, and `write_text_atomic` serializes the
- replace, not the PAIR. A session holding a map it read moments earlier
- could therefore reinstate a `dangerous` entry another session had
- explicitly left — with that session's own earlier `enter` row still
- backing it in `ledger_backs`, so nothing downstream noticed. Verifying the
- write did not close it: each writer only ever confirmed its OWN key, and
- the victim had already returned success before the clobber landed.
- Splitting the state removes the shared cell rather than serializing access
- to it, so the interleave has nowhere left to occur. That also matches what
- the plane already is — ADR-0030 position 6 makes it transient and
- session-scoped — and is the direction ADR-0012 named ("session-scoped
- markers") when it deferred this hardening as out of scope for the Codex
- campaign.
- Locking the map with `_hooklib.acquire_lock` was the real alternative, and
- a close one: the primitive already exists, is OS-owned (process death
- releases it, so there is no stale lock to steal), and would have confined
- the change to this function. It loses on the prompt seam. `acquire_lock`
- fail-softs to None after a bounded contention spin, and the only safe
- reading of None here is failure — so under contention a user's flip would
- stop working rather than serialize, which is the cost taskwrite.py accepts
- for a board write and this path should not. Removing the shared cell has no
- contention state at all.
- Resolves through `marker_root` exactly as `mode_marker_path` does."""
- if root is None:
- root = marker_root(payload)
- return os.path.join(root, ".codearbiter", ".markers", "mode.d")
- def _mode_entry_name(session_id):
- """The entry filename for `session_id`: its SHA-256 hex digest.
- Hashed rather than sanitized because a session id arrives from host-
- supplied hook input and is therefore untrusted for path construction. A
- substitution sanitizer has to be injective to be correct, and on this
- Windows-primary project it cannot be: NTFS is case-insensitive, so ids
- differing only in case collapse onto one file — reintroducing the shared
- cell this design exists to remove, on the platform most sessions run on. A
- lowercase hex digest is fixed-length, path-safe, case-stable, cannot
- traverse, and cannot collide with a reserved device name.
- The cost is a directory of opaque names, paid back by the record itself:
- each entry stores the session id it belongs to, so the mapping is
- verifiable by reading one file rather than trusted."""
- return hashlib.sha256(str(session_id).encode("utf-8")).hexdigest()
- def mode_entry_path(session_id, root=None, payload=None):
- """Absolute path of `session_id`'s own mode entry."""
- return os.path.join(mode_entry_dir(root, payload), _mode_entry_name(session_id))
- def _read_session_entry(session_id, root=None, payload=None):
- """(value, diagnostic) off `session_id`'s OWN entry file.
- `value` is the raw recorded mode, or None whenever a diagnostic is set —
- validating it against MODES is `current_mode`'s job, as it was for the map.
- Diagnostics carry the same three-way distinction the map reader draws
- ([[never-fold-unreadable-into-absent]]), and `os.path.exists` gates the
- absent check for the same reason: a directory at that path must report
- UNREADABLE, not ABSENT.
- An entry whose recorded `session` is not the one asked for is UNRECOGNIZED,
- never silently honoured. That makes the hash mapping checked rather than
- assumed — a hand-edited file, a restored backup, or (astronomically) a
- digest collision resolves toward `arbiter` with a diagnostic instead of
- handing one session another's posture."""
- path = mode_entry_path(session_id, root, payload)
- if not os.path.exists(path):
- return None, MODE_DIAG_ABSENT
- try:
- with open(path, encoding="utf-8") as f:
- text = f.read()
- except Exception: # noqa: BLE001 — exists but could not be read
- return None, MODE_DIAG_UNREADABLE
- text = text.strip()
- if not text:
- return None, MODE_DIAG_UNRECOGNIZED
- try:
- data = json.loads(text)
- except Exception: # noqa: BLE001 — not valid JSON
- return None, MODE_DIAG_UNRECOGNIZED
- if not isinstance(data, dict) or data.get("session") != str(session_id):
- return None, MODE_DIAG_UNRECOGNIZED
- return data.get("mode"), None
- def session_has_entry(session_id, root=None, payload=None):
- """(has_entry, diagnostic) — whether `session_id` has recorded ANY mode-
- plane opinion yet, including a deliberate `arbiter`.
- The distinction `current_mode` cannot express: it answers `arbiter` both
- for a session that never flipped and for one that flipped back, and the
- SessionStart legacy conversion (T-47) may only migrate over the first.
- Absence is the only clean "nothing to convert over" — so an unreadable
- entry reports its diagnostic and `False`, and the caller must treat that
- as "could not tell", never as absence."""
- _value, diag = _read_session_entry(session_id, root=root, payload=payload)
- if diag is None:
- return True, None
- if diag != MODE_DIAG_ABSENT:
- return False, diag
- state, legacy_diag = _read_mode_state(root, payload)
- if legacy_diag is not None and legacy_diag != MODE_DIAG_ABSENT:
- return False, legacy_diag
- return str(session_id) in {str(k) for k in state}, None
- def _read_mode_state(root=None, payload=None):
- """(state, diagnostic) off the LEGACY single-file mode marker.
- Read-only since #681 split the plane into per-session entries
- (`mode_entry_dir`); nothing writes this file any more. It is still read so
- a session live across the upgrade keeps the posture it chose, and — more
- importantly — so `session_has_entry` keeps seeing an explicit `arbiter`
- that predates the split. Dropping the read would fail SAFE for the mode
- itself (absent resolves to `arbiter`) but not for that second question: the
- entry would read as "never flipped", re-arming the legacy `dev-active`
- conversion to turn gates off under a session that had already chosen.
- `state` is the RAW dict mapping session_id -> whatever value was on disk
- for it (validation of an individual session's value is `current_mode`'s
- job, not this function's — a per-session bad value must still be visible
- to the caller so it can be reported, not silently dropped). Always a
- dict, never None, so callers never need a None-check. A file that is
- itself absent, unreadable, empty, or not a JSON object returns `{}` plus
- a diagnostic.
- `diagnostic` is None on a clean read (the file parses as a JSON object —
- individual bad entries inside it do not taint this diagnostic). Otherwise
- exactly one of MODE_DIAG_ABSENT / MODE_DIAG_UNREADABLE /
- MODE_DIAG_UNRECOGNIZED — `os.path.exists` (not `os.path.isfile`) gates the
- absent check, so a path that exists but cannot be opened as a normal file
- (a directory sitting at that path, or a real permissions error) falls
- through to the `open()` call and is correctly reported UNREADABLE rather
- than ABSENT. This is the portable, no-chmod-needed shape of the
- distinction: a directory path always fails `open()` (IsADirectoryError on
- POSIX, PermissionError on Windows — both are OSError) without depending
- on host-specific permission semantics."""
- path = mode_marker_path(root, payload)
- if not os.path.exists(path):
- return {}, MODE_DIAG_ABSENT
- try:
- with open(path, encoding="utf-8") as f:
- text = f.read()
- except Exception: # noqa: BLE001 — exists but could not be read
- return {}, MODE_DIAG_UNREADABLE
- text = text.strip()
- if not text:
- return {}, MODE_DIAG_UNRECOGNIZED
- try:
- data = json.loads(text)
- except Exception: # noqa: BLE001 — not valid JSON
- return {}, MODE_DIAG_UNRECOGNIZED
- if not isinstance(data, dict):
- return {}, MODE_DIAG_UNRECOGNIZED
- return data, None
- def current_mode(session_id, root=None, payload=None):
- """(mode, diagnostic) for `session_id`.
- Resolves MODES[0] ("arbiter") whenever the marker file is absent, empty,
- unreadable, or unrecognized (AC-2) — WITH a diagnostic distinguishing
- which — and also when the file is clean but simply has no entry yet for
- this session (a fresh session legitimately starts arbiter; that is not an
- anomaly, so diagnostic is None). When the file is clean but THIS
- session's own recorded value is not a legal mode, that is reported the
- same as a file-level unrecognized value (MODE_DIAG_UNRECOGNIZED) — a
- garbage per-session entry is exactly as much an anomaly as a garbage
- file, and must not be swallowed silently.
- Reads `session_id`'s own entry first and falls back to the legacy map ONLY
- when that entry is absent (never when it is unreadable — an entry we could
- not read is not evidence that the legacy value is current). Once a session
- has written once, its own entry is authoritative and the legacy file can
- never revive a superseded posture."""
- value, diag = _read_session_entry(session_id, root=root, payload=payload)
- if diag is None:
- if value not in MODES:
- return MODES[0], MODE_DIAG_UNRECOGNIZED
- return value, None
- if diag != MODE_DIAG_ABSENT:
- return MODES[0], diag
- state, diag = _read_mode_state(root, payload)
- if diag is not None:
- return MODES[0], diag
- if session_id not in state:
- return MODES[0], None
- value = state.get(session_id)
- if value not in MODES:
- return MODES[0], MODE_DIAG_UNRECOGNIZED
- return value, None
- def write_mode(session_id, mode, root=None, payload=None):
- """Persist `mode` for `session_id` (T-08, AC-1) in that session's OWN entry.
- The write is delegated ENTIRELY to `write_text_atomic` — this function does
- no `open()`/`write()` of its own — so an interrupted write can only ever
- land in write_text_atomic's own guarantee: a sibling temp file, then
- `os.replace()`; on any failure the temp is removed and `path` is left
- exactly as it was (untouched if it existed, absent if it did not). Returns
- True on a confirmed write, False on failure. Never raises — the caller
- (`flip`, T-11/T-14) decides what failure means.
- There is no read-modify-write and therefore no retry loop. Writing one
- session's posture no longer requires reading state other sessions own, so
- the interleave that made the old loop necessary — and that the loop could
- not actually close, because each writer verified only its OWN key while the
- victim had already returned success — has nowhere to occur. See
- `mode_entry_dir` for why the shared cell was removed rather than locked.
- VERIFIED, not merely attempted: the entry is re-read and must come back as
- this session's, carrying this value. ADR-0030 position 5 requires the
- return path out of `dangerous` to be "a verified write" that "must surface
- its failure"; a write that cannot be confirmed returns False rather than
- reporting a success it cannot demonstrate."""
- path = mode_entry_path(session_id, root, payload)
- record = json.dumps({"session": str(session_id), "mode": mode})
- try:
- os.makedirs(os.path.dirname(path), exist_ok=True)
- write_text_atomic(path, record, newline="\n")
- except OSError:
- return False
- observed, diag = _read_session_entry(session_id, root=root, payload=payload)
- return diag is None and observed == mode
- # ---------------------------------------------------------------------------
- # T-11 — flip(): the deterministic token-flip primitive every host caller
- # (prompt-submit.py, pi-bridge.py) drives through. Three distinct sentinels,
- # never a bare bool — a caller has to tell "already there" from "the write
- # failed" apart to report either correctly to the user.
- # ---------------------------------------------------------------------------
- FLIP_FLIPPED = "flipped"
- FLIP_NOOP = "noop"
- FLIP_FAILED = "failed"
- def _mode_audit_line(verb, mode, host_name=None, now=None, session_id=None):
- """One `MODE: <name> enter|exit` audit row (Decided parameters: Audit
- verb). `now` (epoch seconds) is injectable for deterministic tests;
- defaults to the real current time.
- Carries `SESSION:` because the row is an AUTHORIZATION, not just a record:
- `ledger_backs` reads it to decide whether a gates-off marker is allowed to
- take effect. Without the field that check is repo-wide, so one session's
- `enter` row authorizes ANOTHER session's marker — the mode plane is keyed
- per session everywhere else, and an unkeyed authorization defeats that
- isolation (AC-3)."""
- ts = (datetime.datetime.fromtimestamp(now, tz=datetime.timezone.utc)
- if now is not None
- else datetime.datetime.now(datetime.timezone.utc))
- ts_str = ts.strftime("%Y-%m-%dT%H:%M:%SZ")
- return (f"[{ts_str}] | BY: session-mode | HOST: {host_name or 'unknown'} "
- f"| SESSION: {session_id or 'unknown'} "
- f"| MODE: {mode} {verb} | NOTE: —\n")
- def flip(session_id, mode, root=None, payload=None, host_name=None, now=None):
- """Attempt to set `session_id`'s mode to `mode`. Returns one of
- FLIP_FLIPPED / FLIP_NOOP / FLIP_FAILED. Never raises.
- AC-6: a flip TO AN ALREADY-ACTIVE, LEDGER-BACKED mode is a no-op — no
- write is attempted and no audit row is appended, so `overrides.log` is
- left byte-identical. The default arbiter posture needs no authorizing row.
- If a prior non-arbiter write landed but its staged enter row did not, a
- repeat request retries settlement: success reports the effective flip,
- while another failure stays explicit instead of claiming the posture is
- already active. This preserves T-14's fail direction because an unbacked
- non-arbiter marker still cannot authorize persona composition.
- On a genuine transition the order is deliberate: write first, audit row
- ONLY on a confirmed write. AC-11's `ledger_backs` exists to catch exactly
- the opposite ordering — a ledger row minted for a flip that never
- actually landed, which would let an unbacked marker masquerade as an
- audited one."""
- root = root if root is not None else marker_root(payload)
- current, _diag = current_mode(session_id, root=root, payload=payload)
- if current == mode:
- if mode == MODES[0] or ledger_backs(root, mode, session_id=session_id):
- return FLIP_NOOP
- _settle_dev_close(root, host_name=host_name)
- return (FLIP_FLIPPED
- if ledger_backs(root, mode, session_id=session_id)
- else FLIP_FAILED)
- if not write_mode(session_id, mode, root=root, payload=payload):
- return FLIP_FAILED
- # ADR-0030 position 4: EVERY transition row is staged through the #396
- # write-ahead ledger, never a bare append. The exit half already complied;
- # this one did not, so an unwritable overrides.log dropped the `MODE: …
- # enter` row with no replay while `flip` still reported success — an
- # unaudited entry into a gates-off posture, which is the one transition
- # that must never be silent.
- #
- # Reporting FLIP_FAILED when the row is not confirmed is consistent rather
- # than pessimistic: `ledger_backs` (AC-11) already refuses to compose a
- # body whose mode has no matching `enter` row, so an unaudited marker is
- # not in effect anyway. Saying so out loud beats leaving the user believing
- # a flip took that the injector will ignore.
- #
- # Confirmed by looking for the row itself, not by the settle count: a
- # settle can append an OLDER owed line and stall on this one, which would
- # read as success from the count alone.
- line = _mode_audit_line("enter", mode, host_name=host_name, now=now,
- session_id=session_id)
- _settle_dev_close(root, new_line=line, host_name=host_name)
- if not _overrides_has_line(root, line):
- return FLIP_FAILED
- return FLIP_FLIPPED
- # ---------------------------------------------------------------------------
- # T-12 — the token table: `mode --arbiter|--dangerous|--ops`, matched
- # WHOLE-PROMPT, never substring (Decided parameters: Token). Pure text logic,
- # no I/O — every host's prompt-seam interceptor (Claude/Codex/Pi) imports
- # this so the matching rule can never drift between hosts.
- # ---------------------------------------------------------------------------
- MODE_TOKEN_REPORT = "report" # bare `mode`: report current + legal values, write nothing
- _MODE_TOKEN_RE = re.compile(r"mode(?:\s+--(arbiter|dangerous|ops))?", re.I)
- def match_mode_token(prompt):
- """Classify `prompt` against the mode control-token table.
- Returns one of MODES (a flip request), MODE_TOKEN_REPORT (bare `mode`),
- or None (not a control token at all — the prompt reaches the model
- unmodified).
- Whole-prompt only: `re.fullmatch` against the prompt after stripping
- SURROUNDING whitespace (never internal) means a token embedded anywhere
- in a longer prompt — before, after, or on another line — cannot match,
- because fullmatch requires the ENTIRE stripped string to be consumed by
- the pattern and the pattern contains no `\\n`. Case-insensitive (`re.I`);
- surrounding whitespace of any kind (spaces, tabs, newlines) is
- insensitive because it is stripped before matching."""
- if not isinstance(prompt, str):
- return None
- stripped = prompt.strip()
- if not stripped:
- return None
- m = _MODE_TOKEN_RE.fullmatch(stripped)
- if not m:
- return None
- name = m.group(1)
- if name is None:
- return MODE_TOKEN_REPORT
- return name.lower()
- # ---------------------------------------------------------------------------
- # T-13 — ledger_backs(): the AC-11 compensating control. The deterministic
- # flip removes ADR-0022's tier-2 confirmation for dangerous-mode entry (its
- # supersession, per the spec's ADR conflict note); this is the load-bearing
- # replacement — the injector refuses to compose a non-arbiter body the audit
- # trail does not back.
- # ---------------------------------------------------------------------------
- _LEGACY_DEV_ENTER_RE = re.compile(r"\|\s*DEV:\s*enter\s*(?:\||$)", re.M)
- def ledger_backs(root, mode, session_id=None):
- """True iff the audit trail (at `root`) holds a matching
- `MODE: <mode> enter` row FOR `session_id`.
- Session-scoped, because this row is an authorization rather than a
- record: it decides whether a gates-off marker takes effect. A repo-wide
- match let one session's `enter` row authorize a DIFFERENT session's marker
- — every other part of the mode plane is keyed per session, and an unkeyed
- authorization defeats that isolation (AC-3). Pass `session_id` at every
- production call site; omitting it keeps the older repo-wide question,
- which is only ever the right one for a caller that has no session.
- A row written before this field existed carries no session and therefore
- backs NO session-scoped query. That fails toward `arbiter` — gates ON, one
- re-flip — which is the direction ADR-0030 requires; the alternative would
- reopen the hole for exactly the history that cannot be checked.
- A legacy `DEV: enter` row backs `mode == "dangerous"` ONLY — dev was
- retired INTO dangerous (T-47 converts a live `dev-active` marker to
- `dangerous` exactly once), so a pre-mode-plane audit trail's DEV: enter
- rows must continue to authorize it. A legacy row must NEVER back `ops`:
- `ops` did not exist when any DEV: row could have been written, so
- accepting one there would be a fail-OPEN into a mode the operator never
- actually requested — the exact failure this function exists to prevent,
- just relocated to a different mode.
- Read-only and tolerant: an absent or unreadable log answers False,
- never raises — consistent with this module's fail-toward-arbiter
- convention (a missing ledger can never AUTHORIZE anything)."""
- try:
- with open(_overrides_log_path(root), encoding="utf-8", errors="replace") as f:
- text = f.read()
- except Exception: # noqa: BLE001 — absent/unreadable log -> nothing backs it
- return False
- enter_re = re.compile(r"\|\s*MODE:\s*" + re.escape(mode) + r"\s+enter\s*(?:\||$)", re.M)
- if session_id is None:
- if enter_re.search(text):
- return True
- else:
- session_re = re.compile(r"\|\s*SESSION:\s*" + re.escape(str(session_id)) + r"\s*\|")
- for line in text.splitlines():
- if session_re.search(line) and enter_re.search(line):
- return True
- # The legacy exception, deliberately session-blind: `dev` was retired INTO
- # `dangerous` (T-47 converts a live `dev-active` marker exactly once), and a
- # pre-mode-plane `DEV: enter` row predates session attribution entirely, so
- # requiring one would break the migration it exists to serve. Bounded to
- # `dangerous` on a repo that already has DEV history — `ops` never gets it,
- # since accepting a legacy row there would authorize a mode the operator
- # could not have requested when that row was written.
- if mode == "dangerous" and _LEGACY_DEV_ENTER_RE.search(text):
- return True
- return False
- # --- #396: a durable, retryable DEV: exit -----------------------------------
- # The synthetic close line is the ONLY thing that keeps the append-only audit
- # trail's DEV: enter/exit pairs matched after an abandoned maintainer session.
- # It used to be written best-effort ("except OSError: pass") and the marker was
- # then removed regardless — so a locked file, a full disk, or a permission blip
- # permanently erased the obligation and left an orphaned DEV: enter that no
- # later session could know about.
- #
- # The fix is a small write-ahead record: the owed line is staged on disk BEFORE
- # the append is attempted, and the record is deleted only once BOTH the append
- # is confirmed AND the marker it settles is gone. That single record therefore
- # carries three facts at once:
- #
- # "lines" — close lines still owed to overrides.log. Emptied one at a
- # time as each append is confirmed.
- # "marker_mtime" — the identity of the dev-active marker this close belongs
- # to. While the record still names a LIVE marker, the
- # force-close path knows that marker has already been
- # closed in the audit trail and refuses to mint a second
- # row for it — which is what makes a failed `os.remove`
- # idempotent rather than duplicating the close. It is
- # cleared the moment that marker is gone: an mtime only
- # identifies a file that still EXISTS, and a stale one is
- # free to collide with an unrelated future marker (2s
- # granularity on FAT32/exFAT/SMB/WSL mounts makes that a
- # real event, not a theoretical one) and suppress a close
- # that is genuinely owed.
- # "dropped" — how many owed close lines the bound below has discarded.
- # The cap keeps the record small, but the loss must not be
- # silent: the count is written to the trail as one
- # attributable note the moment overrides.log accepts writes.
- #
- # Replayed lines carry the timestamp they were MINTED with, not the time they
- # land, so a delayed replay leaves overrides.log non-chronological. Enter/exit
- # pairing is by timestamp, so that is correct — but an audit reader must not
- # assume file order is time order.
- #
- # Every boundary is covered:
- # crash before the append -> record present, line owed -> replayed
- # crash after the append -> record present, line owed -> the bounded
- # tail scan sees the line already landed and
- # drops it instead of appending a duplicate
- # marker removal fails -> record present, no line owed -> the next
- # session only retries the removal
- #
- # That tail scan is applied ONLY to lines read back off the record — the ones
- # that might have landed before a crash. A line minted in THIS process cannot
- # already be on the trail, and must never be dedupe-checked: close rows are
- # timestamped to the second, so two distinct closes minted in the same second
- # are byte-identical, and checking the fresh one against an owed copy of itself
- # would silently swallow a close that is genuinely owed.
- #
- # Everything here is best-effort by the module's standing convention: session
- # startup must never be bricked by audit bookkeeping, so nothing raises.
- _DEV_PENDING_CLOSE_MAX = 8 # bounded: never accumulate owed lines forever
- _DEV_PENDING_SCAN_BYTES = 64 * 1024 # bounded tail scan for the dedupe check
- def _dev_pending_close_path(root):
- return os.path.join(root, ".codearbiter", ".markers", "dev-close-pending.json")
- def _overrides_log_path(root):
- return os.path.join(root, ".codearbiter", "overrides.log")
- def _read_dev_pending_close(root):
- """The pending-close record as
- {"lines": [...], "marker_mtime": float|None, "dropped": int}, or None when
- there is nothing usable on disk. A record that exists but carries no
- replayable line, no marker identity and no unreported drop is reported as
- None so the caller discards it — a corrupt record must never wedge the
- mechanism shut. Never raises."""
- try:
- with open(_dev_pending_close_path(root), encoding="utf-8") as f:
- data = json.load(f)
- if not isinstance(data, dict):
- return None
- lines = [ln for ln in (data.get("lines") or [])
- if isinstance(ln, str) and ln.strip()][:_DEV_PENDING_CLOSE_MAX]
- mtime = data.get("marker_mtime")
- mtime = float(mtime) if isinstance(mtime, (int, float)) else None
- dropped = data.get("dropped")
- # `isinstance(True, int)` is True, so booleans are excluded explicitly.
- dropped = (int(dropped) if isinstance(dropped, int)
- and not isinstance(dropped, bool) and dropped > 0 else 0)
- if not lines and mtime is None and not dropped:
- return None
- return {"lines": lines, "marker_mtime": mtime, "dropped": dropped}
- except Exception: # noqa: BLE001 — absent/corrupt record -> no signal
- return None
- def _write_dev_pending_close(root, rec):
- """Atomically persist the pending-close record. Never raises — a write
- failure only costs the retry signal this call was trying to create, which
- is exactly the pre-#396 behavior and still must not brick startup."""
- try:
- path = _dev_pending_close_path(root)
- os.makedirs(os.path.dirname(path), exist_ok=True)
- write_text_atomic(path, json.dumps(rec), newline="\n")
- except Exception: # noqa: BLE001 — must never brick session startup
- pass
- def _discard_dev_pending_close(root):
- try:
- os.remove(_dev_pending_close_path(root))
- except OSError:
- pass
- def _overrides_has_line(root, line):
- """True iff `line` already appears in the tail of overrides.log. Bounded to
- the last _DEV_PENDING_SCAN_BYTES — a replay always happens on the very next
- SessionStart, so the line it is looking for is at (or near) the end. An
- unreadable log answers False: re-appending a close row is a far smaller
- harm than silently dropping one.
- Read in BINARY and decoded here on purpose: a byte offset is only
- meaningful to seek() on a binary stream, and the comparison is made on the
- stripped line so the platform EOL the append produced never matters."""
- needle = line.strip()
- if not needle:
- return False
- try:
- path = _overrides_log_path(root)
- size = os.path.getsize(path)
- with open(path, "rb") as f:
- if size > _DEV_PENDING_SCAN_BYTES:
- f.seek(size - _DEV_PENDING_SCAN_BYTES)
- tail = f.read().decode("utf-8", "replace")
- return needle in tail
- except Exception: # noqa: BLE001 — cannot confirm -> assume not present
- return False
- def _append_override_line(root, line):
- """Append one audit line to overrides.log. True on a confirmed write."""
- lock = None
- try:
- path = _overrides_log_path(root)
- lock = acquire_lock(audit_lock_key(root, path))
- if lock is None:
- return False
- with open(path, "a", encoding="utf-8") as f:
- f.write(line)
- f.flush()
- os.fsync(f.fileno())
- return True
- except Exception: # noqa: BLE001 — mode audit settlement remains fail-soft
- return False
- finally:
- release_lock(lock)
- def _dev_dropped_close_note(count, host_name=None):
- """One audit line accounting for close rows the pending-close cap had to
- discard. Deliberately NOT a `DEV: exit` row — it closes nothing; it records
- that N closes can never be written, so a reader of the append-only trail
- can attribute the unmatched entries instead of finding an unexplained gap.
- """
- ts = datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
- return (f"[{ts}] | BY: session-cleanup | HOST: {host_name or 'unknown'} "
- f"| DEV: close-dropped | NOTE: {count} owed close row(s) discarded - the "
- f"pending-close cap ({_DEV_PENDING_CLOSE_MAX}) was reached while "
- f"overrides.log was unwritable; that many maintainer sessions have "
- f"no matching close row\n")
- def _settle_dev_close(root, marker=None, new_line=None, host_name=None):
- """Drive the pending-close record to settlement; the single place the owed
- DEV: exit is appended and the retry state is cleared.
- `marker` is the dev-active path when one is live (its mtime becomes the
- close identity), None when there is no marker to settle. `new_line` is a
- freshly minted close line to take on, or None when this is a pure replay of
- whatever is already owed. `host_name` only attributes the cap-overflow note
- below; the close lines themselves already carry their own HOST field.
- Returns the number of close lines appended by THIS call. Never raises."""
- if (marker is None and new_line is None
- and not os.path.isfile(_dev_pending_close_path(root))):
- return 0 # nothing owed, nothing to settle — the overwhelming case
- rec = _read_dev_pending_close(root)
- owed = list(rec["lines"]) if rec else []
- prev_mtime = rec["marker_mtime"] if rec else None
- dropped = rec["dropped"] if rec else 0
- marker_mtime = None
- if marker:
- try:
- marker_mtime = os.path.getmtime(marker)
- except OSError:
- marker_mtime = None
- # Everything already in `owed` came off disk, so it MAY have reached the
- # trail before a crash and has to be dedupe-checked. Anything appended
- # below is minted in this process and cannot possibly be there yet.
- replays = len(owed)
- if new_line is not None:
- # Already closed THIS marker (the append landed, only the removal
- # failed) -> do not mint a second row for it; just retry the cleanup.
- already_closed = (rec is not None and prev_mtime is not None
- and marker_mtime is not None
- and prev_mtime == marker_mtime)
- if not already_closed:
- owed.append(new_line)
- if len(owed) > _DEV_PENDING_CLOSE_MAX:
- # Bounded, but never SILENT. A permanently-unwritable overrides.log
- # would otherwise accumulate owed lines forever, so the oldest are
- # discarded — and counted, so the loss is itself auditable rather than
- # reintroducing exactly the unmatched `DEV: enter` this record exists
- # to prevent.
- overflow = len(owed) - _DEV_PENDING_CLOSE_MAX
- dropped += overflow
- owed = owed[-_DEV_PENDING_CLOSE_MAX:]
- replays = max(0, replays - overflow) # the discards come off the front
- if owed or dropped or marker_mtime is not None:
- # Write-ahead: the obligation is durable BEFORE the append is tried.
- _write_dev_pending_close(root, {"lines": owed,
- "marker_mtime": marker_mtime,
- "dropped": dropped})
- # The overflow note goes in FIRST — the rows it accounts for are older than
- # everything still owed. It is minted fresh each attempt, so it is not
- # deduped by the tail scan; a crash between this append and the write-back
- # below can repeat it once, which is the same "a duplicate beats a loss"
- # trade the close rows themselves make.
- if dropped and _append_override_line(root, _dev_dropped_close_note(dropped, host_name)):
- dropped = 0
- appended = 0
- remaining = []
- stalled = False
- for idx, line in enumerate(owed):
- if stalled:
- remaining.append(line) # the log is failing — everything after
- continue # the first failure is still owed
- if idx < replays and _overrides_has_line(root, line):
- continue # crash-after-append: already in the trail
- if not _append_override_line(root, line):
- stalled = True
- remaining.append(line) # still owed — replay on the next session
- continue
- appended += 1
- marker_gone = True
- if marker:
- try:
- os.remove(marker)
- except OSError:
- marker_gone = not os.path.isfile(marker)
- # Keep the record ONLY while it still carries information: a line still
- # owed, an unreported cap overflow, or the identity of a marker that
- # survived its own removal (the tombstone that stops the next session
- # minting a second close for it). A marker that IS gone takes its tombstone
- # with it — a dead marker's mtime identifies nothing, and leaving it behind
- # lets an unrelated future marker collide with it and lose a real close.
- if remaining or dropped or (not marker_gone and marker_mtime is not None):
- _write_dev_pending_close(root, {"lines": remaining,
- "marker_mtime": (None if marker_gone
- else marker_mtime),
- "dropped": dropped})
- else:
- _discard_dev_pending_close(root)
- return appended
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.