framein 0.0.4

package/dist/db.js

@@ -0,0 +1,7 @@
+// Thin typed facade over the experimental built-in node:sqlite.
+// Declaring our own minimal surface decouples us from @types/node version drift.
+// @ts-ignore - node:sqlite is experimental; type defs may be absent.
+import { DatabaseSync } from 'node:sqlite';
+export function openDb(path) {
+    return new DatabaseSync(path);
+}

package/dist/debt.js

@@ -0,0 +1,42 @@
+// Vibe Debt Delta (F-LOOP-9, ADR-0008): show the debt THIS change added — not the codebase's
+// hundreds of pre-existing warnings. Pure: parse a unified git diff into a small delta. Heuristic
+// by design (a hint, not a linter); reading the diff (git) lives in cli.ts.
+import { PLAIN } from './ui/theme.js';
+export function parseDiffDebt(diff) {
+    let addedLines = 0, removedLines = 0, todos = 0;
+    const addedDeps = [];
+    let curFile = '';
+    for (const line of (diff ?? '').split('\n')) {
+        if (line.startsWith('+++ ')) {
+            curFile = line.replace(/^\+\+\+ (b\/)?/, '').trim();
+            continue;
+        }
+        if (line.startsWith('--- ') || line.startsWith('@@') || line.startsWith('diff '))
+            continue;
+        if (line.startsWith('+')) {
+            addedLines++;
+            if (/\b(TODO|FIXME|HACK|XXX)\b/.test(line))
+                todos++;
+            if (/package\.json$/.test(curFile)) {
+                const m = line.match(/^\+\s*"([^"]+)":\s*"[~^]?\d/); // "pkg": "^1.2.3" style additions
+                if (m)
+                    addedDeps.push(m[1]);
+            }
+        }
+        else if (line.startsWith('-')) {
+            removedLines++;
+        }
+    }
+    return { addedLines, removedLines, addedDeps, todos };
+}
+export function renderDebt(d, ui = PLAIN) {
+    const lines = [ui.tone('Debt delta (this change only):', 'muted')];
+    if (d.addedDeps.length)
+        lines.push(ui.tone(`  + ${d.addedDeps.length} runtime dependency${d.addedDeps.length > 1 ? '(ies)' : ''}: ${d.addedDeps.join(', ')}`, 'warning'));
+    if (d.todos)
+        lines.push(ui.tone(`  + ${d.todos} TODO/FIXME`, 'warning'));
+    lines.push(`  ~ ${d.addedLines} added / ${d.removedLines} removed lines`);
+    if (!d.addedDeps.length && !d.todos)
+        lines.push(ui.tone('  (no new deps or TODOs)', 'success'));
+    return lines.join('\n');
+}

package/dist/delegate.js

