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

package/dist/durable/cwd-rule.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The C4 cwd rule (S1/C4 registered worktree root; C14-R04; BACKBONE C4 "Lock-time cwd check",
+ * amendment 32). A cwd is accepted when its realpath equals `git rev-parse --show-toplevel` (run
+ * with hooks and fsmonitor off and every GIT_* variable cleared): the primary checkout or a linked
+ * worktree. Otherwise it is `durable_cwd_not_root {cwd_kind}`:
+ *   subdirectory        inside a work tree, not its top level
+ *   not_git             not inside a git work tree (or gone)
+ *   symlink_transcript  a running session whose cwd is reached through a symlink (the path
+ *                       differs from its realpath) and whose transcript sits under the project
+ *                       dir slugged from the symlink path, not the realpath
+ * A running session whose transcript is under neither slug is unadoptable (no_transcript): the
+ * slug rule cannot place it (e.g. a long path Claude Code truncates and hashes), so it is never
+ * guessed to be a symlink.
+ * The fix lines are the S1 catalogue entries under the fix-line rule (renderFixLine). A line whose
+ * path parameter is unknown (not_git outside any checkout) is not printed: every printed fix line
+ * is a working command (C11-R27), never a placeholder.
+ *
+ * The decision is pure over injected facts; liveCwdDeps is the thin driver.
+ */
+import { type CwdKind, type LauncherKey } from "../vendor/durable-contract/index.js";
+export interface CwdDeps {
+    /** realpath(p), or null when it does not resolve. */
+    realpath(p: string): string | null;
+    /** `git rev-parse --show-toplevel` in `dir` (hooks, fsmonitor and GIT_* off), or null. */
+    gitToplevel(dir: string): string | null;
+    /** The project-dir names under `${CLAUDE_CONFIG_DIR:-~/.claude}/projects` holding `<ccSessionId>.jsonl`. */
+    transcriptDirs(ccSessionId: string): string[];
+}
+export type CwdVerdict = {
+    ok: true;
+    root: string;
+} | {
+    ok: false;
+    cwd_kind: CwdKind;
+    /** The fix-line parameter for this kind: toplevel or realpath; not_git knows no checkout. */
+    params: Record<string, string>;
+} | {
+    ok: false;
+    cwd_kind: null;
+    unadoptable: "no_transcript";
+};
+/** Claude Code's project-dir name for a path: every non-alphanumeric character becomes '-'. */
+export declare function projectSlug(path: string): string;
+/**
+ * Classify a cwd. `ccSessionId` is given for a running session (lock of a running session,
+ * adopt): its transcript must sit under the realpath's project dir; a transcript reached only
+ * through the symlink slug is symlink_transcript, and none at all is unadoptable (a seat could
+ * not --resume it).
+ */
+export declare function classifyCwd(cwd: string, deps: CwdDeps, ccSessionId?: string | null): CwdVerdict;
+/**
+ * The S1 fix line for a cwd refusal (fix-line rule: the done clause when a non-terminal row holds
+ * the name, the config suffix when the launcher key is not `always`), or null when a path the
+ * entry needs is unknown.
+ */
+export declare function cwdFixLine(verdict: Extract<CwdVerdict, {
+    cwd_kind: CwdKind;
+}>, ctx: {
+    name: string;
+    launcherKey: LauncherKey;
+    nameHeld: boolean;
+}): string | null;
+/** git with no hooks, no fsmonitor and no GIT_* from the caller's environment. */
+export declare function gitEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare function liveCwdDeps(env?: NodeJS.ProcessEnv): CwdDeps;

package/dist/durable/cwd-rule.js

