opencode-turnstile 0.2.1 → 0.2.5

package/src/setup.ts

@@ -11,7 +11,11 @@
  * BLOCKED errors thrown by the gate layer propagate to the host.
  */
 
-import { loadConfig } from "./config.ts"
+import * as fs from "node:fs"
+import * as path from "node:path"
+import { fileURLToPath } from "node:url"
+
+import { configDigest, loadConfig } from "./config.ts"
 import { createJournaler, type Journaler } from "./journal.ts"
 import {
   agentFromTaskInput,
@@ -21,12 +25,24 @@ import {
   VERDICT_RE,
 } from "./markers.ts"
 import { BlockError, createGates, type Gates } from "./gates.ts"
+import { createEvidenceTracker } from "./evidence.ts"
+import {
+  LANDING_REQUIREMENT,
+  createToolPolicy,
+  isPushLanding,
+  type ToolPolicy,
+} from "./tool-policy.ts"
 import { createLedger, type GateLedger } from "./state.ts"
+import { ORCHESTRATOR_POLICY } from "./policy.ts"
 import type {
   CompactionDraft,
+  ChildVerdict,
   EventProperties,
+  GateState,
   GenerateDraft,
   Host,
+  MarkerEvent,
+  PermissionEvaluateEvent,
   PromptHookProperties,
   TaskInput,
   ToolHookEvent,
@@ -43,6 +59,22 @@ function asSessionID(value: unknown): string {
   return String(value ?? "")
 }
 
+/**
+ * Picks the user prompt text from the host's candidate keys: the FIRST
+ * candidate that is a NON-EMPTY string wins. An empty `text` no longer
+ * shadows a marker-bearing `prompt` (and vice versa); when neither key holds a
+ * non-empty string the prompt text is unresolvable and "" is returned (the
+ * keyless-misconfiguration telemetry keys off exactly this).
+ * @param properties The `session.prompt` hook payload.
+ * @returns The resolved prompt text, or "" when unresolvable.
+ */
+function promptTextOf(properties: PromptHookProperties | undefined): string {
+  for (const candidate of [properties?.text, properties?.prompt]) {
+    if (typeof candidate === "string" && candidate !== "") return candidate
+  }
+  return ""
+}
+
 /**
  * Tracks a hook registration handle so it can be disposed on teardown.
  * @param reg Registration handle returned by a host hook call.
@@ -54,6 +86,42 @@ function track(reg: unknown, cleanups: Array<() => void>): void {
   }
 }
 
+/**
+ * Reads the plugin version from package.json for the load heartbeat.
+ *
+ * Fail-open: returns null when package.json is unreadable (e.g. a bare
+ * `setup.ts` + `src/` copy without it), mirroring the `install.mjs` version
+ * read. Resolved from `import.meta.url` so it is correct under symlink
+ * installs (Node realpaths the module URL to the repo) and npm installs
+ * (`package.json` ships at the root). `pkgPath` is injectable so tests can
+ * exercise the unreadable path without mocking `fs`.
+ * @param pkgPath Optional package.json path override (tests).
+ * @returns The version string, or null when it cannot be read.
+ */
+export function readPluginVersion(pkgPath?: string): string | null {
+  try {
+    const resolved =
+      pkgPath ?? path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "package.json")
+    return JSON.parse(fs.readFileSync(resolved, "utf8")).version ?? null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Message prefix the evaluate handler stamps on every plan-gate ask, so the
+ * stream consumer can recognize a plan ask even when the host omits the
+ * session id on the `permission.asked` event.
+ */
+const PLAN_ASK_MESSAGE_PREFIX = "turnstile: plan approval required"
+
+/**
+ * Message prefix the evaluate handler stamps on every landing-gate ask, so the
+ * stream consumer can recognize a landing ask (even when the host omits the
+ * session id) and route its reply to the landing gate.
+ */
+const LANDING_ASK_MESSAGE_PREFIX = "turnstile: push/PR requires a reviewer"
+
 /**
  * Builds the turnstile plugin for a host: resolves the layered config,
  * creates the telemetry writer and gate ledger (replaying the journal),
@@ -69,6 +137,9 @@ export function createTurnstile(
 ): (h: Host) => Promise<(() => void) | void> {
   const env = opts.env ?? process.env
   const { config } = loadConfig(env, opts.config)
+  // Version is read once here (fail-open, alongside loadConfig) for the load
+  // heartbeat; null on exotic installs where package.json is unreadable.
+  const version = readPluginVersion()
   const journaler: Journaler = createJournaler({
     metricsDir: config.metricsDir,
     trace: config.trace,
@@ -77,8 +148,18 @@ export function createTurnstile(
   })
   // Config warnings are already journaled by config.ts (the pre-journaler
   // sink); journaling them here too would double-write every entry.
-  const gateRe = compileMarkerRegex(config.gateMarker, GATE_RE)
-  const verdictRe = compileMarkerRegex(config.verdictMarker, VERDICT_RE)
+  const gateRe = compileMarkerRegex(config.gateMarker, GATE_RE, (cause) =>
+    journaler.journal({
+      type: "error",
+      error: `config gateMarker: invalid regex, using default: ${String(cause)}`,
+    }),
+  )
+  const verdictRe = compileMarkerRegex(config.verdictMarker, VERDICT_RE, (cause) =>
+    journaler.journal({
+      type: "error",
+      error: `config verdictMarker: invalid regex, using default: ${String(cause)}`,
+    }),
+  )
 
   /**
    * True when the text contains at least one GATE or VERDICT marker per the
@@ -91,12 +172,527 @@ export function createTurnstile(
   }
   const ledger: GateLedger = createLedger(journaler.journalPath, config.maxSessions)
   const gates: Gates = createGates(config, journaler)
+  // Stateless denylist for bash/shell and write/edit tools in execute.before
+  // regexes compile once here; it throws the same BlockError gates
+  // throw, so the hook's existing catch rethrows blocks and journals the rest.
+  const toolPolicy: ToolPolicy = createToolPolicy(config, journaler)
+  // Evidence tracker: correlates a GATE: PASS against journaled exit-0
+  // bash/shell test executions attributed to the parent. Owns only the
+  // *evidence* dimension; marker authority is separate.
+  const evidence = createEvidenceTracker(config, (raw) => ledger.parentOf(raw), journaler)
   let projectDir: string = process.cwd()
   // Per-delivery dedup scope counter: each task result is a distinct
   // delivery, so a re-run emitting a byte-identical marker is still
   // journaled; streaming sources share the empty scope (re-delivery dedup).
   let taskDeliverySeq = 0
 
+  // Host session API, bound at setup time (hooks already fire post-setup).
+  // Kept in factory scope so the shared `resolveParent` helper can call it
+  // without capturing the per-setup `h`; enables the plan-reviewer delivery
+  // path to await edge resolution via `session.get`.
+  let hostSession: Host["session"] | undefined = undefined
+
+  // Parent-lookup bookkeeping, keyed by child session ID.
+  // Values record how many lookups were attempted and why the record stayed
+  // unresolved: `"not-visible"` (host `session.get` threw) or `"no-parent-id"`
+  // (the record exists but has no parent edge); cleared on success. Capped so
+  // long-lived hosts cannot grow it unboundedly.
+  const failedLookups = new Map<string, { attempts: number; reason: string }>()
+  // `"not-visible"`: host `session.get` threw the lookup is retryable.
+  const LOOKUP_REASON_NOT_VISIBLE = "not-visible"
+  // `"no-parent-id"`: the record exists but has no parent edge (negative cache).
+  const LOOKUP_REASON_NO_PARENT_ID = "no-parent-id"
+  // Parent session ID → Date.now() of its LATEST plan-reviewer dispatch
+  // (last-wins; cleared on prompt reset for that parent). Plausibility
+  // input: an unresolved-child verdict is plausible only within the parent's
+  // current task scope (recorded at-or-after this time, and unique across
+  // parents). Capped via boundDispatches, the same eviction idiom as
+  // boundLookups.
+  const planReviewerDispatch = new Map<string, number>()
+  // Plan-gate permission asks, keyed by host request id → the parent session
+  // the ask was raised for + when it was recorded. Only asks escalated by the
+  // evaluate handler (reason "plan-gate") are recorded, so a reply to an
+  // unrelated permission ask (bash, write, …) can never match or release the
+  // plan gate, and concurrent sessions cannot clobber each other (values
+  // carry their own session). Bounded: evict oldest past the cap.
+  const planGateAsks = new Map<string, { sessionID: string; recordedAt: number }>()
+  // Cap on tracked plan-gate asks: evict oldest (insertion order) past it.
+  const maxTrackedPlanAsks = 50
+  // Parents whose evaluate handler has escalated to an ask but whose
+  // `permission.asked` stream event has not arrived yet: parent → escalation
+  // time. The evaluate handler does not know the host request id (it rides the
+  // later stream event), so the next ask for an escalated parent is treated as
+  // the plan ask and recorded. Bounded by boundAwaitingAsks, and latches
+  // expire (see awaitingPlanAskTtlMs) so a lost stream event cannot latch a
+  // parent indefinitely.
+  const awaitingPlanAsk = new Map<string, number>()
+  // Latch TTL for awaiting-plan-ask markers: an escalation whose stream event
+  // never arrives stops latching after this window, so a stale marker cannot
+  // record an unrelated later ask (whose approval would then release the plan
+  // gate). Fail-toward-strict: expired = not recorded = reply inert = the
+  // gate re-asks on the next dispatch.
+  const awaitingPlanAskTtlMs = 5_000
+  // Parents whose evaluate handler has been armed to force a landing ask (the
+  // guard sets this under `gitGates.mode: enforce` on a repeat `git push`
+  // attempt: no reviewer approval AND >= 1 prior landing block). Parent → arm
+  // time. The landing arm consults it (not the command, whose wire shape in the
+  // permission event is unverified — the guard is the single source of truth
+  // for landing-candidate detection via isPushLanding). Bounded by
+  // boundLandingAsks; expires like awaitingPlanAsk so a lost stream event
+  // cannot latch a parent indefinitely.
+  const pendingLandingAsk = new Map<string, number>()
+  const maxTrackedLandingAsks = 50
+  const pendingLandingAskTtlMs = 5_000
+  // Landing-gate permission asks, keyed by host request id → the parent session
+  // the ask was raised for + when it was recorded. Only asks by the evaluate
+  // handler's landing arm (message prefixed `turnstile: push/PR …`) are
+  // recorded, so a reply to an unrelated permission ask can never match or
+  // release the landing gate; per-reason keying keeps a landing `once` grant
+  // from ever being consumed by a plan-gate (task) dispatch and vice versa.
+  // Bounded: evict oldest past the cap.
+  const landingGateAsks = new Map<string, { sessionID: string; recordedAt: number }>()
+  const maxTrackedLandingGateAsks = 50
+  // A thrown lookup may mean the child record is not yet visible to the
+  // host API, so failures are retried up to this many times per session.
+  const maxLookupAttempts = 3
+  // Bound on tracked sessions: evict oldest (insertion order) when past.
+  const maxTrackedLookups = 256
+
+  /**
+   * Bounds the failed-lookup map by evicting its oldest entries.
+   */
+  function boundLookups(): void {
+    while (failedLookups.size > maxTrackedLookups) {
+      // The loop condition guarantees a first entry exists.
+      const oldest = failedLookups.keys().next().value as string
+      failedLookups.delete(oldest)
+    }
+  }
+
+  /**
+   * Bounds the dispatch-timestamp map by evicting its oldest entries.
+   * Mirrors boundLookups; see planReviewerDispatch.
+   */
+  function boundDispatches(): void {
+    while (planReviewerDispatch.size > maxTrackedLookups) {
+      // The loop condition guarantees a first entry exists.
+      const oldest = planReviewerDispatch.keys().next().value as string
+      planReviewerDispatch.delete(oldest)
+    }
+  }
+
+  /**
+   * Bounds the plan-gate ask map by evicting its oldest recorded asks.
+   * Mirrors boundLookups; see planGateAsks.
+   */
+  function boundPlanAsks(): void {
+    while (planGateAsks.size > maxTrackedPlanAsks) {
+      // The loop condition guarantees a first entry exists.
+      const oldest = planGateAsks.keys().next().value as string
+      planGateAsks.delete(oldest)
+    }
+  }
+
+  /**
+   * Bounds the awaiting-plan-ask map (parent → escalation time), evicting its
+   * oldest entries. Mirrors boundPlanAsks; see awaitingPlanAsk.
+   */
+  function boundAwaitingAsks(): void {
+    while (awaitingPlanAsk.size > maxTrackedPlanAsks) {
+      // The loop condition guarantees a first entry exists.
+      const oldest = awaitingPlanAsk.keys().next().value as string
+      awaitingPlanAsk.delete(oldest)
+    }
+  }
+
+  /**
+   * Reads (and expires) the awaiting-plan-ask latch for a session: a marker
+   * older than the TTL is dropped and reported as absent. Fail-toward-strict:
+   * an expired latch records nothing, so a reply to any later ask stays inert
+   * and the plan gate re-asks on the next dispatch.
+   * @param sid The session whose latch is consulted.
+   * @returns Whether a live (unexpired) latch exists for the session.
+   */
+  function hasLiveAwaitingAsk(sid: string): boolean {
+    const at = awaitingPlanAsk.get(sid)
+    if (at === undefined) return false
+    if (Date.now() - at > awaitingPlanAskTtlMs) {
+      awaitingPlanAsk.delete(sid)
+      return false
+    }
+    return true
+  }
+
+  /**
+   * Bounds the pending-landing-ask map (parent → arm time), evicting its oldest
+   * entries. Mirrors boundAwaitingAsks; see pendingLandingAsk.
+   */
+  function boundLandingAsks(): void {
+    while (pendingLandingAsk.size > maxTrackedLandingAsks) {
+      const oldest = pendingLandingAsk.keys().next().value as string
+      pendingLandingAsk.delete(oldest)
+    }
+  }
+
+  /**
+   * Bounds the landing-gate ask map (requestID → parent + record time),
+   * evicting its oldest entries. Mirrors boundPlanAsks; see landingGateAsks.
+   */
+  function boundLandingGateAsks(): void {
+    while (landingGateAsks.size > maxTrackedLandingGateAsks) {
+      const oldest = landingGateAsks.keys().next().value as string
+      landingGateAsks.delete(oldest)
+    }
+  }
+
+  /**
+   * Reads (and expires) the pending-landing-ask latch for a session: an arm
+   * older than the TTL is dropped and reported as absent. Fail-toward-strict:
+   * an expired latch arms nothing, so a later ask is inert and the landing gate
+   * re-blocks. Only armed under `gitGates.mode: enforce` on a repeat attempt, so
+   * shadow/off never ask.
+   * @param sid The parent session whose latch is consulted.
+   * @returns Whether a live (unexpired) latch exists for the session.
+   */
+  function hasLiveLandingAsk(sid: string): boolean {
+    const at = pendingLandingAsk.get(sid)
+    if (at === undefined) return false
+    if (Date.now() - at > pendingLandingAskTtlMs) {
+      pendingLandingAsk.delete(sid)
+      return false
+    }
+    return true
+  }
+
+  /**
+   * Resolves and caches the parent of a child session via the host API.
+   * Parent-less records are negatively cached (a stable signal: the session
+   * exists and has no parent edge); thrown lookups are retried up to
+   * `maxLookupAttempts` because the record may appear later. Each failure is
+   * recorded as `{ attempts, reason }`: `"not-visible"` when
+   * `session.get` threw, `"no-parent-id"` when the record has no parent edge;
+   * cleared on success.
+   * Without a usable edge the caller falls back to keying by the session
+   * itself. Lifted to factory scope so the plan-reviewer delivery path can
+   * await it before attribution; byte-identical to the original
+   * per-setup definition.
+   * @param sessionID Child session ID to resolve.
+   */
+  async function resolveParent(sessionID: string | undefined): Promise<void> {
+    if (!sessionID || ledger.childToParent.has(sessionID)) return
+    const attempts = failedLookups.get(sessionID)?.attempts ?? 0
+    if (attempts >= maxLookupAttempts) return
+    const get = hostSession?.get
+    if (typeof get !== "function") return
+    try {
+      const rec = await get({ sessionID })
+      const parentID = rec?.parentID ?? rec?.data?.parentID
+      if (typeof parentID === "string") {
+        ledger.setParent(sessionID, parentID)
+        failedLookups.delete(sessionID)
+      } else {
+        // Record present but parent-less: negatively cached (a stable signal).
+        failedLookups.set(sessionID, {
+          attempts: maxLookupAttempts,
+          reason: LOOKUP_REASON_NO_PARENT_ID,
+        })
+        boundLookups()
+      }
+    } catch {
+      // lookup failure: retryable; fall back to keying by the session
+      // itself until the record becomes visible or attempts run out
+      failedLookups.set(sessionID, { attempts: attempts + 1, reason: LOOKUP_REASON_NOT_VISIBLE })
+      boundLookups()
+    }
+  }
+
+  /**
+   * Resolves the read-budget key for a whole-file read: awaits the child→parent
+   * edge, then returns the parent session (or the session itself when the edge
+   * is genuinely absent). Journals a bounded signal only when a lookup was
+   * attempted but stayed inconclusive — a child whose record is not yet visible
+   * to `session.get`. Root sessions that resolve cleanly as parent-less, and
+   * children already resolved to a parent, never signal (no journal spam).
+   * @param sid The reading session ID, already normalized via `asSessionID`.
+   * @returns The session ID the read budget should be keyed against.
+   */
+  async function readBudgetKey(sid: string): Promise<string> {
+    await resolveParent(sid)
+    const key = ledger.parentOf(sid)
+    if (key === sid) {
+      // Byte-identical read: reads the attempts count off the
+      // structured record; the gate (`attempts > 0 && attempts < max`) is
+      // unchanged, so this signal is byte-identical to the pre-enrichment form.
+      const attempts = failedLookups.get(sid)?.attempts ?? 0
+      // Inconclusive window only: a lookup was tried and the record was not yet
+      // visible (attempts climb 1..max-1). Zero means no host session API
+      // (never knowable); at the cap means a resolved parent-less root. Bounded
+      // to ≤ maxLookupAttempts-1 signals per session.
+      if (attempts > 0 && attempts < maxLookupAttempts) {
+        journaler.journal({
+          type: "error",
+          sessionID: sid,
+          error: `read budget keyed by session; parent unresolved after ${attempts}/${maxLookupAttempts} lookup attempt(s)`,
+        })
+      }
+    }
+    return key
+  }
+
+  /**
+   * Returns the last verdict match in `text` for `re` (last-match-wins, the
+   * same rule `parseGateMarkers` uses); "" when there is no match. Independent
+   * of `String.match`'s global-regex lastIndex state because `.match` resets it.
+   * @param text The text to scan.
+   * @param re The compiled verdict regex.
+   * @returns The last match text, or "" when `text` has no verdict match.
+   */
+  function lastMatch(text: string, re: RegExp): string {
+    return text.match(re)?.at(-1) ?? ""
+  }
+
+  /**
+   * Stamps a plan-reviewer verdict's approval against the current plans-dir
+   * signature so a later re-plan is detectable at dispatch time. An APPROVE
+   * against an unreadable dir stamps "" (unknown): the approval is accepted
+   * once and stamped on the next enforcing dispatch (fail-open); a BLOCK
+   * clears the stamp (hygiene). Mutates `s` in place.
+   * @param s The session's gate state (mutated).
+   * @param result The verdict result ("APPROVE" or "BLOCK").
+   * @param projectDir The current project directory (for the plans-dir scan).
+   */
+  function stampPlanApproval(s: GateState, result: string, projectDir: string): void {
+    s.plansSignature = result === "APPROVE" ? (gates.plansSignature(projectDir) ?? "") : ""
+  }
+
+  /**
+   * Splits a self-keyed delivery's attributable children into the
+   * registered-edge scan (`edge`, today's scan) and every child with a stored
+   * verdict that is not the delivery session itself (`unresolved`). `edge`
+   * keeps its LRU promotion; `unresolved` is a pure snapshot that feeds the
+   * plausibility join in plausibleUnresolved.
+   * @param sid The delivery's parent id (=== child in the self-keyed branch).
+   * @returns Registered candidates and verdict-bearing children (minus sid).
+   */
+  function discoverCandidates(sid: string): {
+    edge: string[]
+    unresolved: Array<{ child: string; verdict: ChildVerdict }>
+  } {
+    const edge: string[] = []
+    for (const c of ledger.childToParent.keys()) {
+      if (ledger.childToParent.get(c) === sid && ledger.childVerdict(c).marker !== "") edge.push(c)
+    }
+    return {
+      edge,
+      unresolved: ledger.evidencedChildren().filter(({ child }) => child !== sid),
+    }
+  }
+
+  /**
+   * Unresolved children plausibly this parent's next task: a plan-reviewer
+   * dispatch is recorded for `sid` AND the verdict was recorded at-or-after it
+   * (inclusive, tolerating same-millisecond ties) AND no OTHER parent
+   * dispatched at-or-before that verdict (unique-owner rule; a verdict with two
+   * candidate parents is ambiguous and excluded → fail-open). Pure read.
+   * @param sid The delivery's parent id.
+   * @param unresolved The `{ child, verdict }` candidates from discoverCandidates.
+   * @returns The child ids plausibly belonging to `sid`.
+   */
+  function plausibleUnresolved(
+    sid: string,
+    unresolved: Array<{ child: string; verdict: ChildVerdict }>,
+  ): string[] {
+    const dispatchTs = planReviewerDispatch.get(sid)
+    if (dispatchTs === undefined) return []
+    const out: string[] = []
+    for (const { child, verdict } of unresolved) {
+      if (verdict.recordedAt < dispatchTs) continue
+      // Unique-owner: another parent dispatched at-or-before this verdict's
+      // recordedAt ⇒ ambiguous ⇒ excluded (never-guess).
+      let ambiguous = false
+      for (const [other, ts] of planReviewerDispatch) {
+        if (other === sid) continue
+        if (ts <= verdict.recordedAt) {
+          ambiguous = true
+          break
+        }
+      }
+      if (!ambiguous) out.push(child)
+    }
+    return out
+  }
+
+  /**
+   * The most-recently-recorded child among the given ids, by stored
+   * `recordedAt` (ties keep insertion order); undefined when none. Pure read.
+   * @param children The candidate child ids (from the plausible list).
+   * @returns The most recently recorded child id, or undefined.
+   */
+  function mostRecentUnresolved(children: string[]): string | undefined {
+    let best: string | undefined
+    let bestAt = -1
+    for (const c of children) {
+      const at = ledger.childVerdict(c).recordedAt
+      if (at > bestAt) {
+        bestAt = at
+        best = c
+      }
+    }
+    return best
+  }
+
+  /**
+   * Parent-lookup diagnostic for the delivery child, its parent (sid, when
+   * distinct), and each unresolved candidate: `{ attempts, reason }` — the
+   * current parent-lookup attempt count and why it stayed unresolved
+   * (`"not-visible"` / `"no-parent-id"`, or `"resolved-or-never-tried"` when
+   * clean). Distinct sessions are kept in the entry so the field can tell the
+   * three root-cause hypotheses apart. Pure read; clears nothing.
+   * @param child The delivery's session id.
+   * @param unresolved The unresolved candidate child ids.
+   * @returns A per-session `{ attempts, reason }` map.
+   */
+  function lookupDiag(
+    child: string,
+    unresolved: string[],
+  ): Record<string, { attempts: number; reason: string }> {
+    const out: Record<string, { attempts: number; reason: string }> = {}
+    for (const s of [child, ...unresolved])
+      out[s] = {
+        attempts: failedLookups.get(s)?.attempts ?? 0,
+        reason: failedLookups.get(s)?.reason ?? "resolved-or-never-tried",
+      }
+    for (const c of unresolved)
+      out[c] = {
+        attempts: failedLookups.get(c)?.attempts ?? 0,
+        reason: failedLookups.get(c)?.reason ?? "resolved-or-never-tried",
+      }
+    return out
+  }
+
+  /**
+   * Attributes a plan-reviewer result to the parent's plan-approval gate,
+   * ensuring the journaled `plan` entry's `raw` is always an actual child
+   * session ID (never the parent `sessionID`):
+   *
+   * - Edge-resolved (`childToParent.has(child)`): the delivery's own verdict
+   *   wins over any stored child-text observation (delivery-wins only when the
+   *   output itself carries a marker); the `source` names the winning pipeline.
+   *   `raw = child`.
+   * - Self-keyed (`parentOf(child) === child`, e.g. a host re-fire reporting
+   *   the parent's own session ID): never reads `childVerdict(child)` (that is
+   *   the parent's own quoted text, not a child's evidence). It journals a
+   *   forensic `type:"attribution"` entry first (before any mutation,
+   *   replay-inert, never containing the word "unattributable" so the
+   *   /unattributable/ error count stays exactly one), then discovers
+   *   attributable children from registered edges AND from unresolved children
+   *   whose streamed verdict plausibly belongs to this parent, and
+   *   attributes through the unique unanimous pool (`raw = first edge child,
+   *   else most-recently-recorded unresolved child`). Zero candidates, or more
+   *   than one (contradictory), journals the existing `type:"error"` and
+   *   mutates nothing: a marker-less, unattributable parent-keyed delivery can
+   *   never clobber a live approval with a BLOCK, and any plausible streamed
+   *   APPROVE makes a self-keyed BLOCK unreachable (structural fail-open).
+   *
+   * Never throws (fail-open).
+   * @param child The raw child session ID, for the `plan` entry's `raw` field.
+   * @param output The delivery's own result text.
+   */
+  async function attributePlanVerdict(child: string, output: string): Promise<void> {
+    const sid = ledger.parentOf(child)
+    const own = lastMatch(output, verdictRe)
+    // Edge-resolved: attribute through the child directly, delivery-wins merge.
+    if (ledger.childToParent.has(child)) {
+      const s = ledger.state(sid)
+      const rec = ledger.childVerdict(child)
+      const marker = own || rec.marker
+      const markerSource = own ? "task-result" : rec.source || "task-result"
+      const result = marker.includes("APPROVE") ? "APPROVE" : "BLOCK"
+      s.hasPlanVerdict = result === "APPROVE"
+      stampPlanApproval(s, result, projectDir)
+      journaler.journal({
+        type: "plan",
+        sessionID: sid,
+        raw: child,
+        result,
+        marker: marker || "<none>",
+        source: markerSource,
+      })
+      journaler.traceEvent("plan-reviewer", "verdict", marker || "<no verdict marker>", sid)
+      return
+    }
+    // Self-keyed: the delivery's own session id is not a registered child.
+    const { edge, unresolved } = discoverCandidates(sid)
+    const unresolvedIDs = unresolved.map(({ child: cid }) => cid)
+    const plausible = plausibleUnresolved(sid, unresolved)
+    const edgeCandidates = edge
+    const pool = [...edgeCandidates, ...plausible]
+    const verdictOf = (c: string): "APPROVE" | "BLOCK" =>
+      ledger.childVerdict(c).marker.includes("APPROVE") ? "APPROVE" : "BLOCK"
+    const unanimous = new Set(pool.map(verdictOf))
+    // Attribute only on a non-empty unanimous pool: today's lone-edge-candidate
+    // attribution (edge-only) is unchanged; a plausible streamed APPROVE either
+    // becomes the sole candidate (approved) or contradicts a BLOCK pool
+    // (fail-open) — so a self-keyed BLOCK is unreachable while such evidence
+    // exists.
+    const attributed =
+      pool.length > 0 && unanimous.size === 1
+        ? (edgeCandidates[0] ?? mostRecentUnresolved(plausible))
+        : undefined
+    const decision = attributed ? "attributed" : "fail-open"
+    // Journal the forensic entry first (before any gate mutation). A new journal
+    // type is replay-inert; its wording avoids "unattributable" so the
+    // single-error count is stable.
+    journaler.journal({
+      type: "attribution",
+      sessionID: sid,
+      raw: child,
+      decision,
+      deliveryIsParent: child === sid,
+      sessionApi: typeof hostSession?.get === "function",
+      candidates: {
+        edge: edgeCandidates.length,
+        unresolved: unresolved.length,
+        plausible: plausible.length,
+      },
+      unresolvedIDs,
+      lookup: lookupDiag(child, unresolvedIDs),
+    })
+    if (attributed) {
+      const s = ledger.state(sid)
+      const rec = ledger.childVerdict(attributed)
+      // Attributed candidates are evidenced (a non-empty stored marker and a
+      // non-empty source label), so marker needs no "<none>" fallback here —
+      // the edge-resolved branch above keeps its fallback for marker-less
+      // deliveries.
+      const marker = own || rec.marker
+      const markerSource = own ? "task-result" : rec.source
+      const result = marker.includes("APPROVE") ? "APPROVE" : "BLOCK"
+      s.hasPlanVerdict = result === "APPROVE"
+      stampPlanApproval(s, result, projectDir)
+      journaler.journal({
+        type: "plan",
+        sessionID: sid,
+        raw: attributed,
+        result,
+        marker,
+        source: markerSource,
+      })
+      journaler.traceEvent("plan-reviewer", "verdict", marker, sid)
+      return
+    }
+    // Empty or contradictory evidence: fail-open. Gate untouched — never a
+    // BLOCK, never a parent-keyed plan entry, never a clobber of a live
+    // approval (the attribution entry above carries the diagnostics). A
+    // one-candidate pool always attributes, so this error only fires with
+    // zero or multiple candidates — plural noun always correct.
+    journaler.journal({
+      type: "error",
+      sessionID: sid,
+      error: `plan attribution: unattributable parent-keyed delivery; gate unchanged (${pool.length} evidenced candidates)`,
+    })
+  }
+
   /**
    * Parses markers out of assistant text and journals first-sight events.
    * @param text The assistant text to scan.
@@ -106,19 +702,60 @@ export function createTurnstile(
    */
   function parseMarkers(
     text: string,
-    sessionID: string | undefined,
+    sessionID: string,
     source: string,
     dedupScope = "",
-  ): void {
-    if (!text) return
+  ): MarkerEvent[] {
+    const events: MarkerEvent[] = []
+    if (!text) return events
+    // Record a child's latest VERDICT from the text itself, before the parent
+    // edge is needed, so a child with an unresolved edge still records. Only
+    // non-task-result sources enter the store: task-result markers are handled
+    // by the delivery's own match during attribution, and keeping them out
+    // preserves "a marker-less task-result delivery keeps the gate red".
+    //
+    // Store-backed verdict observations: the store records the child's latest
+    // VERDICT (per (child, marker, source) first-sight) for the plan gate's
+    // attribution reads; the parent-bucket dedup (markers.ts) keys on
+    // (scope, marker), so identical re-delivery and a cross-source same-marker
+    // replay (a source change with an unchanged marker, e.g. delta→ended) are
+    // both silently suppressed; only a marker flip reaches the journal.
+    if (sessionID && source !== "task-result") {
+      const m = lastMatch(text, verdictRe)
+      if (m) ledger.recordChildVerdict(sessionID, m, source)
+    }
     const sid = ledger.parentOf(sessionID)
-    if (!sid) return
+    if (!sid) return events
     const s = ledger.state(sid)
-    for (const event of parseGateMarkers(s, text, gateRe, verdictRe, dedupScope)) {
+    // Evidence verdict computed here: the caller owns the tracker + config.
+    // Under "enforce" the flip switch is the observed correlation; under "flag"
+    // the flip switch is omitted (always flips) while the journal is stamped;
+    // under "off" neither the flip switch nor the stamp is passed, keeping
+    // events byte-identical to legacy output.
+    const observed = config.gateEvidence === "off" ? undefined : evidence.has(sid)
+    const passVerified = config.gateEvidence === "enforce" ? observed : undefined
+    const stampVerified = observed
+    const stampMode = observed === undefined ? undefined : config.gateEvidence
+    // Thread the raw child session ID as `raw`: dedup provenance is per-child,
+    // so a dedup hit from a different child accounts as cross-child suppression
+    // while the same child's re-delivery stays silent.
+    for (const event of parseGateMarkers(
+      s,
+      text,
+      gateRe,
+      verdictRe,
+      dedupScope,
+      sessionID,
+      passVerified,
+      stampVerified,
+      stampMode,
+    )) {
       const suppressed = event.suppressed > 0 ? { suppressed: event.suppressed } : {}
       if (event.kind === "gate") {
         // Keyed by parent session so journal replay restores state where the
         // reviewer gate looks it up; raw child ID kept for forensics.
+        const evidenceStamp =
+          event.verified !== undefined ? { verified: event.verified, mode: event.mode } : {}
         journaler.journal({
           type: "gate",
           sessionID: sid,
@@ -126,10 +763,16 @@ export function createTurnstile(
           result: event.result,
           source,
           marker: event.marker,
+          ...evidenceStamp,
           ...suppressed,
         })
-        journaler.traceEvent("test-runner", "gate", event.marker)
+        journaler.traceEvent("test-runner", "gate", event.marker, sid)
       } else {
+        // Streaming verdict dedup is per (child, marker, source) via the store
+        // (a source change with an unchanged marker re-journals; identical
+        // re-delivery never emits an event here because the parent-bucket
+        // dedup on (scope, marker) suppresses it first). Gate-kind events
+        // above are unaffected.
         journaler.journal({
           type: "verdict",
           sessionID: sid,
@@ -139,9 +782,13 @@ export function createTurnstile(
           source,
           ...suppressed,
         })
-        journaler.traceEvent("reviewer", "verdict", event.marker)
+        journaler.traceEvent("reviewer", "verdict", event.marker, sid)
       }
+      // Collected for the caller: the execute.after reviewer branch uses these
+      // events to detect a first-sight verdict APPROVE and set hasReviewApprove.
+      events.push(event)
     }
+    return events
   }
 
   /**
@@ -152,68 +799,121 @@ export function createTurnstile(
    */
   return async function setup(h: Host): Promise<(() => void) | void> {
     const cleanups: Array<() => void> = []
+    // Count of successfully registered hooks (3 session + 2 tool + 1 event
+    // subscriber = 6 on a full host); feeds the load heartbeat below.
+    let hooks = 0
+    // Prompt-channel waiver capture (issue #34, AC-1): the waiver must
+    // provenance from the user's prompt, never the dispatch prompt. A counter
+    // tracks prompts where NEITHER candidate text key (`text`/`prompt`) holds a
+    // non-empty string, so an unresolvable source is reported once (keylessPrompts hits
+    // 1 exactly once) as a misconfiguration (mirrors the bash `command ?? cmd`
+    // telemetry).
+    let keylessPrompts = 0
 
-    // Parent-lookup bookkeeping, keyed by child session ID. Values are
-    // attempts made; capped so long-lived hosts cannot grow it unboundedly.
-    const failedLookups = new Map<string, number>()
-    // A thrown lookup may mean the child record is not yet visible to the
-    // host API, so failures are retried up to this many times per session.
-    const maxLookupAttempts = 3
-    // Bound on tracked sessions: evict oldest (insertion order) when past.
-    const maxTrackedLookups = 256
-
-    /**
-     * Bounds the failed-lookup map by evicting its oldest entries.
-     */
-    function boundLookups(): void {
-      while (failedLookups.size > maxTrackedLookups) {
-        const oldest = failedLookups.keys().next()
-        if (oldest.done) break
-        failedLookups.delete(oldest.value)
-      }
-    }
-
-    /**
-     * Resolves and caches the parent of a child session via the host API.
-     * Parent-less records are negatively cached (a stable signal: the
-     * session exists and has no parent edge); thrown lookups are retried
-     * up to `maxLookupAttempts` because the record may appear later.
-     * Without a usable edge the caller falls back to keying by the session
-     * itself.
-     * @param sessionID Child session ID to resolve.
-     */
-    async function resolveParent(sessionID: string | undefined): Promise<void> {
-      if (!sessionID || ledger.childToParent.has(sessionID)) return
-      const attempts = failedLookups.get(sessionID) ?? 0
-      if (attempts >= maxLookupAttempts) return
-      const get = h.session?.get
-      if (typeof get !== "function") return
-      try {
-        const rec = await get({ sessionID })
-        const parentID = rec?.parentID ?? rec?.data?.parentID
-        if (typeof parentID === "string") {
-          ledger.setParent(sessionID, parentID)
-          failedLookups.delete(sessionID)
-        } else {
-          failedLookups.set(sessionID, maxLookupAttempts)
-          boundLookups()
-        }
-      } catch {
-        // lookup failure: retryable; fall back to keying by the session
-        // itself until the record becomes visible or attempts run out
-        failedLookups.set(sessionID, attempts + 1)
-        boundLookups()
-      }
-    }
+    // Bind the host session API for the shared `resolveParent` helper (hooks
+    // already fire post-setup).
+    hostSession = h.session
 
     // Task-state reset: a new user prompt starts a new task.
     if (typeof h.session?.hook === "function") {
       try {
         const reg = await h.session.hook("prompt", (properties: PromptHookProperties) => {
           const sessionID = properties?.sessionID
-          if (typeof sessionID === "string") ledger.resetState(sessionID)
+          if (typeof sessionID === "string") {
+            // Mark the session a live parent before the reset: resetState
+            // re-caps `states`, and a registered parent is never evicted,
+            // so the rebuilt MRU slot stays pinned.
+            ledger.markParent(sessionID)
+            ledger.resetState(sessionID)
+            // A prompt reset invalidates all prior dispatch-scoped
+            // evidence for this parent, so an unresolved-child verdict is only
+            // plausible within the parent's current task scope.
+            planReviewerDispatch.delete(sessionID)
+            // Evidence is task-scoped, exactly like gate state: a new user
+            // prompt drops the in-memory correlation.
+            evidence.clear(sessionID)
+            // A prompt reset also drops any pending plan-ask latch: the
+            // escalation's stream event belongs to the previous task scope, so
+            // a new prompt must not let a later unrelated ask be recorded as
+            // the plan ask.
+            awaitingPlanAsk.delete(sessionID)
+            // A landing-ask arm (an enforce repeat-attempt escalation) belongs
+            // to the previous task scope too: a new prompt drops it, so the new
+            // task starts from a pure first block again.
+            pendingLandingAsk.delete(sessionID)
+            // Waiver capture (prompt channel): the user's text following the
+            // waiver marker waives both gates for the whole task. Read + capture
+            // in one guarded block; a coercion that throws (a malformed prompt
+            // value) is journaled under the historical "waiver capture" key and
+            // swallowed — fail-open.
+            try {
+              const waiverText = promptTextOf(properties)
+              const at = waiverText.indexOf(config.waiverMarker)
+              if (at !== -1) {
+                ledger.state(sessionID).userWaiver = config.trace
+                  ? waiverText.slice(at, at + 200)
+                  : "<present>"
+              }
+            } catch (e) {
+              // Fail-open: capture never blocks a prompt.
+              journaler.journal({ type: "error", error: `waiver capture: ${e}` })
+            }
+            // Human approval (item 7): a `PLAN APPROVED:` marker in the user
+            // prompt releases the plan gate — the same release signal the
+            // plan-reviewer verdict sets. Read + capture in one guarded block:
+            // set hasPlanVerdict (execute.before reads it) and humanApproval
+            // (provenance), and journal an APPROVE entry that replays identically
+            // to a verdict (replayGatePasses accepts any type:"plan" APPROVE;
+            // mergeAfterReplay carries it). A coercion that throws is journaled
+            // and swallowed — fail-open.
+            try {
+              const approvalText = promptTextOf(properties)
+              const atPlan = approvalText.indexOf(config.approvalMarker)
+              if (atPlan !== -1) {
+                const s = ledger.state(sessionID)
+                s.hasPlanVerdict = true
+                s.humanApproval = true
+                journaler.journal({
+                  type: "plan",
+                  sessionID,
+                  result: "APPROVE",
+                  // Provenance only: replay reads only type+result, so this
+                  // restores exactly like a VERDICT: APPROVE verdict.
+                  source: "session-prompt",
+                  marker: config.approvalMarker,
+                })
+              }
+            } catch (e) {
+              // Fail-open: approval capture never blocks a prompt.
+              journaler.journal({ type: "error", error: `approval capture: ${e}` })
+            }
+            // Misconfiguration telemetry: if neither candidate text key holds a
+            // non-empty string, the prompt text is unresolvable (an empty
+            // `text` does not count — it cannot carry a marker). Report the
+            // first such prompt once (keylessPrompts hits 1 exactly once) so a
+            // host-shape change stays observable without journaling on every
+            // prompt. An unreadable payload (a hostile getter) counts as
+            // unresolvable and is swallowed — fail-open.
+            let unresolvable: boolean
+            try {
+              unresolvable = promptTextOf(properties) === ""
+            } catch {
+              unresolvable = true
+            }
+            if (unresolvable) {
+              keylessPrompts++
+              if (keylessPrompts === 1)
+                journaler.journal({
+                  type: "error",
+                  sessionID,
+                  error:
+                    "waiver capture: neither prompt text key (text|prompt) is a string; does the host send the user prompt elsewhere?",
+                })
+            }
+          }
         })
         track(reg, cleanups)
+        hooks++
       } catch (e) {
         journaler.journal({ type: "error", error: `session.prompt hook registration: ${e}` })
       }
@@ -246,6 +946,7 @@ export function createTurnstile(
           }
         })
         track(reg, cleanups)
+        hooks++
       } catch (e) {
         journaler.journal({ type: "error", error: `session.generate hook registration: ${e}` })
       }
@@ -264,11 +965,103 @@ export function createTurnstile(
           }
         })
         track(reg, cleanups)
+        hooks++
       } catch (e) {
         journaler.journal({ type: "error", error: `session.compaction hook registration: ${e}` })
       }
     }
 
+    // Permission escalation (Phase 1): on a `task` dispatch the host asks the
+    // plugin to evaluate whether the call should proceed. The payload carries
+    // NO tool input, so escalation is driven by the parent session's plan-gate
+    // state (planGateStatus), never the dispatch target. Optional surface: an
+    // absent permission.hook degrades to today's behavior exactly.
+    if (typeof h.permission?.hook === "function") {
+      try {
+        const reg = await h.permission.hook("evaluate", (event: unknown) => {
+          try {
+            const pe = event as PermissionEvaluateEvent
+            const sessionID = asSessionID(pe?.sessionID)
+            // Plan-approval arm: the task/subagent dispatch exposes
+            // `action === "task"`; the payload carries no tool input, so
+            // escalation is driven purely by the parent's plan-gate state.
+            if (pe?.action === "task") {
+              const parent = ledger.parentOf(sessionID)
+              const status = gates.planGateStatus(projectDir, ledger, parent)
+              if (!status.red) return
+              // Red ⇒ summary is present by construction (planGateStatus builds
+              // it from a scan whose names[0] was already read). Escalate:
+              // force the host to ask the human, naming the plan file + head.
+              // Journal the ask so a reply can be matched (the requestID rides
+              // the permission.asked stream event).
+              const file = status.summary!.file
+              // The plan body is prompt context; journal/quote it only when the
+              // trace is enabled (SECURITY.md redaction contract), mirroring how
+              // the waiver quote is trace-gated at capture. Without it the ask
+              // still names the plan file.
+              const head = config.trace ? status.summary!.head : ""
+              pe.effect = "ask"
+              pe.message = head
+                ? `${PLAN_ASK_MESSAGE_PREFIX} — ${file}: ${head}`
+                : `${PLAN_ASK_MESSAGE_PREFIX} — ${file}`
+              // Mark this parent as awaiting its plan ask: the NEXT
+              // permission.asked stream event for this session is recorded as
+              // the plan-gate ask, so only escalated asks can ever match.
+              awaitingPlanAsk.set(parent, Date.now())
+              boundAwaitingAsks()
+              journaler.journal({
+                type: "permission",
+                sessionID: parent,
+                action: "ask",
+                // The requestID is attached to the subsequent permission.asked
+                // stream event (matched below by message prefix / latch).
+                reason: "plan-gate",
+                plan: file,
+              })
+              return
+            }
+            // Landing arm: a bash/shell permission.evaluate whose landing ask
+            // is armed (the guard set the pending-landing-ask latch under
+            // enforce on a repeat attempt). Candidate detection lives in
+            // `isPushLanding` (used by the guard); the evaluate handler
+            // consults the arm rather than re-reading the command from the
+            // (host-shape-uncertain) permission event — the guard is the single
+            // source of truth for landing-candidate detection. Approval
+            // releases the gate; a live latch means the human must decide this
+            // landing (the first block already threw, and shadow never arms).
+            // The arm is ONE-SHOT: it is consumed by the first evaluate it
+            // forces. The permission request the arm is meant to attach to is
+            // the very next one (the repeat push the guard just allowed through
+            // for escalation), so a one-shot latch cannot mislabel a later
+            // unrelated command with the push/PR ask inside the TTL window.
+            if (pe?.action === "bash" || pe?.action === "shell") {
+              const parent = ledger.parentOf(sessionID)
+              const st = ledger.state(parent)
+              if (st.hasReviewApprove) return
+              if (!hasLiveLandingAsk(parent)) return
+              pendingLandingAsk.delete(parent)
+              pe.effect = "ask"
+              pe.message = `turnstile: ${LANDING_REQUIREMENT}`
+              // No journal of the ask here: guardLanding already journaled
+              // `{type:"permission", action:"ask", reason:"landing"}` when it
+              // armed the latch, so there is a single landing-ask entry.
+              return
+            }
+            return
+          } catch (e) {
+            // Fail-open: the evaluate handler NEVER blocks the host.
+            journaler.journal({ type: "error", error: `permission evaluate: ${e}` })
+          }
+        })
+        track(reg, cleanups)
+        hooks++
+      } catch (e) {
+        // A registration failure journals (fail-open); a bad hook leaves
+        // today's behavior exactly.
+        journaler.journal({ type: "error", error: `permission.evaluate hook registration: ${e}` })
+      }
+    }
+
     // Tool-level gate + trace.
     if (typeof h.tool?.hook === "function") {
       try {
@@ -277,6 +1070,10 @@ export function createTurnstile(
             if (event?.tool === "task" || event?.tool === "subagent") {
               const agent = agentFromTaskInput(event.input)
               const sessionID = asSessionID(event?.sessionID)
+              // Sessions dispatching guarded subagents are parents by
+              // definition: mark before the guards so their
+              // state() inserts land pinned against LRU eviction.
+              ledger.markParent(sessionID)
               const prompt = String(event.input?.prompt ?? "")
               journaler.journal({
                 type: "dispatch",
@@ -288,23 +1085,140 @@ export function createTurnstile(
                   ? String(event.input?.description ?? "").slice(0, 200)
                   : "",
               })
-              journaler.traceEvent("orchestrator", "dispatch", `task -> ${agent}`)
+              journaler.traceEvent("orchestrator", "dispatch", `task -> ${agent}`, sessionID)
+
+              // Last-wins: record this parent's LATEST plan-reviewer
+              // dispatch time for the plausibility join. A prompt reset clears it
+              // (see the prompt hook), so a verdict is only plausible within the
+              // parent's current task scope. Bounded by boundDispatches.
+              if (agent === config.agents.planReviewer) {
+                planReviewerDispatch.set(sessionID, Date.now())
+                boundDispatches()
+              }
+
+              // An empty agent name is the only reliable misconfiguration
+              // signal: the host input shape no longer uses
+              // subagent_type/agent/subagent, so every gate condition misses.
+              // Telemetry only — journaling cannot throw.
+              if (!agent)
+                journaler.journal({
+                  type: "error",
+                  sessionID,
+                  error:
+                    "task dispatch: could not resolve the agent name; does the host input shape still use subagent_type/agent/subagent?",
+                })
+
+              // Once-granted human approval (from a `permission.replied` reply)
+              // grants exactly ONE EXECUTOR dispatch past the plan gate and is
+              // cleared immediately, so a stale grant cannot outlive the single
+              // dispatch it was given for, short-circuiting the plan-gate block
+              // below. Scoped to the executor dispatch class: the grant exists
+              // solely to release the plan-gate block, so any other agent
+              // (reviewer, plan-reviewer, …) leaves it pending and still runs
+              // its own guards (guardReviewerDispatch / …). execute.before
+              // consults only hasPlanVerdict / pendingOnceGrant — never
+              // humanApproval, which is provenance only.
+              if (
+                agent === config.agents.executor &&
+                ledger.state(sessionID).pendingOnceGrant.plan !== ""
+              ) {
+                // Consume the plan-gate once grant (a `permission.replied`
+                // `once`): clears just `.plan` so a landing `.landing` grant,
+                // if any, survives for the push it was given for.
+                ledger.state(sessionID).pendingOnceGrant.plan = ""
+                return
+              }
 
               if (agent === config.agents.reviewer) {
-                gates.guardReviewerDispatch(sessionID, prompt, ledger)
+                gates.guardReviewerDispatch(sessionID, ledger)
               }
 
               if (agent === config.agents.executor) {
-                gates.enforcePlanApproval(sessionID, prompt, projectDir, ledger)
+                gates.enforcePlanApproval(sessionID, projectDir, ledger)
                 gates.enforceDecomposition(sessionID, prompt, projectDir)
               }
               return
             }
 
             if (event?.tool === "read") {
-              // Keyed off the parent session: a subagent's reads draw down
-              // the parent's budget (AGENTS.md contract), not a per-child one.
-              gates.guardReadLimit(ledger.parentOf(asSessionID(event?.sessionID)), ledger)
+              // Keyed off the parent session: a subagent's reads draw down the
+              // parent's budget (AGENTS.md contract), not a per-child one.
+              // Resolve the child→parent edge first so an in-flight child keys
+              // the parent's budget, not its own; a still-unresolved child
+              // self-keys and journals a bounded signal.
+              gates.guardReadLimit(await readBudgetKey(asSessionID(event?.sessionID)), ledger)
+            }
+
+            // Tool-call denylist: bash/shell commands and write/edit
+            // target paths are matched against the configured denylist. The
+            // extraction coerces the unconfirmed host payload (candidate keys
+            // documented on each guard); an empty result fails open with
+            // misconfiguration telemetry. A block throws BlockError (rethrown by
+            // the catch below); shadow journals only; off is a no-op.
+            if (event?.tool === "bash" || event?.tool === "shell") {
+              const command = event.input?.command ?? event.input?.cmd
+              const sid = asSessionID(event?.sessionID)
+              // Denylist first: `gh pr create|merge` is denied wholesale, so it
+              // wins over the landing telemetry/gate below and the two journal
+              // reasons stay disjoint.
+              toolPolicy.guardBash(event.tool, command, sid)
+              // Conventional-commit lint (fail-closed under enforce for
+              // uninspectable forms; audit-only under shadow; silent under off).
+              toolPolicy.guardCommitMessage(event.tool, command, sid)
+              // Landing telemetry (always) then the reviewer-gated landing gate.
+              const text = String(command ?? "")
+              toolPolicy.observeLanding(sid, text)
+              // The stateful ledger stays out of tool-policy: only a shaped
+              // capability is handed over. `parent` is the parent session (a
+              // subagent's bash draws on the parent's task scope) and `st` is
+              // its bucket, so a still-unattributed child self-keys its own
+              // fresh state.
+              const parent = ledger.parentOf(sid)
+              const st = ledger.state(parent)
+              // Landing once-grant (from a `permission.replied` `once` for a
+              // landing ask) releases exactly ONE push, consumed here, before
+              // the gate decides, so a stale grant cannot outlive that single
+              // dispatch. Scoped to landing candidates: a non-push bash command
+              // leaves the grant pending (burning it on `git status` would
+              // defeat the "single push" contract). Keyed per-reason
+              // (`.landing`), so it can never be consumed by a plan-gate (task)
+              // dispatch or vice versa.
+              if (st.pendingOnceGrant.landing !== "" && isPushLanding(text)) {
+                st.pendingOnceGrant.landing = ""
+                return
+              }
+              toolPolicy.guardLanding(event.tool, text, sid, {
+                hasApproval: () => st.hasReviewApprove,
+                priorBlocks: () => st.landingBlocks,
+                recordBlock: () => {
+                  st.landingBlocks += 1
+                },
+                escalate: () => {
+                  // Arm the pending-landing-ask latch: the evaluate handler
+                  // forces the human ask off this latch. Called by guardLanding
+                  // only under `enforce` on a repeat attempt (no approval,
+                  // >= 1 prior block); fail-toward-strict — a host reject leaves
+                  // approval absent, so the next attempt re-blocks and re-arms.
+                  pendingLandingAsk.set(parent, Date.now())
+                  boundLandingAsks()
+                },
+              })
+              return
+            }
+            if (event?.tool === "write" || event?.tool === "edit") {
+              toolPolicy.guardPath(
+                event.tool,
+                event.input?.filePath ?? event.input?.path,
+                asSessionID(event?.sessionID),
+              )
+              return
+            }
+            if (event?.tool === "session_move") {
+              // Telemetry only (never blocks): journal the dispatched move. The
+              // target directory comes from the (unconfirmed) tool payload.
+              const moveDir = (event.input as { directory?: unknown } | undefined)?.directory
+              toolPolicy.observeSessionMove(asSessionID(event?.sessionID), moveDir)
+              return
             }
           } catch (e) {
             if (e instanceof BlockError) throw e
@@ -312,6 +1226,7 @@ export function createTurnstile(
           }
         })
         track(reg, cleanups)
+        hooks++
       } catch (e) {
         journaler.journal({ type: "error", error: `tool.before hook registration: ${e}` })
       }
@@ -321,51 +1236,121 @@ export function createTurnstile(
           try {
             if (event?.tool === "task" || event?.tool === "subagent") {
               const output = String(event.result?.output ?? "")
-              parseMarkers(
+              const child = asSessionID(event?.sessionID)
+              const agent =
+                agentFromTaskInput(event.input) ||
+                agentFromTaskInput(event.result?.input as TaskInput | undefined)
+              // Plan-reviewer delivery path only: await the child→parent edge
+              // before marker parsing and attribution, so a continued subagent
+              // session (no new session.created; edge resolved via session.get)
+              // still attributes. Every other agent keeps today's byte-identical
+              // sync ordering.
+              if (agent === config.agents.planReviewer) {
+                await resolveParent(child)
+              }
+              // Mark the resolved parent live: covers both host
+              // delivery shapes (parent-keyed and child-keyed). A genuinely
+              // unresolved child delivery self-marks, protecting one extra
+              // bucket until the registry LRU ages it out — bounded, documented.
+              ledger.markParent(ledger.parentOf(child))
+              const markerEvents = parseMarkers(
                 output,
-                asSessionID(event?.sessionID),
+                child,
                 "task-result",
                 `task-result\u0000${++taskDeliverySeq}`,
               )
-              const agent =
-                agentFromTaskInput(event.input) ||
-                agentFromTaskInput(event.result?.input as TaskInput | undefined)
+              // Reviewer-APPROVE capture (landing gate, chunk-7): a reviewer
+              // task-result delivery whose first-sight verdict is APPROVE sets
+              // hasReviewApprove — the landing gate's release signal. Mirrors
+              // the plan-reviewer verdict lifecycle but for the landing gate.
+              // Streaming child text does NOT set it: this branch runs only on
+              // task-result delivery, keeping the stream attribution-neutral
+              // (AC-12 — a streamed verdict in child text can't release the
+              // landing gate).
+              if (agent === config.agents.reviewer) {
+                const approved = markerEvents.some(
+                  (e) => e.kind === "verdict" && e.marker.includes("APPROVE"),
+                )
+                if (approved) ledger.state(ledger.parentOf(child)).hasReviewApprove = true
+              }
               // Plan-approval attribution: only a plan-reviewer result moves
-              // the plan gate. Latest verdict wins; a BLOCK or marker-less
-              // result keeps the gate red. Keyed by parent session like the
-              // other gate state.
+              // the plan gate. See attributePlanVerdict — `raw` is always an
+              // actual child session ID, never the parent; an unattributable,
+              // marker-less parent-keyed re-fire journals type:"error" and
+              // leaves the gate untouched (never clobbers a live approval).
               if (agent === config.agents.planReviewer) {
-                const sid = ledger.parentOf(asSessionID(event?.sessionID))
-                const s = ledger.state(sid)
-                const verdicts = output.match(verdictRe) ?? []
-                const marker = verdicts[verdicts.length - 1] ?? ""
-                const result = marker.includes("APPROVE") ? "APPROVE" : "BLOCK"
-                s.hasPlanVerdict = result === "APPROVE"
-                journaler.journal({
-                  type: "plan",
-                  sessionID: sid,
-                  raw: asSessionID(event?.sessionID),
-                  result,
-                  marker: marker || "<none>",
-                  source: "task-result",
-                })
-                journaler.traceEvent("plan-reviewer", "verdict", marker || "<no verdict marker>")
+                await attributePlanVerdict(child, output)
               }
+              // The bare-output suppression — a streamed verdict in the
+              // child's own text hiding a summarized, marker-less delivery —
+              // is scoped to the plan-reviewer only. reviewer/test-runner keep
+              // their pre-suppression behavior: a marker-less delivery
+              // violates even when the child's streamed text quoted a VERDICT.
               const bare =
-                config.agents.bareOutput.includes(agent) && output !== "" && !hasMarker(output)
+                config.agents.bareOutput.includes(agent) &&
+                output !== "" &&
+                !hasMarker(output) &&
+                (agent !== config.agents.planReviewer || ledger.childVerdict(child).marker === "")
               if (bare) {
                 journaler.journal({
                   type: "violation",
-                  sessionID: asSessionID(event?.sessionID),
+                  sessionID: child,
                   agent,
                   reason: "task output contained no GATE/VERDICT marker",
                 })
               }
+              // Orchestrator policy injection: prepend
+              // the policy to the model-facing output text on the first
+              // per-parent per-task delivery, so the model always carries the
+              // pipeline contract. Scoped three ways: tool name (task/subagent
+              // only), config-known subagent name (children dispatch under
+              // their own name — defense in depth), and the policyInjected
+              // flag (once per task; reset per prompt re-supplies it, also
+              // after compaction). The mutation target is event.result.output
+              // in place — the same production-proven target as the read-budget
+              // warn prefix below. Fail-open via an inner try/catch scoped to
+              // ONLY this phase; the handler's shared outer catch (marker
+              // parsing, plan attribution, read-warn) is intentionally not
+              // disturbed, so a policy failure journals injected:false and
+              // swallows rather than blocking the tool.
+              const subagentNames = new Set(
+                (
+                  [
+                    "reviewer",
+                    "planReviewer",
+                    "executor",
+                    "testRunner",
+                    "debugger",
+                    "planner",
+                  ] as const
+                ).map((name) => config.agents[name]),
+              )
+              if (typeof event.agent === "string" && subagentNames.has(event.agent)) return
+              const policyState = ledger.state(child)
+              if (policyState.policyInjected) return
+              // A string result is the confirmed task/subagent shape; any other
+              // shape fails open silently (no corruption, no journal entry).
+              if (!event.result || typeof event.result.output !== "string") return
+              try {
+                event.result.output = ORCHESTRATOR_POLICY + "\n" + event.result.output
+                policyState.policyInjected = true
+                journaler.journal({ type: "policy", sessionID: child, injected: true })
+              } catch (e) {
+                journaler.journal({
+                  type: "policy",
+                  sessionID: child,
+                  injected: false,
+                  error: String(e),
+                })
+              }
               return
             }
             if (event?.tool === "read") {
               // Same parent keying as the guard: count and budget stay in
-              // step regardless of which session ID the host reports.
+              // step regardless of which session ID the host reports. This
+              // stays synchronous on purpose — the before-hook already awaited
+              // resolveParent(sid) for this same sessionID, so the edge is
+              // cached by the time it fires.
               const sessionID = ledger.parentOf(asSessionID(event?.sessionID))
               const s = ledger.state(sessionID)
               s.reads++
@@ -396,13 +1381,60 @@ export function createTurnstile(
                   : "<redacted>",
                 exit: meta.exit ?? meta.exitCode ?? meta.code,
               })
+              // Evidence correlation: record a plausible exit-0
+              // test execution and promote an earlier unverified PASS the
+              // moment its evidence arrives, within the same task lifetime.
+              // No command text ever leaves memory (redaction contract).
+              if (config.gateEvidence !== "off") {
+                const obsSid = asSessionID(event?.sessionID)
+                const exit = meta.exit ?? meta.exitCode ?? meta.code
+                if (
+                  evidence.observe(
+                    obsSid,
+                    event.input?.command ?? event.input?.cmd ?? event.result?.title ?? "",
+                    exit,
+                  )
+                ) {
+                  journaler.journal({
+                    type: "evidence",
+                    sessionID: obsSid,
+                    event: "observed",
+                    exit,
+                  })
+                }
+                const parent = ledger.parentOf(obsSid)
+                // Peek, don't insert: a fresh bucket can never carry a
+                // non-empty `unverifiedPass`, so unknown bash sessions must
+                // not enter the LRU (behavior-preserving guard).
+                const ps = ledger.peek(parent)
+                if (ps && ps.unverifiedPass && evidence.has(parent)) {
+                  ps.hasGatePass = true
+                  ps.unverifiedPass = ""
+                  journaler.journal({
+                    type: "gate",
+                    sessionID: parent,
+                    result: "PASS",
+                    event: "promoted",
+                    verified: true,
+                    mode: config.gateEvidence,
+                  })
+                  journaler.traceEvent(
+                    "test-runner",
+                    "gate",
+                    "GATE: PASS promoted on evidence",
+                    parent,
+                  )
+                }
+              }
             }
           } catch (e) {
-            if (e instanceof BlockError) throw e
+            // execute.after performs no gating, so nothing here can throw a
+            // BlockError; every failure is journaled and the call proceeds.
             journaler.journal({ type: "error", error: `tool.execute.after: ${e}` })
           }
         })
         track(reg, cleanups)
+        hooks++
       } catch (e) {
         journaler.journal({ type: "error", error: `tool.after hook registration: ${e}` })
       }
