framein 0.0.4

package/dist/mcpServer.js

@@ -0,0 +1,138 @@
+// Thin framein MCP surface (F-OWN-1): the minimum tools agents need to share the store.
+// `handleTool` maps a tool call to a store op (unit-tested); `dispatch` handles one JSON-RPC
+// message; `serve` is the stdio loop. The wire format is newline-delimited JSON (NDJSON) —
+// that IS the MCP stdio transport (ADR-0007). MCP stdio is NOT Content-Length framed (that's
+// LSP); headers only appear in MCP's separate Streamable HTTP transport. Live MCP-CLIENT
+// wiring (each CLI launching its own `frame mcp serve`) is the orchestration layer (B).
+import { createInterface } from 'node:readline';
+const obj = (properties, required = []) => ({ type: 'object', properties, required });
+const str = { type: 'string' };
+export const TOOLS = [
+    { name: 'append_adr', description: 'record an ADR', inputSchema: obj({ title: str, decision: str, context: str, consequences: str }, ['title']) },
+    { name: 'list_adr', description: 'list all ADRs', inputSchema: obj({}) },
+    { name: 'get_adr', description: 'get one ADR', inputSchema: obj({ id: { type: 'number' } }, ['id']) },
+    { name: 'read_memory', description: 'read scoped memory', inputSchema: obj({ scope: str, key: str }, ['scope', 'key']) },
+    { name: 'write_memory', description: 'write scoped memory', inputSchema: obj({ scope: str, key: str, value: {} }, ['scope', 'key', 'value']) },
+    { name: 'list_memory', description: 'list a memory scope', inputSchema: obj({ scope: str }, ['scope']) },
+    { name: 'get_role', description: 'agent assigned to a role', inputSchema: obj({ role: str }, ['role']) },
+    { name: 'get_roles', description: 'all role assignments', inputSchema: obj({}) },
+    { name: 'acquire_lock', description: 'acquire the write lock', inputSchema: obj({ holder: str, scope: str }, ['holder']) },
+    { name: 'release_lock', description: 'release the write lock', inputSchema: obj({ holder: str, scope: str }, ['holder']) },
+];
+const TOOL_NAMES = new Set(TOOLS.map((t) => t.name));
+/** Protocol versions we accept, newest first. Negotiation echoes the client's if supported. */
+export const PROTOCOL_VERSIONS = ['2025-06-18', '2025-03-26', '2024-11-05'];
+// Advertised to clients; keep loosely in sync with package.json (a string is required by spec).
+const SERVER_INFO = { name: 'framein', version: '0.0.1' };
+export function handleTool(store, name, args = {}) {
+    switch (name) {
+        case 'append_adr': {
+            const title = String(args.title ?? '');
+            if (!title)
+                throw new Error('append_adr requires a title');
+            const a = store.appendAdr({
+                title,
+                decision: String(args.decision ?? title),
+                context: args.context,
+                consequences: args.consequences,
+            });
+            return { id: a.id };
+        }
+        case 'list_adr': return store.listAdrs();
+        case 'get_adr': return store.getAdr(Number(args.id)) ?? null;
+        case 'read_memory': return store.getMemory(String(args.scope), String(args.key)) ?? null;
+        case 'write_memory':
+            store.setMemory(String(args.scope), String(args.key), args.value);
+            return { ok: true };
+        case 'list_memory': return store.listMemory(String(args.scope));
+        case 'get_role': return store.getRole(args.role) ?? null;
+        case 'get_roles': return store.getRoles();
+        case 'acquire_lock': return { acquired: store.acquireLock(String(args.holder), { scope: args.scope }) };
+        case 'release_lock': return { released: store.releaseLock(String(args.holder), { scope: args.scope }) };
+        default: throw new Error(`unknown tool: ${name}`);
+    }
+}
+/**
+ * Dispatch one parsed JSON-RPC value. Never throws. Returns a reply object for requests, or
+ * `null` for notifications and for anything we can't reply to (no id). When a `session` is
+ * supplied, the initialize-first lifecycle is enforced (ADR-0007); without one, dispatch stays
+ * lenient (used by unit tests). `initialize` and `ping` are always allowed pre-init.
+ */
+export function dispatch(store, req, session) {
+    const isObj = typeof req === 'object' && req !== null && !Array.isArray(req);
+    const r = (isObj ? req : {});
+    const hasId = isObj && 'id' in r && r.id !== null && r.id !== undefined;
+    const id = hasId ? r.id : null;
+    const params = (typeof r.params === 'object' && r.params !== null ? r.params : {});
+    const reply = (result) => (hasId ? { jsonrpc: '2.0', id, result } : null);
+    const errReply = (code, message) => (hasId ? { jsonrpc: '2.0', id, error: { code, message } } : null);
+    if (typeof r.method !== 'string')
+        return errReply(-32600, 'invalid request');
+    const method = r.method;
+    // Lifecycle methods allowed before initialization completes.
+    if (method === 'notifications/initialized') {
+        if (session)
+            session.initialized = true;
+        return null;
+    }
+    if (method === 'initialize') {
+        if (session)
+            session.initialized = false; // re-init resets; the initialized notification re-arms it
+        const want = params.protocolVersion;
+        const protocolVersion = typeof want === 'string' && PROTOCOL_VERSIONS.includes(want) ? want : PROTOCOL_VERSIONS[0];
+        return reply({ protocolVersion, serverInfo: SERVER_INFO, capabilities: { tools: { listChanged: false } } });
+    }
+    if (method === 'ping')
+        return reply({});
+    if (session && !session.initialized)
+        return errReply(-32600, 'received request before initialization');
+    try {
+        switch (method) {
+            case 'tools/list': return reply({ tools: TOOLS });
+            case 'tools/call': {
+                const name = params.name;
+                if (typeof name !== 'string' || !TOOL_NAMES.has(name))
+                    return errReply(-32602, `unknown tool: ${String(name)}`);
+                const args = (typeof params.arguments === 'object' && params.arguments !== null ? params.arguments : {});
+                try {
+                    const out = handleTool(store, name, args);
+                    return reply({ content: [{ type: 'text', text: JSON.stringify(out) }], isError: false });
+                }
+                catch (e) {
+                    // Tool EXECUTION errors stay in-band (isError) so the model sees them and can recover.
+                    return reply({ content: [{ type: 'text', text: e.message }], isError: true });
+                }
+            }
+            default: return errReply(-32601, `unknown method: ${method}`);
+        }
+    }
+    catch (e) {
+        return errReply(-32603, e.message);
+    }
+}
+/**
+ * MCP stdio loop: newline-delimited JSON-RPC over stdin/stdout (the MCP stdio transport — not
+ * Content-Length framing, ADR-0007). A malformed line is answered with a JSON-RPC parse error
+ * (-32700), not silently dropped. Only valid MCP messages are written to `output` (stdout
+ * hygiene); diagnostics belong on stderr. Consumes input until EOF.
+ */
+export async function serve(store, input = process.stdin, output = process.stdout) {
+    const rl = createInterface({ input, crlfDelay: Infinity });
+    const session = { initialized: false };
+    for await (const line of rl) {
+        const t = line.trim();
+        if (!t)
+            continue;
+        let req;
+        try {
+            req = JSON.parse(t);
+        }
+        catch {
+            output.write(JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'parse error' } }) + '\n');
+            continue;
+        }
+        const res = dispatch(store, req, session);
+        if (res)
+            output.write(JSON.stringify(res) + '\n');
+    }
+}

