framein 0.0.4

package/dist/stats.js

@@ -0,0 +1,74 @@
+// Repo-local Routing (F-LOOP-7, ADR-0008): route by THIS repo's actual results, not generic model
+// reputation, and — crucially — EXPLAIN the choice rather than auto-deciding silently (trust comes
+// from "why", not magic). Pure: derive per-agent stats from the ledger, then score + explain via
+// roles.scoreAgent. Accumulating richer signals (first-try pass rate, human reverts) comes later.
+import { AGENTS } from './types.js';
+import { scoreAgent, DEFAULT_ROLE_PRIORITY } from './roles.js';
+import { PLAIN } from './ui/theme.js';
+const isAgentName = (s) => AGENTS.includes(s);
+/** The trailing token of a ledger target is the agent: "reviewer:codex" -> codex, "codex" -> codex. */
+function agentOf(target) {
+    const tail = target.split(':').pop() ?? '';
+    return isAgentName(tail) ? tail : undefined;
+}
+export function computeRepoStats(ledger) {
+    const stats = {};
+    const ensure = (a) => (stats[a] ??= { delegations: 0, failures: 0, quotaHits: 0 });
+    for (const e of ledger) {
+        const a = agentOf(e.target);
+        if (!a)
+            continue;
+        if (e.kind === 'delegated')
+            ensure(a).delegations++;
+        else if (e.kind === 'delegate-fail') {
+            const s = ensure(a);
+            s.delegations++;
+            s.failures++;
+        }
+        else if (e.kind === 'quota')
+            ensure(a).quotaHits++;
+    }
+    return stats;
+}
+function routeReasons(st) {
+    if (!st || st.delegations === 0)
+        return ['no local track record yet (using role defaults)'];
+    const success = st.delegations - st.failures;
+    const reasons = [`+ ${Math.round((success / st.delegations) * 100)}% delegation success in this repo (${success}/${st.delegations})`];
+    if (st.failures)
+        reasons.push(`- ${st.failures} failure${st.failures > 1 ? 's' : ''}`);
+    reasons.push(st.quotaHits ? `- ${st.quotaHits} quota hit${st.quotaHits > 1 ? 's' : ''}` : '+ no quota issues');
+    return reasons;
+}
+export function explainRoute(role, ctx, stats) {
+    const priority = (ctx.rolePriority ?? DEFAULT_ROLE_PRIORITY)[role] ?? [...AGENTS];
+    const scored = priority
+        .map((agent) => ({ agent, score: scoreAgent(agent, { ...ctx, role, repoStats: stats }) }))
+        .filter((s) => Number.isFinite(s.score))
+        .sort((a, b) => b.score - a.score);
+    const best = scored[0];
+    const second = scored[1];
+    let alternative;
+    if (best && second) {
+        const total = best.score + second.score;
+        alternative = { agent: second.agent, confidence: total > 0 ? Number((second.score / total).toFixed(2)) : 0 };
+    }
+    return { role, agent: best?.agent ?? null, reasons: best ? routeReasons(stats[best.agent]) : ['no eligible agent'], alternative };
+}
+export function renderRouteExplain(e, ui = PLAIN) {
+    const lines = [e.agent ? `Selected ${ui.tone(e.agent, 'brand')} as ${e.role}.` : `No eligible agent for ${e.role}.`, ui.tone('Why:', 'muted')];
+    for (const r of e.reasons)
+        lines.push(`  ${r}`);
+    if (e.alternative)
+        lines.push(ui.tone(`Alternative: ${e.alternative.agent}, confidence ${e.alternative.confidence}`, 'muted'));
+    return lines.join('\n');
+}
+export function renderStats(stats, ui = PLAIN) {
+    const entries = Object.entries(stats);
+    if (entries.length === 0)
+        return 'No repo-local stats yet. Delegations (`framein ask --run`) accumulate them.';
+    const lines = [ui.tone('Repo-local agent stats (from the ledger):', 'muted')];
+    for (const [a, st] of entries)
+        lines.push(`  ${ui.tone(a, 'brand')}: ${st.delegations} delegations, ${st.failures} failed, ${st.quotaHits} quota`);
+    return lines.join('\n');
+}

