@mnemom/mnemom 0.17.33 → 0.17.34-next.2

package/dist/lib/durable/refusal.js

@@ -0,0 +1,78 @@
+/**
+ * Durable refusals on the CLI (wave-0 fix ruling 19; S1 cli-output.ts). One shape for every refused
+ * durable verb, with or without --json:
+ *
+ *   stderr  <refusal line>
+ *           fix: <S1 catalogue line, rendered under the fix-line rule>   (when there is one)
+ *           code: <machine code>
+ *   stdout  with --json only: exactly one JSON document, the ruling-14 error envelope. An API or
+ *           gateway refusal body is passed through unchanged; a refusal the CLI decides itself is
+ *           built with S1 `cliRefusalJson` (details.fix carries the rendered line).
+ *   exit    CLI_REFUSAL_EXIT (1).
+ *
+ * The refusal line never contains "code:"/"error:" text, so the first machine-readable stderr token
+ * is always the code line.
+ */
+import { CLI_REFUSAL_EXIT, cliRefusalJson, } from "../../vendor/shared/durable-contract/cli-output.js";
+import { isDurableCode } from "../../vendor/shared/durable-contract/codes.js";
+import { renderFixLine, } from "../../vendor/shared/durable-contract/fixlines.js";
+/** A refused durable verb. Commands throw it; `printDurableRefusal` renders it. */
+export class DurableRefusal extends Error {
+    code;
+    fix;
+    details;
+    apiBody;
+    exit;
+    fixParams;
+    constructor(init) {
+        super(init.message);
+        this.name = "DurableRefusal";
+        this.code = init.code;
+        this.fix = init.fix ?? null;
+        this.details = init.details ?? {};
+        this.apiBody = init.apiBody;
+        this.exit = init.exit ?? CLI_REFUSAL_EXIT;
+        this.fixParams = init.fixParams ?? {};
+    }
+}
+/** Render one catalogue line (thin wrapper so callers never restate a fix text). */
+export function fixLine(key, launcherKey, nameHeld, params) {
+    const ctx = { launcherKey, nameHeld, params };
+    return renderFixLine(key, ctx);
+}
+/** The --json stdout document for a refusal. */
+export function refusalJson(r) {
+    if (r.apiBody !== undefined && r.apiBody !== null)
+        return r.apiBody;
+    const details = { ...r.details };
+    if (r.fix)
+        details.fix = r.fix;
+    if (isDurableCode(r.code) && r.fix) {
+        return cliRefusalJson(r.code, r.message, details);
+    }
+    // A non-durable code (agent_not_found, nested_launch_refused, …) or no fix: the same envelope.
+    return {
+        error: {
+            code: r.code,
+            message: r.message,
+            ...(Object.keys(details).length ? { details } : {}),
+        },
+    };
+}
+/** Print a refusal (stderr always; stdout JSON only with --json) and return its exit status. */
+export function printDurableRefusal(r, json, sink) {
+    sink.err(r.message);
+    if (r.fix)
+        sink.err(`fix: ${r.fix}`);
+    sink.err(`code: ${r.code}`);
+    if (json)
+        sink.out(JSON.stringify(refusalJson(r)));
+    return r.exit;
+}
+/**
+ * The agent action's catch (index.ts): a DurableRefusal is printed (refusal line, fix, code) and its
+ * exit status returned; anything else is null and goes to the generic CLI error report.
+ */
+export function durableRefusalExit(error, sink) {
+    return error instanceof DurableRefusal ? printDurableRefusal(error, false, sink) : null;
+}