package/dist/palette.js

@@ -0,0 +1,63 @@
+// Pure core for the lobby's inline `/` command palette (Claude-style, non-modal). Unlike the modal
+// picker (select.ts), here the TYPED LINE is primary: a suggestion list appears *below* the line you're
+// editing as soon as it starts with `/`, filters as you type, and ⏎ runs exactly what you typed — it
+// never force-selects the top item. ↑/↓ opt into picking a suggestion; ⏎ then runs the highlighted one.
+// No npm deps, no I/O — the raw-mode stdin loop + ANSI redraw live in cli.ts (readLobbyLine).
+export function initPalette(buf = '') { return { buf, index: 0, navigated: false }; }
+/** Suggestions are shown ONLY while the buffer is a slash-command being typed (`/…`). Filtered by the
+ *  text after the leading `/` (substring over cmd + desc). Empty when the line isn't a slash command —
+ *  so bare verbs / agent names (`verify`, `codex fix bug`) type freely with no popup. */
+export function paletteSuggestions(buf, cmds) {
+    if (!buf.startsWith('/'))
+        return [];
+    const q = buf.slice(1).trim().toLowerCase();
+    if (!q)
+        return cmds;
+    return cmds.filter((c) => `${c.cmd} ${c.desc}`.toLowerCase().includes(q));
+}
+/** Pure reducer: (state, key) → next state OR a terminal step. Mirrors select.ts but the default ⏎
+ *  action is "run what I typed", not "accept the highlighted item". */
+export function reducePaletteKey(state, key, cmds) {
+    const sugg = paletteSuggestions(state.buf, cmds);
+    const n = sugg.length;
+    const idx = n ? Math.min(state.index, n - 1) : 0;
+    if (key.ctrl && key.name === 'c')
+        return { kind: 'sigint' };
+    if (key.ctrl && key.name === 'd')
+        return state.buf ? { kind: 'edit', state } : { kind: 'exit' };
+    if (key.name === 'escape')
+        return { kind: 'edit', state: initPalette('') }; // close the palette / clear the line
+    if (key.name === 'return' || key.name === 'enter') {
+        if (n && state.navigated)
+            return { kind: 'submit', line: sugg[idx].cmd }; // user picked one → run it
+        const line = state.buf.trim();
+        if (line === '' || line === '/')
+            return { kind: 'edit', state }; // nothing meaningful typed → no-op
+        return { kind: 'submit', line };
+    }
+    if (key.name === 'up')
+        return { kind: 'edit', state: { ...state, index: n ? (idx - 1 + n) % n : 0, navigated: true } };
+    if (key.name === 'down')
+        return { kind: 'edit', state: { ...state, index: n ? (idx + 1) % n : 0, navigated: true } };
+    if (key.name === 'tab')
+        return n ? { kind: 'edit', state: { buf: `${sugg[idx].cmd} `, index: 0, navigated: false } } : { kind: 'edit', state };
+    if (key.name === 'backspace')
+        return { kind: 'edit', state: { ...state, buf: state.buf.slice(0, -1), index: 0, navigated: false } };
+    // A single printable character extends the line (control sequences ignored). Typing resets the
+    // highlight so ⏎ goes back to "run what I typed" until the user navigates again.
+    const ch = key.sequence;
+    if (ch && ch.length === 1 && ch >= ' ' && !key.ctrl) {
+        return { kind: 'edit', state: { ...state, buf: state.buf + ch, index: 0, navigated: false } };
+    }
+    return { kind: 'edit', state };
+}
+/** Pure renderer for the suggestion list drawn below the input line (no ANSI; the I/O layer colors the
+ *  hints). Returns [] when no suggestions are visible. The input line itself is drawn by the caller. */
+export function renderPaletteSuggestions(state, cmds, marker = '>') {
+    const sugg = paletteSuggestions(state.buf, cmds);
+    if (!sugg.length)
+        return [];
+    const w = Math.max(...sugg.map((c) => c.cmd.length));
+    const idx = Math.min(state.index, sugg.length - 1);
+    return sugg.map((c, i) => `${i === idx ? `${marker} ` : '  '}${c.cmd.padEnd(w)}   ${c.desc}`);
+}

