@mgiles/perk 1.0.1

package/extension/factories/planSave.ts

@@ -0,0 +1,589 @@
+// The warm `/plan-save` door (turn-3 §5/§6). The in-session twin of the Python cold
+// door (`perk plan save`): a deterministic, terminating tool + command that WRAP the existing
+// storage — they do NOT reimplement the GitHub write. `savePlan()` delegates to `perk plan save
+// --json` via the shared cold-door client (`runColdDoor` — the plan markdown rides the run-scratch
+// stdin channel), then appends `active_plan_ref` so the live session is linked immediately
+// (strict read-back, idempotent, headless-safe). Failures are loud-but-non-fatal — never throw.
+//
+// FILE-FIRST PLAN SOURCE. Both surfaces resolve their plan through
+// `resolvePlanSource`: the validated `plan-draft.md` artifact (`readSessionArtifact`,
+// digest-validated, fail-open) wins; the explicit `plan` param (tool only, now optional) is the
+// fallback for sessions that never wrote a draft; `extractPlanMarkdown` (the transcript scrape)
+// is the universal last resort. A differing ignored param is surfaced, never silent.
+//
+// APPROVAL→SAVE ORCHESTRATION. The exported `approvalSave` seam is the shared
+// APPROVED-review → save flow: artifact-first resolution → `savePlan` (warm node-link recovery
+// inside, from the `objective_node_claim` carrier) → gate exit on a successful save (D1a). The
+// `/plan-save` command is the MANUAL FAILSAFE invocation of the same seam; the review backends
+// (plannotator / first-party / tombell) wire their APPROVED outcome into it.
+//
+// SEAM-SHARED SUBSTRATE. `savePlan`/the `plan_save` tool/`/plan-save`/the read-only gate
+// are the produced-contract landing for the PLAN seam (`adapter-architecture.md` Invariant 1) — the
+// adapter bridges a foreign plan surface *to* `plan_save`/`cache.plan-ref`/the gate, so
+// they must stay always-registered. They do NOT defer when a foreign `[providers] plan` is selected
+// — only perk's own authoring surface (`extension/factories/planMode.ts`: `/plan`, `Ctrl+Alt+P`, `--plan`,
+// the `perk:plan-context` injection) steps aside. Deferring this substrate would break the adapter.
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { PlanRef } from "../substrate/cache.ts";
+import {
+  booleanField,
+  type ColdJson,
+  nullableStringField,
+  objectField,
+  runColdDoor,
+  stringField,
+} from "../substrate/coldDoor.ts";
+import { failFor, ok, type Result } from "../substrate/result.ts";
+import { readSessionArtifact, type SessionDataCtx } from "../substrate/sessionData.ts";
+import type { ToolGating } from "../substrate/toolGating.ts";
+import { idArrayParam, paramsOf, stringParam } from "../substrate/toolParams.ts";
+import {
+  appendWorkflowState,
+  type BranchEntry,
+  branchOf,
+  planRefsEqual,
+  rebuildWorkflowState,
+} from "../substrate/workflowState.ts";
+import { report, type Severity } from "../surfaces/report.ts";
+import { nodeClaimsEqual, readNodeClaim } from "./objectivePlan.ts";
+import { PLAN_DRAFT_ARTIFACT } from "./planDraft.ts";
+import { generatePlanTitle } from "./planTitle.ts";
+
+/** The ok-arm fields (turn-3 D6) — the `details` surface doubles as branch-safe persisted state. */
+export interface PlanSaveOk {
+  /** `issue.id` is the opaque string issue id (GitHub "42", Linear "ENG-123") — §8.21. */
+  issue: { id: string; url: string };
+  plan_ref: PlanRef;
+  cached: boolean;
+  existed: boolean | null;
+  updated: boolean;
+  objective_node: ObjectiveNodeLink | null;
+  plan_source: PlanSource | null;
+}
+
+/** The atomic objective node→plan commit surfaced by `perk plan save`. */
+export interface ObjectiveNodeLink {
+  linked: boolean;
+  node: string | null;
+  status: string | null;
+  error: string | null;
+}
+
+/** A tool result patch (AgentToolResult has no `isError`; failure is signaled via details.ok). */
+export type SaveResult = Result<PlanSaveOk>;
+export type PlanSaveDetails = SaveResult["details"];
+
+/**
+ * The decoded `perk plan save --json` payload slice the warm door consumes. Decode policy
+ * (`docs/learned/workflow/cold-door-client.md`: strict iff appended to workflow-state): only
+ * `plan_ref` is strict. The rendered `issue.id`/`url` are DERIVED from the strict ref — the cold
+ * door constructs the ref from the issue (`pr_id == issue.id`, `url == issue.url`), so they are
+ * byte-identical by construction; `existed` and `objective_node` are advisory.
+ */
+interface PlanSavePayload {
+  issue: { id: string; url: string; existed: boolean | undefined };
+  plan_ref: PlanRef;
+  cached?: boolean;
+  updated?: boolean;
+  objective_node: ObjectiveNodeLink | null;
+}
+
+/**
+ * Fully strict `plan_ref` decode — a half-formed ref appended to workflow-state would poison
+ * `planRefsEqual` and every downstream consumer, so any miss → null → bad_output.
+ */
+function decodePlanRef(payload: ColdJson): PlanRef | null {
+  const ref = objectField(payload, "plan_ref");
+  if (ref === undefined) return null;
+  const provider = stringField(ref, "provider");
+  const prId = stringField(ref, "pr_id");
+  const url = stringField(ref, "url");
+  const labels = ref.labels;
+  const objectiveId = nullableStringField(ref, "objective_id");
+  if (
+    provider === undefined ||
+    prId === undefined ||
+    url === undefined ||
+    !Array.isArray(labels) ||
+    !labels.every((l) => typeof l === "string") ||
+    objectiveId === undefined
+  ) {
+    return null;
+  }
+  // `base` stays Python-owned for all behavior; carrying it keeps the workflow-state
+  // `active_plan_ref` copy byte-consistent with the cold door's `--json` plan_ref. Parity-only +
+  // lenient: a present null/string is carried, an absent/mistyped value is simply omitted (never a
+  // decode failure — legacy plan-refs lack the field).
+  const base = nullableStringField(ref, "base");
+  return { provider, pr_id: prId, url, labels, objective_id: objectiveId, base };
+}
+
+/** Validate the optional `objective_node` sub-object; malformed → null (advisory, never fatal). */
+function decodeObjectiveNode(payload: ColdJson): ObjectiveNodeLink | null {
+  const node = objectField(payload, "objective_node");
+  if (node === undefined) return null;
+  const linked = booleanField(node, "linked");
+  const name = nullableStringField(node, "node");
+  const status = nullableStringField(node, "status");
+  const error = nullableStringField(node, "error");
+  if (linked === undefined || name === undefined || status === undefined || error === undefined) {
+    return null;
+  }
+  return { linked, node: name, status, error };
+}
+
+/**
+ * Narrow the `perk plan save --json` success payload. Strict ONLY on `plan_ref` (malformed →
+ * bad_output — it is appended to workflow-state, where a half-formed ref would poison
+ * `planRefsEqual`). The rendered issue id/url are derived from the strict ref instead of decoded
+ * independently — the cold door builds the ref FROM the issue, so they are byte-identical by
+ * construction; this makes any `issue` sub-object shape change (e.g. a `number`→`id`
+ * rename under CLI↔extension version skew) skew-harmless. `existed` and
+ * `objective_node` are advisory — the plan genuinely saved, so the success report must survive
+ * them. With `plan_ref` the only strict field, `bad_output` is reachable only for a payload whose
+ * persistence would corrupt workflow-state.
+ */
+function decodePlanSave(payload: ColdJson): PlanSavePayload | null {
+  const ref = decodePlanRef(payload);
+  if (ref === null) return null;
+  const issue = objectField(payload, "issue");
+  const existed = issue === undefined ? undefined : booleanField(issue, "existed");
+  return {
+    issue: { id: ref.pr_id, url: ref.url, existed },
+    plan_ref: ref,
+    cached: booleanField(payload, "cached"),
+    updated: booleanField(payload, "updated"),
+    objective_node: decodeObjectiveNode(payload),
+  };
+}
+
+/**
+ * Whether perk-owned plan mode is active — read from perk's OWN signal, the `read-only` `mode` of
+ * `perk:workflow-state` (the structural tool gate). This retires the soft coupling to
+ * `@tombell/pi-plan`'s `plan-mode-state` entry: perk now owns plan mode (`/plan` toggles
+ * `gating.enter`/`exit`, which append `mode`), so the gate's own field is the source of truth.
+ */
+export function isPlanModeActive(branch: readonly BranchEntry[]): boolean {
+  return rebuildWorkflowState(branch).mode === "read-only";
+}
+
+function textOf(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .map((block) => {
+      const b = block as { type?: string; text?: string };
+      return b.type === "text" && typeof b.text === "string" ? b.text : "";
+    })
+    .filter(Boolean)
+    .join("\n");
+}
+
+/**
+ * Best-effort, deterministic: the whole text of the latest assistant message, or null. This is
+ * the universal fail-open transcript FALLBACK behind the validated plan-draft
+ * artifact (see `resolvePlanSource`) — no longer the `/plan-save` command's primary plan source.
+ * Inherently fragile (it cannot tell a clean plan from conversation): keep the working draft
+ * current with `plan_draft` so the validated artifact wins. (There is no tag/marker convention to
+ * extract — the borrowed plan-mode package emits no structured plan, only free-form prose.)
+ */
+export function extractPlanMarkdown(entries: readonly unknown[]): string | null {
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const entry = entries[i] as { type?: string; message?: { role?: string; content?: unknown } };
+    if (entry.type !== "message" || entry.message?.role !== "assistant") continue;
+    const text = textOf(entry.message.content).trim();
+    if (!text) continue;
+    return text;
+  }
+  return null;
+}
+
+/** Where the saved plan bytes came from (the file-first resolution order). */
+export type PlanSource = "plan-draft" | "param" | "transcript";
+
+/**
+ * The shared plan-source resolver both save surfaces use — and the
+ * approval→save orchestration. Resolution order: (1) the validated `plan-draft.md`
+ * artifact (`readSessionArtifact`: digest-validated, fail-open — null on no run_id / no pointer
+ * / fork run_id mismatch / missing file / digest mismatch); (2) a non-blank explicit param;
+ * (3) the transcript scrape (`extractPlanMarkdown`); else null.
+ *
+ * `paramMismatch` is true iff the artifact won AND a non-blank explicit param was passed whose
+ * trimmed bytes differ from the artifact's — surfaced by `savePlan`, never silently dropped and
+ * never a hard-fail.
+ */
+export function resolvePlanSource(
+  ctx: SessionDataCtx,
+  explicit?: string,
+): { plan: string; source: PlanSource; paramMismatch: boolean } | null {
+  const artifact = readSessionArtifact(ctx, PLAN_DRAFT_ARTIFACT);
+  if (artifact !== null && artifact.content.trim().length > 0) {
+    const param = explicit?.trim() ?? "";
+    return {
+      plan: artifact.content,
+      source: "plan-draft",
+      paramMismatch: param.length > 0 && param !== artifact.content.trim(),
+    };
+  }
+  if (explicit !== undefined && explicit.trim().length > 0) {
+    return { plan: explicit, source: "param", paramMismatch: false };
+  }
+  const scraped = extractPlanMarkdown(branchOf(ctx));
+  if (scraped !== null) return { plan: scraped, source: "transcript", paramMismatch: false };
+  return null;
+}
+
+/**
+ * The single save implementation both surfaces call. Delegates the GitHub write to the Python
+ * cold door, then links the live session. Returns a soft result (never throws); failures set
+ * `details.ok = false` and append no linkage.
+ */
+export async function savePlan(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  opts: {
+    plan: string;
+    title?: string;
+    objectiveId?: string;
+    nodeId?: string;
+    consumedLearn?: string[];
+    /** The resolved plan source — surfaced in the message + details when non-param. */
+    source?: PlanSource;
+    /** A differing explicit param was ignored in favor of the artifact (visibly flagged). */
+    paramMismatch?: boolean;
+  },
+): Promise<SaveResult> {
+  const fail = failFor(ctx, "plan-save");
+
+  const plan = opts.plan.trim();
+  if (!plan) return fail("no plan markdown to save (propose a plan first)", "invalid_input");
+
+  // Forward an explicit title (previously accepted but DROPPED), else best-effort generate
+  // one via the session model. On any failure the cold door's `derive_title` fallback takes over.
+  const explicit = opts.title?.trim();
+  const title =
+    explicit && explicit.length > 0
+      ? explicit
+      : ((await generatePlanTitle(ctx, plan, ctx.signal)) ?? undefined);
+
+  const branch = (): BranchEntry[] => branchOf(ctx);
+  // No read-only fail-fast here (D1a): the `plan_save` TOOL is structurally unreachable while
+  // read-only (the read-only allowlist excludes it), so reaching savePlan via the tool means the gate is
+  // already off; the `/plan-save` COMMAND is allowed to run while read-only and the command handler
+  // exits the gate on a successful save (the read-only → read-write boundary in one gesture).
+  const runId = rebuildWorkflowState(branch()).run_id ?? "";
+
+  // Warm node-link recovery. When BOTH link params are absent (an
+  // approval-triggered save carries no model params), fill both-or-neither from the rebuilt
+  // `objective_node_claim`. Any explicit value (even one) wins outright — a half-specified link
+  // is the caller's, never mixed with the claim. Fail-open: a malformed/missing claim never
+  // blocks a save (readNodeClaim returns null). Mirrors the cold `_link_from_handoff`.
+  let objectiveId = opts.objectiveId;
+  let nodeId = opts.nodeId;
+  if (objectiveId === undefined && nodeId === undefined) {
+    const claim = readNodeClaim(ctx);
+    if (claim !== null) {
+      objectiveId = claim.objective;
+      nodeId = claim.node;
+    }
+  }
+
+  const args = ["plan", "save", "--json"];
+  if (runId) args.push("--run-id", runId);
+  // The resolved title (explicit or LLM-generated). When absent, the cold door derives it.
+  if (title) args.push("--title", title);
+  // The plan→objective link. The objective plan-factory passes the active objective
+  // number; non-objective plans omit it (unchanged behavior).
+  if (objectiveId) args.push("--objective-id", objectiveId);
+  // The objective plan factory passes the node id alongside the objective id; the cold
+  // door commits the node→plan backlink + `in_progress` advance atomically. Non-factory plans
+  // omit it (unchanged behavior).
+  if (nodeId) args.push("--node-id", nodeId);
+  // The learn-docs factory passes the consumed perk:learn issue numbers; docs plans land
+  // them (close + label perk:consolidated). Non-factory plans omit it (unchanged behavior).
+  if (opts.consumedLearn && opts.consumedLearn.length > 0) {
+    args.push("--consumed-learn", opts.consumedLearn.join(","));
+  }
+  const r = await runColdDoor<PlanSavePayload>(pi, ctx, args, {
+    label: "perk plan save",
+    decode: decodePlanSave,
+    stdin: { flag: "--plan-file", content: plan, filename: "plan.md" },
+  });
+  if (!r.ok) return fail(r.message, r.errorType);
+
+  // Link the live session (turn-3 D4): append iff the rebuilt ref differs, with a strict read-back.
+  const ref = r.data.plan_ref;
+  if (!planRefsEqual(rebuildWorkflowState(branch()).active_plan_ref ?? null, ref)) {
+    appendWorkflowState(pi, ctx, {
+      data: { active_plan_ref: ref },
+      field: "active_plan_ref",
+      expected: ref,
+      scope: "plan-save",
+      failure: `plan-ref read-back failed for ${ref.provider}:${ref.pr_id}`,
+      equals: planRefsEqual,
+    });
+  }
+
+  const verb = r.data.issue.existed ? "Updated" : "Saved";
+  const nodeLink = r.data.objective_node;
+  // A successful node-linked save clears the matching claim (best-effort —
+  // failure only risks a stale claim silently linking a later, unrelated save; surfaced via
+  // appendWorkflowState's report()). An unrelated claim is never clobbered.
+  if (nodeLink?.linked === true) {
+    const linkedNode = nodeLink.node ?? nodeId ?? null;
+    const claim = readNodeClaim(ctx);
+    if (linkedNode !== null && claim !== null && claim.node === linkedNode) {
+      appendWorkflowState(pi, ctx, {
+        data: { objective_node_claim: null },
+        field: "objective_node_claim",
+        expected: null,
+        scope: "plan-save",
+        failure: `objective_node_claim clear read-back failed for node ${linkedNode}`,
+        equals: nodeClaimsEqual,
+      });
+    }
+  }
+  // Render all THREE node-link outcomes (the silent-partial-failure fix). A failed advance
+  // (`linked: false`) is a non-fatal sub-step — the plan genuinely saved — but it must be VISIBLE
+  // (the §8.4 "warn + retriable" intent), not swallowed. Both surfaces render content[0].text, so
+  // this one site fixes the tool path (the model relays it) and the command path (the user sees the
+  // notify) at once.
+  let linkSuffix = "";
+  if (nodeLink?.linked === true) {
+    linkSuffix = ` · linked objective node ${nodeLink.node} → in_progress`;
+  } else if (nodeLink && nodeLink.linked === false) {
+    linkSuffix = ` · ⚠ objective node ${nodeLink.node} NOT advanced — re-run /plan-save to retry${
+      nodeLink.error ? ` (${nodeLink.error})` : ""
+    }`;
+  }
+  // Surface NON-param sources in the message (param-path success messages stay
+  // byte-stable); a differing ignored param is visibly flagged, never silent.
+  let sourceSuffix = "";
+  if (opts.source === "plan-draft" || opts.source === "transcript") {
+    sourceSuffix =
+      opts.source === "plan-draft"
+        ? " · plan source: plan-draft artifact"
+        : " · plan source: transcript";
+    if (opts.paramMismatch) {
+      sourceSuffix += " (⚠ differing plan param ignored — the validated artifact was saved)";
+    }
+  }
+  return ok(
+    `${verb} plan #${ref.pr_id} → ${ref.url}${sourceSuffix}${linkSuffix}`,
+    {
+      issue: { id: r.data.issue.id, url: r.data.issue.url },
+      plan_ref: ref,
+      cached: r.data.cached ?? false,
+      existed: r.data.issue.existed ?? null,
+      updated: r.data.updated ?? false,
+      objective_node: nodeLink,
+      plan_source: opts.source ?? null,
+    },
+    { terminate: true },
+  );
+}
+
+/** The approval→save orchestration outcome. */
+export type ApprovalSaveOutcome =
+  | { status: "no-plan" }
+  | { status: "saved" | "save-failed"; result: SaveResult; gateExited: boolean };
+
+/**
+ * The shared approval→save orchestration seam: an APPROVED review outcome
+ * (the `plan_review` door, planReview.ts — the plannotator bridge AND the first-party
+ * in-TUI editor review; tombell's re-aim is pending) and the manual `/plan-save`
+ * failsafe both run THIS. Flow: artifact-first plan resolution (`resolvePlanSource` — the reviewed plan text is
+ * the explicit fallback, the transcript scrape last) → `savePlan` (warm node-link recovery happens
+ * inside) → gate exit on a successful save while read-only (the D1a pattern: snapshot
+ * `gating.isActive()` before the save; a failed save leaves the gate ON). No resolvable plan
+ * source → `no-plan` (nothing saved, the gate untouched); callers render their own fallback.
+ * The returned `SaveResult` keeps `terminate: true` for tool-path callers (plannotator's
+ * approved arm propagates it).
+ */
+export async function approvalSave(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  gating: ToolGating,
+  opts: { reviewedPlan?: string; title?: string } = {},
+): Promise<ApprovalSaveOutcome> {
+  const src = resolvePlanSource(ctx, opts.reviewedPlan);
+  if (src === null) return { status: "no-plan" };
+  // D1a: snapshot the gate BEFORE the save; on success, exit it so save marks the read-only →
+  // read-write boundary in one gesture. A failed save leaves the gate on.
+  const wasReadOnly = gating.isActive();
+  const result = await savePlan(pi, ctx, {
+    plan: src.plan,
+    source: src.source,
+    paramMismatch: src.paramMismatch,
+    title: opts.title,
+  });
+  let gateExited = false;
+  if (result.details.ok && wasReadOnly) {
+    gating.exit(ctx);
+    gateExited = true;
+  }
+  return { status: result.details.ok ? "saved" : "save-failed", result, gateExited };
+}
+
+/** The decoded `plan_save` tool params (snake_case, as the schema declares them). */
+interface PlanSaveParams {
+  plan?: string;
+  title?: string;
+  objective_id?: string;
+  node_id?: string;
+  consumed_learn?: string[];
+}
+
+/**
+ * Decode unknown `plan_save` tool-call params (the tool-boundary seam). `plan` is
+ * optional (the validated plan-draft artifact is preferred) — absent decodes to
+ * `undefined`, but present-but-mistyped → null (strict-fail); the optional fields likewise.
+ */
+export function decodePlanSaveParams(params: unknown): PlanSaveParams | null {
+  const p = paramsOf(params);
+  if (p === null) return null;
+  const plan = stringParam(p, "plan");
+  if (plan === null) return null;
+  const title = stringParam(p, "title");
+  const objectiveId = stringParam(p, "objective_id");
+  const nodeId = stringParam(p, "node_id");
+  // Opaque string ids (§8.21); numbers are coerced — the learn-docs guidance renders bare
+  // numeric ids on GitHub, so the model may echo them un-quoted.
+  const consumedLearn = idArrayParam(p, "consumed_learn");
+  if (title === null || objectiveId === null || nodeId === null || consumedLearn === null) {
+    return null;
+  }
+  return {
+    plan: plan ?? undefined,
+    title,
+    objective_id: objectiveId,
+    node_id: nodeId,
+    consumed_learn: consumedLearn,
+  };
+}
+
+const TOOL_GUIDELINES = [
+  "Use plan_save only after the plan is decision-complete and the user has agreed; it creates the canonical GitHub plan and ends the turn.",
+  "Keep the working draft current with plan_draft — the validated plan-draft artifact is what plan_save saves; the `plan` parameter is only a fallback when no draft exists. Never reference line numbers — use durable anchors (function names, behavioral descriptions, structural locations).",
+  "Pass consumed_learn (the gathered perk:learn issue ids) only from the learned-docs factory — it links the issues the docs plan consolidates so /land closes + labels them.",
+  "When saving an objective-factory plan, pass BOTH objective_id and node_id — this links the node to the plan and advances it planning → in_progress (no separate backlink call).",
+];
+
+/** Register the warm door: the `plan_save` tool (canonical) + the `/plan-save` command twin. */
+export function registerPlanSave(pi: ExtensionAPI, gating: ToolGating): void {
+  pi.registerTool({
+    name: "plan_save",
+    label: "Save plan",
+    description:
+      "Persist the current plan to GitHub as the canonical perk plan and link this session to it. " +
+      "Terminating: ends the turn on save. Call only when the plan is decision-complete.",
+    promptSnippet: "Save the decision-complete plan to GitHub (terminates the turn)",
+    promptGuidelines: TOOL_GUIDELINES,
+    executionMode: "sequential",
+    parameters: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        plan: {
+          type: "string",
+          description:
+            "Optional — the validated plan-draft.md artifact is preferred when present; this " +
+            "param is the fallback for sessions that never wrote a draft (no line-number " +
+            "references).",
+        },
+        title: {
+          type: "string",
+          description: "Optional issue title (defaults to the plan's first heading).",
+        },
+        objective_id: {
+          type: "string",
+          description:
+            "Optional objective issue number to link this plan to (the objective plan factory " +
+            "passes the active objective; omit for a standalone plan).",
+        },
+        node_id: {
+          type: "string",
+          description:
+            "Objective node id to commit on save — the objective plan factory passes it with " +
+            "`objective_id` (links the node and advances it to `in_progress`); omit for a " +
+            "standalone plan.",
+        },
+        consumed_learn: {
+          type: "array",
+          items: { type: ["string", "number"] },
+          description:
+            "Optional perk:learn issue ids this docs plan consumes (the learned-docs factory " +
+            "passes the gathered ids; omit for a standalone plan). /land closes + labels them.",
+        },
+      },
+    },
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const decoded = decodePlanSaveParams(params);
+      if (decoded === null) {
+        // The `label` arg matters: this handler-level closure renders "plan_save failed: …" while
+        // savePlan's internal failFor(ctx, "plan-save") stays as-is.
+        return failFor(
+          ctx,
+          "plan-save",
+          "plan_save",
+        )("plan_save needs { plan: string, … } per the tool schema", "bad_input");
+      }
+      const src = resolvePlanSource(ctx, decoded.plan);
+      if (src === null) {
+        return failFor(
+          ctx,
+          "plan-save",
+          "plan_save",
+        )(
+          "no plan to save — write the working draft with plan_draft, or pass the plan parameter",
+          "invalid_input",
+        );
+      }
+      return savePlan(pi, ctx, {
+        plan: src.plan,
+        source: src.source,
+        paramMismatch: src.paramMismatch,
+        title: decoded.title,
+        objectiveId: decoded.objective_id,
+        nodeId: decoded.node_id,
+        consumedLearn: decoded.consumed_learn,
+      });
+    },
+  });
+
+  pi.registerCommand("plan-save", {
+    description:
+      "Save the latest proposed plan to GitHub — the manual failsafe for the approval→save flow " +
+      "(the read-only → read-write boundary).",
+    handler: async (args, ctx) => {
+      const title = args.trim() || undefined;
+      // The manual-failsafe invocation of the shared approval→save seam. Artifact-first
+      // (no explicit param on the command path ⇒ paramMismatch is always false); the D1a gate exit
+      // lives in the seam. (The tool path never exits the gate — it is structurally unreachable
+      // while read-only.)
+      const outcome = await approvalSave(pi, ctx, gating, { title });
+      if (outcome.status === "no-plan") {
+        report(
+          ctx,
+          "plan-save",
+          "warning",
+          "no plan to save; write a draft with plan_draft, propose a plan, or call the plan_save tool.",
+          { alsoLog: true },
+        );
+        return;
+      }
+      // Severity reflects a failed objective-node advance: not-ok → error; saved-but-link-failed →
+      // warning; otherwise info. A failed node-link never blocks the gate exit above (the plan was
+      // saved) — but it MUST surface (the silent-partial-failure fix), in headless runs too.
+      const result = outcome.result;
+      const message = result.content[0]?.text ?? "plan-save done";
+      const severity: Severity = !result.details.ok
+        ? "error"
+        : result.details.objective_node?.linked === false
+          ? "warning"
+          : "info";
+      report(ctx, "plan-save", severity, message);
+    },
+  });
+}