@mgiles/perk 2.3.0 → 3.1.0

package/extension/index.ts

@@ -4,26 +4,36 @@
 // `session_start` (verified-linkage), rebuild `perk:workflow-state` on `session_start` AND
 // `session_tree` (per-field LWW), and derive a child run_id on fork.
 
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync } from "node:fs";
 import { basename, join } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { registerPlanAdapterPlannotator } from "./adapters/planAdapterPlannotator.ts";
 import { registerPlanAdapterTombell } from "./adapters/planAdapterTombell.ts";
-import { registerTodoAdapterJuicesharp } from "./adapters/todoAdapterJuicesharp.ts";
-import { registerCheckpoints } from "./checkpoints/checkpoints.ts";
 import { registerAddress } from "./doors/address.ts";
-import { registerAskUser } from "./doors/askUser.ts";
+import { registerAnnotationPushTool } from "./doors/annotationPush.ts";
+import { registerAuditWave } from "./doors/auditWaveTools.ts";
 import { registerCiExecutor } from "./doors/ciExecutor.ts";
 import { registerCommitAndCompact } from "./doors/commitCompact.ts";
+import { registerDraftReviewWaveTools } from "./doors/draftReviewWaveTools.ts";
+import { registerDreamWave } from "./doors/dreamWaveTools.ts";
+import { registerHarvestWave } from "./doors/harvestWaveTools.ts";
 import { registerLand } from "./doors/land.ts";
 import { registerLearn } from "./doors/learn.ts";
 import { CODE_DOOR, DOCS_DOOR, registerLearnFactoryDoor } from "./doors/learnFactory.ts";
 import { registerLifecycleGates } from "./doors/lifecycleGates.ts";
+import {
+  openObjectiveReviewSurface,
+  registerObjectiveReviewBrowser,
+} from "./doors/objectiveReviewBrowser.ts";
+import { registerObjectiveStack } from "./doors/objectiveStack.ts";
+import { plannotatorPresent } from "./doors/plannotatorHandoff.ts";
+import { openPlanReviewSurface, registerPlanReviewBrowser } from "./doors/planReviewBrowser.ts";
 import { registerPrReview } from "./doors/prReview.ts";
 import { registerPrReviewBrowser } from "./doors/prReviewBrowser.ts";
 import { registerPrReviewDynamic } from "./doors/prReviewDynamic.ts";
 import { registerPrReviewTerminal } from "./doors/prReviewTerminal.ts";
 import { registerReady } from "./doors/ready.ts";
+import { registerReviewWaveTools } from "./doors/reviewWaveTools.ts";
 import { registerSelfcheck } from "./doors/selfcheck.ts";
 import { registerSubmit } from "./doors/submit.ts";
 import { registerSubmitPrReview } from "./doors/submitPrReview.ts";
@@ -40,8 +50,11 @@ import { registerPlanDraft } from "./factories/planDraft.ts";
 import { registerPlanMode } from "./factories/planMode.ts";
 import { registerPlanReview } from "./factories/planReview.ts";
 import { registerPlanSave } from "./factories/planSave.ts";
