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

package/dist/commands/durable-verbs.js

@@ -0,0 +1,393 @@
+/**
+ * The flat durable owner verbs (BACKBONE C1; S1 owner-verbs.ts, ROUTES.own_*; C11, C16):
+ *
+ *   mnemom agent pause|resume|done|kill <name> [--json]
+ *   mnemom agent amend <name> [--budget <n>] [--turns <n>] [--json]
+ *   mnemom agent sessions unlock <name>
+ *   mnemom agent containment pause|resume <agent>
+ *
+ * The API decides (S1 owner-verb table, first match wins); the CLI resolves the name through the
+ * registry, sends the verb, and renders the answer: a refusal with its S1 fix line and machine
+ * code, a 200 no-op with its state, a 202 device step (user_code + verification_uri_complete,
+ * polled at the server interval with the 202's device_code and client_id; never a token printed
+ * or kept), or the applied change. `done`/`kill` on a tracked session also stop the local tracked
+ * claude after the 200 (final F04; SIGTERM, SIGKILL after TRACKED_STOP_GRACE_S).
+ *
+ * Every dependency is injected (`DurableVerbDeps`), so each branch is unit-tested.
+ */
+import { PER_SESSION_BUDGET_LIMIT_USD, TRACKED_STOP_GRACE_S, } from "../vendor/shared/durable-contract/constants.js";
+import { renderFixLine, } from "../vendor/shared/durable-contract/fixlines.js";
+import { errorCodeOf, errorDetailsOf, errorMessageOf, RegistryAnswerError, RegistryUnavailable, } from "../lib/durable/api.js";
+import { DurableRefusal, printDurableRefusal } from "../lib/durable/refusal.js";
+import { isLocked, liveRow, stateLabel } from "../lib/durable/view.js";
+import { CODE } from "../lib/durable/codes.js";
+const VERB_ROUTE = {
+    pause: "own_pause",
+    resume: "own_resume",
+    done: "own_complete",
+    kill: "own_kill",
+    amend: "own_amend",
+    unlock: "own_unlock",
+};
+const APPLIED_TEXT = {
+    pause: "paused",
+    resume: "resumed; the host daemon picks it up",
+    done: "done",
+    kill: "killed",
+    amend: "amended",
+    unlock: "unlocked",
+};
+/** The session a verb acts on: the non-terminal row holding the name, else the newest row. */
+export async function resolveTarget(api, name) {
+    let rows;
+    try {
+        rows = await api.listSessions({ name });
+    }
+    catch (e) {
+        if (e instanceof RegistryAnswerError)
+            throw refusalFromAnswer(e.answer, name, "off");
+        throw e;
+    }
+    const row = liveRow(rows) ?? rows[0] ?? null;
+    if (row === null) {
+        throw new DurableRefusal({
+            code: "agent_not_found",
+            message: `no session named ${name}`,
+            fix: null,
+        });
+    }
+    return row;
+}
+/**
+ * A refusal from an API answer: the API's message and code, its rendered fix (details.fix, as the
+ * API already applied the fix-line rule), else the CLI's catalogue fallback for that code.
+ */
+export function refusalFromAnswer(a, name, launcherKey, row) {
+    const code = errorCodeOf(a.body) ?? `http_${a.status}`;
+    const details = errorDetailsOf(a.body);
+    const apiFix = typeof details.fix === "string" && details.fix !== "" ? details.fix : null;
+    const fix = apiFix ?? fallbackFix(code, details, name, launcherKey, row);
+    const apiMessage = errorMessageOf(a.body);
+    // The refusal line always names the session the verb was for (C02-R05: the user sees what failed).
+    const message = apiMessage === null
+        ? `${name}: refused (${a.status})`
+        : apiMessage.includes(name)
+            ? apiMessage
+            : `${name}: ${apiMessage}`;
+    return new DurableRefusal({ code, message: sanitizeLine(message), fix, apiBody: a.body });
+}
+/** A one-line message: no control characters reach the terminal. */
+function sanitizeLine(s) {
+    return (s
+        // eslint-disable-next-line no-control-regex
+        .replace(/[\u0000-\u001f\u007f]+/g, " ")
+        .replace(/ {2,}/g, " ")
+        .trim());
+}
+function render(key, params, launcherKey, held) {
+    return renderFixLine(key, { launcherKey, nameHeld: held, params });
+}
+/** The catalogue fix the CLI prints when the API body carries none. */
+export function fallbackFix(code, details, name, launcherKey, row) {
+    const agent = row?.agent_name ?? row?.agent_id ?? "<agent>";
+    switch (code) {
+        case CODE.durable_session_ended:
+            return details.state_reason === "agent_killed"
+                ? render("agent_killed", { name }, launcherKey, false)
+                : render("session_ended", { name }, launcherKey, false);
+        case CODE.durable_agent_contained:
+            return render("agent_contained", { agent }, launcherKey, true);
+        case CODE.durable_not_owner:
+            return typeof details.owner === "string"
+                ? render("not_owner_info", { owner: details.owner }, launcherKey, true)
+                : null;
+        case CODE.durable_session_login_required:
+            return render("device_step_login", {}, launcherKey, true);
+        case CODE.durable_unsupported:
+            if (details.feature === "launch_spec_change") {
+                // The flags come from the answer; without them there is no line to print.
+                const flags = Array.isArray(details.flags)
+                    ? details.flags.filter((f) => typeof f === "string").join(" ")
+                    : typeof details.flags === "string"
+                        ? details.flags
+                        : "";
+                return flags.trim() === ""
+                    ? null
+                    : render("launch_spec_change", { name, flags: flags.trim() }, launcherKey, true);
+            }
+            if (details.feature === "above_limit_raise")
+                return render("above_limit_raise", { name, limit: String(PER_SESSION_BUDGET_LIMIT_USD) }, launcherKey, true);
+            return null;
+        default:
+            return null;
+    }
+}
+function isRecord(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+export function deviceStepOf(body) {
+    if (!isRecord(body))
+        return null;
+    const b = (isRecord(body.device_step) ? body.device_step : body);
+    const s = (k) => (typeof b[k] === "string" && b[k] !== "" ? b[k] : null);
+    const user = s("user_code");
+    const uri = s("verification_uri_complete");
+    const dc = s("device_code");
+    const cid = s("client_id");
+    if (!user || !uri || !dc || !cid)
+        return null;
+    const interval = typeof b.interval === "number" && b.interval > 0 ? b.interval : 5;
+    return {
+        user_code: user,
+        verification_uri_complete: uri,
+        device_code: dc,
+        interval,
+        client_id: cid,
+        ...(s("approval_id") ? { approval_id: s("approval_id") } : {}),
+    };
+}
+/** How long the CLI keeps polling a device step before giving up (the approval TTL). */
+export const DEVICE_STEP_POLL_MAX_MS = 15 * 60 * 1000;
+/**
+ * Print the device step and poll until it resolves. 0 when applied; throws a DurableRefusal when
+ * denied, expired or refused. Never prints the device_code or any token.
+ */
+export async function runDeviceStep(step, note, deps) {
+    deps.err(`Approve this change: open ${step.verification_uri_complete}`);
+    deps.err(`and confirm the code ${step.user_code}.`);
+    if (note)
+        deps.err(note);
+    let interval = step.interval * 1000;
+    const deadline = deps.now() + DEVICE_STEP_POLL_MAX_MS;
+    for (;;) {
+        await deps.sleep(interval);
+        const a = await deps.api.devicePoll(step.device_code, step.client_id);
+        const code = errorCodeOf(a.body);
+        if (a.status < 300 && code === null) {
+            deps.err("approved and applied");
+            return 0;
+        }
+        if (code === "authorization_pending" || code === "slow_down") {
+            if (code === "slow_down")
+                interval += 5000;
+            if (deps.now() + interval > deadline) {
+                throw new DurableRefusal({
+                    code: "expired_token",
+                    message: "the approval expired",
+                    fix: null,
+                });
+            }
+            continue;
+        }
+        const why = code === "access_denied"
+            ? "the approval was denied"
+            : code === "expired_token"
+                ? "the approval expired"
+                : (errorMessageOf(a.body) ?? "the approval was refused");
+        throw new DurableRefusal({ code: code ?? `http_${a.status}`, message: why, fix: null });
+    }
+}
+/** Run one verb end to end and return its exit status (refusals rendered here). */
+export async function runVerb(verb, name, body, opts, deps) {
+    const launcherKey = deps.launcherKey();
+    try {
+        const row = await resolveTarget(deps.api, name);
+        const a = await deps.api.ownerVerb(VERB_ROUTE[verb], row.conversation_id, row.agent_id, body);
+        if (a.status === 202) {
+            const step = deviceStepOf(a.body);
+            if (step === null) {
+                throw new DurableRefusal({
+                    code: "device_step_malformed",
+                    message: "the API answered 202 without a usable device step",
+                    fix: null,
+                });
+            }
+            const contained = row.state === "paused" && row.state_reason === "agent_contained";
+            const note = contained
+                ? "an org admin other than you must approve this unpause (a solo org approves it itself)"
+                : null;
+            const rc = await runDeviceStep(step, note, deps);
+            if (opts.json)
+                deps.out(JSON.stringify({ name, verb, applied: true }));
+            return rc;
+        }
+        if (a.status >= 200 && a.status < 300) {
+            if (verb === "done" || verb === "kill") {
+                // An ending verb fails closed: only an answer that says the session ended (or a re-read
+                // that shows it) counts, and only then is a tracked claude stopped. Never SIGKILL on an
+                // ambiguous 2xx (a null body, a proxy-swallowed body, schema drift).
+                if (!(isRecord(a.body) && a.body.changed === false)) {
+                    await confirmEnded(verb, row, a, deps.api, name);
+                }
+            }
+            const changed = !(isRecord(a.body) && a.body.changed === false);
+            // --json: stdout carries the one JSON document; the human lines go to stderr.
+            const say = opts.json ? deps.err : deps.out;
+            if (!changed) {
+                say(`${name}: no change (${stateLabel(row)})`);
+                if (verb === "resume")
+                    say(`fix: ${render("resume_live", { name }, launcherKey, true)}`);
+            }
+            else {
+                say(`${name}: ${APPLIED_TEXT[verb]}`);
+                if ((verb === "done" || verb === "kill") && !isLocked(row) && deps.stopTrackedClaude) {
+                    await deps.stopTrackedClaude(row, TRACKED_STOP_GRACE_S);
+                }
+            }
+            if (opts.json)
+                deps.out(JSON.stringify(a.body ?? { changed }));
+            return 0;
+        }
+        throw refusalFromAnswer(a, name, launcherKey, row);
+    }
+    catch (e) {
+        return handleVerbError(e, opts.json === true, deps);
+    }
+}
+/** The state an applied done / kill writes (S1 owner-verbs: complete -> completed, kill -> killed). */
+const ENDED_STATE = { done: "completed", kill: "killed" };
+/**
+ * Confirm an applied done / kill: the answer's own `{changed: true, state}` when it names the ended
+ * state, else one re-read of the session by conversation id. Throws a refusal (nothing stopped
+ * locally) when neither shows the session ended.
+ */
+export async function confirmEnded(verb, row, a, api, name) {
+    const want = ENDED_STATE[verb];
+    if (isRecord(a.body) && a.body.changed === true && a.body.state === want)
+        return;
+    const seen = await api.listSessions({ name }).then((rows) => rows.find((r) => r.conversation_id === row.conversation_id) ?? null, () => null);
+    if (seen !== null && seen.state === want)
+        return;
+    throw new DurableRefusal({
+        code: "verb_unconfirmed",
+        message: `${name}: the API answered ${a.status} but did not confirm the session ${want === "completed" ? "completed" : "was killed"}; nothing was stopped locally`,
+        fix: null,
+    });
+}
+export function handleVerbError(e, json, deps) {
+    if (e instanceof DurableRefusal)
+        return printDurableRefusal(e, json, deps);
+    if (e instanceof RegistryUnavailable) {
+        return printDurableRefusal(new DurableRefusal({
+            code: "session_registry_unavailable",
+            message: `the session registry is unreachable (${e.message}); nothing was changed`,
+            fix: null,
+        }), json, deps);
+    }
+    throw e;
+}
+/** Parse a positive amount (amend --budget); `integer` for a count (amend --turns). */
+export function parsePositive(flag, raw, integer = false) {
+    if (raw === undefined)
+        return undefined;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n <= 0 || (integer && !Number.isInteger(n))) {
+        throw new DurableRefusal({
+            code: "invalid_argument",
+            message: `${flag} must be a positive ${integer ? "whole number" : "number"} (got '${raw}')`,
+            fix: null,
+            exit: 2,
+        });
+    }
+    return n;
+}
+export async function amendCommand(name, opts, deps) {
+    let budget;
+    let turns;
+    try {
+        budget = parsePositive("--budget", opts.budget);
+        turns = parsePositive("--turns", opts.turns, true);
+    }
+    catch (e) {
+        return handleVerbError(e, opts.json === true, deps);
+    }
+    if (budget === undefined && turns === undefined) {
+        deps.err("mnemom agent amend: give --budget <n> and/or --turns <n>");
+        return 2;
+    }
+    const body = {};
+    if (budget !== undefined)
+        body.budget_usd = budget;
+    if (turns !== undefined)
+        body.max_turns = turns;
+    return runVerb("amend", name, body, opts, deps);
+}
+export async function unlockCommand(name, deps) {
+    return runVerb("unlock", name, {}, {}, deps);
+}
+/**
+ * `mnemom agent containment pause|resume <agent>` (BACKBONE C1, amendment 35; C16-R30): a thin
+ * verb over POST /v1/orgs/{org}/agents/{id}/pause|resume. The org comes from the agent record,
+ * never the active org. It needs a session login: on an API-key-only credential, or the api's
+ * 403 org_scope_requires_session, it exits non-zero with the containment_login line and never
+ * sends the API key or prints the raw 403.
+ */
+export async function containmentCommand(verb, agentRef, deps) {
+    const launcherKey = deps.launcherKey();
+    const loginRefusal = () => new DurableRefusal({
+        // Never the raw 403 code (C11-R26): the machine code is the S1 fix key.
+        code: "containment_login",
+        message: `mnemom agent containment ${verb}: org containment acts as a signed-in org admin`,
+        fix: render("containment_login", {}, launcherKey, false),
+    });
+    try {
+        if ((await deps.api.credentialType()) !== "jwt")
+            throw loginRefusal();
+        const { orgId, agentId } = await resolveContainmentAgent(agentRef, deps, launcherKey);
+        const a = await deps.api.containment(orgId, agentId, verb);
+        if (a.status === 403 && errorCodeOf(a.body) === "org_scope_requires_session")
+            throw loginRefusal();
+        if (a.status >= 200 && a.status < 300) {
+            deps.out(`agent ${agentRef}: ${verb === "pause" ? "paused (contained)" : "active again"}`);
+            return 0;
+        }
+        throw refusalFromAnswer(a, agentRef, launcherKey);
+    }
+    catch (e) {
+        return handleVerbError(e, false, deps);
+    }
+}
+/** An agent id as the CLI recognises one (lib/api.ts resolveAgentId). */
+export const AGENT_ID_RE = /^(smolt-[0-9a-f]{8}|mnm-[0-9a-f-]{36})$/;
+/**
+ * The containment target and its org, from the agent record (never the active org): an id is read
+ * with GET /v1/agents/{id}; a name is looked up in the caller's org fleets and must match exactly one.
+ */
+export async function resolveContainmentAgent(agentRef, deps, launcherKey) {
+    if (AGENT_ID_RE.test(agentRef)) {
+        const ag = await deps.api.getAgent(agentRef);
+        if (ag.status !== 200 || !isRecord(ag.body))
+            throw refusalFromAnswer(ag, agentRef, launcherKey);
+        const rec = (isRecord(ag.body.agent) ? ag.body.agent : ag.body);
+        const orgId = typeof rec.org_id === "string" ? rec.org_id : null;
+        if (orgId === null) {
+            throw new DurableRefusal({
+                code: "agent_not_found",
+                message: `agent ${agentRef} has no org on record`,
+                fix: null,
+            });
+        }
+        return { orgId, agentId: typeof rec.id === "string" ? rec.id : agentRef };
+    }
+    const found = await deps.api.agentsByName(agentRef);
+    if (found.length === 0) {
+        throw new DurableRefusal({
+            code: "agent_not_found",
+            message: `no agent named ${agentRef} in your orgs`,
+            fix: null,
+        });
+    }
+    if (found.length > 1) {
+        throw new DurableRefusal({
+            code: "agent_ambiguous",
+            message: `${found.length} agents are named ${agentRef} in your orgs (${found.map((a) => a.id).join(", ")}); name one by its id`,
+            fix: null,
+        });
+    }
+    const [only] = found;
+    return { orgId: only.org_id, agentId: only.id };
+}
+/** The thin verbs (pause/resume/done/kill) with no body. */
+export async function ownerVerbCommand(verb, name, opts, deps) {
+    return runVerb(verb, name, {}, opts, deps);
+}