package/dist/projector.js

@@ -0,0 +1,65 @@
+// Projects the single source of truth into the three native context files.
+// The canonical CORE BLOCK is byte-identical across all three => guaranteed sync.
+import { buildAdrDigest } from './adr.js';
+import { renderContractDigest } from './task.js';
+import { wrapManaged, upsertManagedBlock } from './managedBlock.js';
+export function buildCoreBlock(state) {
+    const rulesVal = state.config['rules'];
+    const rules = typeof rulesVal === 'string' && rulesVal.trim() ? rulesVal.trim() : '_No project rules defined._';
+    const roleEntries = Object.entries(state.roles);
+    const roleLines = roleEntries.length === 0
+        ? '_No roles assigned._'
+        : roleEntries.map(([r, a]) => `- **${r}** → ${a}`).join('\n');
+    const contract = state.taskContract ? renderContractDigest(state.taskContract) : '_No active task contract._';
+    // Operating guide for the AGENT (ADR-0012): framein is driven from inside your normal flow, not by the
+    // human typing long commands. Run any verb with the shell (`framein <verb>`) or the host slash command.
+    const guide = [
+        'This project is kept aligned by **framein** (intent → validation → continuity). Drive it from your',
+        'normal flow — run a verb with the shell (`framein <verb>`) or the host command (`/fr:<verb>`, Codex',
+        '`$fr-<verb>`). Automation-facing verbs expose `--json`; use the generated wrapper syntax when available.',
+        'On Windows PowerShell, use `framein.cmd <verb>` if the npm `.ps1` shim is blocked; generated wrappers already do this.',
+        '',
+        '- **At session start (and after any model switch)** — run `framein capsule` first to load where the',
+        '  project left off (last-green commit, recent changes, open blocker, decisions). This is how context',
+        '  follows you across models — don\'t ask the user to re-explain.',
+        '- **Task start** — fix what "done" means before coding: `framein start "<goal>"`, then',
+        '  `framein task amend acceptance|nongoal|protected "<…>"`. Changes auto-apply and show up in `git diff` —',
+        '  keep them honest; the human reviews. Don\'t silently drift the contract.',
+        '- **Before you claim done** — run the Validation Gate: `framein verify`. Never report "done" without it.',
+        '- **Ship** — `framein ship` for commit/deploy readiness.',
+        '- **Risky change** (auth · payments · migrations · deploy · secrets) — `framein risk`, then satisfy the required gates.',
+        '- **Stuck in a repeat-fix loop** — `framein rescue` (it proposes options; it never auto-acts).',
+        '- **Want a second opinion** — `framein challenge "<proposal>" --run` gets an INDEPENDENT model\'s verdict',
+        '  (a *different* model reviews — don\'t write the critique yourself; you keep the lead and `decide`).',
+        '- **Hand work to another model** — `framein capsule <agent>`, then exit; framein switches to that model,',
+        '  which loads the capsule on arrival. The context follows the handoff automatically.',
+        '',
+        'The **Task Contract** below is the definition of done — honor it. The human stays the final gate.',
+    ].join('\n');
+    return [
+        '## Working with framein', guide, '',
+        '## Task Contract', contract, '',
+        '## Project Rules', rules, '',
+        '_Project defaults — change them with `framein rules set "<…>"` (edits typed directly here are overwritten on sync). They guide the agent; the Validation Gate is what\'s enforced._', '',
+        '## Agent Roles', roleLines, '',
+        '## Architecture Decisions (digest)', buildAdrDigest(state.adrs),
+    ].join('\n');
+}
+/** The managed block (markers + canonical core), byte-identical across all three files. */
+export function renderManagedBlock(state) {
+    return wrapManaged(buildCoreBlock(state));
+}
+/** A from-scratch native file (heading + managed block); used when no file exists yet. */
+function projectFresh(title, state) {
+    return upsertManagedBlock(null, title, renderManagedBlock(state));
+}
+export function projectClaudeMd(state) { return projectFresh('CLAUDE.md', state); }
+export function projectAgentsMd(state) { return projectFresh('AGENTS.md', state); }
+export function projectGeminiMd(state) { return projectFresh('GEMINI.md', state); }
+export function projectAll(state) {
+    return {
+        'CLAUDE.md': projectClaudeMd(state),
+        'AGENTS.md': projectAgentsMd(state),
+        'GEMINI.md': projectGeminiMd(state),
+    };
+}