@@ -0,0 +1,111 @@
+/**
+ * The C4 cwd rule (S1/C4 registered worktree root; C14-R04; BACKBONE C4 "Lock-time cwd check",
+ * amendment 32). A cwd is accepted when its realpath equals `git rev-parse --show-toplevel` (run
+ * with hooks and fsmonitor off and every GIT_* variable cleared): the primary checkout or a linked
+ * worktree. Otherwise it is `durable_cwd_not_root {cwd_kind}`:
+ *   subdirectory        inside a work tree, not its top level
+ *   not_git             not inside a git work tree (or gone)
+ *   symlink_transcript  a running session whose cwd is reached through a symlink (the path
+ *                       differs from its realpath) and whose transcript sits under the project
+ *                       dir slugged from the symlink path, not the realpath
+ * A running session whose transcript is under neither slug is unadoptable (no_transcript): the
+ * slug rule cannot place it (e.g. a long path Claude Code truncates and hashes), so it is never
+ * guessed to be a symlink.
+ * The fix lines are the S1 catalogue entries under the fix-line rule (renderFixLine). A line whose
+ * path parameter is unknown (not_git outside any checkout) is not printed: every printed fix line
+ * is a working command (C11-R27), never a placeholder.
+ *
+ * The decision is pure over injected facts; liveCwdDeps is the thin driver.
+ */
+import { spawnSync } from "node:child_process";
+import { readdirSync, realpathSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { placeholdersOf, renderFixLine, } from "../vendor/durable-contract/index.js";
+/** Claude Code's project-dir name for a path: every non-alphanumeric character becomes '-'. */
+export function projectSlug(path) {
+    return path.replace(/[^A-Za-z0-9]/g, "-");
+}
+/**
+ * Classify a cwd. `ccSessionId` is given for a running session (lock of a running session,
+ * adopt): its transcript must sit under the realpath's project dir; a transcript reached only
+ * through the symlink slug is symlink_transcript, and none at all is unadoptable (a seat could
+ * not --resume it).
+ */
+export function classifyCwd(cwd, deps, ccSessionId = null) {
+    const real = deps.realpath(cwd);
+    if (real === null)
+        return { ok: false, cwd_kind: "not_git", params: {} };
+    const top = deps.gitToplevel(real);
+    if (top === null)
+        return { ok: false, cwd_kind: "not_git", params: {} };
+    const realTop = deps.realpath(top) ?? top;
+    if (realTop !== real)
+        return { ok: false, cwd_kind: "subdirectory", params: { toplevel: realTop } };
+    if (ccSessionId === null)
+        return { ok: true, root: real };
+    const dirs = deps.transcriptDirs(ccSessionId);
+    if (dirs.includes(projectSlug(real)))
+        return { ok: true, root: real };
+    if (cwd !== real && dirs.includes(projectSlug(cwd)))
+        return { ok: false, cwd_kind: "symlink_transcript", params: { realpath: real } };
+    return { ok: false, cwd_kind: null, unadoptable: "no_transcript" };
+}
+const CWD_FIX = {
+    subdirectory: "cwd_subdirectory",
+    not_git: "cwd_not_git",
+    symlink_transcript: "cwd_symlink_transcript",
+};
+/**
+ * The S1 fix line for a cwd refusal (fix-line rule: the done clause when a non-terminal row holds
+ * the name, the config suffix when the launcher key is not `always`), or null when a path the
+ * entry needs is unknown.
+ */
+export function cwdFixLine(verdict, ctx) {
+    const key = CWD_FIX[verdict.cwd_kind];
+    const params = { ...verdict.params, name: ctx.name };
+    if (placeholdersOf(key).some((p) => params[p] === undefined))
+        return null;
+    return renderFixLine(key, { launcherKey: ctx.launcherKey, nameHeld: ctx.nameHeld, params });
+}
+/** git with no hooks, no fsmonitor and no GIT_* from the caller's environment. */
+export function gitEnv(env) {
+    const out = {};
+    for (const [k, v] of Object.entries(env))
+        if (!k.startsWith("GIT_"))
+            out[k] = v;
+    return out;
+}
+export function liveCwdDeps(env = process.env) {
+    const projects = join((env.CLAUDE_CONFIG_DIR ?? "").trim() || join(homedir(), ".claude"), "projects");
+    return {
+        realpath(p) {
+            try {
+                return realpathSync(p);
+            }
+            catch {
+                return null;
+            }
+        },
+        gitToplevel(dir) {
+            const r = spawnSync("git", [
+                "-c",
+                "core.hooksPath=/dev/null",
+                "-c",
+                "core.fsmonitor=false",
+                "rev-parse",
+                "--show-toplevel",
+            ], { cwd: dir, env: gitEnv(env), encoding: "utf8", timeout: 10_000 });
+            const out = typeof r.stdout === "string" ? r.stdout.trim() : "";
+            return r.status === 0 && out !== "" ? out : null;
+        },
+        transcriptDirs(ccSessionId) {
+            try {
+                return readdirSync(projects).filter((d) => existsSync(join(projects, d, `${ccSessionId}.jsonl`)));
+            }
+            catch {
+                return [];
+            }
+        },
+    };
+}

package/dist/durable/discover.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The step-2 discovery of BACKBONE C1/C02-R26: the live tracked claude processes on this machine,
+ * one per conversation, each with its exact argv (KERN_PROCARGS2 / /proc, never ps), environment
+ * and cwd.
+ *
+ * A tracked claude is the process `mnemom agent` exec'd: its environment carries the session name
+ * (MNEMOM_AGENT_SESSION_NAME) and the conversation id (the `x-mnemom-conversation-id` line of
+ * ANTHROPIC_CUSTOM_HEADERS on the terminal shape, MNEMOM_AGENT_RC_CONVERSATION_ID on the RC shape).
+ * Its descendants (hooks, MCP servers, tools) inherit that environment, so the claude is the
+ * topmost process of the conversation: the one whose parent does not carry the same conversation
+ * id. The parent launcher's own argv is read too: its tokens after `--` pin the passthrough split.
+ *
+ * Pure over an injected snapshot (`ProcSnapshot`); `liveSnapshot` is the thin driver.
+ */
+import { type ProcArgs, type ProcDeps, type ProcRow } from "./proc.js";
+export declare const SESSION_NAME_ENV = "MNEMOM_AGENT_SESSION_NAME";
+export declare const RC_CONVERSATION_ENV = "MNEMOM_AGENT_RC_CONVERSATION_ID";
+/** The agent slug the original runs under (its x-mnemom-agent header), or null. */
+export declare function agentSlugOf(env: Readonly<Record<string, string>>): string | null;
+export interface LiveClaude {
+    pid: number;
+    ppid: number;
+    conversationId: string;
+    sessionName: string;
+    /** argv[0..] exactly as exec'd. */
+    argv: string[];
+    env: Record<string, string>;
+    /** The process cwd (always a realpath), or null when unreadable. */
+    cwd: string | null;
+    /** The parent launcher's tokens after its own `--`, or null when it is not readable. */
+    passthroughHint: string[] | null;
+    /** RC shape (the conversation id came from the RC proxy variable). */
+    remoteControl: boolean;
+    /** The process start time when it was discovered (readProcStart), or null when unreadable. */
+    start: string | null;
+}
+export interface ProcSnapshot {
+    table: ProcRow[];
+    args: Map<number, ProcArgs>;
+    cwd(pid: number): string | null;
+    start(pid: number): string | null;
+}
+/** `KEY=value` entries as a record (the first `=` splits). */
+export declare function envRecord(entries: readonly string[]): Record<string, string>;
+/** The conversation a process belongs to, from its environment (terminal header first). */
+export declare function conversationOf(env: Readonly<Record<string, string>>): {
+    id: string;
+    rc: boolean;
+} | null;
+/**
+ * The tokens after the first `--` of `mnemom agent`'s argv; [] when the argv was read and has
+ * none (the launcher takes no flag passthrough without `--`, so the split is still exact); null
+ * when the parent's argv could not be read or is not a `mnemom agent` launch (the split is then by
+ * shape, see splitLauncherArgv).
+ */
+export declare function launcherPassthrough(argv: readonly string[] | undefined): string[] | null;
+/** A durable seat's claude (C2 sets MNEMOM_SEAT_* in its env): never an original to adopt. */
+export declare function isSeatEnv(env: Readonly<Record<string, string>>): boolean;
+/**
+ * The process is the claude binary itself (argv[0] names it), not a hook, MCP server or tool that
+ * inherited the session's environment: such a child outlives a dead claude (reparented to init) and
+ * must never read as the live session.
+ */
+export declare function isClaudeArgv0(argv0: string | undefined): boolean;
+/** The live tracked claudes in a snapshot, one per conversation (the lowest pid on a tie). */
+export declare function findLiveClaudes(snap: ProcSnapshot, selfPid: number): LiveClaude[];
+/** A snapshot of this user's processes (argv and environment read exactly). */
+export declare function liveSnapshot(deps?: ProcDeps, uid?: number): ProcSnapshot;

package/dist/durable/discover.js

@@ -0,0 +1,123 @@
+/**
+ * The step-2 discovery of BACKBONE C1/C02-R26: the live tracked claude processes on this machine,
+ * one per conversation, each with its exact argv (KERN_PROCARGS2 / /proc, never ps), environment
+ * and cwd.
+ *
+ * A tracked claude is the process `mnemom agent` exec'd: its environment carries the session name
+ * (MNEMOM_AGENT_SESSION_NAME) and the conversation id (the `x-mnemom-conversation-id` line of
+ * ANTHROPIC_CUSTOM_HEADERS on the terminal shape, MNEMOM_AGENT_RC_CONVERSATION_ID on the RC shape).
+ * Its descendants (hooks, MCP servers, tools) inherit that environment, so the claude is the
+ * topmost process of the conversation: the one whose parent does not carry the same conversation
+ * id. The parent launcher's own argv is read too: its tokens after `--` pin the passthrough split.
+ *
+ * Pure over an injected snapshot (`ProcSnapshot`); `liveSnapshot` is the thin driver.
+ */
+import { basename } from "node:path";
+import { liveProcDeps, processTable, readManyProcArgs, readProcCwd, readProcStart, } from "./proc.js";
+export const SESSION_NAME_ENV = "MNEMOM_AGENT_SESSION_NAME";
+export const RC_CONVERSATION_ENV = "MNEMOM_AGENT_RC_CONVERSATION_ID";
+const CONVERSATION_HEADER_RE = /^x-mnemom-conversation-id:\s*(\S+)\s*$/im;
+const AGENT_HEADER_RE = /^x-mnemom-agent:\s*(\S+)\s*$/im;
+/** The agent slug the original runs under (its x-mnemom-agent header), or null. */
+export function agentSlugOf(env) {
+    const m = AGENT_HEADER_RE.exec(env.ANTHROPIC_CUSTOM_HEADERS ?? "");
+    return m ? m[1] : null;
+}
+/** `KEY=value` entries as a record (the first `=` splits). */
+export function envRecord(entries) {
+    const out = {};
+    for (const e of entries) {
+        const i = e.indexOf("=");
+        if (i > 0)
+            out[e.slice(0, i)] = e.slice(i + 1);
+    }
+    return out;
+}
+/** The conversation a process belongs to, from its environment (terminal header first). */
+export function conversationOf(env) {
+    const m = CONVERSATION_HEADER_RE.exec(env.ANTHROPIC_CUSTOM_HEADERS ?? "");
+    if (m)
+        return { id: m[1], rc: false };
+    const rc = env[RC_CONVERSATION_ENV];
+    return rc ? { id: rc, rc: true } : null;
+}
+/**
+ * The tokens after the first `--` of `mnemom agent`'s argv; [] when the argv was read and has
+ * none (the launcher takes no flag passthrough without `--`, so the split is still exact); null
+ * when the parent's argv could not be read or is not a `mnemom agent` launch (the split is then by
+ * shape, see splitLauncherArgv).
+ */
+export function launcherPassthrough(argv) {
+    if (!argv)
+        return null;
+    const i = argv.indexOf("--");
+    // A parent that is not `… agent …` (a wrapper, a shell) says nothing about the split.
+    if (!(i < 0 ? argv : argv.slice(0, i)).includes("agent"))
+        return null;
+    return i < 0 ? [] : argv.slice(i + 1);
+}
+/** A durable seat's claude (C2 sets MNEMOM_SEAT_* in its env): never an original to adopt. */
+export function isSeatEnv(env) {
+    return Object.keys(env).some((k) => k.startsWith("MNEMOM_SEAT_"));
+}
+/**
+ * The process is the claude binary itself (argv[0] names it), not a hook, MCP server or tool that
+ * inherited the session's environment: such a child outlives a dead claude (reparented to init) and
+ * must never read as the live session.
+ */
+export function isClaudeArgv0(argv0) {
+    return argv0 !== undefined && basename(argv0) === "claude";
+}
+/** The live tracked claudes in a snapshot, one per conversation (the lowest pid on a tie). */
+export function findLiveClaudes(snap, selfPid) {
+    const rows = new Map(snap.table.map((r) => [r.pid, r]));
+    const convOf = (pid) => {
+        const a = snap.args.get(pid);
+        return a ? conversationOf(envRecord(a.env)) : null;
+    };
+    const byConv = new Map();
+    for (const row of [...snap.table].sort((a, b) => a.pid - b.pid)) {
+        if (row.pid === selfPid)
+            continue;
+        const a = snap.args.get(row.pid);
+        if (!a)
+            continue;
+        const env = envRecord(a.env);
+        const conv = conversationOf(env);
+        const name = env[SESSION_NAME_ENV];
+        if (!conv || !name || isSeatEnv(env))
+            continue;
+        if (!isClaudeArgv0(a.argv[0]))
+            continue; // a hook, MCP server or tool, never the session
+        if (convOf(row.ppid)?.id === conv.id)
+            continue; // a descendant of the claude
+        if (byConv.has(conv.id))
+            continue;
+        const parent = rows.has(row.ppid) ? snap.args.get(row.ppid) : undefined;
+        byConv.set(conv.id, {
+            pid: row.pid,
+            ppid: row.ppid,
+            conversationId: conv.id,
+            sessionName: name,
+            argv: a.argv,
+            env,
+            cwd: snap.cwd(row.pid),
+            passthroughHint: launcherPassthrough(parent?.argv),
+            remoteControl: conv.rc,
+            start: snap.start(row.pid),
+        });
+    }
+    return [...byConv.values()];
+}
+/** A snapshot of this user's processes (argv and environment read exactly). */
+export function liveSnapshot(deps = liveProcDeps, uid = process.getuid?.() ?? -1) {
+    const table = processTable(deps);
+    const mine = table.filter((r) => r.uid === uid).map((r) => r.pid);
+    const args = readManyProcArgs(mine, deps);
+    return {
+        table,
+        args,
+        cwd: (pid) => readProcCwd(pid, deps),
+        start: (pid) => readProcStart(pid, deps),
+    };
+}

package/dist/durable/gate.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The off-state answer of a durable verb the CLI registers hidden (C14-R22: with the flag off
+ * `sessions adopt` does not exist; BACKBONE Flags/CLI: every durable verb word, `--help` too,
+ * exits 2 with gatedMessage(…, 'durable') and no side effects). Both hold at once: commander's own
+ * unknown-command line, then the gate pointer. The caller prints the lines on stderr and exits 2.
+ */
+import { type ExperimentalId } from "../lib/experimental.js";
+export declare function durableVerbOffLines(word: string, what: string, enabled: readonly ExperimentalId[]): string[] | null;

package/dist/durable/gate.js

@@ -0,0 +1,13 @@
+/**
+ * The off-state answer of a durable verb the CLI registers hidden (C14-R22: with the flag off
+ * `sessions adopt` does not exist; BACKBONE Flags/CLI: every durable verb word, `--help` too,
+ * exits 2 with gatedMessage(…, 'durable') and no side effects). Both hold at once: commander's own
+ * unknown-command line, then the gate pointer. The caller prints the lines on stderr and exits 2.
+ */
+import { gateCheck } from "../lib/experimental.js";
+export function durableVerbOffLines(word, what, enabled) {
+    const pointer = gateCheck(what, "durable", enabled);
+    return pointer === null
+        ? null
+        : [`error: unknown command '${word}' (durable sessions are off)`, pointer];
+}

package/dist/durable/launch-spec.d.ts

@@ -0,0 +1,137 @@
+/**
+ * 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 { EFFORT_VALUES, type LaunchSpec, type LauncherKey } from "../vendor/durable-contract/index.js";
+/** The bypass flag the launcher's yolo default injects (cli/src/commands/agent.ts buildCliArgs). */
+export declare const YOLO_FLAG = "--dangerously-skip-permissions";
+/** The launcher option for Remote Control; never committed in M1, always named when dropped. */
+export declare const REMOTE_CONTROL_FLAG = "--remote-control";
+/** The user flags a spec can carry, after the filter. */
+export interface KeptFlags {
+    model?: string;
+    effort?: (typeof EFFORT_VALUES)[number];
+    trim_mcp: boolean;
+}
+/**
+ * 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 declare function filterSeatArgv(argv: readonly string[]): {
+    kept: KeptFlags;
+    invalid: string[];
+};
+/** The dropped-flag names (ruling 15) plus the invalid-value names, positional entry kept last. */
+export declare function droppedNames(argv: readonly string[]): string[];
+/** What the one builder reads (S1 BUILDER_INPUT_TABLE). */
+export interface BuilderInput {
+    /** `running`: the original claude's argv read exactly; `idle`: the launcher's continue argv. */
+    source: "running" | "idle";
+    /**
+     * The argv the spec's flags come from, claude-level, without the daemon-only flags: the
+     * launcher's own --model/--effort/--trim-mcp plus the user's passthrough
+     * (semanticArgvOf splits an original claude argv into these).
+     */
+    argv: readonly string[];
+    /** The user's tokens whose dropped flags are named (the passthrough). Defaults to `argv`. */
+    userArgv?: readonly string[];
+    /** The launcher injected the yolo-default bypass flag (named as dropped, S1 freeze). */
+    yoloInjected?: boolean;
+    /** The launch was (or would have auto-upgraded to) Remote Control: named, never committed. */
+    remoteControl?: boolean;
+    /** The registered worktree root (realpath, checked by the C4 cwd rule before this call). */
+    cwd: string;
+}
+export interface BuiltLaunchSpec {
+    spec: LaunchSpec;
+    /** The 'flags dropped:' list (ruling 15), unchanged into the Note, lock and non-TTY lines. */
+    dropped: string[];
+    /** The canonical spec hash (S1 specHash): what the charter commits. */
+    hash: string;
+}
+/**
+ * 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 declare function buildDurableLaunchSpec(input: BuilderInput): Promise<BuiltLaunchSpec>;
+/** The seat's user-flag argv for a spec (the daemon adds its own flags around it), C14-R01. */
+export declare function specUserArgv(spec: LaunchSpec): string[];
+/** The canonical multiset of a spec's user flags, for comparing with an argv (S1 canonicalArgvPairs). */
+export declare function specUserPairs(spec: LaunchSpec): string[];
+/** The original claude argv split into what the launcher injected and the user's passthrough. */
+export interface LauncherArgvSplit {
+    /** --model/--effort/--trim-mcp as the launcher rendered them (the spec's launcher half). */
+    launcherArgv: string[];
+    passthrough: string[];
+    yoloInjected: boolean;
+    /** The --session-id the launcher pinned, if any. */
+    sessionId: string | null;
+    /**
+     * The split is known exactly: the parent launcher's passthrough pinned it, or the parent was
+     * read and had no `--` (so the user passed no flags). Otherwise it was read by shape.
+     */
+    exact: boolean;
+    /**
+     * When not exact: the launcher-shaped flags read by shape that a user could also have passed
+     * (--session-id, --plugin-dir, the trailing --mcp-config). They are named as dropped, so a
+     * user's own flag is never silently taken as launcher-injected (C14-R02, R12, R26). --model,
+     * --effort and the yolo flag are never listed: they are kept or named whoever passed them.
+     */
+    ambiguous: string[];
+}
+/**
+ * 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 declare function splitLauncherArgv(argv: readonly string[], passthroughHint?: readonly string[] | null): LauncherArgvSplit;
+/** The running-source builder input for an original claude's exact argv and its checked cwd. */
+export declare function runningSourceInput(originalArgv: readonly string[], cwd: string, opts?: {
+    passthroughHint?: readonly string[] | null;
+    remoteControl?: boolean;
+}): BuilderInput;
+/** The re-lock comparison of a built spec with the committed one, by the S1 canonical hash. */
+export type SpecCompare = {
+    changed: false;
+} | {
+    changed: true;
+    status: 422;
+    code: "durable_unsupported";
+    feature: "launch_spec_change";
+};
+export declare function compareWithCommitted(built: LaunchSpec, committed: LaunchSpec | string): Promise<SpecCompare>;
+/**
+ * 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 declare function launchSpecChangeFixLines(ctx: {
+    name: string;
+    flags: string;
+    launcherKey: LauncherKey;
+    soleLockedSession: boolean;
+}): [string, ...string[]];
+/** The adopt Note for an adopted row (C14-R12, R21): S1 grammar, unchanged builder names. */
+export declare function adoptNote(dropped: readonly string[]): string;