@arcforge/err 2.0.120 → 2.0.122

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@arcforge/err",
-    "version": "2.0.120",
+    "version": "2.0.122",
     "description": "Structured Axon errors — the code map every user-facing failure is rendered from.",
     "type": "module",
     "private": false,
@@ -15,7 +15,7 @@
         "deploy": "echo \"This package is published ONLY by apps/tui/scripts/release.ts, which pins workspace:* deps to concrete versions first. Publishing it directly ships an unresolvable dependency.\" && exit 1"
     },
     "dependencies": {
-        "@arcforge/types": "2.0.120"
+        "@arcforge/types": "2.0.122"
     },
     "devDependencies": {
         "@types/bun": "latest",

package/src/err.ts

@@ -1,4 +1,4 @@
-import { errorMap, type AxonErrorCode, type AxonErrorMap } from "./map"
+import { errorMap, type AxonErrorCode, type AxonErrorMap, type AxonErrorMapEntry } from "./map"
 import { captureStack, firstRealFrame } from "./stack"
 import { renderError } from "./render"
 import { emitError } from "./sink"
@@ -56,7 +56,10 @@ export function err(codeOrCause: AxonErrorCode | unknown, opts?: AxonErrorOpts):
     }
 
     const code = codeOrCause as AxonErrorCode
-    const def = (errorMap as AxonErrorMap)[code]
+    // Read through the ENTRY type, not the literal map type: `as const` keeps
+    // each entry's exact shape, so optional fields are absent from the type of
+    // entries that omit them and unreadable off the union.
+    const def: AxonErrorMapEntry = (errorMap as AxonErrorMap)[code]
 
     const e = new Error(opts?.detail ?? def.title, { cause: opts?.cause }) as AxonError
 
@@ -65,6 +68,9 @@ export function err(codeOrCause: AxonErrorCode | unknown, opts?: AxonErrorOpts):
     e.description = def.description
     e.source = def.source
     e.severity = opts?.severity ?? def.severity
+    // Carried onto the instance so renderers (and the CLI's own catch) can ask
+    // whose fault this is without reaching back into the map.
+    if (def.expected) e.expected = true
     e.context = opts?.context
     e.frames = captureStack(2) // drop captureStack's own frame + err()'s
     e.isAxonError = true

package/src/map.ts

