@wildorder/nightshift 0.17.0 → 0.18.0

package/dist/agent-session.js

@@ -0,0 +1,114 @@
+import { resolveSummary } from "./agent-summary.js";
+/**
+ * Opens a resumed revision brief (§3.7): a resumed agent must be told it is
+ * resuming, or it re-orients as if the brief were its first contact. Shared
+ * verbatim by the spec-critique writer and the test-critique fix brief so
+ * the two revision briefs never drift in wording.
+ */
+export const SESSION_CONTINUATION_PREAMBLE = [
+    "## You are continuing your own session",
+    "",
+    "This is the same conversation in which you wrote this work. The findings",
+    "below came from an independent reviewer who read it afterwards. You do not",
+    "need to re-read what you already know; go straight to the findings.",
+    "",
+].join("\n");
+/** Human sentences for each decline reason, one exported and exhaustively
+ *  switched function so the wording lives in one place and fails to compile
+ *  when a reason is added without a sentence. Never prints the session id
+ *  itself — it is a machine-local handle with no meaning to the reader. */
+export function describeSessionDecline(reason, detail) {
+    switch (reason) {
+        case "no-session-captured":
+            return "no session id was captured from the agent that wrote it";
+        case "provider-mismatch":
+            return detail?.producerCommand !== undefined && detail?.seatCommand !== undefined
+                ? `it ran \`${detail.producerCommand}\` and this seat runs \`${detail.seatCommand}\``
+                : "it ran under a different provider than this seat runs";
+        case "invocation-mismatch":
+            return "it ran under different flags than this seat uses";
+        case "cwd-mismatch":
+            return "it ran in a different directory";
+        case "operator-pinned-session-flag":
+            return "the configured agent manages its own sessions";
+        case "unsupported-resume-argv":
+            return detail?.token !== undefined
+                ? `its arguments cannot be translated to a resume (\`${detail.token}\`)`
+                : "its arguments cannot be translated to a resume";
+        case "resume-spawn-failed":
+            return "the resumed agent failed to start";
+    }
+}
+const NO_SESSION_CAPTURED = {
+    mode: "fresh",
+    declineReason: "no-session-captured",
+};
+function safeObserve(observeContinuity, continuity) {
+    try {
+        observeContinuity?.(continuity);
+    }
+    catch {
+        // An analytics defect must never flip a seat's outcome (SC-13).
+    }
+}
+/**
+ * The one fallback helper the three resuming seats share (§3.6): a resumed
+ * spawn that failed *before touching the artifact* falls back to exactly one
+ * fresh spawn; a resumed spawn that failed *after* changing the tree is
+ * never compounded with a second attempt — the existing verify-and-reset
+ * machinery handles it exactly as it would a fresh spawn's failure.
+ */
+export async function spawnWithSessionContinuity(options) {
+    const { resume, spawn, untouched, log, observeContinuity } = options;
+    if (resume === undefined) {
+        const result = await spawn(undefined, false);
+        const continuity = result.continuity ?? NO_SESSION_CAPTURED;
+        safeObserve(observeContinuity, continuity);
+        return { result, continuity };
+    }
+    let first;
+    try {
+        first = await spawn(resume, true);
+    }
+    catch (error) {
+        const isUntouched = await safeUntouched(untouched);
+        if (!isUntouched) {
+            safeObserve(observeContinuity, { mode: "resumed" });
+            throw error;
+        }
+        log(`session continuity: the resumed spawn failed to start (${error.message}); ` +
+            "retrying fresh since nothing was touched");
+        const fallback = await spawn(undefined, false);
+        const continuity = { mode: "fresh", declineReason: "resume-spawn-failed" };
+        safeObserve(observeContinuity, continuity);
+        return { result: fallback, continuity };
+    }
+    const continuityFromFirst = first.continuity ?? NO_SESSION_CAPTURED;
+    if (continuityFromFirst.mode !== "resumed") {
+        // The resume was declined before the spawn even happened (invokeAgent's
+        // own checks) — nothing to fall back from, the spawn already ran fresh.
+        safeObserve(observeContinuity, continuityFromFirst);
+        return { result: first, continuity: continuityFromFirst };
+    }
+    if (first.exitCode !== 0 && !resolveSummary(first.output).available) {
+        const isUntouched = await safeUntouched(untouched);
+        if (isUntouched) {
+            log("session continuity: the resumed spawn exited non-zero with no reply; retrying fresh");
+            const fallback = await spawn(undefined, false);
+            const continuity = { mode: "fresh", declineReason: "resume-spawn-failed" };
+            safeObserve(observeContinuity, continuity);
+            return { result: fallback, continuity };
+        }
+    }
+    safeObserve(observeContinuity, { mode: "resumed" });
+    return { result: first, continuity: { mode: "resumed" } };
+}
+async function safeUntouched(untouched) {
+    try {
+        return await untouched();
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=agent-session.js.map

package/dist/agent-session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-session.js","sourceRoot":"","sources":["../src/agent-session.ts"],"names":[],"mappings":"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"}

package/dist/atomic-write.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Write-temp-then-rename, shared by every runner-owned durable write
+ * (manifest, analytics artifact). Same-directory rename is atomic on POSIX
+ * and, via libuv's `MOVEFILE_REPLACE_EXISTING`, replaces atomically on
+ * Windows too — a crash mid-write can never leave a half-written artifact; a
+ * reader sees either the old file or the new one.
+ *
+ * `tempDir`, when given, is where the temp file is written before the
+ * rename — out of any staged/committed prefix (see the `build-logs-temp`
+ * decision), so a concurrent commit can never sweep up a stray `.tmp-*`
+ * file. If the rename across `tempDir` → `path` fails with `EXDEV` (an
+ * exotic layout where they live on different filesystems), this falls back
+ * once to a same-directory temp file rather than failing the write.
+ */
+export declare function atomicWriteFile(path: string, contents: string, options?: {
+    tempDir?: string;
+}): Promise<void>;
+//# sourceMappingURL=atomic-write.d.ts.map

package/dist/atomic-write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic-write.d.ts","sourceRoot":"","sources":["../src/atomic-write.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7B,OAAO,CAAC,IAAI,CAAC,CAgCf"}

package/dist/atomic-write.js

@@ -0,0 +1,74 @@
+import { randomBytes } from "node:crypto";
+import { mkdir, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+/**
+ * Write-temp-then-rename, shared by every runner-owned durable write
+ * (manifest, analytics artifact). Same-directory rename is atomic on POSIX
+ * and, via libuv's `MOVEFILE_REPLACE_EXISTING`, replaces atomically on
+ * Windows too — a crash mid-write can never leave a half-written artifact; a
+ * reader sees either the old file or the new one.
+ *
+ * `tempDir`, when given, is where the temp file is written before the
+ * rename — out of any staged/committed prefix (see the `build-logs-temp`
+ * decision), so a concurrent commit can never sweep up a stray `.tmp-*`
+ * file. If the rename across `tempDir` → `path` fails with `EXDEV` (an
+ * exotic layout where they live on different filesystems), this falls back
+ * once to a same-directory temp file rather than failing the write.
+ */
+export async function atomicWriteFile(path, contents, options) {
+    const targetDir = dirname(path);
+    await mkdir(targetDir, { recursive: true });
+    const primaryDir = options?.tempDir ?? targetDir;
+    if (primaryDir !== targetDir)
+        await mkdir(primaryDir, { recursive: true });
+    const tmp = join(primaryDir, `.${randomId()}.tmp-${randomId()}`);
+    await writeFile(tmp, contents, "utf8");
+    try {
+        await renameWithRetry(tmp, path);
+    }
+    catch (error) {
+        if (primaryDir !== targetDir &&
+            error.code === "EXDEV") {
+            await rm(tmp, { force: true }).catch(() => undefined);
+            const fallbackTmp = join(targetDir, `.${randomId()}.tmp-${randomId()}`);
+            await writeFile(fallbackTmp, contents, "utf8");
+            try {
+                await renameWithRetry(fallbackTmp, path);
+            }
+            catch (fallbackError) {
+                await rm(fallbackTmp, { force: true }).catch(() => undefined);
+                throw fallbackError;
+            }
+            return;
+        }
+        // A failed rename must never leave an orphaned temp file behind for a
+        // later staged commit to sweep up as an untracked artifact.
+        await rm(tmp, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}
+/**
+ * Windows-only wrinkle: replacing a file a reader currently holds open (an
+ * agent reading the manifest) fails with `EPERM`/`EBUSY` for the moment the
+ * handle is held; POSIX never does. A few short retries cover that window
+ * without masking a genuine permission problem.
+ */
+async function renameWithRetry(from, to) {
+    const maxAttempts = 6;
+    for (let attempt = 1;; attempt += 1) {
+        try {
+            await rename(from, to);
+            return;
+        }
+        catch (error) {
+            const code = error.code;
+            if ((code !== "EPERM" && code !== "EBUSY") || attempt >= maxAttempts)
+                throw error;
+            await new Promise((resolveDelay) => setTimeout(resolveDelay, 20 * attempt));
+        }
+    }
+}
+function randomId() {
+    return randomBytes(8).toString("hex");
+}
+//# sourceMappingURL=atomic-write.js.map

package/dist/atomic-write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic-write.js","sourceRoot":"","sources":["../src/atomic-write.ts"],"names":[],"mappings":"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"}

package/dist/author.d.ts

@@ -1,9 +1,11 @@
 import { type AgentRunner } from "./agent-runner.js";
 import type { NightshiftConfig } from "./config.js";
 import { type PermitsContext } from "./permits.js";
+import { type ProgramManifest, type Workstream } from "./manifest.js";
 import { type ReviewPassOutcome } from "./review-pass.js";
 import { type GitOps } from "./run-program.js";
-import { type RunRecorder } from "./run-analytics.js";
+import { type SpanHandle, type SpanScope } from "./run-analytics.js";
+import { type Mutex } from "./concurrency.js";
 export interface AuthorOptions {
     cwd: string;
     programId: string;
@@ -19,6 +21,23 @@ export interface AuthorOptions {
      *  stage never builds its own. */
     permits?: PermitsContext;
     git?: GitOps;
+    /**
+     * The run's manifest object. When supplied, authoring mutates and persists
+     * *this* object rather than loading its own — so there is exactly one
+     * in-memory manifest per run and the build scheduler sees discovered
+     * dependency edges and `specStatus` transitions the instant an author makes
+     * them (WS-05 §3.4). Omitted by the standalone `author` CLI, which loads
+     * its own.
+     */
+    manifest?: ProgramManifest;
+    /**
+     * The run-scoped mutex guarding every operation that takes
+     * `.git/index.lock` in the root checkout (WS-05 §3.7). Supplied by
+     * `runProgram` so authoring's spec commits and WS-02's integration commits
+     * share one serializer. Omitted, authoring creates its own — correct for
+     * the standalone CLI, where nothing else commits.
+     */
+    rootIndexMutex?: Mutex;
     log?: (line: string) => void;
     now?: () => Date;
     /**
@@ -40,7 +59,34 @@ export interface AuthorOptions {
      * 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;
+    recorder?: SpanScope;
+    /**
+     * Maximum authoring flows in flight at once. `undefined` or anything below
+     * 1 means unbounded — the dependency graph is the only serializer. `1`
+     * reproduces the pre-WS-03 serial behaviour exactly, including dispatch
+     * order and the absence of any deferred re-author (§3.3 of the spec).
+     * Filled from `run --max-parallel` by WS-04; this module never reads a CLI
+     * flag.
+     */
+    maxParallel?: number;
+    /**
+     * The run's `run` span (WS-01). When present, each authoring flow opens
+     * its spans through `runSpan.scope({ workstream })`, so a span is parented
+     * because the code said so and is stamped with its workstream even when
+     * the call site did not name one — never by whichever span happened to be
+     * open at that microsecond. Absent (the standalone `author` CLI, tests),
+     * spans go through `recorder` exactly as they do today.
+     */
+    runSpan?: SpanHandle;
+    /**
+     * Injectable monotonic clock; defaults to `performance.now()`. Measures
+     * the §3.3 dependency wait for `workstream-waiting`'s `waitedMs`.
+     * Deliberately separate from `now`, which is wall-clock and therefore not
+     * monotonic. `runProgram` passes the same `monotonic` it built its
+     * recorder's `RunClock` from, so a run's authoring waits and its span
+     * offsets are measured on one timebase; tests inject a counter.
+     */
+    monotonic?: () => number;
 }
 export type AuthorOutcome = {
     status: "authored";
@@ -90,10 +136,70 @@ export interface AuthorStageResult {
     borrowedImplementer: boolean;
 }
 /**
- * The authoring stage: writes every missing workstream spec, one clean agent
- * at a time, in dependency-level order. Shaped like `runProgram` — plain
- * inputs, injected boundaries, a structured result the CLI and `run` both
- * consume.
+ * Everything `authorProgram` does *around* its per-workstream loop: agent
+ * resolution and its three stage-level log lines, the cycle check, `--from`
+ * validation into the selected set, the repository check, and the run-scoped
+ * state WS-03 shares across flows (the settled/dispatched sets and their
+ * deferreds, the graph mutex, the flow scopes). See WS-05 §3.3.
+ */
+export interface AuthoringPipeline {
+    /** True when no `authorAgent` was configured and the implementer stood in. */
+    readonly borrowedImplementer: boolean;
+    /**
+     * The manifest object this pipeline authors against — `options.manifest`
+     * when supplied, otherwise the one this call loaded itself. Exposed so a
+     * caller driving its own scheduler (this module's own `authorProgram`, or
+     * `runProgram`'s unified one) reads `dependencies` off the exact same live
+     * objects `authorWorkstream` mutates.
+     */
+    readonly manifest: ProgramManifest;
+    /**
+     * One workstream's authoring flow: WS-03's `handle`, wrapped in WS-03's
+     * dispatch/settle bookkeeping so the deferred re-author (WS-03 §3.3) keeps
+     * working. Call exactly once per workstream in the roster — including
+     * out-of-selection keeps and cone-parked ones, whose `handle`
+     * short-circuits in microseconds. Never throws for a workstream-level
+     * failure; it returns an `AuthorResult`. A throw is an unexpected error
+     * and drains the run, exactly as it does today.
+     */
+    authorWorkstream(workstream: Workstream): Promise<AuthorResult>;
+    /**
+     * Records a workstream's authoring flow as settled without running it —
+     * the environmental-halt branch (WS-05 §3.6): `handle` never runs, so
+     * nothing is spawned and `specStatus` is left exactly as it stood before
+     * this run (no manifest write on this branch, mirroring WS-04's own halt
+     * branch for a build item). Marks the workstream dispatched and settled
+     * exactly like `authorWorkstream`, resolving its settle deferred, so a
+     * sibling's deferred re-author waiting on it is released with the same
+     * not-final answer a parked dependency already gives `specFinal`.
+     * Deliberately synchronous and side-effect-free beyond that bookkeeping —
+     * the caller decides `reason`, since only it knows why the run halted.
+     */
+    haltAuthorWorkstream(workstream: Workstream, reason: string): AuthorResult;
+    /**
+     * The stage result, assembled from every recorded `AuthorResult` in
+     * `stableTopologicalOrder` of the final roster (WS-03 §3.8). Call once,
+     * after every workstream has been through `authorWorkstream` or
+     * `haltAuthorWorkstream`.
+     */
+    finish(): AuthorStageResult;
+}
+/**
+ * Throws for exactly the reasons `authorProgram` throws today — no author
+ * agent configured, a cyclic manifest, an unknown `--from` id — and throws
+ * them before any agent spawns, so a caller that never reaches the scheduler
+ * fails identically to today.
+ */
+export declare function prepareAuthoring(options: AuthorOptions): Promise<AuthoringPipeline>;
+/**
+ * The authoring stage, standalone: writes every missing workstream spec, one
+ * clean agent at a time, in dependency order, at `--max-parallel`'s cap —
+ * `runReadySet` over `manifest.workstreams` directly, the same scheduler
+ * `runProgram`'s unified pipeline (WS-05 §3.1) drives, just with only one
+ * kind of item. `--max-parallel 1` reproduces the pre-WS-03 serial behaviour
+ * exactly, including dispatch order and the absence of any deferred
+ * re-author. This module no longer contains a hand-written scheduler of its
+ * own (WS-04 §8, WS-05 §3.3): one implementation, two callers.
  */
 export declare function authorProgram(options: AuthorOptions): Promise<AuthorStageResult>;
 //# sourceMappingURL=author.d.ts.map

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;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"}
+{"version":3,"file":"author.d.ts","sourceRoot":"","sources":["../src/author.ts"],"names":[],"mappings":"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"}