aiki-cli 0.2.0

package/dist/orchestration/stages/s8-verify.js

@@ -0,0 +1,56 @@
+// S8 — verifier loop (§9, §13). The verifier (codex) independently checks each dispute before the
+// judge sees it. Idea-refinement runs a SINGLE pass (the "max 2 iterations" cap is the code-review
+// reviewer cross-exam, §313, landing at T10). Disputed items are ANONYMIZED — the verifier sees the
+// claim + the argument(s) against it with NO provider labels (§313/§624 anti-self-preference), since
+// codex authored some S4 claims. Zero disputes → skip the call entirely. A verifier failure is
+// graceful: every item is marked UNCERTAIN ("unverified") and passed to the judge, never an abort (§259).
+import { VerificationSet } from '../../schemas/index.js';
+import { isFatal } from '../context.js';
+import { jsonCall } from '../jsonStage.js';
+const S8_PROMPT = `ROLE: Verifier. Below are disputed claims, each with the argument(s) against it, from
+anonymous sources. For EACH item, independently judge whether the argument defeats the claim.
+Output ONLY JSON:
+{"verifications": [{"target_id": "<id>", "verdict": "CONFIRM|REFUTE|UNCERTAIN",
+  "evidence": "<your own independent reasoning>", "note": "<≤2 sentences>"}]}
+CONFIRM = the argument holds (the claim is genuinely doubtful). REFUTE = the argument fails (the claim
+stands). Rules: you MUST issue at least one REFUTE, or set "all_confirmed_justification" explaining why
+every claim survives. JSON only, no prose outside it.
+ITEMS: {{DISPUTED_ITEMS_JSON}}`;
+export async function s8Verify(ctx, map) {
+    const disputes = map.contradictions;
+    if (disputes.length === 0) {
+        const empty = { verifications: [] };
+        await ctx.writer.writeJson('verifications', empty);
+        return empty;
+    }
+    // Anonymized disputed items: claim text + argument text only, no provider attribution.
+    const claimById = new Map();
+    for (const c of [...map.consensus, ...map.unique])
+        claimById.set(c.id, c.statement);
+    const items = disputes.map((d) => ({
+        id: d.id,
+        claim: d.claim_ids.map((cid) => claimById.get(cid) ?? cid).join(' / '),
+        arguments_against: d.attacks.map((a) => a.argument),
+    }));
+    const prompt = S8_PROMPT.replace('{{DISPUTED_ITEMS_JSON}}', JSON.stringify(items, null, 2));
+    try {
+        const vset = await jsonCall(ctx, ctx.handle(ctx.roles.verifier), 'S8', prompt, VerificationSet);
+        await ctx.writer.writeJson('verifications', vset);
+        return vset;
+    }
+    catch (e) {
+        if (isFatal(e))
+            throw e; // budget/deadline/abort → abort the run
+        // Verifier down / bad output: mark every dispute unverified, pass to the judge as low-confidence.
+        const vset = {
+            verifications: disputes.map((d) => ({
+                target_id: d.id,
+                verdict: 'UNCERTAIN',
+                evidence: '(verifier unavailable — unverified)',
+                note: '',
+            })),
+        };
+        await ctx.writer.writeJson('verifications', vset);
+        return vset;
+    }
+}

package/dist/orchestration/stages/s9-judge.js

