@mgiles/perk 2.1.0 → 2.3.0

package/extension/factories/gistDraft.ts

@@ -0,0 +1,265 @@
+// The `gist_draft` file tool: the third member of the draft carve-out family
+// (planDraft.ts, objectiveDraft.ts) — the gist twin, minus the roadmap.
+//
+// Carve-out doctrine: the tool takes NO path/name parameter — the artifact name is the fixed
+// constant `GIST_DRAFT_ARTIFACT` and the path is derived exclusively through the session-data
+// accessor seam (`writeSessionArtifact`, sessionData.ts), so the only bytes it can ever write are
+// the one working-gist artifact in the current run's data dir (gitignored scratch). Allowlisting
+// its name in `READ_ONLY_TOOLS` (toolGating.ts) is therefore safe: the read-only invariant (the
+// worktree stays untouched) holds, and the gate's `tool_call` edit/write/bash blocking logic is
+// UNCHANGED. Full rewrite per call, non-terminating; NOT a save — `gist_save`/`/gist-save` still
+// persist the gist to the issue backend.
+//
+// Format doctrine: JSON is the storage/transport format, NEVER the human review surface. The
+// artifact carries `{schema_version, title?, scope?, prose}` — deliberately light: a gist is a
+// problem-space statement of intent with no structured roadmap (contracts.md §8.41). The review
+// surface reads the draft via `readGistDraft` (over `readSessionArtifact` — digest-validated,
+// fail-open) and renders markdown via `renderGistDraft` (title + a `Scope:` line + the prose) —
+// never raw JSON.
+//
+// Vocabulary ownership: this module owns the shared draft/save param vocabulary
+// (`GistSaveParams`, `decodeGistSaveParams`, `GIST_SCOPES`) — gistDraft is the LEAF (mirroring
+// planDraft←planSave's direction); gistSave.ts consumes it, so it may value-import
+// `readGistDraft` cycle-free for the approval→save orchestration.
+//
+// Imports stay node builtins + sibling seams (sessionData.ts, result.ts) so the module loads
+// under `node --test`; no manual `scratch`/`runs` path segments (cacheGuard.test.ts).
+
+import { relative } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { failFor, ok, type Result } from "../substrate/result.ts";
+import {
+  activeSessionRunId,
+  digestSessionData,
+  readSessionArtifact,
+  type SessionDataCtx,
+  writeSessionArtifact,
+} from "../substrate/sessionData.ts";
+import { paramsOf, stringParam } from "../substrate/toolParams.ts";
+import type { EntrySink } from "../substrate/workflowState.ts";
+import type { ReportTarget } from "../surfaces/report.ts";
+
+/** The gist consumption tiers (`scope` — contracts.md §8.41). */
+export const GIST_SCOPES = ["plan", "objective"] as const;
+
+export type GistScope = (typeof GIST_SCOPES)[number];
+
+/** The decoded `gist_save` tool params (shared with `gist_draft`). */
+export interface GistSaveParams {
+  prose: string;
+  title?: string;
+  scope?: GistScope;
+}
+
+/**
+ * Decode unknown `gist_save` tool-call params (the tool-boundary seam). `prose` absent decodes
+ * to `""` (so `saveGist`'s "no gist prose to save" `invalid_input` arm keeps owning that
+ * message) but present-but-mistyped → null (strict-fail); a present `scope` outside the enum is
+ * likewise a strict-fail (the schema already declares the enum — a bad value means a malformed
+ * call, never a silent default).
+ */
+export function decodeGistSaveParams(params: unknown): GistSaveParams | null {
+  const p = paramsOf(params);
+  if (p === null) return null;
+  const prose = stringParam(p, "prose");
+  const title = stringParam(p, "title");
+  const scope = stringParam(p, "scope");
+  if (prose === null || title === null || scope === null) return null;
+  if (scope !== undefined && !(GIST_SCOPES as readonly string[]).includes(scope)) return null;
+  return { prose: prose ?? "", title, scope: scope as GistScope | undefined };
+}
+
+/** The fixed working-gist artifact name (one JSON file: the prose + the optional scope hint). */
+export const GIST_DRAFT_ARTIFACT = "gist-draft.json";
+
+/** The ok-arm details — provenance-consistent with the recorded `session_artifacts` pointer. */
+export interface GistDraftOk {
+  name: string;
+  path: string;
+  digest: string;
+  bytes: number;
+  run_id: string;
+}
+
+export type GistDraftResult = Result<GistDraftOk>;
+
+/**
+ * The core both the tool handler and tests call: serialize the working gist (prose + the
+ * optional title/scope) as one JSON artifact and write it through the accessor seam (file +
+ * `session_artifacts` provenance pointer). Soft result, never throws — failure taxonomy: empty
+ * prose → `invalid_input`; no session run_id → `no_run_id`; file-or-pointer write failure →
+ * `write_failed` (the seam already warned).
+ */
+export function writeGistDraft(
+  sink: EntrySink,
+  ctx: SessionDataCtx & ReportTarget,
+  opts: { prose: string; title?: string; scope?: GistScope },
+): GistDraftResult {
+  const fail = failFor(ctx, "gist-draft");
+
+  if (!opts.prose.trim()) {
+    return fail("no gist prose to write (pass the full working draft)", "invalid_input");
+  }
+
+  const runId = activeSessionRunId(ctx);
+  if (runId === null) {
+    return fail("session has no run_id — cannot write the gist-draft artifact", "no_run_id");
+  }
+
+  // Deterministic key order via the explicit literal; `title`/`scope` are omitted when blank.
+  const title = opts.title?.trim();
+  const payload = {
+    schema_version: 1,
+    ...(title ? { title } : {}),
+    ...(opts.scope ? { scope: opts.scope } : {}),
+    prose: opts.prose,
+  };
+  const content = `${JSON.stringify(payload, null, 2)}\n`;
+
+  const written = writeSessionArtifact(sink, ctx, GIST_DRAFT_ARTIFACT, content);
+  if (written === null) {
+    return fail(
+      `could not write the ${GIST_DRAFT_ARTIFACT} artifact (see warnings)`,
+      "write_failed",
+    );
+  }
+
+  // Derive digest/relative path consistently with the pointer the seam recorded.
+  const digest = digestSessionData(content);
+  const relPath = relative(ctx.cwd, written);
+  return ok(`Gist draft written → ${relPath} (${digest})`, {
+    name: GIST_DRAFT_ARTIFACT,
+    path: relPath,
+    digest,
+    bytes: Buffer.byteLength(content, "utf8"),
+    run_id: runId,
+  });
+}
+
+// ------------------------------------------------------------------- the reader + the renderer
+
+/** The validated working-gist draft shape consumers receive from `readGistDraft`. */
+export interface GistDraft {
+  title?: string;
+  scope?: GistScope;
+  prose: string;
+}
+
+/**
+ * Read + validate the working-gist draft artifact. Fail-open `null` everywhere (mirroring
+ * `readSessionArtifact`'s loud tier): no pointer/file/digest → `null` (the seam already spoke);
+ * malformed JSON, a non-object payload, an unsupported `schema_version`, or blank prose → a
+ * stderr warning + `null`. `title` is kept only when a non-blank string; `scope` only when a
+ * member of the enum (an unknown scope degrades to absent, never poisons the draft). Never
+ * throws.
+ */
+export function readGistDraft(ctx: SessionDataCtx): GistDraft | null {
+  const artifact = readSessionArtifact(ctx, GIST_DRAFT_ARTIFACT);
+  if (artifact === null) return null;
+
+  const refuse = (why: string): null => {
+    console.error(`perk: warning: ${GIST_DRAFT_ARTIFACT} ${why} — refusing the draft`);
+    return null;
+  };
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(artifact.content);
+  } catch {
+    return refuse("is not valid JSON");
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return refuse("is not a JSON object");
+  }
+  const payload = parsed as Record<string, unknown>;
+  if (payload.schema_version !== 1) {
+    return refuse(`has an unsupported schema_version (${JSON.stringify(payload.schema_version)})`);
+  }
+  const prose = payload.prose;
+  if (typeof prose !== "string" || !prose.trim()) {
+    return refuse("has no prose");
+  }
+  const title =
+    typeof payload.title === "string" && payload.title.trim() ? payload.title : undefined;
+  const scope =
+    typeof payload.scope === "string" && (GIST_SCOPES as readonly string[]).includes(payload.scope)
+      ? (payload.scope as GistScope)
+      : undefined;
+  return {
+    ...(title !== undefined ? { title } : {}),
+    ...(scope !== undefined ? { scope } : {}),
+    prose,
+  };
+}
+
+/**
+ * Render the draft as the markdown review surface (JSON is storage/transport only — contracts
+ * §8.1): the optional `# title` heading, a `Scope:` line when the hint is set, and the prose
+ * verbatim. Pure; never throws.
+ */
+export function renderGistDraft(draft: GistDraft): string {
+  let out = "";
+  if (draft.title) out += `# ${draft.title}\n\n`;
+  if (draft.scope) out += `Scope: ${draft.scope}\n\n`;
+  return out + draft.prose;
+}
+
+const TOOL_GUIDELINES = [
+  "Call gist_draft to persist the current working gist as you author or revise it; pass the FULL prose each time (it rewrites the whole draft).",
+  "gist_draft never saves to the issue backend and never ends the turn — gist_save//gist-save remain the canonical save surface.",
+  "Pass gist_draft's `scope` only once the consumption tier is settled: `plan` for plan-sized intent, `objective` for objective-sized intent.",
+];
+
+/** Register the `gist_draft` tool (the carve-out producer; interior-only). */
+export function registerGistDraft(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "gist_draft",
+    label: "Gist draft",
+    description:
+      "Write (or overwrite) the working gist draft — the statement-of-intent prose + an " +
+      "optional scope hint — to the session data dir and record its provenance pointer. The " +
+      "only sanctioned write surface while read-only. NOT a save — gist_save//gist-save still " +
+      "persist the gist to the issue backend.",
+    promptSnippet:
+      "Persist the working gist draft (statement-of-intent prose) to the session data dir (full rewrite)",
+    promptGuidelines: TOOL_GUIDELINES,
+    executionMode: "sequential",
+    parameters: {
+      type: "object",
+      additionalProperties: false,
+      required: ["prose"],
+      properties: {
+        prose: {
+          type: "string",
+          description:
+            "The gist prose (the problem-space intent: what we want, why it matters, what " +
+            "bounds it — no implementation steps).",
+        },
+        title: {
+          type: "string",
+          description: "Optional gist title (defaults to the prose's first heading).",
+        },
+        scope: {
+          type: "string",
+          enum: [...GIST_SCOPES],
+          description:
+            "Optional consumption tier: plan (plan-sized intent) or objective (objective-sized).",
+        },
+      },
+    },
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      // The shared param contract: the same decode as `gist_save`, so the two cannot drift.
+      const decoded = decodeGistSaveParams(params);
+      if (decoded === null) {
+        return failFor(
+          ctx,
+          "gist-draft",
+          "gist_draft",
+        )(
+          "gist_draft needs { prose: string, scope?: plan|objective } per the tool schema",
+          "bad_input",
+        );
+      }
+      return writeGistDraft(pi, ctx, decoded);
+    },
+  });
+}

