@mgiles/perk 3.1.0 → 3.2.0

package/extension/doors/submit.ts

@@ -28,8 +28,14 @@ import { failFor, type OkDetails, ok, type Result } from "../substrate/result.ts
 import { captureSessionPointer } from "../substrate/sessionPointers.ts";
 import { appendWorkflowState, branchOf, rebuildWorkflowState } from "../substrate/workflowState.ts";
 import { report } from "../surfaces/report.ts";
+import { planningStageRefusal } from "./lifecycleGates.ts";
 
-/** The bounded conflict-resolution re-drive cap: drive the resolver at most this many times. */
+/**
+ * The bounded conflict-resolution re-drive cap: drive the resolver at most this many times.
+ * The counter behind it (`conflict_resolution_attempts`) is SHARED with `/objective-sync`'s
+ * retained-continuation conflict drive (objectiveStack.ts) — submit- and sync-episode attempts
+ * deliberately share one bound, reset on any clean completion of either surface.
+ */
 export const CONFLICT_RESOLUTION_ATTEMPT_CAP = 2;
 
 /** The ok-arm fields — the structured `details` surface doubles as branch-safe persisted state. */
@@ -167,6 +173,11 @@ function isUnmergeable(details: SubmitDetails): details is OkDetails<SubmitOk> {
 export async function submitPr(pi: ExtensionAPI, ctx: ExtensionContext): Promise<SubmitResult> {
   const fail = failFor(ctx, "submit");
 
+  // Planning sessions never legitimately submit — the first check, before any cold-door
+  // delegation (a positioned stacked planning session's cwd binding is the PREDECESSOR).
+  const planningRefusal = planningStageRefusal(ctx, "submit");
+  if (planningRefusal !== null) return fail(planningRefusal, "planning_session");
+
   // Stamp this implement run id into the plan-header `impl_run_ids` linkage (contracts.md
   // §8.35) so a later/other session can resolve the implement session pointers cross-run.
   // Mirrors planSave's `--run-id` thread; covers the interactive /submit AND the headless worker
@@ -203,7 +214,7 @@ export async function submitPr(pi: ExtensionAPI, ctx: ExtensionContext): Promise
   const conflicted = r.data.mergeable === false;
   // Reset the counter on every clean (or undetermined) submit — idempotent; keeps a later
   // independent conflict bounded fresh.
-  if (r.data.mergeable !== false) resetConflictAttempts(pi, ctx);
+  if (r.data.mergeable !== false) resetConflictAttempts(pi, ctx, "submit");
   // Automatic-cascade facts supersede the generic stacked suffix. A malformed operation block was
   // dropped by the lenient decoder, so it falls back to the pre-existing stack wording.
   const deliverySuffix =
@@ -227,35 +238,47 @@ export async function submitPr(pi: ExtensionAPI, ctx: ExtensionContext): Promise
   return ok(message, r.data, { terminate: true });
 }
 
-/** Reset `conflict_resolution_attempts` to 0 (idempotent: a no-op when already 0/absent). */
-function resetConflictAttempts(pi: ExtensionAPI, ctx: ExtensionContext): void {
+/**
+ * Reset `conflict_resolution_attempts` to 0 (idempotent: a no-op when already 0/absent). The
+ * counter is shared across the two warm conflict drives, so `scope` names the TRUE resetting
+ * surface for failure reports — `/submit` passes "submit", the stack door "objective-sync".
+ */
+export function resetConflictAttempts(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  scope: string,
+): void {
   const attempts = rebuildWorkflowState(branchOf(ctx)).conflict_resolution_attempts ?? 0;
   if (attempts === 0) return;
   appendWorkflowState(pi, ctx, {
     data: { conflict_resolution_attempts: 0 },
     field: "conflict_resolution_attempts",
     expected: 0,
-    scope: "submit",
+    scope,
     failure: "conflict_resolution_attempts reset read-back failed (expected 0)",
   });
 }
 
 /**
  * The follow-up guidance the warm `/submit` injects to dispatch the conflict-resolver (modeled on
- * `prReviewGuidance`). Pure + exported for offline tests. When `model` is set, the ONE
- * workflowScript call carries a workflow-level `model` default; otherwise the agent's default
- * model is used.
+ * `prReviewGuidance`). Pure + exported for offline tests. `worktree` is the plan worktree the
+ * child's task text pins with a concrete `cd <worktree>` command — a dispatched child otherwise
+ * has no cwd guarantee and can run its commands outside the plan worktree. When `model` is set,
+ * the ONE workflowScript call carries a workflow-level `model` default; otherwise the agent's
+ * default model is used.
  */
 export function conflictResolutionGuidance(
   base: string,
   attempt: number,
   cap: number,
+  worktree: string,
   model?: string,
 ): string {
   return render("stages/conflict-resolution.md", {
     base,
     attempt: String(attempt),
     cap: String(cap),
+    worktree,
     model: model ?? "",
   });
 }
@@ -267,7 +290,8 @@ export function conflictResolutionGuidance(
  * `followUp` user message is a separate deliberate new turn. Short-circuits (sends nothing) unless
  * the submit succeeded with a definitively-unmergeable PR. Bounded by
  * `CONFLICT_RESOLUTION_ATTEMPT_CAP` via the `conflict_resolution_attempts` field: past the cap it
- * surfaces the unresolved conflict loudly instead of looping.
+ * surfaces the unresolved conflict loudly instead of looping. The counter is shared with
+ * `/objective-sync`'s retained-continuation conflict drive.
  */
 export function driveConflictResolution(
   pi: ExtensionAPI,
@@ -298,7 +322,9 @@ export function driveConflictResolution(
   });
   const model = subagentModel(ctx.cwd, "conflict-resolver");
   const message =
-    conflictResolutionGuidance(base, next, CONFLICT_RESOLUTION_ATTEMPT_CAP, model) +
+    // `/submit` runs only in worktree-bound sessions (planning sessions are refused first), so
+    // the session cwd IS the plan worktree.
+    conflictResolutionGuidance(base, next, CONFLICT_RESOLUTION_ATTEMPT_CAP, ctx.cwd, model) +
     bindingSuffix(ctx.cwd, "command:submit");
   if (ctx.isIdle()) {
     // The `/submit` command path (idle): inject an immediate turn.

package/extension/doors/submitPrReview.ts

@@ -1,18 +1,22 @@
-// The warm `submit_pr_review` tool — the agent-driven curated-posting surface shared by the two
-// PR-review doors (`/pr-review-terminal`, `/pr-review-browser`).
+// The warm `submit_pr_review` tool — the agent-driven curated-posting surface shared by the
+// PR-review doors (`/pr-review-terminal`, `/pr-review-browser`, `/stack-review-browser`).
 //
 // `submit_pr_review` implements the per-door posting contract (contracts §8.4): nothing perk-
 // driven reaches GitHub before the human triage; ALL perk-side posting flows through this tool
 // on every door (`gh` mutations and direct `perk pr review-submit` calls are forbidden); the
 // verdict lands last, atomically with the comments. On the terminal door this tool is the sole
-// posting path. On the browser door the human platform-posts from the plannotator UI — that
-// native posting IS the GitHub path; perk composes nothing by default and posts only what the
-// human explicitly hands it (typically a request-changes verdict, which the UI cannot post). It
-// delegates to the Python cold door (`perk pr review-submit` — mutations canonical in Python)
-// via `runColdDoor` (the batch rides the run-scratch stdin channel), then appends `last_review`
-// to `perk:workflow-state`. The human gate splits: explicit conversational go-ahead ALWAYS
-// (pinned in the guidelines/skill); formal events (`approve`/`request-changes`) additionally get
-// the structural gate — headless refuses, interactive raises a blocking `ctx.ui.confirm`.
+// posting path. On the single-PR browser door the human platform-posts from the plannotator
+// UI — that native posting IS the GitHub path; perk composes nothing by default and posts only
+// what the human explicitly hands it (typically a request-changes verdict, which the UI cannot
+// post). On the stack door the local-diff session has NO attached PR, so ALL posting is
+// perk-side after triage: one real call per member PR, bottom→top, each under its own dry-run
+// anchor validation. It delegates to the Python cold door (`perk pr review-submit` — mutations
+// canonical in Python) via `runColdDoor` (the batch rides the run-scratch stdin channel), then
+// appends `last_review` AND the accumulating `review_posts` ledger row to `perk:workflow-state`
+// (the stack flow's resume authority — posted PRs are skipped, never replayed). The human gate
+// splits: explicit conversational go-ahead ALWAYS (pinned in the guidelines/skill); formal
+// events (`approve`/`request-changes`) additionally get the structural gate — headless refuses,
+// interactive raises a blocking `ctx.ui.confirm`.
 // `dry_run` is the anchor-repair loop: no gates, no record, nothing posted.
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
@@ -34,7 +38,12 @@ import {
   stringParam,
   type ToolParams,
 } from "../substrate/toolParams.ts";
-import { appendWorkflowState, type EntrySink } from "../substrate/workflowState.ts";
+import {
+  appendWorkflowState,
+  branchOf,
+  type EntrySink,
+  rebuildWorkflowState,
+} from "../substrate/workflowState.ts";
 import type { Severity } from "../surfaces/report.ts";
 
 // ------------------------------------------------------------------------ params
@@ -55,6 +64,7 @@ export interface SubmitParams {
   body: string;
   comments?: SubmitComment[];
   dry_run?: boolean;
+  allow_repost?: boolean;
 }
 
 /** Decode the optional `comments` array; null = present-but-malformed (whole-batch refusal). */
@@ -87,7 +97,7 @@ function decodeSubmitComments(p: ToolParams): SubmitComment[] | undefined | null
  * malformed field ⇒ null (whole-batch refusal). `pr` must be an int; `event` exactly one of the
  * three flag spellings; `body` a string (EMPTY ALLOWED — the cold door owns the event-conditioned
  * body rule and reports `bad_batch`); each `comments` row strict on
- * path/line(int)/side(LEFT|RIGHT)/body; `dry_run` a boolean.
+ * path/line(int)/side(LEFT|RIGHT)/body; `dry_run` and `allow_repost` booleans.
  */
 export function decodeSubmitParams(params: unknown): SubmitParams | null {
   const p = paramsOf(params);
@@ -102,9 +112,12 @@ export function decodeSubmitParams(params: unknown): SubmitParams | null {
   if (comments === null) return null;
   const dryRun = booleanParam(p, "dry_run");
   if (dryRun === null) return null;
+  const allowRepost = booleanParam(p, "allow_repost");
+  if (allowRepost === null) return null;
   const result: SubmitParams = { pr, event, body };
   if (comments !== undefined) result.comments = comments;
   if (dryRun !== undefined) result.dry_run = dryRun;
+  if (allowRepost !== undefined) result.allow_repost = allowRepost;
   return result;
 }
 
@@ -167,6 +180,42 @@ function decodeInvalidAnchors(payload: ColdJson): InvalidAnchor[] | null {
   return rows;
 }
 
+// ------------------------------------------------------------------------ the posting ledger
+
+/** One `review_posts` ledger row: a REAL submission that reached GitHub. */
+export interface ReviewPostRow {
+  pr: number;
+  event: string;
+  at: string;
+}
+
+/**
+ * Tolerant re-narrow of the rebuilt `review_posts` list (best-effort tier: a malformed row is
+ * dropped, never a refusal — the ledger only ever grows from this tool's own writes).
+ */
+export function reviewPostsOf(raw: unknown): ReviewPostRow[] {
+  if (!Array.isArray(raw)) return [];
+  const rows: ReviewPostRow[] = [];
+  for (const item of raw) {
+    const row = paramsOf(item);
+    if (row === null) continue;
+    if (typeof row.pr !== "number" || !Number.isInteger(row.pr)) continue;
+    if (typeof row.event !== "string" || typeof row.at !== "string") continue;
+    rows.push({ pr: row.pr, event: row.event, at: row.at });
+  }
+  return rows;
+}
+
+/** Ledger equality for the read-back verification (order-sensitive — posting order matters). */
+function reviewPostsEqual(rebuilt: unknown, expected: unknown): boolean {
+  const a = reviewPostsOf(rebuilt);
+  const b = reviewPostsOf(expected);
+  if (a.length !== b.length) return false;
+  return a.every(
+    (row, i) => row.pr === b[i]?.pr && row.event === b[i]?.event && row.at === b[i]?.at,
+  );
+}
+
 /** Flag spelling → the REST wire spelling shown in the human confirm. */
 const WIRE_EVENT: Record<ReviewEvent, string> = {
   approve: "APPROVE",
@@ -209,6 +258,27 @@ export async function submitPrReview(
   const dryRun = params.dry_run === true;
   const commentCount = params.comments?.length ?? 0;
 
+  // The enforced resume guard (before the confirm AND the cold-door mutation): a PR that
+  // already has a review_posts ledger row in this session is a confirmed success — a repeat
+  // real post is refused unless explicitly deliberate. A ledger row can only be MISSING
+  // spuriously (best-effort tier), never present spuriously — so the guard refuses on
+  // presence and stays silent on absence (a missing row still means: verify posted-vs-pending
+  // against GitHub before re-posting).
+  if (!dryRun && params.allow_repost !== true) {
+    const prior = reviewPostsOf(rebuildWorkflowState(branchOf(ctx)).review_posts).filter(
+      (row) => row.pr === params.pr,
+    );
+    const last = prior.at(-1);
+    if (last !== undefined) {
+      return fail(
+        `a ${last.event} review was already posted to PR #${params.pr} in this session ` +
+          `(review_posts row at ${last.at}) — on a stack resume skip this member; pass ` +
+          "allow_repost: true only for a deliberate second review of the same PR",
+        "already_posted",
+      );
+    }
+  }
+
   if (!dryRun && params.event !== "comment") {
     if (!ctx.hasUI) {
       return fail(
@@ -305,6 +375,21 @@ export async function submitPrReview(
     failure: "last_review read-back failed",
   });
 
+  // The accumulating per-PR ledger (read-rebuild-append): ordered rows, one per real success —
+  // the stack flow's partial-outcome/resume authority. Same best-effort tier as last_review.
+  const posts: ReviewPostRow[] = [
+    ...reviewPostsOf(rebuildWorkflowState(branchOf(ctx)).review_posts),
+    { pr: record.pr, event: params.event, at: record.at },
+  ];
+  appendWorkflowState(pi, ctx, {
+    data: { review_posts: posts },
+    field: "review_posts",
+    expected: posts,
+    scope: "review",
+    failure: "review_posts read-back failed",
+    equals: reviewPostsEqual,
+  });
+
   let text =
     `submitted ${params.event} review to PR #${record.pr} ` +
     `(${data.comment_count ?? commentCount} inline comment(s))`;
@@ -320,10 +405,10 @@ export async function submitPrReview(
 
 const TOOL_GUIDELINES = [
   "Call submit_pr_review only after the human triage has settled the batch AND the human has explicitly approved posting — nothing reaches GitHub before triage.",
-  "Validate first with dry_run: true and repair any reported anchors until validation passes; a dry-run never posts, never gates, and records nothing.",
-  "Make ONE real call: comments + body + event land atomically in a single review — the verdict never lands before the comments.",
+  "Validate first with dry_run: true and repair any reported anchors until validation passes; a dry-run never posts, never gates, and records nothing. A stack review dry-runs ALL per-PR batches before ANY real post.",
+  "Make ONE real call per target PR: comments + body + event land atomically in a single review — the verdict never lands before the comments. A stack review posts one review per member PR, bottom→top; each real success appends a {pr, event, at} row to the review_posts workflow-state ledger. The tool ENFORCES skip-on-resume: a real post to a PR that already has a ledger row is refused (already_posted) unless allow_repost: true — a deliberate second review only. A MISSING row is not proof of no post (the ledger is best-effort): verify posted-vs-pending against GitHub before re-posting.",
   "Formal events (approve / request-changes) additionally raise a blocking in-TUI confirm; headless sessions refuse them (use event: comment or re-run interactively).",
-  "All perk-side GitHub posting flows through this tool on both review doors — never post via gh or bash (direct perk pr review-submit calls are forbidden). On /pr-review-terminal this tool is the sole posting path; on /pr-review-browser the plannotator UI's native platform-posting is the human's own GitHub path, and perk posts only what the human explicitly hands it (typically a request-changes verdict).",
+  "All perk-side GitHub posting flows through this tool on every review door — never post via gh or bash (direct perk pr review-submit calls are forbidden). On /pr-review-terminal this tool is the sole posting path. On /pr-review-browser the plannotator UI's native platform-posting is the human's own GitHub path, and perk posts only what the human explicitly hands it (typically a request-changes verdict). On /stack-review-browser the local-diff session has NO attached PR, so ALL posting is perk-side after triage.",
 ];
 
 // ------------------------------------------------------------------------ registration
@@ -334,9 +419,12 @@ export function registerSubmitPrReview(pi: ExtensionAPI): void {
     name: "submit_pr_review",
     label: "Submit PR review",
     description:
-      "Submit the human-curated review-door outcome to the foreign PR as ONE atomic review " +
-      "(comments + body + event) via the perk cold door. dry_run validates the anchors without " +
-      "posting (the repair loop); a real submission records last_review in workflow-state.",
+      "Submit the human-curated review-door outcome to the target PR as ONE atomic review " +
+      "(comments + body + event) via the perk cold door — the posting surface of the " +
+      "/pr-review-terminal, /pr-review-browser, and /stack-review-browser doors (a stack " +
+      "review makes one real call per member PR). dry_run validates the anchors without " +
+      "posting (the repair loop); a real submission records last_review and appends the " +
+      "review_posts ledger row in workflow-state.",
     promptSnippet: "Submit the curated review batch to the PR",
     promptGuidelines: TOOL_GUIDELINES,
     executionMode: "sequential",
@@ -363,7 +451,9 @@ export function registerSubmitPrReview(pi: ExtensionAPI): void {
           type: "array",
           description:
             "The curated inline comments — human-authored or human-approved only, each anchored " +
-            "to a line in the PR diff (never re-anchor a child's finding).",
+            "to a line in the PR diff. Single-PR mode: never re-anchor a child's finding. Stack " +
+            "mode: the parent re-anchors combined-diff findings into per-PR coordinates under " +
+            "the dry-run loop.",
           items: {
             type: "object",
             additionalProperties: false,
@@ -386,6 +476,13 @@ export function registerSubmitPrReview(pi: ExtensionAPI): void {
             "Validate the batch + anchors without posting (the anchor-repair loop). No gates, " +
             "no last_review record.",
         },
+        allow_repost: {
+          type: "boolean",
+          description:
+            "Deliberately post ANOTHER review to a PR that already has a review_posts ledger " +
+            "row in this session — the enforced resume guard refuses with already_posted " +
+            "otherwise. Never pass it to work around a stack-resume refusal.",
+        },
       },
     },
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {

package/extension/factories/objectivePlan.ts

@@ -631,9 +631,10 @@ export function objectiveReadInstruction(
  * Fetch the objective's URL via `perk objective show <id> --json` (reading `objective.url`).
  * Lenient: returns "" on any failure / missing url — never throws (the seed prompt's step-1
  * `perk objective show <id>` step surfaces the URL anyway). Only called for the linear backend
- * (github needs no clause → no fetch).
+ * (github needs no clause → no fetch). Exported for the warm drives that compose the same
+ * backend-aware read clause (the ready-time reconcile drive in `doors/ready.ts`).
  */
-async function fetchObjectiveUrl(
+export async function fetchObjectiveUrl(
   pi: ExtensionAPI,
   ctx: ExtensionContext,
   objectiveId: string,
@@ -680,7 +681,7 @@ export function reconcileGuidance(objective: string, backend = "github", url = "
 }
 
 const RECONCILE_TOOL_GUIDELINES = [
-  "Call reconcile_objective only to rewrite the objective's Reconcilable prose region after a PR merged — the roadmap table and Immutable notes are never touched.",
+  "Call reconcile_objective only to rewrite the objective's Reconcilable prose region after a PR merged or after a stacked ready stamp (the ready-time pass) — the roadmap table and Immutable notes are never touched.",
   "Pass reconcile_objective the FULL replacement prose; it overwrites the marker-bounded Reconcilable region wholesale.",
   "Judgment + durable writes stay with you; skip reconcile_objective when nothing is stale (do not churn).",
 ];
@@ -688,6 +689,7 @@ const RECONCILE_TOOL_GUIDELINES = [
 const ADD_NODE_TOOL_GUIDELINES = [
   "Use add_objective_node SPARINGLY — only during reconciliation, when a genuine new unit of work emerged that wasn't planned: a deferred follow-up the PR flagged, an uncovered defect/gap, a missing prerequisite for a later node, or human-requested work from the engagement block.",
   "add_objective_node is only for genuinely-new, unplanned work — never to restate, rename, or re-scope an existing node (use objective_node's `description` for that).",
+  "Stacked objectives accept guarded `pending` tail-appends only — a refusal means the discovery is structural: route it to `perk objective replan`.",
   "Judgment + durable writes stay with you; add_objective_node delegates the write to the canonical Python plane.",
 ];
 
@@ -820,9 +822,13 @@ export function registerObjectivePlan(pi: ExtensionAPI, gating: ToolGating): voi
     label: "Reconcile objective prose",
     description:
       "Rewrite the objective's Reconcilable prose region (the marker-bounded prose in the " +
-      "objective body) to reconcile it against a merged PR. The Mechanical roadmap table and any " +
-      "Immutable notes are NEVER touched. Delegates the write to the perk cold door.",
-    promptSnippet: "Reconcile the objective's Reconcilable prose region against the merged diff",
+      "objective body) to reconcile it against the pass's evidence — a merged PR (post-land) or " +
+      "a stacked layer's pinned accepted diff range (the ready-time pass). The Mechanical " +
+      "roadmap table and any Immutable notes are NEVER touched. Delegates the write to the perk " +
+      "cold door.",
+    promptSnippet:
+      "Reconcile the objective's Reconcilable prose region against the pass's evidence " +
+      "(merged diff, or the ready-time pinned accepted range)",
     promptGuidelines: RECONCILE_TOOL_GUIDELINES,
     executionMode: "sequential",
     parameters: {

package/extension/factories/objectiveSave.ts

@@ -87,8 +87,11 @@ function decodeObjectiveCreate(payload: ColdJson): ObjectiveCreatePayload | null
  * `{input}` and the save stamps `generated_at`; the approval path passes the artifact block
  * through with its stored stamp AND stored parts — the stored parts are byte-compared against
  * the freshly re-rendered ones, so run-scratch drift or artifact tamper between draft-write
- * and save refuses `bad_state` (nothing saved, the gate stays on). The parts do NOT cross to
- * the Python plane yet — companion persistence is deferred (explicit in §8.63, not silent).
+ * and save refuses `bad_state` (nothing saved, the gate stays on). On the dream arm the
+ * reviewed CANONICAL parts cross to the Python plane through the run-scoped
+ * `dream-report-transfer.json` handoff (§8.64) — staged atomically before the cold door (a
+ * write failure is the soft `scratch_failed` refusal; the door is not invoked) — and
+ * `perk objective create` re-validates the transfer and converges the companion idempotently.
  */
 export async function saveObjective(
   pi: ExtensionAPI,

package/extension/index.ts

@@ -35,6 +35,7 @@ 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 { registerOpenStackReview, registerStackReviewBrowser } from "./doors/stackReviewBrowser.ts";
 import { registerSubmit } from "./doors/submit.ts";
 import { registerSubmitPrReview } from "./doors/submitPrReview.ts";
 import { registerGistAuthor } from "./factories/gistAuthor.ts";
@@ -260,6 +261,21 @@ export default function (pi: ExtensionAPI) {
       if (handoff === null || handoff.run_id !== decision.runId) {
         reportError(`handoff missing or mismatched for run ${decision.runId}`);
       } else {
+        // The objective-plan cold door's handoff_extra carries the node link
+        // (objective_id/node_id): persist it as the objective_node_claim so the implement-here
+        // exits are structurally suppressed in COLD objective-plan sessions too (the warm
+        // `objective_node` tool records the claim; a cold factory session never calls it — the
+        // door marked the node before launch). Blank/absent ids persist nothing; the claim
+        // clears on a successful node-linked save exactly as the warm-recorded one does.
+        const handoffObjective = handoff.objective_id;
+        const handoffNode = handoff.node_id;
+        const nodeClaim =
+          typeof handoffObjective === "string" &&
+          handoffObjective.trim() !== "" &&
+          typeof handoffNode === "string" &&
+          handoffNode.trim() !== ""
+            ? { objective: handoffObjective, node: handoffNode }
+            : undefined;
         const data: WorkflowState = {
           run_id: decision.runId,
           pi_session_id: currentSessionId ?? undefined,
@@ -268,6 +284,7 @@ export default function (pi: ExtensionAPI) {
           // 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,
+          ...(nodeClaim !== undefined ? { objective_node_claim: nodeClaim } : {}),
         };
         const okAppend = appendWorkflowState(pi, ctx, {
           data,
@@ -572,7 +589,9 @@ export default function (pi: ExtensionAPI) {
   registerSubmit(pi);
 
   // The warm `ready` door: the deliberate draft→ready review gate (submit keeps draft).
-  registerReady(pi);
+  // Takes `gating`: the warm ready→reconcile continuation refuses (loudly) to drive the
+  // ready-time pass into a read-only session (contracts.md §8.66).
+  registerReady(pi, gating);
 
   // Warm doors: `land` merges + sets pending-learn; `learn` clears it (TS-only).
   registerLand(pi);
@@ -630,6 +649,12 @@ 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 `/stack-review-browser` door + its cold-launch twin (`open_stack_review`): the
+  // stacked-PR browser review over the combined base→top diff — one reviewer wave with
+  // `stack: true`, then judgment-routed per-PR posting through `submit_pr_review`.
+  registerStackReviewBrowser(pi);
+  registerOpenStackReview(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

package/extension/substrate/config.ts

@@ -58,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

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");