@@ -0,0 +1,64 @@
+// Headless delegation (ADR-0007 B-2). The PRIMARY way framein pulls another role into a session:
+// drive each CLI's non-interactive print mode over child_process pipes — NO PTY. This sidesteps the
+// Windows ConPTY/node-pty risk and keeps zero runtime deps. Human-in-the-loop attach uses Node's
+// built-in `stdio:'inherit'` (interactiveCommand below) — a programmatic PTY (node-pty) is
+// deliberately not used (ADR-0009). These builders are pure; the spawn lives in cli.ts and is
+// live-verified against real claude/codex/gemini.
+import { DEFAULT_ROLE_PRIORITY } from './roles.js';
+/**
+ * Non-interactive one-shot invocation for each agent (prompt via stdin, response on stdout).
+ * `opts.trustFlags` (from trustPlan, F-TRUST) are FIXED per-agent permission-bypass flags appended
+ * to argv — still no user input there, so it stays shell-safe under shell:true.
+ */
+export function buildInvocation(agent, prompt, opts = {}) {
+    const trust = opts.trustFlags ?? [];
+    switch (agent) {
+        case 'claude': return { command: 'claude', args: ['-p', ...trust], stdin: prompt };
+        case 'codex': return { command: 'codex', args: ['exec', '--skip-git-repo-check', ...trust], stdin: prompt }; // exec refuses untrusted/non-git dirs otherwise
+        // gemini -p takes the prompt as a value and APPENDS stdin; `--prompt=` (empty) + stdin keeps the
+        // prompt off argv (shell-safe), `--skip-trust` is required for headless untrusted dirs. Verified.
+        case 'gemini': return { command: 'gemini', args: ['--prompt=', '--skip-trust', ...trust], stdin: prompt };
+        default: {
+            const _exhaustive = agent;
+            throw new Error(`unknown agent: ${String(_exhaustive)}`);
+        }
+    }
+}
+/** Which agent runs a role: the explicit assignment, else the role's default-priority head. */
+export function resolveAgent(roles, role) {
+    return roles[role] ?? DEFAULT_ROLE_PRIORITY[role][0];
+}
+/** The fixed shell command (flags only, no user input) that runDelegated runs with shell:true. */
+export function invocationCommand(inv) {
+    return [inv.command, ...inv.args].join(' ');
+}
+/**
+ * The bare interactive command for an agent — launched with stdio:'inherit' so the human drives the
+ * agent's own TUI directly, inside the already-synced frame (ADR-0007 B-2 interactive path, zero-dep).
+ * A true programmatic PTY (read/inject/resize the agent's terminal) would need node-pty — a native
+ * runtime dependency that breaks framein's zero-dep invariant (ADR-0003) — and framein observes via
+ * the store/ledger, not by screen-scraping a TTY, so it is deliberately NOT used.
+ */
+// `resume` re-enters the agent's MOST RECENT session in this cwd (handoff continuity, F-CAPSULE/ADR-0009):
+// claude `--continue`, codex `resume --last`, gemini `--resume`. framein decides re-entry from its own
+// ledger (a prior enter/return for this agent) — it never scrapes the printed session id (ADR-0009).
+export function interactiveCommand(agent, resume = false, trustFlags = []) {
+    // F-TRUST placement: codex `resume` is a SUBCOMMAND, so top-level bypass flags must come BEFORE it
+    // (`codex --full-auto resume --last`); appending after the subcommand makes codex reject them. claude
+    // `--continue` and gemini `--resume` are plain flags, so trust flags can follow.
+    const t = trustFlags.length ? ` ${trustFlags.join(' ')}` : '';
+    switch (agent) {
+        case 'claude': return `claude${resume ? ' --continue' : ''}${t}`;
+        case 'codex': return `codex${t}${resume ? ' resume --last' : ''}`;
+        case 'gemini': return `gemini${resume ? ' --resume' : ''}${t}`;
+        default: {
+            const _exhaustive = agent;
+            throw new Error(`unknown agent: ${String(_exhaustive)}`);
+        }
+    }
+}
+/** Human-readable preview for `--show`: the fixed command + a peek at the stdin prompt. */
+export function renderInvocation(inv) {
+    const peek = inv.stdin.length > 60 ? inv.stdin.slice(0, 60) + '…' : inv.stdin;
+    return `${invocationCommand(inv)}  ⟵ stdin: ${JSON.stringify(peek)}`;
+}

package/dist/detect.js