@@ -33,6 +33,25 @@ export type AxonErrorMapEntry = {
     description: string
     source: AxonErrorSource
     severity: AxonErrorSeverity
+    /**
+     * Is this a failure the USER caused and can fix, rather than a fault in
+     * our code?
+     *
+     * `axon publish` outside a project directory is a typo, not a bug — the
+     * title and description already say everything actionable, so a renderer
+     * showing eighty lines of our internals underneath is telling the user to
+     * debug software they did not write. Marking it `expected` renders the
+     * headline alone.
+     *
+     * Deliberately NOT `severity`, which answers a different question:
+     * PROJECT_NOT_FOUND is genuinely `fatal` (the command cannot continue) AND
+     * genuinely expected. Recoverability and blame are independent axes.
+     *
+     * Absent means unexpected — the safe default. An unclassified failure gets
+     * the full trace, which is what makes it debuggable; the only cost of
+     * forgetting this flag is a noisier message, never a hidden bug.
+     */
+    expected?: true
 }
 
 /**
@@ -52,6 +71,7 @@ export const errorMap = {
         description: "The requested prompt could not be resolved — it is not declared by the agent, or the published package it names ships no prompt by that name.",
         source: "runtime",
         severity: "fatal",
+        expected: true,
     },
     PROMPT_FILE_NOT_FOUND: {
         code: "AX-PROMPT-002",
@@ -59,6 +79,7 @@ export const errorMap = {
         description: "The prompt is declared but its source file no longer exists on disk.",
         source: "runtime",
         severity: "fatal",
+        expected: true,
     },
     PROMPT_RENDER_FAILED: {
         code: "AX-PROMPT-003",
@@ -87,6 +108,7 @@ export const errorMap = {
         description: "The requested script was not found in the agent's blueprint. It may not be declared, or the agent needs to be re-prepared.",
         source: "runtime",
         severity: "fatal",
+        expected: true,
     },
     SCRIPT_FILE_NOT_FOUND: {
         code: "AX-SCRIPT-002",
@@ -94,6 +116,7 @@ export const errorMap = {
         description: "The script is declared but its source file no longer exists on disk.",
         source: "runtime",
         severity: "fatal",
+        expected: true,
     },
     ENGINE_MISSING: {
         code: "AX-ENGINE-001",
@@ -236,6 +259,7 @@ export const errorMap = {
         description: "The cognet named by `cognet:` in axon.config.ts could not be located. The detail says where it was looked for — a registry that answered 404, or a node_modules tree it was missing from. Check the specifier for a typo, and check which registry the CLI is pointed at (AXON_API_BASE).",
         source: "cognet",
         severity: "fatal",
+        expected: true,
     },
 
     // ── Project (build/project/) ────────────────────────────────────────────
@@ -303,6 +327,7 @@ export const errorMap = {
         description: "The selected model routes through a provider (OpenRouter, Codex) that isn't connected yet — connect it before picking a model on that route.",
         source: "tui",
         severity: "fatal",
+        expected: true,
     },
     PALETTE_INPUT_REQUIRED: {
         code: "AX-TUI-012",
@@ -310,6 +335,7 @@ export const errorMap = {
         description: "A palette command needs a value for this field before it can run.",
         source: "tui",
         severity: "fatal",
+        expected: true,
     },
     BENCH_NO_CASES: {
         code: "AX-TUI-013",
@@ -326,6 +352,7 @@ export const errorMap = {
         description: "No axon.config.ts, module.config.ts, cognet.config.ts, bench.config.ts, or prompt.config.ts was found at this path — it isn't a recognized project directory.",
         source: "manifest",
         severity: "fatal",
+        expected: true,
     },
     PROJECT_WRONG_KIND: {
         code: "AX-PROJECT-011",
@@ -333,6 +360,7 @@ export const errorMap = {
         description: "This command targets one project kind, and the directory holds another — run the command that matches what is actually here.",
         source: "manifest",
         severity: "fatal",
+        expected: true,
     },
     PROJECT_EXISTS: {
         code: "AX-PROJECT-018",
@@ -357,8 +385,8 @@ export const errorMap = {
     },
     PUBLISH_UNSUPPORTED_KIND: {
         code: "AX-PROJECT-009",
-        title: "This Project Kind Cannot Publish Yet",
-        description: "Only agents and modules publish to the registry today. Cognets and benches become first-class registry artifacts in the unified artifact work — until then, publishing one would register it under the wrong kind and claim its name in the shared namespace.",
+        title: "This Project Kind Cannot Publish",
+        description: "The registry accepts agents, modules, cognets, benches and prompts. Extensions are not accepted yet — the `registry_artifact_kind` enum needs the value first, and publishing before then would register under the wrong kind and claim the name in the shared namespace. A profile is never publishable: it holds one person's credentials, history and agents. See KINDS[kind].publishable.",
         source: "manifest",
         severity: "fatal",
     },
@@ -412,14 +440,14 @@ export const errorMap = {
         severity: "fatal",
     },
     DEPLOY_RUNTIME_FAILED: {
-        code: "AX-PROJECT-013",
+        code: "AX-PROJECT-035",
         title: "Agent Failed To Start",
         description: "Cloud infrastructure was provisioned, but the agent process failed during boot. The reported runtime diagnostic identifies the immediate cause.",
         source: "runtime",
         severity: "fatal",
     },
     DEPLOY_ENV_RESERVED: {
-        code: "AX-PROJECT-014",
+        code: "AX-PROJECT-036",
         title: "Reserved Deployment Variable",
         description: "The production .env file attempts to override a variable owned by the Axon runtime or Cloud Run.",
         source: "manifest",
@@ -468,6 +496,7 @@ export const errorMap = {
         description: "No recorded bench run exists with this id.",
         source: "bench",
         severity: "fatal",
+        expected: true,
     },
     BENCH_NOT_FOUND: {
         code: "AX-BENCH-002",
@@ -475,6 +504,7 @@ export const errorMap = {
         description: "No bench.config.ts was found at this path — it isn't a recognized bench project.",
         source: "bench",
         severity: "fatal",
+        expected: true,
     },
     BENCH_TESTS_NOT_FOUND: {
         code: "AX-BENCH-003",
@@ -482,6 +512,7 @@ export const errorMap = {
         description: "The bench config declares test files that don't exist on disk.",
         source: "bench",
         severity: "fatal",
+        expected: true,
     },
     BENCH_LOCAL_REF_NOT_FOUND: {
         code: "AX-BENCH-004",
@@ -489,6 +520,7 @@ export const errorMap = {
         description: "A factor variable references a local file/directory that doesn't exist.",
         source: "bench",
         severity: "fatal",
+        expected: true,
     },
     BENCH_CONFIG_INVALID: {
         code: "AX-BENCH-005",
@@ -503,6 +535,7 @@ export const errorMap = {
         description: "No package.json exists at the bench root — every bench project needs one for identity.",
         source: "bench",
         severity: "fatal",
+        expected: true,
     },
     BENCH_PACKAGE_NAME_REQUIRED: {
         code: "AX-BENCH-007",
@@ -510,6 +543,7 @@ export const errorMap = {
         description: "The bench's package.json has no name field.",
         source: "bench",
         severity: "fatal",
+        expected: true,
     },
     BENCH_PACKAGE_VERSION_REQUIRED: {
         code: "AX-BENCH-008",
@@ -517,6 +551,7 @@ export const errorMap = {
         description: "The bench's package.json has no version field.",
         source: "bench",
         severity: "fatal",
+        expected: true,
     },
     BENCH_CONTEXT_MISSING: {
         code: "AX-BENCH-009",
@@ -636,6 +671,7 @@ export const errorMap = {
         description: "The bench config's matrix has no axis with this key.",
         source: "bench",
         severity: "fatal",
+        expected: true,
     },
     BENCH_AXIS_VALUE_NOT_FOUND: {
         code: "AX-BENCH-022",
@@ -643,6 +679,7 @@ export const errorMap = {
         description: "The bench config's matrix axis has no declared value with this id.",
         source: "bench",
         severity: "fatal",
+        expected: true,
     },
     BENCH_WORKSPACE_ESCAPE: {
         code: "AX-BENCH-023",
@@ -671,6 +708,7 @@ export const errorMap = {
         description: "A workspace template's declared source path isn't a real directory.",
         source: "bench",
         severity: "fatal",
+        expected: true,
     },
     BENCH_LOG_INVALID: {
         code: "AX-BENCH-027",
@@ -736,6 +774,7 @@ export const errorMap = {
         description: "No axon.config.ts exists at this path.",
         source: "manifest",
         severity: "fatal",
+        expected: true,
     },
     CONFIG_LOAD_FAILED: {
         code: "AX-BLUEPRINT-004",
@@ -773,6 +812,7 @@ export const errorMap = {
         description: "This agent uses a Codex model, but your Axon account is not connected to ChatGPT — run :provider codex connect and try again.",
         source: "kernel",
         severity: "fatal",
+        expected: true,
     },
     RUN_IN_PROGRESS: {
         code: "AX-KERNEL-002",
@@ -838,6 +878,7 @@ export const errorMap = {
         description: "The requested thread id isn't registered in this session.",
         source: "thread",
         severity: "fatal",
+        expected: true,
     },
     THREAD_BRANCH_UNKNOWN: {
         code: "AX-SESSION-003",
@@ -873,6 +914,7 @@ export const errorMap = {
         description: "A control-channel call named a method the peer does not expose. The two ends disagree about the surface — usually a TUI and an extension built from different versions.",
         source: "server",
         severity: "fatal",
+        expected: true,
     },
     CONTROL_PATH_NOT_CALLABLE: {
         code: "AX-CONTROL-002",
@@ -1096,6 +1138,7 @@ export const errorMap = {
         description: "The action needs an active profile, but none is logged in yet.",
         source: "tui",
         severity: "fatal",
+        expected: true,
     },
     PROFILE_NOT_AUTHENTICATED: {
         code: "AX-TUI-003",
@@ -1103,6 +1146,15 @@ export const errorMap = {
         description: "The target profile exists but has no stored session — it has never logged in, or its session was cleared.",
         source: "tui",
         severity: "fatal",
+        expected: true,
+    },
+    BACKEND_UNREACHABLE: {
+        code: "AX-TUI-044",
+        title: "Backend Unreachable",
+        description: "A stored credential could not be verified because the backend could not be reached. The credential is NOT discarded — it may be perfectly valid — but it cannot be trusted until it is checked, so the action is refused rather than proceeding unverified.",
+        source: "tui",
+        severity: "fatal",
+        expected: true,
     },
     PROFILE_UNKNOWN: {
         code: "AX-TUI-004",
@@ -1110,6 +1162,7 @@ export const errorMap = {
         description: "The requested profile id isn't one of the profiles stored on this machine.",
         source: "tui",
         severity: "fatal",
+        expected: true,
     },
     SESSION_ALREADY_RUNNING: {
         code: "AX-TUI-005",
@@ -1117,6 +1170,7 @@ export const errorMap = {
         description: "spawn() was asked to resume a session that already has a live instance. Focus the running instance instead of booting a second runtime over the same log.",
         source: "tui",
         severity: "fatal",
+        expected: true,
     },
     SESSION_NOT_RUNNING: {
         code: "AX-TUI-016",
@@ -1124,6 +1178,15 @@ export const errorMap = {
         description: "focus() was pointed at a sessionId with no live instance behind it. Spawn (or resume) it first — focus is pure selection over running instances.",
         source: "tui",
         severity: "fatal",
+        expected: true,
+    },
+    NO_ACTIVE_AGENT: {
+        code: "AX-TUI-045",
+        title: "No Active Agent",
+        description: "The action needs a running agent, but none is active — start one first.",
+        source: "tui",
+        severity: "fatal",
+        expected: true,
     },
     NO_FOCUSED_INSTANCE: {
         code: "AX-TUI-017",
@@ -1131,6 +1194,7 @@ export const errorMap = {
         description: "A module install/uninstall was requested with no running agent instance focused — spawn or focus one first.",
         source: "tui",
         severity: "fatal",
+        expected: true,
     },
     MODEL_IMMUTABLE_DEPLOYED: {
         code: "AX-TUI-006",
@@ -1138,6 +1202,7 @@ export const errorMap = {
         description: "A deployed agent's config lives in the cloud, not on this machine — its model is fixed at deploy time. Change it in the local project and deploy again.",
         source: "tui",
         severity: "fatal",
+        expected: true,
     },
     MODULE_INSTALL_FAILED: {
         code: "AX-TUI-018",
@@ -1215,6 +1280,7 @@ export const errorMap = {
         description: "`axon watch`/`axon unwatch` need a directory argument.",
         source: "tui",
         severity: "fatal",
+        expected: true,
     },
     WATCH_PATH_NOT_FOUND: {
         code: "AX-TUI-022",
@@ -1222,6 +1288,7 @@ export const errorMap = {
         description: "`axon watch` was given a directory that doesn't exist on disk.",
         source: "tui",
         severity: "fatal",
+        expected: true,
     },
     EDITOR_NOT_SET: {
         code: "AX-TUI-023",
@@ -1243,6 +1310,7 @@ export const errorMap = {
         description: "The init palette's \"watch a new directory\" entry needs both a directory path and an agent name, space-separated.",
         source: "tui",
         severity: "fatal",
+        expected: true,
     },
 
     // ── Module boot-time execution (core runs defineModule setup) ────────────
@@ -1268,7 +1336,7 @@ export const errorMap = {
         severity: "fatal",
     },
     MODULE_SETUP_FAILED: {
-        code: "AX-MODULE-003",
+        code: "AX-MODULE-007",
         title: "Module Setup Failed",
         description: "A module's setup() threw during agent boot. Setup runs sequentially in blueprint order and a failure is total — no later module is wired, and the agent does not boot half-configured.",
         source: "runtime",
@@ -1287,6 +1355,7 @@ export const errorMap = {
         description: "A module's setup() called ctx.env.require() for a variable the agent's resolved environment does not provide. The module declares required env in module.config.ts; the agent must supply it (e.g. in .env).",
         source: "runtime",
         severity: "fatal",
+        expected: true,
     },
     MODULE_POLICY_IMMUTABLE: {
         code: "AX-MODULE-006",
@@ -1294,6 +1363,7 @@ export const errorMap = {
         description: "A module's setup() called ctx.policy.update(). The resolved agent policy is authoritative and cannot be mutated at boot — declare policy needs statically in module.config.ts so the CLI reconciles them at install.",
         source: "runtime",
         severity: "fatal",
+        expected: true,
     },
 
     // ── Registry retrieval (build/registry.ts) ──────────────────────────────
@@ -1303,6 +1373,7 @@ export const errorMap = {
         description: "`axon clone` was run without an artifact to clone. Name one, for example: axon clone @axon/arxiv",
         source: "cli",
         severity: "fatal",
+        expected: true,
     },
     FORK_REF_REQUIRED: {
         code: "AX-PROJECT-023",
@@ -1370,7 +1441,7 @@ export const errorMap = {
         severity: "fatal",
     },
     PROMPT_NOT_INSTALLABLE: {
-        code: "AX-PROJECT-032",
+        code: "AX-PROJECT-037",
         title: "Prompts Are Not Installed Into Agents",
         description: "A prompt is content, not a capability: it resolves from the global cache and renders on demand, so every agent can already use it without declaring anything. Installing one into an agent would put content through the code path — an ABI check, a node_modules link, an agent reload — for something that needs none of it.",
         source: "manifest",
@@ -1545,6 +1616,223 @@ export const errorMap = {
         source: "cli",
         severity: "fatal",
     },
+
+    // ── Extensions ──────────────────────────────────────────────────────────
+    //
+    // The TUI config surface: a profile's main.ts and plugins/, and the
+    // extensions it loads. Almost every entry here is `expected` and
+    // `degraded`, and both flags are deliberate.
+    //
+    // EXPECTED, because this is code the USER wrote. A stack trace through our
+    // loader tells someone to debug software they did not write; the file and
+    // the reason are the entire actionable content.
+    //
+    // DEGRADED, because a broken config must never cost someone their
+    // terminal. One bad file disables itself and everything else still loads —
+    // a user whose plugin has a typo needs a working Axon to go fix it in.
+    // The one FATAL entry is PROFILE_CONFIG_INVALID, and only because it is
+    // thrown by the CLI verbs that edit that file, where continuing would mean
+    // writing over a config we could not read.
+
+    PROFILE_CONFIG_INVALID: {
+        code: "AX-EXT-001",
+        title: "profile.config.ts Did Not Call defineProfile()",
+        description: "A profile's config must default-export defineProfile({ ... }). Without it there is no extension list to read, so nothing can be installed, enabled or disabled. The rest of the profile — main.ts and plugins/ — still loads.",
+        source: "tui",
+        severity: "fatal",
+        expected: true,
+    },
+    PROFILE_CONFIG_FAILED: {
+        code: "AX-EXT-002",
+        title: "profile.config.ts Failed to Load",
+        description: "The file threw while being evaluated, so its extension list could not be read and no extensions were loaded. The profile's own main.ts and plugins/ are unaffected — a typo in an extension list must not cost you the config you already had working.",
+        source: "tui",
+        severity: "degraded",
+        expected: true,
+    },
+    EXTENSION_ENTRY_INVALID: {
+        code: "AX-EXT-003",
+        title: "Malformed Extension Entry",
+        description: "An entry in profile.config.ts's `extensions` array is neither a string nor an object with a `source`. Accepted forms are \"@scope/name\" for a registry extension and \"./extensions/name\" for a local one.",
+        source: "tui",
+        severity: "degraded",
+        expected: true,
+    },
+    EXTENSION_NOT_FOUND: {
+        code: "AX-EXT-004",
+        title: "Extension Not Found",
+        description: "An extension listed in profile.config.ts is not on disk. A local path may have moved or been deleted; a registry name may never have been installed. Everything else in the list still loads.",
+        source: "tui",
+        severity: "degraded",
+        expected: true,
+    },
+    EXTENSION_INSTALL_FAILED: {
+        code: "AX-EXT-005",
+        title: "Extension Install Failed",
+        description: "A registry extension could not be fetched or prepared — most often no network, or a name that does not exist in the registry. It is skipped for this session and retried on the next launch.",
+        source: "tui",
+        severity: "degraded",
+        expected: true,
+    },
+    EXTENSION_NOT_AN_EXTENSION: {
+        code: "AX-EXT-006",
+        title: "Not an Extension",
+        description: "The directory has no extension.config.ts, which is the file that marks a directory as an extension. A path pointing at an agent, a module, or an ordinary folder is not loadable as one.",
+        source: "tui",
+        severity: "degraded",
+        expected: true,
+    },
+    EXTENSION_LOAD_FAILED: {
+        code: "AX-EXT-007",
+        title: "Extension Failed to Load",
+        description: "An extension's main.ts threw while it was being loaded, so whatever it had not yet registered is missing. Its commands, keys and palettes are removed and the rest of your config loads normally.",
+        source: "tui",
+        severity: "degraded",
+        expected: true,
+    },
+    PROFILE_MAIN_FAILED: {
+        code: "AX-EXT-008",
+        title: "main.ts Failed to Load",
+        description: "Your profile's main.ts threw while being evaluated. Anything it registered before the error survives; everything after it did not run. Plugins and extensions still load.",
+        source: "tui",
+        severity: "degraded",
+        expected: true,
+    },
+    PLUGIN_FAILED: {
+        code: "AX-EXT-009",
+        title: "Plugin Failed to Load",
+        description: "A file in plugins/ threw while being imported, so its hooks were not registered. Other plugins in the same folder are unaffected — each file is loaded independently.",
+        source: "tui",
+        severity: "degraded",
+        expected: true,
+    },
+    HOOK_FAILED: {
+        code: "AX-EXT-010",
+        title: "Lifecycle Hook Failed",
+        description: "A tui.hook() handler threw while the event it listens for was firing. For a notification hook nothing else is affected; for a gating hook (tui:boot, tui:shutdown) the operation continues anyway rather than leaving the terminal stuck.",
+        source: "tui",
+        severity: "degraded",
+        expected: true,
+    },
+    HOOK_TIMED_OUT: {
+        code: "AX-EXT-011",
+        title: "Hook Blocked Too Long",
+        description: "A gating hook (tui:boot or tui:shutdown) did not finish within its budget, so the TUI continued without waiting. A config must never be able to hang the terminal silently — whatever the handler was doing may not have completed.",
+        source: "tui",
+        severity: "degraded",
+        expected: true,
+    },
+    COMMAND_NOT_FOUND: {
+        code: "AX-EXT-012",
+        title: "No Such Command",
+        description: "commands.run() was given a path that resolves to nothing in the command tree. The path must name a leaf, spelled exactly as it appears in the `:` palette.",
+        source: "tui",
+        severity: "fatal",
+        expected: true,
+    },
+    PALETTE_NOT_FOUND: {
+        code: "AX-EXT-013",
+        title: "No Such Palette",
+        description: "palette.open() was given a name no palette was registered under. Palettes are created with palette.create(name, ...) — a name is only openable once its registration has run.",
+        source: "tui",
+        severity: "fatal",
+        expected: true,
+    },
+    PALETTE_NAME_TAKEN: {
+        code: "AX-EXT-014",
+        title: "Palette Name Already Registered",
+        description: "Two palettes tried to claim the same name. Names are how palette.open() addresses one, so they have to be unique — silently replacing the first would make whichever loaded last win, invisibly.",
+        source: "tui",
+        severity: "degraded",
+        expected: true,
+    },
+    PALETTE_ALREADY_OPEN: {
+        code: "AX-EXT-015",
+        title: "A Palette Is Already Open",
+        description: "Something tried to open a palette, or ask a question, while the user was already navigating one. Stealing it mid-navigation would drop whatever they were doing, so the call fails instead — check palette.isOpen first.",
+        source: "tui",
+        severity: "degraded",
+        expected: true,
+    },
+    KEY_CHORD_UNBOUND: {
+        code: "AX-EXT-022",
+        title: "No Such Key Binding",
+        description: "keys.send() was given a chord nothing is bound to — neither a mode key nor a registered binding. Sending it would do nothing at all, which is indistinguishable from a binding that ran and had no effect.",
+        source: "tui",
+        severity: "fatal",
+        expected: true,
+    },
+    AGENT_SPAWN_NO_INSTANCE: {
+        code: "AX-EXT-023",
+        title: "Agent Started but No Instance Appeared",
+        description: "A spawn reported success without producing a focused instance, so there is no id to hand back. This is a fault in Axon rather than in your config — the agent may or may not be running.",
+        source: "tui",
+        severity: "fatal",
+    },
+    PROFILE_CONFIG_MISSING: {
+        code: "AX-EXT-025",
+        title: "No profile.config.ts",
+        description: "The profile has no config file to record the extension in. It is normally created on first launch — starting Axon once will scaffold it.",
+        source: "tui",
+        severity: "fatal",
+        expected: true,
+    },
+    PROFILE_CONFIG_UNEDITABLE: {
+        code: "AX-EXT-026",
+        title: "profile.config.ts Could Not Be Edited",
+        description: "The `extensions` array could not be located, or editing it would have produced invalid TypeScript. Nothing was written — this file is yours, and a botched edit costs your whole TUI config. Add or remove the entry by hand.",
+        source: "tui",
+        severity: "fatal",
+        expected: true,
+    },
+    COMMAND_PATH_TAKEN: {
+        code: "AX-EXT-020",
+        title: "Command Already Registered",
+        description: "Two sources registered the same command path. The first one loaded keeps it — your own config beats any extension, and between extensions the one listed earlier in profile.config.ts wins. Rename one of them.",
+        source: "tui",
+        severity: "degraded",
+        expected: true,
+    },
+    KEY_CHORD_TAKEN: {
+        code: "AX-EXT-021",
+        title: "Key Chord Already Bound",
+        description: "Two sources bound the same key chord. The first one loaded keeps it. A silently shadowed binding is unbearable to debug in someone else's config, so the second registration fails instead of replacing it.",
+        source: "tui",
+        severity: "degraded",
+        expected: true,
+    },
+    MODE_KEY_TAKEN: {
+        code: "AX-EXT-016",
+        title: "Mode Key Already Bound",
+        description: "A palette asked for a mode key that is already in use — either by a built-in mode or by another extension. A silently shadowed key is unbearable to debug in someone else's config, so the registration fails loudly instead.",
+        source: "tui",
+        severity: "degraded",
+        expected: true,
+    },
+    MODE_UNKNOWN: {
+        code: "AX-EXT-017",
+        title: "No Such Mode",
+        description: "mode.set() was given a name that is neither a built-in mode nor a registered palette. Doing nothing would look identical to a mode that simply does not render, so this fails instead.",
+        source: "tui",
+        severity: "fatal",
+        expected: true,
+    },
+    NO_FOCUSED_AGENT: {
+        code: "AX-EXT-018",
+        title: "No Agent Focused",
+        description: "A verb that acts on the focused agent — send, stop, reboot — was called while nothing was running. Start one with agents.spawn(name) or tui.nav(name) first.",
+        source: "tui",
+        severity: "fatal",
+        expected: true,
+    },
+    INSTANCE_NOT_RUNNING: {
+        code: "AX-EXT-019",
+        title: "Instance Not Running",
+        description: "An instance id was given for a conversation that is not live — it may already have been stopped, or it belongs to an earlier session. agents.list() returns what is currently running.",
+        source: "tui",
+        severity: "fatal",
+        expected: true,
+    },
 } as const satisfies Record<string, AxonErrorMapEntry>
 
 export type AxonErrorMap = typeof errorMap

package/src/render.ts

@@ -20,6 +20,8 @@ export type AxonErrorLike = {
     context: Record<string, unknown> | undefined
     frames: AxonStackFrame[]
     cause?: unknown
+    /** The user caused this and can fix it — renders without our internals. See map.ts. */
+    expected?: boolean
 }
 
 /** One frame, Rust-style: file:line:col, then its captured source context with a caret. */
