tiergear 0.1.0

package/dist/cli/orca.js

@@ -0,0 +1,105 @@
+import { execFile } from 'node:child_process';
+export class OrcaError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+    }
+}
+export function pick(json, paths) {
+    for (const path of paths) {
+        let value = json;
+        for (const part of path.split('.')) {
+            value = value && typeof value === 'object' ? value[part] : undefined;
+        }
+        if (value !== undefined && value !== null)
+            return value;
+    }
+    return undefined;
+}
+// A long --json call streams one-line keepalive objects before its result, so drop those first.
+export function parseOrcaOutput(stdout) {
+    const body = stdout
+        .split('\n')
+        .filter((line) => !/^\{"_keepalive":true\b/.test(line.trim()))
+        .join('\n')
+        .trim();
+    return body ? safeJson(body) : null;
+}
+function safeJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+export function errorCode(json) {
+    const code = pick(json, ['error.code', 'code']);
+    return typeof code === 'string' ? code : null;
+}
+// Arguments go to execFile as an array: no shell, so a brief's quotes and $ stay literal.
+export function createOrcaExec(binary = process.env['ORCA_CLI_COMMAND'] || 'orca') {
+    return (args, cwd) => new Promise((resolve, reject) => {
+        execFile(binary, [...args, '--json'], { cwd, maxBuffer: 10 * 1024 * 1024 }, (error, stdout, stderr) => {
+            const parsed = parseOrcaOutput(stdout);
+            if (error) {
+                const detail = (stderr || stdout || error.message).trim().slice(0, 300);
+                reject(new OrcaError(`orca ${args.slice(0, 2).join(' ')} failed: ${detail}`, errorCode(parsed) ?? errorCode(safeJson(stderr))));
+                return;
+            }
+            resolve(parsed);
+        });
+    });
+}
+export function parseWorktree(json) {
+    const id = pick(json, ['result.worktree.id', 'worktree.id']);
+    if (typeof id !== 'string' || !id.includes('::'))
+        throw new Error('orca worktree create returned no worktree.id');
+    return { id, path: id.slice(id.indexOf('::') + 2) };
+}
+export function parseHandle(json) {
+    const handle = pick(json, ['result.terminal.handle', 'terminal.handle', 'handle']);
+    if (typeof handle !== 'string' || !handle)
+        throw new Error('orca terminal create returned no handle');
+    return handle;
+}
+export function parseRunId(json) {
+    const id = pick(json, ['result.run.id', 'run.id']);
+    return typeof id === 'string' && id ? id : null;
+}
+export function parseWorkerStart(json) {
+    if (pick(json, ['ok']) === false) {
+        const code = errorCode(json);
+        const message = pick(json, ['error.message']);
+        throw new OrcaError(`orca orchestration worker-start failed: ${code ?? 'error'}: ${typeof message === 'string' ? message : ''}`.trim(), code);
+    }
+    const runId = pick(json, ['result.runId']);
+    const taskId = pick(json, ['result.taskId']);
+    const dispatchId = pick(json, ['result.dispatchId']);
+    const effects = pick(json, ['result.effects']);
+    const terminal = Array.isArray(effects)
+        ? effects.find((e) => !!e && typeof e === 'object' && e.kind === 'terminal' && e.role === 'agent')
+        : undefined;
+    const handle = terminal?.id;
+    if (typeof runId !== 'string' || typeof taskId !== 'string' || typeof dispatchId !== 'string' || typeof handle !== 'string') {
+        throw new Error('orca orchestration worker-start returned no dispatch ids or agent terminal');
+    }
+    return { runId, taskId, dispatchId, handle };
+}
+export function parseSatisfied(json) {
+    return pick(json, ['result.wait.satisfied', 'wait.satisfied', 'satisfied']) === true;
+}
+export function parseBlockedReason(json) {
+    const reason = pick(json, ['result.wait.blockedReason', 'wait.blockedReason']);
+    return typeof reason === 'string' ? reason : null;
+}
+// Orca renames a terminal to its agent, so match on worktree + agent identity first and the title second.
+export function findAgentHandle(json, worktreeId, agent, title) {
+    const list = pick(json, ['result.terminals', 'terminals']);
+    if (!Array.isArray(list))
+        return null;
+    const entries = list.filter((t) => !!t && typeof t === 'object');
+    const match = entries.find((t) => t.worktreeId === worktreeId && t.agentIdentity === agent) ?? entries.find((t) => t.title === title);
+    return typeof match?.handle === 'string' ? match.handle : null;
+}

package/dist/cli/spawn.js

@@ -0,0 +1,70 @@
+import { OrcaError, findAgentHandle, parseBlockedReason, parseHandle, parseRunId, parseSatisfied, parseWorkerStart, parseWorktree, } from './orca.js';
+export const WAIT_FIRST_MS = 60_000;
+export const WAIT_RETRY_MS = 120_000;
+// The direct path types the brief into the agent's prompt, where a leading `!` runs a shell command and `/` a command.
+export function briefProblem(brief) {
+    const start = brief.trimStart()[0];
+    if (start === '!' || start === '/')
+        return `the brief starts with '${start}', which a Claude Code prompt runs as a command; start it with text`;
+    // Line breaks and tabs only: a carriage return submits early and an escape drives the terminal.
+    if (/[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/.test(brief))
+        return 'the brief contains control characters; only line breaks and tabs are allowed';
+    return null;
+}
+export async function spawnWorker(p) {
+    // worker-start only works for the coordinator of a bound Run; without one, launch the agent directly.
+    const runId = parseRunId(await p.orca(['orchestration', 'run-current']));
+    const base = p.baseBranch ? ['--base-branch', p.baseBranch] : [];
+    const worktree = parseWorktree(await p.orca(['worktree', 'create', '--name', p.name, '--no-parent', ...base], p.repoDir));
+    p.log(`worktree ${worktree.path}`);
+    // The floor must exist before the agent reads its first prompt, which worker-start sends itself.
+    if (p.harness === 'claude') {
+        if (p.plan.floor)
+            await p.writeFloor(worktree.path, p.plan.floor);
+        else
+            p.log('no floor written (judge fallback)');
+    }
+    const selector = `id:${worktree.id}`;
+    if (runId) {
+        const { model, effort } = p.plan.target;
+        const dispatch = parseWorkerStart(await p.orca([
+            'orchestration', 'worker-start', '--spec', p.brief, '--task-title', p.name, '--worktree', selector,
+            '--agent', p.harness, '--model', model, ...(effort ? ['--effort', effort] : []),
+            // Same budget as the direct path, so there is time to approve a trust prompt in Orca.
+            '--timeout-ms', String(WAIT_FIRST_MS + WAIT_RETRY_MS),
+        ]));
+        return { status: 'sent', worktree, handle: dispatch.handle, dispatch };
+    }
+    let handle = parseHandle(await p.orca(['terminal', 'create', '--worktree', selector, '--title', p.name, '--command', p.plan.command]));
+    // After an Orca restart a handle goes stale: re-list once and continue with the replacement only.
+    const withHandle = async (args) => {
+        try {
+            return await p.orca(args(handle));
+        }
+        catch (error) {
+            if (!(error instanceof OrcaError) || error.code !== 'terminal_handle_stale')
+                throw error;
+            const replacement = findAgentHandle(await p.orca(['terminal', 'list', '--worktree', selector]), worktree.id, p.harness, p.name);
+            if (!replacement)
+                throw error;
+            handle = replacement;
+            p.log(`handle refreshed: ${handle}`);
+            return p.orca(args(handle));
+        }
+    };
+    const wait = (ms) => withHandle((h) => ['terminal', 'wait', '--terminal', h, '--for', 'tui-idle', '--timeout-ms', String(ms)]);
+    const first = await wait(WAIT_FIRST_MS);
+    let ready = parseSatisfied(first);
+    if (!ready) {
+        // Never accept the trust prompt on the user's behalf.
+        if (parseBlockedReason(first) === 'agent-trust-workspace') {
+            p.log(`Claude is asking whether to trust ${worktree.path}; approve it in Orca — waiting up to 120s`);
+        }
+        ready = parseSatisfied(await wait(WAIT_RETRY_MS));
+    }
+    // A prompt typed into a TUI that is still starting is lost, so never send blind.
+    if (!ready)
+        return { status: 'not-started', worktree, handle, dispatch: null };
+    await withHandle((h) => ['terminal', 'send', '--terminal', h, '--text', p.brief, '--enter']);
+    return { status: 'sent', worktree, handle, dispatch: null };
+}

package/dist/cli/stats.js

@@ -0,0 +1,19 @@
+export function summarize(entries, sinceMs) {
+    const recent = entries.filter((e) => e.at >= sinceMs);
+    if (recent.length === 0)
+        return 'no decisions yet';
+    const count = (change) => recent.filter((e) => e.change === change).length;
+    const lines = [
+        `decisions: ${recent.length}`,
+        `set ${count('set')} · up ${count('up')} · down ${count('down')} · hold ${count('hold')}`,
+    ];
+    const judges = [...new Set(recent.map((e) => e.judge))];
+    for (const judge of judges) {
+        const asked = recent.filter((e) => e.judge === judge && e.outcome !== 'skipped');
+        const answered = asked.filter((e) => e.outcome === 'ok');
+        const latencies = answered.map((e) => e.ms).filter((ms) => typeof ms === 'number');
+        const avg = latencies.length > 0 ? Math.round(latencies.reduce((a, b) => a + b, 0) / latencies.length) : null;
+        lines.push(`${judge} answered ${answered.length}/${asked.length}${avg !== null ? ` · avg ${avg}ms` : ''}`);
+    }
+    return lines.join('\n');
+}

package/dist/cli/status.js

@@ -0,0 +1,78 @@
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { claudeAlias } from '../core/tiers.js';
+import { formatStatus, parseStatus, statusDir, statusField, statusPath } from '../core/status.js';
+// A status line command gets Claude Code's status JSON on stdin: the session, its model and effort.
+function sessionFromStdin(text) {
+    if (!text)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return null;
+    const id = parsed.session_id;
+    const model = parsed.model?.id;
+    const effort = parsed.effort?.level;
+    return {
+        id: typeof id === 'string' && id ? id : undefined,
+        model: typeof model === 'string' && model ? claudeAlias(model) : null,
+        effort: typeof effort === 'string' && effort ? effort : null,
+    };
+}
+// Until tiergear has a value, the session's own stands in; there is no tier then.
+function withSession(status, info) {
+    if (!info || (info.model === null && info.effort === null))
+        return status;
+    if (status)
+        return { ...status, model: status.model ?? info.model, effort: status.effort ?? info.effort };
+    return { session: info.id ?? '', tier: null, model: info.model, effort: info.effort, paused: false, reason: 'session', line: '', updatedAt: 0 };
+}
+// Status files and stdin are read from disk and another program; a status line is a terminal, so no escape gets through.
+const MAX_FIELD_CHARS = 200;
+function printable(text) {
+    return text.replace(/[\u0000-\u001f\u007f-\u009f]/g, '').slice(0, MAX_FIELD_CHARS);
+}
+function printableStatus(status) {
+    if (!status)
+        return null;
+    return {
+        ...status,
+        session: printable(status.session),
+        model: status.model === null ? null : printable(status.model),
+        effort: typeof status.effort === 'string' ? printable(status.effort) : status.effort,
+        reason: printable(status.reason),
+        line: printable(status.line),
+    };
+}
+async function readStatus(path) {
+    const text = await readFile(path, 'utf8').catch(() => null);
+    return text === null ? null : parseStatus(text);
+}
+async function newestStatus(home) {
+    let newest = null;
+    for (const name of await readdir(statusDir(home)).catch(() => [])) {
+        if (!name.endsWith('.json'))
+            continue;
+        const status = await readStatus(join(statusDir(home), name));
+        if (status && (newest === null || status.updatedAt > newest.updatedAt))
+            newest = status;
+    }
+    return newest;
+}
+/** What `tiergear status` prints: the session named by --session, else by stdin, else the one updated last. */
+export async function statusCommand(p) {
+    const info = p.session === undefined ? sessionFromStdin(await p.stdin()) : null;
+    const session = p.session ?? info?.id;
+    const stored = session === undefined ? await newestStatus(p.home) : await readStatus(statusPath(p.home, session));
+    const status = printableStatus(withSession(stored, info));
+    if (p.field)
+        return status ? statusField(status, p.field) : '';
+    if (p.json)
+        return JSON.stringify(status);
+    return status ? formatStatus(status, p.format) : '';
+}

package/dist/core/config.js

@@ -0,0 +1,58 @@
+import { JUDGE_PRESETS, isJudgeName } from './judges/presets.js';
+// A hook has 10s; the judge gets at most 8s of it so the rest of the hook still fits.
+export const MAX_JUDGE_TIMEOUT_MS = 8000;
+const NUMBER_KEYS = [
+    'minUpgradeConfidence',
+    'minDowngradeConfidence',
+    'downgradeStreak',
+    'stuckConfidence',
+    'stuckFailures',
+    'firstTurnTimeoutMs',
+    'turnTimeoutMs',
+];
+function text(options, key) {
+    const value = options[key];
+    return typeof value === 'string' && value ? value : undefined;
+}
+export function resolveConfig(options) {
+    const judge = isJudgeName(options['judge']) ? options['judge'] : 'jev';
+    const preset = JUDGE_PRESETS[judge];
+    const config = {
+        judge,
+        judgeBaseUrl: text(options, 'judgeBaseUrl') ?? preset.baseUrl,
+        judgeModel: text(options, 'judgeModel') ?? preset.model,
+        switchModelMidSession: options['switchModelMidSession'] === true,
+        minUpgradeConfidence: 0.5,
+        minDowngradeConfidence: 0.85,
+        downgradeStreak: 2,
+        stuckConfidence: 0.6,
+        stuckFailures: 3,
+        firstTurnTimeoutMs: preset.firstTurnTimeoutMs,
+        turnTimeoutMs: preset.turnTimeoutMs,
+        showRecentButton: options['showRecentButton'] !== false,
+        showStatusText: options['showStatusText'] !== false,
+        showTierButtons: options['showTierButtons'] !== false,
+        showPrefix: options['showPrefix'] !== false,
+        showTier: options['showTier'] !== false,
+        showConfidence: options['showConfidence'] !== false,
+        showModelEffort: options['showModelEffort'] !== false,
+        showReason: options['showReason'] !== false,
+        instantSwitchConfidence: null,
+        showFloor: options['showFloor'] !== false,
+    };
+    for (const key of NUMBER_KEYS) {
+        const value = options[key];
+        if (typeof value === 'number' && Number.isFinite(value))
+            config[key] = value;
+    }
+    config.firstTurnTimeoutMs = Math.min(config.firstTurnTimeoutMs, MAX_JUDGE_TIMEOUT_MS);
+    config.turnTimeoutMs = Math.min(config.turnTimeoutMs, MAX_JUDGE_TIMEOUT_MS);
+    const instant = options['instantSwitchConfidence'];
+    if (typeof instant === 'number' && Number.isFinite(instant) && instant > 0)
+        config.instantSwitchConfidence = instant;
+    const apiKey = text(options, 'judgeApiKey');
+    if (apiKey)
+        config.judgeApiKey = apiKey;
+    return config;
+}
+export const DEFAULT_CONFIG = resolveConfig({});

package/dist/core/decide.js

@@ -0,0 +1,253 @@
+import { abridge } from './state.js';
+import { effortFor, firstTarget } from './tables.js';
+import { isEffort, isTier, maxTier, stepDown, stepUp, tierRank } from './tiers.js';
+export const JUDGE_FAILURE_LIMIT = 3;
+export const JUDGE_PAUSE_MS = 5 * 60_000;
+export const RECORD_TTL_MS = 7 * 24 * 60 * 60_000;
+// $.store is one JSON file that rejects writes past 4 MiB, so records are capped in count and size.
+export const MAX_RECORDS = 200;
+export const FIRST_PROMPT_CHARS = 2000;
+export function newRecord(firstPrompt, now) {
+    return {
+        // The judge only ever sees this many characters of it.
+        firstPrompt: abridge(firstPrompt, FIRST_PROMPT_CHARS),
+        tier: null,
+        floor: null,
+        ceiling: null,
+        model: null,
+        applied: null,
+        downStreak: 0,
+        pinned: false,
+        started: true,
+        judgeFailures: 0,
+        judgePausedUntil: 0,
+        updatedAt: now,
+    };
+}
+function count(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}
+function readApplied(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const { model, effort } = value;
+    if (effort !== null && !isEffort(effort))
+        return null;
+    return typeof model === 'string' ? { model, effort } : { effort };
+}
+export function parseRecord(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const r = value;
+    if (typeof r['firstPrompt'] !== 'string' || typeof r['updatedAt'] !== 'number')
+        return null;
+    const tier = r['tier'];
+    const floor = r['floor'];
+    if (tier !== null && !isTier(tier))
+        return null;
+    if (floor !== null && !isTier(floor))
+        return null;
+    return {
+        firstPrompt: r['firstPrompt'],
+        tier,
+        floor,
+        // Records stored before ceilings have none.
+        ceiling: isTier(r['ceiling']) ? r['ceiling'] : null,
+        model: typeof r['model'] === 'string' ? r['model'] : null,
+        applied: readApplied(r['applied']),
+        downStreak: count(r['downStreak']),
+        pinned: r['pinned'] === true,
+        // Records stored before this mark were all made by a prompt.
+        started: r['started'] !== false,
+        judgeFailures: count(r['judgeFailures']),
+        judgePausedUntil: count(r['judgePausedUntil']),
+        updatedAt: r['updatedAt'],
+    };
+}
+function appliedFor(model, tier, config, tables) {
+    if (config.switchModelMidSession) {
+        const target = firstTarget(tables, 'claude', tier);
+        return { model: target.model, effort: target.effort };
+    }
+    // Model held: only the effort follows the tier, from the session model's column in table B.
+    const effort = effortFor(tables, 'claude', model ?? '', tier);
+    if (model && effort === null) {
+        // A model without effort cannot be raised by effort alone, so move to the tier's own model.
+        const target = firstTarget(tables, 'claude', tier);
+        if (target.model !== model)
+            return { model: target.model, effort: target.effort };
+    }
+    return model ? { model, effort } : { effort };
+}
+// A paused session runs on its own model and effort: nothing is applied.
+function pausedHold(record, confidence) {
+    return { record: { ...record, pinned: true, applied: null, downStreak: 0 }, change: 'hold', confidence, reason: 'paused' };
+}
+// Paused, tiergear's held model is not in effect: the session's own is.
+function heldModel(record, sessionModel) {
+    return record.pinned ? (sessionModel ?? record.model) : (record.model ?? sessionModel);
+}
+// Before the first prompt there is no cache to lose, so the model follows the tier as on a first turn.
+function appliedForTier(record, model, tier, config, tables) {
+    if (record.started)
+        return appliedFor(model, tier, config, tables);
+    const target = firstTarget(tables, 'claude', tier);
+    return { model: target.model, effort: target.effort };
+}
+/** A floor set by hand: a tier under it rises to it; a launch ceiling still bounds it. */
+export function decideSetFloor(input) {
+    const { record, config, tables } = input;
+    const floor = record.ceiling !== null && tierRank(input.floor) > tierRank(record.ceiling) ? record.ceiling : input.floor;
+    const floored = { ...record, floor };
+    if (record.pinned || record.tier === null || tierRank(record.tier) >= tierRank(floor)) {
+        return { record: floored, change: 'hold', confidence: null, reason: 'floor set' };
+    }
+    const model = heldModel(record, input.sessionModel);
+    const applied = appliedForTier(record, model, floor, config, tables);
+    return { record: { ...floored, tier: floor, applied, model: applied.model ?? model, downStreak: 0 }, change: 'up', confidence: null, reason: 'floor set' };
+}
+export function decidePause(record) {
+    return pausedHold(record, null);
+}
+/** A tier picked by hand: a starting point the judge keeps moving by the usual rules. */
+export function decidePick(input) {
+    const { record, tier, config, tables } = input;
+    const model = heldModel(record, input.sessionModel);
+    const applied = appliedForTier(record, model, tier, config, tables);
+    const floor = record.floor === null ? stepDown(tier) : tierRank(tier) < tierRank(record.floor) ? tier : record.floor;
+    return {
+        record: { ...record, tier, floor, pinned: false, applied, model: applied.model ?? model, downStreak: 0 },
+        change: 'set',
+        confidence: null,
+        reason: 'manual tier',
+    };
+}
+export function decideFirstTurn(input) {
+    const { record, floor, verdict, config, tables } = input;
+    if (record.pinned)
+        return pausedHold(record, null);
+    if (!record.started && record.tier !== null) {
+        // Picked before the first prompt: the pick stands for this turn, and a launch still bounds the session.
+        const launched = floor ? { floor: tierRank(floor.tier) < tierRank(record.tier) ? floor.tier : record.tier, ceiling: floor.ceiling ?? null } : {};
+        return { record: { ...record, ...launched }, change: 'hold', confidence: null, reason: 'manual tier' };
+    }
+    if (floor) {
+        const target = firstTarget(tables, 'claude', floor.tier);
+        return {
+            record: {
+                ...record,
+                tier: floor.tier,
+                floor: floor.tier,
+                ceiling: floor.ceiling ?? null,
+                model: target.model,
+                applied: { model: target.model, effort: target.effort },
+            },
+            change: 'set',
+            confidence: null,
+            reason: `launched at ${floor.tier}`,
+        };
+    }
+    const answer = verdict?.tier ?? null;
+    if (!answer || answer.confidence < config.minUpgradeConfidence) {
+        return { record, change: 'hold', confidence: answer?.confidence ?? null, reason: answer ? 'low confidence' : 'no answer' };
+    }
+    // The first turn has no cache to lose, so the model changes with the tier; a floor set by hand still holds.
+    const tier = maxTier(answer.tier, record.floor);
+    const target = firstTarget(tables, 'claude', tier);
+    return {
+        record: { ...record, tier, floor: record.floor ?? stepDown(answer.tier), model: target.model, applied: { model: target.model, effort: target.effort } },
+        change: 'set',
+        confidence: answer.confidence,
+        reason: 'first turn',
+    };
+}
+export function decideNextTurn(input) {
+    const { record, verdict, config, tables } = input;
+    const model = record.model ?? input.sessionModel;
+    const answer = verdict?.tier ?? null;
+    const confidence = answer?.confidence ?? null;
+    const hold = (reason, downStreak = 0) => ({ record: { ...record, downStreak }, change: 'hold', confidence, reason });
+    const move = (tier, change, reason) => {
+        const applied = appliedFor(model, tier, config, tables);
+        return { record: { ...record, tier, applied, model: applied.model ?? model, downStreak: 0 }, change, confidence, reason };
+    };
+    if (record.pinned)
+        return pausedHold(record, confidence);
+    if (record.tier === null) {
+        if (!answer || answer.confidence < config.minUpgradeConfidence)
+            return hold(answer ? 'low confidence' : 'no answer');
+        const decided = move(maxTier(answer.tier, record.floor), 'set', 'tier decided');
+        return { ...decided, record: { ...decided.record, floor: record.floor ?? stepDown(answer.tier) } };
+    }
+    const current = record.tier;
+    const raise = (tier, reason) => {
+        const capped = record.ceiling !== null && tierRank(tier) > tierRank(record.ceiling) ? record.ceiling : tier;
+        return tierRank(capped) > tierRank(current) ? move(capped, 'up', reason) : hold('at ceiling');
+    };
+    if (answer && tierRank(answer.tier) > tierRank(current) && answer.confidence >= config.minUpgradeConfidence) {
+        return raise(answer.tier, 'harder step');
+    }
+    const stuck = (verdict?.stuck ?? 0) >= config.stuckConfidence || input.repeatedFailures >= config.stuckFailures;
+    if (stuck)
+        return current === 'max' ? hold('stuck at max') : raise(stepUp(current), 'stuck');
+    // A judge sure enough for the instant switch lowers at once, straight to its tier, never under the floor.
+    if (answer && tierRank(answer.tier) < tierRank(current) && config.instantSwitchConfidence !== null && answer.confidence >= config.instantSwitchConfidence) {
+        const lower = maxTier(answer.tier, record.floor);
+        return lower === current ? hold('at floor') : move(lower, 'down', 'instant switch');
+    }
+    // Lowering needs a confident judge on consecutive turns, so one terse follow-up cannot drop the tier.
+    if (answer && tierRank(answer.tier) < tierRank(current) && answer.confidence >= config.minDowngradeConfidence) {
+        const streak = record.downStreak + 1;
+        if (streak < config.downgradeStreak)
+            return hold(`easier step ${streak}/${config.downgradeStreak}`, streak);
+        const lower = maxTier(stepDown(current), record.floor);
+        return lower === current ? hold('at floor') : move(lower, 'down', 'easier steps');
+    }
+    if (!answer)
+        return hold('no answer');
+    const bar = tierRank(answer.tier) > tierRank(current) ? config.minUpgradeConfidence : tierRank(answer.tier) < tierRank(current) ? config.minDowngradeConfidence : 0;
+    return hold(answer.confidence < bar ? 'low confidence' : 'same tier');
+}
+export function canAskJudge(record, now) {
+    return now >= record.judgePausedUntil;
+}
+export function noteJudgeOutcome(record, ok, now) {
+    if (ok)
+        return { ...record, judgeFailures: 0 };
+    const failures = record.judgeFailures + 1;
+    return failures >= JUDGE_FAILURE_LIMIT
+        ? { ...record, judgeFailures: 0, judgePausedUntil: now + JUDGE_PAUSE_MS }
+        : { ...record, judgeFailures: failures };
+}
+export function appliedText(applied) {
+    const effort = applied.effort ?? '-';
+    return applied.model ? `${applied.model}/${effort}` : effort;
+}
+// tiergear's override wins over the engine's values; a missing piece is the engine's.
+export function inEffect(applied, engine) {
+    if (!applied)
+        return engine;
+    return { model: applied.model ?? engine?.model ?? null, effort: applied.effort };
+}
+function inEffectText(current) {
+    const effort = current.effort === null ? '-' : String(current.effort);
+    return current.model ? `${current.model}/${effort}` : effort;
+}
+const SHOW_ALL = { tier: true, confidence: true, modelEffort: true, reason: true };
+// The line without its `tiergear ·` prefix: `deep 0.91 → opus/xhigh`, or `deep 0.62 · sonnet/medium · unchanged (same tier)`.
+export function statusParts(decision, current, show) {
+    const { record, change, confidence, reason } = decision;
+    const head = [show.tier ? (record.tier ?? 'unset') : null, show.confidence ? (confidence === null ? 'n/d' : confidence.toFixed(2)) : null]
+        .filter((part) => part !== null)
+        .join(' ');
+    if (change === 'hold' || !record.applied) {
+        const now = show.modelEffort && current ? inEffectText(current) : '';
+        return [head, now, show.reason ? `unchanged (${reason})` : ''].filter((part) => part).join(' · ');
+    }
+    if (!show.modelEffort)
+        return head;
+    return [head, `→ ${current ? inEffectText(current) : appliedText(record.applied)}`].filter((part) => part).join(' ');
+}
+export function statusText(decision, current = null) {
+    return `tiergear · ${statusParts(decision, current, SHOW_ALL)}`;
+}

package/dist/core/failures.js

@@ -0,0 +1,10 @@
+export const EMPTY_TRACKER = { signature: null, count: 0 };
+export function failureSignature(tool, errorText) {
+    return `${tool}:${errorText.trim().slice(0, 120)}`;
+}
+export function recordFailure(tracker, signature) {
+    return tracker.signature === signature ? { signature, count: tracker.count + 1 } : { signature, count: 1 };
+}
+export function recordSuccess(tracker, tool) {
+    return tracker.signature?.startsWith(`${tool}:`) ? EMPTY_TRACKER : tracker;
+}

package/dist/core/floor.js

@@ -0,0 +1,44 @@
+import { isTier, tierRank } from './tiers.js';
+export const FLOOR_TTL_MS = 24 * 60 * 60 * 1000;
+export function normalizePath(path) {
+    return path.length > 1 ? path.replace(/\/+$/, '') : path;
+}
+// FNV-1a: stable in the hook runtime and in Node without a crypto module.
+export function fnv1a(text) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < text.length; i++) {
+        hash ^= text.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return hash.toString(16).padStart(8, '0');
+}
+export function floorPath(home, worktree) {
+    return `${home}/.local/state/tiergear/floors/${fnv1a(normalizePath(worktree))}.json`;
+}
+export function serializeFloor(record) {
+    return JSON.stringify(record);
+}
+export function parseFloor(text, worktree, now) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return null;
+    const record = parsed;
+    if (typeof record.worktree !== 'string')
+        return null;
+    if (normalizePath(record.worktree) !== normalizePath(worktree))
+        return null;
+    if (!isTier(record.tier) || typeof record.createdAt !== 'number')
+        return null;
+    if (record.ceiling !== undefined && (!isTier(record.ceiling) || tierRank(record.ceiling) < tierRank(record.tier)))
+        return null;
+    if (now - record.createdAt > FLOOR_TTL_MS)
+        return null;
+    const floor = { worktree: record.worktree, tier: record.tier, createdAt: record.createdAt };
+    return record.ceiling === undefined ? floor : { ...floor, ceiling: record.ceiling };
+}

package/dist/core/judge.js

@@ -0,0 +1,13 @@
+const TIMED_OUT = Symbol('timed out');
+/** Runs a judge call under a deadline and turns every failure into a result, so a turn never waits or throws. */
+export async function guarded(work, sleep, timeoutMs) {
+    try {
+        const result = await Promise.race([work(), sleep(timeoutMs).then(() => TIMED_OUT)]);
+        if (result === TIMED_OUT)
+            return { ok: false, reason: `timed out after ${timeoutMs}ms` };
+        return { ok: true, verdict: result };
+    }
+    catch (error) {
+        return { ok: false, reason: error instanceof Error ? error.message : String(error) };
+    }
+}