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

package/dist/vendor/shared/durable-contract/cli-output.js

@@ -0,0 +1,201 @@
+// GENERATED from shared/durable-contract/src/cli-output.ts by cli/scripts/sync-durable-contract.mjs; do not edit.
+/**
+ * `mnemom agent <verb> --json` on a refused durable verb (wave-0 fix ruling 19). stdout carries
+ * exactly one JSON document, the ruling-14 error envelope: an API or gateway refusal body is passed
+ * through unchanged; a refusal the CLI decides itself (S1 codes with status null, such as
+ * session_homed_elsewhere or durable_cwd_not_root) is built here in the same shape, with the code's
+ * closed fields and the rendered fix line in details.fix. stderr is the same with or without
+ * --json (refusal line, fix line, machine code), and nothing reaches stdout on a refusal without it.
+ */
+import { HEX64_RE, sha256Hex, UUID_RE } from "./canonical.js";
+import { CLAIM_UNAVAILABLE_CAUSES, durableErrorBody, } from "./codes.js";
+import { TRANSCRIPT_GUARD_MODES } from "./paths.js";
+import { SESSION_STATES } from "./states.js";
+/** Exit status of every refused or failed `mnemom agent` verb, with or without --json. */
+export const CLI_REFUSAL_EXIT = 1;
+/** Exit status of a usage error and of the experimental gate (C04-R01, ruling 9); never a refusal. */
+export const CLI_USAGE_EXIT = 2;
+/**
+ * The --json stdout document for a CLI-side refusal: durableErrorBody with details always present
+ * and carrying the rendered fix line. Throws on a missing or empty fix, and on a field outside `fix`
+ * and the code's closed fields.
+ */
+export function cliRefusalJson(code, message, details) {
+    if (typeof details.fix !== "string" || details.fix === "")
+        throw new Error(`${code}: a CLI refusal carries its rendered fix line in details.fix`);
+    return durableErrorBody(code, message, details);
+}
+/** Hex characters a fingerprint keeps: the sha256 prefix host status prints (ruling 26; C12-R23). */
+export const FINGERPRINT_HEX_CHARS = 12;
+/** A secret's fingerprint: the first FINGERPRINT_HEX_CHARS lowercase hex characters of its sha256. */
+export async function fingerprint(value) {
+    return (await sha256Hex(value)).slice(0, FINGERPRINT_HEX_CHARS);
+}
+const f = (spec) => Object.freeze(spec);
+/**
+ * One seat row (rulings 26, 26.1; C12-R23): pid is the pane pid; state is the session's stored state
+ * (the DB probe); spec_path is the local launch-spec file the daemon spawned the seat from. Every
+ * field describes the seat at call time, so a value that does not exist yet (mid-spawn) or any more
+ * (claude exited) is null: proxy_pid until the seat proxy runs, proxy_port until it listens,
+ * socket_path until the socket exists, claude_pid while claude is not running. A non-null
+ * proxy_port implies a non-null proxy_pid.
+ */
+export const HOST_STATUS_SEAT = Object.freeze({
+    session_id: f({ type: "uuid", nullable: false }),
+    epoch: f({ type: "integer", nullable: false }),
+    spawn_id: f({ type: "uuid", nullable: false }),
+    state: f({ type: "enum", nullable: false, values: SESSION_STATES }),
+    pid: f({ type: "pid", nullable: false }),
+    proxy_pid: f({ type: "pid", nullable: true }),
+    claude_pid: f({ type: "pid", nullable: true }),
+    proxy_port: f({ type: "port", nullable: true }),
+    socket_path: f({ type: "string", nullable: true }),
+    spec_path: f({ type: "string", nullable: false }),
+    spec_sha256: f({ type: "hex64", nullable: false }),
+});
+/**
+ * One session entry (ruling 24.12, Wassim option 1; C12-R31): claim_unavailable is the last
+ * durable_claim_unavailable cause and the count of consecutive unavailable claims, or null when the
+ * session's last claim was not unavailable.
+ */
+export const HOST_STATUS_SESSION = Object.freeze({
+    session_id: f({ type: "uuid", nullable: false }),
+    claim_unavailable: f({
+        type: "object",
+        nullable: true,
+        fields: Object.freeze({
+            cause: f({ type: "enum", nullable: false, values: CLAIM_UNAVAILABLE_CAUSES }),
+            consecutive: f({ type: "positive_integer", nullable: false }),
+        }),
+    }),
+});
+/**
+ * `mnemom agent host status --json` (ruling 26, Wassim option 1; C12-R04, R23, R31): one closed
+ * document, key order as frozen. The nonce and key appear only as fingerprints, never raw.
+ */
+export const HOST_STATUS_JSON = Object.freeze({
+    installed: f({ type: "boolean", nullable: false }),
+    loaded: f({ type: "boolean", nullable: false }),
+    /** The host instance name (launchd label and tmux socket name), from config/env (C12-R04). */
+    instance: f({ type: "string", nullable: false }),
+    daemon_pid: f({ type: "pid", nullable: true }),
+    lock_holder_pid: f({ type: "pid", nullable: true }),
+    lock_path: f({ type: "string", nullable: false }),
+    transcript_guard: f({ type: "enum", nullable: false, values: TRANSCRIPT_GUARD_MODES }),
+    /** The stored boot-bound nonce's fingerprint; null with no state file or no nonce yet (26.1). */
+    nonce_fingerprint: f({ type: "fingerprint", nullable: true }),
+    /** The executor key's fingerprint; null with no readable state file, whatever installed says (26.1). */
+    key_fingerprint: f({ type: "fingerprint", nullable: true }),
+    seats: f({ type: "array", nullable: false, item: HOST_STATUS_SEAT }),
+    sessions: f({ type: "array", nullable: false, item: HOST_STATUS_SESSION }),
+});
+const FINGERPRINT_RE = new RegExp(`^[0-9a-f]{${FINGERPRINT_HEX_CHARS}}$`);
+const isRecord = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const isInt = (v, min, max = Number.MAX_SAFE_INTEGER) => Number.isSafeInteger(v) && v >= min && v <= max;
+function fieldValueOk(spec, v) {
+    if (v === null)
+        return spec.nullable;
+    switch (spec.type) {
+        case "boolean":
+            return typeof v === "boolean";
+        case "string":
+            return typeof v === "string" && v.length > 0;
+        case "uuid":
+            return typeof v === "string" && UUID_RE.test(v);
+        case "integer":
+            return isInt(v, 0);
+        case "positive_integer":
+        case "pid":
+            return isInt(v, 1);
+        case "port":
+            return isInt(v, 1, 65535);
+        case "hex64":
+            return typeof v === "string" && HEX64_RE.test(v);
+        case "fingerprint":
+            return typeof v === "string" && FINGERPRINT_RE.test(v);
+        case "enum":
+            return typeof v === "string" && spec.values.includes(v);
+        case "array":
+            return Array.isArray(v) && v.every((x) => closedOk(spec.item, x));
+        case "object":
+            return closedOk(spec.fields, v);
+    }
+}
+/** Every key present and well formed, no other key. */
+function closedOk(schema, v) {
+    if (!isRecord(v))
+        return false;
+    const keys = Object.keys(schema);
+    if (Object.keys(v).some((k) => !keys.includes(k)))
+        return false;
+    return keys.every((k) => k in v && fieldValueOk(schema[k], v[k]));
+}
+function stringsIn(v) {
+    if (typeof v === "string")
+        return [v];
+    if (Array.isArray(v))
+        return v.flatMap(stringsIn);
+    if (isRecord(v))
+        return Object.entries(v).flatMap(([k, x]) => [k, ...stringsIn(x)]);
+    return [];
+}
+const VECTOR_DOC = {
+    installed: true,
+    loaded: true,
+    instance: "ai.mnemom.agent-host.default",
+    daemon_pid: 4000,
+    lock_holder_pid: 4000,
+    lock_path: "/Users/dev/.mnemom/durable/host.lock",
+    transcript_guard: "link",
+    seats: [],
+    sessions: [],
+};
+/**
+ * Host status documents for the three enrollment states ruling 26.1 names. The fingerprints are of
+ * "vector-executor-key" (4b27142c3a90) and "vector-nonce" (55ccea8c7f0d).
+ */
+export const HOST_STATUS_JSON_VECTORS = Object.freeze({
+    /** Not enrolled: no state file, so neither fingerprint exists. */
+    no_state_file: Object.freeze({
+        ...VECTOR_DOC,
+        installed: false,
+        loaded: false,
+        daemon_pid: null,
+        lock_holder_pid: null,
+        nonce_fingerprint: null,
+        key_fingerprint: null,
+    }),
+    /** Enrolled and running, before the daemon has written its first nonce. */
+    enrolled_no_nonce: Object.freeze({
+        ...VECTOR_DOC,
+        nonce_fingerprint: null,
+        key_fingerprint: "4b27142c3a90",
+    }),
+    /** Uninstalled: the state file and enrollment stay (C12 F6-05, R24). */
+    not_installed_with_state_file: Object.freeze({
+        ...VECTOR_DOC,
+        installed: false,
+        loaded: false,
+        daemon_pid: null,
+        lock_holder_pid: null,
+        nonce_fingerprint: "55ccea8c7f0d",
+        key_fingerprint: "4b27142c3a90",
+    }),
+});
+/**
+ * True for exactly the frozen document: HOST_STATUS_JSON closed at every level. Given the raw
+ * `secrets`, also false when either appears in any key or string value (only fingerprints may).
+ */
+export function hostStatusJsonOk(v, secrets) {
+    if (secrets && (secrets.nonce === "" || secrets.key === ""))
+        throw new RangeError("hostStatusJsonOk: secrets must be non-empty strings");
+    if (!closedOk(HOST_STATUS_JSON, v))
+        return false;
+    // ruling 26.1: a listening port needs the proxy process it belongs to
+    const seats = v.seats;
+    if (seats.some((seat) => seat.proxy_port !== null && seat.proxy_pid === null))
+        return false;
+    if (!secrets)
+        return true;
+    return !stringsIn(v).some((s) => s.includes(secrets.nonce) || s.includes(secrets.key));
+}

