@mnemom/mnemom 0.17.2-next.6 → 0.17.2-next.8

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-slack.d.ts

@@ -7,6 +7,7 @@
  *   mnemom agent slack logout                # remove them
  *   mnemom agent slack status                # tokens, bot identity, router, live sessions
  *   mnemom agent slack post [--channel C] [--thread TS] [--icon-emoji E] <text…|->
+ *   mnemom agent slack delete [--channel C] <ts>   # delete a message THIS session posted
  *   mnemom agent slack inbox [--peek]        # unread messages addressed to THIS session
  *   mnemom agent slack listen                # this session's channel server (spawned by --slack)
  *   mnemom agent slack router                # the per-operator Socket Mode router (foreground)

package/dist/commands/agent-slack.js

@@ -7,6 +7,7 @@
  *   mnemom agent slack logout                # remove them
  *   mnemom agent slack status                # tokens, bot identity, router, live sessions
  *   mnemom agent slack post [--channel C] [--thread TS] [--icon-emoji E] <text…|->
+ *   mnemom agent slack delete [--channel C] <ts>   # delete a message THIS session posted
  *   mnemom agent slack inbox [--peek]        # unread messages addressed to THIS session
  *   mnemom agent slack listen                # this session's channel server (spawned by --slack)
  *   mnemom agent slack router                # the per-operator Socket Mode router (foreground)
@@ -20,10 +21,10 @@ import { configKeySpec, loadLauncherConfig, writeLauncherConfig } from "../lib/l
 import { runChannelServer } from "../lib/slack-channel.js";
 import { mergeStore, readStore } from "../lib/launcher-store.js";
 import { askInput, isInteractive } from "../lib/prompt.js";
-import { explainSlackError, looksLikeAppToken, looksLikeBotToken, postMessage, resolveSlackToken, sessionPosterName, slackAppManifest, slackCall, SLACK_APP_TOKEN_STORE_KEY, SLACK_TOKEN_STORE_KEY, } from "../lib/slack.js";
+import { explainSlackError, looksLikeAppToken, looksLikeBotToken, deleteMessage, postMessage, resolveSlackToken, sessionPosterName, slackAppManifest, slackCall, SLACK_APP_TOKEN_STORE_KEY, SLACK_TOKEN_STORE_KEY, } from "../lib/slack.js";
 import { routerStatus, runRouter } from "../lib/slack-router.js";
 import { normSession } from "../lib/slack-route.js";
-import { liveSessions, readInboxFrom, recordPost, slackDir } from "../lib/slack-state.js";
+import { findOwnPost, liveSessions, readInboxFrom, recordPost, slackDir, } from "../lib/slack-state.js";
 const out = (line = "") => console.log(line);
 /** Entry point for `mnemom agent slack <verb> [args...]`. Throws on misuse. */
 export async function agentSlackCommand(argv) {
@@ -45,6 +46,8 @@ export async function agentSlackCommand(argv) {
             return status();
         case "post":
             return post(rest);
+        case "delete":
+            return del(rest);
         case "inbox":
             return inbox(rest);
         case "router":
@@ -52,7 +55,7 @@ export async function agentSlackCommand(argv) {
         case "listen":
             return listen();
         default:
-            throw new Error(`mnemom agent slack: unknown verb '${verb}'. Use manifest | login | logout | status | post | inbox | listen | router.`);
+            throw new Error(`mnemom agent slack: unknown verb '${verb}'. Use manifest | login | logout | status | post | delete | inbox | listen | router.`);
     }
 }
 function defaultAppName() {
@@ -170,6 +173,28 @@ async function post(argv) {
         recordPost({ session, channel: res.channel, ts: res.ts, thread_ts: args.thread });
     out(JSON.stringify({ ok: true, channel: res.channel, ts: res.ts, as: session ?? null }));
 }
+/** Delete a message THIS session posted (ownership from the local post index). */
+async function del(argv) {
+    let channel;
+    let ts;
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === "--channel" || argv[i] === "-c")
+            channel = argv[++i];
+        else
+            ts = argv[i];
+    }
+    if (!ts)
+        throw new Error("mnemom agent slack delete: pass the message ts to delete.");
+    const session = sessionPosterName(process.env);
+    if (!session)
+        throw new Error("mnemom agent slack delete: not inside a `mnemom agent` session.");
+    const own = findOwnPost(session, ts, channel);
+    if (!own) {
+        throw new Error(`mnemom agent slack delete: ts=${ts} is not a message ${session} posted.`);
+    }
+    await deleteMessage({ token: botToken(), channel: own.channel, ts: own.ts });
+    out(JSON.stringify({ ok: true, deleted: own.ts, channel: own.channel }));
+}
 // ── inbox (pull) ─────────────────────────────────────────────────────────────
 // Normalised like the inbox file name, so a session name can never escape offsets/.
 const offsetFile = (session) => join(slackDir(), "offsets", `${normSession(session)}.off`);
@@ -208,5 +233,9 @@ async function listen() {
     const session = sessionPosterName(process.env);
     if (!session)
         throw new Error("mnemom agent slack listen: not inside a `mnemom agent` session.");
-    await runChannelServer({ session, botToken: botToken() });
+    await runChannelServer({
+        session,
+        botToken: botToken(),
+        allow: loadLauncherConfig().slackAllow ?? [],
+    });
 }

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();
+    }
+}