Skip to content
Back to search

codearbiter

MarketplaceWorks with Claude CodeGitHub

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.

Checked today

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/arbiterforge-codearbiter/badge.svg)](/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.

  1. {
  2. "name": "codearbiter",
  3. "owner": { "name": "arbiterForge" },
  4. "metadata": {
  5. "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."
  6. },
  7. "plugins": [
  8. {
  9. "name": "ca",
  10. "source": {
  11. "source": "git-subdir",
  12. "url": "https://github.com/arbiterForge/codeArbiter.git",
  13. "path": "plugins/ca",
  14. "ref": "ca-marketplace"
  15. }
  16. },
  17. {
  18. "name": "ca-sandbox",
  19. "source": "./plugins/ca-sandbox"
  20. }
  21. ]
  22. }
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.

  1. <div align="center">
  2. <img src="docs/readme-hero.webp" alt="codeArbiter. Hard gates for agentic coding." width="100%">
  3. **Open-source governance and hard gates for AI coding agents across Claude Code, Codex CLI, and Pi.**
  4. codeArbiter is a repository-owned governance layer for tests, reviews, security checks, decisions,
  5. and durable project context. You decide. codeArbiter enforces.
  6. <img alt="Claude Code plugin" src="https://img.shields.io/badge/Claude_Code-plugin-d97757">
  7. <img alt="Codex plugin" src="https://img.shields.io/badge/OpenAI_Codex-plugin-10a37f">
  8. <img alt="Pi Feature Forge preview" src="https://img.shields.io/badge/ca--pi-Feature_Forge_preview-d97757">
  9. <img alt="version 3.8.9" src="https://img.shields.io/badge/version-3.8.9-2b7489">
  10. <img alt="core lanes" src="https://img.shields.io/badge/core_lanes-17-555">
  11. <img alt="skills" src="https://img.shields.io/badge/skills-22-555">
  12. <img alt="agents" src="https://img.shields.io/badge/agents-20-555">
  13. <img alt="license AGPL v3" src="https://img.shields.io/badge/license-AGPL_v3-3da639">
  14. [Start learning](https://codearbiter.dev/learn/)
  15. &nbsp;&nbsp;·&nbsp;&nbsp;
  16. [Install](https://codearbiter.dev/getting-started/install/)
  17. &nbsp;&nbsp;·&nbsp;&nbsp;
  18. [Browse the reference](https://codearbiter.dev/reference/)
  19. <sub>Install it globally. It stays dormant until a repository explicitly opts in.</sub>
  20. </div>
  21. ## Agentic coding, with a record
  22. codeArbiter is for teams and power users who let coding agents do consequential work and need more
  23. than “the model said it passed.” Every request enters a named lane. The lane defines the evidence it
  24. must produce, the reviewers it must dispatch, and the conditions that stop it.
  25. This repository contains four sibling plugins:
  26. - `ca` for Claude Code, `ca-codex` for Codex CLI, and `ca-pi` for Pi are the three governance hosts.
  27. - `ca-sandbox` is the isolated local-Codespace infrastructure plugin.
  28. The three governance hosts are generated from one shared surface and use one checked-in
  29. `.codearbiter/` project store. A repository can move between hosts without losing its specs, plans,
  30. ADRs, tasks, decisions, or audit history.
  31. codeArbiter will not:
  32. - write feature code before the required failing test exists;
  33. - commit on a red suite or outside the commit gate;
  34. - resolve a `[CONFIRM-NN]` question by guessing;
  35. - silently reconcile a conflict between the rules, the docs, and the code; or
  36. - push directly to the default branch or merge without the user.
  37. The gates scale to the work. A prose edit takes the small docs lane. A security-sensitive feature
  38. takes the full spec, test-first, review, and PR path.
  39. The Codex path was live-verified on **Codex CLI 0.144.1** with trusted SessionStart injection and a
  40. real `[H-03]` PreToolUse block. The dated
  41. [Claude Code + Codex evidence](https://codearbiter.dev/getting-started/claude-code-and-codex/)
  42. separates continuously verified packaging from the live checks that require a model-backed turn.
  43. ## See it catch something
  44. The landing page includes a
  45. [faithful replay of a shipped hook invocation](https://codearbiter.dev/#proof).
  46. It invokes the real `pre-bash.py` guard, records the source digest, proves the blocked command never
  47. ran, and preserves the exact stderr and audit effect. It does not pretend that a direct hook replay
  48. proves host discovery or trust.
  49. The operating loop looks like this:
  50. ```text
  51. you /ca:fix the statusline keeps running the old version after an update
  52. arbiter route to the regression-test-first fix lane
  53. failing test -> minimal fix -> focused proof -> full verification
  54. you /ca:commit
  55. arbiter permission -> branch -> tests -> behavioral proof -> diff review
  56. selective stage -> commit
  57. you /ca:pr
  58. arbiter reviewer fleet challenges the exact diff
  59. BLOCK findings are resolved before the draft PR can advance
  60. ```
  61. The user owns the decision. The repository keeps the evidence.
  62. ## Get running
  63. Choose the adapter for the coding host you already use. The
  64. [host chooser](https://codearbiter.dev/getting-started/choose-your-host/) covers
  65. stability, command syntax, trust, and platform differences.
  66. | Host | Adapter | Command form | Status |
  67. |---|---|---|---|
  68. | Claude Code | `ca` | `/ca:feature` | Stable |
  69. | Codex CLI | `ca-codex` | `$ca-feature` | Stable |
  70. | Pi | `ca-pi` | `/ca-feature` | Feature Forge `preview` |
  71. **Prerequisites:** Python 3 on `PATH` and `git config user.email` set. ADR lifecycle proof requires
  72. Git 2.45.0+ with `--no-lazy-fetch` on all three governance hosts; unavailable flag support blocks
  73. verification with an upgrade prerequisite, never an implicit fetch fallback. Pi also requires Node.js
  74. 22.19+. If Python is missing, Pi installs its final wrappers but blocks mutating calls and points to
  75. `/ca-doctor`; Claude Code and Codex surface an interpreter breadcrumb instead of silently claiming
  76. governance is active. The [compatibility matrix](https://codearbiter.dev/getting-started/compatibility/)
  77. defines the supported native Git/runtime and linked-worktree boundary; mixed Windows Git and WSL Git
  78. over one shared repository are not supported.
  79. ### Claude Code
  80. ```text
  81. /plugin marketplace add arbiterForge/codeArbiter
  82. /plugin install ca@codearbiter
  83. ```
  84. Approve the normal plugin trust prompt, open the target repository, and continue with
  85. `/ca:init`.
  86. ### Codex CLI
  87. The public GitHub-slug flow is **available now**.
  88. The current adapter version is read from `plugins/ca-codex/.codex-plugin/plugin.json`.
  89. The dated end-to-end public-install record discovered `ca-codex 0.2.4` from release `v2.8.13`.
  90. Current packaging and shared-core parity are continuously verified, while that historical record
  91. stays labeled rather than being promoted to evidence for a newer adapter:
  92. ```text
  93. codex plugin marketplace add arbiterForge/codeArbiter --ref ca-codex-marketplace
  94. codex plugin add ca-codex@codearbiter
  95. ```
  96. The `ca-codex-marketplace` branch is the promoted catalog. Its entry pins an
  97. immutable `ca-codex-dist-v<version>` Git tag holding the exact qualified release
  98. archive, including the native artifact engine; `main` remains the development
  99. source tree and is not a substitute for the promoted binary-bearing
  100. distribution. (An `@arbiterforge/ca-codex` npm channel is planned but deferred,
  101. ADR-0040.)
  102. If `codearbiter` was previously registered without
  103. `--ref ca-codex-marketplace`, `marketplace upgrade` keeps that default-branch
  104. registration and does not migrate it to the promoted binary-bearing channel. Remove and
  105. re-add the marketplace once, then reinstall the plugin:
  106. ```text
  107. codex plugin remove ca-codex@codearbiter
  108. codex plugin marketplace remove codearbiter
  109. codex plugin marketplace add arbiterForge/codeArbiter --ref ca-codex-marketplace
  110. codex plugin add ca-codex@codearbiter
  111. ```
  112. Open `/hooks`, review and trust the `ca-codex` handlers, then start a fresh task. Run `$ca-init` and
  113. `$ca-doctor`.
  114. For development against an unpublished checkout:
  115. ```text
  116. git clone https://github.com/arbiterForge/codeArbiter
  117. cd codeArbiter
  118. codex plugin marketplace add .
  119. codex plugin add ca-codex@codearbiter
  120. ```
  121. ### Pi
  122. > [!NOTE]
  123. > `ca-pi` is a Feature Forge `preview`. It is available for real use now, and you are welcome to
  124. > install it, use it in repositories, and report what you find. Its automated and hosted promotion
  125. > matrix is green; broader real-world evidence is still required before codeArbiter claims
  126. > 100% validation or stable status.
  127. The quickest install is the npm channel: `pi install npm:@arbiterforge/ca-pi` (ADR-0029). For the
  128. reproducible pinned install, list the independently versioned tags, choose one exact result, then
  129. inspect the installed package, grant project trust, and start a fresh session:
  130. ```sh
  131. git ls-remote --tags --refs https://github.com/arbiterForge/codeArbiter.git "ca-pi-v*"
  132. pi install git:github.com/arbiterForge/codeArbiter@ca-pi-v<version>
  133. pi list
  134. pi config
  135. ```
  136. Replace `<version>` with the numeric suffix from the chosen tag while retaining the full
  137. `ca-pi-v...` tag in the install source. The Git-tag install carries no native artifact engine, so
  138. it is a partial install that cannot author typed HTML specs and plans; use the npm channel for
  139. that.
  140. Pi 1.5.0 is the supported host for this release line. Generated aliases use `/ca-*`;
  141. `/skill:ca-*` is the host-native fallback. Every `ca-pi-v*` tag is also published to npm as
  142. `npm:@arbiterforge/ca-pi` with provenance (ADR-0029); the pinned Git tag remains the reproducible
  143. install. The [Pi runbook](./docs/pi-parity-testing.md) covers isolated install, trust, verification,
  144. shared-state continuity, and uninstall.
  145. ### Protect the first repository
  146. Use a disposable Git repository for the first run. Add at least one meaningful source file, then
  147. invoke the host-native forms below:
  148. | Outcome | Claude Code | Codex CLI | Pi |
  149. |---|---|---|---|
  150. | Scaffold project state | `/ca:init` | `$ca-init` | `/ca-init` |
  151. | Prove enforcement | `/ca:doctor` | `$ca-doctor` | `/ca-doctor` |
  152. | Read live state | `/ca:status` | `$ca-status` | `/ca-status` |
  153. `init` creates `.codearbiter/` and routes an existing codebase to `create-context` or a greenfield
  154. project to `decompose`. `doctor` must report a healthy interpreter, current payload, and H-03
  155. live-fire probe before you treat the repository as governed.
  156. Follow the complete
  157. [first-repository walkthrough](https://codearbiter.dev/getting-started/quickstart/)
  158. for expected output, proof, and recovery.
  159. ## Practice before using your own repository
  160. [Arbiter Academy](https://arbiterforge.github.io/arbiter-academy/) is an optional practice course for
  161. codeArbiter. It starts in a personal fork of the Academy repository, so you can make real commits,
  162. inspect governed evidence, and recover from a failed attempt without placing your own project at risk.
  163. The Academy website is the lesson surface. Each published lesson identifies whether an action belongs
  164. in the browser, native terminal, active harness, or with the agent, then provides a copyable command,
  165. the result to expect, the evidence to inspect, and a safe recovery path. Start there when you want to
  166. learn the workflow before protecting a production repository.
  167. ## The docs are the operating manual
  168. The site is designed as a continuous path from first contact to source-backed operation:
  169. | Need | Start here | You finish able to... |
  170. |---|---|---|
  171. | Understand the promise | [What is codeArbiter](https://codearbiter.dev/overview/) | explain command, route, dispatch, gate, and ship |
  172. | Choose and install a host | [Start](https://codearbiter.dev/getting-started/choose-your-host/) | install, trust, activate, and verify one adapter |
  173. | Learn in order | [Learning path](https://codearbiter.dev/learn/) | progress from foundation through the power-user capstone |
  174. | Run daily work | [Workflows](https://codearbiter.dev/guides/feature-lane/) | select and complete the smallest correct lane |
  175. | Understand the model | [Concept map](https://codearbiter.dev/concepts/) | trace routing, decisions, context, review, and audit evidence |
  176. | Diagnose a problem | [Troubleshooting](https://codearbiter.dev/guides/troubleshooting/) | follow a symptom to a deterministic recovery |
  177. | Look up exact behavior | [Reference](https://codearbiter.dev/reference/) | inspect generated commands, skills, agents, hooks, and configuration |
  178. | Evaluate preview work | [Feature Forge](https://codearbiter.dev/feature-forge/overview/) | opt in, verify the off switch, and understand the promotion bar |
  179. Command, skill, agent, and hook-gate reference pages are generated from shipped source on every site
  180. build. Hand-authored guides teach the workflow; generated pages define the exact current surface.
  181. ## How governance works
  182. ```mermaid
  183. flowchart LR
  184. I["host-native command"] --> R["owning skill"]
  185. R --> A["author or operator action"]
  186. A --> V["tests + focused proof"]
  187. V --> F["matched reviewer fleet"]
  188. F --> G{"gate clear?"}
  189. G -->|no| X["named finding or user decision"]
  190. X --> A
  191. G -->|yes| P["selective commit + draft PR"]
  192. ```
  193. Activation is explicit and per repository. Claude Code and Codex check
  194. `.codearbiter/CONTEXT.md` at SessionStart. Pi checks the same file through its `session_start`
  195. extension event and also requires affirmative project trust. Without `arbiter: enabled`, the global
  196. install is dormant: no repository persona, no repository gates, and no governance row.
  197. The project record lives beside the code:
  198. ```text
  199. .codearbiter/
  200. ├── CONTEXT.md activation, vocabulary, maturity, current objective
  201. ├── context/ native HTML knowledge (new default)
  202. ├── work/ portable project ID and native work items (new default)
  203. ├── tech-stack.md legacy Markdown knowledge
  204. ├── coding-standards.md legacy Markdown knowledge
  205. ├── security-controls.md security policy; scope blocks persist after conversion
  206. ├── open-tasks.md legacy work board (existing or explicit Markdown)
  207. ├── open-questions.md unresolved [CONFIRM-NN] decisions
  208. ├── decisions/ numbered ADRs
  209. ├── specs/ and plans/ approved intent and execution
  210. ├── sprint-log.md SMARTS-scored autonomous decisions
  211. ├── checkpoints/ periodic reviewer sweeps
  212. ├── audits/ and reports/ assembled evidence
  213. └── overrides.log append-only sanctioned bypass record
  214. ```
  215. The [.codearbiter directory reference](https://codearbiter.dev/codearbiter-directory/)
  216. explains who creates, reads, and updates every artifact, plus its recovery rules.
  217. ### The hard gates
  218. - No feature code before `tdd` Phase 1 completes.
  219. - No commit outside `commit-gate`, and never with a red suite.
  220. - No `[CONFIRM-NN]` resolved by guessing.
  221. - No silent reconciliation of rule conflicts; route to `/ca:conflict`.
  222. - No raw secret stored in the repository, logs, images, or prompts.
  223. - No direct write to the default branch and no force-push.
  224. - No ADR outside `/ca:adr`, with explicit user attribution.
  225. - Every `/ca:override`, `mode --dangerous`/`mode --ops` entry/exit, and sprint auto-decision is durable and attributable.
  226. - H-18 activation protection has no in-session override path; disabling a repository requires an
  227. external editor and an explicit audit record.
  228. Security and audit-trail correctness outrank data integrity, maintainability, performance, and
  229. velocity. A non-obvious tradeoff cites the level at which it was made.
  230. ### SMARTS: bounded autonomy, explicit reasoning
  231. SMARTS evaluates Scalable, Maintainable, Available, Reliable, Testable, and Securable properties.
  232. Each option gets a concrete verdict and evidence, followed by a `strong`, `moderate`, or `tied`
  233. recommendation. The user still decides.
  234. `/ca:sprint` uses the same lenses for bounded non-hard decisions and writes every call to
  235. `.codearbiter/sprint-log.md` with a confidence flag. Security boundaries, irreversible operations,
  236. gate bypasses, merges, and unresolved questions remain true stops. See
  237. [SMARTS](https://codearbiter.dev/concepts/smarts/) and
  238. [autonomous sprints](https://codearbiter.dev/guides/autonomous-sprints/).
  239. ## Core lanes
  240. Choose the workflow first. The canonical lanes keep daily work compact; advanced operations and
  241. compatibility routes remain available in the complete reference.
  242. <!-- core-lane-chooser:start -->
  243. | Workflow | Choose | Use it for |
  244. |---|---|---|
  245. | Initialize | `/ca:init` | Create or inspect the repository-owned state store |
  246. | 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 |
  247. | Review | `/ca:review` | Run the reviewer fleet over a diff or bounded path |
  248. | Decide | `/ca:adr` | Record a numbered, user-attributed architecture decision |
  249. | Ship | `/ca:commit`, `/ca:pr`, `/ca:release` | Commit, stage a pull request, or prepare an authorized release |
  250. | Operate | `/ca:status`, `/ca:task`, `/ca:doctor`, `/ca:override` | Inspect state, manage the task board, verify enforcement, or log an allowed bypass |
  251. <!-- core-lane-chooser:end -->
  252. [Complete command reference](https://codearbiter.dev/reference/commands/) includes
  253. advanced operations, compatibility routes, internal protocols, deprecation guidance, and host
  254. availability. The generated host catalogs remain inspectable in
  255. [`plugins/ca/COMMANDS.md`](./plugins/ca/COMMANDS.md),
  256. [`plugins/ca-codex/COMMANDS.md`](./plugins/ca-codex/COMMANDS.md), and
  257. [`plugins/ca-pi/COMMANDS.md`](./plugins/ca-pi/COMMANDS.md). Claude Code includes `statusline` and
  258. `prune`; Codex intentionally omits both. Pi omits `statusline` and uses native compaction through
  259. its `prune` route.
  260. ## Trust and host boundaries
  261. The blocking enforcement core is local and Python-stdlib-only. It reads repository files and local
  262. Git state. It does not send repository content to a codeArbiter account; there is no hosted
  263. codeArbiter control plane.
  264. Two background reads are separate from blocking evaluation:
  265. - SessionStart may run a detached, read-only `git fetch` against the repository's configured remote
  266. to report hygiene state.
  267. - A once-daily, fail-silent update check reads the public GitHub Releases API. It sends no repository
  268. content and never applies an update.
  269. The optional `/ca:sprint --farm` preview is a distinct opt-in network feature. It sends byte-capped,
  270. secret-redacted task context to the OpenAI-compatible endpoint you configure and is inert without
  271. the flag and provider key.
  272. See [Enforcement and Security](https://codearbiter.dev/enforcement/) and the
  273. [Hooks Reference](https://codearbiter.dev/hooks/) for the exact event, read,
  274. write, block, and network contract.
  275. ### Pi operational contract
  276. `ca-pi` installs a rich footer in interactive parent sessions. The governance row appears only when
  277. the repository is enabled and affirmatively trusted; rate-window telemetry is omitted rather than
  278. fabricated. Execute mode asks before governed mutations and external side effects. Plan mode is
  279. read-only except for the current canonical spec, plan, and plan ledger.
  280. Background jobs are bounded and session-only, and are never restored from Pi session entries.
  281. Unverified cleanup marks the manager unhealthy, blocks later launches, and points to `/ca-doctor`.
  282. Footer, permission, plan, and background surfaces are parent-interactive only and never recurse into
  283. hardened children.
  284. The human-readable generated catalog is `plugins/ca-pi/SKILLS.md`. On a cold checkout, the platform
  285. aggregate reports `missing_prerequisite` and directs the operator to
  286. `npm --prefix plugins/ca-pi/tools ci --ignore-scripts`; it never installs dependencies on the
  287. verification path.
  288. ## Feature Forge
  289. <div align="center">
  290. <img src="docs/feature-forge.webp" alt="A dark machined gate under controlled amber heat: preview work accumulating evidence before promotion." width="100%">
  291. </div>
  292. Preview features are built, tested, and shipping, but they remain opt-in and dormant until
  293. real-world evidence earns stable status. A preview label never weakens a hard gate and never hides
  294. spending or trust requirements.
  295. | Feature | Opt-in | Promotion evidence still needed |
  296. |---|---|---|
  297. | `ca-pi` | install a pinned `ca-pi-v*` Git tag | diverse real repositories, providers, terminals, and workflows |
  298. | Live transcript pruning | `CODEARBITER_PRUNE=dry` | real-session context savings and false-positive data |
  299. | Pluggable execution farm | `/ca:sprint --farm` | per-task pass rates, cost, and gate-escape evidence |
  300. | `ca-sandbox` | install the sibling plugin | real untrusted repositories and interactive `--with-claude` use |
  301. The source-backed
  302. [live Forge catalog](https://codearbiter.dev/feature-forge/whats-in-the-forge/)
  303. names every opt-in, off switch, dependency, trust boundary, and promotion signal.
  304. The farm preview uses one checked-in `farm.js` backend across supported hosts. A Pi-native embedded
  305. farm worker is a future spike, not a shipping dependency or second engine. `ca-pi` distributes as
  306. the pinned Git tag plus the CI-published `npm:@arbiterforge/ca-pi` package (ADR-0029).
  307. ## Operator details
  308. <details>
  309. <summary><strong>Claude Code statusline</strong></summary>
  310. Run `/ca:statusline` to install the optional token-aware statusline.
  311. <div align="center">
  312. <img alt="Annotated codeArbiter statusline" src="./site/public/diagrams/statusline.png" width="880">
  313. </div>
  314. Folder, Git state, rate limits, token use, cost, context headroom, model, effort, and session age
  315. render globally. The governance row activates only in an enabled repository.
  316. Run `/ca:statusline uninstall` to restore the previous statusline, or remove the
  317. codeArbiter setting when no previous line existed. Running `/ca:statusline install`
  318. again refreshes the installed path and preserves the backup; it does not uninstall.
  319. </details>
  320. <details>
  321. <summary><strong>Updates and configuration</strong></summary>
  322. Update the Claude marketplace explicitly:
  323. ```text
  324. /plugin marketplace update codearbiter
  325. ```
  326. The operator-facing environment-variable catalog, defaults, accepted values, safety boundaries,
  327. and verification steps live in the
  328. [Configuration Reference](https://codearbiter.dev/reference/configuration/).
  329. Release notes are in the [Changelog](https://codearbiter.dev/changelog/).
  330. </details>
  331. <details>
  332. <summary><strong>Turn it off or uninstall it</strong></summary>
  333. A repository without `.codearbiter/CONTEXT.md` carrying `arbiter: enabled` is dormant. Remove `ca`
  334. with Claude Code's plugin manager, run `codex plugin remove ca-codex@codearbiter` for Codex, or use
  335. `pi remove` with the pinned Git source for Pi. The repository-owned `.codearbiter/` record survives,
  336. so another supported host can keep using it.
  337. Follow [Uninstall and Disable](https://codearbiter.dev/guides/uninstalling/) for
  338. host-specific removal, pinning, and verification.
  339. </details>
  340. ## Repository map
  341. ```text
  342. .claude-plugin/marketplace.json Claude marketplace
  343. .agents/plugins/marketplace.json Codex marketplace
  344. core/ canonical shared policy and generated surface
  345. plugins/ca/ Claude Code governance host
  346. plugins/ca-codex/ Codex governance host
  347. plugins/ca-pi/ Pi governance host (Feature Forge preview)
  348. plugins/ca-sandbox/ isolated local-Codespace plugin
  349. site/ Astro/Starlight documentation product
  350. docs/ architecture, parity runbooks, reports, and media
  351. .codearbiter/ this repository's own governed project state
  352. ```
  353. `plugins/ca/` contains the always-on orchestrator, public commands, gated skills, dispatched agents,
  354. hooks, and farm tooling. The [architecture docs](./docs/architecture.md), [parity ledger](./docs/parity.md),
  355. and [full hook contract](./docs/hooks.md) are the maintainer entry points.
  356. <details>
  357. <summary><strong>OpenAI Build Week submission record</strong></summary>
  358. codeArbiter predates OpenAI Build Week. The submitted work, added July 13 through July 21, 2026,
  359. delivered the Pi host plus a corrective campaign over the shared governance core. It is consolidated
  360. in [PR #313](https://github.com/arbiterForge/codeArbiter/pull/313) at verified implementation head
  361. `ec64809c1b6c32f69e3d9787ab205f7bbd563d50`.
  362. Codex was the primary development and orchestration environment. GPT-5.6 was used to design and
  363. implement the Pi adapter, investigate live failures, review older paths, and consolidate corrections
  364. across permissions, Windows process-tree cleanup, provenance, audit integrity, generated-source
  365. drift, CI contracts, and documentation.
  366. The final candidate passed the six Pi platform cells — both then-supported Pi versions on Windows,
  367. macOS, and Linux (versions recorded in the linked artifacts), plus security analysis, CodeQL, shared-core contracts, generated-surface contracts, and
  368. the repository's final verifier. Sanitized evidence:
  369. - [`docs/reports/pi-support/promotion.md`](docs/reports/pi-support/promotion.md)
  370. - [`docs/reports/pi-support/promotion.json`](docs/reports/pi-support/promotion.json)
  371. - [`docs/pi-parity-testing.md`](docs/pi-parity-testing.md)
  372. Judge quick start for the immutable candidate:
  373. ```text
  374. pi install git:github.com/arbiterForge/codeArbiter@ec64809c1b6c32f69e3d9787ab205f7bbd563d50
  375. pi list
  376. pi config
  377. ```
  378. Inspect the repository, grant project trust, start a fresh Pi session, then run `/ca-init` and
  379. `/ca-doctor`.
  380. </details>
  381. ## Project history
  382. codeArbiter v2 is a ground-up rebuild of the earlier vendored `.agents/` framework as a native,
  383. multi-host plugin system. The complete record is in [`CHANGELOG.md`](./CHANGELOG.md) and the
  384. [site changelog](https://codearbiter.dev/changelog/). The v1 implementation
  385. remains available in early repository history.
  386. ## License and contributions
  387. codeArbiter is licensed under the
  388. [GNU Affero General Public License v3.0](./LICENSE) (AGPLv3). You may use, study, modify, and
  389. redistribute it under those terms. AGPLv3 section 13 also applies when a modified version is run as a
  390. network service.
  391. The AGPLv3 transition applies from v2.6.0 forward. Earlier releases remain under the license they
  392. shipped with.
  393. **Open source.** codeArbiter is available under AGPLv3 for open-source use, free of charge.
  394. **Commercial licensing.** SUaDtL retains the copyright and reserves the right to offer the project
  395. under separate proprietary terms. Commercial licenses are not being offered at this time. Inquiries
  396. may be made through GitHub if AGPLv3 does not fit a use case.
  397. **Contributions.** No Contributor License Agreement is currently in force. See
  398. [`CLA.md`](./CLA.md) for its status and maintainer handling. A future agreement
  399. requires legal review and separate explicit assent; maintainers must not infer
  400. additional proprietary relicensing rights from the retired template.
  401. <div align="center">
  402. <sub>Built for Claude Code, Codex CLI, and Pi.</sub>
  403. </div>
plugins/ca-sandbox/tools/supply-chain.test.ts · Bundled script · 381 lines · 1 finding marked
  1. /**
  2. * supply-chain.test.ts — structural supply-chain guards for the ca-sandbox driver.
  3. *
  4. * Two tribunal findings are locked down here, both about EXTERNAL BYTES that
  5. * ca-sandbox would otherwise pull in unpinned:
  6. *
  7. * #401 (secrets-supply-002) — no ca-sandbox runtime path may pipe
  8. * network-fetched bytes into a shell. `defaultEnsureNixpacks` used to run
  9. * `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
  10. * developer host, BEFORE any container boundary exists. nixpacks is a
  11. * documented prerequisite (README / SKILL / command description all say so),
  12. * so the missing-prerequisite path now FAILS CLOSED to the pre-existing
  13. * generated-Dockerfile fallback and tells the user to install nixpacks.
  14. *
  15. * #402 (secrets-supply-004) — every external container image reference must be
  16. * bound to a reviewed content digest (`name:tag@sha256:<64 hex>`), so a retag
  17. * or registry compromise cannot silently swap executable code into a sandbox
  18. * build — least of all into the `--with-claude` box, which co-runs the base
  19. * image with CLAUDE_CODE_OAUTH_TOKEN.
  20. *
  21. * These are STRUCTURAL tests on purpose: `defaultEnsureNixpacks` and the image
  22. * constants are defaults that every other suite stubs out, so the real path had
  23. * ZERO coverage. A structural scan cannot be stubbed past — it reads the shipped
  24. * bytes. Test files are exempt from the scan (lifecycle.test.ts deliberately
  25. * hardcodes `alpine/git:latest` when driving docker directly), which is why the
  26. * scan enumerates production sources explicitly rather than globbing everything.
  27. */
  28. import { describe, it, expect } from "vitest";
  29. import { readFileSync, readdirSync } from "node:fs";
  30. import path from "node:path";
  31. import { fileURLToPath } from "node:url";
  32. import {
  33. defaultEnsureNixpacks,
  34. generateDockerfile,
  35. type RunResult,
  36. } from "./build.ts";
  37. import { CLONE_IMAGE } from "./create.ts";
  38. import { CLAUDE_BASE_IMAGE, buildClaudeImageDockerfile } from "./claude-inside.ts";
  39. const TOOLS_DIR = path.dirname(fileURLToPath(import.meta.url));
  40. /**
  41. * The production surface of the driver: every shipped source file plus the
  42. * committed esbuild bundle (`sandbox.js` — the bytes that actually run on a
  43. * user's machine). Test files, fixtures and the vitest config are NOT production
  44. * code and are deliberately excluded.
  45. */
  46. function productionFiles(): string[] {
  47. const entries = readdirSync(TOOLS_DIR, { withFileTypes: true });
  48. const files = entries
  49. .filter((e) => e.isFile())
  50. .map((e) => e.name)
  51. .filter((n) => n.endsWith(".ts") || n === "sandbox.js")
  52. .filter((n) => !n.endsWith(".test.ts"))
  53. .filter((n) => n !== "vitest.config.ts");
  54. return files.sort().map((n) => path.join(TOOLS_DIR, n));
  55. }
  56. function rel(file: string): string {
  57. return path.relative(TOOLS_DIR, file).replace(/\\/g, "/");
  58. }
  59. /** A `sha256:<64 hex>` digest binding, optionally preceded by a tag. */
  60. const DIGEST_PINNED = /@sha256:[0-9a-f]{64}\b/;
  61. /**
  62. * Does this string name an image PULLED FROM A REGISTRY (and therefore in need
  63. * of a digest pin), as opposed to a locally built one? An external ref carries a
  64. * registry namespace (`alpine/git`) or a tag (`node:22-slim`); the driver's own
  65. * `ca-sbx` tag prefix carries neither and has nothing upstream to pin.
  66. */
  67. function isExternalImageRef(ref: string): boolean {
  68. return ref.includes("/") || ref.includes(":");
  69. }
  70. // --------------------------------------------------------------------------
  71. // the digest scanner (#402 AC-2)
  72. // --------------------------------------------------------------------------
  73. //
  74. // This scanner reads JOINED FILE TEXT, never line-by-line. That is load-bearing:
  75. // every image constant in this driver is written with the value on its own
  76. // continuation line —
  77. //
  78. // export const CLONE_IMAGE =
  79. // "alpine/git:latest@sha256:...";
  80. //
  81. // — so a per-line rule that expects `const NAME = "<ref>"` on ONE line matches
  82. // none of the shipped declarations and is silently inert. `scannerSelfTest`
  83. // below locks that in: it runs these same rules against synthetic multi-line
  84. // sources and asserts they actually fire.
  85. /** 1-based line number of `index` within `src`. */
  86. function lineOf(src: string, index: number): number {
  87. return src.slice(0, index).split(/\r?\n/).length;
  88. }
  89. /**
  90. * A named image constant — `export const CLONE_IMAGE = "<ref>"`, the bundled
  91. * `var CLONE_IMAGE = "<ref>"` form, and (critically) the multi-line form where
  92. * the literal sits on the next line. `\s*` spans the newline; the value class
  93. * does not, so the literal itself is still single-line.
  94. */
  95. const IMAGE_CONST = /\b(?:const|let|var)\s+(\w*IMAGE\w*)\s*=\s*(["'`])([^"'`\n]*)\2/g;
  96. /**
  97. * A string literal that IS a namespaced registry reference (`ns/name:tag`) —
  98. * name-independent, so `const TRIVY = "aquasec/trivy:0.50.0"` and a bare argv
  99. * element `"alpine/git:latest"` are both caught even though neither is named
  100. * `*IMAGE*`. Requiring the `/` namespace is what keeps this free of false
  101. * positives: node builtin specifiers (`node:path`, `node:fs/promises`) and
  102. * docs placeholders (`host:container`, `1000:1000`) never match.
  103. *
  104. * Residual, accepted: an official-library image with no namespace and a
  105. * non-`latest` tag (`"node:22-slim"`) bound to a constant NOT named `*IMAGE*`
  106. * would evade this rule — `node:<builtin>` import specifiers are structurally
  107. * identical to it. Today's two such images are both `*IMAGE*`-named (caught by
  108. * IMAGE_CONST) and additionally asserted by name in the tests below.
  109. */
  110. const NAMESPACED_IMAGE_LITERAL =
  111. /(["'`])([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;
  112. /** `FROM <ref>` inside emitted Dockerfile text. */
  113. const FROM_REF = /\bFROM\s+([^\s"'`\\]+)/g;
  114. /** `const <name> = <initializer>` — used to follow a FROM interpolation home. */
  115. const ANY_BINDING = /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*([^;\n]*)/g;
  116. /**
  117. * Names that provably carry a digest-pinned image in this file: the pinned image
  118. * constants themselves, plus bindings initialized from one (`const base =
  119. * opts.baseImage ?? CLAUDE_BASE_IMAGE`). Anything else interpolated into a
  120. * `FROM` is unproven and is reported.
  121. */
  122. function pinnedNames(src: string, pinnedConsts: Set<string>): Set<string> {
  123. const names = new Set(pinnedConsts);
  124. // Iterate to a fixed point so an alias of an alias still resolves.
  125. for (let pass = 0; pass < 3; pass++) {
  126. const before = names.size;
  127. for (const m of src.matchAll(ANY_BINDING)) {
  128. const [, name, init] = m;
  129. const ids = init.match(/[A-Za-z_$][\w$]*/g) ?? [];
  130. if (ids.some((id) => names.has(id))) names.add(name);
  131. }
  132. if (names.size === before) break;
  133. }
  134. return names;
  135. }
  136. /**
  137. * Report every external image reference in `src` that is not bound to a reviewed
  138. * sha256 digest. `label` prefixes each hit so failures name the file and line.
  139. */
  140. function scanUnpinnedImages(src: string, label: string): string[] {
  141. const hits: string[] = [];
  142. const pinnedConsts = new Set<string>();
  143. // Literal offsets already reported, so the namespaced-literal pass does not
  144. // double-report a constant the named-constant pass just flagged.
  145. const reported = new Set<number>();
  146. // (a) named image constants, single- OR multi-line. Only refs that name an
  147. // EXTERNAL registry image are in scope — a bare local tag prefix like
  148. // `ca-sbx` (IMAGE_PREFIX, images this driver builds itself) has no
  149. // registry namespace or tag and nothing upstream to pin.
  150. for (const m of src.matchAll(IMAGE_CONST)) {
  151. const [, name, , value] = m;
  152. if (!isExternalImageRef(value)) continue;
  153. if (DIGEST_PINNED.test(value)) {
  154. pinnedConsts.add(name);
  155. continue;
  156. }
  157. const quoteAt = m.index + m[0].length - value.length - 2;
  158. reported.add(quoteAt);
  159. hits.push(`${label}:${lineOf(src, quoteAt)}: unpinned image constant: ${name} = ${value}`);
  160. }
  161. // (b) any namespaced registry ref, whatever it is bound to.
  162. for (const m of src.matchAll(NAMESPACED_IMAGE_LITERAL)) {
  163. if (DIGEST_PINNED.test(m[2]) || reported.has(m.index)) continue;
  164. hits.push(`${label}:${lineOf(src, m.index)}: unpinned image reference: ${m[2]}`);
  165. }
  166. // (c) `FROM <ref>` in emitted Dockerfile text. An interpolation is allowed
  167. // ONLY when it demonstrably reads a digest-pinned constant from this file;
  168. // a blanket `${...}` pass would let an unpinned constant through (a) via
  169. // the Dockerfile it emits.
  170. const resolvable = pinnedNames(src, pinnedConsts);
  171. for (const m of src.matchAll(FROM_REF)) {
  172. const ref = m[1];
  173. const at = `${label}:${lineOf(src, m.index)}`;
  174. const interpolated = ref.match(/^\$\{(.*)\}$/);
  175. if (interpolated) {
  176. const ids = interpolated[1].match(/[A-Za-z_$][\w$]*/g) ?? [];
  177. if (!ids.some((id) => resolvable.has(id))) {
  178. hits.push(`${at}: FROM ${ref} does not resolve to a digest-pinned image constant`);
  179. }
  180. continue;
  181. }
  182. if (!DIGEST_PINNED.test(ref)) hits.push(`${at}: unpinned FROM: ${ref}`);
  183. }
  184. return hits;
  185. }
  186. describe("supply chain: no remote-fetch-and-execute in production code (#401)", () => {
  187. it("has at least one production file to scan (guards the scanner itself)", async () => {
  188. const files = productionFiles();
  189. expect(files.length).toBeGreaterThan(5);
  190. expect(files.map(rel)).toContain("build.ts");
  191. expect(files.map(rel)).toContain("sandbox.js");
  192. });
  193. it("never pipes network-fetched bytes into a shell or interpreter", async () => {
  194. // A downloader (curl/wget/Invoke-WebRequest) whose output flows into a shell,
  195. // an interpreter, or `source`/`eval` — in any order, on one line.
  196. const PIPE_TO_SHELL = [
  197. /\b(curl|wget|iwr|Invoke-WebRequest)\b[^\n]*\|[^\n]*\b(ba|z|da|k)?sh\b/i,
  198. /\b(curl|wget|iwr|Invoke-WebRequest)\b[^\n]*\|[^\n]*\b(python3?|node|perl|ruby)\b/i,
  199. /\b(eval|source)\b[^\n]*\$\([^\n]*\b(curl|wget)\b/i,
  200. /\b(ba|z)?sh\b[^\n]*<\(\s*(curl|wget)\b/i,
  201. ];
  202. const hits: string[] = [];
  203. for (const file of productionFiles()) {
  204. const lines = readFileSync(file, "utf8").split(/\r?\n/);
  205. lines.forEach((line, i) => {
  206. if (PIPE_TO_SHELL.some((re) => re.test(line))) {
  207. hits.push(`${rel(file)}:${i + 1}: ${line.trim()}`);
  208. }
  209. });
  210. }
  211. expect(
  212. hits,
  213. "ca-sandbox production code must never execute network-fetched bytes " +
  214. "(no `curl | bash`): remote code would run with the developer's privileges " +
  215. "BEFORE any container boundary exists. Declare the tool a prerequisite and " +
  216. "fail closed to the generated-Dockerfile fallback instead.",
  217. ).toEqual([]);
  218. });
  219. it("ships no remote-installer endpoint constant", async () => {
  220. const build = (await import("./build.ts")) as Record<string, unknown>;
  221. expect(Object.keys(build)).not.toContain("NIXPACKS_INSTALL_URL");
  222. const src = readFileSync(path.join(TOOLS_DIR, "build.ts"), "utf8");
  223. expect(src).not.toMatch(/nixpacks\.com\/install\.sh/);
  224. });
  225. it("fails closed when nixpacks is absent: probes only, no host mutation", async () => {
  226. const calls: Array<{ cmd: string; args: string[] }> = [];
  227. const absent: RunResult = { code: 127, out: "not found", stdout: "", stderr: "not found" };
  228. const probe = async (cmd: string, args: string[]): Promise<RunResult> => {
  229. calls.push({ cmd, args });
  230. return absent;
  231. };
  232. const res = await defaultEnsureNixpacks(probe);
  233. // Fails CLOSED to the documented fallback, with an actionable note.
  234. expect(res.available).toBe(false);
  235. expect(res.via).toBeUndefined();
  236. expect(res.note).toMatch(/install nixpacks/i);
  237. // And it mutated NOTHING on the host: every command spawned is a read-only
  238. // version/location probe of an already-installed tool.
  239. const argv = calls.map((c) => [c.cmd, ...c.args].join(" "));
  240. const installerish = argv.filter((s) =>
  241. /\b(curl|wget|Invoke-WebRequest)\b|\binstall\b|\|\s*(ba)?sh\b/i.test(s),
  242. );
  243. expect(
  244. installerish,
  245. "a missing nixpacks prerequisite must not fetch or install anything",
  246. ).toEqual([]);
  247. expect(calls.map((c) => c.cmd).every((c) => c === "nixpacks" || c === "wsl.exe")).toBe(true);
  248. });
  249. });
  250. describe("supply chain: container inputs are digest-pinned (#402)", () => {
  251. it("pins the throwaway clone image by digest", async () => {
  252. expect(CLONE_IMAGE).toMatch(DIGEST_PINNED);
  253. });
  254. it("pins the --with-claude base image by digest (token co-runs with it)", async () => {
  255. expect(CLAUDE_BASE_IMAGE).toMatch(DIGEST_PINNED);
  256. });
  257. it("emits only digest-pinned FROM lines from every generated Dockerfile", async () => {
  258. const dockerfiles = [
  259. generateDockerfile({ node: false, python: false }),
  260. generateDockerfile({ node: true, python: true }),
  261. buildClaudeImageDockerfile(),
  262. ];
  263. for (const df of dockerfiles) {
  264. const froms = df.split(/\r?\n/).filter((l) => /^\s*FROM\s/i.test(l));
  265. expect(froms.length).toBeGreaterThan(0);
  266. for (const line of froms) {
  267. expect(line, `unpinned base image: ${line}`).toMatch(DIGEST_PINNED);
  268. }
  269. }
  270. });
  271. it("references no floating `:latest` tag in production code", async () => {
  272. const hits: string[] = [];
  273. for (const file of productionFiles()) {
  274. const lines = readFileSync(file, "utf8").split(/\r?\n/);
  275. lines.forEach((line, i) => {
  276. // `:latest` is tolerated ONLY when immediately bound to a digest.
  277. for (const m of line.matchAll(/:latest\b(@sha256:[0-9a-f]{64})?/g)) {
  278. if (!m[1]) hits.push(`${rel(file)}:${i + 1}: ${line.trim()}`);
  279. }
  280. });
  281. }
  282. expect(
  283. hits,
  284. "a floating `:latest` tag lets a retag or registry compromise swap " +
  285. "executable code into a sandbox build; bind it as name:tag@sha256:<digest>",
  286. ).toEqual([]);
  287. });
  288. it("digest-pins every image constant and literal FROM in production code", async () => {
  289. const hits: string[] = [];
  290. for (const file of productionFiles()) {
  291. hits.push(...scanUnpinnedImages(readFileSync(file, "utf8"), rel(file)));
  292. }
  293. expect(
  294. hits,
  295. "every external container image reference must be bound to a reviewed " +
  296. "sha256 digest (name:tag@sha256:<digest>)",
  297. ).toEqual([]);
  298. });
  299. });
  300. /**
  301. * The scanner's own regression suite. The rules above are only worth the bytes
  302. * they occupy if they FIRE, and a scanner that quietly matches nothing looks
  303. * exactly like a clean codebase. The previous per-line version of this scanner
  304. * shipped inert against the multi-line declaration style every image constant in
  305. * this driver uses; these cases make that failure mode loud.
  306. */
  307. describe("supply chain: the digest scanner itself fires (#402)", () => {
  308. it("catches an unpinned image constant declared across two lines", async () => {
  309. const src = ["export const PROBE_HELPER_IMAGE =", ' "aquasec/trivy:0.50.0";'].join("\n");
  310. expect(scanUnpinnedImages(src, "probe.ts")).toEqual([
  311. "probe.ts:2: unpinned image constant: PROBE_HELPER_IMAGE = aquasec/trivy:0.50.0",
  312. ]);
  313. });
  314. it("catches an unpinned namespaced ref bound to a constant not named *IMAGE*", async () => {
  315. const src = 'const scanner =\n "aquasec/trivy:0.50.0";';
  316. expect(scanUnpinnedImages(src, "probe.ts")).toEqual([
  317. "probe.ts:2: unpinned image reference: aquasec/trivy:0.50.0",
  318. ]);
  319. });
  320. it("catches a literal FROM and a FROM interpolating an unproven binding", async () => {
  321. const src = [
  322. "const other = opts.baseImage;",
  323. "lines.push(`FROM ${other}`);",
  324. "lines.push(`FROM debian:bookworm`);",
  325. ].join("\n");
  326. expect(scanUnpinnedImages(src, "probe.ts")).toEqual([
  327. "probe.ts:2: FROM ${other} does not resolve to a digest-pinned image constant",
  328. "probe.ts:3: unpinned FROM: debian:bookworm",
  329. ]);
  330. });
  331. it("reports an unpinned constant exactly once, not once per rule", async () => {
  332. const src = 'export const CLONE_IMAGE =\n "alpine/git:latest";';
  333. expect(scanUnpinnedImages(src, "probe.ts")).toHaveLength(1);
  334. });
  335. it("stays silent on the pinned multi-line form the driver actually ships", async () => {
  336. const pinned = `alpine/git:latest@sha256:${"0".repeat(64)}`;
  337. const src = [
  338. "export const CLONE_IMAGE =",
  339. ` "${pinned}";`,
  340. "const base = opts.baseImage ?? CLONE_IMAGE;",
  341. "lines.push(`FROM ${base}`);",
  342. 'const IMAGE_PREFIX = "ca-sbx";',
  343. 'import { x } from "node:fs/promises";',
  344. ].join("\n");
  345. expect(scanUnpinnedImages(src, "probe.ts")).toEqual([]);
  346. });
  347. });
plugins/ca/hooks/_modelib.py · Bundled script · 777 lines · 1 finding marked
  1. #!/usr/bin/env python3
  2. # codeArbiter — mode plane: the three-value runtime posture (arbiter/dangerous/
  3. # ops), its deterministic token flip, and the write-ahead audit-close ledger
  4. # that backs it (#437, mode-plane-deterministic-flip).
  5. #
  6. # T-06 (pure refactor, no behavior change): the write-ahead ledger machinery —
  7. # `_settle_dev_close` and its pending-close record — moved here verbatim from
  8. # `core/pysrc/session-start.py` (formerly ~lines 551-810). `session-start.py`
  9. # now imports `_settle_dev_close` (and the `_DEV_PENDING_CLOSE_MAX` constant,
  10. # which a pre-existing test reads off the session-start module) from here;
  11. # `clear_dev_marker` itself stays in session-start.py — this module owns the
  12. # ledger MECHANISM, not the SessionStart-specific policy of when to invoke it.
  13. #
  14. # The proof this introduced no behavior change: the pre-existing
  15. # `TestDevExitRetryablePendingClose` cases in
  16. # `plugins/ca/hooks/tests/test_session_start.py` pass UNMODIFIED against the
  17. # regenerated (sync-core.py) vendored copy, which now imports from this file.
  18. from __future__ import annotations
  19. import datetime
  20. import hashlib
  21. import json
  22. import os
  23. import re
  24. from _activationlib import marker_root
  25. from _hooklib import acquire_lock, audit_lock_key, release_lock, write_text_atomic
  26. # ---------------------------------------------------------------------------
  27. # T-16 — PERSONA_SENTINEL: a single stable literal embedded in every composed
  28. # persona injection (T-31, Lane B), so a later transcript-pruning pass
  29. # (`_prunelib`/`_prunepolicy`, T-49/T-50, R-5) can recognize an injected-
  30. # persona line and mark it `pinned=True` — protected from folding,
  31. # condensing, and eviction at EVERY tier, including aggressive (AC-26).
  32. #
  33. # Deliberately shaped as an HTML comment (renders invisibly in the persona
  34. # markdown) and deliberately distinct from `_prunepolicy.MARKER_PREFIX`
  35. # ("[ca-condensed ") — the two must never collide: one marks "this content
  36. # was ELIDED by a prior prune pass", the other marks "this content must
  37. # NEVER be elided". Exported here, not in `_prunelib`/`_prunepolicy`,
  38. # because the INJECTOR (this module's consumers) is the single source that
  39. # must emit it — a value redefined in two places is a value that can drift.
  40. 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
  41. # ---------------------------------------------------------------------------
  42. # T-07 — the mode plane: three-value posture, resolved through marker_root
  43. # ---------------------------------------------------------------------------
  44. # `MODES` is the ONLY legal-value tuple; `dev` is retired (superseded by
  45. # `dangerous`, R-3/ADR-0022 supersession). Index 0 is deliberately the safe
  46. # default every anomaly falls back to.
  47. MODES = ("arbiter", "dangerous", "ops")
  48. # [[never-fold-unreadable-into-absent]] — the house rule this constant set
  49. # exists to satisfy: a marker file that genuinely does not exist and one that
  50. # exists but could not be read/parsed are DIFFERENT failure classes and must
  51. # never collapse onto one diagnostic string. Every non-None diagnostic below
  52. # still resolves the mode to MODES[0] ("arbiter") — these strings distinguish
  53. # WHY, not WHAT the fallback is.
  54. MODE_DIAG_ABSENT = "mode-marker-absent"
  55. MODE_DIAG_UNREADABLE = "mode-marker-unreadable"
  56. MODE_DIAG_UNRECOGNIZED = "mode-marker-unrecognized"
  57. def mode_marker_path(root=None, payload=None):
  58. """Absolute path of the mode marker: `<root>/.codearbiter/.markers/mode`.
  59. `root` defaults to `_activationlib.marker_root(payload)` — deliberately
  60. NOT `project_root(payload)`: `marker_root` exists precisely because
  61. `project_root` splits marker state across linked worktrees (#604), and
  62. every other `.codearbiter/.markers/` writer (security-pass.py,
  63. migration-pass.py, the H-09b/H-10b/H-14 guards) already resolves through
  64. it. An explicit `root` is accepted as a test-only escape hatch for
  65. fixture isolation — production callers pass neither and let this resolve
  66. via the host seam."""
  67. if root is None:
  68. root = marker_root(payload)
  69. return os.path.join(root, ".codearbiter", ".markers", "mode")
  70. def mode_entry_dir(root=None, payload=None):
  71. """Absolute path of the per-session entry directory:
  72. `<root>/.codearbiter/.markers/mode.d`.
  73. One file per session, never a shared cell. The single-file
  74. `{session_id: mode}` map this replaces made every flip a read-modify-write
  75. over state other sessions also own, and `write_text_atomic` serializes the
  76. replace, not the PAIR. A session holding a map it read moments earlier
  77. could therefore reinstate a `dangerous` entry another session had
  78. explicitly left — with that session's own earlier `enter` row still
  79. backing it in `ledger_backs`, so nothing downstream noticed. Verifying the
  80. write did not close it: each writer only ever confirmed its OWN key, and
  81. the victim had already returned success before the clobber landed.
  82. Splitting the state removes the shared cell rather than serializing access
  83. to it, so the interleave has nowhere left to occur. That also matches what
  84. the plane already is — ADR-0030 position 6 makes it transient and
  85. session-scoped — and is the direction ADR-0012 named ("session-scoped
  86. markers") when it deferred this hardening as out of scope for the Codex
  87. campaign.
  88. Locking the map with `_hooklib.acquire_lock` was the real alternative, and
  89. a close one: the primitive already exists, is OS-owned (process death
  90. releases it, so there is no stale lock to steal), and would have confined
  91. the change to this function. It loses on the prompt seam. `acquire_lock`
  92. fail-softs to None after a bounded contention spin, and the only safe
  93. reading of None here is failure — so under contention a user's flip would
  94. stop working rather than serialize, which is the cost taskwrite.py accepts
  95. for a board write and this path should not. Removing the shared cell has no
  96. contention state at all.
  97. Resolves through `marker_root` exactly as `mode_marker_path` does."""
  98. if root is None:
  99. root = marker_root(payload)
  100. return os.path.join(root, ".codearbiter", ".markers", "mode.d")
  101. def _mode_entry_name(session_id):
  102. """The entry filename for `session_id`: its SHA-256 hex digest.
  103. Hashed rather than sanitized because a session id arrives from host-
  104. supplied hook input and is therefore untrusted for path construction. A
  105. substitution sanitizer has to be injective to be correct, and on this
  106. Windows-primary project it cannot be: NTFS is case-insensitive, so ids
  107. differing only in case collapse onto one file — reintroducing the shared
  108. cell this design exists to remove, on the platform most sessions run on. A
  109. lowercase hex digest is fixed-length, path-safe, case-stable, cannot
  110. traverse, and cannot collide with a reserved device name.
  111. The cost is a directory of opaque names, paid back by the record itself:
  112. each entry stores the session id it belongs to, so the mapping is
  113. verifiable by reading one file rather than trusted."""
  114. return hashlib.sha256(str(session_id).encode("utf-8")).hexdigest()
  115. def mode_entry_path(session_id, root=None, payload=None):
  116. """Absolute path of `session_id`'s own mode entry."""
  117. return os.path.join(mode_entry_dir(root, payload), _mode_entry_name(session_id))
  118. def _read_session_entry(session_id, root=None, payload=None):
  119. """(value, diagnostic) off `session_id`'s OWN entry file.
  120. `value` is the raw recorded mode, or None whenever a diagnostic is set —
  121. validating it against MODES is `current_mode`'s job, as it was for the map.
  122. Diagnostics carry the same three-way distinction the map reader draws
  123. ([[never-fold-unreadable-into-absent]]), and `os.path.exists` gates the
  124. absent check for the same reason: a directory at that path must report
  125. UNREADABLE, not ABSENT.
  126. An entry whose recorded `session` is not the one asked for is UNRECOGNIZED,
  127. never silently honoured. That makes the hash mapping checked rather than
  128. assumed — a hand-edited file, a restored backup, or (astronomically) a
  129. digest collision resolves toward `arbiter` with a diagnostic instead of
  130. handing one session another's posture."""
  131. path = mode_entry_path(session_id, root, payload)
  132. if not os.path.exists(path):
  133. return None, MODE_DIAG_ABSENT
  134. try:
  135. with open(path, encoding="utf-8") as f:
  136. text = f.read()
  137. except Exception: # noqa: BLE001 — exists but could not be read
  138. return None, MODE_DIAG_UNREADABLE
  139. text = text.strip()
  140. if not text:
  141. return None, MODE_DIAG_UNRECOGNIZED
  142. try:
  143. data = json.loads(text)
  144. except Exception: # noqa: BLE001 — not valid JSON
  145. return None, MODE_DIAG_UNRECOGNIZED
  146. if not isinstance(data, dict) or data.get("session") != str(session_id):
  147. return None, MODE_DIAG_UNRECOGNIZED
  148. return data.get("mode"), None
  149. def session_has_entry(session_id, root=None, payload=None):
  150. """(has_entry, diagnostic) — whether `session_id` has recorded ANY mode-
  151. plane opinion yet, including a deliberate `arbiter`.
  152. The distinction `current_mode` cannot express: it answers `arbiter` both
  153. for a session that never flipped and for one that flipped back, and the
  154. SessionStart legacy conversion (T-47) may only migrate over the first.
  155. Absence is the only clean "nothing to convert over" — so an unreadable
  156. entry reports its diagnostic and `False`, and the caller must treat that
  157. as "could not tell", never as absence."""
  158. _value, diag = _read_session_entry(session_id, root=root, payload=payload)
  159. if diag is None:
  160. return True, None
  161. if diag != MODE_DIAG_ABSENT:
  162. return False, diag
  163. state, legacy_diag = _read_mode_state(root, payload)
  164. if legacy_diag is not None and legacy_diag != MODE_DIAG_ABSENT:
  165. return False, legacy_diag
  166. return str(session_id) in {str(k) for k in state}, None
  167. def _read_mode_state(root=None, payload=None):
  168. """(state, diagnostic) off the LEGACY single-file mode marker.
  169. Read-only since #681 split the plane into per-session entries
  170. (`mode_entry_dir`); nothing writes this file any more. It is still read so
  171. a session live across the upgrade keeps the posture it chose, and — more
  172. importantly — so `session_has_entry` keeps seeing an explicit `arbiter`
  173. that predates the split. Dropping the read would fail SAFE for the mode
  174. itself (absent resolves to `arbiter`) but not for that second question: the
  175. entry would read as "never flipped", re-arming the legacy `dev-active`
  176. conversion to turn gates off under a session that had already chosen.
  177. `state` is the RAW dict mapping session_id -> whatever value was on disk
  178. for it (validation of an individual session's value is `current_mode`'s
  179. job, not this function's — a per-session bad value must still be visible
  180. to the caller so it can be reported, not silently dropped). Always a
  181. dict, never None, so callers never need a None-check. A file that is
  182. itself absent, unreadable, empty, or not a JSON object returns `{}` plus
  183. a diagnostic.
  184. `diagnostic` is None on a clean read (the file parses as a JSON object —
  185. individual bad entries inside it do not taint this diagnostic). Otherwise
  186. exactly one of MODE_DIAG_ABSENT / MODE_DIAG_UNREADABLE /
  187. MODE_DIAG_UNRECOGNIZED — `os.path.exists` (not `os.path.isfile`) gates the
  188. absent check, so a path that exists but cannot be opened as a normal file
  189. (a directory sitting at that path, or a real permissions error) falls
  190. through to the `open()` call and is correctly reported UNREADABLE rather
  191. than ABSENT. This is the portable, no-chmod-needed shape of the
  192. distinction: a directory path always fails `open()` (IsADirectoryError on
  193. POSIX, PermissionError on Windows — both are OSError) without depending
  194. on host-specific permission semantics."""
  195. path = mode_marker_path(root, payload)
  196. if not os.path.exists(path):
  197. return {}, MODE_DIAG_ABSENT
  198. try:
  199. with open(path, encoding="utf-8") as f:
  200. text = f.read()
  201. except Exception: # noqa: BLE001 — exists but could not be read
  202. return {}, MODE_DIAG_UNREADABLE
  203. text = text.strip()
  204. if not text:
  205. return {}, MODE_DIAG_UNRECOGNIZED
  206. try:
  207. data = json.loads(text)
  208. except Exception: # noqa: BLE001 — not valid JSON
  209. return {}, MODE_DIAG_UNRECOGNIZED
  210. if not isinstance(data, dict):
  211. return {}, MODE_DIAG_UNRECOGNIZED
  212. return data, None
  213. def current_mode(session_id, root=None, payload=None):
  214. """(mode, diagnostic) for `session_id`.
  215. Resolves MODES[0] ("arbiter") whenever the marker file is absent, empty,
  216. unreadable, or unrecognized (AC-2) — WITH a diagnostic distinguishing
  217. which — and also when the file is clean but simply has no entry yet for
  218. this session (a fresh session legitimately starts arbiter; that is not an
  219. anomaly, so diagnostic is None). When the file is clean but THIS
  220. session's own recorded value is not a legal mode, that is reported the
  221. same as a file-level unrecognized value (MODE_DIAG_UNRECOGNIZED) — a
  222. garbage per-session entry is exactly as much an anomaly as a garbage
  223. file, and must not be swallowed silently.
  224. Reads `session_id`'s own entry first and falls back to the legacy map ONLY
  225. when that entry is absent (never when it is unreadable — an entry we could
  226. not read is not evidence that the legacy value is current). Once a session
  227. has written once, its own entry is authoritative and the legacy file can
  228. never revive a superseded posture."""
  229. value, diag = _read_session_entry(session_id, root=root, payload=payload)
  230. if diag is None:
  231. if value not in MODES:
  232. return MODES[0], MODE_DIAG_UNRECOGNIZED
  233. return value, None
  234. if diag != MODE_DIAG_ABSENT:
  235. return MODES[0], diag
  236. state, diag = _read_mode_state(root, payload)
  237. if diag is not None:
  238. return MODES[0], diag
  239. if session_id not in state:
  240. return MODES[0], None
  241. value = state.get(session_id)
  242. if value not in MODES:
  243. return MODES[0], MODE_DIAG_UNRECOGNIZED
  244. return value, None
  245. def write_mode(session_id, mode, root=None, payload=None):
  246. """Persist `mode` for `session_id` (T-08, AC-1) in that session's OWN entry.
  247. The write is delegated ENTIRELY to `write_text_atomic` — this function does
  248. no `open()`/`write()` of its own — so an interrupted write can only ever
  249. land in write_text_atomic's own guarantee: a sibling temp file, then
  250. `os.replace()`; on any failure the temp is removed and `path` is left
  251. exactly as it was (untouched if it existed, absent if it did not). Returns
  252. True on a confirmed write, False on failure. Never raises — the caller
  253. (`flip`, T-11/T-14) decides what failure means.
  254. There is no read-modify-write and therefore no retry loop. Writing one
  255. session's posture no longer requires reading state other sessions own, so
  256. the interleave that made the old loop necessary — and that the loop could
  257. not actually close, because each writer verified only its OWN key while the
  258. victim had already returned success — has nowhere to occur. See
  259. `mode_entry_dir` for why the shared cell was removed rather than locked.
  260. VERIFIED, not merely attempted: the entry is re-read and must come back as
  261. this session's, carrying this value. ADR-0030 position 5 requires the
  262. return path out of `dangerous` to be "a verified write" that "must surface
  263. its failure"; a write that cannot be confirmed returns False rather than
  264. reporting a success it cannot demonstrate."""
  265. path = mode_entry_path(session_id, root, payload)
  266. record = json.dumps({"session": str(session_id), "mode": mode})
  267. try:
  268. os.makedirs(os.path.dirname(path), exist_ok=True)
  269. write_text_atomic(path, record, newline="\n")
  270. except OSError:
  271. return False
  272. observed, diag = _read_session_entry(session_id, root=root, payload=payload)
  273. return diag is None and observed == mode
  274. # ---------------------------------------------------------------------------
  275. # T-11 — flip(): the deterministic token-flip primitive every host caller
  276. # (prompt-submit.py, pi-bridge.py) drives through. Three distinct sentinels,
  277. # never a bare bool — a caller has to tell "already there" from "the write
  278. # failed" apart to report either correctly to the user.
  279. # ---------------------------------------------------------------------------
  280. FLIP_FLIPPED = "flipped"
  281. FLIP_NOOP = "noop"
  282. FLIP_FAILED = "failed"
  283. def _mode_audit_line(verb, mode, host_name=None, now=None, session_id=None):
  284. """One `MODE: <name> enter|exit` audit row (Decided parameters: Audit
  285. verb). `now` (epoch seconds) is injectable for deterministic tests;
  286. defaults to the real current time.
  287. Carries `SESSION:` because the row is an AUTHORIZATION, not just a record:
  288. `ledger_backs` reads it to decide whether a gates-off marker is allowed to
  289. take effect. Without the field that check is repo-wide, so one session's
  290. `enter` row authorizes ANOTHER session's marker — the mode plane is keyed
  291. per session everywhere else, and an unkeyed authorization defeats that
  292. isolation (AC-3)."""
  293. ts = (datetime.datetime.fromtimestamp(now, tz=datetime.timezone.utc)
  294. if now is not None
  295. else datetime.datetime.now(datetime.timezone.utc))
  296. ts_str = ts.strftime("%Y-%m-%dT%H:%M:%SZ")
  297. return (f"[{ts_str}] | BY: session-mode | HOST: {host_name or 'unknown'} "
  298. f"| SESSION: {session_id or 'unknown'} "
  299. f"| MODE: {mode} {verb} | NOTE: —\n")
  300. def flip(session_id, mode, root=None, payload=None, host_name=None, now=None):
  301. """Attempt to set `session_id`'s mode to `mode`. Returns one of
  302. FLIP_FLIPPED / FLIP_NOOP / FLIP_FAILED. Never raises.
  303. AC-6: a flip TO AN ALREADY-ACTIVE, LEDGER-BACKED mode is a no-op — no
  304. write is attempted and no audit row is appended, so `overrides.log` is
  305. left byte-identical. The default arbiter posture needs no authorizing row.
  306. If a prior non-arbiter write landed but its staged enter row did not, a
  307. repeat request retries settlement: success reports the effective flip,
  308. while another failure stays explicit instead of claiming the posture is
  309. already active. This preserves T-14's fail direction because an unbacked
  310. non-arbiter marker still cannot authorize persona composition.
  311. On a genuine transition the order is deliberate: write first, audit row
  312. ONLY on a confirmed write. AC-11's `ledger_backs` exists to catch exactly
  313. the opposite ordering — a ledger row minted for a flip that never
  314. actually landed, which would let an unbacked marker masquerade as an
  315. audited one."""
  316. root = root if root is not None else marker_root(payload)
  317. current, _diag = current_mode(session_id, root=root, payload=payload)
  318. if current == mode:
  319. if mode == MODES[0] or ledger_backs(root, mode, session_id=session_id):
  320. return FLIP_NOOP
  321. _settle_dev_close(root, host_name=host_name)
  322. return (FLIP_FLIPPED
  323. if ledger_backs(root, mode, session_id=session_id)
  324. else FLIP_FAILED)
  325. if not write_mode(session_id, mode, root=root, payload=payload):
  326. return FLIP_FAILED
  327. # ADR-0030 position 4: EVERY transition row is staged through the #396
  328. # write-ahead ledger, never a bare append. The exit half already complied;
  329. # this one did not, so an unwritable overrides.log dropped the `MODE: …
  330. # enter` row with no replay while `flip` still reported success — an
  331. # unaudited entry into a gates-off posture, which is the one transition
  332. # that must never be silent.
  333. #
  334. # Reporting FLIP_FAILED when the row is not confirmed is consistent rather
  335. # than pessimistic: `ledger_backs` (AC-11) already refuses to compose a
  336. # body whose mode has no matching `enter` row, so an unaudited marker is
  337. # not in effect anyway. Saying so out loud beats leaving the user believing
  338. # a flip took that the injector will ignore.
  339. #
  340. # Confirmed by looking for the row itself, not by the settle count: a
  341. # settle can append an OLDER owed line and stall on this one, which would
  342. # read as success from the count alone.
  343. line = _mode_audit_line("enter", mode, host_name=host_name, now=now,
  344. session_id=session_id)
  345. _settle_dev_close(root, new_line=line, host_name=host_name)
  346. if not _overrides_has_line(root, line):
  347. return FLIP_FAILED
  348. return FLIP_FLIPPED
  349. # ---------------------------------------------------------------------------
  350. # T-12 — the token table: `mode --arbiter|--dangerous|--ops`, matched
  351. # WHOLE-PROMPT, never substring (Decided parameters: Token). Pure text logic,
  352. # no I/O — every host's prompt-seam interceptor (Claude/Codex/Pi) imports
  353. # this so the matching rule can never drift between hosts.
  354. # ---------------------------------------------------------------------------
  355. MODE_TOKEN_REPORT = "report" # bare `mode`: report current + legal values, write nothing
  356. _MODE_TOKEN_RE = re.compile(r"mode(?:\s+--(arbiter|dangerous|ops))?", re.I)
  357. def match_mode_token(prompt):
  358. """Classify `prompt` against the mode control-token table.
  359. Returns one of MODES (a flip request), MODE_TOKEN_REPORT (bare `mode`),
  360. or None (not a control token at all — the prompt reaches the model
  361. unmodified).
  362. Whole-prompt only: `re.fullmatch` against the prompt after stripping
  363. SURROUNDING whitespace (never internal) means a token embedded anywhere
  364. in a longer prompt — before, after, or on another line — cannot match,
  365. because fullmatch requires the ENTIRE stripped string to be consumed by
  366. the pattern and the pattern contains no `\\n`. Case-insensitive (`re.I`);
  367. surrounding whitespace of any kind (spaces, tabs, newlines) is
  368. insensitive because it is stripped before matching."""
  369. if not isinstance(prompt, str):
  370. return None
  371. stripped = prompt.strip()
  372. if not stripped:
  373. return None
  374. m = _MODE_TOKEN_RE.fullmatch(stripped)
  375. if not m:
  376. return None
  377. name = m.group(1)
  378. if name is None:
  379. return MODE_TOKEN_REPORT
  380. return name.lower()
  381. # ---------------------------------------------------------------------------
  382. # T-13 — ledger_backs(): the AC-11 compensating control. The deterministic
  383. # flip removes ADR-0022's tier-2 confirmation for dangerous-mode entry (its
  384. # supersession, per the spec's ADR conflict note); this is the load-bearing
  385. # replacement — the injector refuses to compose a non-arbiter body the audit
  386. # trail does not back.
  387. # ---------------------------------------------------------------------------
  388. _LEGACY_DEV_ENTER_RE = re.compile(r"\|\s*DEV:\s*enter\s*(?:\||$)", re.M)
  389. def ledger_backs(root, mode, session_id=None):
  390. """True iff the audit trail (at `root`) holds a matching
  391. `MODE: <mode> enter` row FOR `session_id`.
  392. Session-scoped, because this row is an authorization rather than a
  393. record: it decides whether a gates-off marker takes effect. A repo-wide
  394. match let one session's `enter` row authorize a DIFFERENT session's marker
  395. — every other part of the mode plane is keyed per session, and an unkeyed
  396. authorization defeats that isolation (AC-3). Pass `session_id` at every
  397. production call site; omitting it keeps the older repo-wide question,
  398. which is only ever the right one for a caller that has no session.
  399. A row written before this field existed carries no session and therefore
  400. backs NO session-scoped query. That fails toward `arbiter` — gates ON, one
  401. re-flip — which is the direction ADR-0030 requires; the alternative would
  402. reopen the hole for exactly the history that cannot be checked.
  403. A legacy `DEV: enter` row backs `mode == "dangerous"` ONLY — dev was
  404. retired INTO dangerous (T-47 converts a live `dev-active` marker to
  405. `dangerous` exactly once), so a pre-mode-plane audit trail's DEV: enter
  406. rows must continue to authorize it. A legacy row must NEVER back `ops`:
  407. `ops` did not exist when any DEV: row could have been written, so
  408. accepting one there would be a fail-OPEN into a mode the operator never
  409. actually requested — the exact failure this function exists to prevent,
  410. just relocated to a different mode.
  411. Read-only and tolerant: an absent or unreadable log answers False,
  412. never raises — consistent with this module's fail-toward-arbiter
  413. convention (a missing ledger can never AUTHORIZE anything)."""
  414. try:
  415. with open(_overrides_log_path(root), encoding="utf-8", errors="replace") as f:
  416. text = f.read()
  417. except Exception: # noqa: BLE001 — absent/unreadable log -> nothing backs it
  418. return False
  419. enter_re = re.compile(r"\|\s*MODE:\s*" + re.escape(mode) + r"\s+enter\s*(?:\||$)", re.M)
  420. if session_id is None:
  421. if enter_re.search(text):
  422. return True
  423. else:
  424. session_re = re.compile(r"\|\s*SESSION:\s*" + re.escape(str(session_id)) + r"\s*\|")
  425. for line in text.splitlines():
  426. if session_re.search(line) and enter_re.search(line):
  427. return True
  428. # The legacy exception, deliberately session-blind: `dev` was retired INTO
  429. # `dangerous` (T-47 converts a live `dev-active` marker exactly once), and a
  430. # pre-mode-plane `DEV: enter` row predates session attribution entirely, so
  431. # requiring one would break the migration it exists to serve. Bounded to
  432. # `dangerous` on a repo that already has DEV history — `ops` never gets it,
  433. # since accepting a legacy row there would authorize a mode the operator
  434. # could not have requested when that row was written.
  435. if mode == "dangerous" and _LEGACY_DEV_ENTER_RE.search(text):
  436. return True
  437. return False
  438. # --- #396: a durable, retryable DEV: exit -----------------------------------
  439. # The synthetic close line is the ONLY thing that keeps the append-only audit
  440. # trail's DEV: enter/exit pairs matched after an abandoned maintainer session.
  441. # It used to be written best-effort ("except OSError: pass") and the marker was
  442. # then removed regardless — so a locked file, a full disk, or a permission blip
  443. # permanently erased the obligation and left an orphaned DEV: enter that no
  444. # later session could know about.
  445. #
  446. # The fix is a small write-ahead record: the owed line is staged on disk BEFORE
  447. # the append is attempted, and the record is deleted only once BOTH the append
  448. # is confirmed AND the marker it settles is gone. That single record therefore
  449. # carries three facts at once:
  450. #
  451. # "lines" — close lines still owed to overrides.log. Emptied one at a
  452. # time as each append is confirmed.
  453. # "marker_mtime" — the identity of the dev-active marker this close belongs
  454. # to. While the record still names a LIVE marker, the
  455. # force-close path knows that marker has already been
  456. # closed in the audit trail and refuses to mint a second
  457. # row for it — which is what makes a failed `os.remove`
  458. # idempotent rather than duplicating the close. It is
  459. # cleared the moment that marker is gone: an mtime only
  460. # identifies a file that still EXISTS, and a stale one is
  461. # free to collide with an unrelated future marker (2s
  462. # granularity on FAT32/exFAT/SMB/WSL mounts makes that a
  463. # real event, not a theoretical one) and suppress a close
  464. # that is genuinely owed.
  465. # "dropped" — how many owed close lines the bound below has discarded.
  466. # The cap keeps the record small, but the loss must not be
  467. # silent: the count is written to the trail as one
  468. # attributable note the moment overrides.log accepts writes.
  469. #
  470. # Replayed lines carry the timestamp they were MINTED with, not the time they
  471. # land, so a delayed replay leaves overrides.log non-chronological. Enter/exit
  472. # pairing is by timestamp, so that is correct — but an audit reader must not
  473. # assume file order is time order.
  474. #
  475. # Every boundary is covered:
  476. # crash before the append -> record present, line owed -> replayed
  477. # crash after the append -> record present, line owed -> the bounded
  478. # tail scan sees the line already landed and
  479. # drops it instead of appending a duplicate
  480. # marker removal fails -> record present, no line owed -> the next
  481. # session only retries the removal
  482. #
  483. # That tail scan is applied ONLY to lines read back off the record — the ones
  484. # that might have landed before a crash. A line minted in THIS process cannot
  485. # already be on the trail, and must never be dedupe-checked: close rows are
  486. # timestamped to the second, so two distinct closes minted in the same second
  487. # are byte-identical, and checking the fresh one against an owed copy of itself
  488. # would silently swallow a close that is genuinely owed.
  489. #
  490. # Everything here is best-effort by the module's standing convention: session
  491. # startup must never be bricked by audit bookkeeping, so nothing raises.
  492. _DEV_PENDING_CLOSE_MAX = 8 # bounded: never accumulate owed lines forever
  493. _DEV_PENDING_SCAN_BYTES = 64 * 1024 # bounded tail scan for the dedupe check
  494. def _dev_pending_close_path(root):
  495. return os.path.join(root, ".codearbiter", ".markers", "dev-close-pending.json")
  496. def _overrides_log_path(root):
  497. return os.path.join(root, ".codearbiter", "overrides.log")
  498. def _read_dev_pending_close(root):
  499. """The pending-close record as
  500. {"lines": [...], "marker_mtime": float|None, "dropped": int}, or None when
  501. there is nothing usable on disk. A record that exists but carries no
  502. replayable line, no marker identity and no unreported drop is reported as
  503. None so the caller discards it — a corrupt record must never wedge the
  504. mechanism shut. Never raises."""
  505. try:
  506. with open(_dev_pending_close_path(root), encoding="utf-8") as f:
  507. data = json.load(f)
  508. if not isinstance(data, dict):
  509. return None
  510. lines = [ln for ln in (data.get("lines") or [])
  511. if isinstance(ln, str) and ln.strip()][:_DEV_PENDING_CLOSE_MAX]
  512. mtime = data.get("marker_mtime")
  513. mtime = float(mtime) if isinstance(mtime, (int, float)) else None
  514. dropped = data.get("dropped")
  515. # `isinstance(True, int)` is True, so booleans are excluded explicitly.
  516. dropped = (int(dropped) if isinstance(dropped, int)
  517. and not isinstance(dropped, bool) and dropped > 0 else 0)
  518. if not lines and mtime is None and not dropped:
  519. return None
  520. return {"lines": lines, "marker_mtime": mtime, "dropped": dropped}
  521. except Exception: # noqa: BLE001 — absent/corrupt record -> no signal
  522. return None
  523. def _write_dev_pending_close(root, rec):
  524. """Atomically persist the pending-close record. Never raises — a write
  525. failure only costs the retry signal this call was trying to create, which
  526. is exactly the pre-#396 behavior and still must not brick startup."""
  527. try:
  528. path = _dev_pending_close_path(root)
  529. os.makedirs(os.path.dirname(path), exist_ok=True)
  530. write_text_atomic(path, json.dumps(rec), newline="\n")
  531. except Exception: # noqa: BLE001 — must never brick session startup
  532. pass
  533. def _discard_dev_pending_close(root):
  534. try:
  535. os.remove(_dev_pending_close_path(root))
  536. except OSError:
  537. pass
  538. def _overrides_has_line(root, line):
  539. """True iff `line` already appears in the tail of overrides.log. Bounded to
  540. the last _DEV_PENDING_SCAN_BYTES — a replay always happens on the very next
  541. SessionStart, so the line it is looking for is at (or near) the end. An
  542. unreadable log answers False: re-appending a close row is a far smaller
  543. harm than silently dropping one.
  544. Read in BINARY and decoded here on purpose: a byte offset is only
  545. meaningful to seek() on a binary stream, and the comparison is made on the
  546. stripped line so the platform EOL the append produced never matters."""
  547. needle = line.strip()
  548. if not needle:
  549. return False
  550. try:
  551. path = _overrides_log_path(root)
  552. size = os.path.getsize(path)
  553. with open(path, "rb") as f:
  554. if size > _DEV_PENDING_SCAN_BYTES:
  555. f.seek(size - _DEV_PENDING_SCAN_BYTES)
  556. tail = f.read().decode("utf-8", "replace")
  557. return needle in tail
  558. except Exception: # noqa: BLE001 — cannot confirm -> assume not present
  559. return False
  560. def _append_override_line(root, line):
  561. """Append one audit line to overrides.log. True on a confirmed write."""
  562. lock = None
  563. try:
  564. path = _overrides_log_path(root)
  565. lock = acquire_lock(audit_lock_key(root, path))
  566. if lock is None:
  567. return False
  568. with open(path, "a", encoding="utf-8") as f:
  569. f.write(line)
  570. f.flush()
  571. os.fsync(f.fileno())
  572. return True
  573. except Exception: # noqa: BLE001 — mode audit settlement remains fail-soft
  574. return False
  575. finally:
  576. release_lock(lock)
  577. def _dev_dropped_close_note(count, host_name=None):
  578. """One audit line accounting for close rows the pending-close cap had to
  579. discard. Deliberately NOT a `DEV: exit` row — it closes nothing; it records
  580. that N closes can never be written, so a reader of the append-only trail
  581. can attribute the unmatched entries instead of finding an unexplained gap.
  582. """
  583. ts = datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
  584. return (f"[{ts}] | BY: session-cleanup | HOST: {host_name or 'unknown'} "
  585. f"| DEV: close-dropped | NOTE: {count} owed close row(s) discarded - the "
  586. f"pending-close cap ({_DEV_PENDING_CLOSE_MAX}) was reached while "
  587. f"overrides.log was unwritable; that many maintainer sessions have "
  588. f"no matching close row\n")
  589. def _settle_dev_close(root, marker=None, new_line=None, host_name=None):
  590. """Drive the pending-close record to settlement; the single place the owed
  591. DEV: exit is appended and the retry state is cleared.
  592. `marker` is the dev-active path when one is live (its mtime becomes the
  593. close identity), None when there is no marker to settle. `new_line` is a
  594. freshly minted close line to take on, or None when this is a pure replay of
  595. whatever is already owed. `host_name` only attributes the cap-overflow note
  596. below; the close lines themselves already carry their own HOST field.
  597. Returns the number of close lines appended by THIS call. Never raises."""
  598. if (marker is None and new_line is None
  599. and not os.path.isfile(_dev_pending_close_path(root))):
  600. return 0 # nothing owed, nothing to settle — the overwhelming case
  601. rec = _read_dev_pending_close(root)
  602. owed = list(rec["lines"]) if rec else []
  603. prev_mtime = rec["marker_mtime"] if rec else None
  604. dropped = rec["dropped"] if rec else 0
  605. marker_mtime = None
  606. if marker:
  607. try:
  608. marker_mtime = os.path.getmtime(marker)
  609. except OSError:
  610. marker_mtime = None
  611. # Everything already in `owed` came off disk, so it MAY have reached the
  612. # trail before a crash and has to be dedupe-checked. Anything appended
  613. # below is minted in this process and cannot possibly be there yet.
  614. replays = len(owed)
  615. if new_line is not None:
  616. # Already closed THIS marker (the append landed, only the removal
  617. # failed) -> do not mint a second row for it; just retry the cleanup.
  618. already_closed = (rec is not None and prev_mtime is not None
  619. and marker_mtime is not None
  620. and prev_mtime == marker_mtime)
  621. if not already_closed:
  622. owed.append(new_line)
  623. if len(owed) > _DEV_PENDING_CLOSE_MAX:
  624. # Bounded, but never SILENT. A permanently-unwritable overrides.log
  625. # would otherwise accumulate owed lines forever, so the oldest are
  626. # discarded — and counted, so the loss is itself auditable rather than
  627. # reintroducing exactly the unmatched `DEV: enter` this record exists
  628. # to prevent.
  629. overflow = len(owed) - _DEV_PENDING_CLOSE_MAX
  630. dropped += overflow
  631. owed = owed[-_DEV_PENDING_CLOSE_MAX:]
  632. replays = max(0, replays - overflow) # the discards come off the front
  633. if owed or dropped or marker_mtime is not None:
  634. # Write-ahead: the obligation is durable BEFORE the append is tried.
  635. _write_dev_pending_close(root, {"lines": owed,
  636. "marker_mtime": marker_mtime,
  637. "dropped": dropped})
  638. # The overflow note goes in FIRST — the rows it accounts for are older than
  639. # everything still owed. It is minted fresh each attempt, so it is not
  640. # deduped by the tail scan; a crash between this append and the write-back
  641. # below can repeat it once, which is the same "a duplicate beats a loss"
  642. # trade the close rows themselves make.
  643. if dropped and _append_override_line(root, _dev_dropped_close_note(dropped, host_name)):
  644. dropped = 0
  645. appended = 0
  646. remaining = []
  647. stalled = False
  648. for idx, line in enumerate(owed):
  649. if stalled:
  650. remaining.append(line) # the log is failing — everything after
  651. continue # the first failure is still owed
  652. if idx < replays and _overrides_has_line(root, line):
  653. continue # crash-after-append: already in the trail
  654. if not _append_override_line(root, line):
  655. stalled = True
  656. remaining.append(line) # still owed — replay on the next session
  657. continue
  658. appended += 1
  659. marker_gone = True
  660. if marker:
  661. try:
  662. os.remove(marker)
  663. except OSError:
  664. marker_gone = not os.path.isfile(marker)
  665. # Keep the record ONLY while it still carries information: a line still
  666. # owed, an unreported cap overflow, or the identity of a marker that
  667. # survived its own removal (the tombstone that stops the next session
  668. # minting a second close for it). A marker that IS gone takes its tombstone
  669. # with it — a dead marker's mtime identifies nothing, and leaving it behind
  670. # lets an unrelated future marker collide with it and lose a real close.
  671. if remaining or dropped or (not marker_gone and marker_mtime is not None):
  672. _write_dev_pending_close(root, {"lines": remaining,
  673. "marker_mtime": (None if marker_gone
  674. else marker_mtime),
  675. "dropped": dropped})
  676. else:
  677. _discard_dev_pending_close(root)
  678. return appended

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.