package/dist/quota.js

@@ -0,0 +1,30 @@
+// Reactive quota detection (F-ROLE-3). Parse a CLI's stderr/output for rate-limit / quota /
+// overload signals so the orchestrator can fail over to another agent. This is NOT "bypassing
+// limits" — it routes work within each subscription's normal use. Pure + fixture-tested; the
+// live capture of `output` (a real CLI run) is the B-layer spawn (see delegate.ts / M10).
+// Checked in order of severity: a hard quota wins over a transient rate-limit / overload.
+const QUOTA = /quota|usage limit|resource_exhausted|insufficient_quota/i;
+const RATE = /\b429\b|rate[\s_-]?limit|too many requests/i;
+const OVERLOAD = /overloaded|server is busy|try again later|\b529\b/i;
+function parseRetryAfter(text) {
+    const m = text.match(/retry[\s-]?after[:\s]+(\d+)/i) ?? text.match(/try again in (\d+)\s*(seconds?|secs?|minutes?|mins?)/i);
+    if (!m)
+        return undefined;
+    const n = Number(m[1]);
+    if (!Number.isFinite(n))
+        return undefined;
+    const unit = (m[2] ?? 's').toLowerCase();
+    return unit.startsWith('min') ? n * 60 : n;
+}
+/** Classify a single agent's output. `exhausted` is the failover trigger. */
+export function detectQuotaSignal(agent, output) {
+    const text = output ?? '';
+    let kind;
+    if (QUOTA.test(text))
+        kind = 'quota';
+    else if (RATE.test(text))
+        kind = 'rate-limit';
+    else if (OVERLOAD.test(text))
+        kind = 'overloaded';
+    return { agent, exhausted: kind !== undefined, kind, retryAfterSec: parseRetryAfter(text) };
+}

package/dist/recipe.js

