@mnemom/mnemom 0.17.33 → 0.17.34-next.2

package/dist/host/gate.js

@@ -0,0 +1,82 @@
+/**
+ * The host daemon's durable gate (C12-R25, R39, R40; BACKBONE Flags (CLI) carve-out).
+ *
+ * Fresh `mnemom agent host …` verbs resolve the gate like every other command (config.json and
+ * MNEMOM_EXPERIMENTAL). The daemon (`host run`) and `host install` resolve it from config.json
+ * only: the plist and the launchd domain never decide it.
+ */
+import * as fs from "node:fs";
+import { resolveExperimental, gatedMessage } from "../lib/experimental.js";
+import { FIX_LINES, renderFixLine } from "../vendor/shared/durable-contract/fixlines.js";
+import { resolveInstance, hostPaths } from "./instance.js";
+import { readExecutorState } from "./state.js";
+export const DURABLE_ID = "durable";
+export const HOST_WHAT = "`mnemom agent host`";
+export const GATED_TEXT = gatedMessage(HOST_WHAT, DURABLE_ID);
+/** The enable command (S1 FIX_LINES.daemon_idle body). */
+export const ENABLE_FIX = FIX_LINES.daemon_idle.body;
+/** C12-R40: durable on only through the shell. */
+export const INSTALL_SHELL_ONLY_TEXT = `the host daemon reads your config, not this shell: ${ENABLE_FIX}`;
+/** C12-R39: the idle line (status and the launcher). */
+export const IDLE_TEXT = FIX_LINES.daemon_idle.lead.replace(/: $/, "");
+/** The idle line with its fix, rendered from S1 (C12-R39). */
+export const IDLE_FIX = renderFixLine("daemon_idle", {
+    launcherKey: "always",
+    nameHeld: false,
+    params: {},
+});
+export const IDLE_LOG = "durable disabled: idle";
+/** config.json's experimental block, read fresh (a missing or corrupt file is off). */
+export function readStoredExperimental(configFile) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(configFile, "utf8"));
+        return raw && typeof raw === "object" ? raw.experimental : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The daemon gate: config.json only, env ignored (C12-R39). */
+export function durableOnInConfig(configFile) {
+    return resolveExperimental({
+        stored: readStoredExperimental(configFile),
+        env: {},
+    }).enabled.includes(DURABLE_ID);
+}
+/** The fresh-invocation gate: config.json and the environment (C12-R25). */
+export function durableOnFresh(configFile, env) {
+    return resolveExperimental({
+        stored: readStoredExperimental(configFile),
+        env: { ...env },
+    }).enabled.includes(DURABLE_ID);
+}
+/** `host install`: off everywhere -> exit 2 gated; on only in the shell -> exit 1 (R40); on in config -> ok. */
+export function installGate(configFile, env) {
+    if (durableOnInConfig(configFile))
+        return { ok: true };
+    if (durableOnFresh(configFile, env))
+        return { ok: false, exit: 1, message: INSTALL_SHELL_ONLY_TEXT };
+    return { ok: false, exit: 2, message: GATED_TEXT };
+}
+/**
+ * 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 function hostArgvGate(argv, ctx) {
+    if (argv[0] !== "agent" || argv[1] !== "host")
+        return null;
+    const paths = hostPaths(ctx.home, resolveInstance(ctx.env));
+    const gated = { code: 2, message: GATED_TEXT };
+    if (argv[2] === "run") {
+        if (durableOnInConfig(paths.configFile))
+            return null;
+        return readExecutorState(paths.stateFile).kind === "absent" ? gated : null;
+    }
+    return durableOnFresh(paths.configFile, ctx.env) ? null : gated;
+}

package/dist/host/grant.d.ts

@@ -0,0 +1,24 @@
+/** The renew command (S1 FIX_LINES.grant_expired). */
+export declare const RENEW_FIX: string;
+/** An expired grant, with the S1 renew fix. */
+export declare const GRANT_EXPIRED_LINE: string;
+/** The grant as status keeps it (no rendered copy). */
+export type GrantView = {
+    state: "ok";
+} | {
+    state: "warning";
+    days: number;
+} | {
+    state: "expired";
+};
+export type GrantStatus = {
+    state: "ok";
+} | {
+    state: "warning";
+    days: number;
+    line: string;
+} | {
+    state: "expired";
+};
+/** ok above the S1 warning window (or with no known end), warning inside it, expired at or after the end. */
+export declare function grantStatus(grantExpiresAtMs: number | null, nowMs: number): GrantStatus;