@@ -0,0 +1,118 @@
+// Reuse-first (ADR-0002/0004): DETECT each agent's existing MCP servers and skills and
+// surface them; never proxy or reimplement them. Parsers are pure (fixture-testable);
+// the disk layer is best-effort and swallows missing/malformed files.
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+// --- pure parsers (one per CLI's config format) ---
+/** Claude project `.mcp.json`: { "mcpServers": { name: { command, args } } } */
+export function parseClaudeMcpJson(text) {
+    const servers = (JSON.parse(text)?.mcpServers ?? {});
+    return Object.entries(servers).map(([name, def]) => ({ agent: 'claude', name, command: def?.command ?? '' }));
+}
+/** Gemini `settings.json`: { "mcpServers": { name: { command, args } } } */
+export function parseGeminiMcpJson(text) {
+    const servers = (JSON.parse(text)?.mcpServers ?? {});
+    return Object.entries(servers).map(([name, def]) => ({ agent: 'gemini', name, command: def?.command ?? '' }));
+}
+/**
+ * Codex `~/.codex/config.toml`: top-level `[mcp_servers.<name>]` tables (sub-tables like
+ * `[mcp_servers.<name>.env]` are NOT servers). Minimal line-based reader (zero-dep).
+ */
+export function parseCodexMcpToml(text) {
+    const out = [];
+    let cur = null;
+    for (const raw of text.split('\n')) {
+        // strip a trailing ` # comment` (best effort: not quote-aware, but tolerates the common case)
+        const line = raw.replace(/\s+#.*$/, '').trim();
+        const sec = line.match(/^\[mcp_servers\.([^.\]]+)\]$/);
+        if (sec) {
+            cur = { agent: 'codex', name: sec[1], command: '' };
+            out.push(cur);
+            continue;
+        }
+        if (line.startsWith('[')) {
+            cur = null;
+            continue;
+        } // any other section ends the current server
+        if (cur) {
+            const m = line.match(/^command\s*=\s*['"](.*?)['"]\s*$/);
+            if (m)
+                cur.command = m[1];
+        }
+    }
+    return out;
+}
+/** Server names configured for more than one agent (surfaced, not auto-resolved). */
+export function findConflicts(servers) {
+    const byName = new Map();
+    for (const s of servers) {
+        if (!byName.has(s.name))
+            byName.set(s.name, new Set());
+        byName.get(s.name).add(s.agent);
+    }
+    return [...byName.entries()].filter(([, agents]) => agents.size > 1).map(([name]) => name).sort();
+}
+/**
+ * The config patches that would register framein's OWN MCP server into each CLI. Generated
+ * for the user to apply after approval (§6.3) — framein does not write them automatically.
+ */
+export function frameinMcpRegistration(command = 'framein', args = ['mcp', 'serve']) {
+    const json = JSON.stringify({ mcpServers: { framein: { command, args } } }, null, 2);
+    const codex = `[mcp_servers.framein]\ncommand = ${JSON.stringify(command)}\nargs = [${args.map((a) => JSON.stringify(a)).join(', ')}]`;
+    return { claude: json, codex, gemini: json };
+}
+export const FRAMEIN_SKILLS = [
+    { source: 'framein', name: 'adr-flow', description: 'record a decision as an ADR and re-sync all agents' },
+    { source: 'framein', name: 'delegate', description: 'hand a task to another role; it reads the shared store' },
+    { source: 'framein', name: 'cross-review', description: 'ask the reviewer role to audit the current change' },
+];
+/** Parse the `name`/`description` from a SKILL.md YAML-ish frontmatter block. */
+export function parseSkillFrontmatter(md) {
+    const fm = md.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!fm)
+        return {};
+    const name = fm[1].match(/^name:\s*(.+)$/m)?.[1]?.trim();
+    const description = fm[1].match(/^description:\s*(.+)$/m)?.[1]?.trim();
+    return { name, description };
+}
+// --- best-effort disk layer ---
+function tryParse(path, parse, into) {
+    try {
+        if (existsSync(path))
+            into.push(...parse(readFileSync(path, 'utf8')));
+    }
+    catch { /* ignore malformed/missing */ }
+}
+export function detectMcpFromDisk(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const home = opts.home ?? homedir();
+    const servers = [];
+    tryParse(join(cwd, '.mcp.json'), parseClaudeMcpJson, servers);
+    tryParse(join(home, '.codex', 'config.toml'), parseCodexMcpToml, servers);
+    tryParse(join(home, '.gemini', 'settings.json'), parseGeminiMcpJson, servers);
+    tryParse(join(cwd, '.gemini', 'settings.json'), parseGeminiMcpJson, servers);
+    return servers;
+}
+export function detectSkillsFromDisk(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const home = opts.home ?? homedir();
+    const out = [];
+    for (const base of [join(cwd, '.claude', 'skills'), join(home, '.claude', 'skills')]) {
+        try {
+            if (!existsSync(base))
+                continue;
+            for (const entry of readdirSync(base, { withFileTypes: true })) {
+                if (!entry.isDirectory())
+                    continue;
+                const md = join(base, entry.name, 'SKILL.md');
+                if (!existsSync(md))
+                    continue;
+                const { name, description } = parseSkillFrontmatter(readFileSync(md, 'utf8'));
+                out.push({ source: 'claude', name: name ?? entry.name, description: description ?? '' });
+            }
+        }
+        catch { /* ignore */ }
+    }
+    return out;
+}

package/dist/disagree.js

@@ -0,0 +1,85 @@
+// Disagreement Protocol (F-LOOP-5, ADR-0008): bound model-vs-model debate so it converges instead
+// of looping. A proposal is met with at most `maxRounds` blocking challenges; the reviewer returns
+// CLAIMS + a required change (never edits — the lead keeps control); no agreement after the cap
+// escalates to the human with exactly two options. Pure state machine; the model-authored content
+// of each turn is the deferred live path.
+import { PLAIN } from './ui/theme.js';
+export const MAX_ROUNDS = 2;
+export function newDebate(topic, proposal, maxRounds = MAX_ROUNDS) {
+    return { topic, entries: [{ kind: 'proposal', proposal }], maxRounds };
+}
+export function challengeCount(d) {
+    return d.entries.filter((e) => e.kind === 'challenge').length;
+}
+function leadPosition(d) {
+    for (let i = d.entries.length - 1; i >= 0; i--) {
+        const e = d.entries[i];
+        if (e.kind === 'revision')
+            return e.revision.text || d.topic;
+        if (e.kind === 'proposal')
+            return e.proposal.text;
+    }
+    return d.topic;
+}
+function reviewerRequirement(d) {
+    for (let i = d.entries.length - 1; i >= 0; i--) {
+        const e = d.entries[i];
+        if (e.kind === 'challenge' && e.challenge.verdict === 'challenge')
+            return e.challenge.requiredChange ?? e.challenge.claim;
+    }
+    return undefined;
+}
+export function debateStatus(d) {
+    const last = d.entries[d.entries.length - 1];
+    const rounds = challengeCount(d);
+    const escalate = () => ({
+        state: 'escalate',
+        reason: `no agreement after ${rounds} round${rounds === 1 ? '' : 's'} (max ${d.maxRounds})`,
+        options: [`A: ${leadPosition(d)}`, `B: ${reviewerRequirement(d) ?? 'reviewer change'}`],
+    });
+    if (!last || last.kind === 'proposal')
+        return { state: 'awaiting-challenge' };
+    if (last.kind === 'challenge') {
+        if (last.challenge.verdict === 'accept')
+            return { state: 'resolved', how: 'accepted-by-reviewer' };
+        if (rounds >= d.maxRounds)
+            return escalate();
+        return { state: 'awaiting-revision', required: last.challenge.requiredChange };
+    }
+    // last is a revision
+    if (last.revision.accepted)
+        return { state: 'resolved', how: 'lead-accepted' };
+    if (rounds >= d.maxRounds)
+        return escalate();
+    return { state: 'awaiting-challenge' };
+}
+export function renderDebate(d, ui = PLAIN) {
+    const lines = [`Debate: ${d.topic}`, ''];
+    for (const e of d.entries) {
+        if (e.kind === 'proposal')
+            lines.push(`proposal${e.proposal.by ? ` (${e.proposal.by})` : ''}: ${e.proposal.text}`);
+        else if (e.kind === 'challenge') {
+            const c = e.challenge;
+            lines.push(c.verdict === 'accept'
+                ? `challenge${c.by ? ` (${c.by})` : ''}: accept`
+                : `challenge${c.by ? ` (${c.by})` : ''}: ${c.claim ?? ''}${c.requiredChange ? ` → require: ${c.requiredChange}` : ''}`);
+        }
+        else {
+            lines.push(`revision: ${e.revision.accepted ? 'accepted' : 'rejected'}${e.revision.text ? ` — ${e.revision.text}` : ''}`);
+        }
+    }
+    lines.push('');
+    const st = debateStatus(d);
+    if (st.state === 'resolved')
+        lines.push(ui.tone(`Resolved (${st.how}).`, 'success'));
+    else if (st.state === 'escalate') {
+        lines.push(ui.tone(`Escalate to human — ${st.reason}:`, 'warning'));
+        for (const o of st.options)
+            lines.push(`  ${o}`);
+    }
+    else if (st.state === 'awaiting-revision')
+        lines.push(ui.tone(`Awaiting lead revision${st.required ? ` (required: ${st.required})` : ''}.`, 'info'));
+    else
+        lines.push(ui.tone('Awaiting reviewer challenge.', 'info'));
+    return lines.join('\n');
+}

package/dist/evidence.js

@@ -0,0 +1,72 @@
+// Validation Gate (F-LOOP-2, ADR-0008): "done" is a verified check bundle, not a natural-language
+// claim. Pure logic — parse a test runner's output, gate the bundle against the Task Contract, and
+// render the ship summary. Actually RUNNING build/test (local, deterministic) and the reviewer's
+// model call live in cli.ts; only the latter is the deferred live path.
+import { contractIssues } from './task.js';
+import { PLAIN, statusTone } from './ui/theme.js';
+/** Parse pass/fail counts from common runners (node:test "pass N", jest/vitest "N passed"). */
+export function parseTestSummary(output) {
+    const t = output ?? '';
+    const num = (re) => { const m = t.match(re); return m ? Number(m[1]) : null; };
+    const passed = num(/\bpass(?:ed|ing)?\s+(\d+)\b/i) ?? num(/\b(\d+)\s+pass(?:ed|ing)?\b/i);
+    const failed = num(/\bfail(?:ed|ing|ures)?\s+(\d+)\b/i) ?? num(/\b(\d+)\s+fail(?:ed|ing|ures)?\b/i);
+    if (passed === null && failed === null)
+        return null;
+    return { passed: passed ?? 0, failed: failed ?? 0 };
+}
+/**
+ * Gate the evidence against the contract. Hard checks (build, tests) decide `ready`; the contract's
+ * acceptance criteria and unresolved items surface as warnings (they need a reviewer/human, which
+ * the gate never auto-claims as verified).
+ */
+export function gate(contract, bundle) {
+    const checks = [];
+    const warnings = [];
+    if (bundle.build)
+        checks.push({ label: 'Build', ok: bundle.build.exitCode === 0, detail: bundle.build.command });
+    if (bundle.tests) {
+        const s = bundle.tests.summary;
+        const ok = bundle.tests.exitCode === 0 && (!s || s.failed === 0);
+        checks.push({ label: 'Tests', ok, detail: s ? `${s.passed} passed, ${s.failed} failed` : `exit ${bundle.tests.exitCode}` });
+    }
+    if (checks.length === 0)
+        warnings.push('no build/test commands found — nothing was actually verified');
+    if (contract) {
+        for (const issue of contractIssues(contract))
+            warnings.push(`contract: ${issue}`);
+        if (contract.acceptance.length)
+            warnings.push(`${contract.acceptance.length} acceptance criteria need verification (reviewer/human)`);
+    }
+    else {
+        warnings.push('no task contract — run `frame start <goal>` to define "done"');
+    }
+    for (const u of bundle.unresolved ?? [])
+        warnings.push(`unresolved: ${u}`);
+    return { ready: checks.length > 0 && checks.every((c) => c.ok), checks, warnings };
+}
+function header(r) {
+    if (!r.ready)
+        return 'NOT READY';
+    return r.warnings.length ? `READY WITH ${r.warnings.length} WARNING${r.warnings.length > 1 ? 'S' : ''}` : 'READY';
+}
+/** Shared gate body: header + checks + warnings (used by `frame verify`). */
+export function renderGate(r, ui = PLAIN) {
+    const h = header(r);
+    const lines = [ui.tone(h, statusTone(h)), ''];
+    for (const c of r.checks) {
+        const mark = c.ok ? ui.tone(ui.sym.pass, 'success') : ui.tone(ui.sym.fail, 'danger');
+        lines.push(`${mark} ${c.label}${c.detail ? ': ' + c.detail : ''}`);
+    }
+    for (const w of r.warnings)
+        lines.push(`${ui.tone(ui.sym.warn, 'warning')} ${w}`);
+    return lines.join('\n');
+}
+/** Gate body + commit/deploy guidance (used by `frame ship`). */
+export function renderShip(r, ui = PLAIN) {
+    return [
+        renderGate(r, ui),
+        '',
+        `Safe to commit: ${r.ready ? 'yes' : 'no'}`,
+        `Safe to deploy: ${r.ready ? 'requires human confirmation' : 'no'}`,
+    ].join('\n');
+}

package/dist/fileWriter.js

@@ -0,0 +1,35 @@
+import { writeFileSync, mkdirSync, existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { renderManagedBlock } from './projector.js';
+import { upsertManagedBlock } from './managedBlock.js';
+const NATIVE_FILES = [
+    ['CLAUDE.md', 'CLAUDE.md'],
+    ['AGENTS.md', 'AGENTS.md'],
+    ['GEMINI.md', 'GEMINI.md'],
+];
+/** Compute what each native file WOULD become (managed-block upsert), without writing. */
+export function planNativeFiles(dir, state) {
+    const managed = renderManagedBlock(state);
+    return NATIVE_FILES.map(([name, title]) => {
+        const path = join(dir, name);
+        const existing = existsSync(path) ? readFileSync(path, 'utf8') : null;
+        const content = upsertManagedBlock(existing, title, managed);
+        return { path, content, existed: existing != null, changed: existing !== content };
+    });
+}
+/**
+ * Upsert the managed block into the three native files, preserving any user content
+ * outside the framein markers. Only files whose content actually changes are written
+ * (no mtime churn / spurious file-watcher events). Returns the written paths.
+ */
+export function writeNativeFiles(dir, state) {
+    mkdirSync(dir, { recursive: true });
+    const written = [];
+    for (const p of planNativeFiles(dir, state)) {
+        if (p.changed) {
+            writeFileSync(p.path, p.content, 'utf8');
+            written.push(p.path);
+        }
+    }
+    return written;
+}

package/dist/ingest.js

@@ -0,0 +1,38 @@
+// Structured ingest (F-LOOP-5, live): pull a JSON object out of a model's free-form reply so its
+// answer becomes structured framein state (e.g. a reviewer verdict -> a Challenge). Models wrap
+// JSON in prose / ```json fences, so scan for the first balanced, string-aware {...} that parses.
+// Pure; the live model call that produces the text lives in cli.ts.
+export function extractJson(text) {
+    const s = text ?? '';
+    for (let i = s.indexOf('{'); i !== -1; i = s.indexOf('{', i + 1)) {
+        let depth = 0, inStr = false, esc = false;
+        for (let j = i; j < s.length; j++) {
+            const c = s[j];
+            if (inStr) {
+                if (esc)
+                    esc = false;
+                else if (c === '\\')
+                    esc = true;
+                else if (c === '"')
+                    inStr = false;
+                continue;
+            }
+            if (c === '"')
+                inStr = true;
+            else if (c === '{')
+                depth++;
+            else if (c === '}') {
+                if (--depth === 0) {
+                    try {
+                        const o = JSON.parse(s.slice(i, j + 1));
+                        if (o && typeof o === 'object' && !Array.isArray(o))
+                            return o;
+                    }
+                    catch { /* not valid JSON — fall through and try the next `{` */ }
+                    break;
+                }
+            }
+        }
+    }
+    return null;
+}

package/dist/managedBlock.js

@@ -0,0 +1,101 @@
+// Managed-block upsert: framein owns only the region between its markers.
+// Everything a user writes outside the markers is preserved across re-projection.
+//
+// Robustness (see codex review): markers are matched as EXACT FULL LINES, malformed
+// states (dangling / reversed / duplicate markers) are cleaned to a single canonical
+// block without losing user text, and marker strings that appear inside the core data
+// are defanged so they can never be mistaken for real markers.
+export const MANAGED_BEGIN = '<!-- framein:begin — managed by `frame`; edits inside are overwritten. Source: .frame/store.db -->';
+export const MANAGED_END = '<!-- framein:end -->';
+function isMarker(line, marker) {
+    return line.trim() === marker;
+}
+/** Neutralize any core line that IS exactly a marker, so it cannot be parsed as one. */
+function defangMarkerLines(core) {
+    return core.split('\n').map((ln) => {
+        const t = ln.trim();
+        return t === MANAGED_BEGIN || t === MANAGED_END ? ln.replace('<!--', '&lt;!--') : ln;
+    }).join('\n');
+}
+/** Wrap the core block in the managed markers. Identical across all three files. */
+export function wrapManaged(coreBlock) {
+    return `${MANAGED_BEGIN}\n${defangMarkerLines(coreBlock)}\n${MANAGED_END}`;
+}
+/** All well-formed [begin,end] line-index regions, paired greedily. */
+function findRegions(lines) {
+    const regions = [];
+    let i = 0;
+    while (i < lines.length) {
+        if (isMarker(lines[i], MANAGED_BEGIN)) {
+            let j = i + 1;
+            while (j < lines.length && !isMarker(lines[j], MANAGED_END))
+                j++;
+            if (j < lines.length) {
+                regions.push([i, j]);
+                i = j + 1;
+                continue;
+            }
+        }
+        i++;
+    }
+    return regions;
+}
+/** Count of lines that are exactly a begin or end marker. */
+function markerLineCount(lines) {
+    return lines.filter((l) => isMarker(l, MANAGED_BEGIN) || isMarker(l, MANAGED_END)).length;
+}
+/** Remove every well-formed managed region and any stray marker lines; preserve the rest. */
+export function stripManagedBlocks(content) {
+    const lines = content.split('\n');
+    const out = [];
+    for (let i = 0; i < lines.length; i++) {
+        if (isMarker(lines[i], MANAGED_BEGIN)) {
+            let j = i + 1;
+            while (j < lines.length && !isMarker(lines[j], MANAGED_END))
+                j++;
+            if (j < lines.length) {
+                i = j;
+                continue;
+            } // drop a full region
+            continue; // dangling begin: drop just this line
+        }
+        if (isMarker(lines[i], MANAGED_END))
+            continue; // stray end: drop just this line
+        out.push(lines[i]);
+    }
+    return out.join('\n');
+}
+/** The single well-formed managed region (markers inclusive), or null. */
+export function extractManagedBlock(content) {
+    const lines = content.split('\n');
+    const regions = findRegions(lines);
+    if (regions.length === 0)
+        return null;
+    const [b, e] = regions[0];
+    return lines.slice(b, e + 1).join('\n');
+}
+/**
+ * Insert or replace the managed block in `existing`, preserving everything outside it.
+ *
+ * - null/empty existing            → fresh file: `# <title>` heading + the managed block.
+ * - exactly one clean region       → replace it IN PLACE (outside bytes preserved exactly).
+ * - malformed (dangling/reversed/duplicate/stray markers) → clean all of them and append a
+ *   single canonical block; subsequent runs see one clean region and are fully idempotent.
+ *
+ * `managed` must be the output of wrapManaged() (markers included).
+ */
+export function upsertManagedBlock(existing, title, managed) {
+    if (existing == null || existing.trim() === '') {
+        return `# ${title}\n\n${managed}\n`;
+    }
+    const lines = existing.split('\n');
+    const regions = findRegions(lines);
+    const healthySingle = regions.length === 1 && markerLineCount(lines) === 2;
+    if (healthySingle) {
+        const [b, e] = regions[0];
+        return [...lines.slice(0, b), ...managed.split('\n'), ...lines.slice(e + 1)].join('\n');
+    }
+    // malformed or empty-of-user-text: rebuild cleanly without losing content
+    const body = stripManagedBlocks(existing).replace(/\s*$/, '');
+    return `${body === '' ? `# ${title}` : body}\n\n${managed}\n`;
+}

package/dist/mcpRegister.js

@@ -0,0 +1,85 @@
+// Apply step of the MCP registration flow (§6.3: detect -> propose -> APPLY approved -> verify).
+// Pure, idempotent config-merge writers that ADD framein's own MCP server into each CLI's config
+// without clobbering anything else (same safety contract as managedBlock, ADR-0007 B-1). The
+// actual file write + live `claude mcp list` spawn live in cli.ts; only the parser below is pure.
+// Zero-dep: JSON via JSON.parse/stringify, TOML via a line-based text merge (no TOML serializer).
+/** framein registers itself as a subprocess MCP server each CLI launches (ADR-0007). */
+export const FRAMEIN_ENTRY = { command: 'framein', args: ['mcp', 'serve'] };
+/**
+ * Pick the spawn command the agent CLIs should use to launch framein's MCP server: the canonical
+ * `framein` bin when it's on PATH (installed product), else `node <abs cli.js>` (dev / not globally
+ * installed). The agent spawns this verbatim, so it MUST resolve to a real executable.
+ */
+export function resolveFrameinEntry(frameOnPath, cliPath) {
+    return frameOnPath ? { command: 'framein', args: ['mcp', 'serve'] } : { command: 'node', args: [cliPath, 'mcp', 'serve'] };
+}
+/**
+ * Merge `mcpServers.<name>` into a JSON config (Claude `.mcp.json`, Gemini `settings.json`),
+ * preserving every other key and server. Idempotent. Reformats with 2-space indent.
+ */
+export function applyJsonMcp(existing, name = 'framein', entry = FRAMEIN_ENTRY) {
+    let root = {};
+    if (existing && existing.trim()) {
+        const parsed = JSON.parse(existing);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
+            root = parsed;
+    }
+    const prev = root.mcpServers;
+    const servers = prev && typeof prev === 'object' && !Array.isArray(prev) ? prev : {};
+    servers[name] = { command: entry.command, args: entry.args };
+    root.mcpServers = servers;
+    return JSON.stringify(root, null, 2) + '\n';
+}
+/**
+ * Merge a `[mcp_servers.<name>]` table into a Codex `config.toml` as text: replace the existing
+ * block (header line through the next table header / EOF) if present, else append. Idempotent.
+ * Preserves all other content; only the framein table is rewritten.
+ */
+export function applyCodexMcp(existing, name = 'framein', entry = FRAMEIN_ENTRY) {
+    const header = `[mcp_servers.${name}]`;
+    const block = [
+        header,
+        `command = ${JSON.stringify(entry.command)}`,
+        `args = [${entry.args.map((a) => JSON.stringify(a)).join(', ')}]`,
+    ];
+    const text = existing ?? '';
+    const lines = text.split('\n');
+    const start = lines.findIndex((l) => l.trim() === header);
+    if (start === -1) {
+        const base = text.trim();
+        return (base ? base + '\n\n' : '') + block.join('\n') + '\n';
+    }
+    // Block ends at the next table header (any `[...]`) or EOF.
+    let end = lines.length;
+    for (let i = start + 1; i < lines.length; i++) {
+        if (/^\s*\[/.test(lines[i])) {
+            end = i;
+            break;
+        }
+    }
+    const before = lines.slice(0, start);
+    const after = lines.slice(end);
+    const sep = after.length && after[0].trim() !== '' ? [''] : []; // keep a blank line before a following table
+    return [...before, ...block, ...sep, ...after].join('\n').replace(/\n*$/, '\n');
+}
+/**
+ * Read the connection state of a server from `claude mcp list` output. `connected`/`failed` when
+ * a health marker (✓/✗) is shown, `registered` when listed without one, `absent` when not found.
+ * (The verify step; the spawn that produces `output` is the live B-layer piece.)
+ */
+export function parseClaudeMcpList(output, name = 'framein') {
+    for (const raw of output.split('\n')) {
+        const line = raw.trim();
+        const colon = line.indexOf(':');
+        if (colon === -1)
+            continue;
+        if (line.slice(0, colon).trim() !== name)
+            continue;
+        if (/✗|✘|fail/i.test(line))
+            return 'failed';
+        if (/✓|✔|connected/i.test(line))
+            return 'connected';
+        return 'registered';
+    }
+    return 'absent';
+}