opencode-turnstile 0.2.0 → 0.2.5

package/src/types.ts

@@ -16,6 +16,14 @@ export interface TaskInput {
   description?: unknown
   command?: unknown
   cmd?: unknown
+  /**
+   * Target path as delivered by the host's `write`/`edit` tools. The shape is
+   * unconfirmed on v2.0.27, hence `unknown`; `src/tool-policy.ts` reads it as a
+   * documented candidate (`filePath ?? path`) and fails open when absent.
+   */
+  filePath?: unknown
+  /** Alternate candidate key for the same write/edit target path. */
+  path?: unknown
 }
 
 /** Tool result as delivered by the host's `execute.after` hook. */
@@ -29,6 +37,14 @@ export interface ToolResult {
 /** Payload of the `tool.execute.before` and `tool.execute.after` hooks. */
 export interface ToolHookEvent {
   tool?: unknown
+  /**
+   * Dispatched subagent/agent name, observed on v2.0.27
+   * execute.before/after payloads. The host contract does not type this
+   * field, hence `unknown`; `src/setup.ts` reads it (against the configured
+   * agent-name set) to skip injecting orchestrator policy into child
+   * sessions.
+   */
+  agent?: unknown
   sessionID?: unknown
   input?: TaskInput
   result?: ToolResult
@@ -37,6 +53,15 @@ export interface ToolHookEvent {
 /** Payload of the `session.prompt` hook. */
 export interface PromptHookProperties {
   sessionID?: unknown
+  /**
+   * Candidate key for the raw user prompt text on v2.0.27. The host does not
+   * type this field, hence `unknown`; `src/setup.ts` reads it (against the
+   * candidate `text ?? prompt`) to capture user-authored waiver/approval markers
+   * at prompt admission. Fails open when absent.
+   */
+  text?: unknown
+  /** Alternate candidate key for the raw user prompt text. */
+  prompt?: unknown
 }
 
 /** Generation draft passed to the `session.generate` hook. */
@@ -67,6 +92,23 @@ export interface EventProperties {
   text?: unknown
   delta?: unknown
   error?: unknown
+  /**
+   * Host request id on `permission.asked`; the matched id on `permission.replied`.
+   * Present only on the permission stream events (opencode v2.0.27+).
+   */
+  id?: unknown
+  requestID?: unknown
+  /**
+   * A human reply to a permission ask: `"once"`, `"always"`, or `"reject"`.
+   * Present only on `permission.replied`.
+   */
+  reply?: unknown
+  /**
+   * The ask message echoed by the host on `permission.asked`. Read to
+   * recognize plan-gate asks (the evaluate handler stamps a known prefix);
+   * unknown-typed, hence `unknown`.
+   */
+  message?: unknown
 }
 
 /** A single host stream event delivered by `event.subscribe`. */
@@ -76,15 +118,169 @@ export interface StreamEvent {
   properties?: EventProperties
 }
 
+/**
+ * Evidence-correlation mode for the reviewer gate. `enforce` (default) refuses
+ * to flip `hasGatePass` on a `GATE: PASS` with no correlated exit-0
+ * bash/shell test execution; `flag` flips but still stamps `verified`;
+ * `off` behaves exactly as before (no correlation).
+ */
+export type GateEvidenceMode = "enforce" | "flag" | "off"
+
+/**
+ * Enforcement mode for the tool-call denylist policy in `src/tool-policy.ts`.
+ * `enforce` (default) blocks matching bash/shell commands and write/edit paths;
+ * `shadow` journals the would-block without throwing (adoption path); `off` is
+ * a silent no-op escape hatch. Mirrors `GateEvidenceMode`.
+ */
+export type ToolPolicyMode = "enforce" | "shadow" | "off"
+
+/**
+ * Denylist policy governing the tools that flow through `execute.before`:
+ * bash/shell commands and write/edit target paths. Defaults encode the
+ * git-protective prose of `src/policy.ts` verbatim in `bashDeny` and leave
+ * `pathDeny` empty (ordinary editing is covered — a decision is made and, on
+ * block, journaled — with no default blocks, so it never breaks until a user
+ * configures `pathDeny`). Regex sources are case-insensitive, compiled once at
+ * setup, and matched with `RegExp.test`.
+ */
+export interface TurnstileToolPolicy {
+  /** Enforcement mode: `enforce` (default), `shadow`, or `off`. */
+  mode: ToolPolicyMode
+  /** Case-insensitive regex sources matched against bash/shell commands. */
+  bashDeny: string[]
+  /** Case-insensitive regex sources matched against write/edit target paths. */
+  pathDeny: string[]
+  /** Journal `session_move` dispatches (never blocks). */
+  observeSessionMove: boolean
+}
+
+/**
+ * Git-and-commit gate configuration backing the mechanical gates in
+ * `src/tool-policy.ts` (chunk-7/8). The default `mode` is `"shadow"`: the
+ * gates are active but non-blocking (audit-only) until a user flips a key to
+ * `"enforce"`, mirroring the tool-policy "adopt shadow first" adoption path.
+ *
+ * `commitFormat` is a conventional-commits regex SOURCE string (no leading
+ * `^`/trailing `$`): callers compile it with `new RegExp("^" + source + "$",
+ * "s")`. It accepts one of the default types `{feat,fix,docs,style,refactor,
+ * perf,test,build,ci,chore,revert}`, an optional `(scope)`, a required `!` or
+ * `:` separator (only one is needed — no `BREAKING CHANGE` trailer), a subject
+ * of up to 72 characters on the first line, and one optional following body
+ * line.
+ */
+export interface TurnstileGitGates {
+  /** Enforcement mode: `enforce` (blocks), `shadow` (audit-only, default), or `off` (silent no-op). */
+  mode: ToolPolicyMode
+  /** Whether `git commit` messages are linted as conventional commits. */
+  commitMessages: boolean
+  /** Conventional-commit regex SOURCE string (compiled by callers with `"^…$"` + `"s"`). */
+  commitFormat: string
+  /** Whether pushing/PR-landing is gated on a reviewer `VERDICT: APPROVE`. */
+  landingGate: boolean
+}
+
 /** Gate state for one parent session. */
 export interface GateState {
   hasGatePass: boolean
+  /**
+   * Last `GATE: PASS` rejected for lack of correlated test execution (an
+   * unverified claim under `enforce`); "" when none. Cleared on a green flip,
+   * on `GATE: FAIL`, and on a task reset. Task-scoped: never carried through
+   * `mergeAfterReplay`.
+   */
+  unverifiedPass: string
   /** True when this task's plan has a current plan-reviewer APPROVE. */
   hasPlanVerdict: boolean
-  verdicts: string[]
+  /**
+   * True once this task's reviewer `execute.after` delivery has carried a
+   * `VERDICT: APPROVE` for the parent — the landing gate's release signal.
+   * Restart-sticky like `hasPlanVerdict`: restored by journal replay across a
+   * restart (chunk-7) and carried one prompt via `mergeAfterReplay`; fresh
+   * `false` on an ordinary prompt reset.
+   */
+  hasReviewApprove: boolean
+  /**
+   * Latest user-authored prompt text containing the waiver marker; "" when
+   * none. Non-empty ⇒ the current task's reviewer/dispatch gates are waived.
+   * Task-scoped: cleared on every prompt reset and never carried through
+   * `mergeAfterReplay`.
+   */
+  userWaiver: string
+  /**
+   * Provenance flag: true once a human (prompt marker or permission reply)
+   * rather than the plan-reviewer subagent released the plan gate. Provenance
+   * only — `execute.before` never consults it; it is read by the status CLI and
+   * trace lines. Fresh `false` on each prompt reset, but restart-restored values
+   * survive the first post-restart prompt via `mergeAfterReplay`, exactly like
+   * `hasPlanVerdict`.
+   */
+  humanApproval: boolean
+  /**
+   * A single-dispatch grant — the matched host `requestID` for a once-granted
+   * human approval, keyed per ask-reason so a plan-gate `once` grant (releasing
+   * exactly one executor dispatch) can never be consumed by a landing-gate
+   * `once` grant (releasing exactly one push) and vice versa: `{ plan }` for the
+   * plan gate (consumed by the executor dispatch short-circuit), `{ landing }`
+   * for the landing gate (consumed by the bash short-circuit). "" per reason
+   * when none. Task-scoped: cleared immediately after the single dispatch
+   * consumes it (a stale grant cannot outlive one dispatch) and never carried
+   * through `mergeAfterReplay`.
+   */
+  pendingOnceGrant: {
+    /** Plan-gate once grant: the matched requestID, or "" when none. */
+    plan: string
+    /** Landing-gate once grant: the matched requestID, or "" when none. */
+    landing: string
+  }
+  /**
+   * True once this task's first parent task/subagent result delivery has
+   * carried the injected orchestrator policy forward into model context.
+   * Cleared per task by `ledger.resetState()` on every user prompt, so the
+   * policy is re-injected on each task (the intended per-task re-supply,
+   * which also re-applies it after compaction).
+   */
+  policyInjected: boolean
+  /**
+   * Dedup key → raw session ID that first observed the marker; written
+   * alongside `seen.add` by `observeMarker`. Tracks first-sight provenance so
+   * a dedup hit from a different raw session can be accounted as cross-child
+   * suppression (a different raw session than the stored provenance).
+   *
+   * Holds gate-kind provenance only: verdict-kind streaming dedup lives in the
+   * per-child `childVerdicts` store, not here.
+   */
+  seenFrom: Map<string, string>
+  /**
+   * Cross-child suppressions pending attribution on the next emitted
+   * `MarkerEvent` (a `GATE:` dedup hit whose raw session differs from the
+   * provenance stored in `seenFrom`). Read and zeroed when an event emits; 0 on
+   * a fresh bucket. Verdict-kind deliveries use the per-child store instead, so
+   * this counter is now gated on gate-kind hits only.
+   */
+  suppressedPending: number
   reviewRounds: number
+  /**
+   * Count of `git push`/PR-landing blocks this task under the landing gate —
+   * telemetry that arms the permission-ask escalation on a repeat attempt
+   * (chunk-8). Task-scoped: fresh `0` on each prompt reset and never carried
+   * through `mergeAfterReplay`.
+   */
+  landingBlocks: number
   reads: number
   seen: Set<string>
+  /**
+   * Plans-dir signature the approval was issued against; "" means
+   * unknown (journal-replayed or pre-stamp) and is accepted once, then
+   * stamped, on the next enforcing dispatch.
+   */
+  plansSignature: string
+  /**
+   * True while a journal-replayed bucket's unconsumed one-prompt grace is
+   * outstanding: the next reset carries hasGatePass/hasPlanVerdict forward
+   * instead of wiping them. Cleared by the first reset; re-granted only by
+   * journal replay at ledger creation (process restart or plugin reload).
+   */
+  replayGrace: boolean
 }
 
 /** One first-sight marker observation returned by the marker parser. */
@@ -93,13 +289,50 @@ export interface MarkerEvent {
   marker: string
   result?: "PASS" | "FAIL"
   rounds?: number
+  /**
+   * Evidence verdict of a `PASS` gate event: true (correlated exit-0 test
+   * execution exists for this session) or false (flagged, unverified). Present
+   * only on `PASS` gate events when the evidence mode is not `"off"`.
+   */
+  verified?: boolean
+  /** Evidence mode at the time this event was stamped, when `verified` is. */
+  mode?: GateEvidenceMode
   /** Marker matches observed in the same text but not journaled
    *  (latest-wins policy); 0 when this was the only match. */
   suppressed: number
 }
 
+/**
+ * The latest `VERDICT:` marker observation for a single child session and the
+ * provenance label of the pipeline that carried it. The store is
+ * verdict-kind only: only `VERDICT:` markers are stored (never `GATE:`), so a
+ * GATE-only child can never suppress a plan-reviewer bare-output violation.
+ *
+ * It is also the streamed-verdict observation ledger: `recordChildVerdict`
+ * returns whether the observation changed (first-record, marker flip, or
+ * source change), so a caller can distinguish a flip from an identical
+ * re-record without re-reading the store. Gate-kind (`GATE:`) dedup still
+ * lives in `GateState.seen`; this store is verdict-kind only.
+ */
+export interface ChildVerdict {
+  /** Last `VERDICT:` marker observed for the child, or "" when none. */
+  marker: string
+  /** Pipeline provenance label, e.g. "child-text" or "child-message". */
+  source: string
+  /**
+   * `Date.now()` when this verdict was last recorded; `0` on the empty default.
+   *
+   * Used by the plausibility join: an unresolved-child verdict is
+   * plausible for a parent only when it was recorded at-or-after that parent's
+   * most recent plan-reviewer dispatch.
+   */
+  recordedAt: number
+}
+
 /** Agent names turnstile recognizes in dispatches and generation drafts. */
 export interface TurnstileAgents {
+  /** Planner: first in the pipeline; the primary session's plan gate gates dispatch. */
+  planner: string
   reviewer: string
   /** Plan reviewer: adversarial review of the implementation plan. */
   planReviewer: string
@@ -135,6 +368,13 @@ export interface TurnstileConfig {
   readBlock: number
   /** Literal marker that waives the reviewer gate when in the prompt. */
   waiverMarker: string
+  /**
+   * Literal marker that releases the plan gate via an explicit human
+   * approval (chunk-3). Present at config resolution so the key is valid and
+   * the digest is stable; not yet consumed by the chunk-2 prompt-channel
+   * waiver. Defaults to `PLAN APPROVED:`.
+   */
+  approvalMarker: string
   /** Project-relative directory scanned for `## Decomposition` plans. */
   plansDir: string
   /** Whether the human-readable trace file is written (JSONL journal always). */
@@ -145,6 +385,36 @@ export interface TurnstileConfig {
   gateMarker: string
   /** Verdict marker regex source (compiled with `gm`). */
   verdictMarker: string
+  /**
+   * Evidence-correlation mode for the reviewer gate: `enforce` (default)
+   * requires a correlated exit-0 bash/shell test execution before a
+   * `GATE: PASS` flips the gate; `flag` flips yet stamps `verified`; `off`
+   * keeps the pre-evidence behavior. See `src/evidence.ts`.
+   */
+  gateEvidence: GateEvidenceMode
+  /**
+   * Case-insensitive regex source a successful (exit-0) bash/shell command
+   * must match to count as test execution. Overridable for non-JS/other
+   * toolchains; the default covers npm/pnpm/yarn/bun/deno/node --test/
+   * pytest/make test/go test/cargo test.
+   */
+  evidencePattern: string
+  /**
+   * Denylist policy for bash/shell and write/edit tools in `execute.before`.
+   * Default `mode` is `enforce`; the default `bashDeny` encodes the
+   * git-protective prose of `src/policy.ts`, `pathDeny` defaults empty, and
+   * `observeSessionMove` journals `session_move` dispatches without blocking.
+   * See `src/tool-policy.ts`.
+   */
+  toolPolicy: TurnstileToolPolicy
+  /**
+   * Git-and-commit gate configuration. Default `mode` is `shadow` (audit-only
+   * until a user opts into `enforce`), `commitMessages` lints `git commit`
+   * messages against the conventional-commits `commitFormat`, and `landingGate`
+   * gates push/PR-landing on a reviewer `VERDICT: APPROVE`. See
+   * `src/tool-policy.ts`.
+   */
+  gitGates: TurnstileGitGates
 }
 
 /** Options accepted by the plugin factory; tests inject config and env here. */
@@ -173,4 +443,33 @@ export type Host = {
   event?: {
     subscribe?: (options?: { signal?: AbortSignal }) => AsyncIterable<StreamEvent>
   }
+  permission?: {
+    hook?: (
+      name: string,
+      callback: (event: unknown) => unknown | Promise<unknown>,
+    ) => Promise<unknown>
+  }
+}
+
+/**
+ * Properties carried by a host `permission.evaluate` request at the wire
+ * boundary. Every field is optional and typed `unknown`: the host does not
+ * expose a stable shape for this payload, so a reshaped or partial payload
+ * fails open rather than failing hard. The plugin matches on `action` (the
+ * host's task/subagent dispatch name) and `source` rather than the tool input
+ * (which this payload does not carry), so escalation surfaces the same decision
+ * to a human without leaking the dispatch target to the subagent.
+ */
+export interface PermissionEvaluateEvent {
+  sessionID?: unknown
+  action?: unknown
+  resources?: unknown
+  metadata?: unknown
+  source?: {
+    type?: unknown
+    messageID?: unknown
+    id?: unknown
+  }
+  effect?: unknown
+  message?: unknown
 }

package/turnstile.ts

@@ -1,5 +1,13 @@
 /**
- * turnstile: runtime enforcement of the AGENTS.md pipeline contracts.
+ * turnstile: runtime enforcement of the orchestrator pipeline contracts.
+ *
+ * - Orchestrator policy: injected into the primary (parent) session per task
+ *   via the `execute.after` hook — the `ORCHESTRATOR_POLICY` block from
+ *   `src/policy.ts` is prepended to the first `task`/`subagent` result delivery
+ *   per task, with per-task idempotency via `GateState.policyInjected`, fully
+ *   guarded and fail-open (a broken injection journals `type:"policy"` and
+ *   proceeds). Nothing is written to an instructions file at install time — the
+ *   AGENTS.md contract block is a historical install step, removed.
  *
  * Written for OpenCode v2.x promise-plugin host (`{ id, setup }`):
  * - `ctx.tool.hook("execute.before" | "execute.after", cb)`
@@ -8,27 +16,153 @@
  *
  * Enforced mechanically:
  * - Plan-approval gate: `task` dispatches to `executor` require a current
- *   plan-reviewer `VERDICT: APPROVE` for the task whenever a plan file
- *   exists in `.opencode/plans/`, or an explicit user waiver (`USER
- *   WAIVER:` literal in the prompt). Plan-file changes invalidate the
- *   approval, forcing re-review after a re-plan.
+ *   plan approval whenever a plan file exists in `.opencode/plans/`: a
+ *   plan-reviewer `VERDICT: APPROVE`, a prompt-channel human approval, or a
+ *   permission-prompt human approval. A prompt-channel approval is a
+ *   user-authored prompt (a `PLAN APPROVED:` literal in the user's prompt sets
+ *   the plan verdict and records human provenance) and replays identically to
+ *   a plan-reviewer verdict. When none holds, the first executor dispatch
+ *   escalates to the human through the host permission surface:
+ *   `permission.evaluate` forced `ask` with the plan file + head; a reply
+ *   `always` sets the verdict, `once` grants exactly one executor dispatch
+ *   (any other agent's dispatch leaves the grant pending and still runs its
+ *   own guards), and `reject` keeps the gate red (that single reply is
+ *   consumed). Replies match only asks escalated as plan-gate asks (recorded
+ *   per request id, bounded, per session) — a reply to an unrelated permission
+ *   ask can never release the gate: an ask is recorded only when its message
+ *   carries the plan-ask prefix, or when the parent's escalation latch is
+ *   still live (it expires after a few seconds and is cleared by a prompt
+ *   reset) and the ask carries no message of its own. The explicit
+ *   user waiver is prompt-channel too (see the hard-gate bullet): a
+ *   `USER WAIVER:` literal in the user's prompt waives the gate; a
+ *   `USER WAIVER:` literal in an agent-composed dispatch prompt is inert —
+ *   issue #34's injection hole, now closed. Plan-content changes invalidate
+ *   approvals issued against the previous plans-dir signature (replayed
+ *   approvals are accepted once, then stamped). A journal-replayed approval
+ *   survives the first prompt after a restart (the resume prompt) and then
+ *   every later prompt starts a clean cycle.
  * - Hard gate: `task` dispatches to `reviewer` require a recorded `GATE: PASS`
  *   from test-runner for the current task (a later `GATE: FAIL` un-sets
- *   it), or an explicit user waiver (the dispatch prompt must contain the
- *   literal marker `USER WAIVER:`).
- * - Round cap: max 2 `task -> reviewer` dispatches per task.
- * - Horizon: read-counter backstop (warn @8, block @15 whole-file reads).
+ *   it), or an explicit user waiver (`USER WAIVER:` literal in the user's
+ *   prompt). Under the default `gateEvidence:enforce`
+ *   mode a `GATE: PASS` satisfies the gate only when the current task's
+ *   bash/shell executions include a matching exit-0 test command (plausibility
+ *   via `evidencePattern`); an unverified PASS is journaled `verified:false`
+ *   and does not flip the gate. `flag` degrades to the historical
+ *   flip-on-trust semantics while still stamping `verified`, and `off`
+ *   journals without the field — both documented in the README. A
+ *   journal-replayed `GATE: PASS` survives the first prompt after a restart
+ *   (the resume prompt) and then every later prompt starts a clean cycle.
+ * - Round cap: max 2 `task -> reviewer` dispatches per task, regardless of gate
+ *   state; a prompt-channel user waiver bypasses the cap without counting
+ *   toward it (a dispatch prompt with the `USER WAIVER:` marker is inert); a
+ *   new user prompt resets it.
+ * - Parent-bucket eviction: live-parent gate buckets (hasGatePass,
+ *   hasPlanVerdict, read counter, policyInjected) are registered per
+ *   prompt/dispatch/delivery/edge via `markParent`, and the `states` LRU never
+ *   evicts a registered parent; unresolved child buckets remain evictable and
+ *   can no longer push a live parent out past `maxSessions`.
+ * - Horizon: read-counter backstop (warn @8, block @15 whole-file reads),
+ *   keyed off the parent session: the child→parent edge is awaited
+ *   (host `session.get` when `session.created` has not yet landed) before the
+ *   guard fires, so an in-flight child draws down the parent's budget; a
+ *   still-unresolved child self-keys and journals a bounded signal.
  * - Decomposition: `task -> executor` dispatches must cite `chunk-N` / `AC-n`
  *   when a plan file with a `## Decomposition` block exists.
+ * - Status: `turnstile status` (the `opencode-turnstile status` CLI) reads
+ *   the journal read-only — it never writes — and reports gate + plan state
+ *   per parent session: gate flags restored like replay, prompt-channel plan
+ *   approvals and waiver events (with channel), last markers, and
+ *   dispatch/block/permission counts (a human table or `--json`).
+ * - Tool-call policy: `bash`/`shell` commands and `write`/`edit`
+ *   target paths are matched in `execute.before` against a configurable
+ *   denylist (`src/tool-policy.ts`). Under `toolPolicy.mode: enforce` a match
+ *   throws `BLOCKED by turnstile:`; `shadow` journals the would-block without
+ *   throwing and `off` is a no-op. Default `bashDeny` blocks the git-protective
+ *   operations in `src/policy.ts` (worktree, branch `switch`/`checkout`, `merge`,
+ *   `gh pr create|merge`); `pathDeny` defaults empty. `session_move` is journaled
+ *   as telemetry only, never blocked. A misconfigured/absent host payload fails
+ *   open with a journal entry rather than blocking.
+ * - Commit-lint: `bash`/`shell` `git commit -m '<subject>'` messages are
+ *   validated as conventional commits when `gitGates.commitMessages` is on
+ *   (default) — a `type(scope)!: subject` shape (`type` ∈
+ *   `{feat,fix,docs,style,refactor,perf,test,build,ci,chore,revert}`, `!`
+ *   optional, subject ≤ 72 chars). A non-conventional message is
+ *   `BLOCKED by turnstile: commit message '<subject>' is not a conventional
+ *   commit — expected type(scope)!: subject` under `gitGates.mode: enforce`
+ *   (journaled `reason:"invalid-commit-message"`); `shadow` journals only,
+ *   `off` is a no-op. An uninspectable form (`-F`/`-t`/`--edit`/interactive;
+ *   `--amend -m` is inspectable) is treated as non-conventional and blocked
+ *   under `enforce` (`reason:"commit-message-uninspectable"`): pass the subject
+ *   with `git commit -m <subject>`, not an editor or file.
+ * - Landing gate: `git push` with no delivery-attributed reviewer
+ *   `VERDICT: APPROVE` for the current task is `BLOCKED by turnstile:
+ *   push/PR requires a reviewer VERDICT: APPROVE before landing — wait for the
+ *   reviewer or escalate to the user` under `gitGates.mode: enforce` (journaled
+ *   `reason:"no-landing-approval"`); `shadow` journals only, `off` is a no-op.
+ *   Approval is set only when the reviewer's task-result delivery carries
+ *   `VERDICT: APPROVE` (a streamed-only verdict in child text does not
+ *   satisfy the gate); `gh pr create|merge` stays denied by the default
+ *   `bashDeny` list (disjointly journaled), and every `git push` is journaled
+ *   as landing telemetry in every mode.
+ * - Landing escalation: on a repeat `git push` with no approval and
+ *   `gitGates.mode: enforce`, turnstile journals a permission ask
+ *   (`reason:"landing"`) and lets `execute.before` pass so the
+ *   `permission.evaluate` handler forces a human ask
+ *   (`turnstile: push/PR requires a reviewer VERDICT: APPROVE before
+ *   landing`). The reply `always` stands a reviewer approval for the task,
+ *   `once` grants exactly one push (consumed by the next push), and `reject`
+ *   re-blocks and re-arms — the repeat push is the human decision point.
  * - Markers: `GATE:` / `VERDICT:` parsed from task results and child-session
  *   assistant text, deduped per task (streaming re-delivery is ignored);
  *   marker-less outputs from marker-contracted agents (test-runner/reviewer/
- *   plan-reviewer) are journaled as violations; a plan-reviewer result's
- *   last `VERDICT` moves the plan-approval gate (parent-keyed, journaled as
- *   type `plan`); gate journal entries are keyed by the parent session so
- *   replay restores where the gates look.
+ *   plan-reviewer) are journaled as violations; the summary/divergence
+ *   suppression (a child's streamed verdict hiding a marker-less summarized
+ *   delivery) is scoped to the plan-reviewer only — reviewer/test-runner
+ *   violate on a marker-less delivery even when the child's streamed text
+ *   quoted a VERDICT; the last `VERDICT` for a dispatch moves the plan-approval
+ *   gate, taken from the task result or, when the host summarized the result,
+ *   from that child session's assistant text; the journaled `type:"plan"`
+ *   `source` names the winning pipeline; a delivery with no marker on any
+ *   source keeps the gate red (parent-keyed, journaled as type `plan`); gate
+ *   journal entries are keyed by the parent session so replay restores where
+ *   the gates look.
+ * - Verdict attribution: every journaled `type:"plan"` entry is
+ *   keyed `raw` = an actual child session id, never the parent/session id; a
+ *   marker-less parent-keyed re-fire can never journal a `{raw: p1}` phantom
+ *   that clobbers a live verification. Attribution is gated on the delivery's
+ *   agent being `plan-reviewer`: the child→parent edge is awaited (host
+ *   `session.get` when `session.created` has not yet landed), then, for any
+ *   self-keyed delivery (its own id is not a registered child, marker-less or
+ *   not), candidate discovery attributes it to the unique evidenced registered
+ *   child (via the child-text verdict store); an own VERDICT: APPROVE with zero
+ *   evidenced candidates is dropped to the error journal (fail-safe), and zero
+ *   or more-than-one candidate journals an unattributable `type:"error"` and
+ *   returns (fail-open, gate unchanged, nothing mutated). Child-text verdict
+ *   observations dedup per (child, marker, source): identical re-delivery and a
+ *   cross-source same-marker replay are both suppressed; only a marker flip
+ *   journals, and a prompt reset drops the previous
+ *   task's children's evidence (scoped to the reset parent, other parents intact).
+ * - Verdict attribution, unresolved edge: a self-keyed delivery whose
+ *   child→parent edge is unresolved now also claims the unique child evidenced
+ *   only in the streaming store — plausibility = a recorded plan-reviewer
+ *   dispatch for the parent predates (at-or-before) the observation's recordedAt,
+ *   plausibly unique across parents (a verdict with two candidate parents is
+ *   ambiguous and excluded). Timestamps are last-wins and cleared on prompt reset,
+ *   so a verdict is plausible only within the parent's current task scope. Every
+ *   self-keyed delivery journals one `type:"attribution"` entry before any mutation
+ *   (`{decision, deliveryIsParent, sessionApi, candidates:{edge,unresolved,
+ *   plausible} counts, unresolvedIDs, lookup:{session:{attempts,reason}}}`) so the
+ *   field can tell the three root-cause hypotheses apart; the attribution is
+ *   unanimous-pool driven. A plausible streamed `VERDICT: APPROVE` makes a
+ *   self-keyed `BLOCK` unreachable (structural fail-open over BLOCK). The
+ *   edge-resolved branch and the never-BLOCK-on-zero-candidates guarantee are
+ *   unchanged, so an unattributable parent-keyed delivery stays a single
+ *   `/unattributable/` error on fail-open paths.
  * - Trace: JSONL journal of dispatches, gate transitions, verdicts, blocked
- *   calls, bash commands, errors.
+ *   calls, bash commands, errors, and the load heartbeat
+ *   (a "setup" entry: plugin version, config digest, hook count). Errors also
+ *   cover the stream-end and unresolvable-agent signals; all telemetry only.
  * - Decoding: executor/test-runner/debugger temperature clamped ≤ 0.2;
  *   reviewer temperature = 0.
  * - Config: layered and read once at setup: code defaults ⊕
@@ -48,6 +182,8 @@
  * - `src/markers.ts`: GATE/VERDICT parsing and dedup.
  * - `src/gates.ts`: enforcement decisions (plan-approval gate, reviewer
  *   gate, read horizon, decomposition).
+ * - `src/tool-policy.ts`: stateless denylist matching for bash/shell and
+ *   write/edit tools in `execute.before`.
  * - `src/setup.ts`: hook registration and the stream-event loop.
  */
 import { createTurnstile } from "./src/setup.ts"