@mnemom/mnemom 0.17.2-next.7 → 0.17.2-next.9

package/dist/commands/agent-doctor.d.ts

@@ -9,7 +9,7 @@
  * Checks: settings file, coding-agent CLI, Anthropic key source, gateway health
  * (200 + the x-mnemom-verdict header that proves the governance pipeline is
  * live), Remote-Control capability (node + openssl + the --remote-control flag),
- * and claude.ai login (informational — Remote Control needs it).
+ * claude.ai login (informational — Remote Control needs it), and CLI auto-update status.
  */
 type Mark = "ok" | "warn" | "miss" | "info";
 export interface DoctorOptions {

package/dist/commands/agent-doctor.js

@@ -9,7 +9,7 @@
  * Checks: settings file, coding-agent CLI, Anthropic key source, gateway health
  * (200 + the x-mnemom-verdict header that proves the governance pipeline is
  * live), Remote-Control capability (node + openssl + the --remote-control flag),
- * and claude.ai login (informational — Remote Control needs it).
+ * claude.ai login (informational — Remote Control needs it), and CLI auto-update status.
  */
 import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
@@ -20,6 +20,7 @@ import { getCodeEntitlement, MnemomApiError } from "../lib/api.js";
 import { isLoggedIn } from "../lib/auth.js";
 import { getActiveOrg } from "../lib/cli-config.js";
 import { isCodeNotEnabled, sourceLabel } from "./agent-invite.js";
+import { probeUpdateStatus } from "../lib/update/doctor.js";
 const MARK = { ok: "[ ok ]", warn: "[warn]", miss: "[MISS]", info: "[info]" };
 const out = (line = "") => console.log(line);
 /** Run the preflight and print the checklist. Sets process.exitCode on failure. */
@@ -85,6 +86,9 @@ export async function agentDoctorCommand(options = {}) {
     // ── Mnemom Agent access (invited cohort gate) ──
     const gate = await probeCodeAccess();
     add(gate.mark, gate.text, gate.hint);
+    // ── CLI auto-update ──
+    const upd = await probeUpdateStatus();
+    add(upd.mark, upd.text, upd.hint);
     // ── render ──
     const door = resolveAnthropicDoor(env);
     out("mnemom agent doctor");

package/dist/commands/agent-setup.d.ts

@@ -34,10 +34,35 @@ export declare function defaultAgentSlug(): string;
  * The default slug resolved from the authenticated IDENTITY: `agent-<handle>` from
  * the login email fetched via `/v1/auth/me`. The CLI's stored OAuth token carries
  * no email, so the sync `defaultAgentSlug()` alone falls back to "agent-user";
- * this fetches the real email once a session exists. Falls back to
- * `defaultAgentSlug()` on any failure. Call it AFTER the session is ensured.
+ * this fetches the real email once a session exists. Call it AFTER the session
+ * is ensured.
+ *
+ * Default (lenient): falls back to `defaultAgentSlug()` on any failure. With
+ * `strict` (an explicit `--setup` / `mnemom agent setup`) a handle that cannot
+ * be resolved THROWS instead: the gateway identity is hash(credential, name),
+ * so a silent fall-back to "agent-user" would provision and govern a different
+ * agent than the one a prior setup under the real handle created (MNE-7650).
+ */
+export declare function resolveDefaultSlug(opts?: {
+    strict?: boolean;
+}): Promise<string>;
+/**
+ * Thrown when a name-matched agent in the caller's org is NOT the agent the
+ * gateway serves for (credential, name). Both ids are in the message; the
+ * launcher treats it as fatal on an explicit `--setup` (MNE-7650).
  */
-export declare function resolveDefaultSlug(): Promise<string>;
+export declare class AgentIdentityMismatchError extends Error {
+    readonly slug: string;
+    /** The agent the org lookup found by name. */
+    readonly namedId: string;
+    /** The agent the gateway answered with on x-mnemom-agent. */
+    readonly servedId: string;
+    constructor(slug: string, 
+    /** The agent the org lookup found by name. */
+    namedId: string, 
+    /** The agent the gateway answered with on x-mnemom-agent. */
+    servedId: string);
+}
 export interface EnsureAgentOptions {
     /** The already-resolved final agent slug (what rides as x-mnemom-agent). */
     slug: string;
@@ -65,6 +90,12 @@ export interface EnsureAgentResult {
  * setup`) or a warn-and-continue (a bare launch).
  */
 export declare function ensureGovernedAgent(opts: EnsureAgentOptions): Promise<EnsureAgentResult>;
+/**
+ * One line for an api failure that keeps the parts an operator can act on: the
+ * message, the error code, and the scope the endpoint said it needed
+ * (`details.required_scope`). Never the token, never the body.
+ */
+export declare function describeApiError(err: unknown): string;
 /** `mnemom agent setup [--agent <slug>]` — the explicit provisioning entry point. */
 export declare function agentSetupCommand(opts?: {
     agent?: string;

package/dist/commands/agent-setup.js

@@ -51,21 +51,59 @@ export function defaultAgentSlug() {
  * The default slug resolved from the authenticated IDENTITY: `agent-<handle>` from
  * the login email fetched via `/v1/auth/me`. The CLI's stored OAuth token carries
  * no email, so the sync `defaultAgentSlug()` alone falls back to "agent-user";
- * this fetches the real email once a session exists. Falls back to
- * `defaultAgentSlug()` on any failure. Call it AFTER the session is ensured.
+ * this fetches the real email once a session exists. Call it AFTER the session
+ * is ensured.
+ *
+ * Default (lenient): falls back to `defaultAgentSlug()` on any failure. With
+ * `strict` (an explicit `--setup` / `mnemom agent setup`) a handle that cannot
+ * be resolved THROWS instead: the gateway identity is hash(credential, name),
+ * so a silent fall-back to "agent-user" would provision and govern a different
+ * agent than the one a prior setup under the real handle created (MNE-7650).
  */
-export async function resolveDefaultSlug() {
+export async function resolveDefaultSlug(opts = {}) {
+    let reason;
     try {
         const email = (await getMe()).email ?? "";
         const handle = sanitizeAgentName(email.split("@")[0] ?? "");
         if (handle)
             return `agent-${handle}`;
+        reason = email
+            ? `login email '${email}' yields no usable handle`
+            : "no login email on this session";
     }
-    catch {
-        // fall through to the token-based best-effort
+    catch (err) {
+        reason = `/v1/auth/me failed: ${err instanceof Error ? err.message : String(err)}`;
+    }
+    if (opts.strict) {
+        throw new Error(`mnemom agent setup: couldn't derive your agent handle (${reason}) — pass --agent <slug>. ` +
+            "Setup won't silently fall back to 'agent-user': the gateway identity is hash(credential, name), so a different name is a different agent.");
     }
     return defaultAgentSlug();
 }
+/**
+ * Thrown when a name-matched agent in the caller's org is NOT the agent the
+ * gateway serves for (credential, name). Both ids are in the message; the
+ * launcher treats it as fatal on an explicit `--setup` (MNE-7650).
+ */
+export class AgentIdentityMismatchError extends Error {
+    slug;
+    namedId;
+    servedId;
+    constructor(slug, 
+    /** The agent the org lookup found by name. */
+    namedId, 
+    /** The agent the gateway answered with on x-mnemom-agent. */
+    servedId) {
+        super(`mnemom agent setup: '${slug}' in your org is ${namedId}, but the gateway serves ${servedId} for this Anthropic key + name. ` +
+            "Refusing to govern the wrong agent. The gateway identity is hash(credential, name): a different key, " +
+            "or a prior setup under another slug, is a different agent. " +
+            `Either claim the served one (mnemom agent claim ${servedId} --key <the same key>) or launch with the --agent and key you set up.`);
+        this.slug = slug;
+        this.namedId = namedId;
+        this.servedId = servedId;
+        this.name = "AgentIdentityMismatchError";
+    }
+}
 /**
  * Ensure `slug` is a usable governed agent in the customer's org. Returns
  * {provisioned:false} when it is already usable, when provisioning is not
@@ -87,7 +125,18 @@ export async function ensureGovernedAgent(opts) {
             // already-claimed agent (e.g. a protection card that failed on a prior run
             // before we minted its one-time grant). A bare launch leaves it alone.
             if (opts.setup === true) {
-                say(fmt.dim(`mnemom agent: '${slug}' is already claimed — refreshing its cards.`));
+                // MNE-7650: the name is client-controlled and the API exposes no
+                // agent_hash, so a name match proves nothing about which agent the
+                // gateway will serve for (key, slug) — it looks agents up by
+                // hash(credential, name) only. Ask the gateway: the same 16-token
+                // "hello" the birth path uses answers with the served mnm- id on
+                // x-mnemom-agent. Govern that agent or none.
+                const gatewayUrl = opts.gatewayHost.replace(/\/+$/, "");
+                const served = await birthThroughGateway(gatewayUrl, "anthropic", slug, opts.anthropicKey);
+                if (served !== existing.id) {
+                    throw new AgentIdentityMismatchError(slug, existing.id, served);
+                }
+                say(fmt.dim(`mnemom agent: '${slug}' is already claimed (${existing.id}, the agent the gateway serves) — refreshing its cards.`));
                 await publishDefaultCards(existing.id);
                 persistAgentSlug(slug);
                 return { slug, provisioned: true };
@@ -140,6 +189,25 @@ export async function ensureGovernedAgent(opts) {
     return { slug, provisioned: true };
 }
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * One line for an api failure that keeps the parts an operator can act on: the
+ * message, the error code, and the scope the endpoint said it needed
+ * (`details.required_scope`). Never the token, never the body.
+ */
+export function describeApiError(err) {
+    if (!(err instanceof MnemomApiError))
+        return err instanceof Error ? err.message : String(err);
+    const bits = [];
+    if (err.code)
+        bits.push(`code ${err.code}`);
+    const details = err.details;
+    const scope = details && typeof details === "object" && "required_scope" in details
+        ? details.required_scope
+        : undefined;
+    if (typeof scope === "string" && scope)
+        bits.push(`requires ${scope}`);
+    return bits.length ? `${err.message} (${bits.join(", ")})` : err.message;
+}
 /**
  * Write one card with a brief retry to absorb the org-membership propagation that
  * can transiently 401/403/409 a write right after a claim (the same window
@@ -172,12 +240,18 @@ async function publishDefaultCards(agentId) {
     // it with our human login JWT — the "Provision and claim?" confirm is the
     // explicit human approval, and the mint endpoint accepts a human operator (only
     // agent OAuth principals are rejected). The next write consumes the grant. A
-    // mint failure falls through to the write's retry + graceful degrade.
+    // mint failure falls through to the write's retry + graceful degrade, but it
+    // is NAMED: the mint's error code (e.g. an ownership `agent_org_forbidden`)
+    // and `details.required_scope` are the actionable diagnosis — the downstream
+    // protection-write denial alone points at the wrong remedy (MNE-7650).
     try {
         await mintProtectionCapability(agentId);
     }
-    catch {
-        // best effort — the protection write below surfaces the real, actionable error
+    catch (err) {
+        say(fmt.warn(`mnemom agent: couldn't mint the protection grant for ${agentId} — ${describeApiError(err)}`));
+        if (err instanceof MnemomApiError && err.code === "agent_org_forbidden") {
+            say(fmt.dim("  That agent is owned by an org other than your active one — `mnemom org use <org>` to switch, or set up under a different --agent."));
+        }
     }
     const prot = await tryPublishCard("protection", () => putProtectionCard(agentId, JSON.stringify(buildCodeProtectionCard(agentId)), "application/json"));
     if (align.ok && prot.ok) {
@@ -209,10 +283,11 @@ export async function agentSetupCommand(opts = {}) {
         throw err;
     }
     const anthropicKey = await resolveAnthropicKey(process.env, { allowPrompt: true });
-    // Session exists now, so derive the real handle from /v1/auth/me (not "agent-user").
+    // Session exists now, so derive the real handle from /v1/auth/me. Strict: an
+    // explicit setup never silently provisions "agent-user" (MNE-7650).
     const slug = opts.agent?.trim()
         ? sanitizeAgentName(opts.agent.trim())
-        : await resolveDefaultSlug();
+        : await resolveDefaultSlug({ strict: true });
     if (!slug)
         throw new Error("mnemom agent setup: agent slug sanitised to empty — pass --agent <slug>.");
     const result = await ensureGovernedAgent({ slug, anthropicKey, setup: true, gatewayHost });

package/dist/commands/agent.js

@@ -38,7 +38,7 @@ import { configKeySpec, loadLauncherConfig, writeLauncherConfig } from "../lib/l
 import { fmt } from "../lib/format.js";
 import { askInput, askYesNo, isInteractive } from "../lib/prompt.js";
 import { goalAlignmentLine, resolveSessionSetup } from "./agent-session.js";
-import { defaultAgentSlug, ensureGovernedAgent, ensureSessionAndBalance, isQuietPreambleExit, resolveDefaultSlug, resolvePreflightedAccount, } from "./agent-setup.js";
+import { AgentIdentityMismatchError, defaultAgentSlug, ensureGovernedAgent, ensureSessionAndBalance, isQuietPreambleExit, resolveDefaultSlug, resolvePreflightedAccount, } from "./agent-setup.js";
 import { assembleContract, buildGoalModeHeader, buildCustomHeaders, buildHandoffMcpConfigJson, buildSessionConfigB64, resolveContextFold, resolveContextHandoff, resolveHandoffGatewayHost, HANDOFF_RC_KEY_ENV_NAME, isProdGateway, launchPreferenceExplicit, launchPreflighted, remoteControlAllowed, resolveAnthropicDoor, resolveConversationId, resolveGatewayHost, resolveLaunchShape, resolveRemoteControlShape, passthroughName, sanitizeAgentName, sessionDisplayName, SESSION_NAME_ENV, } from "../lib/agent.js";
 import { LAUNCHER_STORE_PATH, mergeStore } from "../lib/launcher-store.js";
 import { slackChannelArgs } from "../lib/slack-launch.js";
@@ -215,9 +215,12 @@ export async function agentCommand(scenarioArg, options = {}) {
     });
     // Now that a session exists, a defaulted slug uses the real login handle from
     // /v1/auth/me (the stored token has no email, so the pre-sign-in value was the
-    // "agent-user" fallback). Only when the caller didn't name an agent.
+    // "agent-user" fallback). Only when the caller didn't name an agent. Under an
+    // explicit --setup the lookup is strict and a missing handle aborts the launch:
+    // provisioning "agent-user" would govern a different gateway identity than the
+    // one a prior setup under the real handle created (MNE-7650).
     if (!options.agent?.trim()) {
-        const refreshed = sanitizeAgentName(await resolveDefaultSlug());
+        const refreshed = sanitizeAgentName(await resolveDefaultSlug({ strict: options.setup === true }));
         if (refreshed)
             agent = refreshed;
     }
@@ -236,6 +239,11 @@ export async function agentCommand(scenarioArg, options = {}) {
             });
         }
         catch (err) {
+            // An identity mismatch is the one setup failure that must NOT degrade: the
+            // launch would run as an agent other than the one --setup just tried to
+            // govern. Refuse, with both ids in the message (MNE-7650).
+            if (err instanceof AgentIdentityMismatchError)
+                throw err;
             const msg = err instanceof Error ? err.message : String(err);
             say(fmt.warn(`mnemom agent: agent setup did not complete (${msg}) — launching with the unclaimed identity.`));
         }

package/dist/commands/config.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `mnemom config list|get|set|unset` — CLI-wide preferences in
+ * ~/.mnemom/config.json. Today: the auto-update keys. (Launcher settings for
+ * `mnemom agent` stay in `mnemom agent config` / launcher.toml.)
+ *
+ * Keys are data (CONFIG_KEYS) so list/get/set/unset share one source of truth.
+ */
+import { type UpdatePrefs } from "../lib/update/decide.js";
+import { setUpdatePref } from "../lib/cli-config.js";
+export interface CliConfigKey {
+    key: string;
+    describe: string;
+    env: string;
+    /** Stored value (undefined when unset). */
+    stored(prefs: UpdatePrefs): string | undefined;
+    /** Value in effect after env + default. */
+    effective(prefs: UpdatePrefs, env: Record<string, string | undefined>): string;
+    /** Validate + persist; throws with a user-facing message on a bad value. */
+    set(raw: string, persist: typeof setUpdatePref): void;
+    unset(persist: typeof setUpdatePref): void;
+}
+export declare const CONFIG_KEYS: readonly CliConfigKey[];
+export declare function findKey(key: string): CliConfigKey;
+export interface ConfigDeps {
+    prefs(): UpdatePrefs;
+    env: Record<string, string | undefined>;
+    persist: typeof setUpdatePref;
+    log(line: string): void;
+}
+/** One line per key: `key = effective  (source)  — description`. */
+export declare function configListCommand(opts?: {
+    json?: boolean;
+}, deps?: ConfigDeps): void;
+export declare function configGetCommand(key: string, deps?: ConfigDeps): void;
+export declare function configSetCommand(key: string, value: string, deps?: ConfigDeps): void;
+export declare function configUnsetCommand(key: string, deps?: ConfigDeps): void;

package/dist/commands/config.js

@@ -0,0 +1,82 @@
+/**
+ * `mnemom config list|get|set|unset` — CLI-wide preferences in
+ * ~/.mnemom/config.json. Today: the auto-update keys. (Launcher settings for
+ * `mnemom agent` stay in `mnemom agent config` / launcher.toml.)
+ *
+ * Keys are data (CONFIG_KEYS) so list/get/set/unset share one source of truth.
+ */
+import { isUpdateChannel, isUpdateMode, resolveChannel, resolveMode, UPDATE_CHANNELS, UPDATE_MODES, } from "../lib/update/decide.js";
+import { loadCliConfig, setUpdatePref } from "../lib/cli-config.js";
+export const CONFIG_KEYS = [
+    {
+        key: "update.channel",
+        describe: `Release channel for auto-update: ${UPDATE_CHANNELS.join(" | ")} (next requires an invite)`,
+        env: "MNEMOM_UPDATE_CHANNEL",
+        stored: (p) => p.channel,
+        effective: (p, env) => resolveChannel(p, env),
+        set: (raw, persist) => {
+            const v = raw.trim();
+            if (!isUpdateChannel(v))
+                throw new Error(`update.channel must be one of ${UPDATE_CHANNELS.join(", ")} (got '${raw}').`);
+            persist("channel", v);
+        },
+        unset: (persist) => persist("channel", undefined),
+    },
+    {
+        key: "update.mode",
+        describe: `Auto-update behaviour: ${UPDATE_MODES.join(" | ")}`,
+        env: "MNEMOM_UPDATE_MODE",
+        stored: (p) => p.mode,
+        effective: (p, env) => resolveMode(p, env),
+        set: (raw, persist) => {
+            const v = raw.trim();
+            if (!isUpdateMode(v))
+                throw new Error(`update.mode must be one of ${UPDATE_MODES.join(", ")} (got '${raw}').`);
+            persist("mode", v);
+        },
+        unset: (persist) => persist("mode", undefined),
+    },
+];
+export function findKey(key) {
+    const spec = CONFIG_KEYS.find((k) => k.key === key);
+    if (!spec)
+        throw new Error(`Unknown config key '${key}'. Known keys: ${CONFIG_KEYS.map((k) => k.key).join(", ")}`);
+    return spec;
+}
+function defaultDeps() {
+    return {
+        prefs: () => loadCliConfig().update ?? {},
+        env: process.env,
+        persist: setUpdatePref,
+        log: (line) => console.log(line),
+    };
+}
+/** One line per key: `key = effective  (source)  — description`. */
+export function configListCommand(opts = {}, deps = defaultDeps()) {
+    const prefs = deps.prefs();
+    const rows = CONFIG_KEYS.map((k) => {
+        const stored = k.stored(prefs);
+        const source = deps.env[k.env] ? `env ${k.env}` : stored !== undefined ? "config" : "default";
+        return { key: k.key, value: k.effective(prefs, deps.env), source, describe: k.describe };
+    });
+    if (opts.json) {
+        deps.log(JSON.stringify(rows, null, 2));
+        return;
+    }
+    for (const r of rows)
+        deps.log(`${r.key} = ${r.value}  (${r.source})  — ${r.describe}`);
+}
+export function configGetCommand(key, deps = defaultDeps()) {
+    deps.log(findKey(key).effective(deps.prefs(), deps.env));
+}
+export function configSetCommand(key, value, deps = defaultDeps()) {
+    const spec = findKey(key);
+    spec.set(value, deps.persist);
+    deps.log(`${key} = ${value.trim()}`);
+    if (deps.env[spec.env])
+        deps.log(`note: ${spec.env} is set in your environment and overrides this.`);
+}
+export function configUnsetCommand(key, deps = defaultDeps()) {
+    findKey(key).unset(deps.persist);
+    deps.log(`${key} reset to default`);
+}

package/dist/commands/update.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `mnemom update [--check] [--channel latest|next] [--force] [--json]`
+ *
+ * The foreground twin of the background worker: same `runUpdate` pass, but it
+ * reports what happened and ignores the CI / non-TTY auto-off (an explicit
+ * command is consent). `--check` never installs; `--force` permits a downgrade
+ * to the channel's version (e.g. leaving next for latest).
+ */
+import { type ResolvedSettings } from "../lib/update/decide.js";
+import { type RunDeps, type RunResult } from "../lib/update/run.js";
+export declare const NEXT_NOT_ENTITLED_HINT: string;
+export interface UpdateOptions {
+    check?: boolean;
+    channel?: string;
+    force?: boolean;
+    json?: boolean;
+}
+/** Validate flags → the settings for this foreground pass, or an error message. */
+export declare function foregroundSettings(opts: UpdateOptions, prefs?: import("../lib/update/decide.js").UpdatePrefs, env?: Record<string, string | undefined>): ResolvedSettings | string;
+/** Human-readable report of one pass. Pure, for testing. */
+export declare function formatUpdateResult(result: RunResult, current: string): string[];
+/** Exit status: non-zero only when something actually failed. */
+export declare function updateExitCode(result: RunResult): number;
+export declare function updateCommand(opts: UpdateOptions, deps?: {
+    settings?: ResolvedSettings | string;
+    acquire?: () => (() => void) | null;
+    runDeps?: RunDeps;
+    log?: (line: string) => void;
+    setExit?: (code: number) => void;
+}): Promise<void>;

package/dist/commands/update.js

@@ -0,0 +1,90 @@
+/**
+ * `mnemom update [--check] [--channel latest|next] [--force] [--json]`
+ *
+ * The foreground twin of the background worker: same `runUpdate` pass, but it
+ * reports what happened and ignores the CI / non-TTY auto-off (an explicit
+ * command is consent). `--check` never installs; `--force` permits a downgrade
+ * to the channel's version (e.g. leaving next for latest).
+ */
+import chalk from "chalk";
+import { CLI_VERSION } from "../version.js";
+import { canSelfUpdate, isUpdateChannel, manualUpgradeCommand, resolveChannel, UPDATE_CHANNELS, } from "../lib/update/decide.js";
+import { runUpdate } from "../lib/update/run.js";
+import { acquireLock } from "../lib/update/state.js";
+import { entryRealpath, foregroundCredential, loadUpdatePrefs } from "../lib/update/system.js";
+import { realRunDeps } from "../lib/update/worker.js";
+export const NEXT_NOT_ENTITLED_HINT = "The next channel is available to invited accounts. Ask your Mnemom contact for an invite " +
+    "(and make sure you're logged in: mnemom login). Using latest for now.";
+/** Validate flags → the settings for this foreground pass, or an error message. */
+export function foregroundSettings(opts, prefs = loadUpdatePrefs(), env = process.env) {
+    if (opts.channel !== undefined && !isUpdateChannel(opts.channel)) {
+        return `--channel must be one of ${UPDATE_CHANNELS.join(", ")} (got '${opts.channel}').`;
+    }
+    const channel = resolveChannel(prefs, env, opts.channel);
+    return { channel, mode: opts.check ? "notify" : "auto" };
+}
+/** Human-readable report of one pass. Pure, for testing. */
+export function formatUpdateResult(result, current) {
+    const lines = [];
+    if (result.channelDowngraded)
+        lines.push(chalk.yellow(NEXT_NOT_ENTITLED_HINT));
+    const action = result.action;
+    if (!action) {
+        lines.push(chalk.red(`✖ Could not check for updates: ${result.error ?? "unknown error"}`));
+        return lines;
+    }
+    const manual = (v) => manualUpgradeCommand(result.method ?? "unknown", v);
+    if (result.installed) {
+        lines.push(chalk.green(`✓ Updated mnemom ${current} → ${result.installed} (${result.channel})`));
+    }
+    else if (action.kind === "install") {
+        // An install action that didn't produce `installed` failed.
+        lines.push(chalk.red(`✖ Update to ${action.version} failed: ${result.error ?? "unknown error"}`));
+        lines.push(`  Try manually: ${manual(action.version)}`);
+    }
+    else if (action.kind === "notify") {
+        lines.push(`mnemom ${action.version} is available on ${result.channel} (you have ${current}).`);
+        lines.push(`  Run: ${canSelfUpdate(result.method ?? "unknown") ? "mnemom update" : manual(action.version)}`);
+    }
+    else {
+        lines.push(`mnemom ${current}: ${action.reason} (${result.channel}).`);
+    }
+    return lines;
+}
+/** Exit status: non-zero only when something actually failed. */
+export function updateExitCode(result) {
+    return result.error ? 1 : 0;
+}
+export async function updateCommand(opts, deps = {}) {
+    const log = deps.log ?? ((line) => console.log(line));
+    const setExit = deps.setExit ?? ((code) => void (process.exitCode = code));
+    const settings = deps.settings ?? foregroundSettings(opts);
+    if (typeof settings === "string") {
+        log(chalk.red(settings));
+        setExit(2);
+        return;
+    }
+    const release = (deps.acquire ?? (() => acquireLock()))();
+    if (!release) {
+        log("Another mnemom update is already running — try again in a minute.");
+        setExit(1);
+        return;
+    }
+    try {
+        if (!opts.check && !opts.json)
+            log(`Checking the ${settings.channel} channel…`);
+        const runDeps = deps.runDeps ?? realRunDeps(entryRealpath(process.argv[1]), () => foregroundCredential());
+        const result = await runUpdate(runDeps, settings, { force: opts.force, foreground: true });
+        if (opts.json) {
+            log(JSON.stringify({ current: CLI_VERSION, requested_channel: settings.channel, ...result }, null, 2));
+        }
+        else {
+            for (const line of formatUpdateResult(result, runDeps.current))
+                log(line);
+        }
+        setExit(updateExitCode(result));
+    }
+    finally {
+        release();
+    }
+}

package/dist/index.js

@@ -34,6 +34,10 @@ import { wrapCommand } from "./commands/wrap.js";
 import { onboardCommand } from "./commands/onboard.js";
 import { skillsListCommand, skillsDescribeCommand } from "./commands/skills.js";
 import { usageCommand, parseNumericFlag, parseDaysFlag } from "./commands/usage.js";
+import { updateCommand } from "./commands/update.js";
+import { runAction } from "./lib/update/action.js";
+import { configListCommand, configGetCommand, configSetCommand, configUnsetCommand, } from "./commands/config.js";
+import { defaultStartupDeps, maybeRunUpdateHook } from "./lib/update/startup.js";
 program
     .name("mnemom")
     .description("Transparent AI agent tracing")
@@ -1876,6 +1880,42 @@ program
         process.exit(1);
     }
 });