package/dist/store.js

@@ -0,0 +1,319 @@
+// The single source of truth: a SQLite-backed store for config, roles,
+// append-only ADRs, scoped memory, and the write lock.
+import { openDb } from './db.js';
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS config (
+  key TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS roles (
+  role TEXT PRIMARY KEY,
+  agent TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS adr (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  created_at TEXT NOT NULL,
+  title TEXT NOT NULL,
+  status TEXT NOT NULL,
+  context TEXT NOT NULL DEFAULT '',
+  decision TEXT NOT NULL,
+  consequences TEXT NOT NULL DEFAULT '',
+  author_agent TEXT,
+  supersedes INTEGER
+);
+CREATE TABLE IF NOT EXISTS memory (
+  scope TEXT NOT NULL,
+  key TEXT NOT NULL,
+  value TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  PRIMARY KEY (scope, key)
+);
+CREATE TABLE IF NOT EXISTS write_lock (
+  scope TEXT PRIMARY KEY,
+  holder TEXT,
+  acquired_at TEXT,
+  expires_at TEXT
+);
+CREATE TABLE IF NOT EXISTS ledger (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  ts TEXT NOT NULL,
+  kind TEXT NOT NULL,
+  target TEXT NOT NULL DEFAULT '',
+  detail TEXT NOT NULL DEFAULT ''
+);
+`;
+// Guard object-key injection (e.g. '__proto__' arriving via the MCP write_memory tool):
+// these keys are rejected at write time so assembled config/memory maps stay clean.
+const UNSAFE_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+function safeKey(k) {
+    if (UNSAFE_KEYS.has(k))
+        throw new Error(`unsafe key: ${k}`);
+    return k;
+}
+function sleepMs(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+function isBusy(e) {
+    const err = e;
+    return err.code === 'ERR_SQLITE_ERROR'
+        && /locked|busy/i.test(`${String(err.message ?? '')} ${String(err.errstr ?? '')}`);
+}
+function execWithBusyRetry(db, sql) {
+    const deadline = Date.now() + 5000;
+    for (;;) {
+        try {
+            db.exec(sql);
+            return;
+        }
+        catch (e) {
+            if (!isBusy(e) || Date.now() >= deadline)
+                throw e;
+            sleepMs(50);
+        }
+    }
+}
+function rowToAdr(row) {
+    return {
+        id: Number(row.id),
+        createdAt: String(row.created_at),
+        title: String(row.title),
+        status: row.status,
+        context: row.context ?? '',
+        decision: String(row.decision),
+        consequences: row.consequences ?? '',
+        authorAgent: row.author_agent ?? null,
+        supersedes: row.supersedes == null ? null : Number(row.supersedes),
+    };
+}
+export class Store {
+    db;
+    constructor(db) { this.db = db; }
+    static open(path = ':memory:') {
+        const db = openDb(path);
+        // WAL + a busy timeout let multiple processes share one .frame/store.db without
+        // "database is locked" errors; lock acquisition itself is a single atomic statement.
+        execWithBusyRetry(db, 'PRAGMA busy_timeout=5000;');
+        execWithBusyRetry(db, 'PRAGMA journal_mode=WAL;');
+        execWithBusyRetry(db, SCHEMA);
+        return new Store(db);
+    }
+    close() { this.db.close(); }
+    // --- config (project rules etc.) ---
+    setConfig(key, value) {
+        this.db.prepare('INSERT INTO config(key,value) VALUES(?,?) ON CONFLICT(key) DO UPDATE SET value=excluded.value').run(safeKey(key), JSON.stringify(value));
+    }
+    getConfig(key) {
+        const row = this.db.prepare('SELECT value FROM config WHERE key=?').get(key);
+        return row ? JSON.parse(row.value) : undefined;
+    }
+    getAllConfig() {
+        const rows = this.db.prepare('SELECT key,value FROM config').all();
+        const out = {};
+        for (const r of rows)
+            out[r.key] = JSON.parse(r.value);
+        return out;
+    }
+    // --- roles ---
+    setRole(role, agent) {
+        this.db.prepare('INSERT INTO roles(role,agent) VALUES(?,?) ON CONFLICT(role) DO UPDATE SET agent=excluded.agent').run(role, agent);
+    }
+    getRole(role) {
+        const row = this.db.prepare('SELECT agent FROM roles WHERE role=?').get(role);
+        return row?.agent;
+    }
+    getRoles() {
+        const rows = this.db.prepare('SELECT role,agent FROM roles').all();
+        const out = {};
+        for (const r of rows)
+            out[r.role] = r.agent;
+        return out;
+    }
+    // --- ADR (APPEND-ONLY by design: no update/delete methods exist) ---
+    appendAdr(input) {
+        const createdAt = new Date().toISOString();
+        const status = input.status ?? 'accepted';
+        const supersedes = input.supersedes ?? null;
+        if (supersedes != null && !this.getAdr(supersedes)) {
+            throw new Error(`ADR-${supersedes} not found; cannot supersede a non-existent decision`);
+        }
+        const res = this.db.prepare('INSERT INTO adr(created_at,title,status,context,decision,consequences,author_agent,supersedes) VALUES(?,?,?,?,?,?,?,?)').run(createdAt, input.title, status, input.context ?? '', input.decision, input.consequences ?? '', input.authorAgent ?? null, supersedes);
+        return {
+            id: Number(res.lastInsertRowid), createdAt, title: input.title, status,
+            context: input.context ?? '', decision: input.decision,
+            consequences: input.consequences ?? '', authorAgent: input.authorAgent ?? null,
+            supersedes,
+        };
+    }
+    /**
+     * Append-only correction: records a NEW ADR that replaces `oldId`. The old row is
+     * never mutated or deleted — supersession is a forward reference (see isSuperseded).
+     */
+    supersedeAdr(oldId, input) {
+        if (!this.getAdr(oldId))
+            throw new Error(`ADR-${oldId} not found; cannot supersede`);
+        if (this.isSuperseded(oldId))
+            throw new Error(`ADR-${oldId} is already superseded; supersede the current decision instead`);
+        return this.appendAdr({ ...input, supersedes: oldId });
+    }
+    getAdr(id) {
+        const row = this.db.prepare('SELECT * FROM adr WHERE id=?').get(id);
+        return row ? rowToAdr(row) : undefined;
+    }
+    /** True if some LATER ADR supersedes this one. Append-only: derived, not stored. */
+    isSuperseded(id) {
+        return this.db.prepare('SELECT 1 FROM adr WHERE supersedes=? AND id>? LIMIT 1').get(id, id) !== undefined;
+    }
+    listAdrs() {
+        const rows = this.db.prepare('SELECT * FROM adr ORDER BY id').all();
+        return rows.map(rowToAdr);
+    }
+    // --- memory (mutable working state, scoped) ---
+    setMemory(scope, key, value) {
+        this.db.prepare('INSERT INTO memory(scope,key,value,updated_at) VALUES(?,?,?,?) ON CONFLICT(scope,key) DO UPDATE SET value=excluded.value, updated_at=excluded.updated_at').run(safeKey(scope), safeKey(key), JSON.stringify(value), new Date().toISOString());
+    }
+    getMemory(scope, key) {
+        const row = this.db.prepare('SELECT value FROM memory WHERE scope=? AND key=?').get(scope, key);
+        return row ? JSON.parse(row.value) : undefined;
+    }
+    listMemory(scope) {
+        const rows = this.db.prepare('SELECT key,value FROM memory WHERE scope=?').all(scope);
+        const out = {};
+        for (const r of rows)
+            out[r.key] = JSON.parse(r.value);
+        return out;
+    }
+    deleteMemory(scope, key) {
+        this.db.prepare('DELETE FROM memory WHERE scope=? AND key=?').run(scope, key);
+    }
+    // --- write lock (governance: one writer at a time, per scope, with TTL) ---
+    // Acquisition is a SINGLE atomic conditional upsert — no read-then-write race across
+    // processes. A lock is takeable when it is free, held by the same holder (reentrant),
+    // or expired (its holder crashed without releasing).
+    //
+    // CAVEAT: reentrancy keys on the holder STRING. For cross-process mutual exclusion the
+    // caller must pass a holder that uniquely identifies the owner (e.g. include the pid) —
+    // two processes sharing a holder name would both be allowed in by design.
+    static DEFAULT_TTL_MS = 15 * 60 * 1000;
+    getLockHolder(scope = 'global') {
+        const row = this.db.prepare('SELECT holder, expires_at FROM write_lock WHERE scope=?').get(scope);
+        if (!row || row.holder == null)
+            return null;
+        if (row.expires_at != null && row.expires_at <= new Date().toISOString())
+            return null; // expired => free
+        return row.holder;
+    }
+    acquireLock(holder, opts = {}) {
+        const scope = opts.scope ?? 'global';
+        const ttlMs = opts.ttlMs ?? Store.DEFAULT_TTL_MS;
+        const now = new Date();
+        const acquiredAt = now.toISOString();
+        const expiresAt = new Date(now.getTime() + ttlMs).toISOString();
+        const res = this.db.prepare(`INSERT INTO write_lock(scope,holder,acquired_at,expires_at) VALUES(?,?,?,?)
+       ON CONFLICT(scope) DO UPDATE SET holder=excluded.holder, acquired_at=excluded.acquired_at, expires_at=excluded.expires_at
+       WHERE write_lock.holder IS NULL OR write_lock.holder=excluded.holder OR write_lock.expires_at <= excluded.acquired_at`).run(scope, holder, acquiredAt, expiresAt);
+        return res.changes > 0;
+    }
+    releaseLock(holder, opts = {}) {
+        const scope = opts.scope ?? 'global';
+        const res = this.db.prepare('UPDATE write_lock SET holder=NULL, acquired_at=NULL, expires_at=NULL WHERE scope=? AND holder=?').run(scope, holder);
+        return res.changes > 0;
+    }
+    /** Force-release a (possibly stale) lock regardless of holder. Backs `frame unlock`. */
+    forceUnlock(scope = 'global') {
+        this.db.prepare('UPDATE write_lock SET holder=NULL, acquired_at=NULL, expires_at=NULL WHERE scope=?').run(scope);
+    }
+    withWriteLock(holder, fn, opts = {}) {
+        if (opts.ttlMs !== undefined && opts.ttlMs <= 0) {
+            throw new Error('withWriteLock requires a positive ttlMs (a non-positive TTL expires immediately)');
+        }
+        if (!this.acquireLock(holder, opts)) {
+            throw new Error(`write lock held by '${this.getLockHolder(opts.scope)}', '${holder}' cannot acquire`);
+        }
+        try {
+            return fn();
+        }
+        finally {
+            this.releaseLock(holder, opts);
+        }
+    }
+    // --- task ledger (runtime work-events; feeds the anomaly/audit detector) ---
+    appendLedger(kind, target = '', detail = '') {
+        this.db.prepare('INSERT INTO ledger(ts,kind,target,detail) VALUES(?,?,?,?)').run(new Date().toISOString(), kind, target, detail);
+    }
+    /** Most recent `limit` ledger entries, returned in chronological order. */
+    listLedger(limit = 500) {
+        const rows = this.db.prepare('SELECT id,ts,kind,target,detail FROM ledger ORDER BY id DESC LIMIT ?').all(limit);
+        return rows.reverse().map((r) => ({
+            id: Number(r.id), ts: String(r.ts), kind: String(r.kind), target: String(r.target ?? ''), detail: String(r.detail ?? ''),
+        }));
+    }
+    // --- task contract (F-LOOP-1: mutable task state, stored under memory scope 'task') ---
+    getTaskContract() {
+        return this.getMemory('task', 'contract');
+    }
+    setTaskContract(c) {
+        this.setMemory('task', 'contract', c);
+    }
+    clearTaskContract() {
+        this.deleteMemory('task', 'contract');
+    }
+    // --- projection snapshot ---
+    getState() {
+        return { config: this.getAllConfig(), roles: this.getRoles(), adrs: this.listAdrs(), taskContract: this.getTaskContract() };
+    }
+    // --- git-friendly text serialization (F-SYNC-6) ---
+    static SCHEMA_VERSION = 1;
+    allMemory() {
+        const rows = this.db.prepare('SELECT scope,key,value FROM memory').all();
+        const out = {};
+        for (const r of rows) {
+            (out[r.scope] ??= {})[r.key] = JSON.parse(r.value);
+        }
+        return out;
+    }
+    /** Full snapshot for the canonical text form. The write lock is intentionally excluded. */
+    exportSnapshot() {
+        return {
+            schemaVersion: Store.SCHEMA_VERSION,
+            config: this.getAllConfig(),
+            roles: this.getRoles(),
+            adrs: this.listAdrs(),
+            memory: this.allMemory(),
+        };
+    }
+    /** Rebuild the store from a snapshot (replaces config/roles/adr/memory). ADR ids are
+     *  preserved so `supersedes` references stay valid. Transactional. */
+    importSnapshot(snap) {
+        if (snap.schemaVersion !== Store.SCHEMA_VERSION) {
+            throw new Error(`unsupported snapshot schemaVersion ${snap.schemaVersion} (expected ${Store.SCHEMA_VERSION})`);
+        }
+        this.db.exec('BEGIN');
+        try {
+            this.db.exec('DELETE FROM config; DELETE FROM roles; DELETE FROM adr; DELETE FROM memory;');
+            for (const [k, v] of Object.entries(snap.config))
+                this.setConfig(k, v);
+            for (const [r, a] of Object.entries(snap.roles))
+                this.setRole(r, a);
+            const ins = this.db.prepare('INSERT INTO adr(id,created_at,title,status,context,decision,consequences,author_agent,supersedes) VALUES(?,?,?,?,?,?,?,?,?)');
+            let maxAdrId = 0;
+            for (const a of snap.adrs) {
+                ins.run(a.id, a.createdAt, a.title, a.status, a.context, a.decision, a.consequences, a.authorAgent, a.supersedes);
+                if (a.id > maxAdrId)
+                    maxAdrId = a.id;
+            }
+            // Reset the AUTOINCREMENT counter so the next appendAdr() id follows the imported max,
+            // not the pre-import max (DELETE FROM adr does not touch sqlite_sequence).
+            this.db.exec("DELETE FROM sqlite_sequence WHERE name='adr'");
+            this.db.prepare("INSERT INTO sqlite_sequence(name,seq) VALUES('adr', ?)").run(maxAdrId);
+            for (const [scope, kv] of Object.entries(snap.memory)) {
+                for (const [k, v] of Object.entries(kv))
+                    this.setMemory(scope, k, v);
+            }
+            this.db.exec('COMMIT');
+        }
+        catch (e) {
+            this.db.exec('ROLLBACK');
+            throw e;
+        }
+    }
+}

package/dist/task.js

@@ -0,0 +1,94 @@
+// Task Contract (F-LOOP-1, ADR-0008): fix "what to treat as done" so every agent judges against
+// the same bar. Pure logic only — the store wiring lives in store.ts and the lead drafting a
+// contract from the user's prompt is the deferred live path. The contract is stored as structured
+// task state (memory scope 'task') and projected into the managed block as standing intent.
+import { PLAIN } from './ui/theme.js';
+export function emptyContract(goal = '') {
+    return { goal, mustPreserve: [], acceptance: [], protected: [], nonGoals: [] };
+}
+/** Set the goal, or append to a list field. Returns a new contract (does not mutate input). */
+export function amendContract(c, field, value) {
+    const next = {
+        goal: c.goal,
+        mustPreserve: [...c.mustPreserve],
+        acceptance: [...c.acceptance],
+        protected: [...c.protected],
+        nonGoals: [...c.nonGoals],
+    };
+    switch (field) {
+        case 'goal':
+            next.goal = value;
+            break;
+        case 'preserve':
+            next.mustPreserve.push(value);
+            break;
+        case 'acceptance':
+            next.acceptance.push(value);
+            break;
+        case 'protected':
+            next.protected.push(value);
+            break;
+        case 'nongoal':
+            next.nonGoals.push(value);
+            break;
+        default: {
+            const _x = field;
+            throw new Error(`unknown contract field: ${String(_x)}`);
+        }
+    }
+    return next;
+}
+export const GUIDED_CONTRACT_STEPS = [
+    { field: 'goal', question: 'Goal — what should be true when this is done?' },
+    { field: 'acceptance', question: 'Acceptance — how will you verify it? (enter to skip)' },
+    { field: 'nongoal', question: 'Non-goal — what is explicitly out of scope? (enter to skip)' },
+    { field: 'preserve', question: 'Must preserve — what must keep working? (enter to skip)' },
+];
+/** Build a contract from guided answers: goal is set (trimmed), blank optional answers are skipped. Pure. */
+export function buildGuidedContract(answers) {
+    let c = emptyContract((answers.goal ?? '').trim());
+    for (const { field } of GUIDED_CONTRACT_STEPS) {
+        if (field === 'goal')
+            continue;
+        const v = (answers[field] ?? '').trim();
+        if (v)
+            c = amendContract(c, field, v);
+    }
+    return c;
+}
+/** Soft warnings (the "ambiguous items" the lead would confirm once). Empty = well-formed. */
+export function contractIssues(c) {
+    const issues = [];
+    if (!c.goal.trim())
+        issues.push('no goal set');
+    if (c.acceptance.length === 0)
+        issues.push('no acceptance criteria — how will "done" be judged?');
+    return issues;
+}
+const inline = (xs) => xs.join('; ');
+/** Compact digest for the managed block (always-loaded standing intent). */
+export function renderContractDigest(c) {
+    if (!c.goal.trim() && c.acceptance.length === 0)
+        return '_No active task contract._';
+    const lines = [`**Goal:** ${c.goal || '(unset)'}`];
+    if (c.acceptance.length)
+        lines.push(`- Acceptance: ${inline(c.acceptance)}`);
+    if (c.mustPreserve.length)
+        lines.push(`- Must preserve: ${inline(c.mustPreserve)}`);
+    if (c.protected.length)
+        lines.push(`- Protected: ${inline(c.protected)}`);
+    if (c.nonGoals.length)
+        lines.push(`- Non-goals: ${inline(c.nonGoals)}`);
+    return lines.join('\n');
+}
+/** Full multi-line view for `frame task show`. */
+export function renderContractFull(c, ui = PLAIN) {
+    const section = (label, xs) => xs.length ? `  ${ui.tone(label, 'muted')}:\n${xs.map((x) => `    - ${x}`).join('\n')}` : `  ${ui.tone(label, 'muted')}: (none)`;
+    return [
+        `Task goal: ${ui.bold(c.goal || '(unset)')}`,
+        section('must preserve', c.mustPreserve),
+        section('acceptance', c.acceptance),
+        section('protected', c.protected),
+        section('non-goals', c.nonGoals),
+    ].join('\n');
+}

package/dist/trust.js

@@ -0,0 +1,39 @@
+// Unified permission mode (F-TRUST, ADR-0007 B-3). framein's most dangerous surface, so it leans
+// on SAFETY over convenience: per-agent opt-in, time-boxed, with honest limits. This module is
+// pure — it only PLANS what trust would enable (the bypass flags each CLI understands). framein
+// does NOT auto-apply it; actually launching an agent with these flags is the live path. A
+// worktree is NOT a sandbox (network/credentials/installs are not blocked) — surfaced as a warning.
+// The "stop asking me" flag per CLI. Codex's --full-auto stays sandboxed; the fuller
+// --dangerously-bypass-approvals-and-sandbox also drops the sandbox (mentioned in warnings).
+const BYPASS_FLAGS = {
+    claude: ['--dangerously-skip-permissions'],
+    codex: ['--full-auto'],
+    gemini: ['--yolo'],
+};
+export const DEFAULT_TRUST_TTL_SEC = 1800; // 30m
+/** Parse "90s" | "30m" | "1h" | "45" (bare = seconds). Returns seconds, or null if unparseable. */
+export function parseDuration(s) {
+    const m = /^(\d+)\s*(s|sec|secs|m|min|mins|h|hr|hrs)?$/i.exec(s.trim());
+    if (!m)
+        return null;
+    const n = Number(m[1]);
+    const unit = (m[2] ?? 's').toLowerCase();
+    if (unit.startsWith('h'))
+        return n * 3600;
+    if (unit.startsWith('m'))
+        return n * 60;
+    return n;
+}
+export function trustPlan(agent, opts = {}) {
+    const ttlSec = opts.ttlSec && opts.ttlSec > 0 ? opts.ttlSec : DEFAULT_TRUST_TTL_SEC;
+    return {
+        agent,
+        flags: BYPASS_FLAGS[agent],
+        ttlSec,
+        warnings: [
+            `${agent} will run WITHOUT per-action permission prompts (${BYPASS_FLAGS[agent].join(' ')}).`,
+            'A worktree is NOT a sandbox: network, credentials, and `npm install` are NOT blocked.',
+            'Use per-agent, time-boxed, and only for a task you trust; pair with freeze/careful guardrails.',
+        ],
+    };
+}

package/dist/types.js

@@ -0,0 +1,3 @@
+// Shared domain types for framein.
+export const AGENTS = ['claude', 'codex', 'gemini'];
+export const ROLES = ['lead', 'implementer', 'reviewer', 'explainer', 'researcher'];

package/dist/ui/banner.js

@@ -0,0 +1,32 @@
+// Active Frame banner + status block. PURE.
+// Width math is done on PLAIN text; color is applied by wrapping whole already-sized lines, so ANSI
+// escapes never corrupt alignment. Unicode box-drawing falls back to ASCII per capabilities (Windows).
+import { statusTone } from './theme.js';
+const MAXW = 72;
+function fit(s, w, unicode) {
+    if (s.length <= w)
+        return s.padEnd(w);
+    return s.slice(0, Math.max(0, w - 1)) + (unicode ? '…' : '~');
+}
+/** The open "Active Frame": brand-colored border with the title in the top rule. */
+export function renderFrame(title, body, ctx) {
+    const longest = Math.max(title.length + 4, ...body.map((b) => b.length + 2), 32);
+    const inner = Math.min(longest, MAXW - 2, Math.max(18, ctx.columns - 2));
+    const ch = ctx.unicode
+        ? { tl: '┌', tr: '┐', bl: '└', br: '┘', h: '─', v: '│' }
+        : { tl: '+', tr: '+', bl: '+', br: '+', h: '-', v: '|' };
+    const topRule = `${ch.h} ${title} `.padEnd(inner, ch.h).slice(0, inner);
+    const top = ctx.ui.tone(`${ch.tl}${topRule}${ch.tr}`, 'brand');
+    const bottom = ctx.ui.tone(`${ch.bl}${ch.h.repeat(inner)}${ch.br}`, 'brand');
+    const mid = body.map((b) => `${ch.v} ${fit(b, inner - 2, ctx.unicode)} ${ch.v}`);
+    return [top, ...mid, bottom].join('\n');
+}
+/** Indented, aligned key/value rows (§7.2 / §8.1 status block). Keys muted, values default. */
+export function renderKeyVals(rows, ui) {
+    const kw = rows.reduce((m, [k]) => Math.max(m, k.length), 0);
+    return rows.map(([k, v]) => `  ${ui.tone(k.padEnd(kw), 'muted')}   ${v}`).join('\n');
+}
+/** A result header: bold label + semantically-colored status word (§8.6/§8.7). */
+export function statusLine(label, status, ui) {
+    return `${ui.bold(label)}  ${ui.tone(status, statusTone(status))}`;
+}

package/dist/ui/capabilities.js

@@ -0,0 +1,35 @@
+// Terminal capability detection. PURE: resolveCapabilities takes
+// an explicit input snapshot so it is fully unit-testable; cli.ts feeds the real process/env values.
+// Zero-dep — every signal is a Node built-in (process.stdout.isTTY/.columns/.getColorDepth(), env).
+//
+// Two gates that matter for non-breaking output:
+//  - color  → ONLY when interactive (tty) + not disabled + depth≥4. Pipes/CI/tests get no ANSI, so
+//    existing plain-string assertions keep passing.
+//  - unicode→ symbols are UTF-8 and pipe fine, so default true; the ASCII fallback only kicks in on
+//    --plain or a *live* legacy Windows console (where box-drawing width actually breaks).
+function quantizeDepth(bits) {
+    if (bits >= 24)
+        return 24;
+    if (bits >= 8)
+        return 8;
+    if (bits >= 4)
+        return 4;
+    return 0;
+}
+export function resolveCapabilities(input = {}) {
+    const env = input.env ?? {};
+    const flags = input.flags ?? [];
+    const plain = flags.includes('--plain');
+    const tty = Boolean(input.isTTY);
+    const colorDepth = quantizeDepth(input.colorDepth ?? (tty ? 4 : 1));
+    // NO_COLOR: any defined value disables (informal standard). FORCE_COLOR (≠"0") forces on.
+    const noColor = plain || flags.includes('--no-color') || env.NO_COLOR !== undefined;
+    const forceColor = env.FORCE_COLOR !== undefined && env.FORCE_COLOR !== '0';
+    const color = !noColor && (forceColor || (tty && colorDepth >= 4));
+    const utf8 = /utf-?8/i.test(`${env.LANG ?? ''} ${env.LC_ALL ?? ''} ${env.LC_CTYPE ?? ''}`);
+    // Box-drawing only misrenders in a *live* legacy Windows console; in a pipe the bytes are fine.
+    const winLegacyTty = tty && input.platform === 'win32' && !env.WT_SESSION && !env.TERM_PROGRAM && !utf8;
+    const unicode = !plain && !winLegacyTty;
+    const columns = input.columns && input.columns > 0 ? input.columns : 80;
+    return { tty, color, colorDepth, unicode, columns };
+}

package/dist/ui/theme.js

@@ -0,0 +1,49 @@
+// Semantic symbols + color. PURE + zero-dep: color is emitted as
+// raw ANSI escapes (no chalk/library), gated by a Painter built from UiCapabilities. The default PLAIN
+// painter colors nothing and uses UTF-8 symbols → byte-identical to framein's pre-existing renderer
+// output, so existing tests pass and color only appears in a real terminal.
+// §5.2/§5.3 truecolor + §5.5 ANSI-16 fallback. agent/provider are never color-coded (§5.4).
+const TRUECOLOR = {
+    brand: [200, 255, 61],
+    success: [82, 210, 115],
+    warning: [242, 184, 75],
+    danger: [255, 101, 119],
+    info: [84, 199, 236],
+    muted: [160, 160, 165],
+};
+const ANSI16 = { brand: 96, success: 92, warning: 93, danger: 91, info: 94, muted: 90 };
+export function symbolSet(unicode) {
+    return unicode
+        ? { pass: '✓', warn: '!', fail: '×', running: '●', waiting: '○', next: '→', note: '·' }
+        : { pass: '[ok]', warn: '[!]', fail: '[x]', running: '[*]', waiting: '[ ]', next: '->', note: '-' };
+}
+function makePainter(opts) {
+    const sym = symbolSet(opts.unicode);
+    if (!opts.color)
+        return { sym, color: false, tone: (t) => t, bold: (t) => t };
+    const code = (t) => (opts.depth >= 24 ? `38;2;${TRUECOLOR[t].join(';')}` : String(ANSI16[t]));
+    return {
+        sym,
+        color: true,
+        tone: (text, t) => `\x1b[${code(t)}m${text}\x1b[0m`,
+        bold: (text) => `\x1b[1m${text}\x1b[0m`,
+    };
+}
+export function painter(caps) {
+    return makePainter({ color: caps.color, depth: caps.colorDepth, unicode: caps.unicode });
+}
+/** No color, UTF-8 symbols — the renderer default so non-cli callers (and tests) get stable plain text. */
+export const PLAIN = makePainter({ color: false, depth: 0, unicode: true });
+/** Map a framein status word to its semantic tone (§8.4). */
+export function statusTone(status) {
+    const s = status.toUpperCase();
+    if (s === 'READY')
+        return 'success';
+    if (s.includes('NOT READY') || s === 'BLOCKED' || s === 'FAILED')
+        return 'danger';
+    if (s === 'WARNING' || s.includes('WARNING'))
+        return 'warning';
+    if (s === 'RUNNING' || s === 'WAITING' || s === 'PAUSED')
+        return 'info';
+    return 'muted';
+}