package/dist/host/grant.js

@@ -0,0 +1,24 @@
+/**
+ * The executor grant as `host status` and `host install` report it (C04-R18, C12-R22). The
+ * warning window, the day count and both fix lines come from S1; only the expired line's lead
+ * is C2 copy.
+ */
+import { renderFixLine, grantWarningDays, } from "../vendor/shared/durable-contract/fixlines.js";
+import { GRANT_WARNING_S } from "../vendor/shared/durable-contract/constants.js";
+const fix = (key, params = {}) => renderFixLine(key, { launcherKey: "always", nameHeld: false, params });
+/** The renew command (S1 FIX_LINES.grant_expired). */
+export const RENEW_FIX = fix("grant_expired");
+/** An expired grant, with the S1 renew fix. */
+export const GRANT_EXPIRED_LINE = `this machine's grant has expired: ${RENEW_FIX}`;
+/** ok above the S1 warning window (or with no known end), warning inside it, expired at or after the end. */
+export function grantStatus(grantExpiresAtMs, nowMs) {
+    if (grantExpiresAtMs === null)
+        return { state: "ok" };
+    const remaining = (grantExpiresAtMs - nowMs) / 1000;
+    if (!(remaining > 0))
+        return { state: "expired" };
+    const days = grantWarningDays(remaining, GRANT_WARNING_S);
+    if (days === null)
+        return { state: "ok" };
+    return { state: "warning", days, line: fix("grant_warning", { days: String(days) }) };
+}

package/dist/host/instance.d.ts

@@ -0,0 +1,35 @@
+export declare const DEFAULT_INSTANCE = "ai.mnemom.agent-host.default";
+export interface HostInstance {
+    /** The launchd label; also the `instance` field of host status. */
+    readonly label: string;
+    /** tmux -L socket name. */
+    readonly tmuxSocket: string;
+}
+export declare class InstanceNameError extends Error {
+}
+export declare function resolveInstance(env: Readonly<Record<string, string | undefined>>): HostInstance;
+/** Every path the host daemon and its verbs use, under one HOME. */
+export interface HostPaths {
+    readonly home: string;
+    /** ~/.mnemom */
+    readonly mnemomDir: string;
+    /** ~/.mnemom/durable (0700) */
+    readonly durableDir: string;
+    /** S1 EXECUTOR_STATE_FILE */
+    readonly stateFile: string;
+    /** The single-instance lock: a separate, never-renamed file (C12-R03). */
+    readonly lockFile: string;
+    /** ~/.mnemom/config.json, the only source of the daemon's durable gate (C12-R39). */
+    readonly configFile: string;
+    readonly logDir: string;
+    /** Per-seat launch-spec files (host status spec_path). */
+    readonly specDir: string;
+    /** S1 transcript guard dir. */
+    readonly transcriptDir: string;
+    /** Short-lived daemon runtime files (control socket). */
+    readonly runDir: string;
+    /** Daemon runtime facts for host status (no secret). */
+    readonly runtimeFile: string;
+    readonly plistFile: string;
+}
+export declare function hostPaths(home: string, instance: HostInstance): HostPaths;

package/dist/host/instance.js

