@mnemom/mnemom 0.17.32-next.2 → 0.17.32-next.3

package/dist/durable/launch-spec.js

@@ -0,0 +1,277 @@
+/**
+ * The one launch-spec builder, buildDurableLaunchSpec (BACKBONE C4; C14-R01..R05, R12, R13; S1
+ * spec.ts). Every path that commits a spec (the lock verb, /mnemom lock, the launcher's
+ * durable=always path, the API lock route's validation and `sessions adopt`) builds it here.
+ *
+ * Pure: no I/O. The callers read the argv (the running source reads the original claude's argv
+ * exactly, the idle source passes the launcher's resolved continue argv) and resolve the cwd.
+ *
+ * Choices (each from S1 or the C14 spec, none invented here):
+ *  - Only --model <v>, --effort <v> and --trim-mcp reach a committed spec (S1 SEAT_USER_FLAGS).
+ *  - Names follow ruling 15 (S1 droppedArgvNames): left to right, flags verbatim, deduplicated,
+ *    then one `positional arguments (<n>)` entry; tokens after claude's own `--` are positionals.
+ *  - An allowlisted flag whose value the closed S1 schema cannot hold (MODEL_RE, EFFORT_VALUES:
+ *    newlines, shell metacharacters, unknown effort) is dropped and named instead (C14-R03, R05,
+ *    R23); the last valid occurrence of a repeated flag wins, as claude's parser does.
+ *  - The yolo-default bypass flag the launcher injects counts as dropped and is named (S1
+ *    spec.ts freeze; C14-R12), and a dropped --remote-control (explicit or auto-upgraded) is
+ *    always named (M1 is terminal-only).
+ *  - The spec holds no goal, prompt, positional, remote-control field, plugin path or hash: the
+ *    plugin is the token `bundled-mnemom` (C14-R05, R26).
+ */
+import { canonicalArgvPairs, droppedArgvNames, EFFORT_VALUES, hasRemoteControl, MODEL_RE, parseLaunchSpec, PLUGIN_TOKEN, renderAdoptNote, renderFixLine, SEAT_USER_FLAGS, SPEC_VERSION, specHash, } from "../vendor/durable-contract/index.js";
+/** The bypass flag the launcher's yolo default injects (cli/src/commands/agent.ts buildCliArgs). */
+export const YOLO_FLAG = "--dangerously-skip-permissions";
+/** The launcher option for Remote Control; never committed in M1, always named when dropped. */
+export const REMOTE_CONTROL_FLAG = "--remote-control";
+/** One token as claude's parser reads it: '-'-leading (not '-') is a flag; `--f=v` is split. */
+function readToken(tok) {
+    if (tok === "-" || !tok.startsWith("-"))
+        return { flag: null };
+    const eq = tok.startsWith("--") ? tok.indexOf("=") : -1;
+    return eq > 0 ? { flag: tok.slice(0, eq), inline: tok.slice(eq + 1) } : { flag: tok };
+}
+function validValue(flag, value) {
+    if (flag === "--model")
+        return MODEL_RE.test(value);
+    return EFFORT_VALUES.includes(value);
+}
+/**
+ * The C14-R01..R03 filter over a claude-level argv (after argv[0]): the flags a seat keeps, and
+ * the allowlisted flags dropped because their value is missing or not schema-valid. Every other
+ * name comes from droppedArgvNames (S1), so the two never disagree.
+ */
+export function filterSeatArgv(argv) {
+    const kept = { trim_mcp: false };
+    const invalid = [];
+    for (let i = 0; i < argv.length; i++) {
+        const tok = argv[i];
+        if (tok === "--")
+            break;
+        const { flag, inline } = readToken(tok);
+        if (flag === null)
+            continue;
+        const arity = Object.prototype.hasOwnProperty.call(SEAT_USER_FLAGS, flag)
+            ? SEAT_USER_FLAGS[flag]
+            : undefined;
+        if (arity === undefined)
+            continue;
+        if (arity === 0) {
+            kept.trim_mcp = true;
+            continue;
+        }
+        let value = inline;
+        if (value === undefined) {
+            const next = argv[i + 1];
+            if (next !== undefined && readToken(next).flag === null) {
+                value = next;
+                i++;
+            }
+        }
+        // A value-less flag is named by droppedArgvNames; only a present, invalid value is ours.
+        if (value === undefined)
+            continue;
+        // The last valued occurrence decides (claude reads the last one): a later valid value
+        // clears an earlier invalid one, and a later invalid one is named though an earlier is kept.
+        const at = invalid.indexOf(flag);
+        if (!validValue(flag, value)) {
+            if (at < 0)
+                invalid.push(flag);
+            continue;
+        }
+        if (at >= 0)
+            invalid.splice(at, 1);
+        if (flag === "--model")
+            kept.model = value;
+        else
+            kept.effort = value;
+    }
+    return { kept, invalid };
+}
+/** The dropped-flag names (ruling 15) plus the invalid-value names, positional entry kept last. */
+export function droppedNames(argv) {
+    const names = droppedArgvNames(argv);
+    const { invalid } = filterSeatArgv(argv);
+    const extra = invalid.filter((f) => !names.includes(f));
+    if (extra.length === 0)
+        return names;
+    const last = names[names.length - 1];
+    const hasPositionals = last !== undefined && last.startsWith("positional arguments (");
+    return hasPositionals ? [...names.slice(0, -1), ...extra, last] : [...names, ...extra];
+}
+/**
+ * buildDurableLaunchSpec: the committed, goal-elided spec and the names of what it dropped.
+ * Throws a RangeError when the result would not validate against the closed S1 schema (a cwd
+ * that is not absolute, or holds a newline): a caller bug, never a user input path.
+ */
+export async function buildDurableLaunchSpec(input) {
+    const { kept } = filterSeatArgv(input.argv);
+    const spec = {
+        v: SPEC_VERSION,
+        cwd: input.cwd,
+        plugin: PLUGIN_TOKEN,
+        trim_mcp: kept.trim_mcp,
+    };
+    if (kept.model !== undefined)
+        spec.model = kept.model;
+    if (kept.effort !== undefined)
+        spec.effort = kept.effort;
+    if (parseLaunchSpec(spec) === null || hasRemoteControl(spec))
+        throw new RangeError("buildDurableLaunchSpec: the spec does not fit the closed S1 schema");
+    const named = [];
+    if (input.yoloInjected)
+        named.push(YOLO_FLAG);
+    if (input.remoteControl)
+        named.push(REMOTE_CONTROL_FLAG);
+    const dropped = droppedNames([...named, ...(input.userArgv ?? input.argv)]);
+    return { spec, dropped, hash: await specHash(spec) };
+}
+/** The seat's user-flag argv for a spec (the daemon adds its own flags around it), C14-R01. */
+export function specUserArgv(spec) {
+    const out = [];
+    if (spec.model !== undefined)
+        out.push("--model", spec.model);
+    if (spec.effort !== undefined)
+        out.push("--effort", spec.effort);
+    if (spec.trim_mcp)
+        out.push("--trim-mcp");
+    return out;
+}
+/** The canonical multiset of a spec's user flags, for comparing with an argv (S1 canonicalArgvPairs). */
+export function specUserPairs(spec) {
+    return canonicalArgvPairs(specUserArgv(spec));
+}
+// ---- the original's argv: launcher layout ---------------------------------------------------
+/** The flags the launcher puts before the passthrough, in buildCliArgs order, with arity. */
+const LAUNCHER_PREFIX = [
+    ["--model", 1],
+    ["--effort", 1],
+    [YOLO_FLAG, 0],
+    ["--session-id", 1],
+    ["--plugin-dir", 1],
+];
+// No bounds check: the one caller's loop keeps 0 <= at and at + needle.length <= hay.length.
+function isSubsequenceAt(hay, needle, at) {
+    for (let k = 0; k < needle.length; k++)
+        if (hay[at + k] !== needle[k])
+            return false;
+    return true;
+}
+/**
+ * Split an original claude argv (after argv[0]) the way `mnemom agent` built it (buildCliArgs):
+ * [--model v] [--effort v] [yolo] [--session-id id] [--plugin-dir dir] <passthrough>
+ * [--strict-mcp-config] [--mcp-config <v>]. `passthroughHint` (the tokens after the parent
+ * launcher's `--`, read from its own argv) pins the split exactly when it occurs where the
+ * layout allows; an empty hint (the parent was read and had no `--`) makes the shape read exact;
+ * without a hint (null or absent) the prefix and suffix are read by shape and reported ambiguous.
+ */
+export function splitLauncherArgv(argv, passthroughHint) {
+    // Prefix: launcher-injected flags in their fixed order.
+    let i = 0;
+    const prefix = {};
+    for (const [flag, arity] of LAUNCHER_PREFIX) {
+        if (argv[i] !== flag)
+            continue;
+        if (arity === 0) {
+            prefix[flag] = true;
+            i += 1;
+            continue;
+        }
+        const v = argv[i + 1];
+        if (v === undefined || readToken(v).flag !== null)
+            break;
+        prefix[flag] = v;
+        i += 2;
+    }
+    // Suffix: [--strict-mcp-config] --mcp-config <v> at the very end.
+    let end = argv.length;
+    let trim = false;
+    let mcpSuffix = false;
+    if (end - 2 >= i && argv[end - 2] === "--mcp-config") {
+        mcpSuffix = true;
+        end -= 2;
+        if (end - 1 >= i && argv[end - 1] === "--strict-mcp-config") {
+            end -= 1;
+            trim = true;
+        }
+    }
+    let passthrough = argv.slice(i, end);
+    let exact = Array.isArray(passthroughHint) && passthroughHint.length === 0;
+    if (passthroughHint && passthroughHint.length > 0) {
+        // The hint wins when it sits inside the shape-read window (prefix and suffix may have been
+        // over-read into user tokens that look like launcher ones).
+        for (let at = 0; at + passthroughHint.length <= argv.length; at++) {
+            if (!isSubsequenceAt(argv, passthroughHint, at))
+                continue;
+            if (at > i || at + passthroughHint.length < end)
+                continue;
+            passthrough = [...passthroughHint];
+            exact = true;
+            break;
+        }
+    }
+    const launcherArgv = [];
+    if (typeof prefix["--model"] === "string")
+        launcherArgv.push("--model", prefix["--model"]);
+    if (typeof prefix["--effort"] === "string")
+        launcherArgv.push("--effort", prefix["--effort"]);
+    if (trim)
+        launcherArgv.push("--trim-mcp");
+    const ambiguous = [];
+    if (!exact) {
+        if (prefix["--session-id"] !== undefined)
+            ambiguous.push("--session-id");
+        if (prefix["--plugin-dir"] !== undefined)
+            ambiguous.push("--plugin-dir");
+        if (mcpSuffix)
+            ambiguous.push("--mcp-config");
+    }
+    return {
+        launcherArgv,
+        passthrough,
+        yoloInjected: prefix[YOLO_FLAG] === true,
+        sessionId: typeof prefix["--session-id"] === "string" ? prefix["--session-id"] : null,
+        exact,
+        ambiguous,
+    };
+}
+/** The running-source builder input for an original claude's exact argv and its checked cwd. */
+export function runningSourceInput(originalArgv, cwd, opts = {}) {
+    const split = splitLauncherArgv(originalArgv, opts.passthroughHint);
+    return {
+        source: "running",
+        argv: [...split.launcherArgv, ...split.passthrough],
+        // A shape-read split names the launcher-shaped flags it could not attribute (conservative).
+        userArgv: [...split.ambiguous, ...split.passthrough],
+        yoloInjected: split.yoloInjected,
+        // Names are deduplicated, so a --remote-control the user also passed is named once.
+        remoteControl: opts.remoteControl === true,
+        cwd,
+    };
+}
+export async function compareWithCommitted(built, committed) {
+    const committedHash = typeof committed === "string" ? committed : await specHash(committed);
+    return (await specHash(built)) === committedHash
+        ? { changed: false }
+        : { changed: true, status: 422, code: "durable_unsupported", feature: "launch_spec_change" };
+}
+/**
+ * The fix lines printed with a launch_spec_change refusal: the S1 `launch_spec_change` entry
+ * under the fix-line rule (the locked row holds the name, so the done clause applies), plus the
+ * sole-unlock entry only when this is the agent's sole locked session (C14-R11).
+ */
+export function launchSpecChangeFixLines(ctx) {
+    const render = {
+        launcherKey: ctx.launcherKey,
+        nameHeld: true,
+        params: { name: ctx.name, flags: ctx.flags },
+    };
+    const lines = [renderFixLine("launch_spec_change", render)];
+    if (ctx.soleLockedSession)
+        lines.push(renderFixLine("launch_spec_change_sole_unlock", { ...render, params: { name: ctx.name } }));
+    return lines;
+}
+/** The adopt Note for an adopted row (C14-R12, R21): S1 grammar, unchanged builder names. */
+export function adoptNote(dropped) {
+    return renderAdoptNote(dropped);
+}

