@mnemom/mnemom 0.17.33 → 0.17.34-next.2

package/dist/host/daemon.js

@@ -0,0 +1,606 @@
+/**
+ * The host daemon core (BACKBONE C2; C12 and C15). One instance per state dir (lock.ts, taken by
+ * the caller before this class exists). Everything with a side effect goes through `deps`, so
+ * every branch is unit-tested without tmux, launchd or a network.
+ *
+ * Cycle (every tick, TICK_MS):
+ *   gate (config.json only, R39) -> idle while off
+ *   first enabled cycle: transcript guards for listed sessions, then adopt-or-kill (R11, R38)
+ *   seat liveness: report exits (R19, R33), kill hello-deadline misses (R17)
+ *   heartbeat every lease_seconds/3 for hello'd seats (R18), kill on fence (R20)
+ *   every EXECUTOR_POLL_S: poll, then claim + spawn up to RESPAWN_CONCURRENCY in flight (R14, R15)
+ *
+ * The daemon never sends hello itself (R32): the seat's plugin hook does, and the seat proxy relays
+ * it to `relayHello` over the control socket; the executor key stays here.
+ */
+import { randomUUID } from "node:crypto";
+import { EXECUTOR_POLL_S, HEARTBEAT_DIVISOR, RESPAWN_CONCURRENCY, CLAIM_BACKOFF_BASE_S, CLAIM_BACKOFF_MAX_S, CLAIM_BACKOFF_JITTER, LEASE_SECONDS_DEFAULT, } from "../vendor/shared/durable-contract/constants.js";
+import { TERMINAL_STATES } from "../vendor/shared/durable-contract/states.js";
+import { IDLE_LOG } from "./gate.js";
+import { classifyClaim, errorCode, } from "./client.js";
+import { seatTmuxSession } from "./tmux.js";
+import { CODE, SEAT_UNKNOWN, SPAWNED_KIND } from "./s1-names.js";
+export const TICK_MS = 1000;
+export const ADOPT_RETRY_MS = 2000;
+export { SPAWNED_KIND } from "./s1-names.js";
+export const spawnIdempotencyKey = (sessionId, epoch, spawnId) => `spawn:${sessionId}:${epoch}:${spawnId}`;
+/** S1 claim backoff: 2 s doubling to 60 s, scaled by 1 + jitter in [0, CLAIM_BACKOFF_JITTER) (R31). */
+export function backoffMs(count, random) {
+    const base = Math.min(CLAIM_BACKOFF_MAX_S, CLAIM_BACKOFF_BASE_S * 2 ** Math.max(0, count - 1));
+    return Math.round(base * (1 + random() * CLAIM_BACKOFF_JITTER) * 1000);
+}
+/** Heartbeat period from the server's lease (R18): lease_seconds / HEARTBEAT_DIVISOR. */
+export const heartbeatPeriodMs = (leaseSeconds) => Math.max(1, (leaseSeconds * 1000) / HEARTBEAT_DIVISOR);
+const ADOPT_HELLO_STATES = new Set(["running", "parked"]);
+const TERMINAL = new Set(TERMINAL_STATES);
+/** States whose sessions the daemon claims (effective parked, detached; resuming is reclaimed after expiry). */
+const CLAIMABLE = new Set(["parked", "detached", "resuming", "running"]);
+/**
+ * The lease length an adopted seat heartbeats on until a heartbeat answer re-derives it (R18):
+ * the time left on the current lease (never longer than the S1 default, so a short lease is never
+ * out-waited), else the S1 default. The poll carries no lease_seconds (ruling 33.28.2).
+ */
+export function adoptedLeaseSeconds(item, now) {
+    const exp = item.lease_expires_at ? Date.parse(item.lease_expires_at) : NaN;
+    if (Number.isFinite(exp) && exp > now)
+        return Math.max(1, Math.min(LEASE_SECONDS_DEFAULT, Math.ceil((exp - now) / 1000)));
+    return LEASE_SECONDS_DEFAULT;
+}
+/** The state says the current epoch's hello was accepted (running, parked, detached(lease_expired)). */
+const helloLanded = (item) => ADOPT_HELLO_STATES.has(item.state ?? "") ||
+    (item.state === "detached" && item.state_reason === "lease_expired");
+/**
+ * C12-R11: adopt a tagged pane, or say why it is killed. `seen` holds sessions already adopted.
+ * The poll carries no spawn id or hello (ruling 33.28.2): the pane's tags name its epoch and spawn,
+ * held_here says the server agrees the lease is ours, and the state says whether the epoch's hello
+ * landed (hello moves resuming to running). The server stays the arbiter: the heartbeat revives a
+ * parked or lease-expired session only for the hello'd spawn, and fences anything else.
+ */
+export function adoptVerdict(pane, item, now, panAlive, seenSessions) {
+    if (!item)
+        return { adopt: false, why: "unknown_session" };
+    if (pane.dead || !panAlive)
+        return { adopt: false, why: "dead_pane" };
+    if (seenSessions.has(item.id))
+        return { adopt: false, why: "duplicate" };
+    if (item.lease_epoch === null || pane.epoch !== item.lease_epoch)
+        return { adopt: false, why: "older_epoch" };
+    if (item.held_here !== true)
+        return { adopt: false, why: "not_held" };
+    const st = item.state ?? "";
+    if (TERMINAL.has(st))
+        return { adopt: false, why: "terminal" };
+    if (helloLanded(item))
+        return { adopt: true, hello: true };
+    const exp = item.lease_expires_at ? Date.parse(item.lease_expires_at) : NaN;
+    if (st === "resuming" && Number.isFinite(exp) && exp > now)
+        return { adopt: true, hello: false };
+    if (st === "resuming")
+        return { adopt: false, why: "hello_deadline_passed" };
+    return { adopt: false, why: `state_${st}${item.state_reason ? `_${item.state_reason}` : ""}` };
+}
+/** How long a pane may outlive its claude before the exit is reported without the pane's status. */
+export const CLAUDE_GONE_GRACE_MS = 3000;
+/**
+ * R19: a seat is alive while its claude pid is (or, before claude has started, while its pane
+ * process is). A dead pane reports its own exit status; a claude that is gone while the pane
+ * lingers is reported after CLAUDE_GONE_GRACE_MS with 137.
+ */
+export function seatLiveness(seat, pane, now, claudePid, alive) {
+    if (!pane || pane.panePid === null)
+        return { kind: "dead", status: 137 };
+    if (pane.dead)
+        return { kind: "dead", status: exitStatusOf(pane) };
+    const c = claudePid(pane.panePid);
+    if (c !== null && alive(c)) {
+        seat.claudePid = c;
+        seat.claudeGoneAt = null;
+        return { kind: "alive" };
+    }
+    if (seat.claudePid === null)
+        return alive(pane.panePid) ? { kind: "alive" } : { kind: "dead", status: 137 };
+    if (seat.claudeGoneAt === null)
+        seat.claudeGoneAt = now;
+    return now - seat.claudeGoneAt >= CLAUDE_GONE_GRACE_MS
+        ? { kind: "dead", status: 137 }
+        : { kind: "alive" };
+}
+/** Exit status as the seat-exit route takes it (0..255); a missing status is a failure. */
+export const exitStatusOf = (pane) => pane && pane.deadStatus !== null ? pane.deadStatus : 137;
+export class HostDaemon {
+    d;
+    seats = new Map();
+    unavailable = new Map();
+    lastPoll = -Infinity;
+    adoptDone = false;
+    idleLogged = false;
+    items = new Map();
+    integrityState = { ok: true };
+    /** The cause claims were last held for, so the log names each change once (mnemom-test #981). */
+    heldFor = null;
+    firstBatchDone = false;
+    stopped = false;
+    /** The last poll said the grant lapsed (ruling 33.28(4)); logged once per transition. */
+    grantExpired = false;
+    constructor(d) {
+        this.d = d;
+    }
+    stop() {
+        this.stopped = true;
+    }
+    /** One pass of the loop. Returns what it did (for tests and logs). */
+    async tick() {
+        const did = [];
+        if (!this.d.gateOn()) {
+            // Once per transition to off: one log line and one runtime-file write (no HOME churn while idle).
+            if (!this.idleLogged) {
+                this.d.log(IDLE_LOG);
+                this.idleLogged = true;
+                this.publish("idle");
+            }
+            return ["idle"];
+        }
+        this.idleLogged = false;
+        // Bind the boot-bound nonce (it may rotate and rewrite the state file) before any request (R06).
+        if (!this.d.nonce)
+            throw new Error("no nonce: the host state file has no usable nonce");
+        const now = this.d.now();
+        const sincePoll = now - this.lastPoll;
+        const pollDue = sincePoll >= EXECUTOR_POLL_S * 1000;
+        // Before adopt-or-kill has run, a failed poll is retried every ADOPT_RETRY_MS, not every tick.
+        let polled = false;
+        if (pollDue || (!this.adoptDone && sincePoll >= ADOPT_RETRY_MS)) {
+            const r = await this.d.api.sessions();
+            if (r.items) {
+                polled = true;
+                this.lastPoll = now;
+                this.items = new Map(r.items.map((i) => [i.id, i]));
+                this.syncGuards(r.items);
+                if (r.grantExpired !== this.grantExpired) {
+                    this.grantExpired = r.grantExpired;
+                    this.d.log(r.grantExpired
+                        ? "executor grant expired: the api lists no sessions until the owner renews it"
+                        : "executor grant renewed: sessions listed again");
+                }
+                if (r.grantExpired)
+                    did.push("grant_expired");
+                // A lapsed grant's empty list is not the session list: adopt-or-kill waits for a real one.
+                if (!this.adoptDone && !r.grantExpired) {
+                    await this.adoptOrKill(did);
+                    this.adoptDone = true;
+                }
+            }
+            else {
+                this.lastPoll = now;
+                did.push(`poll_failed:${r.code ?? r.status}`);
+            }
+        }
+        if (!this.adoptDone) {
+            this.publish("running");
+            return did;
+        }
+        await this.checkSeats(did);
+        await this.heartbeat(did);
+        if (polled && this.items.size > 0)
+            await this.claimWave(did);
+        this.publish("running");
+        return did;
+    }
+    /** Run until stop(): one tick every TICK_MS. */
+    async run(sleep) {
+        while (!this.stopped) {
+            try {
+                await this.tick();
+            }
+            catch (e) {
+                this.d.log(`tick error: ${e.message}`);
+            }
+            await sleep(TICK_MS);
+        }
+    }
+    // ---- transcript guards (R38) ------------------------------------------------------------
+    syncGuards(items) {
+        const live = new Set();
+        for (const it of items) {
+            if (TERMINAL.has(it.state ?? ""))
+                continue;
+            live.add(it.id);
+            try {
+                this.d.guard(it);
+            }
+            catch (e) {
+                this.d.log(`transcript guard ${it.id}: ${e.message}`);
+            }
+        }
+        // A guard whose session is no longer listed (terminal, or no longer homed here) is removed.
+        for (const id of this.d.guardedIds())
+            if (!live.has(id))
+                this.d.removeGuard(id);
+    }
+    // ---- adopt-or-kill (R11, R12) -------------------------------------------------------------
+    async adoptOrKill(did) {
+        const panes = await this.d.panes();
+        const now = this.d.now();
+        const adoptedSessions = new Set();
+        // A copy: killing a seat may change what panes() returned.
+        for (const p of [...panes]) {
+            const item = this.items.get(p.sid);
+            const claude = p.panePid && !p.dead ? this.d.claudePid(p.panePid) : null;
+            const v = adoptVerdict(p, item, now, claude !== null && this.d.alive(claude), adoptedSessions);
+            if (v.adopt && item) {
+                adoptedSessions.add(item.id);
+                const leaseSeconds = adoptedLeaseSeconds(item, now);
+                this.seats.set(item.id, {
+                    sessionId: item.id,
+                    name: item.name,
+                    epoch: item.lease_epoch,
+                    spawnId: p.spawn,
+                    tmuxSession: p.session,
+                    panePid: p.panePid,
+                    claudePid: claude,
+                    claudeGoneAt: null,
+                    helloAccepted: v.hello,
+                    registered: true,
+                    deadline: item.lease_expires_at ? Date.parse(item.lease_expires_at) : now,
+                    leaseSeconds,
+                    // Heartbeat an adopted hello'd seat at once (R37: running within one period).
+                    lastHeartbeat: -Infinity,
+                    leaseKey: null,
+                    specPath: null,
+                    adopted: true,
+                    interruptedTurn: null,
+                });
+                did.push(`adopt:${item.id}:${v.hello ? "hello" : "pending"}`);
+                continue;
+            }
+            // A current-epoch seat held here that died while the daemon was down is reported (BACKBONE C2);
+            // the server checks the spawn id, and its hello_at, not this report, is authoritative.
+            if (item &&
+                p.dead &&
+                item.lease_epoch !== null &&
+                p.epoch === item.lease_epoch &&
+                item.held_here === true) {
+                await this.reportExit(item.id, item.lease_epoch, p.spawn, exitStatusOf(p), helloLanded(item));
+            }
+            await this.d.killSeat(p.session, p.panePid);
+            did.push(`kill:${p.sid || "?"}:${v.adopt ? "?" : v.why}`);
+        }
+    }
+    // ---- seat liveness, exits and hello deadlines (R17, R19, R33) ------------------------------
+    async checkSeats(did) {
+        if (this.seats.size === 0)
+            return;
+        const panes = new Map((await this.d.panes()).map((p) => [p.session, p]));
+        const now = this.d.now();
+        for (const seat of [...this.seats.values()]) {
+            const pane = panes.get(seat.tmuxSession);
+            const v = seatLiveness(seat, pane, now, (pid) => this.d.claudePid(pid), (pid) => this.d.alive(pid));
+            if (v.kind === "dead") {
+                // The claude pid is gone (a remain-on-exit pane does not count as alive, R19).
+                if (seat.registered)
+                    await this.reportExit(seat.sessionId, seat.epoch, seat.spawnId, v.status, seat.helloAccepted);
+                await this.d.killSeat(seat.tmuxSession, seat.panePid);
+                this.seats.delete(seat.sessionId);
+                did.push(`exit:${seat.sessionId}:${v.status}:${seat.helloAccepted ? "hello" : "nohello"}`);
+                continue;
+            }
+            if (!seat.helloAccepted && now >= seat.deadline) {
+                await this.d.killSeat(seat.tmuxSession, seat.panePid);
+                if (seat.registered)
+                    await this.reportExit(seat.sessionId, seat.epoch, seat.spawnId, 137, false);
+                this.seats.delete(seat.sessionId);
+                did.push(`hello_deadline:${seat.sessionId}`);
+            }
+        }
+    }
+    async reportExit(sessionId, epoch, spawnId, exitStatus, helloAccepted) {
+        const r = await this.d.api.seatExit(sessionId, {
+            epoch,
+            nonce: this.d.nonce,
+            spawn_id: spawnId,
+            exit_status: Math.max(0, Math.min(255, exitStatus)),
+            hello_accepted: helloAccepted,
+        });
+        if (r.status >= 400 || r.status === 0)
+            this.d.log(`seat-exit ${sessionId} ${spawnId}: ${r.code ?? r.status}`);
+        return r;
+    }
+    // ---- heartbeat (R18, R20) -------------------------------------------------------------------
+    async heartbeat(did) {
+        const now = this.d.now();
+        const due = [...this.seats.values()].filter((s) => s.helloAccepted && now - s.lastHeartbeat >= heartbeatPeriodMs(s.leaseSeconds));
+        if (due.length === 0)
+            return;
+        // Ruling 33.28.1: the state-file nonce once at the top level; the api fences on it.
+        const r = await this.d.api.heartbeat({
+            nonce: this.d.nonce,
+            entries: due.map((s) => ({ session_id: s.sessionId, epoch: s.epoch, spawn_id: s.spawnId })),
+        });
+        for (const s of due)
+            s.lastHeartbeat = now;
+        if (r.status !== 200 ||
+            !r.body ||
+            typeof r.body !== "object" ||
+            !Array.isArray(r.body.results)) {
+            did.push(`heartbeat_failed:${r.code ?? r.status}`);
+            return;
+        }
+        const results = new Map(r.body.results.map((x) => [String(x.session_id), x]));
+        for (const s of due) {
+            const res = results.get(s.sessionId);
+            if (!res)
+                continue;
+            if (res.extended) {
+                if (res.lease_expires_at) {
+                    const exp = Date.parse(res.lease_expires_at);
+                    if (Number.isFinite(exp)) {
+                        // The lease length the server keeps (R18): derive it from the extension.
+                        const secs = Math.round((exp - now) / 1000);
+                        if (secs >= 1 && secs <= 3600)
+                            s.leaseSeconds = secs;
+                    }
+                }
+                did.push(`hb:${s.sessionId}:${res.reason ?? "extended"}`);
+                continue;
+            }
+            // fenced, contained, terminal, not_hello_spawn, not_revivable: the epoch moved or the seat is not ours to keep (R20).
+            await this.d.killSeat(s.tmuxSession, s.panePid);
+            this.seats.delete(s.sessionId);
+            did.push(`hb_stop:${s.sessionId}:${res.reason ?? "?"}`);
+        }
+    }
+    // ---- claim + spawn (R10, R14, R15, R16, R31, R36) -----------------------------------------------
+    inFlight() {
+        return [...this.seats.values()].filter((s) => !s.helloAccepted).length;
+    }
+    async claimWave(did) {
+        const now = this.d.now();
+        const candidates = [...this.items.values()].filter((i) => this.claimable(i, now));
+        if (candidates.length === 0)
+            return;
+        this.integrityState = await this.d.integrity();
+        if (!this.integrityState.ok) {
+            did.push(`integrity:${this.integrityState.cause}`);
+            if (this.heldFor !== this.integrityState.cause) {
+                this.heldFor = this.integrityState.cause;
+                this.d.log(`claims held: plugin integrity ${this.heldFor}`);
+            }
+            return;
+        }
+        if (this.heldFor !== null) {
+            this.heldFor = null;
+            this.d.log("claims resumed: plugin integrity ok");
+        }
+        let started = 0;
+        for (const item of candidates) {
+            if (this.inFlight() >= RESPAWN_CONCURRENCY)
+                break;
+            const ok = await this.claimAndSpawn(item, did);
+            if (ok)
+                started++;
+        }
+        if (started > 0 && !this.firstBatchDone) {
+            this.firstBatchDone = true;
+            if (this.d.pauseAt === "after_first_batch")
+                await this.d.pause("after_first_batch");
+        }
+    }
+    claimable(i, now) {
+        // Held-seat rule (U02): never claim a session whose seat this daemon holds.
+        if (this.seats.has(i.id))
+            return false;
+        if (!CLAIMABLE.has(i.state ?? ""))
+            return false;
+        if (i.state === "detached" || i.state === "parked") {
+            /* claimable */
+        }
+        else if (i.state === "resuming" || i.state === "running") {
+            // Held elsewhere (or by a seat this daemon lost): claim only after its lease expires.
+            const exp = i.lease_expires_at ? Date.parse(i.lease_expires_at) : NaN;
+            if (Number.isFinite(exp) && exp > now)
+                return false;
+        }
+        const u = this.unavailable.get(i.id);
+        if (u && now < u.nextAt)
+            return false;
+        return true;
+    }
+    async claimAndSpawn(item, did) {
+        const now = this.d.now();
+        // Nothing to resume: never claim, so no empty epoch-bumped lease is left to lapse and be re-claimed.
+        if (!item.cc_session_id) {
+            did.push(`no_cc_session:${item.id}`);
+            return false;
+        }
+        // attest -> claim (BACKBONE C2). Attestation tokens ride on the claim when the route gives them.
+        const at = await this.d.api.attest(item.id, this.d.nonce);
+        const tokens = at.status === 200 && at.body && typeof at.body === "object"
+            ? at.body.tokens
+            : undefined;
+        // mnemom-test #1001 (lead ruling, consistent with 33.28.5): a daemon with no local lease key
+        // for the session asks for one on its first claim. It never holds one here: a session it
+        // seats is not claimable, and the seat takes the key once. A bare claim and then a new_key
+        // retry never works (the bare claim makes the lease live, so the retry is refused
+        // lost_race/lease_live), so this is one claim per attempt, and any refusal waits for a tick.
+        const r = await this.d.api.claim(item.id, {
+            nonce: this.d.nonce,
+            ...(tokens !== undefined ? { tokens } : {}),
+            new_key: true,
+        });
+        const c = classifyClaim(r, now);
+        if (c.kind === "ok" && c.claim.leaseKey === null) {
+            did.push(`claim_none:${item.id}:no_lease_key`);
+            return false;
+        }
+        if (c.kind === "unavailable") {
+            const prev = this.unavailable.get(item.id);
+            const count = (prev?.count ?? 0) + 1;
+            this.unavailable.set(item.id, {
+                cause: c.cause,
+                count,
+                nextAt: now + backoffMs(count, this.d.random),
+            });
+            did.push(`unavailable:${item.id}:${c.cause}:${count}`);
+            return false;
+        }
+        if (c.kind === "none") {
+            did.push(`claim_none:${item.id}:${c.why}`);
+            return false;
+        }
+        this.unavailable.delete(item.id);
+        const claim = c.claim;
+        if (this.d.pauseAt === "after_claim_before_spawn")
+            await this.d.pause("after_claim_before_spawn");
+        // Transcript check after the claim (R16): restore from the guard, or fail transcript_lost. A
+        // session born locked (B5a, the claim's new_session) has none until its first turn: it starts
+        // fresh. Once a transcript exists the marker is irrelevant and the seat resumes.
+        const t = this.d.ensureTranscript(item);
+        const fresh = t.kind === "lost" && claim.newSession;
+        if (t.kind === "lost" && !fresh) {
+            const f = await this.d.api.fail(item.id, {
+                epoch: claim.epoch,
+                nonce: this.d.nonce,
+                reason: "transcript_lost",
+            });
+            did.push(`transcript_lost:${item.id}:${f.status}`);
+            return false;
+        }
+        const spawnId = randomUUID();
+        const tmuxSession = seatTmuxSession(item.id, spawnId);
+        const seat = {
+            sessionId: item.id,
+            name: item.name,
+            epoch: claim.epoch,
+            spawnId,
+            tmuxSession,
+            panePid: null,
+            claudePid: null,
+            claudeGoneAt: null,
+            helloAccepted: false,
+            registered: false,
+            deadline: claim.leaseExpiresAt,
+            leaseSeconds: claim.leaseSeconds,
+            lastHeartbeat: -Infinity,
+            leaseKey: claim.leaseKey,
+            specPath: null,
+            adopted: false,
+            // A fresh (born-locked) seat has no transcript, so no interrupted turn to continue.
+            interruptedTurn: t.kind === "lost" ? null : (this.d.interruptedAt?.(t.path) ?? null),
+        };
+        this.seats.set(item.id, seat);
+        try {
+            const sp = await this.d.spawnSeat({
+                item,
+                epoch: claim.epoch,
+                spawnId,
+                tmuxSession,
+                transcriptPath: t.kind === "lost" ? null : t.path,
+                newSession: fresh,
+            });
+            seat.panePid = sp.panePid;
+            seat.specPath = sp.specPath;
+        }
+        catch (e) {
+            this.seats.delete(item.id);
+            did.push(`spawn_failed:${item.id}:${e.message}`);
+            await this.d.killSeat(tmuxSession, null);
+            return false;
+        }
+        if (this.d.pauseAt === "after_spawn_before_register")
+            await this.d.pause("after_spawn_before_register");
+        // Register the spawn id before the hello (R10).
+        const ap = await this.d.api.append(item.id, {
+            kind: SPAWNED_KIND,
+            refs: { spawn_id: spawnId },
+            idempotency_key: spawnIdempotencyKey(item.id, claim.epoch, spawnId),
+            expected_epoch: claim.epoch,
+            nonce: this.d.nonce,
+        });
+        if (ap.status < 200 || ap.status >= 300) {
+            // Fenced (the epoch moved) or refused: kill the seat tree; a later claim may respawn (R10).
+            await this.d.killSeat(tmuxSession, seat.panePid);
+            this.seats.delete(item.id);
+            did.push(`register_refused:${item.id}:${ap.code ?? ap.status}`);
+            return false;
+        }
+        seat.registered = true;
+        did.push(`spawn:${item.id}:${claim.epoch}:${claim.outcome}`);
+        if (this.d.pauseAt === "after_register_before_hello")
+            await this.d.pause("after_register_before_hello");
+        return true;
+    }
+    // ---- control socket ops (the seat proxy) -------------------------------------------------------
+    /** The one-time lease-key handoff to the seat proxy of `spawnId` (C3). */
+    takeLeaseKey(sessionId, spawnId) {
+        const s = this.seats.get(sessionId);
+        if (!s || s.spawnId !== spawnId || !s.leaseKey)
+            return null;
+        const k = s.leaseKey;
+        s.leaseKey = null;
+        return k;
+    }
+    /**
+     * Relay a seat's hello (R17, R32, R34). Only for a registered seat this daemon holds, with its own
+     * spawn id. 409 durable_hello_late kills that seat's tree.
+     */
+    async relayHello(sessionId, spawnId) {
+        const s = this.seats.get(sessionId);
+        if (!s || s.spawnId !== spawnId || !s.registered)
+            return {
+                status: 404,
+                body: {
+                    error: { code: SEAT_UNKNOWN, message: "no registered seat with that spawn id" },
+                },
+            };
+        const r = await this.d.api.hello(sessionId, {
+            epoch: s.epoch,
+            nonce: this.d.nonce,
+            spawn_id: spawnId,
+        });
+        if (r.status === 200) {
+            const b = (r.body ?? {});
+            if (typeof b.lease_seconds === "number" && b.lease_seconds > 0)
+                s.leaseSeconds = b.lease_seconds;
+            const first = !s.helloAccepted;
+            if (first)
+                s.lastHeartbeat = this.d.now();
+            s.helloAccepted = true;
+            // An adopted seat was resumed by an earlier daemon run; only a seat this run spawned continues.
+            if (first && !s.adopted && this.d.autoContinue)
+                void this.d
+                    .autoContinue({ sessionId, tmuxSession: s.tmuxSession, epoch: s.epoch, spawnId: s.spawnId }, s.interruptedTurn)
+                    .catch((e) => this.d.log(`auto-continue ${sessionId}: ${e.message}`));
+        }
+        else if (r.status === 409 && errorCode(r.body) === CODE.durable_hello_late) {
+            await this.d.killSeat(s.tmuxSession, s.panePid);
+            this.seats.delete(sessionId);
+        }
+        return { status: r.status, body: r.body };
+    }
+    // ---- status ------------------------------------------------------------------------------------
+    publish(state) {
+        this.d.publish({
+            pid: process.pid,
+            state,
+            integrity: this.integrityState,
+            seats: [...this.seats.values()].map((s) => ({
+                session_id: s.sessionId,
+                name: s.name,
+                epoch: s.epoch,
+                spawn_id: s.spawnId,
+                tmux_session: s.tmuxSession,
+                pane_pid: s.panePid,
+                hello: s.helloAccepted,
+                spec_path: s.specPath,
+            })),
+            sessions: [...this.items.values()].map((i) => ({
+                id: i.id,
+                name: i.name,
+                state: i.state,
+                state_reason: i.state_reason,
+            })),
+            unavailable: Object.fromEntries([...this.unavailable].map(([k, v]) => [k, { cause: v.cause, count: v.count }])),
+            updated_at: new Date(this.d.now()).toISOString(),
+        });
+    }
+}

