@mgiles/perk 3.0.0 → 3.2.0

package/extension/factories/objectiveDreamReport.ts

@@ -0,0 +1,347 @@
+// The `dream_report` gate for the objective draft/review/save path (contracts.md §8.63).
+//
+// ONE resolver implements the whole gate matrix — `writeObjectiveDraft` (objectiveDraft.ts)
+// and `saveObjective` (objectiveSave.ts) both consume its typed outcome, so no parallel
+// branch/message implementation can drift. "Dream session" is detected structurally, exactly
+// like `run_dream_wave` (doors/dreamWaveTools.ts): the session's claimed `run_id` plus the
+// existence of the run-scoped dream manifest (no claimed run counts as non-dream). The gate is
+// fail-closed in BOTH directions: a dream session refuses a report-less objective (the
+// objective and its report review as ONE bundle — an approval is always savable), and a
+// `dream_report` outside a dream session refuses rather than being silently dropped. Absence
+// on a non-dream path is byte-identical no-op behavior.
+//
+// Trusted-context recovery follows the session-artifacts digest-pointer doctrine: the bare
+// run-scratch bundle is never trusted — the `dream_bundle_digest` workflow-state marker
+// (cleared at wave entry, set to the finalized bytes' digest after a successful finalize) is
+// the freshness/integrity authority, and the bundle is strictly re-decoded through
+// `decodeFinalizedDreamBundle` on every recovery read (untrusted-at-rest posture). After a
+// successful recovery the revalidation bracket (contracts.md §8.65) re-proves HEAD-unchanged +
+// tree-clean against the manifest's stamped `commit_sha` — at draft-write AND save, since both
+// consumers flow through the one resolver; drift refuses `bad_state` (the analysis is stale).
+//
+// Imports only the dream wave siblings, the substrate seams, and node builtins — cycle-free
+// (nothing in `waves/` imports factories) and loadable under `node --test`.
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { runScratchDir } from "../substrate/cache.ts";
+import { revalidationBracket } from "../substrate/git.ts";
+import { digestSessionData, type SessionDataCtx } from "../substrate/sessionData.ts";
+import { branchOf, rebuildWorkflowState, type WorkflowState } from "../substrate/workflowState.ts";
+import { DREAM_ANALYSES_FILENAME, decodeFinalizedDreamBundle } from "../waves/dreamReducerWave.ts";
+import { buildDreamReport, type DreamReportContext } from "../waves/dreamReport.ts";
+import {
+  codePointLength,
+  DREAM_MANIFEST_FILENAME,
+  decodeDreamManifest,
+} from "../waves/dreamWave.ts";
+
+/**
+ * The shared part-invariance + size rule's comment-body cap (contracts §8.64) — the full
+ * rendered companion comment (marker + blank line + part) must fit with margin under GitHub's
+ * 65,536-char issue-comment limit. The Python twin is
+ * `perk.learn.dream_companion.COMPANION_COMMENT_MAX_CHARS` (parity-pinned fixtures).
+ */
+export const COMPANION_COMMENT_MAX_CHARS = 65_000;
+
+// The invariance shapes (the exact shapes the Linear transcoder `to_linear_markdown`
+// rewrites/drops — derived locally by the same rule, mirroring the Python twin).
+const MARKER_TEXT = "perk:learn-dream-report";
+const PERK_HTML_MARKER_RE = /<!--\s*\/?perk:[^>]+?\s*-->/;
+const DETAILS_OPEN_RE = /^<details><summary><code>[^<]*<\/code><\/summary>$/;
+const DETAILS_CLOSE = "</details>";
+// Every line boundary Python's `str.splitlines()` recognizes EXCEPT `\n` — the Linear
+// transcoder splits on all of them and rejoins with `\n`, so any other boundary form would be
+// normalized in the stored body and defeat the persistence-side byte comparison forever.
+const NON_CANONICAL_LINE_BOUNDARIES = [
+  "\r",
+  "\v",
+  "\f",
+  "\u001c",
+  "\u001d",
+  "\u001e",
+  "\u0085",
+  "\u2028",
+  "\u2029",
+];
+
+/**
+ * The TS mirror of Python's `validate_report_parts` (contracts §8.64) — run over the freshly
+ * rendered parts at draft-write AND save (both flow through `resolveDreamReportGate`), so an
+ * approved report is always Python-savable: no empty/blank part, no perk HTML-comment marker,
+ * no literal companion marker text, no perk-rendered `<details>` wrapper line (the shapes the
+ * Linear transcoder rewrites/drops — transcode-invariance keeps the persistence-side
+ * dual-candidate byte comparison exact), and every rendered comment body (marker + blank line +
+ * part) within `COMPANION_COMMENT_MAX_CHARS` code points. Returns named violations (`[]` =
+ * valid). Parity-pinned against the Python twin by the shared fixture set.
+ */
+export function reportPartInvarianceViolations(parts: string[], runId: string): string[] {
+  const violations: string[] = [];
+  parts.forEach((part, i) => {
+    const index = i + 1;
+    const where = `part ${index}`;
+    if (part.trim() === "") {
+      violations.push(`${where}: empty part`);
+      return;
+    }
+    if (part.includes(MARKER_TEXT)) {
+      violations.push(`${where}: carries the literal '${MARKER_TEXT}' marker text`);
+    }
+    if (PERK_HTML_MARKER_RE.test(part)) {
+      violations.push(
+        `${where}: carries a perk HTML-comment marker (<!-- perk:… --> is rewritten by the ` +
+          "Linear transcoder)",
+      );
+    }
+    if (
+      part.split(/\r\n|\r|\n/).some((line) => DETAILS_OPEN_RE.test(line) || line === DETAILS_CLOSE)
+    ) {
+      violations.push(
+        `${where}: carries a perk-rendered <details> wrapper line (dropped by the Linear ` +
+          "transcoder)",
+      );
+    }
+    if (NON_CANONICAL_LINE_BOUNDARIES.some((boundary) => part.includes(boundary))) {
+      violations.push(
+        `${where}: carries a line boundary other than \\n (normalized by the Linear transcoder)`,
+      );
+    }
+    const bodyLength = codePointLength(`<!-- ${MARKER_TEXT}:${runId}:${index} -->\n\n${part}`);
+    if (bodyLength > COMPANION_COMMENT_MAX_CHARS) {
+      violations.push(
+        `${where}: rendered comment body is ${bodyLength} chars (cap ${COMPANION_COMMENT_MAX_CHARS})`,
+      );
+    }
+  });
+  if (parts.length === 0) violations.push("parts: empty list");
+  return violations;
+}
+
+/**
+ * The `dream_report` block the objective-draft artifact carries (tool-written only — the model
+ * never writes the artifact): the validated model input, the ONE `generated_at` stamp that
+ * keeps re-rendering deterministic across review and save, and the stored CANONICAL parts the
+ * review surface renders and the save byte-compares.
+ */
+export interface ObjectiveDreamReportBlock {
+  input: unknown;
+  generated_at: string;
+  parts: string[];
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * The artifact-side shape check `readObjectiveDraft` uses: a plain object carrying a
+ * plain-object `input`, a non-blank string `generated_at`, and a non-empty all-string `parts`.
+ * Deep validation stays with the resolver (the save re-runs the full gate); `null` = malformed.
+ */
+export function decodeDreamReportBlock(value: unknown): ObjectiveDreamReportBlock | null {
+  if (!isRecord(value)) return null;
+  if (!isRecord(value.input)) return null;
+  if (typeof value.generated_at !== "string" || !value.generated_at.trim()) return null;
+  if (!Array.isArray(value.parts) || value.parts.length === 0) return null;
+  const parts: string[] = [];
+  for (const part of value.parts) {
+    if (typeof part !== "string") return null;
+    parts.push(part);
+  }
+  return { input: value.input, generated_at: value.generated_at, parts };
+}
+
+/**
+ * Recover the trusted `DreamReportContext` from the claimed run's scratch state — every arm
+ * fail-closed with a named detail (the caller maps them to `bad_state`):
+ *
+ *  1. the run-scoped manifest: read + parse + `decodeDreamManifest` (the strict §8.60 decoder,
+ *     path bound at decode time). No `verifyDocContainment` — this path reads no doc files;
+ *     the lexical decode suffices (resolved containment is the wave tool's pre-spawn concern);
+ *  2. the freshness check: the `dream_bundle_digest` marker (read from the caller's ONE
+ *     workflow-state snapshot) must be present, non-empty, and equal the digest of the bundle
+ *     bytes just read — a bare file is never trusted (missing marker = no finalized wave;
+ *     empty = invalidated by a newer attempt, including a cleanup-failure residue; mismatch =
+ *     stale/tampered bytes);
+ *  3. the strict finalized decode (`decodeFinalizedDreamBundle` over the digest of the
+ *     manifest bytes just read — the marker authenticates the bundle bytes and the bundle's
+ *     `manifest_digest` extends that authority to the manifest, so an at-rest manifest edit
+ *     refuses; the analyses-only mid-wave shape refuses here too).
+ */
+function recoverDreamReportContext(
+  ctx: SessionDataCtx,
+  runId: string,
+  marker: string | undefined,
+  generatedAt: string,
+): { ok: true; context: DreamReportContext } | { ok: false; detail: string } {
+  const manifestPath = join(runScratchDir(ctx.cwd, runId), DREAM_MANIFEST_FILENAME);
+  let manifestBytes: string;
+  let rawManifest: unknown;
+  try {
+    manifestBytes = readFileSync(manifestPath, "utf8");
+    rawManifest = JSON.parse(manifestBytes);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    return { ok: false, detail: `dream manifest unreadable at '${manifestPath}': ${detail}` };
+  }
+  const manifest = decodeDreamManifest(rawManifest, manifestPath);
+  if (!manifest.ok) {
+    return { ok: false, detail: `dream manifest invalid: ${manifest.detail}` };
+  }
+
+  const bundlePath = join(dirname(manifestPath), DREAM_ANALYSES_FILENAME);
+  let bundleBytes: string;
+  try {
+    bundleBytes = readFileSync(bundlePath, "utf8");
+  } catch {
+    return {
+      ok: false,
+      detail: `no dream bundle at '${bundlePath}' — re-run the dream wave`,
+    };
+  }
+  if (marker === undefined || marker === "") {
+    return {
+      ok: false,
+      detail: "no finalized dream wave for this session — re-run the dream wave",
+    };
+  }
+  if (digestSessionData(bundleBytes) !== marker) {
+    return {
+      ok: false,
+      detail:
+        "the dream bundle does not match the session's finalized digest — re-run the dream wave",
+    };
+  }
+  let rawBundle: unknown;
+  try {
+    rawBundle = JSON.parse(bundleBytes);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    return { ok: false, detail: `dream bundle is not valid JSON: ${detail}` };
+  }
+  const decoded = decodeFinalizedDreamBundle(
+    rawBundle,
+    manifest.manifest,
+    digestSessionData(manifestBytes),
+  );
+  if (!decoded.ok) {
+    return { ok: false, detail: `${decoded.detail} — re-run the dream wave` };
+  }
+  return {
+    ok: true,
+    context: {
+      manifest: manifest.manifest,
+      analyses: decoded.analyses,
+      reducers: decoded.reducers,
+      run_id: runId,
+      generated_at: generatedAt,
+    },
+  };
+}
+
+/** The typed gate outcome both consumers branch on — the whole matrix, one vocabulary. */
+export type DreamReportGateOutcome =
+  | { kind: "absent" }
+  | { kind: "block"; block: ObjectiveDreamReportBlock }
+  | { kind: "refuse"; errorType: "invalid_input" | "bad_state"; detail: string };
+
+/**
+ * The ONE gate resolver (contracts §8.63) — identical at draft-write and save. `input` is the
+ * model-supplied `dream_report` value, or `undefined` for "no dream_report" (callers pass the
+ * value only when present; an `{input: undefined}` carrier is never constructed). The matrix:
+ *
+ * | session   | `dream_report` | outcome |
+ * | --------- | -------------- | ------- |
+ * | non-dream | absent         | `absent` — unchanged, byte-identical behavior |
+ * | non-dream | present        | refuse `invalid_input` (never silently dropped) |
+ * | dream     | absent         | refuse `invalid_input` (one approval bundle) |
+ * | dream     | present        | recover context → `buildDreamReport` → refuse or `block` |
+ *
+ * An UNREADABLE workflow state (a throwing branch read) refuses `bad_state` BEFORE the matrix —
+ * it is never conflated with a confirmed non-dream session (the `activeSessionRunId`
+ * null-on-throw sentinel would otherwise let a transient read failure surface as `absent`).
+ *
+ * Failure taxonomy: gate violations + `buildDreamReport` refusals → `invalid_input` (the
+ * bounded ≤25 named details newline-joined); an unreadable workflow state and
+ * context-recovery failures → `bad_state`.
+ */
+export function resolveDreamReportGate(
+  ctx: SessionDataCtx,
+  input: unknown,
+  generatedAt: string,
+  bracket: (
+    cwd: string,
+    expectedSha: string,
+  ) => { ok: boolean; detail: string | null } = revalidationBracket,
+): DreamReportGateOutcome {
+  // ONE workflow-state snapshot for the whole gate (run identity + the freshness marker),
+  // read with error distinction: unreadable state fails closed, never "non-dream".
+  let state: WorkflowState;
+  try {
+    state = rebuildWorkflowState(branchOf(ctx));
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    return {
+      kind: "refuse",
+      errorType: "bad_state",
+      detail: `session workflow state is unreadable — cannot resolve the dream_report gate: ${detail}`,
+    };
+  }
+  const runId = typeof state.run_id === "string" && state.run_id.length > 0 ? state.run_id : null;
+  const dream =
+    runId !== null && existsSync(join(runScratchDir(ctx.cwd, runId), DREAM_MANIFEST_FILENAME));
+  if (runId === null || !dream) {
+    if (input === undefined) return { kind: "absent" };
+    return {
+      kind: "refuse",
+      errorType: "invalid_input",
+      detail:
+        "dream_report is only valid inside a perk learn dream session — refusing rather than " +
+        "silently dropping it",
+    };
+  }
+  if (input === undefined) {
+    return {
+      kind: "refuse",
+      errorType: "invalid_input",
+      detail:
+        "this dream session's objective must carry dream_report — the objective and its " +
+        "report review as one bundle",
+    };
+  }
+  const recovered = recoverDreamReportContext(ctx, runId, state.dream_bundle_digest, generatedAt);
+  if (!recovered.ok) {
+    return { kind: "refuse", errorType: "bad_state", detail: recovered.detail };
+  }
+  // The revalidation-bracket re-check (contracts.md §8.65): the manifest — with its stamped
+  // commit_sha — is now decoded and authenticated, so re-prove HEAD-unchanged + tree-clean
+  // against it. Both `writeObjectiveDraft` and `saveObjective` flow through this resolver, so
+  // the bracket re-fires at draft-write AND save; non-dream paths never reach it (the matrix
+  // above returned already). The parameter default is the production bracket — tests inject
+  // stubs.
+  const drift = bracket(ctx.cwd, recovered.context.manifest.commit_sha);
+  if (!drift.ok) {
+    return {
+      kind: "refuse",
+      errorType: "bad_state",
+      detail:
+        `the repository moved since the dream snapshot (${drift.detail}) — the analysis is ` +
+        "stale; re-run perk learn dream",
+    };
+  }
+  const built = buildDreamReport(input, recovered.context);
+  if (!built.ok) {
+    return { kind: "refuse", errorType: "invalid_input", detail: built.details.join("\n") };
+  }
+  // The §8.64 invariance mirror, at draft-write AND save (this resolver is both), so an
+  // approved report is always savable by the Python door's identical rule.
+  const violations = reportPartInvarianceViolations(built.parts, runId);
+  if (violations.length > 0) {
+    return {
+      kind: "refuse",
+      errorType: "invalid_input",
+      detail: `dream report parts violate the invariance rule: ${violations.join("; ")}`,
+    };
+  }
+  return { kind: "block", block: { input, generated_at: generatedAt, parts: built.parts } };
+}

package/extension/factories/objectivePlan.ts

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

package/extension/factories/objectiveSave.ts

@@ -15,8 +15,10 @@
 // FAILSAFE invocation of the same seam, keeping the legacy drive-the-session behavior as the
 // no-draft fallback (objectives have no transcript scrape by design).
 
+import { join } from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { bindingSuffix } from "../substrate/bindingDelivery.ts";
+import { atomicWriteFileSync, ensureRunScratch } from "../substrate/cache.ts";
 import {
   booleanField,
   type ColdJson,
@@ -34,14 +36,24 @@ import { OBJECTIVE_BUDGET_TYPE } from "./objective.ts";
 import {
   DELIVERY_PARAM_SCHEMA,
   type DeliveryChoice,
+  DREAM_REPORT_PARAM_SCHEMA,
   decodeObjectiveSaveParams,
   ROADMAP_PARAM_SCHEMA,
   readObjectiveDraft,
 } from "./objectiveDraft.ts";
+import { resolveDreamReportGate } from "./objectiveDreamReport.ts";
 
 /** The `objective-save` registry stage id (the objectiveAuthor.ts constant's sibling). */
 export const OBJECTIVE_SAVE_STAGE = "objective-save";
 
+/**
+ * The run-scoped dream-report transfer filename (contracts §8.64) — the extension→door handoff
+ * carrying the reviewed CANONICAL parts. The Python mirror is
+ * `perk.learn.dream_companion.DREAM_REPORT_TRANSFER_FILENAME` (parity-pinned by test), beside
+ * the existing `DREAM_MANIFEST_FILENAME` mirror pair.
+ */
+export const DREAM_REPORT_TRANSFER_FILENAME = "dream-report-transfer.json";
+
 /** The ok-arm fields — the structured `details` surface doubles as branch-safe persisted state. */
 export interface ObjectiveSaveOk {
   /** `id` is the opaque string objective id (GitHub "7", Linear "ENG-7") — §8.21. */
@@ -70,6 +82,16 @@ function decodeObjectiveCreate(payload: ColdJson): ObjectiveCreatePayload | null
  * The single save implementation both surfaces call. Delegates the GitHub write to the Python cold
  * door, then links the live session (`active_objective` + budget marker). Returns a soft result
  * (never throws); failures set `details.ok = false` and append no linkage.
+ *
+ * `dream_report` is ONE carrier with two sources (§8.63): the direct tool path supplies
+ * `{input}` and the save stamps `generated_at`; the approval path passes the artifact block
+ * through with its stored stamp AND stored parts — the stored parts are byte-compared against
+ * the freshly re-rendered ones, so run-scratch drift or artifact tamper between draft-write
+ * and save refuses `bad_state` (nothing saved, the gate stays on). On the dream arm the
+ * reviewed CANONICAL parts cross to the Python plane through the run-scoped
+ * `dream-report-transfer.json` handoff (§8.64) — staged atomically before the cold door (a
+ * write failure is the soft `scratch_failed` refusal; the door is not invoked) — and
+ * `perk objective create` re-validates the transfer and converges the companion idempotently.
  */
 export async function saveObjective(
   pi: ExtensionAPI,
@@ -80,6 +102,7 @@ export async function saveObjective(
     roadmap?: unknown[];
     base?: string;
     delivery?: DeliveryChoice;
+    dream_report?: { input: unknown; generated_at?: string; parts?: string[] };
   },
 ): Promise<ObjectiveSaveResult> {
   const fail = failFor(ctx, "objective-save");
@@ -91,9 +114,52 @@ export async function saveObjective(
     return fail("roadmap must be a JSON array of nodes", "invalid_input");
   }
 
+  // The §8.63 fail-closed re-validation, before anything reaches the cold door. Presence is
+  // the `opts.dream_report === undefined` boundary — an `{input: undefined}` carrier is never
+  // constructed (the execute wraps only a present decoded value; the approval path passes the
+  // validated artifact block).
+  const generatedAt = opts.dream_report?.generated_at ?? new Date().toISOString();
+  const gate =
+    opts.dream_report === undefined
+      ? resolveDreamReportGate(ctx, undefined, generatedAt)
+      : resolveDreamReportGate(ctx, opts.dream_report.input, generatedAt);
+  if (gate.kind === "refuse") {
+    return fail(gate.detail, gate.errorType);
+  }
+  if (gate.kind === "block" && opts.dream_report?.parts !== undefined) {
+    // The approval path: the reviewed (stored) parts must byte-match the re-render against
+    // freshly recovered context — the same stored `generated_at` stamp keeps the comparison
+    // deterministic.
+    if (JSON.stringify(gate.block.parts) !== JSON.stringify(opts.dream_report.parts)) {
+      return fail(
+        "the reviewed report no longer matches the wave state — re-draft and re-review",
+        "bad_state",
+      );
+    }
+  }
+
   const branch = () => branchOf(ctx);
   const runId = rebuildWorkflowState(branch()).run_id ?? "";
 
+  if (gate.kind === "block") {
+    // The §8.64 transfer write (the dream arm only): the reviewed CANONICAL parts cross to the
+    // Python save door through the run-scoped scratch handoff — written atomically BEFORE the
+    // cold door is invoked. A write failure is the soft `scratch_failed` failure (the
+    // runColdDoor stdin-staging precedent): the cold door is NOT invoked, nothing activates,
+    // and the read-only gate stays on. Non-dream saves write nothing (byte-identical).
+    try {
+      const dir = ensureRunScratch(ctx.cwd, runId);
+      const content = `${JSON.stringify(
+        { schema_version: "1", run_id: runId, parts: gate.block.parts },
+        null,
+        2,
+      )}\n`;
+      atomicWriteFileSync(join(dir, DREAM_REPORT_TRANSFER_FILENAME), content);
+    } catch (err) {
+      return fail(`could not stage the dream-report transfer: ${String(err)}`, "scratch_failed");
+    }
+  }
+
   const args = ["objective", "create", "--json"];
   if (opts.title) args.push("--title", opts.title);
   if (opts.base) args.push("--base", opts.base);
@@ -175,6 +241,9 @@ export async function objectiveApprovalSave(
     roadmap: draft.roadmap,
     base: draft.base,
     delivery: draft.delivery,
+    // The approval path passes the artifact block through whole — stored stamp + stored parts
+    // (the save re-validates and byte-compares, §8.63).
+    ...(draft.dream_report !== undefined ? { dream_report: draft.dream_report } : {}),
   });
   let gateExited = false;
   if (result.details.ok && wasReadOnly) {
@@ -231,6 +300,7 @@ export function registerObjectiveSave(pi: ExtensionAPI, gating: ToolGating): voi
             "Optional target branch for this objective's plans (omit to use the repo default).",
         },
         delivery: DELIVERY_PARAM_SCHEMA,
+        dream_report: DREAM_REPORT_PARAM_SCHEMA,
         roadmap: {
           type: "array",
           description:
@@ -251,7 +321,13 @@ export function registerObjectiveSave(pi: ExtensionAPI, gating: ToolGating): voi
           "bad_input",
         );
       }
-      return saveObjective(pi, ctx, decoded);
+      // The direct tool path wraps ONLY a present decoded value as the `{input}` carrier (the
+      // save stamps generated_at); no stored parts, so no byte-compare on this path.
+      const { dream_report, ...rest } = decoded;
+      return saveObjective(pi, ctx, {
+        ...rest,
+        ...(dream_report !== undefined ? { dream_report: { input: dream_report } } : {}),
+      });
     },
   });