package/dist/lib/durable/view.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Pure presentation and decision helpers for durable sessions on the CLI (C01-R12, R16, R24, R25,
+ * R28, R30; C11-R27). No I/O: every input is passed in, so each branch is unit-tested.
+ */
+import { type FixKey, type LauncherKey } from "../../vendor/shared/durable-contract/fixlines.js";
+import { type EffectiveState, type StateReason, type UserState } from "../../vendor/shared/durable-contract/states.js";
+import type { RegistryRow } from "./api.js";
+/** The effective state the CLI branches on (GET returns both; I23). */
+export declare function effectiveOf(row: RegistryRow): EffectiveState;
+export declare function isLocked(row: RegistryRow): boolean;
+export declare function isEnded(row: RegistryRow): boolean;
+export declare function reasonOf(row: RegistryRow): StateReason | null;
+/** The user-facing state word (running | waiting | stopped | ended). */
+export declare function userState(row: RegistryRow): UserState;
+/** "ended: agent killed" style label: user state, then the reason in words when there is one. */
+export declare function stateLabel(row: RegistryRow): string;
+/** Spend column (C01-R25): guard_state.spend_usd for locked rows, NA_TEXT for tracked ones. */
+export declare function spendText(row: RegistryRow): string;
+/** --json spend: the cents string for locked rows, null for tracked ones. */
+export declare function spendJson(row: RegistryRow): string | null;
+export declare function committedBudget(row: RegistryRow): number;
+/** The home machine's name, or null when the row carries none. */
+export declare function machineName(row: RegistryRow): string | null;
+/** Where the session lives, for the machine column. */
+export declare function machineText(row: RegistryRow): string;
+export declare function lastActivity(row: RegistryRow): string | null;
+export interface HomeFacts {
+    /** This machine's executor id from its state file, or null (no enrollment here). */
+    localExecutorId: string | null;
+    /** This machine's label (machine_label), for the unreachable-home rule. */
+    localMachineLabel: string | null;
+    nowMs: number;
+}
+export type HomeKind = "here" | "unreachable" | "elsewhere_live" | "elsewhere_stale";
+export declare function homeKind(row: RegistryRow, f: HomeFacts): HomeKind;
+export interface FixContext {
+    launcherKey: LauncherKey;
+    /** The name is held by a non-terminal row (it is when this row is non-terminal). */
+    nameHeld: boolean;
+}
+/** The catalogue key for a row's stopped or ended state, or null for running/waiting. */
+export declare function stateFixKey(row: RegistryRow, extra?: {
+    agentKilled?: boolean;
+    cwdCause?: "missing" | "not_toplevel" | null;
+}): FixKey | null;
+export declare function renderKey(key: FixKey, row: RegistryRow, ctx: FixContext, params?: Record<string, string>): string;
+/** The unreachable-home line (C01-R28): done-then-new, same text in continue, sessions and show. */
+export declare function unreachableHomeFix(row: RegistryRow, ctx: FixContext): string;
+/** The grant warning (BACKBONE C1): days left when inside GRANT_WARNING_S, else null. */
+export declare function grantWarning(row: RegistryRow, nowMs: number): string | null;
+/** The single fix line a row shows in `sessions` / `show` (null when it needs none). */
+export declare function rowFixLine(row: RegistryRow, ctx: FixContext, home: HomeFacts | null): string | null;
+export type ContinueDecision = {
+    kind: "fresh";
+} | {
+    kind: "tracked_continue";
+    row: RegistryRow;
+} | {
+    kind: "attach";
+    row: RegistryRow;
+    wait: boolean;
+} | {
+    kind: "refuse";
+    code: string;
+    message: string;
+    fix: string | null;
+    details?: Record<string, unknown>;
+};
+export interface ContinueInput {
+    /** Every row the caller owns under this name in the active org (any state). */
+    rows: RegistryRow[];
+    launcherKey: LauncherKey;
+    home: HomeFacts;
+    /** This machine's host daemon job is loaded (C01-R16 (c)). */
+    daemonLoaded: boolean;
+    /** The agent the name's latest session ran on is killed (C01-R16 (j), R27). */
+    agentKilled: boolean;
+    /** An explicit --agent that differs from the row's agent (C01-R17). */
+    explicitAgentId: string | null;
+}
+/** The non-terminal row holding the name, if any (names are unique among non-terminal rows). */
+export declare function liveRow(rows: RegistryRow[]): RegistryRow | null;
+export declare function continueDecision(i: ContinueInput): ContinueDecision;