@@ -0,0 +1,55 @@
+// Frame Recipe (F-LOOP-8, ADR-0008): a VENDOR-NEUTRAL task protocol (feature/bugfix/ship) that we
+// COMPILE/PROJECT onto each CLI's native features — NOT "run a Claude skill inside Codex" (that's a
+// category error, ADR-0002/0004). The same numbered protocol body is emitted for every agent; only
+// the header naming the agent's native mechanism differs. Shared state stays in framein MCP + ledger.
+import { PLAIN } from './ui/theme.js';
+export const RECIPES = [
+    { name: 'feature', trigger: 'feature', steps: [
+            { role: 'lead', action: 'define_contract' },
+            { role: 'implementer', action: 'implement' },
+            { action: 'run_validation', required: ['tests', 'build'] },
+            { role: 'reviewer', action: 'blocker_review', readOnly: true },
+            { role: 'implementer', action: 'resolve_findings' },
+            { action: 'human_approval' },
+        ] },
+    { name: 'bugfix', trigger: 'bugfix', steps: [
+            { role: 'implementer', action: 'reproduce' },
+            { role: 'reviewer', action: 'root_cause', readOnly: true },
+            { role: 'implementer', action: 'minimal_fix' },
+            { action: 'run_validation', required: ['regression_test'] },
+            { action: 'human_approval' },
+        ] },
+    { name: 'ship', trigger: 'ship', steps: [
+            { action: 'verify_changes', required: ['tests', 'build'] },
+            { action: 'risk_check' },
+            { role: 'explainer', action: 'ownership_brief' },
+            { action: 'human_approval' },
+        ] },
+];
+// How each CLI expresses a recipe natively (we project onto these; we do not cross-execute).
+const NATIVE_MECHANISM = {
+    claude: 'a Claude Skill + hooks + subagent guidance',
+    codex: 'a Codex skill / plugin / workflow',
+    gemini: 'a Gemini extension / skill / hooks',
+};
+export function listRecipes() { return RECIPES; }
+export function getRecipe(name) { return RECIPES.find((r) => r.name === name); }
+function stepLines(r) {
+    return r.steps.map((s, i) => {
+        const who = s.role ? `[${s.role}] ` : '';
+        const ro = s.readOnly ? ' (read-only)' : '';
+        const req = s.required ? ` — required: ${s.required.join(', ')}` : '';
+        return `${i + 1}. ${who}${s.action}${ro}${req}`;
+    });
+}
+export function renderRecipe(r, ui = PLAIN) {
+    return [ui.tone(`recipe: ${r.name} (trigger: ${r.trigger})`, 'muted'), ...stepLines(r)].join('\n');
+}
+/** Project a recipe onto one agent's native mechanism. Body (numbered steps) is identical per agent. */
+export function compileRecipe(r, agent) {
+    return [
+        `# ${r.name} — compiled for ${agent} as ${NATIVE_MECHANISM[agent]}`,
+        ...stepLines(r),
+        'Shared state: framein MCP + task ledger (the contract, decisions, and validation results all agents read).',
+    ].join('\n');
+}

package/dist/rescue.js

@@ -0,0 +1,38 @@
+// Rescue Mode (F-LOOP-3, ADR-0008): promote the anomaly detector from a side feature to a
+// flagship. When the ledger shows a repair loop, assemble a rescue report — the signals, the last
+// green checkpoint, and three options (diagnose / rewind / continue) — and NEVER act automatically.
+// Pure logic; the actual model diagnosis (option A) and the git rewind (option B) live in cli.ts.
+import { PLAIN } from './ui/theme.js';
+const short = (sha) => sha.slice(0, 7);
+export function buildRescue(signals, opts = {}) {
+    const triggered = signals.length > 0;
+    const options = [];
+    if (triggered) {
+        const who = opts.reviewer ?? 'the reviewer role';
+        options.push({ key: 'A', label: `Ask ${who} to diagnose without editing` });
+        if (opts.lastGreen) {
+            options.push({ key: 'B', label: `Rewind to checkpoint ${short(opts.lastGreen.sha)}${opts.lastGreen.label ? ` (${opts.lastGreen.label})` : ''}` });
+        }
+        options.push({ key: opts.lastGreen ? 'C' : 'B', label: 'Continue with the current agent' });
+    }
+    return { triggered, signals, lastGreen: opts.lastGreen, reviewer: opts.reviewer, options };
+}
+export function renderRescue(report, ui = PLAIN) {
+    if (!report.triggered)
+        return 'No repair loop detected. (rescue is anomaly-triggered — ADR-0005)';
+    const lines = [ui.tone('Framein detected a repair loop.', 'danger'), ''];
+    for (const s of report.signals)
+        lines.push(`  ${ui.tone(ui.sym.warn, 'warning')} ${s.message}`);
+    lines.push('');
+    if (report.lastGreen) {
+        lines.push(`Last green checkpoint: ${short(report.lastGreen.sha)}${report.lastGreen.label ? ` (${report.lastGreen.label})` : ''}`);
+    }
+    else {
+        lines.push('No green checkpoint recorded (run `frame checkpoint` at a known-good state).');
+    }
+    lines.push('', 'Recommended:');
+    for (const o of report.options)
+        lines.push(`  ${ui.tone(o.key, 'brand')}. ${o.label}`);
+    lines.push('', ui.tone('No action taken automatically.', 'muted'));
+    return lines.join('\n');
+}

