agent-nuvira 3.5.0 → 3.5.2

package/dist/learning/duty-lease.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Duty leases — one holder per named background duty, across processes, with no
+ * daemon and no supervisor.
+ *
+ * THE PROBLEM. The background duties (the warmup sweep, the verify-next run,
+ * session-start checks) are all "one of these should happen periodically", and
+ * every process that starts is willing to do it. So two CLI runs, or a CLI run
+ * plus the dashboard, or a long-lived gateway plus a manual `models warm`, each
+ * spend the SAME free-tier budget on the SAME candidates — and a spot-check is a
+ * real generation, so the waste is measured in a provider's rate limit, not in
+ * CPU. In-process guards (`isRunning`) cannot see the other process at all.
+ *
+ * WHY A LEASE AND NOT A DAEMON. A daemon is the obvious shape and the wrong
+ * first step: it needs a supervisor, a way to be started, restarted, discovered
+ * and stopped, and it becomes a thing that can be RUNNING AND WRONG. A lease is
+ * the smallest primitive that removes the actual waste: exactly one process
+ * wins the exclusive create, everyone else steps aside, and the loser has a
+ * perfectly good fallback (do nothing — the work is throttled anyway). It is
+ * also the piece a daemon would need FIRST, so this is not throwaway work.
+ *
+ * HOW EXCLUSION WORKS. `open(path, 'wx')` is the atomic primitive: exactly one
+ * caller anywhere can win it. That is the whole mechanism — no pid liveness
+ * check, no registry service, no lock daemon.
+ *
+ * HOW CRASH RECOVERY WORKS, AND WHY IT IS THE mtime. A holder that is killed
+ * mid-duty leaves its lease file behind, and a lease that can never be taken is
+ * worse than no lease at all. So a lease whose mtime is older than `staleMs` is
+ * STOLEN: the stealer removes it and takes it, and reports `stole: true` so the
+ * event is visible rather than silent. `renewDutyLease` re-writes the file, which
+ * bumps that mtime, which is how a legitimately long duty (a warmup cycle can
+ * take minutes) keeps its lease while still being stealable if it dies.
+ *
+ * The pid is written for DIAGNOSTICS ONLY — "who held this" is the first
+ * question when a duty mysteriously stops running, and it is a question the
+ * user can answer from disk. It is deliberately NOT a correctness input: pid
+ * reuse makes "is this pid alive" an unsafe test (a fresh, unrelated process can
+ * hold the number), and the mtime is what actually decides.
+ *
+ * HONEST BOUNDS. Steal-after-stale means a crashed holder blocks its duty for at
+ * most `staleMs` — hence the default is minutes, not hours. Clock skew between
+ * two machines sharing a config dir shifts that window; it cannot make the
+ * exclusion unsafe, only early or late. Nothing here is a distributed lock:
+ * the config dir is one machine's, and the dashboard sidecar sharing it is the
+ * case this exists for.
+ */
+/**
+ * How long a lease may go un-renewed before it counts as a DEAD holder's and may
+ * be stolen (ms).
+ *
+ * Minutes, not hours, on purpose: this is the worst-case delay before a duty
+ * resumes after a crash, and the alternative — a lease that outlives its holder
+ * by hours — silently switches the duty off for the rest of the afternoon.
+ */
+export declare const DEFAULT_DUTY_LEASE_STALE_MS: number;
+/**
+ * Env override for {@link DEFAULT_DUTY_LEASE_STALE_MS}
+ * (`NUVIRA_DUTY_LEASE_STALE_MS`) — the same rule the warmup bounds follow: a
+ * test or an operator tunes the window without a source edit, and nonsense is
+ * ignored rather than arming a zero-second lease that would be stolen instantly.
+ */
+export declare function dutyLeaseStaleMs(env?: NodeJS.ProcessEnv): number;
+/** What a lease file holds. Everything here is either an input (mtime) or diagnostics. */
+export interface DutyLeaseInfo {
+    /** The duty name, e.g. `model-warmup`. */
+    name: string;
+    /** The holder's process id — DIAGNOSTICS ONLY (see the module header). */
+    pid: number;
+    /** The holder's host, so a shared config dir can say "another machine". */
+    host: string;
+    /** When the holder first took the lease (ms). */
+    startedAt: number;
+    /** When the holder last renewed it (ms) — mirrors the file's mtime, for reading. */
+    renewedAt: number;
+    /** Free-text: what the holder is doing, for the diagnostic readout. */
+    purpose?: string;
+}
+export interface DutyLeaseAcquireResult {
+    /** True when THIS process holds the lease on return. */
+    owned: boolean;
+    /** True when a stale lease had to be broken to get it — never silent. */
+    stole: boolean;
+    /** The lease that was in the way, when it was fresh and therefore respected. */
+    holder?: DutyLeaseInfo;
+}
+export interface DutyLeaseOptions {
+    /** Override the staleness window (ms). Defaults to {@link dutyLeaseStaleMs}. */
+    staleMs?: number;
+    /** Recorded in the lease, for the diagnostic readout. */
+    purpose?: string;
+    /** Clock seam (tests). */
+    now?: number;
+}
+/**
+ * Where leases live: `<memory dir>/duties/`.
+ *
+ * THE MEMORY DIR, NOT THE CONFIG DIR, and not by accident:
+ *
+ *   1. **The lease travels with the state it protects.** The duties this guards
+ *      (warmup, verify-next, session checks) mutate the model registry and the
+ *      verified pool, and those live in the memory dir. An isolated profile — a
+ *      test, a CI run, a sandbox — therefore gets its OWN leases instead of
+ *      contending with the developer's real CLI over one file in `~/.nuvira`.
+ *   2. **It cannot leak into a real profile from a test.**
+ *      `tests/setup/hermetic-env.ts` gives every test file a throwaway
+ *      `NUVIRA_MEMORY_DIR` and deliberately does NOT isolate the config dir (a
+ *      test that needs real credentials must keep working). A lease under the
+ *      memory dir is isolated by construction; one under the config dir would
+ *      have let `chat.ts`'s warmup start write `~/.nuvira/duties/*.lease` on
+ *      every chat test, which is exactly the leak class that harness exists to
+ *      stop — and worse, a real CLI holding that lease would have made the
+ *      test's daemon silently skip.
+ *
+ * `NUVIRA_DUTY_DIR` overrides it for a caller that wants its own namespace.
+ */
+export declare function dutyLeaseDir(): string;
+/** `<duty dir>/<name>.lease`. */
+export declare function dutyLeasePath(name: string): string;
+/** Read the lease without taking it (diagnostics/dashboard). Never throws. */
+export declare function readDutyLease(name: string): DutyLeaseInfo | undefined;
+/**
+ * Try to take a duty lease. Returns `owned: false` (with the holder, when it
+ * could be read) rather than throwing or waiting: every caller's correct
+ * response to a busy lease is "someone else has this", and waiting would make a
+ * background duty block a foreground command.
+ *
+ * Re-acquiring a lease THIS process already holds is idempotent and does NOT
+ * steal — a duty that runs twice in one process must not look like a crash
+ * recovery in the logs.
+ */
+export declare function acquireDutyLease(name: string, opts?: DutyLeaseOptions): DutyLeaseAcquireResult;
+/**
+ * Push a held lease's staleness window out. In-place write (NOT an atomic
+ * rename), so the file never blinks out of existence for a competing stealer,
+ * and the mtime bump is what a stealer actually reads.
+ *
+ * Returns false when this process does not hold the lease — a renewed lease it
+ * does not own would be a lie, and a long duty that quietly continued after
+ * being stolen would defeat the exclusion.
+ */
+export declare function renewDutyLease(name: string, opts?: {
+    now?: number;
+}): boolean;
+/**
+ * Give the lease up. Best-effort and never throws — a lease left behind expires
+ * by `staleMs`, which is exactly why that window exists.
+ *
+ * Refuses to release a lease this process does NOT hold: otherwise a process
+ * whose lease was stolen (because it hung) could finish and delete the new
+ * holder's lease, and two processes would then run the duty at once.
+ */
+export declare function releaseDutyLease(name: string): void;
+/**
+ * Run `fn` while holding `name`, or return `undefined` and run nothing when
+ * someone else holds it.
+ *
+ * The lease is released in a `finally`, so a throwing duty does not block the
+ * next one; a duty that CRASHES the process leaves the file behind, which is the
+ * case `staleMs` covers.
+ */
+export declare function withDutyLease<T>(name: string, fn: () => Promise<T>, opts?: DutyLeaseOptions & {
+    onWait?: (holder: DutyLeaseInfo | undefined) => void;
+}): Promise<T | undefined>;
+//# sourceMappingURL=duty-lease.d.ts.map