package/dist/lib/durable/view.js

@@ -0,0 +1,244 @@
+/**
+ * Pure presentation and decision helpers for durable sessions on the CLI (C01-R12, R16, R24, R25,
+ * R28, R30; C11-R27). No I/O: every input is passed in, so each branch is unit-tested.
+ */
+import { EXECUTOR_LIVE_S, GRANT_WARNING_S, PER_SESSION_BUDGET_LIMIT_USD, } from "../../vendor/shared/durable-contract/constants.js";
+import { formatSpendCents, grantWarningDays, NA_TEXT, renderFixLine, stoppedFixKey, } from "../../vendor/shared/durable-contract/fixlines.js";
+import { endedBody, isEffectiveState, isSessionState, isTerminalState, userStateOf, } from "../../vendor/shared/durable-contract/states.js";
+import { CODE } from "./codes.js";
+/** The effective state the CLI branches on (GET returns both; I23). */
+export function effectiveOf(row) {
+    const e = row.effective_state;
+    if (isEffectiveState(e))
+        return e;
+    if (isSessionState(row.state))
+        return row.state;
+    return "running";
+}
+export function isLocked(row) {
+    return row.durable_mode === "locked";
+}
+export function isEnded(row) {
+    const e = effectiveOf(row);
+    return e === "expired" || (isSessionState(e) && isTerminalState(e));
+}
+export function reasonOf(row) {
+    return (row.state_reason ?? null);
+}
+/** The user-facing state word (running | waiting | stopped | ended). */
+export function userState(row) {
+    return userStateOf(effectiveOf(row));
+}
+/** "ended: agent killed" style label: user state, then the reason in words when there is one. */
+export function stateLabel(row) {
+    const u = userState(row);
+    const e = effectiveOf(row);
+    if (e === "suspended_grant_expired")
+        return `${u}: grant expired`;
+    const reason = reasonOf(row);
+    if (u === "ended" && e === "expired")
+        return "ended: expired";
+    if (reason)
+        return `${u}: ${reason.replace(/_/g, " ")}`;
+    return u;
+}
+/** Spend column (C01-R25): guard_state.spend_usd for locked rows, NA_TEXT for tracked ones. */
+export function spendText(row) {
+    if (!isLocked(row))
+        return NA_TEXT;
+    const s = row.guard_state?.spend_usd ?? row.spend_usd ?? null;
+    return typeof s === "number" && Number.isFinite(s) && s >= 0 ? formatSpendCents(s) : NA_TEXT;
+}
+/** --json spend: the cents string for locked rows, null for tracked ones. */
+export function spendJson(row) {
+    const t = spendText(row);
+    return t === NA_TEXT ? null : t;
+}
+export function committedBudget(row) {
+    const b = row.guard_state?.budget_usd ?? row.budget_usd ?? 0;
+    return typeof b === "number" && Number.isFinite(b) ? b : 0;
+}
+/** The home machine's name, or null when the row carries none. */
+export function machineName(row) {
+    const h = row.home_executor;
+    return h?.machine_label ?? h?.hostname ?? row.machine ?? null;
+}
+/** Where the session lives, for the machine column. */
+export function machineText(row) {
+    return machineName(row) ?? NA_TEXT;
+}
+export function lastActivity(row) {
+    return row.last_activity_at ?? row.updated_at ?? row.created_at ?? null;
+}
+export function homeKind(row, f) {
+    const h = row.home_executor ?? null;
+    const homeId = row.home_executor_id ?? h?.id ?? null;
+    if (h?.revoked_at)
+        return "unreachable";
+    if (homeId !== null && f.localExecutorId !== null && homeId === f.localExecutorId)
+        return "here";
+    const seen = h?.last_seen_at ? Date.parse(h.last_seen_at) : NaN;
+    const stale = !Number.isFinite(seen) || f.nowMs - seen > EXECUTOR_LIVE_S * 1000;
+    if (stale && f.localMachineLabel !== null && h?.machine_label === f.localMachineLabel)
+        return "unreachable";
+    return stale ? "elsewhere_stale" : "elsewhere_live";
+}
+/** The catalogue key for a row's stopped or ended state, or null for running/waiting. */
+export function stateFixKey(row, extra = {}) {
+    const e = effectiveOf(row);
+    const reason = reasonOf(row);
+    const ended = endedBody(e, reason);
+    if (ended !== null)
+        return ended.state_reason === "agent_killed" || extra.agentKilled ? "agent_killed" : null;
+    if (!isLocked(row))
+        return null;
+    if (e === "paused" || e === "suspended" || e === "suspended_grant_expired") {
+        try {
+            return stoppedFixKey(e, reason, {
+                committedBudgetUsd: committedBudget(row),
+                cwdCause: extra.cwdCause ?? null,
+            });
+        }
+        catch {
+            return "stopped_no_m1_remedy";
+        }
+    }
+    return null;
+}
+export function renderKey(key, row, ctx, params = {}) {
+    const name = row.name ?? row.conversation_id;
+    return renderFixLine(key, {
+        launcherKey: ctx.launcherKey,
+        nameHeld: ctx.nameHeld,
+        params: {
+            name,
+            agent: row.agent_name ?? row.agent_id,
+            limit: String(PER_SESSION_BUDGET_LIMIT_USD),
+            n: String(PER_SESSION_BUDGET_LIMIT_USD),
+            machine: machineText(row),
+            days: "",
+            cwd: row.cwd ?? "",
+            toplevel: row.cwd ?? "",
+            checkout: row.cwd ?? "",
+            realpath: row.cwd ?? "",
+            ...params,
+        },
+    });
+}
+/** The unreachable-home line (C01-R28): done-then-new, same text in continue, sessions and show. */
+export function unreachableHomeFix(row, ctx) {
+    return renderKey("unreachable_home", row, { ...ctx, nameHeld: true });
+}
+/** The grant warning (BACKBONE C1): days left when inside GRANT_WARNING_S, else null. */
+export function grantWarning(row, nowMs) {
+    const g = row.home_executor?.grant_expires_at;
+    if (!g)
+        return null;
+    const left = (Date.parse(g) - nowMs) / 1000;
+    const days = grantWarningDays(left, GRANT_WARNING_S);
+    if (days === null)
+        return null;
+    return renderFixLine("grant_warning", {
+        launcherKey: "always",
+        nameHeld: false,
+        params: { days: String(days) },
+    });
+}
+/** The single fix line a row shows in `sessions` / `show` (null when it needs none). */
+export function rowFixLine(row, ctx, home) {
+    if (isLocked(row) && !isEnded(row) && home) {
+        const k = homeKind(row, home);
+        if (k === "unreachable")
+            return unreachableHomeFix(row, ctx);
+    }
+    const key = stateFixKey(row);
+    if (key === null)
+        return null;
+    return renderKey(key, row, { ...ctx, nameHeld: ctx.nameHeld && !isEnded(row) });
+}
+/** The non-terminal row holding the name, if any (names are unique among non-terminal rows). */
+export function liveRow(rows) {
+    return rows.find((r) => !isEnded(r)) ?? null;
+}
+export function continueDecision(i) {
+    const row = liveRow(i.rows);
+    const ctx = { launcherKey: i.launcherKey, nameHeld: row !== null };
+    if (row === null) {
+        // (j) every session under the name ended: fresh, unless the agent was killed.
+        const last = i.rows[0];
+        if (last && i.agentKilled && i.explicitAgentId === null) {
+            return {
+                kind: "refuse",
+                code: CODE.durable_session_ended,
+                message: `${last.name ?? "this session"}: the agent was killed`,
+                fix: renderKey("agent_killed", last, { ...ctx, nameHeld: false }),
+                details: { state: "killed", state_reason: "agent_killed" },
+            };
+        }
+        return { kind: "fresh" };
+    }
+    if (i.explicitAgentId !== null && i.explicitAgentId !== row.agent_id) {
+        return {
+            kind: "refuse",
+            code: "session_agent_mismatch",
+            message: `${row.name}: this session runs on agent ${row.agent_name ?? row.agent_id}; a session never changes agents`,
+            fix: null,
+            details: { agent_id: row.agent_id },
+        };
+    }
+    if (!isLocked(row))
+        return { kind: "tracked_continue", row };
+    const e = effectiveOf(row);
+    // stopped (d)-(i): their own line, wherever the home is.
+    const stoppedKey = stateFixKey(row);
+    if (e === "paused" || e === "suspended" || e === "suspended_grant_expired") {
+        return {
+            kind: "refuse",
+            code: CODE.durable_session_stopped,
+            message: `${row.name} is ${stateLabel(row)}`,
+            fix: stoppedKey ? renderKey(stoppedKey, row, ctx) : null,
+            details: { state: row.state, state_reason: row.state_reason ?? null },
+        };
+    }
+    const home = homeKind(row, i.home);
+    if (home === "unreachable") {
+        // C01-R28: only a home elsewhere is `session_homed_elsewhere`. S1 names no code for an
+        // unreachable home, so it takes a CLI-local one (like cwd_untrusted), never a durable_* name.
+        return {
+            kind: "refuse",
+            code: "home_unreachable",
+            message: `${row.name}: its home machine can no longer run it`,
+            fix: unreachableHomeFix(row, ctx),
+        };
+    }
+    if (home === "elsewhere_live" || home === "elsewhere_stale") {
+        // Both fix lines name <machine>: with no machine name the line is omitted, never printed with a
+        // placeholder (C11-R27).
+        const machine = machineName(row);
+        if (machine === null) {
+            return {
+                kind: "refuse",
+                code: "session_homed_elsewhere",
+                message: `${row.name} runs on another machine`,
+                fix: null,
+            };
+        }
+        return {
+            kind: "refuse",
+            code: "session_homed_elsewhere",
+            message: `${row.name} runs on ${machine}`,
+            fix: renderKey(home === "elsewhere_live" ? "session_homed_elsewhere" : "session_homed_elsewhere_stale", row, ctx),
+            details: { machine },
+        };
+    }
+    // home here: running/parked/detached/resuming
+    if (!i.daemonLoaded) {
+        return {
+            kind: "refuse",
+            code: "session_locked",
+            message: `${row.name} is locked and the host daemon is not running here`,
+            fix: renderKey("daemon_not_running", row, ctx),
+        };
+    }
+    return { kind: "attach", row, wait: e !== "running" };
+}

