@mnemom/mnemom 0.17.34-next.1 → 0.17.34-next.2

package/dist/host/auto-continue.js

@@ -0,0 +1,118 @@
+/**
+ * The seat's automatic "continue" (lead rulings, 2026-10-28: "auto-continue an interrupted turn once
+ * on takeover"): a lock that lands mid-turn leaves the resumed conversation's last turn interrupted,
+ * and `claude --resume` then idles at "What should Claude do instead?". On the seat's first accepted
+ * hello, if the transcript's last turn (as it was before the seat started) was interrupted and that
+ * turn was never continued, the daemon types one "continue" into the pane and logs it. The marker is
+ * keyed on the session and the interrupted turn's record uuid, written before the keys are sent and
+ * kept across respawns: each interrupted turn is continued at most once, so a later mid-turn lock in
+ * the same session is continued too, and a respawn never continues the same turn twice.
+ *
+ * The continue is also journaled: S1's executor.turn_continued (refs {spawn_id}, lead ruling
+ * 2026-10-28) is appended under the seat's epoch after the marker and before the keys. A refused or
+ * failed append sends nothing; the marker stays, so no restart retries that turn unjournaled. The
+ * marker remains the per-turn guard: the event's refs name the spawn, not the turn.
+ *
+ * Pure over injected deps; host/run.ts wires tmux, the marker directory and the daemon log.
+ */
+import { TURN_CONTINUED_KIND } from "./s1-names.js";
+export const CONTINUE_TEXT = "continue";
+/** How long to wait for claude's input prompt in the pane before giving up. */
+export const PANE_READY_TIMEOUT_MS = 30_000;
+export const PANE_READY_POLL_MS = 500;
+/** The marker claude's TUI shows at its input line. */
+const PROMPT_MARK = "❯";
+const blocks = (r) => Array.isArray(r.message?.content) ? r.message.content : [];
+/**
+ * The interrupted turn of a CC transcript: the uuid of its last conversation record when the turn was
+ * cut off, else null. The last record decides: the assistant's tool call (no result yet) or any user
+ * record (a prompt no reply followed, a tool result the model never answered, or CC's "[Request
+ * interrupted by user]") is cut off, as is an assistant record with only thinking; the assistant's own
+ * text finished the turn. Meta records and lines that are not JSON are skipped. A cut-off record with
+ * no uuid also gives null: without a turn id there is no marker to guard the continue with.
+ */
+export function interruptedTurnId(transcript) {
+    const msgs = [];
+    for (const line of transcript.split("\n")) {
+        if (!line.trim())
+            continue;
+        let r;
+        try {
+            r = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if ((r.type === "user" || r.type === "assistant") && r.message && r.isMeta !== true)
+            msgs.push(r);
+    }
+    const last = msgs[msgs.length - 1];
+    if (!last)
+        return null;
+    if (last.type === "assistant") {
+        const b = blocks(last);
+        if (!b.some((x) => x.type === "tool_use") && b.some((x) => x.type === "text"))
+            return null;
+    }
+    return typeof last.uuid === "string" && TURN_ID_RE.test(last.uuid) ? last.uuid : null;
+}
+/** A turn id usable in a marker file name. */
+const TURN_ID_RE = /^[A-Za-z0-9-]{1,64}$/;
+/** The turn_continued idempotency key: one continue per spawn of a session under one epoch. */
+export const continueIdempotencyKey = (seat) => `continue:${seat.sessionId}:${seat.epoch}:${seat.spawnId}`;
+/**
+ * The journal dep over the executor API: POST executor.turn_continued for the seat under its claim
+ * epoch and the boot-bound nonce. A 2xx is journaled (null); anything else answers its code.
+ */
+export function turnContinuedJournal(api, nonce) {
+    return async (seat) => {
+        const r = await api.append(seat.sessionId, {
+            kind: TURN_CONTINUED_KIND,
+            refs: { spawn_id: seat.spawnId },
+            idempotency_key: continueIdempotencyKey(seat),
+            expected_epoch: seat.epoch,
+            nonce: nonce(),
+        });
+        if (r.status >= 200 && r.status < 300)
+            return null;
+        return r.code ?? r.networkError ?? `HTTP ${r.status}`;
+    };
+}
+/**
+ * Run once per seat after its first accepted hello. `turnId` is interruptedTurnId of the transcript
+ * as it was at spawn (null: nothing to continue).
+ */
+export async function autoContinue(seat, turnId, d) {
+    if (turnId === null)
+        return "not_interrupted";
+    if (d.continued(seat.sessionId, turnId)) {
+        d.log(`auto-continue ${seat.sessionId}: turn ${turnId} already continued; not sending again`);
+        return "already_continued";
+    }
+    const deadline = d.now() + (d.readyTimeoutMs ?? PANE_READY_TIMEOUT_MS);
+    for (;;) {
+        const text = await d.capture(seat.tmuxSession);
+        if (text !== null && text.includes(PROMPT_MARK))
+            break;
+        if (text === null || d.now() >= deadline) {
+            d.log(`auto-continue ${seat.sessionId}: claude's prompt never showed; not sending`);
+            return "pane_not_ready";
+        }
+        await d.sleep(PANE_READY_POLL_MS);
+    }
+    try {
+        d.markContinued(seat.sessionId, turnId);
+    }
+    catch (e) {
+        d.log(`auto-continue ${seat.sessionId}: marker not written (${e.message}); not sending`);
+        return "marker_unwritable";
+    }
+    const refused = await d.journal(seat).catch((e) => e.message);
+    if (refused !== null) {
+        d.log(`auto-continue ${seat.sessionId}: turn ${turnId} was interrupted but turn_continued was not journaled (${refused}); not sending, and this turn will not be auto-continued`);
+        return "journal_refused";
+    }
+    await d.send(seat.tmuxSession, CONTINUE_TEXT);
+    d.log(`auto-continue ${seat.sessionId}: turn ${turnId} was interrupted; sent "${CONTINUE_TEXT}" once`);
+    return "sent";
+}

package/dist/host/bootid.d.ts

@@ -0,0 +1,13 @@
+export declare const BOOT_ID_IGNORED_WARNING = "mnemom agent host: DURABLE_BOOT_ID_FILE ignored (test mode off or a non-loopback API/gateway URL); using the OS boot id";
+export interface BootIdDeps {
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly sysctl: () => string;
+    readonly readFile: (p: string) => string;
+}
+export declare function osBootIdSysctl(): string;
+export declare const defaultBootIdDeps: () => BootIdDeps;
+/** The boot id and whether a T1 override was ignored (the caller warns). */
+export declare function resolveBootId(deps: BootIdDeps): {
+    bootId: string;
+    warn: boolean;
+};

package/dist/host/bootid.js

@@ -0,0 +1,41 @@
+/**
+ * The OS boot id the nonce is bound to (C12-R06, R26). macOS: sysctl kern.bootsessionuuid.
+ * T1 (DURABLE_BOOT_ID_FILE) is read only through the CLI test-mode module; when it is set but
+ * not honoured, the caller warns before any network call.
+ */
+import * as fs from "node:fs";
+import { execFileSync } from "node:child_process";
+import { bootIdFileOverride } from "../durable/test-mode.mjs";
+export const BOOT_ID_IGNORED_WARNING = "mnemom agent host: DURABLE_BOOT_ID_FILE ignored (test mode off or a non-loopback API/gateway URL); using the OS boot id";
+export function osBootIdSysctl() {
+    if (process.platform === "darwin") {
+        return execFileSync("/usr/sbin/sysctl", ["-n", "kern.bootsessionuuid"], {
+            encoding: "utf8",
+        }).trim();
+    }
+    // Linux (CI only): the kernel's per-boot uuid.
+    return fs.readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim();
+}
+export const defaultBootIdDeps = () => ({
+    env: process.env,
+    sysctl: osBootIdSysctl,
+    readFile: (p) => fs.readFileSync(p, "utf8"),
+});
+/** The boot id and whether a T1 override was ignored (the caller warns). */
+export function resolveBootId(deps) {
+    const o = bootIdFileOverride({ ...deps.env });
+    if (o.file) {
+        let v;
+        try {
+            v = deps.readFile(o.file).trim();
+        }
+        catch {
+            v = "";
+        }
+        // An unreadable or empty override is not a boot id: use the OS one.
+        if (v !== "")
+            return { bootId: v, warn: false };
+        return { bootId: deps.sysctl(), warn: false };
+    }
+    return { bootId: deps.sysctl(), warn: o.ignored };
+}

package/dist/host/client.d.ts

@@ -0,0 +1,123 @@
+import { type ClaimOutcome, type ClaimUnavailableCause } from "../vendor/shared/durable-contract/codes.js";
+/** The S1 claim outcomes that grant the lease (CLAIM_OUTCOME_STATUS 200). */
+export type ClaimSuccess = Extract<ClaimOutcome, "acquired" | "reclaimed" | "epoch_bump">;
+/** The header that carries the executor key (ruling 33.28(1); S1 EXECUTOR_KEY_HEADER once frozen). */
+export declare const EXECUTOR_KEY_HEADER = "X-Mnemom-Api-Key";
+export interface HttpResult {
+    readonly status: number;
+    readonly body: unknown;
+    /** The durable error code, when the body is `{error: {code}}` (or a bare `{code}`). */
+    readonly code: string | null;
+    /** Network failure (no HTTP status). */
+    readonly networkError?: string;
+}
+export type FetchFn = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+    signal?: AbortSignal;
+}) => Promise<{
+    status: number;
+    text(): Promise<string>;
+}>;
+export declare function errorCode(body: unknown): string | null;
+export declare function errorDetails(body: unknown): Record<string, unknown>;
+/**
+ * One poll item: only `id` is frozen (ruling 24.16); A3 sends {id, agent_id, state, state_reason,
+ * lease_epoch, lease_expires_at, held_here, cc_session_id, cwd, spec} (ruling 33.28.2), read
+ * defensively. spawn_id, hello and lease_seconds are never read from the poll: the first two are the
+ * daemon's own seat state, the last comes from the claim answer.
+ */
+export interface SessionItem {
+    readonly id: string;
+    readonly name: string | null;
+    readonly conversation_id: string | null;
+    readonly agent_id: string | null;
+    readonly state: string | null;
+    readonly state_reason: string | null;
+    readonly lease_epoch: number | null;
+    readonly lease_expires_at: string | null;
+    readonly cc_session_id: string | null;
+    readonly cwd: string | null;
+    readonly spec: Record<string, unknown> | null;
+    /** The lease is held by this executor (A3 lease_executor_id = me); null when the poll omits it. */
+    readonly held_here: boolean | null;
+}
+export declare function parseSessionItem(raw: unknown): SessionItem | null;
+/** One heartbeat entry: exactly S1 HEARTBEAT_ENTRY_FIELDS (ruling 33.28(2)). */
+export interface HeartbeatEntry {
+    readonly session_id: string;
+    readonly epoch: number;
+    readonly spawn_id: string;
+}
+/** The claim body (ruling 33.28(3)); new_key only on the retry after 409 durable_claim_needs_key. */
+export interface ClaimBody {
+    readonly nonce: string;
+    readonly tokens?: unknown;
+    readonly new_key?: true;
+}
+export interface ExecutorApi {
+    /** grantExpired: the lapsed-grant answer `{sessions: [], grant_expired: true}` (ruling 33.28(4)). */
+    sessions(): Promise<HttpResult & {
+        items: SessionItem[] | null;
+        grantExpired: boolean;
+    }>;
+    attest(sessionId: string, nonce: string): Promise<HttpResult>;
+    claim(sessionId: string, body: ClaimBody): Promise<HttpResult>;
+    append(sessionId: string, body: Record<string, unknown>): Promise<HttpResult>;
+    hello(sessionId: string, body: {
+        epoch: number;
+        nonce: string;
+        spawn_id: string;
+    }): Promise<HttpResult>;
+    seatExit(sessionId: string, body: {
+        epoch: number;
+        nonce: string;
+        spawn_id: string;
+        exit_status: number;
+        hello_accepted: boolean;
+    }): Promise<HttpResult>;
+    fail(sessionId: string, body: {
+        epoch: number;
+        nonce: string;
+        reason: "transcript_lost";
+    }): Promise<HttpResult>;
+    /** Exactly `{nonce, entries}`: the daemon's nonce once at the top level, none per entry (ruling 33.28.1). */
+    heartbeat(body: {
+        nonce: string;
+        entries: readonly HeartbeatEntry[];
+    }): Promise<HttpResult>;
+}
+export declare function executorApi(opts: {
+    apiUrl: string;
+    key: string;
+    fetch: FetchFn;
+    timeoutMs?: number;
+}): ExecutorApi;
+/** The claim's success fields (A1 durable_claim_lease plus the minted lease key, A3). */
+export interface ClaimOk {
+    readonly outcome: ClaimSuccess;
+    readonly epoch: number;
+    readonly leaseSeconds: number;
+    readonly leaseExpiresAt: number;
+    readonly leaseKey: string | null;
+    /**
+     * S1 amendment 54 (pending): the row was born locked by create-and-lock (B5a), so its CC session
+     * has no transcript yet. Read from the claim answer only; the poll item keys stay frozen.
+     */
+    readonly newSession: boolean;
+}
+export type ClaimDecision = {
+    kind: "ok";
+    claim: ClaimOk;
+}
+/** cause is null when the server names none, or one outside S1 CLAIM_UNAVAILABLE_CAUSES. */
+ | {
+    kind: "unavailable";
+    cause: ClaimUnavailableCause | null;
+} | {
+    kind: "none";
+    why: string;
+};
+/** Map a claim response to what the daemon does with it (C12-R14, R31). */
+export declare function classifyClaim(r: HttpResult, now: number): ClaimDecision;

