@mgiles/perk 3.0.0 → 3.2.0

package/extension/substrate/resolverLease.ts

@@ -0,0 +1,363 @@
+// The conflict-resolver claim (contracts.md §8.51): a machine-local SESSION CLAIM on a retained
+// sync-continuation operation, taken by the warm dispatcher right before it injects the resolver
+// dispatch. It is honestly NOT a child-lifecycle-bound lock — `pi.sendUserMessage` is
+// fire-and-forget and the extension never observes the dispatched child's start or finish — so
+// there is deliberately NO explicit release on dispatch. The claim self-heals instead, via the
+// reclaimability predicate: the holder pid is dead, the recorded operation was consumed (a fresh
+// conflict minted a new operation id), or the lease is missing/corrupt and the lock dir has aged
+// past `RECLAIM_GRACE_MS`. The accepted residual: a live session's claim on a still-pending SAME
+// operation blocks other sessions' dispatch until that session exits or the operation is
+// consumed — the busy reason names the holder pid, the lock path, and the remediation.
+//
+// Reclaim mechanics mirror `hunkFeedback/store.ts::acquireLease` (the interleaving-safe recipe):
+// judge reclaimability → quarantine-RENAME the observed lock dir to a unique name (rename is
+// atomic, so two reclaimers can never both delete a successor) → post-rename re-judgment on the
+// MOVED state (a claim that changed since the judgment, or whose lease is missing/corrupt but
+// still inside the grace window, is renamed back — a raced-in claim is NEVER stolen, whatever
+// operation it names) → ONE fresh-acquire retry → best-effort quarantine removal; a lost retry
+// is an honest busy. Deletion only ever targets our own quarantine dir or our own same-call
+// acquisition, and the explicit withheld-dispatch release is token-fenced through its own
+// quarantine-verify (`releaseResolverClaim`).
+//
+// Error posture: a MISSING or MALFORMED lease is DATA (it routes to the reclaim rules), and the
+// expected race disappearances (ENOENT on read/stat/rename, EEXIST on mkdir) are contention —
+// every OTHER filesystem failure propagates to the typed `io_error` arm, never a fabricated
+// busy/reclaim judgment.
+
+import { randomBytes } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, rmSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { atomicWriteFileSync } from "./cache.ts";
+
+/**
+ * A corrupt/missing `lease.json` is reclaimable only once the lock dir is older than this —
+ * closes the winner's mkdir↔first-write window (implementation constant, not config).
+ */
+export const RECLAIM_GRACE_MS = 60_000;
+
+/** The claim lock dir sits beside the continuation manifest it guards. */
+export function resolverLockDir(manifestPath: string): string {
+  return `${manifestPath}.resolver-lock`;
+}
+
+export type LeaseAcquisition =
+  | { acquired: true; token: string }
+  | { acquired: false; kind: "busy" | "io_error"; reason: string };
+
+/** Deterministic-interleave seams for the reclaim-race tests — never set in production. */
+export interface AcquireRaceHooks {
+  /** Runs after the reclaimability judgment, before the quarantine rename. */
+  beforeQuarantine?(): void;
+  /** Runs after the quarantine rename attempt, before the fresh-acquire retry. */
+  afterQuarantine?(): void;
+}
+
+/** The raw fs operations the claim touches — injectable ONLY for deterministic fault tests. */
+export interface LeaseFsOps {
+  /** Non-recursive mkdir: EEXIST is the contention signal. */
+  mkdir(path: string): void;
+  /** utf8 read. */
+  readFile(path: string): string;
+  /** Atomic lease write (temp + rename — the atomicWriteFileSync discipline). */
+  writeLease(path: string, content: string): void;
+  rename(from: string, to: string): void;
+  /** Recursive, force. */
+  rm(path: string): void;
+  statMtimeMs(path: string): number;
+}
+
+const REAL_FS: LeaseFsOps = {
+  mkdir: (path) => mkdirSync(path),
+  readFile: (path) => readFileSync(path, "utf8"),
+  writeLease: (path, content) => atomicWriteFileSync(path, content),
+  rename: (from, to) => renameSync(from, to),
+  rm: (path) => rmSync(path, { recursive: true, force: true }),
+  statMtimeMs: (path) => statSync(path).mtimeMs,
+};
+
+interface ResolverLease {
+  schema: 1;
+  pid: number;
+  operation_id: string;
+  /** The per-acquisition ownership fence: rotated on every (re)acquire; release verifies it. */
+  token: string;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function errorCode(error: unknown): string | undefined {
+  return (error as NodeJS.ErrnoException).code;
+}
+
+/**
+ * Read the lease as DATA: a missing file or malformed/mis-shaped content is `null` (the
+ * corrupt/missing reclaim rules own it). Any OTHER read failure (EACCES, EIO, EISDIR, …) is a
+ * genuine I/O failure and THROWS so the caller's typed `io_error` arm reports it honestly.
+ */
+function readLease(fs: LeaseFsOps, lockDir: string): ResolverLease | null {
+  let raw: string;
+  try {
+    raw = fs.readFile(join(lockDir, "lease.json"));
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") return null;
+    throw error;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (
+    isRecord(parsed) &&
+    parsed.schema === 1 &&
+    typeof parsed.pid === "number" &&
+    Number.isInteger(parsed.pid) &&
+    typeof parsed.operation_id === "string" &&
+    typeof parsed.token === "string"
+  ) {
+    return parsed as unknown as ResolverLease;
+  }
+  return null;
+}
+
+/** The lock dir's mtime, or -Infinity when it vanished (ENOENT — a racing reclaim finished);
+ * any other stat failure throws to the typed `io_error` arm. */
+function lockDirBasisMs(fs: LeaseFsOps, path: string): number {
+  try {
+    return fs.statMtimeMs(path);
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") return Number.NEGATIVE_INFINITY;
+    throw error;
+  }
+}
+
+function leaseBytes(lease: ResolverLease): string {
+  return `${JSON.stringify(lease)}\n`;
+}
+
+function mintToken(): string {
+  return randomBytes(8).toString("hex");
+}
+
+/** Liveness probe: ESRCH = dead; EPERM (a foreign-uid process) and success both count alive. */
+function defaultIsAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return errorCode(error) !== "ESRCH";
+  }
+}
+
+/**
+ * Atomic non-recursive `mkdir` (EEXIST = contention) + the first lease write. Returns the fresh
+ * token on acquisition, null on contention; throws on any other fs failure — after best-effort
+ * removing the dir THIS call created (we own it; any surviving residue self-heals via the
+ * aged-corrupt reclaim rule).
+ */
+function tryFreshAcquire(
+  fs: LeaseFsOps,
+  lockDir: string,
+  pid: number,
+  operationId: string,
+): string | null {
+  try {
+    fs.mkdir(lockDir);
+  } catch (error) {
+    if (errorCode(error) === "EEXIST") return null;
+    throw error;
+  }
+  const token = mintToken();
+  try {
+    fs.writeLease(
+      join(lockDir, "lease.json"),
+      leaseBytes({ schema: 1, pid, operation_id: operationId, token }),
+    );
+  } catch (error) {
+    try {
+      fs.rm(lockDir);
+    } catch {
+      // best-effort — the corrupt-lease reclaim rule collects it once it ages
+    }
+    throw error;
+  }
+  return token;
+}
+
+function busyHolder(pid: number, lockDir: string): string {
+  return (
+    `another live session (pid ${pid}) holds the resolver claim at ${lockDir} — ` +
+    "dispatch from that session, or remove the lock dir if it is provably stale"
+  );
+}
+
+function busyUnidentified(lockDir: string): string {
+  return (
+    `an unidentified holder claims the resolver lock at ${lockDir} (lease unreadable, ` +
+    "created recently) — retry shortly, or remove the lock dir if it is provably stale"
+  );
+}
+
+function sameLease(a: ResolverLease, b: ResolverLease | null): boolean {
+  return b !== null && a.pid === b.pid && a.operation_id === b.operation_id && a.token === b.token;
+}
+
+/**
+ * Acquire the resolver claim for `operationId` on the continuation at `manifestPath`. Never
+ * throws: every genuine filesystem failure is caught and returned as `kind: "io_error"` (the
+ * expected race disappearances are classified inline — see the module doc). Same-pid contention
+ * is an idempotent REACQUIRE that rewrites `lease.json` with the CURRENT operation id and a
+ * fresh token (a continue-time NEW conflict reuses the same operation id — the original
+ * dispatching session re-claims; it never routes through reclaim). On success the returned
+ * `token` is the ownership fence a withheld dispatch passes to `releaseResolverClaim`.
+ * `pid`/`isAlive`/`now`/`hooks`/`fs` are injectable for deterministic tests.
+ */
+export function acquireResolverLease(
+  manifestPath: string,
+  operationId: string,
+  opts?: {
+    pid?: number;
+    isAlive?: (pid: number) => boolean;
+    now?: () => number;
+    hooks?: AcquireRaceHooks;
+    fs?: Partial<LeaseFsOps>;
+  },
+): LeaseAcquisition {
+  const pid = opts?.pid ?? process.pid;
+  const isAlive = opts?.isAlive ?? defaultIsAlive;
+  const now = opts?.now ?? Date.now;
+  const hooks = opts?.hooks ?? {};
+  const fs: LeaseFsOps = { ...REAL_FS, ...(opts?.fs ?? {}) };
+  const lockDir = resolverLockDir(manifestPath);
+  try {
+    const fresh = tryFreshAcquire(fs, lockDir, pid, operationId);
+    if (fresh !== null) return { acquired: true, token: fresh };
+
+    const observed = readLease(fs, lockDir);
+    if (observed !== null && observed.pid === pid) {
+      // Same pid: reacquire, not reclaim — rewrite with the current operation id + fresh token.
+      const token = mintToken();
+      fs.writeLease(
+        join(lockDir, "lease.json"),
+        leaseBytes({ schema: 1, pid, operation_id: operationId, token }),
+      );
+      return { acquired: true, token };
+    }
+
+    // Reclaimability: dead holder / consumed operation / aged corrupt-or-missing lease.
+    if (observed !== null) {
+      if (isAlive(observed.pid) && observed.operation_id === operationId) {
+        return { acquired: false, kind: "busy", reason: busyHolder(observed.pid, lockDir) };
+      }
+    } else if (now() - lockDirBasisMs(fs, lockDir) < RECLAIM_GRACE_MS) {
+      // Corrupt/missing lease.json inside the grace window (a winner may sit between its
+      // mkdir and first write) — busy; a vanished dir counts old and the retry settles it.
+      return { acquired: false, kind: "busy", reason: busyUnidentified(lockDir) };
+    }
+
+    // Reclaim: quarantine-rename → post-rename re-judgment → ONE fresh-acquire retry.
+    hooks.beforeQuarantine?.();
+    const quarantine = `${lockDir}.stale-${pid.toString(36)}-${randomBytes(4).toString("hex")}`;
+    let renamed = false;
+    try {
+      fs.rename(lockDir, quarantine);
+      renamed = true;
+    } catch (error) {
+      // ENOENT = a competing reclaimer moved it first — still take the one retry. Any other
+      // rename failure is genuine I/O and must not masquerade as contention.
+      if (errorCode(error) !== "ENOENT") throw error;
+      renamed = false;
+    }
+    if (renamed) {
+      // Post-rename re-judgment on the MOVED state: between our judgment and the rename a
+      // competitor may have installed a successor claim (any operation id — never assume the
+      // one we are acquiring), or a winner may sit inside its mkdir↔first-write window (a
+      // young dir with no lease yet). Neither is ours to take: restore and report busy. Only
+      // the unchanged judged-stale state, a dead raced-in holder, or an AGED lease-less dir
+      // proceeds to the retry.
+      const moved = readLease(fs, quarantine);
+      let busyReason: string | null = null;
+      if (moved !== null) {
+        if (!sameLease(moved, observed) && isAlive(moved.pid)) {
+          busyReason = busyHolder(moved.pid, lockDir);
+        }
+      } else if (now() - lockDirBasisMs(fs, quarantine) < RECLAIM_GRACE_MS) {
+        // rename preserves mtime — the moved dir's age is the original dir's age.
+        busyReason = busyUnidentified(lockDir);
+      }
+      if (busyReason !== null) {
+        try {
+          fs.rename(quarantine, lockDir);
+        } catch {
+          // the name was retaken meanwhile — leave the quarantine; it self-heals as residue
+        }
+        return { acquired: false, kind: "busy", reason: busyReason };
+      }
+    }
+    hooks.afterQuarantine?.();
+    const retried = tryFreshAcquire(fs, lockDir, pid, operationId);
+    if (renamed) {
+      try {
+        fs.rm(quarantine);
+      } catch {
+        // best-effort — a leftover quarantine dir is inert
+      }
+    }
+    if (retried !== null) return { acquired: true, token: retried };
+    return {
+      acquired: false,
+      kind: "busy",
+      reason:
+        `another session claimed the resolver lock at ${lockDir} first — dispatch from that ` +
+        "session, or retry once its claim clears",
+    };
+  } catch (error) {
+    return {
+      acquired: false,
+      kind: "io_error",
+      reason: `resolver-claim filesystem failure at ${lockDir}: ${String(error)}`,
+    };
+  }
+}
+
+/**
+ * Release THIS call's claim — the withheld-dispatch cleanup (a verified-increment failure must
+ * not leave a phantom holder). Token-fenced through a quarantine-verify: the claim is renamed
+ * to a private name first (atomic — a successor installed at the canonical path is never
+ * touched), verified against `token`, and deleted only when it proved ours; anything else is
+ * renamed back. Best-effort and never throws: leftover residue self-heals via the reclaim
+ * rules.
+ */
+export function releaseResolverClaim(
+  manifestPath: string,
+  token: string,
+  opts?: { fs?: Partial<LeaseFsOps> },
+): void {
+  const fs: LeaseFsOps = { ...REAL_FS, ...(opts?.fs ?? {}) };
+  const lockDir = resolverLockDir(manifestPath);
+  const quarantine = `${lockDir}.release-${process.pid.toString(36)}-${randomBytes(4).toString("hex")}`;
+  try {
+    try {
+      fs.rename(lockDir, quarantine);
+    } catch (error) {
+      if (errorCode(error) === "ENOENT") return; // nothing to release
+      throw error;
+    }
+    const moved = readLease(fs, quarantine);
+    if (moved !== null && moved.token === token) {
+      fs.rm(quarantine);
+      return;
+    }
+    // Not ours (a successor raced in) — put it back untouched.
+    try {
+      fs.rename(quarantine, lockDir);
+    } catch {
+      // the name was retaken meanwhile — leave the quarantine; it self-heals as residue
+    }
+  } catch {
+    // best-effort — a leftover claim/quarantine goes stale and is reclaimed by the next acquire
+  }
+}