package/dist/lib/experimental.d.ts

@@ -63,15 +63,6 @@ export declare function resolveExperimental(opts: {
     stored: ExperimentalPrefs | undefined;
     env: Record<string, string | undefined>;
 }): ExperimentalState;
-/**
- * Features a prerelease (`-next.N`) build makes available without `mnemom experimental
- * enable`: door one's T16 turns implicit goals on by default on `next` (decisions 12 and
- * 22), so its flag, its launcher.toml value and `mnemom agent goal` are not refused there.
- * Stable is unchanged.
- */
-export declare const PRERELEASE_AVAILABLE: readonly ExperimentalId[];
-/** The features whose flags, keys and commands are usable: the enabled ones, plus PRERELEASE_AVAILABLE on a prerelease. */
-export declare function availableFeatures(enabled: readonly ExperimentalId[], prerelease: boolean): ExperimentalId[];
 /** The one-line stderr notice for a launch with experimental features on; null when none are. */
 export declare function experimentalNotice(enabled: readonly ExperimentalId[]): string | null;
 /** The error for using an experimental flag or command while its feature is off. */

package/dist/lib/experimental.js

@@ -108,15 +108,23 @@ export const EXPERIMENTAL_FEATURES = [
         },
     },
     {
-        // Durable governed sessions (M1). Off: every durable verb word exits 2 with the gate pointer
-        // and launches are unchanged; the host daemon reads config.json only, never MNEMOM_EXPERIMENTAL.
+        // Durable M1 (BACKBONE Flags/CLI): every durable verb word, `mnemom agent host …` and
+        // `mnemom agent containment …` exit 2 with the pointer while off; the host daemon and
+        // `host install` read the gate from config.json only (never MNEMOM_EXPERIMENTAL).
         id: "durable",
-        summary: "Durable sessions: lock a session so this machine keeps it running, and adopt running ones",
+        summary: "Durable sessions: lock a session so the host daemon (`mnemom agent host`) keeps it running and brings it back after a crash or reboot, and adopt running ones",
         since: "0.17.27",
         gates: {
-            flags: [],
-            configKeys: ["durable"],
-            commands: ["mnemom agent sessions adopt"],
+            flags: ["--new"],
+            configKeys: ["durable = ask|always"],
+            commands: [
+                "mnemom agent lock|pause|resume|done|kill|amend",
+                "mnemom agent containment",
+                "mnemom agent containment pause|resume",
+                "mnemom agent host",
+                "mnemom agent sessions unlock",
+                "mnemom agent sessions adopt",
+            ],
             env: [],
         },
     },