package/extension/factories/gistSave.ts

@@ -0,0 +1,251 @@
+// The warm `gist_save` door, the gist mirror of objectiveSave.ts. The in-session twin of the
+// Python cold door (`perk gist create`): a deterministic, terminating tool + command that WRAP
+// the existing storage — they do NOT reimplement the backend write. `saveGist()` delegates to
+// `perk gist create --json` via the shared cold-door client (`runColdDoor`, the prose rides the
+// run-scratch stdin channel). Unlike the plan/objective twins there is NO session linkage after
+// the save — nothing consumes a gist in-session (adoption happens later via the cold doors), so
+// a successful save just relays the envelope's id/url/consumption story.
+//
+// APPROVAL→SAVE ORCHESTRATION (mirroring objectiveSave.ts's `objectiveApprovalSave`). The
+// exported `gistApprovalSave` seam is the shared APPROVED-review → save flow: re-read the
+// artifact (`readGistDraft` — never the rendered markdown, never the transcript) → `saveGist` →
+// D1a gate exit on a successful save (snapshot `gating.isActive()` BEFORE the save; a failed
+// save leaves the gate ON). `plan_review`'s gist arm (planReview.ts) wires its APPROVED outcome
+// into it; the `/gist-save` command is the artifact-first MANUAL FAILSAFE invocation of the same
+// seam, keeping the legacy drive-the-session behavior as the no-draft fallback (gists have no
+// transcript scrape by design).
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { bindingSuffix } from "../substrate/bindingDelivery.ts";
+import {
+  booleanField,
+  type ColdJson,
+  objectField,
+  runColdDoor,
+  stringField,
+} from "../substrate/coldDoor.ts";
+import { registerPerkCommand } from "../substrate/command.ts";
+import { render } from "../substrate/prompts.ts";
+import { failFor, ok, type Result } from "../substrate/result.ts";
+import type { ToolGating } from "../substrate/toolGating.ts";
+import { branchOf, rebuildWorkflowState } from "../substrate/workflowState.ts";
+import { report, type Severity } from "../surfaces/report.ts";
+import { decodeGistSaveParams, GIST_SCOPES, type GistScope, readGistDraft } from "./gistDraft.ts";
+
+/** The ok-arm fields — the structured `details` surface doubles as branch-safe persisted state. */
+export interface GistSaveOk {
+  /** `id` is the opaque string gist id (GitHub "7", Linear "ENG-7"/project id) — §8.21. */
+  gist: { id: string; url: string };
+  scope: string | null;
+  existed: boolean | null;
+}
+
+export type GistSaveResult = Result<GistSaveOk>;
+
+/** The decoded `perk gist create --json` payload slice the warm door consumes. */
+interface GistCreatePayload {
+  gist: { id: string; url: string; existed: boolean | undefined };
+  scope: string | undefined;
+}
+
+/** Narrow the `perk gist create --json` success payload; strict on `gist`. */
+function decodeGistCreate(payload: ColdJson): GistCreatePayload | null {
+  const gist = objectField(payload, "gist");
+  if (gist === undefined) return null;
+  const id = stringField(gist, "id");
+  const url = stringField(gist, "url");
+  if (id === undefined || url === undefined) return null;
+  return {
+    gist: { id, url, existed: booleanField(gist, "existed") },
+    scope: stringField(payload, "scope"),
+  };
+}
+
+/** The consumption pointer relayed after a save — the adoption door matching the saved scope. */
+function consumptionHint(id: string, scope: string | undefined): string {
+  return scope === "objective"
+    ? `Consume with: perk objective author --from ${id}`
+    : `Consume with: perk plan from ${id}`;
+}
+
+/**
+ * The single save implementation both surfaces call. Delegates the backend write to the Python
+ * cold door (which owns scope resolution: an explicit `scope` wins, else the launch handoff's
+ * pre-seeded `gist_scope`, else `plan`). Returns a soft result (never throws); failures set
+ * `details.ok = false`. No session linkage on success — nothing consumes a gist in-session.
+ */
+export async function saveGist(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  opts: { prose: string; title?: string; scope?: GistScope },
+): Promise<GistSaveResult> {
+  const fail = failFor(ctx, "gist-save");
+
+  const prose = opts.prose.trim();
+  if (!prose) return fail("no gist prose to save (draft the gist first)", "invalid_input");
+  if (opts.scope !== undefined && !(GIST_SCOPES as readonly string[]).includes(opts.scope)) {
+    return fail("scope must be plan or objective", "invalid_input");
+  }
+
+  const runId = rebuildWorkflowState(branchOf(ctx)).run_id ?? "";
+
+  const args = ["gist", "create", "--json"];
+  if (opts.title) args.push("--title", opts.title);
+  if (opts.scope) args.push("--scope", opts.scope);
+  if (runId) args.push("--run-id", runId);
+  const r = await runColdDoor<GistCreatePayload>(pi, ctx, args, {
+    label: "perk gist create",
+    decode: decodeGistCreate,
+    stdin: { flag: "--body", content: prose, filename: "gist.md" },
+  });
+  if (!r.ok) return fail(r.message, r.errorType);
+
+  const gist = r.data.gist;
+  const verb = gist.existed ? "Found existing" : "Saved";
+  return ok(
+    `${verb} gist ${gist.id} → ${gist.url}\n${consumptionHint(gist.id, r.data.scope)}`,
+    {
+      gist: { id: gist.id, url: gist.url },
+      scope: r.data.scope ?? null,
+      existed: gist.existed ?? null,
+    },
+    { terminate: true },
+  );
+}
+
+/** The approval→save orchestration outcome (the gist `ApprovalSaveOutcome`). */
+export type GistApprovalSaveOutcome =
+  | { status: "no-draft" }
+  | { status: "saved" | "save-failed"; result: GistSaveResult; gateExited: boolean };
+
+/**
+ * The shared approval→save orchestration seam (the gist sibling of objectiveSave.ts's
+ * `objectiveApprovalSave`): an APPROVED gist review (`plan_review`'s gist arm) and the manual
+ * `/gist-save` failsafe both run THIS. Flow: re-read the draft artifact at save time
+ * (`readGistDraft` — never the rendered markdown, never in-hand bytes) → `saveGist` → 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 draft → `no-draft` (nothing saved, the gate
+ * untouched); callers render their own fallback. Title/scope precedence: explicit opts win; else
+ * the draft's; else the cold door derives/defaults. The returned result keeps `saveGist`'s
+ * `terminate: true` for tool-path callers.
+ */
+export async function gistApprovalSave(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  gating: ToolGating,
+  opts: { title?: string } = {},
+): Promise<GistApprovalSaveOutcome> {
+  const draft = readGistDraft(ctx);
+  if (draft === null) return { status: "no-draft" };
+  // 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 saveGist(pi, ctx, {
+    prose: draft.prose,
+    title: opts.title ?? draft.title,
+    scope: draft.scope,
+  });
+  let gateExited = false;
+  if (result.details.ok && wasReadOnly) {
+    gating.exit(ctx);
+    gateExited = true;
+  }
+  return { status: result.details.ok ? "saved" : "save-failed", result, gateExited };
+}
+
+const TOOL_GUIDELINES = [
+  "Use gist_save only after the gist says what it means; it creates the tracked gist in the issue backend and ends the turn.",
+  "Pass gist_save the statement-of-intent PROSE in `prose` — problem-space only, no implementation steps or roadmap.",
+  "Pass gist_save's `scope` only once the consumption tier is settled (plan or objective); omit it to keep the pre-seeded/default scope.",
+];
+
+/**
+ * The seed guidance the warm `/gist-save` injects to drive the save (the perk-gist-author skill
+ * pointer rides the skill-binding suffix — not hardcoded here). Pure + exported for offline
+ * tests.
+ */
+export function gistSaveGuidance(title?: string): string {
+  const named = title?.trim() || "";
+  return render("stages/gist-save.md", { title: named });
+}
+
+/** Register the warm door: the `gist_save` tool (canonical) + the `/gist-save` twin. */
+export function registerGistSave(pi: ExtensionAPI, gating: ToolGating): void {
+  pi.registerTool({
+    name: "gist_save",
+    label: "Save gist",
+    description:
+      "Persist a drafted gist (a statement of intent) to the issue backend as a tracked " +
+      "perk:gist. Terminating: ends the turn on save. Call only when the gist says what it " +
+      "means.",
+    promptSnippet: "Save the converged gist to the issue backend (terminates the turn)",
+    promptGuidelines: TOOL_GUIDELINES,
+    executionMode: "sequential",
+    parameters: {
+      type: "object",
+      additionalProperties: false,
+      required: ["prose"],
+      properties: {
+        prose: {
+          type: "string",
+          description:
+            "The gist prose (the problem-space intent: what we want, why it matters, what " +
+            "bounds it — no implementation steps).",
+        },
+        title: {
+          type: "string",
+          description: "Optional gist title (defaults to the prose's first heading).",
+        },
+        scope: {
+          type: "string",
+          enum: [...GIST_SCOPES],
+          description:
+            "Optional consumption tier: plan (plan-sized intent) or objective (objective-sized).",
+        },
+      },
+    },
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const decoded = decodeGistSaveParams(params);
+      if (decoded === null) {
+        return failFor(
+          ctx,
+          "gist-save",
+          "gist_save",
+        )(
+          "gist_save needs { prose: string, scope?: plan|objective } per the tool schema",
+          "bad_input",
+        );
+      }
+      return saveGist(pi, ctx, decoded);
+    },
+  });
+
+  registerPerkCommand(pi, "gist-save", {
+    description:
+      "Save the working gist draft to the issue backend — the manual failsafe for the " +
+      "approval→save flow (artifact-first; drives the save only when no draft exists).",
+    handler: async (args, ctx) => {
+      const title = args.trim() || undefined;
+      // The artifact-first manual-failsafe invocation of the shared approval→save seam (the D1a
+      // gate exit lives in the seam). The legacy drive-the-session behavior is kept as the
+      // NO-DRAFT fallback — gists have no transcript scrape by design, so a draftless session
+      // still needs a working save path.
+      const outcome = await gistApprovalSave(pi, ctx, gating, { title });
+      if (outcome.status === "no-draft") {
+        // Exit the read-only gate so the gist_save tool (excluded from READ_ONLY_TOOLS) becomes
+        // reachable on the driven turn, then drive the turn (mirrors /objective-save).
+        if (gating.isActive()) gating.exit(ctx);
+        report(ctx, "gist-save", "info", "handing the save to the session");
+        // The perk-gist-author pointer rides the skill-binding suffix (D5) since a warm
+        // /gist-save outside a stage:gist-author session gets none from Mechanism A.
+        pi.sendUserMessage(gistSaveGuidance(title) + bindingSuffix(ctx.cwd, "stage:gist-author"));
+        return;
+      }
+      // Saved or save-failed: relay the save message (which carries the consumption hint).
+      const result = outcome.result;
+      const message = result.content[0]?.text ?? "gist-save done";
+      const severity: Severity = result.details.ok ? "info" : "error";
+      report(ctx, "gist-save", severity, message);
+    },
+  });
+}

