@cruxy/cli 0.16.0 → 0.18.0

package/dist/config/schema.d.ts

@@ -182,7 +182,7 @@ export declare const IndexConfigSchema: z.ZodObject<{
     };
     enabled: boolean;
     embedder: "fastembed";
-    store: "auto" | "sqlite" | "memory";
+    store: "memory" | "auto" | "sqlite";
     maxFileBytes: number;
     chunk: {
         windowLines: number;
@@ -196,7 +196,7 @@ export declare const IndexConfigSchema: z.ZodObject<{
     } | undefined;
     enabled?: boolean | undefined;
     embedder?: "fastembed" | undefined;
-    store?: "auto" | "sqlite" | "memory" | undefined;
+    store?: "memory" | "auto" | "sqlite" | undefined;
     maxFileBytes?: number | undefined;
     chunk?: {
         windowLines?: number | undefined;
@@ -320,18 +320,18 @@ export declare const SandboxConfigSchema: z.ZodObject<{
      */
     mounts: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
 }, "strict", z.ZodTypeAny, {
+    memory: string;
     image: string;
     enabled: boolean;
-    memory: string;
     network: "none" | "host-loopback" | "full";
     pids: number;
     cpus: number;
     mounts: string[];
     timeout?: number | undefined;
 }, {
+    memory?: string | undefined;
     image?: string | undefined;
     enabled?: boolean | undefined;
-    memory?: string | undefined;
     network?: "none" | "host-loopback" | "full" | undefined;
     pids?: number | undefined;
     cpus?: number | undefined;
@@ -365,6 +365,49 @@ export declare const HooksConfigSchema: z.ZodObject<{
     trustPrompt?: boolean | undefined;
 }>;
 export type HooksConfig = z.infer<typeof HooksConfigSchema>;
+/**
+ * Multi-model routing (C.30): map declared task classes to tiers so mechanical
+ * work runs on a cheap tier and hard reasoning on a strong one. Fully opt-in —
+ * with an empty `map` and no `default`, every task class routes to the session's
+ * single tier and behavior is unchanged (routing stays inert until configured).
+ * Only tier names appear here; upstream model names never do (U.8). Keys are the
+ * fixed {@link TASK_CLASSES}, so a mistyped class is rejected at config load.
+ */
+export declare const RoutingConfigSchema: z.ZodObject<{
+    /** Tier for any task class not in `map`. Unset → the tier implied by
+     * `model.model` (a real tier, or the auto-fallback tier). */
+    default: z.ZodOptional<z.ZodEnum<["kavi", "vaani", "mira"]>>;
+    /** Per-task-class tier overrides; anything omitted takes `default`. */
+    map: z.ZodDefault<z.ZodRecord<z.ZodEnum<["main-turn", "subagent", "plan", "commit-msg", "classify", "summarize"]>, z.ZodEnum<["kavi", "vaani", "mira"]>>>;
+}, "strict", z.ZodTypeAny, {
+    map: Partial<Record<"main-turn" | "subagent" | "plan" | "commit-msg" | "classify" | "summarize", "kavi" | "vaani" | "mira">>;
+    default?: "kavi" | "vaani" | "mira" | undefined;
+}, {
+    map?: Partial<Record<"main-turn" | "subagent" | "plan" | "commit-msg" | "classify" | "summarize", "kavi" | "vaani" | "mira">> | undefined;
+    default?: "kavi" | "vaani" | "mira" | undefined;
+}>;
+/**
+ * Persistent memory (C.29): structured notes recalled across sessions. ON by
+ * default and safe to be so — user memory is self-authored (nothing you didn't
+ * write is injected) and project memory still requires an explicit
+ * `cruxy memory trust`, so a cloned repo never auto-injects. Recall is bounded
+ * by a token budget; the `remember` tool refuses to persist secrets.
+ */
+export declare const MemoryConfigSchema: z.ZodObject<{
+    /** Master switch. When false, nothing is recalled and the `remember` tool
+     * is not registered (memory stays fully inert). */
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    /** Token budget for the recalled block injected at session start; entries
+     * beyond it are pruned oldest-first (the omission is stated, never silent). */
+    maxRecallTokens: z.ZodDefault<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    enabled: boolean;
+    maxRecallTokens: number;
+}, {
+    enabled?: boolean | undefined;
+    maxRecallTokens?: number | undefined;
+}>;
+export type MemoryConfig = z.infer<typeof MemoryConfigSchema>;
 /** MCP server entry — stdio or URL transport (wired up in a later phase). */
 export declare const McpServerSchema: z.ZodObject<{
     command: z.ZodOptional<z.ZodString>;
@@ -546,7 +589,7 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         };
         enabled: boolean;
         embedder: "fastembed";
-        store: "auto" | "sqlite" | "memory";
+        store: "memory" | "auto" | "sqlite";
         maxFileBytes: number;
         chunk: {
             windowLines: number;
@@ -560,7 +603,7 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         } | undefined;
         enabled?: boolean | undefined;
         embedder?: "fastembed" | undefined;
-        store?: "auto" | "sqlite" | "memory" | undefined;
+        store?: "memory" | "auto" | "sqlite" | undefined;
         maxFileBytes?: number | undefined;
         chunk?: {
             windowLines?: number | undefined;
@@ -662,18 +705,18 @@ export declare const CruxyConfigSchema: z.ZodObject<{
          */
         mounts: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
     }, "strict", z.ZodTypeAny, {
+        memory: string;
         image: string;
         enabled: boolean;
-        memory: string;
         network: "none" | "host-loopback" | "full";
         pids: number;
         cpus: number;
         mounts: string[];
         timeout?: number | undefined;
     }, {
+        memory?: string | undefined;
         image?: string | undefined;
         enabled?: boolean | undefined;
-        memory?: string | undefined;
         network?: "none" | "host-loopback" | "full" | undefined;
         pids?: number | undefined;
         cpus?: number | undefined;
@@ -697,6 +740,33 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         enabled?: boolean | undefined;
         trustPrompt?: boolean | undefined;
     }>>;
+    routing: z.ZodDefault<z.ZodObject<{
+        /** Tier for any task class not in `map`. Unset → the tier implied by
+         * `model.model` (a real tier, or the auto-fallback tier). */
+        default: z.ZodOptional<z.ZodEnum<["kavi", "vaani", "mira"]>>;
+        /** Per-task-class tier overrides; anything omitted takes `default`. */
+        map: z.ZodDefault<z.ZodRecord<z.ZodEnum<["main-turn", "subagent", "plan", "commit-msg", "classify", "summarize"]>, z.ZodEnum<["kavi", "vaani", "mira"]>>>;
+    }, "strict", z.ZodTypeAny, {
+        map: Partial<Record<"main-turn" | "subagent" | "plan" | "commit-msg" | "classify" | "summarize", "kavi" | "vaani" | "mira">>;
+        default?: "kavi" | "vaani" | "mira" | undefined;
+    }, {
+        map?: Partial<Record<"main-turn" | "subagent" | "plan" | "commit-msg" | "classify" | "summarize", "kavi" | "vaani" | "mira">> | undefined;
+        default?: "kavi" | "vaani" | "mira" | undefined;
+    }>>;
+    memory: z.ZodDefault<z.ZodObject<{
+        /** Master switch. When false, nothing is recalled and the `remember` tool
+         * is not registered (memory stays fully inert). */
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        /** Token budget for the recalled block injected at session start; entries
+         * beyond it are pruned oldest-first (the omission is stated, never silent). */
+        maxRecallTokens: z.ZodDefault<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        enabled: boolean;
+        maxRecallTokens: number;
+    }, {
+        enabled?: boolean | undefined;
+        maxRecallTokens?: number | undefined;
+    }>>;
     mcpServers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
         command: z.ZodOptional<z.ZodString>;
         args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
@@ -715,14 +785,18 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     cruxy: {
         gatewayUrl: string;
     };
+    memory: {
+        enabled: boolean;
+        maxRecallTokens: number;
+    };
     checkpoint: {
         enabled: boolean;
         retention: number;
     };
     sandbox: {
+        memory: string;
         image: string;
         enabled: boolean;
-        memory: string;
         network: "none" | "host-loopback" | "full";
         pids: number;
         cpus: number;
@@ -732,6 +806,14 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     approval: {
         mode: "prompt";
     };
+    subagent: {
+        maxDepth: number;
+        defaultBudget: {
+            maxTokens: number;
+            maxIterations: number;
+            timeoutMs?: number | undefined;
+        };
+    };
     model: {
         provider: "cruxy" | "anthropic" | "openai" | "custom";
         model: string;
@@ -770,21 +852,13 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         };
         enabled: boolean;
         embedder: "fastembed";
-        store: "auto" | "sqlite" | "memory";
+        store: "memory" | "auto" | "sqlite";
         maxFileBytes: number;
         chunk: {
             windowLines: number;
             overlapLines: number;
         };
     };
-    subagent: {
-        maxDepth: number;
-        defaultBudget: {
-            maxTokens: number;
-            maxIterations: number;
-            timeoutMs?: number | undefined;
-        };
-    };
     test: {
         maxIterations: number;
         captureBytes: number;
@@ -794,6 +868,10 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         enabled: boolean;
         trustPrompt: boolean;
     };
+    routing: {
+        map: Partial<Record<"main-turn" | "subagent" | "plan" | "commit-msg" | "classify" | "summarize", "kavi" | "vaani" | "mira">>;
+        default?: "kavi" | "vaani" | "mira" | undefined;
+    };
     mcpServers: Record<string, {
         command?: string | undefined;
         args?: string[] | undefined;
@@ -804,14 +882,18 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     cruxy?: {
         gatewayUrl?: string | undefined;
     } | undefined;
+    memory?: {
+        enabled?: boolean | undefined;
+        maxRecallTokens?: number | undefined;
+    } | undefined;
     checkpoint?: {
         enabled?: boolean | undefined;
         retention?: number | undefined;
     } | undefined;
     sandbox?: {
+        memory?: string | undefined;
         image?: string | undefined;
         enabled?: boolean | undefined;
-        memory?: string | undefined;
         network?: "none" | "host-loopback" | "full" | undefined;
         pids?: number | undefined;
         cpus?: number | undefined;
@@ -821,6 +903,14 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     approval?: {
         mode?: "prompt" | undefined;
     } | undefined;
+    subagent?: {
+        maxDepth?: number | undefined;
+        defaultBudget?: {
+            maxTokens?: number | undefined;
+            maxIterations?: number | undefined;
+            timeoutMs?: number | undefined;
+        } | undefined;
+    } | undefined;
     model?: {
         provider?: "cruxy" | "anthropic" | "openai" | "custom" | undefined;
         model?: string | undefined;
@@ -859,21 +949,13 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         } | undefined;
         enabled?: boolean | undefined;
         embedder?: "fastembed" | undefined;
-        store?: "auto" | "sqlite" | "memory" | undefined;
+        store?: "memory" | "auto" | "sqlite" | undefined;
         maxFileBytes?: number | undefined;
         chunk?: {
             windowLines?: number | undefined;
             overlapLines?: number | undefined;
         } | undefined;
     } | undefined;
-    subagent?: {
-        maxDepth?: number | undefined;
-        defaultBudget?: {
-            maxTokens?: number | undefined;
-            maxIterations?: number | undefined;
-            timeoutMs?: number | undefined;
-        } | undefined;
-    } | undefined;
     test?: {
         maxIterations?: number | undefined;
         command?: string | undefined;
@@ -883,6 +965,10 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         enabled?: boolean | undefined;
         trustPrompt?: boolean | undefined;
     } | undefined;
+    routing?: {
+        map?: Partial<Record<"main-turn" | "subagent" | "plan" | "commit-msg" | "classify" | "summarize", "kavi" | "vaani" | "mira">> | undefined;
+        default?: "kavi" | "vaani" | "mira" | undefined;
+    } | undefined;
     mcpServers?: Record<string, {
         command?: string | undefined;
         args?: string[] | undefined;

package/dist/config/schema.js

@@ -1,5 +1,7 @@
 import { z } from "zod";
 import { LOG_LEVELS } from "../utils/logger.js";
+import { MODEL_TIERS } from "../brand/voice.js";
+import { TASK_CLASSES } from "../routing/types.js";
 export const ProviderSchema = z.enum([
     "cruxy",
     "anthropic",
@@ -254,6 +256,40 @@ export const HooksConfigSchema = z
     trustPrompt: z.boolean().default(true),
 })
     .strict();
+/**
+ * Multi-model routing (C.30): map declared task classes to tiers so mechanical
+ * work runs on a cheap tier and hard reasoning on a strong one. Fully opt-in —
+ * with an empty `map` and no `default`, every task class routes to the session's
+ * single tier and behavior is unchanged (routing stays inert until configured).
+ * Only tier names appear here; upstream model names never do (U.8). Keys are the
+ * fixed {@link TASK_CLASSES}, so a mistyped class is rejected at config load.
+ */
+export const RoutingConfigSchema = z
+    .object({
+    /** Tier for any task class not in `map`. Unset → the tier implied by
+     * `model.model` (a real tier, or the auto-fallback tier). */
+    default: z.enum(MODEL_TIERS).optional(),
+    /** Per-task-class tier overrides; anything omitted takes `default`. */
+    map: z.record(z.enum(TASK_CLASSES), z.enum(MODEL_TIERS)).default({}),
+})
+    .strict();
+/**
+ * Persistent memory (C.29): structured notes recalled across sessions. ON by
+ * default and safe to be so — user memory is self-authored (nothing you didn't
+ * write is injected) and project memory still requires an explicit
+ * `cruxy memory trust`, so a cloned repo never auto-injects. Recall is bounded
+ * by a token budget; the `remember` tool refuses to persist secrets.
+ */
+export const MemoryConfigSchema = z
+    .object({
+    /** Master switch. When false, nothing is recalled and the `remember` tool
+     * is not registered (memory stays fully inert). */
+    enabled: z.boolean().default(true),
+    /** Token budget for the recalled block injected at session start; entries
+     * beyond it are pruned oldest-first (the omission is stated, never silent). */
+    maxRecallTokens: z.number().int().positive().default(1000),
+})
+    .strict();
 /** MCP server entry — stdio or URL transport (wired up in a later phase). */
 export const McpServerSchema = z
     .object({
@@ -278,6 +314,8 @@ export const CruxyConfigSchema = z
     test: TestConfigSchema.default({}),
     sandbox: SandboxConfigSchema.default({}),
     hooks: HooksConfigSchema.default({}),
+    routing: RoutingConfigSchema.default({}),
+    memory: MemoryConfigSchema.default({}),
     mcpServers: z.record(z.string(), McpServerSchema).default({}),
     logLevel: z.enum(LOG_LEVELS).default("info"),
 })

package/dist/constants.d.ts

@@ -30,6 +30,17 @@ export declare const COMMANDS_DIR_NAME = "commands";
 /** Per-repo hook-trust record, in the GLOBAL dir only (`~/.cruxy/trust.json`) —
  * never in a repo, so cloning carries no trust (C.19 supply-chain safety). */
 export declare const TRUST_FILE_NAME = "trust.json";
+/**
+ * Persistent memory (C.29). Structured entries live under the memory subdir of
+ * the project dir (`<cwd>/.cruxy/memory`) and the global dir (`~/.cruxy/memory`),
+ * one JSON file per scope — pure data, validated, never eval'd.
+ */
+export declare const MEMORY_DIR_NAME = "memory";
+export declare const MEMORY_FILE_NAME = "entries.json";
+/** Per-repo PROJECT-memory trust record, in the GLOBAL dir only
+ * (`~/.cruxy/memory-trust.json`) — its own file, independent of hook trust, so
+ * cloning a repo carries zero memory trust (C.29 supply-chain safety). */
+export declare const MEMORY_TRUST_FILE_NAME = "memory-trust.json";
 /**
  * Absolute path of the shipped builtin skills directory (`<pkg>/skills`).
  * Anchored the same way as the package.json lookup above: both `dist/` and

package/dist/constants.js

@@ -50,6 +50,17 @@ export const COMMANDS_DIR_NAME = "commands";
 /** Per-repo hook-trust record, in the GLOBAL dir only (`~/.cruxy/trust.json`) —
  * never in a repo, so cloning carries no trust (C.19 supply-chain safety). */
 export const TRUST_FILE_NAME = "trust.json";
+/**
+ * Persistent memory (C.29). Structured entries live under the memory subdir of
+ * the project dir (`<cwd>/.cruxy/memory`) and the global dir (`~/.cruxy/memory`),
+ * one JSON file per scope — pure data, validated, never eval'd.
+ */
+export const MEMORY_DIR_NAME = "memory";
+export const MEMORY_FILE_NAME = "entries.json";
+/** Per-repo PROJECT-memory trust record, in the GLOBAL dir only
+ * (`~/.cruxy/memory-trust.json`) — its own file, independent of hook trust, so
+ * cloning a repo carries zero memory trust (C.29 supply-chain safety). */
+export const MEMORY_TRUST_FILE_NAME = "memory-trust.json";
 /**
  * Absolute path of the shipped builtin skills directory (`<pkg>/skills`).
  * Anchored the same way as the package.json lookup above: both `dist/` and

package/dist/errors/constructors.d.ts

@@ -11,6 +11,15 @@ export declare function usageError(title: string, nextSteps?: string[]): CruxyEr
 export declare function interactiveRequired(what: string, alternatives?: string[]): CruxyError;
 export declare function configKeyUnknown(key: string): CruxyError;
 export declare function providerUnsupported(provider: string): CruxyError;
+/**
+ * A task class is routed (C.30) to a tier the gateway does not offer. A usage
+ * error the user fixes in config — cruxy fails loud here rather than silently
+ * substituting a different tier (which would hand a user a model they never
+ * asked for). Distinct from runtime unavailability (overload/budget), which
+ * stays on the U.5 api codes. Params are tier/class NAMES only — never an
+ * upstream model id — so the message is gag-safe by construction (U.8).
+ */
+export declare function routingTierUnavailable(tier: string, taskClass: string, offered: string[]): CruxyError;
 export declare function configParse(path: string, underlying?: unknown): CruxyError;
 export declare function configInvalid(issues: string, path?: string): CruxyError;
 export declare function authMissingKey(provider: string, envVar: string): CruxyError;
@@ -127,6 +136,20 @@ export declare function subagentFailed(underlying?: unknown): CruxyError;
  * invents a test command — the fix is always to declare one.
  */
 export declare function testCommandNotFound(): CruxyError;
+/**
+ * A memory write was refused because the content matched a known secret shape
+ * (C.29). Secrets are NEVER persisted to memory — the fix is to remember a
+ * non-secret description, not the secret itself.
+ */
+export declare function memorySecretRefused(kind: string): CruxyError;
+/**
+ * A repo's project memory is present but has not been trusted on this machine
+ * (C.29). It is never recalled into the model's context silently — a cloned repo
+ * cannot inject notes until you review and trust them.
+ */
+export declare function memoryUntrusted(root: string): CruxyError;
+/** A malformed memory entry was rejected (C.29) — excluded, never eval'd. */
+export declare function memoryInvalid(detail: string): CruxyError;
 export declare function internal(underlying?: unknown): CruxyError;
 /**
  * Map a known provider/transport error (from `@cruxy/sdk`) to a typed

package/dist/errors/constructors.js

@@ -1,4 +1,5 @@
 import { ApiError, AuthError, NetworkError, OverloadedError, RateLimitError, } from "@cruxy/sdk";
+import { scrubModelNames } from "../brand/index.js";
 import { CruxyError, ErrorCode } from "./types.js";
 /**
  * Helper constructors for {@link CruxyError}. Each encodes the title, the human
@@ -15,6 +16,18 @@ export function messageOf(underlying) {
         return undefined;
     return String(underlying);
 }
+/**
+ * {@link messageOf}, gag-scrubbed (U.8) for a gateway/provider-originated error.
+ * A gateway error body is an arbitrary EXTERNAL string, so it bypasses the
+ * structural tier gag — this is the boundary that scrubs any upstream model name
+ * out of it before it can reach a user-facing `cause`. Used by the provider-error
+ * constructors below (everything `classifyProviderError` routes through). The raw
+ * message stays on `underlying`, shown verbatim only under `--verbose`.
+ */
+function scrubbedMessageOf(underlying) {
+    const msg = messageOf(underlying);
+    return msg === undefined ? undefined : scrubModelNames(msg);
+}
 // ── usage (exit 2) ────────────────────────────────────────────────────────────
 export function usageError(title, nextSteps) {
     return new CruxyError({
@@ -57,6 +70,28 @@ export function providerUnsupported(provider) {
         meta: { provider },
     });
 }
+/**
+ * A task class is routed (C.30) to a tier the gateway does not offer. A usage
+ * error the user fixes in config — cruxy fails loud here rather than silently
+ * substituting a different tier (which would hand a user a model they never
+ * asked for). Distinct from runtime unavailability (overload/budget), which
+ * stays on the U.5 api codes. Params are tier/class NAMES only — never an
+ * upstream model id — so the message is gag-safe by construction (U.8).
+ */
+export function routingTierUnavailable(tier, taskClass, offered) {
+    return new CruxyError({
+        code: ErrorCode.RoutingTierUnavailable,
+        title: `the "${tier}" tier is not available for the "${taskClass}" task`,
+        cause: `routing maps "${taskClass}" to the "${tier}" tier, which this gateway does not currently offer`,
+        nextSteps: [
+            `route it to an available tier, e.g. \`cruxy config set routing.map.${taskClass} ${offered[0] ?? "vaani"}\``,
+            offered.length
+                ? `available tiers: ${offered.join(", ")}`
+                : "no tiers are currently available",
+        ],
+        meta: { tier, taskClass, offered },
+    });
+}
 // ── config (exit 3) ───────────────────────────────────────────────────────────
 export function configParse(path, underlying) {
     return new CruxyError({
@@ -99,7 +134,7 @@ export function authInvalid(underlying) {
     return new CruxyError({
         code: ErrorCode.AuthInvalid,
         title: "the provider rejected your credentials",
-        cause: messageOf(underlying),
+        cause: scrubbedMessageOf(underlying),
         nextSteps: [
             "verify your API key is correct and active",
             "re-export the key and try again",
@@ -112,7 +147,7 @@ export function gatewayUnreachable(underlying) {
     return new CruxyError({
         code: ErrorCode.GatewayUnreachable,
         title: "could not reach the model gateway",
-        cause: messageOf(underlying),
+        cause: scrubbedMessageOf(underlying),
         nextSteps: [
             "check your internet connection",
             "verify the gateway URL with `cruxy config get cruxy.gatewayUrl`",
@@ -129,7 +164,7 @@ export function apiError(underlying) {
         title: status
             ? `the model provider returned an error (HTTP ${status})`
             : "the model provider returned an error",
-        cause: messageOf(underlying),
+        cause: scrubbedMessageOf(underlying),
         nextSteps: [
             "retry in a moment; if it persists, check the provider's status",
         ],
@@ -142,7 +177,7 @@ export function apiRateLimit(underlying) {
     return new CruxyError({
         code: ErrorCode.ApiRateLimit,
         title: "rate limited by the model provider",
-        cause: messageOf(underlying),
+        cause: scrubbedMessageOf(underlying),
         nextSteps: [
             retryAfterMs
                 ? `wait ~${Math.ceil(retryAfterMs / 1000)}s and retry`
@@ -156,7 +191,7 @@ export function apiOverloaded(underlying) {
     return new CruxyError({
         code: ErrorCode.ApiOverloaded,
         title: "the model provider is overloaded",
-        cause: messageOf(underlying),
+        cause: scrubbedMessageOf(underlying),
         nextSteps: ["retry in a few moments"],
         underlying,
     });
@@ -165,7 +200,7 @@ export function budgetExhausted(underlying) {
     return new CruxyError({
         code: ErrorCode.BudgetExhausted,
         title: "your Cruxy budget is exhausted",
-        cause: messageOf(underlying),
+        cause: scrubbedMessageOf(underlying),
         nextSteps: ["top up or raise your budget, then retry"],
         underlying,
     });
@@ -567,6 +602,51 @@ export function testCommandNotFound() {
         ],
     });
 }
+// ── persistent memory (exit 14) — C.29 ────────────────────────────────────────
+/**
+ * A memory write was refused because the content matched a known secret shape
+ * (C.29). Secrets are NEVER persisted to memory — the fix is to remember a
+ * non-secret description, not the secret itself.
+ */
+export function memorySecretRefused(kind) {
+    return new CruxyError({
+        code: ErrorCode.MemorySecret,
+        title: "refused to save that note — it looks like it contains a secret",
+        cause: `the content matched a ${kind}; secrets are never written to memory`,
+        nextSteps: [
+            "remember a non-secret description instead (e.g. “the deploy key lives in 1Password”, not the key)",
+        ],
+        meta: { kind },
+    });
+}
+/**
+ * A repo's project memory is present but has not been trusted on this machine
+ * (C.29). It is never recalled into the model's context silently — a cloned repo
+ * cannot inject notes until you review and trust them.
+ */
+export function memoryUntrusted(root) {
+    return new CruxyError({
+        code: ErrorCode.MemoryUntrusted,
+        title: "this project's memory has not been trusted",
+        cause: "project memory can arrive with a cloned repo (another author), so it is not recalled until you trust it",
+        nextSteps: [
+            "review the entries with `cruxy memory list`",
+            "then trust them with `cruxy memory trust .` (re-trust is required if they change)",
+        ],
+        meta: { root },
+    });
+}
+/** A malformed memory entry was rejected (C.29) — excluded, never eval'd. */
+export function memoryInvalid(detail) {
+    return new CruxyError({
+        code: ErrorCode.MemoryInvalid,
+        title: "a memory entry is malformed and was excluded",
+        cause: detail,
+        nextSteps: [
+            "inspect the file with `cruxy memory list`, or clear it with `cruxy memory clear`",
+        ],
+    });
+}
 // ── internal (exit 1) ─────────────────────────────────────────────────────────
 export function internal(underlying) {
     return new CruxyError({

package/dist/errors/types.d.ts

@@ -21,6 +21,9 @@ export declare const ErrorCode: {
     readonly PlanInvalid: "CRUXY_E_PLAN_INVALID";
     readonly PlanRevisionLimit: "CRUXY_E_PLAN_REVISION_LIMIT";
     readonly CheckpointNotFound: "CRUXY_E_CHECKPOINT_NOT_FOUND";
+    /** Routing (C.30): a task class is mapped to a tier the gateway does not
+     * offer — fix the config, NEVER a silent substitution to another tier. */
+    readonly RoutingTierUnavailable: "CRUXY_E_ROUTING_TIER_UNAVAILABLE";
     readonly ConfigParse: "CRUXY_E_CONFIG_PARSE";
     readonly ConfigInvalid: "CRUXY_E_CONFIG_INVALID";
     readonly AuthMissingKey: "CRUXY_E_AUTH_MISSING_KEY";
@@ -68,6 +71,15 @@ export declare const ErrorCode: {
     readonly HookInvalid: "CRUXY_E_HOOK_INVALID";
     /** A malformed custom slash-command definition — excluded and surfaced. */
     readonly SlashInvalid: "CRUXY_E_SLASH_INVALID";
+    /** A malformed memory entry — excluded from recall/writes and surfaced,
+     * never eval'd. */
+    readonly MemoryInvalid: "CRUXY_E_MEMORY_INVALID";
+    /** A repo's project memory has not been trusted — it is never recalled into
+     * context silently (supply-chain safety). */
+    readonly MemoryUntrusted: "CRUXY_E_MEMORY_UNTRUSTED";
+    /** A memory write was refused because the content matched a secret shape —
+     * secrets are never persisted (defense in depth over C.17). */
+    readonly MemorySecret: "CRUXY_E_MEMORY_SECRET";
 };
 export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
 /** The process exit code for an error code (defaults to 1 for safety). */

package/dist/errors/types.js

@@ -23,6 +23,9 @@ export const ErrorCode = {
     PlanInvalid: "CRUXY_E_PLAN_INVALID",
     PlanRevisionLimit: "CRUXY_E_PLAN_REVISION_LIMIT",
     CheckpointNotFound: "CRUXY_E_CHECKPOINT_NOT_FOUND",
+    /** Routing (C.30): a task class is mapped to a tier the gateway does not
+     * offer — fix the config, NEVER a silent substitution to another tier. */
+    RoutingTierUnavailable: "CRUXY_E_ROUTING_TIER_UNAVAILABLE",
     // config (exit 3)
     ConfigParse: "CRUXY_E_CONFIG_PARSE",
     ConfigInvalid: "CRUXY_E_CONFIG_INVALID",
@@ -82,6 +85,16 @@ export const ErrorCode = {
     HookInvalid: "CRUXY_E_HOOK_INVALID",
     /** A malformed custom slash-command definition — excluded and surfaced. */
     SlashInvalid: "CRUXY_E_SLASH_INVALID",
+    // persistent memory (exit 14) — C.29
+    /** A malformed memory entry — excluded from recall/writes and surfaced,
+     * never eval'd. */
+    MemoryInvalid: "CRUXY_E_MEMORY_INVALID",
+    /** A repo's project memory has not been trusted — it is never recalled into
+     * context silently (supply-chain safety). */
+    MemoryUntrusted: "CRUXY_E_MEMORY_UNTRUSTED",
+    /** A memory write was refused because the content matched a secret shape —
+     * secrets are never persisted (defense in depth over C.17). */
+    MemorySecret: "CRUXY_E_MEMORY_SECRET",
 };
 /**
  * Category exit codes. Distinct per category so a caller (CI, a script) can
@@ -97,6 +110,7 @@ const EXIT_CODES = {
     [ErrorCode.PlanInvalid]: 2,
     [ErrorCode.PlanRevisionLimit]: 2,
     [ErrorCode.CheckpointNotFound]: 2,
+    [ErrorCode.RoutingTierUnavailable]: 2,
     [ErrorCode.ConfigParse]: 3,
     [ErrorCode.ConfigInvalid]: 3,
     [ErrorCode.AuthMissingKey]: 4,
@@ -142,6 +156,12 @@ const EXIT_CODES = {
     [ErrorCode.HookUntrusted]: 13,
     [ErrorCode.HookInvalid]: 13,
     [ErrorCode.SlashInvalid]: 13,
+    // Persistent memory (C.29). A malformed entry and an untrusted project are
+    // data-safety problems; a refused secret write is a security stop — grouped
+    // for a greppable exit code.
+    [ErrorCode.MemoryInvalid]: 14,
+    [ErrorCode.MemoryUntrusted]: 14,
+    [ErrorCode.MemorySecret]: 14,
 };
 /** The process exit code for an error code (defaults to 1 for safety). */
 export function exitCodeFor(code) {

package/dist/hooks/types.d.ts

@@ -103,8 +103,8 @@ export declare const SlashFrontmatterSchema: z.ZodObject<{
     command?: string | undefined;
 }, {
     description: string;
-    command?: string | undefined;
     kind?: "shell" | "prompt" | undefined;
+    command?: string | undefined;
 }>;
 export type SlashFrontmatter = z.infer<typeof SlashFrontmatterSchema>;
 /** A validated custom slash command, tagged with source. */