@luckydraw/cumulus 1.0.3 → 1.0.5

package/dist/gateway/jobs.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Job registry — daemon-owned background jobs (task 139).
+ *
+ * WHY THIS EXISTS
+ * Cumulus tried three times to make background work reliable by TELLING the
+ * model how to do it: task 108 (the redirect cure), 109 (the two-leg
+ * watcher+deadline rule), 116 (the worked one-liner in the content store).
+ * All three are correct and all three still failed live, because the cure has
+ * to be applied by the driver AND every child, and because no shell trick
+ * escapes the third killer at all. This is task 115's lesson applied again:
+ * stop prescribing, enforce at the seam.
+ *
+ * WHAT OWNING IT BUYS, BY CONSTRUCTION
+ *   1. Turn end → SIGPIPE.  The daemon spawns the job with NO pipes: stdout and
+ *      stderr are a file descriptor, stdin is /dev/null. There is nothing whose
+ *      read end can close, so SIGPIPE (task 108's entire failure mode) stops
+ *      being reachable rather than being cured.
+ *   2. Interjection → SIGTERM.  The job is not in the turn's process tree, so
+ *      killing the turn cannot reach it.
+ *   3. Gateway reload → cgroup reap.  NOT solved by spawning here — `detached`
+ *      gives a new session, and a session does not leave a cgroup. It needs
+ *      `KillMode=process` on the unit (shipped in setup.ts's template). What
+ *      this module guarantees regardless is that a job killed by a restart is
+ *      REPORTED as interrupted rather than silently vanishing.
+ *
+ * The exit code is written to disk BY THE JOB ITSELF, not read off the child
+ * `exit` event. The event is authoritative while this process lives and is
+ * unavailable after a restart; the file survives both, which is what makes
+ * adoption able to distinguish "exited 7 while we were down" from "killed".
+ */
+export type JobStatus = 'running' | 'done' | 'failed' | 'cancelled' | 'interrupted';
+export interface JobRecord {
+    id: string;
+    thread: string;
+    label: string;
+    command: string;
+    cwd: string;
+    pid?: number;
+    /**
+     * OS-level start token, guarding against pid reuse across a gateway restart.
+     * A pid alone is not identity: on a busy box the number can belong to an
+     * unrelated process by the time we adopt, and we would then report a live
+     * job for something that died. Linux reads field 22 of /proc/<pid>/stat
+     * (start time in clock ticks); elsewhere it is absent and liveness degrades
+     * to a bare kill(pid, 0).
+     */
+    startToken?: string;
+    startedAt: string;
+    endedAt?: string;
+    status: JobStatus;
+    exitCode?: number;
+    signal?: string;
+    logPath: string;
+}
+export interface CreateJobRequest {
+    thread: string;
+    command: string;
+    label?: string;
+    cwd: string;
+}
+/** Max concurrently-running jobs for one thread. */
+export declare const MAX_RUNNING_PER_THREAD = 5;
+/** Max concurrently-running jobs across all threads. */
+export declare const MAX_RUNNING_TOTAL = 20;
+/** Finished records retained per thread; older ones are pruned with their logs. */
+export declare const MAX_FINISHED_PER_THREAD = 25;
+/** Lines of log tail carried in the completion report. */
+export declare const COMPLETION_TAIL_LINES = 40;
+/** How often adopted jobs (no live child handle) are checked for death. */
+export declare const ADOPTION_POLL_MS = 5000;
+export interface ValidationResult {
+    ok: boolean;
+    error?: string;
+}
+/**
+ * Validate a job request. Deliberately permissive about the command itself —
+ * a thread that reaches this seam has already been checked for `Bash`
+ * availability by the caller, so the command is no more privileged than what
+ * it could already run. What is rejected is what would make the RECORD
+ * unusable: an empty command, or a label that would corrupt the report.
+ */
+export declare function validateJobRequest(req: Partial<CreateJobRequest>): ValidationResult;
+/** Map a process outcome onto a durable status. */
+export declare function classifyExit(exitCode: number | undefined, signal?: string): JobStatus;
+/**
+ * Wrap the command so the job records its OWN exit status before leaving.
+ *
+ * An EXIT trap, NOT trailing statements. Trailing statements are unreachable
+ * whenever the command ends in `exit N` (or `exec`) — which is ordinary in a
+ * driver script, and which silently produced "interrupted" for jobs that had
+ * in fact finished cleanly. A trap fires on both paths. `$?` inside it is the
+ * status that triggered it, and nothing runs before the capture.
+ *
+ * The path arrives through the environment rather than interpolated, so no
+ * quoting of ours can collide with the command's.
+ *
+ * Known limit: a command that installs its own EXIT trap replaces this one, and
+ * that job reports as interrupted. Rare, and it degrades to the honest answer.
+ */
+export declare function wrapCommand(command: string): string;
+/** Read the OS start token for a pid (Linux only; undefined elsewhere). */
+export declare function readStartToken(pid: number): string | undefined;
+/**
+ * Is this pid still the process we started?
+ *
+ * `kill(pid, 0)` answers "does a process with this number exist", which is a
+ * weaker question. When a start token was recorded we also require it to
+ * match, so a recycled pid reads as dead rather than as our job.
+ */
+export declare function isProcessAlive(pid: number | undefined, startToken?: string): boolean;
+/**
+ * The message the finished job sends back into its thread.
+ *
+ * Self-describing on purpose: it may arrive either as a fresh turn (idle) or
+ * inside a batched queue drain (busy), and it has to read correctly both ways.
+ * It carries the exit code and a log tail so the woken turn can DIAGNOSE
+ * without re-running — task 109's "fire on outcome, not on success".
+ */
+export declare function formatCompletionMessage(job: JobRecord, logTail: string): string;
+/** Read the last N lines of a file, bounded so a huge log cannot be slurped. */
+export declare function tailFile(filePath: string, lines: number, maxBytes?: number): string;
+/**
+ * Trim finished records for a thread down to the retention cap.
+ * Returns the records to keep and the ones evicted (whose files the caller
+ * deletes) — pure so the retention rule is testable without a filesystem.
+ */
+export declare function pruneFinished(records: JobRecord[], thread: string, keep?: number): {
+    kept: JobRecord[];
+    evicted: JobRecord[];
+};
+export interface JobRegistryOptions {
+    /** Directory holding jobs.json and the per-job log/exit files. */
+    jobsDir?: string;
+    log?: (msg: string, data?: Record<string, unknown>) => void;
+    /**
+     * Deliver a completion report as a turn on the job's thread. Injected rather
+     * than imported so the registry has no dependency on the HTTP server (and so
+     * tests can observe delivery without spawning Claude). The daemon wires this
+     * to server.ts's `deliverAgentTurn`, which is the SAME busy-gate + queue used
+     * by the scheduler and every other inject path (tasks 100/120).
+     */
+    deliver: (thread: string, text: string, sender: string) => void | Promise<void>;
+    pollIntervalMs?: number;
+}
+export interface JobRegistryHandle {
+    create(req: CreateJobRequest): JobRecord;
+    list(thread: string): JobRecord[];
+    get(thread: string, id: string): JobRecord | undefined;
+    cancel(thread: string, id: string): boolean;
+    tail(thread: string, id: string, lines?: number): string | undefined;
+    /** Adopt jobs recorded by a previous daemon process. Called once at startup. */
+    adopt(): void;
+    stop(): void;
+    /** Test seam: run one adoption-poll pass immediately. */
+    pollOnce(): void;
+}
+export declare function createJobRegistry(opts: JobRegistryOptions): JobRegistryHandle;
+//# sourceMappingURL=jobs.d.ts.map

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

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

package/dist/gateway/jobs.js

@@ -0,0 +1,497 @@
+/**
+ * Job registry — daemon-owned background jobs (task 139).
+ *
+ * WHY THIS EXISTS
+ * Cumulus tried three times to make background work reliable by TELLING the
+ * model how to do it: task 108 (the redirect cure), 109 (the two-leg
+ * watcher+deadline rule), 116 (the worked one-liner in the content store).
+ * All three are correct and all three still failed live, because the cure has
+ * to be applied by the driver AND every child, and because no shell trick
+ * escapes the third killer at all. This is task 115's lesson applied again:
+ * stop prescribing, enforce at the seam.
+ *
+ * WHAT OWNING IT BUYS, BY CONSTRUCTION
+ *   1. Turn end → SIGPIPE.  The daemon spawns the job with NO pipes: stdout and
+ *      stderr are a file descriptor, stdin is /dev/null. There is nothing whose
+ *      read end can close, so SIGPIPE (task 108's entire failure mode) stops
+ *      being reachable rather than being cured.
+ *   2. Interjection → SIGTERM.  The job is not in the turn's process tree, so
+ *      killing the turn cannot reach it.
+ *   3. Gateway reload → cgroup reap.  NOT solved by spawning here — `detached`
+ *      gives a new session, and a session does not leave a cgroup. It needs
+ *      `KillMode=process` on the unit (shipped in setup.ts's template). What
+ *      this module guarantees regardless is that a job killed by a restart is
+ *      REPORTED as interrupted rather than silently vanishing.
+ *
+ * The exit code is written to disk BY THE JOB ITSELF, not read off the child
+ * `exit` event. The event is authoritative while this process lives and is
+ * unavailable after a restart; the file survives both, which is what makes
+ * adoption able to distinguish "exited 7 while we were down" from "killed".
+ */
+import { spawn } from 'child_process';
+import * as crypto from 'crypto';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+// ─── Pure helpers ────────────────────────────────────────────────────────────
+/** Max concurrently-running jobs for one thread. */
+export const MAX_RUNNING_PER_THREAD = 5;
+/** Max concurrently-running jobs across all threads. */
+export const MAX_RUNNING_TOTAL = 20;
+/** Finished records retained per thread; older ones are pruned with their logs. */
+export const MAX_FINISHED_PER_THREAD = 25;
+/** Lines of log tail carried in the completion report. */
+export const COMPLETION_TAIL_LINES = 40;
+/** How often adopted jobs (no live child handle) are checked for death. */
+export const ADOPTION_POLL_MS = 5_000;
+/**
+ * Validate a job request. Deliberately permissive about the command itself —
+ * a thread that reaches this seam has already been checked for `Bash`
+ * availability by the caller, so the command is no more privileged than what
+ * it could already run. What is rejected is what would make the RECORD
+ * unusable: an empty command, or a label that would corrupt the report.
+ */
+export function validateJobRequest(req) {
+    if (typeof req.command !== 'string' || req.command.trim().length === 0) {
+        return { ok: false, error: 'command is required and must be a non-empty string' };
+    }
+    if (req.command.length > 8_000) {
+        return { ok: false, error: 'command exceeds 8000 characters' };
+    }
+    if (req.label !== undefined) {
+        if (typeof req.label !== 'string') {
+            return { ok: false, error: 'label must be a string' };
+        }
+        if (req.label.length > 120) {
+            return { ok: false, error: 'label exceeds 120 characters' };
+        }
+    }
+    if (req.cwd !== undefined && typeof req.cwd !== 'string') {
+        return { ok: false, error: 'cwd must be a string' };
+    }
+    return { ok: true };
+}
+/** Map a process outcome onto a durable status. */
+export function classifyExit(exitCode, signal) {
+    if (signal)
+        return 'failed';
+    if (exitCode === undefined)
+        return 'interrupted';
+    return exitCode === 0 ? 'done' : 'failed';
+}
+/**
+ * Wrap the command so the job records its OWN exit status before leaving.
+ *
+ * An EXIT trap, NOT trailing statements. Trailing statements are unreachable
+ * whenever the command ends in `exit N` (or `exec`) — which is ordinary in a
+ * driver script, and which silently produced "interrupted" for jobs that had
+ * in fact finished cleanly. A trap fires on both paths. `$?` inside it is the
+ * status that triggered it, and nothing runs before the capture.
+ *
+ * The path arrives through the environment rather than interpolated, so no
+ * quoting of ours can collide with the command's.
+ *
+ * Known limit: a command that installs its own EXIT trap replaces this one, and
+ * that job reports as interrupted. Rare, and it degrades to the honest answer.
+ */
+export function wrapCommand(command) {
+    return [
+        `trap '__cumulus_rc=$?; printf %s "$__cumulus_rc" > "$CUMULUS_JOB_EXIT_FILE" 2>/dev/null' EXIT`,
+        command,
+    ].join('\n');
+}
+/** Read the OS start token for a pid (Linux only; undefined elsewhere). */
+export function readStartToken(pid) {
+    try {
+        const stat = fs.readFileSync(`/proc/${pid}/stat`, 'utf-8');
+        // Field 2 (comm) can contain spaces and parentheses, so split after the
+        // LAST ')' rather than tokenising the whole line.
+        const after = stat.slice(stat.lastIndexOf(')') + 2);
+        const fields = after.split(' ');
+        // starttime is field 22 overall = index 19 of the post-comm fields
+        return fields[19];
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Is this pid still the process we started?
+ *
+ * `kill(pid, 0)` answers "does a process with this number exist", which is a
+ * weaker question. When a start token was recorded we also require it to
+ * match, so a recycled pid reads as dead rather than as our job.
+ */
+export function isProcessAlive(pid, startToken) {
+    if (!pid || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+    }
+    catch (err) {
+        // EPERM means it EXISTS but belongs to someone else — alive, not gone.
+        return err?.code === 'EPERM';
+    }
+    if (startToken === undefined)
+        return true;
+    const current = readStartToken(pid);
+    if (current === undefined)
+        return true; // can't tell — don't declare it dead
+    return current === startToken;
+}
+function humanDuration(ms) {
+    const s = Math.round(ms / 1000);
+    if (s < 60)
+        return `${s}s`;
+    const m = Math.floor(s / 60);
+    if (m < 60)
+        return `${m}m ${s % 60}s`;
+    return `${Math.floor(m / 60)}h ${m % 60}m`;
+}
+/**
+ * The message the finished job sends back into its thread.
+ *
+ * Self-describing on purpose: it may arrive either as a fresh turn (idle) or
+ * inside a batched queue drain (busy), and it has to read correctly both ways.
+ * It carries the exit code and a log tail so the woken turn can DIAGNOSE
+ * without re-running — task 109's "fire on outcome, not on success".
+ */
+export function formatCompletionMessage(job, logTail) {
+    const started = new Date(job.startedAt).getTime();
+    const ended = job.endedAt ? new Date(job.endedAt).getTime() : Date.now();
+    const duration = humanDuration(Math.max(0, ended - started));
+    const outcome = job.status === 'done'
+        ? 'succeeded (exit 0)'
+        : job.status === 'cancelled'
+            ? 'was cancelled'
+            : job.status === 'interrupted'
+                ? 'was INTERRUPTED — the gateway restarted while it was running, and it did not record an exit status. It may or may not have completed its work; verify before assuming either.'
+                : job.signal
+                    ? `was killed by ${job.signal}`
+                    : `FAILED (exit ${job.exitCode})`;
+    const lines = [
+        `[background job ${job.id} "${job.label}"] ${outcome} after ${duration}.`,
+        `Command: ${job.command}`,
+        `Working directory: ${job.cwd}`,
+        `Full log: ${job.logPath}`,
+    ];
+    if (logTail.trim().length > 0) {
+        lines.push('', `--- last ${COMPLETION_TAIL_LINES} lines of output ---`, logTail.trimEnd());
+    }
+    else {
+        lines.push('', '(the job produced no output)');
+    }
+    lines.push('', 'This is the job you started reporting its own outcome. Continue the work it was part of; read the full log if the tail is not enough.');
+    return lines.join('\n');
+}
+/** Read the last N lines of a file, bounded so a huge log cannot be slurped. */
+export function tailFile(filePath, lines, maxBytes = 256 * 1024) {
+    try {
+        const stat = fs.statSync(filePath);
+        const start = Math.max(0, stat.size - maxBytes);
+        const fd = fs.openSync(filePath, 'r');
+        try {
+            const length = stat.size - start;
+            const buf = Buffer.alloc(length);
+            fs.readSync(fd, buf, 0, length, start);
+            const text = buf.toString('utf-8');
+            const all = text.split('\n');
+            // A partial first line is an artifact of the byte window, not content.
+            if (start > 0 && all.length > 1)
+                all.shift();
+            return all.slice(-lines).join('\n');
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Trim finished records for a thread down to the retention cap.
+ * Returns the records to keep and the ones evicted (whose files the caller
+ * deletes) — pure so the retention rule is testable without a filesystem.
+ */
+export function pruneFinished(records, thread, keep = MAX_FINISHED_PER_THREAD) {
+    const finished = records
+        .filter(r => r.thread === thread && r.status !== 'running')
+        .sort((a, b) => (a.endedAt ?? a.startedAt).localeCompare(b.endedAt ?? b.startedAt));
+    if (finished.length <= keep)
+        return { kept: records, evicted: [] };
+    const evicted = finished.slice(0, finished.length - keep);
+    const evictedIds = new Set(evicted.map(r => r.id));
+    return { kept: records.filter(r => !evictedIds.has(r.id)), evicted };
+}
+function defaultJobsDir() {
+    return path.join(process.env.CUMULUS_DIR || path.join(os.homedir(), '.cumulus'), 'jobs');
+}
+export function createJobRegistry(opts) {
+    const jobsDir = opts.jobsDir ?? defaultJobsDir();
+    const registryPath = path.join(jobsDir, 'jobs.json');
+    const log = opts.log ?? ((msg) => console.log(`[Jobs] ${msg}`));
+    const pollMs = opts.pollIntervalMs ?? ADOPTION_POLL_MS;
+    let records = [];
+    /** Jobs spawned by THIS process — their exit arrives as an event, not a poll. */
+    const liveChildren = new Map();
+    let poller = null;
+    let stopped = false;
+    fs.mkdirSync(jobsDir, { recursive: true });
+    function loadRegistry() {
+        try {
+            records = JSON.parse(fs.readFileSync(registryPath, 'utf-8'));
+            if (!Array.isArray(records))
+                records = [];
+        }
+        catch {
+            records = [];
+        }
+    }
+    function persist() {
+        try {
+            const tmp = `${registryPath}.tmp`;
+            fs.writeFileSync(tmp, JSON.stringify(records, null, 2));
+            fs.renameSync(tmp, registryPath);
+        }
+        catch (err) {
+            log(`Failed to persist job registry: ${err}`);
+        }
+    }
+    function exitFilePath(id) {
+        return path.join(jobsDir, `${id}.exit`);
+    }
+    function readRecordedExit(id) {
+        try {
+            const raw = fs.readFileSync(exitFilePath(id), 'utf-8').trim();
+            const code = parseInt(raw, 10);
+            return Number.isNaN(code) ? undefined : code;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    function prune(thread) {
+        const { kept, evicted } = pruneFinished(records, thread);
+        if (evicted.length === 0)
+            return;
+        records = kept;
+        for (const job of evicted) {
+            try {
+                fs.unlinkSync(job.logPath);
+            }
+            catch {
+                /* already gone */
+            }
+            try {
+                fs.unlinkSync(exitFilePath(job.id));
+            }
+            catch {
+                /* already gone */
+            }
+        }
+    }
+    /**
+     * Finalize a job and wake its thread. Idempotent — a job reports once.
+     *
+     * `notify` is false only for an explicit cancel: the thread that cancelled is
+     * mid-turn, so a report would be queued and then spend a whole extra turn
+     * telling it something it just did.
+     */
+    function finish(job, status, exitCode, signal, notify = true) {
+        if (job.status !== 'running')
+            return;
+        job.status = status;
+        job.exitCode = exitCode;
+        if (signal)
+            job.signal = signal;
+        job.endedAt = new Date().toISOString();
+        liveChildren.delete(job.id);
+        prune(job.thread);
+        persist();
+        log(`Job ${job.id} ("${job.label}") ${status}`, {
+            thread: job.thread,
+            exitCode,
+            signal,
+            durationMs: Date.now() - new Date(job.startedAt).getTime(),
+        });
+        if (!notify)
+            return;
+        const tail = tailFile(job.logPath, COMPLETION_TAIL_LINES);
+        void Promise.resolve(opts.deliver(job.thread, formatCompletionMessage(job, tail), `job:${job.id}`)).catch(err => log(`Failed to deliver completion for ${job.id}: ${err}`));
+    }
+    function create(req) {
+        const id = `job_${crypto.randomBytes(4).toString('hex')}`;
+        const logPath = path.join(jobsDir, `${id}.log`);
+        const label = req.label?.trim() || req.command.trim().split('\n')[0].slice(0, 60);
+        const job = {
+            id,
+            thread: req.thread,
+            label,
+            command: req.command,
+            cwd: req.cwd,
+            startedAt: new Date().toISOString(),
+            status: 'running',
+            logPath,
+        };
+        // A stale exit file from a recycled id would be read as this job's status.
+        try {
+            fs.unlinkSync(exitFilePath(id));
+        }
+        catch {
+            /* expected: no such file */
+        }
+        // stdout AND stderr go to one fd. Both matter — task 108 measured that an
+        // inherited stderr pipe is a second SIGPIPE source, and the fd here is
+        // exactly what makes both unreachable.
+        const fd = fs.openSync(logPath, 'a');
+        try {
+            const isWindows = process.platform === 'win32';
+            const child = spawn(isWindows ? req.command : wrapCommand(req.command), {
+                cwd: req.cwd,
+                shell: true,
+                detached: true,
+                stdio: ['ignore', fd, fd],
+                windowsHide: true,
+                env: {
+                    ...process.env,
+                    CUMULUS_JOB_ID: id,
+                    CUMULUS_JOB_EXIT_FILE: exitFilePath(id),
+                },
+            });
+            job.pid = child.pid;
+            if (child.pid)
+                job.startToken = readStartToken(child.pid);
+            child.on('exit', (code, signal) => {
+                finish(job, classifyExit(code ?? undefined, signal ?? undefined), code ?? undefined, signal ?? undefined);
+            });
+            child.on('error', err => {
+                log(`Job ${id} failed to start: ${err}`);
+                finish(job, 'failed', undefined);
+            });
+            // The whole point: the daemon must not wait on this, and must be able to
+            // exit without it.
+            child.unref();
+            liveChildren.set(id, child);
+        }
+        finally {
+            // The child dup'd the descriptor; holding ours open would leak one fd per
+            // job for the lifetime of the daemon.
+            fs.closeSync(fd);
+        }
+        records.push(job);
+        persist();
+        log(`Job ${id} started ("${label}")`, { thread: req.thread, pid: job.pid, cwd: req.cwd });
+        return job;
+    }
+    function runningCount(thread) {
+        return records.filter(r => r.status === 'running' && (!thread || r.thread === thread)).length;
+    }
+    /**
+     * Check adopted jobs (those with no live child handle) for death. A job we
+     * spawned reports through its `exit` event; one inherited from a previous
+     * daemon has no event to fire, so its death is only observable by polling.
+     */
+    function pollOnce() {
+        if (stopped)
+            return;
+        for (const job of records) {
+            if (job.status !== 'running')
+                continue;
+            if (liveChildren.has(job.id))
+                continue;
+            if (isProcessAlive(job.pid, job.startToken))
+                continue;
+            const code = readRecordedExit(job.id);
+            finish(job, code === undefined ? 'interrupted' : classifyExit(code), code);
+        }
+    }
+    function adopt() {
+        loadRegistry();
+        const running = records.filter(r => r.status === 'running');
+        if (running.length === 0)
+            return;
+        let alive = 0;
+        for (const job of running) {
+            if (isProcessAlive(job.pid, job.startToken)) {
+                alive++;
+                log(`Adopted still-running job ${job.id} ("${job.label}")`, {
+                    thread: job.thread,
+                    pid: job.pid,
+                });
+            }
+        }
+        log(`Adoption: ${alive} of ${running.length} recorded job(s) still running`);
+        // Anything not alive is finalized here — with its recorded exit code if the
+        // job got far enough to write one, otherwise honestly as `interrupted`.
+        pollOnce();
+    }
+    loadRegistry();
+    poller = setInterval(pollOnce, pollMs);
+    poller.unref();
+    return {
+        create(req) {
+            if (runningCount(req.thread) >= MAX_RUNNING_PER_THREAD) {
+                throw new Error(`Thread already has ${MAX_RUNNING_PER_THREAD} running jobs — wait for one to finish or cancel it`);
+            }
+            if (runningCount() >= MAX_RUNNING_TOTAL) {
+                throw new Error(`Gateway already has ${MAX_RUNNING_TOTAL} running jobs`);
+            }
+            return create(req);
+        },
+        list(thread) {
+            return records.filter(r => r.thread === thread);
+        },
+        get(thread, id) {
+            return records.find(r => r.thread === thread && r.id === id);
+        },
+        cancel(thread, id) {
+            const job = records.find(r => r.thread === thread && r.id === id);
+            if (!job || job.status !== 'running')
+                return false;
+            if (job.pid) {
+                try {
+                    // Negative pid = the whole process group. `detached: true` made the
+                    // job a group leader, so this reaches the children it spawned too —
+                    // without it, cancelling a driver script orphans everything it ran.
+                    process.kill(-job.pid, 'SIGTERM');
+                }
+                catch {
+                    try {
+                        process.kill(job.pid, 'SIGTERM');
+                    }
+                    catch {
+                        /* already gone */
+                    }
+                }
+            }
+            finish(job, 'cancelled', undefined, undefined, false);
+            return true;
+        },
+        tail(thread, id, lines = COMPLETION_TAIL_LINES) {
+            const job = records.find(r => r.thread === thread && r.id === id);
+            if (!job)
+                return undefined;
+            return tailFile(job.logPath, lines);
+        },
+        adopt,
+        pollOnce,
+        stop() {
+            stopped = true;
+            if (poller) {
+                clearInterval(poller);
+                poller = null;
+            }
+            // Deliberately NOT killing running jobs: outliving this process is the
+            // entire feature. They are recorded, and the next daemon adopts them.
+            // Listeners ARE detached, so a stopped registry is fully inert — it must
+            // not keep writing jobs.json out from under whoever adopts next.
+            for (const child of liveChildren.values()) {
+                child.removeAllListeners('exit');
+                child.removeAllListeners('error');
+            }
+            liveChildren.clear();
+        },
+    };
+}
+//# sourceMappingURL=jobs.js.map