harnery 0.37.0 → 0.38.0

package/dist/commander.d.ts

@@ -96,6 +96,15 @@ export interface HarneryProgramContext {
      * zones behind a WAF). harn standalone skips the callback entirely.
      */
     extraHeaders?: (url: string) => Record<string, string>;
+    /**
+     * Optional callback that returns extra cookies to persist into the shared
+     * jar before `fetch` / `browse` attach it. Runs only when a jar is in
+     * play (`--no-cookies` skips it). Use this for host-minted session
+     * cookies; `extraHeaders` cannot merge a `Cookie` header once the jar
+     * has already set one. Must stay synchronous, same as `extraHeaders`.
+     * harn standalone skips the callback entirely.
+     */
+    extraCookies?: import("./lib/cookies/index.js").ExtraCookies;
     /**
      * Host-injected vision-model call for `browse --check-critique`. harnery
      * ships no model client or API key; a consumer wires this to its own

package/dist/commander.d.ts.map

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

package/dist/commander.js

@@ -105,9 +105,14 @@ function harneryCommandBundles({ emit, context, binName, }) {
         lazy("files", "Mint browser links for files served by the local dashboard", async (program) => (await import("./commands/files.js")).registerFilesCommand(program, emit, context)),
         lazy("read [html-file]", `Extract clean readable markdown from HTML. Reads from file or stdin (use '-'). Pair with \`${binName} fetch\` or \`${binName} browse\` for scrape-to-markdown.`, async (program) => (await import("./commands/read.js")).registerReadCommand(program, emit, binName), { hasOptions: true }),
         lazy("browse <url>", "Headless Chromium with persistent profile + cookie jar. Default writes a trio of files (last.png, last.html, last.json) for the LLM iteration loop; --snapshot/--html/--json switch to stdout-print mode.", async (program) => (await import("./commands/browse.js")).registerBrowseCommand(program, emit, context, binName), { hasOptions: true }),
-        lazy("qa-run <target>", `Run the whole page-QA matrix in one command (planner, deterministic gates per context, interactions, critique, snapshot) via child \`${binName} browse\` processes; writes page-qa-result.json with a fail-closed verdict.`, async (program) => (await import("./commands/qa-run.js")).registerQaRunCommand(program, emit), { hasOptions: true }),
+        lazy("qa-run <target>", `Run the whole page-QA matrix in one command (planner, deterministic gates per context, interactions, critique, snapshot) via child \`${binName} browse\` processes; writes page-qa-result.json with a fail-closed verdict.`, async (program) => (await import("./commands/qa-run.js")).registerQaRunCommand(program, emit, context), { hasOptions: true }),
+        lazy("review-pack", "Page review packs: capture a page's rendering contexts (tiles, DOM, signature) into a directory an agent can review without a browser, and judge a pack from disk through one bounded pool of vision calls.", async (program) => (await import("./commands/review-pack.js")).registerReviewPackCommand(program, emit, context), { hasOptions: true }),
+        lazy("qa-verify <path>", "Verify a qa-run result is fresh evidence for a specific invocation: match its run identity (run_id, job digest, tested revision, age, recorded output directory) against expectations. Fail-closed on missing identity.", async (program) => (await import("./commands/qa-verify.js")).registerQaVerifyCommand(program, emit), { hasOptions: true }),
+        lazy("qa-record <target>", "Record hand-performed page QA as a standard result document: same schema, run identity, stage timings, and freshness guarantees as qa-run, marked evidence_source manual so it can report a defect but never a pass.", async (program) => (await import("./commands/qa-record.js")).registerQaRecordCommand(program, emit, context), { hasOptions: true }),
+        lazy("qa-status [path]", "Report a qa-run's live state (queued/launching/running/completed/dead) from its run-status.json, PID liveness, and result document; --wait reconnects to a detached run and exits with its verdict; --queue shows the machine-wide browser-qa admission queue.", async (program) => (await import("./commands/qa-status.js")).registerQaStatusCommand(program, emit, context), { hasOptions: true }),
+        lazy("admission", "Machine-wide admission control for heavy jobs: `admission run --resource <name> -- <command…>` waits for a FIFO slot then runs the command; `admission status` lists holders and waiters per resource.", async (program) => (await import("./commands/admission.js")).registerAdmissionCommand(program, emit)),
         lazy("browse-session", "Control an opted-in headed browse session through an owner-only descriptor", async (program) => (await import("./commands/browse-session.js")).registerBrowseSessionCommand(program, emit)),
-        lazy("browse-ai <url>", `agent-browser (Vercel Labs) wrapper: accessibility-tree snapshots with element refs (@e1, @e2) for LLM consumption. Daemon-mode: successive calls reuse the same browser instance. Sister to ${binName} browse (Playwright).`, async (program) => (await import("./commands/browse-ai.js")).registerBrowseAiCommand(program, emit), { hasOptions: true }),
+        lazy("browse-ai <url>", `agent-browser (Vercel Labs) wrapper: accessibility-tree snapshots with element refs (@e1, @e2) for LLM consumption. Daemon-mode: successive calls reuse the same browser instance. Sister to ${binName} browse (Playwright).`, async (program) => (await import("./commands/browse-ai.js")).registerBrowseAiCommand(program, emit, context), { hasOptions: true }),
         {
             commands: [
                 {

package/dist/commands/admission.d.ts

@@ -0,0 +1,21 @@
+import { type Command } from "commander";
+import type { EmitContext } from "../commander.js";
+interface AdmissionSuperviseOpts {
+    jobDir: string;
+    timeout?: string;
+}
+/**
+ * Root for durable detached job records. A sibling of the admission queue root
+ * rather than a child of it, so job directories are never mistaken for
+ * admission resources by anything listing that directory.
+ */
+export declare function jobsBaseDir(): string;
+export declare function registerAdmissionCommand(program: Command, emit: EmitContext): void;
+/**
+ * Own one job record end to end: queue for the slot, run the command with its
+ * output on disk, then write the terminal record. Exported for tests, which
+ * drive it in-process against a temporary job directory.
+ */
+export declare function superviseJob(emit: EmitContext, opts: AdmissionSuperviseOpts): Promise<void>;
+export {};
+//# sourceMappingURL=admission.d.ts.map