@@ -0,0 +1,62 @@
+/**
+ * The host instance (C12-R04): its name (the launchd label), its tmux socket name and every
+ * path the daemon owns, all pure functions of HOME and the environment. The instance name is
+ * read from config/env, never from the executor state file, so a copied state file does not
+ * carry another host's instance.
+ *
+ * Resolution, first match wins:
+ *  - MNEMOM_HOST_INSTANCE: the label itself; the tmux socket is MNEMOM_HOST_TMUX_SOCKET or
+ *    `mnm-host-<last label segment>`.
+ *  - MNEMOM_HOST_TMUX_SOCKET `mnm-host-<L>` (the local eval lanes): label
+ *    `com.mnemom.durable.dev.<L>`; any other socket name: label `ai.mnemom.agent-host.<socket>`.
+ *  - neither, or the default socket `mnm-host-default` named explicitly: label
+ *    `ai.mnemom.agent-host.default`, socket `mnm-host-default` (the default round-trips).
+ */
+import * as path from "node:path";
+import { DURABLE_DIR, EXECUTOR_STATE_FILE } from "../vendor/shared/durable-contract/paths.js";
+export const DEFAULT_INSTANCE = "ai.mnemom.agent-host.default";
+const DEFAULT_TMUX_SOCKET = "mnm-host-default";
+const NAME_RE = /^[A-Za-z0-9._-]{1,100}$/;
+const LANE_SOCKET_RE = /^mnm-host-([A-Za-z0-9._-]+)$/;
+export class InstanceNameError extends Error {
+}
+function checkName(kind, v) {
+    if (!NAME_RE.test(v))
+        throw new InstanceNameError(`${kind} must match ${NAME_RE}: ${JSON.stringify(v)}`);
+    return v;
+}
+export function resolveInstance(env) {
+    const label = env.MNEMOM_HOST_INSTANCE?.trim() || undefined;
+    const sock = env.MNEMOM_HOST_TMUX_SOCKET?.trim() || undefined;
+    if (label) {
+        checkName("MNEMOM_HOST_INSTANCE", label);
+        const tail = label.split(".").pop() || "default";
+        return { label, tmuxSocket: checkName("MNEMOM_HOST_TMUX_SOCKET", sock ?? `mnm-host-${tail}`) };
+    }
+    if (sock && sock !== DEFAULT_TMUX_SOCKET) {
+        checkName("MNEMOM_HOST_TMUX_SOCKET", sock);
+        const lane = LANE_SOCKET_RE.exec(sock);
+        return {
+            label: lane ? `com.mnemom.durable.dev.${lane[1]}` : `ai.mnemom.agent-host.${sock}`,
+            tmuxSocket: sock,
+        };
+    }
+    return { label: DEFAULT_INSTANCE, tmuxSocket: DEFAULT_TMUX_SOCKET };
+}
+export function hostPaths(home, instance) {
+    const durableDir = path.join(home, DURABLE_DIR);
+    return {
+        home,
+        mnemomDir: path.join(home, ".mnemom"),
+        durableDir,
+        stateFile: path.join(home, EXECUTOR_STATE_FILE),
+        lockFile: path.join(durableDir, "host.lock"),
+        configFile: path.join(home, ".mnemom", "config.json"),
+        logDir: path.join(durableDir, "logs"),
+        specDir: path.join(durableDir, "specs"),
+        transcriptDir: path.join(durableDir, "transcripts"),
+        runDir: path.join(durableDir, "run"),
+        runtimeFile: path.join(durableDir, "run", "daemon.json"),
+        plistFile: path.join(home, "Library", "LaunchAgents", `${instance.label}.plist`),
+    };
+}

package/dist/host/integrity.d.ts

@@ -0,0 +1,35 @@
+import { type PluginDirEntry, type PluginManifest, type PluginManifestFailure } from "../vendor/shared/durable-contract/spec.js";
+/** The package root that holds PLUGIN_DIR, from a resolved plugin dir. */
+export declare function packageRootOf(pluginDir: string): string;
+/**
+ * The bytes of `abs` when it is a regular file, else null. The open refuses a symlink
+ * (O_NOFOLLOW), and the type check and the read use that one descriptor, so the file that is
+ * checked is the file that is read even if the path is swapped in between. O_NONBLOCK keeps a
+ * FIFO from blocking the open.
+ */
+export declare function readRegularFile(abs: string): Buffer | null;
+/**
+ * Directories, relative to PLUGIN_DIR, that Claude Code writes into the loaded plugin at runtime
+ * (mnemom-test #981): `.claude-plugin/types/` holds the editor type stubs it lays when it loads
+ * the plugin (also cli/plugins/.gitignore). The walk skips only a real directory at exactly
+ * this path, on both sides (the pack-time generator and the daemon's pre-claim check), so a
+ * symlink or a file named `.claude-plugin/types`, or a `types/` dir anywhere else, is still
+ * walked and still fails the check.
+ */
+export declare const RUNTIME_WRITTEN_DIRS: readonly string[];
+/**
+ * Every non-directory entry under `dir`, POSIX-relative, symlinks and specials as non-regular,
+ * except under RUNTIME_WRITTEN_DIRS.
+ */
+export declare function walkPluginDir(dir: string, exclude?: (rel: string) => boolean): PluginDirEntry[];
+export declare function buildManifest(entries: readonly PluginDirEntry[]): Promise<PluginManifest>;
+export type IntegrityResult = {
+    ok: true;
+} | {
+    ok: false;
+    cause: PluginManifestFailure | "no_plugin_dir";
+};
+/** Verify the installed plugin dir of the package rooted at `pkgRoot`. */
+export declare function checkIntegrity(pkgRoot: string): Promise<IntegrityResult>;
+/** The host status line for a failed check (BACKBONE C2; C12-R36). */
+export declare function integrityFailureLine(cliVersion: string): string;