+// ============================================================================
+// update + config — CLI auto-update (channel latest|next, mode auto|notify|off)
+//
+// A detached worker (lib/update/startup.ts → update-worker.ts) checks npm at
+// most daily (6h on next) and installs in the background; the new version takes
+// effect on the next run. `mnemom update` is the foreground twin. Preferences
+// live in ~/.mnemom/config.json via `mnemom config`.
+// ============================================================================
+program
+    .command("update")
+    .description("Check for and install a newer mnemom CLI (auto-update runs this in the background)")
+    .option("--check", "Only report whether an update is available; never install")
+    .option("--channel <channel>", "Channel for this run: latest | next (default: update.channel)")
+    .option("--force", "Allow installing an OLDER version (e.g. moving from next back to latest)")
+    .option("--json", "Output JSON")
+    .action((options) => runAction(() => updateCommand(options)));
+const configCmd = program
+    .command("config")
+    .description("CLI-wide preferences in ~/.mnemom/config.json (auto-update channel and mode)");
+configCmd
+    .command("list")
+    .description("Show every setting, its effective value, and where it came from")
+    .option("--json", "Output JSON")
+    .action((options) => runAction(() => configListCommand(options)));
+configCmd
+    .command("get <key>")
+    .description("Print a setting's effective value (e.g. update.channel)")
+    .action((key) => runAction(() => configGetCommand(key)));
+configCmd
+    .command("set <key> <value>")
+    .description("Set a preference, e.g. `mnemom config set update.channel next`")
+    .action((key, value) => runAction(() => configSetCommand(key, value)));
+configCmd
+    .command("unset <key>")
+    .description("Reset a preference to its default")
+    .action((key) => runAction(() => configUnsetCommand(key)));
 // Export the fully-assembled commander program so tooling (e.g. the
 // command-tree snapshot generator in scripts/gen-command-tree.mjs) can
 // statically introspect the command surface WITHOUT executing the CLI.