package/dist/roles.js

@@ -0,0 +1,61 @@
+// Role presets + routing score function (PRD section 5.2).
+// Vendor-role mapping is NOT hardcoded: these are defaults the user can override.
+import { AGENTS, ROLES } from './types.js';
+/** Runtime guard: is `x` one of the three first-class agents? */
+export function isAgent(x) {
+    return AGENTS.includes(x);
+}
+/** Runtime guard: is `x` one of the five role presets? */
+export function isRole(x) {
+    return ROLES.includes(x);
+}
+export const DEFAULT_ROLE_PRIORITY = {
+    lead: ['claude', 'codex'],
+    implementer: ['claude', 'codex'],
+    reviewer: ['codex', 'claude'],
+    explainer: ['gemini', 'claude'],
+    researcher: ['gemini', 'claude'],
+};
+/** Compliance rule (PRD non-goal): consumer Gemini login is not permitted. */
+export function isForbiddenAuth(agent, auth) {
+    return agent === 'gemini' && auth === 'consumer-login';
+}
+/** Repo-local routing bonus: reward local success, penalize local quota trouble (F-LOOP-7). */
+export function repoBonus(st) {
+    if (!st || st.delegations === 0)
+        return 0;
+    const successRate = (st.delegations - st.failures) / st.delegations; // 0..1
+    return successRate * 2 - st.quotaHits * 0.5;
+}
+export const POLICY_PENALTY = Number.POSITIVE_INFINITY;
+// score = roleFit + quotaScore - failurePenalty - costPenalty
+// forbidden auth combos => -Infinity (never selected).
+export function scoreAgent(agent, ctx) {
+    const auth = ctx.authMode[agent];
+    if (auth && isForbiddenAuth(agent, auth))
+        return -POLICY_PENALTY;
+    if (ctx.unavailable?.[agent])
+        return -POLICY_PENALTY; // quota-exhausted / down => fail over to another agent
+    const priority = (ctx.rolePriority ?? DEFAULT_ROLE_PRIORITY)[ctx.role] ?? [];
+    const idx = priority.indexOf(agent);
+    const roleFit = idx === -1 ? 0 : priority.length - idx;
+    const quota = ctx.remainingQuota?.[agent];
+    const quotaScore = quota === undefined ? 1 : quota * 2;
+    const failurePenalty = (ctx.recentFailures?.[agent] ?? 0) * 1.5;
+    const costPenalty = ctx.costBand?.[agent] ?? 0;
+    return roleFit + quotaScore + repoBonus(ctx.repoStats?.[agent]) - failurePenalty - costPenalty;
+}
+export function selectAgent(candidates, ctx) {
+    let best = null;
+    let bestScore = -POLICY_PENALTY;
+    for (const a of candidates) {
+        const s = scoreAgent(a, ctx);
+        if (s === -POLICY_PENALTY)
+            continue;
+        if (best === null || s > bestScore) {
+            best = a;
+            bestScore = s;
+        }
+    }
+    return best;
+}

package/dist/select.js

@@ -0,0 +1,50 @@
+// Pure core for the zero-dep arrow-key picker. The raw-mode stdin loop + ANSI redraw live in cli.ts
+// (promptSelect); this module is the testable reducer: (state, keypress) -> next state OR a terminal
+// action. No npm deps, no I/O. `index` always refers to the CURRENTLY VISIBLE (filtered) list.
+/** Case-insensitive substring filter over label + hint + value. Order preserved. */
+export function filterItems(items, query) {
+    const q = query.trim().toLowerCase();
+    if (!q)
+        return items;
+    return items.filter((it) => `${it.label} ${it.hint ?? ''} ${it.value}`.toLowerCase().includes(q));
+}
+export function initSelect(items) {
+    return { items, query: '', index: 0 };
+}
+/** Pure reducer. Returns the next state (kind 'move') or a terminal action ('accept' | 'cancel'). */
+export function reduceSelectKey(state, key) {
+    const visible = filterItems(state.items, state.query);
+    const n = visible.length;
+    const idx = n ? Math.min(state.index, n - 1) : 0;
+    if (key.ctrl && key.name === 'c')
+        return { kind: 'cancel' };
+    if (key.name === 'escape')
+        return { kind: 'cancel' };
+    if (key.name === 'return' || key.name === 'enter') {
+        return n ? { kind: 'accept', value: visible[idx].value } : { kind: 'move', state };
+    }
+    if (key.name === 'up')
+        return { kind: 'move', state: { ...state, index: n ? (idx - 1 + n) % n : 0 } };
+    if (key.name === 'down')
+        return { kind: 'move', state: { ...state, index: n ? (idx + 1) % n : 0 } };
+    if (key.name === 'backspace')
+        return { kind: 'move', state: { ...state, query: state.query.slice(0, -1), index: 0 } };
+    // A single printable character extends the type-to-filter query (control sequences are ignored).
+    const ch = key.sequence;
+    if (ch && ch.length === 1 && ch >= ' ' && !key.ctrl) {
+        return { kind: 'move', state: { ...state, query: state.query + ch, index: 0 } };
+    }
+    return { kind: 'move', state };
+}
+/** Pure renderer: the lines to draw (no ANSI; the I/O layer colors them). First line is the label. */
+export function renderSelectLines(label, state, marker = '>') {
+    const visible = filterItems(state.items, state.query);
+    const head = state.query ? `${label}  (filter: ${state.query})` : label;
+    if (!visible.length)
+        return [head, '  (no matches — backspace to clear)'];
+    const idx = Math.min(state.index, visible.length - 1);
+    return [head, ...visible.map((it, i) => {
+            const hint = it.hint ? `   ${it.hint}` : '';
+            return `${i === idx ? `${marker} ` : '  '}${it.label}${hint}`;
+        })];
+}