@@ -431,6 +1463,9 @@ export function createTurnstile(
                 ) {
                   ledger.setParent(properties.sessionID, properties.parentID)
                 } else if (typeof properties.sessionID === "string") {
+                  // Root sessions are live parents; the edge
+                  // branch above is covered by setParent marking the parent.
+                  ledger.markParent(properties.sessionID)
                   // Root sessions only: child-session created events must not
                   // move the project dir (any directory they carry belongs to
                   // the parent's context, and last-writer-wins across child
@@ -477,6 +1512,123 @@ export function createTurnstile(
                 })
                 break
               }
+              case "permission.asked": {
+                // Record plan-gate AND landing-gate asks (disjoint by message
+                // prefix). The value carries the ask's parent session so
+                // replies apply per-session and concurrent sessions cannot
+                // cross-apply. Fail-open — the outer loop journals any throw —
+                // and a missing/non-string id is inert (nothing is recorded).
+                const id = properties.id ?? properties.requestID
+                if (typeof id === "string" && id !== "") {
+                  const sid = asSessionID(properties.sessionID)
+                  const message = typeof properties.message === "string" ? properties.message : ""
+                  // Landing-gate ask: message carries the landing-ask prefix
+                  // (the evaluate handler's echo). A landing ask is disjoint from
+                  // a plan ask (different prefix), so an approval of one never
+                  // releases the other.
+                  if (message.startsWith(LANDING_ASK_MESSAGE_PREFIX)) {
+                    landingGateAsks.set(id, {
+                      sessionID: ledger.parentOf(sid),
+                      recordedAt: Date.now(),
+                    })
+                    boundLandingGateAsks()
+                  } else {
+                    // Plan-gate ask: record when the message carries the
+                    // plan-ask prefix (the evaluate echo) or when the session
+                    // is live-latched and the ask carries no message of its own
+                    // (the escalated echo). A non-empty message WITHOUT either
+                    // prefix is an unrelated ask (bash, write, …) even under a
+                    // latched escalation — the evaluate handler always composes
+                    // a prefix into its message, so a prefixed-or-empty message
+                    // is the expected echo and anything else must never be
+                    // recorded (a human's approval of an unrelated ask cannot
+                    // release the plan or landing gate).
+                    const prefixed = message.startsWith(PLAN_ASK_MESSAGE_PREFIX)
+                    if (prefixed || (message === "" && hasLiveAwaitingAsk(sid))) {
+                      awaitingPlanAsk.delete(sid)
+                      planGateAsks.set(id, {
+                        sessionID: ledger.parentOf(sid),
+                        recordedAt: Date.now(),
+                      })
+                      boundPlanAsks()
+                    } else if (message === "" && hasLiveLandingAsk(sid)) {
+                      // Empty-message landing escalate echo: record for the
+                      // landing gate only. Reached only when the plan latch is
+                      // NOT live — a coincident double-escalation (both latches
+                      // live, one empty-message echo) resolves to the plan gate
+                      // by branch order, a documented edge: the human still
+                      // sees one ask, and the other latch survives for its own
+                      // prefixed echo.
+                      landingGateAsks.set(id, {
+                        sessionID: ledger.parentOf(sid),
+                        recordedAt: Date.now(),
+                      })
+                      boundLandingGateAsks()
+                    }
+                  }
+                }
+                break
+              }
+              case "permission.replied": {
+                // Match the reply against RECORDED plan-gate asks only: a
+                // Match the reply against RECORDED asks: plan-gate ask (keyed
+                // by requestID, consumed once, releases/holds the plan gate)
+                // OR landing-gate ask (consumed once, grants/holds a push). A
+                // requestID absent from both maps was never an ask we raised, so
+                // the reply is inert — an approval of an unrelated permission
+                // ask cannot release either gate. Fail-open: the outer loop
+                // journals any throw.
+                const rid = String(properties.requestID ?? "")
+                const reply = properties.reply
+                const planRecord = planGateAsks.get(rid)
+                if (planRecord) {
+                  planGateAsks.delete(rid)
+                  const parent = planRecord.sessionID
+                  const s = ledger.state(parent)
+                  if (reply === "always") {
+                    // A standing human approval releases the plan gate for the
+                    // rest of the task and records provenance.
+                    s.humanApproval = true
+                    s.hasPlanVerdict = true
+                    journaler.journal({ type: "permission", sessionID: parent, decision: "always" })
+                  } else if (reply === "once") {
+                    // A plan-gate single-dispatch grant: consumed by exactly one
+                    // executor dispatch in execute.before (the .plan
+                    // short-circuit), so a stale grant cannot outlive that
+                    // single dispatch.
+                    s.pendingOnceGrant.plan = rid
+                    journaler.journal({ type: "permission", sessionID: parent, decision: "once" })
+                  } else {
+                    // reject (or any non-allow reply) leaves the gate red: the
+                    // next execute.before dispatch re-blocks.
+                    journaler.journal({ type: "permission", sessionID: parent, decision: "reject" })
+                  }
+                } else if (landingGateAsks.get(rid)) {
+                  const landingRecord = landingGateAsks.get(rid)
+                  landingGateAsks.delete(rid)
+                  const parent = landingRecord!.sessionID
+                  const s = ledger.state(parent)
+                  if (reply === "always") {
+                    // A standing human approval releases the landing gate for
+                    // the rest of the task (the bash guard sees hasReviewApprove
+                    // and allows every push).
+                    s.hasReviewApprove = true
+                    journaler.journal({ type: "permission", sessionID: parent, decision: "always" })
+                  } else if (reply === "once") {
+                    // A landing-gate single-dispatch push grant: consumed by
+                    // exactly one bash dispatch in execute.before (the
+                    // .landing short-circuit), so a stale grant cannot outlive
+                    // that single push.
+                    s.pendingOnceGrant.landing = rid
+                    journaler.journal({ type: "permission", sessionID: parent, decision: "once" })
+                  } else {
+                    // reject (or any non-allow reply) leaves the gate red: the
+                    // next execute.before push re-blocks and re-arms the ask.
+                    journaler.journal({ type: "permission", sessionID: parent, decision: "reject" })
+                  }
+                }
+                break
+              }
               default:
                 break
             }
@@ -484,6 +1636,10 @@ export function createTurnstile(
             journaler.journal({ type: "error", error: `event ${event.type}: ${e}` })
           }
         }
+        // A normal completion (closed stream) is a silent death mode; an
+        // abort/detach exit stays silent. Telemetry only.
+        if (!controller.signal.aborted)
+          journaler.journal({ type: "error", error: "event stream ended" })
       }
       const consuming = consume().catch((e: unknown) => {
         if (!controller.signal.aborted)
@@ -493,8 +1649,21 @@ export function createTurnstile(
         controller.abort()
         void consuming
       })
+      hooks++
     }
 
+    // Load heartbeat: one entry per host-session boot, emitted after every
+    // registration so `hooks` is accurate. Telemetry only — it never blocks.
+    journaler.journal({
+      type: "setup",
+      version,
+      digest: configDigest(config),
+      hooks,
+      ...(config.trace
+        ? { trace: true, agents: config.agents, metricsDir: config.metricsDir }
+        : {}),
+    })
+
     /**
      * Disposes every hook registration tracked during setup.
      * @returns Nothing; individual dispose failures are inert.