@@ -175,17 +183,6 @@ export function resolveExperimental(opts) {
         unknown: stored.filter((t) => !isExperimentalId(t)),
     };
 }
-/**
- * Features a prerelease (`-next.N`) build makes available without `mnemom experimental
- * enable`: door one's T16 turns implicit goals on by default on `next` (decisions 12 and
- * 22), so its flag, its launcher.toml value and `mnemom agent goal` are not refused there.
- * Stable is unchanged.
- */
-export const PRERELEASE_AVAILABLE = ["implicit"];
-/** The features whose flags, keys and commands are usable: the enabled ones, plus PRERELEASE_AVAILABLE on a prerelease. */
-export function availableFeatures(enabled, prerelease) {
-    return normalize(prerelease ? [...enabled, ...PRERELEASE_AVAILABLE] : enabled);
-}
 /** The one-line stderr notice for a launch with experimental features on; null when none are. */
 export function experimentalNotice(enabled) {
     if (enabled.length === 0)
@@ -229,6 +226,8 @@ export function experimentalIdForConfigKey(key, value) {
             return value === "true" ? "context-handoff" : undefined;
         case "goal_mode":
             return value === "implicit" ? "implicit" : undefined;
+        case "durable":
+            return value === "off" ? undefined : "durable";
         default:
             return undefined;
     }
@@ -307,6 +306,8 @@ export function configKeyFeature(key) {
         return "context-handoff";
     if (key === "goal_mode")
         return "implicit";
+    if (key === "durable")
+        return "durable";
     return undefined;
 }
 /**

package/dist/lib/launcher-config.d.ts

@@ -16,6 +16,7 @@
  * the caller folds the plain-value settings under the CLI flags.
  */
 import { type SavedAgentAuth } from "./subscription-login.js";
+import { type LauncherKey } from "../vendor/shared/durable-contract/fixlines.js";
 import { type ExperimentalId } from "./experimental.js";
 import { type ContextProfile, type GoalModeDefault, type LaunchShape } from "./agent.js";
 /** The human-editable settings file. Secret key lives elsewhere (launcher.json). */
@@ -85,6 +86,12 @@ export interface LauncherConfig {
      * "off", "350000"), parsed with `parseCompactAt` at the point of use.
      */
     compactAt?: string;
+    /**
+     * Durable launcher key (EXPERIMENTAL `durable`; S1 LAUNCHER_KEYS): `off` (default) launches
+     * tracked, `ask` offers to lock on a TTY, `always` locks every launch. Ignored with the
+     * pointer while `durable` is off (`durable = off` is harmless either way).
+     */
+    durable?: LauncherKey;
     guardrails?: {
         maxTurns?: number;
         budgetUsd?: number;

package/dist/lib/launcher-config.js

@@ -20,6 +20,7 @@ import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "
 import { dirname, join } from "node:path";
 import { parse as parseToml, stringify as stringifyToml, TomlError } from "smol-toml";
 import { MNEMOM_DIR } from "./config.js";
+import { LAUNCHER_KEYS } from "../vendor/shared/durable-contract/fixlines.js";
 import { CONTEXT_PROFILES, isPositiveInt, isPositiveNumber, parseCompactAt, parseAgentRef, parseContextProfile, } from "./agent.js";
 /** The human-editable settings file. Secret key lives elsewhere (launcher.json). */
 export const LAUNCHER_CONFIG_PATH = join(MNEMOM_DIR, "launcher.toml");
@@ -27,6 +28,12 @@ const LAUNCH_SHAPES = ["terminal", "remote-control", "server"];
 const EFFORTS = ["low", "medium", "high", "xhigh", "max"];
 const KEY_SOURCES = ["env", "store", "prompt"];
 const GOAL_MODES = ["implicit", "off"];
+function coerceDurable(raw) {
+    const v = raw.trim().toLowerCase();
+    if (LAUNCHER_KEYS.includes(v))
+        return v;
+    throw new Error(`durable must be one of ${LAUNCHER_KEYS.join(", ")} (got '${raw}').`);
+}
 function coerceLaunch(raw) {
     const v = raw.trim();
     if (LAUNCH_SHAPES.includes(v))
@@ -180,6 +187,14 @@ export const CONFIG_KEYS = [
             c.goalMode = coerceGoalMode(v);
         },
     },
+    {
+        key: "durable",
+        describe: `Durable sessions (${LAUNCHER_KEYS.join("|")}): lock launches so the host daemon runs them (experimental)`,
+        get: (c) => c.durable,
+        set: (c, v) => {
+            c.durable = coerceDurable(v);
+        },
+    },
     {
         key: "context",
         describe: "Context folding (on by default; false disables it for every launch)",
@@ -330,6 +345,8 @@ export function parseLauncherConfig(text) {
         cfg.keySource = coerceKeySource(str(raw.key_source) ?? "");
     if (raw.goal_mode !== undefined)
         cfg.goalMode = coerceGoalMode(str(raw.goal_mode) ?? "");
+    if (raw.durable !== undefined)
+        cfg.durable = coerceDurable(str(raw.durable) ?? "");
     if (raw.context !== undefined)
         cfg.context = coerceBool("context", str(raw.context) ?? "");
     if (raw.slack_listen !== undefined)
@@ -414,6 +431,8 @@ export function serializeLauncherConfig(cfg) {
         doc.key_source = cfg.keySource;
     if (cfg.goalMode !== undefined)
         doc.goal_mode = cfg.goalMode;
+    if (cfg.durable !== undefined)
+        doc.durable = cfg.durable;
     if (cfg.context !== undefined)
         doc.context = cfg.context;
     if (cfg.slackChannel !== undefined)
@@ -527,5 +546,7 @@ export function withoutDisabledExperimental(cfg, enabled) {
         delete out.contextHandoff;
     if (!enabled.includes("implicit") && out.goalMode === "implicit")
         delete out.goalMode;
+    if (!enabled.includes("durable"))
+        delete out.durable;
     return out;
 }

package/dist/lib/scan/caps.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Coverage caps and sampling. Port of mnemom-api src/org-scan/scan/capped-scan.ts (PR #4208).
+ *
+ * Coverage decision (Shraddha, 2026-10-28): each scan covers the last 3 months OR the last 2,000 merged
+ * PRs, whichever is MORE; above 2,000 in the window, an even deterministic sample of 2,000.
+ */
+export declare const COVERAGE_MONTHS = 3;
+export interface ScanCaps {
+    maxPrs: number;
+    /** A PR with more additions+deletions than this is skipped, never read in full. */
+    maxPrSizeLines: number;
+    /** Upstream read calls. */
+    maxReads: number;
+    /** Wall-clock budget. */
+    maxMillis: number;
+}
+export declare const DEFAULT_SCAN_CAPS: ScanCaps;
+export type StopReason = "pr-cap" | "read-cap" | "time-cap";
+/** The day `months` calendar months before `end` (YYYY-MM-DD, UTC), clamped to the month's last day. */
+export declare function monthsBefore(end: string, months: number): string;
+/** `k` items spread evenly across `items` (order kept): index floor(i*n/k). Deterministic; n <= k returns all. */
+export declare function evenSample<T>(items: readonly T[], k: number): T[];
+export declare function sanitiseCaps(c: Partial<ScanCaps>): ScanCaps;
+/** Running read budget. Every call is told how many reads it may spend (`room`). */
+export declare class Budget {
+    private caps;
+    private now;
+    private startedAt;
+    reads: number;
+    constructor(caps: ScanCaps, now: () => number, startedAt: number);
+    block(n?: number): StopReason | null;
+    room(): number;
+    overrun(): StopReason | null;
+    charge(n: number): void;
+}

package/dist/lib/scan/caps.js

@@ -0,0 +1,67 @@
+/**
+ * Coverage caps and sampling. Port of mnemom-api src/org-scan/scan/capped-scan.ts (PR #4208).
+ *
+ * Coverage decision (Shraddha, 2026-10-28): each scan covers the last 3 months OR the last 2,000 merged
+ * PRs, whichever is MORE; above 2,000 in the window, an even deterministic sample of 2,000.
+ */
+export const COVERAGE_MONTHS = 3;
+export const DEFAULT_SCAN_CAPS = {
+    maxPrs: 2_000,
+    maxPrSizeLines: 20_000,
+    maxReads: 4_500,
+    maxMillis: 15 * 60_000,
+};
+/** The day `months` calendar months before `end` (YYYY-MM-DD, UTC), clamped to the month's last day. */
+export function monthsBefore(end, months) {
+    const [y, m, d] = end.split("-").map(Number);
+    const target = new Date(Date.UTC(y, m - 1 - months, 1));
+    const last = new Date(Date.UTC(target.getUTCFullYear(), target.getUTCMonth() + 1, 0)).getUTCDate();
+    target.setUTCDate(Math.min(d, last));
+    return target.toISOString().slice(0, 10);
+}
+/** `k` items spread evenly across `items` (order kept): index floor(i*n/k). Deterministic; n <= k returns all. */
+export function evenSample(items, k) {
+    const n = items.length;
+    if (n <= k)
+        return [...items];
+    return Array.from({ length: k }, (_, i) => items[Math.floor((i * n) / k)]);
+}
+export function sanitiseCaps(c) {
+    const pos = (n, d) => typeof n === "number" && Number.isFinite(n) && n > 0 ? Math.floor(n) : d;
+    return {
+        maxPrs: pos(c.maxPrs, DEFAULT_SCAN_CAPS.maxPrs),
+        maxPrSizeLines: pos(c.maxPrSizeLines, DEFAULT_SCAN_CAPS.maxPrSizeLines),
+        maxReads: pos(c.maxReads, DEFAULT_SCAN_CAPS.maxReads),
+        maxMillis: pos(c.maxMillis, DEFAULT_SCAN_CAPS.maxMillis),
+    };
+}
+/** Running read budget. Every call is told how many reads it may spend (`room`). */
+export class Budget {
+    caps;
+    now;
+    startedAt;
+    reads = 0;
+    constructor(caps, now, startedAt) {
+        this.caps = caps;
+        this.now = now;
+        this.startedAt = startedAt;
+    }
+    block(n = 1) {
+        if (this.now() - this.startedAt >= this.caps.maxMillis)
+            return "time-cap";
+        if (this.reads + n > this.caps.maxReads)
+            return "read-cap";
+        return null;
+    }
+    room() {
+        if (this.now() - this.startedAt >= this.caps.maxMillis)
+            return 0;
+        return Math.max(0, this.caps.maxReads - this.reads);
+    }
+    overrun() {
+        return this.reads > this.caps.maxReads ? "read-cap" : null;
+    }
+    charge(n) {
+        this.reads += n;
+    }
+}