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

package/dist/durable/adopt-live.js

@@ -0,0 +1,152 @@
+/**
+ * The thin live driver for `sessions adopt`: real processes, files, HTTP and the terminal. The
+ * decisions live in adopt.ts (pure over AdoptDeps); this file only wires them to the machine.
+ */
+import { randomUUID } from "node:crypto";
+import { accessSync, constants, readFileSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { createInterface } from "node:readline";
+import { parse as parseToml } from "smol-toml";
+import { executorStateOk, executorStatePath, LAUNCHER_KEYS, } from "../vendor/durable-contract/index.js";
+import { getApiUrl, MNEMOM_DIR } from "../lib/config.js";
+import { resolveAuth } from "../lib/auth.js";
+import { readSessionRecords } from "../lib/agent-ledger.js";
+import { LAUNCHER_CONFIG_PATH } from "../lib/launcher-config.js";
+import { mnemomFetch } from "../lib/version-gate.js";
+import { httpAdoptApi } from "./adopt-api.js";
+import { liveCwdDeps } from "./cwd-rule.js";
+import { findLiveClaudes, liveSnapshot } from "./discover.js";
+import { liveProcDeps, processTableWithStarts, readProcIdentity, readProcStart } from "./proc.js";
+/** The ledger facts for a conversation: its newest record. */
+export function ledgerFactsFrom(records, cid) {
+    let r;
+    for (const x of records)
+        if (x.conversation_id === cid)
+            r = x;
+    if (!r)
+        return null;
+    const goalMode = r.goal_mode ?? (r.contract ? "on" : "off");
+    return {
+        agentId: r.agent_id,
+        agentLabel: r.agent_slug,
+        orgId: r.org_id,
+        goalMode,
+        requirements: r.contract?.requirements ? r.contract.requirements.length : null,
+        launchShape: r.launch_shape,
+    };
+}
+/** The launcher key `durable` (MNEMOM_AGENT_DURABLE, then launcher.toml), default off. */
+export function launcherKeyFrom(env, tomlText) {
+    const ok = (v) => typeof v === "string" && LAUNCHER_KEYS.includes(v);
+    const e = env.MNEMOM_AGENT_DURABLE?.trim().toLowerCase();
+    if (ok(e))
+        return e;
+    if (tomlText !== null) {
+        try {
+            const v = parseToml(tomlText).durable;
+            if (ok(v))
+                return v;
+        }
+        catch {
+            // an unparseable launcher.toml is the launcher's error to report, not adopt's
+        }
+    }
+    return "off";
+}
+/** The executor state file, or null when absent or not the frozen S1 shape. */
+export function executorStateFrom(text) {
+    if (text === null)
+        return null;
+    try {
+        const v = JSON.parse(text);
+        return executorStateOk(v) ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+const readOrNull = (p) => {
+    try {
+        return readFileSync(p, "utf8");
+    }
+    catch {
+        return null;
+    }
+};
+export async function authHeaders() {
+    const cred = await resolveAuth();
+    if (cred.type === "jwt")
+        return { Authorization: `Bearer ${cred.token.trim()}` };
+    if (cred.type === "api-key")
+        return { "X-Mnemom-Api-Key": cred.key.trim() };
+    return {};
+}
+/** A [Y/n] answer: anything not starting with n is yes. */
+export function answerIsYes(a) {
+    return !/^\s*n/i.test(a);
+}
+function ask(question) {
+    return new Promise((resolve) => {
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        rl.question(question, (a) => {
+            // Settle before close(): readline emits "close" synchronously, and the close handler
+            // below would otherwise settle the prompt as declined first.
+            resolve(answerIsYes(a));
+            rl.close();
+        });
+        rl.on("close", () => resolve(false));
+    });
+}
+export function liveAdoptDeps() {
+    const home = homedir();
+    return {
+        discover: () => findLiveClaudes(liveSnapshot(), process.pid),
+        ledger: (cid) => ledgerFactsFrom(readSessionRecords({ dir: MNEMOM_DIR }), cid),
+        api: httpAdoptApi({
+            base: getApiUrl(),
+            auth: authHeaders,
+            fetch: (u, i) => mnemomFetch(u, i),
+            idempotencyKey: randomUUID,
+        }),
+        cwd: (live) => {
+            const env = { ...process.env };
+            delete env.CLAUDE_CONFIG_DIR;
+            if (live.env.CLAUDE_CONFIG_DIR)
+                env.CLAUDE_CONFIG_DIR = live.env.CLAUDE_CONFIG_DIR;
+            return liveCwdDeps(env);
+        },
+        realpath: (p) => {
+            try {
+                return realpathSync(p);
+            }
+            catch {
+                return null;
+            }
+        },
+        executorState: () => executorStateFrom(readOrNull(executorStatePath(home))),
+        // Not wired: S1 ExecutorState and no other frozen host-state shape records the pinned claude
+        // path (gaps/c4-pinned-binary-state.md). The check is then the daemon's, at spawn.
+        pinnedBinary: () => null,
+        binaryRunnable: (p) => {
+            try {
+                accessSync(p, constants.X_OK);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        ownCheckout: () => liveCwdDeps().gitToplevel(process.cwd()),
+        launcherKey: () => launcherKeyFrom(process.env, readOrNull(LAUNCHER_CONFIG_PATH)),
+        processTable: () => processTableWithStarts(liveProcDeps),
+        identity: (pid) => readProcIdentity(pid, liveProcDeps),
+        startOf: (pid) => readProcStart(pid, liveProcDeps),
+        signal: (pid, sig) => process.kill(pid, sig),
+        confirm: (q) => (process.stdin.isTTY ? ask(q) : Promise.resolve(false)),
+        out: (l) => process.stdout.write(`${l}\n`),
+        err: (l) => process.stderr.write(`${l}\n`),
+        sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+        now: () => Date.now(),
+        selfPid: process.pid,
+    };
+}

package/dist/durable/adopt.d.ts

@@ -0,0 +1,305 @@
+/**
+ * `mnemom agent sessions adopt` (BACKBONE C4; C14-R12..R25, R20, R21; C18-R10).
+ *
+ * Plan (no side effects; `--dry-run` stops here): the live tracked claudes on this machine (the
+ * step-2 discovery), grouped one table per agent. For each session: its row (A2 GET), the C4 cwd
+ * rule with the transcript-slug check, the spec built from the original's exact argv by the one
+ * builder, and the Note ('approvals with you; flags dropped: …', S1 grammar). A group holding a
+ * session that fails the cwd rule or is otherwise unadoptable is skipped whole (R15), unless
+ * --own-agent moves its adoptable sessions to their own agent. The group checks (R17 sharing,
+ * R18 lock preconditions) run through the non-mutating lock check before anything is stopped;
+ * a refusal prints its one-line fix and touches nothing. The check fails closed: a check route the
+ * API does not serve (404/405 with no durable code), a timeout or a dropped response refuses the
+ * group as durable_precondition_unavailable, so an original whose group checks did not run is
+ * never stopped.
+ *
+ * A live original whose row is already locked (C14-R11 re-run): its spec is built from its exact
+ * argv and compared with the committed charter's launch_spec by the S1 specHash. Equal is a no-op
+ * (no check, no lock request, no signal). Different is refused 422-style on stderr
+ * (durable_unsupported {feature: launch_spec_change} and the S1 launch_spec_change fix line) and
+ * the command exits 1, again with no request and no signal. A committed spec that cannot be read
+ * is refused the same way as durable_precondition_unavailable.
+ *
+ * Run (after one [Y/n] per adoptable group): per session the U01 handover order (R25): the
+ * pinned-binary check ran in the plan (wired only when a pinned path is known: S1 freezes no host
+ * state field for it, see adopt-live.ts), SIGSTOP of the original claude pid only (an original
+ * that exited meanwhile is reported and skipped), the lock request (retried under one
+ * Idempotency-Key until an answer is decisive, see lockAnswerKind), SIGCONT only on a 4xx
+ * refusal, then the seat's hello (the row reaches running) or ATTACH_WAIT_S, then SIGKILL of the
+ * original's whole tree minus this process. Every signal re-checks its pid first (the original's
+ * identity; each tree pid's start time against the snapshot) and a pid that no longer matches is
+ * skipped and named, never signalled. The handover fails closed: when no attempt is
+ * decisive a request may still be in flight, so a re-read that shows the row locked proceeds and
+ * anything else leaves the original stopped (never two running copies of one conversation);
+ * adopt then names the pid and the way out.
+ *
+ * Every code adopt prints is an S1 code and every fix line an S1 catalogue entry rendered once
+ * (renderFixLine); a line whose parameters are unknown is not printed (C11-R27).
+ *
+ * On a host home (an executor state file present) the summary prints the current S1 risk line
+ * verbatim; adopt writes no seen record and never reads the stored risk-line version (R20).
+ */
+import { type CwdKind, type ExecutorState, type FixKey, type LauncherKey, type LaunchSpec, type LockBody } from "../vendor/durable-contract/index.js";
+import { type CwdDeps } from "./cwd-rule.js";
+import { type LiveClaude } from "./discover.js";
+import { type ProcIdentity, type ProcRow } from "./proc.js";
+/** What the local launch ledger knows about a conversation. */
+export interface LedgerFacts {
+    agentId: string | null;
+    agentLabel: string;
+    orgId: string;
+    goalMode: "off" | "on" | "implicit";
+    requirements: number | null;
+    launchShape: string;
+}
+/** The fields of the A2 session row adopt reads (absent fields are unknown, never assumed). */
+export interface SessionRow {
+    agent_id?: string;
+    name?: string;
+    cc_session_id?: string | null;
+    durable_mode?: "tracked" | "locked";
+    state?: string;
+    effective_state?: string;
+    lease_seconds?: number;
+    /** The committed charter's public commitments (A2 publicView); launch_spec among them. */
+    charter?: {
+        launch_spec?: unknown;
+    } | null;
+}
+export type ApiAnswer = {
+    kind: "ok";
+    status: number;
+    body: unknown;
+} | {
+    kind: "error";
+    status: number;
+    code: string | null;
+    details: unknown;
+    message: string;
+} | {
+    kind: "timeout";
+} | {
+    kind: "network";
+    message: string;
+};
+export interface AdoptApi {
+    getSession(cid: string, facts: LedgerFacts): Promise<ApiAnswer>;
+    /** The non-mutating lock check (group checks before any signal); same body as lock. */
+    lockCheck(cid: string, body: LockBody): Promise<ApiAnswer>;
+    /** One idempotencyKey per handover: every retry of one lock sends the same key. */
+    lock(cid: string, body: LockBody, idempotencyKey?: string): Promise<ApiAnswer>;
+}
+export interface AdoptDeps {
+    discover(): LiveClaude[];
+    ledger(cid: string): LedgerFacts | null;
+    api: AdoptApi;
+    /** The cwd-rule deps for one original (its own CLAUDE_CONFIG_DIR locates the transcript). */
+    cwd(live: LiveClaude): CwdDeps;
+    realpath(p: string): string | null;
+    executorState(): ExecutorState | null;
+    /**
+     * The pinned claude path recorded at host install, or null when this machine records none (the
+     * check is then the daemon's, at spawn; a missing pinned binary there takes the respawn path).
+     */
+    pinnedBinary(): string | null;
+    binaryRunnable(path: string): boolean;
+    /** This command's own git checkout (top level), offered for a not_git fix line, or null. */
+    ownCheckout(): string | null;
+    launcherKey(): LauncherKey;
+    processTable(): ProcRow[];
+    /** A pid's identity read now (start time and argv[0]), or null when it is gone. */
+    identity(pid: number): ProcIdentity | null;
+    /** A pid's start time read now (as processTable's start reads it), or null when it is gone. */
+    startOf(pid: number): string | null;
+    signal(pid: number, sig: "SIGSTOP" | "SIGCONT" | "SIGKILL"): void;
+    confirm(question: string): Promise<boolean>;
+    out(line: string): void;
+    err(line: string): void;
+    sleep(ms: number): Promise<void>;
+    now(): number;
+    selfPid: number;
+}
+export interface AdoptOptions {
+    dryRun?: boolean;
+    json?: boolean;
+    ownAgent?: boolean;
+}
+/**
+ * spec_change: an already-locked session whose live original's spec differs from the committed
+ * one, or could not be compared (refused on stderr, nothing touched, exit 1).
+ */
+export type SessionVerdict = "adopt" | "skip" | "unadoptable" | "durable" | "spec_change";
+export interface PlannedSession {
+    name: string;
+    conversation_id: string;
+    /** The Claude Code session id the seat resumes (null when the row has none: unadoptable). */
+    cc_session_id: string | null;
+    pid: number;
+    cwd: string | null;
+    /** "root" when the cwd rule passed, the S1 cwd_kind when it failed, null when not reached. */
+    cwd_kind: "root" | CwdKind | null;
+    verdict: SessionVerdict;
+    /** Why the session cannot be adopted (unadoptable / durable), or null. */
+    reason: string | null;
+    goal: "sealed" | "implicit" | "none";
+    rules: string;
+    note: string;
+    spec: LaunchSpec | null;
+    spec_hash: string | null;
+    dropped: string[];
+    fix: string | null;
+    /** Internal: what the handover needs. */
+    readonly _live?: LiveClaude;
+    readonly _row?: SessionRow;
+}
+export interface PlannedGroup {
+    agent_id: string | null;
+    agent: string;
+    verdict: "adopt" | "skip" | "refuse" | "none";
+    /** Why the group is skipped or refused, or null. */
+    reason: string | null;
+    code: string | null;
+    fix: string | null;
+    own_agent: boolean;
+    sessions: PlannedSession[];
+}
+export interface AdoptPlan {
+    groups: PlannedGroup[];
+    /** The S1 risk line on a host home, else null. */
+    risk_line: string | null;
+}
+/** The cwd the rule checks: the claude's PWD when it resolves to the process cwd (a symlink kept), else the process cwd. */
+export declare function ruleCwd(live: LiveClaude, realpath: (p: string) => string | null): string | null;
+/** The session row of a GET answer: the body itself, or its `session`; agent_id also from `agent.id`. */
+export declare function rowOf(a: ApiAnswer): SessionRow | null;
+/** What a refusal's fix line may be filled from. */
+export interface RefusalContext {
+    name: string;
+    launcherKey: LauncherKey;
+    /** The group's agent (for agent_contained when the refusal names none). */
+    agent?: string;
+}
+/**
+ * The S1 fix line for a lock refusal answered by the check or the lock route, or null when the
+ * code has none or a parameter it needs is unknown (no placeholder is ever printed).
+ */
+export declare function refusalFix(code: string | null, details: unknown, ctx: RefusalContext): string | null;
+/**
+ * The precheck route answered 404/405 with no durable code: the API does not serve it (see
+ * PRECHECK note in adopt-api.ts; gaps/c4-adopt-precheck-route.md). Adopt fails closed on it.
+ */
+export declare function isPrecheckMissing(a: ApiAnswer): boolean;
+/** The lock body for a planned session (S1 LOCK_BODY_KEYS: spec, executor_id, own_agent). */
+export declare function lockBodyFor(s: PlannedSession, executorId: string, ownAgent: boolean): LockBody;
+/** Build the plan: discovery, per-session checks, grouping and the group checks. No side effects. */
+export declare function planAdopt(deps: AdoptDeps, opts?: AdoptOptions): Promise<AdoptPlan>;
+/** The --json document (internal fields removed). */
+export declare function planJson(plan: AdoptPlan): unknown;
+/** One table per agent group (R12): Session, Goal, Rules, Note; Note last and unpadded. */
+export declare function renderGroup(g: PlannedGroup): string[];
+export declare function renderPlan(plan: AdoptPlan): string[];
+export type HandoverResult = 
+/** killed false: the original's pid named another process (or none) before SIGKILL; none sent. */
+{
+    ok: true;
+    name: string;
+    hello: boolean;
+    killed: boolean;
+} | {
+    ok: false;
+    name: string;
+    committed: false;
+    code: string;
+    fix: string | null;
+}
+/** The original exited before it could be stopped: no lock request was sent. */
+ | {
+    ok: false;
+    name: string;
+    committed: false;
+    gone: true;
+}
+/**
+ * The original's pid no longer names the process discovery saw (it ended while the confirm
+ * prompt waited, and the pid may be reused): no lock request, and nothing left stopped.
+ */
+ | {
+    ok: false;
+    name: string;
+    committed: false;
+    ended: true;
+}
+/**
+ * No lock attempt was decisive and no re-read showed the row locked: the lock may still commit,
+ * so the original (pid) is left stopped rather than resumed beside a seat (fail closed).
+ */
+ | {
+    ok: false;
+    name: string;
+    committed: null;
+    unconfirmed: true;
+    pid: number;
+    code: string;
+};
+/**
+ * The pid still names the process discovery saw: the same start time and argv[0]. A pid is reused
+ * once its process exits, so a bare pid is never signalled on its own (pid reuse guard).
+ */
+export declare function sameProcess(live: LiveClaude, now: ProcIdentity | null): boolean;
+/** Re-reads of the row after the lock attempts ran out undecided, REREAD_GAP_MS apart. */
+export declare const REREAD_ATTEMPTS = 3;
+export declare const REREAD_GAP_MS = 1000;
+/**
+ * What the server says about a lock whose answer never came. Only a row that carries its
+ * durable_mode counts as an answer; a failed read, or a row without the field, is no answer.
+ */
+export declare function commitOutcome(cid: string, deps: AdoptDeps, facts: LedgerFacts): Promise<"committed" | "not_committed" | "unknown">;
+/** Lock attempts per handover (the first plus same-key retries) and the gaps between them. */
+export declare const LOCK_RETRY_GAPS_MS: readonly [2000, 5000, 10000];
+export declare const LOCK_ATTEMPTS: number;
+/**
+ * How one lock answer reads:
+ *  - committed: any 2xx. A same-key replay of the first answer, or, once the api's 30 s window
+ *    has passed and the retry re-runs the lock, the already-locked noop ({changed:false}), which
+ *    the api answers only when the session is locked with this exact launch spec.
+ *  - refused: a 4xx refusal; the lock did not commit, so the original is resumed. Also
+ *    durable_precondition_unavailable on the first attempt: the api answers it only before the
+ *    commit write (the locked step runs before every probe), and no earlier request is in flight.
+ *  - pending: 409 idempotency_key_in_flight, the first request is still running; never a refusal.
+ *  - ambiguous: a timeout, a network error, any other 5xx (a 503 can follow a commit whose answer
+ *    was lost), durable_precondition_unavailable on a retry (an earlier request may still commit),
+ *    or 409 durable_retry (another lock on this session committed while this one ran).
+ */
+export type LockAnswerKind = "committed" | "refused" | "pending" | "ambiguous";
+/** A lock answer read once: a refusal always carries the error answer it came from. */
+export type LockDecision = {
+    kind: "refused";
+    a: Extract<ApiAnswer, {
+        kind: "error";
+    }>;
+} | {
+    kind: "committed" | "pending" | "ambiguous";
+    a: ApiAnswer;
+};
+/** One lock answer, read: see lockAnswerKind. */
+export declare function lockDecision(a: ApiAnswer, first: boolean): LockDecision;
+export declare function lockAnswerKind(a: ApiAnswer, first: boolean): LockAnswerKind;
+/**
+ * The lock, retried under one Idempotency-Key until an answer is decisive (committed or refused)
+ * or LOCK_ATTEMPTS run out; the last answer is returned either way.
+ */
+export declare function lockDecided(cid: string, body: LockBody, deps: AdoptDeps): Promise<LockDecision>;
+/** An API call that never throws (a throw reads as a dropped response). */
+export declare function settle(f: () => Promise<ApiAnswer>): Promise<ApiAnswer>;
+/** One session's U01 handover (R25 steps 2-5); step 1 ran in the plan. */
+export declare function handover(s: PlannedSession, g: PlannedGroup, exec: ExecutorState, deps: AdoptDeps, facts: LedgerFacts, launcherKey: LauncherKey): Promise<HandoverResult>;
+/**
+ * Ruling 19: the plan already holds a refusal, a refused group (lock check, executor state, pinned
+ * binary) or a locked session's changed spec (C14-R11). A group skipped by the cwd rule, or with
+ * nothing to adopt, is not a refusal.
+ */
+export declare function planRefused(plan: AdoptPlan): boolean;
+/** The whole verb. Returns the exit status: 1 when anything was refused (ruling 19), else 0. */
+export declare function adoptCommand(deps: AdoptDeps, opts?: AdoptOptions): Promise<number>;
+/** The fix catalogue entries adopt can print (exported for the catalogue lint test). */
+export declare const ADOPT_FIX_KEYS: readonly FixKey[];