@crouton-kit/crouter 0.3.78 → 0.3.79

package/dist/core/runtime/recap.js

@@ -4,7 +4,7 @@
 // One entry point: generateRecap — async (execFile, non-blocking), mirroring
 // naming.ts's headless-`pi -p` pattern exactly. It runs the live conversation's
 // working model over the literal back-and-forth (the caller concatenates user and
-// assistant text) with a stripped-
+// assistant text, plus the node's roadmap when one exists) with a stripped-
 // down pi invocation (no tools/session/context/extensions/skills), so it's fast
 // and side-effect free and can never recurse into another spawn.
 //
@@ -24,30 +24,49 @@ const RECAP_TIMEOUT_MS = 25_000;
  *  turn, avoiding a dead hard-pinned provider. CRTR_RECAP_MODEL overrides both. */
 const DEFAULT_RECAP_MODEL = 'anthropic/claude-haiku-4-5';
 const RECAP_SYSTEM_PROMPT = 'You brief a developer returning to a paused coding-agent conversation. They run ' +
-    'many agent sessions in parallel and have lost this one\'s thread; the brief is ' +
-    'pinned above their input box and must re-orient them in seconds, without ' +
-    're-reading the transcript. You are given the literal user/agent back-and-forth ' +
-    '(tool output omitted, most recent last).\n' +
+    'many agent sessions in parallel and have lost this one\'s thread: they no longer ' +
+    'know what this conversation is about or what they originally asked for. The ' +
+    'brief exists to solve exactly that — pinned above their input box, it must tell ' +
+    'them at a glance what this conversation is FOR and where it actually stands. ' +
+    'You are given the first and most recent messages of the literal user/agent ' +
+    'back-and-forth (tool output omitted), and the agent\'s roadmap file when one ' +
+    'exists.\n' +
     '\n' +
