@sema-agent/server 1.322.0 → 2.0.0

package/dist/plugins/worktree-isolation.js

@@ -1,36 +1,109 @@
+/**
+ * SVC-3 — git-WORKTREE ISOLATION wrapper for the deployment-level `executionEnvFactory` (design/97
+ * CORE-6). A higher-order factory that mints a per-AGENT isolated git worktree when (and ONLY
+ * when) core threads `ctx.isolation === "worktree"` through the TRUSTED `RunInternals` channel.
+ *
+ * WHY this lives in service, not core: core ships the env-AGNOSTIC primitive (`addWorktree` / `pruneWorktrees`
+ * on the base `ExecutionEnv` seam, plus the `ExecutionEnvFactoryContext.isolation` hint). The env-SPECIFIC
+ * bits — which concrete adapter roots an env at the worktree dir, which repo is the operator-trusted base,
+ * where the reaper runs — are deployment wiring, so they belong here (铁律 core-service-boundary). We consume
+ * the core export; we do NOT reimplement the git plumbing.
+ *
+ * SHAPE (per the task contract):
+ *   const factory = withWorktreeIsolation(baseFactory, opts);
+ *   - ctx.isolation === "worktree": `addWorktree(baseEnvForGit, { repoRoot, sessionId: ctx.sessionId,
+ *     rootEnvAt, commit? })` → a worktree-rooted env WITH `destroy()` (the Runner calls it on task end →
+ *     `git worktree remove --force`, which tears down ONLY that worktree, never the base repo).
+ *   - otherwise: `baseFactory(ctx)` verbatim — the SHARED base env, NO `destroy` (the Runner must never tear
+ *     the base down). Non-isolated tasks behave exactly as before this wrapper existed.
+ *
+ * 🔴 TRUST GATE (the whole point of SVC-3): the ONLY input that turns isolation ON is core's
+ * `ctx.isolation` — populated from `ctx.agent({ isolation })` via the TRUSTED `RunInternals`, which core
+ * guarantees is NEVER sourced from the untrusted `TaskSpec` (see core remote-env.ts §isolation). This wrapper
+ * reads NOTHING else from `ctx` to decide isolation, and `repoRoot` comes ENTIRELY from the operator-supplied
+ * closure (config), never from any task/`ctx` field — so an untrusted caller can neither flip isolation on a
+ * repo it shouldn't touch nor inject a `repoRoot` path to escape the allowed roots. We additionally assert the
+ * configured `repoRoot` is contained within an operator-trusted `allowedRoots` set at wrap time (defence in
+ * depth: a mis-wired deployment fails loud rather than git-worktree-ing an arbitrary path).
+ *
+ * 🔴 ISOLATE-ONLY (clay): the runtime NEVER merges a worktree back. The orchestrator script reads each
+ * worktree's result (via the worktree dir / the snapshot) and decides verify+merge in USERLAND. We only mint
+ * and reap; merge policy is not ours.
+ *
+ * ⚠️ BOUNDARY CAVEATS (from core's CORE-6 doc — kept here so a future wirer doesn't reintroduce
+ * a footgun):
+ *  - durable-suspend is INCOMPATIBLE with a worktree env: core's prepare-task rejects a NON-remote factory env
+ *    for a suspendable run (a host/NodeExecutionEnv-rooted worktree is not snapshotable). So an isolated agent
+ *    MUST run to completion without parking — do NOT combine `isolation:"worktree"` with a suspend/HITL park
+ *    on the host lane. (On an isolated lane like e2b/k8s the worktree would have to root a REMOTE env; that is
+ *    a follow-on, see `rootEnvAt` below — host lane is v1.)
+ *  - `git worktree` isolates the git WORKING COPY, not arbitrary shell access: bash inside the worktree can
+ *    still reach the host filesystem/network. The worktree is a coordination boundary, NOT a security sandbox
+ *    — pair it with a real sandbox lane (e2b/k8s/local-docker) when isolation from the host is required.
+ *  - UNCOMMITTED changes in the base repo are ABSENT in the child worktree (core creates it `--detach` at
+ *    `HEAD`/`commit`). An isolated agent sees the committed tree only — commit (or stash→apply, in userland)
+ *    before fanning out if the base's dirty state must be visible.
+ *  - a worktree orphaned by a process CRASH (the Runner never reached `destroy`) is reaped by
+ *    {@link pruneWorktrees} — wired into the service reaper (best-effort, userland; core ships no post-kill
+ *    Runner hook).
+ */
 import path from "node:path";
 import { addWorktree, pruneWorktrees, } from "@sema-agent/core";
+/** Normalize a path for containment checks: resolve to absolute + drop a trailing separator. */
 function norm(p) {
     const r = path.resolve(p);
     return r.length > 1 && r.endsWith(path.sep) ? r.slice(0, -1) : r;
 }
+/** True when `child` is `root` itself or a descendant of it (segment-aware: `/a/b` is NOT under `/a/bc`). */
 function isWithin(root, child) {
     const r = norm(root);
     const c = norm(child);
     if (c === r)
         return true;
     const rel = path.relative(r, c);
+    // path.relative returns "" for equal, a non-"../"-leading relative for a descendant, and a "../"-leading
+    // (or absolute, on Windows drive change) path for an outside/sibling target.
     return rel.length > 0 && !rel.startsWith("..") && !path.isAbsolute(rel);
 }
