@wildorder/nightshift 0.14.0 → 0.16.0

package/README.md

@@ -33,7 +33,7 @@ npx --yes @wildorder/nightshift --help
 
 What you need before anything else:
 
-- **Node.js 20+** and a **git repository** (an existing project or a fresh one).
+- **Node.js 22+** and a **git repository** (an existing project or a fresh one).
 - **At least one coding-agent CLI** installed and authenticated on the
   machine that will run programs — `claude` (Claude Code) and `codex` are
   the two exercised daily. Two different providers is the intended shape:
@@ -77,36 +77,38 @@ things only you can write:
   "authorAgent":   { "command": "claude", "args": ["-p", "--model", "opus"], "promptMode": "stdin" },
   "deciderAgent":  { "command": "codex", "args": ["exec", "--model", "gpt-5.6-sol"], "promptMode": "stdin" },
   "reviewerAgent": { "command": "codex", "args": ["exec"] },
-  "recoveryAgent": { "command": "codex", "args": ["exec", "--model", "gpt-5.6-sol", "--sandbox", "workspace-write"], "promptMode": "stdin" }
+  "recoveryAgent": { "command": "codex", "args": ["exec", "--model", "gpt-5.6-sol"], "promptMode": "stdin" },
+  "permits": {
+    "policy": "Anything inside this repository is fine, including installing dev dependencies and creating fixture files. Do not reach the network beyond npm install. Never push, publish, or change global git or npm configuration.",
+    "allow": ["Bash(git stash:*)"],
+    "deny": ["Bash(git push:*)", "Bash(npm publish:*)", "Bash(git config --global:*)", "Bash(npm config set:*)"]
+  }
 }
 ```
 
-Notice what is missing: no `--permission-mode`, no `--allowedTools`. nightshift
-derives each role's permission posture itself — from the role (`agent`,
-`authorAgent`, and `recoveryAgent` get a workspace posture; `deciderAgent` and
-`reviewerAgent` get read-only, never edit-capable regardless of the host) and
-from the host it runs on (a claude `auto` classifier plus an OS sandbox on
-macOS/Linux, a `--sandbox workspace-write` grant on codex, a documented
-fallback when a capability cannot be detected). `recoveryAgent`'s
-`--sandbox workspace-write` above is still honored untouched: any
-permission-bearing flag an operator already wrote — `--permission-mode`,
-`--allowedTools`, `--sandbox`, and their siblings — always wins, and that
-role is reported as operator-configured rather than silently overridden.
-
-An optional `permits` block widens or narrows the derived posture without
-hand-writing provider flags:
-
-```json
-"permits": {
-  "policy": "free prose read by the implementer and recovery briefs",
-  "allow": ["Bash(git stash:*)"],
-  "deny": ["Bash(rm -rf *)"]
-}
-```
+Notice what is missing: no `--permission-mode`, no `--allowedTools`, no
+`--sandbox`. nightshift derives each role's permission posture itself — from
+the role (`agent`, `authorAgent`, and `recoveryAgent` get a workspace posture;
+`deciderAgent` and `reviewerAgent` get read-only, never edit-capable
+regardless of the host) and from the host it runs on (a claude `auto`
+classifier plus an OS sandbox on macOS/Linux, a `--sandbox workspace-write`
+grant on codex write seats and `--sandbox read-only` on its reply-only seats,
+a documented fallback when a capability cannot be detected). Any
+permission-bearing flag an operator writes anyway — `--permission-mode`,
+`--allowedTools`, `--sandbox`, and their siblings — always wins untouched,
+and that role is reported as operator-configured rather than silently
+overridden.
+
+The optional `permits` block, shown above as this repository uses it, widens
+or narrows the derived posture without hand-writing provider flags: `policy`
+is prose the implementer and recovery briefs quote verbatim (the same thing
+you would tell a contractor on day one), `allow` names commands that never
+wait on the classifier, and `deny` is the short catastrophic list that binds
+in every mode.
 
 `allow`/`deny` use Claude's rule syntax and fold into the generated settings
-file every claude spawn reads; `policy` is prose the implementer/recovery
-briefs quote verbatim. On a throwaway CI runner, set
+file every claude spawn reads; codex has no per-command rules, so on those
+seats only the sandbox and the brief's policy apply. On a throwaway CI runner, set
 `NIGHTSHIFT_CONTAINMENT=ephemeral` in the environment to let workspace-posture
 roles skip permission prompts entirely (`ci init github`'s hosted variant sets
 this for you; never set it on a machine you or someone else works on
@@ -118,14 +120,14 @@ derived posture a real run would use, verifies on disk that the writing seats
 can write, and reports whether they can run the verify commands — the
 environment failures that otherwise burn a whole run's budget (a sandboxed
 shell, an untrusted workspace, a read-only recovery agent) show up as one
-labeled line each instead. Note `recoveryAgent`'s `--sandbox workspace-write`
-above: `codex exec` defaults to a read-only sandbox, which is the right
-posture for the decider and reviewer seats and exactly wrong for a seat that
-must fix a failing tree. nightshift does not trust that default, though: the
-decider and reviewer seats are spawned with an explicit `--sandbox read-only`,
-because a codex user config can widen the default (a `sandbox = "elevated"`
-setting, a trusted-project entry) and a seat labeled read-only that can write
-is exactly the kind of quiet mismatch the posture lines exist to prevent.
+labeled line each instead. On codex, `exec` defaults to a read-only sandbox,
+which is the right posture for the decider and reviewer seats and exactly
+wrong for a seat that must fix a failing tree — so nightshift spawns
+`recoveryAgent` with `--sandbox workspace-write` and, rather than trusting the
+default, the decider and reviewer with an explicit `--sandbox read-only`. A
+codex user config can widen the default (a `sandbox = "elevated"` setting, a
+trusted-project entry), and a seat labeled read-only that can write is exactly
+the kind of quiet mismatch the posture lines exist to prevent.
 
 Only `agent` is required to run; every other role degrades loudly, not
 silently, when absent. The verify commands are the contract every
@@ -230,16 +232,25 @@ or to see the specs before a build starts:
 nightshift author <program-id>
 ```
 
