klyro 1.0.0 → 1.0.2

package/dist/agent/orchestrator.js

@@ -12,12 +12,19 @@
  * The compact result is a `ChildSummary` — a `ToolResult` the parent model
  * can act on — never the full child transcript.
  */
-import { run } from './runtime.js';
+import { run, resolveSystemPrompt } from './runtime.js';
 import { ScopedRegistry } from './scoped-registry.js';
 import { globalBus } from '../events/bus.js';
 import { TaskManager } from './task-manager.js';
 import { WorkerSpawner } from './worker-spawner.js';
 import { resolveCapabilities, DEFAULT_WRITE_TOOLS, DEFAULT_SPAWN_TOOLS, DEFAULT_DENIED_TOOLS, } from './capabilities.js';
+import { forkChild, workerEntryPath } from './child-worker.js';
+import { resolveAndFollowSymlinks } from '../policy/path-guard.js';
+import { ensureGitRepo, createWorktree, mergeWorktree, removeWorktree, deleteBranch, } from './worktree-manager.js';
+/** Concurrency budgets enforced in `spawnAgent` (CONCURRENCY_LIMIT on exceed). */
+export const MAX_CONCURRENT_TASKS = 4;
+export const MAX_TASKS_PER_PARENT = 8;
+export const MAX_TOTAL_TASKS_PER_SESSION = 32;
 /** Default agents a model can delegate to. */
 export const BUILTIN_AGENTS = [
     {
@@ -25,20 +32,20 @@ export const BUILTIN_AGENTS = [
         description: 'Read-only reconnaissance: map the repo, find symbols and tests.',
         readonly: true,
         canSpawn: false,
-        allowedTools: ['read_file', 'list_dir', 'glob', 'grep', 'search_files', 'repo_map', 'find_symbol', 'git_status', 'git_log', 'git_diff', 'recent_files', 'imports_of', 'importers_of'],
+        allowedTools: ['read_file', 'list_directory', 'glob', 'grep', 'search_files', 'repo_map', 'find_symbol', 'git_status', 'git_log', 'git_diff', 'recent_files', 'imports_of', 'importers_of'],
     },
     {
         id: 'implementer',
         description: 'Write-capable worker for concrete, well-scoped coding tasks.',
         canSpawn: false,
-        allowedTools: ['read_file', 'list_dir', 'glob', 'grep', 'search_files', 'write_file', 'edit_file', 'multi_edit', 'apply_patch', 'shell_exec', 'git_status', 'git_log', 'git_diff', 'run_verify', 'todo_write'],
+        allowedTools: ['read_file', 'list_directory', 'glob', 'grep', 'search_files', 'write_file', 'edit_file', 'multi_edit', 'apply_patch', 'shell_exec', 'git_status', 'git_log', 'git_diff', 'run_verify', 'todo_write'],
         maxSteps: 60,
     },
     {
         id: 'tester',
         description: 'Runs verification and tests, reports failures with diagnostics.',
         canSpawn: false,
-        allowedTools: ['read_file', 'list_dir', 'glob', 'grep', 'shell_exec', 'run_verify', 'git_status', 'git_log', 'git_diff'],
+        allowedTools: ['read_file', 'list_directory', 'glob', 'grep', 'shell_exec', 'run_verify', 'git_status', 'git_log', 'git_diff'],
         maxTimeMs: 120_000,
     },
     {
@@ -46,7 +53,21 @@ export const BUILTIN_AGENTS = [
         description: 'Read-only review of a diff or change set for bugs.',
         readonly: true,
         canSpawn: false,
-        allowedTools: ['read_file', 'list_dir', 'glob', 'grep', 'search_files', 'git_status', 'git_diff', 'git_log', 'imports_of', 'importers_of', 'find_symbol'],
+        allowedTools: ['read_file', 'list_directory', 'glob', 'grep', 'search_files', 'git_status', 'git_diff', 'git_log', 'imports_of', 'importers_of', 'find_symbol'],
+    },
+    {
+        id: 'debugger',
+        description: 'Read-only diagnosis: inspect failures, traces, and code paths without modifying files.',
+        readonly: true,
+        canSpawn: false,
+        allowedTools: ['read_file', 'list_directory', 'glob', 'grep', 'search_files', 'repo_map', 'find_symbol', 'imports_of', 'importers_of', 'git_status', 'git_log', 'git_diff', 'recent_files', 'run_verify'],
+    },
+    {
+        id: 'docs',
+        description: 'Read-only documentation lookup: find and summarise docs, READMEs, and code structure.',
+        readonly: true,
+        canSpawn: false,
+        allowedTools: ['read_file', 'list_directory', 'glob', 'grep', 'search_files', 'repo_map', 'recent_files'],
     },
 ];
 /** Map a runtime `RunResult.status` to a task status. */
@@ -66,16 +87,61 @@ function mapResultStatus(status) {
             return 'failed';
     }
 }
+/**
+ * Build a `subtask.progress` note for one finished tool call.
+ * Pure — unit-tested directly (see agent-tools.test.ts).
+ */
+export function progressNote(step, tool, isError) {
+    return `step ${step}: ${tool} ${isError ? 'ERR' : 'ok'}`;
+}
+/**
+ * Build the `RunOptions.onEvent` handler the orchestrator passes into each
+ * child's run options. Emits at most one `subtask.progress` per tool call:
+ * a `tool_result` is only mirrored when its `tool_call_end` was observed
+ * first, so duplicate/late results can never double-emit. (The note needs
+ * the ok/ERR outcome, which only `tool_result` carries — `tool_call_end`
+ * alone cannot build it — hence the end-gated result throttle.)
+ */
+export function createSubtaskProgressEmitter(opts) {
+    let step = 0;
+    const ended = new Set();
+    return (ev) => {
+        if (ev.kind === 'step_start') {
+            step = ev.step;
+        }
+        else if (ev.kind === 'tool_call_end') {
+            ended.add(ev.id);
+        }
+        else if (ev.kind === 'tool_result') {
+            if (!ended.has(ev.id))
+                return;
+            ended.delete(ev.id);
+            globalBus.emit({
+                type: 'subtask.progress',
+                ts: Date.now(),
+                sessionId: opts.sessionId,
+                taskId: opts.taskId,
+                note: progressNote(step, ev.name, ev.isError),
+            });
+        }
+    };
+}
 export class AgentOrchestrator {
     sessionId;
     deps;
     taskManager;
     workerSpawner;
+    isTui;
+    /** Per-task spawn metadata: capability drops + worktree placement. */
+    taskMeta = new Map();
+    /** Finished summaries not yet drained via `drainCompletions`. */
+    undrained = new Map();
     constructor(opts) {
         this.sessionId = opts.sessionId;
         this.deps = opts.deps;
         this.taskManager = opts.taskManager ?? new TaskManager({ sessionId: opts.sessionId });
         this.workerSpawner = opts.workerSpawner ?? new WorkerSpawner();
+        this.isTui = opts.isTui ?? false;
     }
     listAgents() {
         return [...BUILTIN_AGENTS];
@@ -98,6 +164,10 @@ export class AgentOrchestrator {
                 const s = this.taskManager.toSummary(r);
                 return r.error ? { ...s, error: { code: r.error.code, message: r.error.message } } : s;
             },
+            drainCompletions: () => this.drainCompletions(),
+            waitForTasks: (taskIds, timeoutMs) => this.waitForTasks(taskIds, timeoutMs),
+            cancelTask: (taskId) => this.cancelTask(taskId),
+            applyTask: (taskId) => this.applyTask(taskId),
         };
     }
     /** Compute a child's effective capabilities from the parent's own. */
@@ -111,13 +181,14 @@ export class AgentOrchestrator {
             spawnTools: DEFAULT_SPAWN_TOOLS,
             denied: DEFAULT_DENIED_TOOLS,
         };
-        const resolved = resolveCapabilities({ ...input, maxDepth: parent.maxDepth });
+        const resolved = resolveCapabilities({ ...input, maxDepth: parent.maxDepth, parentAllowedPaths: parent.allowedPaths });
         return resolved;
     }
     /**
-     * Spawn a child agent for a given capability context, await its run, and
-     * return a compact summary. Blocks until the child settles (P0 scope;
-     * async task_wait arrives in a later slice).
+     * Spawn a child agent asynchronously: start the child worker and return
+     * IMMEDIATELY with `{ status: 'running' }`. Completion/failure bus emits
+     * and `taskManager.finish` happen in the worker closure; the parent
+     * observes them via `task_wait` / `task_get` / `drainCompletions`.
      */
     async spawnAgent(input, parent) {
         const def = this.getAgent(input.agent);
@@ -139,10 +210,67 @@ export class AgentOrchestrator {
                 },
             };
         }
