aiki-cli 0.2.2 → 0.3.1

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

@@ -1,24 +1,46 @@
 // 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';
+// deterministic; if the planner fails or produces unanchored actions, we write flagged unavailability.
+import { ActionPlan, FeatureBacklog, ImplementationPlan } from '../../schemas/index.js';
+import { z } from 'zod';
 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}}
+const PlannerOutput = z.object({
+    actions: z.array(z.object({
+        order: z.number().int().min(1).optional(),
+        action: z.string().min(1),
+        why: z.string().min(1),
+        validates: z.string().min(1),
+        effort: z.string().min(1).optional(),
+        kill_signal: z.string().min(1),
+    }).strict()).min(1).max(7),
+    sequencing_note: z.string().min(1),
+    feature_backlog: FeatureBacklog.optional(),
+    implementation_plan: ImplementationPlan.optional(),
+}).strict();
+const S9B_PROMPT = `ROLE: Validation planner. You write the requested practical outputs after an idea
+council has debated and judged the idea. The actions list remains validation work: test unsettled risks,
+blind spots, or open questions, with the 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 graph claim id from upheld_risks, e.g. "G3"
   - 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.
+- Preserve the chair's numeric distinctions: operating break-even is not capital payback, and a target cap
+  is not a known cost. Do not introduce or reinterpret a number that is absent from decision_snapshot.
 - sequencing_note explains why this order is cheapest and decisive.
+- Read requested_outputs in CONTEXT. When it includes FEATURE_BACKLOG, include feature_backlog with
+  must/should/later items {feature,user_value,rationale,effort:S|M|L} and wont items {feature,reason}.
+  Prioritize the smallest judge-impressing golden path; MUST is required, not a wishlist.
+- When requested_outputs includes IMPLEMENTATION_PLAN, include implementation_plan.milestones with
+  {order,timebox,outcome,tasks,acceptance_test}. This is a concrete build sequence, not validation prose.
+- Do not omit a requested output and do not invent an unrequested product surface.
 
 CONTEXT: {{CONTEXT_JSON}}`;
 function clip(s, n) {
@@ -31,29 +53,37 @@ function sevRank(s) {
 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]));
