@arcforge/err 2.0.120 → 2.0.121

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@arcforge/err",
-    "version": "2.0.120",
+    "version": "2.0.121",
     "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.121"
     },
     "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",
@@ -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) ────────────
@@ -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",

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)))
     }