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

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

@@ -0,0 +1,136 @@
+/**
+ * The durable registry and owner-verb client (BACKBONE C1, A2; S1 routes.ts ROUTES.own_*).
+ *
+ * Every call returns `{status, body}` and never throws on an HTTP answer: the commands decide from
+ * the status and the S1 code. A transport failure, a timeout or a 5xx (other than a durable 503 the
+ * caller must surface, which keeps its body) is a `RegistryUnavailable`, so a launch fails closed
+ * with `session_registry_unavailable` (C01-R18) instead of minting a conversation it could not
+ * resolve. The timeout is fixed in code: REGISTRY_TIMEOUT_MS covers connect plus total.
+ *
+ * Credentials (S1 owner-credential rule; BACKBONE owner Q6): the owner's JWT, else the personal
+ * org `mnm_` API key (MNEMOM_API_KEY). Org containment and device-step polls are JWT-only; the
+ * caller asks for that with `jwtOnly`.
+ *
+ * Not frozen by S1 (A2 owns them; recorded in notes-c1.md as the cross-piece assumption):
+ *   GET  /v1/agent/sessions?name=&agent_id=&org_id=   -> {sessions: Row[]} (or a bare array)
+ *   POST /v1/agent/sessions/{cid}?agent_id=            -> 201/200 Row (create)
+ *   GET  /v1/agent/sessions/{cid}/lock?agent_id=&dry_run=true -> the doctor's lock preflight
+ */
+import { type RouteName } from "../../vendor/shared/durable-contract/routes.js";
+/** CLI registry timeout, connect plus total (C01-R18: at most 10 s). */
+export declare const REGISTRY_TIMEOUT_MS = 10000;
+export type DurableCredential = {
+    type: "jwt";
+    token: string;
+} | {
+    type: "api-key";
+    key: string;
+} | {
+    type: "none";
+};
+export interface DurableHttpDeps {
+    fetch: typeof fetch;
+    apiBase: () => string;
+    credential: () => Promise<DurableCredential>;
+    /** The active org id (`mnemom org use`), or undefined. */
+    activeOrgId: () => string | undefined;
+    /** Agents named `name` in the caller's org fleets (lib/api.ts listOrgAgents); none when absent. */
+    agentsByName?: (name: string) => Promise<Array<{
+        id: string;
+        org_id: string;
+    }>>;
+}
+export interface ApiAnswer {
+    status: number;
+    body: unknown;
+}
+/** The registry could not be read: transport error, timeout or a non-durable 5xx. */
+export declare class RegistryUnavailable extends Error {
+    constructor(detail: string);
+}
+/** A registry row as the CLI reads it. Every field but the name and cid is optional. */
+export interface RegistryRow {
+    id?: string;
+    conversation_id: string;
+    name: string | null;
+    agent_id: string;
+    org_id?: string | null;
+    agent_name?: string | null;
+    durable_mode?: "tracked" | "locked";
+    state: string;
+    state_reason?: string | null;
+    effective_state?: string;
+    cc_session_id?: string | null;
+    cwd?: string | null;
+    home_executor_id?: string | null;
+    home_executor?: {
+        id?: string;
+        machine_label?: string | null;
+        hostname?: string | null;
+        last_seen_at?: string | null;
+        revoked_at?: string | null;
+        grant_expires_at?: string | null;
+    } | null;
+    machine?: string | null;
+    spend_usd?: number | null;
+    guard_state?: {
+        spend_usd?: number | null;
+        budget_usd?: number | null;
+    } | null;
+    budget_usd?: number | null;
+    last_activity_at?: string | null;
+    updated_at?: string | null;
+    created_at?: string | null;
+    created_by?: string | null;
+    owner?: string | null;
+    agent_containment?: string | null;
+    [k: string]: unknown;
+}
+export declare function errorCodeOf(body: unknown): string | null;
+export declare function errorDetailsOf(body: unknown): Record<string, unknown>;
+export declare function errorMessageOf(body: unknown): string | null;
+export declare class DurableApi {
+    private readonly deps;
+    constructor(deps: DurableHttpDeps);
+    private request;
+    private q;
+    /** The caller's own sessions in the active org, optionally by name and agent. */
+    listSessions(filter?: {
+        name?: string;
+        agentId?: string;
+    }): Promise<RegistryRow[]>;
+    /**
+     * GET /v1/code/entitlement in the active org (C01-R26): its `durable` field says whether this
+     * caller has the registry at all. The answer as is; the launcher decides (launch.ts).
+     */
+    entitlement(): Promise<ApiAnswer>;
+    getSession(cid: string, agentId: string, include?: "goal"): Promise<ApiAnswer>;
+    createSession(cid: string, agentId: string, body: Record<string, unknown>): Promise<ApiAnswer>;
+    /** An owner session verb (S1 ROUTES.own_*). */
+    ownerVerb(route: RouteName, cid: string, agentId: string, body?: unknown): Promise<ApiAnswer>;
+    /** POST ROUTES.own_lock with the closed S1 lock body (spec, executor_id, own_agent). */
+    lock(cid: string, agentId: string, body: unknown): Promise<ApiAnswer>;
+    /**
+     * The read-only lock preflight for `mnemom agent doctor` (C02-R19): a GET on the lock route with
+     * dry_run, so it never mutates (A2 owns the route; see commands/durable-doctor.ts).
+     */
+    lockPreflight(cid: string, agentId: string): Promise<ApiAnswer>;
+    /** The existing org containment route; JWT only (the route refuses API keys). */
+    containment(orgId: string, agentId: string, verb: "pause" | "resume"): Promise<ApiAnswer>;
+    /** The agent record (for its org id). */
+    getAgent(agentId: string): Promise<ApiAnswer>;
+    /** Agents by name across the caller's orgs (containment by name). */
+    agentsByName(name: string): Promise<Array<{
+        id: string;
+        org_id: string;
+    }>>;
+    /** RFC 8628 device token poll for an owner_mutation device step (issues no token). */
+    devicePoll(deviceCode: string, clientId: string): Promise<ApiAnswer>;
+    credentialType(): Promise<DurableCredential["type"]>;
+}
+/** A non-200 list answer the caller turns into a refusal. */
+export declare class RegistryAnswerError extends Error {
+    readonly answer: ApiAnswer;
+    constructor(answer: ApiAnswer);
+}
+export declare function rowsOf(body: unknown): RegistryRow[];

