harness-dispatch 0.8.0 → 0.10.0

package/dist/jobs/context.js

@@ -15,9 +15,13 @@ import { assertValidJobId, jobsRoot, readJson } from "./store.js";
  * Every character here is a character the delegate's model must read before it
  * reaches the actual instruction, and agent CLIs are already carrying a system
  * prompt and file contents. 24k is roughly six pages: enough for several prior
- * results, small enough that it cannot crowd out the task itself. Oldest
- * entries are truncated first, since the most recent step is usually the one
- * being built on.
+ * results, small enough that it cannot crowd out the task itself.
+ *
+ * Entries are filled in the order the CALLER listed them, and it is the LAST
+ * ones that get truncated or omitted when the budget runs out. This comment
+ * claimed the opposite — "oldest entries are truncated first" — which was
+ * never true of the loop below and would be the wrong policy to infer: the
+ * caller controls the order, so put the job you most want carried first.
  */
 /** Newline, named so the templates below stay readable. */
 const NL = "\n";
@@ -36,12 +40,63 @@ function clip(text, limit) {
  * a delegate told "here is what came before" while a step is quietly missing
  * would reason from an incomplete picture and never know.
  */
+/**
+ * Where a prior job ran, as a header suffix — or "" when it cannot be read.
+ *
+ * `contextJobs` takes any jobId from the machine-wide jobs root and inlines
+ * that job's prompt and output verbatim, with no working-directory scoping.
+ * Reproduced: a job recorded against one project chained cleanly into a
+ * dispatch for another, its prompt and output carried across with nothing
+ * saying they came from somewhere else.
+ *
+ * Deliberately DISCLOSED rather than blocked. Chaining across projects is a
+ * legitimate thing to want — a review job informing work in a sibling
+ * checkout — and the jobId has to be passed explicitly by the orchestrator, so
+ * this is a missing guardrail, not an injection route. What was actually
+ * wrong is that neither the orchestrator nor the delegate could SEE it: an
+ * agent that passed the wrong id got another project's source in its prompt
+ * and no hint of it. Naming the directory is also plainly useful when the
+ * chaining is intended.
+ */
+async function ranIn(jobId) {
+    try {
+        const manifest = await readJson(path.join(jobsRoot(), jobId, "manifest.json"));
+        const dir = manifest.workingDir;
+        return typeof dir === "string" && dir !== "" ? `, ran in ${dir}` : "";
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * A prior job's PARTIAL output, when it has no result.json.
+ *
+ * Returns undefined when there is nothing on disk, so the caller can fall
+ * through to its "no result available" wording — the partial log is the
+ * salvage path, not a replacement for a real result.
+ */
+async function partialSection(jobId) {
+    const partialPath = path.join(jobsRoot(), jobId, "output", "stdout.partial.log");
+    const partial = await readFile(partialPath, "utf8").catch(() => undefined);
+    if (partial === undefined || partial.trim() === "")
+        return undefined;
+    const priorPrompt = await readFile(path.join(jobsRoot(), jobId, "prompt.md"), "utf8").catch(() => "(prompt unavailable)");
+    return [
+        `### ${jobId} (INCOMPLETE — no final result; this is how far it got${await ranIn(jobId)})`,
+        "",
+        "Task it was given:",
+        clip(priorPrompt.trim(), 1_000),
+        "",
+        "Partial output before it stopped:",
+        clip(partial.trim(), MAX_CONTEXT_CHARS_PER_JOB),
+    ].join(NL);
+}
 export async function buildContextPreamble(contextJobs) {
     if (contextJobs.length === 0)
         return "";
     const sections = [];
     let budget = MAX_CONTEXT_CHARS;
-    for (const jobId of contextJobs) {
+    for (const [index, jobId] of contextJobs.entries()) {
         let section;
         try {
             assertValidJobId(jobId);
@@ -50,7 +105,7 @@ export async function buildContextPreamble(contextJobs) {
             const priorPrompt = await readFile(path.join(jobDir, "prompt.md"), "utf8").catch(() => "(prompt unavailable)");
             const output = payload.result?.output ?? "";
             section = [
-                `### ${jobId} (${payload.result?.success === false ? "FAILED" : "completed"})`,
+                `### ${jobId} (${payload.result?.success === false ? "FAILED" : "completed"}${await ranIn(jobId)})`,
                 "",
                 "Task it was given:",
                 clip(priorPrompt.trim(), 1_000),
@@ -60,14 +115,47 @@ export async function buildContextPreamble(contextJobs) {
             ].join(NL);
         }
         catch {
-            section = `### ${jobId}${NL}${NL}(no result available — this job is unknown, still running, or was pruned)`;
+            // No result.json — but a job whose supervisor died leaves its progress
+            // in stdout.partial.log, and chaining on "what the last job got to" is
+            // exactly what a caller wants after an orphaned run. Reporting "no
+            // result available" while that file sits on disk discards the trail
+            // PRODUCT.md names as the thing that must never be lost.
+            section = await partialSection(jobId).catch(() => undefined) ??
+                `### ${jobId}${NL}${NL}(no result available — this job is unknown, still running, or was pruned)`;
         }
         if (section.length > budget)
             section = clip(section, Math.max(0, budget));
         budget -= section.length;
         sections.push(section);
-        if (budget <= 0)
+        if (budget <= 0) {
+            // Name what did not fit, rather than stopping silently.
+            //
+            // This loop dropped every remaining job with no header and no note —
+            // measured with five 8KB results: three appeared, jobs 4 and 5 were
+            // absent from the output entirely. That contradicts this module's own
+            // contract two functions up: "Unknown or unfinished jobs are reported
+            // inline rather than skipped silently: a delegate ... would reason from
+            // an incomplete picture and never know." A job dropped for want of
+            // budget is exactly that case, and it is worse than an unknown one,
+            // because the caller explicitly asked for it.
+            // Slice from the LOOP's position, not `indexOf`.
+            //
+            // `indexOf` returns the FIRST occurrence, so a repeated jobId made the
+            // notice describe the wrong point in the list: with [j1,j2,j1,j3,j4] it
+            // named four jobs omitted — including j1 and j2, whose output was
+            // rendered directly above it — and told the delegate to fetch them.
+            // Only j3 and j4 were actually dropped. A duplicate id is a plausible
+            // thing for an orchestrator to pass, and the notice was added in this
+            // same release, so this is that fix being wrong one case over.
+            const dropped = contextJobs.slice(index + 1);
+            if (dropped.length > 0) {
+                sections.push(`### ${dropped.length} earlier job(s) omitted` +
+                    `${NL}${NL}The ${MAX_CONTEXT_CHARS}-character context budget ran out before these: ` +
+                    `${dropped.join(", ")}. Their output is NOT below. Ask for it with job_status if ` +
+                    `you need it.`);
+            }
             break;
+        }
     }
     return [
         "## Context from earlier delegated work",

package/dist/jobs/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/jobs/context.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAGlE;;;;;;;;;GASG;AACH,2DAA2D;AAC3D,MAAM,EAAE,GAAG,IAAI,CAAC;AAEhB,MAAM,iBAAiB,GAAG,MAAM,CAAC;AAEjC,iFAAiF;AACjF,MAAM,yBAAyB,GAAG,KAAK,CAAC;AAExC,SAAS,IAAI,CAAC,IAAY,EAAE,KAAa;IACvC,IAAI,IAAI,CAAC,MAAM,IAAI,KAAK;QAAE,OAAO,IAAI,CAAC;IACtC,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,GAAG,EAAE,mBAAmB,IAAI,CAAC,MAAM,GAAG,KAAK,mBAAmB,CAAC;AAC/F,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,WAAqB;IAC9D,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACxC,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,IAAI,MAAM,GAAG,iBAAiB,CAAC;IAE/B,KAAK,MAAM,KAAK,IAAI,WAAW,EAAE,CAAC;QAChC,IAAI,OAAe,CAAC;QACpB,IAAI,CAAC;YACH,gBAAgB,CAAC,KAAK,CAAC,CAAC;YACxB,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,KAAK,CAAC,CAAC;YAC5C,MAAM,OAAO,GAAG,MAAM,QAAQ,CAC5B,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,EAAE,aAAa,CAAC,CAC3C,CAAC;YACF,MAAM,WAAW,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,CAAC,CAAC,KAAK,CAC9E,GAAG,EAAE,CAAC,sBAAsB,CAC7B,CAAC;YACF,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,MAAM,IAAI,EAAE,CAAC;YAC5C,OAAO,GAAG;gBACR,OAAO,KAAK,KAAK,OAAO,CAAC,MAAM,EAAE,OAAO,KAAK,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,WAAW,GAAG;gBAC9E,EAAE;gBACF,oBAAoB;gBACpB,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,EAAE,KAAK,CAAC;gBAC/B,EAAE;gBACF,mBAAmB;gBACnB,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,aAAa,EAAE,yBAAyB,CAAC;aAChE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACb,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,GAAG,OAAO,KAAK,GAAG,EAAE,GAAG,EAAE,2EAA2E,CAAC;QAC9G,CAAC;QACD,IAAI,OAAO,CAAC,MAAM,GAAG,MAAM;YAAE,OAAO,GAAG,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;QAC1E,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;QACzB,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACvB,IAAI,MAAM,IAAI,CAAC;YAAE,MAAM;IACzB,CAAC;IAED,OAAO;QACL,wCAAwC;QACxC,EAAE;QACF,4EAA4E;QAC5E,gCAAgC;QAChC,EAAE;QACF,QAAQ,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;QACtB,EAAE;QACF,KAAK;QACL,EAAE;KACH,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACb,CAAC"}
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/jobs/context.ts"],"names":[],"mappings":"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"}

package/dist/jobs/lifecycle.d.ts

@@ -0,0 +1,100 @@
+/**
+ * The lifecycle verbs: stop a run, resolve its workspace, run it again.
+ *
+ * These sit above start/read because a retry starts a new job and a cancel
+ * reads one, so the dependency runs one way — lifecycle imports start, never
+ * the reverse.
+ */
+import type { JobDeps, JobStatus } from "./types.js";
+/** What a cancel request actually did — the caller needs to tell these apart. */
+export interface CancelOutcome {
+    jobId: string;
+    /**
+     * `cancelled`  — it was queued and never started; stopped outright.
+     * `cancelling` — it is running; teardown requested and lands shortly.
+     * `already_finished` — it had already reached a terminal state; nothing done.
+     */
+    outcome: "cancelled" | "cancelling" | "already_finished";
+    status: JobStatus["status"];
+    message: string;
+}
+/**
+ * Ask a job to stop.
+ *
+ * Cancellation cannot be a signal here: jobs run inside POOLED supervisors,
+ * and the only pid recorded against a job belongs to a process that is also
+ * running other jobs, so signalling it would cancel work nobody asked to
+ * cancel. Instead this writes a marker the run itself honours — it drops out
+ * of its event stream, which triggers the dispatcher's teardown (killTree on
+ * the agent CLI and its children) and releases the workspace lock through the
+ * same path a normal finish uses.
+ *
+ * Two consequences worth stating plainly, because a caller who assumes
+ * otherwise will be surprised:
+ *
+ *   1. It is not instantaneous. A running job stops within about a second;
+ *      `cancelling` means requested, not done. Poll job_status to see it land.
+ *   2. Work already done is NOT undone. A cancelled agent may have already
+ *      edited files in the workspace, and those edits stay. Cancelling stops
+ *      further work; it is not a rollback.
+ *
+ * A cancelled run is deliberately not recorded as a failure: the route's
+ * circuit breaker and failure count never see it, because the caller changing
+ * their mind says nothing about whether the route works.
+ */
+export declare function cancelJob(jobId: string, reason?: string): Promise<CancelOutcome>;
+/**
+ * Inspect or resolve the isolated workspace a finished job left behind.
+ *
+ * Looks the job up the same way job_status does, then hands off to
+ * workspace-resolve.ts. Kept here so the caller only ever needs a jobId —
+ * where the workspace lives, and which policy produced it, are details
+ * recorded in the job's own result.
+ */
+export declare function resolveJobWorkspace(jobId: string, action: "diff" | "apply" | "discard", opts?: {
+    force?: boolean;
+}): Promise<unknown>;
+export interface RetryOutcome {
+    jobId: string;
+    retryOf: string;
+    service?: string;
+    reusedFrom: {
+        prompt: boolean;
+        files: number;
+        workingDir: string;
+    };
+    /**
+     * The original's model, when the retry's route does not declare it.
+     *
+     * `retryJob` has always SET this and the MCP tool description has always
+     * documented it, but the interface never listed it — the object is built
+     * with a conditional spread, which TypeScript does not excess-property
+     * check. So a typed caller could not see a field that ships, and the tests
+     * asserting it only compiled because the tests were not typechecked.
+     */
+    droppedModel?: string;
+    message: string;
+}
+/**
+ * Run a finished job's task again.
+ *
+ * The last verb missing from the job lifecycle: you could start work, watch
+ * it, stop it, and resolve its workspace — but if it failed, reproducing it
+ * meant reconstructing the prompt, the file list, the working directory and
+ * the hints by hand, from a job record that already holds all four. The
+ * machinery to execute a job bundle existed (executeJobDir) and simply was
+ * not reachable from outside.
+ *
+ * The prompt is taken from prompt.md, which is the FROZEN prompt — including
+ * any context preamble the original dispatch rendered in. A retry therefore
+ * reproduces what the delegate actually saw, not what the caller typed.
+ *
+ * `service` retargets the attempt, which is the common case rather than an
+ * afterthought: the reason a run failed is often the route, not the task
+ * ("codex hit its usage limit — try claude"). Omit it to reuse the original
+ * route, or to let the router pick again if the original had none.
+ */
+export declare function retryJob(jobId: string, deps: JobDeps, opts?: {
+    service?: string;
+}): Promise<RetryOutcome>;
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/jobs/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../src/jobs/lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAqBH,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACrD,iFAAiF;AACjF,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,OAAO,EAAE,WAAW,GAAG,YAAY,GAAG,kBAAkB,CAAC;IACzD,MAAM,EAAE,SAAS,CAAC,QAAQ,CAAC,CAAC;IAC5B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAqFtF;AAED;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,EACpC,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,GAC7B,OAAO,CAAC,OAAO,CAAC,CAsBlB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IACnE;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,QAAQ,CAC5B,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,OAAO,EACb,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GAC9B,OAAO,CAAC,YAAY,CAAC,CAoFvB"}

package/dist/jobs/lifecycle.js

@@ -0,0 +1,263 @@
+/**
+ * The lifecycle verbs: stop a run, resolve its workspace, run it again.
+ *
+ * These sit above start/read because a retry starts a new job and a cancel
+ * reads one, so the dependency runs one way — lifecycle imports start, never
+ * the reverse.
+ */
+import { getAsyncJob } from "./read.js";
+import { startAsyncJobTracked } from "./start.js";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { declaresModel } from "../router.js";
+import { applyWorkspace, discardWorkspace, isResolvable, workspaceDiff, } from "../workspace-resolve.js";
+import { requestCancel, jobsRoot, readJson, timestamp, updateStatus, } from "./store.js";
+/**
+ * Ask a job to stop.
+ *
+ * Cancellation cannot be a signal here: jobs run inside POOLED supervisors,
+ * and the only pid recorded against a job belongs to a process that is also
+ * running other jobs, so signalling it would cancel work nobody asked to
+ * cancel. Instead this writes a marker the run itself honours — it drops out
+ * of its event stream, which triggers the dispatcher's teardown (killTree on
+ * the agent CLI and its children) and releases the workspace lock through the
+ * same path a normal finish uses.
+ *
+ * Two consequences worth stating plainly, because a caller who assumes
+ * otherwise will be surprised:
+ *
+ *   1. It is not instantaneous. A running job stops within about a second;
+ *      `cancelling` means requested, not done. Poll job_status to see it land.
+ *   2. Work already done is NOT undone. A cancelled agent may have already
+ *      edited files in the workspace, and those edits stay. Cancelling stops
+ *      further work; it is not a rollback.
+ *
+ * A cancelled run is deliberately not recorded as a failure: the route's
+ * circuit breaker and failure count never see it, because the caller changing
+ * their mind says nothing about whether the route works.
+ */
+export async function cancelJob(jobId, reason) {
+    const job = await getAsyncJob(jobId); // throws the friendly "No such job" for a stranger
+    const current = job.status.status;
+    // There are TWO kinds of orphaned job and they need opposite answers.
+    //
+    //   WRITTEN — `drainSlotQueue` marks a slot-queued job orphaned on disk when
+    //     the server exits before it ever starts. That job is genuinely
+    //     terminal: its own error text says it is not resumed automatically and
+    //     to use retry_job. Cancelling it is a no-op that would leave a marker
+    //     nothing reads.
+    //   DERIVED — `withOrphanCheck` reports a job orphaned when its heartbeat
+    //     goes stale, while the FILE still says `queued` or `running`. That job
+    //     is not inert: once the dead owner's claim ages out, claimNextJob will
+    //     pick it up and run it. Answering "had already finished; nothing to
+    //     cancel" was wrong about work that could still start, and left the
+    //     caller no way to stop it.
+    //
+    // So the raw status decides, not the derived one. `getAsyncJob` has already
+    // applied the orphan check, which is why this re-reads the file.
+    const rawStatus = await readJson(path.join(jobsRoot(), jobId, "status.json")).catch(() => undefined);
+    const terminalOnDisk = rawStatus?.status === "orphaned";
+    if (current === "completed" ||
+        current === "failed" ||
+        current === "cancelled" ||
+        terminalOnDisk) {
+        return {
+            jobId,
+            outcome: "already_finished",
+            status: current,
+            message: `Job ${jobId} had already finished (${current}); nothing to cancel.`,
+        };
+    }
+    const jobDir = path.join(jobsRoot(), jobId);
+    await requestCancel(jobDir, reason);
+    // A job still waiting for a slot has no runner to notice the marker, so
+    // stop it here. claimNextJob also refuses to claim a marked job, which
+    // closes the window where a supervisor picks it up between these two steps.
+    // `orphaned` joins `queued` here rather than falling through to "the runner
+    // will notice the marker": an orphaned job has no live runner BY
+    // DEFINITION, so nothing would ever act on the marker and the job would sit
+    // at "cancelling" forever. The marker written above still matters — it is
+    // what stops a supervisor reclaiming it — but the status has to be settled
+    // here, by the only process still involved.
+    if (current === "queued" || current === "orphaned") {
+        await updateStatus(jobDir, {
+            ...job.status,
+            status: "cancelled",
+            updatedAt: timestamp(),
+            success: false,
+            error: reason !== undefined ? `Cancelled: ${reason}` : "Cancelled before it started.",
+        });
+        // Deliberately NOT draining the slot queue here. Freeing this job's slot
+        // makes room for a waiting one, but drainSlotQueue can SPAWN supervisor
+        // processes, and a cancel — the operation whose whole point is to stop
+        // work — must not start any. Every dispatch and every runner exit already
+        // drains, which is the same "resumes on the next event" contract the
+        // queue documents elsewhere.
+        return {
+            jobId,
+            outcome: "cancelled",
+            status: "cancelled",
+            message: current === "orphaned"
+                ? `Job ${jobId} was orphaned — the process running it is gone — and is now ` +
+                    `marked cancelled, so no supervisor can reclaim it. Any partial output it ` +
+                    `wrote is still available from job_status.`
+                : `Job ${jobId} was waiting for a slot and has been cancelled; it never started.`,
+        };
+    }
+    return {
+        jobId,
+        outcome: "cancelling",
+        status: current,
+        message: `Cancellation requested for ${jobId}. The run stops within a second or so — poll ` +
+            `job_status to confirm. Any files the agent already changed are NOT reverted.`,
+    };
+}
+/**
+ * Inspect or resolve the isolated workspace a finished job left behind.
+ *
+ * Looks the job up the same way job_status does, then hands off to
+ * workspace-resolve.ts. Kept here so the caller only ever needs a jobId —
+ * where the workspace lives, and which policy produced it, are details
+ * recorded in the job's own result.
+ */
+export async function resolveJobWorkspace(jobId, action, opts = {}) {
+    const job = await getAsyncJob(jobId);
+    const run = job.result?.result?.workspace;
+    if (!isResolvable(run)) {
+        // Read through a separate binding: the type guard narrows `run` to never
+        // on this branch, which would make the diagnostic unable to say WHICH
+        // policy the caller actually got.
+        const raw = job.result?.result?.workspace;
+        const policy = raw?.policy ?? "shared";
+        throw new Error(`Job ${jobId} has no isolated workspace to ${action} (workspace policy: ${policy}). ` +
+            `Only 'copy' and 'git_worktree' dispatches produce one — a 'shared' or ` +
+            `'shared_locked' run edited ${raw?.originalWorkingDir ?? "the working directory"} ` +
+            `directly, so there is nothing separate to inspect, apply or throw away.`);
+    }
+    const jobDir = path.join(jobsRoot(), jobId);
+    if (action === "diff")
+        return workspaceDiff(jobId, jobDir, run);
+    if (action === "apply")
+        return applyWorkspace(jobId, jobDir, run, opts);
+    // force reaches discard too: it now refuses to destroy work the project
+    // does not have, and the caller needs the same override apply offers.
+    return discardWorkspace(jobId, run, opts);
+}
+/**
+ * Run a finished job's task again.
+ *
+ * The last verb missing from the job lifecycle: you could start work, watch
+ * it, stop it, and resolve its workspace — but if it failed, reproducing it
+ * meant reconstructing the prompt, the file list, the working directory and
+ * the hints by hand, from a job record that already holds all four. The
+ * machinery to execute a job bundle existed (executeJobDir) and simply was
+ * not reachable from outside.
+ *
+ * The prompt is taken from prompt.md, which is the FROZEN prompt — including
+ * any context preamble the original dispatch rendered in. A retry therefore
+ * reproduces what the delegate actually saw, not what the caller typed.
+ *
+ * `service` retargets the attempt, which is the common case rather than an
+ * afterthought: the reason a run failed is often the route, not the task
+ * ("codex hit its usage limit — try claude"). Omit it to reuse the original
+ * route, or to let the router pick again if the original had none.
+ */
+export async function retryJob(jobId, deps, opts = {}) {
+    const prior = await getAsyncJob(jobId); // friendly "No such job" for a stranger
+    const state = prior.status.status;
+    if (state === "running" || state === "queued") {
+        throw new Error(`Job ${jobId} is still ${state}. Let it finish, or cancel it first with ` +
+            `cancel_job — retrying a live run would leave two attempts racing on the ` +
+            `same working directory.`);
+    }
+    // A DERIVED orphan produces exactly the outcome the message above forbids,
+    // and this guard could not see it.
+    //
+    // `getAsyncJob` reports orphaned when the heartbeat is stale, but the status
+    // FILE still says `queued`, and `claimNextJob` filters on the raw file — so
+    // a supervisor can still claim the original while the retry runs. The guard
+    // reads the derived status, which is neither `running` nor `queued`, so it
+    // let the retry through. `cancelJob` was given this reasoning when it learnt
+    // to tell the two kinds of orphan apart; retry was not, so the fix stopped
+    // one square short.
+    //
+    // Marking the original cancelled is what closes it: claimNextJob refuses a
+    // marked job, so the retry becomes the only attempt. A job orphaned while
+    // RUNNING has no live runner either, so the marker is equally correct there
+    // and simply has nothing left to interrupt.
+    if (state === "orphaned") {
+        const rawStatus = await readJson(path.join(jobsRoot(), jobId, "status.json")).catch(() => undefined);
+        if (rawStatus?.status === "queued" || rawStatus?.status === "running") {
+            await cancelJob(jobId, `superseded by a retry`);
+        }
+    }
+    const manifest = prior.manifest;
+    const prompt = await readFile(manifest.promptPath, "utf8");
+    if (opts.service !== undefined && !(opts.service in deps.holder.state.config.services)) {
+        throw new Error(`Unknown service: ${opts.service}. Valid route ids: ` +
+            `${Object.keys(deps.holder.state.config.services).join(", ")}.`);
+    }
+    const service = opts.service ?? manifest.service;
+    const { hints, droppedModel } = hintsForRetry(manifest.hints, prior.status.route ?? manifest.service, service, deps.holder.state.config.services);
+    const { status } = await startAsyncJobTracked(deps, {
+        prompt,
+        files: manifest.files.map((f) => f.originalPath),
+        workingDir: manifest.workingDir,
+        retryOf: jobId,
+        ...(hints !== undefined ? { hints } : {}),
+        ...(manifest.workspacePolicy !== undefined
+            ? { workspacePolicy: manifest.workspacePolicy }
+            : {}),
+        ...(service !== undefined ? { service } : {}),
+    });
+    return {
+        jobId: status.jobId,
+        retryOf: jobId,
+        ...(service !== undefined ? { service } : {}),
+        ...(droppedModel !== undefined ? { droppedModel } : {}),
+        reusedFrom: {
+            prompt: true,
+            files: manifest.files.length,
+            workingDir: manifest.workingDir,
+        },
+        message: `Started ${status.jobId} from ${jobId}'s prompt, files and working directory` +
+            `${opts.service !== undefined ? `, retargeted to ${opts.service}` : ""}. ` +
+            `${droppedModel !== undefined
+                ? `Left behind the original's model "${droppedModel}", which ${service} does ` +
+                    `not declare — a model name belongs to the route it was chosen for. Pass ` +
+                    `hints.model on a fresh dispatch if you want a specific model here. `
+                : ""}` +
+            `Check it with job_status; the original job is untouched.`,
+    };
+}
+/**
+ * Carry the original's hints into a retry — except a model that belonged to
+ * the route being left behind.
+ *
+ * Retrying somewhere else is the documented reason this tool exists ("the task
+ * was fine and the route was not"), and reusing the model verbatim defeated
+ * exactly that case: model names are route-scoped, so the retry failed for the
+ * same reason as the original. Observed end to end — a Cursor run that died on
+ * `Cannot use this model` was retried onto Claude and died on
+ * `unrecognized_model`, having never reached the task.
+ *
+ * Narrow on purpose. The model is kept when the retry stays on the original's
+ * route (that is a plain "try again"), and when the new route declares it
+ * anyway. Only a model the destination does not know is dropped, and the
+ * caller is told — a silently changed model is the failure this project keeps
+ * finding, so it is reported in the response rather than inferred from a
+ * different result.
+ */
+function hintsForRetry(hints, priorRoute, service, services) {
+    if (hints === undefined)
+        return { hints };
+    const model = hints.model;
+    if (model === undefined || service === undefined || service === priorRoute)
+        return { hints };
+    const target = services[service];
+    if (target === undefined || declaresModel(target, model))
+        return { hints };
+    const { model: _dropped, ...rest } = hints;
+    return { hints: rest, droppedModel: model };
+}
+//# sourceMappingURL=lifecycle.js.map

package/dist/jobs/lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.js","sourceRoot":"","sources":["../../src/jobs/lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,aAAa,GACd,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,aAAa,EACb,QAAQ,EACR,QAAQ,EACR,SAAS,EACT,YAAY,GACb,MAAM,YAAY,CAAC;AAepB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,KAAa,EAAE,MAAe;IAC5D,MAAM,GAAG,GAAG,MAAM,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,mDAAmD;IACzF,MAAM,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC;IAElC,sEAAsE;IACtE,EAAE;IACF,6EAA6E;IAC7E,oEAAoE;IACpE,4EAA4E;IAC5E,2EAA2E;IAC3E,qBAAqB;IACrB,0EAA0E;IAC1E,4EAA4E;IAC5E,4EAA4E;IAC5E,yEAAyE;IACzE,wEAAwE;IACxE,gCAAgC;IAChC,EAAE;IACF,4EAA4E;IAC5E,iEAAiE;IACjE,MAAM,SAAS,GAAG,MAAM,QAAQ,CAC9B,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,aAAa,CAAC,CAC5C,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IACzB,MAAM,cAAc,GAAG,SAAS,EAAE,MAAM,KAAK,UAAU,CAAC;IACxD,IACE,OAAO,KAAK,WAAW;QACvB,OAAO,KAAK,QAAQ;QACpB,OAAO,KAAK,WAAW;QACvB,cAAc,EACd,CAAC;QACD,OAAO;YACL,KAAK;YACL,OAAO,EAAE,kBAAkB;YAC3B,MAAM,EAAE,OAAO;YACf,OAAO,EAAE,OAAO,KAAK,0BAA0B,OAAO,uBAAuB;SAC9E,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,KAAK,CAAC,CAAC;IAC5C,MAAM,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEpC,wEAAwE;IACxE,uEAAuE;IACvE,4EAA4E;IAC5E,4EAA4E;IAC5E,iEAAiE;IACjE,4EAA4E;IAC5E,0EAA0E;IAC1E,2EAA2E;IAC3E,4CAA4C;IAC5C,IAAI,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,UAAU,EAAE,CAAC;QACnD,MAAM,YAAY,CAAC,MAAM,EAAE;YACzB,GAAG,GAAG,CAAC,MAAM;YACb,MAAM,EAAE,WAAW;YACnB,SAAS,EAAE,SAAS,EAAE;YACtB,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,cAAc,MAAM,EAAE,CAAC,CAAC,CAAC,8BAA8B;SACtF,CAAC,CAAC;QACH,yEAAyE;QACzE,wEAAwE;QACxE,uEAAuE;QACvE,0EAA0E;QAC1E,qEAAqE;QACrE,6BAA6B;QAC7B,OAAO;YACL,KAAK;YACL,OAAO,EAAE,WAAW;YACpB,MAAM,EAAE,WAAW;YACnB,OAAO,EACL,OAAO,KAAK,UAAU;gBACpB,CAAC,CAAC,OAAO,KAAK,8DAA8D;oBAC1E,2EAA2E;oBAC3E,2CAA2C;gBAC7C,CAAC,CAAC,OAAO,KAAK,mEAAmE;SACtF,CAAC;IACJ,CAAC;IAED,OAAO;QACL,KAAK;QACL,OAAO,EAAE,YAAY;QACrB,MAAM,EAAE,OAAO;QACf,OAAO,EACL,8BAA8B,KAAK,+CAA+C;YAClF,8EAA8E;KACjF,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,KAAa,EACb,MAAoC,EACpC,OAA4B,EAAE;IAE9B,MAAM,GAAG,GAAG,MAAM,WAAW,CAAC,KAAK,CAAC,CAAC;IACrC,MAAM,GAAG,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC;IAC1C,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC;QACvB,yEAAyE;QACzE,sEAAsE;QACtE,kCAAkC;QAClC,MAAM,GAAG,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC;QAC1C,MAAM,MAAM,GAAG,GAAG,EAAE,MAAM,IAAI,QAAQ,CAAC;QACvC,MAAM,IAAI,KAAK,CACb,OAAO,KAAK,iCAAiC,MAAM,uBAAuB,MAAM,KAAK;YACnF,wEAAwE;YACxE,8BAA8B,GAAG,EAAE,kBAAkB,IAAI,uBAAuB,GAAG;YACnF,yEAAyE,CAC5E,CAAC;IACJ,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,KAAK,CAAC,CAAC;IAC5C,IAAI,MAAM,KAAK,MAAM;QAAE,OAAO,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC;IAChE,IAAI,MAAM,KAAK,OAAO;QAAE,OAAO,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;IACxE,wEAAwE;IACxE,sEAAsE;IACtE,OAAO,gBAAgB,CAAC,KAAK,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;AAC5C,CAAC;AAoBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,KAAa,EACb,IAAa,EACb,OAA6B,EAAE;IAE/B,MAAM,KAAK,GAAG,MAAM,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,wCAAwC;IAChF,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC;IAClC,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9C,MAAM,IAAI,KAAK,CACb,OAAO,KAAK,aAAa,KAAK,2CAA2C;YACvE,0EAA0E;YAC1E,yBAAyB,CAC5B,CAAC;IACJ,CAAC;IACD,2EAA2E;IAC3E,mCAAmC;IACnC,EAAE;IACF,6EAA6E;IAC7E,4EAA4E;IAC5E,4EAA4E;IAC5E,2EAA2E;IAC3E,6EAA6E;IAC7E,2EAA2E;IAC3E,oBAAoB;IACpB,EAAE;IACF,2EAA2E;IAC3E,0EAA0E;IAC1E,4EAA4E;IAC5E,4CAA4C;IAC5C,IAAI,KAAK,KAAK,UAAU,EAAE,CAAC;QACzB,MAAM,SAAS,GAAG,MAAM,QAAQ,CAC9B,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,aAAa,CAAC,CAC5C,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QACzB,IAAI,SAAS,EAAE,MAAM,KAAK,QAAQ,IAAI,SAAS,EAAE,MAAM,KAAK,SAAS,EAAE,CAAC;YACtE,MAAM,SAAS,CAAC,KAAK,EAAE,uBAAuB,CAAC,CAAC;QAClD,CAAC;IACH,CAAC;IAED,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;IAChC,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IAC3D,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,IAAI,CAAC,CAAC,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;QACvF,MAAM,IAAI,KAAK,CACb,oBAAoB,IAAI,CAAC,OAAO,qBAAqB;YACnD,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAClE,CAAC;IACJ,CAAC;IACD,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,QAAQ,CAAC,OAAO,CAAC;IACjD,MAAM,EAAE,KAAK,EAAE,YAAY,EAAE,GAAG,aAAa,CAC3C,QAAQ,CAAC,KAAK,EACd,KAAK,CAAC,MAAM,CAAC,KAAK,IAAI,QAAQ,CAAC,OAAO,EACtC,OAAO,EACP,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAClC,CAAC;IAEF,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,oBAAoB,CAAC,IAAI,EAAE;QAClD,MAAM;QACN,KAAK,EAAE,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC;QAChD,UAAU,EAAE,QAAQ,CAAC,UAAU;QAC/B,OAAO,EAAE,KAAK;QACd,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACzC,GAAG,CAAC,QAAQ,CAAC,eAAe,KAAK,SAAS;YACxC,CAAC,CAAC,EAAE,eAAe,EAAE,QAAQ,CAAC,eAAe,EAAE;YAC/C,CAAC,CAAC,EAAE,CAAC;QACP,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC9C,CAAC,CAAC;IAEH,OAAO;QACL,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,OAAO,EAAE,KAAK;QACd,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7C,GAAG,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACvD,UAAU,EAAE;YACV,MAAM,EAAE,IAAI;YACZ,KAAK,EAAE,QAAQ,CAAC,KAAK,CAAC,MAAM;YAC5B,UAAU,EAAE,QAAQ,CAAC,UAAU;SAChC;QACD,OAAO,EACL,WAAW,MAAM,CAAC,KAAK,SAAS,KAAK,wCAAwC;YAC7E,GAAG,IAAI,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,mBAAmB,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI;YAC1E,GACE,YAAY,KAAK,SAAS;gBACxB,CAAC,CAAC,qCAAqC,YAAY,YAAY,OAAO,QAAQ;oBAC5E,0EAA0E;oBAC1E,qEAAqE;gBACvE,CAAC,CAAC,EACN,EAAE;YACF,0DAA0D;KAC7D,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,SAAS,aAAa,CACpB,KAA6B,EAC7B,UAA8B,EAC9B,OAA2B,EAC3B,QAAuC;IAEvC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC1C,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;IAC1B,IAAI,KAAK,KAAK,SAAS,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,UAAU;QAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC7F,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;IACjC,IAAI,MAAM,KAAK,SAAS,IAAI,aAAa,CAAC,MAAM,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC3E,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,GAAG,KAAK,CAAC;IAC3C,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC;AAC9C,CAAC"}

package/dist/jobs/read.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Reading a job back: one with its partial output, or the recent list.
+ *
+ * Separate from start.ts because the supervisor reads jobs while deciding
+ * what to run, and start.ts needs the supervisor — keeping the reads beside
+ * the start verbs closed that loop.
+ */
+import type { JobManifest, JobResultPayload, JobStatus } from "./types.js";
+export declare function getAsyncJob(jobId: string): Promise<{
+    manifest: JobManifest;
+    status: JobStatus;
+    result?: JobResultPayload;
+    /** Tail of live stdout/stderr while the job is still running. */
+    partialOutput?: string;
+}>;
+export declare function listAsyncJobs(): Promise<JobStatus[]>;
+//# sourceMappingURL=read.d.ts.map

package/dist/jobs/read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../../src/jobs/read.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAaH,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAG3E,wBAAsB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IACxD,QAAQ,EAAE,WAAW,CAAC;IACtB,MAAM,EAAE,SAAS,CAAC;IAClB,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,iEAAiE;IACjE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC,CAsED;AAED,wBAAsB,aAAa,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC,CAgB1D"}