package/dist/host/gate.d.ts

@@ -0,0 +1,46 @@
+import { type ExperimentalPrefs } from "../lib/experimental.js";
+export declare const DURABLE_ID: "durable";
+export declare const HOST_WHAT = "`mnemom agent host`";
+export declare const GATED_TEXT: string;
+/** The enable command (S1 FIX_LINES.daemon_idle body). */
+export declare const ENABLE_FIX: string;
+/** C12-R40: durable on only through the shell. */
+export declare const INSTALL_SHELL_ONLY_TEXT: string;
+/** C12-R39: the idle line (status and the launcher). */
+export declare const IDLE_TEXT: string;
+/** The idle line with its fix, rendered from S1 (C12-R39). */
+export declare const IDLE_FIX: string;
+export declare const IDLE_LOG = "durable disabled: idle";
+/** config.json's experimental block, read fresh (a missing or corrupt file is off). */
+export declare function readStoredExperimental(configFile: string): ExperimentalPrefs | undefined;
+/** The daemon gate: config.json only, env ignored (C12-R39). */
+export declare function durableOnInConfig(configFile: string): boolean;
+/** The fresh-invocation gate: config.json and the environment (C12-R25). */
+export declare function durableOnFresh(configFile: string, env: Readonly<Record<string, string | undefined>>): boolean;
+export type InstallGate = {
+    ok: true;
+} | {
+    ok: false;
+    exit: 1 | 2;
+    message: string;
+};
+/** `host install`: off everywhere -> exit 2 gated; on only in the shell -> exit 1 (R40); on in config -> ok. */
+export declare function installGate(configFile: string, env: Readonly<Record<string, string | undefined>>): InstallGate;
+export type HostArgvGate = {
+    code: 2;
+    message: string;
+} | null;
+/**
+ * The `host` verb-word gate (C17-R10, C12-R25), applied to the raw argv before commander runs,
+ * so that neither the bare word, nor a trailing `--help`/`--json`, nor an unknown sub-word
+ * (`host breakglass`) reaches commander's help, usage or unknown-command paths while durable is
+ * off. Reads config.json only; writes nothing, sends nothing, spawns nothing.
+ *
+ * The hidden `run` keeps its carve-out: the gate comes from config.json only (env ignored, R39),
+ * and it refuses only when there is no enrollment state file; an enrolled host goes on to take
+ * the lock and idle, which `run` itself decides.
+ */
+export declare function hostArgvGate(argv: readonly string[], ctx: {
+    env: Readonly<Record<string, string | undefined>>;
+    home: string;
+}): HostArgvGate;