+import { createHunkFeedbackReceiver } from "./hunkFeedback/receiver.ts";
+import { createAgentScratchProvisioner, registerAgentScratch } from "./substrate/agentScratch.ts";
 import { registerBindingDelivery } from "./substrate/bindingDelivery.ts";
 import {
+  atomicWriteFileSync,
   ensureRunScratch,
   markHandoffConsumed,
   readHandoff,
@@ -50,7 +63,7 @@ import {
   workflowDir,
 } from "./substrate/cache.ts";
 import { loadRegistry, type Registry, stageConsumesPlanRef } from "./substrate/registry.ts";
-import { perkVersion, sharedDir } from "./substrate/resources.ts";
+import { perkVersion, sharedDir, versionStamp } from "./substrate/resources.ts";
 import { mintRunId } from "./substrate/runId.ts";
 import { captureSessionPointer } from "./substrate/sessionPointers.ts";
 import { registerToolGating } from "./substrate/toolGating.ts";
@@ -70,7 +83,9 @@ import {
   createPerkStatus,
   installPerkFooter,
   latestCacheHitRate,
+  REPORT_DETAIL_TYPE,
   registerTranscriptRenderer,
+  reportDetailEntryRenderer,
   workflowStateEntryRenderer,
 } from "./surfaces/surfaces.ts";
 import { registerBtw } from "./vendor/btw/btw.ts";
@@ -88,7 +103,7 @@ function writeT3Sentinel(
   try {
     const dir = workflowDir(cwd);
     if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-    writeFileSync(
+    atomicWriteFileSync(
       join(dir, ".perk-t3.json"),
       `${JSON.stringify({
         source,
@@ -102,7 +117,6 @@ function writeT3Sentinel(
         pi_session_id: state.pi_session_id ?? null,
         active_plan_ref: state.active_plan_ref ?? null,
       })}\n`,
-      "utf8",
     );
   } catch {
     // never throw from a probe
@@ -116,12 +130,18 @@ export default function (pi: ExtensionAPI) {
   // both session_start AND session_tree below. enter/exit are the surface the gated stages consume.
   const gating = registerToolGating(pi);
 
+  // Run-owned disposable scratch guidance for every eligible write-capable model turn. One
+  // activation-scoped provisioner shares retry/warning suppression with the isolated /btw side
+  // session; no model tool or process-global temp environment is introduced.
+  const agentScratch = createAgentScratchProvisioner();
+  registerAgentScratch(pi, agentScratch);
+
   // Vendored `btw`: a `/btw` human-only side-chat popover backed by an isolated in-memory
   // AgentSession. Takes `gating` for the gate-mirror — its side-session toolset + cache key follow
   // perk's read-only gate (`sideSessionTools`), so the isolated session never bypasses the read-only
   // guarantee. Its `ctx.ui.custom` overlay is the ONE sanctioned charter exception (§6 D6): human-
   // invoked only, `hasUI`-gated, no model tool, not a stage/door — never machine-reachable.
-  registerBtw(pi, gating);
+  registerBtw(pi, gating, agentScratch);
 
   // Vendored `whimsical`: flavors pi's default working-message label with a random phrase per
   // turn, via the headless-no-op `setWorkingMessage` surfaces seam. Always on, no config toggle.
@@ -150,8 +170,15 @@ export default function (pi: ExtensionAPI) {
   // `plan_review`, perk's UNIVERSAL review door: plannotator-selected → the event-bus
   // bridge; ANY other selection → the first-party in-TUI editor review. It takes `gating` only to
   // COMPOSE the approvalSave seam on an APPROVED review (auto-save → D1a gate exit) — Invariant 1
-  // holds: the door composes the gate through the seam, never owns it.
-  registerPlanReview(pi, gating);
+  // holds: the door composes the gate through the seam, never owns it. The injected wave-launch
+  // deps power the plannotator launch chooser (§8.23): the presence probe + the two door open
+  // cores are composed HERE so planReview.ts imports nothing from door modules (the value-import
+  // cycle break — planReviewBrowser.ts already value-imports planReview.ts).
+  registerPlanReview(pi, gating, {
+    present: () => plannotatorPresent(pi),
+    plan: (ctx, opts) => openPlanReviewSurface(pi, ctx, gating, opts),
+    objective: (ctx, opts) => openObjectiveReviewSurface(pi, ctx, gating, opts),
+  });
 
   // Objective-author context injection (the objective mirror of plan mode's authoring
   // half). Keyed off (read-only gate AND stage === objective-author); planMode defers to it.
@@ -179,27 +206,33 @@ export default function (pi: ExtensionAPI) {
   }
   const registryOk = registryStages > 0;
 
-  // The composed `perk` status handle (charter D2): one slot, ordered objective →
-  // checkpoints segments. Created once here (no hidden module state) and threaded into the two
-  // segment publishers below; the footer reads it back via get/subscribe.
+  // The single-value `perk` status handle (charter D2): one slot carrying the objective
+  // segment. Created once here (no hidden module state) and threaded into the objective
+  // publisher below; the footer reads it back via get/subscribe.
   const perkStatus = createPerkStatus();
 
-  // Install the perk-owned footer once per session (charter D2/D7). Once-only: pi's
-  // dispose contract for a REPLACED footer factory is unverified, so re-installing on every
-  // 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.
+  // The generic full report-detail entry and the `perk:workflow-state` transition marker. Renderer
+  // bodies live in surfaces.ts; registration is wiring through the pre-0.80.4-safe seam. The report
+  // family is appended by command-attached sinks; one workflow registration covers every appender.
+  registerTranscriptRenderer(pi, REPORT_DETAIL_TYPE, reportDetailEntryRenderer);
   registerTranscriptRenderer(pi, WORKFLOW_STATE_TYPE, workflowStateEntryRenderer);
 
+  // The hunk watch feedback receiver controller (contracts §8.58) — factory-scoped (no module
+  // globals). Synced from session_start/session_tree below; closed on session_shutdown so the
+  // consumer lease releases with the session. A stale /reload predecessor instance is retired
+  // by the lease fencing (fresh token per same-identity reacquire + verify-before-inject).
+  const feedbackReceiver = createHunkFeedbackReceiver(pi);
+  pi.on("session_shutdown", async () => {
+    feedbackReceiver.close();
+  });
+
   pi.on("session_start", async (_event, ctx) => {
     const branchEntries = () => branchOf(ctx);
     const sessionFile = ctx.sessionManager.getSessionFile();
     const currentSessionId = sessionFile ? basename(sessionFile) : null;
 
-    // Headless-safe linkage failure: loud (notify if UI + stderr), non-fatal, leaves unclaimed.
+    // Terminal-safe linkage failure: managed headline when headful, complete stderr when headless
+    // (plus the explicit RPC mirror); non-fatal and leaves the run unclaimed.
     const reportError = (message: string) => {
       report(ctx, "workflow-state linkage error", "error", message, { alsoLog: true });
     };
@@ -211,6 +244,11 @@ export default function (pi: ExtensionAPI) {
       cwd: ctx.cwd,
     });
 
+    // The session-audit exact-vintage stamp (§8.3), recorded by every run-identity arm below
+    // (claim/fork/adopt/mint); undefined on the perkVersion() failure sentinel, which drops the
+    // key on serialize and leaves the session on the timestamp-estimate arm.
+    const stamp = versionStamp(version);
+
     // `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;
@@ -226,6 +264,7 @@ export default function (pi: ExtensionAPI) {
           run_id: decision.runId,
           pi_session_id: currentSessionId ?? undefined,
           mode: handoff.mode,
+          perk_version: stamp,
           // Record the launched stage so the interior can tell e.g. objective-author from plan
           // (both are read-only) and inject the right authoring context (planMode vs objectiveAuthor).
           stage: handoff.stage,
@@ -247,13 +286,26 @@ export default function (pi: ExtensionAPI) {
         }
       }
     } else if (decision.action === "fork") {
-      // Inherited a run_id from a different session file → isolate the child's scratch.
-      ensureRunScratch(ctx.cwd, decision.childRunId);
+      // Inherited a run_id from a different session file → isolate the child's scratch. A static
+      // redirect or filesystem failure is loud but does not prevent the derived workflow identity
+      // from settling; later eligible turns retry through the agent-scratch resolver.
+      try {
+        ensureRunScratch(ctx.cwd, decision.childRunId);
+      } catch (error) {
+        report(
+          ctx,
+          "run scratch",
+          "warning",
+          `could not create fork run root for ${decision.childRunId}: ${String(error)}`,
+          { alsoLog: true },
+        );
+      }
       const data: WorkflowState = {
         run_id: decision.childRunId,
         pi_session_id: currentSessionId ?? undefined,
         predecessor: decision.parentRunId,
         mode: decision.state.mode,
+        perk_version: stamp,
       };
       pi.appendEntry(WORKFLOW_STATE_TYPE, data);
       resolved = data;
@@ -264,12 +316,23 @@ export default function (pi: ExtensionAPI) {
       // 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);
+      try {
+        ensureRunScratch(ctx.cwd, decision.childRunId);
+      } catch (error) {
+        report(
+          ctx,
+          "run scratch",
+          "warning",
+          `could not create adopted run root for ${decision.childRunId}: ${String(error)}`,
+          { alsoLog: true },
+        );
+      }
       const data: WorkflowState = {
         run_id: decision.childRunId,
         pi_session_id: currentSessionId ?? undefined,
         predecessor: decision.parentRunId,
         mode: decision.mode,
+        perk_version: stamp,
       };
       pi.appendEntry(WORKFLOW_STATE_TYPE, data);
       resolved = data;
@@ -279,7 +342,11 @@ export default function (pi: ExtensionAPI) {
       // dirs are the accessor's job; provenance is recorded separately. A failed cold claim above never
       // falls here (claim stays a loud unclaimed error).
       const runId = mintRunId();
-      const data: WorkflowState = { run_id: runId, pi_session_id: currentSessionId ?? undefined };
+      const data: WorkflowState = {
+        run_id: runId,
+        pi_session_id: currentSessionId ?? undefined,
+        perk_version: stamp,
+      };
       const okAppend = appendWorkflowState(pi, ctx, {
         data,
         field: "run_id",
@@ -377,6 +444,20 @@ export default function (pi: ExtensionAPI) {
       });
     }
 
+    // The hunk watch feedback receiver (§8.58): sync strictly AFTER the run-identity claim and
+    // the plan-ref reconciliation above, so an unclaimed or mislinked session never touches the
+    // outbox. Eligibility (interactive TUI + implement stage + non-adopted + settled identity +
+    // plan-ref match against one fresh cache read) is evaluated inside sync; every ineligible
+    // shape closes any open inbox. Never throws (the controller contains its own failures).
+    feedbackReceiver.sync(ctx, {
+      stage: implStage,
+      adopted: decision.action === "adopt",
+      runId: resolved.run_id ?? null,
+      piSessionId: currentSessionId,
+      activePlanRef: resolved.active_plan_ref ?? null,
+      mode: ctx.mode ?? null,
+    });
+
     // Soft version-parity drift signal: pi can lazy-install / load a stale `npm:@mgiles/perk`, so the
     // extension actually running may differ from the `perk` CLI that launched it. The local launch
     // seam injects PERK_CLI_VERSION; compare it against this extension's own `perkVersion()`. Soft +
@@ -397,11 +478,16 @@ export default function (pi: ExtensionAPI) {
     // Charter D7: perk identity is standing footer state, not a transition — the
     // `v<version> loaded` toast (and its headless stderr mirror) is retired. D5 is rescinded:
     // perk keeps pi's default working indicator (no setWorkingIndicator call anywhere).
+    // Install on EVERY headful session_start: pi ≥ 0.84's `setExtensionFooter` explicitly
+    // disposes a replaced footer factory (verified at 0.84.1), and `resetExtensionUI` restores
+    // the built-in footer on /reload and before session replacement — both paths also re-run
+    // this extension factory, so repeated installs leak nothing and each install's deps
+    // closures capture the current event's ctx.
     // Footer-seam install-site vacating: under a foreign `[providers] footer` selection perk does
     // NOT install its own footer, leaving the foreign footer (`pi-powerline-footer` / `pi-bar`) as
-    // the sole footer surface. perk's objective/checkpoints progress still reaches it via the
-    // composed `perk` setStatus slot. Fail-safe: any config-read error resolves to install.
-    if (ctx.hasUI && !footerInstalled && isPerkFooterReferenceSelected(ctx.cwd)) {
+    // the sole footer surface. perk's objective progress still reaches it via the
+    // single-value `perk` setStatus slot. Fail-safe: any config-read error resolves to install.
+    if (ctx.hasUI && isPerkFooterReferenceSelected(ctx.cwd)) {
       installPerkFooter(ctx, {
         identity: `perk v${version}`,
         status: perkStatus,
@@ -413,7 +499,6 @@ export default function (pi: ExtensionAPI) {
           return usage ? { percent: usage.percent, contextWindow: usage.contextWindow } : null;
         },
       });
-      footerInstalled = true;
     }
 
     if (process.env.PERK_SELFCHECK) {
@@ -421,7 +506,7 @@ export default function (pi: ExtensionAPI) {
         const dir = workflowDir(ctx.cwd);
         if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
         // The gate sentinel (unchanged — those gates parse this line).
-        writeFileSync(
+        atomicWriteFileSync(
           join(dir, ".perk-loaded"),
           `perk ${version} loaded; shared=${sharedOk ? "ok" : "miss"}; ` +
             `registry=${registryOk ? "ok" : "miss"} stages=${registryStages}; hasUI=${ctx.hasUI}\n`,
@@ -444,6 +529,17 @@ export default function (pi: ExtensionAPI) {
     } catch (error) {
       console.error(`perk: tool-gating sync failed on session_tree — ${error}`);
     }
+    // Re-sync the feedback receiver from the LWW-rebuilt state (§8.58). `adopted: false` is
+    // right here: an env-adopted child's fresh branch carries no stage, so the stage gate
+    // alone keeps it inert on tree navigation.
+    feedbackReceiver.sync(ctx, {
+      stage: state.stage ?? null,
+      adopted: false,
+      runId: state.run_id ?? null,
+      piSessionId: state.pi_session_id ?? null,
+      activePlanRef: state.active_plan_ref ?? null,
+      mode: ctx.mode ?? null,
+    });
     if (process.env.PERK_SELFCHECK) {
       writeT3Sentinel(ctx.cwd, "tree", state, ctx.mode ?? null);
     }
@@ -469,11 +565,6 @@ export default function (pi: ExtensionAPI) {
   // The `gist_draft` working-gist file tool (the third draft carve-out).
   registerGistDraft(pi);
 
-  // The universal `ask_user_question` tool: lets a model interactively ask the human a
-  // clarifying question (free-text or multiple-choice). Registered in the factory so it exists
-  // 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`.
   registerLifecycleGates(pi);
 
@@ -487,9 +578,15 @@ export default function (pi: ExtensionAPI) {
   registerLand(pi);
   registerLearn(pi);
 
-  // The warm `/address` review loop: the `resolve_review_threads` tool + `/address`
+  // The warm stacked-delivery surface (§8.51): `/objective-stack` (read) +
+  // `/objective-sync`/`/objective-recover` (drives) + the four typed stack tools. Takes
+  // `gating` for the driving commands' gate-on soft refusal (stack sync/recovery mutates
+  // published branches; the stack tools never join READ_ONLY_TOOLS).
+  registerObjectiveStack(pi, gating);
+
+  // The warm `/address` review loop: the submit-then-resolve `finalize_address` tool + `/address`
   // command. Classify-then-act (the verbose feedback fetch + classification runs in an isolated
-  // spawned child; the parent fixes actionable items and batch-resolves the threads).
+  // spawned child; the parent fixes actionable items and finalizes the committed repairs).
   registerAddress(pi);
 
   // The warm `/pr-review` door: automated code review in a FRESH, isolated subagent that
@@ -506,6 +603,24 @@ export default function (pi: ExtensionAPI) {
   // doors ride (contracts §8.4) — neither door registers tools of its own.
   registerSubmitPrReview(pi);
 
+  // The flow-scoped review-wave pair (`start_review_wave`/`collect_review_wave`) both human
+  // review doors drive: non-blocking adversarial-review launch + the typed collect, flow-scoped
+  // via the session's pending-wave guard.
+  registerReviewWaveTools(pi);
+  registerAuditWave(pi);
+  registerHarvestWave(pi);
+  registerDreamWave(pi);
+
+  // The flow-scoped draft-review-wave pair (`start_draft_review_wave`/
+  // `collect_draft_review_wave`) the draft-review door drives: non-blocking draft-review
+  // launch over the door-primed context + the typed collect.
+  registerDraftReviewWaveTools(pi);
+
+  // The door-primed browser annotation tool (`push_annotations`): the browser door primes the
+  // surface handle on open and clears it on settle/degrade — the tool refuses outside a
+  // door-opened flow.
+  registerAnnotationPushTool(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);
@@ -515,34 +630,31 @@ export default function (pi: ExtensionAPI) {
   // human's own platform-post from the UI, with `submit_pr_review` for request-changes only.
   registerPrReviewBrowser(pi);
 
+  // The warm `/plan-review-browser` door: the summonable streaming draft review — the
+  // plannotator plan-review browser on the working plan draft, draft reviewers streaming
+  // phrase-anchored findings in; APPROVE auto-saves via the approvalSave seam, DENY returns a
+  // model-mediated revision round.
+  registerPlanReviewBrowser(pi, gating);
+
+  // The warm `/objective-review-browser` door: the summonable streaming objective-draft review
+  // — the plannotator plan-review browser on the RENDERED working objective draft, draft
+  // reviewers streaming phrase-anchored findings in; APPROVE auto-saves via the
+  // objectiveApprovalSave seam, Direct Edits = a model-mediated revise round (never auto-saved).
+  registerObjectiveReviewBrowser(pi, gating);
+
   // 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);
 
-  // perk-owned checkpoints: seed from the plan body's `## Steps`, advance on `[DONE:n]`.
-  // Inert when no step list is present (perk plans are prose). Own `session_start`/`session_tree`/
-  // `turn_end` handlers (coexist with the others; pi.on supports multiple handlers per event).
-  // Todo-seam deferral: perk is the reference todo provider (`perk-checkpoints`); these
-  // runtime surfaces step aside when a foreign `[providers] todo` is selected (the todo-seam mirror
-  // of planMode's plan-seam deferral) — silent on the event handlers, announced on `/checkpoints`.
-  registerCheckpoints(pi, perkStatus);
-
-  // The FIRST 3rd-party todo adapter (the todo-seam mirror of registerPlanAdapterTombell).
-  // Injection-only: inert unless `[providers] todo = "juicesharp-todo"` is selected AND the session
-  // is an active workflow. It carries perk's implement-progress discipline onto `@juicesharp/rpiv-
-  // todo`'s checklist overlay (perk's own checkpoints deferred). No `gating` argument —
-  // the shim NEVER arbitrates tools (Invariant 1); no registration-time vacating (no command-name
-  // collision on the todo seam, unlike the plan seam); never writes `perk:checkpoint`.
-  registerTodoAdapterJuicesharp(pi);
-
   // The objective substrate: `/objective` set/clear, budget accounting, threshold
   // compaction, all keyed off the now-live `active_objective`. Inert when no objective is active.
   // (The deterministic objective mechanics live in the Python plane: `perk objective …`.)
   registerObjective(pi, perkStatus);
 
-  // The warm `/commit-and-compact` utility door: drive a commit of the work so far, then
-  // compact the session once HEAD has actually advanced (clean/read-only trees compact
-  // immediately; no commit → compaction skipped, loudly). Human-only — no tool twin.
+  // The warm `/commit-and-compact` utility door: drive a commit of the work so far, compact once
+  // a successful outcome is known, then completion-gate an automatic evidence-first continuation
+  // (clean/read-only trees compact immediately; no commit → no compaction or continuation).
+  // Human-only — no tool twin.
   registerCommitAndCompact(pi, gating);
 
   // The warm `objective_save` door: the `objective_save` tool + `/objective-save` command

package/extension/substrate/agentScratch.ts

@@ -0,0 +1,171 @@
+// Run-owned agent scratch provisioning and hidden model guidance (contracts.md §8.1).
+//
+// This module is guidance, not enforcement: it registers no tool and changes no process-global
+// temp environment. Eligible write-capable model turns receive the repository-relative current-run
+// 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.
+
+import { relative, sep } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+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. */
+  path: string;
+  marker: string;
+  content: string;
+}
+
+export type AgentScratchContext = SessionDataCtx & ReportTarget;
+
+/** Render the exact run-aware hidden block; provisioning stays in the resolver below. */
+export function renderAgentScratchBlock(cwd: string, runId: string): AgentScratchBlock {
+  const path = relative(cwd, agentScratchDir(cwd, runId)).split(sep).join("/");
+  const marker = `[PERK AGENT SCRATCH run=${runId} path=${path}]`;
+  const content = [
+    marker,
+    `Put disposable command/model intermediate files for this run in \`${path}/\` instead of shared \`/tmp\`.`,
+    "Use descriptive, non-colliding names. These files are non-authoritative: re-read canonical repository or backend sources before making durable decisions.",
+  ].join("\n");
+  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;
+}
+
+/**
+ * Build one extension-activation-scoped resolver. Failures warn once per run but are retried on
+ * every call; one success clears suppression so a later regression is reported again.
+ */
+export function createAgentScratchProvisioner(
+  deps: {
+    ensure?: typeof ensureAgentScratch;
+    warn?: (ctx: AgentScratchContext, runId: string, error: unknown) => void;
+  } = {},
+): AgentScratchProvisioner {
+  const ensure = deps.ensure ?? ensureAgentScratch;
+  const warn =
+    deps.warn ??
+    ((ctx: AgentScratchContext, runId: string, error: unknown) => {
+      report(
+        ctx,
+        "agent scratch",
+        "warning",
+        `could not provision scratch for run ${runId}: ${String(error)}`,
+        { alsoLog: true },
+      );
+    });
+  const suppressedRuns = new Set<string>();
+
+  return {
+    resolve(ctx): AgentScratchBlock | null {
+      const runId = activeSessionRunId(ctx);
+      if (runId === null) return null;
+      try {
+        ensure(ctx.cwd, runId);
+      } catch (error) {
+        if (!suppressedRuns.has(runId)) {
+          suppressedRuns.add(runId);
+          warn(ctx, runId, error);
+        }
+        return null;
+      }
+      suppressedRuns.delete(runId);
+      return renderAgentScratchBlock(ctx.cwd, runId);
+    },
+  };
+}
+
+/** 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)),
+  );
+}
+
+/** Register eligible-turn delivery and direct scratch-custom context hygiene. */
+export function registerAgentScratch(
+  pi: ExtensionAPI,
+  provisioner: AgentScratchProvisioner = createAgentScratchProvisioner(),
+): void {
+  pi.on("before_agent_start", async (_event, ctx) => {
+    if (!isAgentScratchEligible(ctx)) return;
+
+    // Provision before dedup: an externally deleted directory is repaired even while the live
+    // branch still carries this run's exact guidance block.
+    const block = provisioner.resolve(ctx);
+    if (block === null) return;
+    if (branchHasBlock(branchOf(ctx), block)) return;
+    return {
+      message: {
+        customType: AGENT_SCRATCH_CONTEXT_TYPE,
+        content: block.content,
+        display: false,
+      },
+    };
+  });
+
+  pi.on("context", async (event, ctx) => {
+    const eligible = isAgentScratchEligible(ctx);
+    const block = eligible ? provisioner.resolve(ctx) : null;
+    let keptCurrent = false;
+    return {
+      messages: event.messages.filter((message) => {
+        const candidate = message as { customType?: string; content?: unknown };
+        if (candidate.customType !== AGENT_SCRATCH_CONTEXT_TYPE) return true;
+        if (block === null || candidate.content !== block.content || keptCurrent) return false;
+        keptCurrent = true;
+        return true;
+      }),
+    };
+  });
+}

package/extension/substrate/bindingDelivery.ts

@@ -14,9 +14,10 @@
 //
 // 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 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
+// 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.
 //
@@ -30,6 +31,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { loadDefaultBindings, resolveBindings, type SkillBinding } from "./bindings.ts";
 import { loadPerkConfig } from "./config.ts";
 import {
+  activeContextWindow,
   type BranchEntry,
   branchCarries,
   branchOf,
@@ -154,13 +156,9 @@ function stripFrontmatter(text: string): string {
   return text; // no closing delimiter — leave the text unchanged
 }
 
-/**
- * Whether anything on the branch already carries `BINDING_HEADER` — the cold launch's initial
- * prompt OR a prior warm injection. Serializing each entry is the robust, shape-agnostic scan: the
- * header is a distinctive literal, so a substring hit means "already delivered on this branch".
- */
+/** Whether a cold prompt or warm injection still active in model context carries the marker. */
 function branchHasHeader(branch: readonly BranchEntry[]): boolean {
-  return branchCarries(branch, BINDING_HEADER);
+  return branchCarries(activeContextWindow(branch), BINDING_HEADER);
 }
 
 /** The launched stage's `stage:<id>` render, or `null` when there is no stage / nothing matches. */
@@ -178,8 +176,8 @@ 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 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 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
   // 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).