package/dist/durable/proc.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Exact process facts for the running-session builder source (S1 BUILDER_INPUT_TABLE `running`:
+ * "the original's argv, read exactly (KERN_PROCARGS2 or the shim log, never ps)").
+ *
+ *  - argv and environment: macOS KERN_PROCARGS2 (sysctl through perl's syscall, no native addon),
+ *    Linux /proc/<pid>/cmdline and /proc/<pid>/environ. Never ps, which loses argv boundaries.
+ *  - cwd: lsof (macOS) or /proc/<pid>/cwd (Linux).
+ *  - the process table (pid, ppid, state) for discovery and process trees: ps, which is exact for
+ *    these columns; argv is never taken from it.
+ *
+ * parseProcArgs2 is pure; the rest is the thin driver.
+ */
+export interface ProcArgs {
+    /** argv[0..argc-1] exactly as exec'd. */
+    argv: string[];
+    /** The environment as exec'd, `KEY=value` entries. */
+    env: string[];
+}
+/**
+ * Parse a KERN_PROCARGS2 buffer: int32 argc, the exec path, NUL padding, then argc NUL-terminated
+ * argv strings, then NUL-terminated environment strings up to an empty one. Null when malformed.
+ */
+export declare function parseProcArgs2(buf: Buffer): ProcArgs | null;
+/** Split a NUL-separated /proc file (cmdline, environ). */
+export declare function splitNul(buf: Buffer): string[];
+/** The perl one-shot that copies a pid's KERN_PROCARGS2 to stdout (CTL_KERN=1, KERN_PROCARGS2=49, KERN_ARGMAX=8; SYS_sysctl=202). */
+export declare const PROCARGS2_PERL: string;
+/**
+ * The same sysctl over many pids in one perl process: per pid a header line "<pid> <n>\n" then n
+ * raw bytes (n = 0 when the pid cannot be read).
+ */
+export declare const PROCARGS2_MANY_PERL: string;
+/** Parse PROCARGS2_MANY_PERL output into pid -> parsed args (unreadable pids are left out). */
+export declare function parseManyProcArgs2(buf: Buffer): Map<number, ProcArgs>;
+export interface ProcDeps {
+    platform: NodeJS.Platform;
+    run(cmd: string, args: string[]): {
+        status: number | null;
+        stdout: Buffer;
+    };
+    readFile(p: string): Buffer;
+    readlink(p: string): string;
+}
+export declare const liveProcDeps: ProcDeps;
+/** A pid's exact argv and environment, or null when it cannot be read (gone, or not ours). */
+export declare function readProcArgs(pid: number, deps?: ProcDeps): ProcArgs | null;
+/**
+ * What a pid named when it was read: its start time as the OS reports it, and argv[0]. A pid can be
+ * reused once its process exits; the start time cannot, so equal identities are the same process.
+ */
+export interface ProcIdentity {
+    start: string;
+    argv0: string;
+}
+/**
+ * A pid's start time, or null when it is gone or unreadable. Linux: /proc/<pid>/stat field 22
+ * (starttime, clock ticks since boot); elsewhere `ps -o lstart= -p <pid>`.
+ */
+export declare function readProcStart(pid: number, deps?: ProcDeps): string | null;
+/** A pid's identity (start time and argv[0]), or null when either cannot be read. */
+export declare function readProcIdentity(pid: number, deps?: ProcDeps): ProcIdentity | null;
+/** Many pids' exact argv and environment in one pass; unreadable pids are left out. */
+export declare function readManyProcArgs(pids: readonly number[], deps?: ProcDeps): Map<number, ProcArgs>;
+/** A pid's working directory, or null. */
+export declare function readProcCwd(pid: number, deps?: ProcDeps): string | null;
+export interface ProcRow {
+    pid: number;
+    ppid: number;
+    uid: number;
+    /** ps STAT, e.g. "S+", "T" (stopped). */
+    stat: string;
+    /** The start time as readProcStart reads it, when the table was read with starts. */
+    start?: string;
+}
+/** Parse `ps -axo pid=,ppid=,uid=,stat=[,lstart=]` output (a trailing lstart becomes start). */
+export declare function parsePsTable(text: string): ProcRow[];
+/** The process table (pid, ppid, state). Empty when ps fails. */
+export declare function processTable(deps?: ProcDeps): ProcRow[];
+/**
+ * The process table with each row's start time, in the form readProcStart reads it, so a pid
+ * from this snapshot can be re-checked before it is signalled. Darwin: ps lstart in the same pass.
+ * Linux: /proc/<pid>/stat per row. A row whose start cannot be read has none.
+ */
+export declare function processTableWithStarts(deps?: ProcDeps): ProcRow[];
+/** `root` and every descendant, root first, minus `exclude` and the excluded pids' own subtrees. */
+export declare function processTree(root: number, table: readonly ProcRow[], exclude?: ReadonlySet<number>): number[];

package/dist/durable/proc.js

@@ -0,0 +1,279 @@
+/**
+ * Exact process facts for the running-session builder source (S1 BUILDER_INPUT_TABLE `running`:
+ * "the original's argv, read exactly (KERN_PROCARGS2 or the shim log, never ps)").
+ *
+ *  - argv and environment: macOS KERN_PROCARGS2 (sysctl through perl's syscall, no native addon),
+ *    Linux /proc/<pid>/cmdline and /proc/<pid>/environ. Never ps, which loses argv boundaries.
+ *  - cwd: lsof (macOS) or /proc/<pid>/cwd (Linux).
+ *  - the process table (pid, ppid, state) for discovery and process trees: ps, which is exact for
+ *    these columns; argv is never taken from it.
+ *
+ * parseProcArgs2 is pure; the rest is the thin driver.
+ */
+import { spawnSync } from "node:child_process";
+import { readFileSync, readlinkSync } from "node:fs";
+/**
+ * Parse a KERN_PROCARGS2 buffer: int32 argc, the exec path, NUL padding, then argc NUL-terminated
+ * argv strings, then NUL-terminated environment strings up to an empty one. Null when malformed.
+ */
+export function parseProcArgs2(buf) {
+    if (buf.length < 4)
+        return null;
+    const argc = buf.readInt32LE(0);
+    if (argc < 0 || argc > 65536)
+        return null;
+    let i = 4;
+    const end = buf.length;
+    while (i < end && buf[i] !== 0)
+        i++; // exec path
+    while (i < end && buf[i] === 0)
+        i++; // padding
+    const strings = [];
+    while (i < end) {
+        let j = i;
+        while (j < end && buf[j] !== 0)
+            j++;
+        if (j >= end)
+            break; // an unterminated tail
+        const s = buf.subarray(i, j).toString("utf8");
+        if (strings.length >= argc && s === "")
+            break;
+        strings.push(s);
+        i = j + 1;
+    }
+    if (strings.length < argc)
+        return null;
+    return { argv: strings.slice(0, argc), env: strings.slice(argc) };
+}
+/** Split a NUL-separated /proc file (cmdline, environ). */
+export function splitNul(buf) {
+    const s = buf.toString("utf8");
+    const parts = s.split("\0");
+    if (parts.length > 0 && parts[parts.length - 1] === "")
+        parts.pop();
+    return parts;
+}
+/** The perl one-shot that copies a pid's KERN_PROCARGS2 to stdout (CTL_KERN=1, KERN_PROCARGS2=49, KERN_ARGMAX=8; SYS_sysctl=202). */
+export const PROCARGS2_PERL = [
+    "use strict;",
+    "my $pid = int($ARGV[0]);",
+    'my $mib = pack("i3", 1, 49, $pid);',
+    // The buffer must be exactly kern.argmax (KERN_ARGMAX=8): a larger one fails with EINVAL.
+    'my $ammib = pack("i2", 1, 8); my $am = "\\0" x 4; my $amsz = pack("Q", 4);',
+    "exit 4 if syscall(202, $ammib, 2, $am, $amsz, 0, 0) != 0;",
+    'my $buf = "\\0" x unpack("i", $am);',
+    'my $size = pack("Q", length($buf));',
+    "my $r = syscall(202, $mib, 3, $buf, $size, 0, 0);",
+    "exit 3 if $r != 0;",
+    "binmode STDOUT;",
+    'print substr($buf, 0, unpack("Q", $size));',
+].join("\n");
+/**
+ * The same sysctl over many pids in one perl process: per pid a header line "<pid> <n>\n" then n
+ * raw bytes (n = 0 when the pid cannot be read).
+ */
+export const PROCARGS2_MANY_PERL = [
+    "use strict;",
+    'my $ammib = pack("i2", 1, 8); my $am = "\\0" x 4; my $amsz = pack("Q", 4);',
+    "exit 4 if syscall(202, $ammib, 2, $am, $amsz, 0, 0) != 0;",
+    'my $max = unpack("i", $am);',
+    "binmode STDOUT;",
+    "for my $a (@ARGV) {",
+    "  my $pid = int($a);",
+    '  my $mib = pack("i3", 1, 49, $pid);',
+    '  my $buf = "\\0" x $max;',
+    '  my $size = pack("Q", $max);',
+    '  my $out = "";',
+    '  $out = substr($buf, 0, unpack("Q", $size)) if syscall(202, $mib, 3, $buf, $size, 0, 0) == 0;',
+    '  print "$pid " . length($out) . "\\n" . $out;',
+    "}",
+].join("\n");
+/** Parse PROCARGS2_MANY_PERL output into pid -> parsed args (unreadable pids are left out). */
+export function parseManyProcArgs2(buf) {
+    const out = new Map();
+    let i = 0;
+    while (i < buf.length) {
+        const nl = buf.indexOf(10, i);
+        if (nl < 0)
+            break;
+        const m = /^(\d+) (\d+)$/.exec(buf.subarray(i, nl).toString("latin1"));
+        if (!m)
+            break;
+        const n = Number(m[2]);
+        const body = buf.subarray(nl + 1, nl + 1 + n);
+        if (body.length < n)
+            break;
+        const parsed = n > 0 ? parseProcArgs2(body) : null;
+        if (parsed)
+            out.set(Number(m[1]), parsed);
+        i = nl + 1 + n;
+    }
+    return out;
+}
+export const liveProcDeps = {
+    platform: process.platform,
+    run(cmd, args) {
+        const r = spawnSync(cmd, args, { timeout: 10_000, maxBuffer: 16 * 1024 * 1024 });
+        return { status: r.status, stdout: r.stdout ?? Buffer.alloc(0) };
+    },
+    readFile: (p) => readFileSync(p),
+    readlink: (p) => readlinkSync(p),
+};
+/** A pid's exact argv and environment, or null when it cannot be read (gone, or not ours). */
+export function readProcArgs(pid, deps = liveProcDeps) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return null;
+    try {
+        if (deps.platform === "linux") {
+            return {
+                argv: splitNul(deps.readFile(`/proc/${pid}/cmdline`)),
+                env: splitNul(deps.readFile(`/proc/${pid}/environ`)),
+            };
+        }
+        const r = deps.run("perl", ["-e", PROCARGS2_PERL, String(pid)]);
+        if (r.status !== 0)
+            return null;
+        return parseProcArgs2(r.stdout);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * A pid's start time, or null when it is gone or unreadable. Linux: /proc/<pid>/stat field 22
+ * (starttime, clock ticks since boot); elsewhere `ps -o lstart= -p <pid>`.
+ */
+export function readProcStart(pid, deps = liveProcDeps) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return null;
+    try {
+        if (deps.platform === "linux") {
+            const stat = deps.readFile(`/proc/${pid}/stat`).toString("utf8");
+            // comm (field 2) is parenthesised and may hold spaces: field 3 on follow the last ")".
+            const close = stat.lastIndexOf(")");
+            if (close < 0)
+                return null;
+            const fields = stat.slice(close + 2).split(" ");
+            return fields[22 - 3] || null;
+        }
+        const r = deps.run("ps", ["-o", "lstart=", "-p", String(pid)]);
+        const out = r.stdout.toString("utf8").trim();
+        return r.status === 0 && out !== "" ? out : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** A pid's identity (start time and argv[0]), or null when either cannot be read. */
+export function readProcIdentity(pid, deps = liveProcDeps) {
+    const start = readProcStart(pid, deps);
+    if (start === null)
+        return null;
+    const argv0 = readProcArgs(pid, deps)?.argv[0];
+    return argv0 === undefined ? null : { start, argv0 };
+}
+/** Many pids' exact argv and environment in one pass; unreadable pids are left out. */
+export function readManyProcArgs(pids, deps = liveProcDeps) {
+    const valid = pids.filter((p) => Number.isSafeInteger(p) && p > 0);
+    if (valid.length === 0)
+        return new Map();
+    if (deps.platform === "linux") {
+        const out = new Map();
+        for (const p of valid) {
+            const a = readProcArgs(p, deps);
+            if (a)
+                out.set(p, a);
+        }
+        return out;
+    }
+    try {
+        const r = deps.run("perl", ["-e", PROCARGS2_MANY_PERL, ...valid.map(String)]);
+        return r.status === 0 ? parseManyProcArgs2(r.stdout) : new Map();
+    }
+    catch {
+        return new Map();
+    }
+}
+/** A pid's working directory, or null. */
+export function readProcCwd(pid, deps = liveProcDeps) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return null;
+    try {
+        if (deps.platform === "linux")
+            return deps.readlink(`/proc/${pid}/cwd`);
+        const r = deps.run("lsof", ["-a", "-p", String(pid), "-d", "cwd", "-Fn"]);
+        if (r.status !== 0)
+            return null;
+        const line = r.stdout
+            .toString("utf8")
+            .split("\n")
+            .find((l) => l.startsWith("n"));
+        return line ? line.slice(1) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Parse `ps -axo pid=,ppid=,uid=,stat=[,lstart=]` output (a trailing lstart becomes start). */
+export function parsePsTable(text) {
+    const out = [];
+    for (const line of text.split("\n")) {
+        const m = /^\s*(\d+)\s+(\d+)\s+(\d+)\s+(\S+)(?:\s+(\S.*?))?\s*$/.exec(line);
+        if (!m)
+            continue;
+        const row = {
+            pid: Number(m[1]),
+            ppid: Number(m[2]),
+            uid: Number(m[3]),
+            stat: m[4],
+        };
+        if (m[5] !== undefined)
+            row.start = m[5];
+        out.push(row);
+    }
+    return out;
+}
+/** The process table (pid, ppid, state). Empty when ps fails. */
+export function processTable(deps = liveProcDeps) {
+    const r = deps.run("ps", ["-axo", "pid=,ppid=,uid=,stat="]);
+    return r.status === 0 ? parsePsTable(r.stdout.toString("utf8")) : [];
+}
+/**
+ * The process table with each row's start time, in the form readProcStart reads it, so a pid
+ * from this snapshot can be re-checked before it is signalled. Darwin: ps lstart in the same pass.
+ * Linux: /proc/<pid>/stat per row. A row whose start cannot be read has none.
+ */
+export function processTableWithStarts(deps = liveProcDeps) {
+    if (deps.platform !== "linux") {
+        const r = deps.run("ps", ["-axo", "pid=,ppid=,uid=,stat=,lstart="]);
+        return r.status === 0 ? parsePsTable(r.stdout.toString("utf8")) : [];
+    }
+    return processTable(deps).map((row) => {
+        const start = readProcStart(row.pid, deps);
+        return start === null ? row : { ...row, start };
+    });
+}
+/** `root` and every descendant, root first, minus `exclude` and the excluded pids' own subtrees. */
+export function processTree(root, table, exclude = new Set()) {
+    if (exclude.has(root))
+        return [];
+    const children = new Map();
+    for (const r of table) {
+        const list = children.get(r.ppid) ?? [];
+        list.push(r.pid);
+        children.set(r.ppid, list);
+    }
+    const out = [];
+    const queue = [root];
+    const seen = new Set();
+    while (queue.length > 0) {
+        const p = queue.shift();
+        if (seen.has(p) || exclude.has(p))
+            continue;
+        seen.add(p);
+        out.push(p);
+        for (const c of children.get(p) ?? [])
+            queue.push(c);
+    }
+    return out;
+}

package/dist/index.d.ts

@@ -1,6 +1,12 @@
 #!/usr/bin/env node
 import "./lib/retired-env-guard.js";
-import { program } from "commander";
+import { program, type Command } from "commander";
+/**
+ * The durable-gated commands (BACKBONE Flags/CLI: off lists no durable verb). The committed
+ * command-tree.json leaves them out whatever the generating machine's experimental state
+ * (scripts/gen-command-tree.mjs); a piece that registers another durable verb adds it here.
+ */
+export declare const DURABLE_GATED_COMMANDS: ReadonlySet<Command>;
 export { program };
 /**
  * The entrypoint dispatch. `mnemom agent slack …` owns its own flags (--thread,