package/dist/commands/admission.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admission.d.ts","sourceRoot":"","sources":["../../src/commands/admission.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,KAAK,OAAO,EAAU,MAAM,WAAW,CAAC;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AA2CnD,UAAU,sBAAsB;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAiBD;;;;GAIG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAiED,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CA8TlF;AAkHD;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CA8GjG"}

package/dist/commands/admission.js

@@ -0,0 +1,565 @@
+// `admission`: inspect the machine-wide admission queues, or run an arbitrary
+// command while holding a slot on a named resource. The queue mechanics live
+// in src/lib/admission.ts and the durable job record in src/lib/durable-job.ts;
+// this command owns flag parsing, human/JSON rendering, and exit-code
+// propagation for the wrapped child process.
+//
+// `run --detach` splits the work in two: the client mints a job record and
+// launches a detached supervisor, then returns. The supervisor holds the
+// admission slot, runs the command, and writes the terminal record. Losing the
+// client after that point interrupts nothing.
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { closeSync, openSync } from "node:fs";
+import { join } from "node:path";
+import { Option } from "commander";
+import { resolveBinName } from "../core/config.js";
+import { AdmissionTimeoutError, acquireAdmission, admissionBaseDir, admissionStatus, listAdmissionResources, } from "../lib/admission.js";
+import { classifyJob, createJobDir, DURABLE_JOB_HEARTBEAT_MS, DURABLE_JOB_LOG_FILENAME, DURABLE_JOB_SCHEMA_VERSION, formatJobAge, jobExitCode, listJobs, readJobDocument, writeJobDocument, writeJobStatus, } from "../lib/durable-job.js";
+import { coordEnv } from "../lib/env.js";
+const LABEL_MAX_CHARS = 80;
+const WAIT_POLL_MS = 2_000;
+const DEFAULT_WAIT_TIMEOUT_MINUTES = 120;
+const DEFAULT_JOBS_LIMIT = 20;
+/**
+ * Root for durable detached job records. A sibling of the admission queue root
+ * rather than a child of it, so job directories are never mistaken for
+ * admission resources by anything listing that directory.
+ */
+export function jobsBaseDir() {
+    return coordEnv("JOBS_DIR") ?? `${admissionBaseDir()}-jobs`;
+}
+/** Parse an integer flag with a bounded range; undefined means invalid. */
+function parseBoundedInt(raw, fallback, min, max) {
+    if (raw === undefined)
+        return fallback;
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value < min || value > max)
+        return undefined;
+    return value;
+}
+function describeEntry(entry) {
+    const since = entry.acquired_at ?? entry.created_at;
+    return `${entry.label || "(no label)"} (pid ${entry.pid}) since ${since}`;
+}
+function logResourceStatus(emit, status) {
+    emit.log(`${status.resource}: ${status.holders.length} holder(s), ${status.waiters.length} waiter(s)`, "info");
+    for (const holder of status.holders)
+        emit.log(`  holding: ${describeEntry(holder)}`, "info");
+    for (const waiter of status.waiters)
+        emit.log(`  waiting: ${describeEntry(waiter)}`, "info");
+}
+function describeError(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+function sleep(ms) {
+    return new Promise((resolvePromise) => setTimeout(resolvePromise, ms));
+}
+function nowIso() {
+    return new Date().toISOString();
+}
+/** One-line job summary shared by `jobs`, `wait`, and `status`. */
+function describeJobReport(report, nowMs) {
+    const label = report.label || "(no label)";
+    const resource = report.resource ?? "(no resource)";
+    const bits = [`${report.state}`, `resource ${resource}`];
+    if (report.terminal) {
+        bits.push(report.signal !== null
+            ? `killed by ${report.signal}`
+            : `exit ${report.exit_code ?? "unknown"}`);
+    }
+    else if (report.state === "dead") {
+        bits.push(`pid ${report.pid ?? "unknown"} not running`);
+    }
+    else {
+        bits.push(`pid ${report.pid ?? "unknown"}`);
+    }
+    if (report.heartbeat_age_ms !== null) {
+        bits.push(`heartbeat ${formatJobAge(report.heartbeat_age_ms)} ago`);
+    }
+    const startedMs = report.started_at !== null ? Date.parse(report.started_at) : Number.NaN;
+    if (!Number.isNaN(startedMs))
+        bits.push(`age ${formatJobAge(nowMs - startedMs)}`);
+    return `job ${report.job_id ?? "(no id)"}: ${bits.join(", ")} — ${label}`;
+}
+export function registerAdmissionCommand(program, emit) {
+    const admission = program
+        .command("admission")
+        .description("Machine-wide admission control for heavy jobs: inspect the per-resource " +
+        "slot queues, run a command while holding a slot, or launch it as a " +
+        "durable detached job that survives losing its client.")
+        .enablePositionalOptions();
+    // ------------------------------------------------------------------ status
+    admission
+        .command("status")
+        .description("Show holders and waiters per admission resource, plus any detached jobs " +
+        "still in flight. Queues prune dead-PID, expired, and torn entries as a " +
+        "side effect of being listed.")
+        .option("--resource <name>", "Show one resource instead of all of them.")
+        .option("--json", "Emit { resources: [...], jobs: [...] } as JSON.")
+        .addHelpText("after", "\nExit codes: 0 always (reporting only) · 1 usage error.")
+        .action((opts) => {
+        const dir = admissionBaseDir();
+        const resources = opts.resource !== undefined ? [opts.resource] : listAdmissionResources(dir);
+        const statuses = resources.map((resource) => admissionStatus({ dir, resource }));
+        const nowMs = Date.now();
+        const liveJobs = listJobs(jobsBaseDir())
+            .map((entry) => entry.report)
+            .filter((report) => report !== null && !report.terminal)
+            .filter((report) => report.state !== "dead" &&
+            (opts.resource === undefined || report.resource === opts.resource));
+        if (opts.json) {
+            emit.data({
+                resources: statuses.map((status) => ({
+                    resource: status.resource,
+                    holders: status.holders,
+                    waiters: status.waiters,
+                })),
+                jobs: liveJobs,
+            });
+            return;
+        }
+        const active = statuses.filter((status) => status.holders.length > 0 || status.waiters.length > 0);
+        if (active.length === 0 && liveJobs.length === 0) {
+            emit.log(opts.resource !== undefined
+                ? `no admission activity on ${opts.resource}`
+                : "no admission activity", "info");
+            return;
+        }
+        for (const status of active)
+            logResourceStatus(emit, status);
+        if (liveJobs.length > 0) {
+            emit.log(`detached jobs in flight: ${liveJobs.length}`, "info");
+            for (const report of liveJobs)
+                emit.log(`  ${describeJobReport(report, nowMs)}`, "info");
+        }
+    });
+    // --------------------------------------------------------------------- run
+    admission
+        .command("run")
+        .description("Acquire one slot on an admission resource, run <command...> with inherited " +
+        "stdio (no shell — the first token is the executable), then release the " +
+        "slot and propagate the child's exit code. Everything after -- reaches " +
+        "the child untouched. With --detach the command instead becomes a durable " +
+        "job supervised by a detached process.")
+        .passThroughOptions()
+        .requiredOption("--resource <name>", 'Admission resource to queue on, e.g. "browser-qa".')
+        .option("--capacity <n>", "Concurrent holders this machine should allow (1-32; default 1).")
+        .option("--timeout <minutes>", "Maximum admission wait before giving up (1-1440; default 60).")
+        .option("--label <text>", "Holder description shown in status listings (default: the command itself).")
+        .option("--detach", "Launch the command as a durable job: a detached supervisor holds the slot, " +
+        "runs the command, and records the outcome on disk. Prints the job id and " +
+        "job directory and returns immediately; losing the client no longer kills " +
+        "the job. Reconnect with admission wait <job-dir>.")
+        .option("--json", "With --detach, print the job envelope as JSON.")
+        .argument("<command...>", "Command to run while holding the slot.")
+        .addHelpText("after", "\nExit codes (foreground): the child's exit code · 4 admission timeout · " +
+        "1 usage error, spawn failure, or child killed by a signal." +
+        "\nExit codes (--detach): 0 once the job is launched · 1 usage error or " +
+        "launch failure. The job's own outcome comes from admission wait.")
+        .action(async (commandArgs, opts) => {
+        const capacity = parseBoundedInt(opts.capacity, 1, 1, 32);
+        if (capacity === undefined) {
+            emit.error({
+                code: "admission_usage",
+                message: "--capacity must be an integer between 1 and 32",
+            });
+            process.exitCode = 1;
+            return;
+        }
+        const timeoutMinutes = parseBoundedInt(opts.timeout, 60, 1, 1440);
+        if (timeoutMinutes === undefined) {
+            emit.error({
+                code: "admission_usage",
+                message: "--timeout must be an integer number of minutes between 1 and 1440",
+            });
+            process.exitCode = 1;
+            return;
+        }
+        const joined = commandArgs.join(" ");
+        const label = opts.label ??
+            (joined.length > LABEL_MAX_CHARS ? `${joined.slice(0, LABEL_MAX_CHARS - 3)}...` : joined);
+        if (opts.detach) {
+            launchDetachedJob(emit, {
+                commandArgs,
+                resource: opts.resource,
+                capacity,
+                label,
+                timeoutMinutes,
+                json: opts.json === true,
+            });
+            return;
+        }
+        const dir = admissionBaseDir();
+        let lastWaitMessage = "";
+        let handle;
+        try {
+            handle = await acquireAdmission({ dir, resource: opts.resource, capacity }, {
+                label,
+                timeoutMs: timeoutMinutes * 60_000,
+                onWait: (info) => {
+                    const holders = info.holders.map((holder) => holder.label).join(", ") || "none";
+                    const message = `queued for a ${opts.resource} slot: position ${info.position}, ` +
+                        `capacity ${capacity}, holder(s): ${holders}`;
+                    if (message !== lastWaitMessage) {
+                        lastWaitMessage = message;
+                        emit.log(message, "info");
+                    }
+                },
+            });
+        }
+        catch (err) {
+            if (err instanceof AdmissionTimeoutError) {
+                emit.error({
+                    code: "admission_timeout",
+                    message: err.message,
+                    hint: `${resolveBinName()} admission status --resource ${opts.resource} lists current holders`,
+                });
+                process.exitCode = 4;
+                return;
+            }
+            throw err;
+        }
+        const [executable, ...childArgs] = commandArgs;
+        try {
+            const outcome = await new Promise((resolvePromise, rejectPromise) => {
+                const child = spawn(executable, childArgs, {
+                    stdio: "inherit",
+                    shell: false,
+                });
+                child.on("error", rejectPromise);
+                child.on("exit", (code, signal) => resolvePromise({ code, signal }));
+            });
+            if (outcome.signal !== null) {
+                emit.error({
+                    code: "admission_child_signal",
+                    message: `${executable} was terminated by signal ${outcome.signal}`,
+                });
+                process.exitCode = 1;
+                return;
+            }
+            process.exitCode = outcome.code ?? 1;
+        }
+        catch (err) {
+            emit.error({
+                code: "admission_spawn_error",
+                message: `cannot run ${executable}: ${describeError(err)}`,
+            });
+            process.exitCode = 1;
+        }
+        finally {
+            handle.release();
+        }
+    });
+    // --------------------------------------------------------------- supervise
+    admission
+        .command("supervise", { hidden: true })
+        .description("Internal: run one durable job record to completion (detach child plumbing).")
+        .addOption(new Option("--job-dir <dir>", "Job directory to supervise.").makeOptionMandatory().hideHelp())
+        .addOption(new Option("--timeout <minutes>", "Maximum admission wait.").hideHelp())
+        .action(async (opts) => {
+        await superviseJob(emit, opts);
+    });
+    // -------------------------------------------------------------------- wait
+    admission
+        .command("wait <job-dir>")
+        .description("Reconnect to a detached job and block until it settles. Polls the job " +
+        "record every 2s: the record is authoritative, so a client that died and " +
+        "came back sees exactly the same outcome.")
+        .option("--timeout <minutes>", `Maximum time to wait for the job to settle (1-1440; default ${DEFAULT_WAIT_TIMEOUT_MINUTES}).`)
+        .option("--json", "Print the job report as JSON.")
+        .addHelpText("after", "\nExit codes: the job's own exit code once completed · 1 usage error or an " +
+        "unreadable job record · 4 the job is dead (non-terminal state, dead " +
+        "supervisor PID) · 5 the wait timed out while the job was still running.")
+        .action(async (jobDir, opts) => {
+        const timeoutMinutes = parseBoundedInt(opts.timeout, DEFAULT_WAIT_TIMEOUT_MINUTES, 1, 1440);
+        if (timeoutMinutes === undefined) {
+            emit.error({
+                code: "admission_usage",
+                message: "--timeout must be an integer number of minutes between 1 and 1440",
+            });
+            process.exitCode = 1;
+            return;
+        }
+        const deadline = Date.now() + timeoutMinutes * 60_000;
+        let lastState = "";
+        while (true) {
+            const outcome = classifyJob(jobDir);
+            if (!outcome.ok) {
+                emit.error({ code: "admission_job_unreadable", message: outcome.error });
+                process.exitCode = 1;
+                return;
+            }
+            const report = outcome.report;
+            const settled = report.terminal || report.state === "dead";
+            if (settled) {
+                if (opts.json)
+                    emit.data(report);
+                emit.log(describeJobReport(report, Date.now()), report.terminal ? "info" : "warn");
+                if (!report.terminal)
+                    emit.log(`log: ${report.log_path}`, "warn");
+                for (const warning of report.warnings)
+                    emit.log(`warning: ${warning}`, "warn");
+                const exit = jobExitCode(report);
+                if (exit !== 0)
+                    process.exitCode = exit;
+                return;
+            }
+            // Progress prints on state transitions only; a job that runs for an
+            // hour should not scroll a line every two seconds.
+            if (report.state !== lastState) {
+                lastState = report.state;
+                emit.log(describeJobReport(report, Date.now()), "info");
+            }
+            if (Date.now() >= deadline) {
+                if (opts.json)
+                    emit.data(report);
+                emit.log(`wait timed out after ${timeoutMinutes}m; job is still ${report.state}`, "warn");
+                process.exitCode = 5;
+                return;
+            }
+            await sleep(WAIT_POLL_MS);
+        }
+    });
+    // -------------------------------------------------------------------- jobs
+    admission
+        .command("jobs")
+        .description("List recent detached jobs, newest first: id, resource, state, label, age, " +
+        "and exit code. A job whose supervisor PID is gone before it completed " +
+        "lists as dead.")
+        .option("--json", "Emit { dir, jobs: [...] } as JSON.")
+        .option("--limit <n>", `Maximum jobs to list (1-500; default ${DEFAULT_JOBS_LIMIT}).`)
+        .addHelpText("after", "\nExit codes: 0 always (reporting only) · 1 usage error.")
+        .action((opts) => {
+        const limit = parseBoundedInt(opts.limit, DEFAULT_JOBS_LIMIT, 1, 500);
+        if (limit === undefined) {
+            emit.error({
+                code: "admission_usage",
+                message: "--limit must be an integer between 1 and 500",
+            });
+            process.exitCode = 1;
+            return;
+        }
+        const base = jobsBaseDir();
+        const entries = listJobs(base).slice(0, limit);
+        if (opts.json) {
+            emit.data({ dir: base, jobs: entries });
+            return;
+        }
+        if (entries.length === 0) {
+            emit.log(`no detached jobs under ${base}`, "info");
+            return;
+        }
+        const nowMs = Date.now();
+        for (const entry of entries) {
+            if (entry.report === null) {
+                emit.log(`job ${entry.job_id}: unreadable (${entry.error ?? "no status"})`, "warn");
+                continue;
+            }
+            emit.log(describeJobReport(entry.report, nowMs), entry.report.terminal ? "info" : "warn");
+        }
+    });
+}
+function launchDetachedJob(emit, options) {
+    const cliScript = process.argv[1];
+    if (!cliScript) {
+        emit.error({
+            code: "admission_no_cli_script",
+            message: "cannot resolve the host CLI script path to launch a detached supervisor",
+        });
+        process.exitCode = 1;
+        return;
+    }
+    const jobId = randomUUID();
+    const base = jobsBaseDir();
+    let jobDir;
+    let logFd;
+    try {
+        jobDir = createJobDir(base, jobId);
+        const document = {
+            schema_version: DURABLE_JOB_SCHEMA_VERSION,
+            job_id: jobId,
+            resource: options.resource,
+            capacity: options.capacity,
+            label: options.label,
+            argv: options.commandArgs,
+            cwd: process.cwd(),
+            created_at: nowIso(),
+        };
+        writeJobDocument(jobDir, document);
+        logFd = openSync(join(jobDir, DURABLE_JOB_LOG_FILENAME), "a");
+    }
+    catch (err) {
+        emit.error({
+            code: "admission_job_setup_failed",
+            message: `cannot create a job record under ${base}: ${describeError(err)}`,
+        });
+        process.exitCode = 1;
+        return;
+    }
+    // The supervisor is this same CLI, detached from the terminal with its
+    // output on disk: the client may die at any moment after this point.
+    let child;
+    try {
+        child = spawn(process.execPath, [
+            cliScript,
+            "admission",
+            "supervise",
+            "--job-dir",
+            jobDir,
+            "--timeout",
+            String(options.timeoutMinutes),
+        ], { detached: true, stdio: ["ignore", logFd, logFd] });
+        child.unref();
+    }
+    catch (err) {
+        closeSync(logFd);
+        emit.error({
+            code: "admission_supervisor_spawn_failed",
+            message: `cannot launch the job supervisor: ${describeError(err)}`,
+        });
+        process.exitCode = 1;
+        return;
+    }
+    closeSync(logFd);
+    const startedAt = nowIso();
+    const launching = {
+        schema_version: DURABLE_JOB_SCHEMA_VERSION,
+        job_id: jobId,
+        pid: child.pid ?? 0,
+        state: "launching",
+        started_at: startedAt,
+        updated_at: startedAt,
+    };
+    writeJobStatus(jobDir, launching);
+    const logPath = join(jobDir, DURABLE_JOB_LOG_FILENAME);
+    const binName = resolveBinName();
+    emit.log(`detached job ${jobId} (supervisor pid ${child.pid ?? "unknown"})`, "info");
+    emit.log(`job dir: ${jobDir}`, "info");
+    emit.log(`log: ${logPath}`, "info");
+    emit.log(`reconnect: ${binName} admission wait ${jobDir}`, "info");
+    if (options.json) {
+        emit.data({
+            detached: true,
+            job_id: jobId,
+            pid: child.pid ?? null,
+            job_dir: jobDir,
+            log: logPath,
+            resource: options.resource,
+        });
+    }
+}
+// ---------------------------------------------------------------------------
+// Detach: supervisor half
+// ---------------------------------------------------------------------------
+/**
+ * Own one job record end to end: queue for the slot, run the command with its
+ * output on disk, then write the terminal record. Exported for tests, which
+ * drive it in-process against a temporary job directory.
+ */
+export async function superviseJob(emit, opts) {
+    const jobDir = opts.jobDir;
+    const document = readJobDocument(jobDir);
+    if (!document || document.argv.length === 0) {
+        emit.error({
+            code: "admission_job_document_unreadable",
+            message: `${jobDir} carries no usable job document`,
+        });
+        process.exitCode = 1;
+        return;
+    }
+    const timeoutMinutes = parseBoundedInt(opts.timeout, 60, 1, 1440) ?? 60;
+    const startedAt = nowIso();
+    const status = {
+        schema_version: DURABLE_JOB_SCHEMA_VERSION,
+        job_id: document.job_id,
+        pid: process.pid,
+        state: "queued",
+        started_at: startedAt,
+        updated_at: startedAt,
+        queue: { resource: document.resource, waiting_since: startedAt },
+    };
+    writeJobStatus(jobDir, status);
+    const finish = (state) => {
+        writeJobStatus(jobDir, {
+            schema_version: DURABLE_JOB_SCHEMA_VERSION,
+            job_id: document.job_id,
+            pid: process.pid,
+            state: "completed",
+            started_at: startedAt,
+            updated_at: nowIso(),
+            exit_code: state.exitCode,
+            signal: state.signal,
+        });
+    };
+    let handle;
+    try {
+        handle = await acquireAdmission({
+            dir: admissionBaseDir(),
+            resource: document.resource,
+            capacity: document.capacity,
+        }, {
+            label: document.label,
+            timeoutMs: timeoutMinutes * 60_000,
+            onWait: () => {
+                writeJobStatus(jobDir, { ...status, updated_at: nowIso() });
+            },
+        });
+    }
+    catch (err) {
+        if (err instanceof AdmissionTimeoutError) {
+            emit.error({ code: "admission_timeout", message: err.message });
+            finish({ exitCode: 4, signal: null });
+            process.exitCode = 4;
+            return;
+        }
+        finish({ exitCode: 1, signal: null });
+        throw err;
+    }
+    const runningAt = nowIso();
+    const running = {
+        schema_version: DURABLE_JOB_SCHEMA_VERSION,
+        job_id: document.job_id,
+        pid: process.pid,
+        state: "running",
+        started_at: startedAt,
+        updated_at: runningAt,
+    };
+    writeJobStatus(jobDir, running);
+    // The heartbeat is what lets a reader tell a wedged supervisor from a busy
+    // one; a dead supervisor stops writing and the record classifies as dead.
+    const heartbeat = setInterval(() => {
+        writeJobStatus(jobDir, { ...running, updated_at: nowIso() });
+    }, DURABLE_JOB_HEARTBEAT_MS);
+    heartbeat.unref?.();
+    const [executable, ...childArgs] = document.argv;
+    let logFd;
+    try {
+        logFd = openSync(join(jobDir, DURABLE_JOB_LOG_FILENAME), "a");
+        const outcome = await new Promise((resolvePromise, rejectPromise) => {
+            const child = spawn(executable, childArgs, {
+                stdio: ["ignore", logFd, logFd],
+                shell: false,
+                ...(document.cwd ? { cwd: document.cwd } : {}),
+            });
+            child.on("error", rejectPromise);
+            child.on("exit", (code, signal) => resolvePromise({ code, signal }));
+        });
+        finish({ exitCode: outcome.code, signal: outcome.signal });
+        process.exitCode = outcome.signal !== null ? 1 : (outcome.code ?? 1);
+    }
+    catch (err) {
+        emit.error({
+            code: "admission_spawn_error",
+            message: `cannot run ${executable}: ${describeError(err)}`,
+        });
+        finish({ exitCode: 1, signal: null });
+        process.exitCode = 1;
+    }
+    finally {
+        clearInterval(heartbeat);
+        if (logFd !== undefined)
+            closeSync(logFd);
+        handle.release();
+    }
+}

package/dist/commands/agents.d.ts

@@ -121,6 +121,13 @@ export type EventLedgerHealthV3 = {
         /** Times the summary gate failed open (loose write proceeded). */
         mitigation_fail_open: number;
     };
+    coordination_authority: {
+        safe: boolean;
+        global_diagnostics: number;
+        isolated_diagnostics: number;
+        affected_generations: string[];
+        codes: string[];
+    };
     span_pressure: Array<{
         instance_id: string;
         generation_id: string;