@mgiles/perk 1.0.1 → 2.0.0

package/extension/factories/planSave.ts

@@ -1,4 +1,4 @@
-// The warm `/plan-save` door (turn-3 §5/§6). The in-session twin of the Python cold
+// The warm `/plan-save` door. The in-session twin of the Python cold
 // door (`perk plan save`): a deterministic, terminating tool + command that WRAP the existing
 // storage — they do NOT reimplement the GitHub write. `savePlan()` delegates to `perk plan save
 // --json` via the shared cold-door client (`runColdDoor` — the plan markdown rides the run-scratch
@@ -13,7 +13,7 @@
 //
 // APPROVAL→SAVE ORCHESTRATION. The exported `approvalSave` seam is the shared
 // APPROVED-review → save flow: artifact-first resolution → `savePlan` (warm node-link recovery
-// inside, from the `objective_node_claim` carrier) → gate exit on a successful save (D1a). The
+// inside, from the `objective_node_claim` carrier) → gate exit on a successful save. The
 // `/plan-save` command is the MANUAL FAILSAFE invocation of the same seam; the review backends
 // (plannotator / first-party / tombell) wire their APPROVED outcome into it.
 //
@@ -34,8 +34,10 @@ import {
   runColdDoor,
   stringField,
 } from "../substrate/coldDoor.ts";
+import { registerPerkCommand } from "../substrate/command.ts";
 import { failFor, ok, type Result } from "../substrate/result.ts";
 import { readSessionArtifact, type SessionDataCtx } from "../substrate/sessionData.ts";