+/**
+ * Wrap a deployment's `executionEnvFactory` so an agent with `ctx.isolation === "worktree"` runs in its own
+ * detached git worktree. See the file header for the full contract + trust gate + caveats.
+ *
+ * Throws at WRAP time (fail-loud, not faked) if `repoRoot` is not contained within `allowedRoots` — a
+ * mis-wired deployment must not silently git-worktree an arbitrary path.
+ */
 export function withWorktreeIsolation(baseFactory, opts) {
     const repoRoot = norm(opts.repoRoot);
     const allowedRoots = (opts.allowedRoots?.length ? opts.allowedRoots : [repoRoot]).map(norm);
+    // Trust gate (defence in depth): the configured repoRoot must live inside an operator-trusted root. This is
+    // a CONFIG invariant (repoRoot is never a task input), so a violation = mis-wire → fail loud at boot.
     if (!allowedRoots.some((root) => isWithin(root, repoRoot))) {
         throw new Error(`withWorktreeIsolation: repoRoot ${repoRoot} is not within any allowedRoots [${allowedRoots.join(", ")}] — refusing to git-worktree an untrusted path`);
     }
+    // SERIALIZE git worktree ADMIN ops on this shared repo. `git worktree add`/`remove` mutate the repo's
+    // `.git/worktrees` registry under a repo-level lock; running them CONCURRENTLY against one repo races (a
+    // parallel fan-out finishing together → the Runner calls several `destroy()` at once → some
+    // `git worktree remove` lose the lock and leave the worktree dir+registration behind — an orphan the
+    // dir-only `pruneWorktrees` can't reap). A per-wrapper (= per-repoRoot) promise-chain mutex chains every
+    // add/remove so they apply one at a time (git ops are fast + serial-safe; the agents themselves still run
+    // fully in parallel — only the ~ms git bookkeeping serializes).
     let gitLock = Promise.resolve();
     const serialize = (fn) => {
-        const run = gitLock.then(fn, fn);
+        const run = gitLock.then(fn, fn); // run after the prior op SETTLES (success OR failure — never deadlock)
         gitLock = run.then(() => undefined, () => undefined);
         return run;
     };
     return async (ctx) => {
+        // TRUST GATE: the ONLY trigger is core's RunInternals-sourced ctx.isolation. We read nothing else from ctx
+        // (and never anything from a TaskSpec) to decide isolation — see file header.
         if (ctx.isolation !== "worktree") {
+            // Non-isolated: the SHARED base env, verbatim, NO destroy attached → the Runner never tears the base
+            // down (core's hasDestroy() returns false for a plain base env). Behaviour identical to no wrapper.
             return baseFactory(ctx);
         }
         const { env, worktreeDir } = await serialize(() => addWorktree(opts.baseEnvForGit, {
             repoRoot,
-            sessionId: ctx.sessionId,
+            sessionId: ctx.sessionId, // core sanitizes this into the worktree dir name (human-readable orphan diag)
             rootEnvAt: opts.rootEnvAt,
             ...(opts.commit ? { commit: opts.commit } : {}),
         }));
@@ -39,28 +112,54 @@ export function withWorktreeIsolation(baseFactory, opts) {
             ...(ctx.taskId ? { taskId: ctx.taskId } : {}),
             worktreeDir,
         });
+        // Wrap core's `destroy()` (runs `git worktree remove`) through the SAME mutex so a concurrent teardown can't
+        // race the registry lock and orphan the worktree. The other env methods (exec/fs) keep their own binding —
+        // we only override `destroy`. Idempotent at the git level (remove of an already-gone worktree is a no-op).
+        //
+        // POST-MORTEM + RETRY (2026-07-26, the deterministic pin for the 30-round reaper-race intermittent):
+        // core's destroy is FAIL-OPEN on the remove — `git-worktree-env.js` neither checks the exec Result nor lets a
+        // rejection out (`.catch(() => undefined)`), so one transient failure (spawn EAGAIN/EMFILE under full-suite
+        // load) resolves destroy() normally while leaving dir+registration behind — and `git worktree prune` can NEVER
+        // reap a worktree whose dir still exists, so the orphan is permanent. Until core checks the result (reported),
+        // we verify the dir is actually gone after each destroy, retry ONCE on residue, and FAIL LOUD if it survives
+        // both — a thrown teardown is diagnosable; a silently-accumulating orphan tree is not.
         const coreDestroy = env.destroy.bind(env);
         const residue = async () => {
             const r = await opts.baseEnvForGit.exists(worktreeDir);
-            return r.ok ? r.value : false;
+            return r.ok ? r.value : false; // can't verify (base env unhealthy) → don't invent a residue; destroy stays best-effort
         };
+        // IDEMPOTENCY (core 1.423): the remove leg is now FAIL-LOUD ([1796]§二 → [1801] — the fail-open this wrapper's
+        // post-mortem was built against is fixed), so a REPEAT destroy would hit `git worktree remove` on an
+        // already-removed worktree and reject. A completed destroy + no residue ⇒ short-circuit (the goal state is
+        // already reached; double/concurrent destroy is a legal Runner shape). The first call always goes through
+        // coreDestroy (the inner env's own teardown must run).
         let destroyedOnce = false;
         env.destroy = () => serialize(async () => {
             if (destroyedOnce && !(await residue()))
-                return;
+                return; // idempotent repeat — done is done
             await coreDestroy();
             destroyedOnce = true;
             if (!(await residue()))
                 return;
             opts.logger?.warn?.("worktree_destroy_residue_retry", { worktreeDir, sessionId: ctx.sessionId });
-            await coreDestroy();
+            await coreDestroy(); // second shot on a live registration/dir — safe; a missing one is short-circuited above
             if (await residue()) {
                 throw new Error(`worktree destroy left residue at ${worktreeDir} (git worktree remove failed twice — see core git-worktree-env fail-open)`);
             }
         });
-        return env;
+        return env; // carries the serialized destroy() → core's Runner removes the worktree (ONLY this one) on task end.
     };
 }