@@ -0,0 +1,152 @@
+// S9 — judge synthesis (§9, §13). The judge (claude) adjudicates DISPUTED items only; consensus is
+// already settled (S7 grouping) and passes through untouched. Two guards beyond the schema:
+//   1. Anti-blending (§260, the §602 acceptance test): the judge may reference ONLY disputed ids in
+//      `adjudications` — never a consensus id. `adjudicationScopeViolations` (pure) detects this; the
+//      stage re-asks once, then filters any still-invalid adjudications out and flags the run.
+//   2. Mandatory dissent (§260): empty dissent → re-ask once → else flag `synthesis_suspect` and
+//      inject a placeholder so the report still renders (continue, not abort).
+// Confidence is NOT taken from the judge here — the held/failed/unverified audit + HIGH/MED/LOW labels
+// are derived deterministically at S10 (§624: confidence from cross-model confirmation, not self-report).
+import { JudgeReportModel } from '../../schemas/index.js';
+import { isFatal } from '../context.js';
+import { jsonCall } from '../jsonStage.js';
+const S9_PROMPT = `ROLE: Judge. You adjudicate ONLY the disputed items below. Consensus items are already
+settled; do not restate, edit, re-litigate, or reference them in your adjudications.
+Apply this rubric strictly: {{RUBRIC_JSON}}
+
+You are the CHAIRMAN of the panel. Write for a decision-maker who did not see the debate — be clear,
+specific, and professional. No hedging mush, no restating the question back.
+
+Output ONLY JSON matching the judge schema:
+- adjudications: for EACH disputed id → {id, ruling: UPHOLD|REJECT|UNRESOLVED, reasoning ≤3 sentences, evidence_cited}.
+  UPHOLD = the argument defeats the claim; REJECT = the claim survives; UNRESOLVED = genuinely undecided.
+- verdict: 2-5 sentences — your clear recommendation (proceed / proceed-if / don't) and the single most
+  important reason. Grounded ONLY in adjudicated + consensus claims.
+- recommendation: one of PROCEED, PROCEED_WITH_CONDITIONS, PIVOT, STOP.
+  PIVOT = the core idea is unsound but an adjacent version may work. STOP = load-bearing assumptions failed
+  with no credible repair. PROCEED_WITH_CONDITIONS means the idea is viable only if specific checks pass.
+- conditions: required ONLY for PROCEED_WITH_CONDITIONS; each condition must be checkable, not a vibe.
+- key_points: 4-8 bullets — the reasoning a decision-maker needs, in plain language. Cover: what decided
+  it, the decisive trade-offs, where the analysts DISAGREED and whose side you took and why, and the one
+  thing that would most change the verdict. Each bullet a full standalone point, not a fragment.
+- dissent: ≥1 item — the strongest argument AGAINST your own verdict. Empty dissent is invalid.
+- confidence_notes: which conclusions are HIGH/MEDIUM/LOW and why.
+DISPUTED ITEMS + VERIFICATION: {{DISPUTES_JSON}}
+CONSENSUS (context only, read-only): {{CONSENSUS_JSON}}`;
+/** Pure anti-blending validator: adjudication ids that are NOT disputed items (the judge trying to
+ *  touch consensus). Empty = clean. This is the heart of the §602 "rejects consensus edits" test. */
+export function adjudicationScopeViolations(report, disputeIds) {
+    const allowed = new Set(disputeIds);
+    return report.adjudications.map((a) => a.id).filter((id) => !allowed.has(id));
+}
+/** Idea S9 semantic guard: the model-facing schema permits missing recommendation fields so S9 can
+ *  re-ask once instead of losing a usable judge report to one absent enum. */
+export function recommendationIssues(report) {
+    const issues = [];
+    const hasConditions = (report.conditions?.length ?? 0) > 0;
+    if (!report.recommendation)
+        issues.push('recommendation is required');
+    if (report.recommendation === 'PROCEED_WITH_CONDITIONS' && !hasConditions) {
+        issues.push('conditions are required for PROCEED_WITH_CONDITIONS');
+    }
+    if (hasConditions && report.recommendation !== 'PROCEED_WITH_CONDITIONS') {
+        issues.push('conditions are only valid with PROCEED_WITH_CONDITIONS');
+    }
+    return issues;
+}
+/** §272 2-provider demotion (pure). When the judge is also an S4 author (only happens with 2
+ *  providers), any adjudication on a dispute whose contested claim was authored SOLELY by the judge's
+ *  provider is forced to `UNRESOLVED` — the judge may not confirm its own claim; it stays for the
+ *  human. A no-op with 3 providers, where the judge (claude) authored no S4 claim. */
+export function demoteSelfAuthored(adjudications, map, judgeProvider) {
+    const claimProviders = new Map();
+    for (const c of [...map.consensus, ...map.unique])
+        claimProviders.set(c.id, c.providers);
+    const disputeClaims = new Map(map.contradictions.map((d) => [d.id, d.claim_ids]));
+    return adjudications.map((a) => {
+        const cids = disputeClaims.get(a.id) ?? [];
+        const soleJudge = cids.length > 0 && cids.every((cid) => {
+            const ps = claimProviders.get(cid) ?? [];
+            return ps.length === 1 && ps[0] === judgeProvider;
+        });
+        return soleJudge && a.ruling !== 'UNRESOLVED' ? { ...a, ruling: 'UNRESOLVED' } : a;
+    });
+}
+const sevRank = (s) => (s === 'HIGH' ? 0 : s === 'MED' ? 1 : 2);
+function fallbackConditions(map, adjudications) {
+    const claimById = new Map([...map.consensus, ...map.unique].map((c) => [c.id, c.statement]));
+    const rulingById = new Map(adjudications.map((a) => [a.id, a.ruling]));
+    const riskConditions = map.contradictions
+        .filter((d) => rulingById.get(d.id) === 'UPHOLD')
+        .sort((a, b) => Math.min(...a.attacks.map((x) => sevRank(x.severity))) - Math.min(...b.attacks.map((x) => sevRank(x.severity))))
+        .map((d) => {
+        const claim = d.claim_ids.map((id) => claimById.get(id) ?? id).join(' / ');
+        return `Proceed only if you can validate that ${claim}.`;
+    });
+    const blindSpotConditions = map.blind_spots.map((b) => `Proceed only after examining the ${b} gap.`);
+    return [...riskConditions, ...blindSpotConditions, 'Proceed only after one cheap test confirms the core user need.'].slice(0, 6);
+}
+export async function s9Judge(ctx, contract, map, verifications, rubric) {
+    const claimById = new Map();
+    for (const c of [...map.consensus, ...map.unique])
+        claimById.set(c.id, c.statement);
+    const verdictById = new Map(verifications.verifications.map((v) => [v.target_id, v.verdict]));
+    const disputes = map.contradictions.map((d) => ({
+        id: d.id,
+        claim: d.claim_ids.map((cid) => claimById.get(cid) ?? cid).join(' / '),
+        arguments_against: d.attacks.map((a) => a.argument),
+        verifier_verdict: verdictById.get(d.id) ?? 'UNVERIFIED',
+    }));
+    const consensus = map.consensus.map((c) => ({ id: c.id, statement: c.statement }));
+    const disputeIds = map.contradictions.map((d) => d.id);
+    const basePrompt = S9_PROMPT.replace('{{RUBRIC_JSON}}', JSON.stringify(rubric.map((r) => r.label)))
+        .replace('{{DISPUTES_JSON}}', JSON.stringify(disputes, null, 2))
+        .replace('{{CONSENSUS_JSON}}', JSON.stringify(consensus, null, 2))
+        // reference the contract task so the verdict stays anchored to what the user asked
+        .concat(`\nTASK: ${contract.task}`);
+    const judge = ctx.handle(ctx.roles.judge);
+    let report = await jsonCall(ctx, judge, 'S9', basePrompt, JudgeReportModel);
+    // Semantic guards beyond the schema → one targeted re-ask.
+    let violations = adjudicationScopeViolations(report, disputeIds);
+    let recIssues = recommendationIssues(report);
+    if (violations.length || report.dissent.length === 0 || recIssues.length) {
+        const fix = `${basePrompt}\n\n---\nYour previous output had problems:\n` +
+            (violations.length ? `- adjudications must reference ONLY these disputed ids [${disputeIds.join(', ')}]; not: ${violations.join(', ')}\n` : '') +
+            (report.dissent.length === 0 ? `- dissent must contain at least one item.\n` : '') +
+            (recIssues.length ? `- recommendation/conditions problem: ${recIssues.join('; ')}.\n` : '') +
+            `Output ONLY the corrected JSON.`;
+        try {
+            report = await jsonCall(ctx, judge, 'S9-repair', fix, JudgeReportModel);
+            violations = adjudicationScopeViolations(report, disputeIds);
+            recIssues = recommendationIssues(report);
+        }
+        catch (e) {
+            if (isFatal(e))
+                throw e; // keep the first report on a non-fatal repair failure
+        }
+    }
+    // Enforce after the re-ask: drop any still-out-of-scope adjudications; guarantee non-empty dissent.
+    const inScope = report.adjudications.filter((a) => new Set(disputeIds).has(a.id));
+    if (inScope.length !== report.adjudications.length)
+        ctx.addFlag('synthesis_suspect');
+    // §272: if the judge authored a contested claim (2-provider only), it can't confirm it → UNRESOLVED.
+    const adjudications = demoteSelfAuthored(inScope, map, ctx.roles.judge);
+    let dissent = report.dissent;
+    if (dissent.length === 0) {
+        ctx.addFlag('synthesis_suspect');
+        dissent = ['(none produced — flagged synthesis_suspect)'];
+    }
+    let recommendation = report.recommendation;
+    let conditions = report.conditions;
+    if (recIssues.length) {
+        ctx.addFlag('synthesis_suspect');
+        recommendation = 'PROCEED_WITH_CONDITIONS';
+        conditions = fallbackConditions(map, adjudications);
+    }
+    else if (recommendation !== 'PROCEED_WITH_CONDITIONS') {
+        conditions = undefined;
+    }
+    const final = { ...report, adjudications, dissent, recommendation, conditions };
+    await ctx.writer.writeJson('judge-report', final);
+    return final;
+}