-A `taskFile` that already exists is always kept, never overwritten. To
-deliberately re-author one after a plan edit, name it explicitly and force it:
+A finished `taskFile` is always kept, never overwritten, and an interrupted
+attempt — one a crash or a killed process cut off partway through — is
+re-authored automatically, without `--force`: a durable marker in the
+manifest, not the file's existence, is what proves authoring finished.
+
+Two flags select a range and a force level, independently:
 
 ```sh
-nightshift author <program-id> --only WS-03 --force
+nightshift author <program-id> --from WS-03
+nightshift author <program-id> --from WS-03 --force
 ```
 
-`--force` on its own does nothing to existing specs — it only takes effect
-for ids named in `--only`, so a bare `--force` can never silently regenerate
-a program's worth of hand-reviewed specs.
+`--from <workstream-id>` resumes from that workstream onward, in dependency
+order; everything before it is left untouched. Within the selected range,
+plain authoring (no `--force`) only writes missing or interrupted specs —
+completed and hand-authored ones are kept. Adding `--force` regenerates
+every selected spec, including already-completed ones, so `--from WS-03
+--force` regenerates WS-03 and everything after it. A bare `--force` with no
+`--from` selects the whole roster and regenerates every spec in the program.
 
 ## Flipping a decision
 
@@ -268,7 +279,7 @@ implementer brief carries it as binding.
 
 ## Development
 
-Requires Node.js 20+.
+Requires Node.js 22+.
 
 ```sh
 npm ci

package/dist/author.d.ts

@@ -7,9 +7,10 @@ export interface AuthorOptions {
     cwd: string;
     programId: string;
     config: NightshiftConfig;
-    /** Workstream ids eligible for `force` re-authoring. */
-    only?: string[];
-    /** Re-author ids named in `only`, even though their spec already exists. */
+    /** Workstream id to begin authoring from, in stable authoring order.
+     *  Undefined selects the whole roster. Validated before any agent spawns. */
+    from?: string;
+    /** Re-author every selected workstream, even ones already complete or legacy. */
     force?: boolean;
     agentRunner?: AgentRunner;
     /** Defaults to a no-op context; the owner (`runProgram`, or the `author`
@@ -67,6 +68,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,wDAAwD;IACxD,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,4EAA4E;IAC5E,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;AA6lBD;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,iBAAiB,CAAC,CA8b5B"}
+{"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;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;AAktBD;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,iBAAiB,CAAC,CA6jB5B"}

package/dist/author.js

@@ -6,7 +6,7 @@ import { NOOP_PERMITS_CONTEXT } from "./permits.js";
 import { decisionContract, decisionFingerprint, extractDecisions, } from "./decision.js";
 import { appendLedgerEvents } from "./decision-ledger.js";
 import { reviewDecisions, triageFindings } from "./decider-review.js";
-import { findCycles, topologicalLevels } from "./graph.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";
@@ -31,6 +31,102 @@ async function readFinishedSpec(root, workstream) {
         return undefined;
     }
 }
+/**
+ * Classifies a workstream's spec by runner-owned lifecycle state, not by
+ * file existence alone: a non-empty `taskFile` proves only that writing
+ * started, never that authoring finished (WS-01 SC-01/SC-02/SC-03).
+ * Precedence: `missing` first regardless of the marker (a deleted taskFile is
+ * always re-authored), then `interrupted` (a prior attempt did not finish,
+ * even though it left a non-empty partial file), then the two kept classes.
+ */
+function classifySpec(existing, workstream) {
+    if (existing === undefined)
+        return "missing";
+    if (workstream.specStatus === "in_progress")
+        return "interrupted";
+    if (workstream.specStatus === "complete")
+        return "complete";
+    return "legacy";
+}
+/**
+ * True when a *returned* (not thrown) author invocation reported failure —
+ * 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) {
+    return invocation.exitCode !== 0 || invocation.inputError !== undefined;
+}
+function describeProtocolFailure(invocation) {
+    const parts = [`exit code ${invocation.exitCode}`];
+    if (invocation.inputError !== undefined)
+        parts.push(`input error: ${invocation.inputError}`);
+    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;
@@ -237,6 +333,9 @@ async function authorBrief(root, manifest, workstream, rosterById, reauthorNote)
         "",
         "- 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.",
         "",
         decisionContract(),
@@ -477,7 +576,6 @@ export async function authorProgram(options) {
     const git = options.git ?? defaultGitOps;
     const log = options.log ?? ((line) => console.log(line));
     const now = options.now ?? (() => new Date());
-    const only = options.only;
     const force = options.force === true;
     const reviewed = options.reviewed ?? new Set();
     const triaged = options.triaged ?? new Set();
@@ -504,6 +602,25 @@ export async function authorProgram(options) {
             .map((cycle) => cycle.join(" -> "))
             .join("; ")}. Re-plan with /plan-program.`);
     }