+/**
+ * Best-effort reaper hook: deregister worktrees orphaned by a process crash (the Runner never reached
+ * `destroy`). Core's {@link pruneWorktrees} runs `git worktree prune` against the base repo — it cleans up
+ * registrations whose worktree dirs are already gone. Wired into the service reaper (userland; core ships no
+ * post-kill Runner hook). NEVER throws (a prune failure is logged, never fatal).
+ *
+ * NOTE: `git worktree prune` only deregisters worktrees whose DIRECTORY is missing. A crashed run that left
+ * the dir intact is NOT reaped by prune alone — that is acceptable for v1 (the worktree lives under the known
+ * `.sema-worktrees/` parent and is human-/script-reapable; a stricter age-based sweep is a follow-on).
+ */
 export async function reapOrphanWorktrees(baseEnvForGit, repoRoot, logger) {
     try {
         await pruneWorktrees(baseEnvForGit, norm(repoRoot));

package/dist/plugins/write-behind-counter.d.ts

@@ -1,10 +1,45 @@
+/**
+ * Cross-replica write-behind aggregating counter — the shared mechanism behind the cost quota (P0-1)
+ * and the rate limiter (P0-2), on BOTH dialects. Both are additive per-key counters over an aligned fixed
+ * window, so the shared store uses an ATOMIC INCREMENT (`val = val + delta`), never last-writer-wins.
+ *
+ * design/158 A12 C1b: this file used to be MySQL-hardwired and the PG lane carried TWO inline copies of the
+ * same 150-line class (pg-cost-quota.ts's private `PgWriteBehindCounter` + pg-rate-limiter.ts's exported one).
+ * They are now ONE dialect-parameterized implementation; `WriteBehindCounter` (mysql2) and
+ * `PgWriteBehindCounter` (node-pg) remain as ctor subclasses so every call site and test keeps its shape.
+ *
+ * Hot path stays sync: `addLocal` accumulates a local pending delta, `used` reads (cached fleet total
+ * from the last refresh) + (this replica's unflushed delta). A periodic `flush` pushes deltas atomically
+ * and refreshes the current window's fleet totals into the cache.
+ *
+ * Consistency is **eventual** → this is **SOFT limiting**: a replica may briefly exceed the ceiling by
+ * up to (replicas × per-flush-interval spend/requests) at the boundary before peers' totals propagate.
+ * Right for cost/fairness ceilings (and backstopped, for cost, by the hard per-task `maxCostUsd` gate).
+ * A HARD compliance ceiling would instead need a linearizable CAS/atomic count, not write-behind — same
+ * trade as the cross-replica circuit breaker. Windows are aligned fixed buckets (`floor(now/windowMs)`),
+ * the standard distributed choice (a rolling per-key window is the hard part to coordinate cross-replica).
+ *
+ * ── Dialect deltas, kept EXPLICIT (the four the PG twins' file headers used to list) ──────────────────
+ *   - placeholders `?` vs `$1..$n`
+ *   - atomic increment: `ON DUPLICATE KEY UPDATE val = val + VALUES(val)` vs
+ *     `ON CONFLICT (<keyCol>, window_bucket) DO UPDATE SET val = <table>.val + EXCLUDED.val`
+ *   - affected rows: mysql2 `ResultSetHeader.affectedRows` vs node-pg `result.rowCount`
+ *   - BIGINT/INT read back: node-pg returns them as STRINGS → always `Number(...)` on read (the read path
+ *     already wraps every counter cell, so this is a no-op difference at the JS boundary)
+ *   - per-query timeout ARG SHAPE: mysql2 takes `{sql, timeout}` as the first query arg; node-pg takes a
+ *     `QueryConfig` with `query_timeout`. That is why this file keeps its own exec instead of using
+ *     sql-driver.ts (which is on the plain `(sql, params)` form).
+ */
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 export interface CounterTable {
+    /** Table name; must have columns (<keyCol>, window_bucket BIGINT, <valCol>, updated_at). */
     table: string;
     keyCol: string;
     valCol: string;
 }
+/** S9 (SILENT-FALLBACK P0-e): a flush/refresh failure notification. `streak` = consecutive failures of that
+ *  kind (0 = recovered); `prevStreak` lets the consumer detect the recovery edge. Shared by both dialects. */
 export interface CounterDegradeInfo {
     table: string;
     kind: "flush" | "refresh" | "stalled";
@@ -13,8 +48,14 @@ export interface CounterDegradeInfo {
     error?: string;
 }
 export type CounterDegradeHook = (info: CounterDegradeInfo) => void;
+/** S9 deeper fix: default per-query timeout for the counter family's statements. Always ON (unlike the
+ *  opt-in pool-wide DB_QUERY_TIMEOUT_MS): every statement here is a tiny single-row/single-bucket op, so
+ *  30s is ~1000× headroom — a query that slow IS the S9 pathology (a DB-side hang would otherwise pin the
+ *  flush round forever; the stalled watchdog can then only report, not recover). The rejection lands in
+ *  the existing flush/refresh catch → the S9 streak telemetry counts it; the round ENDS and retries. */
 export declare const DEFAULT_COUNTER_QUERY_TIMEOUT_MS = 30000;
 type CounterDialect = "tidb" | "pg";
+/** Dual-dialect write-behind aggregating counter. See the file header for the dialect-delta ledger. */
 export declare class SqlWriteBehindCounter {
     private readonly dialect;
     private readonly pool;
@@ -29,24 +70,38 @@ export declare class SqlWriteBehindCounter {
     private flushing;
     private flushStartedAt;
     private failStreak;
-    constructor(dialect: CounterDialect, pool: MySqlPool | PgPool, t: CounterTable, windowMs: number, now?: () => number, onDegraded?: CounterDegradeHook | undefined, queryTimeoutMs?: number);
+    constructor(dialect: CounterDialect, pool: MySqlPool | PgPool, t: CounterTable, windowMs: number, now?: () => number, onDegraded?: CounterDegradeHook | undefined, // S9: observability tap — never affects counting
+    queryTimeoutMs?: number);
+    /** The ONLY place the two drivers' query shapes diverge. Returns {rows, affected}. */
     private exec;
+    /** S9: track the consecutive-failure streak per kind and notify on every failure + on the recovery edge
+     *  (streak>0 → 0). Steady healthy state stays silent. The hook must never break the counter. */
     private bump;
     bucket(): number;
     private rk;
+    /** Cached fleet total (peers, from the last refresh) + this replica's unflushed delta, current window. */
     used(key: string): number;
     addLocal(key: string, n: number): void;
+    /** Seconds until the current aligned window rolls over. */
     retryAfterSec(): number;
+    /** Atomically push pending deltas, then refresh the current window's fleet totals + reap old buckets.
+     *  Reentrancy-guarded: two overlapping flushes would each apply `+delta` from the same snapshot and
+     *  double-count into the shared table (inflating fleet totals → spurious rate-limit/quota rejection). */
     flush(): Promise<void>;
     private flushOnce;
+    /** Load the current window's fleet totals into the cache (pendingDelta is separate → never clobbered). */
     refresh(): Promise<void>;
+    /** Delete expired window buckets to bound the table. */
     reap(): Promise<number>;
     startRefresh(intervalMs?: number): this;
     stop(): void;
 }
+/** MySQL-protocol (TiDB) binding — historical class name + ctor shape preserved. */
 export declare class WriteBehindCounter extends SqlWriteBehindCounter {
     constructor(pool: MySqlPool, t: CounterTable, windowMs: number, now?: () => number, onDegraded?: CounterDegradeHook, queryTimeoutMs?: number);
 }
+/** PostgreSQL binding — the class pg-rate-limiter.ts used to define inline (and pg-cost-quota.ts duplicated
+ *  privately, hardwired to the cost_quota columns). Same ctor shape as the mysql2 twin. */
 export declare class PgWriteBehindCounter extends SqlWriteBehindCounter {
     constructor(pool: PgPool, t: CounterTable, windowMs: number, now?: () => number, onDegraded?: CounterDegradeHook, queryTimeoutMs?: number);
 }

package/dist/plugins/write-behind-counter.js

@@ -1,5 +1,11 @@
-const SEP = "\u0000";
+const SEP = "\u0000"; // NUL — can't appear in a principal / scope / IP key
+/** S9 deeper fix: default per-query timeout for the counter family's statements. Always ON (unlike the
+ *  opt-in pool-wide DB_QUERY_TIMEOUT_MS): every statement here is a tiny single-row/single-bucket op, so
+ *  30s is ~1000× headroom — a query that slow IS the S9 pathology (a DB-side hang would otherwise pin the
+ *  flush round forever; the stalled watchdog can then only report, not recover). The rejection lands in
+ *  the existing flush/refresh catch → the S9 streak telemetry counts it; the round ENDS and retries. */
 export const DEFAULT_COUNTER_QUERY_TIMEOUT_MS = 30_000;
+/** Dual-dialect write-behind aggregating counter. See the file header for the dialect-delta ledger. */
 export class SqlWriteBehindCounter {
     dialect;
     pool;
@@ -8,13 +14,18 @@ export class SqlWriteBehindCounter {
     now;
     onDegraded;
     queryTimeoutMs;
-    pendingDelta = new Map();
-    fleetTotal = new Map();
+    pendingDelta = new Map(); // unflushed local, by rowKey (key + window bucket)
+    fleetTotal = new Map(); // peers' current-window view, refreshed periodically
     timer;
     flushing = false;
-    flushStartedAt = 0;
-    failStreak = new Map();
-    constructor(dialect, pool, t, windowMs, now = () => Date.now(), onDegraded, queryTimeoutMs = DEFAULT_COUNTER_QUERY_TIMEOUT_MS) {
+    flushStartedAt = 0; // S9 review MED-1: hang-watchdog anchor // reentrancy guard: a flush slower than the timer interval must not overlap
+    failStreak = new Map(); // S9: consecutive-failure runs, per kind
+    constructor(dialect, pool, t, windowMs, now = () => Date.now(), onDegraded, // S9: observability tap — never affects counting
+    // S9 deeper fix: per-query inactivity timeout. mysql2's is the client-side `{sql, timeout}` form (the
+    // connection is held until the hung command really ends, so a poisoned connection is never reused
+    // mid-query); node-pg's is `query_timeout` on the QueryConfig. Overridable via DB_QUERY_TIMEOUT_MS
+    // (threaded by store-backend.ts); the default keeps the counter face always bounded.
+    queryTimeoutMs = DEFAULT_COUNTER_QUERY_TIMEOUT_MS) {
         this.dialect = dialect;
         this.pool = pool;
         this.t = t;
@@ -23,6 +34,7 @@ export class SqlWriteBehindCounter {
         this.onDegraded = onDegraded;
         this.queryTimeoutMs = queryTimeoutMs;
     }
+    /** The ONLY place the two drivers' query shapes diverge. Returns {rows, affected}. */
     async exec(sql, params) {
         if (this.dialect === "tidb") {
             const [r] = (await this.pool.query({ sql, timeout: this.queryTimeoutMs }, params));
@@ -34,6 +46,8 @@ export class SqlWriteBehindCounter {
         const res = await this.pool.query(q);
         return { rows: (res.rows ?? []), affected: res.rowCount ?? 0 };
     }
+    /** S9: track the consecutive-failure streak per kind and notify on every failure + on the recovery edge
+     *  (streak>0 → 0). Steady healthy state stays silent. The hook must never break the counter. */
     bump(kind, failed, error) {
         if (!this.onDegraded)
             return;
@@ -46,6 +60,7 @@ export class SqlWriteBehindCounter {
             this.onDegraded({ table: this.t.table, kind, streak: next, prevStreak: prev, ...(failed && error !== undefined ? { error: error instanceof Error ? error.message : String(error) } : {}) });
         }
         catch {
+            /* observability must never break the counter */
         }
     }
     bucket() {
@@ -54,6 +69,7 @@ export class SqlWriteBehindCounter {
     rk(key) {
         return `${key}${SEP}${this.bucket()}`;
     }
+    /** Cached fleet total (peers, from the last refresh) + this replica's unflushed delta, current window. */
     used(key) {
         const rk = this.rk(key);
         return (this.fleetTotal.get(rk) ?? 0) + (this.pendingDelta.get(rk) ?? 0);
@@ -64,11 +80,20 @@ export class SqlWriteBehindCounter {
         const rk = this.rk(key);
         this.pendingDelta.set(rk, (this.pendingDelta.get(rk) ?? 0) + n);
     }
+    /** Seconds until the current aligned window rolls over. */
     retryAfterSec() {
         return Math.ceil(((this.bucket() + 1) * this.windowMs - this.now()) / 1000);
     }
+    /** Atomically push pending deltas, then refresh the current window's fleet totals + reap old buckets.
+     *  Reentrancy-guarded: two overlapping flushes would each apply `+delta` from the same snapshot and
+     *  double-count into the shared table (inflating fleet totals → spurious rate-limit/quota rejection). */
     async flush() {
         if (this.flushing) {
+            // S9 review MED-1: a hung query holds this guard: every later tick returns HERE and bump() is never
+            // reached, so the reject-path telemetry goes silent exactly when the fleet is degraded. Surface the
+            // stall itself — >60s inside one flush round = a "stalled" failure signal per tick; its streak clears
+            // when the round finally settles. (The per-query timeout above is the deeper fix — a round now self-
+            // terminates at queryTimeoutMs; this watchdog stays as the backstop for anything it doesn't cover.)
             if (this.now() - this.flushStartedAt > 60_000)
                 this.bump("stalled", true, "flush round stalled >60s (hung query?)");
             return;
@@ -80,17 +105,18 @@ export class SqlWriteBehindCounter {
         }
         finally {
             this.flushing = false;
-            this.bump("stalled", false);
+            this.bump("stalled", false); // watchdog recovery edge (no-op if it never fired)
         }
     }
     async flushOnce() {
         const { table, keyCol, valCol } = this.t;
+        // The atomic-increment upsert — the ONE statement whose dialect delta actually matters here.
         const sql = this.dialect === "tidb"
             ? `INSERT INTO ${table} (${keyCol}, window_bucket, ${valCol}, updated_at) VALUES (?,?,?,?) ` +
                 `ON DUPLICATE KEY UPDATE ${valCol} = ${valCol} + VALUES(${valCol}), updated_at = VALUES(updated_at)`
             : `INSERT INTO ${table} (${keyCol}, window_bucket, ${valCol}, updated_at) VALUES ($1,$2,$3,$4) ` +
                 `ON CONFLICT (${keyCol}, window_bucket) DO UPDATE SET ${valCol} = ${table}.${valCol} + EXCLUDED.${valCol}, updated_at = EXCLUDED.updated_at`;
-        let attempted = false;
+        let attempted = false; // S9: only score a flush round that actually tried a write
         let failure;
         let hadFailure = false;
         for (const [rk, delta] of [...this.pendingDelta]) {
@@ -101,7 +127,8 @@ export class SqlWriteBehindCounter {
             const windowBucket = Number(rk.slice(sep + 1));
             attempted = true;
             try {
-                await this.exec(sql, [key, windowBucket, delta, new Date()]);
+                await this.exec(sql, [key, windowBucket, delta, new Date()]); // S9 deeper fix: a hung INSERT rejects into the catch below (streak counts it)
+                // subtract what we flushed (not delete — a concurrent addLocal may have grown it meanwhile)
                 const remaining = (this.pendingDelta.get(rk) ?? 0) - delta;
                 if (remaining > 0)
                     this.pendingDelta.set(rk, remaining);
@@ -109,15 +136,22 @@ export class SqlWriteBehindCounter {
                     this.pendingDelta.delete(rk);
             }
             catch (err) {
-                hadFailure = true;
+                hadFailure = true; // S9: surfaced via bump() below — the retry/soft-limit semantics are unchanged
                 failure = err;
+                // keep the delta; retry next flush (advisory — never throw into the caller).
+                // KNOWN/ACCEPTED (audit B): an ambiguous failure (INSERT applied but the ack was lost) re-adds
+                // the delta next flush = double-count; conversely a reader between our INSERT and a peer's sees
+                // a momentary under-count. Both are bounded by one flush window and this counter backs SOFT
+                // limits only (quota/rate-limit, design: eventual consistency; hard caps use per-task budgets).
+                // Exactly-once would need a flush ledger/CAS — not worth it at this tier.
             }
         }
         if (attempted)
-            this.bump("flush", hadFailure, failure);
+            this.bump("flush", hadFailure, failure); // S9: empty rounds carry no health signal
         await this.refresh();
         await this.reap();
     }
+    /** Load the current window's fleet totals into the cache (pendingDelta is separate → never clobbered). */
     async refresh() {
         const { table, keyCol, valCol } = this.t;
         const b = this.bucket();
@@ -127,15 +161,17 @@ export class SqlWriteBehindCounter {
                 : `SELECT ${keyCol}, ${valCol} FROM ${table} WHERE window_bucket = $1`, [b]);
             const next = new Map();
             for (const row of rows) {
-                next.set(`${String(row[keyCol])}${SEP}${b}`, Number(row[valCol]));
+                next.set(`${String(row[keyCol])}${SEP}${b}`, Number(row[valCol])); // node-pg returns BIGINT/INT as STRING
             }
             this.fleetTotal = next;
-            this.bump("refresh", false);
+            this.bump("refresh", false); // S9: recovery edge (no-op while healthy)
         }
         catch (err) {
-            this.bump("refresh", true, err);
+            // keep last-known cache on a transient read failure
+            this.bump("refresh", true, err); // S9
         }
     }
+    /** Delete expired window buckets to bound the table. */
     async reap() {
         try {
             const { affected } = await this.exec(this.dialect === "tidb"
@@ -158,11 +194,14 @@ export class SqlWriteBehindCounter {
         this.timer = undefined;
     }
 }
+/** MySQL-protocol (TiDB) binding — historical class name + ctor shape preserved. */
 export class WriteBehindCounter extends SqlWriteBehindCounter {
     constructor(pool, t, windowMs, now, onDegraded, queryTimeoutMs) {
         super("tidb", pool, t, windowMs, now, onDegraded, queryTimeoutMs);
     }
 }
+/** PostgreSQL binding — the class pg-rate-limiter.ts used to define inline (and pg-cost-quota.ts duplicated
+ *  privately, hardwired to the cost_quota columns). Same ctor shape as the mysql2 twin. */
 export class PgWriteBehindCounter extends SqlWriteBehindCounter {
     constructor(pool, t, windowMs, now, onDegraded, queryTimeoutMs) {
         super("pg", pool, t, windowMs, now, onDegraded, queryTimeoutMs);

package/dist/principal-jwt.d.ts

@@ -1,4 +1,10 @@
 import type { ApprovalHmacKey, PrincipalJwtKey } from "./auth-keys.js";
+/**
+ * design/80 D-G: verify a compact JWS principal token. Returns the crypto-verified principal (`sub`) + the
+ * channel-binding (`bnd`) on success, or `null` on ANY failure (caller fail-closes — NEVER falls back to a header).
+ * 🔴 Hardening: the JWS header `alg` MUST equal the kid's PINNED alg (rejects `alg:none`, symmetric, downgrade);
+ * the kid MUST resolve to a configured key; iss/aud/exp/nbf (with a small skew) are enforced; `sub` MUST be present.
+ */
 export declare function verifyPrincipalJwt(token: string, keys: PrincipalJwtKey[], expect: {
     iss: string;
     aud: string;
@@ -9,11 +15,29 @@ export declare function verifyPrincipalJwt(token: string, keys: PrincipalJwtKey[
     sub: string;
     bnd?: string;
 } | null;
+/** The channel-binding value a direct client's principal JWT must carry in `cnf.bnd`: the hex SHA-256 of the
+ *  CLIENT-VISIBLE action identity (sessionId + boundCallId + boundInputHash — NOT the unexposed checkpointToken).
+ *  Binds the identity assertion to THIS specific suspended action so a captured JWT cannot be lifted onto another. */
 export declare function approvalBnd(env: {
     sessionId: string;
     boundCallId?: string | null;
     boundInputHash?: string | null;
 }): string;
+/**
+ * design/80 D-G: verify the WHOLE direct-door proof for one /decide — the signed principal JWT (identity) + its
+ * cnf.bnd channel-binding + the HMAC envelope (integrity) — and return the CRYPTO-VERIFIED principal, or a typed
+ * reject. 🔴 Fail-closed: every failure rejects (the caller must NOT fall back to the trusted header). Order:
+ * verify principal → bind → mac-present → mac-valid (so a non-operator never gets a MAC oracle, an unverified
+ * caller never reaches the operator list).
+ *
+ * 🔴 `opts.actionBinding`: the boundCallId/boundInputHash action-binding is `policy_ask`-
+ * SPECIFIC (a pending TOOL call). A NON-ACTION gate — `plan_review` (and any review-pause) — `binds NO action`
+ * (core checkpoint-store.ts: pendingAction `{kind:"plan_review"}`, editedPlan is a typed sibling that binds no
+ * action), so the proof correctly DEGRADES to "verify WHO": JWT identity + cnf.bnd channel-binding + the HMAC over
+ * {sessionId, decision} (bound fields null) — WITHOUT requiring a boundInputHash. Pass `actionBinding:false` for a
+ * non-action gate; the default (true) keeps the /decide tool-approval contract byte-identical. Binding the decision
+ * to a plan HASH was REJECTED (the plan artifact lives in a profile ref store; the worker has no TOCTOU original).
+ */
 export declare function verifyDirectDoorProof(proof: {
     jwt?: string;
     mac?: string;

package/dist/principal-jwt.js

@@ -1,8 +1,29 @@
+/**
+ * design/80 D-G: principal crypto-binding (the direct-door IDENTITY gate) + the combined direct-door proof
+ * verifier. Split out of `security.ts` (design/158 A13, internal-lossless — the facade re-exports every symbol
+ * below unchanged; `verifyDirectDoorProof` imports {@link verifyApprovalHmac} from `./approval-hmac.js` for the
+ * integrity half of the combined proof; `security.ts`'s own `verifiedPrincipal` imports {@link verifyPrincipalJwt}
+ * from here for the direct-door identity branch).
+ *
+ * ✅ WIRED (was "🔴 SCAFFOLD — NOT YET WIRED" — STALE, corrected by the 2026-07-25 doc-rot sweep). Two live call
+ * sites, both traced: `verifiedPrincipal` (security.ts) takes the direct-door branch when `directDoorActive` and
+ * derives the principal from {@link verifyPrincipalJwt} instead of the header, and {@link verifyDirectDoorProof}
+ * verifies the same JWT for the decide routes. Still true, and the part worth keeping: `directDoorActive` is
+ * computed from the anchors (config.ts) and is OFF by default, so the direct branch never runs in a stock
+ * deployment — activation = provisioning the issuer JWKS + iss/aud, a deployment task, not a coding one.
+ * The direct-connect /decide door must NEVER trust a client-supplied principal header
+ * (invariant #1). Instead the client presents a SIGNED JWT (sub = principal), and the worker verifies the SIGNATURE
+ * against the issuer's PUBLIC key — so identity is crypto-DERIVED, not header-asserted. PUBLIC keys ⇒ non-secret
+ * (ride the config projection like OPERATOR_PRINCIPALS, not the HMAC secret path). The issuer's PRIVATE key lives
+ * ONLY with the trusted minter (the BFF/identity service), never on a worker. HMAC stays integrity; this is identity.
+ */
 import { createHash, createPublicKey, verify as cryptoVerify } from "node:crypto";
 import { verifyApprovalHmac } from "./approval-hmac.js";
 function b64urlToBuf(s) {
     return Buffer.from(s, "base64url");
 }
+/** Map a PINNED JWS alg → the node:crypto verify call. EdDSA(Ed25519): algorithm=null. RS256: RSA-PKCS1+sha256.
+ *  ES256: ECDSA P-256 with the JWS raw r||s encoding (dsaEncoding ieee-p1363, NOT DER). Returns false on mismatch. */
 function verifyJwsSignature(alg, signingInput, sig, pub) {
     try {
         if (alg === "EdDSA")
@@ -17,6 +38,12 @@ function verifyJwsSignature(alg, signingInput, sig, pub) {
         return false;
     }
 }
+/**
+ * design/80 D-G: verify a compact JWS principal token. Returns the crypto-verified principal (`sub`) + the
+ * channel-binding (`bnd`) on success, or `null` on ANY failure (caller fail-closes — NEVER falls back to a header).
+ * 🔴 Hardening: the JWS header `alg` MUST equal the kid's PINNED alg (rejects `alg:none`, symmetric, downgrade);
+ * the kid MUST resolve to a configured key; iss/aud/exp/nbf (with a small skew) are enforced; `sub` MUST be present.
+ */
 export function verifyPrincipalJwt(token, keys, expect) {
     if (keys.length === 0)
         return null;
@@ -35,13 +62,15 @@ export function verifyPrincipalJwt(token, keys, expect) {
     catch {
         return null;
     }
+    // A payload of the JSON literal `null` (or any non-object) parses WITHOUT throwing — guard before any deref so a
+    // crafted `base64url("null").<payload>.<sig>` token fail-closes to a typed reject, not an uncaught TypeError → 500.
     if (typeof header !== "object" || header === null || typeof payload !== "object" || payload === null)
         return null;
     if (typeof header.alg !== "string" || typeof header.kid !== "string" || sig.length === 0)
         return null;
     const key = keys.find((k) => k.kid === header.kid);
     if (!key || key.alg !== header.alg)
-        return null;
+        return null; // 🔴 alg PINNED to the kid's key — no confusion/downgrade
     let pub;
     try {
         pub = createPublicKey(key.key);
@@ -52,6 +81,7 @@ export function verifyPrincipalJwt(token, keys, expect) {
     const signingInput = Buffer.from(`${h}.${p}`, "utf8");
     if (!verifyJwsSignature(key.alg, signingInput, sig, pub))
         return null;
+    // claims — signature verified, now enforce the envelope
     if (payload.iss !== expect.iss)
         return null;
     const aud = payload.aud;
@@ -62,32 +92,57 @@ export function verifyPrincipalJwt(token, keys, expect) {
         return null;
     const now = expect.nowSec ?? Math.floor(Date.now() / 1000);
     const skew = expect.skewSec ?? 30;
+    // 🔴 exp is MANDATORY (the design mandates a short-lived token, ≤120s) — a missing/non-numeric exp must FAIL, else a
+    // token minted without exp would never expire (anti-replay = single-use checkpointToken ONLY, with no time bound).
     if (typeof payload.exp !== "number" || payload.exp + skew < now)
-        return null;
+        return null; // missing / non-numeric / expired
     if (payload.nbf !== undefined && (typeof payload.nbf !== "number" || payload.nbf - skew > now))
-        return null;
+        return null; // nbf, if present, must be numeric + reached
+    // Cap the TTL so a sloppy/over-permissive minter can't widen the replay window past the short-lived mandate.
     if (expect.maxTtlSec && payload.exp - now > expect.maxTtlSec + skew)
         return null;
     const bnd = typeof payload.cnf?.bnd === "string" ? payload.cnf.bnd : undefined;
     return { sub: payload.sub, bnd };
 }
+/** The channel-binding value a direct client's principal JWT must carry in `cnf.bnd`: the hex SHA-256 of the
+ *  CLIENT-VISIBLE action identity (sessionId + boundCallId + boundInputHash — NOT the unexposed checkpointToken).
+ *  Binds the identity assertion to THIS specific suspended action so a captured JWT cannot be lifted onto another. */
 export function approvalBnd(env) {
     return createHash("sha256").update(JSON.stringify([env.sessionId, env.boundCallId ?? null, env.boundInputHash ?? null])).digest("hex");
 }
+/**
+ * design/80 D-G: verify the WHOLE direct-door proof for one /decide — the signed principal JWT (identity) + its
+ * cnf.bnd channel-binding + the HMAC envelope (integrity) — and return the CRYPTO-VERIFIED principal, or a typed
+ * reject. 🔴 Fail-closed: every failure rejects (the caller must NOT fall back to the trusted header). Order:
+ * verify principal → bind → mac-present → mac-valid (so a non-operator never gets a MAC oracle, an unverified
+ * caller never reaches the operator list).
+ *
+ * 🔴 `opts.actionBinding`: the boundCallId/boundInputHash action-binding is `policy_ask`-
+ * SPECIFIC (a pending TOOL call). A NON-ACTION gate — `plan_review` (and any review-pause) — `binds NO action`
+ * (core checkpoint-store.ts: pendingAction `{kind:"plan_review"}`, editedPlan is a typed sibling that binds no
+ * action), so the proof correctly DEGRADES to "verify WHO": JWT identity + cnf.bnd channel-binding + the HMAC over
+ * {sessionId, decision} (bound fields null) — WITHOUT requiring a boundInputHash. Pass `actionBinding:false` for a
+ * non-action gate; the default (true) keeps the /decide tool-approval contract byte-identical. Binding the decision
+ * to a plan HASH was REJECTED (the plan artifact lives in a profile ref store; the worker has no TOCTOU original).
+ */
 export function verifyDirectDoorProof(proof, envelope, config, opts) {
-    const actionBinding = opts?.actionBinding ?? true;
+    const actionBinding = opts?.actionBinding ?? true; // default = the policy_ask tool-approval action-binding (unchanged)
     if (!proof.jwt)
         return { ok: false, status: 401, errorCode: "principal_unverified", error: "direct door requires a signed principal token (X-Approval-Principal-Token)" };
     const verified = verifyPrincipalJwt(proof.jwt, config.principalJwtPubkeys, { iss: config.principalJwtIss ?? "\0", aud: config.principalJwtAud ?? "\0", maxTtlSec: config.principalJwtMaxTtlSec });
     if (!verified)
         return { ok: false, status: 401, errorCode: "principal_unverified", error: "principal token failed verification" };
+    // action-binding gates (policy_ask) MUST carry the bound action; a non-action gate (plan_review) skips this — the
+    // cnf.bnd + HMAC below still bind {sessionId, decision} (with null bound fields), so WHO + decision-integrity hold.
     if (actionBinding && !envelope.boundInputHash)
         return { ok: false, status: 400, errorCode: "approval_mac_required", error: "direct door requires boundInputHash (the bound action) in the body" };
     if (verified.bnd !== approvalBnd(envelope))
         return { ok: false, status: 401, errorCode: "principal_unbound", error: "principal token is not bound to this decision (cnf.bnd mismatch)" };
     if (!proof.mac)
         return { ok: false, status: 401, errorCode: "approval_mac_required", error: "direct door requires an approval MAC (X-Approval-Mac)" };
-    const ok = verifyApprovalHmac({ sessionId: envelope.sessionId, boundCallId: envelope.boundCallId ?? null, boundInputHash: envelope.boundInputHash ?? null, decision: envelope.decision, reason: envelope.reason ?? null }, proof.mac, proof.kid, config.approvalHmacKeys);
+    const ok = verifyApprovalHmac(
+    // reason 与两个绑定位同样归一到 null(缺席=null),使"服务端算的"与"签名器签的"在缺席形上逐字节一致。
+    { sessionId: envelope.sessionId, boundCallId: envelope.boundCallId ?? null, boundInputHash: envelope.boundInputHash ?? null, decision: envelope.decision, reason: envelope.reason ?? null }, proof.mac, proof.kid, config.approvalHmacKeys);
     if (!ok)
         return { ok: false, status: 401, errorCode: "approval_mac_invalid", error: "approval envelope MAC invalid" };
     return { ok: true, principal: verified.sub };