@cruxy/cli 1.4.0 → 1.6.0

package/dist/hooks/config.js

@@ -1,5 +1,6 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
+import { isReservedSlash } from "../cli/command-catalog.js";
 import { globalDir } from "../config/paths.js";
 import { COMMANDS_DIR_NAME, GLOBAL_DIR_NAME, HOOKS_FILE_NAME, } from "../constants.js";
 import { defaultBlocking, HOOK_SOURCE_PRECEDENCE, HookSpecSchema, SlashFrontmatterSchema, } from "./types.js";
@@ -143,6 +144,23 @@ async function scanCommandsDir(source, dir, out, errors) {
             });
             continue;
         }
+        // A reserved name is refused HERE, at load, and excluded from the catalog
+        // (P10 track 0). Both halves matter. Loading it and letting it lose the
+        // race later is what shipped before: `commands/status.md` parsed, appeared
+        // in `cruxy hooks list` and in the palette, and could not run, because the
+        // shells dispatch `/status` themselves several branches before the custom
+        // catalogue is consulted. Nothing said so at load and nothing said so at
+        // use. Keeping it in the catalog with a warning would fix half of that and
+        // leave the palette advertising a command that does nothing.
+        if (isReservedSlash(name)) {
+            errors.push({
+                source,
+                file,
+                name,
+                message: `"/${name}" is a built-in command and cannot be overridden — rename this file`,
+            });
+            continue;
+        }
         let text;
         try {
             text = await fs.readFile(file, "utf8");

package/dist/hooks/index.js

@@ -2,6 +2,6 @@ export { HOOK_EVENTS, HOOK_SOURCE_PRECEDENCE, HookSpecSchema, HooksFileSchema, S
 export { defaultHookSources, loadHookCatalog, } from "./config.js";
 export { fileTrustStore, fingerprintHooks, isTrusted, memoryTrustStore, trustPath, } from "./trust.js";
 export { HookRunner, } from "./runner.js";
-export { BUILTIN_SLASH_COMMANDS, expandTemplate, isBuiltinSlash, resolveSlash, } from "./slash.js";
+export { expandTemplate, resolveSlash } from "./slash.js";
 export { buildHooksService, } from "./service.js";
 export { buildHooksRouter, } from "./router.js";

package/dist/hooks/router.js

@@ -79,7 +79,7 @@ export async function buildHooksRouter(opts) {
     for (const root of opts.workspace.roots()) {
         const catalog = await loadCatalog(root);
         for (const err of catalog.errors) {
-            opts.logger.warn(`ignoring malformed ${err.source} hook/command "${err.name}" in ${root.name}: ${err.message}`);
+            opts.logger.warn(`ignoring ${err.source} hook/command "${err.name}" in ${root.name}: ${err.message}`);
         }
         // Each root's runner owns ONLY its project hooks. User hooks are global —
         // loaded once (from the primary, whose `sources.user` is identical for every

package/dist/hooks/service.js

@@ -5,15 +5,15 @@ import { defaultHookSources, loadHookCatalog, } from "./config.js";
 import { HookRunner } from "./runner.js";
 import { fileTrustStore } from "./trust.js";
 /**
- * Load the catalog and assemble the {@link HooksService}. Malformed definitions
- * are surfaced (never eval'd, never silently dropped) through the logger; the
- * valid ones proceed.
+ * Load the catalog and assemble the {@link HooksService}. Rejected definitions
+ * — malformed, or a command name the shells reserve — are surfaced (never
+ * eval'd, never silently dropped) through the logger; the valid ones proceed.
  */
 export async function buildHooksService(opts) {
     const sources = opts.sources ?? defaultHookSources(opts.cwd);
     const catalog = await loadHookCatalog(sources);
     for (const err of catalog.errors) {
-        opts.logger.warn(`ignoring malformed ${err.source} hook/command "${err.name}": ${err.message}`);
+        opts.logger.warn(`ignoring ${err.source} hook/command "${err.name}": ${err.message}`);
     }
     const trust = opts.trust ?? fileTrustStore();
     const runner = new HookRunner({

package/dist/hooks/slash.js

@@ -1,29 +1,13 @@
+import { isReservedSlash } from "../cli/command-catalog.js";
 /**
- * Custom slash-command resolution (C.19). Builtins are reserved and always win —
- * a custom command can never shadow `/help`, `/exit`, etc. A resolved custom
- * command is either a `prompt` (expanded to safe text fed to the agent) or a
- * `shell` binding (executed through the SAME gate + sandbox as everything else,
- * by the caller). Nothing here executes anything; it only resolves + expands.
- */
-/** The builtin slash commands (C.13) — reserved, not overridable. */
-export const BUILTIN_SLASH_COMMANDS = [
-    "help",
-    "clear",
-    "compact",
-    "reload",
-    "plan",
-    "exit",
-    "quit",
-];
-const BUILTINS = new Set(BUILTIN_SLASH_COMMANDS);
-/** Is `name` (no leading slash) a reserved builtin? */
-export function isBuiltinSlash(name) {
-    return BUILTINS.has(name);
-}
-/**
- * Resolve one input line. Non-slash input and unknown names → `none`. Builtins
- * short-circuit to `builtin` BEFORE the custom catalog is consulted, so a custom
- * command named after a builtin is inert (surfaced separately at load time).
+ * Resolve one input line. Non-slash input and unknown names → `none`. Reserved
+ * names short-circuit to `builtin` BEFORE the custom catalog is consulted.
+ *
+ * This is now belt-and-braces rather than the only guard: the loader refuses a
+ * command file whose name is reserved, so the colliding spec should never reach
+ * this catalogue at all. It stays because a caller may assemble a spec list by
+ * some other route, and the failure mode this prevents — a project-authored
+ * `shell` command answering to `/clear` — is not one to leave to a single check.
  */
 export function resolveSlash(line, commands) {
     const trimmed = line.trim();
@@ -34,7 +18,7 @@ export function resolveSlash(line, commands) {
     const args = space === -1 ? "" : trimmed.slice(space + 1).trim();
     if (name === "")
         return { kind: "none" };
-    if (isBuiltinSlash(name))
+    if (isReservedSlash(name))
         return { kind: "builtin", name };
     const spec = commands.find((c) => c.name === name);
     if (!spec)

package/dist/limits/cache.js

@@ -0,0 +1,100 @@
+import { reduceLimits } from "./reduce.js";
+/**
+ * How long a probe's answer is treated as current. The pool moves when the user
+ * spends, and the surfaces that spend it (this CLI, web chat, desktop) do so in
+ * turns — so a per-turn refresh is the natural cadence and this floor exists
+ * only to coalesce the several triggers a single turn can produce.
+ */
+const MIN_INTERVAL_MS = 15_000;
+export class LimitsCache {
+    probe;
+    now;
+    minIntervalMs;
+    state;
+    /** The refresh in flight, so concurrent triggers share one request. */
+    inFlight = null;
+    lastAttemptAt = 0;
+    constructor(
+    /**
+     * Absent when there is no credential to ask with. That is not a failure to
+     * report later — it is knowable now, costs no request to determine, and the
+     * panel's answer ("sign in") is the same either way.
+     */
+    probe, opts = {}) {
+        this.probe = probe;
+        this.now = opts.now ?? Date.now;
+        this.minIntervalMs = opts.minIntervalMs ?? MIN_INTERVAL_MS;
+        this.state = probe
+            ? { status: "pending" }
+            : { status: "error", reason: "unauthenticated" };
+    }
+    /** The last settled state — a field read, safe from the paint path. */
+    current() {
+        return this.state;
+    }
+    /** True once a reading has been obtained, whatever has happened since. */
+    hasReading() {
+        return this.state.status === "ready";
+    }
+    /**
+     * Re-read the limits, off the paint path. Coalesces concurrent callers onto
+     * one request and declines to re-probe within {@link minIntervalMs} of the
+     * last attempt.
+     *
+     * Never rejects: a refresh is a background probe for a status panel, and a
+     * caller that has to `.catch` a status update will eventually forget to.
+     */
+    async refresh() {
+        if (!this.probe)
+            return;
+        if (this.inFlight)
+            return this.inFlight;
+        const at = this.now();
+        // The floor applies only once something is on screen. Before the first
+        // answer there is nothing to protect, and rate-limiting our way to a blank
+        // panel would be the floor working against its own purpose.
+        if (this.state.status === "ready" &&
+            at - this.lastAttemptAt < this.minIntervalMs) {
+            return;
+        }
+        this.lastAttemptAt = at;
+        this.inFlight = this.run(this.probe);
+        try {
+            await this.inFlight;
+        }
+        finally {
+            this.inFlight = null;
+        }
+    }
+    async run(probe) {
+        try {
+            const res = await probe();
+            this.state = { status: "ready", reading: reduceLimits(res, this.now()) };
+        }
+        catch (err) {
+            // Keep a good reading rather than blanking a panel that was correct a
+            // moment ago; only report an error when there is nothing else to say.
+            if (this.state.status === "ready")
+                return;
+            this.state = { status: "error", reason: classify(err) };
+        }
+    }
+}
+/**
+ * Why the probe failed, in the three distinctions a user can act on.
+ *
+ * Matched on the SDK's error class names rather than `instanceof`, so this stays
+ * a pure classification with no import of the transport into a module the TUI
+ * loads. A 404/501 is the interesting case: it means a gateway that does not
+ * serve `/limits` at all — an older deployment, or a base URL pointed somewhere
+ * else entirely — and telling that user "you are offline" would send them
+ * debugging a network that is working fine.
+ */
+function classify(err) {
+    const e = err;
+    if (e?.name === "AuthError")
+        return "unauthenticated";
+    if (e?.status === 404 || e?.status === 501)
+        return "unsupported";
+    return "unreachable";
+}

package/dist/limits/index.js

@@ -0,0 +1,11 @@
+/**
+ * Limits (P9): the gateway's own account of what this credential may spend, and
+ * how much of it is left.
+ *
+ * Three files, one direction: `reduce.ts` turns the wire response into the
+ * closed {@link LimitsReading} union, `cache.ts` owns the network read and the
+ * staleness rules, and `types.ts` holds the union both sides agree on. The
+ * rendering lives in `tui/limits-panel.ts` — nothing here formats anything.
+ */
+export { LimitsCache } from "./cache.js";
+export { reduceLimits, bindingWindow, usedFraction } from "./reduce.js";

package/dist/limits/reduce.js

@@ -0,0 +1,172 @@
+/**
+ * Wire response → {@link LimitsReading}: one place where "which absence means
+ * what" is decided (P9).
+ *
+ * The reduction is driven by `bucket` and NOTHING else. Not by how the user
+ * logged in, not by whether a key looks like `cxy_live_`, not by which config
+ * fields are set — every one of those was a plausible inference and every one of
+ * them is now wrong, because the gateway changed which bucket a CLI login mints
+ * into (cruxy-ai/api#174) without changing anything a client could see locally.
+ * The endpoint is the answer to that question; asking anything else is guessing.
+ */
+/** A cap is only a denominator when it is a positive, finite number. */
+function usableCap(cap) {
+    return Number.isFinite(cap) && cap > 0;
+}
+/**
+ * A weighted-token window, or `undefined` when it cannot serve as a fraction.
+ *
+ * A cap of 0 is dropped rather than rendered as "100% used": zero is what an
+ * unprovisioned or misconfigured plan reports, and dividing by it produces
+ * either a crash or a full red bar, neither of which is a true statement about
+ * what the user may spend.
+ */
+function toWindow(w) {
+    if (!w || !usableCap(w.cap))
+        return undefined;
+    return {
+        cap: w.cap,
+        used: w.used,
+        remaining: w.remaining,
+        ...(w.state !== undefined ? { state: w.state } : {}),
+        ...(w.resets_at !== undefined ? { resetsAt: w.resets_at } : {}),
+    };
+}
+function toSpendCap(c) {
+    if (!c || !usableCap(c.cap))
+        return undefined;
+    return {
+        cap: c.cap,
+        spent: c.spent,
+        remaining: c.remaining,
+        ...(c.resets_at !== undefined ? { resetsAt: c.resets_at } : {}),
+    };
+}
+function toRateWindow(w) {
+    return {
+        limit: w.limit,
+        remaining: w.remaining,
+        windowSeconds: w.window_seconds,
+        ...(w.resets_at !== undefined ? { resetsAt: w.resets_at } : {}),
+    };
+}
+/**
+ * The budget shape for this credential.
+ *
+ * Ordered by bucket, and each branch answers only for its own bucket — a
+ * `subscription` response that somehow also carried `credits` does not get to
+ * fall through into the headless branch. The server decides which section is
+ * authoritative by telling us the bucket; honouring that literally is what keeps
+ * this reduction and the gate in agreement.
+ */
+function reduceBudget(res) {
+    switch (res.bucket) {
+        case "subscription": {
+            const pool = res.token_pool;
+            // No section at all: gated by something we were not told about.
+            if (!pool)
+                return { kind: "unknown" };
+            // Enterprise. The one place "no numbers" is a complete answer.
+            if (!pool.enforced)
+                return { kind: "unenforced" };
+            const monthly = toWindow(pool.monthly);
+            const burst = toWindow(pool.burst);
+            // Enforced, but nothing readable to enforce against. NOT "unenforced":
+            // the pool exists and will stop this user, we just cannot say when.
+            if (!monthly && !burst)
+                return { kind: "unknown" };
+            return {
+                kind: "pool",
+                unit: pool.unit ?? "weighted_tokens",
+                ...(pool.state !== undefined ? { state: pool.state } : {}),
+                ...(monthly ? { monthly } : {}),
+                ...(burst ? { burst } : {}),
+                ...(pool.mira && usableCap(pool.mira.cap)
+                    ? {
+                        mira: {
+                            cap: pool.mira.cap,
+                            used: pool.mira.used,
+                            remaining: pool.mira.remaining,
+                            state: pool.mira.state,
+                            window: pool.mira.window,
+                            ...(pool.mira.resets_at !== undefined
+                                ? { resetsAt: pool.mira.resets_at }
+                                : {}),
+                        },
+                    }
+                    : {}),
+                blockedModels: pool.blocked_models ?? [],
+            };
+        }
+        case "apikey":
+            // `metered: true` is the server's positive statement that there is no pool
+            // to report. Its absence on an apikey bucket means this build is reading a
+            // response it does not fully understand, so it says so.
+            return res.metered === true ? { kind: "metered" } : { kind: "unknown" };
+        case "headless": {
+            const c = res.credits;
+            if (!c)
+                return { kind: "unknown" };
+            return {
+                kind: "credits",
+                plan: c.plan,
+                granted: c.granted,
+                used: c.used,
+                remaining: c.remaining,
+                ...(c.resets_at !== undefined ? { resetsAt: c.resets_at } : {}),
+            };
+        }
+        default:
+            // A bucket added after this build. The tier and the rate limits below are
+            // still real and still reported; only the budget shape is unreadable.
+            return { kind: "unknown" };
+    }
+}
+/** Reduce a wire response to the reading the panel consumes. */
+export function reduceLimits(res, readAt = Date.now()) {
+    const chat = res.rate_limits?.chat;
+    const keySpendCap = toSpendCap(res.key_spend_cap);
+    const workspaceSpendCap = toSpendCap(res.workspace_spend_cap);
+    const rate = chat
+        ? {
+            perKey: toRateWindow(chat.per_key),
+            perOrg: toRateWindow(chat.per_org),
+            maxConcurrentRequests: chat.max_concurrent_requests,
+        }
+        : undefined;
+    return {
+        tier: res.tier,
+        bucket: res.bucket,
+        budget: reduceBudget(res),
+        ...(rate ? { chat: rate } : {}),
+        ...(keySpendCap ? { keySpendCap } : {}),
+        ...(workspaceSpendCap ? { workspaceSpendCap } : {}),
+        readAt,
+    };
+}
+/**
+ * The window that will stop this user FIRST — the one the gate itself calls
+ * binding: whichever of monthly/burst has the smaller REMAINING fraction
+ * (`internal/budget/decide.go`).
+ *
+ * This is what earns the single bar the rail has room for. Drawing the month
+ * because it is the bigger number would routinely show a comfortable 6% while
+ * the trailing-12h window — a quarter of the month's cap on every self-serve
+ * tier — is the one about to refuse the next request.
+ */
+export function bindingWindow(monthly, burst) {
+    if (!monthly)
+        return burst ? { window: burst, name: "burst" } : undefined;
+    if (!burst)
+        return { window: monthly, name: "month" };
+    const frac = (w) => w.remaining / w.cap;
+    return frac(burst) < frac(monthly)
+        ? { window: burst, name: "burst" }
+        : { window: monthly, name: "month" };
+}
+/** The fraction of a cap consumed, clamped to [0,1] for display. */
+export function usedFraction(w) {
+    if (!usableCap(w.cap))
+        return undefined;
+    return Math.min(1, Math.max(0, w.used / w.cap));
+}

package/dist/limits/types.js

@@ -0,0 +1,25 @@
+/**
+ * The CLI's reading of `GET /api/v1/limits` (P9).
+ *
+ * THE WIRE SHAPE IS NOT THE RENDER SHAPE, and the gap between them is the whole
+ * reason this module exists. On the wire a section is present or absent and a
+ * reader must know which absence means what: no `token_pool` on an `apikey` is
+ * normal, no `monthly` inside an enforced pool is a gateway this build cannot
+ * read, and `{enforced: false}` is a definite statement that there is no cap —
+ * three absences with three different meanings, one of which must never be shown
+ * as another.
+ *
+ * So the reduction resolves them ONCE, into a closed union where each variant
+ * carries exactly the numbers that variant may legitimately state. A renderer
+ * handed a {@link Unenforced} has no cap to divide by because the type has no
+ * cap in it — the honesty is structural, not a rule someone has to remember at
+ * the call site.
+ *
+ * WHAT THIS ADDS TO `usage/weighted.ts`, which computes the same unit locally:
+ * that module is explicit that it can state consumption and never headroom,
+ * because a cap needs the user's plan and what every OTHER surface (web chat,
+ * desktop, phone) has already spent — "neither of which is on this machine".
+ * This is the other half arriving over the wire: the denominator, already
+ * inclusive of every surface, from the meter itself.
+ */
+export {};

package/dist/memory/secrets.js

@@ -59,3 +59,46 @@ export function containsSecret(text) {
     }
     return { secret: false };
 }
+/**
+ * The global twins of {@link SECRET_PATTERNS}, built once.
+ *
+ * Detection asks "is there one?" and can stop at the first hit; redaction has to
+ * replace EVERY occurrence, which needs the `g` flag — and a `g` regex carries
+ * `lastIndex` state that would make `containsSecret` return alternating answers
+ * for the same input. So the two uses get their own objects rather than sharing
+ * one and remembering to reset it.
+ */
+const GLOBAL_PATTERNS = SECRET_PATTERNS.map(({ kind, re }) => ({ kind, re: new RegExp(re.source, `${re.flags}g`) }));
+/**
+ * Replace every recognised secret in `text` with an opaque marker (P10 track 5).
+ *
+ * THE SAME DENYLIST as detection, deliberately — a `/redact` that used a
+ * different pattern set from the one that refuses a memory write would give two
+ * different answers about what counts as a secret, and the weaker of the two
+ * would be the one a user found out about.
+ *
+ * The marker is fixed text with no quotes, backslashes or control characters, so
+ * a redacted string survives being embedded in JSON unchanged — which is what
+ * lets a `tool_use` input be redacted by round-tripping through its serialised
+ * form rather than by walking an arbitrary shape.
+ *
+ * Everything the pattern matched goes, including a `api_key =` prefix on the
+ * generic assignment rule. Keeping the field name would read better and would
+ * leak the shape of the thing next to a marker announcing that something was
+ * there; the marker's `kind` already says as much as is safe to say.
+ */
+export function redactSecrets(text) {
+    const kinds = [];
+    let count = 0;
+    let out = text;
+    for (const { kind, re } of GLOBAL_PATTERNS) {
+        re.lastIndex = 0;
+        out = out.replace(re, () => {
+            count++;
+            if (!kinds.includes(kind))
+                kinds.push(kind);
+            return `[redacted ${kind}]`;
+        });
+    }
+    return { text: out, kinds, count };
+}

package/dist/onboarding/detect.js

@@ -1,36 +1,122 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from "node:fs";
 import { dirname, join } from "node:path";
 import { ONBOARDING_FILE_NAME } from "../constants.js";
 import { globalDir, resolveApiKey } from "../config/index.js";
+import { ONBOARDING_VERSION, OnboardingStateSchema, } from "./types.js";
 /**
  * First-run detection + onboarding-state persistence (U.6). "First run" is
  * deliberately derived from observable facts (no key + no completion marker)
  * rather than a flag, and is **TTY-gated** so a non-interactive run never
  * branches into an interactive flow.
  */
-const ONBOARDING_VERSION = 1;
 /** `~/.cruxy/onboarding.json` */
 export function onboardingStatePath() {
     return join(globalDir(), ONBOARDING_FILE_NAME);
 }
-/** Read persisted onboarding state, or `null` if absent/unreadable. */
+/**
+ * Read persisted onboarding state, or `null` if absent, unreadable, or not the
+ * shape this file is supposed to hold.
+ *
+ * VALIDATED, not cast. `as OnboardingState` accepted any object at all, so a
+ * truncated write or a hand-edit could hand the flow a `completedAt` that was a
+ * number — and the completion marker is the one fact that decides whether a
+ * user is walked through setup again or silently isn't.
+ *
+ * An invalid file reads as ABSENT rather than throwing, which is the same
+ * treatment corrupt JSON already got: the worst outcome of re-onboarding is one
+ * extra prompt, and the worst outcome of a hard error is a CLI that won't start
+ * because of a file that only exists to say "you've done this before".
+ */
 export function readOnboardingState(file = onboardingStatePath()) {
     if (!existsSync(file))
         return null;
+    let parsed;
     try {
-        const parsed = JSON.parse(readFileSync(file, "utf8"));
-        if (parsed && typeof parsed === "object")
-            return parsed;
+        parsed = JSON.parse(readFileSync(file, "utf8"));
     }
     catch {
         // A corrupt marker is treated as absent — onboarding can rewrite it.
+        return null;
     }
-    return null;
+    const result = OnboardingStateSchema.safeParse(parsed);
+    return result.success ? migrateState(result.data) : null;
+}
+/**
+ * The version branch the file has been writing a number for since U.6 and
+ * nothing has ever read.
+ *
+ * OLDER than this build: bring it forward. There is exactly one version today,
+ * so this is a re-stamp and nothing else — the point is that the next bump has
+ * one obvious place to add its step, instead of discovering at that moment that
+ * every reader assumed v1.
+ *
+ * NEWER than this build: return it untouched and keep trusting `completedAt`.
+ * Both alternatives are worse. Discarding it re-runs onboarding for someone who
+ * has plainly finished it, every time they use the older binary — running two
+ * cruxy versions against one home directory is ordinary, and being re-prompted
+ * for a key you already saved is not a reasonable punishment for it. Rewriting
+ * it down to our shape would destroy state we don't understand. `completedAt`
+ * is the marker in every version that has one; reading it across a version we
+ * don't know is a smaller assumption than either.
+ */
+function migrateState(state) {
+    if (state.version >= ONBOARDING_VERSION)
+        return state;
+    return { ...state, version: ONBOARDING_VERSION };
 }
-/** Persist onboarding state (creates `~/.cruxy` if needed). */
+/**
+ * Persist onboarding state (creates `~/.cruxy` if needed), owner-only.
+ *
+ * MERGED over what is on disk, not written over it. The schema passes unknown
+ * keys through, so a field a newer cruxy wrote survives a run of an older one
+ * — tolerating it on read and then flattening it on the next write would lose
+ * the data anyway, just one write later.
+ *
+ * The version is the MAX of the two for the same reason `migrateState` doesn't
+ * discard a future file: this build preserved the newer keys, so stamping our
+ * own lower number over them would tell the newer cruxy that its migration
+ * hasn't run when its data is in fact all still there.
+ */
 export function writeOnboardingState(state, file = onboardingStatePath()) {
+    const existing = readOnboardingState(file);
+    const merged = {
+        ...existing,
+        ...state,
+        version: Math.max(existing?.version ?? 0, state.version),
+    };
     mkdirSync(dirname(file), { recursive: true });
-    writeFileSync(file, JSON.stringify(state, null, 2) + "\n", "utf8");
+    writeFileSync(file, JSON.stringify(merged, null, 2) + "\n", {
+        encoding: "utf8",
+        mode: 0o600,
+    });
+    restrictToOwner(file);
+}
+/**
+ * Make the marker owner-only. It was the one store under `~/.cruxy` still at
+ * `0644` — usage, memory trust, MCP trust and hook trust are all `0600` — and
+ * while it holds no secret, it does record that this machine's user has a cruxy
+ * key configured and when they set it up. That is nobody else's business on a
+ * shared box, and "every file cruxy writes to your home directory is yours
+ * alone" is a rule worth being able to state without an exception.
+ *
+ * The `mode` on the write above only applies when the file is CREATED, so it
+ * does nothing for the `0644` files already out there; this fixes those on the
+ * next write. Best-effort and non-fatal, deliberately: unlike the credential
+ * store — which refuses to persist a secret it cannot secure — refusing to
+ * write this one would mean re-running onboarding forever on a filesystem
+ * without modes. Windows is skipped because POSIX modes are meaningless there
+ * (see `config/owner-only.ts`), and an `icacls` edit is more than a marker
+ * warrants.
+ */
+function restrictToOwner(file) {
+    if (process.platform === "win32")
+        return;
+    try {
+        chmodSync(file, 0o600);
+    }
+    catch {
+        // A filesystem that can't do modes still gets a working marker.
+    }
 }
 /** A fresh state object. */
 export function newOnboardingState() {

package/dist/onboarding/types.js

@@ -1,6 +1,34 @@
+import { z } from "zod";
 /**
  * Types for the first-run onboarding flow (U.6). The flow is built from injected
  * dependencies (validation, persistence, the first-win runner) so every step is
  * unit-testable with scripted IO and no real network or filesystem.
  */
-export {};
+/**
+ * Bump when the on-disk onboarding state shape changes. The number is only
+ * worth writing if something READS it — see `migrateState` in `detect.ts`,
+ * which is where the branch it enables lives.
+ */
+export const ONBOARDING_VERSION = 1;
+/**
+ * The persisted state (`~/.cruxy/onboarding.json`), as a schema rather than a
+ * cast. It was read with `as OnboardingState` — a cast validates nothing, so
+ * `{"completedAt": 42}` or a JSON array parsed clean and the completion marker
+ * became whatever the file happened to contain.
+ *
+ * `.passthrough()`, for the reason `usage/types.ts` sets out at length: a read
+ * that can't validate is a read that discards, and a store hostile to its own
+ * future silently drops what a newer cruxy wrote the moment an older one runs
+ * against the same home directory. Passthrough both TOLERATES an unknown key
+ * and PRESERVES it, so `writeOnboardingState`'s merge hands it back intact.
+ */
+export const OnboardingStateSchema = z
+    .object({
+    /** Shape version — see {@link ONBOARDING_VERSION}. */
+    version: z.number().int().nonnegative(),
+    /** ISO timestamp; **its presence is the completion marker**. */
+    completedAt: z.string().min(1).optional(),
+    /** Whether a key has been successfully configured at least once. */
+    keyConfigured: z.boolean().optional(),
+})
+    .passthrough();

package/dist/render/context-view.js

@@ -51,8 +51,8 @@ export function contextReportLines(report, t, width = Infinity) {
     // The headline, worded exactly as the panel words it — same estimate, same
     // caveats, so the detail view can never read as the more authoritative one.
     lines.push(`${t.strong(`${approx(reading.used)} / ${formatTokens(reading.total)} budget`)} ` +
-        t.muted(`(estimated · budget is a local setting, not the model's window)`));
-    lines.push(t.muted(`${report.messages} message${report.messages === 1 ? "" : "s"} · compacts above ${approx(reading.compactAt)}`));
+        t.muted(`(estimated${t.sep}budget is a local setting, not the model's window)`));
+    lines.push(t.muted(`${report.messages} message${report.messages === 1 ? "" : "s"}${t.sep}compacts above ${approx(reading.compactAt)}`));
     // ── where the tokens are ──────────────────────────────────────────────────
     const historyTokens = report.parts.reduce((sum, p) => sum + p.tokens, 0);
     lines.push("");