@mnemom/mnemom 0.17.33 → 0.17.34-next.2

package/dist/commands/durable-doctor.js

@@ -0,0 +1,186 @@
+/**
+ * The durable lines of `mnemom agent doctor` (BACKBONE C1 "doctor (MFA, branch protection)";
+ * C02-R19): for each of the caller's open sessions, the MFA and branch-protection verdicts lock would
+ * compute at that moment, with the same probes and codes. The API computes them (S1 lock.ts steps
+ * `mfa` and `protection`); the doctor only renders. Read-only: one GET per session, never a POST.
+ *
+ * Not frozen by S1 (A2 owns it; gaps/c1-doctor-lock-preflight.md):
+ *   GET /v1/agent/sessions/{cid}/lock?agent_id=&dry_run=true
+ *     200 {mfa, repos: [{repo, verdict | protected | reason, pushable?}]}  (read defensively), or the
+ *     lock refusal envelope of the first failing step (403 durable_lock_mfa_required, 409
+ *     durable_lock_branch_unprotected {refusals}, 503 durable_precondition_unavailable, ...).
+ * A route that is absent (404/405) prints one info line; nothing here is ever a MISS, so the doctor's
+ * exit status keeps meaning "launch-ready".
+ */
+import { errorCodeOf, errorDetailsOf, } from "../lib/durable/api.js";
+import { fixLine } from "../lib/durable/refusal.js";
+import { isEnded } from "../lib/durable/view.js";
+import { CODE } from "../lib/durable/codes.js";
+/** At most this many open sessions are checked (one GET each). */
+export const DOCTOR_SESSION_CAP = 5;
+function rec(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v)
+        ? v
+        : {};
+}
+function mfaOf(v) {
+    if (typeof v === "boolean")
+        return v ? "ok" : "missing";
+    if (typeof v === "string")
+        return v === "ok" ? "ok" : "missing";
+    if (typeof rec(v).ok === "boolean")
+        return rec(v).ok ? "ok" : "missing";
+    return "unknown";
+}
+const STATE_WORDS = {
+    protected: "protected",
+    unprotected: "unprotected",
+    unsupported_host: "unsupported_host",
+};
+/** One repo entry; null for a read-only repo (lock ignores it) or one without a name. */
+function repoOf(v) {
+    const r = rec(v);
+    if (typeof r.repo !== "string")
+        return null;
+    if (r.pushable === false)
+        return null;
+    const word = r.verdict ?? r.state ?? r.reason;
+    if (word === "read_only")
+        return null;
+    if (typeof r.protected === "boolean")
+        return { repo: r.repo, state: r.protected ? "protected" : "unprotected" };
+    return { repo: r.repo, state: (typeof word === "string" && STATE_WORDS[word]) || "unknown" };
+}
+const reposOf = (list) => (Array.isArray(list) ? list : []).map(repoOf).filter((r) => r !== null);
+/**
+ * A refusals[] list fails closed: membership is the server refusing the repo, so every listed repo
+ * shows as refused whatever state word sits next to it. A "protected", "read_only", unknown word or
+ * pushable:false cannot turn a refusal into an ok or drop it; the one finer reason kept is
+ * unsupported_host, itself a refusal (a non-github.com host cannot be protected).
+ */
+const refusedReposOf = (list) => (Array.isArray(list) ? list : []).flatMap((v) => {
+    const r = rec(v);
+    if (typeof r.repo !== "string")
+        return [];
+    const word = r.verdict ?? r.state ?? r.reason;
+    const state = word === "unsupported_host" ? "unsupported_host" : "unprotected";
+    return [{ repo: r.repo, state }];
+});
+/**
+ * The api's own codes for a route it does not serve (mnemom-api http-errors.ts STATUS_CODE_MAP: the
+ * router's fallback `errorResponse("Not found", 404)` carries not_found, a wrong method 405
+ * method_not_allowed). Only these, or no code at all, mean "no preflight here"; any other code on a
+ * 404/405 (agent_not_found, ...) is the api refusing, shown as such.
+ */
+const ROUTE_ABSENT_CODE = { 404: "not_found", 405: "method_not_allowed" };
+/** Read a preflight answer into the verdict the doctor prints. */
+export function preflightVerdict(a) {
+    const code = errorCodeOf(a.body);
+    if (a.status === 200) {
+        const b = rec(a.body);
+        const list = b.repos ?? b.protection;
+        const repos = Array.isArray(list) ? reposOf(list) : refusedReposOf(b.refusals);
+        return { kind: "verdict", mfa: mfaOf(b.mfa), repos };
+    }
+    const absentCode = ROUTE_ABSENT_CODE[a.status];
+    if (absentCode !== undefined && (code === null || code === absentCode))
+        return { kind: "absent" };
+    if (code === CODE.durable_lock_mfa_required)
+        return { kind: "verdict", mfa: "missing", repos: [] };
+    if (code === CODE.durable_lock_branch_unprotected)
+        return { kind: "verdict", mfa: "ok", repos: refusedReposOf(errorDetailsOf(a.body).refusals) };
+    if (code === CODE.durable_precondition_unavailable)
+        return { kind: "unavailable", detail: code };
+    return { kind: "earlier", code: code ?? `http_${a.status}` };
+}
+function verdictLines(name, v) {
+    const p = `durable lock (${name})`;
+    switch (v.kind) {
+        case "absent":
+            return [
+                {
+                    mark: "info",
+                    text: `${p}: this server has no lock preflight; \`mnemom agent lock ${name}\` reports MFA and branch protection`,
+                },
+            ];
+        case "unavailable":
+            return [
+                { mark: "info", text: `${p}: could not check MFA and branch protection (${v.detail})` },
+            ];
+        case "earlier":
+            return [
+                {
+                    mark: "info",
+                    text: `${p}: lock refuses first with ${v.code}, before MFA and branch protection`,
+                },
+            ];
+        case "verdict": {
+            const lines = [];
+            if (v.mfa === "ok")
+                lines.push({ mark: "ok", text: `${p}: MFA ok` });
+            else if (v.mfa === "missing")
+                lines.push({
+                    mark: "warn",
+                    text: `${p}: MFA missing (lock refuses: durable_lock_mfa_required)`,
+                    hint: fixLine("lock_mfa_required", "off", true, { name }),
+                });
+            else
+                lines.push({ mark: "info", text: `${p}: MFA could not be determined` });
+            for (const r of v.repos) {
+                const fix = fixLine("lock_branch_unprotected", "off", true, { name, repo: r.repo });
+                if (r.state === "protected")
+                    lines.push({ mark: "ok", text: `${p}: ${r.repo} protected` });
+                else if (r.state === "unprotected")
+                    lines.push({ mark: "warn", text: `${p}: ${r.repo} unprotected`, hint: fix });
+                else if (r.state === "unsupported_host")
+                    lines.push({
+                        mark: "warn",
+                        text: `${p}: ${r.repo} not on github.com, so it cannot be protected`,
+                        hint: fix,
+                    });
+                else
+                    lines.push({ mark: "info", text: `${p}: ${r.repo} protection could not be determined` });
+            }
+            return lines;
+        }
+    }
+}
+const detailOf = (e) => (e instanceof Error ? e.message : String(e));
+/** The doctor's durable lines: one block per open session (newest first as listed), capped. */
+export async function durableDoctorLines(api) {
+    let rows;
+    try {
+        rows = await api.listSessions({});
+    }
+    catch (e) {
+        return [{ mark: "info", text: `durable lock: could not read your sessions (${detailOf(e)})` }];
+    }
+    const open = rows.filter((r) => !isEnded(r));
+    if (open.length === 0)
+        return [
+            {
+                mark: "info",
+                text: "durable lock: no open session to check",
+                hint: "`mnemom agent lock <name>` checks MFA and branch protection for that session",
+            },
+        ];
+    const lines = [];
+    for (const r of open.slice(0, DOCTOR_SESSION_CAP)) {
+        const name = r.name ?? r.conversation_id.slice(0, 8);
+        let v;
+        try {
+            v = preflightVerdict(await api.lockPreflight(r.conversation_id, r.agent_id));
+        }
+        catch (e) {
+            v = { kind: "unavailable", detail: detailOf(e) };
+        }
+        lines.push(...verdictLines(name, v));
+    }
+    const rest = open.length - DOCTOR_SESSION_CAP;
+    if (rest > 0)
+        lines.push({
+            mark: "info",
+            text: `durable lock: ${rest} more open sessions not checked; \`mnemom agent lock <name>\` checks each`,
+        });
+    return lines;
+}