package/dist/lib/durable/api.js

@@ -0,0 +1,220 @@
+/**
+ * The durable registry and owner-verb client (BACKBONE C1, A2; S1 routes.ts ROUTES.own_*).
+ *
+ * Every call returns `{status, body}` and never throws on an HTTP answer: the commands decide from
+ * the status and the S1 code. A transport failure, a timeout or a 5xx (other than a durable 503 the
+ * caller must surface, which keeps its body) is a `RegistryUnavailable`, so a launch fails closed
+ * with `session_registry_unavailable` (C01-R18) instead of minting a conversation it could not
+ * resolve. The timeout is fixed in code: REGISTRY_TIMEOUT_MS covers connect plus total.
+ *
+ * Credentials (S1 owner-credential rule; BACKBONE owner Q6): the owner's JWT, else the personal
+ * org `mnm_` API key (MNEMOM_API_KEY). Org containment and device-step polls are JWT-only; the
+ * caller asks for that with `jwtOnly`.
+ *
+ * Not frozen by S1 (A2 owns them; recorded in notes-c1.md as the cross-piece assumption):
+ *   GET  /v1/agent/sessions?name=&agent_id=&org_id=   -> {sessions: Row[]} (or a bare array)
+ *   POST /v1/agent/sessions/{cid}?agent_id=            -> 201/200 Row (create)
+ *   GET  /v1/agent/sessions/{cid}/lock?agent_id=&dry_run=true -> the doctor's lock preflight
+ */
+import { randomUUID } from "node:crypto";
+import { routePath } from "../../vendor/shared/durable-contract/routes.js";
+/** CLI registry timeout, connect plus total (C01-R18: at most 10 s). */
+export const REGISTRY_TIMEOUT_MS = 10_000;
+/** The registry could not be read: transport error, timeout or a non-durable 5xx. */
+export class RegistryUnavailable extends Error {
+    constructor(detail) {
+        super(detail);
+        this.name = "RegistryUnavailable";
+    }
+}
+export function errorCodeOf(body) {
+    if (body === null || typeof body !== "object")
+        return null;
+    const b = body;
+    const e = b.error;
+    if (e !== null &&
+        typeof e === "object" &&
+        typeof e.code === "string")
+        return e.code;
+    if (typeof b.code === "string")
+        return b.code;
+    if (typeof e === "string")
+        return e;
+    return null;
+}
+export function errorDetailsOf(body) {
+    if (body === null || typeof body !== "object")
+        return {};
+    const b = body;
+    const e = b.error;
+    if (e !== null && typeof e === "object") {
+        const d = e.details;
+        if (d !== null && typeof d === "object")
+            return d;
+    }
+    if (b.details !== null && typeof b.details === "object")
+        return b.details;
+    return {};
+}
+export function errorMessageOf(body) {
+    if (body === null || typeof body !== "object")
+        return null;
+    const b = body;
+    const e = b.error;
+    if (e !== null &&
+        typeof e === "object" &&
+        typeof e.message === "string")
+        return e.message;
+    if (typeof b.message === "string")
+        return b.message;
+    return null;
+}
+export class DurableApi {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async request(method, path, opts = {}) {
+        const cred = await this.deps.credential();
+        const headers = { Accept: "application/json" };
+        if (cred.type === "jwt")
+            headers.Authorization = `Bearer ${cred.token.trim()}`;
+        else if (cred.type === "api-key" && !opts.jwtOnly)
+            headers["X-Mnemom-Api-Key"] = cred.key.trim();
+        let body;
+        if (opts.form) {
+            headers["Content-Type"] = "application/x-www-form-urlencoded";
+            body = new URLSearchParams(opts.form).toString();
+        }
+        else if (opts.body !== undefined) {
+            headers["Content-Type"] = "application/json";
+            body = JSON.stringify(opts.body);
+        }
+        if (method === "POST")
+            headers["Idempotency-Key"] = randomUUID();
+        const url = new URL(path, this.deps.apiBase().replace(/\/+$/, "") + "/").href;
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), REGISTRY_TIMEOUT_MS);
+        let res;
+        let text;
+        try {
+            res = await this.deps.fetch(url, { method, headers, body, signal: ctrl.signal });
+            // The body read is inside the same budget: a stalled (aborted) body is a timeout too.
+            text = await res.text();
+        }
+        catch (e) {
+            throw new RegistryUnavailable(e instanceof Error ? e.message : String(e));
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        let parsed = null;
+        if (text) {
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                parsed = { error: { code: "unparseable_body", message: text.slice(0, 200) } };
+            }
+        }
+        // A 5xx is the registry being down unless it carries a durable code the caller surfaces.
+        if (res.status >= 500 && !(errorCodeOf(parsed) ?? "").startsWith("durable_")) {
+            throw new RegistryUnavailable(`HTTP ${res.status}`);
+        }
+        return { status: res.status, body: parsed };
+    }
+    q(params) {
+        const s = new URLSearchParams();
+        for (const [k, v] of Object.entries(params))
+            if (v !== undefined && v !== "")
+                s.set(k, v);
+        const t = s.toString();
+        return t ? `?${t}` : "";
+    }
+    /** The caller's own sessions in the active org, optionally by name and agent. */
+    async listSessions(filter = {}) {
+        const a = await this.request("GET", `/v1/agent/sessions${this.q({ name: filter.name, agent_id: filter.agentId, org_id: this.deps.activeOrgId() })}`);
+        // Every non-200, a bare 404 (the route absent: API flag off) included, goes to the caller,
+        // which maps 403/404 to the legacy launch (launch.ts registryRows).
+        if (a.status !== 200)
+            throw new RegistryAnswerError(a);
+        return rowsOf(a.body);
+    }
+    /**
+     * GET /v1/code/entitlement in the active org (C01-R26): its `durable` field says whether this
+     * caller has the registry at all. The answer as is; the launcher decides (launch.ts).
+     */
+    async entitlement() {
+        return this.request("GET", `/v1/code/entitlement${this.q({ org_id: this.deps.activeOrgId() })}`);
+    }
+    async getSession(cid, agentId, include) {
+        return this.request("GET", `/v1/agent/sessions/${encodeURIComponent(cid)}${this.q({ agent_id: agentId, include })}`);
+    }
+    async createSession(cid, agentId, body) {
+        return this.request("POST", `/v1/agent/sessions/${encodeURIComponent(cid)}${this.q({ agent_id: agentId })}`, { body });
+    }
+    /** An owner session verb (S1 ROUTES.own_*). */
+    async ownerVerb(route, cid, agentId, body = {}) {
+        return this.request("POST", `${routePath(route, cid)}${this.q({ agent_id: agentId })}`, {
+            body,
+        });
+    }
+    /** POST ROUTES.own_lock with the closed S1 lock body (spec, executor_id, own_agent). */
+    async lock(cid, agentId, body) {
+        return this.ownerVerb("own_lock", cid, agentId, body);
+    }
+    /**
+     * The read-only lock preflight for `mnemom agent doctor` (C02-R19): a GET on the lock route with
+     * dry_run, so it never mutates (A2 owns the route; see commands/durable-doctor.ts).
+     */
+    async lockPreflight(cid, agentId) {
+        return this.request("GET", `${routePath("own_lock", cid)}${this.q({ agent_id: agentId, dry_run: "true" })}`);
+    }
+    /** The existing org containment route; JWT only (the route refuses API keys). */
+    async containment(orgId, agentId, verb) {
+        return this.request("POST", `/v1/orgs/${encodeURIComponent(orgId)}/agents/${encodeURIComponent(agentId)}/${verb}`, { body: {}, jwtOnly: true });
+    }
+    /** The agent record (for its org id). */
+    async getAgent(agentId) {
+        return this.request("GET", `/v1/agents/${encodeURIComponent(agentId)}`);
+    }
+    /** Agents by name across the caller's orgs (containment by name). */
+    async agentsByName(name) {
+        return this.deps.agentsByName ? this.deps.agentsByName(name) : [];
+    }
+    /** RFC 8628 device token poll for an owner_mutation device step (issues no token). */
+    async devicePoll(deviceCode, clientId) {
+        return this.request("POST", "/v1/oauth/token", {
+            form: {
+                grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+                device_code: deviceCode,
+                client_id: clientId,
+            },
+        });
+    }
+    async credentialType() {
+        return (await this.deps.credential()).type;
+    }
+}
+/** A non-200 list answer the caller turns into a refusal. */
+export class RegistryAnswerError extends Error {
+    answer;
+    constructor(answer) {
+        super(errorMessageOf(answer.body) ?? `HTTP ${answer.status}`);
+        this.answer = answer;
+        this.name = "RegistryAnswerError";
+    }
+}
+export function rowsOf(body) {
+    const isRow = (r) => r !== null && typeof r === "object" && typeof r.conversation_id === "string";
+    if (Array.isArray(body))
+        return body.filter(isRow);
+    if (body !== null && typeof body === "object") {
+        for (const k of ["sessions", "rows", "items", "data"]) {
+            const v = body[k];
+            if (Array.isArray(v))
+                return v.filter(isRow);
+        }
+    }
+    return [];
+}

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

