@mnemom/mnemom 0.17.33 → 0.17.34-next.2

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/protection.js

@@ -15,7 +15,7 @@ const OP_SEVERITIES = ["low", "medium", "high", "critical"];
 // Per ADR-037 Decision 4: deny public LLM endpoints + public DNS providers,
 // and the any-host CIDRs, at write time.
 // T8-4 (2026-05-19) extended the corpus per
-// `safe-house-hardening/audit/deny-list-completeness.md`: added emerging
+// `safe-house-hardening/audits/deny-list-completeness.md`: added emerging
 // LLM providers (Replicate, Together, Anyscale, Fireworks, xAI,
 // Perplexity, DeepSeek) and three reserved IP ranges (link-local v4/v6
 // + multicast v4).

package/dist/commands/scan.d.ts

@@ -0,0 +1,97 @@
+/**
+ * `mnemom scan`: a read-only local scan of GitHub PR metadata. Runs entirely on this machine; nothing is
+ * uploaded in this build. The share-level prompt gates what a later upload step may send, and the chosen
+ * payload is printed so the user sees exactly what would leave. Pure logic is exported so each reject
+ * 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 AnthropicUsageDeps } from "../lib/scan/spend/anthropic-usage.js";
+import { type RecordDeps, type RecordOutcome } from "../lib/scan/record.js";
+import { type ReportEmailDeps } from "../lib/scan/report-email.js";
+import { type ReportRecipients } from "../lib/scan/share.js";
+export interface ScanCommandOptions {
+    repos: string[];
+    period?: {
+        start: string;
+        end: string;
+    };
+    share?: string;
+    /** Report recipient. Required unless the runner is the CTO (asked when omitted). */
+    ctoEmail?: string;
+    /** Tier 2: the CTO's own monthly figure, as typed. Needs MNEMOM_ORG_SCAN_MODE=true. */
+    monthlySpend?: string;
+    /** Tier 2 without a figure on the command line: ask for one on the terminal. */
+    noAnthropicUsage?: boolean;
+    /** Tier 1: ask for the Anthropic admin key on the terminal (masked). Otherwise ANTHROPIC_ADMIN_KEY is used if set. */
+    anthropicAdminKey?: boolean;
+    /** Tier 1 result, when the caller already has it (test seam; set from the Anthropic reads otherwise). */
+    anthropicUsageUsd?: number;
+    anthropicOver200kShare?: number | null;
+    /** Test seam: the fetch behind the two Anthropic reads. */
+    anthropicDeps?: AnthropicUsageDeps;
+    /**
+     * The org the report is emailed for; inferred from the signed-in user's single non-personal org when
+     * omitted (see resolveScanOrg). The Record totals preview (MNEMOM_ORG_SCAN_MODE=true) reads ONLY an
+     * org passed explicitly here, never an inferred one: a guess could read the wrong org.
+     */
+    org?: string;
+    /** Test seam: the Record read. */
+    recordDeps?: RecordDeps;
+    /** Test seam: the report-email POST. */
+    emailDeps?: ReportEmailDeps;
+    /** Test seam: the signed-in user's orgs, used to infer --org when it is omitted. */
+    listOrgs?: () => Promise<Array<{
+        org_id: string;
+        name?: string;
+        is_personal?: boolean;
+    }>>;
+    /** Test seams. */
+    isTty?: boolean;
+    env?: NodeJS.ProcessEnv;
+    runnerEmail?: string;
+    credential?: GitHubCredential;
+    deps?: Partial<ScanDeps>;
+    now?: () => number;
+}
+/** Parses repeated/comma-separated `--repo owner/name`. Returns null on any invalid slug. */
+export declare function parseRepoFlags(raw: string[] | undefined): string[] | null;
+export declare const isEmail: (v: unknown) => v is string;
+/** The runner's email (mnemom login, else asked) and the CTO's (flag, else "are you the CTO?"). */
+export declare function resolveRecipients(o: {
+    runnerEmail?: string;
+    ctoEmail?: string;
+}): 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>;
+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.";
+/**
+ * Tier 1: read measured usage with the CTO's Anthropic admin key, locally. The key comes from
+ * ANTHROPIC_ADMIN_KEY or a masked prompt (--anthropic-admin-key; never a value on argv), lives only in this
+ * call, and goes only to api.anthropic.com. Returns null for "no key" and for every failure, after printing a
+ * fixed sentence: the key, the thrown value and the response never reach the terminal. The caller then falls
+ * back to tier 2, then tier 3.
+ */
+export declare function resolveMeasuredUsage(o: ScanCommandOptions, period: {
+    start: string;
+    end: string;
+}): Promise<{
+    usd: number;
+    over200kShare: number | null;
+} | null>;
+/**
+ * --org is optional only because it can be inferred: the report is emailed on every scan, so the scan
+ * needs an org. Inference uses the signed-in user's own memberships (GET /v1/orgs, personal org
+ * excluded): exactly one org is used; none, several, or a failed read stops the scan loudly BEFORE any
+ * scan work, naming the fix. It never guesses between orgs and never skips the email.
+ */
+export declare function resolveScanOrg(o: ScanCommandOptions): Promise<string>;
+export declare const INVALID_ORG_MSG = "--org must be an org id like org-1a2b3c4d.";
+/**
+ * The Record read for the preview: null when the flag gate is off (no read, no output, as before).
+ * With the gate on and no --org it is a note, not a guess. 404 becomes a note; 401/403 throw
+ * RecordAuthError (fail closed); every other failure becomes a fixed note. Nothing is stored.
+ */
+export declare function resolveRecordOutcome(o: ScanCommandOptions): Promise<RecordOutcome | "no_org" | null>;
+export declare function scanCommand(o: ScanCommandOptions): Promise<void>;