@@ -37,7 +39,23 @@ export function renderFrame(frame: AxonStackFrame): string {
 
 const RULE_WIDTH = 80
 
-/** The full renderable report: headline + description, a rule, then every frame and the cause chain. Blank line before and after the whole block. */
+/**
+ * The renderable report.
+ *
+ * Two shapes, chosen by whose fault the failure is:
+ *
+ *   EXPECTED   headline + description + context. `axon publish` outside a
+ *              project is a typo; the description already says exactly what
+ *              to do, and eighty lines of our call stack underneath tells the
+ *              user to debug software they did not write.
+ *
+ *   otherwise  the full report — frames, source snippets, cause chain. An
+ *              unclassified failure IS ours, and this is what makes it
+ *              debuggable from a pasted terminal log.
+ *
+ * The default is the full report (see map.ts's `expected`), so forgetting to
+ * classify a code costs a noisy message and never a hidden bug.
+ */
 export function renderError(error: AxonErrorLike): string {
     const lines = [`Axon Error: ${error.title}`, error.description]
 
@@ -49,8 +67,17 @@ export function renderError(error: AxonErrorLike): string {
         lines.push("", "Context:", indent(renderContext(error.context)))
     }
 
-    lines.push("─".repeat(RULE_WIDTH), ...error.frames.map(renderFrame))
+    // OUR frames are what an expected failure omits — they describe code the
+    // user did not write and cannot act on.
+    if (!error.expected) {
+        lines.push("─".repeat(RULE_WIDTH), ...error.frames.map(renderFrame))
+    }
 
+    // A cause survives either way: something deliberately attached it, and it
+    // names the underlying fault ("ECONNREFUSED" under a missing file), which
+    // is the most actionable line in the whole report. Suppressing it would
+    // leave the user reading "the file is missing" with no hint that the real
+    // problem was the network.
     if (error.cause !== undefined) {
         lines.push("", "Caused by:", indent(causeMessage(error.cause)))
     }