harness-dispatch 0.4.0

package/dist/job-runner.js

@@ -0,0 +1,42 @@
+/**
+ * Detached job runner — the process a `dispatch` background run actually
+ * lives in, so the run survives the MCP server that started it.
+ *
+ * Field incident that motivated this (2026-07-24): background runs used to
+ * execute inside the server process; a session restart killed the server
+ * and every in-flight run died with it, leaving status files frozen at
+ * "running". Now the server only *starts* this process (detached, unref'd)
+ * and watches the job directory; the run itself owes the server nothing.
+ * Orphan detection (jobs.ts heartbeat) remains the safety net for the rare
+ * case this runner itself dies.
+ *
+ * Usage: node dist/job-runner.js <jobDir>
+ * Config: HARNESS_DISPATCH_CONFIG (set by the spawning server so the run
+ * bootstraps against the same config file), else ./config.yaml if present,
+ * else auto-detect — mirroring bin.ts's resolution.
+ */
+import { existsSync } from "node:fs";
+import { bootstrapRuntime, RuntimeHolder } from "./mcp/config-hot-reload.js";
+import { executeJobDir } from "./jobs.js";
+async function main() {
+    const jobDir = process.argv[2];
+    if (!jobDir) {
+        console.error("usage: job-runner <jobDir>");
+        process.exit(2);
+    }
+    const configPath = process.env.HARNESS_DISPATCH_CONFIG ??
+        (existsSync("config.yaml") ? "config.yaml" : undefined);
+    const state = await bootstrapRuntime(configPath !== undefined ? { configPath } : {});
+    await executeJobDir({ holder: new RuntimeHolder(state) }, jobDir);
+    // executeJobDir never throws (runJob writes failures to the job dir), but
+    // dispatcher/OTEL handles can keep the loop alive — exit deliberately.
+    process.exit(0);
+}
+main().catch((err) => {
+    // Last-resort: bootstrap itself failed (bad config, missing deps). The
+    // job dir still holds only the frozen "queued/running" status, which the
+    // heartbeat-staleness check will surface as orphaned.
+    console.error(`harness-dispatch job-runner: fatal: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+});
+//# sourceMappingURL=job-runner.js.map

package/dist/job-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-runner.js","sourceRoot":"","sources":["../src/job-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAErC,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC7E,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE1C,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC/B,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,CAAC,KAAK,CAAC,4BAA4B,CAAC,CAAC;QAC5C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IACD,MAAM,UAAU,GACd,OAAO,CAAC,GAAG,CAAC,uBAAuB;QACnC,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAC1D,MAAM,KAAK,GAAG,MAAM,gBAAgB,CAClC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAC/C,CAAC;IACF,MAAM,aAAa,CAAC,EAAE,MAAM,EAAE,IAAI,aAAa,CAAC,KAAK,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;IAClE,0EAA0E;IAC1E,uEAAuE;IACvE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,uEAAuE;IACvE,yEAAyE;IACzE,sDAAsD;IACtD,OAAO,CAAC,KAAK,CACX,uCAAuC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAC1F,CAAC;IACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/jobs.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Async job bundle support.
+ *
+ * `dispatch` returns quickly after creating a reproducible bundle on disk,
+ * then the run executes in a DETACHED job-runner process (job-runner.ts) —
+ * not inside the MCP server — so a server restart, session reconnect, or
+ * client timeout never kills an in-flight run. The server (and any later
+ * server instance) reads progress and results back from the job directory.
+ * Set HARNESS_DISPATCH_INPROC_JOBS=1 to run jobs in-process instead (used
+ * by the unit-test suite, which injects fake dispatchers a separate
+ * process could not see).
+ */
+import type { RuntimeHolder } from "./mcp/config-hot-reload.js";
+import type { DispatchResult, DispatcherEvent, RouteHints, RoutingDecision, WorkspacePolicy } from "./types.js";
+export interface JobDeps {
+    holder: RuntimeHolder;
+}
+export interface StartJobInput {
+    prompt: string;
+    files?: string[];
+    workingDir?: string;
+    hints?: RouteHints;
+    workspacePolicy?: WorkspacePolicy;
+    service?: string;
+    /**
+     * Live dispatcher-event tap, used by the `dispatch` tool to forward MCP
+     * progress notifications during its inline grace window. Never serialized
+     * (the manifest lists its fields explicitly), never awaited, and a throw
+     * here must not fail the job.
+     */
+    onEvent?: (event: DispatcherEvent) => void;
+}
+export interface JobStatus {
+    jobId: string;
+    /**
+     * "orphaned" is never written to disk — it's computed on read: a job
+     * whose status file says "running" but whose heartbeat (updatedAt) has
+     * gone stale means the server process that owned the background run
+     * exited (session restart, crash) and the run died with it. Reporting it
+     * as still "running" forever is a lie that makes callers poll a corpse.
+     */
+    status: "queued" | "running" | "completed" | "failed" | "orphaned";
+    createdAt: string;
+    updatedAt: string;
+    jobDir: string;
+    service?: string;
+    route?: string;
+    success?: boolean;
+    /** Bounded copy — full text in output/stderr.log. */
+    error?: string;
+    durationMs?: number;
+    /** Suggested seconds to wait before polling action=get again. */
+    nextPollSeconds?: number;
+    /** Agent-facing guidance on how to collect the result. */
+    instructions?: string;
+    /** Set when workingDir was omitted and defaulted to the router's own cwd. */
+    warning?: string;
+}
+export interface JobManifest {
+    jobId: string;
+    createdAt: string;
+    workingDir: string;
+    promptPath: string;
+    files: Array<{
+        originalPath: string;
+        snapshotPath?: string;
+        sizeBytes?: number;
+        error?: string;
+    }>;
+    hints?: RouteHints;
+    workspacePolicy?: WorkspacePolicy;
+    service?: string;
+    /** Set when workingDir was omitted and defaulted to the router's own cwd. */
+    warning?: string;
+}
+export interface JobResultPayload {
+    jobId: string;
+    result: DispatchResult;
+    decision: RoutingDecision | null;
+}
+/**
+ * Config-driven retention (`retention: { jobs_days: N }` in config.yaml) —
+ * set at runtime bootstrap and on every hot reload. Precedence:
+ * HARNESS_DISPATCH_JOB_MAX_AGE_MS env > config > 7-day default.
+ */
+export declare function setJobRetentionDays(days: number | undefined): void;
+export interface StartedJob {
+    status: JobStatus;
+    /**
+     * Resolves once the run has reached a terminal state on disk (result.json
+     * or a failed/orphaned status). Never rejects. In detached mode this is a
+     * disk watcher on the job directory — the run itself lives in a separate
+     * job-runner process; in in-process mode (HARNESS_DISPATCH_INPROC_JOBS=1,
+     * used by unit tests with injected fakes) it is the runJob promise itself.
+     */
+    completion: Promise<void>;
+}
+/**
+ * Rebuild a job's input from its on-disk bundle and execute it. This is the
+ * detached runner's whole job; the manifest deliberately carries everything
+ * a run needs (prompt path, resolved workingDir, hints, service) precisely
+ * so execution can happen in a process that wasn't there when the job was
+ * created.
+ */
+export declare function executeJobDir(deps: JobDeps, jobDir: string): Promise<void>;
+export declare function startAsyncJob(deps: JobDeps, input: StartJobInput): Promise<JobStatus>;
+export declare function startAsyncJobTracked(deps: JobDeps, input: StartJobInput): Promise<StartedJob>;
+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=jobs.d.ts.map

package/dist/jobs.d.ts.map

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