-    'Output EXACTLY one concise plain-text briefing: no labels, numbering, bullets, ' +
-    'or line breaks. In one or two sentences, explain the overall goal, what has ' +
-    'actually happened, and the current next move or blocker. If the agent is ' +
-    'waiting on the developer, make the needed answer clear. Be concrete: use the ' +
-    'actual file names, commands, branches, option labels, and error messages from ' +
-    'the conversation — a developer re-orients on specifics, never abstractions. ' +
-    'Weight the end of the conversation, never narrate ("the user asked…"), hedge, ' +
-    'or pad. If the conversation has barely started, still emit your best briefing. ' +
-    'Output JUST the briefing.';
-/** Put the conversation FIRST in a delimited block, then the instruction, so the
- *  model reads the content before being told what to do. */
-function recapUserPrompt(conversation) {
-    return `<conversation>\n${conversation}\n</conversation>\n\nWrite the concise returning-developer briefing for the conversation above. Output JUST the briefing.`;
+    'Output EXACTLY two plain-text lines, nothing else:\n' +
+    'Goal: <what was requested — the original ask / what this conversation is for>\n' +
+    'State: <catch-them-up: what is ACTUALLY going on right now>\n' +
+    '\n' +
+    'Both lines are extremely short — telegraphic fragments, roughly 8-15 words, no ' +
+    'filler. The State line must NOT restate the most recent message — the last ' +
+    'message is often mid-progress, a question, or noise; instead synthesize the ' +
+    'real position: what has landed, what is in flight, and the live blocker or ' +
+    'needed answer. If the agent is waiting on the developer, say exactly what for. ' +
+    'Be concrete (real file names, branches, SHAs, error messages — one specific ' +
+    'anchor beats abstractions). Never narrate turn by turn, hedge, or pad. If the ' +
+    'conversation has barely started, still emit your best two lines.\n' +
+    '\n' +
+    'Examples of the shape (from other conversations):\n' +
+    'Goal: Validate + commit the Unit 3 attach-keybinding migration in this worktree.\n' +
+    'State: Done — 17/17 tests green, committed and rebased onto main.\n' +
+    '\n' +
+    'Goal: Build the trimmed-v1 command-plugin seam (orchestrating phases).\n' +
+    'State: Phase 1 landed; waiting on the core-seam worker\'s final.\n' +
+    '\n' +
+    'Goal: Standing personal assistant — iMessage wakes, Reddit scans, small tasks.\n' +
+    'State: Idle — waiting on you: hook pick, map export, Omi timing.';
+/** Put the content FIRST in delimited blocks (roadmap, then conversation), then
+ *  the instruction, so the model reads the content before being told what to do. */
+function recapUserPrompt(conversation, roadmap) {
+    const rm = roadmap !== undefined && roadmap.trim() !== ''
+        ? `<roadmap>\n${roadmap.trim()}\n</roadmap>\n\n`
+        : '';
+    return `${rm}<conversation>\n${conversation}\n</conversation>\n\nWrite the two-line Goal:/State: briefing for the conversation above. Output JUST the two lines.`;
 }
 /** The pi argv for a headless recap request. Stripped down (no tools, session,
  *  context files, extensions, skills, templates, themes) so it's fast and
  *  side-effect free. Thinking stays off; model precedence is explicit env
  *  override → the conversation's live working model → the small fallback. */
-function recapArgs(conversation, liveModel) {
+function recapArgs(conversation, liveModel, roadmap) {
     const override = process.env['CRTR_RECAP_MODEL'];
     // An explicit operator override wins. Otherwise prefer the live conversation's
     // current model: it just completed a successful turn, while a hard-pinned
@@ -71,14 +90,20 @@ function recapArgs(conversation, liveModel) {
         '--thinking', 'off',
         '--model', model,
         '--system-prompt', RECAP_SYSTEM_PROMPT,
-        recapUserPrompt(conversation),
+        recapUserPrompt(conversation, roadmap),
     ];
     return argv;
 }
-/** Normalize model stdout to one display string. Newlines are whitespace rather
- *  than separate fields; the viewer wraps this string to its available width. */
+/** Normalize model stdout to the two-line `Goal:`/`State:` briefing. Collapses
+ *  intra-line whitespace and drops blank lines; the viewer paints each line
+ *  (wrapping to its width). A garbled shape still returns whatever lines came
+ *  back — the widget is best-effort chrome, not a contract. */
 function parseRecap(stdout) {
-    return stdout.replace(/\s+/g, ' ').trim();
+    return stdout
+        .split('\n')
+        .map((l) => l.replace(/\s+/g, ' ').trim())
+        .filter((l) => l !== '')
+        .join('\n');
 }
 /** Ask pi headlessly for a concise briefing of `conversation`, async. Invokes
  *  `onRecap` with the parsed string on success, or never (silent) on any
@@ -87,12 +112,12 @@ function parseRecap(stdout) {
  *  and execFile's default stdin is an OPEN pipe that never closes, so without
  *  this pi blocks waiting for EOF and the call exits non-zero (the same gotcha
  *  naming.ts documents). */
-export function generateRecap(conversation, onRecap, liveModel) {
+export function generateRecap(conversation, onRecap, liveModel, roadmap) {
     const body = (conversation ?? '').trim();
     if (body === '')
         return;
     try {
-        const child = execFile(process.execPath, [resolveBundledPiCliPath(), ...recapArgs(body, liveModel)], { encoding: 'utf8', timeout: RECAP_TIMEOUT_MS, env: bundledPiSubprocessEnv() }, (err, stdout) => {
+        const child = execFile(process.execPath, [resolveBundledPiCliPath(), ...recapArgs(body, liveModel, roadmap)], { encoding: 'utf8', timeout: RECAP_TIMEOUT_MS, env: bundledPiSubprocessEnv() }, (err, stdout) => {
             if (err || typeof stdout !== 'string')
                 return; // silent — no recap
             const briefing = parseRecap(stdout);

package/dist/core/runtime/session-list-cache.d.ts

@@ -10,13 +10,23 @@ export declare class SessionListCache {
     private loaded;
     private persisting;
     private persistAgain;
+    private persistTimer;
     constructor(cacheFile: string);
+    /** Fire-and-forget warm of the cwd scope at broker start, so the first
+     *  `/resume` open after this broker launches is already warm. The cold scan
+     *  streams each file via readline (yields per chunk), so it never blocks the
+     *  broker loop — pre-warming beats worker threads here. Errors are swallowed
+     *  by the same paths that guard a normal open. */
+    prewarm(sessionDir: string): void;
     /** Sessions for one cwd's session dir (the picker's default `cwd` scope). */
     listDir(sessionDir: string): Promise<WireSessionInfo[]>;
     /** Sessions across every cwd's dir under the sessions root (`all` scope). */
     listAll(sessionsRoot: string): Promise<WireSessionInfo[]>;
     private build;
     private ensureLoaded;
+    /** Coalesce persists onto a single trailing timer so the tens-of-MB
+     *  `JSON.stringify` never runs on the reply path and rapid opens write once. */
+    private schedulePersist;
     /** Atomic write (temp + rename) so a concurrent reader never sees a partial
      *  file. Coalesces overlapping writes into one trailing flush. */
     private persist;

package/dist/core/runtime/session-list-cache.js

@@ -17,9 +17,9 @@
 // file's info without re-reading the whole corpus is to reproduce its parse.
 // Keep it in sync with pi's session-file format (CURRENT_SESSION_VERSION).
 import { createReadStream } from 'node:fs';
-import { readFile, readdir, rename, stat, writeFile } from 'node:fs/promises';
+import { readFile, readdir, rename, stat, unlink, writeFile } from 'node:fs/promises';
 import { createInterface } from 'node:readline';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 /** Search-text bound: `allMessagesText` is searched on every query edit; pi's
  *  unbounded value retains gigabytes in the viewer and turns key-repeat into GC
  *  jitter. The opening and latest text keep search useful. */
@@ -31,6 +31,29 @@ export function compactSessionSearchText(text) {
     return `${text.slice(0, half)} … ${text.slice(-half)}`;
 }
 const MAX_CONCURRENT_INFO_LOADS = 10;
+/** Persisted-file schema version. Bump whenever `CacheEntry`'s shape (or
+ *  `WireSessionInfo`'s) changes: on a version mismatch the whole file is
+ *  discarded and rebuilt from disk — no per-entry migration, no lenient
+ *  recovery (the cache is fully derivable). */
+const CACHE_SCHEMA_VERSION = 1;
+/** The full map is tens of MB (~15 MB for one cwd, ~46 MB for `all`); a
+ *  synchronous `JSON.stringify` of it must never sit on the reply path. Persists
+ *  are coalesced onto this trailing timer so rapid opens write at most once per
+ *  window, off the hot path. */
+const PERSIST_DEBOUNCE_MS = 2000;
+/** Shape-check a loaded entry — a well-formed-JSON file with the right version
+ *  but a stale entry shape (e.g. missing `info`) would otherwise push undefined
+ *  into the sort and throw. Any failure discards the whole file (rebuild). */
+function isValidEntry(e) {
+    if (typeof e !== 'object' || e === null)
+        return false;
+    const c = e;
+    return (typeof c['mtimeMs'] === 'number' &&
+        typeof c['size'] === 'number' &&
+        typeof c['info'] === 'object' &&
+        c['info'] !== null &&
+        typeof c['info']['modified'] === 'string');
+}
 // ---- faithful mirror of pi's private buildSessionInfo -----------------------
 function parseLine(line) {
     if (!line.trim())
@@ -152,12 +175,21 @@ export class SessionListCache {
     loaded = false;
     persisting = false;
     persistAgain = false;
+    persistTimer = null;
     constructor(cacheFile) {
         this.cacheFile = cacheFile;
     }
+    /** Fire-and-forget warm of the cwd scope at broker start, so the first
+     *  `/resume` open after this broker launches is already warm. The cold scan
+     *  streams each file via readline (yields per chunk), so it never blocks the
+     *  broker loop — pre-warming beats worker threads here. Errors are swallowed
+     *  by the same paths that guard a normal open. */
+    prewarm(sessionDir) {
+        void this.listDir(sessionDir);
+    }
     /** Sessions for one cwd's session dir (the picker's default `cwd` scope). */
     async listDir(sessionDir) {
-        return this.build(await jsonlFiles(sessionDir));
+        return this.build(await jsonlFiles(sessionDir), new Set([sessionDir]));
     }
     /** Sessions across every cwd's dir under the sessions root (`all` scope). */
     async listAll(sessionsRoot) {
@@ -173,32 +205,44 @@ export class SessionListCache {
         const files = [];
         for (const dir of dirEntries)
             files.push(...(await jsonlFiles(dir)));
-        return this.build(files);
+        return this.build(files, new Set(dirEntries));
     }
-    async build(files) {
+    async build(files, scannedDirs) {
         await this.ensureLoaded();
         const present = new Set(files);
+        let changed = false;
+        // Prune ONLY keys under the dirs we actually scanned. A cwd-scope open must
+        // not evict other cwds' cached entries: they weren't rescanned, so their
+        // absence from `files` says nothing about whether they still exist on disk.
+        // (Pruning the whole map here would self-destruct the global/`all` cache on
+        // every cwd open.)
         for (const key of this.cache.keys()) {
-            if (!present.has(key))
+            if (!present.has(key) && scannedDirs.has(dirname(key))) {
                 this.cache.delete(key);
+                changed = true;
+            }
         }
-        const infos = [];
-        let changed = false;
+        // Positioned by file index so equal-`modified` ties keep readdir order
+        // deterministically (workers finish out of order); a stable sort preserves it.
+        const infos = new Array(files.length);
         let next = 0;
         const worker = async () => {
-            while (next < files.length) {
-                const file = files[next++];
+            for (;;) {
+                const i = next++;
+                if (i >= files.length)
+                    return;
+                const file = files[i];
                 if (file === undefined)
                     return;
                 const st = await stat(file).catch(() => null);
                 if (!st) {
-                    this.cache.delete(file);
-                    changed = true;
+                    if (this.cache.delete(file))
+                        changed = true;
                     continue;
                 }
                 const cached = this.cache.get(file);
                 if (cached && cached.mtimeMs === st.mtimeMs && cached.size === st.size) {
-                    infos.push(cached.info);
+                    infos[i] = cached.info;
                     continue;
                 }
                 const info = await buildWireSessionInfo(file);
@@ -208,14 +252,15 @@ export class SessionListCache {
                     continue;
                 }
                 this.cache.set(file, { mtimeMs: st.mtimeMs, size: st.size, info });
-                infos.push(info);
+                infos[i] = info;
             }
         };
         await Promise.all(Array.from({ length: Math.min(MAX_CONCURRENT_INFO_LOADS, files.length) }, () => worker()));
         if (changed)
-            void this.persist();
-        infos.sort((a, b) => new Date(b.modified).getTime() - new Date(a.modified).getTime());
-        return infos;
+            this.schedulePersist();
+        const result = infos.filter((x) => x !== undefined);
+        result.sort((a, b) => new Date(b.modified).getTime() - new Date(a.modified).getTime());
+        return result;
     }
     async ensureLoaded() {
         if (this.loaded)
@@ -223,15 +268,35 @@ export class SessionListCache {
         this.loaded = true;
         try {
             const raw = JSON.parse(await readFile(this.cacheFile, 'utf8'));
-            for (const [path, entry] of Object.entries(raw))
+            // Version mismatch or shape drift → discard and rebuild. No lenient
+            // multi-path recovery: the cache is derivable, so a bad file is just
+            // overwritten on the next persist.
+            if (raw?.version !== CACHE_SCHEMA_VERSION || typeof raw.entries !== 'object')
+                return;
+            for (const [path, entry] of Object.entries(raw.entries)) {
+                if (!isValidEntry(entry)) {
+                    this.cache.clear();
+                    return;
+                }
                 this.cache.set(path, entry);
+            }
         }
         catch {
-            // Missing or corrupt cache file → start empty and rebuild. No lenient
-            // multi-path recovery: the cache is derivable, so a bad file is just
-            // overwritten on the next persist.
+            // Missing or corrupt cache file → start empty and rebuild.
+            this.cache.clear();
         }
     }
+    /** Coalesce persists onto a single trailing timer so the tens-of-MB
+     *  `JSON.stringify` never runs on the reply path and rapid opens write once. */
+    schedulePersist() {
+        if (this.persistTimer)
+            return;
+        this.persistTimer = setTimeout(() => {
+            this.persistTimer = null;
+            void this.persist();
+        }, PERSIST_DEBOUNCE_MS);
+        this.persistTimer.unref?.();
+    }
     /** Atomic write (temp + rename) so a concurrent reader never sees a partial
      *  file. Coalesces overlapping writes into one trailing flush. */
     async persist() {
@@ -240,16 +305,19 @@ export class SessionListCache {
             return;
         }
         this.persisting = true;
+        const tmp = `${this.cacheFile}.${process.pid}.tmp`;
         try {
-            const obj = {};
+            const entries = {};
             for (const [path, entry] of this.cache)
-                obj[path] = entry;
-            const tmp = `${this.cacheFile}.${process.pid}.tmp`;
-            await writeFile(tmp, JSON.stringify(obj));
+                entries[path] = entry;
+            const payload = { version: CACHE_SCHEMA_VERSION, entries };
+            await writeFile(tmp, JSON.stringify(payload));
             await rename(tmp, this.cacheFile);
         }
         catch {
-            // Best-effort: a failed persist only costs a rebuild next open.
+            // Best-effort: a failed persist only costs a rebuild next open. Clean up
+            // the temp file so a failed write never leaks it.
+            await unlink(tmp).catch(() => { });
         }
         finally {
             this.persisting = false;

package/dist/core/runtime/spawn.js

@@ -12,7 +12,6 @@
 import { spawn } from 'node:child_process';
 import { readdirSync, existsSync } from 'node:fs';
 import { isAbsolute, resolve, join } from 'node:path';
-import { homedir } from 'node:os';
 import { spawnNode, currentNodeContext, rootOfSpine, newNodeId } from './nodes.js';
 import { loadProfileManifest } from '../profiles/manifest.js';
 import { selectProfileForCwd } from '../profiles/select.js';
@@ -28,6 +27,7 @@ import { installTmuxBindings } from './tmux-chrome.js';
 import { getNode, fullName, recordPid } from '../canvas/index.js';
 import { registerViewerFocus, openViewerWindow, waitForBrokerViewSocket, viewerSplitEnv, windowOfPane, currentTmux, inTmux, focusWindow, } from './placement.js';
 import { transition } from './lifecycle.js';
+import { piSessionsRoot } from './pi-vendored.js';
 import { headlessBrokerHost } from './host.js';
 import { ensureDaemon } from '../../daemon/manage.js';
 // ---------------------------------------------------------------------------
@@ -186,18 +186,6 @@ export async function bootRoot(opts) {
     }
     process.exit(await attachExit);
 }
-/** pi's sessions root, VENDORED from pi `config.getSessionsDir()` (= `<agentDir>/
- *  sessions`). pi's package `exports` map is `.`-only, so config.js can't be
- *  deep-imported, and a ROOT import of `getAgentDir` would eager-load the entire
- *  heavy pi SDK index on crtr's front-door hot path (the reason broker-sdk.ts
- *  dynamic-imports the engine). Mirrors pi: `PI_CODING_AGENT_DIR` env, else
- *  `~/.pi/agent` (APP_NAME defaults to 'pi'). Re-sync on a pi SDK bump that moves
- *  the sessions dir — same vendoring rationale as pi-vendored.ts. */
-function piSessionsRoot() {
-    const env = process.env['PI_CODING_AGENT_DIR'];
-    const agentDir = env !== undefined && env !== '' ? env : join(homedir(), '.pi', 'agent');
-    return join(agentDir, 'sessions');
-}
 /** Resolve a bare/partial pi session uuid to its ABSOLUTE `.jsonl` path by
  *  scanning pi's sessions store the way pi's own CLI does (exact id, else a
  *  unique prefix). The broker fork seam (`SessionManager.forkFrom`) loads a FILE

package/dist/core/runtime/tmux.js

@@ -419,6 +419,7 @@ const MENU_ACTIONS = {
     'crtr.tmux.menu.detach': { description: 'detach to background', action: { kind: 'command', run: 'node lifecycle demote --pane {pane} --detach' } },
     'crtr.tmux.menu.close-subtree': { description: 'close agent + subtree', action: { kind: 'command', run: 'node lifecycle close --pane {pane}' } },
     'crtr.tmux.menu.context': { description: 'browse context dirs', action: { kind: 'keys', keys: '/context' } },
+    'crtr.tmux.menu.providers': { description: 'manage providers', action: { kind: 'popup', run: 'sys setup' } },
     'crtr.tmux.menu.graph': { description: 'graph view', action: { kind: 'keys', keys: '/graph' } },
     'crtr.tmux.menu.focus-manager': { description: 'focus manager', action: { kind: 'command', run: 'node focus {manager}' } },
     'crtr.tmux.menu.open': undefined,
@@ -501,7 +502,7 @@ function menuItems(bindings) {
     for (const id of [
         'crtr.tmux.menu.promote', 'crtr.tmux.menu.resume', 'crtr.tmux.menu.demote',
         'crtr.tmux.menu.detach', 'crtr.tmux.menu.close-subtree', 'crtr.tmux.menu.context',
-        'crtr.tmux.menu.graph', 'crtr.tmux.menu.focus-manager', 'crtr.tmux.menu.issues',
+        'crtr.tmux.menu.providers', 'crtr.tmux.menu.graph', 'crtr.tmux.menu.focus-manager', 'crtr.tmux.menu.issues',
     ]) {
         const entry = id === 'crtr.tmux.menu.issues'
             ? { description: 'new issue / todo', action: { kind: 'submenu', title: 'new issue / todo', items: issueItems } }

package/dist/core/scope.js

@@ -1,5 +1,5 @@
 import { homedir } from 'node:os';
-import { existsSync, statSync } from 'node:fs';
+import { existsSync, statSync, realpathSync } from 'node:fs';
 import { join, resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { CRTR_DIR_NAME } from '../types.js';
@@ -48,6 +48,14 @@ export function builtinPiPackageDir(name) {
 export function userScopeRoot() {
     return join(homedir(), CRTR_DIR_NAME);
 }
+function realpathOrSelf(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+}
 function isProjectScopeDir(candidate, userRoot) {
     if (candidate === userRoot || !existsSync(candidate))
         return false;
@@ -61,16 +69,31 @@ function isProjectScopeDir(candidate, userRoot) {
 export function findProjectScopeRoot(startDir = process.cwd()) {
     return findProjectScopeRoots(startDir)[0] ?? null;
 }
-/** Walk `startDir` upward to the filesystem root, collecting every ancestor
- *  `.crouter/` dir (nearest first). The user-global `~/.crouter/` is excluded
- *  because it is the separate user scope, not a project ancestor. */
+/** Walk `startDir` upward collecting every ancestor `.crouter/` dir (nearest
+ *  first). The user-global `~/.crouter/` is excluded because it is the separate
+ *  user scope, not a project ancestor.
+ *
+ *  The walk is FENCED at `homedir()`: it must never climb at or above HOME.
+ *  Home's own `.crouter/` is the user scope (already excluded), and nothing at
+ *  or above HOME is a project ancestor. Without this fence, a relocated HOME
+ *  nested under a directory tree that itself contains a `.crouter/` (e.g. a
+ *  mock-VM home under the real host home) would sweep the host's `~/.crouter`
+ *  (and any other above-HOME `.crouter`) in as a bogus project ancestor,
+ *  leaking one machine's user-global memory into a nested-HOME node. Mirrors
+ *  the on-read positional-walk fence (src/core/substrate/on-read.ts). A read
+ *  whose start dir is outside HOME (e.g. a production VM with HOME=/root and no
+ *  ancestor `.crouter`) never reaches home and walks to the filesystem root, as
+ *  before. */
 function collectAncestorScopeRoots(startDir, userRoot) {
     const roots = [];
+    const home = realpathOrSelf(homedir());
     let dir = resolve(startDir);
     while (true) {
         const candidate = join(dir, CRTR_DIR_NAME);
         if (isProjectScopeDir(candidate, userRoot))
             roots.push(candidate);
+        if (realpathOrSelf(dir) === home)
+            return roots;
         const parent = dirname(dir);
         if (parent === dir)
             return roots;

package/dist/core/subscription-state.d.ts

@@ -0,0 +1,90 @@
+import type { ThinkingLevel } from "@earendil-works/pi-ai";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+export declare const ANTHROPIC_PROVIDER_ID = "anthropic";
+export declare const OPENAI_CODEX_PROVIDER_ID = "openai-codex";
+export type ManagedProviderId = typeof ANTHROPIC_PROVIDER_ID | typeof OPENAI_CODEX_PROVIDER_ID;
+export type LadderProviderId = "anthropic" | "openai";
+export type ModelStrength = "ultra" | "strong" | "medium" | "light";
+export type SubscriptionCredential = {
+    label: string;
+    refresh?: string;
+    access?: string;
+    expires?: number;
+    rateLimitedUntil: number;
+    lastAttemptAt: number;
+    lastRateLimitedAt: number;
+    accountId?: string;
+};
+export type ModelRef = {
+    providerId: ManagedProviderId;
+    modelId: string;
+};
+export type RotationConfig = {
+    defaultFallbackStrength?: ModelStrength;
+    revertWhenAvailable?: boolean;
+    preferredModel?: ModelRef;
+};
+type RotationConfigUpdate = {
+    defaultFallbackStrength?: ModelStrength;
+    revertWhenAvailable?: boolean;
+    preferredModel?: ModelRef | null;
+};
+export type FallbackTarget = {
+    providerId: ManagedProviderId;
+    modelId: string;
+    label: string;
+    strength: ModelStrength;
+    thinkingLevel?: ThinkingLevel;
+};
+export declare function isManagedProvider(providerId: string | undefined): providerId is ManagedProviderId;
+/** The `modelLadders` CONFIG key for a runtime provider id -- `openai-codex`
+ *  (the runtime/auth id) maps to the `openai` ladder key used in
+ *  ~/.crouter/config.json. Callers building a repair command that a user can
+ *  paste into `crtr sys config set modelLadders.<key>...` must use THIS key,
+ *  not the runtime provider id. */
+export declare function getLadderProviderId(providerId: ManagedProviderId): LadderProviderId;
+export declare function getProviderLabel(providerId: ManagedProviderId): string;
+export declare function mutateSubscriptionPool(providerId: ManagedProviderId, fn: (pool: SubscriptionCredential[]) => SubscriptionCredential[] | undefined): SubscriptionCredential[];
+export declare function readSubscriptionPool(providerId: ManagedProviderId): SubscriptionCredential[];
+export declare function writeSubscriptionPool(providerId: ManagedProviderId, next: SubscriptionCredential[]): SubscriptionCredential[];
+export declare function upsertSubscription(providerId: ManagedProviderId, next: SubscriptionCredential): SubscriptionCredential[];
+export declare class DuplicateSubscriptionError extends Error {
+    constructor(message: string);
+}
+export declare function addSubscription(providerId: ManagedProviderId, entry: SubscriptionCredential): SubscriptionCredential[];
+export declare function upsertSubscriptionWithUniqueAccount(providerId: ManagedProviderId, next: SubscriptionCredential): SubscriptionCredential[];
+export type DefaultSlotLogin = {
+    refresh: string;
+    access: string;
+    expires: number;
+    accountId?: string;
+    lastRateLimitedAt: number;
+};
+export declare function commitDefaultIdentity(providerId: ManagedProviderId, login: DefaultSlotLogin): SubscriptionCredential[];
+export declare function renameSubscription(providerId: ManagedProviderId, ref: string, nextLabel: string): SubscriptionCredential[];
+export declare function removeManagedAccount(providerId: ManagedProviderId, ref: string): SubscriptionCredential[];
+export declare function commitManagedLogin(providerId: ManagedProviderId, label: string, credential: {
+    refresh: string;
+    access: string;
+    expires: number;
+    accountId?: string;
+    defaultLastRateLimitedAt: number;
+}): SubscriptionCredential[];
+export declare function removeManagedProvider(providerId: ManagedProviderId, label?: string): SubscriptionCredential[];
+export declare function removeSubscription(providerId: ManagedProviderId, ref: string): SubscriptionCredential[];
+export declare function promoteSubscription(providerId: ManagedProviderId, ref: string): SubscriptionCredential[];
+export declare function markSubscriptionAttempt(providerId: ManagedProviderId, ref: string, attemptAt?: number): SubscriptionCredential[];
+export declare function markSubscriptionRateLimited(providerId: ManagedProviderId, ref: string, retryAfterMs: number, attemptAt?: number, rateLimitedAt?: number): SubscriptionCredential[];
+export declare function markSubscriptionSuccess(providerId: ManagedProviderId, ref: string, attemptAt?: number): SubscriptionCredential[];
+export declare function findAvailableSubscription(providerId: ManagedProviderId, now?: number): SubscriptionCredential | undefined;
+export declare function parseRetryAfterHeader(value: string | undefined, now?: number): number | undefined;
+export declare function readRotationConfig(): RotationConfig;
+export declare function writeRotationConfig(next: RotationConfigUpdate): RotationConfig;
+export declare function clearPreferredModel(): RotationConfig;
+export declare function rememberPreferredModel(model: ModelRef): RotationConfig;
+export declare function resolveFallbackTarget(currentProviderId: ManagedProviderId, currentModelId?: string, config?: RotationConfig, currentThinkingLevel?: string): FallbackTarget | undefined;
+export declare function shouldRestorePreferredModel(config?: RotationConfig, now?: number): boolean;
+export declare function restorePreferredModelIfPossible(piApi: ExtensionAPI, ctx: Pick<ExtensionContext, "model" | "modelRegistry">): Promise<boolean>;
+export declare function switchToFallbackIfPossible(piApi: ExtensionAPI, ctx: Pick<ExtensionContext, "model" | "modelRegistry">, preferredModel?: ModelRef | undefined): Promise<FallbackTarget | undefined>;
+export declare function formatStatusLine(providerId: ManagedProviderId, now?: number): string;
+export {};