+    // The selected range (SC-05): computed once, up front, from the manifest
+    // as loaded — before any agent spawns — so `--from` validation and the
+    // selected set are deterministic, independent of dependency edges an
+    // author might discover mid-run. The same stable order the authoring loop
+    // below walks level-by-level, so selection and execution agree by
+    // construction.
+    const stableOrder = stableTopologicalOrder(manifest.workstreams);
+    let selectedIds;
+    if (options.from === undefined) {
+        selectedIds = new Set(stableOrder.map((workstream) => workstream.id));
+    }
+    else {
+        const fromIndex = stableOrder.findIndex((workstream) => workstream.id === options.from);
+        if (fromIndex === -1) {
+            throw new Error(`Unknown workstream id "${options.from}" for --from. Valid ids: ` +
+                `${stableOrder.map((workstream) => workstream.id).join(", ")}.`);
+        }
+        selectedIds = new Set(stableOrder.slice(fromIndex).map((workstream) => workstream.id));
+    }
     const isRepository = await git.isRepository(root);
     if (!isRepository) {
         log("warning: not a git repository — commits and decision anchors are unavailable");
@@ -548,9 +665,31 @@ export async function authorProgram(options) {
             };
             return base;
         }
+        // Out-of-range keep (SC-05): a workstream before `--from` is kept and
+        // never drift-checked — the operator explicitly asked to start
+        // elsewhere, so this is neither authored nor parked. Decided ahead of
+        // both classification and the drift check.
+        if (!selectedIds.has(workstream.id)) {
+            return base;
+        }
         const existing = await readFinishedSpec(root, workstream);
-        const shouldAuthor = existing === undefined || (force && only !== undefined && only.includes(workstream.id));
+        const classification = classifySpec(existing, workstream);
+        const shouldAuthor = force || classification === "missing" || classification === "interrupted";
         if (!shouldAuthor) {
+            // Legacy specHash migration (SC-03): a legacy spec (no specStatus
+            // marker) whose specHash matches the manifest's current inputs is
+            // recognized as completed legacy Nightshift authoring and normalized
+            // — persisted immediately, since a kept-only invocation otherwise
+            // never saves.
+            if (classification === "legacy" &&
+                workstream.specHash !== undefined &&
+                specInputsHash(manifest, workstream) === workstream.specHash) {
+                workstream.specStatus = "complete";
+                await saveManifest(root, options.programId, manifest, { log });
+                log(`${workstream.id}: recognized as completed legacy authoring — ` +
+                    'normalized to specStatus "complete"');
+                return base;
+            }
             // Drift check: the spec exists and is about to be graded against, but
             // if the manifest entry changed since it was authored, the spec text
             // may promise something the manifest no longer does. The manifest is
@@ -574,7 +713,7 @@ export async function authorProgram(options) {
                         reason: `the manifest entry (name, scope, dependencies, or the program's ` +
                             `success criteria) changed after ${workstream.taskFile} was ` +
                             `authored, so the spec may be stale. Re-author it with ` +
-                            `\`nightshift author ${options.programId} --only ${workstream.id} --force\``,
+                            `\`nightshift author ${options.programId} --from ${workstream.id} --force\``,
                     };
                     return base;
                 }