package/dist/orchestration/stages/s9b-plan.js

@@ -0,0 +1,192 @@
+// S9b — idea validation plan. This is the one report-v3 model call after the judge: it turns the
+// adjudicated risks, blind spots, and open questions into anchored validation actions. Rendering stays
+// deterministic; if the planner fails or produces unanchored actions, we write a flagged fallback plan.
+import { ActionPlan } from '../../schemas/index.js';
+import { BudgetExceeded, isFatal } from '../context.js';
+import { jsonCall } from '../jsonStage.js';
+import { loadSkill } from '../skills.js';
+import { mergeOpenQuestions } from './s10-render.js';
+const S9B_PROMPT = `ROLE: Validation planner. You write the next actions for a decision-maker after an
+idea council has already debated and judged the idea. Do not write a build roadmap. Write only validation
+actions that test unsettled risks, blind spots, or open questions. Cheapest decisive test first.{{SKILL}}
+
+Output ONLY JSON matching the ActionPlan schema:
+- actions: 1-7 ordered actions, each imperative and concrete.
+- validates MUST anchor to one of:
+  - a dispute id from upheld_risks, e.g. "D3"
+  - a blind spot label as "blind:<label>"
+  - an open-question prefix as "Q:<question prefix>"
+- why ties the action to the risk, blind spot, or question.
+- kill_signal is the result that should stop or reshape the idea.
+- sequencing_note explains why this order is cheapest and decisive.
+
+CONTEXT: {{CONTEXT_JSON}}`;
+function clip(s, n) {
+    const t = s.trim();
+    return t.length > n ? `${t.slice(0, n - 1).trimEnd()}...` : t;
+}
+function sevRank(s) {
+    return s === 'HIGH' ? 0 : s === 'MED' ? 1 : 2;
+}
+function norm(s) {
+    return s.trim().toLowerCase();
+}
+function questionAnchor(q) {
+    return `Q:${clip(q, 90)}`;
+}
+function blindAnchor(b) {
+    return `blind:${b}`;
+}
+function upheldRisks(map, judgeReport) {
+    const claimById = new Map([...map.consensus, ...map.unique].map((c) => [c.id, c.statement]));
+    const rulingById = new Map(judgeReport.adjudications.map((a) => [a.id, a]));
+    return map.contradictions
+        .map((d) => {
+        const adj = rulingById.get(d.id);
+        if (adj?.ruling !== 'UPHOLD')
+            return null;
+        return {
+            id: d.id,
+            assumption: d.claim_ids.map((id) => claimById.get(id) ?? id).join(' / '),
+            severity: [...d.attacks].sort((a, b) => sevRank(a.severity) - sevRank(b.severity))[0]?.severity ?? 'MED',
+            reasoning: adj.reasoning,
+        };
+    })
+        .filter((r) => r !== null)
+        .sort((a, b) => sevRank(a.severity) - sevRank(b.severity));
+}
+export function buildActionPlannerPrompt(input, skill) {
+    return S9B_PROMPT
+        .replace('{{SKILL}}', skill ? `\n\n${skill}` : '')
+        .replace('{{CONTEXT_JSON}}', JSON.stringify(input, null, 2));
+}
+export function validAnchor(anchor, anchors) {
+    const a = anchor.trim();
+    if (anchors.disputeIds.includes(a))
+        return true;
+    if (a.toLowerCase().startsWith('blind:')) {
+        const label = norm(a.slice('blind:'.length));
+        return anchors.blindSpots.some((b) => {
+            const n = norm(b);
+            return n.startsWith(label) || label.startsWith(n);
+        });
+    }
+    if (a.toLowerCase().startsWith('q:')) {
+        const prefix = norm(a.slice(2));
+        return anchors.openQuestions.some((q) => {
+            const n = norm(q);
+            return n.startsWith(prefix) || prefix.startsWith(n);
+        });
+    }
+    return false;
+}
+export function anchoredActionPlan(plan, anchors) {
+    const actions = plan.actions
+        .filter((a) => validAnchor(a.validates, anchors))
+        .sort((a, b) => a.order - b.order)
+        .map((a, i) => ({ ...a, order: i + 1 }));
+    if (actions.length === 0)
+        return null;
+    return { actions, sequencing_note: plan.sequencing_note };
+}
+export function fallbackActionPlan(contract, map, judgeReport, openQuestions) {
+    const risks = upheldRisks(map, judgeReport);
+    const actions = [];
+    for (const r of risks) {
+        actions.push({
+            order: actions.length + 1,
+            action: `Test whether "${clip(r.assumption, 120)}" is true with the smallest realistic sample.`,
+            why: `The chair upheld this as a load-bearing ${r.severity} risk.`,
+            validates: r.id,
+            effort: 'S',
+            kill_signal: 'The assumption fails in the sample or only works outside the intended use case.',
+        });
+    }
+    for (const b of map.blind_spots) {
+        actions.push({
+            order: actions.length + 1,
+            action: `Answer the ${b} gap with one concrete evidence source.`,
+            why: 'No analyst examined this dimension enough to rely on it.',
+            validates: blindAnchor(b),
+            effort: 'S',
+            kill_signal: 'The answer exposes a hard blocker or makes the target user/use case incoherent.',
+        });
+    }
+    for (const q of openQuestions) {
+        actions.push({
+            order: actions.length + 1,
+            action: `Resolve this question: ${clip(q, 140)}`,
+            why: 'The analysts identified it as an answer that could change the verdict.',
+            validates: questionAnchor(q),
+            effort: 'S',
+            kill_signal: 'The answer contradicts the value proposition or removes the target user.',
+        });
+    }
+    if (actions.length === 0) {
+        const q = `What evidence would change the verdict for ${clip(contract.task, 80)}?`;
+        actions.push({
+            order: 1,
+            action: 'Run one cheap test of the core user need before investing more.',
+            why: 'The council produced no unsettled anchored item, so validate the core demand directly.',
+            validates: questionAnchor(q),
+            effort: 'S',
+            kill_signal: 'Target users do not recognize the problem or would not switch from existing alternatives.',
+        });
+    }
+    return ActionPlan.parse({
+        actions: actions.slice(0, 7).map((a, i) => ({ ...a, order: i + 1 })),
+        sequencing_note: 'Start with upheld risks, then blind spots, then open questions; stop when a kill signal fires.',
+    });
+}
+export async function s9bPlan(ctx, contract, seats, map, judgeReport) {
+    const openQuestions = mergeOpenQuestions(seats);
+    const risks = upheldRisks(map, judgeReport);
+    const anchors = {
+        disputeIds: risks.map((r) => r.id),
+        blindSpots: map.blind_spots,
+        openQuestions,
+    };
+    const fallback = async (flag) => {
+        ctx.addFlag(flag);
+        const plan = fallbackActionPlan(contract, map, judgeReport, openQuestions);
+        await ctx.writer.writeJson('action-plan', plan);
+        return plan;
+    };
+    if (ctx.budget.limit - ctx.budget.used < 2)
+        return fallback('plan_skipped');
+    const prompt = buildActionPlannerPrompt({
+        task: contract.task,
+        recommendation: judgeReport.recommendation,
+        conditions: judgeReport.conditions,
+        upheld_risks: risks,
+        blind_spots: map.blind_spots,
+        open_questions: openQuestions,
+    }, loadSkill('idea-refinement', 'planner'));
+    try {
+        const first = await jsonCall(ctx, ctx.handle(ctx.roles.judge), 'S9b-plan', prompt, ActionPlan);
+        const anchored = anchoredActionPlan(first, anchors);
+        if (anchored) {
+            await ctx.writer.writeJson('action-plan', anchored);
+            return anchored;
+        }
+        if (ctx.budget.limit - ctx.budget.used < 1)
+            return fallback('plan_fallback');
+        const repair = `${prompt}\n\n---\nYour previous plan had no actions with valid anchors.\n` +
+            `Valid dispute ids: ${anchors.disputeIds.join(', ') || '(none)'}\n` +
+            `Valid blind spots: ${anchors.blindSpots.join(' | ') || '(none)'}\n` +
+            `Valid open questions: ${anchors.openQuestions.join(' | ') || '(none)'}\n` +
+            `Output ONLY corrected JSON with every action anchored to one of those values.`;
+        const repaired = await jsonCall(ctx, ctx.handle(ctx.roles.judge), 'S9b-anchor-repair', repair, ActionPlan);
+        const repairedAnchored = anchoredActionPlan(repaired, anchors);
+        if (repairedAnchored) {
+            await ctx.writer.writeJson('action-plan', repairedAnchored);
+            return repairedAnchored;
+        }
+        return fallback('plan_fallback');
+    }
+    catch (e) {
+        if (isFatal(e) && !(e instanceof BudgetExceeded))
+            throw e;
+        return fallback('plan_fallback');
+    }
+}