package/extension/substrate/result.ts

@@ -53,8 +53,9 @@ export function ok<D extends object>(
 /**
  * Bind the module's fail constructor once: `const fail = failFor(ctx, scope)` (or
  * `failFor(ctx, scope, label)` when the content label differs from the report scope). Each call
- * reports loudly (`report(ctx, scope, "error", message, { alsoLog: true })`) and returns the
- * canonical soft failure: content `"<label> failed: <message>"`, details
+ * reports through the terminal-safe report seam (`alsoLog` mirrors complete diagnostics only in
+ * headless/RPC contexts) and returns the canonical soft failure: content
+ * `"<label> failed: <message>"`, details
  * `{ ok: false, error: message, error_type: errorType }`, no `terminate`. `X` is the
  * `FailDetails` extras hook: `failFor<X>(…)` lets a call attach module-specific fail details
  * (spread AFTER `error`/`error_type`) — e.g. the learn wave's attempt receipts. Extras stay

package/extension/substrate/sessionData.ts

@@ -36,7 +36,7 @@ import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { join, relative } from "node:path";
 import type { ReportTarget } from "../surfaces/report.ts";
-import { atomicWriteFileSync, sessionDataDir } from "./cache.ts";
+import { atomicWriteFileSync, ensureRunScratch, sessionDataDir } from "./cache.ts";
 import {
   appendWorkflowState,
   type BranchSource,
@@ -72,11 +72,13 @@ export function activeSessionDataDir(ctx: SessionDataCtx): string | null {
   return sessionDataDir(ctx.cwd, runId);
 }
 
-/** Ensure (mkdir -p) the current session's data dir; `null` + a warning on failure. */
+/** Ensure the validated run root, then its data dir; `null` + a warning on failure. */
 export function ensureSessionDataDir(ctx: SessionDataCtx): string | null {
-  const dir = activeSessionDataDir(ctx);
-  if (dir === null) return null;
+  const runId = activeSessionRunId(ctx);
+  if (runId === null) return null;
+  const dir = sessionDataDir(ctx.cwd, runId);
   try {
+    ensureRunScratch(ctx.cwd, runId);
     mkdirSync(dir, { recursive: true });
   } catch (error) {
     console.error(`perk: warning: could not create session data dir ${dir}: ${error}`);

package/extension/substrate/sessionPointers.ts

@@ -13,9 +13,9 @@
 // wedge the save/launch/drive it rides on. Node builtins + cache.ts + git.ts only (loads under
 // `node --test`).
 
-import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { basename, join } from "node:path";
-import { atomicWriteFileSync, runScratchDir } from "./cache.ts";
+import { atomicWriteFileSync, ensureRunScratch, runScratchDir } from "./cache.ts";
 import { mainCheckoutRoot } from "./git.ts";
 
 export const SESSION_POINTERS_FILE = "session-pointers.json";
@@ -119,8 +119,7 @@ export function recordSessionPointer(
     // The run id is authoritative — a record read from disk keeps its own; a fresh one is minted
     // with `runId`. (A mismatched on-disk run_id is left as-is; self-keying guarantees a match.)
     record[klass][site] = pointer;
-    const dir = runScratchDir(root, runId);
-    mkdirSync(dir, { recursive: true });
+    ensureRunScratch(root, runId);
     atomicWriteFileSync(sessionPointersPath(root, runId), serialize(record));
     return true;
   } catch (error) {

package/extension/substrate/toolGating.ts

@@ -263,6 +263,14 @@ export const READ_ONLY_TOOLS = [
   // `perk.harvest-analyst` over the already-carved-in SUBAGENT_TOOLS/SUBAGENT_CHILD_TOOLS, and
   // it writes nothing to the worktree (contracts.md §8.48).
   "run_harvest_wave",
+  // The dream-wave carve-in: the seeded `perk learn dream` session runs GATED (the read-only
+  // objective-author borrow), so `run_dream_wave` must be reachable while read-only. The tool
+  // takes NO parameters: its manifest read AND its one write (the fixed-name run-scratch
+  // bundle beside that manifest) are both derived from the claimed run's manifest path — no
+  // caller-supplied path exists (the `run_audit_wave` no-aimable-writer posture, BOTH sides),
+  // and it spawns only the read-only `perk.dream-analyst`/`perk.dream-reducer` over the
+  // already-carved-in delegation family (contracts.md §8.61).
+  "run_dream_wave",
 ];
 
 /**
@@ -287,6 +295,7 @@ export const PERK_TOOLS: readonly string[] = [
   "run_learn_wave",
   "run_audit_wave",
   "run_harvest_wave",
+  "run_dream_wave",
   "land",
   "post_pr_review",
   "ready",
@@ -303,6 +312,9 @@ export const PERK_TOOLS: readonly string[] = [
   "collect_draft_review_wave",
   "run_ci",
   "submit",
+  // The stack-review launch-recovery tool (contracts.md §8.4): parameterless — the snapshot
+  // comes only from the `perk objective stack review` launch handoff.
+  "open_stack_review",
   // The stacked-delivery warm surface (contracts.md §8.51/§8.56): read + control tools over
   // the cold `objective stack` workers. Never in READ_ONLY_TOOLS — sync/adopt/recover/land
   // mutate published branches and PRs; the gated posture is the driving commands' soft
@@ -482,6 +494,19 @@ export const STAGE_TOOLS: Readonly<Record<string, readonly string[]>> = {
   // (read-only mode), where this list is inert; it exists for the keys≡registry pin and the
   // defensive gate-off arm.
   audit: ["ask_user_question", "run_audit_wave", ...RESEARCH_TOOLS],
+  // The stacked-PR browser-review launcher (`perk objective stack review`): exactly the flow
+  // set the stack.md guidance names — the launch-recovery tool, the review-wave pair, the
+  // annotation push, per-PR posting, delegation (the wave's relay loop), and research.
+  "stack-review": [
+    "ask_user_question",
+    "open_stack_review",
+    "start_review_wave",
+    "collect_review_wave",
+    "push_annotations",
+    "submit_pr_review",
+    ...SUBAGENT_TOOLS,
+    ...RESEARCH_TOOLS,
+  ],
 };
 
 /** The read-only marker / custom-message type injected into context while active. */

package/extension/substrate/workflowState.ts

@@ -45,8 +45,10 @@ export interface WorkflowState {
   last_review_batch?: unknown;
   /**
    * The last `/pr-review` outcome posted via the `post_pr_review` warm tool (§8.3):
-   * `{pr, verdict, angles, comment_count, mode, at}`. Best-effort tier (per-field LWW in
-   * `rebuildWorkflowState`, no rebuild change). The PR comment stays canonical.
+   * `{pr, verdict, angles, covered_angles, comment_count, mode, at}`. After a recorded wave,
+   * `angles` is the authoritative attempted manifest and `covered_angles` is its schema-valid
+   * subset; standalone posts use the caller's `angles` for both. Best-effort tier (per-field LWW
+   * in `rebuildWorkflowState`, no rebuild change). The PR comment stays canonical.
    */
   last_pr_review?: unknown;
   /**
@@ -55,6 +57,14 @@ export interface WorkflowState {
    * `rebuildWorkflowState`, no rebuild change). The submitted PR review stays canonical.
    */
   last_review?: unknown;
+  /**
+   * The accumulating per-PR posting ledger of a stacked review (§8.3/§8.4): one
+   * `{pr, event, at}` row per REAL `submit_pr_review` success, ordered by posting time
+   * (read-rebuild-append — the whole list is re-appended each time). The resume authority for
+   * a partially-posted stack sequence: confirmed successes are skipped, never replayed.
+   * Best-effort tier (per-field LWW in `rebuildWorkflowState`, no rebuild change).
+   */
+  review_posts?: unknown;
   /** Session-artifact provenance pointers, keyed by artifact name (§8.3). */
   session_artifacts?: Record<string, SessionArtifactPointer> | null;
   /**
@@ -65,9 +75,20 @@ export interface WorkflowState {
    */
   objective_node_claim?: { objective: string; node: string } | null;
   /**
-   * The bounded conflict-resolution re-drive counter (§8.3). Incremented each time
-   * `/submit` drives the `perk.conflict-resolver` subagent on a definitively-unmergeable PR;
-   * reset to 0 on a clean submit. Best-effort tier (cheaply reconstructable). Per-field LWW in
+   * The dream-wave finalized-bundle digest marker (§8.61) — the freshness/integrity authority
+   * the dream-report recovery (§8.63) trusts over the bare run-scratch bundle file. `""` =
+   * invalidated (cleared unconditionally at wave entry BEFORE the stale-bundle removal attempt,
+   * so a failed cleanup leaves prior files behind but recovery refuses them); `sha256:<hex>` =
+   * the digest of the current finalized bundle bytes, set only after a successful finalize
+   * write. Per-field LWW; no rebuild change.
+   */
+  dream_bundle_digest?: string;
+  /**
+   * The bounded conflict-resolution re-drive counter (§8.3). Incremented on each
+   * `perk.conflict-resolver` dispatch from EITHER warm surface — `/submit`'s PR-rebase drive on
+   * a definitively-unmergeable PR, or `/objective-sync`'s retained-continuation drive; reset to
+   * 0 on any clean completion (a clean submit; a clean non-declined mutating stack
+   * sync/continue/abort/adopt). Best-effort tier (cheaply reconstructable). Per-field LWW in
    * `rebuildWorkflowState` handles it with no rebuild change.
    */
   conflict_resolution_attempts?: number;
@@ -78,6 +99,8 @@ export interface BranchEntry {
   type: string;
   customType?: string;
   data?: Record<string, unknown>;
+  /** Present on Pi custom_message entries (hidden model-context messages). */
+  content?: unknown;
 }
 
 /** The minimal read-only session surface the branch accessor needs. */
@@ -107,6 +130,35 @@ export function branchCarries(branch: readonly BranchEntry[], needle: string): b
   return branch.some((entry) => JSON.stringify(entry).includes(needle));
 }
 
+/**
+ * The branch entries still represented directly in model context. Before compaction that is the
+ * full branch. After compaction, Pi keeps entries from `firstKeptEntryId` onward plus anything
+ * appended later; historical entries before that cutoff survive only through the summary.
+ * Compaction entries are excluded because text quoted by a summary is not a live custom block.
+ */
+export function activeContextWindow(branch: readonly BranchEntry[]): BranchEntry[] {
+  let latestCompaction = -1;
+  for (let i = branch.length - 1; i >= 0; i--) {
+    if (branch[i]?.type === "compaction") {
+      latestCompaction = i;
+      break;
+    }
+  }
+  if (latestCompaction === -1) return [...branch];
+
+  const firstKeptEntryId = (branch[latestCompaction] as { firstKeptEntryId?: unknown })
+    .firstKeptEntryId;
+  const firstKept =
+    typeof firstKeptEntryId === "string"
+      ? branch.findIndex(
+          (entry, index) =>
+            index < latestCompaction && (entry as { id?: unknown }).id === firstKeptEntryId,
+        )
+      : -1;
+  const start = firstKept === -1 ? latestCompaction + 1 : firstKept;
+  return branch.slice(start).filter((entry) => entry.type !== "compaction");
+}
+
 /**
  * Per-field last-write-wins over the `perk:workflow-state` custom entries on a branch.
  * Non-perk entries are ignored; `undefined` fields never clobber (but explicit `null` does).

package/extension/surfaces/report.ts

@@ -1,20 +1,39 @@
-// The one headless-safe report seam — owns the `perk: <scope> — <message>` prefix, the severity,
-// and the `hasUI ? notify : console.error` routing so callers inherit the headless-fail-safe
-// invariant for free (cf. the `branchOf`/`BranchSource` seam in workflowState.ts).
+// The one terminal-safe report seam — owns the `perk: <scope> — <message>` prefix, the severity,
+// and the projection of complete diagnostics into a managed headline plus an optional durable detail
+// sink (cf. the `branchOf`/`BranchSource` seam in workflowState.ts).
 
 export type Severity = "info" | "warning" | "error";
+export type ReportDetailSink = (text: string, severity: Severity) => void;
 
 /** The minimal headless-aware surface report() needs. `ExtensionContext` satisfies it; tests fake it. */
 export interface ReportTarget {
   hasUI: boolean;
+  mode?: "tui" | "rpc" | "json" | "print";
   ui: { notify(message: string, type?: Severity): void };
 }
 
+const detailSinks = new WeakMap<ReportTarget, ReportDetailSink>();
+const LOGICAL_LINE = /\r\n|\n|\r/;
+const HORIZONTAL_WHITESPACE = /[^\S\r\n]+/g;
+
+/** Attach display-only multiline report detail to this exact context object. */
+export function attachReportDetailSink(target: ReportTarget, sink: ReportDetailSink): void {
+  detailSinks.set(target, sink);
+}
+
+function headlineFor(prefix: string, message: string): string {
+  for (const line of message.split(LOGICAL_LINE)) {
+    const trimmed = line.trim();
+    if (trimmed.length > 0) return `${prefix}${trimmed.replace(HORIZONTAL_WHITESPACE, " ")}`;
+  }
+  return prefix;
+}
+
 /**
- * The single headless-safe report seam. Builds `perk: <scope> — <message>`, notifies the UI when
- * present and otherwise writes to stderr (the headless-fail-safe invariant — callers inherit it for
- * free). Pass { alsoLog: true } to ALSO write to stderr when headful (cold-door failures land in run
- * logs even in a TUI). Returns the prefixed string for reuse (tool-result text, etc.).
+ * Build and return the complete `perk: <scope> — <message>` value. Headless targets receive that
+ * value on stderr. Headful targets receive a managed one-line headline; multiline detail goes to an
+ * attached display-only sink in every non-RPC mode. `{ alsoLog: true }` is narrowly an RPC/headless
+ * diagnostic mirror and never permits raw terminal output in a headful non-RPC context.
  */
 export function report(
   target: ReportTarget,
@@ -23,12 +42,19 @@ export function report(
   message: string,
   opts?: { alsoLog?: boolean },
 ): string {
-  const full = `perk: ${scope} — ${message}`;
-  if (target.hasUI) {
-    target.ui.notify(full, severity);
-    if (opts?.alsoLog) console.error(full);
-  } else {
+  const prefix = `perk: ${scope} — `;
+  const full = `${prefix}${message}`;
+  if (!target.hasUI) {
     console.error(full);
+    return full;
   }
+
+  target.ui.notify(headlineFor(prefix, message), severity);
+  if (target.mode === "rpc") {
+    if (opts?.alsoLog) console.error(full);
+    return full;
+  }
+
+  if (message.split(LOGICAL_LINE).length > 1) detailSinks.get(target)?.(full, severity);
   return full;
 }