package/extension/factories/objectivePlan.ts

@@ -556,8 +556,9 @@ async function fetchObjectiveUrl(
  * perk-objective-plan skill pointer rides the skill-binding suffix — not hardcoded).
  * The loop is file-first (`plan_draft` → `plan_review` → approval-driven save); the node link
  * rides the `objective_node_claim` carrier recorded by the unconditional `planning` mark.
- * When `model` is set, the OPTIONAL `perk.objective-explorer` spawn carries an inline `model`
- * override ([models.subagents] objective-explorer); otherwise the agent's frontmatter default is used. */
+ * When `model` is set, the OPTIONAL `perk.objective-explorer` workflowScript call carries a
+ * workflow-level `model` default ([models.subagents] objective-explorer); otherwise the agent's
+ * frontmatter default is used. */
 export function factoryGuidance(
   objective: string,
   node: string | null,

package/extension/factories/planMode.ts

@@ -46,6 +46,7 @@ import { report } from "../surfaces/report.ts";
 // `Key` via the surfaces re-export (keybinding vocabulary, not rich UI) — keeps pi-tui imports
 // structurally confined to the surfaces module (the surfacesGuard pi-tui import rule).
 import { Key } from "../surfaces/surfaces.ts";
+import { GIST_AUTHOR_STAGE } from "./gistAuthor.ts";
 import { OBJECTIVE_AUTHOR_STAGE } from "./objectiveAuthor.ts";
 
 /** The plan-authoring context customType (distinct from the gate's `perk:mode-context`). */
@@ -156,14 +157,16 @@ export function registerPlanMode(pi: ExtensionAPI, gating: ToolGating): void {
     });
   }
 