package/dist/vendor/shared/durable-contract/cli-surface.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Every command path and long option M1 adds to the CLI (ruling 32.01). E4's report-only D1
+ * detector tags a non-PASS row `product_missing` when a CLI step's argv (before a literal `--`)
+ * names an entry here that the build's cli/command-tree.json lacks; nothing here changes a verdict.
+ *
+ * Sources, in order (a later amendment wins): design-v3 section 7 (P0a-A rows 6 and 7), the
+ * BACKBONE CLI pieces C1-C4 and their amendments, rulings 19, 20, 24.12, 26, 32.31 and 32.33. An entry is a new
+ * path, or a pre-M1 path with only the options M1 adds to it; nothing the pre-M1 CLI already has
+ * (cli/command-tree.json at merge-base(int, origin/main)) is listed. Sorted by path, then closed.
+ *
+ * Deliberately absent: `agent sessions` / `agent show` and their --json (pre-M1); `agent config`
+ * and `agent doctor` (pre-M1 launcher scenarios, not commander paths); `experimental enable
+ * durable` (a value, not a path); `--local` and `host breakglass` (BACKBONE cut list: P0a-B);
+ * `amend --goal` (design section 7 row 12: P0a-B). Ruling 32.31: a spelling exists only if a binding
+ * source names it, so dataset-only spellings (a top-level agent adopt, agent contract, amend
+ * --model, lock --also-lock, options on bare `agent sessions` such as --own-agent/--dry-run,
+ * launcher --durable/--direct/--door, host enroll --json) are not listed; contract and amend are API
+ * verbs (BACKBONE A2). Ruling 32.33 corrects 32.31: the `agent sessions adopt` and `agent sessions
+ * unlock` subcommands are M1 paths and are listed. C1 builds every M1 verb as a commander command,
+ * so each entry appears in cli/command-tree.json once it lands.
+ */
+export interface CliSurfaceEntry {
+    readonly path: readonly string[];
+    /** Long options M1 adds on this path, sorted. */
+    readonly options: readonly string[];
+}
+export declare const M1_CLI_SURFACE: readonly CliSurfaceEntry[];
+/**
+ * Which M1 piece builds each entry (ruling 32.31; an internal S1 tag, not part of the frozen
+ * {path, options} shape): C1 the launcher and owner verbs (BACKBONE line 122), C2 the host daemon
+ * verbs (line 131; `agent host` is the shared parent, so it is C2's), C3 the credential proxy's
+ * hidden seat-proxy (line 145), C4 the launch spec and adopt (line 146; ruling 32.33). `agent
+ * sessions unlock` is C1 (BACKBONE C1 flat verbs; the unlock owner_mutation device step, A4). R1 is
+ * the Doors thin runner, `agent run` (ruling 34.12; Doors lane W-L13). Every entry has exactly one
+ * tag.
+ */
+export declare const M1_CLI_SURFACE_BUILDERS: Readonly<{
+    readonly C1: readonly string[];
+    readonly C2: readonly string[];
+    readonly C3: readonly string[];
+    readonly C4: readonly string[];
+    readonly R1: readonly string[];
+}>;
+export type M1CliBuilder = keyof typeof M1_CLI_SURFACE_BUILDERS;
+/** A command tree's surface: "a b" path strings and "a b --opt" option strings. */
+export interface CliTreeSurface {
+    readonly paths: ReadonlySet<string>;
+    readonly options: ReadonlySet<string>;
+}
+/**
+ * One builder group against a candidate tree (ruling 32.31). Its items are its paths absent from
+ * the pre-M1 `baseline` and every option of its entries. The group has landed once any item is in
+ * the candidate; then every item must be (`missing` empty). Before that, `present` is empty.
+ */
+export declare function m1CliGroupCheck(group: M1CliBuilder, candidate: CliTreeSurface, baseline: CliTreeSurface): {
+    landed: boolean;
+    present: string[];
+    missing: string[];
+};
+/**
+ * Pre-M1 launcher sub-verbs (ruling 32.35): words `mnemom agent` reads from its `session`
+ * positional and dispatches itself, so gen-command-tree never lists them. b37bfbf1
+ * cli/src/index.ts: `scenario === "help"` (493), "config" (523), "slack" (530), "doctor" (577),
+ * "setup" (587). Accepted only as the first word after `agent`; the words after it are its
+ * arguments and are not checked.
+ */
+export declare const PRE_M1_LAUNCHER_SUBVERBS: readonly ["config", "doctor", "help", "setup", "slack"];
+/** The parts of cli/command-tree.json the resolver reads. */
+export interface CliTreeOption {
+    readonly long?: string;
+    readonly required?: boolean;
+    readonly optional?: boolean;
+}
+export interface CliTreeNode {
+    readonly name: string;
+    readonly arguments?: readonly {
+        readonly variadic?: boolean;
+    }[];
+    readonly options?: readonly CliTreeOption[];
+    readonly commands?: readonly CliTreeNode[];
+}
+export interface CliTree {
+    readonly globalOptions?: readonly CliTreeOption[];
+    readonly commands: readonly CliTreeNode[];
+}
+export interface CliResolution {
+    ok: boolean;
+    /** The command path the argv resolves to (a launcher sub-verb is ["agent", <sub-verb>]). */
+    path: string[];
+    /** Each unknown command word or option, in argv order; absent when ok. */
+    unknown?: string[];
+}
+/**
+ * One argv (binary name excluded) against the pre-M1 tree and M1_CLI_SURFACE (rulings 32.31,
+ * 32.33, 32.35; CASE-DSL rule 29). Read as commander does: a word is a subcommand when the
+ * current path has it and no positional has been taken there, else the path's positional (a
+ * pre-M1 path's declared arguments; an M1-only path without subcommands takes any number), else
+ * unknown, and the walk stops (commander stops at an unknown command). A word that names a
+ * command anywhere in the tree, the surface or the sub-verb list never fills a positional, so a
+ * misplaced verb (`agent adopt <name>`, `agent lock doctor`) is unknown. A launcher sub-verb is
+ * accepted only as the first word after `agent`, and its arguments are not checked. An option
+ * counts on its own path or as a global option, never on an ancestor; a pre-M1 option that takes
+ * a value consumes the next token, and M1 options are read as flags (each M1 path that adds one
+ * takes positionals, so a value is a positional there). `--name=value` is read as `--name`.
+ * Short options, `--help`, `$` references and everything after a literal `--` are not checked.
+ */
+export declare function resolveCliArgv(argv: readonly string[], preM1Tree: CliTree, surface?: readonly CliSurfaceEntry[]): CliResolution;
+/** An argv slot the resolver fills from the named environment variable. */
+export interface EnvArg {
+    readonly env: string;
+}
+/**
+ * The CLI call the bundled plugin's /mnemom lock makes: the M1 `agent lock` path with the session
+ * name as its one positional, read from MNEMOM_AGENT_SESSION_NAME (the launcher sets it in the
+ * claude it starts). No option, no cwd argument: the child inherits the original's process cwd.
+ */
+export declare const PLUGIN_LOCK_ARGV: readonly (string | EnvArg)[];
+/** PLUGIN_LOCK_ARGV resolved against `env`; null when MNEMOM_AGENT_SESSION_NAME is unset or empty (the plugin then runs no CLI call). */
+export declare function pluginLockArgv(env: Readonly<Record<string, string | undefined>>): string[] | null;

