looply-cli 0.0.0-stage → 0.3.0

package/dist/daemon-cmd.js

@@ -0,0 +1,1751 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SKIP_REFUSED_REASON = exports.PLACEMENT_WAIT_MS = exports.CLI_VERSION = void 0;
+exports.pairCommand = pairCommand;
+exports.resolveProjectId = resolveProjectId;
+exports.resolveProjectIdWithConsent = resolveProjectIdWithConsent;
+exports.isYes = isYes;
+exports.renderRegisterAsk = renderRegisterAsk;
+exports.nodeRegisterAsk = nodeRegisterAsk;
+exports.reviewRefusedReason = reviewRefusedReason;
+exports.makeCommandHandler = makeCommandHandler;
+exports.daemonCommand = daemonCommand;
+exports.grantOf = grantOf;
+const pursuit_delivery_1 = require("./pursuit-delivery");
+const node_crypto_1 = require("node:crypto");
+const node_path_1 = require("node:path");
+const machine_store_1 = require("./machine-store");
+const server_client_1 = require("./server-client");
+const daemon_1 = require("./daemon");
+const signals_1 = require("./signals");
+const pair_cmd_1 = require("./pair-cmd");
+const redraw_1 = require("./redraw");
+const goal_ownership_1 = require("./goal-ownership");
+const run_launcher_1 = require("./run-launcher");
+const control_file_1 = require("./control-file");
+const command_receipts_1 = require("./command-receipts");
+const ledger_store_1 = require("./ledger-store");
+const stale_run_sweep_1 = require("./stale-run-sweep");
+const run_ending_locator_1 = require("./run-ending-locator");
+const run_lease_1 = require("./run-lease");
+const workspace_1 = require("./workspace");
+const cursor_store_1 = require("./cursor-store");
+const ledger_replay_1 = require("./ledger-replay");
+const goal_runs_1 = require("./goal-runs");
+const goal_store_1 = require("./goal-store");
+const core_1 = require("@looply/core");
+const autonomy_store_1 = require("./autonomy-store");
+const start_attempts_1 = require("./start-attempts");
+const autonomy_tick_1 = require("./autonomy-tick");
+const grant_reconcile_1 = require("./grant-reconcile");
+const run_start_marks_1 = require("./run-start-marks");
+const run_refusal_marks_1 = require("./run-refusal-marks");
+const approval_gate_read_1 = require("./approval-gate-read");
+const explicit_start_gate_1 = require("./explicit-start-gate");
+const approval_resumes_1 = require("./approval-resumes");
+const governed_approvals_1 = require("./governed-approvals");
+const core_2 = require("@looply/core");
+const git_driver_1 = require("./git-driver");
+const setup_prompt_1 = require("./setup-prompt");
+const ui_1 = require("./ui");
+const rails_stores_1 = require("./rails-stores");
+const daemon_lock_1 = require("./daemon-lock");
+const coordinator_1 = require("./coordinator");
+const coordinator_state_1 = require("./coordinator-state");
+const ask_brain_1 = require("./ask-brain");
+const depends_review_1 = require("./depends-review");
+const brain_advice_1 = require("./brain-advice");
+const index_for_head_1 = require("./index-for-head");
+const packet_for_goal_1 = require("./packet-for-goal");
+const project_index_facts_1 = require("./project-index-facts");
+const project_memory_store_1 = require("./project-memory-store");
+const workspace_provisioner_1 = require("./workspace-provisioner");
+const preemptor_1 = require("./preemptor");
+const stop_follow_up_1 = require("./stop-follow-up");
+const programme_mode_1 = require("./programme-mode");
+const reaper_1 = require("./reaper");
+const integrator_1 = require("./integrator");
+const integration_deps_1 = require("./integration-deps");
+const completion_1 = require("./completion");
+const lane_coverage_1 = require("./lane-coverage");
+/**
+ * Composition roots for `looply pair` and `looply daemon`.
+ *
+ * Both need the same three things — a machine identity on disk, a server client
+ * carrying its token, and a project id for this repo — so they are assembled
+ * here rather than twice.
+ */
+exports.CLI_VERSION = '0.1.0';
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const sha256 = (s) => (0, node_crypto_1.createHash)('sha256').update(s, 'utf8').digest('hex');
+async function pairCommand(opts) {
+    const store = new machine_store_1.MachineStore((0, machine_store_1.machineFilePath)());
+    const client = new server_client_1.ServerClient({ baseUrl: opts.serverUrl });
+    // A repo checked out at a filesystem root has an empty basename, which would
+    // send a blank machine name to the server and show as a blank row in the app.
+    const machineName = opts.machineName ?? ((0, node_path_1.basename)(opts.cwd) || 'this machine');
+    opts.log(`server  : ${opts.serverUrl}`);
+    opts.log(`machine : ${machineName}`);
+    const redrawer = new redraw_1.Redrawer((0, redraw_1.nodeRedrawSink)());
+    const result = await (0, pair_cmd_1.runPair)({
+        serverUrl: opts.serverUrl,
+        machineName,
+        store,
+        client,
+        log: opts.log,
+        // Drawn in place. A reissue replaces the box instead of printing a second
+        // one below it, so the only code on screen is the one that still works.
+        render: (info, secondsLeft) => redrawer.draw((0, pair_cmd_1.renderPairCode)(info, secondsLeft)),
+        sleep,
+        now: () => Date.now(),
+    });
+    if (!result.paired) {
+        opts.log(`pair    : gave up — ${result.reason ?? 'unknown'}`);
+        return 1;
+    }
+    opts.log('          next: `looply daemon` to keep this machine connected.');
+    return 0;
+}
+/**
+ * Resolve this repo to a server-side project, registering it the first time.
+ *
+ * The mapping is cached on the machine so a second run does not create a second
+ * project row for the same directory, and the server keys on
+ * `(machineId, repoPathHash)` so even a lost cache converges rather than
+ * duplicating.
+ */
+async function resolveProjectId(store, client, machineId, cwd, name) {
+    const hash = (0, machine_store_1.repoPathHash)(cwd, sha256);
+    const cached = store.projectFor(hash);
+    if (cached)
+        return cached;
+    const r = await client.registerProject({ machineId, name, repoPathHash: hash });
+    store.rememberProject(hash, r.project.id);
+    return r.project.id;
+}
+/**
+ * Resolve this repo to a project, asking before creating one that does not exist.
+ *
+ * Registration is the one irreversible thing the daemon does on startup, and it
+ * used to happen silently: `looply daemon` in the wrong folder — a home
+ * directory, a scratch clone, a tarball someone unpacked — put a permanent row
+ * on the server that nobody asked for and, until recently, nothing could remove.
+ * A directory this machine already knows is never asked about, so the ordinary
+ * case is unchanged and the question only appears when something new is about to
+ * be created.
+ */
+async function resolveProjectIdWithConsent(store, client, machineId, cwd, name, gate) {
+    const cached = store.projectFor((0, machine_store_1.repoPathHash)(cwd, sha256));
+    if (cached)
+        return { kind: 'known', projectId: cached };
+    if (!gate.assumeYes) {
+        if (!gate.ask)
+            return { kind: 'refused', reason: 'no-terminal' };
+        if (!(await gate.ask({ cwd, name })))
+            return { kind: 'refused', reason: 'declined' };
+    }
+    return { kind: 'registered', projectId: await resolveProjectId(store, client, machineId, cwd, name) };
+}
+/** Blank means no. The safe answer to "shall I create something permanent" is the default one. */
+function isYes(raw) {
+    return /^(y|yes)$/i.test(raw.trim());
+}
+function renderRegisterAsk(info) {
+    return `\n${(0, ui_1.box)([
+        'No looply project is registered for this directory:',
+        '',
+        `  ${(0, ui_1.bold)(info.cwd)}`,
+        '',
+        (0, ui_1.grey)('Saying yes creates one on the server, called'),
+        `  ${(0, ui_1.bold)(info.name)}`,
+        (0, ui_1.grey)('and it stays there until somebody deletes it.'),
+    ], { title: 'register this directory?', tone: ui_1.volt })}\n`;
+}
+/** The terminal half: print the box, read one answer, put the prompt away. */
+function nodeRegisterAsk(write) {
+    return async (info) => {
+        write(renderRegisterAsk(info));
+        const asker = (0, setup_prompt_1.nodeAsker)();
+        try {
+            return isYes(await asker.question(`  ${(0, ui_1.volt)('›')} ${(0, ui_1.dim)('[y/N]')} `));
+        }
+        finally {
+            asker.close();
+        }
+    };
+}
+/** How long a person's Start waits for the coordinator to place its goal. */
+exports.PLACEMENT_WAIT_MS = 60_000;
+/**
+ * M6-17: WHAT THE DAEMON SAYS WHEN THE PHONE ASKS FOR A VERB THIS BUILD DOES
+ * NOT CARRY OUT. The refusal was a bare `refused` — the phone saw the word and
+ * nothing else (the audit's I-06), while the review it was tapping on writes
+ * one row on the server and reaches no machine (J-03). The kit's plan says the
+ * wiring is a later, governed cycle and that the honest first step is the
+ * truth on both surfaces: the reason travels on the wire the way M6-10's
+ * ceiling refusal does, stored with the receipt, replayed on a redelivery.
+ */
+exports.SKIP_REFUSED_REASON = 'skip is not carried out by this build — a run picks its own next item; stop it if the current one should not go on';
+function reviewRefusedReason(kind) {
+    return (`${kind} is not carried out by this machine — a review is recorded on the server and reaches no machine yet; ` +
+        'nothing has been pushed or reverted');
+}
+function makeCommandHandler(log, starter, control, 
+/**
+ * What this machine has already finished with.
+ *
+ * Optional so every existing caller and test keeps working without one; when
+ * present it is what stops a redelivered command being carried out twice.
+ */
+receipts, 
+/** The project this daemon is for, when it knows. Commands for others are not ours. */
+projectId, 
+/**
+ * How this machine lets go of a goal's work.
+ *
+ * Optional like `starter`, and for the same reason: a caller that cannot
+ * carry a release out must leave it queued rather than ack something it
+ * never did.
+ */
+releaser, 
+/**
+ * Where a grant of autonomy is written down.
+ *
+ * Optional like the rest, and for the same reason: a daemon with no store to
+ * put it in must leave the command queued rather than ack a permission it
+ * did not record. A grant that was acked and not stored is the worst of both
+ * -- the phone shows it was received, and nothing on this machine knows.
+ */
+autonomy, 
+/**
+ * THE LAST AUTHORITY BOUNDARY BEFORE A RUN EXISTS.
+ *
+ * Asked immediately before the Start seam, and not a moment earlier, because
+ * everything between the question and the spawn is a window in which a person
+ * can be asked something. A gate read at the top of `dispatch` would answer
+ * about a world that had already moved.
+ *
+ * Optional like everything beside it: a daemon that cannot ask has no
+ * approvals to be held by, and every existing caller and test keeps working
+ * without one.
+ */
+approvals, 
+/**
+ * M6-9: WHERE THE COORDINATOR PLACED A GOAL THIS CADENCE, when it has.
+ *
+ * A person's Start on a placed goal goes to that checkout — the same answer
+ * the autonomy tick hands the launcher — and that checkout's lease is the
+ * explicit-start carrier. Found live (M6-8): without this the person's run
+ * landed in the project checkout, found an empty queue, compiled through the
+ * agent and ended `aborted`, while the work it was resumed for sat in the
+ * checkout the machine had made for it. Optional so every existing caller is
+ * unchanged; absent, or a goal placed nowhere, is today's path.
+ */
+workspaceFor, 
+/**
+ * M6-10: the owner's Start ceiling per grant (`machine.programme.limits.starts_per_grant`).
+ * The daemon's own ceiling was core's MAX; a declared one lower than that is
+ * honoured here — a grant asking for more is refused, naming the limit,
+ * never clamped. Absent, core's MAX as before.
+ */
+startCeiling, 
+/**
+ * M6-14: whether the coordinator is still placing a goal (see
+ * {@link PlacementInProgress}). Optional so every existing caller is
+ * unchanged; absent, a goal placed nowhere goes to the project checkout as
+ * before.
+ */
+placing) {
+    // When each waiting Start was first seen, by command id — so the bound is
+    // measured from the first poll that found the goal being placed.
+    const waitingSince = new Map();
+    return async (command) => {
+        // A machine can host several projects, and `pop` scopes only to the
+        // machine. Without this a daemon running in project A would faithfully
+        // carry out a start-run meant for project B — spawning a run in the wrong
+        // repository. Left for the daemon that owns it rather than refused.
+        if (projectId !== undefined && command.projectId !== projectId) {
+            log(`daemon  : ${command.kind} is for another project here — leaving it queued.`);
+            return 'retry';
+        }
+        // Already finished with. The lease cannot answer this: it stops existing
+        // when the run ends, so a start-run redelivered after its run completed
+        // would find a free tree and start a second one.
+        const priorReceipt = receipts?.seen(command.id);
+        if (priorReceipt) {
+            log(`daemon  : ${command.kind} was already carried out here (${priorReceipt.outcome}).`);
+            // The SAME answer as the first time, reason included. A redelivery is a
+            // repeated question, not a new one, and answering it with a barer version
+            // of the original would make a lost ack quietly cost the explanation.
+            return priorReceipt.outcome === 'refused' && priorReceipt.reason !== undefined
+                ? { disposition: 'refused', reason: priorReceipt.reason }
+                : priorReceipt.outcome;
+        }
+        // An unreadable receipts file means we cannot prove a consequential command
+        // has not already run. Refused rather than retried — retrying will not make
+        // the file readable — and terminal, so it does not repeat every three
+        // seconds for the redelivery window. Deleting the file clears it.
+        if (receipts?.status() === 'unreadable' && !(0, command_receipts_1.isRepeatable)(command.kind)) {
+            log(`daemon  : cannot tell whether ${command.kind} already ran here — refusing it.`);
+            log('          .looply/state/commands.json is unreadable; delete it to reset.');
+            return 'refused';
+        }
+        const decision = await dispatch(command);
+        const disposition = typeof decision === 'string' ? decision : decision.disposition;
+        const reason = typeof decision === 'string' ? undefined : decision.reason;
+        // Recorded before the ack, so a crash between the two leaves the receipt
+        // rather than losing it: the redelivery that follows is then recognised
+        // instead of re-executed. The reason goes down with it for the same
+        // reason — a receipt that outlives the ack has to be able to answer as
+        // fully as the ack would have.
+        if (receipts && disposition !== 'retry') {
+            await receipts.record(command.id, command.kind, disposition, reason);
+        }
+        return decision;
+    };
+    async function dispatch(command) {
+        switch (command.kind) {
+            case 'start-run': {
+                if (!starter) {
+                    log('daemon  : start-run is not carried out here — leaving it queued.');
+                    return 'retry';
+                }
+                // Read defensively: the payload is `unknown` all the way from the
+                // phone, stored verbatim as Json, handed back through Redis, and this
+                // build may be older or newer than the one that wrote the row.
+                const read = (0, run_launcher_1.readStartPayload)(command.payload);
+                if (!read.ok) {
+                    // Refused rather than run, because the other option is starting an
+                    // UNBOUND run over the whole queue while the phone waits for a goal
+                    // that will never bind — the failure this reader exists to prevent.
+                    // Terminal: a durable row will not read any better in three seconds.
+                    log(`daemon  : start-run ${read.problem} — refusing it.`);
+                    return 'refused';
+                }
+                /**
+                 * ASKED HERE, WITH NOTHING BETWEEN THIS AND THE SPAWN.
+                 *
+                 * A person tapping Start while a question of theirs is still open would
+                 * buy a run that meets the same boundary and files nothing new — the
+                 * request key is derived from the run — so it would spend a Start to
+                 * arrive exactly where it began. And a person tapping Start after an
+                 * answer is the ONE thing that resumes a pursuit, so this is also where
+                 * that answer is picked up.
+                 *
+                 * `undefined` when this daemon cannot ask; the run itself still refuses
+                 * to file anything it cannot get an approval for, so the boundary is
+                 * never crossed silently.
+                 */
+                // M6-9: a goal the coordinator has placed is started where it was placed.
+                const placed = read.start.goalId === undefined ? undefined : workspaceFor?.(read.start.goalId);
+                // M6-14: a goal the coordinator is still placing — its checkout asked
+                // for or made, the placement not yet recorded — is not a goal placed
+                // nowhere. The Start waits for the placement rather than running in
+                // the project checkout; past the bound it is refused, with the reason.
+                if (placed === undefined && read.start.goalId !== undefined && placing?.placing(read.start.goalId) === true) {
+                    const now = placing.now?.() ?? Date.now();
+                    const since = waitingSince.get(command.id) ?? now;
+                    waitingSince.set(command.id, since);
+                    const waitMs = placing.waitMs ?? exports.PLACEMENT_WAIT_MS;
+                    if (now - since < waitMs) {
+                        log(`daemon  : start-run for ${read.start.goalId} waits for the coordinator to place it`);
+                        return 'retry';
+                    }
+                    waitingSince.delete(command.id);
+                    const reason = `the coordinator did not place ${read.start.goalId} within ${Math.round(waitMs / 1000)} s — ` +
+                        'try again, or turn the coordinator off to start it here';
+                    log(`daemon  : start-run refused — ${reason}`);
+                    return { disposition: 'refused', reason };
+                }
+                waitingSince.delete(command.id);
+                if (placed !== undefined) {
+                    log(`daemon  : start-run for ${read.start.goalId} goes to the checkout the coordinator placed it in — ${placed}`);
+                }
+                const decision = approvals === undefined ? {} : await approvals(read.start, command.id, placed);
+                if (decision.refuse) {
+                    log(`daemon  : start-run refused — ${decision.refuse.reason}`);
+                    // Terminal for a definite answer, queued for one nobody obtained. A
+                    // person whose approval is still open taps Start again when they have
+                    // decided; a machine that could not reach the server may reach it on
+                    // the next poll.
+                    return decision.refuse.terminal
+                        ? { disposition: 'refused', reason: decision.refuse.reason }
+                        : 'retry';
+                }
+                // The command IS the request here, and says so. `requestId` is what
+                // every durable record is keyed by; `origin` is what the machine
+                // consults when it needs to know whether a person is actually behind
+                // this Start. For a human command the two carry the same string, which
+                // is exactly what keeps every existing lease, mark and receipt readable.
+                const started = await starter.start({
+                    ...read.start,
+                    requestId: command.id,
+                    origin: { kind: 'human-command', commandId: command.id },
+                    ...(placed === undefined ? {} : { workspace: placed }),
+                    ...(decision.governedApprovalId === undefined
+                        ? {}
+                        : { governedApprovalId: decision.governedApprovalId }),
+                    ...(decision.resumedFromApprovalId === undefined
+                        ? {}
+                        : { resumedFromApprovalId: decision.resumedFromApprovalId }),
+                });
+                if (!started.started) {
+                    // A refusal that retrying cannot fix — something is already working
+                    // here, or we cannot prove otherwise. Left queued it would be offered
+                    // again every three seconds for the whole redelivery window, which is
+                    // noise rather than resilience.
+                    if ('terminal' in started) {
+                        log(`daemon  : start-run refused — ${started.reason}`);
+                        // The run's own words, carried through. This is the line the phase
+                        // exists for: without the reason, "this goal's work is done" and
+                        // "nothing here can move without you" both reached the phone as a
+                        // bare `refused`, which is the same as saying nothing.
+                        return { disposition: 'refused', reason: started.reason };
+                    }
+                    if ('waiting' in started) {
+                        // A child is going and has not proven a Run yet. Left queued on
+                        // purpose: acking here is precisely the lie this phase removed, and
+                        // the launcher will not spawn a second child for the same request.
+                        log(`daemon  : ${started.reason} — waiting for it to prove it before acking.`);
+                        return 'retry';
+                    }
+                    log(`daemon  : start-run failed — ${started.reason}. Leaving it queued.`);
+                    return 'retry';
+                }
+                // Reached only with durable proof that this command's run crossed the
+                // start boundary. The run id comes from that proof, so it names the run
+                // the phone's tap actually produced rather than one we assume.
+                log(`daemon  : run confirmed started${started.runId === undefined ? '' : ` (${started.runId})`}${started.pid === undefined ? '' : ` (pid ${started.pid})`}${read.start.goalId === undefined ? '' : ` for goal ${read.start.goalId}`}${read.start.hours === undefined ? '' : `, ${read.start.hours}h budget`}${started.already ? ' — already in progress here' : ''}.`);
+                return 'done';
+            }
+            case 'release-goal-items': {
+                if (!releaser) {
+                    log('daemon  : release-goal-items is not carried out here — leaving it queued.');
+                    return 'retry';
+                }
+                const named = releaseOf(command.payload);
+                if (named === null) {
+                    // The server builds this payload itself and puts exactly one field in
+                    // it, so an unreadable one is a build that disagrees with the server
+                    // rather than a transient fault. Terminal.
+                    log('daemon  : release-goal-items names a goal this build cannot read — refusing it.');
+                    return 'refused';
+                }
+                const out = await releaser.release(named.goalId, named.goalVersion);
+                if ('busy' in out) {
+                    // Left queued on purpose: the queue file is shared with a live run,
+                    // and this is the one thing that must not race it.
+                    log(`daemon  : ${out.busy}.`);
+                    return 'retry';
+                }
+                log(`daemon  : goal ${named.goalId} let go of ${out.released} item(s)` +
+                    (out.heldByARun ? `, ${out.heldByARun} still being worked on` : '') +
+                    (out.keptAsRecord ? `, ${out.keptAsRecord} finished and kept` : '') +
+                    '.');
+                return 'done';
+            }
+            case 'authorize-goal-autonomy': {
+                // WRITTEN DOWN, AND NOTHING ELSE.
+                //
+                // Not a Start. `start-run` authorizes one run and this authorizes
+                // several, but the acts are separate on purpose: turning a grant into
+                // a Start here would make the grant indistinguishable from the tap
+                // that begins work, and the whole point of a bounded permission is
+                // that the machine decides WHEN to spend it, later, under its own
+                // budget. Nothing in 6D1R spends one; there is no controller yet.
+                if (!autonomy) {
+                    log('daemon  : authorize-goal-autonomy is not carried out here — leaving it queued.');
+                    return 'retry';
+                }
+                const ceiling = startCeiling ?? core_1.MAX_AUTONOMOUS_STARTS;
+                const asked = askedStarts(command.payload);
+                if (asked !== null && asked > ceiling) {
+                    log(`daemon  : the grant asks for ${asked} Start(s) and this machine's programme limit is ${ceiling} — refusing it.`);
+                    return {
+                        disposition: 'refused',
+                        reason: `this machine's programme limit is ${ceiling} Start(s) per grant; the grant asked for ${asked}`,
+                    };
+                }
+                const grant = grantOf(command.payload, ceiling);
+                if (grant === null) {
+                    // The server builds this payload itself, so an unreadable one is a
+                    // build that disagrees with the server rather than a transient
+                    // fault. Terminal, with a reason the phone can show.
+                    log('daemon  : the grant is in a shape this build cannot read — refusing it.');
+                    return {
+                        disposition: 'refused',
+                        reason: 'this machine could not read the terms of that permission',
+                    };
+                }
+                try {
+                    // Idempotent by controllerId. A redelivery of the same grant writes
+                    // nothing at all; a controllerId already held whose TERMS have moved
+                    // is refused rather than adopted, because from 6D1R-B one
+                    // controllerId is one act of permission forever and a second
+                    // authorization arrives as an id this machine has never seen.
+                    await autonomy.adopt(grant);
+                }
+                catch (e) {
+                    // NOT EVERY FAILURE IS AN ANSWER. A refusal is durable and the person
+                    // has to notice it and authorize again; a locked file is neither
+                    // their fault nor a lasting fact. Adopt is idempotent by
+                    // controllerId, so leaving it queued costs nothing and the redelivery
+                    // writes nothing if the first one did land.
+                    if (e.transient === true) {
+                        log('daemon  : the grant could not be recorded just now — leaving it queued.');
+                        return 'retry';
+                    }
+                    log(`daemon  : the grant could not be recorded — refusing it.`);
+                    return { disposition: 'refused', reason: e.message };
+                }
+                log(`daemon  : autonomy recorded for goal ${grant.goalId} at version ` +
+                    `${grant.goalVersion} — up to ${grant.maxStarts} Start(s), until ${grant.expiresAt}. ` +
+                    'Nothing is started by this.');
+                return 'done';
+            }
+            case 'pause':
+            case 'resume':
+            case 'stop': {
+                if (!control) {
+                    log(`daemon  : ${command.kind} is not carried out here — leaving it queued.`);
+                    return 'retry';
+                }
+                // The run is a separate, detached process (see run-launcher.ts), so the
+                // request goes on disk and the runner picks it up between rounds. It is
+                // written even when no run is in progress: the phone's intent outlives
+                // the moment, and a pause that only lands if a round happens to be
+                // running is a pause you cannot trust.
+                await control.request(command.kind, command.actor);
+                log(command.kind === 'pause'
+                    ? 'daemon  : pause written — the current round finishes, then the run holds.'
+                    : command.kind === 'resume'
+                        ? 'daemon  : resume written — a holding run picks up its next round.'
+                        : 'daemon  : stop written — the run ends after the current round.');
+                return 'done';
+            }
+            case 'scan': {
+                if (!starter?.scan) {
+                    log('daemon  : scan is not carried out here — leaving it queued.');
+                    return 'retry';
+                }
+                const scan = await starter.scan();
+                if (!scan.started) {
+                    log(`daemon  : scan failed — ${scan.reason}. Leaving it queued.`);
+                    return 'retry';
+                }
+                log(scan.already
+                    ? 'daemon  : scan received, but a scan is already running here.'
+                    : `daemon  : scan started${scan.pid === undefined ? '' : ` (pid ${scan.pid})`} — its passes stream to your phone as they finish.`);
+                return 'done';
+            }
+            // The three verbs this build does not implement. `refused` rather than
+            // `retry`, and the distinction is now load-bearing: commands are really
+            // redelivered until they reach a terminal state, so leaving these unacked
+            // would have the server offer them again every three seconds for the life
+            // of the machine. Refusing ends them, and says why.
+            case 'skip':
+                log(`daemon  : skip is not carried out by this version — refusing it: ${exports.SKIP_REFUSED_REASON}.`);
+                return { disposition: 'refused', reason: exports.SKIP_REFUSED_REASON };
+            case 'approve':
+            case 'undo': {
+                // M6-17: the reason on the wire, not only in this log.
+                const reason = reviewRefusedReason(command.kind);
+                log(`daemon  : ${command.kind} is not carried out by this version — refusing it: ${reason}.`);
+                return { disposition: 'refused', reason };
+            }
+            default:
+                // A newer phone talking to an older daemon. Refused rather than left
+                // queued: the tap will be stale long before anyone upgrades the CLI,
+                // and an instruction nothing here can dispatch is better ended with a
+                // reason than offered forever.
+                log(`daemon  : unrecognised command ${String(command.kind)} — refusing it.`);
+                return 'refused';
+        }
+    }
+}
+async function daemonCommand(opts) {
+    const store = new machine_store_1.MachineStore((0, machine_store_1.machineFilePath)());
+    const identity = store.load();
+    if (!identity) {
+        opts.log('daemon  : this machine has not paired. Run `looply pair` first.');
+        return 1;
+    }
+    const client = new server_client_1.ServerClient({ baseUrl: identity.serverUrl }).withToken(identity.token);
+    let projectId;
+    try {
+        const resolved = await resolveProjectIdWithConsent(store, client, identity.machineId, opts.cwd, opts.config.project.name, opts.gate ?? {});
+        if (resolved.kind === 'refused') {
+            opts.log(resolved.reason === 'declined'
+                ? 'daemon  : nothing registered, nothing started. Run it inside the project you meant.'
+                : 'daemon  : this directory is not a registered project and there is no terminal to ask on. `looply daemon --yes` registers it.');
+            return 1;
+        }
+        projectId = resolved.projectId;
+    }
+    catch (e) {
+        if (e instanceof server_client_1.ServerError && e.isAuth) {
+            opts.log('daemon  : this machine\'s access was revoked. Run `looply pair` again.');
+            return 1;
+        }
+        if (e instanceof server_client_1.ServerError && e.isOffline) {
+            // Registration is the one thing that genuinely needs the server, so this
+            // is a refusal rather than a degraded start — a daemon with no project id
+            // has nothing to attach its events to.
+            opts.log(`daemon  : cannot reach ${identity.serverUrl} to register this project.`);
+            return 1;
+        }
+        throw e;
+    }
+    opts.log(`machine : ${identity.machineId}`);
+    opts.log(`project : ${projectId}`);
+    opts.log(`server  : ${identity.serverUrl}`);
+    opts.log(`mode    : ${(0, programme_mode_1.describeProgramme)(opts.config)}`);
+    /**
+     * 🔴 BOTH CALLBACKS, BECAUSE NEITHER WAS EVER WIRED HERE.
+     *
+     * The RUN wires both correctly and says what it is doing. The daemon
+     * constructed its watcher with neither, so a first Ctrl-C printed NOTHING —
+     * a person saw a daemon that appeared to ignore them, pressed again, saw
+     * nothing again, and needed a third press with no explanation for any of it.
+     *
+     * ⚠️ AND THE FIRST PRESS IS STILL GRACEFUL. The daemon holds delivery state
+     * — cursors, receipts, the outbound buffer — and killing it mid-flush loses
+     * the tail of a night's ledger. The distinction between the two presses is
+     * the whole reason to say anything at all.
+     */
+    const signals = new signals_1.SignalWatcher({
+        proc: (0, signals_1.nodeSignalSource)(),
+        onGraceful: () => {
+            opts.log('');
+            opts.log('daemon  : stopping after this tick. Press Ctrl-C again to stop now.');
+        },
+        onForce: () => {
+            opts.log('daemon  : stopping now — anything not yet shipped stays on disk for the next start.');
+        },
+    });
+    signals.install();
+    const receipts = new command_receipts_1.CommandReceipts((0, node_path_1.join)(opts.cwd, git_driver_1.STATE_DIR, 'state'), ledger_store_1.nodeLedgerFs);
+    if ((await receipts.open()) === 'unreadable') {
+        opts.log('daemon  : .looply/state/commands.json is unreadable — commands that');
+        opts.log('          spawn work will be refused until it is deleted.');
+    }
+    // The standing daemon is the one process that owns delivery state. Its
+    // usage line has always said it ships the ledger and until now nothing fed
+    // it: no producer was wired, so it flushed an empty buffer forever while a
+    // crashed run's tail sat on disk with nothing that would ever look at it.
+    const cursors = new cursor_store_1.CursorStore((0, node_path_1.join)(opts.cwd, git_driver_1.STATE_DIR, 'state'), ledger_store_1.nodeLedgerFs);
+    if ((await cursors.open()) === 'unreadable') {
+        opts.log('daemon  : .looply/state/cursor.json is unreadable — replaying from the start.');
+        opts.log('          Duplicates are discarded by the server, so this is safe, only slower.');
+    }
+    // What a previous run left behind, settled before the loop starts.
+    //
+    // After `projectId` is resolved and before the daemon runs, and both halves
+    // of that are load-bearing rather than tidy. After, because a recovery event
+    // stamped with anything but the id the server registered is dropped by ingest
+    // on arrival — the exact defect `run-identity.spec.ts` guards. Before, so the
+    // first replay pass ships what this appends, rather than it waiting a tick.
+    //
+    // The append goes through the ledger rather than straight into the daemon's
+    // buffer on purpose: it is what rewrites `status.json`, so `looply status`
+    // locally stops reading `live`, and it survives a daemon that dies before it
+    // ever flushes. An `enqueue` would do neither.
+    /**
+     * Built once and called BOTH at startup and on the loop's sweep.
+     *
+     * Startup alone was enough while nothing waited on a run: if the last run had
+     * been killed, the next daemon start tidied up. It stops being enough the
+     * moment something waits for `run.ended` — a SIGKILLed run never writes one,
+     * so on a daemon that stays up for a week that run stays un-ended for a week,
+     * and whatever is waiting waits for ever.
+     *
+     * Idempotent by contract: it answers `idle` when there is no lease, when the
+     * run is live, or when the ending is already written.
+     */
+    /**
+     * 🔴 EVERY CHECKOUT THIS PROJECT EXECUTES IN, NOT ONLY THIS ONE. The sweep
+     * was built over `join(opts.cwd, STATE_DIR, 'state')` alone, so a run the
+     * coordinator placed in a linked worktree was never given its ending when it
+     * died — see `stale-run-sweep.ts`. The same factory drives the end-to-end
+     * proof, so what is proven is what runs here.
+     */
+    const sweep = (0, stale_run_sweep_1.makeStaleRunSweep)({ cwd: opts.cwd, projectId, log: opts.log });
+    /**
+     * M6-5 — THE FOLLOW-UP ON A RUN THAT IGNORES ITS STOP (STATE §5 item 16).
+     *
+     * Same cadence as the sweep, after it: the sweep closes runs that died, this
+     * names runs that were asked to stop and began a round anyway — once, in the
+     * log and as ONE `alert` on the run's own ledger, which ships to the phone
+     * on the next flush. It never ends a run; that stays a person's act.
+     */
+    const followUpOnStops = (0, stop_follow_up_1.nodeStopFollowUp)({ projectState: (0, git_driver_1.projectStateDir)(opts.cwd), projectId, log: opts.log });
+    const recoverStaleRun = async () => {
+        await sweep();
+        await followUpOnStops();
+    };
+    await recoverStaleRun();
+    // The server's goals, mirrored locally. Loaded before the loop so a daemon
+    // that starts offline still has whatever the last one saw, rather than an
+    // empty mirror it cannot distinguish from "this project has no goals".
+    //
+    // Read-only, and read by nothing yet: this phase writes the file and stops
+    // there. A goal is not consulted to decide what work to do until a later one.
+    const goals = new goal_store_1.GoalStore((0, git_driver_1.projectStateDir)(opts.cwd), ledger_store_1.nodeLedgerFs, opts.log);
+    await goals.load();
+    // ───────────────────────────────────────────────────────────────────────────
+    // THE AUTONOMY GRAPH, BUILT ONCE.
+    //
+    // Every authority the controller consults is the real one: the grant store,
+    // the attempt claims, the durable start and refusal marks, the ledger's
+    // run-ended reader, and the machine-authenticated server. Nothing here is a
+    // stub and nothing defaults to "authorized" — a controller that could not
+    // reach the server must not be able to spend a person's Start on the strength
+    // of a fallback.
+    /**
+     * 🔴 THE AUTHORITY'S WRITER AND ITS READERS DISAGREED ABOUT WHERE IT IS.
+     *
+     * This was `join(opts.cwd, STATE_DIR, 'state')` — a path built from the
+     * literal working directory — while `bin.ts`, the run and the control store
+     * all use `projectStateDir`, which resolves the REPOSITORY. The two agree
+     * only when the daemon is started from the repository root of a main
+     * worktree, which is why every measurement of it agreed.
+     *
+     * Start the daemon from `packages/cli`, or from a linked worktree, and the
+     * grants, the attempt claims and the start marks are written somewhere no
+     * reader looks: a controller re-spends a Start it already spent, and the run
+     * that did happen is invisible to the daemon that launched it.
+     */
+    const stateDir = (0, git_driver_1.projectStateDir)(opts.cwd);
+    const readRunEnded_ = (0, run_ending_locator_1.makeRunEndedReader)({ cwd: opts.cwd });
+    // ONE control file, read by the autonomy tick and written by the command
+    // handler. The same path `looply run` reads: the daemon, the run and the
+    // controller are three processes over one repo, and this file is all they
+    // share about whether a person has asked the machine to hold.
+    // PROJECT-SCOPED: see `projectStateDir`. The run reads the same path.
+    // PROJECT-SCOPED: see `projectStateDir`. The run reads the same path.
+    const projectState = (0, git_driver_1.projectStateDir)(opts.cwd);
+    const controlFile = new control_file_1.ControlStore(projectState, ledger_store_1.nodeLedgerFs);
+    /**
+     * 🔴 THE PHONE'S BRAKE REACHED ONE RUN IN N, and this is the path that matters
+     * most — nobody is standing at the terminal to notice that two of three runs
+     * kept going.
+     *
+     * Writing one shared `control.json` is not enough once there are several
+     * executions: the FIRST to reach a round boundary consumes it by writing
+     * `resume` over it, and every other one then reads `resume` and carries on.
+     * `looply stop` had already been taught to write an addressed request per live
+     * execution; this had not, and had a different code path besides.
+     *
+     * ⚠️ WRITING ONLY. Reading stays on `controlFile` above, because the autonomy
+     * tick asks a different question — "has a person asked this machine to hold" —
+     * of the one file that answers for the project.
+     */
+    const controlWriter = {
+        request: async (kind, actor) => {
+            const live = new workspace_1.RunRegistry(projectState).active();
+            const out = await (0, workspace_1.requestControlEverywhere)(projectState, live, kind, actor ?? 'phone', ledger_store_1.nodeLedgerFs, opts.cwd);
+            /**
+             * ⚠️ AND SAY WHICH RUNS IT MISSED. The reach report was discarded, so a
+             * `stop` that could not be written into one execution's state directory
+             * looked exactly like one that reached them all — on the path where
+             * nobody is at a terminal to notice.
+             */
+            if (out.unreachable.length > 0) {
+                opts.log(`daemon  : could not reach ${out.unreachable.join(', ')} — their state could not be written.`);
+            }
+            return { kind, requestedAt: new Date().toISOString(), ...(actor === undefined ? {} : { actor }) };
+        },
+    };
+    // Advances once per autonomy cadence so the scan does not always begin at
+    // the same grant. Fairness only: it decides who is ASKED first, never what
+    // the answer is.
+    //
+    // SEEDED, not zero. The scan looks at a bounded window, and a window that
+    // always opened at the same place would leave a machine holding more grants
+    // than the window is wide with a far controller it never reached — one
+    // starvation traded for another. Advancing solves that for a daemon that
+    // stays up; seeding solves it for one that does not, because two runs of a
+    // crash-looping daemon then open on different grants instead of the same one
+    // for ever.
+    //
+    // The clock is a fine source here precisely because this decides nothing:
+    // correctness does not depend on the order, only on every grant eventually
+    // getting a turn.
+    let autonomyTurn = Date.now();
+    // The same, for which accepted dependency edge a cadence raises first (`fileReviewed`).
+    let edgeTurn = Date.now();
+    const autonomyStore = new autonomy_store_1.AutonomyStore(stateDir, autonomy_store_1.nodeAutonomyFs);
+    const attempts = new start_attempts_1.StartAttempts(stateDir, start_attempts_1.nodeAttemptFs);
+    /**
+     * 🔴 PROJECT-SCOPED, BECAUSE THE RUN THAT WRITES THEM MAY BE IN ANOTHER
+     * CHECKOUT — AND THE CONTROLLER READS THESE, not the launcher's copy.
+     *
+     * `startMarkOf` is what `autonomy-controller` uses to decide whether a Start
+     * BEGAN. Reading it from the daemon's own execution state meant a
+     * coordinator-placed run's mark was never found, so three cadences later
+     * every placed goal was escalated with
+     *
+     *     Start 1 was attempted 3 times and never began
+     *
+     * while its runs had started, worked and finished perfectly. The launcher's
+     * `provenStart` had the identical bug and was fixed with it; both readers
+     * have to agree with the writer, and the writer is a run that may be
+     * anywhere in this project.
+     */
+    const marksDir = (0, git_driver_1.projectStateDir)(opts.cwd);
+    const startMarks = new run_start_marks_1.RunStartMarks(marksDir, ledger_store_1.nodeLedgerFs);
+    const refusalMarks = new run_refusal_marks_1.RunRefusalMarks(marksDir, ledger_store_1.nodeLedgerFs);
+    // Which of a person's answers have already been handed to a run. Read by the
+    // approval gate below and written at the Start boundary, by exclusive create,
+    // so two daemons over one project cannot both give out the same answer.
+    const resumes = new approval_resumes_1.ApprovalResumes(stateDir, start_attempts_1.nodeAttemptFs);
+    // Which approved action each Start took responsibility for. Written here, at
+    // the Start boundary, and read by the run to derive the claim key it must
+    // present — including after a crash, which is why it is durable at all.
+    const governed = new governed_approvals_1.GovernedApprovals(stateDir, start_attempts_1.nodeAttemptFs);
+    /**
+     * The safety history. Constructed once; RE-OPENED on every consultation.
+     *
+     * The observations are written by the RUN process, so a snapshot taken at
+     * startup is a fact about a moment that has passed — the same reason the
+     * approval gate is read from the server every tick rather than from anything
+     * this machine wrote down.
+     */
+    // MACHINE-SCOPED, and it must be the SAME directory the run raises into,
+    // or every hold this gate reads is one no run ever wrote. Both go through
+    // `railsSafetyStore`, which is what keeps that true by construction.
+    /**
+     * THE COORDINATOR LOCK, ONCE IT HAS BEEN TAKEN.
+     *
+     * 🔴 IT WAS TAKEN ONCE AND NEVER LOOKED AT AGAIN. The daemon claimed it
+     * before `run()` and nothing consulted it afterwards, so if the file was
+     * removed — a person tidying `.looply`, a disk that filled and was cleared,
+     * a second daemon sweeping what it judged litter — this daemon carried on
+     * scheduling with no lock at all, for the rest of its life, silently. The
+     * whole point of the lock is that exactly one coordinator schedules.
+     *
+     * Null until it is held, so a tick before the claim schedules nothing.
+     */
+    let coordinatorLock = null;
+    /**
+     * WHERE THE COORDINATOR PLACED EACH GOAL THIS CADENCE, and how many starts it
+     * decided were free. Both are filled by `prefer` and read by the two deps
+     * below it, within one tick.
+     *
+     * ⚠️ PROCESS-LOCAL AND DELIBERATELY NOT DURABLE. They describe ONE cadence's
+     * decision; a restarted daemon recomputes from the registry and the leases,
+     * which are the durable facts. Anything that outlived the cadence would be a
+     * second opinion about capacity, and the registry is the first.
+     */
+    const placement = new Map();
+    /** F28 (corr-3): each goal's controller's last decision, for the next cadence's scheduler. */
+    const lastDecision = new Map();
+    let freeCapacity = 1;
+    /**
+     * M4-1 — THE MACHINE MAKES ITS OWN CHECKOUT, when the project asked.
+     *
+     * `machine.provision_workspaces` is off by default; then `provisioner` is
+     * null and the gatherer tells the scheduler so, and a `provision` action
+     * cannot even be emitted — every wait is the one it always was. On, the tick
+     * may ask for ONE checkout per cadence; it is made after the tick returns
+     * (the tick is synchronous by contract), with the same code a person uses,
+     * and the next cadence finds it idle and places the goal.
+     */
+    const provisioner = opts.config.machine?.provisionWorkspaces === true ? (0, workspace_provisioner_1.nodeWorkspaceProvisioner)(opts.cwd) : null;
+    let toProvision = null;
+    /**
+     * M6-14: THE GOAL A CHECKOUT IS BEING MADE FOR, and the checkouts made but
+     * not yet placed. `provisioningFor` is set beside `toProvision` for the
+     * cadence the tick asks; `provisionedFor` holds a goal from the moment its
+     * checkout exists until the tick places it (or a minute passes). Between the
+     * two the placement map is empty for that goal, and that is the window a
+     * person's Start fell into (M6-13).
+     */
+    let provisioningFor = null;
+    const provisionedFor = new Map();
+    /**
+     * M6-22: IS THIS MACHINE PURSUING THIS GOAL?
+     *
+     * Asked of the live grants — the same records the coordinator's own gatherer
+     * reads — and only while the coordinator is on, because with it off nothing
+     * places anything and a person's Start belongs in the project checkout, as it
+     * always did. `authorized` is the one state that means "the machine may spend
+     * Starts against this", and an expired grant is not live however it is
+     * labelled.
+     *
+     * ⚠️ IT ANSWERS "IS IT BEING PLACED", NOT "WHERE". The placement itself is
+     * still `workspaceFor`'s to answer, freshly, every poll; this only decides
+     * whether a Start waits for that answer or goes without one.
+     */
+    const pursuing = (goalId) => {
+        if (opts.config.machine?.coordinator !== true)
+            return false;
+        const now = Date.now();
+        return autonomyStore
+            .all()
+            .some((g) => g.goalId === goalId && g.state === 'authorized' && Date.parse(g.expiresAt) > now);
+    };
+    /**
+     * M4-2 — THE MACHINE ASKS ONE OF ITS OWN RUNS TO STOP, when the project asked.
+     *
+     * `machine.preemption` is off by default; then `preemptor` is null and a
+     * `preempt` decision stays a line in `schedule.jsonl` that nothing acts on,
+     * as it always was. On, the first preempt of a tick is answered after the
+     * tick with the run's own graceful `stop` request — the one `looply stop`
+     * writes — never a kill; only a run the machine started can be named,
+     * because the gatherer reports a person's as not preemptible.
+     */
+    const preemptor = opts.config.machine?.preemption === true ? (0, preemptor_1.nodePreemptor)(projectState, ledger_store_1.nodeLedgerFs) : null;
+    let toPreempt = null;
+    /**
+     * M4-4 — THE MACHINE RETIRES WHAT IT MADE, when the project asked.
+     *
+     * `machine.reap_provisioned` is off by default; then `reaper` is null and
+     * nothing is inspected or removed. On, after the tick and after any stop
+     * request, at most ONE checkout per cadence that the machine itself made,
+     * idle beyond `idle_checkout_minutes`, referenced by no run and holding no
+     * residue, is retired through the manual command's own reaping. A checkout
+     * a person cut is never touched.
+     */
+    const reaper = opts.config.machine?.reapProvisioned === true
+        ? (0, reaper_1.nodeReaper)(opts.cwd, projectState, { idleMinutes: opts.config.machine?.idleCheckoutMinutes ?? 60, log: opts.log })
+        : null;
+    /** M4-4: what the tick placed last cadence — a launch is not an arrival, and the reaper must not race it. */
+    let placedBefore = [];
+    /**
+     * M5-1 — THE MACHINE OFFERS A FINISHED RUN'S BRANCH TO THE LANE, when the project asked.
+     *
+     * `machine.integrate` is off by default; then `integrator` is null and
+     * nothing is listed or offered. On — and only with the lane's own gate,
+     * `run.integration`, on — one branch per cadence, after the reaper, goes
+     * through the very `integrationTick` the `looply integrate` command calls,
+     * with the command's own deps. A fast-forward or a refusal is the lane's
+     * decision, on record either way.
+     */
+    /**
+     * RULE #2's READER FOR THE LANE (F18): the goal as the server holds it at the
+     * moment a candidate is judged, so the lane can regenerate the integrated
+     * receipt (`laneGoalReader`).
+     *
+     * ⚠️ PROGRAMME MODE ONLY. Absent `currency` is the lane's whole simple-mode
+     * guarantee — no receipt computed, no attempt field written — and a simple
+     * project keeps it.
+     */
+    const goalNow = 
+    // F31 (soun-1/corr-2): the SAME predicate the worker defers its coverage on — slice 1
+    // (`machine.programme: true`) included — so no goal closes with coverage judged by nobody.
+    !(0, programme_mode_1.programmeIsOn)(opts.config) ? undefined : (0, integration_deps_1.laneGoalReader)(() => client.projectGoals(projectId));
+    const integrator = opts.config.machine?.integrate === true ? (0, integrator_1.nodeIntegrator)(opts.cwd, projectState, opts.config, opts.log, goalNow) : null;
+    /**
+     * M5-2: publication as the THIRD KEY. Asked only when this daemon integrates
+     * for itself AND the lane is on — a hold on a lane nobody runs would never
+     * lift. Otherwise the tick is handed nothing, and a met goal closes its grant
+     * exactly as it did before this existed.
+     */
+    /**
+     * ⚠️ IN PROGRAMME MODE THE THIRD KEY ALSO CARRIES STRICT COVERAGE, judged on the
+     * integration tip (F25, `withLaneCoverage`). The worker defers its fourth key to it.
+     */
+    const thirdKey = integrator !== null && opts.config.run.integration === true
+        ? goalNow === undefined
+            ? (0, completion_1.nodePublication)(opts.cwd)
+            : (0, lane_coverage_1.withLaneCoverage)(
+            // F27: a programme's Starts judge the tree the lane holds, so a hold a Start can move buys one.
+            (0, completion_1.nodePublication)(opts.cwd, { rejudge: true }), (0, lane_coverage_1.nodeLaneCoverageDeps)(opts.cwd, new git_driver_1.GitDriver((0, git_driver_1.nodeGitExec)(opts.cwd)), client, projectId, goalNow))
+        : null;
+    const safety = (0, rails_stores_1.railsSafetyStore)(opts.cwd);
+    if ((await safety.open()) === 'unreadable') {
+        opts.log('daemon  : the loop-safety history could not be read — autonomy will hold');
+    }
+    /**
+     * WHETHER A PERSON'S START MAY PROCEED, ASKED OF THE SERVER.
+     *
+     * The same derivation the controller holds on, at the other boundary. One
+     * reading answers both halves: whether to turn this Start away, and which
+     * answer — if any — it has just been given the right to carry.
+     *
+     * A START WITH NO PURSUIT IS NOT GATED. An approval belongs to a goal at a
+     * version, so a run that names none can have nothing outstanding; asking
+     * would be a request that could only ever come back empty.
+     *
+     * THE CLAIM IS TAKEN HERE, before the run exists, because that is where two
+     * Starts race. Losing it is not a refusal: the other Start has the answer and
+     * is about to hold the working tree, so this one carries on as an ordinary
+     * Start and meets the lease like any other.
+     */
+    /**
+     * THE DECISION LIVES IN `explicit-start-gate.ts`, and this is the wiring.
+     *
+     * It was a closure here, over these same five values, which meant it had no
+     * export and no test seam — and that is a large part of why it could hand an
+     * approval id to `approved` only, while `refusesExplicitStart` admitted three
+     * more kinds so that something could go and look. Nothing looked, and the
+     * pursuit wedged. Injecting the collaborators costs nothing and makes the
+     * wiring answerable to a spec.
+     */
+    const explicitStartGate = async (start, requestId, workspace) => {
+        // The pursuit is resolved HERE and nowhere further in. `decideExplicitStart`
+        // takes a gate rather than a way to read one, because the decision does not
+        // need to know what a goal is — and `goal-wiring.spec.ts` enforces exactly
+        // that confinement across the whole tree.
+        if (start.goalId === undefined || start.goalVersion === undefined)
+            return {};
+        /**
+         * A PERSON'S EXPLICIT START IS THE ESCAPE HATCH FROM A SAFETY HOLD, and it
+         * is spent HERE — before a run exists, in the same place the governed
+         * reservation is taken, because this is where two Starts race.
+         *
+         * ⚠️ IT IS ONE RETRY, NOT "SAFETY OFF". The incident is marked spent and the
+         * observation history is left exactly where it is, so a Run that also
+         * achieves nothing raises a NEW incident. That is the difference between a
+         * person saying "try once more" and a person disabling a brake, and there
+         * is deliberately no flag anywhere that does the second.
+         *
+         * The refusal is RETRYABLE rather than terminal: losing this race means
+         * another Start took the retry, and that Start may yet fail to produce a
+         * run.
+         */
+        if ((await safety.open()) === 'ok') {
+            const incident = safety.activeIncident(start.goalId, start.goalVersion);
+            if (incident !== null) {
+                const spent = await safety.override(incident.id, requestId);
+                if (!spent.ok)
+                    return { refuse: { reason: spent.because, terminal: false } };
+                opts.log(`daemon  : a person is trying again after ${incident.kind} (${incident.id})`);
+            }
+        }
+        const gate = await (0, approval_gate_read_1.readApprovalGate)(client, {
+            projectId,
+            goalId: start.goalId,
+            goalVersion: start.goalVersion,
+            now: Date.now(),
+            consumed: (ids) => resumes.consumed(ids),
+        });
+        return await (0, explicit_start_gate_1.decideExplicitStart)({
+            governed,
+            resumes,
+            // The SAME durable lease the startup recovery gates on, not a second
+            // notion of liveness. `RunLauncher.isRunning()` would not do: it knows
+            // only about children THIS daemon spawned, so a run left by a previous
+            // one would read as nobody.
+            // M6-9: the placed checkout's lease when the goal was placed, the project's otherwise.
+            carrier: () => new run_lease_1.RunLeaseStore((0, node_path_1.join)(workspace ?? opts.cwd, git_driver_1.STATE_DIR, 'state'), run_lease_1.nodeLeaseFs).inspect(),
+            log: opts.log,
+        }, gate, requestId);
+    };
+    const runStarter = (0, run_launcher_1.nodeRunLauncher)(opts.cwd, stateDir);
+    /**
+     * The brain's tools, built only when the project switched it on (M3-1).
+     * Off — the default — costs nothing: no store opened, no transport built.
+     */
+    const brain = opts.config.run.brain === true ? await (0, brain_advice_1.brainDepsFor)(opts.cwd, opts.config, opts.log) : null;
+    const daemon = new daemon_1.Daemon({
+        client,
+        machineId: identity.machineId,
+        projectId,
+        cliVersion: exports.CLI_VERSION,
+        cursors,
+        goals,
+        recoverStaleRun,
+        /**
+         * One controller transition per cadence.
+         *
+         * The tick itself is bounded: it reads durable facts, asks the server once,
+         * and at most launches ONE detached child before returning. It does not
+         * wait for a run — that would hold the heartbeat for hours.
+         */
+        autonomyTick: async () => {
+            /**
+             * 🔴 THE HEARTBEAT BELONGS TO THE CADENCE, NOT TO THE SCHEDULER —
+             * AND IT WAS REACHABLE ONLY THROUGH A BRANCH THAT IS OFF BY DEFAULT.
+             *
+             * `refresh()` had exactly one call site in the tree: inside `prefer()`,
+             * AFTER `if (coordinator !== true) return []`. Every daemon takes the
+             * lock; only a coordinator daemon ever said it was still there. MEASURED:
+             * a default daemon holds its claim, never refreshes it, and ten minutes
+             * later `heartbeatStale` judges it dead — so a second `looply daemon`
+             * over the same repository takes the lock and both run, which is the one
+             * outcome this lock exists to prevent.
+             *
+             * ⚠️ AND LOSING IT STOPS THE TICK, NOT ONLY THE ORDERING. The hazard is
+             * two processes spending the same Start; refusing to schedule while
+             * continuing to launch would not address it. A daemon that no longer
+             * holds its claim does nothing autonomous until it is restarted.
+             */
+            if (coordinatorLock !== null && !coordinatorLock.refresh()) {
+                opts.log('daemon  : this daemon no longer holds this repository’s lock — not acting autonomously.');
+                placement.clear();
+                freeCapacity = 1;
+                return;
+            }
+            const gatherState = () => (0, coordinator_state_1.gatherScheduleState)(opts.cwd, {
+                goals,
+                autonomy: autonomyStore,
+                registry: new workspace_1.RunRegistry(projectState),
+                safety,
+                /**
+                 * 🔴 THE MINIMUM OF EVERY CEILING, NOT THE COORDINATOR'S OWN.
+                 *
+                 * MEASURED by the end-to-end proof: with `max_workspaces: 2` the
+                 * scheduler correctly placed two goals in two checkouts and
+                 * exactly ONE run ever registered, because
+                 * `run.max_concurrent_runs` defaults to 1 and the second was
+                 * refused by the slot bound AFTER a workspace was cut, a goal
+                 * placed and a process spawned. Planning past a ceiling somebody
+                 * else enforces wastes exactly that much work every cadence.
+                 */
+                capacity: {
+                    maxWorkspaces: (0, core_2.effectiveConcurrency)({
+                        workspaces: opts.config.machine?.maxWorkspaces,
+                        runs: opts.config.run.maxConcurrentRuns,
+                    }),
+                    maxAgentsInFlight: (0, core_2.effectiveConcurrency)({
+                        agents: opts.config.machine?.maxAgentsInFlight,
+                        runs: opts.config.run.maxConcurrentRuns,
+                    }),
+                    provision: provisioner !== null,
+                },
+                /**
+                 * 🔴 WHETHER THIS PROGRAMME INTEGRATES, AND THEREFORE WHETHER
+                 * FINISHING LOCALLY IS FINISHING.
+                 *
+                 * Both halves, the same pair `describeProgramme` reports as off:
+                 * the machine must run the integrator AND the run must be allowed to
+                 * integrate. With either off there is no lane, nothing is ever
+                 * published, and reading "not integrated" as "not satisfied" would
+                 * stop every dependent for ever.
+                 */
+                integrates: opts.config.machine?.integrate === true && opts.config.run.integration === true,
+                // F28 (corr-3): a grant whose controller is only waiting or holding takes no slot.
+                held: new Set([...lastDecision].filter(([, kind]) => kind === 'wait' || kind === 'hold').map(([goalId]) => goalId)),
+                // F34: in a programme whose brain proposes dependencies, a goal waits for its answer —
+                // F36: an answer that STANDS (accepted); a refused one filed no edge, so it is not advice —
+                // F36c: until the version has had its bounded number of answers (`advisedVersions`).
+                ...(brain !== null && (0, programme_mode_1.programmeIsOn)(opts.config) && opts.config.machine?.coordinator === true
+                    ? { advised: (0, ask_brain_1.advisedVersions)(brain.store.all()) }
+                    : {}),
+                now: () => Date.now(),
+            });
+            /**
+             * M3-1 — THE BRAIN'S ADVICE FOR THIS CADENCE, ASKED BEFORE THE TICK.
+             *
+             * `run.brain` is off by default, and then `brain` is null and nothing
+             * here runs: the coordinator receives no proposals, exactly as before.
+             * On, every live authorised goal the mirror holds is asked about at most
+             * once per (goal, version, tree, prompt digest) — the record on disk
+             * answers a repeat — and at most ONE new question is put per cadence, so
+             * the heartbeat waits for one model call, never for a fleet of them.
+             * What comes back is advice: `decideSchedule` writes it into a start's
+             * `because` and starts nothing it would not have started without it.
+             * Asked BEFORE the tick because `prefer` is synchronous by contract and
+             * a model is not.
+             */
+            let advice;
+            /**
+             * 🔴 PROPOSED EDGES ARE CARRIED, NOT APPLIED. `dependsVerdict` is the
+             * fence and it needs facts this cadence does not assemble — goal
+             * versions, source versions, the graph. Holding them here rather than
+             * dropping them is the difference between a suggestion that goes nowhere
+             * and one that has somewhere to go next; applying one from a daemon tick
+             * would be a provider's suggestion reaching the graph without passing a
+             * person, which is what the fence and the approval path exist to prevent.
+             */
+            let proposedEdges = [];
+            if (brain !== null && opts.config.machine?.coordinator === true && coordinatorLock !== null) {
+                try {
+                    const head = await (0, index_for_head_1.indexForHead)(opts.cwd);
+                    if (!head.ok) {
+                        opts.log(`brain   : not asked this cadence — ${head.because}`);
+                    }
+                    else {
+                        const tick = await (0, ask_brain_1.proposalsForTick)(gatherState().goals, {
+                            projectId,
+                            treeSha: head.treeSha,
+                            facts: (0, project_index_facts_1.factsFromIndex)(head.snapshot, (0, project_memory_store_1.projectKeyFor)(opts.cwd, sha256)).map((d) => `${d.subject}: ${d.content}`),
+                            goalFor: (id) => goals.get(id),
+                            packetFor: async (goal) => (await (0, packet_for_goal_1.packetForGoal)(goal, (id) => client.sourceDetail(projectId, id), 
+                            // F19: what the programme's other goals own, so a proposal is made knowing it.
+                            (0, programme_mode_1.programmeIsOn)(opts.config) ? goals.all() : [])).packet,
+                        }, brain, opts.log, undefined, 
+                        // F34: in a programme each goal version is asked once.
+                        (0, programme_mode_1.programmeIsOn)(opts.config));
+                        advice = tick.advice;
+                        proposedEdges = tick.edges;
+                    }
+                }
+                catch (e) {
+                    // The brain is optional; a failure to ask must not take the cadence with it.
+                    opts.log(`brain   : not asked this cadence — ${e.message}`);
+                }
+            }
+            /**
+             * 🔴 EVERY PROPOSED EDGE IS PUT TO THE FENCE, AND NOTHING IS APPLIED.
+             * `reviewEdges` answers `accepted` when every check a machine can make
+             * passes; the edge is still not in the graph and will not be until
+             * somebody puts it there. Writing one from a cadence would be a
+             * provider's suggestion reaching the graph without passing a person.
+             *
+             * ⚠️ THE READS ARE PAID FOR ONLY WHEN THERE IS SOMETHING TO JUDGE.
+             * `reviewEdges` short-circuits on an empty list before it touches either
+             * reader, so a cadence that produced no edges makes no extra server call
+             * — which is why it is safe to hang a network read off a heartbeat.
+             */
+            if (proposedEdges.length > 0) {
+                try {
+                    const review = await (0, depends_review_1.reviewEdges)(proposedEdges, {
+                        projectId,
+                        goals: async () => goals.all().map((g) => ({ id: g.id, version: g.version, dependsOn: g.dependsOn ?? [], projectId: g.projectId })),
+                        sourceShas: async () => new Map((await client.sources(projectId)).sources.map((s) => [s.id, s.sha256])),
+                    });
+                    (0, depends_review_1.reportReview)(review, opts.log);
+                    /**
+                     * 🔴 AND THE ACCEPTED ONES ARE PUT TO A PERSON. This is the two-key
+                     * rule's first key and nothing more: a machine raises the request,
+                     * and a person turns the second. `fileReviewed` files only an
+                     * `accepted` verdict — a stale or refused edge must never reach
+                     * somebody's phone, because asking about those spends the one thing
+                     * this system cannot replace, which is somebody's willingness to read
+                     * the NEXT question carefully.
+                     *
+                     * ⚠️ ONE PER HEARTBEAT, and the rest said out loud. See
+                     * `MAX_EDGE_FILINGS_PER_TICK` for why that bound is not hypothetical.
+                     */
+                    const filing = await (0, depends_review_1.fileReviewed)(review, 
+                    /**
+                     * 🔴 `'system'`, NOT A PERSON AND NOT A RUN ROLE. `Actor` offers
+                     * `runner`, `prover`, `keeper`, `system` and `human:<id>`; a cadence
+                     * is none of the three run roles, and writing a `human:` here would
+                     * be a machine signing somebody's name on the thing they are about
+                     * to be asked to approve.
+                     */
+                    { projectId, requestedBy: 'system' }, { createApproval: (p, input) => client.createApproval(p, input) }, 
+                    // F34: in a programme every accepted edge is filed the cadence it is proposed — a goal must not
+                    // start before the edge that holds it exists, and asking once per version keeps it to one per goal.
+                    (0, programme_mode_1.programmeIsOn)(opts.config) ? Number.MAX_SAFE_INTEGER : depends_review_1.MAX_EDGE_FILINGS_PER_TICK, 
+                    // WHOSE TURN IT IS, so an edge already waiting for a decision
+                    // cannot hold the one filing a cadence allows for ever. Seeded
+                    // and process-local for the reasons `autonomyTurn` is.
+                    (edgeTurn += 1));
+                    (0, depends_review_1.reportFiling)(filing, opts.log);
+                }
+                catch (e) {
+                    /**
+                     * ⚠️ A FAILURE HERE IS NOT A FAILURE OF THE CADENCE. The edges stay
+                     * on record and the next cadence judges them against a newer world,
+                     * which is the right answer for a proposal whose whole verdict
+                     * depends on when it is asked.
+                     */
+                    opts.log(`depends : not judged this cadence — ${e.message}`);
+                }
+            }
+            await (0, autonomy_tick_1.autonomyTick)({
+                // WHOSE TURN IT IS FIRST. Process-local and deliberately not
+                // durable: the ORDER controllers are served in is not a fact about
+                // any of them, so a restarted daemon beginning again costs nothing.
+                // It was never wired at all, which left the scan starting from the
+                // same grant every cadence for the life of the process.
+                rotation: () => (autonomyTurn += 1),
+                /**
+                 * 🔴 AND THIS IS WHERE THE DOLLAR CEILING BECAME REAL. `withinEnvelope`
+                 * shipped fully specced with no production caller, no config key that
+                 * could construct an `Envelope`, and a spend ledger nothing ever read.
+                 * `machine.envelope` produces one; the tick enforces it at the moment
+                 * the machine is about to spend without asking.
+                 *
+                 * ⚠️ ABSENT MEANS NO CEILING, which is what every existing project has.
+                 */
+                ...(opts.config.machine?.envelope === undefined
+                    ? {}
+                    : {
+                        envelope: () => opts.config.machine?.envelope,
+                        estimateUsd: () => opts.config.machine?.envelope?.estimateUsdPerStart,
+                        runsInFlight: () => new workspace_1.RunRegistry(projectState).active().length,
+                    }),
+                /**
+                 * 🔴 AND THIS IS WHERE THE SCHEDULER BECAME REACHABLE.
+                 *
+                 * `decideSchedule` and `coordinatorTick` were written, specced, and
+                 * imported by nothing that ships. Cycles, holds, dependency order and
+                 * the anti-starvation age boost all existed and could not affect one
+                 * overnight decision, while `coordinator.spec.ts` opened by describing
+                 * "the thing wired into the daemon".
+                 *
+                 * ⚠️ OFF UNLESS THE PROJECT ASKS — see `machine.coordinator`. With it
+                 * off this returns nothing and the tick rotates exactly as before.
+                 *
+                 * ⚠️ AND A TICK THAT REFUSES ORDERS NOTHING. `coordinatorTick` refuses
+                 * without the coordinator lock, and a refusal must not be read as "no
+                 * goal is worth doing": returning `[]` falls back to the old order,
+                 * which is a worse order rather than a wrong one.
+                 */
+                prefer: () => {
+                    /**
+                     * ⚠️ THE PLACEMENT IS CLEARED WHENEVER THIS RETURNS NOTHING, and a
+                     * refusal that left it standing was a defect of its own: `prefer`
+                     * returned `[]` while `workspaceFor` went on answering last
+                     * cadence's checkout and `launchesPerTick` last cadence's number, so
+                     * a daemon that had stopped deciding kept acting on a decision it no
+                     * longer stood behind.
+                     */
+                    if (opts.config.machine?.coordinator !== true) {
+                        placement.clear();
+                        provisionedFor.clear();
+                        provisioningFor = null;
+                        freeCapacity = 1;
+                        return [];
+                    }
+                    // The lock is refreshed once per cadence in `autonomyTick` above,
+                    // which reaches a daemon in every mode; by here it is known held.
+                    if (coordinatorLock === null) {
+                        placement.clear();
+                        provisionedFor.clear();
+                        provisioningFor = null;
+                        freeCapacity = 1;
+                        return [];
+                    }
+                    try {
+                        const gathered = gatherState();
+                        // The advice rides on the same input the gatherer built; with the brain off it is the same object.
+                        const input = advice === undefined ? gathered : { ...gathered, proposals: advice };
+                        const tick = (0, coordinator_1.coordinatorTick)(opts.cwd, input);
+                        if (!tick.ok) {
+                            opts.log(`daemon  : the coordinator did not decide — ${tick.because}.`);
+                            placement.clear();
+                            provisionedFor.clear();
+                            provisioningFor = null;
+                            freeCapacity = 1;
+                            return [];
+                        }
+                        /**
+                         * 🔴 ONE DECISION, THREE ANSWERS. The tick needs to know WHO to ask
+                         * first, WHERE each one runs, and HOW MANY it may launch — and all
+                         * three come from the same `decideSchedule` call. Computing them
+                         * separately would let the three disagree within one cadence, which
+                         * is how a goal gets placed in a workspace another goal was just
+                         * given.
+                         */
+                        // M4-1: the checkout this tick asked for, if any — made after the tick. The
+                        // provisioner knows nothing about goals; whom it is for is said here.
+                        const askedFor = tick.actions.find((a) => a.kind === 'provision');
+                        toProvision = askedFor === undefined ? null : { because: `for ${askedFor.goalId} (${askedFor.because})` };
+                        provisioningFor = askedFor === undefined ? null : askedFor.goalId;
+                        // M4-2: the run this tick would stop, if any — asked after the tick. The
+                        // preemptor knows nothing about goals; whose run it is is said here.
+                        const victim = tick.actions.find((a) => a.kind === 'preempt');
+                        toPreempt =
+                            victim === undefined
+                                ? null
+                                : { runId: victim.runId, who: `${victim.runId} (${victim.goalId}, started by the machine)`, because: victim.because };
+                        const starts = tick.actions.filter((a) => a.kind === 'start');
+                        placement.clear();
+                        for (const a of starts) {
+                            placement.set(a.goalId, a.observed.workspace);
+                            provisionedFor.delete(a.goalId);
+                        }
+                        // A checkout made a minute ago for a goal the tick has still not
+                        // placed is not a placement in progress any more (the grant may be
+                        // gone); a Start on that goal is then a goal placed nowhere.
+                        for (const [g, made] of [...provisionedFor]) {
+                            if (Date.now() - made.at > exports.PLACEMENT_WAIT_MS)
+                                provisionedFor.delete(g);
+                        }
+                        freeCapacity = starts.length;
+                        return starts.map((a) => a.goalId);
+                    }
+                    catch (e) {
+                        // A gatherer that throws must not take the night's daemon with it.
+                        opts.log(`daemon  : the coordinator could not read this project — ${e.message}.`);
+                        placement.clear();
+                        provisionedFor.clear();
+                        provisioningFor = null;
+                        freeCapacity = 1;
+                        return [];
+                    }
+                },
+                /**
+                 * 🔴 THE SCHEDULER ALREADY CHOSE A CHECKOUT FOR EVERY START, and
+                 * nothing carried it. `ObservedPremise.workspace` has been on the start
+                 * action since Phase 3; the launcher keyed its live map on the literal
+                 * string `'run'` and peeked the project's own lease, so a second launch
+                 * was refused by the first however many workspaces were idle.
+                 */
+                workspaceFor: (goalId) => placement.get(goalId),
+                onDecision: (goalId, kind) => {
+                    lastDecision.set(goalId, kind);
+                },
+                /**
+                 * 🔴 AND HOW MANY MAY GO AT ONCE. `decideSchedule` already bounds its
+                 * own answer by `maxWorkspaces` and `maxAgentsInFlight` minus what is
+                 * in flight, so the number of `start` actions IS the free capacity. The
+                 * tick used to launch one per cadence whatever it was told, which fills
+                 * N slots in N cadences and calls that a fleet.
+                 */
+                launchesPerTick: () => (opts.config.machine?.coordinator === true ? freeCapacity : 1),
+                autonomy: autonomyStore,
+                attempts,
+                starter: runStarter,
+                // REAL reconciliation. The server is the authority on whether a person
+                // still permits this, and an unreachable server is `unreachable` — a
+                // reason to wait — never `active` and never an ending.
+                reconcile: async (grant) => {
+                    try {
+                        // ONE read, answering both halves: is this grant still authorized,
+                        // and is the wording it was authorized for still the wording.
+                        // Asking separately would act on two answers from two moments, with
+                        // an edit able to land in between.
+                        const { autonomy, goal } = await client.goalAutonomy(projectId, grant.goalId);
+                        const mine = autonomy.find((a) => a.controllerId === grant.controllerId) ?? null;
+                        return (0, grant_reconcile_1.reconcileGrant)(grant, mine, goal, Date.now());
+                    }
+                    catch (e) {
+                        return { kind: 'unreachable', because: e.message };
+                    }
+                },
+                projectTerminal: async (grant, state, because) => {
+                    const settlable = (0, grant_reconcile_1.settlableState)(state);
+                    // Nothing to report. `cancelled` is the case: a person's word, which
+                    // this machine may observe and stop on but may not write.
+                    if (settlable === null)
+                        return { ok: true };
+                    try {
+                        const { autonomy } = await client.goalAutonomy(projectId, grant.goalId);
+                        const mine = autonomy.find((a) => a.controllerId === grant.controllerId);
+                        if (!mine)
+                            return { ok: false, because: 'the server has no record of this grant' };
+                        // L4b: a met goal is settled WITH what key 2 confirmed, when the run wrote it.
+                        let delivery = null;
+                        if (settlable === 'satisfied') {
+                            await refusalMarks.load();
+                            delivery = (0, pursuit_delivery_1.deliveryForPursuit)((id) => refusalMarks.find(id), grant.controllerId);
+                        }
+                        await client.settleGoalAutonomy(projectId, grant.controllerId, {
+                            version: mine.version,
+                            state: settlable,
+                            reason: because,
+                            ...(delivery === null ? {} : { delivery }),
+                        });
+                        return { ok: true };
+                    }
+                    catch (e) {
+                        return { ok: false, because: e.message };
+                    }
+                },
+                // A PERSON'S TAP, read straight off the control file the daemon
+                // already writes when a pause/stop/resume command arrives.
+                //
+                // An unreadable control file reports a STOP rather than nothing. Not
+                // being able to see whether somebody asked the machine to wait is not
+                // the same as nobody having asked, and only one of those two mistakes
+                // costs a person their evening.
+                humanHold: async () => {
+                    // `readOrTrouble`, not `read`. This catch used to be unreachable:
+                    // ControlStore.read swallows the failure and answers null, so an
+                    // unreadable control file read as "nobody asked" and the machine
+                    // carried on — a fail-OPEN default under a comment claiming the
+                    // opposite.
+                    const out = await controlFile.readOrTrouble();
+                    if (!out.ok) {
+                        return { kind: 'stop', actor: 'this machine could not read the control file' };
+                    }
+                    const req = out.request;
+                    if (req === null || req.kind === 'resume')
+                        return null;
+                    return { kind: req.kind, ...(req.actor === undefined ? {} : { actor: req.actor }) };
+                },
+                /**
+                 * 🔴 READ FROM THE RUN'S OWN LEDGER, WHEREVER THE RUN IS. This was
+                 * `readRunEnded(stateDir, …)` — the PROJECT's ledger — and a run the
+                 * coordinator placed in another checkout writes its ending to that
+                 * checkout, so its ordinal never closed. The reader locates the run
+                 * through the registry record and the start mark and validates the
+                 * checkout before reading; an ordinary checkout takes the exact path
+                 * it always did. See `run-ending-locator.ts`.
+                 */
+                // PROGRAMME MODE, slice 1 (M6-7): off by default. On, the controller
+                // continues from an `approved` decision and the Start carries it,
+                // reserved once through the person's own explicit-start decision —
+                // WITHOUT the person-only safety override that sits in front of it
+                // for a tap (a loop-safety hold still holds in the controller).
+                programme: opts.config.machine?.programme === true,
+                continueFrom: (gate, requestId, workspace) => (0, explicit_start_gate_1.decideExplicitStart)({
+                    governed,
+                    resumes,
+                    carrier: () => new run_lease_1.RunLeaseStore((0, node_path_1.join)(workspace ?? opts.cwd, git_driver_1.STATE_DIR, 'state'), run_lease_1.nodeLeaseFs).inspect(),
+                    log: opts.log,
+                }, gate, requestId),
+                runEnded: async (runId) => readRunEnded_(runId),
+                /**
+                 * WHAT THE SERVER SAYS THE PURSUIT IS WAITING FOR.
+                 *
+                 * Deliberately placed AFTER `runEnded`, and not because of ordering in
+                 * the object: `autonomy-wiring.spec.ts` reads the source text between
+                 * `reconcile:` and `runEnded:` to prove the reconciliation callback
+                 * never turns a caught error into an answer. A second callback with its
+                 * own catch inside that slice would fail a guard for a reason that has
+                 * nothing to do with it.
+                 *
+                 * FAILS CLOSED, in the two ways it can. Without a server there is
+                 * nobody to have asked, so a machine that cannot pair reports `unknown`
+                 * rather than `none` — the same choice `humanHold` above makes about an
+                 * unreadable control file, and for the same reason: not being able to
+                 * see whether somebody was asked is not the same as nobody having been.
+                 *
+                 * A CLAIM ALREADY GIVEN OUT IS NOT A BLOCKER, so the resumes are read
+                 * here and folded in. An answer is a message to one run, once; without
+                 * this the first refusal a goal ever received would hold it for the
+                 * rest of its life.
+                 */
+                approvalGate: (grant) => (0, approval_gate_read_1.readApprovalGate)(client, {
+                    projectId,
+                    goalId: grant.goalId,
+                    goalVersion: grant.goalVersion,
+                    now: Date.now(),
+                    // Asked with the ids that came back. `unknown` on trouble, never an
+                    // empty set: a claim that could not be read is not a claim that is
+                    // not there, and reading it as absent hands one answer to two runs.
+                    consumed: (ids) => resumes.consumed(ids),
+                }),
+                /**
+                 * Whether this machine has already decided that repeating is useless.
+                 *
+                 * RE-OPENED EVERY TICK, exactly like `startMarkOf` below and for the
+                 * identical reason: the observations are written by the RUN process, so
+                 * a snapshot taken when the daemon booted is of the moment before the
+                 * thing being looked for happened.
+                 *
+                 * FAILS CLOSED. A history that cannot be read HOLDS — a machine that
+                 * cannot see its own safety record must not spend a night on the
+                 * assumption that the record is empty, which is the same choice
+                 * `approvalGate` makes about an unreachable server.
+                 */
+                loopSafety: async (grant) => {
+                    if ((await safety.open()) !== 'ok') {
+                        return { held: true, because: 'the loop-safety history could not be read' };
+                    }
+                    const incident = safety.activeIncident(grant.goalId, grant.goalVersion);
+                    return incident === null ? { held: false } : { held: true, because: incident.because };
+                },
+                startMarkOf: async (requestId) => {
+                    // Re-read every time: the file is written by the RUN process, so a
+                    // snapshot taken here would be of the moment before the thing being
+                    // looked for happened.
+                    await startMarks.load();
+                    return startMarks.find(requestId);
+                },
+                refusalOf: async (requestId) => {
+                    await refusalMarks.load();
+                    const mark = refusalMarks.find(requestId);
+                    return mark === null
+                        ? null
+                        : {
+                            reason: mark.reason,
+                            ...(mark.code === undefined ? {} : { code: mark.code }),
+                            ...(mark.branch === undefined ? {} : { branch: mark.branch }),
+                        };
+                },
+                ...(thirdKey === null ? {} : { publicationOf: thirdKey }),
+                now: () => Date.now(),
+                log: opts.log,
+            });
+            // M4-1: one checkout per cadence, after the tick, only when it asked for one.
+            const asked = toProvision;
+            toProvision = null;
+            const made = await (0, workspace_provisioner_1.provisionOnce)(asked, provisioner, opts.log);
+            if (made.path !== null && provisioningFor !== null)
+                provisionedFor.set(provisioningFor, { path: made.path, at: Date.now() });
+            provisioningFor = null;
+            // M4-2: one stop request per cadence, after the tick, only when it decided one.
+            const stopAsk = toPreempt;
+            toPreempt = null;
+            await (0, preemptor_1.preemptOnce)(stopAsk, preemptor, opts.log);
+            // M4-4: one checkout the machine made, retired per cadence, only with the lock held — never one
+            // placed this cadence or last, never the one just provisioned.
+            const placedNow = [...placement.values()];
+            if (reaper !== null && coordinatorLock !== null)
+                await reaper([...placedNow, ...placedBefore, ...(made.path === null ? [] : [made.path])]);
+            placedBefore = placedNow;
+            // M5-1: one branch offered to the integration lane per cadence, only with the lock held.
+            if (integrator !== null && coordinatorLock !== null)
+                await integrator();
+        },
+        // M5-6: every ledger this machine holds — the project's, the reaper's retired records, each registered
+        // run's, each checkout's — the same list `looply goal` reads, re-listed every pass; one cursor per run as before.
+        replay: (0, ledger_replay_1.makeLedgersReplay)(() => (0, goal_runs_1.ledgersOn)(stateDir, new workspace_1.RunRegistry(projectState), opts.cwd), ledger_store_1.nodeLedgerFs, { log: opts.log }),
+        onCommand: makeCommandHandler(opts.log, 
+        // Given the state dir so it can read the run lease before spawning. The
+        // daemon's own memory of what it started does not survive its restart;
+        // the lease does, and that gap is the duplicate-runner window.
+        // Given the state dir so it can read the run lease before spawning, AND
+        // the durable start marks — the only thing that may report a run as
+        // started, and therefore the only thing that may make a start-run
+        // terminally done.
+        (0, run_launcher_1.nodeRunLauncher)(opts.cwd, (0, node_path_1.join)(opts.cwd, git_driver_1.STATE_DIR, 'state')), 
+        // The same path `looply run` reads (see run-cmd.ts). The daemon and the
+        // run are different processes over one repo, and this file is all they
+        // share.
+        // The FANNING writer, not the bare store: a phone Stop has to reach every
+        // live execution, not just the first one to look. See `controlWriter`.
+        controlWriter, 
+        // What this machine has already finished with. The lease covers "is a run
+        // happening now"; this covers "did I already do this", which the lease
+        // cannot answer because it stops existing when the run ends.
+        receipts, 
+        // This daemon is for one project. `pop` scopes only to the machine, and a
+        // machine can host several.
+        projectId, 
+        // How this machine lets go of a goal's work. Given the lease store as
+        // well as the queue, because it must not write `queue.json` while a run
+        // is doing the same.
+        (0, goal_ownership_1.nodeGoalReleaser)((0, node_path_1.join)(opts.cwd, git_driver_1.STATE_DIR, 'state'), ledger_store_1.nodeLedgerFs, new run_lease_1.RunLeaseStore((0, node_path_1.join)(opts.cwd, git_driver_1.STATE_DIR, 'state'), run_lease_1.nodeLeaseFs), exports.CLI_VERSION, 
+        // The same mirror the daemon pulls into, so carrying out a release also
+        // records WHY, and a Start still in flight for the old version cannot
+        // adopt work back into a goal that has been given up on.
+        goals), 
+        // Where a grant of autonomy is written down. Its OWN directory of
+        // receipts, not a field on any file two processes already share.
+        // The same instance the controller reads. Two stores over one file would
+        // be two caches of one fact.
+        autonomyStore, explicitStartGate, 
+        // M6-9: the same placement the tick hands the launcher, for a person's Start too.
+        (goalId) => placement.get(goalId), 
+        // M6-10: the owner's Start ceiling per grant, when declared.
+        opts.config.machine?.programmeMode?.limits.startsPerGrant, 
+        /**
+         * M6-14, widened in M6-22: while this machine is still deciding WHERE a
+         * goal runs, a person's Start waits for it rather than falling to the
+         * project checkout.
+         *
+         * Three ways to be in that state, and the third is the one M6-21 found:
+         * a checkout is being made for it, one was made and the goal is not yet
+         * placed in it, or this machine simply holds a live grant for the goal —
+         * it is pursuing it, and the tick that says where has not run yet.
+         */
+        {
+            placing: (goalId) => provisioningFor === goalId || provisionedFor.has(goalId) || pursuing(goalId),
+        }),
+        log: opts.log,
+        sleep,
+        now: () => Date.now(),
+        stopRequested: () => signals.requested(),
+    });
+    if (opts.once) {
+        const beat = await daemon.beat();
+        opts.log(`daemon  : heartbeat ${beat ? 'ok' : 'failed'}`);
+        signals.uninstall();
+        return beat ? 0 : 1;
+    }
+    /**
+     * 🔴 THE COORDINATOR LOCK, TAKEN AT LAST.
+     *
+     * `daemon-lock.ts` was written, specced, and never called by anything that
+     * ships. So `coordinatorTick` — whose first act is to refuse without the lock
+     * — could never return anything but a refusal, and, far more immediately, two
+     * `looply daemon` processes over one repository both ran: two autonomy ticks
+     * reading the same grants, each free to spend the same Start, with nothing in
+     * either log mentioning the other. The file existed; the hazard it describes
+     * was live.
+     *
+     * ⚠️ AFTER THE `--once` BRANCH, DELIBERATELY. A heartbeat check is not a
+     * coordinator and must keep working beside a running daemon — refusing it
+     * would break `looply daemon --once` on exactly the machines that are
+     * working properly.
+     *
+     * ⚠️ AND IT IS A REFUSAL, NOT A WAIT. A second daemon that queued for the
+     * lock would sit invisible until the first one stopped, which is the shape a
+     * person reads as "it started fine".
+     */
+    const taken = (0, daemon_lock_1.takeDaemonLock)(opts.cwd);
+    if (!taken.ok) {
+        opts.log(`daemon  : ${taken.because}.`);
+        signals.uninstall();
+        return 1;
+    }
+    // Visible to the tick, which refreshes it and refuses to schedule without it.
+    coordinatorLock = taken.lock;
+    opts.log('daemon  : connected. Ctrl-C to stop.');
+    try {
+        const final = await daemon.run();
+        opts.log(`daemon  : stopped — ${final.delivered} events delivered, ${final.buffered} still buffered`);
+        return 0;
+    }
+    finally {
+        coordinatorLock = null;
+        taken.lock.release();
+        signals.uninstall();
+    }
+}
+/**
+ * The terms of a grant, off an `unknown` payload.
+ *
+ * Read defensively for the same reason `readStartPayload` is: the payload
+ * travels from the server as Json and this build may be older or newer than
+ * the one that wrote it. Every field is required -- there is no sensible
+ * default for any of them, and a grant missing its ceiling or its expiry is
+ * not a grant with a gap in it, it is not a grant.
+ */
+/** The Starts a grant payload asks for, when it says. Read before `grantOf` so a refusal can name the ceiling. */
+function askedStarts(payload) {
+    if (typeof payload !== 'object' || payload === null)
+        return null;
+    const v = payload['maxStarts'];
+    return typeof v === 'number' && Number.isInteger(v) ? v : null;
+}
+function grantOf(payload, ceiling = core_1.MAX_AUTONOMOUS_STARTS) {
+    if (typeof payload !== 'object' || payload === null)
+        return null;
+    const p = payload;
+    const { controllerId, goalId, goalVersion, maxStarts, expiresAt } = p;
+    if (typeof controllerId !== 'string' || controllerId.length === 0)
+        return null;
+    if (typeof goalId !== 'string' || goalId.length === 0)
+        return null;
+    if (typeof goalVersion !== 'number' || !Number.isInteger(goalVersion) || goalVersion < 0) {
+        return null;
+    }
+    // A ceiling of zero authorizes nothing and would be recorded as a live grant
+    // that can never spend; a negative or fractional one is a build disagreeing
+    // with the server. Both are refusals, not values to clamp.
+    // THE MACHINE HOLDS ITS OWN CEILING.
+    //
+    // MAX_AUTONOMOUS_STARTS was enforced at exactly one site — the server,
+    // where the row is minted — and the machine copied whatever arrived. So the
+    // bound lived entirely on the far side of the wire: a bad migration, a
+    // restored backup or a server bug carrying maxStarts: 100000 would have been
+    // adopted verbatim, and reconciliation would have agreed with itself because
+    // both numbers came off the same wrong row.
+    //
+    // A person's evening is spent HERE, so the bound that protects it belongs
+    // here too. Refused rather than clamped: a grant whose terms this machine
+    // does not recognise is not one to quietly reinterpret.
+    if (typeof maxStarts !== 'number' || !Number.isInteger(maxStarts) || maxStarts < 1)
+        return null;
+    if (maxStarts > ceiling)
+        return null;
+    // PARSEABLE, not merely a string. An expiry that reads as NaN compares false
+    // against every clock, so `Date.parse(expiresAt) <= now` would be false
+    // forever and the grant would never run out of time.
+    if (typeof expiresAt !== 'string' || Number.isNaN(Date.parse(expiresAt)))
+        return null;
+    return { controllerId, goalId, goalVersion, maxStarts, expiresAt };
+}
+/**
+ * The goal and version a release names, off an `unknown` payload.
+ *
+ * `null` rather than `undefined` for an unreadable one: there is no "no goal"
+ * case here — a release with no goal names nothing and can only be a mistake,
+ * so both the missing and the malformed reading are the same refusal.
+ */
+function releaseOf(payload) {
+    if (typeof payload !== 'object' || payload === null)
+        return null;
+    const p = payload;
+    if (typeof p.goalId !== 'string' || p.goalId.length === 0)
+        return null;
+    // Required, not optional. The server stamps it on every release, and a
+    // release without one could only record `abandoned` against whatever version
+    // this machine happened to hold — a row no server ever wrote.
+    if (typeof p.goalVersion !== 'number' || !Number.isInteger(p.goalVersion) || p.goalVersion < 0)
+        return null;
+    return { goalId: p.goalId, goalVersion: p.goalVersion };
+}
+//# sourceMappingURL=daemon-cmd.js.map