@mgiles/perk 3.1.0 → 3.3.0

package/extension/substrate/agentScratch.ts

@@ -5,38 +5,23 @@
 // path after the confined directory has been established. The context filter removes inherited or
 // stale direct scratch custom blocks. A compaction summary may quote old prose/path text; that is
 // not a live guidance delivery or authoritative provenance, and is deliberately left intact.
+//
+// Delivery dedup reads Pi's OWN live context projection (`pi/v1/contextEvidence.ts`) and requires
+// EXACT identity: a `custom` message of this customType whose string content equals the current
+// run's rendered block byte-for-byte. Nothing looser counts — not a text-part array, a user quote,
+// a marker-only match, changed bytes, a parent run's block, or plain `custom` state (`data.content`
+// is state, never model delivery). A projection read failure escapes the hook to Pi's hook-error
+// reporting; no guessed copy is injected.
 
 import { relative, sep } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { activeContextMessages, type ContextMessage } from "../pi/v1/contextEvidence.ts";
 import { type ReportTarget, report } from "../surfaces/report.ts";
 import { agentScratchDir, ensureAgentScratch } from "./cache.ts";
 import { activeSessionRunId, type SessionDataCtx } from "./sessionData.ts";
-import {
-  activeContextWindow,
-  type BranchEntry,
-  type BranchSource,
-  branchOf,
-  rebuildWorkflowState,
-} from "./workflowState.ts";
 
 export const AGENT_SCRATCH_CONTEXT_TYPE = "perk:agent-scratch";
 
-/** Perk-owned children whose canonical definitions are report-only. */
-export const REPORT_ONLY_CHILD_AGENTS = [
-  "perk.adversarial-reviewer",
-  "perk.draft-reviewer",
-  "perk.dream-analyst",
-  "perk.dream-reducer",
-  "perk.harvest-analyst",
-  "perk.learn-analyst",
-  "perk.objective-explorer",
-  "perk.pr-reviewer",
-  "perk.review-angle-selector",
-  "perk.review-classifier",
-] as const;
-
-const REPORT_ONLY_CHILD_SET = new Set<string>(REPORT_ONLY_CHILD_AGENTS);
-
 export interface AgentScratchBlock {
   runId: string;
   /** Repository-relative POSIX-style path carried in model context. */
@@ -59,22 +44,6 @@ export function renderAgentScratchBlock(cwd: string, runId: string): AgentScratc
   return { runId, path, marker, content };
 }
 
-/**
- * Eligibility follows the branch-LWW workflow mode and the locally exposed pi-subagents child
- * identity. Unknown/custom children remain eligible because no generic report-only metadata exists.
- */
-export function isAgentScratchEligible(
-  ctx: BranchSource,
-  childAgent: string | undefined = process.env.PI_SUBAGENT_CHILD_AGENT,
-): boolean {
-  try {
-    if (rebuildWorkflowState(branchOf(ctx)).mode === "read-only") return false;
-  } catch {
-    // No rebuilt explicit read-only mode means the parent posture remains the fallback.
-  }
-  return childAgent === undefined || !REPORT_ONLY_CHILD_SET.has(childAgent);
-}
-
 export interface AgentScratchProvisioner {
   resolve(ctx: AgentScratchContext): AgentScratchBlock | null;
 }
@@ -122,29 +91,34 @@ export function createAgentScratchProvisioner(
   };
 }
 
