tickmarkr 1.30.0

package/README.md

@@ -0,0 +1,347 @@
+# tickmarkr
+
+**Assertions are free. Tickmarks are earned.**
+
+tickmarkr is a spec-driven orchestration harness for AI coding agent CLIs — framed as an external
+audit engagement. You scope assertions (acceptance criteria); the engine earns tickmarks (passed
+gates) only after independent verification. An **engagement** (`tickmarkr run`) compiles a spec
+into a task graph, routes work to the best installed agent CLI (claude-code, codex, cursor-agent,
+opencode, grok, pi) by cost within capability floors, dispatches **field teams** in isolated git
+worktrees — as real visible TUIs when running under [herdr](https://herdr.dev), headless
+subprocesses otherwise — and records every event in the **audit trail** (`.drovr/runs/<runId>/journal.jsonl`).
+Green tasks consolidate onto a `tickmarkr/<runId>` **consolidation** branch; **sign-off** (merge to
+your mainline) is always the Partner's call, never the engine's. A fully green engagement is an
+**unqualified opinion** — every assertion independently ticked.
+
+> The package ships `tickmarkr` as the primary bin, plus `drovr` and a `drover` bin alias for
+> backward compatibility — all three invoke the same entry. New installs should call `tickmarkr`.
+
+## Vocabulary
+
+Audit voice in docs and reports maps to engine concepts exactly once:
+
+| Audit term | Engine concept |
+|---|---|
+| Partner | Human operator |
+| Manager | Overseer |
+| tickmarkr | Orchestrator daemon |
+| field teams / staff | Workers (agent CLIs in worktrees) |
+| seniors | Watchers (status monitor, gate panes) |
+| engagement | Run (`tickmarkr run` / `resume`) |
+| assertion | Acceptance criterion (`acceptance[]` entry) |
+| tickmark | Passed gate |
+| audit evidence | Evidence gate (commits/diff exist) |
+| audit trail | Journal (`.drovr/runs/<runId>/journal.jsonl`) |
+| the consolidation | Integration branch (`tickmarkr/<runId>`) |
+| sign-off / issuance | Merge consolidation branch to main |
+| unqualified opinion | Green engagement (all tasks merged) |
+| qualified opinion | Failed or stalled engagement |
+| EQR | Acceptance judge (LLM gate vs `acceptance[]`) |
+| National Office | Consult (frontier-model escalation on deadlock) |
+
+Commands below use the real CLI surface — audit terms never replace bin names in examples.
+
+## Invariants
+
+These are law; the codebase fails closed around them:
+
+- `acceptance[]` required on every task; compile fails without it
+- new engagements consolidate to a `tickmarkr/<runId>` branch — never main (resume of older
+  engagements keeps the branch names recorded in their journal, including legacy `drovr/<runId>`)
+- gates never trust worker claims; tickmarkr verifies everything itself
+- state is files + git only (`.drovr/`); no DB, no services
+- worker/judge/review/consult prompts end with machine-parseable trailers
+  (`DROVR_RESULT` / JSON verdicts); parse defensively, fail closed
+
+## Install
+
+Requirements: Node ≥ 20, git, and at least one agent CLI on PATH (`claude`, `codex`, `cursor-agent`,
+`opencode`, `grok`, or `pi`) authenticated through its own login.
+
+```bash
+npm install
+npm run build
+npm link        # exposes the `tickmarkr` bin (and the `drovr` / `drover` compat alias)
+```
+
+Then verify your fleet:
+
+```bash
+tickmarkr doctor   # probes installed adapters, herdr, auth; prints the capability matrix
+```
+
+## Quickstart
+
+```bash
+tickmarkr init                 # guided setup + doctor; scaffolds .drovr/config.yaml and drovr.spec.md
+# edit drovr.spec.md            # the native spec template, marked <!-- drovr:spec -->
+tickmarkr compile drovr.spec.md # spec → .drovr/graph.json (fails without acceptance criteria)
+tickmarkr plan                 # dry-run routing table + cost estimate + floor lints
+tickmarkr run                  # execute the graph (--concurrency N --driver herdr|subprocess --route-strict)
+tickmarkr report <runId> --md  # engagement record in Markdown
+```
+
+Supervise and finish:
+
+```bash
+tickmarkr status               # live engagement state (--watch to follow)
+tickmarkr resume <runId>       # continue an engagement from its audit trail
+tickmarkr approve <runId> <taskId>   # Partner sign-off on a parked task (--by <name> --reason <text>)
+tickmarkr report <runId>       # cost/quality report
+tickmarkr profile              # show the learned routing profile
+tickmarkr unlock               # remove a stale/garbage run lock (refuses if the holder is alive)
+```
+
+Green tasks land on the engagement's `tickmarkr/<runId>` consolidation branch; sign-off to your
+mainline is your call, never tickmarkr's.
+
+### Escalation and National Office verdicts
+
+When gates or field teams stall, tickmarkr escalates to a frontier-model **National Office** consult
+for a structured verdict. The consult can recommend rerouting to a different adapter/model channel,
+or human approval if deadlock persists. Reroute verdicts can target two scopes:
+
+- **Channel-level reroute**: exclude a single channel (e.g., `claude-code:opus-4-8`) and try the next ranked channel
+- **Adapter-level reroute**: exclude an entire adapter (e.g., `cursor-agent`) when the consult detects an environmental
+  CLI-level failure (blocked dialog, auth issue, timeout pattern). The daemon expands the task's exclusion list to cover
+  every available channel of that adapter, ensuring zero re-try of the same root cause
+
+Both exclusion types persist across resume — a task that failed due to a consult reroute will never re-try excluded channels
+or adapters in a subsequent `tickmarkr resume`.
+
+### Approving tasks
+
+`tickmarkr approve` unblocks two task states:
+
+**Human gates** (attempt budget ≥ 1):
+- The task finished with a result but gates require human judgment (`humanGate: true` in the spec)
+- Approving records the Partner's verdict and the task proceeds to merge
+
+**Attempt-cap parks** (attempt budget exhausted):
+- The task has burned its full attempt budget without reaching a conclusive result
+- All channels (including adapter exclusions from prior consults) remain excluded from retry
+- Approving grants a **fresh attempt budget** with the same exclusion list — the task re-routes around all previously-burned channels
+  and adapters, giving it one more escalation ladder before exhaustion
+
+Example: a task escalates away from cursor-agent due to a trust dialog (adapter-level exclusion), then away from all claude-code
+models before hitting the attempt cap. `tickmarkr approve` grants a fresh ladder to try the frontier tier, still avoiding both
+cursor-agent and claude-code entirely.
+
+## Model scoping and auth detection
+
+Each agent CLI exposes a list of available models. tickmarkr's routing works only with **classified** models — those you explicitly enter into `.drovr/config.yaml` under `tiers`. The `tickmarkr doctor` command probes these models to detect auth status and records the results in `.drovr/doctor.json`, which routing consumes to avoid 401/403 dispatch failures.
+
+**Model terminology**:
+
+- **Listed models**: All models a CLI advertises as available (e.g., pi advertises both `pi:glm-5.2` and `pi:anthropic-claude-opus-4-8`, but not all are authed)
+- **Scoped models**: Listed models with an explicit CLI namespace prefix (e.g., `pi:glm-5.2`, `openai:gpt-4o`). The design rule is to classify scoped models primarily, not unscoped listed models
+- **Classified models**: Models you've entered into `tiers` — the routing-eligible set, regardless of scope
+
+When you run `tickmarkr doctor`, it:
+1. Probes each classified model exactly once (one minimal headless API call per model per adapter)
+2. Records results in `.drovr/doctor.json`: `authed: true` or `authed: false` with the failure reason and probe timestamp
+3. Prints a model-status table for classified models only, showing tier, auth verdict, denial status, and prefer rank
+
+**Routing and auth**:
+- Routing discovers channels only from authed classified models (unauthed channels are dropped)
+- `tickmarkr plan` lints each excluded model, naming the probe reason and timestamp
+- If a task's floor can only be satisfied by unauthed models, the plan fails loudly — never a silent fallback
+
+**When to re-run doctor**:
+- After classifying new scoped models into tiers (e.g., onboarding a new vendor or aggregator CLI)
+- Before a run, if credentials may have changed (API key rotation, quota reset, subscription renewal)
+
+**Operator model control — deny.models**:
+You can bench a classified model without removing it from tiers:
+```yaml
+routing:
+  deny:
+    models:
+      - pi:glm-5.2      # stays in tiers, never routes
+      - openai:gpt-4o   # reason in git commit
+```
+`tickmarkr plan` lints denied models identically to unauthed ones. Re-enable by deleting one line.
+
+## Run output and narration
+
+When you execute `tickmarkr run`, the daemon streams live narration of each audit-trail event to stdout — task status changes,
+gate results (tickmarks), worker dispatch, and merge commits. This narration is derived from the append-only `.drovr/runs/<runId>/journal.jsonl`
+ledger, which remains the authoritative source of truth for resumability. If an engagement is interrupted, `tickmarkr resume <runId>`
+replays the journal and picks up where it left off. You can also tail the journal directly for raw event inspection or
+feed it to external tools; the narration is a convenience layer on top.
+
+## Usage and cost
+
+Every engagement record includes a **Usage & efficiency** section showing token/window consumption, cost estimates,
+and first-attempt success rate. Cost reporting follows strict honesty rules and never infers absent data:
+
+### Cost model — two channel economics
+
+**API channels** (real marginal cost):
+- Formula: `tokens × price`
+- Pricing data sourced from [LiteLLM model prices](https://github.com/BerriAI/litellm/blob/main/litellm/model_prices_and_context_window.json)
+- Each estimate carries its basis: input tokens, output tokens, cache reads (if applicable), rate per Mtok, and rate date
+
+**Subscription channels** (flat monthly, no marginal token cost):
+- Two metrics reported when computable:
+  - **Amortized window cost**: `plan monthly cost ÷ usable windows per month` — a range accounting for time-varying quotas
+  - **API-equivalent counterfactual**: `metered tokens × API price of the same/nearest model` — e.g., a $100/month Claude Max user
+    who consumes tokens worth $500 API-equivalent has paid $500 API-equivalent for flat $100
+- Both metrics appear in the report alongside their sample count and range bounds
+
+### Honesty rules (no guessing allowed)
+
+- **Ranges, never single numbers**: quota multipliers and monthly-window variation make subscription costs a range, not a point estimate
+- **"Not measurable" never becomes $0**: if a channel lacks pricing or metering data, the report explicitly states "not measurable"
+- **Basis always shown**: every cost figure prints the token count, rate used, and date so estimates can be audited
+- **No network calls**: pricing config is operator-maintained in `.drovr/config.yaml` (or `~/.config/drovr/config.yaml`), seeded with dated
+  comments and LiteLLM's JSON file named as the copy-from source; tickmarkr never calls home to fetch rates
+- **Attribution from journal**: token counts come from tickmarkr's own telemetry spans in the audit trail, never from provider invoices or dashboards
+
+## Visibility: supervised fleet UX
+
+When running under [herdr](https://herdr.dev), tickmarkr creates a visible, labeled pane-and-tab workspace:
+
+### Tab vocabulary
+
+- **WORKERS**: the primary generation tab showing active field-team tasks. The tab header shows a live token (task ID) plus one state glyph:
+  - ↻ — the member is a retry attempt (attempt > 0)
+  - ✋ — the driver detected the member is blocked
+  - (bare token) — member is running normally
+- **cleanup · <taskId>**: overflow/teardown generation tabs. When a new generation starts (on retry escalation), a new cleanup tab
+  opens labeled with the newest live member's task ID; it auto-closes when the generation completes
+- **watch**: a single pane running `tickmarkr status --watch` — the senior's glanceable engagement monitor
+
+### Pane naming (when visibility.llm = pane)
+
+- **judge · <taskId>**: the EQR evaluating acceptance criteria
+- **review · <taskId>**: the cross-vendor code review gate
+- **consult · <taskId>**: National Office escalation on deadlock (gates or worker stall)
+
+### Notification tiers
+
+Only operator-decision events notify (with sound):
+
+- ✓ Gate failure escalations (move to next channel, human approval needed)
+- ✓ National Office verdicts (deadlock resolved or escalation recommended)
+- ✓ Human gates (task parked, awaiting `tickmarkr approve`)
+- ✓ Quota failover (channel exhausted, routed to next)
+- ✓ Engagement end (unqualified or qualified opinion)
+
+Routine events do NOT notify:
+- ✗ Task dispatch (tab already shows progress)
+- ✗ Task done (tab state updated, already visible)
+
+This keeps the Partner focused on decisions that require attention, not noise.
+
+### Reconciliation model: level-triggered pane lifecycle
+
+tickmarkr closes exactly what it owns and no longer needs, no matter how any process died.
+
+Every pane and tab tickmarkr creates receives a **parseable ownership name** encoding the pane's role, task, attempt, and run:
+- `WORKERS` — active worker generation tab
+- `cleanup · <taskId>` — teardown generation tab for overflow attempts
+- `watch` — status monitor pane
+- `<role> · <taskId> · A<attempt> · R<runId>` — judge, review, consult, and worker panes (formats like `judge · task-abc123 · A1 · Rrun-20260713-175532`)
+
+tickmarkr creates all owned panes only within the run's workspace; any tickmarkr-owned panes discovered outside the run's workspace (from prior runs or placement bugs) are reconciled and closed along with their emptied tabs. Any pane not matching the ownership contract is **foreign** — created by the operator or another tool — and is never a candidate for closing.
+
+**Desired-state reconciliation**: A pure function computes the exact set of panes that should exist from the audit trail at any moment:
+- Worker panes for all in-flight task attempts
+- Gate panes for unread judge/review/consult verdicts
+- The watch pane (if running)
+- Empty set (after engagement end)
+
+The daemon reconciles at every safe point:
+1. **Run start** — clean up any orphaned panes from crashed earlier runs of the same repo
+2. **Resume** — reconcile the restarted journal state and close panes for superseded attempts
+3. **After terminal events** (task done, failed, human gate) — close the corresponding worker/gate pane and its emptied tab
+4. **At engagement end** — close all remaining owned panes and tabs
+
+Reconciliation failures (herdr unavailable, a pane vanished mid-sweep) never fail the engagement — visibility is cosmetic, gates are law.
+
+### Workspace-trust pre-flight
+
+tickmarkr runs field teams in fresh git worktrees cloned from your repo. Before dispatch, every worker checks whether that repo is trusted by its CLI, fail-closed:
+
+**Seeding trust at doctor time**:
+- `tickmarkr doctor` probes each adapter's trust status for your repo root
+- Adapters that can pre-seed trust (codex via `config.toml`, others if applicable) do so automatically; you see `seeded` in the doctor output
+- Adapters requiring manual trust grant show `action-required` with the exact one-time command to run (e.g., `codex init /path/to/repo`)
+- Adapters without a trust concept report `n/a`
+
+**Auto-answering trust dialogs during runs**:
+- Some CLIs (e.g., cursor-agent) cannot pre-seed trust and show an interactive "Workspace Trust Required" dialog the first time they touch the worktree
+- For these CLIs, tickmarkr detects the trust dialog by its fingerprint and auto-answers it exactly once per slot — safe because tickmarkr created the worktree from your own repo
+- Any other blocked dialog still pages the operator for manual approval
+
+## Spec front-ends (what compiles today)
+
+tickmarkr is SDD-agnostic downstream of `compile` — routing, gates, and merges never know which methodology
+produced the graph. Upstream, these front-ends exist:
+
+| Spec source | Support | How |
+|---|---|---|
+| **drovr spec** (native format) | Native/default | `tickmarkr init` template with the `<!-- drovr:spec -->` marker |
+| **Spec Kit** feature dir | Native | dir containing `tasks.md` |
+| **GSD** phase dir | Native | dir containing `*-PLAN.md` |
+| **Markdown PRD** | Native (universal adapter) | any `.md` with tasks + acceptance criteria |
+| OpenSpec, BMAD, Superpowers, others | Not yet | render to a drovr spec (the `<!-- drovr:spec -->` marker plus the full Task surface), or contribute a front-end: one parser module behind `src/compile/index.ts`, same pattern as `gsd.ts` |
+
+Compile fails loudly on anything it can't recognize (`--type native|speckit|prd|gsd` to force).
+
+## Planning layer: intent → spec → engagement
+
+tickmarkr pairs a lightweight planning step (`tickmarkr scope`) with the existing compile/run flow. The flow is:
+
+```
+intent file (prose)
+  ↓ [tickmarkr scope: 3-question gate]
+  ↓ [clarification ≤3 blocking Qs]
+native spec (REQ-nn → oracle → task)
+  ↓ [tickmarkr compile]
+  ↓ [fails without acceptance criteria]
+task graph + routing table
+  ↓ [tickmarkr run]
+  ↓ [gates never trust workers]
+merged green tasks + engagement record
+```
+
+**Clarification gate**: The `tickmarkr scope` CLI enforces ≤3 blocking questions. Drafting refuses until all are answered; residual uncertainty becomes explicit assumptions in the spec.
+
+**Oracle types** — assertions are typed for deterministic verification:
+
+- `oracle: command <cmd>` — exit code (0 = pass); most reliable
+- `oracle: test <name>` — run a named test (must exist in the task's acceptance[] context)
+- `oracle: judge <rubric>` — EQR verdict, fail-closed, never overrides failed command/test
+
+Untyped acceptance strings in existing specs compile as `oracle: judge` + warning (read-old/write-new compat, same as the rename precedent).
+
+**Scope semantics**: Plan-time blast radius is advisory + structured `{paths, confidence, reason}` — never authoritative. The run-time scope gate verifies actual file changes; if a worker requests widening, the daemon pauses as a designed human gate for operator approval.
+
+## Claude Code skills (ship with the repo)
+
+Cloning this repo gives Claude Code project skills under `.claude/skills/`:
+
+- **`/drovr-loop`** — the SDD-agnostic loop: compile one spec, read the plan, run from the journal, merge green work, and commit only the Markdown execution record beside that spec. For GSD bookkeeping, use `/drovr-auto`.
+- **`/drovr-auto`** — the **GSD binding**: run remaining GSD milestone phases autonomously with tickmarkr as the
+  executor (plans → compile → dry-run → run → merge → sync-back). Bindings are per-SDD by nature — the
+  sync-back writes that methodology's artifacts; other SDDs need their own thin binding, not this one.
+- **`/overseer`** — supervise an autonomous tickmarkr engagement from a Herdr workspace: two-tier visible hierarchy,
+  journal-based watchers, gate-failure triage, human-checkpoint routing. Requires `HERDR_ENV=1`.
+
+Repo-scoped: available automatically in Claude Code sessions inside this repo; not installed by npm.
+
+## Development
+
+```bash
+npm test               # vitest unit+integration — zero tokens, fake adapter only
+npm run test:coverage  # coverage floors enforced on core dirs
+npm run e2e            # real-CLI end-to-end (spends tokens; needs ≥1 agent CLI)
+```
+
+Design spec: `docs/superpowers/specs/2026-07-07-drover-design.md`.
+
+## License
+
+MIT

package/dist/adapters/claude-code.d.ts

@@ -0,0 +1,4 @@
+import { type AuthHealth, type WorkerAdapter } from "./types.js";
+export declare function claudeSlug(real: string): string;
+export declare function probeVersion(bin: string): AuthHealth;
+export declare const claudeCode: WorkerAdapter;

package/dist/adapters/claude-code.js

@@ -0,0 +1,191 @@
+import { spawnSync } from "node:child_process";
+import { readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { parseWorkerResult } from "./prompt.js";
+import { channelsFromConfig, shq, TokenUsageSchema } from "./types.js";
+// SPEND-01/SPEND-11: claude writes a per-session JSONL to ~/.claude/projects/<slug>/ where slug is the
+// realpath'd cwd with every non-alphanumeric char replaced by "-" (verified 114/114 — 36-DIAGNOSIS.md).
+// The old `/`-only formula missed the "." in `.drovr/worktrees/…` — ENOENT on every worktree dispatch.
+// Each assistant message carries a per-record ISO `timestamp` and message.usage. We read it POST-HOC
+// (never the pane, never the trailer) and sum
+// tokens for records whose top-level cwd matches this task's worktree AND whose timestamp is at/after
+// `sinceMs` (this attempt's dispatch wall-clock, from the daemon). The cursor makes a per-attempt fold
+// correct even though this store ACCUMULATES across attempts under a stable slug — without it, folding
+// gives 3A+2B+C (checker blocker). Filter PER RECORD by the record's own timestamp, never file mtime.
+// FAIL OPEN everywhere: any missing dir / unreadable file / torn line / no match / unparseable
+// timestamp ⇒ undefined ⇒ unmetered. A metering read must NEVER throw — it must never fail a task.
+// SPEND-06: we sum ONLY the four token counts. message.usage may also carry a costUSD — a NOTIONAL
+// list price (0.74 for a two-token sub reply, LIVE-CHECK finding 3); we never read it. Money is
+// Phase 18's operator-price × tokens derivation, not a CLI claim.
+const MAX_SESSION_FILES = 20; // newest-first; a long-lived project dir can hold many sessions
+const MAX_SESSION_BYTES = 8_000_000; // per-file cap; a runaway JSONL cannot make the read unbounded
+export function claudeSlug(real) {
+    return real.replace(/[^A-Za-z0-9]/g, "-");
+}
+export function probeVersion(bin) {
+    const r = spawnSync(bin, ["--version"], { encoding: "utf8", timeout: 10000 });
+    if (r.error || r.status !== 0)
+        return { installed: false, authed: false, models: [] };
+    return {
+        installed: true,
+        authed: true,
+        version: (r.stdout || r.stderr).trim().split("\n")[0],
+        models: [],
+        note: "auth assumed; verified at dispatch (failover on auth/quota errors)",
+    };
+}
+export const claudeCode = {
+    id: "claude-code",
+    vendor: "anthropic",
+    probe: async () => probeVersion("claude"),
+    channels: (cfg) => channelsFromConfig("claude-code", cfg),
+    // --strict-mcp-config --mcp-config '{"mcpServers":{}}': pin the MCP surface to empty so fresh-worktree
+    // workers/gates don't load project .mcp.json servers (herdr scrapes dialogs as idle — v1.4 incident,
+    // memory drovr-worker-mcp-dialog-stall). Live-verified 2026-07-10 on claude 2.1.205 (operator check):
+    // headless (-p) fully suppressed — exit 0, no dialog. Interactive TUI STILL shows the project
+    // MCP-enable dialog (project trust/enablement, not config loading); Esc dismisses it, and drovr's
+    // blocked/idle paging surfaces the pane to the operator (same path as cursor's trust dialog).
+    // Gotchas (both bit the 2026-07-10 live check): bare '{}' is REJECTED ("mcpServers: expected record"),
+    // and --mcp-config is VARIADIC — a positional after it is eaten as a config-file path, so another
+    // flag must always follow the value, never the prompt.
+    headlessCommand: (promptFile, model) => `claude -p "$(cat ${shq(promptFile)})" --model ${shq(model)} --permission-mode acceptEdits --strict-mcp-config --mcp-config '{"mcpServers":{}}' --output-format text`,
+    // HYG-03: the residual first-entry dialog on an interactive TUI is the workspace TRUST dialog (not MCP
+    // config loading) — CLI-imposed, no flag to pre-accept, only store is claude's global last-writer-wins
+    // ~/.claude.json keyed on the exact path. Closed WON'T-FIX (decision B, 2026-07-10): drovr writes nothing
+    // to that file (a seed races claude's own writes, nondeterministically). Amortizes to one operator dismissal
+    // per stable worktree path; blocked-pane paging surfaces it. Do NOT change this command to "fix" the dialog —
+    // see .planning/REQUIREMENTS.md HYG-03 and 21-02-LIVE-CHECK.md. Revisit if upstream ships a --trust flag.
+    interactiveCommand: (promptFile, model) => `claude --model ${shq(model)} --strict-mcp-config --mcp-config '{"mcpServers":{}}' --permission-mode acceptEdits "$(cat ${shq(promptFile)})"`,
+    resumeCommand: (sessionId, promptFile, model) => `claude -r ${shq(sessionId)} --model ${shq(model)} --strict-mcp-config --mcp-config '{"mcpServers":{}}' --permission-mode acceptEdits "$(cat ${shq(promptFile)})"`,
+    invoke(task, _cwd, a, ctx) {
+        return { command: this.headlessCommand(ctx.promptFile, a.model) };
+    },
+    parse: parseWorkerResult,
+    collectUsage(cwd, sinceMs) {
+        try {
+            const real = realpathSync(cwd); // resolve symlinks (darwin /tmp → /private/tmp)
+            const slug = claudeSlug(real);
+            const dir = join(homedir(), ".claude", "projects", slug);
+            // newest-first by mtime, bounded — mtime picks WHICH files to scan, never a record's cursor.
+            const files = readdirSync(dir)
+                .filter((f) => f.endsWith(".jsonl"))
+                .map((f) => {
+                try {
+                    return { f, m: statSync(join(dir, f)).mtimeMs };
+                }
+                catch {
+                    return undefined; // a stat failure just drops that file
+                }
+            })
+                .filter((x) => x !== undefined)
+                .sort((a, b) => b.m - a.m)
+                .slice(0, MAX_SESSION_FILES);
+            let input = 0, output = 0, kept = false;
+            let cacheRead, cacheWrite;
+            const seen = new Set(); // message.id is globally unique across session files in one call
+            for (const { f } of files) {
+                let text;
+                try {
+                    text = readFileSync(join(dir, f), "utf8").slice(0, MAX_SESSION_BYTES);
+                }
+                catch {
+                    continue; // unreadable file ⇒ skip
+                }
+                for (const line of text.split("\n")) {
+                    if (!line.trim())
+                        continue;
+                    let recRaw;
+                    try {
+                        recRaw = JSON.parse(line); // torn final line / garbage ⇒ dropped
+                    }
+                    catch {
+                        continue;
+                    }
+                    const rec = recRaw;
+                    if (rec.cwd !== real)
+                        continue;
+                    const u = rec.message?.usage;
+                    if (!u || typeof u !== "object")
+                        continue;
+                    const ts = Date.parse(String(rec.timestamp));
+                    if (!Number.isFinite(ts) || ts < sinceMs)
+                        continue; // absent/unparseable/pre-cursor ⇒ skip
+                    // claude splits one assistant response across N records (one per content block), each
+                    // repeating the FULL message.usage; dedup after the cursor so a pre-sinceMs id cannot poison seen.
+                    const id = rec.message?.id;
+                    if (typeof id === "string") {
+                        if (seen.has(id))
+                            continue;
+                        seen.add(id);
+                    }
+                    const uu = u;
+                    const n = (k) => (typeof uu[k] === "number" ? uu[k] : 0);
+                    input += n("input_tokens");
+                    output += n("output_tokens");
+                    if ("cache_read_input_tokens" in uu)
+                        cacheRead = (cacheRead ?? 0) + n("cache_read_input_tokens");
+                    if ("cache_creation_input_tokens" in uu)
+                        cacheWrite = (cacheWrite ?? 0) + n("cache_creation_input_tokens");
+                    kept = true;
+                }
+            }
+            if (!kept)
+                return undefined; // nothing matched ⇒ unmetered, never {input:0,…}
+            const out = { input, output, ...(cacheRead !== undefined ? { cacheRead } : {}), ...(cacheWrite !== undefined ? { cacheWrite } : {}) };
+            const p = TokenUsageSchema.safeParse(out);
+            return p.success ? p.data : undefined;
+        }
+        catch {
+            return undefined; // missing dir / any throw ⇒ fail open
+        }
+    },
+    // v1.23 T1: last-turn context fill from ~/.claude/projects/<slug>/<sessionId>.jsonl ONLY.
+    // tokens = input_tokens + cache_creation_input_tokens + cache_read_input_tokens of the LAST
+    // assistant usage record (not a sum over turns — ctx-watch.sh class; overseer wake signal).
+    // Disk read only: no claude spawn, no pane, no network. null = unknown.
+    contextUsage(session) {
+        try {
+            const real = realpathSync(session.cwd);
+            const slug = claudeSlug(real);
+            // session id is a filename stem (herdr agent_session.value); refuse path traversal.
+            const sid = session.id.replace(/\.jsonl$/i, "");
+            if (!sid || sid.includes("/") || sid.includes("\\") || sid.includes(".."))
+                return null;
+            const file = join(homedir(), ".claude", "projects", slug, `${sid}.jsonl`);
+            let text;
+            try {
+                text = readFileSync(file, "utf8").slice(0, MAX_SESSION_BYTES);
+            }
+            catch {
+                return null;
+            }
+            let last;
+            for (const line of text.split("\n")) {
+                if (!line.trim())
+                    continue;
+                let recRaw;
+                try {
+                    recRaw = JSON.parse(line);
+                }
+                catch {
+                    continue;
+                }
+                const rec = recRaw;
+                const u = rec.message?.usage;
+                if (!u || typeof u !== "object")
+                    continue;
+                const uu = u;
+                const n = (k) => (typeof uu[k] === "number" ? uu[k] : 0);
+                // last turn wins — overwrite, never accumulate (the sum-over-turns bug this API exists to avoid)
+                last = n("input_tokens") + n("cache_creation_input_tokens") + n("cache_read_input_tokens");
+            }
+            if (last === undefined)
+                return null;
+            return { tokens: last };
+        }
+        catch {
+            return null;
+        }
+    },
+};

package/dist/adapters/codex.d.ts

@@ -0,0 +1,8 @@
+import { type TrustVerdict, type WorkerAdapter } from "./types.js";
+export declare function readCodexModelsCache(path?: string): {
+    models: string[];
+    fetchedAt?: string;
+};
+export declare function seedCodexTrust(repoRoot: string, configPath?: string): TrustVerdict;
+export declare function hasCodexTrustedProject(text: string, root: string): boolean;
+export declare const codex: WorkerAdapter;