+function unresolvedRisks(graph, judgeReport) {
+    const claimById = new Map(graph.claims.map((claim) => [claim.id, claim]));
     const rulingById = new Map(judgeReport.adjudications.map((a) => [a.id, a]));
-    return map.contradictions
-        .map((d) => {
-        const adj = rulingById.get(d.id);
+    const risks = graph.claims
+        .map((claim) => {
+        const adj = rulingById.get(claim.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',
+            id: claim.id,
+            assumption: claim.proposition,
+            severity: claim.sensitivity === 'DECISIVE' ? 'HIGH' : claim.sensitivity === 'MATERIAL' ? 'MED' : 'LOW',
             reasoning: adj.reasoning,
         };
     })
-        .filter((r) => r !== null)
-        .sort((a, b) => sevRank(a.severity) - sevRank(b.severity));
+        .filter((risk) => risk !== null);
+    const seen = new Set(risks.map((risk) => risk.id));
+    for (const hole of graph.holes.evidence) {
+        if (seen.has(hole.claim_id))
+            continue;
+        const claim = claimById.get(hole.claim_id);
+        if (!claim)
+            continue;
+        risks.push({
+            id: claim.id,
+            assumption: claim.proposition,
+            severity: claim.sensitivity === 'DECISIVE' ? 'HIGH' : claim.sensitivity === 'MATERIAL' ? 'MED' : 'LOW',
+            reasoning: hole.reason,
+        });
+    }
+    return risks.sort((a, b) => sevRank(a.severity) - sevRank(b.severity));
 }
 export function buildActionPlannerPrompt(input, skill) {
     return S9B_PROMPT
@@ -62,7 +92,7 @@ export function buildActionPlannerPrompt(input, skill) {
 }
 export function validAnchor(anchor, anchors) {
     const a = anchor.trim();
-    if (anchors.disputeIds.includes(a))
+    if (anchors.claimIds.includes(a))
         return true;
     if (a.toLowerCase().startsWith('blind:')) {
         const label = norm(a.slice('blind:'.length));
@@ -80,104 +110,107 @@ export function validAnchor(anchor, anchors) {
     }
     return false;
 }
-export function anchoredActionPlan(plan, anchors) {
+export function anchoredActionPlan(plan, anchors, requestedOutputs = []) {
     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 };
+    if (requestedOutputs.includes('FEATURE_BACKLOG') && !plan.feature_backlog)
+        return null;
+    if (requestedOutputs.includes('IMPLEMENTATION_PLAN') && !plan.implementation_plan)
+        return null;
+    return {
+        actions,
+        sequencing_note: plan.sequencing_note,
+        ...(requestedOutputs.includes('FEATURE_BACKLOG') && plan.feature_backlog ? { feature_backlog: plan.feature_backlog } : {}),
+        ...(requestedOutputs.includes('IMPLEMENTATION_PLAN') && plan.implementation_plan ? { implementation_plan: plan.implementation_plan } : {}),
+    };
 }
-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.',
-        });
-    }
+export function normalizeEffort(raw) {
+    const value = raw?.trim().toLowerCase();
+    if (value === 's' || value === 'm' || value === 'l')
+        return value.toUpperCase();
+    const match = value?.match(/(\d+(?:\.\d+)?)(?:\s*-\s*(\d+(?:\.\d+)?))?\s*(minute|hour|day|week|month|year)s?/);
+    if (!match)
+        return 'M';
+    const amount = Number(match[2] ?? match[1]);
+    const unit = match[3];
+    const days = amount * (unit === 'minute' ? 1 / 1440 : unit === 'hour' ? 1 / 24 : unit === 'day' ? 1 : unit === 'week' ? 7 : unit === 'month' ? 30 : 365);
+    return days <= 2 ? 'S' : days <= 14 ? 'M' : 'L';
+}
+export function normalizePlannerOutput(plan) {
     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.',
+        actions: plan.actions.map((action, i) => ({
+            ...action,
+            order: i + 1,
+            effort: normalizeEffort(action.effort),
+        })),
+        sequencing_note: plan.sequencing_note,
+        ...(plan.feature_backlog ? { feature_backlog: plan.feature_backlog } : {}),
+        ...(plan.implementation_plan ? { implementation_plan: plan.implementation_plan } : {}),
     });
 }