-/** Whether this exact current-run block remains directly represented after compaction. */
-function branchHasBlock(branch: readonly BranchEntry[], block: AgentScratchBlock): boolean {
-  return activeContextWindow(branch).some(
-    (entry) =>
-      entry.customType === AGENT_SCRATCH_CONTEXT_TYPE &&
-      ((entry.type === "custom_message" && entry.content === block.content) ||
-        (entry.type === "custom" && entry.data?.content === block.content)),
+/** Whether this exact current-run block is still directly delivered in Pi's live projection. */
+function contextHasBlock(messages: readonly ContextMessage[], block: AgentScratchBlock): boolean {
+  return messages.some(
+    (message) =>
+      message.role === "custom" &&
+      message.customType === AGENT_SCRATCH_CONTEXT_TYPE &&
+      message.content === block.content,
   );
 }
 
-/** Register eligible-turn delivery and direct scratch-custom context hygiene. */
+/**
+ * Register eligible-turn delivery and direct scratch-custom context hygiene. `eligible` is the
+ * composition root's `!gate && !runner` — a runner child (every perk report child) never
+ * provisions scratch; the module knows nothing about agent names.
+ */
 export function registerAgentScratch(
   pi: ExtensionAPI,
-  provisioner: AgentScratchProvisioner = createAgentScratchProvisioner(),
+  provisioner: AgentScratchProvisioner,
+  eligible: () => boolean,
 ): void {
   pi.on("before_agent_start", async (_event, ctx) => {
-    if (!isAgentScratchEligible(ctx)) return;
+    if (!eligible()) return;
 
-    // Provision before dedup: an externally deleted directory is repaired even while the live
-    // branch still carries this run's exact guidance block.
+    // Provision before dedup: an externally deleted directory is repaired even while live
+    // context still carries this run's exact guidance block (and before any projection read).
     const block = provisioner.resolve(ctx);
     if (block === null) return;
-    if (branchHasBlock(branchOf(ctx), block)) return;
+    if (contextHasBlock(activeContextMessages(ctx), block)) return;
     return {
       message: {
         customType: AGENT_SCRATCH_CONTEXT_TYPE,
@@ -155,8 +129,7 @@ export function registerAgentScratch(
   });
 
   pi.on("context", async (event, ctx) => {
-    const eligible = isAgentScratchEligible(ctx);
-    const block = eligible ? provisioner.resolve(ctx) : null;
+    const block = eligible() ? provisioner.resolve(ctx) : null;
     let keptCurrent = false;
     return {
       messages: event.messages.filter((message) => {

package/extension/substrate/bashScanTimeout.ts

@@ -0,0 +1,181 @@
+// The bash scan-timeout guard's pure policy: the default `timeout` for gitignore-blind scans issued
+// through Pi's `bash` tool, the command classifier, and the expiry steer. Recursive `grep -r…` and
+// `find` without `-maxdepth` ignore `.gitignore`, so from a checkout carrying `node_modules/`,
+// `.venv/`, `.worktrees/` and the like they walk everything — observed running for minutes to the
+// better part of an hour with no `timeout` on the call, so nothing stopped them. Every
+// legitimately scoped scan finished in single-digit seconds. The hooks that apply this policy
+// (the `tool_call` injection + the `tool_result` note) live in the Pi adapter home,
+// `pi/v1/bashScanTimeout.ts`; the contract is contracts.md §8.69.
+//
+// The override contract: an explicit `timeout` of ANY value on the call is the model's override —
+// never rewritten or capped. Expiry is detected only from Pi's own terminal `Command timed out
+// after N seconds` status line, never from a line the command printed.
+//
+// Classifier design: regex-only over each physical line's quote-aware top-level segments (the
+// gate's splitter, reused so both hooks agree on what a segment is and a flag in a LATER pipeline
+// stage — `grep -n foo f | sort -r` — is never attributed to the grep). The command word is
+// matched at ANY command boundary inside a segment rather than as the segment's leading word, so
+// wrapper prefixes (`env`/`nice`/`time`/`nohup`/`xargs`), nested shells (`sh -c '…'`) and `$(…)`
+// substitutions are covered without enumerating wrappers. A grep's recursion flag is searched over
+// its full tail (over-matches only); a find's `-maxdepth` exemption is searched only in the find's
+// OWN window — up to the next command word or a quoted-in sequencing operator, quoted spans blanked
+// — so neither a later bounded find nor a quoted argument ever exempts an unbounded one.
+// Over-matching is tolerated by design — a spurious 30s cap on a fast command is harmless, a
+// missed scan is the bug. The accepted over-matches (pinned as such in the tests, so any future
+// tightening is deliberate): `echo grep -r`, `git grep -rn foo`, `rg -n 'grep -rn foo' src/`,
+// `grep -n "x -r y" f`.
+// Incidental precision, not a goal: a quote-adjacent cluster (`"-r"`, `'grep -r'`) is not a flag
+// position, so quoted flags do not match.
+
+import { splitTopLevelSegments } from "./toolGating.ts";
+
+/**
+ * The injected default, in seconds — the ONE source of truth for the number. The managed
+ * `AGENTS.md` bullet the Python plane renders (`_agents_inner()`) mirrors it verbatim and a Python
+ * parity test pins the mirror; change both in the same turn.
+ */
+export const SCAN_TIMEOUT_SECONDS = 30;
+
+export type ScanKind = "recursive-grep" | "unbounded-find";
+
+/**
+ * A grep-family or `find` command word at a command boundary: segment start, whitespace, a quote,
+ * a backtick, `(` (as in `$(`) or a `\` alias-bypass, with an optional `dir/` path prefix, followed
+ * by whitespace or end. `ast-grep` never matches (`-` precedes `grep`); `docs/find.md` and
+ * `findings/` never match (`.`/`i` follow `find`).
+ */
+const COMMAND_WORD =
+  /(?:^|[\s'"`(\\])(?:[\w./-]*\/)?(grep|egrep|fgrep|zgrep|zegrep|zfgrep|bzgrep|xzgrep|rgrep|find)(?=\s|$)/g;
+
+/**
+ * A recursion flag in a grep's tail: a whitespace-delimited short cluster containing `r`/`R`
+ * (`-r`, `-rn`, `-rniE`, `-Rl`, `-nr`, `-rnA3`) or one of the explicit long forms. Other long
+ * options (`--color=never`, `--exclude-dir=…`) never match — the cluster arm cannot consume the
+ * second `-`.
+ */
+const RECURSIVE_FLAG =
+  /(?:^|\s)(?:--recursive|--dereference-recursive|--directories=recurse|(?:-d|--directories)\s+recurse|-[A-Za-z0-9]*[rR][A-Za-z0-9]*)(?=\s|$)/;
+
+/** A depth bound in a find's own window — the only thing that exempts a `find` (`-prune`/`-not -path` still walk). */
+const MAXDEPTH_FLAG = /(?:^|\s)-maxdepth(?=\s|$)/;
+
+/**
+ * A sequencing operator that survived the top-level split — i.e. one inside a quoted nested shell
+ * (`sh -c 'find . -type f; find . -maxdepth 1'`) or a lone `&`. It ends a `find`'s exemption
+ * window (see `findWindow`).
+ */
+const INNER_OPERATOR = /[;|&]/;
+
+/**
+ * Pi's terminal status line for an expired bash call. No `m` flag — `$` is end-of-string, so the
+ * line must be the LAST thing in the text (Pi's `appendStatus` always places the status last), never
+ * a line the command itself printed mid-output.
+ */
+const TIMEOUT_STATUS = /(?:^|\n)Command timed out after (\S+) seconds$/;
+
+/**
+ * Classify a bash command as a gitignore-blind scan, or `null`. Pure and offline-testable. Per
+ * physical line, per quote-aware top-level segment, in order: the first segment that classifies
+ * decides. Fast non-scans (`rg`, `fd`, `ast-grep`, `grep -n foo file`) are `null`.
+ */
+export function classifyScanCommand(command: string): ScanKind | null {
+  for (const line of command.split("\n")) {
+    for (const segment of splitTopLevelSegments(line)) {
+      const kind = classifySegment(segment);
+      if (kind !== null) return kind;
+    }
+  }
+  return null;
+}
+
+/** One command-word occurrence: the word, where its tail starts, and where the next occurrence begins. */
+type Occurrence = { word: string; tailStart: number; nextStart: number };
+
+function occurrences(segment: string): Occurrence[] {
+  // A fresh matcher per segment: the shared regex is global (stateful `lastIndex`).
+  const words = new RegExp(COMMAND_WORD.source, "g");
+  const found: Occurrence[] = [];
+  for (const match of segment.matchAll(words)) {
+    const word = match[1];
+    if (word === undefined) continue;
+    const previous = found.at(-1);
+    if (previous !== undefined) previous.nextStart = match.index;
+    found.push({ word, tailStart: match.index + match[0].length, nextStart: segment.length });
+  }
+  return found;
+}
+
+/**
+ * `text` with every single-/double-quoted span replaced by ONE space (token boundaries kept,
+ * quoted content gone). The same quote model as the segment splitter (no backslash-escape
+ * handling; an unterminated quote runs to the end).
+ */
+function blankQuoted(text: string): string {
+  let out = "";
+  let quote: '"' | "'" | null = null;
+  for (const ch of text) {
+    if (quote !== null) {
+      if (ch === quote) quote = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      out += " ";
+      continue;
+    }
+    out += ch;
+  }
+  return out;
+}
+
+/**
+ * The text in which THIS `find`'s `-maxdepth` may appear: its tail up to the next command word,
+ * with quoted spans blanked, then cut at the first sequencing operator that survived the
+ * top-level split (a quoted nested shell's `;`/`|`/`&`). Blanking first means only an UNQUOTED
+ * standalone `-maxdepth` option counts (a `-printf 'x -maxdepth y'` format or a `-name
+ * "-maxdepth"` operand never exempts) and a quoted `;` inside a `-name` pattern never ends the
+ * window. The exemption is the inverse of a match — it REMOVES a cap — so its window must be
+ * tight: a later bounded find (`sh -c 'find . -type f; find . -maxdepth 1'`) or another command
+ * after a quoted-in operator must never exempt an earlier unbounded one; shrinking the window can
+ * only add caps. Residual: an UNQUOTED `-maxdepth` operand value (`-name -maxdepth`) still
+ * exempts — not a real-world shape.
+ */
+function findWindow(segment: string, occurrence: Occurrence): string {
+  const tail = blankQuoted(segment.slice(occurrence.tailStart, occurrence.nextStart));
+  const operator = INNER_OPERATOR.exec(tail);
+  return operator === null ? tail : tail.slice(0, operator.index);
+}
+
+function classifySegment(segment: string): ScanKind | null {
+  for (const occurrence of occurrences(segment)) {
+    if (occurrence.word === "rgrep") return "recursive-grep";
+    if (occurrence.word === "find") {
+      if (!MAXDEPTH_FLAG.test(findWindow(segment, occurrence))) return "unbounded-find";
+      continue;
+    }
+    // A grep's recursion flag is searched over its FULL tail (not a window): a permuted `-r` may
+    // follow a quoted pattern that itself contains a command word (`grep -n "find . -maxdepth 1"
+    // -r .`), and for a grep the full tail can only over-match — never miss.
+    if (RECURSIVE_FLAG.test(segment.slice(occurrence.tailStart))) return "recursive-grep";
+  }
+  return null;
+}
+
+/**
+ * The seconds from Pi's terminal timeout status when `text` (a bash error result's last text
+ * block) ENDS with it; `null` otherwise — including when the literal appears mid-output.
+ */
+export function expiredAfterSeconds(text: string): string | null {
+  return TIMEOUT_STATUS.exec(text)?.[1] ?? null;
+}
+
+/** The steer appended to an expired scan's result (`seconds` as parsed from Pi's status line). */
+export function scanTimeoutNote(kind: ScanKind, seconds: string): string {
+  const what = kind === "recursive-grep" ? "recursive grep" : "unbounded find";
+  return (
+    `perk: this ${what} hit the ${seconds}s timeout. Recursive \`grep -r…\` and \`find\` without ` +
+    "`-maxdepth` ignore `.gitignore` (they walk `node_modules`, `.venv`, `.worktrees`, …). Prefer " +
+    "the `grep`/`find` tools or `rg`/`fd`, which honor `.gitignore`; to run this command anyway, " +
+    "pass a larger explicit `timeout` (seconds) on the bash call."
+  );
+}

package/extension/substrate/bindingDelivery.ts

@@ -14,29 +14,29 @@
 //
 // This is the SINGLE delivery path for perk's own nudges. Delivery NEVER double-delivers: the
 // cold↔warm dedup marker is `BINDING_HEADER` itself — the cold door's initial prompt and every warm
-// injection carry it, so Mechanism A injects ONLY when neither the compaction-active branch window
-// NOR the submitting turn's prompt already carries the header (idempotent across turns/reloads;
-// after compaction drops the original from model context it re-delivers). The prompt scan is
-// load-bearing on the launch turn: at
-// `before_agent_start` the just-submitted prompt is NOT yet on the branch, so the branch scan
-// alone would miss a cold seed's binding suffix and double-deliver.
+// injection carry it, so Mechanism A injects ONLY when neither the submitting turn's prompt NOR
+// Pi's live context projection (`pi/v1/contextEvidence.ts` — the header as persisted USER content
+// or as an owned `perk:binding-context` custom) already carries the header (idempotent across
+// turns/reloads; after compaction drops the original from model context it re-delivers, and a
+// summary quoting the header never suppresses). The prompt scan is load-bearing on the launch
+// turn: at `before_agent_start` the just-submitted prompt is NOT yet persisted, so the projection
+// alone would miss a cold seed's binding suffix and double-deliver. The full branch is read only
+// for the stage (`activeStageRender`) — eligibility survives compaction; delivery evidence is
+// Pi's. A projection read failure escapes the hook to Pi's hook-error reporting rather than
+// injecting a guessed copy.
 //
-// LBYL throughout: a missing/unreadable transclude target degrades to the nudge pointer with a
-// loud-but-non-fatal warning, never throws, never blocks a turn. Resolver shape `issues` are NOT
-// surfaced warm (the cold launch + doctor own them); only the transclude `warnings` are.
+// LBYL on the render path: a missing/unreadable transclude target degrades to the nudge pointer
+// with a loud-but-non-fatal warning, never throws, never blocks a turn (only a session read
+// failure — branch or projection — escapes the hooks). Resolver shape `issues` are NOT surfaced
+// warm (the cold launch + doctor own them); only the transclude `warnings` are.
 
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { activeContextMessages, contextCarriesMarker } from "../pi/v1/contextEvidence.ts";
 import { loadDefaultBindings, resolveBindings, type SkillBinding } from "./bindings.ts";
 import { loadPerkConfig } from "./config.ts";
-import {
-  activeContextWindow,
-  type BranchEntry,
-  branchCarries,
-  branchOf,
-  rebuildWorkflowState,
-} from "./workflowState.ts";
+import { type BranchEntry, branchOf, rebuildWorkflowState } from "./workflowState.ts";
 
 /**
  * The cross-plane dedup marker AND render header. MUST stay byte-identical to the Python cold
@@ -156,9 +156,16 @@ function stripFrontmatter(text: string): string {
   return text; // no closing delimiter — leave the text unchanged
 }
 
-/** Whether a cold prompt or warm injection still active in model context carries the marker. */
-function branchHasHeader(branch: readonly BranchEntry[]): boolean {
-  return branchCarries(activeContextWindow(branch), BINDING_HEADER);
+/**
+ * Whether a persisted cold prompt (user content) or a prior warm injection (the owned custom)
+ * still live in Pi's context projection carries the header. Throws when the projection read
+ * fails — the hook boundary owns that.
+ */
+function contextHasHeader(ctx: ExtensionContext): boolean {
+  return contextCarriesMarker(activeContextMessages(ctx), {
+    customType: BINDING_CONTEXT_TYPE,
+    marker: BINDING_HEADER,
+  });
 }
 
 /** The launched stage's `stage:<id>` render, or `null` when there is no stage / nothing matches. */
@@ -171,22 +178,22 @@ function activeStageRender(cwd: string, branch: readonly BranchEntry[]): Binding
 /**
  * Register warm-door binding delivery: Mechanism A's dedup-guarded `before_agent_start` injection
  * plus a `context` strip mirroring planMode.ts / objectiveAuthor.ts (keep while the stage's
- * bindings are live; strip the stale custom otherwise). Inert when nothing matches the stage;
- * never throws. Mechanism B (`bindingSuffix`) is wired by the command modules themselves.
+ * bindings are live; strip the stale custom otherwise). Inert when nothing matches the stage; the
+ * render path never throws (only a failed session read escapes to Pi's hook-error reporting).
+ * Mechanism B (`bindingSuffix`) is wired by the command modules themselves.
  */
 export function registerBindingDelivery(pi: ExtensionAPI): void {
   // Mechanism A — inject the launched stage's resolved bindings as a hidden context message,
-  // but ONLY when no entry in the compaction-active branch window AND not the submitting turn's
-  // prompt already carries BINDING_HEADER (the cold door's initial prompt or a prior warm inject) — the cold↔warm
+  // but ONLY when neither the submitting turn's prompt NOR Pi's live context projection already
+  // carries BINDING_HEADER (the cold door's initial prompt or a prior warm inject) — the cold↔warm
   // idempotency guard. The `event.prompt` scan covers the launch turn, where the just-submitted
-  // prompt is not yet on the branch; a worker prompt carries no header, so Mechanism A still
-  // fires there (contracts.md §8.38).
+  // prompt is not yet persisted; a worker prompt carries no header, so Mechanism A still fires
+  // there (contracts.md §8.38). Render-before-dedup: an inert stage never reads the projection.
   pi.on("before_agent_start", async (event, ctx) => {
-    const branch = branchOf(ctx);
-    const rendered = activeStageRender(ctx.cwd, branch);
+    const rendered = activeStageRender(ctx.cwd, branchOf(ctx));
     if (rendered === null || rendered.text === null) return;
-    if (branchHasHeader(branch)) return;
     if (event.prompt.includes(BINDING_HEADER)) return;
+    if (contextHasHeader(ctx)) return;
     for (const warning of rendered.warnings) console.error(`perk: ${warning}`);
     return {
       message: {
@@ -204,7 +211,8 @@ export function registerBindingDelivery(pi: ExtensionAPI): void {
   //
   // Deliberately NARROWER than planMode: it strips ONLY the BINDING_CONTEXT_TYPE custom, never a
   // user message carrying the header — a cold launch's initial prompt legitimately carries
-  // BINDING_HEADER and must survive in context.
+  // BINDING_HEADER and must survive in context, even after the stage stops binding. The strip
+  // never reads the projection (it filters the messages Pi hands it).
   pi.on("context", async (event, ctx) => {
     const branch = branchOf(ctx);
     const rendered = activeStageRender(ctx.cwd, branch);

package/extension/substrate/bindings.ts

@@ -12,8 +12,6 @@
 
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
-// Type-only import (config.ts value-imports this module; a value import here would cycle).
-import type { TomlScalar } from "./config.ts";
 import { parse } from "./miniYaml.ts";
 import { sharedDir } from "./resources.ts";
 
@@ -76,10 +74,11 @@ export function loadDefaultBindings(): SkillBinding[] {
 }
 
 /**
- * Parse `.perk/config.toml` `[[bindings]]` rows (scalar tables) into `SkillBinding`s. Tolerant like
- * the YAML reader: absent/ill-typed fields become empty strings so the *resolver* reports them.
+ * Parse `.perk/config.toml` `[[bindings]]` rows into `SkillBinding`s. Rows are tolerant
+ * unknown-valued records (like the YAML reader's entries): absent/ill-typed fields become empty
+ * strings so the *resolver* reports them.
  */
-export function parseUserBindings(rows: Array<Record<string, TomlScalar>>): SkillBinding[] {
+export function parseUserBindings(rows: Array<Record<string, unknown>>): SkillBinding[] {
   return rows.map((row) => {
     const trigger = typeof row.trigger === "string" ? row.trigger : "";
     const [kind, targetId] = splitTrigger(trigger);

package/extension/substrate/cache.ts

@@ -15,11 +15,13 @@
 // `atomicWriteFileSync` (temp file in the same directory + atomic rename) so a concurrent
 // writer can never tear a file — a reader sees either the old bytes or the new bytes, never a
 // mix (guard-tested by writeGuard.test.ts). The exemptions are the append-only NDJSON streams
-// — the worker's `events.ndjson` (worker/worker.ts) and the §8.58 hunk-watch `outbox.ndjson` /
+// — the worker's `events.ndjson` (worker/stageExecution.ts) and the §8.58 hunk-watch `outbox.ndjson` /
 // `delivered.ndjson` (hunkFeedback/perkFeedback.ts / hunkFeedback/store.ts) — where O_APPEND
 // appends cannot truncate-tear and whole-file replace would introduce a read-modify-write race
-// between independent processes. Atomicity is not mutual exclusion — whole-file
-// last-writer-wins between concurrent writers is the accepted residual.
+// between independent processes. The §8.3 worktree resolver lock (`worktreeResolverLock.ts`)
+// separately writes/fsyncs only freshly wx-created descriptors: atomic replacement would destroy
+// exclusion. Atomicity alone is not mutual exclusion — ordinary artifact writes remain
+// whole-file last-writer-wins.
 
 import { randomBytes } from "node:crypto";
 import {
@@ -34,7 +36,7 @@ import {
   rmSync,
   writeFileSync,
 } from "node:fs";
-import { join, relative } from "node:path";
+import { join, relative, sep } from "node:path";
 
 /**
  * Atomically replace `path` with `content` (the interior atomic-write seam).
@@ -147,16 +149,28 @@ export function sessionDataDir(cwd: string, runId: string): string {
   return join(runScratchDir(cwd, runId), "data");
 }
 
+/**
+ * Whether a run id can only select one child of the shared runs directory: non-empty, not
+ * `.`/`..`, and free of `/`, `\`, and NUL. The one run-id trust predicate — the write path
+ * throws through it (`assertSafeRunId`); the read-path identity seam
+ * (`sessionData.activeSessionRunId`) narrows through it so a hostile rebuilt run_id degrades to
+ * no-identity before any path derivation. Legitimate ids (ULID mints, `<parent>.<n>` fork
+ * derivations) all pass.
+ */
+export function isSafeRunId(runId: string): boolean {
+  return (
+    runId.length > 0 &&
+    runId !== "." &&
+    runId !== ".." &&
+    !runId.includes("/") &&
+    !runId.includes("\\") &&
+    !runId.includes("\0")
+  );
+}
+
 /** Reject run ids that could select anything except one child of the shared runs directory. */
 function assertSafeRunId(runId: string): void {
-  if (
-    runId.length === 0 ||
-    runId === "." ||
-    runId === ".." ||
-    runId.includes("/") ||
-    runId.includes("\\") ||
-    runId.includes("\0")
-  ) {
+  if (!isSafeRunId(runId)) {
     throw new Error(`refusing unsafe run id ${JSON.stringify(runId)}`);
   }
 }
@@ -215,6 +229,44 @@ export function ensureRunScratch(cwd: string, runId: string): string {
   return dir;
 }
 
+/**
+ * Strict current-run data namespace for exclusion and provenance reads. Aliased checkout roots
+ * canonicalize together; redirects within checkout-owned components refuse. Reads never create
+ * directories. A missing component is absent, not an I/O-error sentinel.
+ */
+export function canonicalSessionDataDir(
+  cwd: string,
+  runId: string,
+  opts: { create: boolean },
+): string | null {
+  assertSafeRunId(runId);
+  const root = realpathSync(cwd);
+  const dir = sessionDataDir(root, runId);
+  let component = root;
+  for (const segment of relative(root, dir).split(sep)) {
+    component = join(component, segment);
+    if (opts.create) {
+      ensureUnredirectedDirectory(component, {
+        createMode: 0o755,
+        rejectGroupWorldWrite: true,
+      });
+    } else {
+      let stat: ReturnType<typeof lstatSync>;
+      try {
+        stat = lstatSync(component);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+        throw error;
+      }
+      if (!stat.isDirectory() || stat.isSymbolicLink() || (stat.mode & 0o022) !== 0) {
+        throw new Error(`refusing an unsafe session-data namespace: ${component}`);
+      }
+    }
+  }
+  if (realpathSync(dir) !== dir) throw new Error("refusing redirected session data");
+  return dir;
+}
+
 /**
  * Create the private run-owned agent directory as 0700 from the outset, then re-apply that mode on
  * reuse. The mode protects against other OS users; it is not a sandbox from another process running

package/extension/substrate/childRestrictions.ts

@@ -0,0 +1,39 @@
+// The two native-child booleans (contracts.md §8.3): the pi-subagents runner bit and perk's
+// report restriction packet. Neither is identity; the floor is the only thing that restricts.
+
+const FAMILY = "perk.parent-restrictions/";
+const NAMESPACE = `${FAMILY}1`;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** The runner stamp pi-subagents sets on every background (runner-hosted) child. */
+export function isRunnerChild(env: NodeJS.ProcessEnv): boolean {
+  return env.PI_SUBAGENT_CHILD === "1";
+}
+
+/**
+ * Runner bit AND perk's packet ⇒ floor. No packet (the delegation-dispatched writer) ⇒ no floor.
+ * A present packet must be exactly `{readOnly: boolean}` under perk's v1 namespace; any other
+ * `perk.parent-restrictions/…` key (an unsupported version — producer/consumer skew) or any
+ * other shape fails closed. Unrelated namespaces beside it are opaque.
+ */
+export function decodeReadOnlyFloor(runner: boolean, raw: string | undefined): boolean {
+  if (!runner || raw === undefined) return false;
+  let envelope: unknown;
+  try {
+    envelope = JSON.parse(raw);
+  } catch {
+    return true;
+  }
+  if (!isRecord(envelope)) return true;
+  if (Object.keys(envelope).some((key) => key.startsWith(FAMILY) && key !== NAMESPACE)) return true;
+  if (!Object.hasOwn(envelope, NAMESPACE)) return false;
+  const value = envelope[NAMESPACE];
+  // Own-key check: a polluted `Object.prototype.readOnly` must never un-floor a malformed value.
+  if (!isRecord(value) || !Object.hasOwn(value, "readOnly") || Object.keys(value).length !== 1) {
+    return true;
+  }
+  return typeof value.readOnly === "boolean" ? value.readOnly : true;
+}

package/extension/substrate/coldDoor.ts

@@ -8,7 +8,7 @@
 //
 // A door consumes it as:
 //
-//   const r = await runColdDoor<SubmitOk>(pi, ctx, ["pr", "submit", "--json"], {
+//   const r = await runColdDoor<PublishedChange>(pi, ctx, ["pr", "submit", "--json"], {
 //     label: "perk pr submit",
 //     decode,
 //   });
@@ -99,6 +99,22 @@ export function objectField(payload: ColdJson, key: string): ColdJson | undefine
   return value as ColdJson;
 }
 
+/** Lenient object-list field: a non-array (or any non-object element) contributes nothing. */
+export function objectListField(payload: ColdJson, key: string): ColdJson[] {
+  const value = payload[key];
+  if (!Array.isArray(value)) return [];
+  return value.filter(
+    (item): item is ColdJson => typeof item === "object" && item !== null && !Array.isArray(item),
+  );
+}
+
+/** Lenient string-list field: non-string elements are dropped. */
+export function stringListField(payload: ColdJson, key: string): string[] {
+  const value = payload[key];
+  if (!Array.isArray(value)) return [];
+  return value.filter((item): item is string => typeof item === "string");
+}
+
 /** Best-effort parse of stdout into a plain object; null on anything else. */
 function parseObject(stdout: string): ColdJson | null {
   let parsed: unknown;