package/dist/learning/duty-lease.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"duty-lease.d.ts","sourceRoot":"","sources":["../../src/learning/duty-lease.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAOH;;;;;;;GAOG;AACH,eAAO,MAAM,2BAA2B,QAAgB,CAAC;AAEzD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAK7E;AAED,0FAA0F;AAC1F,MAAM,WAAW,aAAa;IAC5B,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,GAAG,EAAE,MAAM,CAAC;IACZ,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB,oFAAoF;IACpF,SAAS,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,sBAAsB;IACrC,wDAAwD;IACxD,KAAK,EAAE,OAAO,CAAC;IACf,yEAAyE;IACzE,KAAK,EAAE,OAAO,CAAC;IACf,gFAAgF;IAChF,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0BAA0B;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED,iCAAiC;AACjC,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAElD;AAiCD,8EAA8E;AAC9E,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CASrE;AAWD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,gBAAqB,GAAG,sBAAsB,CA8BlG;AAgCD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,OAAO,CAUjF;AAYD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAQnD;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAAC,CAAC,EACnC,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,IAAI,GAAE,gBAAgB,GAAG;IAAE,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,aAAa,GAAG,SAAS,KAAK,IAAI,CAAA;CAAO,GACrF,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAexB"}

package/dist/learning/duty-lease.js