package/dist/providers/adapter-core.js

@@ -0,0 +1,131 @@
+import { spawnCapture } from './spawn.js';
+const CREDENTIAL_RE = /KEY|TOKEN|SECRET/i;
+/** Inherit the user's env minus anything credential-looking (§7.2, §19 defense in depth). */
+export function filterEnv(base = process.env) {
+    const out = {};
+    for (const [k, v] of Object.entries(base)) {
+        if (!CREDENTIAL_RE.test(k))
+            out[k] = v;
+    }
+    return out;
+}
+const AUTH_RE = /\b(login|log in|unauthorized|expired|authenticat|not authenticated|ineligible|unsupported client|no longer supported|sign in|please run)\b/i;
+const QUOTA_RE = /\b(rate limit|quota|429|resource[_ ]exhausted|too many requests|usage limit|out of)\b/i;
+/**
+ * Map a raw process result to a ProviderError, or 'OK' (§7.2 taxonomy). Order is deliberate.
+ * Exit 0 short-circuits to OK — we do NOT scan stderr on success. Some CLIs (codex) write a
+ * full session transcript (prompt + result) to stderr, so pattern-matching it on success would
+ * false-positive AUTH/QUOTA on innocent content. AUTH/QUOTA are failure modes: only relevant
+ * when the process did not exit cleanly.
+ */
+export function classify(raw) {
+    if (raw.notFound)
+        return 'NOT_FOUND';
+    if (raw.timedOut)
+        return 'TIMEOUT';
+    if (raw.code === 0)
+        return 'OK';
+    const err = raw.stderr ?? '';
+    if (AUTH_RE.test(err))
+        return 'AUTH';
+    if (QUOTA_RE.test(err))
+        return 'QUOTA';
+    return 'CRASH';
+}
+function tryParse(s) {
+    try {
+        return JSON.parse(s);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** First balanced {...} object in text, ignoring braces inside strings. */
+function firstBalancedObject(text) {
+    const start = text.indexOf('{');
+    if (start < 0)
+        return undefined;
+    let depth = 0;
+    let inStr = false;
+    let esc = false;
+    for (let i = start; i < text.length; i++) {
+        const c = text[i];
+        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 === '}') {
+            depth--;
+            if (depth === 0)
+                return text.slice(start, i + 1);
+        }
+    }
+    return undefined;
+}
+/**
+ * §14 JSON location within already-de-enveloped model text:
+ * whole-parse → fenced ```json block → first balanced {...}. Returns undefined if none parse.
+ */
+export function extractJson(text) {
+    const whole = tryParse(text.trim());
+    if (whole !== undefined)
+        return whole;
+    const fence = text.match(/```(?:json)?\s*([\s\S]*?)```/i);
+    if (fence?.[1]) {
+        const p = tryParse(fence[1].trim());
+        if (p !== undefined)
+            return p;
+    }
+    const bal = firstBalancedObject(text);
+    if (bal) {
+        const p = tryParse(bal);
+        if (p !== undefined)
+            return p;
+    }
+    return undefined;
+}
+/**
+ * Shared adapter runner: build argv → spawn (fd-capture) → classify → de-envelope → extract JSON.
+ * Exactly one retry, only for TIMEOUT | BAD_OUTPUT | CRASH (§7.2). AUTH/QUOTA/NOT_FOUND fail fast.
+ */
+export async function runAdapter(spec, req, flags, deps = {}) {
+    const spawnFn = deps.spawn ?? spawnCapture;
+    const attempt = async () => {
+        const args = spec.buildArgs(req, flags);
+        const raw = await spawnFn(spec.id, args, { cwd: req.cwd, timeoutMs: req.timeoutMs, env: filterEnv(), signal: req.signal });
+        const cls = classify(raw);
+        if (cls !== 'OK') {
+            return { ok: false, error: cls, stderrTail: raw.stderr, durationMs: raw.durationMs };
+        }
+        const envErr = spec.envelopeError?.(raw.stdout);
+        if (envErr) {
+            return { ok: false, error: envErr, stderrTail: raw.stderr, durationMs: raw.durationMs };
+        }
+        const text = spec.extractText(raw.stdout);
+        let json;
+        if (req.expectJson) {
+            json = extractJson(text);
+            if (json === undefined) {
+                return { ok: false, error: 'BAD_OUTPUT', stderrTail: raw.stderr, durationMs: raw.durationMs };
+            }
+        }
+        return { ok: true, text, json, durationMs: raw.durationMs, providerMeta: spec.meta?.(raw.stdout) };
+    };
+    const first = await attempt();
+    if (first.ok)
+        return first;
+    // Don't burn a retry (a fresh child) when the run is being aborted (Ctrl+C, T8).
+    if (!req.signal?.aborted && (first.error === 'TIMEOUT' || first.error === 'BAD_OUTPUT' || first.error === 'CRASH')) {
+        return attempt(); // exactly one retry
+    }
+    return first;
+}

package/dist/providers/adapters.js

@@ -0,0 +1,9 @@
+import { claude } from './claude.js';
+import { codex } from './codex.js';
+import { agy } from './agy.js';
+/** All provider adapters with a working run(). */
+export const ADAPTERS = {
+    claude,
+    codex,
+    agy,
+};

package/dist/providers/agy.js

@@ -0,0 +1,29 @@
+import { runAdapter } from './adapter-core.js';
+/**
+ * Antigravity CLI (`agy`, runs Gemini 3.1 Pro) — replaces the discontinued gemini CLI.
+ * Invocation (verified live, T2):
+ *   agy -p "<prompt>" [--sandbox]
+ * No JSON-output flag: `-p` prints the model's response as raw text, so when we ask for JSON
+ * the response *is* the JSON → §14 extraction parses it directly (no envelope to strip).
+ * Read-only is best-effort via `--sandbox` (terminal restrictions); write-blocking is
+ * UNVERIFIED — see docs/PROVIDER_NOTES.md, to be pinned down at T10 (code-review).
+ * NEVER pass --dangerously-skip-permissions (§19).
+ */
+const agySpec = {
+    id: 'agy',
+    buildArgs(req, flags) {
+        const args = ['-p', req.prompt];
+        if (req.readOnly !== false && flags.readOnlyFlag === 'sandbox')
+            args.push('--sandbox');
+        if (flags.model)
+            args.push('--model', flags.model); // V8: verified `agy --model <id>` (ids may contain spaces — one argv elem)
+        return args;
+    },
+    extractText(stdout) {
+        return stdout; // raw text; §14 extraction handles whole/fenced/balanced JSON
+    },
+};
+export const agy = {
+    id: 'agy',
+    run: (req, flags, deps) => runAdapter(agySpec, req, flags, deps),
+};

package/dist/providers/claude.js

@@ -0,0 +1,56 @@
+import { runAdapter } from './adapter-core.js';
+function envelope(stdout) {
+    try {
+        const v = JSON.parse(stdout);
+        return v && typeof v === 'object' ? v : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Claude Code (`claude`). Invocation per §7.3:
+ *   claude -p "<prompt>" [--output-format json] [--permission-mode plan]
+ * `--output-format json` returns an envelope: { type, subtype, is_error, result, session_id,
+ * total_cost_usd, usage, ... } — the model's text lives in `.result` (verified live, T2).
+ */
+const claudeSpec = {
+    id: 'claude',
+    buildArgs(req, flags) {
+        const args = ['-p', req.prompt];
+        if (req.expectJson && flags.jsonOutput)
+            args.push('--output-format', 'json');
+        if (req.readOnly !== false && flags.readOnlyFlag === 'plan')
+            args.push('--permission-mode', 'plan');
+        if (flags.model)
+            args.push('--model', flags.model); // V8: verified `claude --model <alias|name>`
+        return args;
+    },
+    extractText(stdout) {
+        const env = envelope(stdout);
+        if (env && typeof env.result === 'string')
+            return env.result;
+        return stdout; // plain mode (no --output-format) or unexpected shape
+    },
+    envelopeError(stdout) {
+        const env = envelope(stdout);
+        if (env?.is_error === true)
+            return 'CRASH'; // model-level failure signalled in the envelope
+        return undefined;
+    },
+    meta(stdout) {
+        const env = envelope(stdout);
+        if (!env)
+            return undefined;
+        return {
+            session_id: env.session_id,
+            subtype: env.subtype,
+            total_cost_usd: env.total_cost_usd,
+            usage: env.usage,
+        };
+    },
+};
+export const claude = {
+    id: 'claude',
+    run: (req, flags, deps) => runAdapter(claudeSpec, req, flags, deps),
+};

package/dist/providers/codex.js

@@ -0,0 +1,35 @@
+import { runAdapter } from './adapter-core.js';
+/**
+ * Codex CLI (`codex`). Invocation (verified live, T3):
+ *   codex exec [-s read-only] "<prompt>"   (cwd set via spawn's cwd option)
+ *
+ * Output split (verified): stdout carries ONLY the model's final message; the full session
+ * transcript (session id, echoed prompt, "tokens used") goes to stderr. So stdout *is* the
+ * result text → §14 extraction parses it directly, no envelope. (We deliberately avoid
+ * `--json` JSONL: plain stdout is already clean and needs no event-stream parsing.)
+ *
+ * Because codex mirrors the prompt + result into stderr, error classification must not scan
+ * stderr on success — adapter-core.classify short-circuits on exit 0 for exactly this reason.
+ *
+ * T10 note: `codex exec` may need a git-repo/writable-cwd check for arbitrary review dirs;
+ * verify when wiring code-review. NEVER pass --dangerously-bypass-approvals-and-sandbox (§19).
+ */
+const codexSpec = {
+    id: 'codex',
+    buildArgs(req, flags) {
+        const args = ['exec'];
+        if (req.readOnly !== false && flags.readOnlyFlag === 'sandbox')
+            args.push('-s', 'read-only');
+        if (flags.model)
+            args.push('--model', flags.model); // V8: verified `codex exec --model <id>` (before the prompt)
+        args.push(req.prompt);
+        return args;
+    },
+    extractText(stdout) {
+        return stdout; // clean final message; §14 extraction handles whole/fenced/balanced JSON
+    },
+};
+export const codex = {
+    id: 'codex',
+    run: (req, flags, deps) => runAdapter(codexSpec, req, flags, deps),
+};