-  // Inject the plan-authoring context while the read-only gate is active (display:false). The one
-  // exception: an objective-author session is ALSO read-only, but objectiveAuthor.ts injects its
-  // own authoring context there — so plan mode defers when the launched stage is objective-author
-  // (the coupling break: plan-authoring context is no longer keyed off the bare read-only gate).
+  // Inject the plan-authoring context while the read-only gate is active (display:false). The
+  // exceptions: objective-author and gist-author sessions are ALSO read-only, but
+  // objectiveAuthor.ts / gistAuthor.ts inject their own authoring contexts there — so plan mode
+  // defers when the launched stage is either (the coupling break: plan-authoring context is no
+  // longer keyed off the bare read-only gate).
   pi.on("before_agent_start", async (_event, ctx) => {
     if (!gating.isActive()) return;
     const branch = branchOf(ctx);
-    if (rebuildWorkflowState(branch).stage === OBJECTIVE_AUTHOR_STAGE) return;
+    const launchedStage = rebuildWorkflowState(branch).stage;
+    if (launchedStage === OBJECTIVE_AUTHOR_STAGE || launchedStage === GIST_AUTHOR_STAGE) return;
     // Once-only: injected customs persist to the branch, so a live copy suppresses re-injection;
     // compaction dropping it makes the scan come up clean and the next turn re-injects.
     if (branchCarries(branch, PLAN_MARKER)) return;