@wildorder/nightshift 0.15.0 → 0.17.0

package/dist/author.d.ts

@@ -3,6 +3,7 @@ import type { NightshiftConfig } from "./config.js";
 import { type PermitsContext } from "./permits.js";
 import { type ReviewPassOutcome } from "./review-pass.js";
 import { type GitOps } from "./run-program.js";
+import { type RunRecorder } from "./run-analytics.js";
 export interface AuthorOptions {
     cwd: string;
     programId: string;
@@ -33,6 +34,13 @@ export interface AuthorOptions {
      * Threaded the same way as `reviewed`.
      */
     triaged?: Set<string>;
+    /**
+     * The run's analytics recorder (WS-01); `runProgram` threads its own
+     * recorder through so authoring's agent/critique spawns can be observed
+     * under the same run. A caller with no run-scoped recorder (a standalone
+     * `author` CLI invocation, tests) gets a shared no-op default.
+     */
+    recorder?: RunRecorder;
 }
 export type AuthorOutcome = {
     status: "authored";
@@ -68,6 +76,10 @@ export interface AuthorResult {
      *  spawned; surfaced here, never fatal — mirrors run-program.ts's
      *  WorkstreamResult.stageErrors (WS-04 SC-12). */
     stageErrors?: string[];
+    /** What the runner had to do about the author's reply — a summary lifted
+     *  out of the spec file, or none emitted at all. Rendered in the report so
+     *  a degraded reply is stated, never silently substituted. */
+    notes?: string[];
 }
 export interface AuthorStageResult {
     programId: string;

package/dist/author.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"author.d.ts","sourceRoot":"","sources":["../src/author.ts"],"names":[],"mappings":"AAEA,OAAO,EAOL,KAAK,WAAW,EAEjB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,KAAK,EAAe,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAkBzE,OAAO,EASL,KAAK,iBAAiB,EAEvB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAiC,KAAK,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAe9E,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,gBAAgB,CAAC;IACzB;iFAC6E;IAC7E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iFAAiF;IACjF,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;sCAEkC;IAClC,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACvB;;;;OAIG;IACH,OAAO,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACvB;AAED,MAAM,MAAM,aAAa,GACrB;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GACvC;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAClB;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzC,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,aAAa,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,gEAAgE;IAChE,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,+EAA+E;IAC/E,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,qEAAqE;IACrE,oBAAoB,EAAE,MAAM,EAAE,CAAC;IAC/B,uEAAuE;IACvE,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,8FAA8F;IAC9F,UAAU,EAAE,OAAO,CAAC;IACpB,gFAAgF;IAChF,YAAY,CAAC,EAAE,iBAAiB,CAAC;IACjC;;sDAEkD;IAClD,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,8EAA8E;IAC9E,mBAAmB,EAAE,OAAO,CAAC;CAC9B;AAooBD;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,iBAAiB,CAAC,CAqjB5B"}
+{"version":3,"file":"author.d.ts","sourceRoot":"","sources":["../src/author.ts"],"names":[],"mappings":"AAEA,OAAO,EAOL,KAAK,WAAW,EAEjB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,KAAK,EAAe,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAkBzE,OAAO,EASL,KAAK,iBAAiB,EAEvB,MAAM,kBAAkB,CAAC;AAO1B,OAAO,EAAwD,KAAK,MAAM,EAAE,MAAM,kBAAkB,CAAC;AACrG,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAezE,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,gBAAgB,CAAC;IACzB;iFAC6E;IAC7E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iFAAiF;IACjF,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;sCAEkC;IAClC,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACvB;;;;OAIG;IACH,OAAO,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACtB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,WAAW,CAAC;CACxB;AAED,MAAM,MAAM,aAAa,GACrB;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GACvC;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAClB;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzC,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,aAAa,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,gEAAgE;IAChE,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,+EAA+E;IAC/E,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,qEAAqE;IACrE,oBAAoB,EAAE,MAAM,EAAE,CAAC;IAC/B,uEAAuE;IACvE,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,8FAA8F;IAC9F,UAAU,EAAE,OAAO,CAAC;IACpB,gFAAgF;IAChF,YAAY,CAAC,EAAE,iBAAiB,CAAC;IACjC;;sDAEkD;IAClD,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB;;kEAE8D;IAC9D,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,8EAA8E;IAC9E,mBAAmB,EAAE,OAAO,CAAC;CAC9B;AAyvBD;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,iBAAiB,CAAC,CA2nB5B"}

package/dist/author.js

@@ -9,7 +9,9 @@ import { reviewDecisions, triageFindings } from "./decider-review.js";
 import { findCycles, stableTopologicalOrder, topologicalLevels } from "./graph.js";
 import { loadManifest, saveManifest, specInputsHash, } from "./manifest.js";
 import { extractFindings, findingsContract, findingsToLedgerEvents, hasRoutableEvidence, locateInRepo, reviewerAbsentOutcome, runReviewPass, verifyEvidence, } from "./review-pass.js";
-import { defaultGitOps, downstreamCone } from "./run-program.js";
+import { createBriefBuilder, demotedDependenciesPoint, promptComponentSizePoints, } from "./prompt-telemetry.js";
+import { commitEvidence, defaultGitOps, downstreamCone, timed } from "./run-program.js";
+import { NOOP_RUN_RECORDER } from "./run-analytics.js";
 /**
  * The authoring stage: for every workstream whose spec does not exist, a
  * clean agent writes it — human-first, grounded in the repository,
@@ -50,23 +52,83 @@ function classifySpec(existing, workstream) {
 }
 /**
  * True when a *returned* (not thrown) author invocation reported failure —
- * a nonzero exit code, an undelivered prompt, or an absent required summary
- * block. Each means the process either reported failure or never produced
- * the reply contract, so any spec it may have written cannot be trusted as
- * complete (WS-01 SC-07): the safe direction is to re-author, not to
- * silently substitute raw output and proceed toward completion.
+ * a nonzero exit code or an undelivered prompt. Each means the process
+ * itself reported failure, so any spec it may have written cannot be
+ * trusted as complete (WS-01 SC-07): the safe direction is to re-author.
+ *
+ * A missing summary block is deliberately *not* a protocol failure. The
+ * summary contract (`agent-summary.ts`) says a missing block is never fatal,
+ * and the implementer path honors that; the author path once did not, and
+ * the first real run to hit it discarded a complete 36 KB spec because the
+ * agent ended the *file* with its summary instead of its *reply*. The spec
+ * is the artifact; its presence is checked deterministically above. The
+ * reply's shape is a proxy, and grading the proxy is the courtroom.
  */
-function isAuthorProtocolFailure(invocation, summary) {
-    return invocation.exitCode !== 0 || invocation.inputError !== undefined || !summary.available;
+function isAuthorProtocolFailure(invocation) {
+    return invocation.exitCode !== 0 || invocation.inputError !== undefined;
 }
-function describeProtocolFailure(invocation, summary) {
+function describeProtocolFailure(invocation) {
     const parts = [`exit code ${invocation.exitCode}`];
     if (invocation.inputError !== undefined)
         parts.push(`input error: ${invocation.inputError}`);
-    if (!summary.available)
-        parts.push("no summary block in the reply");
     return parts.join(", ");
 }
+/**
+ * A fenced summary block that ends the spec file, with nothing after it.
+ * Only a *trailing* block is treated as a misplaced reply: a summary block
+ * quoted mid-document is spec content and stays untouched.
+ */
+const TRAILING_SUMMARY_BLOCK = /(?:\r?\n)*```summary[^\S\r\n]*\r?\n([\s\S]*?)```\s*$/u;
+/**
+ * When an author emitted no summary in its reply, the block usually landed
+ * at the end of the spec it wrote — the agent treated the file as its
+ * output. Lift it out: the summary is recorded as the agent's own words and
+ * the spec no longer carries a reply artifact the implementer would read.
+ * Returns the salvaged summary and the spec content *before* stripping (so
+ * decision blocks the agent also wrote into the file can be journaled), or
+ * undefined when the file has no trailing summary block. Never throws.
+ */
+async function salvageSummaryFromSpec(root, workstream) {
+    const path = join(root, workstream.taskFile);
+    let content;
+    try {
+        content = await readFile(path, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    const match = TRAILING_SUMMARY_BLOCK.exec(content);
+    const text = match?.[1]?.trim();
+    if (match === null || text === undefined || text === "")
+        return undefined;
+    const stripped = `${content.slice(0, match.index).replace(/\s+$/u, "")}\n`;
+    await writeFile(path, stripped, "utf8");
+    return { summary: text, spec: content };
+}
+/**
+ * The summary and decision source for an author reply, degrading in order:
+ * the reply's own block; a block salvaged from the end of the spec file; the
+ * reply's output tail. Each degradation is stated in `notes` so the run
+ * report says what happened instead of silently substituting.
+ */
+async function resolveAuthorReply(root, workstream, invocation, notes) {
+    const fromReply = resolveSummary(invocation.output);
+    if (fromReply.available)
+        return { summary: fromReply, decisionSource: invocation.output };
+    const salvaged = await salvageSummaryFromSpec(root, workstream);
+    if (salvaged !== undefined) {
+        notes.push(`${workstream.id}'s author wrote its summary block into ${workstream.taskFile} ` +
+            `instead of ending its reply with it; the runner lifted the block out of the ` +
+            `spec and recorded it as the summary.`);
+        return {
+            summary: { text: salvaged.summary, available: true, needsPermission: [] },
+            decisionSource: `${invocation.output}\n${salvaged.spec}`,
+        };
+    }
+    notes.push(`${workstream.id}'s author ended its reply without a summary block; the tail of ` +
+        `its reply was recorded instead. The spec it wrote is kept.`);
+    return { summary: fromReply, decisionSource: invocation.output };
+}
 async function programDocumentSection(root, manifest) {
     const relPath = join("docs", "programs", `${manifest.program.id}-program.md`);
     let content;
@@ -166,6 +228,7 @@ async function dependencySpecsSection(root, workstream, rosterById) {
         return {
             section: ["## Dependency specs", "", "No dependencies declared.", ""],
             demoted: [],
+            demotedBytes: 0,
         };
     }
     const entries = await Promise.all(workstream.dependencies
@@ -177,6 +240,7 @@ async function dependencySpecsSection(root, workstream, rosterById) {
     })));
     let total = entries.reduce((sum, e) => sum + (e.content?.length ?? 0), 0);
     const demoted = new Set();
+    let demotedBytes = 0;
     const bySizeDesc = entries
         .filter((e) => e.content !== undefined)
         .sort((a, b) => (b.content?.length ?? 0) - (a.content?.length ?? 0));
@@ -185,6 +249,7 @@ async function dependencySpecsSection(root, workstream, rosterById) {
             break;
         demoted.add(e.entry.id);
         total -= e.content?.length ?? 0;
+        demotedBytes += e.content === undefined ? 0 : Buffer.byteLength(e.content, "utf8");
     }
     const lines = ["## Dependency specs", ""];
     for (const { entry, content } of entries) {
@@ -202,7 +267,7 @@ async function dependencySpecsSection(root, workstream, rosterById) {
         lines.push(`### ${entry.id} ${entry.name}`, "", content.trim(), "");
     }
     lines.push("");
-    return { section: lines, demoted: [...demoted] };
+    return { section: lines, demoted: [...demoted], demotedBytes };
 }
 const SPEC_CONTRACT = [
     "## Write a spec for a human",
@@ -247,39 +312,36 @@ block entirely when you have nothing to add.
 function dependenciesContract() {
     return DEPENDENCIES_CONTRACT;
 }
+/**
+ * Builds the author's brief, byte-for-byte identical to the plain
+ * `array.join("\n")` this produced before WS-03 — but through a
+ * `BriefBuilder` so every line is also classified into an SC-07 prompt
+ * component, with `components` summing exactly to the joined brief's byte
+ * length.
+ */
 async function authorBrief(root, manifest, workstream, rosterById, reauthorNote) {
     const programDoc = await programDocumentSection(root, manifest);
     const deps = await dependencySpecsSection(root, workstream, rosterById);
-    const brief = [
-        `# Workstream ${workstream.id}: ${workstream.name}`,
-        "",
-        `Program: ${manifest.program.id} — ${manifest.program.name}`,
-        "",
-        "Write this workstream's specification document — the narrative file a",
-        "human and a later implementing agent will both read to build it.",
-        "",
-        ...programDoc,
-        ...successCriteriaSection(manifest),
-        ...scopeSection(workstream),
-        ...rosterSection(manifest),
-        ...prerequisitesSection(manifest, workstream),
-        ...deps.section,
-        ...(reauthorNote ? [reauthorNote, ""] : []),
-        SPEC_CONTRACT,
-        GROUNDING_CONTRACT,
-        dependenciesContract(),
-        "",
-        "## Rules",
-        "",
-        "- Write exactly one file: this workstream's taskFile (create parent",
-        "  directories as needed). Do not write or edit any other file.",
-        "- Never commit; the runner owns commits.",
-        "",
-        decisionContract(),
-        "",
-        summaryContract(),
-    ].join("\n");
-    return { brief, demoted: deps.demoted };
+    const builder = createBriefBuilder();
+    builder.push("framing", `# Workstream ${workstream.id}: ${workstream.name}`, "");
+    builder.push("program-narrative", `Program: ${manifest.program.id} — ${manifest.program.name}`);
+    builder.push("framing", "", "Write this workstream's specification document — the narrative file a", "human and a later implementing agent will both read to build it.", "");
+    builder.push("program-narrative", ...programDoc);
+    builder.push("success-criteria", ...successCriteriaSection(manifest));
+    builder.push("scope", ...scopeSection(workstream));
+    builder.push("roster", ...rosterSection(manifest));
+    builder.push("prerequisites", ...prerequisitesSection(manifest, workstream));
+    builder.push("dependency-specs", ...deps.section);
+    builder.push("re-author-note", ...(reauthorNote ? [reauthorNote, ""] : []));
+    builder.push("runner-instructions", SPEC_CONTRACT, GROUNDING_CONTRACT, dependenciesContract());
+    builder.push("framing", "", "## Rules", "", "- Write exactly one file: this workstream's taskFile (create parent", "  directories as needed). Do not write or edit any other file.", "- Your reply is a separate channel from that file. The decision and", "  summary blocks described below go in your reply, never inside the", "  taskFile — the runner reads them from what you say, not what you wrote.", "- Never commit; the runner owns commits.", "");
+    builder.push("runner-instructions", decisionContract(), "", summaryContract());
+    return {
+        brief: builder.join(),
+        demoted: deps.demoted,
+        demotedBytes: deps.demotedBytes,
+        components: builder.components(),
+    };
 }
 const SPEC_CRITIQUE_FRAMING = [
     "## Critique this spec",
@@ -405,8 +467,10 @@ async function runSpecCritique(options) {
     const reviewer = resolveReviewerAgent(options.config);
     if (!reviewer)
         return reviewerAbsentOutcome();
+    const recorder = options.recorder ?? NOOP_RUN_RECORDER;
     const locate = (file) => locateInRepo(options.root, file);
-    const review = async (_round, priorOpen) => {
+    const span = recorder.span({ stage: "spec-critique", workstream: options.workstream.id });
+    const review = async (round, priorOpen) => {
         const currentSpec = (await readFinishedSpec(options.root, options.workstream)) ?? options.spec;
         const brief = await specCritiqueReviewerBrief(options.root, options.manifest, options.workstream, options.rosterById, currentSpec, priorOpen);
         let invocation;
@@ -416,7 +480,7 @@ async function runSpecCritique(options) {
                 programId: options.programId,
                 label: `${options.workstream.id}-spec-critique-reviewer`,
                 log: options.log,
-            });
+            }, recorder, { workstream: options.workstream.id, attemptIndex: round });
         }
         catch (error) {
             // Fail open, matching the equivalent build-side guard in
@@ -433,7 +497,7 @@ async function runSpecCritique(options) {
         const ran = invocation.exitCode === 0 && hasFindingsBlock(invocation.output);
         return { findings, errors: parsed.errors, ran };
     };
-    const respond = async (_round, findings) => {
+    const respond = async (round, findings) => {
         const currentSpec = (await readFinishedSpec(options.root, options.workstream)) ?? options.spec;
         const brief = specCritiqueWriterBrief(options.workstream, currentSpec, findings);
         let invocation;
@@ -443,7 +507,7 @@ async function runSpecCritique(options) {
                 programId: options.programId,
                 label: `${options.workstream.id}-spec-critique-writer`,
                 log: options.log,
-            });
+            }, recorder, { workstream: options.workstream.id, attemptIndex: round });
         }
         catch (error) {
             // Fail open: the spec is left as the reviewer last saw it and the
@@ -455,7 +519,15 @@ async function runSpecCritique(options) {
         }
         return { note: resolveSummary(invocation.output).text };
     };
-    return runReviewPass({ review, respond });
+    try {
+        const outcome = await runReviewPass({ review, respond });
+        span.close({ outcome: "success" });
+        return outcome;
+    }
+    catch (error) {
+        span.close({ outcome: "failed" });
+        throw error;
+    }
 }
 function mergeDependencies(workstream, rosterIds, declaredIds) {
     const merged = [];
@@ -516,6 +588,7 @@ export async function authorProgram(options) {
     const force = options.force === true;
     const reviewed = options.reviewed ?? new Set();
     const triaged = options.triaged ?? new Set();
+    const recorder = options.recorder ?? NOOP_RUN_RECORDER;
     const manifest = await loadManifest(root, options.programId);
     const resolvedAuthor = resolveAuthorAgent(config);
     if (!resolvedAuthor) {
@@ -595,7 +668,7 @@ export async function authorProgram(options) {
         };
         if (blockedCone.has(workstream.id)) {
             workstream.status = "parked";
-            await saveManifest(root, options.programId, manifest, { log });
+            await timed(recorder, { stage: "manifest-persist", workstream: workstream.id }, () => saveManifest(root, options.programId, manifest, { log }));
             base.outcome = {
                 status: "parked",
                 reason: "an upstream dependency's authoring failed; parked, not attempted",
@@ -622,7 +695,7 @@ export async function authorProgram(options) {
                 workstream.specHash !== undefined &&
                 specInputsHash(manifest, workstream) === workstream.specHash) {
                 workstream.specStatus = "complete";
-                await saveManifest(root, options.programId, manifest, { log });
+                await timed(recorder, { stage: "manifest-persist", workstream: workstream.id }, () => saveManifest(root, options.programId, manifest, { log }));
                 log(`${workstream.id}: recognized as completed legacy authoring — ` +
                     'normalized to specStatus "complete"');
                 return base;
@@ -639,7 +712,7 @@ export async function authorProgram(options) {
                 const current = specInputsHash(manifest, workstream);
                 if (current !== workstream.specHash) {
                     workstream.status = "parked";
-                    await saveManifest(root, options.programId, manifest, { log });
+                    await timed(recorder, { stage: "manifest-persist", workstream: workstream.id }, () => saveManifest(root, options.programId, manifest, { log }));
                     for (const id of downstreamCone(manifest.workstreams, [workstream.id])) {
                         blockedCone.add(id);
                     }
@@ -669,12 +742,18 @@ export async function authorProgram(options) {
         const allDecisionsById = new Map();
         const first = await authorBrief(root, manifest, workstream, rosterById);
         base.demotedDependencies = first.demoted;
+        for (const point of promptComponentSizePoints(first.components, { role: "authorAgent" })) {
+            recorder.point(point);
+        }
+        const firstDemotedPoint = demotedDependenciesPoint(first.demoted, first.demotedBytes, { role: "authorAgent" });
+        if (firstDemotedPoint)
+            recorder.point(firstDemotedPoint);
         // Stamped before the agent can write anything (SC-01): the agent has
         // whole-file write access, so a crash at any point after this line
         // leaves a durable `in_progress` marker the next attempt classifies as
         // interrupted, regardless of whether a partial file exists.
         workstream.specStatus = "in_progress";
-        await saveManifest(root, options.programId, manifest, { log });
+        await timed(recorder, { stage: "manifest-persist", workstream: workstream.id }, () => saveManifest(root, options.programId, manifest, { log }));
         let invocation;
         try {
             invocation = await invokeAgent(agentRunner, author, first.brief, root, permits, "authorAgent", {
@@ -682,7 +761,7 @@ export async function authorProgram(options) {
                 programId: options.programId,
                 label: `${workstream.id}-author`,
                 log,
-            });
+            }, recorder, { stage: "author", workstream: workstream.id });
         }
         catch (error) {
             // A spawn error here means the author agent never started — the same
@@ -694,7 +773,7 @@ export async function authorProgram(options) {
             // stays `in_progress` — never cleared on a failure path — so a later
             // retry resumes without needing --force (SC-07).
             workstream.status = "parked";
-            await saveManifest(root, options.programId, manifest, { log });
+            await timed(recorder, { stage: "manifest-persist", workstream: workstream.id }, () => saveManifest(root, options.programId, manifest, { log }));
             for (const id of downstreamCone(manifest.workstreams, [workstream.id])) {
                 blockedCone.add(id);
             }
@@ -705,28 +784,30 @@ export async function authorProgram(options) {
             };
             return base;
         }
-        const firstSummary = resolveSummary(invocation.output);
-        if (isAuthorProtocolFailure(invocation, firstSummary)) {
-            // The process reported failure, its prompt was not fully delivered, or
-            // it never produced the required summary contract — any spec it may
-            // have written cannot be trusted as complete (SC-07). Park exactly
-            // like a spawn failure and leave `specStatus` at `in_progress` so a
-            // force-free retry re-authors.
+        if (isAuthorProtocolFailure(invocation)) {
+            // The process reported failure or its prompt was not fully delivered —
+            // any spec it may have written cannot be trusted as complete (SC-07).
+            // Park exactly like a spawn failure and leave `specStatus` at
+            // `in_progress` so a force-free retry re-authors.
             workstream.status = "parked";
-            await saveManifest(root, options.programId, manifest, { log });
+            await timed(recorder, { stage: "manifest-persist", workstream: workstream.id }, () => saveManifest(root, options.programId, manifest, { log }));
             for (const id of downstreamCone(manifest.workstreams, [workstream.id])) {
                 blockedCone.add(id);
             }
-            base.summary = firstSummary.text;
+            base.summary = resolveSummary(invocation.output).text;
             base.outcome = {
                 status: "failed",
-                reason: `the author agent reported a protocol failure (${describeProtocolFailure(invocation, firstSummary)}); ` +
+                reason: `the author agent reported a protocol failure (${describeProtocolFailure(invocation)}); ` +
                     `not trusted as a finished spec.`,
             };
             return base;
         }
-        base.summary = firstSummary.text;
-        let parsed = extractDecisions(invocation.output);
+        const notes = [];
+        const firstReply = await resolveAuthorReply(root, workstream, invocation, notes);
+        base.summary = firstReply.summary.text;
+        if (notes.length > 0)
+            (base.notes ??= []).push(...notes);
+        let parsed = extractDecisions(firstReply.decisionSource);
         base.decisionErrors.push(...parsed.errors);
         for (const decision of parsed.decisions) {
             allDecisionsById.set(decisionFingerprint(workstream.id, decision), decision);
@@ -744,12 +825,12 @@ export async function authorProgram(options) {
         if (merge.merged.length > 0) {
             const originalDependencies = workstream.dependencies.filter((id) => !merge.merged.includes(id));
             base.mergedDependencies = merge.merged;
-            await saveManifest(root, options.programId, manifest, { log });
+            await timed(recorder, { stage: "manifest-persist", workstream: workstream.id }, () => saveManifest(root, options.programId, manifest, { log }));
             log(`${workstream.id}: merged new dependency edge(s): ${merge.merged.join(", ")}`);
             const cyclesNow = findCycles(manifest.workstreams);
             if (cyclesNow.length > 0) {
                 workstream.dependencies = originalDependencies;
-                await saveManifest(root, options.programId, manifest, { log });
+                await timed(recorder, { stage: "manifest-persist", workstream: workstream.id }, () => saveManifest(root, options.programId, manifest, { log }));
                 throw new Error(`Dependency cycle(s) created by a discovered edge from ${workstream.id}: ` +
                     `${cyclesNow.map((cycle) => cycle.join(" -> ")).join("; ")}. Re-plan with /plan-program.`);
             }
@@ -777,9 +858,17 @@ export async function authorProgram(options) {
                 ].join("\n");
                 const second = await authorBrief(root, manifest, workstream, rosterById, note);
                 base.demotedDependencies = second.demoted;
+                for (const point of promptComponentSizePoints(second.components, { role: "authorAgent" })) {
+                    recorder.point(point);
+                }
+                const secondDemotedPoint = demotedDependenciesPoint(second.demoted, second.demotedBytes, {
+                    role: "authorAgent",
+                });
+                if (secondDemotedPoint)
+                    recorder.point(secondDemotedPoint);
                 let reauthorInvocation;
                 try {
-                    reauthorInvocation = await invokeAgent(agentRunner, author, second.brief, root, permits, "authorAgent", { root, programId: options.programId, label: `${workstream.id}-author-reauthor`, log });
+                    reauthorInvocation = await invokeAgent(agentRunner, author, second.brief, root, permits, "authorAgent", { root, programId: options.programId, label: `${workstream.id}-author-reauthor`, log }, recorder, { stage: "re-author", workstream: workstream.id });
                 }
                 catch (error) {
                     // Fail open: the first pass already wrote a spec and journaled
@@ -790,35 +879,38 @@ export async function authorProgram(options) {
                         `pass: ${error.message}. The pre-discovery spec was kept.`);
                 }
                 if (reauthorInvocation !== undefined) {
-                    const reauthorSummary = resolveSummary(reauthorInvocation.output);
-                    if (isAuthorProtocolFailure(reauthorInvocation, reauthorSummary)) {
+                    if (isAuthorProtocolFailure(reauthorInvocation)) {
                         // A *returned* protocol failure on the re-author pass is treated
                         // exactly like one on the first invocation (SC-07): the process
-                        // reported failure, its prompt was not fully delivered, or it
-                        // never produced the summary contract, so nothing this pass
-                        // produced can be trusted — park, isolate the downstream cone,
-                        // and leave specStatus at in_progress for a force-free retry.
-                        // This differs from a *thrown* spawn error above, which fails
-                        // open because the first pass's spec is otherwise untouched; a
-                        // returned failure carries no such guarantee.
+                        // reported failure or its prompt was not fully delivered, so
+                        // nothing this pass produced can be trusted — park, isolate the
+                        // downstream cone, and leave specStatus at in_progress for a
+                        // force-free retry. This differs from a *thrown* spawn error
+                        // above, which fails open because the first pass's spec is
+                        // otherwise untouched; a returned failure carries no such
+                        // guarantee.
                         workstream.status = "parked";
-                        await saveManifest(root, options.programId, manifest, { log });
+                        await timed(recorder, { stage: "manifest-persist", workstream: workstream.id }, () => saveManifest(root, options.programId, manifest, { log }));
                         for (const id of downstreamCone(manifest.workstreams, [workstream.id])) {
                             blockedCone.add(id);
                         }
-                        base.summary = reauthorSummary.text;
+                        base.summary = resolveSummary(reauthorInvocation.output).text;
                         base.outcome = {
                             status: "failed",
                             reason: `the author agent reported a protocol failure during ${workstream.id}'s ` +
-                                `re-author pass (${describeProtocolFailure(reauthorInvocation, reauthorSummary)}); ` +
+                                `re-author pass (${describeProtocolFailure(reauthorInvocation)}); ` +
                                 `not trusted as a finished spec.`,
                         };
                         return base;
                     }
                     else {
                         invocation = reauthorInvocation;
-                        base.summary = reauthorSummary.text;
-                        parsed = extractDecisions(invocation.output);
+                        const reauthorNotes = [];
+                        const reauthorReply = await resolveAuthorReply(root, workstream, reauthorInvocation, reauthorNotes);
+                        base.summary = reauthorReply.summary.text;
+                        if (reauthorNotes.length > 0)
+                            (base.notes ??= []).push(...reauthorNotes);
+                        parsed = extractDecisions(reauthorReply.decisionSource);
                         base.decisionErrors.push(...parsed.errors);
                         for (const decision of parsed.decisions) {
                             allDecisionsById.set(decisionFingerprint(workstream.id, decision), decision);
@@ -837,7 +929,7 @@ export async function authorProgram(options) {
         const final = await readFinishedSpec(root, workstream);
         if (final === undefined) {
             workstream.status = "parked";
-            await saveManifest(root, options.programId, manifest, { log });
+            await timed(recorder, { stage: "manifest-persist", workstream: workstream.id }, () => saveManifest(root, options.programId, manifest, { log }));
             for (const id of downstreamCone(manifest.workstreams, [workstream.id])) {
                 blockedCone.add(id);
             }
@@ -863,6 +955,7 @@ export async function authorProgram(options) {
             author,
             log,
             pushStageError: (message) => (base.stageErrors ??= []).push(message),
+            recorder,
         });
         base.specCritique = critique;
         const postCritique = await readFinishedSpec(root, workstream);
@@ -877,7 +970,7 @@ export async function authorProgram(options) {
             ...(baseCommit === undefined ? {} : { baseCommit }),
             now,
         });
-        await appendLedgerEvents(root, options.programId, critiqueEvents);
+        await timed(recorder, { stage: "ledger-persist", workstream: workstream.id }, () => appendLedgerEvents(root, options.programId, critiqueEvents));
         // Stamped after every dependency merge above, so the hash records the
         // manifest exactly as this spec's author last saw it — a later manifest
         // edit is drift; authoring's own merges are not. `specStatus` is
@@ -887,10 +980,10 @@ export async function authorProgram(options) {
         // must still classify as interrupted on retry, not falsely complete with
         // an unmade commit.
         workstream.specHash = specInputsHash(manifest, workstream);
-        await saveManifest(root, options.programId, manifest, { log });
+        await timed(recorder, { stage: "manifest-persist", workstream: workstream.id }, () => saveManifest(root, options.programId, manifest, { log }));
         let commit;
         if (isRepository) {
-            commit = await git.commitPaths(root, `nightshift(${options.programId}): author ${workstream.id} ${workstream.name}`, [workstream.taskFile, "docs/programs"]);
+            commit = await timed(recorder, { stage: "git-commit", workstream: workstream.id }, () => git.commitPaths(root, `nightshift(${options.programId}): author ${workstream.id} ${workstream.name}`, [workstream.taskFile, "docs/programs"]), commitEvidence);
         }
         // Outside a git repository there is no commit to wait for — the finished
         // spec, its specHash, and this manifest save are already the durable
@@ -898,7 +991,7 @@ export async function authorProgram(options) {
         // only runs after `commitPaths` above resolves, so the transition is
         // recoverable on both sides of the commit (SC-01, SC-02).
         workstream.specStatus = "complete";
-        await saveManifest(root, options.programId, manifest, { log });
+        await timed(recorder, { stage: "manifest-persist", workstream: workstream.id }, () => saveManifest(root, options.programId, manifest, { log }));
         {
             const spawnErrors = await reviewWorkstreamDecisions(workstream.id, [...allDecisionsById.values()], baseCommit);
             if (spawnErrors.length > 0)
@@ -925,7 +1018,7 @@ export async function authorProgram(options) {
             ...(baseCommit === undefined ? {} : { baseCommit }),
             decidedBy: "implementer",
         }));
-        await appendLedgerEvents(root, options.programId, events);
+        await timed(recorder, { stage: "ledger-persist", workstream: workstream.id }, () => appendLedgerEvents(root, options.programId, events));
         for (const decision of decisions) {
             log(`${workstream.id} decision: ${decision.title} -> ${decision.chosen}`);
         }
@@ -948,6 +1041,7 @@ export async function authorProgram(options) {
             now,
             log,
             observe: { root, programId: options.programId, label: `${workstreamId}-decider-decision`, log },
+            recorder,
         });
     }
     function reviewWorkstreamFindings(workstreamId, findings, baseCommit) {
@@ -968,6 +1062,7 @@ export async function authorProgram(options) {
             now,
             log,
             observe: { root, programId: options.programId, label: `${workstreamId}-decider-finding`, log },
+            recorder,
         });
     }
 }