@@ -1897,6 +1937,7 @@ export function runEntrypoint(argv = process.argv.slice(2)) {
         });
     }
     else {
+        maybeRunUpdateHook(defaultStartupDeps(argv));
         program.parse();
     }
 }

package/dist/lib/agent.d.ts

@@ -24,15 +24,17 @@ export declare const PROD_GATEWAY_HOST = "https://gateway.mnemom.ai";
 /**
  * The sealed-contract shape sent as `x-mnemom-contract` and re-parsed by the
  * gateway's goal-contract hook (gateway/src/goal-contract.ts `SealedContract`).
- * Empty arrays / empty `goal_id` are omitted, and the guardrail ceilings are
- * plain finite numbers.
+ * The three list fields are ALWAYS present (empty when no flag was given) —
+ * that is the shape the gateway's `parseContractHeader` materialises before it
+ * hashes, so the sha we print is the sha it seals (MNE-7649). An empty
+ * `goal_id` is omitted, and the guardrail ceilings are plain finite numbers.
  */
 export interface SealedContract {
     goal_id?: string;
     statement: string;
-    requirements?: string[];
-    allowed_paths?: string[];
-    forbidden_paths?: string[];
+    requirements: string[];
+    allowed_paths: string[];
+    forbidden_paths: string[];
     /** Guardrail ceilings — positive finite numbers, sealed into the contract hash. */
     max_turns?: number;
     budget_usd?: number;
@@ -140,8 +142,12 @@ export interface SealedContractEnvelope {
  *   - a guardrail ceiling that is not strictly positive (`parseContractHeader`
  *     drops those, so a "guarded" launch would actually be unguarded).
  *
- * The canonical form OMITS empty arrays and an empty goal_id, so the sha printed
- * here matches whatever the gateway seals for the same flags.
+ * The canonical form always carries `requirements`, `allowed_paths` and
+ * `forbidden_paths` (empty arrays when unset) and omits an empty goal_id —
+ * exactly what the gateway's `parseContractHeader` normalises to before
+ * `canonicalHash`, so the sha printed here is the `x-mnemom-contract-hash` it
+ * returns. (Omitting the empty arrays made every `--goal`-only launch print a
+ * sha the gateway never sealed: MNE-7649.)
  */
 export declare function assembleContract(flags: ContractFlags): SealedContractEnvelope | null;
 /** The request header that opts a conversation into implicit goal mode. */

package/dist/lib/agent.js

@@ -159,8 +159,12 @@ function hasText(v) {
  *   - a guardrail ceiling that is not strictly positive (`parseContractHeader`
  *     drops those, so a "guarded" launch would actually be unguarded).
  *
- * The canonical form OMITS empty arrays and an empty goal_id, so the sha printed
- * here matches whatever the gateway seals for the same flags.
+ * The canonical form always carries `requirements`, `allowed_paths` and
+ * `forbidden_paths` (empty arrays when unset) and omits an empty goal_id —
+ * exactly what the gateway's `parseContractHeader` normalises to before
+ * `canonicalHash`, so the sha printed here is the `x-mnemom-contract-hash` it
+ * returns. (Omitting the empty arrays made every `--goal`-only launch print a
+ * sha the gateway never sealed: MNE-7649.)
  */
 export function assembleContract(flags) {
     // Implicit goal mode seals nothing: the ceilings ride on the mode header
@@ -176,16 +180,12 @@ export function assembleContract(flags) {
         throw new Error("--goal is required when any contract flag " +
             "(--requirement/--allow/--forbid/--goal-id/--budget/--max-turns/--stall) is given.");
     }
-    const contract = { statement };
-    const requirements = cleanList(flags.requirement);
-    if (requirements.length)
-        contract.requirements = requirements;
-    const allowed = cleanList(flags.allow);
-    if (allowed.length)
-        contract.allowed_paths = allowed;
-    const forbidden = cleanList(flags.forbid);
-    if (forbidden.length)
-        contract.forbidden_paths = forbidden;
+    const contract = {
+        statement,
+        requirements: cleanList(flags.requirement),
+        allowed_paths: cleanList(flags.allow),
+        forbidden_paths: cleanList(flags.forbid),
+    };
     const goalId = (flags.goalId ?? "").trim();
     if (goalId)
         contract.goal_id = goalId;