@mgiles/perk 3.0.0 → 3.2.0

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).

package/extension/substrate/cache.ts

@@ -23,15 +23,18 @@
 
 import { randomBytes } from "node:crypto";
 import {
+  chmodSync,
   existsSync,
+  lstatSync,
   mkdirSync,
   readdirSync,
   readFileSync,
+  realpathSync,
   renameSync,
   rmSync,
   writeFileSync,
 } from "node:fs";
-import { join } from "node:path";
+import { join, relative } from "node:path";
 
 /**
  * Atomically replace `path` with `content` (the interior atomic-write seam).
@@ -129,6 +132,11 @@ export function runScratchDir(cwd: string, runId: string): string {
   return join(scratchDir(cwd), "runs", runId);
 }
 
+/** The run-owned directory for disposable, non-authoritative model intermediates. */
+export function agentScratchDir(cwd: string, runId: string): string {
+  return join(runScratchDir(cwd, runId), "agent");
+}
+
 /**
  * The session data dir for a run — a dedicated `data/` subdir so
  * run-scoped session artifacts never overlap perk machine records (dispatch.json,
@@ -139,9 +147,91 @@ export function sessionDataDir(cwd: string, runId: string): string {
   return join(runScratchDir(cwd, runId), "data");
 }
 
+/** 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")
+  ) {
+    throw new Error(`refusing unsafe run id ${JSON.stringify(runId)}`);
+  }
+}
+
+/**
+ * Ensure one checkout-owned path component is a real directory, never a static redirect.
+ * Check-before-create races against a same-UID process are intentionally out of scope.
+ */
+function ensureUnredirectedDirectory(
+  path: string,
+  opts: { createMode: number; rejectGroupWorldWrite: boolean },
+): void {
+  let stat: ReturnType<typeof lstatSync>;
+  try {
+    stat = lstatSync(path);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    mkdirSync(path, { mode: opts.createMode });
+    stat = lstatSync(path);
+  }
+  if (stat.isSymbolicLink()) throw new Error(`refusing a symlinked run-scratch path: ${path}`);
+  if (!stat.isDirectory()) throw new Error(`refusing a non-directory run-scratch path: ${path}`);
+  if (opts.rejectGroupWorldWrite && (stat.mode & 0o022) !== 0) {
+    throw new Error(`refusing a group/world-writable run-scratch path: ${path}`);
+  }
+}
+
+/**
+ * Establish a run root beneath this checkout without following redirected checkout content.
+ * Symlinks above `cwd` remain legal; every existing component from `.perk` through the run root
+ * must be a real directory without group/world write permission, and missing components are
+ * created no broader than 0755 even under a permissive umask. Run-id validation happens before
+ * the first filesystem write.
+ */
 export function ensureRunScratch(cwd: string, runId: string): string {
+  assertSafeRunId(runId);
   const dir = runScratchDir(cwd, runId);
-  mkdirSync(dir, { recursive: true });
+  const components = [
+    join(cwd, ".perk"),
+    join(cwd, ".perk", "workflow"),
+    scratchDir(cwd),
+    join(scratchDir(cwd), "runs"),
+    dir,
+  ];
+  for (const component of components) {
+    ensureUnredirectedDirectory(component, {
+      createMode: 0o755,
+      rejectGroupWorldWrite: true,
+    });
+  }
+
+  const expected = join(realpathSync(cwd), relative(cwd, dir));
+  if (realpathSync(dir) !== expected) {
+    throw new Error(`refusing a redirected run-scratch dir: ${dir}`);
+  }
+  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
+ * as the same user.
+ */
+export function ensureAgentScratch(cwd: string, runId: string): string {
+  const runDir = ensureRunScratch(cwd, runId);
+  const dir = agentScratchDir(cwd, runId);
+  ensureUnredirectedDirectory(dir, {
+    createMode: 0o700,
+    rejectGroupWorldWrite: false,
+  });
+  const expected = join(realpathSync(runDir), "agent");
+  if (realpathSync(dir) !== expected) {
+    throw new Error(`refusing a redirected agent scratch dir: ${dir}`);
+  }
+  chmodSync(dir, 0o700);
   return dir;
 }
 

package/extension/substrate/command.ts

@@ -1,14 +1,16 @@
 // The single chokepoint that gives every perk command a uniform, immediate "running…"
 // acknowledgement at entry. pi does not echo the invoked command and handlers only report() at the
 // end, so without this a command's async work (cold-door subprocess calls, GitHub round-trips) is
-// dead air between Enter and completion. registerPerkCommand wraps the handler to emit one transient
-// entry toast through the headless-safe report() seam (no cleanup state, headless-fail-safe for
-// free) before awaiting the original handler. The toast fires synchronously before the first await,
-// so it lands before any cold-door work, sendUserMessage drive, or gate transition; the wrapper does
-// not try/catch, so errors propagate exactly as before.
+// dead air between Enter and completion. registerPerkCommand attaches the command's durable report-
+// detail sink to the exact context object, then emits one transient entry toast through report()
+// before awaiting the original handler. The toast fires synchronously before the first await, so it
+// lands before any cold-door work, sendUserMessage drive, or gate transition; the wrapper does not
+// try/catch, so errors propagate exactly as before. The WeakMap attachment deliberately survives the
+// handler for background work launched with the same context.
 
 import type { ExtensionAPI, RegisteredCommand } from "@earendil-works/pi-coding-agent";
-import { report } from "../surfaces/report.ts";
+import { attachReportDetailSink, report } from "../surfaces/report.ts";
+import { createReportDetailSink } from "../surfaces/surfaces.ts";
 
 export function registerPerkCommand(
   pi: ExtensionAPI,
@@ -18,6 +20,7 @@ export function registerPerkCommand(
   pi.registerCommand(name, {
     ...options,
     handler: async (args, ctx) => {
+      attachReportDetailSink(ctx, createReportDetailSink(pi));
       report(ctx, name, "info", "running…");
       await options.handler(args, ctx);
     },

package/extension/substrate/config.ts

@@ -49,7 +49,8 @@ export interface PerkConfig {
    * The agent-keyed `[models.subagents]` table: a per-agent model override for each perk-owned
    * project agent (`pr-reviewer`, `review-classifier`, `objective-explorer`, `conflict-resolver`,
    * `learn-analyst`, `adversarial-reviewer`, `review-angle-selector`, `draft-reviewer`,
-   * `harvest-analyst` — consumed by `run_harvest_wave` at execute time — and the
+   * `harvest-analyst` — consumed by `run_harvest_wave` at execute time — `dream-analyst` and
+   * `dream-reducer` — consumed by `run_dream_wave` at execute time — and the
    * dev-only `session-auditor`, whose def is repo-local to perk's own repository
    * (`.pi/agents/perk-dev/session-auditor.md`, never delivered by `perk init`), so the key is
    * dormant in consumer repos). Each configured
@@ -57,8 +58,10 @@ export interface PerkConfig {
    * workflowScript call — a default flowing onto every lane, single-child runs included (as
    * /pr-review does); when a key is absent the agent's frontmatter `model` (in
    * `.pi/agents/perk/<name>.md`; the session-auditor's in its repo-local def) is the default.
-   * (`subagents.agentOverrides` does NOT reach project agents — `pi-subagents`'
-   * `applyBuiltinOverrides` applies only to builtins — so this inline injection is the mechanism.)
+   * (Since pi-subagents 0.52, `subagents.agentOverrides` also reaches custom/project agents —
+   * but only as a frontmatter-sensitive fill that never displaces a field the def's own
+   * frontmatter sets; every perk def pins `model:` in frontmatter, so this inline workflow-level
+   * injection remains the mechanism.)
    * A value may carry a `:thinking` suffix (`"anthropic/claude-sonnet-4-5:high"`) or be the
    * `"inherit"` sentinel (child inherits the parent session's model) — both resolved by
    * pi-subagents on the injected value (the last-colon segment counts as thinking only when it
@@ -75,6 +78,8 @@ export interface PerkConfig {
     "review-angle-selector"?: string;
     "draft-reviewer"?: string;
     "harvest-analyst"?: string;
+    "dream-analyst"?: string;
+    "dream-reducer"?: string;
     "session-auditor"?: string;
   };
   /**
@@ -326,6 +331,8 @@ const SUBAGENT_KEYS = [
   "review-angle-selector",
   "draft-reviewer",
   "harvest-analyst",
+  "dream-analyst",
+  "dream-reducer",
   // Dev-only: the perk-dev session-audit judgment wave's auditor (dormant in consumer repos).
   "session-auditor",
 ] as const;

package/extension/substrate/git.ts

@@ -3,6 +3,8 @@
 // Node builtins only (so it loads cleanly under `node --test`); shells `git` via `execFileSync`,
 // never with a shell. Fail-open by design: every failure degrades to the caller's `cwd` (or null
 // where stated) rather than throwing — the carriers that use this must never wedge a session.
+// The ONE deliberate fail-closed composition is `revalidationBracket` (documented there): a
+// snapshot proof must treat an unprovable probe as drift, never as "unchanged".
 
 import { execFileSync } from "node:child_process";
 import { isAbsolute, resolve } from "node:path";
@@ -115,9 +117,90 @@ export function worktreeDirty(cwd: string): boolean | null {
 }
 
 /**
- * The `git log --oneline <fromSha>..HEAD` listing of commits made since `fromSha` — or every
+ * Whether the index carries `assume-unchanged` (a lowercase `git ls-files -v` tag) or
+ * `skip-worktree` (`S`/`s` — sparse checkouts) entries. Either bit hides worktree edits from
+ * `git status --porcelain`, so a status-based cleanliness proof over a flagged index is not a
+ * proof. **Fail-open to null** on any failure (not a repo, git missing) — callers must NOT
+ * conflate null with "no flags". Own `execFileSync` rather than the `git()` helper: `git()`
+ * conflates empty output (an empty index — meaningful here) with failure.
+ */
+export function indexHidesChanges(cwd: string): boolean | null {
+  try {
+    const out = execFileSync("git", ["ls-files", "-v"], {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    return out.split("\n").some((line) => {
+      const tag = line[0];
+      return tag !== undefined && (tag === "S" || (tag >= "a" && tag <= "z"));
+    });
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The dream-snapshot revalidation bracket (contracts.md §8.65) — the module's ONE deliberately
+ * **fail-closed** composition (a documented exception to the fail-open charter above): it exists
+ * to PROVE the repository still matches a stamped snapshot, so an unprovable probe must read as
+ * drift, never as "unchanged". The claim is END-STATE equality only — HEAD unchanged, the
+ * working tree clean, and no assume-unchanged/skip-worktree index flags (which would hide edits
+ * from the status probe) at the moment of the check — never mid-window byte immutability (a
+ * transient modify-and-restore inside the window is invisible by design; §8.65's accepted
+ * residuals). `probes` defaults to the real `headSha`/`worktreeDirty`/`indexHidesChanges` and
+ * exists so tests can pin each fail-closed arm independently (from a non-repo fixture the HEAD
+ * arm returns first, making the later null arms reachable only through the seam).
+ */
+export function revalidationBracket(
+  cwd: string,
+  expectedSha: string,
+  probes?: {
+    head?: (cwd: string) => string | null;
+    dirty?: (cwd: string) => boolean | null;
+    flags?: (cwd: string) => boolean | null;
+  },
+): { ok: boolean; detail: string | null } {
+  const head = probes?.head ?? headSha;
+  const dirty = probes?.dirty ?? worktreeDirty;
+  const flags = probes?.flags ?? indexHidesChanges;
+  const actual = head(cwd);
+  if (actual === null) {
+    return {
+      ok: false,
+      detail: "HEAD could not be resolved — cannot prove the snapshot is unchanged",
+    };
+  }
+  if (actual !== expectedSha) {
+    return { ok: false, detail: `HEAD moved from ${expectedSha} to ${actual}` };
+  }
+  const isDirty = dirty(cwd);
+  if (isDirty === null) {
+    return { ok: false, detail: "working-tree cleanliness could not be verified" };
+  }
+  if (isDirty) {
+    return { ok: false, detail: "the working tree is no longer clean" };
+  }
+  const hidden = flags(cwd);
+  if (hidden === null) {
+    return { ok: false, detail: "index flag state could not be verified" };
+  }
+  if (hidden) {
+    return {
+      ok: false,
+      detail:
+        "the index carries assume-unchanged/skip-worktree flag(s) — worktree cleanliness " +
+        "cannot be proven against the snapshot",
+    };
+  }
+  return { ok: true, detail: null };
+}
+
+/**
+ * The `git log --oneline <fromSha>..HEAD` listing of commits now ahead of `fromSha` — or every
  * commit (`git log --oneline HEAD`) when `fromSha` is null (HEAD was unborn at capture time).
- * **Fail-open**: null on failure or when the range is empty.
+ * This is range evidence, not proof that this command created every listed commit. **Fail-open**:
+ * null on failure or when the range is empty.
  */
 export function commitsSince(cwd: string, fromSha: string | null): string | null {
   const range = fromSha === null ? "HEAD" : `${fromSha}..HEAD`;

package/extension/substrate/paths.ts

@@ -1,8 +1,8 @@
 // perk-owned dot-directory path construction — the TS twin of perk/substrate/paths.py
 // (contracts.md §8.1).
 //
-// The sole construction site for the perk-owned config family (`config.toml`/`local.toml`) and
-// the perk dir. The config family now lives at `.perk/` (TS reads the target only — the legacy
+// The sole construction site for the perk-owned config family (`config.toml`/`local.toml`).
+// The config family now lives at `.perk/` (TS reads the target only — the legacy
 // `.pi/perk.toml` migration is Python-side). The workflow family lives in the established cache
 // seam (substrate/cache.ts's `workflowDir`); together these two modules own every perk-owned
 // dot-path on this plane.
@@ -17,11 +17,6 @@ import { join } from "node:path";
 export const CONFIG_FILENAME = "config.toml";
 export const LOCAL_CONFIG_FILENAME = "local.toml";
 
-/** The perk-owned dot-dir root (shared with Pi today). */
-export function perkDir(cwd: string): string {
-  return join(cwd, ".pi");
-}
-
 /** The single config-family redirection point (the file helpers derive from it). */
 export function configDir(cwd: string): string {
   return join(cwd, ".perk");