@@ -593,6 +732,12 @@ export async function authorProgram(options) {
         const allDecisionsById = new Map();
         const first = await authorBrief(root, manifest, workstream, rosterById);
         base.demotedDependencies = first.demoted;
+        // 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 });
         let invocation;
         try {
             invocation = await invokeAgent(agentRunner, author, first.brief, root, permits, "authorAgent", {
@@ -608,7 +753,9 @@ export async function authorProgram(options) {
             // path rather than the build one. Nothing was written, so this parks
             // the workstream exactly like the "no spec was written" branch below,
             // instead of letting the rejection travel through authorProgram (which
-            // runProgram awaits unguarded) into a process crash.
+            // runProgram awaits unguarded) into a process crash. `specStatus`
+            // 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 });
             for (const id of downstreamCone(manifest.workstreams, [workstream.id])) {
@@ -621,8 +768,30 @@ export async function authorProgram(options) {
             };
             return base;
         }
-        base.summary = resolveSummary(invocation.output).text;
-        let parsed = extractDecisions(invocation.output);
+        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 });
+            for (const id of downstreamCone(manifest.workstreams, [workstream.id])) {
+                blockedCone.add(id);
+            }
+            base.summary = resolveSummary(invocation.output).text;
+            base.outcome = {
+                status: "failed",
+                reason: `the author agent reported a protocol failure (${describeProtocolFailure(invocation)}); ` +
+                    `not trusted as a finished spec.`,
+            };
+            return base;
+        }
+        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);
@@ -686,19 +855,49 @@ export async function authorProgram(options) {
                         `pass: ${error.message}. The pre-discovery spec was kept.`);
                 }
                 if (reauthorInvocation !== undefined) {
-                    invocation = reauthorInvocation;
-                    base.summary = resolveSummary(invocation.output).text;
-                    parsed = extractDecisions(invocation.output);
-                    base.decisionErrors.push(...parsed.errors);
-                    for (const decision of parsed.decisions) {
-                        allDecisionsById.set(decisionFingerprint(workstream.id, decision), decision);
+                    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 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 });
+                        for (const id of downstreamCone(manifest.workstreams, [workstream.id])) {
+                            blockedCone.add(id);
+                        }
+                        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)}); ` +
+                                `not trusted as a finished spec.`,
+                        };
+                        return base;
                     }
-                    await journalDecisions(workstream, parsed.decisions, baseCommit);
-                    base.decisionIds.push(...parsed.decisions.map((decision) => decisionFingerprint(workstream.id, decision)));
-                    const secondDeclaration = extractDependenciesDeclaration(invocation.output);
-                    if (secondDeclaration.ids.length > 0) {
-                        log(`${workstream.id}: additional dependency declaration after the ` +
-                            `re-author pass was not honored: ${secondDeclaration.ids.join(", ")}`);
+                    else {
+                        invocation = reauthorInvocation;
+                        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);
+                        }
+                        await journalDecisions(workstream, parsed.decisions, baseCommit);
+                        base.decisionIds.push(...parsed.decisions.map((decision) => decisionFingerprint(workstream.id, decision)));
+                        const secondDeclaration = extractDependenciesDeclaration(invocation.output);
+                        if (secondDeclaration.ids.length > 0) {
+                            log(`${workstream.id}: additional dependency declaration after the ` +
+                                `re-author pass was not honored: ${secondDeclaration.ids.join(", ")}`);
+                        }
                     }
                 }
             }
@@ -749,13 +948,25 @@ export async function authorProgram(options) {
         await 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.
+        // edit is drift; authoring's own merges are not. `specStatus` is
+        // deliberately NOT stamped `complete` in this same save (SC-01, SC-02):
+        // inside a repository, the durable signal is the git commit below, and a
+        // crash or throw from `commitPaths` between this save and the commit
+        // 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 });
         let commit;
         if (isRepository) {
             commit = await git.commitPaths(root, `nightshift(${options.programId}): author ${workstream.id} ${workstream.name}`, [workstream.taskFile, "docs/programs"]);
         }
+        // Outside a git repository there is no commit to wait for — the finished
+        // spec, its specHash, and this manifest save are already the durable
+        // state, so `complete` is stamped right here. Inside one, this still
+        // 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 });
         {
             const spawnErrors = await reviewWorkstreamDecisions(workstream.id, [...allDecisionsById.values()], baseCommit);
             if (spawnErrors.length > 0)