package/dist/commands/durable-lock.d.ts

@@ -0,0 +1,254 @@
+/**
+ * `mnemom agent lock <name> [--own-agent] [--json]` (BACKBONE C1, design PR 6; C02-R01, R05, R17,
+ * R20, R26, R27; S1 lock.ts, spec.ts, fixlines.ts).
+ *
+ * The idle-source lock (no live tracked claude): resolve the name through the registry, apply the
+ * R27 cwd rule to the session's registered cwd BEFORE any lock request (a failing cwd sends none),
+ * read this machine's executor id, build the launch spec, POST ROUTES.own_lock, and print the one
+ * quiet lock line plus the S1 laptop risk sentence. The API runs the S1 LOCK_STEPS in order; the CLI
+ * only renders its answer.
+ *
+ * Boundaries (cross-piece, see notes-c1.md):
+ *  - The spec comes from C4's `buildDurableLaunchSpec` by the builder input table (`lockSpecOf`):
+ *    a live original is read exactly (C14-R13), else the launcher's resolved continue flags; what
+ *    it dropped is named on the lock line (C14-R12).
+ *  - The executor id is read from S1 EXECUTOR_STATE_FILE (C2 writes it); only `executor_id` is kept.
+ *  - A live tracked claude for the session on this machine (the verb from another terminal, or
+ *    `/mnemom lock` inside the session) takes the C02-R26 handover order (lib/durable/handover.ts)
+ *    around the commit when `handover` is injected; the launcher's own lock (idle source) injects
+ *    none and sends zero signals. The verb takes no passthrough.
+ */
+import { type LauncherKey } from "../vendor/shared/durable-contract/fixlines.js";
+import { type LaunchSpec } from "../vendor/shared/durable-contract/spec.js";
+import type { CwdKind } from "../vendor/shared/durable-contract/codes.js";
+import { type RegistryRow } from "../lib/durable/api.js";
+import { type HandoverDeps } from "../lib/durable/handover.js";
+import { DurableRefusal } from "../lib/durable/refusal.js";
+import { type DurableVerbDeps } from "./durable-verbs.js";
+import { type BuiltLaunchSpec } from "../durable/launch-spec.js";
+export type CwdRuleResult = {
+    ok: true;
+    root: string;
+} | {
+    ok: false;
+    kind: CwdKind;
+    params: Record<string, string>;
+};
+export interface CwdProbe {
+    /** realpath(dir), or null when it does not exist. */
+    realpath: (dir: string) => string | null;
+    /** `git rev-parse --show-toplevel` in dir (hooks and fsmonitor off, GIT_* cleared), or null. */
+    toplevel: (dir: string) => string | null;
+}
+/**
+ * C02-R27: the registered root is realpath(D) when git's toplevel equals it. not_git knows no
+ * checkout, so it carries no <checkout> and prints no fix line (C11-R27, as the C4 rule).
+ */
+export declare function cwdRule(dir: string, probe: CwdProbe): CwdRuleResult;
+/** The live probe: node realpath and git with hooks/fsmonitor off and every GIT_* var cleared. */
+export declare const liveCwdProbe: CwdProbe;
+/** Claude Code's project directory name for a cwd: every non-alphanumeric character becomes '-'. */
+export declare const claudeSlug: (cwd: string) => string;
+/**
+ * The Claude Code project dirs holding `<ccSessionId>.jsonl`: empty when there are none (no
+ * projects dir at all included), null when the projects dir exists but cannot be read, so the
+ * check cannot be made.
+ */
+export type TranscriptDirs = (ccSessionId: string) => string[] | null;
+/** The live lookup under `${CLAUDE_CONFIG_DIR:-~/.claude}/projects`. */
+export declare function liveTranscriptDirs(env: NodeJS.ProcessEnv): TranscriptDirs;
+/**
+ * BACKBONE C1 lock-time cwd check: the realpath `root` is committed only if the session's transcript
+ * (found by cc_session_id) sits under the project dir slugged from it; a transcript found only under
+ * another slug (the symlink path's) is symlink_transcript. No transcript found: nothing to check.
+ */
+export declare function transcriptSlugRule(root: string, ccSessionId: string | null, dirs: TranscriptDirs | undefined): CwdRuleResult | {
+    ok: false;
+    kind: "transcript_unverifiable";
+};
+/**
+ * Claude Code's folder trust as the shipped claude (2.1.285) reads it: projects[<key>].hasTrustDialogAccepted
+ * in `${CLAUDE_CONFIG_DIR}/.claude.json` (else `~/.claude.json`). A seat has nobody to accept the trust
+ * dialog, so a root without it would park the seat at "Quick safety check". Read-only: never written.
+ */
+export interface TrustProbe {
+    /** The `projects` map of Claude Code's global config, or null when the file is missing or unreadable. */
+    projects: () => Record<string, unknown> | null;
+    /** realpath of the main checkout's toplevel for a dir in a git work tree (a linked worktree's main), or null. */
+    mainRoot: (dir: string) => string | null;
+}
+/**
+ * claude's order for a root (the cwd rule already made it a realpath'd toplevel): the canonical key
+ * (the main checkout for a linked worktree) first, then the bounded walk, which at a toplevel is the
+ * root itself. A parent above the root never counts; the keys are realpaths, never symlink paths.
+ */
+export declare function rootTrusted(root: string, probe: TrustProbe): boolean;
+/** A path as one POSIX shell word: bare when it is plainly safe, else single-quoted. */
+export declare const shellWord: (p: string) => string;
+/** The live probe: the config file Claude Code reads, and git with hooks/fsmonitor off and GIT_* cleared. */
+export declare function liveTrustProbe(env: NodeJS.ProcessEnv): TrustProbe;
+/** This machine's executor id from S1 EXECUTOR_STATE_FILE, or null (not enrolled here). */
+export declare function readLocalExecutorId(home: string, read?: (p: string) => string): string | null;
+export interface IdleSpecInput {
+    root: string;
+    trimMcp?: boolean;
+    model?: string;
+    effort?: string;
+}
+/**
+ * The idle-source spec in the S1 closed schema; fields the schema refuses are dropped, not sent.
+ * Null when even the required core does not parse (e.g. a root the schema refuses).
+ */
+export declare function idleLaunchSpec(i: IdleSpecInput): LaunchSpec | null;
+/** The model/effort one launch recorded in the local ledger (agent-ledger SessionRecord). */
+export interface LaunchModelRecord {
+    conversation_id: string;
+    model: string | null;
+    effort: string | null;
+}
+/**
+ * The lock spec's model/effort: the locked conversation's own launch (its newest ledger record)
+ * wins over the launcher defaults, so a session launched with `--model` keeps that model in its
+ * seat instead of resuming on launcher.toml's (or Claude Code's default) model.
+ */
+export declare function lockSpecDefaults(conversationId: string, records: readonly LaunchModelRecord[], launcher: {
+    trimMcp?: boolean;
+    model?: string;
+    effort?: string;
+}): {
+    trimMcp?: boolean;
+    model?: string;
+    effort?: string;
+};
+export interface LockFacts {
+    name: string;
+    rules: string | null;
+    budgetUsd: number | null;
+    agent: string;
+    /** --own-agent: the lock moved the session onto a new agent, named by `agent` (C02-R10). */
+    ownAgent: boolean;
+    durableOnly: boolean;
+    sharedWith: number;
+    droppedFlags: readonly string[];
+}
+export declare function lockLine(f: LockFacts): string;
+/** Lock facts from the lock answer, falling back to the row (A2 owns the body; read defensively). */
+export declare function lockFactsOf(body: unknown, row: RegistryRow, name: string, built?: readonly string[]): LockFacts;
+export interface LockDeps extends DurableVerbDeps {
+    api: DurableVerbDeps["api"] & {
+        lock(cid: string, agentId: string, body: unknown): Promise<{
+            status: number;
+            body: unknown;
+        }>;
+    };
+    home: string;
+    cwd: () => string;
+    probe: CwdProbe;
+    readExecutorId: (home: string) => string | null;
+    /**
+     * The org this machine's executor is enrolled in, or null when unknown. Read only after a
+     * durable_no_executor answer, to say when the session's org differs; absent: not read.
+     */
+    executorOrg?: (executorId: string) => Promise<string | null>;
+    /**
+     * The spec defaults for the row being locked: the launch's own model/effort (its ledger record),
+     * else the launcher's resolved defaults (launcher.toml model/effort/trim_mcp).
+     */
+    specDefaults: (row: RegistryRow) => {
+        trimMcp?: boolean;
+        model?: string;
+        effort?: string;
+    };
+    /** Where Claude Code holds a session's transcript (the symlink_transcript check); absent: none. */
+    transcriptDirs?: TranscriptDirs;
+    /** The running-session handover (C02-R26); absent on the launcher's idle-source lock. */
+    handover?: HandoverDeps;
+    /** Claude Code's folder trust for the root (cwd_untrusted); absent: not checked. */
+    trust?: TrustProbe;
+    /** The live original's exact argv (KERN_PROCARGS2, C14-R13), or null when unreadable. */
+    readOriginal?: (pid: number) => OriginalLaunch | null;
+    /**
+     * Idle source: would the launcher's continue have been Remote Control (an explicit RC shape, or
+     * the auto-upgrade: entitled and capable)? Evaluated only to name `--remote-control` in
+     * `flags dropped:` (BACKBONE builder input table); never committed.
+     */
+    rcNamed?: () => Promise<boolean>;
+    /** A durable launch of this name has started and not yet registered (launching.ts); absent: none. */
+    launching?: (name: string) => boolean;
+}
+/**
+ * Would the launcher's continue have been Remote Control? An explicit shape counts only when it is
+ * RC on an entitled account (a non-entitled one is degraded to terminal by the launcher, nothing
+ * is dropped); an unpinned one only by the auto-upgrade (entitled and capable). The capability
+ * probe runs only when it decides.
+ */
+export declare function rcWouldBeNamed(i: {
+    shape: string;
+    shapeExplicit: boolean;
+    rcAllowed: boolean;
+    rcCapable: () => boolean;
+}): boolean;
+/** What the running source reads of the live original claude (C14-R13). */
+export interface OriginalLaunch {
+    /** argv[0..] exactly as exec'd. */
+    argv: readonly string[];
+    /** The parent launcher's tokens after its `--`, or null (see discover.ts launcherPassthrough). */
+    passthroughHint: readonly string[] | null;
+    /** RC shape (the conversation id came from the RC proxy variable). */
+    remoteControl: boolean;
+}
+/**
+ * The spec by the builder input table (BACKBONE C4, final F01): a live tracked claude for the
+ * session on this machine is the running source, read exactly; otherwise the idle source, the
+ * launcher's resolved continue flags. `unreadable` when the original is live but its argv cannot be
+ * read (re-resolving the launcher config for a running session is C02-M53); null when the spec does
+ * not fit the closed schema.
+ */
+export declare function lockSpecOf(row: RegistryRow, root: string, deps: Pick<LockDeps, "handover" | "readOriginal" | "rcNamed" | "specDefaults">): Promise<BuiltLaunchSpec | "unreadable" | null>;
+/** The refusal for a session that has not run its first turn, registered or not yet. */
+export declare function firstTurnPending(name: string): DurableRefusal;
+/**
+ * A lock refusal's fix line from the S1 lock catalogue, its params (<repo>, <toplevel>, <checkout>,
+ * <realpath>) from the API details. A param the answer does not carry leaves no fix line: an
+ * unfilled placeholder is never printed.
+ */
+export declare function lockRefusalFix(code: string, details: Record<string, unknown>, name: string, launcherKey: LauncherKey, nameHeld: boolean): string | null;
+/** The answer of one lock attempt on a resolved row: the API body, or the refusal to print. */
+export type LockOutcome = {
+    ok: true;
+    body: unknown;
+    changed: boolean;
+    dropped: string[];
+} | {
+    ok: false;
+    refusal: DurableRefusal;
+};
+/**
+ * Lock one resolved row (the idle source): the R27 cwd rule, this machine's executor id, the spec,
+ * POST own_lock. Never prints; the lock verb and the launcher (C02-R23 c, e) render the outcome.
+ */
+export declare function lockResolvedRow(row: RegistryRow, name: string, opts: {
+    ownAgent?: boolean;
+}, deps: LockDeps): Promise<LockOutcome>;
+/**
+ * durable_no_executor because this machine's executor is enrolled in another org than the
+ * session's: say so, with no fix line (installing a host here would not change the org). Null when
+ * the orgs match or either is unknown; the refusal then renders as the API answered.
+ */
+export declare function orgMismatchRefusal(row: RegistryRow, name: string, executorId: string, deps: Pick<LockDeps, "executorOrg">, apiBody: unknown): Promise<DurableRefusal | null>;
+/**
+ * 422 durable_unsupported {feature: launch_spec_change} on a re-lock (BACKBONE l.57, final F09): the
+ * S1 `launch_spec_change` entry with <flags> filled from the spec this lock built, so the printed
+ * line is a command that works (C11-R27). The locked row holds the name: the done clause applies.
+ */
+export declare function specChangeRefusal(name: string, built: BuiltLaunchSpec, launcherKey: LauncherKey, apiBody: unknown): DurableRefusal;
+/** Print a successful lock: the one quiet line and the S1 laptop risk sentence (C02-R17). */
+export declare function printLocked(o: {
+    body: unknown;
+    changed: boolean;
+    dropped?: readonly string[];
+}, row: RegistryRow, name: string, out: (l: string) => void): void;
+export declare function lockCommand(name: string, opts: {
+    ownAgent?: boolean;
+    json?: boolean;
+}, deps: LockDeps): Promise<number>;