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

package/dist/durable/adopt.js

@@ -0,0 +1,679 @@
+/**
+ * `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 { randomUUID } from "node:crypto";
+import { attachWaitSeconds, ATTACH_WAIT_S, FIX_LINES, lockRefusalFixKey, renderFixLine, RISK_LINE_TEXT, parseLaunchSpec, placeholdersOf, specHash, } from "../vendor/durable-contract/index.js";
+import { classifyCwd, cwdFixLine } from "./cwd-rule.js";
+import { agentSlugOf } from "./discover.js";
+import { adoptNote, buildDurableLaunchSpec, launchSpecChangeFixLines, runningSourceInput, specUserArgv, } from "./launch-spec.js";
+import { processTree } from "./proc.js";
+const GOAL = {
+    on: "sealed",
+    implicit: "implicit",
+    off: "none",
+};
+const UNADOPTABLE_TEXT = {
+    no_ledger: "no local launch record for this conversation",
+    no_row: "the session is not registered",
+    row_unreadable: "the session row could not be read",
+    server_shape: "a server-shape session (no local transcript)",
+    no_cc_session_id: "no Claude Code session id is registered, so a seat cannot resume it",
+    no_transcript: "no local transcript for its Claude Code session",
+    no_cwd: "its working directory cannot be read",
+};
+/** The cwd the rule checks: the claude's PWD when it resolves to the process cwd (a symlink kept), else the process cwd. */
+export function ruleCwd(live, realpath) {
+    const pwd = live.env.PWD;
+    if (pwd && live.cwd && realpath(pwd) === live.cwd)
+        return pwd;
+    return live.cwd;
+}
+/** The session row of a GET answer: the body itself, or its `session`; agent_id also from `agent.id`. */
+export function rowOf(a) {
+    if (a.kind !== "ok" || a.body === null || typeof a.body !== "object")
+        return null;
+    const b = a.body;
+    const inner = (b.session && typeof b.session === "object" ? b.session : b);
+    if (inner.agent_id === undefined && typeof inner.agent?.id === "string")
+        return { ...inner, agent_id: inner.agent.id };
+    return inner;
+}
+async function planSession(live, deps, launcherKey) {
+    const facts = deps.ledger(live.conversationId);
+    const base = {
+        name: live.sessionName,
+        conversation_id: live.conversationId,
+        cc_session_id: null,
+        pid: live.pid,
+        cwd: live.cwd,
+        cwd_kind: null,
+        verdict: "unadoptable",
+        reason: null,
+        goal: facts ? GOAL[facts.goalMode] : "none",
+        rules: facts?.requirements != null ? String(facts.requirements) : "-",
+        note: "",
+        spec: null,
+        spec_hash: null,
+        dropped: [],
+        fix: null,
+        _live: live,
+    };
+    const unadoptable = (reason) => {
+        base.verdict = "unadoptable";
+        base.reason = reason;
+        base.note = `unadoptable: ${UNADOPTABLE_TEXT[reason]}`;
+        return {
+            s: base,
+            agentId: facts?.agentId ?? null,
+            agentLabel: facts?.agentLabel ?? agentSlugOf(live.env) ?? "unknown",
+        };
+    };
+    if (!facts)
+        return unadoptable("no_ledger");
+    if (facts.launchShape === "server")
+        return unadoptable("server_shape");
+    const got = await settle(() => deps.api.getSession(live.conversationId, facts));
+    if (got.kind === "error" && got.status === 404)
+        return unadoptable("no_row");
+    const row = rowOf(got);
+    if (!row)
+        return unadoptable("row_unreadable");
+    Object.assign(base, { _row: row });
+    const agentId = row.agent_id ?? facts.agentId;
+    if (row.durable_mode === "locked") {
+        await compareLocked(base, live, row, deps, launcherKey);
+        return { s: base, agentId, agentLabel: facts.agentLabel };
+    }
+    const cc = typeof row.cc_session_id === "string" && row.cc_session_id ? row.cc_session_id : null;
+    if (cc === null)
+        return unadoptable("no_cc_session_id");
+    base.cc_session_id = cc;
+    const cwd = ruleCwd(live, deps.realpath);
+    if (cwd === null)
+        return unadoptable("no_cwd");
+    const verdict = classifyCwd(cwd, deps.cwd(live), cc);
+    if (!verdict.ok && verdict.cwd_kind === null)
+        return unadoptable(verdict.unadoptable);
+    if (!verdict.ok) {
+        base.verdict = "skip";
+        base.cwd_kind = verdict.cwd_kind;
+        base.reason = `cwd_${verdict.cwd_kind}`;
+        // A tracked row holds the name, so the fix carries the done clause (S1 fix-line rule).
+        base.fix = cwdFixLine(verdict, { name: live.sessionName, launcherKey, nameHeld: true });
+        base.note = cwdNote(verdict.cwd_kind, base.fix);
+        return { s: base, agentId, agentLabel: facts.agentLabel };
+    }
+    base.cwd = verdict.root;
+    base.cwd_kind = "root";
+    const built = await buildDurableLaunchSpec(runningSourceInput(live.argv.slice(1), verdict.root, {
+        passthroughHint: live.passthroughHint,
+        remoteControl: live.remoteControl,
+    }));
+    base.verdict = "adopt";
+    base.spec = built.spec;
+    base.spec_hash = built.hash;
+    base.dropped = built.dropped;
+    base.note = adoptNote(built.dropped);
+    return { s: base, agentId, agentLabel: facts.agentLabel };
+}
+const cwdNote = (kind, fix) => (fix ? `${kind}: ${fix}` : kind);
+/**
+ * C14-R11: a live original of an already-locked session. Build its spec from the exact argv (at
+ * the realpath of its cwd, as the committed spec holds it) and compare by the S1 specHash with the
+ * committed charter's launch_spec. Sets the session's verdict; makes no request and no signal.
+ */
+async function compareLocked(base, live, row, deps, launcherKey) {
+    const committed = parseLaunchSpec(row.charter?.launch_spec ?? null);
+    const cwd = ruleCwd(live, deps.realpath);
+    const real = cwd === null ? null : deps.realpath(cwd);
+    if (committed === null || real === null) {
+        base.verdict = "spec_change";
+        base.reason = "spec_unverified";
+        base.note = "locked: the committed launch spec could not be compared";
+        return;
+    }
+    let built;
+    try {
+        built = await buildDurableLaunchSpec(runningSourceInput(live.argv.slice(1), real, {
+            passthroughHint: live.passthroughHint,
+            remoteControl: live.remoteControl,
+        }));
+    }
+    catch {
+        base.verdict = "spec_change";
+        base.reason = "spec_unverified";
+        base.note = "locked: the committed launch spec could not be compared";
+        return;
+    }
+    if ((await specHash(built.spec)) === (await specHash(committed))) {
+        base.verdict = "durable";
+        base.reason = "already_durable";
+        base.note = "already durable: not adopted again";
+        return;
+    }
+    base.verdict = "spec_change";
+    base.reason = "launch_spec_change";
+    base.spec = built.spec;
+    base.spec_hash = built.hash;
+    base.dropped = built.dropped;
+    base.note = "locked: the launch spec differs from the committed one";
+    // The sole-unlock line needs "the agent's sole locked session", which no S1 route lets adopt
+    // read (gaps/c4-relock-sole-unlock.md): it is never offered from here.
+    // launchSpecChangeFixLines' tuple type guarantees the launch_spec_change line is first.
+    base.fix = launchSpecChangeFixLines({
+        name: live.sessionName,
+        flags: specUserArgv(built.spec).join(" "),
+        launcherKey,
+        soleLockedSession: false,
+    })[0];
+}
+/**
+ * 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 function refusalFix(code, details, ctx) {
+    const d = (details && typeof details === "object" ? details : {});
+    let key;
+    if (code === "durable_agent_contained") {
+        key = d.status === "killed" ? "agent_killed" : "agent_contained";
+    }
+    else if (code !== null && code in LOCK_REFUSAL_FIX_CODES) {
+        key = lockRefusalFixKey({ code: code });
+    }
+    else
+        key = null;
+    if (key === null)
+        return null;
+    const params = { name: ctx.name };
+    const agent = typeof d.agent === "string" ? d.agent : ctx.agent;
+    if (agent)
+        params.agent = agent;
+    const refusals = Array.isArray(d.refusals) ? d.refusals : [];
+    const repos = refusals
+        .map((r) => r.repo)
+        .filter((r) => typeof r === "string" && r !== "");
+    if (repos.length > 0)
+        params.repo = repos.join(", ");
+    if (placeholdersOf(key).some((p) => params[p] === undefined))
+        return null;
+    return renderFixLine(key, { launcherKey: ctx.launcherKey, nameHeld: true, params });
+}
+const LOCK_REFUSAL_FIX_CODES = Object.freeze({
+    durable_lock_not_entitled: true,
+    durable_lock_mfa_required: true,
+    durable_lock_branch_unprotected: true,
+    durable_lock_agent_shared: true,
+    durable_no_executor: true,
+    // No durable_cwd_not_root: S1 makes it a CLI-only code (codes.ts:135, status null, surfaces
+    // ["cli"]), so neither route can answer it, and its one field, cwd_kind, names no path for a fix
+    // line. The cwd rule is adopt's own (classifyCwd), with its own fix lines (cwdFixLine).
+    durable_precondition_unavailable: true,
+});
+/**
+ * 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 function isPrecheckMissing(a) {
+    return a.kind === "error" && (a.status === 404 || a.status === 405) && a.code === null;
+}
+/** The lock body for a planned session (S1 LOCK_BODY_KEYS: spec, executor_id, own_agent). */
+export function lockBodyFor(s, executorId, ownAgent) {
+    if (!s.spec)
+        throw new RangeError(`no spec for ${s.name}`);
+    return ownAgent
+        ? { spec: s.spec, executor_id: executorId, own_agent: true }
+        : { spec: s.spec, executor_id: executorId };
+}
+/** Build the plan: discovery, per-session checks, grouping and the group checks. No side effects. */
+export async function planAdopt(deps, opts = {}) {
+    const launcherKey = deps.launcherKey();
+    const exec = deps.executorState();
+    const groups = new Map();
+    for (const live of deps.discover()) {
+        const { s, agentId, agentLabel } = await planSession(live, deps, launcherKey);
+        const key = agentId ?? `?${agentLabel}`;
+        let g = groups.get(key);
+        if (!g) {
+            g = {
+                agent_id: agentId,
+                agent: agentLabel,
+                verdict: "adopt",
+                reason: null,
+                code: null,
+                fix: null,
+                own_agent: false,
+                sessions: [],
+            };
+            groups.set(key, g);
+        }
+        g.sessions.push(s);
+    }
+    let ownCheckout;
+    for (const g of groups.values()) {
+        g.sessions.sort((a, b) => a.name.localeCompare(b.name));
+        // not_git: offer a checkout this agent already runs in, else this command's own (C11-R27).
+        for (const s of g.sessions) {
+            if (s.cwd_kind !== "not_git")
+                continue;
+            const root = g.sessions.find((x) => x.cwd_kind === "root")?.cwd ?? null;
+            if (root === null && ownCheckout === undefined)
+                ownCheckout = deps.ownCheckout();
+            const checkout = root ?? ownCheckout ?? null;
+            if (checkout === null)
+                continue;
+            s.fix = cwdFixLine({ ok: false, cwd_kind: "not_git", params: { checkout } }, { name: s.name, launcherKey, nameHeld: true });
+            s.note = cwdNote("not_git", s.fix);
+        }
+        const adoptable = g.sessions.filter((s) => s.verdict === "adopt");
+        const blocking = g.sessions.filter((s) => s.verdict === "skip" || s.verdict === "unadoptable");
+        if (adoptable.length === 0) {
+            g.verdict = blocking.length > 0 ? "skip" : "none";
+            g.reason = blocking.length > 0 ? blocking[0].reason : null;
+            continue;
+        }
+        if (blocking.length > 0 && !opts.ownAgent) {
+            // R15: the whole group is skipped; the header names the blocking session.
+            g.verdict = "skip";
+            const first = blocking[0];
+            g.reason = `${first.reason} (${first.name})`;
+            continue;
+        }
+        g.own_agent = blocking.length > 0 || opts.ownAgent === true;
+        if (!exec) {
+            g.verdict = "refuse";
+            g.code = "durable_no_executor";
+            g.fix = renderFixLine("no_executor", { launcherKey, nameHeld: true, params: {} });
+            continue;
+        }
+        const pinned = deps.pinnedBinary();
+        if (pinned !== null && !deps.binaryRunnable(pinned)) {
+            // No S1 code or fix entry names a missing pinned binary (gaps/c4-pinned-binary-state.md).
+            g.verdict = "refuse";
+            g.code = "durable_precondition_unavailable";
+            g.reason = `the pinned claude binary ${pinned} is missing`;
+            continue;
+        }
+        for (const s of adoptable) {
+            const a = await settle(() => deps.api.lockCheck(s.conversation_id, lockBodyFor(s, exec.executor_id, g.own_agent)));
+            if (a.kind === "ok")
+                continue;
+            g.verdict = "refuse";
+            if (isPrecheckMissing(a)) {
+                g.code = "durable_precondition_unavailable";
+                g.reason = "this API does not serve the lock check, so nothing was stopped";
+            }
+            else if (a.kind === "error") {
+                g.code = a.code ?? `http_${a.status}`;
+                g.reason = a.message;
+                g.fix = refusalFix(a.code, a.details, { name: s.name, launcherKey, agent: g.agent });
+            }
+            else {
+                g.code = "durable_precondition_unavailable";
+                g.reason = a.kind === "timeout" ? "the lock check timed out" : a.message;
+            }
+            break;
+        }
+    }
+    return { groups: [...groups.values()], risk_line: exec ? RISK_LINE_TEXT : null };
+}
+// ---- rendering ---------------------------------------------------------------------------------
+/** The --json document (internal fields removed). */
+export function planJson(plan) {
+    return {
+        groups: plan.groups.map((g) => ({
+            ...g,
+            sessions: g.sessions.map(({ _live, _row, ...s }) => s),
+        })),
+        risk_line: plan.risk_line,
+    };
+}
+const COLS = ["Session", "Goal", "Rules", "Note"];
+/** One table per agent group (R12): Session, Goal, Rules, Note; Note last and unpadded. */
+export function renderGroup(g) {
+    const head = g.verdict === "adopt"
+        ? `Agent ${g.agent}${g.own_agent ? " (moving to its own agent)" : ""}`
+        : g.verdict === "refuse"
+            ? `Agent ${g.agent}: refused (${g.code})${g.reason ? `: ${g.reason}` : ""}`
+            : g.verdict === "skip"
+                ? `Agent ${g.agent}: skipped (${g.reason})`
+                : `Agent ${g.agent}: nothing to adopt`;
+    const rows = g.sessions.map((s) => [s.name, s.goal, s.rules, s.note]);
+    const width = [0, 1, 2].map((c) => Math.max(COLS[c].length, ...rows.map((r) => r[c].length)));
+    const line = (r) => `  ${r
+        .slice(0, 3)
+        .map((v, c) => v.padEnd(width[c]))
+        .join("  ")}  ${r[3]}`;
+    const out = [head, line(COLS), ...rows.map(line)];
+    if (g.fix)
+        out.push(`  fix: ${g.fix}`);
+    return out;
+}
+export function renderPlan(plan) {
+    const out = [];
+    if (plan.groups.length === 0)
+        out.push("No running tracked sessions on this machine.");
+    for (const g of plan.groups)
+        out.push(...renderGroup(g), "");
+    if (plan.risk_line)
+        out.push(plan.risk_line);
+    return out;
+}
+/**
+ * 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 function sameProcess(live, now) {
+    return (now !== null && live.start !== null && now.start === live.start && now.argv0 === live.argv[0]);
+}
+/** A lock outcome that stayed unknown: S1 has no timeout code. */
+const LOCK_UNAVAILABLE_CODE = "durable_precondition_unavailable";
+/** Re-reads of the row after the lock attempts ran out undecided, REREAD_GAP_MS apart. */
+export const REREAD_ATTEMPTS = 3;
+export 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 async function commitOutcome(cid, deps, facts) {
+    for (let i = 0; i < REREAD_ATTEMPTS; i++) {
+        if (i > 0)
+            await deps.sleep(REREAD_GAP_MS);
+        const mode = rowOf(await settle(() => deps.api.getSession(cid, facts)))?.durable_mode;
+        if (typeof mode === "string")
+            return mode === "locked" ? "committed" : "not_committed";
+    }
+    return "unknown";
+}
+/** Lock attempts per handover (the first plus same-key retries) and the gaps between them. */
+export const LOCK_RETRY_GAPS_MS = [2000, 5000, 10000];
+export const LOCK_ATTEMPTS = LOCK_RETRY_GAPS_MS.length + 1;
+/** One lock answer, read: see lockAnswerKind. */
+export function lockDecision(a, first) {
+    const kind = lockAnswerKind(a, first);
+    return kind === "refused" ? { kind, a: a } : { kind, a };
+}
+export function lockAnswerKind(a, first) {
+    if (a.kind === "ok")
+        return "committed";
+    if (a.kind !== "error")
+        return "ambiguous";
+    if (a.code === LOCK_UNAVAILABLE_CODE)
+        return first ? "refused" : "ambiguous";
+    if (a.status >= 500 || a.code === "durable_retry")
+        return "ambiguous";
+    if (a.code === "idempotency_key_in_flight")
+        return "pending";
+    return "refused";
+}
+/**
+ * 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 async function lockDecided(cid, body, deps) {
+    const key = randomUUID();
+    let last = { a: { kind: "timeout" }, kind: "ambiguous" };
+    for (const gap of [0, ...LOCK_RETRY_GAPS_MS]) {
+        if (gap > 0)
+            await deps.sleep(gap);
+        const a = await settle(() => deps.api.lock(cid, body, key));
+        last = lockDecision(a, gap === 0);
+        if (last.kind === "committed" || last.kind === "refused")
+            return last;
+    }
+    return last;
+}
+/** An API call that never throws (a throw reads as a dropped response). */
+export async function settle(f) {
+    try {
+        return await f();
+    }
+    catch (e) {
+        return { kind: "network", message: e instanceof Error ? e.message : String(e) };
+    }
+}
+/** One session's U01 handover (R25 steps 2-5); step 1 ran in the plan. */
+export async function handover(s, g, exec, deps, facts, launcherKey) {
+    const live = s._live;
+    const same = () => sameProcess(live, deps.identity(live.pid));
+    const ended = { ok: false, name: s.name, committed: false, ended: true };
+    // The confirm prompt has no deadline: re-read the identity right before each signal.
+    if (!same())
+        return ended;
+    try {
+        deps.signal(live.pid, "SIGSTOP");
+    }
+    catch {
+        return { ok: false, name: s.name, committed: false, gone: true };
+    }
+    // It changed between the check and the stop: the stop hit another process, so resume it.
+    if (!same()) {
+        try {
+            deps.signal(live.pid, "SIGCONT");
+        }
+        catch {
+            // gone too: nothing to resume
+        }
+        return ended;
+    }
+    const d = await lockDecided(s.conversation_id, lockBodyFor(s, exec.executor_id, g.own_agent), deps);
+    // Only a 4xx refusal proves the lock did not commit: resume the original and report it. The
+    // lock attempts can take seconds, so the identity is re-read: a reused pid is never signalled.
+    if (d.kind === "refused") {
+        const a = d.a;
+        if (same()) {
+            try {
+                deps.signal(live.pid, "SIGCONT");
+            }
+            catch {
+                // it exited while stopped: nothing to resume, the refusal still stands
+            }
+        }
+        else
+            deps.err(`${s.name}: pid ${live.pid} is no longer the original; not resumed`);
+        return {
+            ok: false,
+            name: s.name,
+            committed: false,
+            code: a.code ?? `http_${a.status}`,
+            fix: refusalFix(a.code, a.details, { name: s.name, launcherKey, agent: g.agent }),
+        };
+    }
+    // No attempt was decisive and a request may still be in flight: only a re-read that shows the
+    // lock decides. A row that is not locked proves nothing yet, so the original stays stopped.
+    if (d.kind !== "committed" &&
+        (await commitOutcome(s.conversation_id, deps, facts)) !== "committed")
+        return {
+            ok: false,
+            name: s.name,
+            committed: null,
+            unconfirmed: true,
+            pid: live.pid,
+            code: LOCK_UNAVAILABLE_CODE,
+        };
+    // After the commit the original is never resumed: wait for the seat's hello, then end it.
+    const lease = s._row?.lease_seconds;
+    let waitS = ATTACH_WAIT_S;
+    try {
+        if (typeof lease === "number")
+            waitS = attachWaitSeconds(lease);
+    }
+    catch {
+        waitS = ATTACH_WAIT_S;
+    }
+    const deadline = deps.now() + waitS * 1000;
+    let hello = false;
+    while (deps.now() < deadline) {
+        const r = rowOf(await settle(() => deps.api.getSession(s.conversation_id, facts)));
+        if (r && (r.effective_state ?? r.state) === "running") {
+            hello = true;
+            break;
+        }
+        await deps.sleep(500);
+    }
+    // Stopped by us, the original cannot exit on its own; if its pid names another process now, it
+    // was ended from outside and that pid is not ours to kill.
+    if (!same())
+        return { ok: true, name: s.name, hello, killed: false };
+    const table = deps.processTable();
+    const tree = processTree(live.pid, table, new Set([deps.selfPid]));
+    const startAt = new Map(table.map((row) => [row.pid, row.start]));
+    for (const pid of tree) {
+        // Re-check each pid against the snapshot right before its kill: a pid that exited and was
+        // reused (or whose start the snapshot could not read) is skipped, never killed.
+        const snap = startAt.get(pid);
+        if (snap === undefined || deps.startOf(pid) !== snap) {
+            deps.err(`${s.name}: pid ${pid} no longer matches the process tree read before the kill; skipped`);
+            continue;
+        }
+        try {
+            deps.signal(pid, "SIGKILL");
+        }
+        catch {
+            // already gone
+        }
+    }
+    return { ok: true, name: s.name, hello, killed: true };
+}
+/**
+ * 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 function planRefused(plan) {
+    return plan.groups.some((g) => g.verdict === "refuse" || g.sessions.some((s) => s.verdict === "spec_change"));
+}
+/** The whole verb. Returns the exit status: 1 when anything was refused (ruling 19), else 0. */
+export async function adoptCommand(deps, opts = {}) {
+    const plan = await planAdopt(deps, opts);
+    if (opts.dryRun) {
+        if (opts.json)
+            deps.out(JSON.stringify(planJson(plan), null, 2));
+        else
+            for (const l of renderPlan(plan))
+                deps.out(l);
+        return planRefused(plan) ? 1 : 0;
+    }
+    if (opts.json)
+        deps.out(JSON.stringify(planJson(plan), null, 2));
+    else
+        for (const l of renderPlan(plan))
+            deps.out(l);
+    const exec = deps.executorState();
+    const launcherKey = deps.launcherKey();
+    let failed = planRefused(plan);
+    // C14-R11: a locked session's changed (or uncomparable) spec is refused on stderr; no request.
+    for (const g of plan.groups)
+        for (const s of g.sessions) {
+            if (s.verdict !== "spec_change")
+                continue;
+            failed = true;
+            deps.err(s.reason === "launch_spec_change"
+                ? `${s.name}: not adopted (durable_unsupported {feature: launch_spec_change}); it keeps running as before`
+                : `${s.name}: not adopted (durable_precondition_unavailable): the committed launch spec could not be compared; it keeps running as before`);
+            if (s.fix)
+                deps.err(`  fix: ${s.fix}`);
+        }
+    for (const g of plan.groups) {
+        if (g.verdict !== "adopt")
+            continue;
+        if (!exec) {
+            // The plan saw the executor state; it is gone now. Refuse loudly, never skip in silence.
+            failed = true;
+            deps.err(`${g.agent}: not adopted (durable_no_executor); it keeps running as before`);
+            deps.err(`  fix: ${renderFixLine("no_executor", { launcherKey, nameHeld: true, params: {} })}`);
+            continue;
+        }
+        const adoptable = g.sessions.filter((s) => s.verdict === "adopt");
+        const ok = await deps.confirm(`Adopt ${adoptable.length} session${adoptable.length === 1 ? "" : "s"} of agent ${g.agent}${g.own_agent ? " onto their own agent" : ""}? [Y/n] `);
+        if (!ok) {
+            deps.out(`${g.agent}: not adopted`);
+            continue;
+        }
+        for (const s of adoptable) {
+            // Read again at run time: the session record can go between the plan and now (a
+            // concurrent `mnemom agent done`), and nothing is stopped without its facts.
+            const facts = deps.ledger(s.conversation_id);
+            if (facts === null) {
+                failed = true;
+                deps.err(`${s.name}: not adopted (${LOCK_UNAVAILABLE_CODE}): its session record is gone since the plan; it keeps running as before`);
+                continue;
+            }
+            const r = await handover(s, g, exec, deps, facts, launcherKey);
+            if (r.ok) {
+                deps.out(`\`${s.name}\` is locked; the host daemon runs it. Attach: \`mnemom agent ${s.name}\` (${s.note})`);
+                if (!r.hello)
+                    deps.out(`${s.name}: the seat has not said hello yet: \`mnemom agent host status\``);
+                if (!r.killed)
+                    deps.out(`${s.name}: the original process ended while waiting; nothing was killed`);
+            }
+            else if ("ended" in r) {
+                failed = true;
+                deps.out(`${s.name}: not adopted: the session ended while waiting for confirmation; no lock was requested. Re-run \`mnemom agent sessions adopt\``);
+            }
+            else if ("unconfirmed" in r) {
+                failed = true;
+                deps.err(`${s.name}: not confirmed (${r.code}): the lock request got no clear answer and the session does not show it locked, so the original (pid ${r.pid}) is left stopped`);
+                deps.err(`  next: run \`mnemom agent sessions adopt --dry-run\`; if it shows ${s.name} already durable, the host daemon runs it and \`kill -KILL ${r.pid}\` ends the stopped original; otherwise \`kill -CONT ${r.pid}\` resumes it`);
+            }
+            else if ("gone" in r) {
+                failed = true;
+                deps.out(`${s.name}: not adopted: it exited before it could be stopped`);
+            }
+            else {
+                failed = true;
+                deps.out(`${s.name}: not adopted (${r.code}); it keeps running as before`);
+                if (r.fix)
+                    deps.out(`  fix: ${r.fix}`);
+            }
+        }
+    }
+    return failed ? 1 : 0;
+}
+/** The fix catalogue entries adopt can print (exported for the catalogue lint test). */
+export const ADOPT_FIX_KEYS = Object.freeze([
+    "agent_killed",
+    "agent_contained",
+    "no_executor",
+    "launch_spec_change",
+    "cwd_subdirectory",
+    "cwd_not_git",
+    "cwd_symlink_transcript",
+].filter((k) => k in FIX_LINES));