+        // Concurrency budgets — enforced before creating the task.
+        const all = this.taskManager.list();
+        const runningCount = all.filter((t) => t.status === 'running').length;
+        if (runningCount >= MAX_CONCURRENT_TASKS) {
+            return {
+                ok: false,
+                error: { code: 'CONCURRENCY_LIMIT', message: `maxConcurrentTasks (${MAX_CONCURRENT_TASKS}) reached` },
+            };
+        }
+        const perParentCount = all.filter((t) => t.parentTaskId === parent.taskId).length;
+        if (perParentCount >= MAX_TASKS_PER_PARENT) {
+            return {
+                ok: false,
+                error: { code: 'CONCURRENCY_LIMIT', message: `maxTasksPerParent (${MAX_TASKS_PER_PARENT}) reached` },
+            };
+        }
+        if (all.length >= MAX_TOTAL_TASKS_PER_SESSION) {
+            return {
+                ok: false,
+                error: { code: 'CONCURRENCY_LIMIT', message: `maxTotalTasksPerSession (${MAX_TOTAL_TASKS_PER_SESSION}) reached` },
+            };
+        }
+        // Spawn cwd containment (S6): an explicit cwd must stay inside the parent.
+        let baseCwd = parent.cwd;
+        if (input.cwd) {
+            try {
+                baseCwd = (await resolveAndFollowSymlinks(parent.cwd, input.cwd)).resolved;
+            }
+            catch (err) {
+                return {
+                    ok: false,
+                    error: {
+                        code: 'PATH_ESCAPE',
+                        message: err instanceof Error ? err.message : `cwd escapes parent: ${input.cwd}`,
+                    },
+                };
+            }
+        }
         const registryTools = new Set(this.deps.registry.list().map((t) => t.name));
         const resolved = this.resolveChild(def, parent, registryTools);
         const childModel = input.model ?? resolved.model ?? parent.model;