package/dist/commands/scan.d.ts

@@ -5,9 +5,11 @@
  * arm is unit-testable without Commander (same pattern as commands/usage.ts).
  */
 import { type GitHubCredential } from "../lib/scan/credential.js";
-import { type ScanDeps } from "../lib/scan/scan.js";
+import { type ScanDeps, type ScanResult } from "../lib/scan/scan.js";
+import { selectSpend } from "../lib/scan/spend/spend-tiers.js";
 import { type AnthropicUsageDeps } from "../lib/scan/spend/anthropic-usage.js";
 import { type RecordDeps, type RecordOutcome } from "../lib/scan/record.js";
+import { type CostSpend } from "../lib/scan/cost-per-pr.js";
 import { type ReportEmailDeps } from "../lib/scan/report-email.js";
 import { type ReportRecipients } from "../lib/scan/share.js";
 export interface ScanCommandOptions {
@@ -64,6 +66,15 @@ export declare function resolveRecipients(o: {
 }): Promise<ReportRecipients>;
 /** The CTO's figure in USD, or null for none. Throws fixed text only; the input is never echoed. */
 export declare function resolveSelfReportedSpend(o: ScanCommandOptions): Promise<number | null>;
+/**
+ * The one spend the cost-per-PR figures split, matching the tier the scan chose. Null leaves them out.
+ * Tier 1 sends the measured Anthropic total; tier 2 NEVER does (a figure split from the stated monthly
+ * spend would let that number be recovered, and the tier 2 line promises it is "not sent"); tier 3 (or
+ * tiers off) the modelled range. Sources are never mixed.
+ */
+export declare function resolveCostSpend(o: ScanCommandOptions, result: ScanResult, spend: ReturnType<typeof selectSpend> | null, measured: {
+    usd: number;
+} | null): CostSpend | null;
 export declare const NO_ADMIN_KEY_TERMINAL_MSG = "Set ANTHROPIC_ADMIN_KEY (there is no terminal to ask on).";
 export declare const TIER1_FALLBACK_NOTE = "Tier 1 skipped: falling back to the next tier.";
 /**

package/dist/commands/scan.js

@@ -13,6 +13,7 @@ import { ADMIN_KEY_ENV, AnthropicUsageError, fetchMeasuredUsage, isAdminKeyShape
 import { getAuthInfo } from "../lib/auth.js";
 import { listMyOrgs } from "../lib/api.js";
 import { fetchRecordTotals, isOrgId, } from "../lib/scan/record.js";
+import { modelledSpend } from "../lib/scan/cost-per-pr.js";
 import { RECORD_NO_ORG_NOTE, renderRecordSection } from "../lib/scan/report.js";
 import { buildEmailBody, buildEmailReport, DRY_RUN_MSG, UNAVAILABLE_MSG, failureMessage, ReportEmailError, sendReportEmail, } from "../lib/scan/report-email.js";
 import { buildSharePayload, parseShareLevel, promptShareLevel, } from "../lib/scan/share.js";
@@ -67,6 +68,23 @@ export async function resolveSelfReportedSpend(o) {
         throw new Error(SPEND_INVALID_MSG);
     return n;
 }
+/**
+ * The one spend the cost-per-PR figures split, matching the tier the scan chose. Null leaves them out.
+ * Tier 1 sends the measured Anthropic total; tier 2 NEVER does (a figure split from the stated monthly
+ * spend would let that number be recovered, and the tier 2 line promises it is "not sent"); tier 3 (or
+ * tiers off) the modelled range. Sources are never mixed.
+ */
+export function resolveCostSpend(o, result, spend, measured) {
+    if (spend === null)
+        return modelledSpend(result.spend);
+    if (spend.tier === 1) {
+        const usd = measured?.usd ?? o.anthropicUsageUsd;
+        return typeof usd === "number" ? { source: "anthropic_usage", usd } : null;
+    }
+    if (spend.tier === 2)
+        return null;
+    return spend.tier === 3 ? modelledSpend(result.spend) : null;
+}
 export const NO_ADMIN_KEY_TERMINAL_MSG = "Set ANTHROPIC_ADMIN_KEY (there is no terminal to ask on).";
 export const TIER1_FALLBACK_NOTE = "Tier 1 skipped: falling back to the next tier.";
 /**
@@ -194,7 +212,7 @@ export async function scanCommand(o) {
     const level = parseShareLevel(o.share) ?? (await promptShareLevel());
     // Every successful scan emails the report to the person who ran it, at every share level, no opt-out.
     // Mnemom keeps nothing from a share=none send (the server sends the email and does nothing else).
-    const emailFailure = await emailReport(o, emailOrg, result, level, period, spend);
+    const emailFailure = await emailReport(o, emailOrg, result, level, spend, period, resolveCostSpend(o, result, spend, measured));
     if (level === "none") {
         console.log("Share level: nothing. No share payload is built; Mnemom keeps nothing (the report email is only sent to you).");
         if (emailFailure)
@@ -211,16 +229,17 @@ export async function scanCommand(o) {
  * Emails the report. Loud on every failure: prints the reason name, never the server's words, and
  * returns it so the caller exits non-zero after the local report is shown.
  */
-async function emailReport(o, org, result, level, period, spend) {
+async function emailReport(o, org, result, level, spend, period, costSpend) {
     const fail = (f) => {
         console.log(failureMessage(f));
         return f;
     };
     const report = buildEmailReport(result, {
         orgId: org,
-        period,
         now: o.now ?? Date.now,
         sendSpendRange: spend ? spend.shareable && spend.tier === 3 : true,
+        period,
+        costSpend,
     });
     const body = buildEmailBody(report, level, result.coverage.complete, o.ctoEmail?.trim());
     const outcome = await sendReportEmail(org, body, o.emailDeps);

package/dist/commands/wrap.js

@@ -41,7 +41,7 @@ const PROVIDERS = {
         label: "Google Gemini",
         keyEnv: "GOOGLE_API_KEY",
         keyHeader: "x-goog-api-key",
-        defaultModel: "gemini-2.0-flash",
+        defaultModel: "gemini-2.5-flash",
         basePath: "/gemini",
     },
 };

package/dist/durable/adopt-live.js

@@ -11,7 +11,7 @@ import { executorStateOk, executorStatePath, LAUNCHER_KEYS, } from "../vendor/du
 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 { durableLauncherKey, 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";
@@ -37,21 +37,18 @@ export function ledgerFactsFrom(records, cid) {
 }
 /** 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;
+    let configured;
     if (tomlText !== null) {
         try {
             const v = parseToml(tomlText).durable;
-            if (ok(v))
-                return v;
+            if (typeof v === "string" && LAUNCHER_KEYS.includes(v))
+                configured = v;
         }
         catch {
             // an unparseable launcher.toml is the launcher's error to report, not adopt's
         }
     }
-    return "off";
+    return durableLauncherKey(env, configured);
 }
 /** The executor state file, or null when absent or not the frozen S1 shape. */
 export function executorStateFrom(text) {

package/dist/durable/adopt.d.ts

@@ -172,12 +172,20 @@ export interface AdoptPlan {
 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;
+/**
+ * A session's fix lines name it by its registry row's own name (the row discovery matched by
+ * conversation id); only then does the name hold a row, so only then may a line carry the done step.
+ * The environment's name is the launcher's display name (agent-scenario), which no verb resolves.
+ */
+export declare function nameHeldOf(s: Pick<PlannedSession, "name" | "_row">): boolean;
 /** 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;
+    /** Whether the name holds a registry row (nameHeldOf): only then does the line carry the done step. */
+    nameHeld: boolean;
 }
 /**
  * The S1 fix line for a lock refusal answered by the check or the lock route, or null when the

package/dist/durable/adopt.js

@@ -76,6 +76,14 @@ export function rowOf(a) {
         return { ...inner, agent_id: inner.agent.id };
     return inner;
 }
+/**
+ * A session's fix lines name it by its registry row's own name (the row discovery matched by
+ * conversation id); only then does the name hold a row, so only then may a line carry the done step.
+ * The environment's name is the launcher's display name (agent-scenario), which no verb resolves.
+ */
+export function nameHeldOf(s) {
+    return typeof s._row?.name === "string" && s._row.name !== "" && s._row.name === s.name;
+}
 async function planSession(live, deps, launcherKey) {
     const facts = deps.ledger(live.conversationId);
     const base = {
@@ -117,6 +125,8 @@ async function planSession(live, deps, launcherKey) {
     if (!row)
         return unadoptable("row_unreadable");
     Object.assign(base, { _row: row });
+    if (typeof row.name === "string" && row.name !== "")
+        base.name = row.name;
     const agentId = row.agent_id ?? facts.agentId;
     if (row.durable_mode === "locked") {
         await compareLocked(base, live, row, deps, launcherKey);
@@ -137,7 +147,7 @@ async function planSession(live, deps, launcherKey) {
         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.fix = cwdFixLine(verdict, { name: base.name, launcherKey, nameHeld: nameHeldOf(base) });
         base.note = cwdNote(verdict.cwd_kind, base.fix);
         return { s: base, agentId, agentLabel: facts.agentLabel };
     }
@@ -199,7 +209,8 @@ async function compareLocked(base, live, row, deps, launcherKey) {
     // 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,
+        name: base.name,
+        nameHeld: nameHeldOf(base),
         flags: specUserArgv(built.spec).join(" "),
         launcherKey,
         soleLockedSession: false,
@@ -234,7 +245,7 @@ export function refusalFix(code, details, ctx) {
         params.repo = repos.join(", ");
     if (placeholdersOf(key).some((p) => params[p] === undefined))
         return null;
-    return renderFixLine(key, { launcherKey: ctx.launcherKey, nameHeld: true, params });
+    return renderFixLine(key, { launcherKey: ctx.launcherKey, nameHeld: ctx.nameHeld, params });
 }
 const LOCK_REFUSAL_FIX_CODES = Object.freeze({
     durable_lock_not_entitled: true,
@@ -299,7 +310,7 @@ export async function planAdopt(deps, opts = {}) {
             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.fix = cwdFixLine({ ok: false, cwd_kind: "not_git", params: { checkout } }, { name: s.name, launcherKey, nameHeld: nameHeldOf(s) });
             s.note = cwdNote("not_git", s.fix);
         }
         const adoptable = g.sessions.filter((s) => s.verdict === "adopt");
@@ -343,7 +354,12 @@ export async function planAdopt(deps, opts = {}) {
             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 });
+                g.fix = refusalFix(a.code, a.details, {
+                    name: s.name,
+                    launcherKey,
+                    agent: g.agent,
+                    nameHeld: nameHeldOf(s),
+                });
             }
             else {
                 g.code = "durable_precondition_unavailable";
@@ -513,7 +529,12 @@ export async function handover(s, g, exec, deps, facts, launcherKey) {
             name: s.name,
             committed: false,
             code: a.code ?? `http_${a.status}`,
-            fix: refusalFix(a.code, a.details, { name: s.name, launcherKey, agent: g.agent }),
+            fix: refusalFix(a.code, a.details, {
+                name: s.name,
+                launcherKey,
+                agent: g.agent,
+                nameHeld: nameHeldOf(s),
+            }),
         };
     }
     // No attempt was decisive and a request may still be in flight: only a re-read that shows the

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

@@ -17,7 +17,7 @@
  *
  * The decision is pure over injected facts; liveCwdDeps is the thin driver.
  */
-import { type CwdKind, type LauncherKey } from "../vendor/durable-contract/index.js";
+import { type CwdCheckCause, 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;
@@ -48,6 +48,14 @@ export declare function projectSlug(path: string): string;
  * not --resume it).
  */
 export declare function classifyCwd(cwd: string, deps: CwdDeps, ccSessionId?: string | null): CwdVerdict;
+/**
+ * The daemon's spawn-time cwd check (attestation check `cwd`, C14-R04; mnemom-test #1002): the
+ * committed cwd's realpath must equal `git rev-parse --show-toplevel` there. Null when it holds;
+ * otherwise the S1 CWD_CHECK_CAUSES value: `missing` when there is no committed cwd or it does not
+ * resolve, `not_toplevel` when it resolves but is not a work tree's top level (a subdirectory, or
+ * not in a git work tree at all).
+ */
+export declare function spawnCwdCause(cwd: string | null, deps: Pick<CwdDeps, "realpath" | "gitToplevel">): CwdCheckCause | null;
 /**
  * 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