package/dist/host/client.js

@@ -0,0 +1,171 @@
+/**
+ * The executor contract client (S1 ROUTES exec_*; BACKBONE A3). Every call carries the executor
+ * key in X-Mnemom-Api-Key and never sends Authorization (ruling 33.28(1)); nothing else on the host
+ * ever sees the key (C12-R27). Bodies follow S1 where S1 freezes them (heartbeat entries,
+ * executor.spawned refs and idempotency key, seat-exit fields, fail reason) and ruling 33.28 / A3
+ * elsewhere; response parsing is tolerant of extra fields.
+ */
+import { routePath } from "../vendor/shared/durable-contract/routes.js";
+import { CLAIM_OUTCOME_STATUS, CLAIM_UNAVAILABLE_CAUSES, } from "../vendor/shared/durable-contract/codes.js";
+import { LEASE_SECONDS_DEFAULT } from "../vendor/shared/durable-contract/constants.js";
+import { CODE } from "./s1-names.js";
+const isClaimSuccess = (v) => typeof v === "string" &&
+    Object.prototype.hasOwnProperty.call(CLAIM_OUTCOME_STATUS, v) &&
+    CLAIM_OUTCOME_STATUS[v] === 200;
+/** The header that carries the executor key (ruling 33.28(1); S1 EXECUTOR_KEY_HEADER once frozen). */
+export const EXECUTOR_KEY_HEADER = "X-Mnemom-Api-Key";
+export function errorCode(body) {
+    if (body && typeof body === "object") {
+        const b = body;
+        if (b.error &&
+            typeof b.error === "object" &&
+            typeof b.error.code === "string")
+            return b.error.code;
+        if (typeof b.error === "string")
+            return b.error;
+        if (typeof b.code === "string")
+            return b.code;
+    }
+    return null;
+}
+export function errorDetails(body) {
+    if (body && typeof body === "object") {
+        const e = body.error;
+        if (e && typeof e === "object") {
+            const d = e.details;
+            if (d && typeof d === "object")
+                return d;
+        }
+    }
+    return {};
+}
+const str = (v) => (typeof v === "string" && v !== "" ? v : null);
+const num = (v) => typeof v === "number" && Number.isFinite(v)
+    ? v
+    : typeof v === "string" && /^\d+$/.test(v)
+        ? Number(v)
+        : null;
+export function parseSessionItem(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return null;
+    const o = raw;
+    const id = str(o.id);
+    if (!id || !/^[0-9a-f-]{36}$/i.test(id))
+        return null;
+    const spec = o.spec && typeof o.spec === "object" && !Array.isArray(o.spec)
+        ? o.spec
+        : null;
+    return {
+        id: id.toLowerCase(),
+        name: str(o.name),
+        conversation_id: str(o.conversation_id),
+        agent_id: str(o.agent_id),
+        state: str(o.state),
+        state_reason: str(o.state_reason),
+        lease_epoch: num(o.lease_epoch ?? o.epoch),
+        lease_expires_at: str(o.lease_expires_at),
+        cc_session_id: str(o.cc_session_id),
+        cwd: str(o.cwd) ?? (spec ? str(spec.cwd) : null),
+        spec,
+        held_here: typeof o.held_here === "boolean" ? o.held_here : null,
+    };
+}
+export function executorApi(opts) {
+    const base = opts.apiUrl.replace(/\/+$/, "");
+    const call = async (route, id, method, body) => {
+        const url = `${base}${routePath(route, id)}`;
+        const ctl = new AbortController();
+        const timer = setTimeout(() => ctl.abort(), opts.timeoutMs ?? 15000);
+        try {
+            const res = await opts.fetch(url, {
+                method,
+                headers: {
+                    [EXECUTOR_KEY_HEADER]: opts.key,
+                    "content-type": "application/json",
+                    accept: "application/json",
+                },
+                ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+                signal: ctl.signal,
+            });
+            const text = await res.text();
+            let parsed = null;
+            try {
+                parsed = text ? JSON.parse(text) : null;
+            }
+            catch {
+                parsed = text;
+            }
+            return {
+                status: res.status,
+                body: parsed,
+                code: res.status >= 400 ? errorCode(parsed) : null,
+            };
+        }
+        catch (e) {
+            return { status: 0, body: null, code: null, networkError: e.message };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    };
+    return {
+        async sessions() {
+            const r = await call("exec_sessions", undefined, "GET");
+            let items = null;
+            let grantExpired = false;
+            if (r.status === 200 &&
+                r.body &&
+                typeof r.body === "object" &&
+                Array.isArray(r.body.sessions)) {
+                items = r.body.sessions
+                    .map(parseSessionItem)
+                    .filter((x) => x !== null);
+                grantExpired = r.body.grant_expired === true;
+            }
+            return { ...r, items, grantExpired };
+        },
+        attest: (id, nonce) => call("exec_attest", id, "POST", { nonce }),
+        claim: (id, body) => call("exec_claim", id, "POST", body),
+        append: (id, body) => call("exec_append", id, "POST", body),
+        hello: (id, body) => call("exec_hello", id, "POST", body),
+        seatExit: (id, body) => call("exec_seat_exit", id, "POST", body),
+        fail: (id, body) => call("exec_fail", id, "POST", body),
+        heartbeat: (body) => call("exec_heartbeat", undefined, "POST", body),
+    };
+}
+/** Map a claim response to what the daemon does with it (C12-R14, R31). */
+export function classifyClaim(r, now) {
+    if (r.status === 503 && (r.code === CODE.durable_claim_unavailable || r.code === null)) {
+        const cause = errorDetails(r.body).cause;
+        return {
+            kind: "unavailable",
+            cause: CLAIM_UNAVAILABLE_CAUSES.includes(cause)
+                ? cause
+                : null,
+        };
+    }
+    if (r.status === 200 && r.body && typeof r.body === "object") {
+        const b = r.body;
+        const outcome = b.outcome;
+        const epoch = num(b.epoch);
+        if (isClaimSuccess(outcome) && epoch !== null) {
+            const ls = num(b.lease_seconds) ?? LEASE_SECONDS_DEFAULT;
+            const exp = typeof b.lease_expires_at === "string" ? Date.parse(b.lease_expires_at) : NaN;
+            const key = str(b.lease_key) ?? str(b.key);
+            return {
+                kind: "ok",
+                claim: {
+                    outcome,
+                    epoch,
+                    leaseSeconds: ls,
+                    leaseExpiresAt: Number.isFinite(exp) ? exp : now + ls * 1000,
+                    leaseKey: key,
+                    newSession: b.new_session === true,
+                },
+            };
+        }
+    }
+    if (r.networkError)
+        return { kind: "none", why: `network: ${r.networkError}` };
+    return { kind: "none", why: r.code ?? `http ${r.status}` };
+}

package/dist/host/commands.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerHostCommands(agent: Command, hidden: boolean): Command;

package/dist/host/commands.js

@@ -0,0 +1,122 @@
+/**
+ * Registers `mnemom agent host …` (BACKBONE C2; S1 M1_CLI_SURFACE builder group C2) on the
+ * `agent` command. The whole group is hidden from help while durable is off at load, so the
+ * pre-M1 help text is unchanged (C17). Every verb refuses with the gated text, exit 2, before
+ * any side effect when durable is off (C12-R25); `run` applies its own carve-out (run.ts).
+ */
+import * as os from "node:os";
+import { CLI_VERSION } from "../version.js";
+import { getApiUrl } from "../lib/config.js";
+import { getAccessToken } from "../lib/auth.js";
+import { resolveBootId, defaultBootIdDeps } from "./bootid.js";
+import { realLaunchctl } from "./launchd.js";
+import { ownerApi, parseExecutorList } from "./owner.js";
+import { freshGate, hostInstall, hostEnroll, hostRenew, hostUninstall, } from "./verbs.js";
+import { collectStatus, printStatus, lsofPids, lsofListenPort, lsofUnixPaths } from "./status.js";
+import { hostRun, cliExec, resolveClaudeBin, homeTag } from "./run.js";
+import { Tmux, tmuxRunner } from "./tmux.js";
+import { psTable, alive, defaultProcDeps } from "./procs.js";
+import { resolveInstance } from "./instance.js";
+function verbIo(json) {
+    const env = process.env;
+    const owner = ownerApi({
+        apiUrl: getApiUrl(),
+        jwt: getAccessToken,
+        fetch: globalThis.fetch,
+    });
+    return {
+        env,
+        home: os.homedir(),
+        uid: os.userInfo().uid,
+        json,
+        out: (l) => console.log(l),
+        err: (l) => console.error(l),
+        owner,
+        launchctl: realLaunchctl,
+        now: () => Date.now(),
+        bootId: () => resolveBootId({ ...defaultBootIdDeps(), env }).bootId,
+        programArguments: () => [...cliExec(), "agent", "host", "run"],
+        claudeBin: () => resolveClaudeBin(env),
+    };
+}
+async function guarded(json, fn) {
+    const io = verbIo(json);
+    const g = freshGate(io);
+    if (g !== null) {
+        process.exitCode = g;
+        return;
+    }
+    try {
+        process.exitCode = await fn(io);
+    }
+    catch (e) {
+        console.error("Error:", e instanceof Error ? e.message : e);
+        process.exitCode = 1;
+    }
+}
+export function registerHostCommands(agent, hidden) {
+    const host = agent
+        .command("host", { hidden })
+        .description("Run locked durable sessions on this machine (experimental: `mnemom experimental enable durable`)");
+    host
+        .command("install")
+        .description("Enroll this machine (once) and install the host daemon as a user LaunchAgent")
+        .option("--json", "JSON lines output")
+        .action(async (o) => guarded(Boolean(o.json), hostInstall));
+    host
+        .command("enroll")
+        .description("Enroll this machine as an executor (device step); `install` does this when needed")
+        .action(async () => guarded(false, hostEnroll));
+    host
+        .command("renew")
+        .description("Renew this machine's executor grant (device step)")
+        .option("--json", "JSON lines output")
+        .action(async (o) => guarded(Boolean(o.json), hostRenew));
+    host
+        .command("uninstall")
+        .description("Unload the host daemon; seats keep running and the enrollment stays")
+        .action(async () => guarded(false, hostUninstall));
+    host
+        .command("status")
+        .description("Show the host daemon, its lock and its seats")
+        .option("--json", "Output as JSON")
+        .action(async (o) => guarded(Boolean(o.json), async (io) => {
+        const tmux = new Tmux(tmuxRunner(resolveInstance(io.env).tmuxSocket, io.env));
+        const s = await collectStatus({
+            env: io.env,
+            home: io.home,
+            uid: io.uid,
+            launchctl: io.launchctl,
+            panes: () => tmux.panes(),
+            ps: psTable,
+            lsofPids,
+            lsofListenPort,
+            lsofUnixPaths,
+            alive: (pid) => alive(defaultProcDeps(), pid),
+            executorRow: async (id) => {
+                const r = await io.owner.list();
+                return r.status === 200
+                    ? (parseExecutorList(r.body)?.find((x) => x.id === id) ?? null)
+                    : null;
+            },
+            homeTag: homeTag(io.home),
+            cliVersion: CLI_VERSION,
+            now: io.now,
+        });
+        printStatus(s, Boolean(o.json), io.out, io.err);
+        return 0;
+    }));
+    host
+        .command("run", { hidden: true })
+        .description("The host daemon (started by launchd)")
+        .action(async () => {
+        const code = await hostRun({
+            env: process.env,
+            home: os.homedir(),
+            err: (l) => console.error(l),
+        });
+        // Seats live on their own tmux server; nothing the daemon leaves open may keep it alive.
+        process.exit(code);
+    });
+    return host;
+}

package/dist/host/control.d.ts

@@ -0,0 +1,33 @@
+import * as net from "node:net";
+/** macOS sun_path is 104 bytes; keep a margin. */
+export declare const MAX_SOCKET_PATH = 100;
+/** A socket dir for this HOME: under the durable run dir when short enough, else a hashed /tmp dir. */
+export declare function socketDir(runDir: string, home: string, uid?: number): string;
+/**
+ * Create (or check) the control socket's directory: 0700 and owned by this uid. Under the /tmp
+ * fallback the predictable /tmp/mnm-host-<uid> parent gets the same check, so a directory another
+ * user created there first is refused rather than used. Throws when either is not ours.
+ */
+export declare function ensureSocketDir(dir: string, uid?: number): void;
+export declare const controlSocketPath: (dir: string) => string;
+export interface ControlHandlers {
+    takeLeaseKey(sessionId: string, spawnId: string): string | null;
+    relayHello(sessionId: string, spawnId: string): Promise<{
+        status: number;
+        body: unknown;
+    }>;
+}
+export declare function handleControl(h: ControlHandlers, line: string): Promise<Record<string, unknown>>;
+export declare function startControlServer(socket: string, h: ControlHandlers, log: (s: string) => void): net.Server;
+/** dev and inode of the socket file at `socket`, or null when there is none. */
+export declare function socketIdentity(socket: string): {
+    dev: number;
+    ino: number;
+} | null;
+/**
+ * Stop serving `socket`. Node unlinks a unix socket's path when its server closes, whoever owns
+ * the path by then, so the server is closed (and the path removed) only while the path is still
+ * the socket this server created. Otherwise another daemon has re-bound it: the server is only
+ * unref'd and the caller must leave with process.exit, which never unlinks.
+ */
+export declare function releaseControlSocket(srv: net.Server, socket: string): "closed" | "left";