-        const childCwd = input.cwd ?? parent.cwd;
+        // Worktree isolation: write-capable children get their own worktree —
+        // including when the spawn carries an explicit cwd (the worktree is
+        // then rooted at the resolved explicit cwd, which containment above
+        // already pinned inside the parent). Readonly agents keep the resolved
+        // cwd with no worktree. A write-capable spawn outside a git repo is
+        // rejected outright.
+        const writeCapable = [...resolved.allowed].some((t) => DEFAULT_WRITE_TOOLS.has(t));
+        let childCwd = baseCwd;
+        let worktree;
+        let repoCwd;
+        if (!resolved.readonly && writeCapable) {
+            const isRepo = await ensureGitRepo(baseCwd).catch(() => false);
+            if (!isRepo) {
+                return {
+                    ok: false,
+                    error: { code: 'WRITES_REQUIRE_GIT', message: 'parallel write agents require a git repository for worktree isolation' },
+                };
+            }
+            repoCwd = baseCwd;
+        }
         const createOpts = {
             agentName: def.id,
             cwd: childCwd,
@@ -154,8 +282,42 @@ export class AgentOrchestrator {
             abortOnParent: undefined, // wired below via the parent signal
         };
         const record = this.taskManager.create(createOpts);
+        // Worktree creation needs the task id (branch `klyro/<taskId>`), so it
+        // happens after `create`. On failure the task is marked failed and the
+        // spawn returns the error.
+        if (repoCwd !== undefined) {
+            try {
+                worktree = await createWorktree({ repoCwd, taskId: record.id });
+                childCwd = worktree.worktreePath;
+                record.cwd = childCwd;
+            }
+            catch (err) {
+                this.taskManager.finish(record.id, 'failed', {
+                    error: { code: 'WORKTREE_FAILED', message: err instanceof Error ? err.message : String(err) },
+                });
+                const failed = this.taskManager.get(record.id);
+                this.stashSummary(failed, def, resolved.dropped);
+                this.taskMeta.set(record.id, { def, dropped: resolved.dropped });
+                return {
+                    ok: false,
+                    error: { code: 'WORKTREE_FAILED', message: err instanceof Error ? err.message : String(err) },
+                };
+            }
+        }
+        this.taskMeta.set(record.id, worktree ? { def, dropped: resolved.dropped, worktree, repoCwd } : { def, dropped: resolved.dropped });
         const childRegistry = new ScopedRegistry(this.deps.registry, resolved.allowed);
         const childDeps = { ...this.deps, registry: childRegistry };
+        const childRef = {
+            taskId: record.id,
+            ...(parent.taskId !== undefined ? { parentTaskId: parent.taskId } : {}),
+            sessionId: this.sessionId,
+            cwd: childCwd,
+            depth: childDepth,
+            maxDepth,
+            allowedTools: resolved.allowed,
+            ...(childModel !== undefined ? { model: childModel } : {}),
+            ...(resolved.allowedPaths !== undefined ? { allowedPaths: resolved.allowedPaths } : {}),
+        };
         const childOptions = {
             task: input.task,
             cwd: childCwd,
@@ -165,6 +327,15 @@ export class AgentOrchestrator {
             maxTimeMs: def.maxTimeMs ?? input.timeoutMs,
             signal: record.abortController.signal,
             nonInteractive: true,
+            // Mid-life progress: mirror each finished tool call as one
+            // `subtask.progress` bus event (see createSubtaskProgressEmitter).
+            // Process-isolated children don't run this closure — only the
+            // in-process path reports mid-life progress.
+            onEvent: createSubtaskProgressEmitter({ taskId: record.id, sessionId: this.sessionId }),
+            // Grandchildren: only children that canSpawn receive the bridge —
+            // otherwise tools see NO_ORCHESTRATOR as before.
+            ...(resolved.canSpawn ? { agentBridge: this.bridgeFor(childRef) } : {}),
+            ...(def.maxTokens !== undefined ? { maxTokens: def.maxTokens } : {}),
         };
         // Lifecycle events on the shared bus (mirror TaskManager transitions).
         globalBus.emit({
@@ -177,65 +348,261 @@ export class AgentOrchestrator {
             depth: childDepth,
             ...(typeof childModel === 'string' ? { model: childModel } : {}),
         });
-        const handle = this.workerSpawner.spawn(async () => {
-            let result;
+        // G2 — process isolation for headless sub-agents. In-process is the
+        // fallback (and mandatory for TUI children — see OrchestratorOpts.isTui),
+        // and opt-out via KLYRO_WORKER=0 for tests/dev.
+        const useProcessIsolation = !this.isTui && process.env.KLYRO_WORKER !== '0';
+        this.workerSpawner.spawn(async (signal) => {
+            // Both the in-process path and the forked child resolve to the same
+            // minimal outcome shape the settle tail needs.
+            let childOutcome;
             try {
-                result = await run(childOptions, childDeps);
+                if (useProcessIsolation) {
+                    const sysPrompt = resolveSystemPrompt(this.deps.systemPrompt, { cwd: childCwd });
+                    // Splice the volatile telemetry suffix into the stable prefix so the
+                    // child's provider sees one system string. Telemetry is best-effort
+                    // inside the child (it re-emits); the goal here is parity, not
+                    // perfect replay.
+                    const systemPrompt = sysPrompt.suffix ? `${sysPrompt.system}\n${sysPrompt.suffix}` : sysPrompt.system;
+                    const payload = {
+                        cwd: childCwd,
+                        task: input.task,
+                        // A concrete provider model must reach the child — 'inherit' only
+                        // exists to defer resolution inside the parent's run().
+                        model: (childModel ?? parent.model),
+                        systemPrompt,
+                        agentId: def.id,
+                        maxSteps: def.maxSteps,
+                        maxCost: def.maxCost,
+                        maxTimeMs: def.maxTimeMs ?? input.timeoutMs,
+                        ...(def.maxTokens !== undefined ? { maxTokens: def.maxTokens } : {}),
+                    };
+                    const cr = await forkChild(workerEntryPath(), payload, { signal });
+                    childOutcome = cr; // ChildResult is the minimal settle shape
+                }
+                else {
+                    const r = await run(childOptions, childDeps);
+                    childOutcome = { status: r.status, steps: r.steps, toolCalls: r.toolCalls, finalText: r.finalText };
+                }
             }
             catch (err) {
-                this.taskManager.finish(record.id, 'failed', {
-                    error: { code: 'CHILD_CRASH', message: err instanceof Error ? err.message : String(err) },
-                });
+                const isCrash = err instanceof Error && err.name === 'ChildCrashError';
+                const crashErr = isCrash ? err : undefined;
+                this.settleChild(record.id, 'failed', {
+                    error: {
+                        code: 'CHILD_CRASH',
+                        message: isCrash
+                            ? `child process isolated failure (${crashErr?.likelyCause ?? 'exit'}): ${crashErr?.message ?? ''}`.trim()
+                            : err instanceof Error ? err.message : String(err),
+                    },
+                }, { steps: 0, toolCalls: 0 });
                 return;
             }
-            const status = mapResultStatus(result.status);
-            if (status === 'cancelled') {
-                this.taskManager.cancel(record.id, 'parent aborted');
-            }
-            else {
-                this.taskManager.finish(record.id, status, {
-                    summary: [`status: ${status}`, `steps: ${result.steps}`, `toolCalls: ${result.toolCalls}`],
-                    error: status === 'failed'
-                        ? { code: mapFailureCode(result.status), message: result.finalText?.slice(0, 300) ?? 'child failed' }
-                        : undefined,
-                });
-            }
-            const final = this.taskManager.get(record.id);
-            const durationMs = final.finishedAt ? final.finishedAt - final.startedAt : 0;
-            if (status === 'succeeded') {
-                globalBus.emit({
-                    type: 'subtask.completed',
-                    ts: Date.now(),
-                    sessionId: this.sessionId,
-                    taskId: record.id,
-                    status: 'succeeded',
-                    durationMs,
-                    steps: result?.steps ?? 0,
-                    toolCalls: result?.toolCalls ?? 0,
-                });
-            }
-            else {
-                globalBus.emit({
-                    type: 'subtask.failed',
-                    ts: Date.now(),
-                    sessionId: this.sessionId,
-                    taskId: record.id,
-                    status: status,
-                    durationMs,
-                    error: final.error ? { code: final.error.code, message: final.error.message } : undefined,
-                });
-            }
+            const status = mapResultStatus(childOutcome.status);
+            this.settleChild(record.id, status, {
+                summary: [`status: ${status}`, `steps: ${childOutcome.steps}`, `toolCalls: ${childOutcome.toolCalls}`],
+                error: status === 'failed'
+                    ? { code: mapFailureCode(childOutcome.status), message: childOutcome.finalText?.slice(0, 300) ?? 'child failed' }
+                    : undefined,
+            }, { steps: childOutcome.steps, toolCalls: childOutcome.toolCalls });
         }, { label: `agent:${def.id}` });
-        await handle.done.catch(() => undefined);
-        const finalRecord = this.taskManager.get(record.id);
-        if (!finalRecord) {
+        // Async contract: return immediately with the running summary. The final
+        // text is omitted while running; observe via task_wait / drainCompletions.
+        return {
+            ok: true,
+            value: { taskId: record.id, agentName: def.id, status: 'running', durationMs: 0, changedFiles: [] },
+        };
+    }
+    /**
+     * Settle a child in the worker closure: finish the task (idempotent —
+     * a TaskManager timeout/cancel that fired first wins), emit the terminal
+     * bus event, stash the summary for `drainCompletions`, and best-effort
+     * remove the worktree unless the child succeeded (merge happens later in
+     * `task_apply`).
+     */
+    settleChild(taskId, status, patch, counts) {
+        const existing = this.taskManager.get(taskId);
+        if (!existing)
+            return;
+        let finalStatus = status;
+        if (existing.status === 'queued' || existing.status === 'running') {
+            this.taskManager.finish(taskId, status, patch);
+        }
+        else {
+            // Already terminal (timeout/cancel raced the run) — preserve it.
+            finalStatus = existing.status;
+        }
+        const final = this.taskManager.get(taskId);
+        this.stashSummary(final);
+        const durationMs = final.finishedAt ? final.finishedAt - final.startedAt : 0;
+        const error = final.error ? { code: final.error.code, message: final.error.message } : undefined;
+        const steps = counts?.steps ?? 0;
+        const toolCalls = counts?.toolCalls ?? 0;
+        if (finalStatus === 'succeeded') {
+            globalBus.emit({
+                type: 'subtask.completed',
+                ts: Date.now(),
+                sessionId: this.sessionId,
+                taskId,
+                status: 'succeeded',
+                durationMs,
+                steps,
+                toolCalls,
+            });
+        }
+        else if (finalStatus === 'cancelled') {
+            globalBus.emit({
+                type: 'subtask.cancelled',
+                ts: Date.now(),
+                sessionId: this.sessionId,
+                taskId,
+                status: 'cancelled',
+                durationMs,
+                ...(error ? { error } : {}),
+            });
+        }
+        else if (finalStatus === 'timed_out') {
+            globalBus.emit({
+                type: 'subtask.timed_out',
+                ts: Date.now(),
+                sessionId: this.sessionId,
+                taskId,
+                status: 'timed_out',
+                durationMs,
+                ...(error ? { error } : {}),
+            });
+        }
+        else {
+            globalBus.emit({
+                type: 'subtask.failed',
+                ts: Date.now(),
+                sessionId: this.sessionId,
+                taskId,
+                status: finalStatus,
+                durationMs,
+                ...(error ? { error } : {}),
+            });
+        }
+        // Non-success terminal states never merge — drop the worktree.
+        const meta = this.taskMeta.get(taskId);
+        if (meta?.worktree && meta.repoCwd && finalStatus !== 'succeeded') {
+            const { worktree, repoCwd } = meta;
+            void removeWorktree({ repoCwd, worktreePath: worktree.worktreePath, force: true }).catch(() => undefined);
+        }
+    }
+    /** Build and stash the finished summary for `drainCompletions`. */
+    stashSummary(r, def, dropped) {
+        const meta = this.taskMeta.get(r.id);
+        const d = def ?? meta?.def;
+        if (!d)
+            return;
+        this.undrained.set(r.id, this.toChildSummary(r, d, dropped ?? meta?.dropped ?? []));
+    }
+    /** Completed-then-undrained child summaries; each drained exactly once. */
+    drainCompletions() {
+        const out = [...this.undrained.values()];
+        this.undrained.clear();
+        return out;
+    }
+    /**
+     * Await each task's `done` up to `timeoutMs` per task. Unsettled entries
+     * come back with status `'running'` and a running summary — the underlying
+     * task is NOT cancelled.
+     */
+    async waitForTasks(taskIds, timeoutMs) {
+        const tasks = await Promise.all(taskIds.map(async (taskId) => {
+            const rec = this.taskManager.get(taskId);
+            if (!rec) {
+                return { taskId, status: 'failed', error: { code: 'NOT_FOUND', message: `Unknown task: ${taskId}` } };
+            }
+            const meta = this.taskMeta.get(taskId);
+            const settled = await this.awaitDone(rec, timeoutMs);
+            const summary = meta ? this.toChildSummary(settled, meta.def, meta.dropped) : undefined;
+            const entry = { taskId, status: settled.status };
+            if (summary)
+                entry.summary = summary;
+            if (settled.error)
+                entry.error = { code: settled.error.code, message: settled.error.message };
+            return entry;
+        }));
+        return { tasks };
+    }
+    async awaitDone(rec, timeoutMs) {
+        if (timeoutMs === undefined)
+            return rec.done;
+        let timer;
+        try {
+            return await Promise.race([
+                rec.done,
+                new Promise((resolve) => {
+                    timer = setTimeout(() => resolve(this.taskManager.get(rec.id)), timeoutMs);
+                }),
+            ]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+    /** Signal abort for a live task via `taskManager.cancel` (in-process workers; no subprocesses yet). Idempotent on terminal tasks. */
+    cancelTask(taskId) {
+        const rec = this.taskManager.get(taskId);
+        if (!rec) {
+            return { ok: false, error: { code: 'NOT_FOUND', message: `Unknown task: ${taskId}` } };
+        }
+        this.taskManager.cancel(taskId, 'stopped via task_stop');
+        const final = this.taskManager.get(taskId);
+        return { ok: true, value: { taskId, status: final.status } };
+    }
+    /**
+     * Apply a succeeded task: merge its worktree branch into the parent tree
+     * (or acknowledge a shared-cwd task whose edits already landed) and emit
+     * `subtask.merged`. Non-succeeded tasks error with NOT_READY; merge
+     * conflicts error with MERGE_CONFLICT (merge already aborted, branch kept).
+     */
+    async applyTask(taskId) {
+        const rec = this.taskManager.get(taskId);
+        if (!rec) {
+            return { ok: false, error: { code: 'NOT_FOUND', message: `Unknown task: ${taskId}` } };
+        }
+        if (rec.status !== 'succeeded') {
             return {
                 ok: false,
-                error: { code: 'INTERNAL', message: `task ${record.id} missing after child run` },
+                error: { code: 'NOT_READY', message: `task ${taskId} is ${rec.status}, not succeeded` },
             };
         }
-        return { ok: true, value: this.toChildSummary(finalRecord, def, resolved.dropped) };
+        const meta = this.taskMeta.get(taskId);
+        const summary = meta ? this.toChildSummary(rec, meta.def, meta.dropped) : this.toChildSummary(rec, this.getAgent(rec.agentName) ?? { id: rec.agentName, description: '' }, []);
+        // merged=true only when a real worktree branch merge ran; shared-cwd
+        // tasks (edits already in the parent tree) are an acknowledgement.
+        let didMerge = false;
+        if (meta?.worktree && meta.repoCwd) {
+            const merged = await mergeWorktree({ repoCwd: meta.repoCwd, branch: meta.worktree.branch });
+            if (!merged.merged) {
+                return {
+                    ok: false,
+                    error: {
+                        code: 'MERGE_CONFLICT',
+                        message: `merge of ${meta.worktree.branch} conflicted`,
+                        details: { conflictFiles: merged.conflictFiles },
+                    },
+                };
+            }
+            await removeWorktree({ repoCwd: meta.repoCwd, worktreePath: meta.worktree.worktreePath }).catch(() => undefined);
+            await deleteBranch({ repoCwd: meta.repoCwd, branch: meta.worktree.branch });
+            didMerge = true;
+        }
+        globalBus.emit({
+            type: 'subtask.merged',
+            ts: Date.now(),
+            sessionId: this.sessionId,
+            taskId,
+            changedFiles: summary.changedFiles,
+            merged: didMerge,
+        });
+        return { ok: true, value: summary };
     }
+    /** Compact summary for a task record (also used by task_wait). */
     toChildSummary(r, def, dropped) {
         const s = this.taskManager.toSummary(r);
         return {

package/dist/agent/provider-adapter.d.ts

@@ -28,6 +28,8 @@ export type StreamEvent = {
     usage?: {
         input: number;
         output: number;
+        cacheRead?: number;
+        cacheWrite?: number;
     };
 } | {
     kind: 'tool_call_start';
@@ -56,6 +58,12 @@ export interface ToolDefinition {
 export interface CallRequest {
     model: string;
     system?: string;
+    /**
+     * Volatile prompt suffix (Level-7 runtime telemetry). Adapters keep it
+     * out of the cacheable prefix: Anthropic sends the array system form
+     * (breakpoint on the stable part), OpenAI appends it with a separator.
+     */
+    systemSuffix?: string;
     messages: Message[];
     tools: ToolDefinition[];
     maxTokens?: number;

package/dist/agent/provider-adapter.js

@@ -108,8 +108,12 @@ function zodFieldSchema(s) {
  */
 export function buildChatCompletionsBody(req) {
     const messages = [];
+    // OpenAI has no system array form: the volatile suffix rides along as a
+    // plain concatenation (behavior-preserving when absent).
     if (req.system)
-        messages.push({ role: 'system', content: req.system });
+        messages.push({ role: 'system', content: req.systemSuffix ? `${req.system}\n\n${req.systemSuffix}` : req.system });
+    else if (req.systemSuffix)
+        messages.push({ role: 'system', content: req.systemSuffix });
     for (const m of req.messages) {
         if (m.role === 'assistant') {
             const text = m.content.filter((b) => b.kind === 'text').map((b) => b.text).join('');
@@ -202,11 +206,16 @@ async function* streamChatCompletions(url, opts, req, fetchImpl) {
         req.signal?.removeEventListener('abort', onAbort);
         const rawErr = await res.text().catch(() => '');
         const errText = redact(rawErr).slice(0, 500);
-        const retryable = res.status >= 500 || res.status === 429;
+        // Context overflow is a client-side budget problem, not a transient
+        // failure: surface a dedicated code (never retryable here — the runtime
+        // owns the compress-and-retry recovery) so callers can distinguish it
+        // from 429/5xx backoff cases.
+        const isOverflow = res.status === 413 || /request_too_large|too_large|prompt_too_long|context_length|maximum context length/i.test(rawErr);
+        const retryable = !isOverflow && (res.status >= 500 || res.status === 429);
         const retryAfterMs = retryable ? parseRetryAfterMs(res.headers?.get('retry-after')) : undefined;
         yield {
             kind: 'error',
-            code: `HTTP_${res.status}`,
+            code: isOverflow ? 'REQUEST_TOO_LARGE' : `HTTP_${res.status}`,
             message: `provider returned ${res.status}: ${errText}`,
             retryable,
             status: String(res.status),

package/dist/agent/retry.d.ts

@@ -15,7 +15,7 @@
  *
  *   delay = min(maxMs, baseMs * 2^attempt) ± jitter
  *
- * The default policy matches the L6 plan: 3 attempts, 500ms base, 8s cap.
+ * The default policy matches the L6 plan: 5 attempts, 500ms base, 8s cap.
  */
 import type { ProviderAdapter } from './provider-adapter.js';
 export interface RetryOptions {