@@ -0,0 +1,8 @@
+/**
+ * Every S1 durable code keyed by itself, typed to its literal: `CODE.durable_session_ended` is that
+ * code's string. C1 names durable codes only through this map (S1
+ * FREEZE_STRUCTURED.CODES, built from DURABLE_CODES), so a code S1 does not freeze fails to compile
+ * and no durable code is restated as a quoted literal outside S1 (C10-STATIC-001).
+ */
+import type { DurableCode } from "../../vendor/shared/durable-contract/codes.js";
+export declare const CODE: { readonly [K in DurableCode]: K; };

package/dist/lib/durable/codes.js

@@ -0,0 +1,2 @@
+import { FREEZE_STRUCTURED } from "../../vendor/shared/durable-contract/freeze-record.js";
+export const CODE = FREEZE_STRUCTURED.CODES;

package/dist/lib/durable/first-turn.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Lock after the first turn (ruling dogfood B5). A launch that locks a NEW Claude Code session
+ * (`durable = always`, or ask answered yes, with no transcript yet) cannot lock before claude has
+ * run: the daemon's seat resumes the session's transcript, and there is none until the first turn
+ * writes it (host/transcript.ts ensureTranscript answers lost, the session fails transcript_lost).
+ *
+ * So the launcher spawns claude attended and watches the transcript. Once the first turn has
+ * completed it locks, under the running-session handover (C02-R26: freeze, commit, the seat's
+ * hello, then the original is killed and the parent attaches to the seat). Never before. A lock
+ * refusal at that point leaves the attended session running and prints the refusal with its fix
+ * line.
+ *
+ * No I/O here: lib/durable/live.ts wires the transcript reads, the lock and the clock.
+ */
+import type { LockOutcome, TranscriptDirs } from "../../commands/durable-lock.js";
+import { DurableRefusal } from "./refusal.js";
+/** How often the launcher re-reads the transcript while it waits for the first turn. */
+export declare const FIRST_TURN_POLL_MS = 1000;
+/**
+ * Whether a Claude Code transcript (JSONL) holds a completed turn: an assistant entry whose
+ * stop_reason ends the turn (end_turn, max_tokens, stop_sequence, refusal), or the engine's own
+ * turn-end record (system turn_duration or stop_hook_summary). Unparseable lines (a line still
+ * being written) are skipped.
+ */
+export declare function turnCompleted(jsonl: string): boolean;
+/**
+ * Reads `<projects>/<dir>/<cc>.jsonl` from the first project dir that holds it; null while none
+ * does, when it cannot be read (it is read again on the next poll), or with no CC session id.
+ */
+export declare function transcriptReader(projects: string, dirs: TranscriptDirs, cc: string | null | undefined, read: (path: string) => string): () => string | null;
+export interface FirstTurnLockDeps {
+    /** The session name (the fix line of a lock that could not be sent). */
+    name: string;
+    /** The session's transcript text, or null while Claude Code has written none. */
+    readTranscript(): string | null;
+    /** The attended claude is still running. */
+    childAlive(): boolean;
+    /** The lock of the row under the running-session handover (lockResolvedRow). */
+    lock(): Promise<LockOutcome>;
+    /** Print a lock refusal and its fix line (the session stays attended). */
+    printRefusal(r: DurableRefusal): void;
+    sleep(ms: number): Promise<void>;
+}
+export type FirstTurnLock = "locked" | "refused" | "ended";
+/**
+ * Wait for the first completed turn, then lock. "ended": claude exited first, nothing was locked.
+ * "locked": the handover took the session (the parent's exit path attaches to the seat).
+ * "refused": the refusal was printed and the attended session goes on.
+ */
+export declare function lockAfterFirstTurn(d: FirstTurnLockDeps, pollMs?: number): Promise<FirstTurnLock>;

