sidecar-cli 0.1.5-beta.1 → 0.1.5-beta.2

package/dist/prompts/prompt-service.js

@@ -1,3 +1,4 @@
+import { loadPromptPreferences } from '../runners/config.js';
 import { createRunRecordEntry, updateRunRecordEntry } from '../runs/run-service.js';
 import { getTaskPacket } from '../tasks/task-service.js';
 import { compilePromptMarkdown, saveCompiledPrompt } from './prompt-compiler.js';
@@ -10,6 +11,11 @@ export function compileTaskPrompt(input) {
         status: 'preparing',
         branch: task.tracking.branch,
         worktree: task.tracking.worktree,
+        ...(input.parentRunId ? { parent_run_id: input.parentRunId } : {}),
+        ...(input.replayReason ? { replay_reason: input.replayReason } : {}),
+        ...(input.pipelineId ? { pipeline_id: input.pipelineId } : {}),
+        ...(input.pipelineStep ? { pipeline_step: input.pipelineStep } : {}),
+        ...(input.pipelineTotal ? { pipeline_total: input.pipelineTotal } : {}),
     });
     const compiledPrompt = compilePromptMarkdown({
         task,
@@ -17,6 +23,7 @@ export function compileTaskPrompt(input) {
         runner: input.runner,
         agentRole: input.agentRole,
         linkedContext: input.linkedContext,
+        budget: loadPromptPreferences(input.rootPath),
     });
     const promptPath = saveCompiledPrompt(input.rootPath, created.run.run_id, compiledPrompt.markdown);
     updateRunRecordEntry(input.rootPath, created.run.run_id, {

package/dist/prompts/prompt-spec.js

@@ -0,0 +1,128 @@
+// Freestanding prompt spec loader. Parses a `.yaml`/`.yml`/`.json` file into
+// the `CompileSectionsInput` shape used by the core compiler — no TaskPacket
+// required. Intended for quick prompt iteration (`sidecar prompt compile
+// prompt.yaml`) and as an agent-facing primitive for composing prompts
+// programmatically.
+import fs from 'node:fs';
+import path from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { z } from 'zod';
+import { PROMPT_PREFERENCE_DEFAULTS } from '../runners/config.js';
+const trimPolicySchema = z.enum(['keep', 'trim-last', 'drop']);
+const trimConfigSchema = z
+    .object({
+    policy: trimPolicySchema.optional(),
+    limit: z.number().int().positive().optional(),
+    limit_strict: z.number().int().positive().optional(),
+    overflow_label: z.string().optional(),
+})
+    .strict();
+// `content` accepts either a text block (string or string[]) or a list
+// (`list: []`). A section is a text section when `content` is a string or
+// single-item array without `list`; a list section when `list` is present.
+const sectionSpecSchema = z
+    .object({
+    id: z.string().min(1).optional(),
+    title: z.string().min(1),
+    required: z.boolean().optional(),
+    // text content:
+    content: z.union([z.string(), z.array(z.string())]).optional(),
+    // list content:
+    list: z.array(z.string()).optional(),
+    empty_placeholder: z.string().optional(),
+    trim: z.union([trimPolicySchema, trimConfigSchema]).optional(),
+})
+    .strict();
+const budgetSchema = z
+    .object({
+    target: z.number().int().positive().optional(),
+    max: z.number().int().positive().optional(),
+})
+    .strict();
+export const promptSpecSchema = z
+    .object({
+    header: z.union([z.string(), z.array(z.string())]).optional(),
+    sections: z.array(sectionSpecSchema).min(1),
+    budget: budgetSchema.optional(),
+    policy_overrides: z.record(z.string(), trimPolicySchema).optional(),
+})
+    .strict();
+function toLines(value) {
+    if (value == null)
+        return [];
+    if (typeof value === 'string')
+        return value.split('\n').map((l) => l.replace(/\s+$/, ''));
+    return value;
+}
+function slugifyTitle(title) {
+    return title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, '')
+        .slice(0, 40) || 'section';
+}
+function resolveTrim(entry, isList) {
+    if (entry.required)
+        return { policy: 'keep' };
+    const t = entry.trim;
+    if (t == null)
+        return { policy: 'keep' };
+    if (typeof t === 'string')
+        return { policy: t };
+    const policy = t.policy ?? (isList ? 'trim-last' : 'keep');
+    return { policy, config: t };
+}
+function toSection(entry, index) {
+    const id = entry.id?.trim() || `${slugifyTitle(entry.title)}_${index + 1}`;
+    const isList = entry.list != null;
+    const trim = resolveTrim(entry, isList);
+    if (isList) {
+        const items = entry.list ?? [];
+        const section = {
+            id,
+            title: entry.title,
+            kind: 'list',
+            items,
+            ...(entry.empty_placeholder ? { empty_placeholder: entry.empty_placeholder } : {}),
+            trim: {
+                policy: trim.policy,
+                ...(trim.config?.limit ? { limit: trim.config.limit } : {}),
+                ...(trim.config?.limit_strict ? { limit_strict: trim.config.limit_strict } : {}),
+                ...(trim.config?.overflow_label ? { overflow_label: trim.config.overflow_label } : {}),
+            },
+        };
+        return section;
+    }
+    const section = {
+        id,
+        title: entry.title,
+        kind: 'text',
+        content: toLines(entry.content),
+        ...(trim.policy === 'keep' || trim.policy === 'drop' ? { trim: trim.policy } : { trim: 'keep' }),
+    };
+    return section;
+}
+export function specToCompileInput(spec) {
+    const header = toLines(spec.header);
+    const sections = spec.sections.map((s, i) => toSection(s, i));
+    const target = spec.budget?.target ?? PROMPT_PREFERENCE_DEFAULTS.budget_target;
+    const max = spec.budget?.max ?? Math.max(target, PROMPT_PREFERENCE_DEFAULTS.budget_max);
+    return {
+        ...(header.length > 0 ? { header } : {}),
+        sections,
+        budget: { target, max },
+        ...(spec.policy_overrides ? { policy_overrides: spec.policy_overrides } : {}),
+    };
+}
+export function parsePromptSpec(raw, format) {
+    const parsed = format === 'json' ? JSON.parse(raw) : parseYaml(raw);
+    return promptSpecSchema.parse(parsed);
+}
+export function loadPromptSpec(specPath) {
+    const abs = path.resolve(specPath);
+    const raw = fs.readFileSync(abs, 'utf8');
+    const ext = path.extname(abs).toLowerCase();
+    const format = ext === '.json' ? 'json' : 'yaml';
+    const spec = parsePromptSpec(raw, format);
+    return { spec, input: specToCompileInput(spec) };
+}

package/dist/prompts/sections.js

@@ -0,0 +1,194 @@
+// Runner-agnostic, packet-agnostic prompt compiler.
+//
+// A section is either a block of raw text (`kind: 'text'`) or a bulleted list
+// (`kind: 'list'`). Each section carries a stable `id` so callers — and the
+// `--section-policy`/`--explain` CLI surfaces — can reference it without
+// depending on the rendered title. The core does three jobs: (1) render to
+// markdown, (2) apply per-section trim policies under a token budget,
+// (3) produce a trace explaining what happened to each section.
+//
+// The `TaskPacket` adapter lives in `packet-sections.ts` and re-uses this
+// primitive. Freestanding `.yaml`/`.json` spec files use the same type surface
+// via `prompt-spec.ts`.
+export function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+function dedupeList(items) {
+    const seen = new Set();
+    const out = [];
+    for (const item of items.map((v) => v.trim()).filter(Boolean)) {
+        const key = item.toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(item);
+    }
+    return out;
+}
+function renderSection(section, items) {
+    if (section.kind === 'text') {
+        const lines = [`## ${section.title}`, ...section.content, ''];
+        return lines.join('\n');
+    }
+    const rendered = items ?? section.items;
+    const empty = section.empty_placeholder ?? '- none';
+    const body = rendered.length === 0 ? [empty] : rendered.map((v) => (v.startsWith('- ') ? v : `- ${v}`));
+    return [`## ${section.title}`, ...body, ''].join('\n');
+}
+function renderAll(input, listItemsById, droppedIds) {
+    const lines = [];
+    if (input.header && input.header.length > 0) {
+        lines.push(...input.header);
+        lines.push('');
+    }
+    for (const section of input.sections) {
+        if (droppedIds.has(section.id))
+            continue;
+        if (section.kind === 'list') {
+            lines.push(renderSection(section, listItemsById.get(section.id) ?? section.items));
+        }
+        else {
+            lines.push(renderSection(section));
+        }
+    }
+    return `${lines.join('\n').trim()}\n`;
+}
+function applyListTrim(section, limit) {
+    const deduped = dedupeList(section.items);
+    if (limit == null || deduped.length <= limit)
+        return deduped;
+    const kept = deduped.slice(0, limit);
+    const overflow = deduped.length - kept.length;
+    if (overflow > 0 && section.trim?.overflow_label) {
+        kept.push(`+ ${overflow} more ${section.trim.overflow_label} (see task packet for full list)`);
+    }
+    return kept;
+}
+function sectionTokens(section, items) {
+    return estimateTokens(renderSection(section, items));
+}
+function effectivePolicy(section, overrides) {
+    const override = overrides?.[section.id];
+    if (override)
+        return override;
+    if (section.kind === 'text')
+        return section.trim ?? 'keep';
+    return section.trim?.policy ?? 'keep';
+}
+export function compileSections(input) {
+    const { target, max } = input.budget;
+    // Pass 1 — baseline: dedupe lists, no trimming.
+    const baseItems = new Map();
+    for (const section of input.sections) {
+        if (section.kind === 'list')
+            baseItems.set(section.id, dedupeList(section.items));
+    }
+    const baselineMarkdown = renderAll(input, baseItems, new Set());
+    const baselineTokens = estimateTokens(baselineMarkdown);
+    // Fast path — fits within target, nothing to trim.
+    if (baselineTokens <= target) {
+        const traces = input.sections.map((section) => {
+            const items = section.kind === 'list' ? baseItems.get(section.id) ?? [] : undefined;
+            return {
+                id: section.id,
+                title: section.title,
+                kind: section.kind,
+                policy_applied: effectivePolicy(section, input.policy_overrides),
+                ...(section.kind === 'list' ? { total_items: dedupeList(section.items).length, kept_items: items?.length ?? 0 } : {}),
+                was_trimmed: false,
+                was_dropped: false,
+                estimated_tokens: sectionTokens(section, items),
+            };
+        });
+        return {
+            markdown: baselineMarkdown,
+            metadata: {
+                estimated_tokens_before: baselineTokens,
+                estimated_tokens_after: baselineTokens,
+                budget_target: target,
+                budget_max: max,
+                trimmed_sections: [],
+                dropped_sections: [],
+                sections: traces,
+            },
+        };
+    }
+    // Pass 2 — target trim: apply `limit` to each trim-last list (except keep).
+    const passItems = new Map();
+    const droppedIds = new Set();
+    for (const section of input.sections) {
+        if (section.kind !== 'list')
+            continue;
+        const policy = effectivePolicy(section, input.policy_overrides);
+        if (policy === 'keep') {
+            passItems.set(section.id, dedupeList(section.items));
+        }
+        else if (policy === 'drop') {
+            // leave droppedIds decision for the strict pass
+            passItems.set(section.id, dedupeList(section.items));
+        }
+        else {
+            // trim-last
+            passItems.set(section.id, applyListTrim(section, section.trim?.limit));
+        }
+    }
+    let markdown = renderAll(input, passItems, droppedIds);
+    let tokens = estimateTokens(markdown);
+    // Pass 3 — strict pass: apply limit_strict, then drop `drop`-policy sections.
+    if (tokens > max) {
+        for (const section of input.sections) {
+            const policy = effectivePolicy(section, input.policy_overrides);
+            if (policy === 'drop') {
+                droppedIds.add(section.id);
+                continue;
+            }
+            if (section.kind === 'list' && policy === 'trim-last') {
+                passItems.set(section.id, applyListTrim(section, section.trim?.limit_strict ?? section.trim?.limit));
+            }
+        }
+        markdown = renderAll(input, passItems, droppedIds);
+        tokens = estimateTokens(markdown);
+    }
+    const traces = input.sections.map((section) => {
+        const policy = effectivePolicy(section, input.policy_overrides);
+        const isDropped = droppedIds.has(section.id);
+        if (section.kind === 'list') {
+            const total = dedupeList(section.items).length;
+            const kept = isDropped ? 0 : passItems.get(section.id)?.length ?? 0;
+            const overflowLine = section.trim?.overflow_label ? 1 : 0;
+            const realKept = Math.max(0, kept - overflowLine);
+            return {
+                id: section.id,
+                title: section.title,
+                kind: 'list',
+                policy_applied: policy,
+                total_items: total,
+                kept_items: realKept,
+                was_trimmed: !isDropped && realKept < total,
+                was_dropped: isDropped,
+                estimated_tokens: isDropped ? 0 : sectionTokens(section, passItems.get(section.id)),
+            };
+        }
+        return {
+            id: section.id,
+            title: section.title,
+            kind: 'text',
+            policy_applied: policy,
+            was_trimmed: false,
+            was_dropped: isDropped,
+            estimated_tokens: isDropped ? 0 : sectionTokens(section),
+        };
+    });
+    return {
+        markdown,
+        metadata: {
+            estimated_tokens_before: baselineTokens,
+            estimated_tokens_after: tokens,
+            budget_target: target,
+            budget_max: max,
+            trimmed_sections: traces.filter((t) => t.was_trimmed).map((t) => t.id),
+            dropped_sections: traces.filter((t) => t.was_dropped).map((t) => t.id),
+            sections: traces,
+        },
+    };
+}

package/dist/runners/claude-runner.js

@@ -1,36 +1,15 @@
+import { buildPreparedCommand, runSpawn } from './runner-exec.js';
 export class ClaudeRunnerAdapter {
     runner = 'claude';
     prepare(input) {
-        const args = ['run', '--prompt-file', input.promptPath, '--role', input.agentRole];
-        return {
+        return buildPreparedCommand(input, 'claude', {
             command: 'claude',
-            args,
-            shellLine: `claude ${args.join(' ')}`,
-        };
+            buildArgs: (prompt) => ['-p', prompt, '--permission-mode', 'acceptEdits'],
+            shellLine: (_prompt, promptPath) => `claude -p "<prompt from ${promptPath}>"`,
+        });
     }
-    execute(input) {
-        if (input.dryRun) {
-            return {
-                ok: true,
-                executed: false,
-                exitCode: 0,
-                summary: 'Dry run: prepared Claude command only.',
-                commandsRun: [input.prepared.shellLine],
-                validationResults: ['dry-run'],
-                blockers: [],
-                followUps: [],
-            };
-        }
-        return {
-            ok: true,
-            executed: false,
-            exitCode: 0,
-            summary: 'Prepared Claude command. Live execution is placeholder behavior in v1.',
-            commandsRun: [input.prepared.shellLine],
-            validationResults: ['runner execute placeholder'],
-            blockers: [],
-            followUps: ['Integrate real Claude command execution in runner adapter.'],
-        };
+    async execute(input) {
+        return runSpawn(input, 'claude', 'Claude');
     }
     collectResult(result) {
         return result;

package/dist/runners/codex-runner.js

@@ -1,36 +1,15 @@
+import { buildPreparedCommand, runSpawn } from './runner-exec.js';
 export class CodexRunnerAdapter {
     runner = 'codex';
     prepare(input) {
-        const args = ['run', '--prompt-file', input.promptPath, '--role', input.agentRole];
-        return {
+        return buildPreparedCommand(input, 'codex', {
             command: 'codex',
-            args,
-            shellLine: `codex ${args.join(' ')}`,
-        };
+            buildArgs: (prompt) => ['exec', prompt],
+            shellLine: (_prompt, promptPath) => `codex exec "<prompt from ${promptPath}>"`,
+        });
     }
-    execute(input) {
-        if (input.dryRun) {
-            return {
-                ok: true,
-                executed: false,
-                exitCode: 0,
-                summary: 'Dry run: prepared Codex command only.',
-                commandsRun: [input.prepared.shellLine],
-                validationResults: ['dry-run'],
-                blockers: [],
-                followUps: [],
-            };
-        }
-        return {
-            ok: true,
-            executed: false,
-            exitCode: 0,
-            summary: 'Prepared Codex command. Live execution is placeholder behavior in v1.',
-            commandsRun: [input.prepared.shellLine],
-            validationResults: ['runner execute placeholder'],
-            blockers: [],
-            followUps: ['Integrate real Codex command execution in runner adapter.'],
-        };
+    async execute(input) {
+        return runSpawn(input, 'codex', 'Codex');
     }
     collectResult(result) {
         return result;

package/dist/runners/config.js

@@ -1,10 +1,20 @@
 import fs from 'node:fs';
 import { getSidecarPaths } from '../lib/paths.js';
+export const REVIEW_PREFERENCE_DEFAULTS = {
+    auto_approve_on_all_green: false,
+};
 const DEFAULTS = {
     default_runner: 'codex',
     preferred_runners: ['codex', 'claude'],
     default_agent_role: 'builder-app',
 };
+export const PROMPT_PREFERENCE_DEFAULTS = {
+    budget_target: 1200,
+    budget_max: 1500,
+};
+// Hard safety bounds. Prevents misconfiguration from producing empty or absurdly large prompts.
+export const PROMPT_BUDGET_MIN = 200;
+export const PROMPT_BUDGET_CEILING = 20000;
 export function loadRunnerPreferences(rootPath) {
     const prefsPath = getSidecarPaths(rootPath).preferencesPath;
     if (!fs.existsSync(prefsPath))
@@ -14,6 +24,7 @@ export function loadRunnerPreferences(rootPath) {
         const defaultRunner = raw.runner?.defaultRunner;
         const preferredRunners = raw.runner?.preferredRunners;
         const defaultAgentRole = raw.runner?.defaultAgentRole;
+        const runnerCommands = parseRunnerCommands(raw.runner?.runnerCommands);
         return {
             default_runner: defaultRunner === 'codex' || defaultRunner === 'claude' ? defaultRunner : DEFAULTS.default_runner,
             preferred_runners: Array.isArray(preferredRunners) && preferredRunners.every((r) => r === 'codex' || r === 'claude')
@@ -31,9 +42,73 @@ export function loadRunnerPreferences(rootPath) {
                 }
                 return DEFAULTS.default_agent_role;
             })(),
+            ...(runnerCommands ? { runner_commands: runnerCommands } : {}),
         };
     }
     catch {
         return DEFAULTS;
     }
 }
+function parseRunnerCommandOverride(raw) {
+    if (!raw || typeof raw !== 'object')
+        return undefined;
+    const r = raw;
+    const override = {};
+    if (typeof r.command === 'string' && r.command.length > 0)
+        override.command = r.command;
+    if (Array.isArray(r.args) && r.args.every((a) => typeof a === 'string'))
+        override.args = r.args;
+    return override.command || override.args ? override : undefined;
+}
+function parseRunnerCommands(raw) {
+    if (!raw || typeof raw !== 'object')
+        return undefined;
+    const r = raw;
+    const claude = parseRunnerCommandOverride(r.claude);
+    const codex = parseRunnerCommandOverride(r.codex);
+    if (!claude && !codex)
+        return undefined;
+    return {
+        ...(claude ? { claude } : {}),
+        ...(codex ? { codex } : {}),
+    };
+}
+function clampBudget(value, fallback) {
+    if (!Number.isFinite(value))
+        return fallback;
+    return Math.max(PROMPT_BUDGET_MIN, Math.min(PROMPT_BUDGET_CEILING, Math.floor(value)));
+}
+export function loadReviewPreferences(rootPath) {
+    const prefsPath = getSidecarPaths(rootPath).preferencesPath;
+    if (!fs.existsSync(prefsPath))
+        return { ...REVIEW_PREFERENCE_DEFAULTS };
+    try {
+        const raw = JSON.parse(fs.readFileSync(prefsPath, 'utf8'));
+        const flag = raw.review?.autoApproveOnAllGreen;
+        return {
+            auto_approve_on_all_green: flag === true,
+        };
+    }
+    catch {
+        return { ...REVIEW_PREFERENCE_DEFAULTS };
+    }
+}
+export function loadPromptPreferences(rootPath) {
+    const prefsPath = getSidecarPaths(rootPath).preferencesPath;
+    if (!fs.existsSync(prefsPath))
+        return { ...PROMPT_PREFERENCE_DEFAULTS };
+    try {
+        const raw = JSON.parse(fs.readFileSync(prefsPath, 'utf8'));
+        const rawTarget = typeof raw.prompt?.budgetTarget === 'number' ? raw.prompt.budgetTarget : NaN;
+        const rawMax = typeof raw.prompt?.budgetMax === 'number' ? raw.prompt.budgetMax : NaN;
+        const target = clampBudget(rawTarget, PROMPT_PREFERENCE_DEFAULTS.budget_target);
+        let max = clampBudget(rawMax, PROMPT_PREFERENCE_DEFAULTS.budget_max);
+        // Max must be >= target; otherwise the safety valve can never trigger correctly.
+        if (max < target)
+            max = target;
+        return { budget_target: target, budget_max: max };
+    }
+    catch {
+        return { ...PROMPT_PREFERENCE_DEFAULTS };
+    }
+}

package/dist/runners/runner-exec.js

@@ -0,0 +1,152 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadRunnerPreferences } from './config.js';
+export function buildPreparedCommand(input, runner, defaults) {
+    const prompt = readPromptFile(input.promptPath);
+    const override = loadOverride(input.projectRoot, runner);
+    if (override) {
+        const command = override.command ?? defaults.command;
+        const args = override.args
+            ? override.args.map((a) => substituteTokens(a, prompt, input.promptPath, input.agentRole))
+            : defaults.buildArgs(prompt, input.promptPath, input.agentRole);
+        return {
+            command,
+            args,
+            shellLine: defaults.shellLine(prompt, input.promptPath, input.agentRole),
+        };
+    }
+    return {
+        command: defaults.command,
+        args: defaults.buildArgs(prompt, input.promptPath, input.agentRole),
+        shellLine: defaults.shellLine(prompt, input.promptPath, input.agentRole),
+    };
+}
+function readPromptFile(promptPath) {
+    try {
+        return fs.readFileSync(promptPath, 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
+function loadOverride(projectRoot, runner) {
+    try {
+        const prefs = loadRunnerPreferences(projectRoot);
+        return prefs.runner_commands?.[runner];
+    }
+    catch {
+        return undefined;
+    }
+}
+function substituteTokens(value, prompt, promptPath, role) {
+    return value
+        .replace(/\{\{prompt\}\}/g, prompt)
+        .replace(/\{\{promptPath\}\}/g, promptPath)
+        .replace(/\{\{role\}\}/g, role);
+}
+export async function runSpawn(input, runner, runnerLabel) {
+    if (input.dryRun) {
+        return {
+            ok: true,
+            executed: false,
+            exitCode: 0,
+            summary: `Dry run: prepared ${runnerLabel} command only.`,
+            commandsRun: [input.prepared.shellLine],
+            validationResults: ['dry-run'],
+            blockers: [],
+            followUps: [],
+            durationMs: 0,
+        };
+    }
+    const started = Date.now();
+    const header = `# ${runner} run at ${new Date().toISOString()}\n# cmd: ${input.prepared.shellLine}\n# cwd: ${input.cwd}\n\n`;
+    let logStream = null;
+    try {
+        fs.mkdirSync(path.dirname(input.logPath), { recursive: true });
+        logStream = fs.createWriteStream(input.logPath, { flags: 'w' });
+        logStream.write(header);
+    }
+    catch {
+        logStream = null;
+    }
+    const env = { ...process.env, ...(input.env ?? {}) };
+    try {
+        const child = spawn(input.prepared.command, input.prepared.args, {
+            cwd: input.cwd,
+            env,
+            stdio: ['inherit', 'pipe', 'pipe'],
+        });
+        const streamTarget = input.streamOutput ?? 'stdout';
+        const stdoutSink = streamTarget === 'stdout'
+            ? process.stdout
+            : streamTarget === 'stderr'
+                ? process.stderr
+                : null;
+        const stderrSink = streamTarget === 'none' ? null : process.stderr;
+        child.stdout?.on('data', (chunk) => {
+            stdoutSink?.write(chunk);
+            logStream?.write(chunk);
+        });
+        child.stderr?.on('data', (chunk) => {
+            stderrSink?.write(chunk);
+            logStream?.write(chunk);
+        });
+        const exitCode = await new Promise((resolve, reject) => {
+            child.on('error', reject);
+            child.on('close', (code) => resolve(code === null ? -1 : code));
+        });
+        const durationMs = Date.now() - started;
+        logStream?.end();
+        const seconds = Math.round(durationMs / 1000);
+        if (exitCode === 0) {
+            return {
+                ok: true,
+                executed: true,
+                exitCode,
+                summary: `${runnerLabel} run completed (exit 0) in ${seconds}s.`,
+                commandsRun: [input.prepared.shellLine],
+                validationResults: [],
+                blockers: [],
+                followUps: [],
+                logPath: input.logPath,
+                durationMs,
+            };
+        }
+        return {
+            ok: false,
+            executed: true,
+            exitCode,
+            summary: `${runnerLabel} run failed (exit ${exitCode}) in ${seconds}s. See log: ${input.logPath}`,
+            commandsRun: [input.prepared.shellLine],
+            validationResults: [],
+            blockers: [`runner exited with code ${exitCode}`],
+            followUps: [],
+            logPath: input.logPath,
+            durationMs,
+        };
+    }
+    catch (err) {
+        const durationMs = Date.now() - started;
+        const message = err instanceof Error ? err.message : String(err);
+        try {
+            logStream?.write(`\n# spawn error: ${message}\n`);
+            logStream?.end();
+        }
+        catch {
+            /* ignore */
+        }
+        return {
+            ok: false,
+            executed: false,
+            exitCode: -1,
+            summary: `Failed to launch ${runnerLabel}: ${message}`,
+            commandsRun: [input.prepared.shellLine],
+            validationResults: [],
+            blockers: [message],
+            followUps: [`Install the ${runnerLabel} CLI or override the command in .sidecar/preferences.json`],
+            logPath: input.logPath,
+            durationMs,
+        };
+    }
+}