agent-nuvira 3.3.4 → 3.3.5

package/dist/agent-sdk/src/scaffold.d.ts

@@ -34,7 +34,7 @@ export interface ScaffoldOptions {
  * a custom agent fail to load. A test asserts the two agree, so a release that
  * forgets this constant fails rather than shipping.
  */
-export declare const SDK_VERSION = "3.3.4";
+export declare const SDK_VERSION = "3.3.5";
 /**
  * Scaffold a new custom agent project.
  *

package/dist/agent-sdk/src/scaffold.js

@@ -34,7 +34,7 @@ function toCamelCase(pascal) {
  * a custom agent fail to load. A test asserts the two agree, so a release that
  * forgets this constant fails rather than shipping.
  */
-export const SDK_VERSION = '3.3.4';
+export const SDK_VERSION = '3.3.5';
 // ─── Templates ──────────────────────────────────────────────────────────────
 const PACKAGE_JSON_TEMPLATE = (opts) => `{
   "name": "${toKebabCase(opts.agentName)}-agent",

package/dist/config/process-env.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Curated process-environment variables — the allowlist behind the dashboard's
+ * Process Environment page.
+ *
+ * WHY AN ALLOWLIST. `~/.nuvira/.env` already has a general writer: the skill
+ * secret editor, which accepts any well-formed NAME because a skill may declare
+ * any name it likes. The process-behaviour switches are a different thing
+ * entirely — they change how a RUN behaves rather than what a skill can read,
+ * and several of them are tri-state (asked / declined / nobody said anything),
+ * which a free-text NAME=VALUE box cannot express. So the dashboard does not
+ * expose "write any variable"; it exposes a fixed, curated set of switches, and
+ * the endpoint that writes them refuses every name on this list and no other.
+ *
+ * WHY THE RULES ARE HERE AND NOT IN THE UI. Every flag below is read somewhere
+ * else in the codebase by a specific rule, and those rules are NOT the same:
+ *
+ *   - `envAsks` (worktree.ts) — `1`/`true`/`yes` ask; everything else, including
+ *     unset, does not.
+ *   - `resolveResumeRequest` (step-checkpoint.ts) — `1`/`true`/`yes` ask for the
+ *     automatic record, `''`/`0`/`false` are off, and ANY OTHER VALUE IS A
+ *     RECORD NAME, which is an active resume. Note what that means for `off` and
+ *     `no`: unlike the two rules above, `NUVIRA_RESUME=no` is a resume, not a
+ *     refusal. The page reports what the reader will really do rather than the
+ *     tidier thing it looks like it should do, because a config page that lies
+ *     about behaviour is worse than one that omits the variable.
+ *   - `debugLoggingEnabled` (debug-log.ts) and `otelExportEnabled` (otel.ts) —
+ *     anything except `0`/`false`/`off`/`no`/blank, so `NUVIRA_OTEL=false` in an
+ *     `.env` means OFF rather than "a non-empty string".
+ *   - `strictModelMode` (route-resolver.ts) — the literal `1`, and nothing else.
+ *     `NUVIRA_STRICT_MODEL=true` does NOT enable it, which is exactly the kind of
+ *     detail a config UI gets wrong by assuming.
+ *
+ * Because the readers disagree, the page must not write "whatever the user
+ * typed" and then claim it took effect. It writes the canonical value the
+ * reader understands (`1` for on, `0` for off) and says, per variable, what
+ * leaving it unset means.
+ */
+/** The vocabulary a variable is declared for, which is also its UI grouping. */
+export type ProcessEnvGroup = 'turn' | 'observability' | 'hooks';
+/** How the reader that owns a switch decides it is ON. */
+export type ProcessEnvFlagRule = 
+/** `1`/`true`/`yes` ask for it; anything else is off. (`envAsks`) */
+'asks'
+/** Any value except `0`/`false`/`off`/`no`/blank. (`debugLoggingEnabled`, `otelExportEnabled`) */
+ | 'truthy'
+/** The literal `1` and nothing else. (`strictModelMode`) */
+ | 'strict-one'
+/** `1`/`true`/`yes` ask; `''`/`0`/`false` are off; any other value NAMES one. (`resolveResumeRequest`) */
+ | 'asks-or-names';
+/** One curated variable, in the shape both the endpoint and the page render. */
+export interface ProcessEnvVarSpec {
+    /** The exact environment name. `NUVIRA_*`; the `BUFF_*` aliases are legacy. */
+    name: string;
+    /** Short human name for the row. */
+    label: string;
+    /** Which section of the page the row belongs to. */
+    group: ProcessEnvGroup;
+    /**
+     * `flag` renders on/off/unset, because the variable's meaning is a decision.
+     * `text` renders a single-line value, because the variable IS a value.
+     */
+    kind: 'flag' | 'text';
+    /** For `flag` only: the rule its reader uses. */
+    rule?: ProcessEnvFlagRule;
+    /**
+     * For a `flag` that ALSO accepts a name — `NUVIRA_RESUME=1` asks for the
+     * automatic record for this ask in this directory, while any other non-falsey
+     * value names a specific checkpoint. Without this the page could only express
+     * the boolean half of a variable that has two.
+     */
+    acceptsValue?: boolean;
+    /** Label for the optional value box (only when `acceptsValue`). */
+    valueLabel?: string;
+    /** Placeholder for a `text` row or the optional value box. */
+    placeholder?: string;
+    /** What the variable does, in one line. */
+    description: string;
+    /**
+     * What leaving it UNSET means. This is the state the row starts in and the
+     * state a user has to be able to reason about, so it is written down per
+     * variable rather than assumed to be "off" — for most of these it is, but
+     * "nobody said anything" and "someone said no" are different for the two
+     * tri-state switches, and the page must not blur them.
+     */
+    unsetMeans: string;
+    /** Where the same switch is reachable without the dashboard. */
+    cliEquivalent?: string;
+}
+/**
+ * The set — deliberately small, and every entry is a switch this codebase
+ * actually reads. A variable that nothing consumes would be a control that
+ * silently does nothing, which is worse than no control at all.
+ */
+export declare const PROCESS_ENV_VARS: readonly ProcessEnvVarSpec[];
+/** Look up a spec by its exact name. */
+export declare function processEnvVarSpec(name: string): ProcessEnvVarSpec | undefined;
+/**
+ * Is this name on the allowlist?
+ *
+ * The write endpoints call this FIRST, before touching the file, so a request
+ * cannot append an arbitrary name to the credential `.env` through a page that
+ * claims to be curated.
+ */
+export declare function isCuratedProcessEnvVar(name: string): boolean;
+/** Why a value was refused — a stable code the page turns into copy. */
+export type ProcessEnvValueError = 'unknown-name' | 'empty' | 'multiline' | 'too-long' | 'not-a-flag';
+/** Bound on a stored value. A hook command is a command, not a script. */
+export declare const PROCESS_ENV_VALUE_MAX_CHARS = 512;
+/**
+ * Normalize a value to the single spelling its reader understands.
+ *
+ * `flag` rows are canonicalized to `1`/`0` rather than stored as typed, because
+ * `NUVIRA_STRICT_MODEL=true` reads as OFF (`strictModelMode` compares to `'1'`).
+ * Storing the user's word would let the page show "on" while the run disagrees —
+ * the failure this whole module exists to prevent.
+ *
+ * A `flag` with `acceptsValue` keeps any other non-falsey string: that is the
+ * checkpoint-id half of `NUVIRA_RESUME`, and it is the reader's own rule
+ * (`resolveResumeRequest`) that "anything else names one".
+ */
+export declare function normalizeProcessEnvValue(name: string, raw: string): {
+    ok: true;
+    value: string;
+} | {
+    ok: false;
+    reason: ProcessEnvValueError;
+};
+/**
+ * Is this stored value ON, by the rule its own reader uses?
+ *
+ * Deliberately not `normalize(...).value === '1'`: a value written by hand —
+ * `NUVIRA_OTEL=anything`, which IS on — must be reported as it will really
+ * behave, not as the page wishes it were spelled.
+ */
+export declare function processEnvFlagIsOn(rule: ProcessEnvFlagRule | undefined, value: string | null): boolean;
+//# sourceMappingURL=process-env.d.ts.map

package/dist/config/process-env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-env.d.ts","sourceRoot":"","sources":["../../src/config/process-env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,gFAAgF;AAChF,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,eAAe,GAAG,OAAO,CAAC;AAEjE,0DAA0D;AAC1D,MAAM,MAAM,kBAAkB;AAC5B,qEAAqE;AACnE,MAAM;AACR,kGAAkG;GAChG,QAAQ;AACV,4DAA4D;GAC1D,YAAY;AACd,0GAA0G;GACxG,eAAe,CAAC;AAEpB,gFAAgF;AAChF,MAAM,WAAW,iBAAiB;IAChC,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,KAAK,EAAE,eAAe,CAAC;IACvB;;;OAGG;IACH,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACtB,iDAAiD;IACjD,IAAI,CAAC,EAAE,kBAAkB,CAAC;IAC1B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,gEAAgE;IAChE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,iBAAiB,EAkGxD,CAAC;AAEF,wCAAwC;AACxC,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS,CAE7E;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE5D;AAMD,wEAAwE;AACxE,MAAM,MAAM,oBAAoB,GAAG,cAAc,GAAG,OAAO,GAAG,WAAW,GAAG,UAAU,GAAG,YAAY,CAAC;AAEtG,0EAA0E;AAC1E,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAE/C;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,GACV;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,oBAAoB,CAAA;CAAE,CAoB3E;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,kBAAkB,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAkBtG"}

package/dist/config/process-env.js

@@ -0,0 +1,217 @@
+/**
+ * Curated process-environment variables — the allowlist behind the dashboard's
+ * Process Environment page.
+ *
+ * WHY AN ALLOWLIST. `~/.nuvira/.env` already has a general writer: the skill
+ * secret editor, which accepts any well-formed NAME because a skill may declare
+ * any name it likes. The process-behaviour switches are a different thing
+ * entirely — they change how a RUN behaves rather than what a skill can read,
+ * and several of them are tri-state (asked / declined / nobody said anything),
+ * which a free-text NAME=VALUE box cannot express. So the dashboard does not
+ * expose "write any variable"; it exposes a fixed, curated set of switches, and
+ * the endpoint that writes them refuses every name on this list and no other.
+ *
+ * WHY THE RULES ARE HERE AND NOT IN THE UI. Every flag below is read somewhere
+ * else in the codebase by a specific rule, and those rules are NOT the same:
+ *
+ *   - `envAsks` (worktree.ts) — `1`/`true`/`yes` ask; everything else, including
+ *     unset, does not.
+ *   - `resolveResumeRequest` (step-checkpoint.ts) — `1`/`true`/`yes` ask for the
+ *     automatic record, `''`/`0`/`false` are off, and ANY OTHER VALUE IS A
+ *     RECORD NAME, which is an active resume. Note what that means for `off` and
+ *     `no`: unlike the two rules above, `NUVIRA_RESUME=no` is a resume, not a
+ *     refusal. The page reports what the reader will really do rather than the
+ *     tidier thing it looks like it should do, because a config page that lies
+ *     about behaviour is worse than one that omits the variable.
+ *   - `debugLoggingEnabled` (debug-log.ts) and `otelExportEnabled` (otel.ts) —
+ *     anything except `0`/`false`/`off`/`no`/blank, so `NUVIRA_OTEL=false` in an
+ *     `.env` means OFF rather than "a non-empty string".
+ *   - `strictModelMode` (route-resolver.ts) — the literal `1`, and nothing else.
+ *     `NUVIRA_STRICT_MODEL=true` does NOT enable it, which is exactly the kind of
+ *     detail a config UI gets wrong by assuming.
+ *
+ * Because the readers disagree, the page must not write "whatever the user
+ * typed" and then claim it took effect. It writes the canonical value the
+ * reader understands (`1` for on, `0` for off) and says, per variable, what
+ * leaving it unset means.
+ */
+/**
+ * The set — deliberately small, and every entry is a switch this codebase
+ * actually reads. A variable that nothing consumes would be a control that
+ * silently does nothing, which is worse than no control at all.
+ */
+export const PROCESS_ENV_VARS = [
+    {
+        name: 'NUVIRA_ISOLATE',
+        label: 'Isolate every turn',
+        group: 'turn',
+        kind: 'flag',
+        rule: 'asks',
+        description: 'Run each turn in its own git worktree of the project and return the diff against the commit it started from.',
+        unsetMeans: 'A turn runs in the project directory itself.',
+        cliEquivalent: 'nuvira chat --worktree',
+    },
+    {
+        name: 'NUVIRA_RESUME',
+        label: 'Replay recorded steps',
+        group: 'turn',
+        kind: 'flag',
+        rule: 'asks-or-names',
+        acceptsValue: true,
+        valueLabel: '…or a checkpoint id',
+        placeholder: 'blank = this ask, in this directory',
+        description: 'Replay the model calls of this ask whose whole input is unchanged instead of paying for them again.',
+        unsetMeans: 'Nothing is replayed; every step is paid for.',
+        cliEquivalent: 'nuvira chat --resume [id]',
+    },
+    {
+        name: 'NUVIRA_STRICT_MODEL',
+        label: 'Refuse model substitution',
+        group: 'turn',
+        kind: 'flag',
+        rule: 'strict-one',
+        description: 'Fail instead of substituting a model when a pinned one is unavailable, so "it ran on something else" cannot happen silently.',
+        unsetMeans: 'A dead pin is repaired by substituting an available model, and the swap is announced.',
+    },
+    {
+        name: 'NUVIRA_DEBUG_LOG',
+        label: 'Write a session debug log',
+        group: 'observability',
+        kind: 'flag',
+        rule: 'truthy',
+        description: 'Write one redacted, bounded log file per turn to <config dir>/debug-logs, ready to attach to a bug report.',
+        unsetMeans: 'No log is written.',
+    },
+    {
+        name: 'NUVIRA_OTEL',
+        label: 'Export OTLP spans',
+        group: 'observability',
+        kind: 'flag',
+        rule: 'truthy',
+        description: 'Export a span tree per turn (nuvira.turn with one child per tool call that really ran) over OTLP/HTTP.',
+        unsetMeans: 'Nothing is built and the OpenTelemetry SDK is never even imported.',
+    },
+    {
+        name: 'OTEL_EXPORTER_OTLP_ENDPOINT',
+        label: 'OTLP collector endpoint',
+        group: 'observability',
+        kind: 'text',
+        placeholder: 'http://localhost:4318',
+        description: 'Where spans are shipped. The OTLP spec appends /v1/traces to this; set OTEL_EXPORTER_OTLP_TRACES_ENDPOINT instead to give the full path.',
+        unsetMeans: 'NUVIRA_OTEL builds spans and then drops them, because there is nowhere to send them.',
+    },
+    {
+        name: 'NUVIRA_TOOL_HOOK_BEFORE',
+        label: 'Before a tool call',
+        group: 'hooks',
+        kind: 'text',
+        placeholder: 'node ~/deny-shell.mjs',
+        description: 'A command run before each tool call. The call arrives as JSON on stdin; silence means allow, and {"decision":"deny","reason":"…"} stops the call.',
+        unsetMeans: 'No before-hook. A hook declared in tools.hooks (buffconfig.json) still runs.',
+        cliEquivalent: 'tools.hooks in buffconfig.json',
+    },
+    {
+        name: 'NUVIRA_TOOL_HOOK_AFTER',
+        label: 'After a tool call',
+        group: 'hooks',
+        kind: 'text',
+        placeholder: 'node ~/audit.mjs',
+        description: 'A command run after each tool call, with the call and a bounded preview of its result on stdin. It cannot veto — the call already happened.',
+        unsetMeans: 'No after-hook. A hook declared in tools.hooks (buffconfig.json) still runs.',
+        cliEquivalent: 'tools.hooks in buffconfig.json',
+    },
+    {
+        name: 'NUVIRA_TOOL_HOOK_FAILED',
+        label: 'After a failed tool call',
+        group: 'hooks',
+        kind: 'text',
+        placeholder: 'node ~/on-failure.mjs',
+        description: 'A command run when a tool call fails, with the failure on stdin.',
+        unsetMeans: 'No failed-hook. A hook declared in tools.hooks (buffconfig.json) still runs.',
+        cliEquivalent: 'tools.hooks in buffconfig.json',
+    },
+];
+/** Look up a spec by its exact name. */
+export function processEnvVarSpec(name) {
+    return PROCESS_ENV_VARS.find((v) => v.name === name);
+}
+/**
+ * Is this name on the allowlist?
+ *
+ * The write endpoints call this FIRST, before touching the file, so a request
+ * cannot append an arbitrary name to the credential `.env` through a page that
+ * claims to be curated.
+ */
+export function isCuratedProcessEnvVar(name) {
+    return processEnvVarSpec(name) !== undefined;
+}
+/** The words that mean ON / OFF, as the readers themselves accept them. */
+const ON_WORDS = new Set(['1', 'true', 'yes', 'on']);
+const OFF_WORDS = new Set(['0', 'false', 'off', 'no']);
+/** Bound on a stored value. A hook command is a command, not a script. */
+export const PROCESS_ENV_VALUE_MAX_CHARS = 512;
+/**
+ * Normalize a value to the single spelling its reader understands.
+ *
+ * `flag` rows are canonicalized to `1`/`0` rather than stored as typed, because
+ * `NUVIRA_STRICT_MODEL=true` reads as OFF (`strictModelMode` compares to `'1'`).
+ * Storing the user's word would let the page show "on" while the run disagrees —
+ * the failure this whole module exists to prevent.
+ *
+ * A `flag` with `acceptsValue` keeps any other non-falsey string: that is the
+ * checkpoint-id half of `NUVIRA_RESUME`, and it is the reader's own rule
+ * (`resolveResumeRequest`) that "anything else names one".
+ */
+export function normalizeProcessEnvValue(name, raw) {
+    const spec = processEnvVarSpec(name);
+    if (!spec)
+        return { ok: false, reason: 'unknown-name' };
+    // A newline would smuggle a second variable into the file, so it is refused
+    // rather than stripped: silently dropping half a pasted value is how a config
+    // ends up containing something the user never wrote.
+    if (/[\r\n]/.test(raw))
+        return { ok: false, reason: 'multiline' };
+    const value = raw.trim();
+    if (value === '')
+        return { ok: false, reason: 'empty' };
+    if (value.length > PROCESS_ENV_VALUE_MAX_CHARS)
+        return { ok: false, reason: 'too-long' };
+    if (spec.kind === 'text')
+        return { ok: true, value };
+    const word = value.toLowerCase();
+    if (ON_WORDS.has(word))
+        return { ok: true, value: '1' };
+    if (OFF_WORDS.has(word))
+        return { ok: true, value: '0' };
+    if (spec.acceptsValue)
+        return { ok: true, value };
+    return { ok: false, reason: 'not-a-flag' };
+}
+/**
+ * Is this stored value ON, by the rule its own reader uses?
+ *
+ * Deliberately not `normalize(...).value === '1'`: a value written by hand —
+ * `NUVIRA_OTEL=anything`, which IS on — must be reported as it will really
+ * behave, not as the page wishes it were spelled.
+ */
+export function processEnvFlagIsOn(rule, value) {
+    if (value === null)
+        return false;
+    const word = value.trim().toLowerCase();
+    switch (rule) {
+        case 'truthy':
+            return word !== '' && word !== '0' && word !== 'false' && word !== 'off' && word !== 'no';
+        case 'asks':
+            return word === '1' || word === 'true' || word === 'yes';
+        case 'strict-one':
+            return value.trim() === '1';
+        case 'asks-or-names':
+            // `resolveResumeRequest` in full: only blank, `0` and `false` decline.
+            // `off` and `no` are NOT refusals here — they name a record.
+            return word !== '' && word !== '0' && word !== 'false';
+        default:
+            // A `text` row has no on/off reading; callers only ask this for flags.
+            return false;
+    }
+}
+//# sourceMappingURL=process-env.js.map

package/dist/config/process-env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-env.js","sourceRoot":"","sources":["../../src/config/process-env.ts"],"names":[],"mappings":"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"}

package/dist/learning/model-reachability.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Can the router use this model RIGHT NOW — and if not, what exactly is wrong?
+ *
+ * WHY THIS MODULE EXISTS. The dashboard's Discovery Timeline answered that
+ * question three different ways on one screen and they disagreed: the summary
+ * cards and the filter classified on PROBE age (`lastProbedAt`), while each
+ * row's badge checked verification `status` first. MEASURED on a real profile:
+ * 555 tracked models, 17 verified, and 531 probed within 7 days — so the "Fresh
+ * (531)" card opened a list in which 514 rows read "Unverified". Nothing was
+ * broken and nothing agreed.
+ *
+ * The deeper fault was the question. "Fresh" and "unverified" are not two
+ * answers to one question, they are two different questions:
+ *
+ *   - `lastProbedAt` — is the provider still listing this id? (discovery)
+ *   - `status` / `lastVerifiedAt` — has a real turn been proven to work on it?
+ *     (routing eligibility)
+ *
+ * A model can be freshly probed and never verified (the common case: a provider
+ * lists hundreds of ids, none tried), or verified and long unprobed. Flattening
+ * both into one label is what produced the contradiction, so this module keeps
+ * them apart and names each state for what it actually is.
+ *
+ * THE ROUTING VERDICT IS NOT RE-DERIVED HERE. `classifyReachability` mirrors
+ * `ModelRegistry.isUsable()` clause for clause, in its order, including the
+ * subtlety that a verified model is blocked only by a MODEL-level park
+ * (`providerParked === false`) and never by a provider-level one. Two copies of
+ * this rule is exactly the divergence that made the Models page present a
+ * listing as availability (see that panel's own history), so `routable` here
+ * means "isUsable() would return true" and nothing else.
+ */
+/**
+ * What the router would do with this model right now.
+ *
+ * An enum rather than a boolean because "not routable" is four different
+ * situations behind one word, and they need opposite actions from a user:
+ * one is unknown and will be resolved by a spot-check, one is proven dead, one
+ * clears itself, and one is repaired by re-probing.
+ */
+export type ModelReachability = 
+/** Verified, un-parked, verified within the staleness window — `isUsable() === true`. */
+'routable'
+/** Verified, but resting on a MODEL-level quota park. Clears by itself. */
+ | 'parked'
+/** Verified, but the proof is older than `DEFAULT_STALE_MS` (7d) — re-probe to restore. */
+ | 'proof-expired'
+/** `unavailable`: a real call established this id does not work here. */
+ | 'proven-dead'
+/** `unverified`: the provider lists it and nothing has ever succeeded on it. NOT a failure. */
+ | 'never-verified';
+/** The subset of a registry entry this classifier reads. */
+export interface ReachabilityInput {
+    status: string;
+    lastVerifiedAt?: number;
+    quotaParkedUntil?: number;
+    providerParked?: boolean;
+}
+/**
+ * Mirror of `ModelRegistry.isUsable()`, clause for clause and in the same order.
+ *
+ * Order is load-bearing and is NOT the order you would guess: a model that is
+ * `unavailable` AND parked reads as `proven-dead`, because the status check
+ * comes first. Keeping the two functions adjacent in shape is what makes them
+ * diffable by eye.
+ */
+export declare function classifyReachability(entry: ReachabilityInput, now?: number): ModelReachability;
+/** How a state is worded. One place, so the page and any CLI cannot drift. */
+export declare const REACHABILITY_COPY: Record<ModelReachability, {
+    label: string;
+    blurb: string;
+    color: string;
+}>;
+/** Would the router pick this model right now? The one question routing asks. */
+export declare function isRoutable(reachability: ModelReachability): boolean;
+/**
+ * Is the provider still listing this id?
+ *
+ * Deliberately separate from reachability: probe age says nothing about whether
+ * a turn would work, and reachability says nothing about whether the model still
+ * exists in the catalog. The old page treated them as one axis.
+ */
+export type ModelFreshness = 'fresh' | 'stale' | 'likely-removed';
+/** Probe-age thresholds. Kept here so the numbers are stated once. */
+export declare const FRESH_DAYS = 7;
+export declare const REMOVED_DAYS = 30;
+/** Error rate above which a long-unprobed model reads as actually gone. */
+export declare const REMOVED_ERROR_RATE = 0.5;
+export declare function classifyFreshness(lastProbedAt: number | undefined, errorRate: number | undefined, now?: number): ModelFreshness;
+/** How a freshness state is worded. */
+export declare const FRESHNESS_COPY: Record<ModelFreshness, {
+    label: string;
+    blurb: string;
+    color: string;
+}>;
+//# sourceMappingURL=model-reachability.d.ts.map

package/dist/learning/model-reachability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-reachability.d.ts","sourceRoot":"","sources":["../../src/learning/model-reachability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAIH;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB;AAC3B,yFAAyF;AACvF,UAAU;AACZ,2EAA2E;GACzE,QAAQ;AACV,2FAA2F;GACzF,eAAe;AACjB,yEAAyE;GACvE,aAAa;AACf,+FAA+F;GAC7F,gBAAgB,CAAC;AAErB,4DAA4D;AAC5D,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,iBAAiB,EACxB,GAAG,GAAE,MAAmB,GACvB,iBAAiB,CAWnB;AAED,8EAA8E;AAC9E,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,iBAAiB,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CA4BxG,CAAC;AAEF,iFAAiF;AACjF,wBAAgB,UAAU,CAAC,YAAY,EAAE,iBAAiB,GAAG,OAAO,CAEnE;AAED;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,OAAO,GAAG,gBAAgB,CAAC;AAElE,sEAAsE;AACtE,eAAO,MAAM,UAAU,IAAI,CAAC;AAC5B,eAAO,MAAM,YAAY,KAAK,CAAC;AAC/B,2EAA2E;AAC3E,eAAO,MAAM,kBAAkB,MAAM,CAAC;AAEtC,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,GAAG,GAAE,MAAmB,GACvB,cAAc,CAKhB;AAED,uCAAuC;AACvC,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,cAAc,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAQlG,CAAC"}

package/dist/learning/model-reachability.js

@@ -0,0 +1,111 @@
+/**
+ * Can the router use this model RIGHT NOW — and if not, what exactly is wrong?
+ *
+ * WHY THIS MODULE EXISTS. The dashboard's Discovery Timeline answered that
+ * question three different ways on one screen and they disagreed: the summary
+ * cards and the filter classified on PROBE age (`lastProbedAt`), while each
+ * row's badge checked verification `status` first. MEASURED on a real profile:
+ * 555 tracked models, 17 verified, and 531 probed within 7 days — so the "Fresh
+ * (531)" card opened a list in which 514 rows read "Unverified". Nothing was
+ * broken and nothing agreed.
+ *
+ * The deeper fault was the question. "Fresh" and "unverified" are not two
+ * answers to one question, they are two different questions:
+ *
+ *   - `lastProbedAt` — is the provider still listing this id? (discovery)
+ *   - `status` / `lastVerifiedAt` — has a real turn been proven to work on it?
+ *     (routing eligibility)
+ *
+ * A model can be freshly probed and never verified (the common case: a provider
+ * lists hundreds of ids, none tried), or verified and long unprobed. Flattening
+ * both into one label is what produced the contradiction, so this module keeps
+ * them apart and names each state for what it actually is.
+ *
+ * THE ROUTING VERDICT IS NOT RE-DERIVED HERE. `classifyReachability` mirrors
+ * `ModelRegistry.isUsable()` clause for clause, in its order, including the
+ * subtlety that a verified model is blocked only by a MODEL-level park
+ * (`providerParked === false`) and never by a provider-level one. Two copies of
+ * this rule is exactly the divergence that made the Models page present a
+ * listing as availability (see that panel's own history), so `routable` here
+ * means "isUsable() would return true" and nothing else.
+ */
+import { DEFAULT_STALE_MS } from './model-registry.js';
+/**
+ * Mirror of `ModelRegistry.isUsable()`, clause for clause and in the same order.
+ *
+ * Order is load-bearing and is NOT the order you would guess: a model that is
+ * `unavailable` AND parked reads as `proven-dead`, because the status check
+ * comes first. Keeping the two functions adjacent in shape is what makes them
+ * diffable by eye.
+ */
+export function classifyReachability(entry, now = Date.now()) {
+    if (entry.status !== 'verified') {
+        return entry.status === 'unavailable' ? 'proven-dead' : 'never-verified';
+    }
+    // Model-specific park only — a provider-wide park deliberately does NOT
+    // exclude a proven model (the "Gemini parking bug").
+    const parkedUntil = entry.quotaParkedUntil ?? 0;
+    if (parkedUntil > now && entry.providerParked === false)
+        return 'parked';
+    const verifiedAt = entry.lastVerifiedAt ?? 0;
+    if (now - verifiedAt > DEFAULT_STALE_MS)
+        return 'proof-expired';
+    return 'routable';
+}
+/** How a state is worded. One place, so the page and any CLI cannot drift. */
+export const REACHABILITY_COPY = {
+    routable: {
+        label: 'Routable',
+        blurb: 'Verified within 7 days and not parked — the router can pick this now.',
+        color: '#3fb950',
+    },
+    parked: {
+        label: 'Parked',
+        blurb: 'Resting on a model-level quota window. It re-enters routing on its own when the window lapses.',
+        color: '#d29922',
+    },
+    'proof-expired': {
+        label: 'Proof expired',
+        blurb: 'Was verified, but not within the last 7 days, so the registry no longer offers it. A re-probe restores it.',
+        color: '#d29922',
+    },
+    'proven-dead': {
+        label: 'Proven dead',
+        blurb: 'A real call established this id does not work here — re-probing will not fix it.',
+        color: '#f85149',
+    },
+    'never-verified': {
+        label: 'Never verified',
+        blurb: 'The provider lists this id and nothing has ever been tried against it. This is an unknown, not a failure — ' +
+            'background spot-checks work through these a few at a time.',
+        color: '#58a6ff',
+    },
+};
+/** Would the router pick this model right now? The one question routing asks. */
+export function isRoutable(reachability) {
+    return reachability === 'routable';
+}
+/** Probe-age thresholds. Kept here so the numbers are stated once. */
+export const FRESH_DAYS = 7;
+export const REMOVED_DAYS = 30;
+/** Error rate above which a long-unprobed model reads as actually gone. */
+export const REMOVED_ERROR_RATE = 0.5;
+export function classifyFreshness(lastProbedAt, errorRate, now = Date.now()) {
+    if (!lastProbedAt)
+        return 'likely-removed';
+    const days = (now - lastProbedAt) / (24 * 60 * 60 * 1000);
+    if (days > REMOVED_DAYS && (errorRate ?? 0) > REMOVED_ERROR_RATE)
+        return 'likely-removed';
+    return days > FRESH_DAYS ? 'stale' : 'fresh';
+}
+/** How a freshness state is worded. */
+export const FRESHNESS_COPY = {
+    fresh: { label: 'Fresh', blurb: `Probed within ${FRESH_DAYS} days.`, color: '#3fb950' },
+    stale: { label: 'Stale', blurb: `Not probed for over ${FRESH_DAYS} days.`, color: '#d29922' },
+    'likely-removed': {
+        label: 'Likely removed',
+        blurb: `Not probed for over ${REMOVED_DAYS} days and failing — probably gone from the provider.`,
+        color: '#f85149',
+    },
+};
+//# sourceMappingURL=model-reachability.js.map

package/dist/learning/model-reachability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-reachability.js","sourceRoot":"","sources":["../../src/learning/model-reachability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AA8BvD;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAClC,KAAwB,EACxB,MAAc,IAAI,CAAC,GAAG,EAAE;IAExB,IAAI,KAAK,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;QAChC,OAAO,KAAK,CAAC,MAAM,KAAK,aAAa,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,gBAAgB,CAAC;IAC3E,CAAC;IACD,wEAAwE;IACxE,qDAAqD;IACrD,MAAM,WAAW,GAAG,KAAK,CAAC,gBAAgB,IAAI,CAAC,CAAC;IAChD,IAAI,WAAW,GAAG,GAAG,IAAI,KAAK,CAAC,cAAc,KAAK,KAAK;QAAE,OAAO,QAAQ,CAAC;IACzE,MAAM,UAAU,GAAG,KAAK,CAAC,cAAc,IAAI,CAAC,CAAC;IAC7C,IAAI,GAAG,GAAG,UAAU,GAAG,gBAAgB;QAAE,OAAO,eAAe,CAAC;IAChE,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,8EAA8E;AAC9E,MAAM,CAAC,MAAM,iBAAiB,GAA+E;IAC3G,QAAQ,EAAE;QACR,KAAK,EAAE,UAAU;QACjB,KAAK,EAAE,uEAAuE;QAC9E,KAAK,EAAE,SAAS;KACjB;IACD,MAAM,EAAE;QACN,KAAK,EAAE,QAAQ;QACf,KAAK,EAAE,gGAAgG;QACvG,KAAK,EAAE,SAAS;KACjB;IACD,eAAe,EAAE;QACf,KAAK,EAAE,eAAe;QACtB,KAAK,EAAE,4GAA4G;QACnH,KAAK,EAAE,SAAS;KACjB;IACD,aAAa,EAAE;QACb,KAAK,EAAE,aAAa;QACpB,KAAK,EAAE,kFAAkF;QACzF,KAAK,EAAE,SAAS;KACjB;IACD,gBAAgB,EAAE;QAChB,KAAK,EAAE,gBAAgB;QACvB,KAAK,EACH,6GAA6G;YAC7G,4DAA4D;QAC9D,KAAK,EAAE,SAAS;KACjB;CACF,CAAC;AAEF,iFAAiF;AACjF,MAAM,UAAU,UAAU,CAAC,YAA+B;IACxD,OAAO,YAAY,KAAK,UAAU,CAAC;AACrC,CAAC;AAWD,sEAAsE;AACtE,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC;AAC5B,MAAM,CAAC,MAAM,YAAY,GAAG,EAAE,CAAC;AAC/B,2EAA2E;AAC3E,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAG,CAAC;AAEtC,MAAM,UAAU,iBAAiB,CAC/B,YAAgC,EAChC,SAA6B,EAC7B,MAAc,IAAI,CAAC,GAAG,EAAE;IAExB,IAAI,CAAC,YAAY;QAAE,OAAO,gBAAgB,CAAC;IAC3C,MAAM,IAAI,GAAG,CAAC,GAAG,GAAG,YAAY,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;IAC1D,IAAI,IAAI,GAAG,YAAY,IAAI,CAAC,SAAS,IAAI,CAAC,CAAC,GAAG,kBAAkB;QAAE,OAAO,gBAAgB,CAAC;IAC1F,OAAO,IAAI,GAAG,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;AAC/C,CAAC;AAED,uCAAuC;AACvC,MAAM,CAAC,MAAM,cAAc,GAA4E;IACrG,KAAK,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,iBAAiB,UAAU,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE;IACvF,KAAK,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,uBAAuB,UAAU,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE;IAC7F,gBAAgB,EAAE;QAChB,KAAK,EAAE,gBAAgB;QACvB,KAAK,EAAE,uBAAuB,YAAY,sDAAsD;QAChG,KAAK,EAAE,SAAS;KACjB;CACF,CAAC"}

package/dist/learning/model-registry.d.ts

@@ -694,6 +694,28 @@ export declare class ModelRegistry {
     pruneAbsentModels(provider: string, liveModels: string[]): number;
     /** Load the JSON mirror synchronously (never throws). */
     private loadMirror;
+    /**
+     * Re-read the JSON mirror into memory — adopt what OTHER processes learned.
+     *
+     * The singleton loads the mirror exactly ONCE, in the constructor, and
+     * {@link persist} writes the WHOLE entry map from `this.data`. Those two facts
+     * together mean a long-lived process holds a snapshot of every model it never
+     * touched, and flushes that snapshot back over the file the moment it persists
+     * anything — silently reverting anything another process (the gateway, a CLI
+     * run, the warmup daemon) verified in the meantime.
+     *
+     * Callers that are about to spend a probe budget and persist should reload
+     * first so that `this.data` is as current as the file allows. The window does
+     * not close — a write from another process DURING a long run is still lost on
+     * this process's next persist — but it shrinks from "since this process booted"
+     * to "since this run started".
+     *
+     * DISCARDING, deliberately: this drops any in-memory change this process has
+     * made but not yet persisted. Every mutator on this class persists immediately,
+     * so there is normally nothing pending — but that is the contract that makes
+     * this safe, and it is why this is not called from arbitrary paths.
+     */
+    reloadFromMirror(): void;
     /**
      * Persist: JSON mirror synchronously (canonical, guaranteed), then mirror to
      * the VectorStore namespace asynchronously (best-effort, auto-tiers to JSON