package/dist/host/integrity.js

@@ -0,0 +1,115 @@
+/**
+ * Plugin integrity (C12-R36; ruling 25; BACKBONE C2 "Plugin integrity"). Before each claim the
+ * daemon resolves the plugin dir from its own installed package and verifies it against the
+ * package's shipped manifest (S1 PLUGIN_MANIFEST_PATH, dir-hash recipe). The pack-time generator
+ * (scripts/gen-integrity-manifest.mjs) uses buildManifest from this module, so the writer and the
+ * reader share one recipe.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { createHash } from "node:crypto";
+import { PLUGIN_DIR, PLUGIN_MANIFEST_PATH, pluginDirHash, verifyPluginManifest, } from "../vendor/shared/durable-contract/spec.js";
+import { PLUGIN_HASH_RECIPE_VERSION } from "../vendor/shared/durable-contract/constants.js";
+/** The package root that holds PLUGIN_DIR, from a resolved plugin dir. */
+export function packageRootOf(pluginDir) {
+    return path.resolve(pluginDir, "..", "..");
+}
+/**
+ * The bytes of `abs` when it is a regular file, else null. The open refuses a symlink
+ * (O_NOFOLLOW), and the type check and the read use that one descriptor, so the file that is
+ * checked is the file that is read even if the path is swapped in between. O_NONBLOCK keeps a
+ * FIFO from blocking the open.
+ */
+export function readRegularFile(abs) {
+    const c = fs.constants;
+    let fd;
+    try {
+        fd = fs.openSync(abs, c.O_RDONLY | (c.O_NOFOLLOW ?? 0) | (c.O_NONBLOCK ?? 0));
+    }
+    catch (e) {
+        if (e.code === "ELOOP")
+            return null;
+        throw e;
+    }
+    try {
+        if (!fs.fstatSync(fd).isFile())
+            return null;
+        return fs.readFileSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/**
+ * Directories, relative to PLUGIN_DIR, that Claude Code writes into the loaded plugin at runtime
+ * (mnemom-test #981): `.claude-plugin/types/` holds the editor type stubs it lays when it loads
+ * the plugin (also cli/plugins/.gitignore). The walk skips only a real directory at exactly
+ * this path, on both sides (the pack-time generator and the daemon's pre-claim check), so a
+ * symlink or a file named `.claude-plugin/types`, or a `types/` dir anywhere else, is still
+ * walked and still fails the check.
+ */
+export const RUNTIME_WRITTEN_DIRS = [".claude-plugin/types"];
+/**
+ * Every non-directory entry under `dir`, POSIX-relative, symlinks and specials as non-regular,
+ * except under RUNTIME_WRITTEN_DIRS.
+ */
+export function walkPluginDir(dir, exclude = () => false) {
+    const out = [];
+    const walk = (abs, rel) => {
+        for (const name of fs.readdirSync(abs)) {
+            const a = path.join(abs, name);
+            const r = rel ? `${rel}/${name}` : name;
+            const st = fs.lstatSync(a);
+            if (st.isDirectory()) {
+                if (RUNTIME_WRITTEN_DIRS.includes(r))
+                    continue;
+                walk(a, r);
+                continue;
+            }
+            if (exclude(r))
+                continue;
+            const bytes = st.isFile() ? readRegularFile(a) : null;
+            if (bytes !== null)
+                out.push({
+                    path: r,
+                    sha256: createHash("sha256").update(bytes).digest("hex"),
+                    regular: true,
+                });
+            else
+                out.push({ path: r, sha256: null, regular: false });
+        }
+    };
+    walk(dir, "");
+    return out.sort((x, y) => (x.path < y.path ? -1 : x.path > y.path ? 1 : 0));
+}
+export async function buildManifest(entries) {
+    const files = entries.map((e) => {
+        if (!e.regular || e.sha256 === null)
+            throw new Error(`plugin entry ${e.path} is not a regular file`);
+        return { path: e.path, sha256: e.sha256 };
+    });
+    return {
+        recipe_version: PLUGIN_HASH_RECIPE_VERSION,
+        plugin_dir: PLUGIN_DIR,
+        files,
+        dir_hash: await pluginDirHash(files),
+    };
+}
+/** Verify the installed plugin dir of the package rooted at `pkgRoot`. */
+export async function checkIntegrity(pkgRoot) {
+    const dir = path.join(pkgRoot, PLUGIN_DIR);
+    if (!fs.existsSync(dir))
+        return { ok: false, cause: "no_plugin_dir" };
+    let text;
+    try {
+        text = fs.readFileSync(path.join(pkgRoot, PLUGIN_MANIFEST_PATH), "utf8");
+    }
+    catch {
+        text = null;
+    }
+    return verifyPluginManifest(text, walkPluginDir(dir));
+}
+/** The host status line for a failed check (BACKBONE C2; C12-R36). */
+export function integrityFailureLine(cliVersion) {
+    return `installed CLI fails its integrity check: \`npm i -g @mnemom/mnemom@${cliVersion}\``;
+}

package/dist/host/launchd.d.ts

@@ -0,0 +1,16 @@
+export interface LaunchctlResult {
+    readonly code: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export type Launchctl = (args: readonly string[]) => Promise<LaunchctlResult>;
+export declare const realLaunchctl: Launchctl;
+export declare const guiDomain: (uid: number) => string;
+export declare const serviceTarget: (uid: number, label: string) => string;
+export declare function printJob(lc: Launchctl, uid: number, label: string): Promise<{
+    loaded: boolean;
+    pid: number | null;
+}>;
+/** Load (or reload) the job from its plist: bootout when loaded, then bootstrap. One job per label. */
+export declare function loadJob(lc: Launchctl, uid: number, label: string, plistFile: string): Promise<LaunchctlResult>;
+export declare function unloadJob(lc: Launchctl, uid: number, label: string): Promise<boolean>;

package/dist/host/launchd.js

@@ -0,0 +1,45 @@
+/**
+ * launchctl, scoped to the host instance's own label in the user's gui domain. Never touches
+ * any other job (BACKBONE C2; lane labels com.mnemom.durable.dev.<L>).
+ */
+import { execFile } from "node:child_process";
+import { setTimeout as sleep } from "node:timers/promises";
+export const realLaunchctl = (args) => new Promise((resolve) => {
+    execFile("/bin/launchctl", [...args], { env: { PATH: "/usr/bin:/bin:/usr/sbin:/sbin" }, timeout: 30000 }, (err, stdout, stderr) => {
+        const code = err
+            ? typeof err.code === "number"
+                ? err.code
+                : 1
+            : 0;
+        resolve({ code, stdout: String(stdout), stderr: String(stderr) });
+    });
+});
+export const guiDomain = (uid) => `gui/${uid}`;
+export const serviceTarget = (uid, label) => `${guiDomain(uid)}/${label}`;
+export async function printJob(lc, uid, label) {
+    const r = await lc(["print", serviceTarget(uid, label)]);
+    if (r.code !== 0)
+        return { loaded: false, pid: null };
+    const m = /\bpid = (\d+)/.exec(r.stdout);
+    return { loaded: true, pid: m ? Number(m[1]) : null };
+}
+/** Load (or reload) the job from its plist: bootout when loaded, then bootstrap. One job per label. */
+export async function loadJob(lc, uid, label, plistFile) {
+    const st = await printJob(lc, uid, label);
+    if (st.loaded)
+        await lc(["bootout", serviceTarget(uid, label)]);
+    // bootout completes asynchronously: a bootstrap racing it fails with EIO (5); retry briefly.
+    let r = await lc(["bootstrap", guiDomain(uid), plistFile]);
+    for (let i = 0; i < 20 && r.code !== 0 && st.loaded; i++) {
+        await sleep(250);
+        r = await lc(["bootstrap", guiDomain(uid), plistFile]);
+    }
+    return r;
+}
+export async function unloadJob(lc, uid, label) {
+    const st = await printJob(lc, uid, label);
+    if (!st.loaded)
+        return false;
+    await lc(["bootout", serviceTarget(uid, label)]);
+    return true;
+}

package/dist/host/lock.d.ts

@@ -0,0 +1,20 @@
+export type LockResult = {
+    ok: true;
+    fd: number;
+} | {
+    ok: false;
+    reason: "held" | "unsupported" | "error";
+    message: string;
+};
+export declare function lockSupported(platform?: NodeJS.Platform): boolean;
+/**
+ * Take the lock or report why not. Never blocks. The fd must stay open for the process lifetime
+ * (closing it releases the lock).
+ */
+export declare function acquireHostLock(lockFile: string, platform?: NodeJS.Platform): LockResult;
+/**
+ * Whether `fd` still locks the file at `lockFile`. A lock file deleted or replaced under a running
+ * daemon (an `rm -rf` of the state dir) leaves it holding a lock on an unlinked inode, so a second
+ * daemon can take the new file; the first must notice and stop rather than run beside it.
+ */
+export declare function lockStillHeld(fd: number, lockFile: string): boolean;

package/dist/host/lock.js

@@ -0,0 +1,63 @@
+/**
+ * The single-instance lock (C12-R01..R04): a kernel lock on a separate, never-renamed lock file
+ * in the state dir. macOS open(2) O_EXLOCK|O_NONBLOCK takes a flock(2) lock atomically with the
+ * open; the kernel drops it when the holder dies (kill -9), and a SIGSTOPped holder keeps it. No
+ * staleness timeout, no pid file.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+/** <sys/fcntl.h> on Darwin. Node does not export these. */
+const O_EXLOCK_DARWIN = 0x20;
+const O_NONBLOCK_DARWIN = 0x4;
+export function lockSupported(platform = process.platform) {
+    return platform === "darwin";
+}
+/**
+ * Take the lock or report why not. Never blocks. The fd must stay open for the process lifetime
+ * (closing it releases the lock).
+ */
+export function acquireHostLock(lockFile, platform = process.platform) {
+    if (!lockSupported(platform)) {
+        return {
+            ok: false,
+            reason: "unsupported",
+            message: `the host daemon runs on macOS only (platform ${platform})`,
+        };
+    }
+    try {
+        fs.mkdirSync(path.dirname(lockFile), { recursive: true, mode: 0o700 });
+        const flags = fs.constants.O_RDWR | fs.constants.O_CREAT | O_EXLOCK_DARWIN | O_NONBLOCK_DARWIN;
+        const fd = fs.openSync(lockFile, flags, 0o600);
+        return { ok: true, fd };
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === "EAGAIN" || code === "EWOULDBLOCK") {
+            return {
+                ok: false,
+                reason: "held",
+                message: `another mnemom agent host daemon holds ${lockFile}`,
+            };
+        }
+        return {
+            ok: false,
+            reason: "error",
+            message: `cannot open ${lockFile}: ${e.message}`,
+        };
+    }
+}
+/**
+ * Whether `fd` still locks the file at `lockFile`. A lock file deleted or replaced under a running
+ * daemon (an `rm -rf` of the state dir) leaves it holding a lock on an unlinked inode, so a second
+ * daemon can take the new file; the first must notice and stop rather than run beside it.
+ */
+export function lockStillHeld(fd, lockFile) {
+    try {
+        const held = fs.fstatSync(fd);
+        const now = fs.statSync(lockFile);
+        return held.ino === now.ino && held.dev === now.dev;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/host/owner.d.ts

@@ -0,0 +1,55 @@
+import { type FetchFn } from "./client.js";
+export declare const EXECUTOR_CONTRACT = "durable-executor/v1";
+export interface OwnerHttp {
+    readonly status: number;
+    readonly body: unknown;
+    readonly networkError?: string;
+}
+export interface OwnerApi {
+    enrollStart(body: {
+        kind: "host";
+        runtime: string;
+        contract_version: string;
+        machine_label?: string;
+    }): Promise<OwnerHttp>;
+    enrollPoll(pollSecret: string, approvalId: string | null): Promise<OwnerHttp>;
+    list(): Promise<OwnerHttp>;
+    renew(executorId: string): Promise<OwnerHttp>;
+}
+export declare function ownerApi(opts: {
+    apiUrl: string;
+    jwt: () => Promise<string | null>;
+    fetch: FetchFn;
+}): OwnerApi;
+/** One executor as exec_list reports it (fields read defensively). */
+export interface ExecutorRow {
+    readonly id: string;
+    readonly revoked: boolean;
+    readonly grantExpiresAt: number | null;
+    readonly riskLineVersion: number | null;
+    readonly label: string | null;
+    readonly orgId: string | null;
+}
+export declare function parseExecutorList(body: unknown): ExecutorRow[] | null;
+export interface EnrollStart {
+    readonly approvalId: string | null;
+    readonly userCode: string;
+    readonly verificationUri: string;
+    readonly expiresIn: number;
+    readonly interval: number;
+    readonly pollSecret: string;
+}
+export declare function parseEnrollStart(body: unknown): EnrollStart | null;
+export type PollOutcome = {
+    kind: "done";
+    executorId: string;
+    executorKey: string;
+} | {
+    kind: "pending";
+} | {
+    kind: "slow_down";
+} | {
+    kind: "terminal";
+    error: string;
+};
+export declare function classifyPoll(r: OwnerHttp): PollOutcome;