looply-cli 0.0.0-stage → 0.2.0

package/dist/run-launcher.js

@@ -0,0 +1,652 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_ADOPTED_ITEMS = exports.RunLauncher = exports.DEFAULT_SETTLE_MS = void 0;
+exports.asStartResult = asStartResult;
+exports.refuseStart = refuseStart;
+exports.readStartPayload = readStartPayload;
+exports.hoursFromPayload = hoursFromPayload;
+exports.nodeRunLauncher = nodeRunLauncher;
+const node_child_process_1 = require("node:child_process");
+const node_path_1 = require("node:path");
+const run_lease_1 = require("./run-lease");
+const git_driver_1 = require("./git-driver");
+const run_start_marks_1 = require("./run-start-marks");
+const run_refusal_marks_1 = require("./run-refusal-marks");
+const ledger_store_1 = require("./ledger-store");
+/**
+ * The same answer, restated for a caller that must decide rather than report.
+ *
+ * A pure projection, so there is exactly one implementation of "what happened"
+ * and this is a view onto it — not a second opinion. The daemon's command
+ * handler keeps reading {@link LaunchResult} directly and is untouched.
+ *
+ * The two rules worth stating out loud:
+ *
+ *   A terminal result with NO code is `blocked`, never `refused`. That covers
+ *   every contention case and also the case where the run did refuse but its
+ *   mark could not be read — in which case the honest answer is "I do not know
+ *   why", and a caller that may end a person's grant on the strength of this
+ *   must not be handed a guess.
+ *
+ *   `started: true` without a runId is `pending`, not `run-started`. For a run
+ *   that can only ever be true of a job held to no proof contract, and a
+ *   controller that treated it as a Run would wait for an ending that no
+ *   ledger will ever carry.
+ */
+function asStartResult(r) {
+    if (r.started) {
+        return r.runId === undefined
+            ? { kind: 'pending', reason: 'a run is going here but has not proven itself yet' }
+            : { kind: 'run-started', runId: r.runId };
+    }
+    if ('waiting' in r)
+        return { kind: 'pending', reason: r.reason };
+    if ('terminal' in r) {
+        return r.code === undefined
+            ? { kind: 'blocked', reason: r.reason }
+            : { kind: 'refused', code: r.code, reason: r.reason };
+    }
+    return { kind: 'failed', reason: r.reason };
+}
+/**
+ * Long enough for an ENOENT or an argument the CLI refuses outright to come
+ * back, short enough that the phone's tap still feels answered.
+ */
+exports.DEFAULT_SETTLE_MS = 750;
+/**
+ * The exit code `looply run` uses for a refusal retrying cannot fix.
+ *
+ * A second declaration of run-cmd's `EXIT_REFUSED`, on purpose and not
+ * exported: the daemon's spawner must not import the composition root of the
+ * thing it spawns to read one number. The pairing is covered by tests on both
+ * sides — that run-cmd's constant is 3, and that a child exiting 3 is reported
+ * terminal here.
+ */
+const EXIT_REFUSED = 3;
+/**
+ * The child's door for "another process already owns this exact attempt".
+ *
+ * A second declaration of run-cmd's `EXIT_ATTEMPT_CLAIMED`, on purpose and for
+ * the same reason `EXIT_REFUSED` is one: the spawner must not import the
+ * composition root of the thing it spawns to read a number. Both sides are
+ * pinned.
+ *
+ * Reported terminal for this poll but WITHOUT a code, so it reads as `blocked`
+ * and never as a statement about the goal. Nothing happened to the work; two
+ * processes simply arrived at the same instant.
+ */
+const EXIT_ATTEMPT_CLAIMED = 4;
+class RunLauncher {
+    deps;
+    /**
+     * Job name → the child believed to still be running. Absent once it exits.
+     *
+     * It remembers `goalId` because "a run is already going" is no longer a
+     * complete answer: a second start-run naming a DIFFERENT goal is a different
+     * request, and answering it with the run that is already here would ack a goal
+     * that never ran.
+     */
+    live = new Map();
+    /**
+     * How a child this launcher spawned actually ended, by the command that asked
+     * for it.
+     *
+     * The child is detached and unref'd, so `launch` has long returned by the time
+     * it exits — and under the old contract nobody ever read the exit code again.
+     * A run that refuses its goal after a second of preflight exits 3, and this is
+     * what carries that answer to the next poll.
+     *
+     * In memory only, and deliberately: it is an optimisation, not the record. A
+     * daemon restart forgets, relaunches once, and the child refuses again — one
+     * wasted spawn rather than a wrong ack.
+     */
+    ended = new Map();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * What to tell the daemon a terminal refusal was, given what this process saw.
+     *
+     * `fallback` is what the launcher can see by itself — an exit code — and it
+     * is what shipped before the run could say more. The run's own reason is
+     * preferred whenever it left one for THIS command: the whole point is that
+     * "the run exited — exit 3" and "this goal's work is done" are not the same
+     * answer to somebody waiting on their phone.
+     *
+     * Keyed by command id, so a refusal can only ever be reported against the
+     * request that produced it. Never throws: a reason that cannot be read leaves
+     * the refusal exactly as truthful as it was, just less specific.
+     */
+    async refusalMark(requestId) {
+        if (requestId === undefined || !this.deps.refusalOf)
+            return null;
+        try {
+            return await this.deps.refusalOf(requestId);
+        }
+        catch {
+            // Never throws. A reason that cannot be read leaves the refusal exactly
+            // as truthful as it was, just less specific — and, importantly, without a
+            // code, so nothing downstream may conclude anything from it.
+            return null;
+        }
+    }
+    /**
+     * Is any run live in this process?
+     *
+     * ⚠️ ANY CHECKOUT, NOT ONLY THE MAIN ONE. Job keys are `run` for an unplaced
+     * run and `run:<workspace>` for one a coordinator placed, and a caller asking
+     * "is a run going" means any of them.
+     */
+    isRunning() {
+        return [...this.live.keys()].some((k) => k === 'run' || k.startsWith('run:'));
+    }
+    async start(req) {
+        const { requestId } = req;
+        /**
+         * 🔴 A REFUSAL OUTRANKS A RECEIPT, AND IT HAS TO NOW THAT THE RECEIPT IS
+         * HONEST ABOUT WHEN A RUN BEGAN.
+         *
+         * The receipt used to be written at `run.started`, which is after every
+         * refusal that can still speak for the goal — so nothing could ever hold
+         * both. It is now written when the run REGISTERS (see `run-cmd`, at
+         * `registry.register`), because that is when "a Run exists" becomes true,
+         * and six terminal refusals live downstream of it: a superseded goal, an
+         * adoption failure, a finished work set, a stalled one.
+         *
+         * Read in this order, a run that registered and then refused reports the
+         * REFUSAL — the more specific statement, and the only arm that may ever
+         * end a person's grant. Read the other way round it would report
+         * `run-started`, and a goal that asked for a human would be quietly
+         * retried instead.
+         *
+         * ⚠️ AND IT IS CORRECT IN EVERY ORDER. A refusal before registration has
+         * no receipt to outrank; a receipt with no refusal is a run that began and
+         * did not decide, which is exactly `run-started`.
+         */
+        const refusedFirst = await this.refusalMark(requestId);
+        if (refusedFirst?.code !== undefined)
+            return terminalOf(refusedFirst, refusedFirst.reason);
+        // Proven next, and durably. This is the only thing that may report
+        // `started`, and it is also what makes a repeat of the SAME request
+        // idempotent after the child has gone: no lease, no live child, but the run
+        // it asked for demonstrably happened.
+        if (this.deps.provenStart) {
+            const mark = await this.deps.provenStart(requestId);
+            if (mark)
+                return { started: true, already: true, pid: undefined, runId: mark.runId };
+        }
+        // How the child this request already spawned ended, if it has. Read before
+        // the lease, because a child that refused has released whatever it held and
+        // would otherwise look like a free tree to relaunch into.
+        const ended = this.ended.get(requestId);
+        if (ended) {
+            return ended.terminal
+                ? terminalOf(await this.refusalMark(requestId), ended.reason)
+                : { started: false, reason: ended.reason };
+        }
+        /**
+         * 🔴 THE JOB KEY IS THE CHECKOUT, NOT THE WORD "run".
+         *
+         * `live` was keyed by the literal `'run'`, so the SECOND launch of a cadence
+         * found the first and reported "the run this asked for is still starting" —
+         * one run per daemon, for ever, whatever the scheduler decided. The
+         * contended resource is a WORKING TREE, and two runs in two trees contend
+         * over nothing.
+         *
+         * ⚠️ WITH NO WORKSPACE THE KEY IS STILL EXACTLY `'run'`, so the phone's
+         * Start and a single-checkout daemon keep the one-run-per-project behaviour
+         * they have always had.
+         */
+        const job = req.workspace === undefined ? 'run' : `run:${req.workspace}`;
+        return this.launch(job, [
+            'run',
+            ...(req.hours !== undefined ? ['--hours', String(req.hours)] : []),
+            // WHERE THIS EXECUTION RUNS — Phase 1's own parallel interface, used by
+            // the coordinator exactly as a person uses it: a second isolated
+            // execution is a second `looply run` in a second workspace.
+            ...(req.workspace === undefined ? [] : ['--in', req.workspace]),
+            // Carried into the run's lease, so a repeated Start can be told apart
+            // from a second request for another run.
+            //
+            // The FLAG keeps its name while the value generalises, for the same
+            // reason the mark files keep theirs: it is the established wire between
+            // this daemon and the child it spawns, renaming it buys nothing a
+            // comment cannot, and every durable record already written is keyed
+            // this way.
+            '--command-id',
+            requestId,
+            // The goal this run is for, on the same argv channel. The daemon only
+            // CARRIES these three; the run process is what resolves the goal,
+            // decides whether the mirrored version is fresh enough to act on, and
+            // adopts the items. Splitting that judgement across two processes is
+            // how the two would come to disagree.
+            // Only an autonomous Start counts its tries, so only an autonomous
+            // Start carries the number. A human Start's argv is byte-identical to
+            // what it has always been.
+            //
+            // `--autonomous` carries the ONE fact the run needs about who asked:
+            // whether beginning it counts as a person saying go. Not the
+            // controller id, not the ordinal, not the grant — none of that is the
+            // run's business, and sending it would put controller vocabulary
+            // inside a process that must stay blind to it.
+            ...(req.origin.kind === 'autonomy'
+                ? ['--request-attempt', String(req.origin.attempt), '--autonomous']
+                : []),
+            ...(req.resumedFromApprovalId !== undefined
+                ? ['--resumed-from-approval', req.resumedFromApprovalId]
+                : []),
+            // The exact approved action this Start was accepted to carry out. The
+            // daemon CARRIES it and proves nothing about it; the run checks it
+            // against the reservation the Start gate wrote.
+            ...(req.governedApprovalId !== undefined
+                ? ['--governed-approval', req.governedApprovalId]
+                : []),
+            ...(req.goalId !== undefined ? ['--goal-id', req.goalId] : []),
+            ...(req.goalVersion !== undefined ? ['--goal-version', String(req.goalVersion)] : []),
+            ...(req.itemIds !== undefined ? ['--item-ids', req.itemIds.join(',')] : []),
+        ], { commandId: requestId, goalId: req.goalId }, 
+        // A run has a start boundary that can be proven — `run.started` in the
+        // ledger — so it is held to it.
+        true, req.workspace);
+    }
+    /**
+     * `looply scan`, as a child, so the lens passes stream into the ledger and
+     * reach the phone rather than being twenty silent minutes.
+     */
+    async scan() {
+        // Deliberately NOT held to the proof contract, and the one place the two
+        // protocols differ. A scan has no start boundary to prove: it emits
+        // `scan.started` but nothing downstream binds a command to it, and unlike a
+        // run it leaves nothing half-done — a scan that dies writes no items, and
+        // the next one simply does the work again. Holding it to a proof it cannot
+        // produce would leave every scan command unacked until it expired.
+        return this.launch('scan', ['scan']);
+    }
+    async launch(job, args, want = {}, 
+    /** Whether this job can produce durable evidence that it started. */
+    provable = false, 
+    /** The checkout this run is for, when a coordinator placed it there. */
+    workspace) {
+        // Two of the same job on one repo would fight over the same files: two runs
+        // over one branch and working tree, two scans over one queue.json. This
+        // reports started rather than refusing: the phone asked for the job to be in
+        // progress and it is, and a refusal would leave the command unacked to be
+        // retried against the job already doing what was asked.
+        const running = this.live.get(job);
+        if (running) {
+            const clash = refuseStart(want, running);
+            if (clash)
+                return { started: false, terminal: true, reason: clash };
+            // A child for this same request is already going and has not proven
+            // itself yet — the proven check above would have caught it if it had.
+            // Waiting, NOT started: this is exactly the moment the old contract lied.
+            return provable
+                ? { started: false, waiting: true, reason: `the ${job} this asked for is still starting` }
+                : { started: true, already: true, pid: running.pid };
+        }
+        // The durable half of the same question. The map above only remembers what
+        // *this* daemon started; after a restart it is empty, and a redelivered
+        // start-run would spawn a second runner over a tree the first is still
+        // editing. The lease outlives the daemon, so it answers correctly.
+        /**
+         * ⚠️ THE LEASE OF THE CHECKOUT THIS RUN IS FOR. With no workspace that is
+         * the project's own, which is exactly what it has always been — and asking
+         * the project's lease about a second workspace is asking the wrong file: a
+         * live run in the main checkout refused a launch into an empty workspace
+         * beside it, which is the single-run behaviour that made N-way scheduling
+         * impossible however the scheduler decided.
+         */
+        const peek = workspace !== undefined && this.deps.peekLeaseAt
+            ? () => this.deps.peekLeaseAt(workspace)
+            : this.deps.peekLease;
+        if (job.startsWith('run') && peek) {
+            const state = await peek();
+            if (state.kind === 'active') {
+                // Already doing what the phone asked. Reported as started rather than
+                // refused, so the command is acknowledged instead of retried against
+                // the very run that is already satisfying it.
+                //
+                // Unless it is NOT what was asked. The lease records the goal the live
+                // run is bound to and it outlives this daemon, so this is the answer
+                // that still works after a restart, when the map above is empty.
+                const clash = refuseStart(want, {
+                    commandId: state.lease.startedByCommandId,
+                    goalId: state.lease.goalId,
+                });
+                if (clash)
+                    return { started: false, terminal: true, reason: clash };
+                // The lease says a run for this request holds the tree. That is NOT
+                // proof it started: the lease is taken before adoption and before
+                // verification, either of which can still end the process without a
+                // Run. Only the mark above proves it, and it did not.
+                return {
+                    started: false,
+                    waiting: true,
+                    reason: `a run for this request holds the tree and has not started yet`,
+                };
+            }
+            if (state.kind === 'ambiguous') {
+                // Cannot prove nothing is running here. Terminal, not retryable: an
+                // hour of three-second retries would not make it any more decidable,
+                // and starting anyway is the failure this whole mechanism prevents.
+                return { started: false, terminal: true, reason: (0, run_lease_1.describeLease)(state) };
+            }
+        }
+        let failure = null;
+        let refused = false;
+        /** The child lost the attempt race. Terminal for this poll, never semantic. */
+        let claimed = false;
+        /** Keep the child's answer for the next poll, since `launch` has returned by then. */
+        const remember = (terminal, reason) => {
+            if (want.commandId !== undefined && !this.ended.has(want.commandId)) {
+                this.ended.set(want.commandId, { terminal, reason });
+            }
+        };
+        const handle = this.deps.spawn(args);
+        const live = { pid: handle.pid, ...want };
+        this.live.set(job, live);
+        const clear = () => {
+            // Only if it is still *this* child: a late exit from a previous job must
+            // not clear the slot a newer one is holding.
+            if (this.live.get(job) === live)
+                this.live.delete(job);
+        };
+        // First reason wins — error-then-exit is one failure, reported once.
+        handle.onError((e) => {
+            failure ??= `could not start the ${job}: ${e.message}`;
+            remember(false, failure);
+            clear();
+        });
+        handle.onExit((code) => {
+            // Not a refusal, and not a failure worth retrying on its own: the winner
+            // is doing the work right now. Terminal for this poll, uncoded, so the
+            // caller reads `blocked` and asks again later about the request rather
+            // than about this attempt.
+            if (code === EXIT_ATTEMPT_CLAIMED) {
+                claimed = true;
+                failure ??= `another process is already executing this attempt`;
+                remember(true, failure);
+                clear();
+                return;
+            }
+            // The child's own door for a refusal it will not take back: a goal that
+            // was abandoned, a version that moved on, items that cannot be adopted.
+            // Retrying those every three seconds for the rest of the redelivery
+            // window is noise, so this is reported terminal rather than failed.
+            if (code === EXIT_REFUSED)
+                refused = true;
+            // Not "immediately" any more: this fires whenever the child ends, which
+            // may be long after the settle window. That is the whole point — the
+            // answer is kept for the next poll instead of being thrown away.
+            failure ??= `the ${job} exited — ${code === null ? 'killed by a signal' : `exit ${code}`}`;
+            remember(code === EXIT_REFUSED, failure);
+            clear();
+        });
+        // Still a wait, and still worth having: an ENOENT or a config the CLI
+        // refuses outright comes back inside it, and answering the phone in one
+        // tick beats answering in the next poll. But NOTHING depends on it any
+        // more. Surviving it is not evidence of anything; it only means no answer
+        // has arrived yet.
+        await this.deps.sleep(this.deps.settleMs ?? exports.DEFAULT_SETTLE_MS);
+        if (failure !== null) {
+            // Both doors reach the same answer. A run that refuses fast — an
+            // abandoned goal, a stale version — exits inside the settle window and
+            // returns here; one that refuses after preflight returns through the
+            // remembered path above. Enriching only one of them would make the
+            // reason depend on how quickly the child made up its mind.
+            // A lost attempt is terminal for this poll and carries NO code, so it
+            // reads as blocked rather than as anything about the goal. It is checked
+            // before the refusal path because the loser wrote no mark to read.
+            if (claimed)
+                return { started: false, terminal: true, reason: failure };
+            return refused
+                ? terminalOf(await this.refusalMark(want.commandId), failure)
+                : { started: false, reason: failure };
+        }
+        if (handle.pid === undefined) {
+            // No pid and no error: nothing to point at, so nothing to claim.
+            clear();
+            return { started: false, reason: `the ${job} process never started` };
+        }
+        handle.release();
+        return provable
+            ? { started: false, waiting: true, reason: `the ${job} is starting`, spawnedPid: handle.pid }
+            : { started: true, already: false, pid: handle.pid };
+    }
+}
+exports.RunLauncher = RunLauncher;
+/**
+ * The run budget the phone asked for, if it asked for a sane one.
+ *
+ * The payload comes off the wire as `unknown` and goes onto a command line, so
+ * anything that is not a positive finite number is dropped in favour of the
+ * config's own budget rather than passed through to be refused by the child.
+ */
+/**
+ * A terminal LaunchResult built from whatever the run left behind.
+ *
+ * ONE place decides how a mark becomes a result, so the two paths that reach a
+ * terminal refusal — the child that exits inside the settle window and the one
+ * that exits long after it — cannot come to different answers. Enriching only
+ * one of them would make the reason a person reads depend on how quickly the
+ * child made up its mind.
+ *
+ * An empty reason is not a reason: it falls back to what the launcher itself
+ * could see. The CODE does not fall back, because there is nothing to fall back
+ * to — its absence is the honest report that this process cannot say which
+ * refusal happened.
+ */
+function terminalOf(mark, fallback) {
+    const reason = mark && mark.reason.trim() !== '' ? mark.reason : fallback;
+    return {
+        started: false,
+        terminal: true,
+        reason,
+        ...(mark?.code === undefined ? {} : { code: mark.code }),
+    };
+}
+/**
+ * Whether an already-running job answers the Start that just arrived.
+ *
+ * "A run is already going here" used to be a complete answer, and it was: both
+ * callers had asked for a run to be in progress, and one was. A goal makes it
+ * incomplete, and `itemIds` makes goal identity insufficient too — these are
+ * DIFFERENT requests:
+ *
+ *     C1  goal G, items [A]        C2  goal G, items [B]
+ *
+ * C2 is not satisfied because a G-bound run happens to exist; it asked for work
+ * that run will never pick. So the identity of a Start is its REQUEST, not its
+ * goal.
+ *
+ * That is sound for a human Start because the command row is durable and its
+ * payload cannot mutate after creation — the only writes to an existing row are
+ * the ack and the expiry sweep — so one command id means one unchanging request.
+ * It is sound for an autonomous Start for a different reason with the same
+ * force: `autonomyStartId(C, N)` is derived from a controller id and an ordinal
+ * whose reservation receipt is created with O_EXCL and never rewritten, so one
+ * request id there also means one unchanging request. Neither depends on the
+ * other, and the launcher does not need to know which it is holding.
+ *
+ * Returns the refusal text, or `null` when the live run genuinely satisfies it.
+ */
+function refuseStart(want, live) {
+    // Two unbound Starts are still the request they always were — "have a run in
+    // progress" — and one is. Left exactly as it was, so nothing about a manual
+    // or legacy run changes.
+    if (want.goalId === undefined && live.goalId === undefined)
+        return null;
+    // Same command: a redelivery of one durable row. Idempotent by construction.
+    if (want.commandId !== undefined && want.commandId === live.commandId)
+        return null;
+    const describe = (r) => (r.goalId === undefined ? 'no goal' : `goal ${r.goalId}`);
+    if (want.goalId !== live.goalId) {
+        return `a run is already going here for ${describe(live)}, and this asked for ${describe(want)} — stop it first`;
+    }
+    // Same goal, different command. The live run is bound to whatever items its
+    // own Start named, and will pick nothing else — so acking this one would
+    // promise work that is never going to happen.
+    return `a different run for ${describe(live)} is already going here — it will not pick this request's items, so stop it first`;
+}
+/**
+ * How many items one Start may adopt.
+ *
+ * The adoption list travels to the run process on its command line, and an
+ * argv that exceeds the OS limit produces a spawn failure rather than a
+ * refusal — a command nobody can carry out and nobody can read. A bound the
+ * daemon states is better than one the kernel enforces.
+ */
+exports.MAX_ADOPTED_ITEMS = 200;
+function readStartPayload(payload) {
+    const p = typeof payload === 'object' && payload !== null ? payload : {};
+    const hours = hoursFromPayload(payload);
+    const budget = hours === undefined ? {} : { hours };
+    if (p['goalId'] === undefined) {
+        // A legacy Start. Goal-shaped fields beside no goal are a payload this
+        // build cannot honour, not one it may quietly ignore: running them as an
+        // unbound run is exactly the silent widening this reader exists to stop.
+        if (p['goalVersion'] !== undefined || p['itemIds'] !== undefined) {
+            return { ok: false, problem: 'carries goal fields but names no goal' };
+        }
+        return { ok: true, start: budget };
+    }
+    const goalId = p['goalId'];
+    if (typeof goalId !== 'string' || goalId.length === 0) {
+        return { ok: false, problem: 'names a goal this build cannot read' };
+    }
+    // Required, not optional. The server stamps it on every goal-bound Start, so
+    // a payload naming a goal without one did not come from a server this build
+    // can reason about — and accepting it would mean running with no way to tell
+    // whether the local mirror of the goal is the one the phone was looking at.
+    const version = p['goalVersion'];
+    if (typeof version !== 'number' || !Number.isInteger(version) || version < 0) {
+        return { ok: false, problem: `names goal ${goalId} without a version this build can read` };
+    }
+    let itemIds;
+    if (p['itemIds'] !== undefined) {
+        const ids = p['itemIds'];
+        if (!Array.isArray(ids) || ids.some((i) => typeof i !== 'string' || i.length === 0)) {
+            return { ok: false, problem: `names items for goal ${goalId} this build cannot read` };
+        }
+        if (ids.length > exports.MAX_ADOPTED_ITEMS) {
+            return { ok: false, problem: `names ${ids.length} items for goal ${goalId}, more than the ${exports.MAX_ADOPTED_ITEMS} one start may adopt` };
+        }
+        // The list crosses to the run process comma-separated. Ids are minted
+        // without commas, but this reader does not get to assume what some other
+        // process minted — a comma inside one id would silently become two ids,
+        // and adopting an item nobody named is worse than refusing.
+        if (ids.some((i) => i.includes(','))) {
+            return { ok: false, problem: `names an item id for goal ${goalId} this build cannot carry` };
+        }
+        if (new Set(ids).size !== ids.length) {
+            return { ok: false, problem: `names the same item twice for goal ${goalId}` };
+        }
+        itemIds = ids;
+    }
+    return { ok: true, start: { ...budget, goalId, goalVersion: version, ...(itemIds === undefined ? {} : { itemIds }) } };
+}
+function hoursFromPayload(payload) {
+    if (typeof payload !== 'object' || payload === null || !('hours' in payload))
+        return undefined;
+    const h = payload.hours;
+    if (typeof h !== 'number' || !Number.isFinite(h) || h <= 0)
+        return undefined;
+    return h;
+}
+/* istanbul ignore next — real child processes; the logic lives in RunLauncher */
+function nodeRunLauncher(cwd, stateDir) {
+    const leases = stateDir ? new run_lease_1.RunLeaseStore(stateDir, run_lease_1.nodeLeaseFs) : null;
+    /**
+     * 🔴 PROJECT-SCOPED, BECAUSE THESE ARE THE DAEMON↔RUN WIRE — AND EXECUTION
+     * SCOPING THEM ESCALATED EVERY COORDINATED GOAL TO A HUMAN.
+     *
+     * A LEASE is about a CHECKOUT: one run per working tree, so it belongs beside
+     * the tree, and `peekLeaseAt` below reads whichever tree is being launched
+     * into. A START MARK is about a REQUEST — durable proof that the Start the
+     * daemon asked for produced a Run — and the daemon is its only reader.
+     *
+     * MEASURED end to end: a coordinator-placed run wrote `run-starts.json` into
+     * its WORKSPACE, and the daemon read it from its own checkout. `provenStart`
+     * therefore answered null for every placed run, the launcher never reported
+     * `started`, and `autonomy-controller` concluded
+     *
+     *     Start 1 was attempted 3 times and never began
+     *
+     * escalating a perfectly healthy goal to `human_required` — three cadences
+     * into every night, for every goal the coordinator placed.
+     *
+     * ⚠️ INVISIBLE IN A SINGLE CHECKOUT, which is why nothing caught it: there
+     * the project and execution state directories ARE the same path, so writer
+     * and reader agree by accident. It appears only once a run is placed
+     * somewhere else, which is the entire point of a coordinator.
+     */
+    const project = (0, git_driver_1.projectStateDir)(cwd);
+    const marks = new run_start_marks_1.RunStartMarks(project, ledger_store_1.nodeLedgerFs);
+    const refusals = new run_refusal_marks_1.RunRefusalMarks(project, ledger_store_1.nodeLedgerFs);
+    return new RunLauncher({
+        ...(leases ? { peekLease: () => leases.inspect() } : {}),
+        /**
+         * 🔴 THE LEASE OF THE CHECKOUT BEING LAUNCHED INTO.
+         *
+         * `peekLease` above answers about the project's own state directory and
+         * nothing else, so a live run in the main checkout refused every launch
+         * into an idle workspace beside it — the single-run behaviour that made
+         * N-way scheduling impossible however the scheduler decided.
+         *
+         * ⚠️ THE SAME `STATE_DIR` LAYOUT, addressed at another root: a workspace is
+         * a checkout, and a checkout's lease lives where every checkout's does.
+         */
+        peekLeaseAt: (workspace) => new run_lease_1.RunLeaseStore((0, node_path_1.join)(workspace, git_driver_1.STATE_DIR, 'state'), run_lease_1.nodeLeaseFs).inspect(),
+        ...(refusals
+            ? {
+                // Re-read every time, for the same reason `provenStart` does: the
+                // file is written by another process, and the thing this is looking
+                // for happens after any snapshot taken before it.
+                refusalOf: async (requestId) => {
+                    await refusals.load();
+                    const mark = refusals.find(requestId);
+                    if (mark === null)
+                        return null;
+                    // Reason AND code. The code is what lets a caller act on the
+                    // refusal instead of merely reporting it.
+                    return {
+                        reason: mark.reason,
+                        ...(mark.code === undefined ? {} : { code: mark.code }),
+                    };
+                },
+            }
+            : {}),
+        ...(marks
+            ? {
+                // Re-read every time. The file is written by another process — the run
+                // itself — so anything cached here would be a snapshot of the moment
+                // before the very thing it is looking for happened.
+                provenStart: async (requestId) => {
+                    await marks.load();
+                    return marks.find(requestId);
+                },
+            }
+            : {}),
+        spawn: (args) => {
+            // Re-invoke this same CLI rather than resolving `looply` on PATH: the
+            // daemon may well have been started through npx or a workspace link, and
+            // the child must be the same build as the daemon that spawned it.
+            const entry = process.argv[1];
+            const child = (0, node_child_process_1.spawn)(process.execPath, entry ? [entry, ...args] : [...args], {
+                cwd,
+                // Detached and released, so Ctrl-C on the daemon does not take down a
+                // run mid-round and leave a half-built tree behind.
+                detached: true,
+                stdio: 'ignore',
+            });
+            return {
+                pid: child.pid,
+                onExit: (cb) => child.on('exit', (code) => cb(code)),
+                onError: (cb) => child.on('error', cb),
+                release: () => child.unref(),
+            };
+        },
+        sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+    });
+}
+//# sourceMappingURL=run-launcher.js.map