@mnemom/mnemom 0.17.33 → 0.17.34-next.2

package/dist/host/control.js

@@ -0,0 +1,144 @@
+/**
+ * The daemon's control socket: the one channel between the daemon and the seat proxies it
+ * spawned (C3, `mnemom agent host seat-proxy`). Newline-delimited JSON, one request per
+ * connection, a 0600 unix socket in a 0700 directory. Ops:
+ *   {op:"seat_key", session_id, spawn_id} -> {ok:true, lease_key} once per spawn, then {ok:false}
+ *   {op:"hello",    session_id, spawn_id} -> {ok, status, body}: the daemon POSTs the executor hello
+ *                                            (the executor key never leaves the daemon, C12-R27)
+ * Anything else is refused locally.
+ */
+import * as fs from "node:fs";
+import * as net from "node:net";
+import * as path from "node:path";
+import * as os from "node:os";
+import { createHash } from "node:crypto";
+/** macOS sun_path is 104 bytes; keep a margin. */
+export 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 function socketDir(runDir, home, uid = os.userInfo().uid) {
+    if (path.join(runDir, "00000000.sock").length <= MAX_SOCKET_PATH)
+        return runDir;
+    const h = createHash("sha256").update(home).digest("hex").slice(0, 12);
+    return path.join("/tmp", `mnm-host-${uid}`, h);
+}
+/**
+ * One socket directory must be a real directory (not a symlink), owned by this uid, and 0700.
+ * The same check as seat-socket.ts's ensureSocketDir: throws when it is not.
+ */
+function checkOwnSocketDir(dir, uid) {
+    const st = fs.lstatSync(dir);
+    if (!st.isDirectory())
+        throw new Error("socket dir is not a directory");
+    if (st.uid !== uid)
+        throw new Error("socket dir is owned by another user");
+    if ((st.mode & 0o777) !== 0o700)
+        fs.chmodSync(dir, 0o700);
+}
+/**
+ * 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 function ensureSocketDir(dir, uid = os.userInfo().uid) {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const parent = path.dirname(dir);
+    if (parent.startsWith("/tmp/mnm-host-"))
+        checkOwnSocketDir(parent, uid);
+    checkOwnSocketDir(dir, uid);
+}
+export const controlSocketPath = (dir) => path.join(dir, "daemon.sock");
+const ID = /^[0-9a-f-]{36}$/i;
+export async function handleControl(h, line) {
+    let req;
+    try {
+        req = JSON.parse(line);
+    }
+    catch {
+        return { ok: false, error: "bad_request" };
+    }
+    const sid = typeof req.session_id === "string" && ID.test(req.session_id)
+        ? req.session_id.toLowerCase()
+        : null;
+    const spawn = typeof req.spawn_id === "string" && ID.test(req.spawn_id) ? req.spawn_id.toLowerCase() : null;
+    if (!sid || !spawn)
+        return { ok: false, error: "bad_request" };
+    if (req.op === "seat_key") {
+        const k = h.takeLeaseKey(sid, spawn);
+        return k ? { ok: true, lease_key: k } : { ok: false, error: "no_key" };
+    }
+    if (req.op === "hello") {
+        const r = await h.relayHello(sid, spawn);
+        return { ok: r.status === 200, status: r.status, body: r.body };
+    }
+    return { ok: false, error: "unknown_op" };
+}
+export function startControlServer(socket, h, log) {
+    fs.rmSync(socket, { force: true });
+    const srv = net.createServer((conn) => {
+        let buf = "";
+        conn.setTimeout(30000, () => conn.destroy());
+        conn.on("data", (d) => {
+            buf += d.toString("utf8");
+            if (buf.length > 64 * 1024)
+                return conn.destroy();
+            const i = buf.indexOf("\n");
+            if (i < 0)
+                return;
+            const line = buf.slice(0, i);
+            buf = "";
+            handleControl(h, line)
+                .then((res) => conn.end(`${JSON.stringify(res)}\n`))
+                .catch((e) => {
+                log(`control: ${e.message}`);
+                conn.end(`${JSON.stringify({ ok: false, error: "internal" })}\n`);
+            });
+        });
+        conn.on("error", () => { });
+    });
+    const old = process.umask(0o177);
+    try {
+        srv.listen(socket);
+    }
+    finally {
+        process.umask(old);
+    }
+    srv.on("listening", () => {
+        try {
+            fs.chmodSync(socket, 0o600);
+            boundSockets.set(srv, socketIdentity(socket));
+        }
+        catch {
+            /* raced with shutdown */
+        }
+    });
+    return srv;
+}
+/** dev and inode of the socket file at `socket`, or null when there is none. */
+export function socketIdentity(socket) {
+    try {
+        const st = fs.statSync(socket);
+        return st.isSocket() ? { dev: st.dev, ino: st.ino } : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The socket file each control server created, recorded when it started listening. */
+const boundSockets = new WeakMap();
+/**
+ * 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 function releaseControlSocket(srv, socket) {
+    const bound = boundSockets.get(srv) ?? null;
+    const now = socketIdentity(socket);
+    if (bound !== null && now !== null && bound.dev === now.dev && bound.ino === now.ino) {
+        srv.close();
+        fs.rmSync(socket, { force: true });
+        return "closed";
+    }
+    srv.unref();
+    return "left";
+}

package/dist/host/daemon.d.ts

@@ -0,0 +1,217 @@
+import type { ClaimUnavailableCause } from "../vendor/shared/durable-contract/codes.js";
+import { type ExecutorApi, type SessionItem } from "./client.js";
+import { type SeatPane } from "./tmux.js";
+export declare const TICK_MS = 1000;
+export declare const ADOPT_RETRY_MS = 2000;
+export { SPAWNED_KIND } from "./s1-names.js";
+export declare const spawnIdempotencyKey: (sessionId: string, epoch: number, spawnId: string) => string;
+export type PausePoint = "after_claim_before_spawn" | "after_spawn_before_register" | "after_register_before_hello" | "after_first_batch";
+/** One seat this daemon holds (spawned or adopted). */
+export interface Seat {
+    readonly sessionId: string;
+    readonly name: string | null;
+    readonly epoch: number;
+    readonly spawnId: string;
+    readonly tmuxSession: string;
+    panePid: number | null;
+    /** The claude pid once seen under the pane; liveness is judged by it (R19). */
+    claudePid: number | null;
+    /** When the claude pid was first seen gone while the pane still ran (proxy lingering). */
+    claudeGoneAt: number | null;
+    helloAccepted: boolean;
+    registered: boolean;
+    /** Hello deadline (ms epoch) while not hello'd: the claim's lease expiry (R17). */
+    deadline: number;
+    leaseSeconds: number;
+    lastHeartbeat: number;
+    /** One-time lease key handoff to the seat proxy; cleared once taken. */
+    leaseKey: string | null;
+    specPath: string | null;
+    adopted: boolean;
+    /** The transcript's interrupted turn when this seat was spawned, or null (auto-continue). */
+    interruptedTurn: string | null;
+}
+export interface SpawnRequest {
+    readonly item: SessionItem;
+    readonly epoch: number;
+    readonly spawnId: string;
+    readonly tmuxSession: string;
+    /** Null for a born-locked session's first spawn (B5a): no transcript exists yet. */
+    readonly transcriptPath: string | null;
+    /** B5a: start the CC session fresh under its id (--session-id) instead of resuming it. */
+    readonly newSession: boolean;
+}
+export interface DaemonDeps {
+    readonly api: ExecutorApi;
+    readonly nonce: string;
+    readonly home: string;
+    readonly now: () => number;
+    readonly random: () => number;
+    readonly log: (line: string) => void;
+    /** Durable gate from config.json only (R39). */
+    readonly gateOn: () => boolean;
+    /** Plugin integrity of the installed package (R36). */
+    readonly integrity: () => Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        cause: string;
+    }>;
+    /** This daemon's tagged panes (only panes tagged with this HOME). */
+    readonly panes: () => Promise<SeatPane[]>;
+    /** The claude pid under a pane (null when claude is not running). */
+    readonly claudePid: (panePid: number) => number | null;
+    readonly alive: (pid: number) => boolean;
+    /** Kill the pane's whole process tree and its tmux session. */
+    readonly killSeat: (tmuxSession: string, panePid: number | null) => Promise<void>;
+    /** Spawn a seat in tmux; returns the pane pid and the launch-spec path. */
+    readonly spawnSeat: (req: SpawnRequest) => Promise<{
+        panePid: number;
+        specPath: string;
+    }>;
+    /** Transcript guard: refresh for an item; returns the transcript path now on disk (or null). */
+    readonly guard: (item: SessionItem) => string | null;
+    /** Before --resume: present, restored from the guard, or lost. */
+    readonly ensureTranscript: (item: SessionItem) => {
+        kind: "present" | "restored";
+        path: string;
+    } | {
+        kind: "lost";
+    };
+    readonly removeGuard: (sessionId: string) => void;
+    readonly guardedIds: () => string[];
+    /** T2 test pause point (null when not in test mode). */
+    readonly pauseAt: PausePoint | null;
+    /** Blocks forever (T2): the harness kills the daemon here. */
+    readonly pause: (point: PausePoint) => Promise<never>;
+    /** Persist status facts (no secret) for `host status`. */
+    readonly publish: (snapshot: DaemonSnapshot) => void;
+    /** interruptedTurnId of the transcript at `path` (null when unreadable). */
+    readonly interruptedAt?: (path: string) => string | null;
+    /** The one continue of an interrupted turn after a seat's first accepted hello (host/auto-continue.ts). */
+    readonly autoContinue?: (seat: {
+        sessionId: string;
+        tmuxSession: string;
+        epoch: number;
+        spawnId: string;
+    }, turnId: string | null) => Promise<unknown>;
+}
+export interface UnavailableInfo {
+    cause: ClaimUnavailableCause | null;
+    count: number;
+    nextAt: number;
+}
+export interface DaemonSnapshot {
+    readonly pid: number;
+    readonly state: "running" | "idle";
+    readonly integrity: {
+        ok: true;
+    } | {
+        ok: false;
+        cause: string;
+    };
+    readonly seats: readonly {
+        session_id: string;
+        name: string | null;
+        epoch: number;
+        spawn_id: string;
+        tmux_session: string;
+        pane_pid: number | null;
+        hello: boolean;
+        spec_path: string | null;
+    }[];
+    readonly sessions: readonly {
+        id: string;
+        name: string | null;
+        state: string | null;
+        state_reason: string | null;
+    }[];
+    readonly unavailable: Readonly<Record<string, {
+        cause: ClaimUnavailableCause | null;
+        count: number;
+    }>>;
+    readonly updated_at: string;
+}
+/** S1 claim backoff: 2 s doubling to 60 s, scaled by 1 + jitter in [0, CLAIM_BACKOFF_JITTER) (R31). */
+export declare function backoffMs(count: number, random: () => number): number;
+/** Heartbeat period from the server's lease (R18): lease_seconds / HEARTBEAT_DIVISOR. */
+export declare const heartbeatPeriodMs: (leaseSeconds: number) => number;
+/**
+ * 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 declare function adoptedLeaseSeconds(item: SessionItem, now: number): number;
+export type AdoptVerdict = {
+    adopt: true;
+    hello: boolean;
+} | {
+    adopt: false;
+    why: string;
+};
+/**
+ * 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 declare function adoptVerdict(pane: SeatPane, item: SessionItem | undefined, now: number, panAlive: boolean, seenSessions: ReadonlySet<string>): AdoptVerdict;
+/** How long a pane may outlive its claude before the exit is reported without the pane's status. */
+export declare const CLAUDE_GONE_GRACE_MS = 3000;
+export type Liveness = {
+    kind: "alive";
+} | {
+    kind: "dead";
+    status: number;
+};
+/**
+ * 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 declare function seatLiveness(seat: Seat, pane: SeatPane | undefined, now: number, claudePid: (panePid: number) => number | null, alive: (pid: number) => boolean): Liveness;
+/** Exit status as the seat-exit route takes it (0..255); a missing status is a failure. */
+export declare const exitStatusOf: (pane: SeatPane | undefined) => number;
+export declare class HostDaemon {
+    private readonly d;
+    readonly seats: Map<string, Seat>;
+    readonly unavailable: Map<string, UnavailableInfo>;
+    private lastPoll;
+    private adoptDone;
+    private idleLogged;
+    private items;
+    private integrityState;
+    /** The cause claims were last held for, so the log names each change once (mnemom-test #981). */
+    private heldFor;
+    private firstBatchDone;
+    private stopped;
+    /** The last poll said the grant lapsed (ruling 33.28(4)); logged once per transition. */
+    private grantExpired;
+    constructor(d: DaemonDeps);
+    stop(): void;
+    /** One pass of the loop. Returns what it did (for tests and logs). */
+    tick(): Promise<string[]>;
+    /** Run until stop(): one tick every TICK_MS. */
+    run(sleep: (ms: number) => Promise<void>): Promise<void>;
+    private syncGuards;
+    private adoptOrKill;
+    private checkSeats;
+    private reportExit;
+    private heartbeat;
+    private inFlight;
+    private claimWave;
+    private claimable;
+    private claimAndSpawn;
+    /** The one-time lease-key handoff to the seat proxy of `spawnId` (C3). */
+    takeLeaseKey(sessionId: string, spawnId: string): string | null;
+    /**
+     * 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.
+     */
+    relayHello(sessionId: string, spawnId: string): Promise<{
+        status: number;
+        body: unknown;
+    }>;
+    private publish;
+}