@mgiles/perk 3.2.0 → 3.3.0

package/extension/pi/v1/objectiveRefinement.ts

@@ -0,0 +1,1320 @@
+// The v1 Pi installer for the objective-node refinement feature (contracts.md §8.67):
+// `installObjectiveRefinementBindings` owns every refinement registration — the ONE model-facing
+// `objective_refinement_draft` tool, the warm `/objective-refine` entry, the human failsafe
+// `/objective-refinement-save`, and the refinement context hook pair; `runRefinementReviewV1` is
+// the `plan_review` refinement arm the stage dispatcher routes to; `importRefinementContextOnClaim`
+// is the cold claim's one-time context import. The feature logic lives in
+// `authoring/refinement/`; this module decodes at the tool/command boundary, builds the
+// cold-door backend / worker / gate adapters, constructs the warm-door Result envelopes, and
+// places the feature-owned prose units in Pi fields.
+//
+// Isolation posture: a refinement session never creates a plan, claims a node, links a plan-ref,
+// changes node/objective state or provisions a checkout. There is NO `objective_refinement_save`
+// tool — the two persistence paths are the APPROVED `plan_review` arm and the human command,
+// both through the shared save seam over the `perk objective refinement-save` worker.
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+  importColdRefinementContext,
+  importRefinementContext,
+  REFINE_STAGE,
+  REFINEMENT_CONTEXT_ARTIFACT,
+  type RefinementContextRead,
+  validateContextTransfer,
+} from "../../authoring/refinement/context.ts";
+import {
+  REFINEMENT_DRAFT_ARTIFACT,
+  renderRefinementDraft,
+  resumeRefinementDraft,
+  reviseRefinementDraft,
+} from "../../authoring/refinement/draft.ts";
+import {
+  REFINEMENT_CONTEXT_TYPE,
+  REFINEMENT_DRAFT_TOOL_GUIDELINES,
+  REFINEMENT_MARKER,
+  refinementContextContent,
+  refinementGuidance,
+  refinementStageRefusal,
+} from "../../authoring/refinement/prose.ts";
+import {
+  completeRefinementReview,
+  type RefinementReviewOutcome,
+  type ReviewRefinementResult,
+} from "../../authoring/refinement/review.ts";
+import {
+  type RefinementApprovalSaveOutcome,
+  type RefinementBackend,
+  type RefinementBackendSaveResult,
+  type ReviewedRefinementPair,
+  refinementApprovalSave,
+  reviewedPairOf,
+} from "../../authoring/refinement/save.ts";
+import type { ApprovalGate } from "../../authoring/review/approvalGate.ts";
+import { openBranchWorkflowSession } from "../../session/branchWorkflowSession.ts";
+import type { WorkflowSession } from "../../session/workflowSession.ts";
+import { bindingSuffix } from "../../substrate/bindingDelivery.ts";
+import {
+  type Handoff,
+  handoffPath,
+  isSafeRunId,
+  readHandoff,
+  runScratchDir,
+} from "../../substrate/cache.ts";
+import {
+  booleanField,
+  type ColdJson,
+  runColdDoor,
+  stringField,
+  stringListField,
+} from "../../substrate/coldDoor.ts";
+import { registerPerkCommand } from "../../substrate/command.ts";
+import { loadPerkConfig } from "../../substrate/config.ts";
+import { failFor, ok, type Result } from "../../substrate/result.ts";
+import type { ToolGating } from "../../substrate/toolGating.ts";
+import { paramsOf, stringParam } from "../../substrate/toolParams.ts";
+import {
+  type BranchEntry,
+  branchOf,
+  rebuildWorkflowState,
+  type WorkflowState,
+} from "../../substrate/workflowState.ts";
+import { report } from "../../surfaces/report.ts";
+import { installInjectedContext } from "./contextInjection.ts";
+import {
+  checkDraftReviewDecision,
+  type DecisionCheck,
+  type DraftReviewSlot,
+  destinationChangedResult,
+  type OpenDraftReview,
+  openRefusedResult,
+  recordSaveOutcome,
+  saveUnconfirmedResult,
+  staleApprovalResult,
+  supersededReviewResult,
+  withDraftChangedNote,
+} from "./draftReview.ts";
+import { hasDirectEditsHeading } from "./providers/plannotator.ts";
+import { isPlannotatorPlanSelected } from "./providers/selection.ts";
+import {
+  approvedSubjectSaveResult,
+  type DraftReviewBridge,
+  type ReviewOutcome,
+  type ReviewSubject,
+  runFirstPartyReview,
+  skipResult,
+  subjectReviewOutcomeResult,
+  type ToolResult,
+  verdictsFor,
+} from "./review.ts";
+
+const SCOPE_REFINE = "objective-refine";
+const SCOPE_SAVE = "objective-refinement-save";
+
+// ------------------------------------------------------------------- the tool-boundary decode
+
+/** Decode the `objective_refinement_draft` params: exactly `{ markdown: string }` (strict). */
+export function decodeRefinementDraftParams(params: unknown): { markdown: string } | null {
+  const p = paramsOf(params);
+  if (p === null) return null;
+  const markdown = stringParam(p, "markdown");
+  if (markdown === null || markdown === undefined) return null;
+  return { markdown };
+}
+
+// ----------------------------------------------------------------- the command-args decode
+
+export type RefineCommandArgs =
+  | { ok: true; objective: string | null; node: string | null }
+  | { ok: false; problem: string };
+
+/**
+ * Parse `/objective-refine [objective] [--node ID | --node=ID]`: at most one positional (an
+ * opaque objective id, `#` tolerated), at most one `--node` with a nonblank value, nothing else.
+ * Every extra/duplicate/missing-value shape refuses (never a silent default). Pure.
+ */
+export function parseRefineCommandArgs(args: string): RefineCommandArgs {
+  const tokens = args
+    .trim()
+    .split(/\s+/)
+    .filter((t) => t.length > 0);
+  let objective: string | null = null;
+  let node: string | null = null;
+  for (let i = 0; i < tokens.length; i += 1) {
+    const token = tokens[i] as string;
+    if (token === "--node" || token.startsWith("--node=")) {
+      if (node !== null) return { ok: false, problem: "--node may be given at most once" };
+      const value = token === "--node" ? tokens[++i] : token.slice("--node=".length);
+      if (value === undefined || value.trim() === "" || value.startsWith("--"))
+        return { ok: false, problem: "--node needs a node id (e.g. --node 2.3)" };
+      node = value;
+      continue;
+    }
+    if (token.startsWith("-")) return { ok: false, problem: `unknown option ${token}` };
+    if (objective !== null) return { ok: false, problem: `unexpected extra argument ${token}` };
+    const id = token.replace(/^#/, "");
+    if (id === "") return { ok: false, problem: "the objective id must not be blank" };
+    objective = id;
+  }
+  return { ok: true, objective, node };
+}
+
+// ------------------------------------------------------------------- the warm admission
+
+/** The plan-graph stages a launch handoff marks a session as plan-bearing with. */
+const PLAN_BEARING_STAGES: readonly string[] = [
+  "plan",
+  "objective-plan",
+  "save",
+  "implement",
+  "submit",
+  "address",
+  "land",
+  "learn",
+];
+
+export type WarmRefinementAdmission =
+  | { ok: true; runId: string; activeObjective: string | null; alreadyRefining: boolean }
+  | { ok: false; code: "bad_state" | "bound_session"; problem: string };
+
+function isNonblankString(value: unknown): value is string {
+  return typeof value === "string" && value.trim() !== "";
+}
+
+/**
+ * Decide whether an existing session may enter refinement (contracts.md §8.67's warm
+ * admission), read STRICTLY over the rebuilt state + the run's launch handoff:
+ *  - an unsafe/missing run identity, a malformed claim / plan-ref / stage, or an unreadable
+ *    handoff → `bad_state` (never treated as absence);
+ *  - a sound active plan-ref, a planning claim, or a plan-bearing launch handoff (a plan-graph
+ *    stage, a planning link or an adoption source) → `bound_session` — nothing is cleared,
+ *    suspended or restored;
+ *  - otherwise admitted; `alreadyRefining` marks an explicit re-entry (a new grounding pass).
+ * The cached root plan-ref selector is never consulted. Pure.
+ */
+export function decideWarmRefinementAdmission(
+  state: WorkflowState,
+  handoff:
+    | { status: "absent" }
+    | { status: "present"; handoff: Handoff }
+    | { status: "unreadable" },
+): WarmRefinementAdmission {
+  const bad = (problem: string): WarmRefinementAdmission => ({
+    ok: false,
+    code: "bad_state",
+    problem,
+  });
+  const bound = (problem: string): WarmRefinementAdmission => ({
+    ok: false,
+    code: "bound_session",
+    problem,
+  });
+  const runId = state.run_id;
+  if (typeof runId !== "string" || !isSafeRunId(runId)) return bad("no safe session run identity");
+  const claim = state.objective_node_claim;
+  if (claim !== undefined && claim !== null) {
+    if (
+      typeof claim !== "object" ||
+      Array.isArray(claim) ||
+      !isNonblankString((claim as { objective?: unknown }).objective) ||
+      !isNonblankString((claim as { node?: unknown }).node)
+    )
+      return bad("the session's objective_node_claim is malformed");
+    return bound(
+      `this session carries a planning claim (objective ${(claim as { objective: string }).objective} node ${(claim as { node: string }).node})`,
+    );
+  }
+  const ref = state.active_plan_ref;
+  if (ref !== undefined && ref !== null) {
+    if (
+      typeof ref !== "object" ||
+      Array.isArray(ref) ||
+      !isNonblankString((ref as { provider?: unknown }).provider) ||
+      !isNonblankString((ref as { pr_id?: unknown }).pr_id)
+    )
+      return bad("the session's active_plan_ref is malformed");
+    return bound(
+      `this session is bound to plan ${(ref as { provider: string }).provider}:${(ref as { pr_id: string }).pr_id}`,
+    );
+  }
+  const stage = state.stage;
+  if (stage !== undefined && stage !== null && typeof stage !== "string")
+    return bad("the session's stage is malformed");
+  if (handoff.status === "unreadable") return bad("the run's launch handoff is unreadable");
+  if (handoff.status === "present") {
+    const h = handoff.handoff;
+    if (h.run_id !== runId) return bad("the run's launch handoff names another run");
+    if (isNonblankString(h.objective_id) || isNonblankString(h.node_id))
+      return bound("this session was launched with a planning link");
+    if (isNonblankString(h.adopt_from))
+      return bound("this session was launched as a plan adoption");
+    if (typeof h.stage === "string" && PLAN_BEARING_STAGES.includes(h.stage))
+      return bound(`this session was launched as a ${h.stage} session`);
+  }
+  if (typeof stage === "string" && PLAN_BEARING_STAGES.includes(stage))
+    return bound(`this session is a ${stage} session`);
+  const activeObjective = state.active_objective;
+  return {
+    ok: true,
+    runId,
+    activeObjective: isNonblankString(activeObjective) ? activeObjective : null,
+    alreadyRefining: stage === REFINE_STAGE,
+  };
+}
+
+/** Read the run's handoff strictly: ENOENT is `absent`; any other failure is `unreadable`. */
+function readHandoffStrict(
+  cwd: string,
+  runId: string,
+): { status: "absent" } | { status: "present"; handoff: Handoff } | { status: "unreadable" } {
+  let raw: string;
+  try {
+    raw = readFileSync(handoffPath(cwd, runId), "utf8");
+  } catch (error) {
+    if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT")
+      return { status: "absent" };
+    return { status: "unreadable" };
+  }
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+      return { status: "unreadable" };
+    const h = parsed as Record<string, unknown>;
+    if (typeof h.run_id !== "string") return { status: "unreadable" };
+    return { status: "present", handoff: h as unknown as Handoff };
+  } catch {
+    return { status: "unreadable" };
+  }
+}
+
+// ---------------------------------------------------------------- the cold-door adapters
+
+/** The decoded `perk objective refine-context --json` envelope slice. */
+interface RefineContextPayload {
+  contextJson: string;
+  contextDigest: string;
+}
+
+function decodeRefineContext(payload: ColdJson): RefineContextPayload | null {
+  const contextJson = stringField(payload, "context_json");
+  const contextDigest = stringField(payload, "context_digest");
+  if (contextJson === undefined || contextDigest === undefined) return null;
+  return { contextJson, contextDigest };
+}
+
+/**
+ * The warm context worker: `perk objective refine-context <objective> [--node ID] --run-id RID
+ * --json` — the context is a JSON STRING inside the envelope (never re-encoded here).
+ */
+async function fetchRefinementContext(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  req: { objective: string; node: string | null; runId: string },
+): Promise<
+  | { ok: true; contextJson: string; contextDigest: string }
+  | { ok: false; message: string; errorType: string }
+> {
+  const args = ["objective", "refine-context", req.objective];
+  if (req.node !== null) args.push("--node", req.node);
+  args.push("--run-id", req.runId, "--json");
+  const r = await runColdDoor<RefineContextPayload>(pi, ctx, args, {
+    label: "perk objective refine-context",
+    decode: decodeRefineContext,
+  });
+  if (!r.ok) return { ok: false, message: r.message, errorType: r.errorType };
+  return { ok: true, contextJson: r.data.contextJson, contextDigest: r.data.contextDigest };
+}
+
+/** The decoded `perk objective refinement-save --json` success payload. */
+interface RefinementSavePayload {
+  commentId: string;
+  carrierUrl: string;
+  carrierIdentifier: string;
+  objectiveId: string;
+  objectiveRunId: string;
+  nodeId: string;
+  bodyDigest: string;
+  savedAt: string;
+  authoredAt: string;
+}
+
+function decodeRefinementSave(payload: ColdJson): RefinementSavePayload | null {
+  const fields = [
+    "comment_id",
+    "carrier_url",
+    "carrier_identifier",
+    "objective_id",
+    "objective_run_id",
+    "node_id",
+    "body_digest",
+    "saved_at",
+    "authored_at",
+  ] as const;
+  const values: Record<string, string> = {};
+  for (const key of fields) {
+    const value = stringField(payload, key);
+    if (value === undefined) return null;
+    values[key] = value;
+  }
+  return {
+    commentId: values.comment_id as string,
+    carrierUrl: values.carrier_url as string,
+    carrierIdentifier: values.carrier_identifier as string,
+    objectiveId: values.objective_id as string,
+    objectiveRunId: values.objective_run_id as string,
+    nodeId: values.node_id as string,
+    bodyDigest: values.body_digest as string,
+    savedAt: values.saved_at as string,
+    authoredAt: values.authored_at as string,
+  };
+}
+
+/**
+ * The production `RefinementBackend` over the Python worker (`perk objective refinement-save
+ * --run-id RID --json` via the shared cold-door client; the EXACT draft bytes ride the
+ * run-scratch `--draft-file` channel). The worker reads the bound context from the run's
+ * session data itself — no caller-supplied context path, target or expectation. Failures keep
+ * the worker's typed diagnostics (`write_attempted`, `comment_ids`) beside the message.
+ */
+export function coldDoorRefinementBackend(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+): RefinementBackend {
+  return {
+    async save(req) {
+      const r = await runColdDoor<RefinementSavePayload>(
+        pi,
+        ctx,
+        ["objective", "refinement-save", "--run-id", req.runId, "--json"],
+        {
+          label: "perk objective refinement-save",
+          decode: decodeRefinementSave,
+          stdin: {
+            flag: "--draft-file",
+            content: req.draftRaw,
+            filename: REFINEMENT_DRAFT_ARTIFACT,
+          },
+        },
+      );
+      if (!r.ok) {
+        const attempted =
+          r.payload === undefined ? undefined : booleanField(r.payload, "write_attempted");
+        return {
+          status: "failed",
+          message: r.message,
+          errorType: r.errorType,
+          writeAttempted: attempted ?? null,
+          commentIds: r.payload === undefined ? [] : stringListField(r.payload, "comment_ids"),
+        };
+      }
+      const d = r.data;
+      return {
+        status: "saved",
+        commentId: d.commentId,
+        carrierUrl: d.carrierUrl,
+        carrierIdentifier: d.carrierIdentifier,
+        objectiveId: d.objectiveId,
+        objectiveRunId: d.objectiveRunId,
+        nodeId: d.nodeId,
+        bodyDigest: d.bodyDigest,
+        savedAt: d.savedAt,
+        authoredAt: d.authoredAt,
+      };
+    },
+  };
+}
+
+// ------------------------------------------------------------------------- result envelopes
+
+/** The ok-arm fields of a verified refinement save (the structured `details` surface). */
+export interface RefinementSaveOk {
+  refinement: {
+    comment_id: string;
+    carrier_url: string;
+    carrier_identifier: string;
+    objective_id: string;
+    objective_run_id: string;
+    node_id: string;
+    body_digest: string;
+    saved_at: string;
+    authored_at: string;
+  };
+  advisory: true;
+}
+
+export type RefinementSaveResult = Result<
+  RefinementSaveOk,
+  { write_attempted: boolean | null; comment_ids: string[] }
+>;
+
+/**
+ * Render a backend save outcome as the warm-door Result envelope — the ONE result-construction
+ * site for every refinement save surface (review arm + human command). A verified save says
+ * ADVISORY content — not an executable plan — was saved and terminates; a failure reports
+ * through `failFor` with the worker's diagnostics retained (never "nothing saved", never a
+ * blind-retry prescription).
+ */
+export function refinementSaveResultOf(
+  ctx: ExtensionContext,
+  save: RefinementBackendSaveResult,
+): RefinementSaveResult {
+  if (save.status === "failed") {
+    return failFor<{ write_attempted: boolean | null; comment_ids: string[] }>(ctx, SCOPE_SAVE)(
+      save.message,
+      save.errorType,
+      {
+        write_attempted: save.writeAttempted,
+        comment_ids: save.commentIds,
+      },
+    );
+  }
+  return ok(
+    `Saved refinement for objective ${save.objectiveId} node ${save.nodeId} → comment ` +
+      `${save.commentId} on ${save.carrierIdentifier} (${save.carrierUrl}); body digest ` +
+      `${save.bodyDigest}; saved at ${save.savedAt}.\n` +
+      "ADVISORY content — not an executable plan — was saved: no plan was created, no node was " +
+      "claimed, and no node/objective state changed.",
+    {
+      refinement: {
+        comment_id: save.commentId,
+        carrier_url: save.carrierUrl,
+        carrier_identifier: save.carrierIdentifier,
+        objective_id: save.objectiveId,
+        objective_run_id: save.objectiveRunId,
+        node_id: save.nodeId,
+        body_digest: save.bodyDigest,
+        saved_at: save.savedAt,
+        authored_at: save.authoredAt,
+      },
+      advisory: true,
+    },
+    { terminate: true },
+  );
+}
+
+// ------------------------------------------------------------------------- adapter plumbing
+
+function openSession(pi: ExtensionAPI, ctx: ExtensionContext): WorkflowSession {
+  return openBranchWorkflowSession(pi, ctx);
+}
+
+function gateFor(gating: ToolGating, ctx: ExtensionContext): ApprovalGate {
+  return { isActive: () => gating.isActive(), exit: () => gating.exit(ctx) };
+}
+
+/** Whether the branch is a refinement session (stage match; the gate is checked separately). */
+export function isRefinementSession(branch: readonly BranchEntry[]): boolean {
+  return rebuildWorkflowState(branch).stage === REFINE_STAGE;
+}
+
+function inRefinementStage(ctx: ExtensionContext): boolean {
+  try {
+    return isRefinementSession(branchOf(ctx));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The cold claim's one-time context import (called from `session_start` right after a
+ * successful claim): reads the consumed handoff back for its namespaced block, then imports the
+ * fixed run-scratch transfer. A refusal is reported loudly; the session stays gated and no
+ * draft can be written until a grounding pass supplies a valid context. Never throws.
+ */
+export function importRefinementContextOnClaim(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  claim: { runId: string; stage: string | undefined },
+): void {
+  if (claim.stage !== REFINE_STAGE) return;
+  try {
+    const handoff = readHandoff(ctx.cwd, claim.runId);
+    if (handoff === null) {
+      report(
+        ctx,
+        SCOPE_REFINE,
+        "error",
+        "context import refused — the run's handoff is unreadable",
+        {
+          alsoLog: true,
+        },
+      );
+      return;
+    }
+    const transferPath = join(runScratchDir(ctx.cwd, claim.runId), REFINEMENT_CONTEXT_ARTIFACT);
+    const imported = importColdRefinementContext(
+      openSession(pi, ctx),
+      { runId: claim.runId, stage: claim.stage, handoff },
+      {
+        readTransfer() {
+          try {
+            // Fatal decoding: malformed UTF-8 is a refusal, never a silent U+FFFD substitution.
+            return new TextDecoder("utf-8", { fatal: true }).decode(readFileSync(transferPath));
+          } catch (error) {
+            if (
+              typeof error === "object" &&
+              error !== null &&
+              "code" in error &&
+              error.code === "ENOENT"
+            )
+              return null;
+            throw error;
+          }
+        },
+      },
+    );
+    if (imported.status === "refused") {
+      report(ctx, SCOPE_REFINE, "error", `context import refused — ${imported.problem}`, {
+        alsoLog: true,
+      });
+    }
+  } catch (error) {
+    report(ctx, SCOPE_REFINE, "error", `context import failed — ${String(error)}`, {
+      alsoLog: true,
+    });
+  }
+}
+
+// ------------------------------------------------------------------------------ the installer
+
+/**
+ * Install every refinement Pi binding: the refinement context hook pair, the
+ * `objective_refinement_draft` tool, the warm `/objective-refine` entry and the human
+ * `/objective-refinement-save` failsafe. Inert outside refinement sessions; never throws.
+ */
+export function installObjectiveRefinementBindings(
+  pi: ExtensionAPI,
+  gating: ToolGating,
+  reviews: DraftReviewSlot,
+  runnerChild: () => boolean,
+): void {
+  // The refinement context is keyed off (the gate active AND the refinement stage on the FULL
+  // branch — the module's own `isRefinementSession`); once the approved save exits the gate the
+  // selection turns null and the shared helper retires the owned copy. The runner fence lives in
+  // the shared helper.
+  installInjectedContext(
+    pi,
+    {
+      customType: REFINEMENT_CONTEXT_TYPE,
+      flavors: {
+        [REFINEMENT_MARKER]: (ctx) =>
+          refinementContextContent(loadPerkConfig(ctx.cwd).planAuthoring),
+      },
+      select: (_ctx, branch) =>
+        gating.isActive() && isRefinementSession(branch) ? REFINEMENT_MARKER : null,
+    },
+    runnerChild,
+  );
+
+  pi.registerTool({
+    name: "objective_refinement_draft",
+    label: "Refinement draft",
+    description:
+      "Write (or overwrite) the working objective-node refinement — the advisory Markdown — to " +
+      "the session data dir, bound to this session's grounding context. The only sanctioned " +
+      "write surface in a refinement session. NOT a save: an APPROVED plan_review, or the " +
+      "human's /objective-refinement-save, persists the node's refinement comment.",
+    promptSnippet:
+      "Persist the working refinement Markdown to the session data dir (full rewrite, context-bound)",
+    promptGuidelines: REFINEMENT_DRAFT_TOOL_GUIDELINES,
+    executionMode: "sequential",
+    parameters: {
+      type: "object",
+      additionalProperties: false,
+      required: ["markdown"],
+      properties: {
+        markdown: {
+          type: "string",
+          description:
+            "The full refinement Markdown: what the node must deliver, the prerequisites that " +
+            "do not exist yet, the code seams as observed at capture time, the risks, and the " +
+            "assumptions a later real plan must re-verify.",
+        },
+      },
+    },
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const fail = failFor(ctx, "objective-refinement-draft", "objective_refinement_draft");
+      const decoded = decodeRefinementDraftParams(params);
+      if (decoded === null)
+        return fail("objective_refinement_draft needs { markdown: string }", "bad_input");
+      // Independent of tool visibility: the draft writer only exists inside a refinement session.
+      if (!inRefinementStage(ctx))
+        return fail(
+          "objective_refinement_draft is only available in an objective-refine session " +
+            "(enter one with perk objective refine <objective> or /objective-refine)",
+          "wrong_stage",
+        );
+      const revised = reviseRefinementDraft(decoded, openSession(pi, ctx));
+      switch (revised.status) {
+        case "revised":
+        case "unchanged": {
+          const c = revised.context.context;
+          return ok(
+            `Refinement draft written → ${revised.receipt.path} (${revised.receipt.digest}); ` +
+              `bound to objective ${c.objective.id} node ${c.target.identity.node_id} ` +
+              `(context ${revised.context.digest})`,
+            {
+              name: REFINEMENT_DRAFT_ARTIFACT,
+              path: revised.receipt.path,
+              digest: revised.receipt.digest,
+              bytes: revised.bytes,
+              run_id: revised.receipt.runId,
+              context_digest: revised.context.digest,
+              objective_id: c.objective.id,
+              node_id: c.target.identity.node_id,
+              unchanged: revised.status === "unchanged",
+            },
+          );
+        }
+        case "rejected":
+          return fail(
+            revised.problem,
+            revised.reason === "blank_markdown"
+              ? "invalid_input"
+              : revised.reason === "no_identity"
+                ? "no_run_id"
+                : revised.reason === "no_context"
+                  ? "refinement_context_missing"
+                  : revised.reason === "context_refused"
+                    ? "refinement_context_invalid"
+                    : "write_failed",
+          );
+        case "unverified":
+          return fail(revised.problem, "write_failed");
+      }
+    },
+  });
+
+  registerPerkCommand(pi, "objective-refine", {
+    description:
+      "Enter an objective-node refinement pass in this session: [objective] [--node ID] " +
+      "(else the active objective; the first refinable future node). Read-only.",
+    handler: async (args, ctx) => {
+      const warn = (message: string) => report(ctx, SCOPE_REFINE, "warning", message);
+      const parsed = parseRefineCommandArgs(args ?? "");
+      if (!parsed.ok) {
+        warn(`${parsed.problem}. Usage: /objective-refine [objective] [--node ID]`);
+        return;
+      }
+      if (!ctx.isIdle()) {
+        warn("the model is running — wait for the turn to finish, then re-run /objective-refine");
+        return;
+      }
+      const state = rebuildWorkflowState(branchOf(ctx));
+      const runIdForHandoff = typeof state.run_id === "string" ? state.run_id : "";
+      const admission = decideWarmRefinementAdmission(
+        state,
+        runIdForHandoff && isSafeRunId(runIdForHandoff)
+          ? readHandoffStrict(ctx.cwd, runIdForHandoff)
+          : { status: "absent" },
+      );
+      const objectiveHint = parsed.objective ?? "<objective>";
+      if (!admission.ok) {
+        warn(
+          `${admission.problem} — refusing (${admission.code}). Start a fresh session with ` +
+            `\`perk objective refine ${objectiveHint}${parsed.node ? ` --node ${parsed.node}` : ""}\`.`,
+        );
+        return;
+      }
+      const objective = parsed.objective ?? admission.activeObjective;
+      if (objective === null) {
+        warn(
+          "no objective given and none active (objective_required). Use " +
+            "`/objective-refine <objective> [--node ID]`.",
+        );
+        return;
+      }
+      report(
+        ctx,
+        SCOPE_REFINE,
+        "info",
+        `${objective}${parsed.node ? ` node ${parsed.node}` : ""}${admission.alreadyRefining ? " (new grounding pass)" : ""}`,
+      );
+      const fetched = await fetchRefinementContext(pi, ctx, {
+        objective,
+        node: parsed.node,
+        runId: admission.runId,
+      });
+      if (!fetched.ok) {
+        report(ctx, SCOPE_REFINE, "error", `${fetched.message} (${fetched.errorType})`, {
+          alsoLog: true,
+        });
+        return;
+      }
+      const validated = validateContextTransfer(fetched.contextJson, {
+        runId: admission.runId,
+        expectedDigest: fetched.contextDigest,
+      });
+      if (!validated.ok) {
+        report(
+          ctx,
+          SCOPE_REFINE,
+          "error",
+          `the prepared context is invalid — ${validated.problem} (refinement_context_invalid)`,
+          { alsoLog: true },
+        );
+        return;
+      }
+      // Recheck the same run/admission against LIVE state, persist the exact raw context, then
+      // the stage-only entry. A new grounding pass rebinds the reviewed context digest, so any
+      // open review's approval is refused by the reviewed-bytes guard (`draftReview.ts`).
+      type Entered =
+        | { status: "entered" | "unchanged"; path: string; read: RefinementContextRead }
+        | { status: "refused"; problem: string };
+      const enter = (session: WorkflowSession): Entered => {
+        const live = rebuildWorkflowState(branchOf(ctx));
+        const runId = typeof live.run_id === "string" ? live.run_id : "";
+        const again = decideWarmRefinementAdmission(
+          live,
+          runId && isSafeRunId(runId) ? readHandoffStrict(ctx.cwd, runId) : { status: "absent" },
+        );
+        if (!again.ok) return { status: "refused", problem: `${again.problem} (${again.code})` };
+        if (again.runId !== admission.runId)
+          return { status: "refused", problem: "the session identity changed (bad_state)" };
+        const imported = importRefinementContext(session, validated.read);
+        if (imported.status === "rejected" || imported.status === "unverified")
+          return {
+            status: "refused",
+            problem: `could not persist the context (${imported.problem})`,
+          };
+        const staged = session.apply({ kind: "enter-refinement-stage" });
+        if (staged.status === "rejected" || staged.status === "unverified")
+          return {
+            status: "refused",
+            problem:
+              `the context was persisted but the stage entry failed (${staged.problem}) — the ` +
+              "session is not in refinement; re-run /objective-refine",
+          };
+        return {
+          status:
+            imported.status === "unchanged" && staged.status === "unchanged"
+              ? "unchanged"
+              : "entered",
+          path: imported.receipt.path,
+          read: imported.read,
+        };
+      };
+      const entered = enter(openSession(pi, ctx));
+      if (entered.status === "refused") {
+        report(ctx, SCOPE_REFINE, "error", entered.problem, { alsoLog: true });
+        return;
+      }
+      // Enter/re-scope the gate for the refinement stage (its own allowlist + mode flavor), then
+      // drive the shared flow guidance. Failed setup above never reaches this point.
+      if (!gating.isActive()) gating.enter(ctx);
+      gating.syncFromState("read-only", REFINE_STAGE);
+      const c = entered.read.context;
+      report(
+        ctx,
+        SCOPE_REFINE,
+        "info",
+        `${entered.status === "unchanged" ? "context unchanged" : "context prepared"} for objective ` +
+          `${c.objective.id} node ${c.target.identity.node_id} (${c.target.status}` +
+          `${c.prior !== null ? "; re-refining a prior refinement" : ""}) → ${entered.path}; ` +
+          "read-only ON — author with objective_refinement_draft, review with plan_review.",
+      );
+      pi.sendUserMessage(
+        refinementGuidance(c, entered.path) + bindingSuffix(ctx.cwd, `stage:${REFINE_STAGE}`),
+      );
+    },
+  });
+
+  registerPerkCommand(pi, "objective-refinement-save", {
+    description:
+      "Save the current validated refinement draft as the node's refinement comment — the " +
+      "human's explicit save gesture (no arguments; artifact-first; refinement sessions only).",
+    handler: async (args, ctx) => {
+      const warn = (message: string) => report(ctx, SCOPE_SAVE, "warning", message);
+      if ((args ?? "").trim() !== "") {
+        warn("/objective-refinement-save takes no arguments (invalid_input)");
+        return;
+      }
+      if (!inRefinementStage(ctx)) {
+        warn(
+          "not an objective-refine session (wrong_stage) — nothing saved. Enter one with " +
+            "`perk objective refine <objective>` or /objective-refine.",
+        );
+        return;
+      }
+      if (!ctx.isIdle()) {
+        warn("the model is running (session_busy) — wait for the turn to finish, then re-run");
+        return;
+      }
+      // The command IS the human authorization — the deliberate retry the unconfirmed-save latch
+      // points at, so it never consults the latch (but reports into it). The shared seam
+      // strict-resumes both artifacts and saves the EXACT draft bytes; the gate exits only on a
+      // verified save.
+      const outcome = await refinementApprovalSave({
+        session: openSession(pi, ctx),
+        backend: coldDoorRefinementBackend(pi, ctx),
+        gate: gateFor(gating, ctx),
+      });
+      recordRefinementSaveOutcome(reviews, outcome);
+      switch (outcome.status) {
+        case "no-draft":
+          report(
+            ctx,
+            SCOPE_SAVE,
+            "error",
+            "no working refinement draft — nothing saved. Write it with objective_refinement_draft " +
+              "(the model's tool), then re-run /objective-refinement-save.",
+          );
+          return;
+        case "no-context":
+          report(
+            ctx,
+            SCOPE_SAVE,
+            "error",
+            "no refinement context in this session — nothing saved. Re-enter a grounding pass " +
+              "with /objective-refine, rewrite the draft, then re-run.",
+          );
+          return;
+        case "refused-draft":
+          report(
+            ctx,
+            SCOPE_SAVE,
+            "error",
+            `the working refinement draft is invalid: ${outcome.problem} — nothing saved. ` +
+              "Rewrite it with objective_refinement_draft, then re-run /objective-refinement-save.",
+          );
+          return;
+        case "source-changed":
+          // Unreachable without a `reviewed` pair (the manual save reviews nothing) — kept total.
+          report(ctx, SCOPE_SAVE, "error", "the refinement pair changed — nothing saved; re-run");
+          return;
+        case "saved": {
+          const result = refinementSaveResultOf(ctx, outcome.save);
+          // One headline line: the verified facts AND the advisory statement stay visible.
+          report(
+            ctx,
+            SCOPE_SAVE,
+            "info",
+            `manual human save (not a reviewer approval): ${(result.content[0]?.text ?? "saved").replace(/\n/g, " ")}`,
+          );
+          return;
+        }
+        case "save-failed": {
+          const s = outcome.save;
+          const diagnostics =
+            `write_attempted=${s.writeAttempted === null ? "unknown" : String(s.writeAttempted)}` +
+            (s.commentIds.length > 0 ? `; comment_ids=${s.commentIds.join(",")}` : "");
+          report(
+            ctx,
+            SCOPE_SAVE,
+            "error",
+            `manual save FAILED (${s.errorType}): ${s.message} [${diagnostics}] — the session ` +
+              "stays read-only; read the node's comments back and reconcile before another attempt.",
+          );
+          return;
+        }
+      }
+    },
+  });
+}
+
+/** Report a refinement approval-save outcome into the unconfirmed-save latch. */
+function recordRefinementSaveOutcome(
+  slot: DraftReviewSlot,
+  outcome: RefinementApprovalSaveOutcome,
+): void {
+  switch (outcome.status) {
+    case "saved":
+      recordSaveOutcome(slot, "refinement", { confirmed: true });
+      return;
+    case "save-failed":
+      recordSaveOutcome(slot, "refinement", {
+        confirmed: false,
+        detail: `${outcome.save.message} (write attempted: ${
+          outcome.save.writeAttempted === null ? "unknown" : String(outcome.save.writeAttempted)
+        })`,
+      });
+      return;
+    case "no-draft":
+    case "no-context":
+    case "refused-draft":
+    case "source-changed":
+      // Nothing reached the backend — no attempt to confirm.
+      return;
+  }
+}
+
+// ------------------------------------------------------------------------ the review arm
+
+/**
+ * The refinement review subject. It carries no static `saveDestination`: the first-party approve
+ * label names the bound context's carrier per backend (`refinementSaveDestination`), so every
+ * `verdictsFor` call for this subject spreads the derived destination in. The outcome texts read
+ * the other fields only.
+ */
+const REFINEMENT_SUBJECT: ReviewSubject = {
+  noun: "refinement",
+  present: "the complete refinement to the user",
+  presentUnavailable: "the complete refinement to the user",
+  implementHereWhere: "on the refinement path",
+  draftTool: "objective_refinement_draft",
+  failsafeCmd: "/objective-refinement-save",
+  detailsExtra: { subject: "refinement" },
+  noSourceError: "no refinement draft resolved",
+};
+
+/**
+ * The save destination the first-party approve verdict names, derived from the bound context's
+ * `identity.backend` (the carrier the save is bound to — never the checkout's `[issues]`
+ * config, which the service fences separately). Pure; never throws: an unrecognized backend id
+ * renders verbatim so the label never lies about where the save lands.
+ */
+export function refinementSaveDestination(backend: string): string {
+  switch (backend) {
+    case "linear":
+      return "Linear (the node's refinement comment)";
+    case "github":
+      return "GitHub (the objective issue's refinement comment)";
+    default:
+      return `${backend} (the node's refinement comment)`;
+  }
+}
+
+const REFINEMENT_REVIEW_EDITOR_TITLE =
+  "Refinement review (view only — edits are not saved) — Enter: continue to verdict · Esc: " +
+  "skip · Ctrl+G: $EDITOR";
+
+function noRefinementDraftResult(): ToolResult {
+  return {
+    content: [
+      {
+        type: "text",
+        text:
+          "no refinement draft to review — write the working refinement with " +
+          "objective_refinement_draft, then call plan_review again.",
+      },
+    ],
+    details: {
+      ok: false,
+      error: "no refinement draft to review — write it with objective_refinement_draft first",
+      error_type: "no_refinement_draft",
+      status: "skipped",
+      reason: "no_refinement_draft",
+      subject: "refinement",
+    },
+  };
+}
+
+function noRefinementContextResult(): ToolResult {
+  return {
+    content: [
+      {
+        type: "text",
+        text:
+          "no refinement context in this session — the working draft cannot be reviewed. " +
+          "Ask the human to re-enter a grounding pass with /objective-refine, then rewrite the " +
+          "draft with objective_refinement_draft and call plan_review again.",
+      },
+    ],
+    details: {
+      ok: false,
+      error: "no refinement context — a grounding pass is required",
+      error_type: "refinement_context_missing",
+      status: "skipped",
+      reason: "no_refinement_context",
+      subject: "refinement",
+    },
+  };
+}
+
+/** Translate a review-door outcome into the feature's `RefinementReviewOutcome`. */
+function refinementOutcomeOf(outcome: ReviewOutcome): RefinementReviewOutcome {
+  switch (outcome.status) {
+    case "completed": {
+      const carried = {
+        ...(outcome.feedback !== undefined ? { feedback: outcome.feedback } : {}),
+        reviewId: outcome.reviewId,
+      };
+      if (outcome.approved) {
+        if (outcome.feedback !== undefined && hasDirectEditsHeading(outcome.feedback))
+          return { status: "approvedDirectEdits", feedback: outcome.feedback, ...carried };
+        return { status: "approved", ...carried };
+      }
+      return { status: "denied", ...carried };
+    }
+    case "unavailable":
+      return { status: "unavailable", warning: outcome.warning };
+    case "aborted":
+      return { status: "aborted" };
+    case "dismissed":
+    case "implement-here":
+      return { status: "dismissed" };
+  }
+}
+
+/**
+ * The first-party reviewer: the in-TUI editor review, VIEW-ONLY (3 verdicts). Returns the door
+ * vocabulary (`ReviewOutcome`) so both arms share one ladder + completion path. The approve
+ * verdict names the bound context's carrier for `backend` (`refinementSaveDestination`), so the
+ * human approves a save to the place it actually lands.
+ */
+async function firstPartyRefinementReview(
+  ctx: ExtensionContext,
+  rendered: string,
+  signal: AbortSignal | undefined,
+  backend: string,
+): Promise<ReviewOutcome> {
+  const fp = await runFirstPartyReview({
+    ui: ctx.ui,
+    plan: rendered,
+    writeDraft: () => true,
+    signal,
+    editorTitle: REFINEMENT_REVIEW_EDITOR_TITLE,
+    verdicts: verdictsFor({
+      ...REFINEMENT_SUBJECT,
+      saveDestination: refinementSaveDestination(backend),
+    }),
+    viewOnly: true,
+  });
+  return fp.outcome;
+}
+
+/** Whether a completed bridge outcome's effect is a save (an approval without Direct Edits). */
+function refinementEffectOf(
+  outcome: Extract<ReviewOutcome, { status: "completed" }>,
+): "save" | "revision" {
+  return outcome.approved &&
+    !(outcome.feedback !== undefined && hasDirectEditsHeading(outcome.feedback))
+    ? "save"
+    : "revision";
+}
+
+/** Render a non-`proceed` ladder verdict as the refinement arm's tool result (nothing saved). */
+function refinementGuardResult(
+  check: Exclude<DecisionCheck, { kind: "proceed" }>,
+  review: OpenDraftReview,
+  feedback: string | undefined,
+): ToolResult {
+  switch (check.kind) {
+    case "superseded":
+      return supersededReviewResult("refinement");
+    case "save-unconfirmed":
+      return saveUnconfirmedResult("refinement", review.runId, check.detail, feedback);
+    case "stale-approval":
+      return staleApprovalResult("refinement", check.reviewedDigest, feedback);
+    case "destination-changed":
+      return destinationChangedResult("refinement", check.changed, feedback);
+  }
+}
+
+function completedOutcome(
+  approved: boolean,
+  carried: { feedback?: string; reviewId?: string },
+): Extract<ReviewOutcome, { status: "completed" }> {
+  return {
+    status: "completed",
+    approved,
+    ...(carried.feedback !== undefined ? { feedback: carried.feedback } : {}),
+    reviewId: carried.reviewId ?? "",
+  };
+}
+
+/**
+ * The `plan_review` refinement arm: headless soft-skip; the validated (draft, context) PAIR as
+ * the sole review source (a well-typed `plan` param is ignored upstream); the slot open with the
+ * exact pair (`raw` = the draft bytes, `contextDigest` = the grounding context's digest — the
+ * reviewed-bytes guard compares BOTH, so a re-prepared context also refuses the approval);
+ * reviewer dispatch (plannotator bridge or the first-party view-only editor); the decision
+ * ladder; the shared completion. An approval carrying Direct Edits returns the NON-terminating
+ * revise round with nothing saved; a plain approval re-resumes the pair through
+ * `refinementApprovalSave` with the reviewed pair as its content guard (gate released only after
+ * the verified save).
+ */
+export async function runRefinementReviewV1(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  gating: ToolGating,
+  bridge: DraftReviewBridge,
+  slot: DraftReviewSlot,
+  signal?: AbortSignal,
+): Promise<ToolResult> {
+  if (!ctx.hasUI) return skipResult();
+  const sig = signal ?? ctx.signal;
+  if (sig?.aborted) return subjectReviewOutcomeResult(REFINEMENT_SUBJECT, { status: "aborted" });
+  const session = openSession(pi, ctx);
+  const resumed = resumeRefinementDraft(session);
+  if (resumed.kind === "absent") return noRefinementDraftResult();
+  if (resumed.kind === "no-context") return noRefinementContextResult();
+  if (resumed.kind === "refused" || resumed.kind === "mismatch")
+    return renderRefinementReviewResult(ctx, { status: "refusedDraft", problem: resumed.problem });
+  const reviewed = reviewedPairOf(resumed.pair);
+  const rendered = renderRefinementDraft(resumed.pair);
+  const plannotator = isPlannotatorPlanSelected(ctx.cwd);
+  const opened = slot.open(ctx, {
+    subject: "refinement",
+    source: plannotator ? "artifact" : "editor",
+    raw: reviewed.draftRaw,
+    markdown: rendered,
+    contextDigest: reviewed.contextDigest,
+  });
+  if (!opened.ok) return openRefusedResult(opened);
+  const review = opened.review;
+  const outcome = plannotator
+    ? await bridge.review(rendered, sig)
+    : await firstPartyRefinementReview(
+        ctx,
+        rendered,
+        sig,
+        resumed.pair.context.context.target.identity.backend,
+      );
+  if (sig?.aborted) return subjectReviewOutcomeResult(REFINEMENT_SUBJECT, { status: "aborted" });
+  if (outcome.status !== "completed")
+    return subjectReviewOutcomeResult(REFINEMENT_SUBJECT, outcome);
+  const check = checkDraftReviewDecision(slot, ctx, review, refinementEffectOf(outcome));
+  if (check.kind !== "proceed") return refinementGuardResult(check, review, outcome.feedback);
+  return withDraftChangedNote(
+    await completeRefinementReviewV1(pi, ctx, gating, slot, outcome, reviewed),
+    check.draftChanged,
+  );
+}
+
+export function renderRefinementReviewResult(
+  ctx: ExtensionContext,
+  result: ReviewRefinementResult,
+): ToolResult {
+  switch (result.status) {
+    case "noDraft":
+      return noRefinementDraftResult();
+    case "noContext":
+      return noRefinementContextResult();
+    case "refusedDraft":
+      return {
+        content: [
+          {
+            type: "text",
+            text:
+              `the working refinement draft is invalid: ${result.problem} — rewrite it with ` +
+              "objective_refinement_draft, then call plan_review again.",
+          },
+        ],
+        details: {
+          ok: false,
+          error: result.problem,
+          error_type: "bad_state",
+          status: "skipped",
+          reason: "refinement_draft_refused",
+          subject: "refinement",
+        },
+      };
+    case "directEditsRevise":
+      return {
+        content: [
+          {
+            type: "text",
+            text:
+              "refinement APPROVED with direct browser edits — nothing was saved. Fold the " +
+              "Markdown hunks below into one objective_refinement_draft rewrite; hunks against " +
+              "the header (objective, node, carrier, pass time, checkout observation) are bound " +
+              "metadata — they need a new grounding pass (/objective-refine), never fabricated " +
+              `values. Then call plan_review again to confirm.\n\nReviewer feedback:\n${result.feedback}`,
+          },
+        ],
+        details: {
+          ok: true,
+          status: "revise",
+          reason: "direct_edits",
+          approved: true,
+          feedback: result.feedback,
+          reviewId: result.reviewId,
+          subject: "refinement",
+        },
+      };
+    case "approvedSaved":
+      return approvedSubjectSaveResult(REFINEMENT_SUBJECT, completedOutcome(true, result), {
+        status: "saved",
+        result: refinementSaveResultOf(ctx, result.save.save),
+        gateExited: result.save.gateExited,
+      });
+    case "approvedSaveFailed":
+      return approvedSubjectSaveResult(REFINEMENT_SUBJECT, completedOutcome(true, result), {
+        status: "save-failed",
+        result: refinementSaveResultOf(ctx, result.save.save),
+        gateExited: false,
+      });
+    case "approvedNoDraft":
+      return approvedSubjectSaveResult(REFINEMENT_SUBJECT, completedOutcome(true, result), {
+        status: "no-source",
+      });
+    case "approvedRefusedDraft":
+      return approvedSubjectSaveResult(REFINEMENT_SUBJECT, completedOutcome(true, result), {
+        status: "refused-draft",
+        problem: result.problem,
+      });
+    case "approvedSourceChanged": {
+      const what =
+        result.changed === "context"
+          ? "grounding context was re-prepared"
+          : "working draft was rewritten";
+      return {
+        content: [
+          {
+            type: "text",
+            text:
+              `refinement APPROVED by reviewer, but the ${what} after the reviewed version was ` +
+              "shown — nothing was saved and the session stays read-only. An approval never " +
+              "transfers to a replacement: call plan_review again over the current draft.",
+          },
+        ],
+        details: {
+          ok: false,
+          status: "stale",
+          reason: "source_changed",
+          changed: result.changed,
+          approved: true,
+          ...(result.feedback !== undefined ? { feedback: result.feedback } : {}),
+          ...(result.reviewId !== undefined ? { reviewId: result.reviewId } : {}),
+          subject: "refinement",
+        },
+      };
+    }
+    case "denied":
+      return subjectReviewOutcomeResult(REFINEMENT_SUBJECT, completedOutcome(false, result));
+    case "dismissed":
+      return subjectReviewOutcomeResult(REFINEMENT_SUBJECT, { status: "dismissed" });
+    case "aborted":
+      return subjectReviewOutcomeResult(REFINEMENT_SUBJECT, { status: "aborted" });
+    case "unavailable":
+      return subjectReviewOutcomeResult(REFINEMENT_SUBJECT, {
+        status: "unavailable",
+        warning: result.warning,
+      });
+  }
+}
+
+/**
+ * The refinement completion shared by the tool arm and any door: a completed outcome → the
+ * feature completion (an approval re-resumes the pair through `refinementApprovalSave`, the
+ * `reviewed` pair its content guard — a replacement written during the wait is the
+ * `approvedSourceChanged` arm; Direct Edits is the no-save revise round) → the latch record →
+ * the rendered tool result. A failed worker surfaces as the feature's own `approvedSaveFailed`
+ * (its typed diagnostics ride the rendered save message).
+ */
+export async function completeRefinementReviewV1(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  gating: ToolGating,
+  slot: DraftReviewSlot,
+  outcome: Extract<ReviewOutcome, { status: "completed" }>,
+  reviewed: ReviewedRefinementPair,
+): Promise<ToolResult> {
+  const result = await completeRefinementReview(refinementOutcomeOf(outcome), () =>
+    refinementApprovalSave({
+      session: openSession(pi, ctx),
+      backend: coldDoorRefinementBackend(pi, ctx),
+      gate: gateFor(gating, ctx),
+      reviewed,
+    }),
+  );
+  // Denials, Direct Edits and the no-draft arm never reach the backend — nothing to confirm.
+  if (result.status === "approvedSaved" || result.status === "approvedSaveFailed")
+    recordRefinementSaveOutcome(slot, result.save);
+  return renderRefinementReviewResult(ctx, result);
+}
+
+/** The refusal text the plan-graph surfaces render inside a refinement session. */
+export { refinementStageRefusal };