package/dist/vendor/shared/durable-contract/cli-surface.js

@@ -0,0 +1,270 @@
+// GENERATED from shared/durable-contract/src/cli-surface.ts by cli/scripts/sync-durable-contract.mjs; do not edit.
+/**
+ * Every command path and long option M1 adds to the CLI (ruling 32.01). E4's report-only D1
+ * detector tags a non-PASS row `product_missing` when a CLI step's argv (before a literal `--`)
+ * names an entry here that the build's cli/command-tree.json lacks; nothing here changes a verdict.
+ *
+ * Sources, in order (a later amendment wins): design-v3 section 7 (P0a-A rows 6 and 7), the
+ * BACKBONE CLI pieces C1-C4 and their amendments, rulings 19, 20, 24.12, 26, 32.31 and 32.33. An entry is a new
+ * path, or a pre-M1 path with only the options M1 adds to it; nothing the pre-M1 CLI already has
+ * (cli/command-tree.json at merge-base(int, origin/main)) is listed. Sorted by path, then closed.
+ *
+ * Deliberately absent: `agent sessions` / `agent show` and their --json (pre-M1); `agent config`
+ * and `agent doctor` (pre-M1 launcher scenarios, not commander paths); `experimental enable
+ * durable` (a value, not a path); `--local` and `host breakglass` (BACKBONE cut list: P0a-B);
+ * `amend --goal` (design section 7 row 12: P0a-B). Ruling 32.31: a spelling exists only if a binding
+ * source names it, so dataset-only spellings (a top-level agent adopt, agent contract, amend
+ * --model, lock --also-lock, options on bare `agent sessions` such as --own-agent/--dry-run,
+ * launcher --durable/--direct/--door, host enroll --json) are not listed; contract and amend are API
+ * verbs (BACKBONE A2). Ruling 32.33 corrects 32.31: the `agent sessions adopt` and `agent sessions
+ * unlock` subcommands are M1 paths and are listed. C1 builds every M1 verb as a commander command,
+ * so each entry appears in cli/command-tree.json once it lands.
+ */
+const entry = (path, options = []) => Object.freeze({ path: Object.freeze(path), options: Object.freeze(options) });
+export const M1_CLI_SURFACE = Object.freeze([
+    // BACKBONE C1 "--new"; design-v3 CLI table ("`--new` starts fresh", marked New).
+    entry(["agent"], ["--new"]),
+    // BACKBONE C1 amend (lowering + budget raise) and the amend line (`amend <name> --budget <n>`);
+    // ruling 19 (--json on the durable verbs); --turns: BACKBONE C1 (amend lowers; a turns raise is
+    // refused) and C08 (a `--turns` raise stays refused), ruling 32.31.
+    entry(["agent", "amend"], ["--budget", "--json", "--turns"]),
+    // BACKBONE C1 `mnemom agent containment pause|resume <agent>`; amendment 26.
+    entry(["agent", "containment"]),
+    entry(["agent", "containment", "pause"]),
+    entry(["agent", "containment", "resume"]),
+    // BACKBONE C1 flat verbs; ruling 19.
+    entry(["agent", "done"], ["--json"]),
+    // BACKBONE C2 (`mnemom agent host` replaces `mnemom host`, amendment 2; design-v3 row 7).
+    entry(["agent", "host"]),
+    // BACKBONE C2 enroll (device step).
+    entry(["agent", "host", "enroll"]),
+    // BACKBONE C2 install/status/uninstall; --json: C04 (`mnemom agent host install --json`),
+    // ruling 32.31.
+    entry(["agent", "host", "install"], ["--json"]),
+    // BACKBONE C2 renew; amendment 15; --json: C04 (`mnemom agent host renew --json`), ruling 32.31.
+    entry(["agent", "host", "renew"], ["--json"]),
+    // BACKBONE C2 hidden `run` for launchd; amendment 49.
+    entry(["agent", "host", "run"]),
+    // BACKBONE C3 hidden `mnemom agent host seat-proxy`; amendment 49; options: C13 test_hooks
+    // (`seat-proxy --conversation <cid> --agent-id <uuid> --door <url> --cwd <dir>`), ruling 32.31.
+    entry(["agent", "host", "seat-proxy"], ["--agent-id", "--conversation", "--cwd", "--door"]),
+    // BACKBONE C2 host status `--json` (line 139); rulings 24.12 and 26.
+    entry(["agent", "host", "status"], ["--json"]),
+    entry(["agent", "host", "uninstall"]),
+    // BACKBONE C1 flat verbs; ruling 19.
+    entry(["agent", "kill"], ["--json"]),
+    // BACKBONE C1 lock; design-v3 `mnemom agent lock <name> [--own-agent]` (row 6); ruling 16
+    // lock_agent_shared fix; rulings 19 and 20 (C02-LOCK-SUBDIR-JSON-215, lock --json).
+    entry(["agent", "lock"], ["--json", "--own-agent"]),
+    // BACKBONE C1 flat verbs; ruling 19.
+    entry(["agent", "pause"], ["--json"]),
+    entry(["agent", "resume"], ["--json"]),
+    // Doors thin runner (W-L13), ruling 34.12 (1): --watch or --once, --fail-mode, --json, --oidc.
+    entry(["agent", "run"], ["--fail-mode", "--json", "--oidc", "--once", "--watch"]),
+    // BACKBONE C4 (line 147: buildDurableLaunchSpec serves 'sessions adopt'); options: C14 spec
+    // (`sessions adopt --dry-run --json`, `sessions adopt --own-agent`); ruling 32.33.
+    entry(["agent", "sessions", "adopt"], ["--dry-run", "--json", "--own-agent"]),
+    // fixlines.ts launch_spec_change_sole_unlock (`mnemom agent sessions unlock <name>`); C11, C16 and
+    // C17 specs; no source names an option; ruling 32.33.
+    entry(["agent", "sessions", "unlock"]),
+]);
+/**
+ * Which M1 piece builds each entry (ruling 32.31; an internal S1 tag, not part of the frozen
+ * {path, options} shape): C1 the launcher and owner verbs (BACKBONE line 122), C2 the host daemon
+ * verbs (line 131; `agent host` is the shared parent, so it is C2's), C3 the credential proxy's
+ * hidden seat-proxy (line 145), C4 the launch spec and adopt (line 146; ruling 32.33). `agent
+ * sessions unlock` is C1 (BACKBONE C1 flat verbs; the unlock owner_mutation device step, A4). R1 is
+ * the Doors thin runner, `agent run` (ruling 34.12; Doors lane W-L13). Every entry has exactly one
+ * tag.
+ */
+export const M1_CLI_SURFACE_BUILDERS = Object.freeze({
+    C1: Object.freeze([
+        "agent",
+        "agent amend",
+        "agent containment",
+        "agent containment pause",
+        "agent containment resume",
+        "agent done",
+        "agent kill",
+        "agent lock",
+        "agent pause",
+        "agent resume",
+        "agent sessions unlock",
+    ]),
+    C2: Object.freeze([
+        "agent host",
+        "agent host enroll",
+        "agent host install",
+        "agent host renew",
+        "agent host run",
+        "agent host status",
+        "agent host uninstall",
+    ]),
+    C3: Object.freeze(["agent host seat-proxy"]),
+    C4: Object.freeze(["agent sessions adopt"]),
+    R1: Object.freeze(["agent run"]),
+});
+/**
+ * One builder group against a candidate tree (ruling 32.31). Its items are its paths absent from
+ * the pre-M1 `baseline` and every option of its entries. The group has landed once any item is in
+ * the candidate; then every item must be (`missing` empty). Before that, `present` is empty.
+ */
+export function m1CliGroupCheck(group, candidate, baseline) {
+    const paths = M1_CLI_SURFACE_BUILDERS[group];
+    const present = [];
+    const missing = [];
+    for (const e of M1_CLI_SURFACE) {
+        const p = e.path.join(" ");
+        if (!paths.includes(p))
+            continue;
+        if (!baseline.paths.has(p))
+            (candidate.paths.has(p) ? present : missing).push(p);
+        for (const o of e.options)
+            (candidate.options.has(`${p} ${o}`) ? present : missing).push(`${p} ${o}`);
+    }
+    return { landed: present.length > 0, present, missing };
+}
+/**
+ * Pre-M1 launcher sub-verbs (ruling 32.35): words `mnemom agent` reads from its `session`
+ * positional and dispatches itself, so gen-command-tree never lists them. b37bfbf1
+ * cli/src/index.ts: `scenario === "help"` (493), "config" (523), "slack" (530), "doctor" (577),
+ * "setup" (587). Accepted only as the first word after `agent`; the words after it are its
+ * arguments and are not checked.
+ */
+export const PRE_M1_LAUNCHER_SUBVERBS = Object.freeze([
+    "config",
+    "doctor",
+    "help",
+    "setup",
+    "slack",
+]);
+const takesValue = (o) => o.required === true || o.optional === true;
+/**
+ * One argv (binary name excluded) against the pre-M1 tree and M1_CLI_SURFACE (rulings 32.31,
+ * 32.33, 32.35; CASE-DSL rule 29). Read as commander does: a word is a subcommand when the
+ * current path has it and no positional has been taken there, else the path's positional (a
+ * pre-M1 path's declared arguments; an M1-only path without subcommands takes any number), else
+ * unknown, and the walk stops (commander stops at an unknown command). A word that names a
+ * command anywhere in the tree, the surface or the sub-verb list never fills a positional, so a
+ * misplaced verb (`agent adopt <name>`, `agent lock doctor`) is unknown. A launcher sub-verb is
+ * accepted only as the first word after `agent`, and its arguments are not checked. An option
+ * counts on its own path or as a global option, never on an ancestor; a pre-M1 option that takes
+ * a value consumes the next token, and M1 options are read as flags (each M1 path that adds one
+ * takes positionals, so a value is a positional there). `--name=value` is read as `--name`.
+ * Short options, `--help`, `$` references and everything after a literal `--` are not checked.
+ */
+export function resolveCliArgv(argv, preM1Tree, surface = M1_CLI_SURFACE) {
+    const info = new Map();
+    const get = (p) => {
+        let i = info.get(p);
+        if (!i)
+            info.set(p, (i = { children: new Set(), slots: -1, options: new Map() }));
+        return i;
+    };
+    const verbs = new Set(PRE_M1_LAUNCHER_SUBVERBS);
+    const walk = (n, parent) => {
+        const p = [...parent, n.name];
+        const i = get(p.join(" "));
+        verbs.add(n.name);
+        if (parent.length > 0)
+            get(parent.join(" ")).children.add(n.name);
+        const args = n.arguments ?? [];
+        i.slots = args.some((a) => a.variadic) ? Infinity : args.length;
+        for (const o of n.options ?? [])
+            if (o.long)
+                i.options.set(o.long, takesValue(o));
+        for (const c of n.commands ?? [])
+            walk(c, p);
+    };
+    for (const c of preM1Tree.commands)
+        walk(c, []);
+    const top = get("");
+    for (const c of preM1Tree.commands)
+        top.children.add(c.name);
+    for (const e of surface) {
+        for (let k = 1; k <= e.path.length; k++) {
+            get(e.path.slice(0, k - 1).join(" ")).children.add(e.path[k - 1]);
+            verbs.add(e.path[k - 1]);
+        }
+        const i = get(e.path.join(" "));
+        for (const o of e.options)
+            if (!i.options.has(o))
+                i.options.set(o, false);
+    }
+    // An M1-only path (not in the tree) takes positionals unless it has subcommands.
+    for (const i of info.values())
+        if (i.slots < 0)
+            i.slots = i.children.size > 0 ? 0 : Infinity;
+    top.slots = 0;
+    const global = new Map();
+    for (const o of preM1Tree.globalOptions ?? [])
+        if (o.long)
+            global.set(o.long, takesValue(o));
+    const path = [];
+    const unknown = [];
+    let taken = 0;
+    for (let k = 0; k < argv.length; k++) {
+        const t = argv[k];
+        if (t === "--")
+            break;
+        if (t.startsWith("--")) {
+            const name = t.split("=")[0];
+            if (name === "--help")
+                continue;
+            const here = get(path.join(" ")).options;
+            const value = here.has(name) ? here.get(name) : global.get(name);
+            if (value === undefined)
+                unknown.push(name);
+            else if (value && !t.includes("="))
+                k++;
+            continue;
+        }
+        if (t.startsWith("-") || t.startsWith("$"))
+            continue;
+        if (path.length === 1 &&
+            path[0] === "agent" &&
+            taken === 0 &&
+            PRE_M1_LAUNCHER_SUBVERBS.includes(t))
+            return finish([...path, t]);
+        const here = get(path.join(" "));
+        if (taken === 0 && here.children.has(t)) {
+            path.push(t);
+            continue;
+        }
+        if (!verbs.has(t) && taken < here.slots) {
+            taken++;
+            continue;
+        }
+        unknown.push(t);
+        break;
+    }
+    return finish(path);
+    function finish(p) {
+        return unknown.length === 0 ? { ok: true, path: p } : { ok: false, path: p, unknown };
+    }
+}
+/**
+ * The CLI call the bundled plugin's /mnemom lock makes: the M1 `agent lock` path with the session
+ * name as its one positional, read from MNEMOM_AGENT_SESSION_NAME (the launcher sets it in the
+ * claude it starts). No option, no cwd argument: the child inherits the original's process cwd.
+ */
+export const PLUGIN_LOCK_ARGV = Object.freeze([
+    "agent",
+    "lock",
+    Object.freeze({ env: "MNEMOM_AGENT_SESSION_NAME" }),
+]);
+/** PLUGIN_LOCK_ARGV resolved against `env`; null when MNEMOM_AGENT_SESSION_NAME is unset or empty (the plugin then runs no CLI call). */
+export function pluginLockArgv(env) {
+    const out = [];
+    for (const a of PLUGIN_LOCK_ARGV) {
+        if (typeof a === "string") {
+            out.push(a);
+            continue;
+        }
+        const v = env[a.env];
+        if (v === undefined || v === "")
+            return null;
+        out.push(v);
+    }
+    return out;
+}