+import { captureSessionPointer } from "../substrate/sessionPointers.ts";
 import type { ToolGating } from "../substrate/toolGating.ts";
 import { idArrayParam, paramsOf, stringParam } from "../substrate/toolParams.ts";
 import {
@@ -50,7 +52,7 @@ import { nodeClaimsEqual, readNodeClaim } from "./objectivePlan.ts";
 import { PLAN_DRAFT_ARTIFACT } from "./planDraft.ts";
 import { generatePlanTitle } from "./planTitle.ts";
 
-/** The ok-arm fields (turn-3 D6) — the `details` surface doubles as branch-safe persisted state. */
+/** The ok-arm fields — the `details` surface doubles as branch-safe persisted state. */
 export interface PlanSaveOk {
   /** `issue.id` is the opaque string issue id (GitHub "42", Linear "ENG-123") — §8.21. */
   issue: { id: string; url: string };
@@ -312,7 +314,20 @@ export async function savePlan(
   });
   if (!r.ok) return fail(r.message, r.errorType);
 
-  // Link the live session (turn-3 D4): append iff the rebuilt ref differs, with a strict read-back.
+  // Capture the planning session pointer (contracts.md §8.35): this planning run self-keys by its
+  // own run_id into the shared main checkout, so a later/other session can resolve it cross-run.
+  // Best-effort + non-fatal (the carrier warns + returns false; a successful save must stand).
+  // Covers /plan-save, the plan_save tool, and approvalSave (all flow through savePlan).
+  captureSessionPointer({
+    cwd: ctx.cwd,
+    runId,
+    klass: "planning",
+    site: "main",
+    // Optional-chained: best-effort, and some side-session fakes have no getSessionFile.
+    sessionFile: ctx.sessionManager.getSessionFile?.(),
+  });
+
+  // Link the live session: append iff the rebuilt ref differs, with a strict read-back.
   const ref = r.data.plan_ref;
   if (!planRefsEqual(rebuildWorkflowState(branch()).active_plan_ref ?? null, ref)) {
     appendWorkflowState(pi, ctx, {
@@ -346,7 +361,7 @@ export async function savePlan(
   }
   // Render all THREE node-link outcomes (the silent-partial-failure fix). A failed advance
   // (`linked: false`) is a non-fatal sub-step — the plan genuinely saved — but it must be VISIBLE
-  // (the §8.4 "warn + retriable" intent), not swallowed. Both surfaces render content[0].text, so
+  // (the §8.3 "surfaced, never swallowed" intent), not swallowed. Both surfaces render content[0].text, so
   // this one site fixes the tool path (the model relays it) and the command path (the user sees the
   // notify) at once.
   let linkSuffix = "";
@@ -466,8 +481,8 @@ export function decodePlanSaveParams(params: unknown): PlanSaveParams | null {
 const TOOL_GUIDELINES = [
   "Use plan_save only after the plan is decision-complete and the user has agreed; it creates the canonical GitHub plan and ends the turn.",
   "Keep the working draft current with plan_draft — the validated plan-draft artifact is what plan_save saves; the `plan` parameter is only a fallback when no draft exists. Never reference line numbers — use durable anchors (function names, behavioral descriptions, structural locations).",
-  "Pass consumed_learn (the gathered perk:learn issue ids) only from the learned-docs factory — it links the issues the docs plan consolidates so /land closes + labels them.",
-  "When saving an objective-factory plan, pass BOTH objective_id and node_id — this links the node to the plan and advances it planning → in_progress (no separate backlink call).",
+  "Pass plan_save's consumed_learn (the gathered perk:learn issue ids) only from the learned-docs factory — it links the issues the docs plan consolidates so /land closes + labels them.",
+  "When saving an objective-factory plan, pass plan_save BOTH objective_id and node_id — this links the node to the plan and advances it planning → in_progress (no separate backlink call).",
 ];
 
 /** Register the warm door: the `plan_save` tool (canonical) + the `/plan-save` command twin. */
@@ -552,7 +567,7 @@ export function registerPlanSave(pi: ExtensionAPI, gating: ToolGating): void {
     },
   });
 
-  pi.registerCommand("plan-save", {
+  registerPerkCommand(pi, "plan-save", {
     description:
       "Save the latest proposed plan to GitHub — the manual failsafe for the approval→save flow " +
       "(the read-only → read-write boundary).",

package/extension/index.ts

@@ -16,12 +16,16 @@ import { registerAskUser } from "./doors/askUser.ts";
 import { registerCiExecutor } from "./doors/ciExecutor.ts";
 import { registerLand } from "./doors/land.ts";
 import { registerLearn } from "./doors/learn.ts";
-import { registerLearnDocs } from "./doors/learnDocs.ts";
+import { CODE_DOOR, DOCS_DOOR, registerLearnFactoryDoor } from "./doors/learnFactory.ts";
 import { registerLifecycleGates } from "./doors/lifecycleGates.ts";
 import { registerPrReview } from "./doors/prReview.ts";
+import { registerPrReviewBrowser } from "./doors/prReviewBrowser.ts";
+import { registerPrReviewTerminal } from "./doors/prReviewTerminal.ts";
 import { registerReady } from "./doors/ready.ts";
 import { registerSelfcheck } from "./doors/selfcheck.ts";
 import { registerSubmit } from "./doors/submit.ts";
+import { registerSubmitPrReview } from "./doors/submitPrReview.ts";
+import { registerImplementHere } from "./factories/implementHere.ts";
 import { registerObjective } from "./factories/objective.ts";
 import { registerObjectiveAuthor } from "./factories/objectiveAuthor.ts";
 import { registerObjectiveDraft } from "./factories/objectiveDraft.ts";
@@ -38,10 +42,12 @@ import {
   readHandoff,
   readPlanRef,
   setMarker,
+  workflowDir,
 } from "./substrate/cache.ts";
 import { loadRegistry, type Registry, stageConsumesPlanRef } from "./substrate/registry.ts";
 import { perkVersion, sharedDir } from "./substrate/resources.ts";
 import { mintRunId } from "./substrate/runId.ts";
+import { captureSessionPointer } from "./substrate/sessionPointers.ts";
 import { registerToolGating } from "./substrate/toolGating.ts";
 import {
   appendWorkflowState,
@@ -55,7 +61,13 @@ import {
 } from "./substrate/workflowState.ts";
 import { isPerkFooterReferenceSelected } from "./surfaces/footerProvider.ts";
 import { report } from "./surfaces/report.ts";
-import { createPerkStatus, installPerkFooter } from "./surfaces/surfaces.ts";
+import {
+  createPerkStatus,
+  installPerkFooter,
+  latestCacheHitRate,
+  registerTranscriptRenderer,
+  workflowStateEntryRenderer,
+} from "./surfaces/surfaces.ts";
 import { registerBtw } from "./vendor/btw/btw.ts";
 import { registerWhimsical } from "./vendor/whimsical/whimsical.ts";
 
@@ -69,7 +81,7 @@ function writeT3Sentinel(
   runMode: string | null,
 ): void {
   try {
-    const dir = join(cwd, ".pi", "workflow");
+    const dir = workflowDir(cwd);
     if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
     writeFileSync(
       join(dir, ".perk-t3.json"),
@@ -168,6 +180,11 @@ export default function (pi: ExtensionAPI) {
   // session_start (reload) could leak the previous handle subscription.
   let footerInstalled = false;
 
+  // Transcript marker for `perk:workflow-state` deltas (audit §2.3): the renderer body lives in
+  // surfaces.ts, this registration is wiring, and the seam carries the typeof feature-detect
+  // (pre-0.80.4 hosts stay inert). One registration covers every workflow-state appender.
+  registerTranscriptRenderer(pi, WORKFLOW_STATE_TYPE, workflowStateEntryRenderer);
+
   pi.on("session_start", async (_event, ctx) => {
     const branchEntries = () => branchOf(ctx);
     const sessionFile = ctx.sessionManager.getSessionFile();
@@ -185,7 +202,9 @@ export default function (pi: ExtensionAPI) {
       cwd: ctx.cwd,
     });
 
-    let resolved: WorkflowState = decision.action === "claim" ? {} : decision.state;
+    // `claim`/`adopt` carry no prior branch state (adopt's is written by its arm below).
+    let resolved: WorkflowState =
+      decision.action === "claim" || decision.action === "adopt" ? {} : decision.state;
     let minted = false;
 
     if (decision.action === "claim") {
@@ -229,6 +248,22 @@ export default function (pi: ExtensionAPI) {
       };
       pi.appendEntry(WORKFLOW_STATE_TYPE, data);
       resolved = data;
+    } else if (decision.action === "adopt") {
+      // An env-inherited run id whose handoff was already consumed by a different session: a
+      // spawned child (contracts §8.2). Mirror the fork arm — derived child identity, isolated
+      // scratch, inherited mode (read-only gating survives) — minus everything that belongs to
+      // the launched session: never re-consume the handoff (its pi_session_id keeps the true
+      // claimer), no `stage` (no stage impersonation / stage-binding injection), and no
+      // implementation/main pointer capture (resolveRunStage stays null for adopt).
+      ensureRunScratch(ctx.cwd, decision.childRunId);
+      const data: WorkflowState = {
+        run_id: decision.childRunId,
+        pi_session_id: currentSessionId ?? undefined,
+        predecessor: decision.parentRunId,
+        mode: decision.mode,
+      };
+      pi.appendEntry(WORKFLOW_STATE_TYPE, data);
+      resolved = data;
     } else if (decision.action === "none") {
       // A warm session with no identity mints its own run_id so
       // per-run state (the session data dir) can key off it. No disk artifacts —
@@ -249,7 +284,28 @@ export default function (pi: ExtensionAPI) {
       }
     }
 
-    // Plan-ref linkage (turn-2b §6, stage-gated): reconcile the cache.plan-ref file into
+    // Reapply the read-only allowlist + stage scoping from the resolved mode/stage — FIRST,
+    // before the plan-ref/stage reconciliation below. `resolved.mode` is final once the
+    // claim/fork/none arms settle (the later blocks only touch `active_plan_ref` / capture
+    // pointers), and ordering the sync ahead of them guarantees no cache read or reconciliation
+    // failure can leave the gate unsynced (defense in depth on top of the total cache readers).
+    // The scope stage is the workflow-state `stage` key (§8.40): claim → the handoff-recorded
+    // stage just appended; keep/none → the branch-LWW stage; fork INHERITS the parent's stage (a
+    // forked implement session is an implement session); adopt NEVER impersonates (subagent
+    // children stay unscoped — their fresh branch carries no stage, so session_tree agrees). A
+    // failed claim leaves `resolved` empty → no stage → unscoped (stage scoping is fail-open).
+    // Fail-closed on the gate: if the sync throws, leave it as-is (a failed sync never opens it).
+    const scopeStage =
+      decision.action === "adopt"
+        ? undefined
+        : (resolved.stage ?? (decision.action === "fork" ? decision.state.stage : undefined));
+    try {
+      gating.syncFromState(resolved.mode, scopeStage);
+    } catch (error) {
+      console.error(`perk: tool-gating sync failed on session_start — ${error}`);
+    }
+
+    // Plan-ref linkage (stage-gated): reconcile the cache.plan-ref file into
     // active_plan_ref — but ONLY when the launched stage *consumes* the ref (its registry
     // `requires`/`reads` list `cache.plan-ref`). That is the worktree binding stages
     // (implement/submit/address/land/learn); the root `worktree: none` stages
@@ -290,12 +346,26 @@ export default function (pi: ExtensionAPI) {
       resolved = { ...resolved, active_plan_ref: linked };
     }
 
-    // Reapply the read-only allowlist from the resolved mode. Fail-closed: if the sync throws,
-    // leave the gate as-is (a failed sync never opens it).
-    try {
-      gating.syncFromState(resolved.mode);
-    } catch (error) {
-      console.error(`perk: tool-gating sync failed on session_start — ${error}`);
+    // Implementation session pointer (contracts.md §8.35): an implement session self-keys its own
+    // session file into the shared main checkout so a later/other session resolves it cross-run.
+    // The headless worker's inner session lands here too (.main); driveStage records the matching
+    // .worker. A forked implement session inherits the parent's launched stage + threads the
+    // inherited parent session id as fork provenance. Best-effort + non-fatal (carrier warns).
+    // First-write-wins (`preserveForeign`): this is the corroborated shadowing defect site — the
+    // claimer's original capture stays authoritative, and any future shadow vector warns loudly
+    // instead of silently corrupting /learn evidence.
+    const implStage =
+      runStage ?? (decision.action === "fork" ? (decision.state.stage ?? null) : null);
+    if (resolved.run_id && implStage === "implement") {
+      captureSessionPointer({
+        cwd: ctx.cwd,
+        runId: resolved.run_id,
+        klass: "implementation",
+        site: "main",
+        sessionFile,
+        parentSessionId: decision.action === "fork" ? (decision.state.pi_session_id ?? null) : null,
+        preserveForeign: true,
+      });
     }
 
     // Soft version-parity drift signal: pi can lazy-install / load a stale `npm:@mgiles/perk`, so the
@@ -327,6 +397,8 @@ export default function (pi: ExtensionAPI) {
         identity: `perk v${version}`,
         status: perkStatus,
         getModelId: () => ctx.model?.id ?? null,
+        getThinkingLevel: () => (ctx.model ? pi.getThinkingLevel() : null),
+        getCacheHitRate: () => latestCacheHitRate(ctx.sessionManager.getEntries()),
         getContext: () => {
           const usage = ctx.getContextUsage();
           return usage ? { percent: usage.percent, contextWindow: usage.contextWindow } : null;
@@ -337,7 +409,7 @@ export default function (pi: ExtensionAPI) {
 
     if (process.env.PERK_SELFCHECK) {
       try {
-        const dir = join(ctx.cwd, ".pi", "workflow");
+        const dir = workflowDir(ctx.cwd);
         if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
         // The gate sentinel (unchanged — those gates parse this line).
         writeFileSync(
@@ -356,9 +428,10 @@ export default function (pi: ExtensionAPI) {
   // Non-negotiable: rebuild on branch navigation too, or state goes stale after /tree (§8.3).
   pi.on("session_tree", async (_event, ctx) => {
     const state = rebuildWorkflowState(branchOf(ctx));
-    // Non-negotiable: re-sync the gate on tree navigation too (mode is per-field LWW). Fail-closed.
+    // Non-negotiable: re-sync the gate + stage scoping on tree navigation too (mode and stage are
+    // per-field LWW — the branch-rebuilt stage is the §8.40 key). Fail-closed on the gate.
     try {
-      gating.syncFromState(state.mode);
+      gating.syncFromState(state.mode, state.stage);
     } catch (error) {
       console.error(`perk: tool-gating sync failed on session_tree — ${error}`);
     }
@@ -367,10 +440,15 @@ export default function (pi: ExtensionAPI) {
     }
   });
 
-  // Warm door: the `plan_save` tool + `/plan-save` command (turn-3). Takes `gating` for D1a:
+  // Warm door: the `plan_save` tool + `/plan-save` command. Takes `gating`:
   // a successful command-path save exits read-only mode (the read-only → read-write boundary).
   registerPlanSave(pi, gating);
 
+  // The `/implement-here` command: the human-only no-save exit from plan mode (§8.23) —
+  // implement the reviewed draft in-session, no issue created. Composes the gate through the
+  // implementHereExit seam; no model tool is registered (machine-unreachable by construction).
+  registerImplementHere(pi, gating);
+
   // The `plan_draft` working-draft file tool. Registered in the factory so it
   // exists before the gate snapshots tools; its name is in READ_ONLY_TOOLS (the structural
   // session-data carve-out), so it survives plan mode.
@@ -384,16 +462,16 @@ export default function (pi: ExtensionAPI) {
   // before the gate snapshots tools; its name is in READ_ONLY_TOOLS so it survives plan mode.
   registerAskUser(pi);
 
-  // Lifecycle gates: the dirty-repo switch/fork guard + the guard-only `/implement` (turn-4b).
+  // Lifecycle gates: the dirty-repo switch/fork guard + the guard-only `/implement`.
   registerLifecycleGates(pi);
 
-  // Warm door: the `submit` tool + `/submit` command (turn-5a).
+  // Warm door: the `submit` tool + `/submit` command.
   registerSubmit(pi);
 
   // The warm `ready` door: the deliberate draft→ready review gate (submit keeps draft).
   registerReady(pi);
 
-  // Warm doors: `land` (turn-5b) merges + sets pending-learn; `learn` clears it (TS-only).
+  // Warm doors: `land` merges + sets pending-learn; `learn` clears it (TS-only).
   registerLand(pi);
   registerLearn(pi);
 
@@ -406,6 +484,19 @@ export default function (pi: ExtensionAPI) {
   // POSTS its review to the PR (the deliberate departure from /address's read-only-child rule).
   registerPrReview(pi);
 
+  // The warm `submit_pr_review` tool: the human-gated curated-posting surface both review
+  // doors ride (contracts §8.4) — neither door registers tools of its own.
+  registerSubmitPrReview(pi);
+
+  // The warm `/pr-review-terminal` door: the terminal review entry — hunk always, no provider
+  // dispatch (the command IS the selection); posting rides `submit_pr_review` above.
+  registerPrReviewTerminal(pi);
+
+  // The warm `/pr-review-browser` door: the browser review entry — plannotator always, opened
+  // in the background (pre-PR it absorbs the since-base local browser review); posting is the
+  // human's own platform-post from the UI, with `submit_pr_review` for request-changes only.
+  registerPrReviewBrowser(pi);
+
   // The read-only CI executor: the `run_ci` tool + `/ci` command + `--allow-project-ci`
   // flag. Runs the project's `[ci]` named checks deterministically and reports (never fixes/loops).
   registerCiExecutor(pi);
@@ -445,11 +536,17 @@ export default function (pi: ExtensionAPI) {
   // The learned-docs plan factory's warm surface: the `/learn-docs` command gathers open
   // perk:learn issues into an inbox (via the `perk learn docs --gather` cold door) and injects the
   // factory guidance so the model authors a docs/learned consolidation plan (no model tool).
-  registerLearnDocs(pi);
+  registerLearnFactoryDoor(pi, DOCS_DOOR);
+
+  // The learn-code plan factory's warm surface: the `/learn-code` command gathers pre-stamped
+  // SHOULD_BE_CODE perk:learn issues into an inbox (via the `perk learn code --gather` cold door)
+  // and injects the factory guidance so the model authors a code-routing plan (no model tool).
+  registerLearnFactoryDoor(pi, CODE_DOOR);
 
   // Warm-door skill-binding delivery: Mechanism A's `before_agent_start` injection of
   // the launched stage's user-originated bindings (+ the stale-context strip). Mechanism B (the
-  // `command:<id>` suffix) is wired into the `/objective-reconcile` + `/learn-docs` guidance.
+  // `command:<id>` suffix) is wired into the `/objective-reconcile` + `/learn-docs` +
+  // `/learn-code` guidance.
   registerBindingDelivery(pi);
 
   // `/perk-selfcheck` — the session-wiring verifier (turned from a liveness ping into a real check

package/extension/substrate/bindingDelivery.ts

@@ -14,8 +14,11 @@
 //
 // 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 nothing on the branch already carries the
-// header (idempotent across turns/reloads; after compaction drops the original it re-delivers).
+// injection carry it, so Mechanism A injects ONLY when neither the branch NOR the submitting
+// turn's prompt already carries the header (idempotent across turns/reloads; after compaction
+// drops the original 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.
 //
 // 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
@@ -26,7 +29,12 @@ import { join } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { loadDefaultBindings, resolveBindings, type SkillBinding } from "./bindings.ts";
 import { loadPerkConfig } from "./config.ts";
-import { type BranchEntry, branchOf, rebuildWorkflowState } from "./workflowState.ts";
+import {
+  type BranchEntry,
+  branchCarries,
+  branchOf,
+  rebuildWorkflowState,
+} from "./workflowState.ts";
 
 /**
  * The cross-plane dedup marker AND render header. MUST stay byte-identical to the Python cold
@@ -58,7 +66,10 @@ export function resolvedBindings(cwd: string): SkillBinding[] {
 
 /**
  * Render the resolved bindings matching `trigger` into a header-joined fragment (or `null` when
- * none match). `nudge` renders a `Follow the \`<skill>\` skill.` pointer; `transclude` inlines
+ * none match). `nudge` renders a `Follow the \`<skill>\` skill (read
+ * \`.agents/skills/<skill>/SKILL.md\`).` pointer — the read path is unconditional, so a skill
+ * hidden from the ambient prompt (`disable-model-invocation: true`) stays reachable; `transclude`
+ * inlines
  * `.agents/skills/<skill>/SKILL.md` (frontmatter stripped), degrading to the nudge pointer with a
  * loud-but-non-fatal warning when the file is absent/unreadable. Pure but for the LBYL file read.
  */
@@ -86,7 +97,10 @@ export function renderBindings(cwd: string, trigger: string): BindingRender {
           `under ${SKILLS_SUBDIR}/${binding.skill}/${SKILL_FILENAME} — the pointer may dangle.`,
       );
     }
-    parts.push(`Follow the \`${binding.skill}\` skill.`);
+    parts.push(
+      `Follow the \`${binding.skill}\` skill ` +
+        `(read \`${SKILLS_SUBDIR}/${binding.skill}/${SKILL_FILENAME}\`).`,
+    );
   }
   const text = parts.length > 0 ? [BINDING_HEADER, ...parts].join("\n\n") : null;
   return { text, warnings };
@@ -116,7 +130,11 @@ function readSkillBody(cwd: string, skill: string): string | null {
   const path = join(cwd, SKILLS_SUBDIR, skill, SKILL_FILENAME);
   if (!existsSync(path)) return null;
   try {
-    return stripFrontmatter(readFileSync(path, "utf8"));
+    // Normalize CRLF/CR before stripping (the miniJinja.ts pattern): Node's readFileSync keeps
+    // `\r\n` where Python's read_text() normalizes, so without this a CRLF checkout would defeat
+    // the `---\n` frontmatter check AND break the cross-plane byte parity pinned by
+    // tests/test_binding_render_parity.py.
+    return stripFrontmatter(readFileSync(path, "utf8").replace(/\r\n?/g, "\n"));
   } catch {
     return null;
   }
@@ -142,7 +160,7 @@ function stripFrontmatter(text: string): string {
  * header is a distinctive literal, so a substring hit means "already delivered on this branch".
  */
 function branchHasHeader(branch: readonly BranchEntry[]): boolean {
-  return branch.some((entry) => JSON.stringify(entry).includes(BINDING_HEADER));
+  return branchCarries(branch, BINDING_HEADER);
 }
 
 /** The launched stage's `stage:<id>` render, or `null` when there is no stage / nothing matches. */
@@ -160,13 +178,17 @@ function activeStageRender(cwd: string, branch: readonly BranchEntry[]): Binding
  */
 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 on the branch already carries BINDING_HEADER (the cold door's initial
-  // prompt or a prior warm inject) — the cold↔warm idempotency guard.
-  pi.on("before_agent_start", async (_event, ctx) => {
+  // but ONLY when no entry on the branch 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
+  // 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).
+  pi.on("before_agent_start", async (event, ctx) => {
     const branch = branchOf(ctx);
     const rendered = activeStageRender(ctx.cwd, branch);
     if (rendered === null || rendered.text === null) return;
     if (branchHasHeader(branch)) return;
+    if (event.prompt.includes(BINDING_HEADER)) return;
     for (const warning of rendered.warnings) console.error(`perk: ${warning}`);
     return {
       message: {

package/extension/substrate/bindings.ts

@@ -12,6 +12,8 @@
 
 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";
 
@@ -74,10 +76,10 @@ export function loadDefaultBindings(): SkillBinding[] {
 }
 
 /**
- * Parse `.pi/perk.toml` `[[bindings]]` rows (string tables) into `SkillBinding`s. Tolerant like
+ * 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.
  */
-export function parseUserBindings(rows: Array<Record<string, string>>): SkillBinding[] {
+export function parseUserBindings(rows: Array<Record<string, TomlScalar>>): SkillBinding[] {
   return rows.map((row) => {
     const trigger = typeof row.trigger === "string" ? row.trigger : "";
     const [kind, targetId] = splitTrigger(trigger);

package/extension/substrate/cache.ts

@@ -1,8 +1,15 @@
-// `.pi/workflow/` cache-tier I/O — the TS twin of perk/state/cache.py (contracts.md §8.1).
+// `.perk/workflow/` cache-tier I/O — the TS twin of perk/state/cache.py (contracts.md §8.1).
 //
 // Both planes read and write the SAME files; the cross-plane contract is the *files*, not a
 // shared module. State-tiering primitives only — no workflow semantics. Imports use no
 // relative paths (only node builtins), so this module loads cleanly under `node --test`.
+//
+// Readers are TOTAL: a corrupt/unreadable file is reported loudly on stderr (`console.error` —
+// the report() seam is intentionally unavailable here, and stderr is headless-safe) and treated
+// as absent (`null`), so a bad cache blob can never crash a caller mid-`session_start` before
+// the read-only gate engages. The Python twins (src/perk/state/cache.py) deliberately keep
+// RAISING `CacheError` (exterior plane, launch-time fail-loud) — the cross-plane contract is
+// the *files*, not error semantics.
 
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
@@ -18,7 +25,26 @@ export interface Handoff {
 }
 
 export function workflowDir(cwd: string): string {
-  return join(cwd, ".pi", "workflow");
+  return join(cwd, ".perk", "workflow");
+}
+
+/**
+ * Read + parse a JSON cache blob, totally: a missing file is a silent `null` (absence is the
+ * normal state); an unreadable/corrupt/wrong-shape file is a LOUD `null` (one stderr line naming
+ * the file kind + path + error) — treated as absent by every caller.
+ */
+function readJsonOrNull<T>(path: string, what: string): T | null {
+  if (!existsSync(path)) return null;
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      throw new Error(`expected a JSON object, got ${JSON.stringify(parsed)}`);
+    }
+    return parsed as T;
+  } catch (error) {
+    console.error(`perk: unreadable ${what} at ${path} — treating as absent (${error})`);
+    return null;
+  }
 }
 
 // --- handoff -----------------------------------------------------------------------------
@@ -28,9 +54,7 @@ export function handoffPath(cwd: string, runId: string): string {
 }
 
 export function readHandoff(cwd: string, runId: string): Handoff | null {
-  const path = handoffPath(cwd, runId);
-  if (!existsSync(path)) return null;
-  return JSON.parse(readFileSync(path, "utf8")) as Handoff;
+  return readJsonOrNull<Handoff>(handoffPath(cwd, runId), "handoff");
 }
 
 /** Mark a handoff consumed (idempotent); a no-op when absent. Keeps the file (audit + GC). */
@@ -113,9 +137,7 @@ export function planRefPath(cwd: string): string {
 }
 
 export function readPlanRef(cwd: string): PlanRef | null {
-  const path = planRefPath(cwd);
-  if (!existsSync(path)) return null;
-  return JSON.parse(readFileSync(path, "utf8")) as PlanRef;
+  return readJsonOrNull<PlanRef>(planRefPath(cwd), "plan-ref");
 }
 
 export function writePlanRef(cwd: string, ref: PlanRef): void {
@@ -137,7 +159,12 @@ export function planBodyPath(cwd: string): string {
 export function readPlanBody(cwd: string): string | null {
   const path = planBodyPath(cwd);
   if (!existsSync(path)) return null;
-  return readFileSync(path, "utf8");
+  try {
+    return readFileSync(path, "utf8");
+  } catch (error) {
+    console.error(`perk: unreadable plan body at ${path} — treating as absent (${error})`);
+    return null;
+  }
 }
 
 // --- markers (existence-only) ------------------------------------------------------------

package/extension/substrate/clipboard.ts

@@ -0,0 +1,81 @@
+// A fail-soft "copy this text to the OS clipboard" seam for the extension interior. Used by the
+// terminal review door's R7 hunk handoff so the human always has the launch command one paste
+// away — belt-and-braces beside the loud print and the terminal auto-launch.
+//
+// Two functions: a pure `resolveClipboardScript` (platform + env → a POSIX `sh` script, or `null`
+// for "don't copy") and a thin `copyToClipboard` runner that stages the text in a temp file and
+// shells the script. Never throws, never notifies — the caller owns all messaging. The
+// `PERK_CLIPBOARD_CMD` env seam: unset → the platform default; empty → disabled (the test seam);
+// non-empty → a custom copier.
+
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { ExecHost } from "./coldDoor.ts";
+
+/**
+ * Resolve the clipboard-copy shell script for `platform` + the `PERK_CLIPBOARD_CMD` override. The
+ * script copies the file named by `$1`; returns `null` for "don't copy".
+ *
+ * - `envCmd === ""` → `null` (the test seam / explicit opt-out);
+ * - `envCmd` non-empty → `<envCmd> < "$1"` (custom override — receives the file path as `$1`);
+ * - `darwin` → `pbcopy < "$1"`;
+ * - `linux`/other POSIX → a `command -v` chain (`wl-copy` → `xclip` → `xsel`), else `exit 127`;
+ * - `win32` → `null` (no POSIX `sh`; the print+launch fallback covers it).
+ */
+export function resolveClipboardScript(
+  platform: string,
+  envCmd: string | undefined,
+): string | null {
+  if (envCmd !== undefined) {
+    if (envCmd === "") return null;
+    return `${envCmd} < "$1"`;
+  }
+  if (platform === "darwin") return `pbcopy < "$1"`;
+  if (platform === "win32") return null;
+  return (
+    'if command -v wl-copy >/dev/null 2>&1; then wl-copy < "$1"; ' +
+    'elif command -v xclip >/dev/null 2>&1; then xclip -selection clipboard < "$1"; ' +
+    'elif command -v xsel >/dev/null 2>&1; then xsel --clipboard --input < "$1"; ' +
+    "else exit 127; fi"
+  );
+}
+
+/**
+ * Copy `text` to the OS clipboard, best-effort. Resolves the script from `process.platform` +
+ * `process.env.PERK_CLIPBOARD_CMD`; a `null` script (win32, or the disabled seam) short-circuits
+ * to `false` without shelling. Otherwise stages `text` in a temp file and runs
+ * `sh -c <script> sh <file>` with a 3s cap (guards a display-less `xclip` hanging). Returns
+ * `true` iff the copier exited 0 and was not killed. Any throw → `false`. Never rejects, never
+ * notifies.
+ */
+export async function copyToClipboard(
+  pi: ExecHost,
+  ctx: { cwd: string; signal?: AbortSignal },
+  text: string,
+): Promise<boolean> {
+  const script = resolveClipboardScript(process.platform, process.env.PERK_CLIPBOARD_CMD);
+  if (script === null) return false;
+  let dir: string | undefined;
+  try {
+    dir = mkdtempSync(join(tmpdir(), "perk-clip-"));
+    const file = join(dir, "clip.txt");
+    writeFileSync(file, text, "utf8");
+    const res = await pi.exec("sh", ["-c", script, "sh", file], {
+      cwd: ctx.cwd,
+      signal: ctx.signal,
+      timeout: 3000,
+    });
+    return res.code === 0 && !res.killed;
+  } catch {
+    return false;
+  } finally {
+    if (dir !== undefined) {
+      try {
+        rmSync(dir, { recursive: true, force: true });
+      } catch {
+        // best-effort cleanup — a leaked temp file is harmless
+      }
+    }
+  }
+}