@@ -0,0 +1,301 @@
+/**
+ * Duty leases — one holder per named background duty, across processes, with no
+ * daemon and no supervisor.
+ *
+ * THE PROBLEM. The background duties (the warmup sweep, the verify-next run,
+ * session-start checks) are all "one of these should happen periodically", and
+ * every process that starts is willing to do it. So two CLI runs, or a CLI run
+ * plus the dashboard, or a long-lived gateway plus a manual `models warm`, each
+ * spend the SAME free-tier budget on the SAME candidates — and a spot-check is a
+ * real generation, so the waste is measured in a provider's rate limit, not in
+ * CPU. In-process guards (`isRunning`) cannot see the other process at all.
+ *
+ * WHY A LEASE AND NOT A DAEMON. A daemon is the obvious shape and the wrong
+ * first step: it needs a supervisor, a way to be started, restarted, discovered
+ * and stopped, and it becomes a thing that can be RUNNING AND WRONG. A lease is
+ * the smallest primitive that removes the actual waste: exactly one process
+ * wins the exclusive create, everyone else steps aside, and the loser has a
+ * perfectly good fallback (do nothing — the work is throttled anyway). It is
+ * also the piece a daemon would need FIRST, so this is not throwaway work.
+ *
+ * HOW EXCLUSION WORKS. `open(path, 'wx')` is the atomic primitive: exactly one
+ * caller anywhere can win it. That is the whole mechanism — no pid liveness
+ * check, no registry service, no lock daemon.
+ *
+ * HOW CRASH RECOVERY WORKS, AND WHY IT IS THE mtime. A holder that is killed
+ * mid-duty leaves its lease file behind, and a lease that can never be taken is
+ * worse than no lease at all. So a lease whose mtime is older than `staleMs` is
+ * STOLEN: the stealer removes it and takes it, and reports `stole: true` so the
+ * event is visible rather than silent. `renewDutyLease` re-writes the file, which
+ * bumps that mtime, which is how a legitimately long duty (a warmup cycle can
+ * take minutes) keeps its lease while still being stealable if it dies.
+ *
+ * The pid is written for DIAGNOSTICS ONLY — "who held this" is the first
+ * question when a duty mysteriously stops running, and it is a question the
+ * user can answer from disk. It is deliberately NOT a correctness input: pid
+ * reuse makes "is this pid alive" an unsafe test (a fresh, unrelated process can
+ * hold the number), and the mtime is what actually decides.
+ *
+ * HONEST BOUNDS. Steal-after-stale means a crashed holder blocks its duty for at
+ * most `staleMs` — hence the default is minutes, not hours. Clock skew between
+ * two machines sharing a config dir shifts that window; it cannot make the
+ * exclusion unsafe, only early or late. Nothing here is a distributed lock:
+ * the config dir is one machine's, and the dashboard sidecar sharing it is the
+ * case this exists for.
+ */
+import { closeSync, mkdirSync, openSync, readFileSync, rmSync, statSync, writeSync } from 'node:fs';
+import { hostname } from 'node:os';
+import { dirname, join } from 'node:path';
+import { envBuff, resolveNuviraHome } from '../config/paths.js';
+/**
+ * How long a lease may go un-renewed before it counts as a DEAD holder's and may
+ * be stolen (ms).
+ *
+ * Minutes, not hours, on purpose: this is the worst-case delay before a duty
+ * resumes after a crash, and the alternative — a lease that outlives its holder
+ * by hours — silently switches the duty off for the rest of the afternoon.
+ */
+export const DEFAULT_DUTY_LEASE_STALE_MS = 5 * 60 * 1000;
+/**
+ * Env override for {@link DEFAULT_DUTY_LEASE_STALE_MS}
+ * (`NUVIRA_DUTY_LEASE_STALE_MS`) — the same rule the warmup bounds follow: a
+ * test or an operator tunes the window without a source edit, and nonsense is
+ * ignored rather than arming a zero-second lease that would be stolen instantly.
+ */
+export function dutyLeaseStaleMs(env = process.env) {
+    const raw = env.NUVIRA_DUTY_LEASE_STALE_MS;
+    if (raw === undefined || raw.trim() === '')
+        return DEFAULT_DUTY_LEASE_STALE_MS;
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : DEFAULT_DUTY_LEASE_STALE_MS;
+}
+/**
+ * Where leases live: `<memory dir>/duties/`.
+ *
+ * THE MEMORY DIR, NOT THE CONFIG DIR, and not by accident:
+ *
+ *   1. **The lease travels with the state it protects.** The duties this guards
+ *      (warmup, verify-next, session checks) mutate the model registry and the
+ *      verified pool, and those live in the memory dir. An isolated profile — a
+ *      test, a CI run, a sandbox — therefore gets its OWN leases instead of
+ *      contending with the developer's real CLI over one file in `~/.nuvira`.
+ *   2. **It cannot leak into a real profile from a test.**
+ *      `tests/setup/hermetic-env.ts` gives every test file a throwaway
+ *      `NUVIRA_MEMORY_DIR` and deliberately does NOT isolate the config dir (a
+ *      test that needs real credentials must keep working). A lease under the
+ *      memory dir is isolated by construction; one under the config dir would
+ *      have let `chat.ts`'s warmup start write `~/.nuvira/duties/*.lease` on
+ *      every chat test, which is exactly the leak class that harness exists to
+ *      stop — and worse, a real CLI holding that lease would have made the
+ *      test's daemon silently skip.
+ *
+ * `NUVIRA_DUTY_DIR` overrides it for a caller that wants its own namespace.
+ */
+export function dutyLeaseDir() {
+    return envBuff('DUTY_DIR') || join(envBuff('MEMORY_DIR') || join(resolveNuviraHome(), 'memory'), 'duties');
+}
+/** `<duty dir>/<name>.lease`. */
+export function dutyLeasePath(name) {
+    return join(dutyLeaseDir(), `${safeName(name)}.lease`);
+}
+/**
+ * Keep a duty name path-safe. The names are internal constants, but a lease
+ * whose path was derived from an arbitrary string could be pointed anywhere.
+ */
+function safeName(name) {
+    return name.replace(/[^a-zA-Z0-9._-]/g, '_');
+}
+function leaseDir(name) {
+    return dirname(dutyLeasePath(name));
+}
+/**
+ * This machine's label, defensively.
+ *
+ * `hostname()` is diagnostics, so it must never be able to fail an acquisition —
+ * and it CAN be absent: a test that mocks `node:os` for `homedir()` (the duties
+ * suite does exactly that) replaces the whole module, and a bare `hostname()`
+ * then throws inside the take and reads as "someone else holds it". The lease
+ * would go silently unused, which is the failure mode this module exists to
+ * prevent. A missing host therefore degrades to a shared label, and same-process
+ * detection still works off the pid.
+ */
+function hostLabel() {
+    try {
+        return hostname() || 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/** Read the lease without taking it (diagnostics/dashboard). Never throws. */
+export function readDutyLease(name) {
+    try {
+        const parsed = JSON.parse(readFileSync(dutyLeasePath(name), 'utf-8'));
+        if (!parsed || typeof parsed !== 'object')
+            return undefined;
+        return parsed;
+    }
+    catch {
+        // Absent or corrupt: from a reader's point of view both mean "no lease".
+        return undefined;
+    }
+}
+/** Age of a lease file (ms), or `undefined` when there is no readable file. */
+function leaseAgeMs(name, now) {
+    try {
+        return Math.max(0, now - statSync(dutyLeasePath(name)).mtimeMs);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Try to take a duty lease. Returns `owned: false` (with the holder, when it
+ * could be read) rather than throwing or waiting: every caller's correct
+ * response to a busy lease is "someone else has this", and waiting would make a
+ * background duty block a foreground command.
+ *
+ * Re-acquiring a lease THIS process already holds is idempotent and does NOT
+ * steal — a duty that runs twice in one process must not look like a crash
+ * recovery in the logs.
+ */
+export function acquireDutyLease(name, opts = {}) {
+    const now = opts.now ?? Date.now();
+    const staleMs = opts.staleMs ?? dutyLeaseStaleMs();
+    // 1. The atomic take: exactly one caller can win an exclusive create.
+    if (tryCreate(name, opts.purpose, now))
+        return { owned: true, stole: false };
+    // 2. Someone holds it. Is it the SAME process? Then this is not a contention,
+    //    it is us asking twice.
+    const existing = readDutyLease(name);
+    if (existing && existing.host === hostLabel() && existing.pid === process.pid) {
+        return { owned: true, stole: false };
+    }
+    // 3. Is it too old to belong to a live call? Then it is a dead holder's, and
+    //    a lease nobody can take would switch the duty off forever.
+    const age = leaseAgeMs(name, now);
+    if (age !== undefined && age > staleMs) {
+        try {
+            rmSync(dutyLeasePath(name), { force: true });
+        }
+        catch {
+            // Lost the race to break it — fall through to the retry and let the
+            // exclusive create decide the winner.
+        }
+        if (tryCreate(name, opts.purpose, now))
+            return { owned: true, stole: true };
+        // Another process re-took it between the break and our retry: respect it.
+        return { owned: false, stole: false, holder: readDutyLease(name) };
+    }
+    return { owned: false, stole: false, holder: existing };
+}
+/** The exclusive-create step, in one place so both callers share it. */
+function tryCreate(name, purpose, now) {
+    try {
+        mkdirSync(leaseDir(name), { recursive: true });
+    }
+    catch {
+        // A failing mkdir surfaces as a failing create below, which is the honest
+        // "we do not own the lease" answer.
+    }
+    try {
+        const fd = openSync(dutyLeasePath(name), 'wx');
+        try {
+            const info = {
+                name,
+                pid: process.pid,
+                host: hostLabel(),
+                startedAt: now,
+                renewedAt: now,
+                ...(purpose ? { purpose } : {}),
+            };
+            writeSync(fd, `${JSON.stringify(info, null, 2)}\n`);
+        }
+        finally {
+            closeSync(fd);
+        }
+        return true;
+    }
+    catch {
+        // EEXIST (someone else won it) or an unusable directory — either way, not ours.
+        return false;
+    }
+}
+/**
+ * Push a held lease's staleness window out. In-place write (NOT an atomic
+ * rename), so the file never blinks out of existence for a competing stealer,
+ * and the mtime bump is what a stealer actually reads.
+ *
+ * Returns false when this process does not hold the lease — a renewed lease it
+ * does not own would be a lie, and a long duty that quietly continued after
+ * being stolen would defeat the exclusion.
+ */
+export function renewDutyLease(name, opts = {}) {
+    const existing = readDutyLease(name);
+    if (!existing || existing.host !== hostLabel() || existing.pid !== process.pid)
+        return false;
+    try {
+        const renewed = { ...existing, renewedAt: opts.now ?? Date.now() };
+        writeFileInPlace(dutyLeasePath(name), `${JSON.stringify(renewed, null, 2)}\n`);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Truncate-and-write in place, so the path is never absent mid-renewal. */
+function writeFileInPlace(path, content) {
+    const fd = openSync(path, 'w');
+    try {
+        writeSync(fd, content);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/**
+ * Give the lease up. Best-effort and never throws — a lease left behind expires
+ * by `staleMs`, which is exactly why that window exists.
+ *
+ * Refuses to release a lease this process does NOT hold: otherwise a process
+ * whose lease was stolen (because it hung) could finish and delete the new
+ * holder's lease, and two processes would then run the duty at once.
+ */
+export function releaseDutyLease(name) {
+    const existing = readDutyLease(name);
+    if (existing && !(existing.host === hostLabel() && existing.pid === process.pid))
+        return;
+    try {
+        rmSync(dutyLeasePath(name), { force: true });
+    }
+    catch {
+        /* a lock left behind expires by `staleMs` */
+    }
+}
+/**
+ * Run `fn` while holding `name`, or return `undefined` and run nothing when
+ * someone else holds it.
+ *
+ * The lease is released in a `finally`, so a throwing duty does not block the
+ * next one; a duty that CRASHES the process leaves the file behind, which is the
+ * case `staleMs` covers.
+ */
+export async function withDutyLease(name, fn, opts = {}) {
+    const taken = acquireDutyLease(name, opts);
+    if (!taken.owned) {
+        try {
+            opts.onWait?.(taken.holder);
+        }
+        catch {
+            // Diagnostics must never break the caller.
+        }
+        return undefined;
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        releaseDutyLease(name);
+    }
+}
+//# sourceMappingURL=duty-lease.js.map

package/dist/learning/duty-lease.js.map

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

package/dist/learning/model-first-router.d.ts

@@ -125,6 +125,20 @@ export declare function buildFailoverChain(bestCandidate: ModelCandidate, allCan
 export type CapabilityTier = 'high' | 'medium' | 'low' | 'local';
 /**
  * Classify a model into a capability tier.
+ *
+ * TWO AXES, and they are different questions:
+ *   1. WHERE the model runs — a keyless local runner (`local`, `lmstudio`,
+ *      `vllm`) is the LAST resort whatever its size, so it keeps its own tier.
+ *   2. HOW MUCH it can do — `model-capability` bands, name-derived and
+ *      deterministic, the SAME bands the pinned-handoff repair, the local
+ *      last-resort pick and the router's capability floors already use.
+ *
+ * The band used to come from this module's own `capabilityFit` dimension, a
+ * task-relative score: a fast small model fits a trivial task well, so it read
+ * `high` HERE and `low` to everything else — two taxonomies for one fact, and
+ * the reason a 0.5B and a 120B could land in the same tier. `capabilityFit`
+ * still decides the candidate ORDER (it is the task fit); it no longer decides
+ * the BAND.
  */
 export declare function classifyTier(candidate: ModelCandidate): CapabilityTier;
 /**

package/dist/learning/model-first-router.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"model-first-router.d.ts","sourceRoot":"","sources":["../../src/learning/model-first-router.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"model-first-router.d.ts","sourceRoot":"","sources":["../../src/learning/model-first-router.ts"],"names":[],"mappings":"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"}

package/dist/learning/model-first-router.js

@@ -21,6 +21,13 @@ import { getCatalogProvider, CATALOG_PROVIDER_IDS } from '../inference/provider-
 import { isSmallTalk } from './hybrid-router.js';
 import { hasCredentials, isPairPlausible } from './model-selection.js';
 export { isPairPlausible };
+// ONE capability taxonomy. The tier below used to be computed from this
+// module's OWN `capabilityFit` score while every other decision (pinned
+// handoffs, the local last resort, the router's band checks) used
+// `model-capability` bands — two taxonomies, so the same pair could be
+// `medium` on one path and `low` on another, which is how a 0.5B and a 120B
+// ended up as "same tier".
+import { capabilityClassOf, estimateModelCapability } from './model-capability.js';
 import { isNonChatModel } from '../inference/model-catalog.js';
 // ─── Task Analysis ──────────────────────────────────────────────────────────
 /**
@@ -434,16 +441,41 @@ export function buildFailoverChain(bestCandidate, allCandidates) {
 }
 /**
  * Classify a model into a capability tier.
+ *
+ * TWO AXES, and they are different questions:
+ *   1. WHERE the model runs — a keyless local runner (`local`, `lmstudio`,
+ *      `vllm`) is the LAST resort whatever its size, so it keeps its own tier.
+ *   2. HOW MUCH it can do — `model-capability` bands, name-derived and
+ *      deterministic, the SAME bands the pinned-handoff repair, the local
+ *      last-resort pick and the router's capability floors already use.
+ *
+ * The band used to come from this module's own `capabilityFit` dimension, a
+ * task-relative score: a fast small model fits a trivial task well, so it read
+ * `high` HERE and `low` to everything else — two taxonomies for one fact, and
+ * the reason a 0.5B and a 120B could land in the same tier. `capabilityFit`
+ * still decides the candidate ORDER (it is the task fit); it no longer decides
+ * the BAND.
  */
 export function classifyTier(candidate) {
     if (candidate.provider === 'local' || candidate.provider === 'lmstudio' || candidate.provider === 'vllm') {
         return 'local';
     }
-    if (candidate.dimensions.capabilityFit >= 0.8)
-        return 'high';
-    if (candidate.dimensions.capabilityFit >= 0.5)
-        return 'medium';
-    return 'low';
+    return capabilityClassOf(candidate.model);
+}
+/**
+ * Order the candidates of ONE tier strongest-first, stable within equal
+ * capability (so the scorer's task fit still decides among equals).
+ *
+ * WHY, and why here: the tiers were ordered by the scorer, which is a HEALTH-
+ * AND-COST ranking, and a small model wins that ranking precisely because it is
+ * fast and cheap. Inside a tier that is the wrong question — the tier already
+ * said "these are equally suitable", so the strongest must go first. MEASURED
+ * (trace-1791879575576-x731yp): the LOCAL tier is where it bit, because a local
+ * tier holds every local model from a 0.5B to a 120B and nothing ranked them by
+ * size, so the agentic ask was answered by the weakest one on the machine.
+ */
+function strongestFirstInTier(candidates) {
+    return [...candidates].sort((a, b) => estimateModelCapability(b.model) - estimateModelCapability(a.model));
 }
 /**
  * Check if a model candidate has available quota (not parked, not blocked).
@@ -500,11 +532,12 @@ export function buildTieredFailoverChain(bestCandidate, allCandidates) {
         });
         sameModelDifferentProvider.forEach(c => tried.add(`${c.provider}:${c.model}`));
     }
-    // Phase 2: Same capability tier, different models (pre-check quota)
-    const sameTier = allCandidates.filter(c => classifyTier(c) === bestTier
+    // Phase 2: Same capability tier, different models (pre-check quota).
+    // STRONGEST-FIRST within the tier — see `strongestFirstInTier`.
+    const sameTier = strongestFirstInTier(allCandidates.filter(c => classifyTier(c) === bestTier
         && c.model !== bestCandidate.model
         && !tried.has(`${c.provider}:${c.model}`)
-        && isCandidateAvailable(c));
+        && isCandidateAvailable(c)));
     if (sameTier.length > 0) {
         tiers.push({
             phase: 'same-tier',
@@ -518,9 +551,9 @@ export function buildTieredFailoverChain(bestCandidate, allCandidates) {
         : bestTier === 'medium' ? ['high']
             : [];
     for (const tier of higherTiers) {
-        const escalation = allCandidates.filter(c => classifyTier(c) === tier
+        const escalation = strongestFirstInTier(allCandidates.filter(c => classifyTier(c) === tier
             && !tried.has(`${c.provider}:${c.model}`)
-            && isCandidateAvailable(c));
+            && isCandidateAvailable(c)));
         if (escalation.length > 0) {
             tiers.push({
                 phase: 'escalate',
@@ -535,9 +568,9 @@ export function buildTieredFailoverChain(bestCandidate, allCandidates) {
         : bestTier === 'medium' ? ['low']
             : [];
     for (const tier of lowerTiers) {
-        const deescalation = allCandidates.filter(c => classifyTier(c) === tier
+        const deescalation = strongestFirstInTier(allCandidates.filter(c => classifyTier(c) === tier
             && !tried.has(`${c.provider}:${c.model}`)
-            && isCandidateAvailable(c));
+            && isCandidateAvailable(c)));
         if (deescalation.length > 0) {
             tiers.push({
                 phase: 'de-escalate',
@@ -547,9 +580,13 @@ export function buildTieredFailoverChain(bestCandidate, allCandidates) {
             deescalation.forEach(c => tried.add(`${c.provider}:${c.model}`));
         }
     }
-    // Phase 5: Local models (always available, last resort before neural)
-    const localModels = allCandidates.filter(c => classifyTier(c) === 'local'
-        && !tried.has(`${c.provider}:${c.model}`));
+    // Phase 5: Local models (always available, last resort before neural).
+    // STRONGEST-FIRST is the whole point of this phase: the local tier is a
+    // single tier by necessity (keyless, no quota, no account), so without this
+    // the weakest model on the machine — the one that wins a health ranking for
+    // being fast — is what an agentic ask lands on.
+    const localModels = strongestFirstInTier(allCandidates.filter(c => classifyTier(c) === 'local'
+        && !tried.has(`${c.provider}:${c.model}`)));
     if (localModels.length > 0) {
         tiers.push({
             phase: 'local',
@@ -559,8 +596,8 @@ export function buildTieredFailoverChain(bestCandidate, allCandidates) {
         localModels.forEach(c => tried.add(`${c.provider}:${c.model}`));
     }
     // Phase 6: Any remaining available models (last resort)
-    const remaining = allCandidates.filter(c => !tried.has(`${c.provider}:${c.model}`)
-        && isCandidateAvailable(c));
+    const remaining = strongestFirstInTier(allCandidates.filter(c => !tried.has(`${c.provider}:${c.model}`)
+        && isCandidateAvailable(c)));
     if (remaining.length > 0) {
         tiers.push({
             phase: 'remaining',