-export async function s9bPlan(ctx, contract, seats, map, judgeReport) {
+function unavailablePlan(reason, contract, risks, blindSpots, openQuestions) {
+    const unresolved = openQuestions.length ? openQuestions : [
+        ...risks.map((risk) => `What evidence would resolve whether ${risk.assumption}?`),
+        ...blindSpots.map((spot) => `What evidence resolves the ${spot} gap?`),
+    ];
+    return {
+        kind: 'PlannerUnavailable',
+        reason,
+        unresolved_questions: (unresolved.length ? unresolved : [`What evidence would change the verdict for ${clip(contract.task, 100)}?`]).slice(0, 10),
+    };
+}
+export async function s9bPlan(ctx, contract, seats, graph, judgeReport) {
     const openQuestions = mergeOpenQuestions(seats);
-    const risks = upheldRisks(map, judgeReport);
+    const requestedOutputs = contract.requested_outputs
+        ?? ['DECISION'];
+    const risks = unresolvedRisks(graph, judgeReport);
+    const blindSpots = graph.holes.coverage.map((hole) => hole.label);
     const anchors = {
-        disputeIds: risks.map((r) => r.id),
-        blindSpots: map.blind_spots,
+        claimIds: risks.map((r) => r.id),
+        blindSpots,
         openQuestions,
     };
     const fallback = async (flag) => {
         ctx.addFlag(flag);
-        const plan = fallbackActionPlan(contract, map, judgeReport, openQuestions);
+        const plan = unavailablePlan(flag === 'plan_skipped' ? 'budget_exhausted' : 'planner_failed', contract, risks, blindSpots, openQuestions);
         await ctx.writer.writeJson('action-plan', plan);
         return plan;
     };
-    if (ctx.budget.limit - ctx.budget.used < 2)
+    if (ctx.budget.limit - ctx.budget.used < 1)
         return fallback('plan_skipped');
     const prompt = buildActionPlannerPrompt({
         task: contract.task,
         recommendation: judgeReport.recommendation,
         conditions: judgeReport.conditions,
+        decision_snapshot: judgeReport.decision_snapshot,
         upheld_risks: risks,
-        blind_spots: map.blind_spots,
+        blind_spots: blindSpots,
         open_questions: openQuestions,
+        requested_outputs: requestedOutputs,
     }, loadSkill('idea-refinement', 'planner'));
     try {
-        const first = await jsonCall(ctx, ctx.handle(ctx.roles.judge), 'S9b-plan', prompt, ActionPlan);
-        const anchored = anchoredActionPlan(first, anchors);
+        const first = normalizePlannerOutput(await jsonCall(ctx, ctx.handle(ctx.roles.judge), 'S9b-plan', prompt, PlannerOutput, {
+            repair: ctx.budget.limit - ctx.budget.used >= 2,
+        }));
+        const anchored = anchoredActionPlan(first, anchors, requestedOutputs);
         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` +
+        const repair = `${prompt}\n\n---\nYour previous plan had no actions with valid anchors or omitted a requested deliverable.\n` +
+            `Valid graph claim ids: ${anchors.claimIds.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);
+            `Required outputs: ${requestedOutputs.join(', ')}\n` +
+            `Output ONLY corrected JSON with every action anchored and every requested deliverable present.`;
+        const repaired = normalizePlannerOutput(await jsonCall(ctx, ctx.handle(ctx.roles.judge), 'S9b-anchor-repair', repair, PlannerOutput, { repair: false }));
+        const repairedAnchored = anchoredActionPlan(repaired, anchors, requestedOutputs);
         if (repairedAnchored) {
             await ctx.writer.writeJson('action-plan', repairedAnchored);
             return repairedAnchored;

package/dist/orchestration/url-sources.js

@@ -0,0 +1,200 @@
+import { createHash } from 'node:crypto';
+import { lookup } from 'node:dns/promises';
+import { isIP } from 'node:net';
+import { UrlSourceSet, } from '../schemas/index.js';
+const MAX_SOURCES = 5;
+const MAX_RESPONSE_BYTES = 500_000;
+const MAX_CONTENT_CHARS = 30_000;
+const MAX_REDIRECTS = 3;
+export function extractPublicUrls(input) {
+    const matches = input.match(/https?:\/\/[^\s<>"']+/gi) ?? [];
+    const seen = new Set();
+    const urls = [];
+    for (const match of matches) {
+        const cleaned = match.replace(/[.,;:!?\]\)}]+$/g, '');
+        if (seen.has(cleaned))
+            continue;
+        seen.add(cleaned);
+        urls.push(cleaned);
+        if (urls.length === MAX_SOURCES)
+            break;
+    }
+    return urls;
+}
+function isPrivateAddress(address) {
+    if (address === '::' || address === '::1')
+        return true;
+    if (address.toLowerCase().startsWith('fe80:') || address.toLowerCase().startsWith('fc') || address.toLowerCase().startsWith('fd'))
+        return true;
+    const mapped = address.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/i)?.[1];
+    const ipv4 = mapped ?? (isIP(address) === 4 ? address : undefined);
+    if (!ipv4)
+        return false;
+    const [a, b] = ipv4.split('.').map(Number);
+    return a === 0
+        || a === 10
+        || a === 127
+        || (a === 169 && b === 254)
+        || (a === 172 && b >= 16 && b <= 31)
+        || (a === 192 && b === 168)
+        || (a === 100 && b >= 64 && b <= 127)
+        || a >= 224;
+}
+async function assertPublicUrl(url, resolveHostname) {
+    if (url.protocol !== 'http:' && url.protocol !== 'https:')
+        throw new Error('only public http/https URLs are supported');
+    const hostname = url.hostname.toLowerCase().replace(/\.$/, '');
+    if (hostname === 'localhost' || hostname.endsWith('.localhost') || hostname.endsWith('.local') || hostname === '169.254.169.254') {
+        throw new Error('private or local URLs are not allowed');
+    }
+    if (isIP(hostname) && isPrivateAddress(hostname))
+        throw new Error('private or local URLs are not allowed');
+    if (!resolveHostname || isIP(hostname))
+        return;
+    const addresses = await lookup(hostname, { all: true });
+    if (addresses.length === 0 || addresses.some(({ address }) => isPrivateAddress(address))) {
+        throw new Error('private or local URLs are not allowed');
+    }
+}
+function npmRegistryUrl(url) {
+    if (url.hostname !== 'npmjs.com' && url.hostname !== 'www.npmjs.com')
+        return undefined;
+    const match = url.pathname.match(/^\/package\/(.+?)\/?$/);
+    if (!match)
+        return undefined;
+    const name = decodeURIComponent(match[1]);
+    return `https://registry.npmjs.org/${encodeURIComponent(name)}/latest`;
+}
+function decodeHtml(value) {
+    const named = { amp: '&', apos: "'", gt: '>', lt: '<', nbsp: ' ', quot: '"' };
+    return value.replace(/&(#x[\da-f]+|#\d+|\w+);/gi, (entity, code) => {
+        if (code[0] === '#') {
+            const radix = code[1]?.toLowerCase() === 'x' ? 16 : 10;
+            const value = Number.parseInt(code.slice(radix === 16 ? 2 : 1), radix);
+            return Number.isFinite(value) ? String.fromCodePoint(value) : entity;
+        }
+        return named[code.toLowerCase()] ?? entity;
+    });
+}
+function readableHtml(html) {
+    const titleMatch = html.match(/<title\b[^>]*>([\s\S]*?)<\/title>/i);
+    const title = titleMatch ? decodeHtml(titleMatch[1].replace(/<[^>]+>/g, ' ')).replace(/\s+/g, ' ').trim() : undefined;
+    const content = decodeHtml(html
+        .replace(/<(script|style|noscript|svg)\b[^>]*>[\s\S]*?<\/\1>/gi, ' ')
+        .replace(/<[^>]+>/g, ' '))
+        .replace(/\s+/g, ' ')
+        .trim();
+    return { title: title || undefined, content };
+}
+function sha256(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+async function readLimited(response) {
+    if (!response.body)
+        return '';
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let bytes = 0;
+    let body = '';
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            return body + decoder.decode();
+        bytes += value.byteLength;
+        if (bytes > MAX_RESPONSE_BYTES) {
+            await reader.cancel();
+            throw new Error(`response exceeds ${MAX_RESPONSE_BYTES} bytes`);
+        }
+        body += decoder.decode(value, { stream: true });
+    }
+}
+function failure(id, url, accessedAt, status, error, finalUrl) {
+    return { id, url, final_url: finalUrl, status, accessed_at: accessedAt, error };
+}
+async function fetchWithRedirects(startUrl, fetchImpl, resolveHostname) {
+    let current = new URL(startUrl);
+    for (let redirect = 0; redirect <= MAX_REDIRECTS; redirect++) {
+        await assertPublicUrl(current, resolveHostname);
+        const response = await fetchImpl(current.toString(), {
+            redirect: 'manual',
+            headers: { accept: 'text/html,application/json,text/plain;q=0.9,*/*;q=0.1' },
+        });
+        if (response.status < 300 || response.status >= 400)
+            return { response, finalUrl: current.toString() };
+        const location = response.headers.get('location');
+        if (!location)
+            return { response, finalUrl: current.toString() };
+        if (redirect === MAX_REDIRECTS)
+            throw new Error(`more than ${MAX_REDIRECTS} redirects`);
+        current = new URL(location, current);
+    }
+    throw new Error('redirect limit exceeded');
+}
+async function snapshotOne(sourceUrl, index, options) {
+    const id = `U${index + 1}`;
+    const accessedAt = (options.now?.() ?? new Date()).toISOString();
+    const fetchImpl = options.fetchImpl ?? fetch;
+    try {
+        const original = new URL(sourceUrl);
+        await assertPublicUrl(original, options.fetchImpl === undefined);
+        const adapterUrl = npmRegistryUrl(original);
+        const { response, finalUrl } = await fetchWithRedirects(adapterUrl ?? sourceUrl, fetchImpl, options.fetchImpl === undefined);
+        const declaredLength = Number(response.headers.get('content-length') ?? 0);
+        if (declaredLength > MAX_RESPONSE_BYTES) {
+            return failure(id, sourceUrl, accessedAt, 'FAILED', `response exceeds ${MAX_RESPONSE_BYTES} bytes`, finalUrl);
+        }
+        const body = await readLimited(response);
+        const contentType = response.headers.get('content-type')?.split(';')[0]?.trim() || 'text/plain';
+        const blocked = response.status === 403
+            || response.status === 429
+            || response.status === 503
+            || /cdn-cgi\/challenge|just a moment|captcha|access denied/i.test(body);
+        if (blocked) {
+            return failure(id, sourceUrl, accessedAt, 'BLOCKED', `site blocked automated access (HTTP ${response.status})`, finalUrl);
+        }
+        if (!response.ok)
+            return failure(id, sourceUrl, accessedAt, 'FAILED', `HTTP ${response.status}`, finalUrl);
+        let title;
+        let content;
+        if (adapterUrl) {
+            const metadata = JSON.parse(body);
+            const name = typeof metadata.name === 'string' ? metadata.name : original.pathname.split('/').at(-1) ?? 'npm package';
+            const version = typeof metadata.version === 'string' ? metadata.version : 'unknown version';
+            title = `${name} ${version}`;
+            content = [
+                `Package: ${name}`,
+                `Version: ${version}`,
+                typeof metadata.description === 'string' ? `Description: ${metadata.description}` : '',
+                typeof metadata.homepage === 'string' ? `Homepage: ${metadata.homepage}` : '',
+                typeof metadata.readme === 'string' ? `README:\n${metadata.readme}` : '',
+            ].filter(Boolean).join('\n');
+        }
+        else if (contentType === 'text/html' || /<html\b|<body\b/i.test(body)) {
+            ({ title, content } = readableHtml(body));
+        }
+        else {
+            content = body.replace(/\s+/g, ' ').trim();
+        }
+        content = content.slice(0, MAX_CONTENT_CHARS).trim();
+        if (!content)
+            return failure(id, sourceUrl, accessedAt, 'FAILED', 'source contained no readable text', finalUrl);
+        return {
+            id,
+            url: sourceUrl,
+            final_url: finalUrl,
+            status: 'FETCHED',
+            title,
+            content_type: contentType,
+            accessed_at: accessedAt,
+            sha256: sha256(content),
+            content,
+        };
+    }
+    catch (error) {
+        return failure(id, sourceUrl, accessedAt, 'FAILED', error instanceof Error ? error.message : String(error));
+    }
+}
+export async function snapshotUrlSources(input, options = {}) {
+    const sources = await Promise.all(extractPublicUrls(input).map((url, index) => snapshotOne(url, index, options)));
+    return UrlSourceSet.parse({ sources });
+}

package/dist/providers/codex.js

@@ -17,7 +17,8 @@ import { runAdapter } from './adapter-core.js';
 const codexSpec = {
     id: 'codex',
     buildArgs(req, flags) {
-        const args = ['exec', '--skip-git-repo-check'];
+        // `--search` is a verified root option: it must precede `exec` (Codex 0.144.1).
+        const args = req.research ? ['--search', 'exec', '--skip-git-repo-check'] : ['exec', '--skip-git-repo-check'];
         if (req.readOnly !== false && flags.readOnlyFlag === 'sandbox')
             args.push('-s', 'read-only');
         if (flags.model)

package/dist/providers/spawn.js

@@ -81,6 +81,7 @@ export const spawnCapture = (bin, args, { cwd, timeoutMs, env, signal }) => {
         let notFound = false;
         let settled = false;
         const child = spawn(bin, args, { cwd, env, detached: true, stdio: ['ignore', fd, 'pipe'] });
+        child.unref(); // a child that survives the group-kill must never keep our process alive post-resolve
         // SIGKILL the whole detached process group. Shared by the timeout and the Ctrl+C abort (T8).
         const killGroup = () => {
             try {
@@ -99,6 +100,10 @@ export const spawnCapture = (bin, args, { cwd, timeoutMs, env, signal }) => {
         const timer = setTimeout(() => {
             timedOut = true;
             killGroup();
+            // Bound the call at timeoutMs even if the group-kill missed a detached child holding our pipe/fd
+            // (observed with the claude CLI). Waiting on 'close' alone lets one hung call overrun the wall-clock
+            // deadline by an unbounded amount; force-resolve instead. A late 'close' is ignored (`settled`).
+            finish(null, 'SIGKILL');
         }, timeoutMs);
         // Ctrl+C: kill the in-flight child immediately so no orphaned metered call survives (§472, T8).
         const onAbort = () => killGroup();