package/dist/shell.js

@@ -0,0 +1,127 @@
+// Optional interactive `framein` lobby (ADR-0010, layer 4). A zero-dep readline *switchboard*: run framein
+// verbs inline, switch the lead agent, and hand the terminal to a lead's NATIVE TUI via stdio:'inherit'
+// (framein pauses while the lead drives, resumes on exit). Simultaneous overlay of framein + a live TUI
+// would require node-pty (a native dep) — deferred/optional, never bundled (ADR-0010). This module is the
+// PURE line router (fully unit-tested); the I/O loop (readline + spawn) is the thin wrapper in cli.ts.
+import { AGENTS } from './types.js';
+import { isAgent } from './roles.js';
+/** Split a lobby line into tokens, honoring "double" and 'single' quotes (quotes stripped) so multi-word
+ *  values like `start "add Google login"` survive as one token instead of leaking literal quotes. */
+export function tokenizeLine(line) {
+    const tokens = [];
+    const re = /"([^"]*)"|'([^']*)'|(\S+)/g;
+    let m;
+    while ((m = re.exec(line)) !== null)
+        tokens.push(m[1] ?? m[2] ?? m[3]);
+    return tokens;
+}
+/** Map one input line to an action. Pure: no I/O, no agent launch — the loop performs the effect. */
+export function routeShellLine(line, state) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return { kind: 'noop' };
+    const tokens = tokenizeLine(trimmed);
+    const head = tokens[0].toLowerCase();
+    const rest = tokens.slice(1);
+    if (head === 'exit' || head === 'quit' || head === '/exit' || head === '/quit')
+        return { kind: 'exit' };
+    if (head === 'help' || head === '/help' || head === '?')
+        return { kind: 'help' };
+    if (head === '/lead') {
+        if (rest.length === 0)
+            return { kind: 'pickLead' }; // bare /lead → interactive picker (TTY); printed fallback otherwise
+        const agent = rest[0].toLowerCase();
+        if (!isAgent(agent))
+            return { kind: 'error', message: `Unknown agent '${rest[0]}'. Valid: ${AGENTS.join(', ')}` };
+        return { kind: 'setLead', agent };
+    }
+    if (head === '/go') {
+        const prompt = rest.join(' ').trim();
+        return { kind: 'launchLead', agent: state.lead, prompt: prompt || undefined };
+    }
+    if (head === '/trust')
+        return { kind: 'toggleTrust' }; // arm/disarm permission-bypass for the next /go (time-boxed)
+    // A bare agent name (optionally with a prompt) switches to + launches that agent's native TUI.
+    if (isAgent(head)) {
+        const prompt = rest.join(' ').trim();
+        return { kind: 'launchLead', agent: head, prompt: prompt || undefined };
+    }
+    // Otherwise it's a framein command — `/verify` and `verify` both reach the engine.
+    const verb = head.startsWith('/') ? head.slice(1) : head;
+    if (verb === 'lobby' || verb === 'shell')
+        return { kind: 'error', message: 'Already in the lobby.' };
+    return { kind: 'engine', args: [verb, ...rest] };
+}
+/** Rows for the context card shown right before handing the terminal to a lead's native TUI (`/go`).
+ *  Pure: the loop reads these from the store and renders them, so the user carries intent INTO the
+ *  native UI. We surface state here; we never screen-scrape the TUI itself (ADR-0009). */
+export function handoffCardRows(info) {
+    const rows = [['lead', info.lead]];
+    if (info.reviewer)
+        rows.push(['reviewer', info.reviewer]);
+    rows.push(['task', info.goal && info.goal.trim() ? info.goal : 'no active contract']);
+    if (info.lastGreen)
+        rows.push(['last green', info.lastGreen]);
+    if (info.blocker)
+        rows.push(['blocker', info.blocker]);
+    return rows;
+}
+export function renderShellHelp() {
+    return [
+        'framein lobby — your switchboard for AI coding. The leading / is optional. Every verb is',
+        'deterministic and LOCAL: you don’t need an agent to run one (the agent just decides when to).',
+        '',
+        '  Lobby-only — choose who drives & hand off (these live in the lobby, not inside agents):',
+        '    /lead                switch the lead agent (↑↓ · type to filter · enter)',
+        '    /go [task]           hand the terminal to the lead — work there, exit (Ctrl-D) to return',
+        '    /trust               arm/disarm permission-bypass for /go (off by default · 30m)',
+        '    /exit                leave the lobby (or Ctrl-D on an empty line)',
+        `    ${AGENTS.join(' · ')}   shortcut: jump straight into that agent (e.g. \`codex fix the bug\`)`,
+        '',
+        '  framein verbs — run here, inside your agent (/fr:verify · $fr-verify), or as `framein <verb>`:',
+        '    start <goal>         define what “done” means — the Task Contract',
+        '    verify               run build/test, check validation against the contract',
+        '    ship                 deployment-readiness gate (blocks if not ready)',
+        '    risk                 blast-radius of the current change',
+        '    rescue               stuck in a fix-loop? show the loop + safe options',
+        '    challenge · decide   have another model argue a proposal, then you rule',
+        '    task · capsule       show/amend the contract · carry state across a model switch',
+        '    status               project · contract · state',
+        '',
+        '  Also in the lobby / terminal (not wrapped into agents): init · stats · explain',
+        '',
+        'Tip: type / to browse (filters as you type · ↑↓ to pick · ⏎ runs) · full list: framein --help · manual: docs/MANUAL.md',
+    ].join('\n');
+}
+/** Verbs offered by lobby Tab-completion (a friendly subset of the full CLI surface). */
+export const LOBBY_VERBS = ['init', 'start', 'verify', 'ship', 'rescue', 'status', 'stats', 'explain', 'risk', 'task', 'checkpoint', 'capsule'];
+const LOBBY_COMMANDS = [...LOBBY_VERBS, ...LOBBY_VERBS.map((v) => `/${v}`), '/lead', '/go', '/trust', '/help', 'exit', 'quit'];
+/** readline completer for the lobby line editor (pure). Completes agent names after `/lead `, otherwise
+ *  the first token against the verb / slash-command list. Returns [matches, fragmentBeingCompleted]. */
+export function lobbyCompleter(line) {
+    const lead = line.match(/^\/lead\s+(\S*)$/i);
+    if (lead) {
+        const frag = lead[1];
+        const hits = AGENTS.filter((a) => a.startsWith(frag.toLowerCase()));
+        return [hits.length ? hits : AGENTS.slice(), frag];
+    }
+    const hits = LOBBY_COMMANDS.filter((c) => c.startsWith(line));
+    return [hits, line];
+}
+/** Commands shown in the lobby's live `/` palette (the inline menu opened by typing `/`). All slash-
+ *  prefixed for consistency; the leading `/` is what surfaces the menu. Curated to what's actually
+ *  useful FROM the lobby — the deterministic checks ("local, no agent" → they run without an LLM) plus
+ *  the switchboard verbs. The real coding happens after /go, inside the lead's own UI. (palette.ts) */
+export const LOBBY_PALETTE = [
+    { cmd: '/go', desc: 'hand the terminal to the lead agent — where the coding happens' },
+    { cmd: '/lead', desc: 'switch the lead agent (claude · codex · gemini)' },
+    { cmd: '/trust', desc: 'arm/disarm permission-bypass for /go (time-boxed)' },
+    { cmd: '/status', desc: 'project · contract · state (local, no agent)' },
+    { cmd: '/verify', desc: 'run build/test, check validation vs the contract (local, no agent)' },
+    { cmd: '/ship', desc: 'deployment-readiness check (local, no agent)' },
+    { cmd: '/risk', desc: 'blast-radius of the current changes (local, no agent)' },
+    { cmd: '/rescue', desc: 'stuck? detect the loop + get options (local, no agent)' },
+    { cmd: '/init', desc: 'set up framein in this folder' },
+    { cmd: '/help', desc: 'all commands' },
+    { cmd: '/exit', desc: 'leave the lobby' },
+];