package/dist/lib/durable/first-turn.js

@@ -0,0 +1,102 @@
+/**
+ * Lock after the first turn (ruling dogfood B5). A launch that locks a NEW Claude Code session
+ * (`durable = always`, or ask answered yes, with no transcript yet) cannot lock before claude has
+ * run: the daemon's seat resumes the session's transcript, and there is none until the first turn
+ * writes it (host/transcript.ts ensureTranscript answers lost, the session fails transcript_lost).
+ *
+ * So the launcher spawns claude attended and watches the transcript. Once the first turn has
+ * completed it locks, under the running-session handover (C02-R26: freeze, commit, the seat's
+ * hello, then the original is killed and the parent attaches to the seat). Never before. A lock
+ * refusal at that point leaves the attended session running and prints the refusal with its fix
+ * line.
+ *
+ * No I/O here: lib/durable/live.ts wires the transcript reads, the lock and the clock.
+ */
+import { join } from "node:path";
+import { DurableRefusal } from "./refusal.js";
+/** How often the launcher re-reads the transcript while it waits for the first turn. */
+export const FIRST_TURN_POLL_MS = 1000;
+/** An assistant stop that ends the turn: anything but a tool call or a paused turn. */
+const TURN_CONTINUES = new Set(["tool_use", "pause_turn"]);
+/**
+ * Whether a Claude Code transcript (JSONL) holds a completed turn: an assistant entry whose
+ * stop_reason ends the turn (end_turn, max_tokens, stop_sequence, refusal), or the engine's own
+ * turn-end record (system turn_duration or stop_hook_summary). Unparseable lines (a line still
+ * being written) are skipped.
+ */
+export function turnCompleted(jsonl) {
+    for (const line of jsonl.split("\n")) {
+        let e;
+        try {
+            e = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (e === null || typeof e !== "object")
+            continue;
+        const r = e;
+        if (r.type === "system" && (r.subtype === "turn_duration" || r.subtype === "stop_hook_summary"))
+            return true;
+        if (r.type !== "assistant" || r.message === null || typeof r.message !== "object")
+            continue;
+        const stop = r.message.stop_reason;
+        if (typeof stop === "string" && !TURN_CONTINUES.has(stop))
+            return true;
+    }
+    return false;
+}
+/**
+ * Reads `<projects>/<dir>/<cc>.jsonl` from the first project dir that holds it; null while none
+ * does, when it cannot be read (it is read again on the next poll), or with no CC session id.
+ */
+export function transcriptReader(projects, dirs, cc, read) {
+    return () => {
+        if (!cc)
+            return null;
+        const found = dirs(cc)?.[0];
+        if (found === undefined)
+            return null;
+        try {
+            return read(join(projects, found, `${cc}.jsonl`));
+        }
+        catch {
+            return null;
+        }
+    };
+}
+/**
+ * Wait for the first completed turn, then lock. "ended": claude exited first, nothing was locked.
+ * "locked": the handover took the session (the parent's exit path attaches to the seat).
+ * "refused": the refusal was printed and the attended session goes on.
+ */
+export async function lockAfterFirstTurn(d, pollMs = FIRST_TURN_POLL_MS) {
+    for (;;) {
+        if (!d.childAlive())
+            return "ended";
+        const t = d.readTranscript();
+        if (t !== null && turnCompleted(t))
+            break;
+        await d.sleep(pollMs);
+    }
+    let o;
+    try {
+        o = await d.lock();
+    }
+    catch (e) {
+        o = {
+            ok: false,
+            refusal: e instanceof DurableRefusal
+                ? e
+                : new DurableRefusal({
+                    code: "session_registry_unavailable",
+                    message: `mnemom agent: the lock after the first turn failed (${e instanceof Error ? e.message : String(e)}); the session stays attended`,
+                    fix: `\`mnemom agent lock ${d.name}\``,
+                }),
+        };
+    }
+    if (o.ok)
+        return "locked";
+    d.printRefusal(o.refusal);
+    return "refused";
+}

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

@@ -0,0 +1,48 @@
+/**
+ * The CLI `durable` gate (BACKBONE Flags/CLI; C17-R10; amendments 26, 35).
+ *
+ * While `durable` is off every durable verb word exits 2 with `gatedMessage(…, 'durable')`, sends
+ * no HTTP, writes nothing under HOME and starts no process — `--help` and `--json` included, which
+ * is why the check runs on raw argv before commander parses it (commander answers `--help` before
+ * any preAction hook). The words are the declared allowlisted difference: a session named `lock`
+ * or `containment` is not launched by name while durable is off.
+ *
+ * `mnemom agent host run` is gated like every other word until C2 registers its handler (C2 then
+ * reads the gate from config.json only, C12-R25); ungated, it would fall through to the launcher as
+ * a session named "host". The pre-existing `mnemom agent sessions` / `show` are not gated.
+ */
+import { type ExperimentalId } from "../experimental.js";
+export declare const DURABLE_ID: "durable";
+/** `mnemom agent <word>` words that exist only with durable on. */
+export declare const DURABLE_VERB_WORDS: readonly ["lock", "pause", "resume", "done", "kill", "amend", "host", "containment"];
+/** `mnemom agent sessions <sub>` sub-verbs that exist only with durable on. */
+export declare const DURABLE_SESSIONS_SUBVERBS: readonly ["unlock", "adopt"];
+export declare function durableOn(enabled: readonly ExperimentalId[]): boolean;
+/**
+ * The options that take a value, by flag spelling, as commander parses them: a `required` one always
+ * takes the next word; an `optional` one takes it only when it does not start with `-`. Every other
+ * option is a bare flag. The scan uses them to step over options placed before the verb word.
+ */
+export interface OptionShapes {
+    required: ReadonlySet<string>;
+    optional: ReadonlySet<string>;
+}
+/** The value-taking options of `commands` (commander `Command#options`), merged. */
+export declare function optionShapesOf(commands: ReadonlyArray<{
+    options: readonly unknown[];
+}>): OptionShapes;
+/**
+ * The gated use `argv` (process.argv.slice(2)) makes, as the `what` of the gate message, or null
+ * when argv names no durable verb. The verb is the first operand after `agent`, with options (and
+ * their values, per `shapes`) stepped over exactly as commander would before it dispatches the
+ * subcommand, so `agent --new lock x` is gated like `agent lock x`. A word after `--` or as a later
+ * positional is not a verb use.
+ */
+export declare function durableVerbUse(argv: readonly string[], shapes?: OptionShapes): string | null;
+/**
+ * The guard inside every durable verb's action: the pointer (exit 2) while durable is off, else
+ * null. The argv gate above runs first; this one holds for any argv shape that reaches commander.
+ */
+export declare function durableActionGate(what: string, enabled: readonly ExperimentalId[]): string | null;
+/** The gate decision for argv: null when allowed, else the stderr message (exit 2). */
+export declare function durableGate(argv: readonly string[], enabled: readonly ExperimentalId[], shapes?: OptionShapes): string | null;