@pat-lewczuk/cezar 0.1.4 → 0.1.5

package/dist/workflows/run.js

@@ -2,20 +2,65 @@ import { randomUUID } from 'node:crypto';
 import { spawn } from 'node:child_process';
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { onUsage, registerRunProcess, unregisterRunProcess } from '../core/process-usage.js';
 import { createRunner } from '../core/runner-factory.js';
 import { HANDOFF_INSTRUCTIONS, appendHandoffHeartbeat, handoffPath, seedHandoffFile, } from '../handoff.js';
 import { todosPath } from '../todos.js';
 import { discoverSkills } from '../skills.js';
 import { materializeSkillDir } from '../skills-remote.js';
 import { loadConfig } from '../config.js';
-import { autosaveCommit, createWorktree, resolveBaseRef, worktreeDiff } from '../git-worktree.js';
+import { autosaveCommit, createWorktree, resolveBaseRef, worktreeDiff, worktreeShortstat } from '../git-worktree.js';
 import { getRepoInfo } from '../server/git.js';
+import { loadWorkflows } from './load.js';
+import { deriveTitleSummary } from '../runs/title-summary.js';
+import { UiEventSink } from '../runs/ui-event-sink.js';
 import { DEFAULT_ALLOWED_TOOLS, stepKind } from './types.js';
 const CHECK_OUTPUT_CAP = 20_000;
 /** An interactive session that hears nothing from the user closes itself. */
 export const IDLE_TIMEOUT_MS = 15 * 60_000;
+/**
+ * Task-completion marker from the agent contract (HANDOFF_INSTRUCTIONS): a
+ * turn whose text ends with `CEZ:DONE` means "goal achieved, nothing to ask" —
+ * the session is closed right away instead of parking at `waiting` (#347).
+ * Detection runs on the accumulated turn text so delta-streaming backends
+ * (codex, opencode) can't split the marker across text events.
+ */
+const DONE_MARKER_RE = /CEZ:DONE\s*$/;
+/** Strip a trailing marker from one text event so transcripts stay free of
+ *  protocol noise. Delta backends may split the marker across events — then
+ *  it stays visible; detection above is unaffected. */
+function stripDoneMarker(text) {
+    return text.replace(/\s*CEZ:DONE\s*$/, '');
+}
 /** Periodic "cezar autosave" commit in the task worktree (spec 006). */
 export const AUTOSAVE_INTERVAL_MS = 90_000;
+/** Safety cap on autonomous auto-continues per run — stops a stuck agent from nudging forever. */
+const MAX_AUTO_CONTINUES = 40;
+const AUTONOMOUS_NUDGE = 'Continue working autonomously until the task is fully complete. Do not ask me for confirmation or clarification — make reasonable assumptions and proceed. When everything is done, end the session with your done signal.';
+/**
+ * The effective "extra" system prompt for a run (spec §protocol v2, R2 2.3):
+ * the per-run override (`POST /api/runs` `systemPrompt`) REPLACES the
+ * `config.json` default — they are the same knob at two scopes, so the more
+ * specific one wins outright; they never concatenate. Whichever wins is
+ * ADDITIVE to the skill body and the handoff contract, which always ride
+ * along (see `composeSystemPrompt`). Blank strings count as unset.
+ */
+export function resolveExtraSystemPrompt(override, configDefault) {
+    return override?.trim() || configDefault?.trim() || undefined;
+}
+/**
+ * Joins the parts of one agent step's system prompt in fixed order — skill
+ * body (most task-specific), then the run's extra prompt (user guidance, can
+ * amend the skill), then the handoff contract (always last, never optional in
+ * practice). Blank parts drop out; survivors join with the same `\n\n---\n\n`
+ * divider the skill+handoff composition has always used.
+ */
+export function composeSystemPrompt(...parts) {
+    return parts
+        .map((p) => p?.trim())
+        .filter((p) => Boolean(p))
+        .join('\n\n---\n\n');
+}
 /** Variant letters + the fixed diversification hints (spec 010). A runs the
  *  task verbatim; B/C get one constant sentence each — zero configuration. */
 export const VARIANT_LETTERS = ['A', 'B', 'C'];
@@ -43,14 +88,66 @@ export class RunManager {
     // registering in `active`, so parallel-slot counting is never racy.
     queue = [];
     starting = new Set();
+    // Runs parked at `waiting` (open session, ball in the user's court). They
+    // don't consume a `maxParallel` slot (#347) — an idle claude process costs
+    // memory but no tokens, queued work progressing matters more, and the idle
+    // timeout already bounds how long a session can sit open. Invariant:
+    // `waiting ⊆ active` — always cleared together via dropActive().
+    waiting = new Set();
     pendingJobs = new Map();
     pumping = false;
     /** `.ai/cezar` — where the per-task handoff files and todos.json live. */
     dataDir;
+    /** Runs currently being paused by the memory guard — dedupes the ~2 s samples so one breach
+     *  triggers one pause, not a burst. Cleared in dropActive when the run leaves the registry. */
+    memoryPausing = new Set();
     constructor(store, repoRoot) {
         this.store = store;
         this.repoRoot = repoRoot;
         this.dataDir = join(repoRoot, '.ai/cezar');
+        // Memory guard (#memory-guard): the shared process-tree sampler already ticks ~every 2 s for
+        // the runs table; piggyback on it to enforce the per-task memory ceiling.
+        onUsage((snapshot) => void this.enforceMemoryLimit(snapshot));
+    }
+    /**
+     * Pause any active run whose whole process tree exceeds `config.memoryLimitMb`, freeing its
+     * slot so the queue advances (#memory-guard). "Pause" closes the session — freeing the tree's
+     * memory — and leaves the run resumable via Continue; a loud warning explains why. No-op when
+     * no limit is set or the sampler has no data (e.g. `ps`/PowerShell unavailable).
+     */
+    async enforceMemoryLimit(snapshot) {
+        const runIds = Object.keys(snapshot);
+        if (runIds.length === 0)
+            return;
+        const limitMb = (await loadConfig(this.repoRoot)).memoryLimitMb;
+        if (!limitMb || limitMb <= 0)
+            return;
+        const limitBytes = limitMb * 1024 * 1024;
+        for (const runId of runIds) {
+            const usage = snapshot[runId];
+            if (!usage || usage.rssBytes <= limitBytes)
+                continue;
+            if (this.memoryPausing.has(runId))
+                continue;
+            const state = this.active.get(runId);
+            if (!state?.session?.open || state.cancelled)
+                continue;
+            this.memoryPausing.add(runId);
+            const usedMb = Math.round(usage.rssBytes / (1024 * 1024));
+            this.store.appendEvent(runId, {
+                type: 'note',
+                message: `⚠ memory limit exceeded — this task's process tree is using ${usedMb} MiB (limit ${limitMb} MiB). Pausing it and letting the next queued task run; resume it with Continue.`,
+            });
+            this.store.appendEvent(runId, {
+                type: 'lifecycle',
+                message: `paused — memory limit exceeded (${usedMb} MiB > ${limitMb} MiB)`,
+            });
+            // Closing the session frees the tree and lets the normal exit path settle the run and
+            // pump the queue. Suppress autonomous auto-continue so the pause actually holds.
+            state.autonomous = false;
+            this.clearIdleTimer(state);
+            state.session.end();
+        }
     }
     /** Env the spawned claude gets so the agent can find its handoff file and
      *  the global inbox (spec 007). */
@@ -72,6 +169,9 @@ export class RunManager {
             variant: group?.variant,
             steps: workflow.steps.map((s) => ({ id: s.id, name: s.name ?? s.id, kind: stepKind(s) })),
         });
+        // Persist the full definition so a queued run survives a restart (#367) —
+        // ad-hoc "(planned)" chains exist nowhere else to re-resolve from.
+        this.store.updateRun(run.id, { workflowDef: workflow });
         this.pendingJobs.set(run.id, { workflow, input });
         this.queue.push(run.id);
         void this.pump();
@@ -104,7 +204,11 @@ export class RunManager {
         try {
             const repo = await getRepoInfo(this.repoRoot);
             const maxParallel = repo ? (await loadConfig(this.repoRoot)).maxParallel : 1;
-            while (this.queue.length > 0 && this.active.size + this.starting.size < maxParallel) {
+            // `waiting` runs don't hold a slot (#347). A message into a waiting run
+            // resumes it even when that momentarily exceeds maxParallel — resumed
+            // conversations must never be blocked by the queue.
+            const busy = () => this.active.size + this.starting.size - this.waiting.size;
+            while (this.queue.length > 0 && busy() < maxParallel) {
                 const runId = this.queue.shift();
                 if (!runId)
                     break;
@@ -126,7 +230,7 @@ export class RunManager {
                         this.clearAutosaveTimer(state);
                     }
                     this.starting.delete(runId);
-                    this.active.delete(runId);
+                    this.dropActive(runId);
                     void this.pump();
                 });
             }
@@ -135,6 +239,98 @@ export class RunManager {
             this.pumping = false;
         }
     }
+    /**
+     * Startup recovery (#367) — re-adopt runs that were live when the previous
+     * cezar process exited (requires the store opened with `keepLive`):
+     *  - `queued`  → back into the queue (FIFO by createdAt), from the persisted
+     *    workflowDef (or the catalog by name for older records);
+     *  - `waiting` → the turn was over and the ball was in the user's court —
+     *    settle exactly like a closed session (review/done, Continue still works);
+     *  - `running` → mark interrupted, then immediately resume the last agent
+     *    session via the Continue path, pointing the agent at its handoff file.
+     * Call once, before the server starts taking requests.
+     */
+    async recover() {
+        const live = this.store
+            .listRuns()
+            .filter((r) => ['queued', 'waiting', 'running'].includes(r.status))
+            .sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+        for (const run of live) {
+            if (run.status === 'queued') {
+                const workflow = await this.reviveWorkflow(run);
+                if (workflow) {
+                    this.pendingJobs.set(run.id, {
+                        workflow,
+                        input: { task: run.task, model: run.model, runner: run.runner },
+                    });
+                    this.queue.push(run.id);
+                    this.store.appendEvent(run.id, { type: 'lifecycle', message: 'cezar restarted — task re-queued' });
+                }
+                else {
+                    this.store.updateRun(run.id, {
+                        status: 'failed',
+                        error: 'interrupted — workflow definition not recoverable after a restart',
+                        finishedAt: new Date().toISOString(),
+                    });
+                    this.store.appendEvent(run.id, {
+                        type: 'lifecycle',
+                        message: 'cezar restarted — workflow definition not recoverable, task failed',
+                    });
+                }
+                continue;
+            }
+            if (run.status === 'waiting') {
+                for (const step of run.steps) {
+                    if (step.status === 'waiting' || step.status === 'running') {
+                        this.store.updateStep(run.id, step.id, { status: 'done', finishedAt: new Date().toISOString() });
+                    }
+                }
+                this.store.appendEvent(run.id, {
+                    type: 'lifecycle',
+                    message: 'cezar restarted — the open session was settled',
+                });
+                await this.settleSuccess(run.id);
+                continue;
+            }
+            // `running`: the process died mid-turn. Mark it interrupted (the state
+            // continueRun expects), then pick the work back up from the last session.
+            const finishedAt = new Date().toISOString();
+            for (const step of run.steps) {
+                if (step.status === 'running' || step.status === 'waiting') {
+                    this.store.updateStep(run.id, step.id, { status: 'failed', finishedAt });
+                }
+            }
+            this.store.updateRun(run.id, {
+                status: 'failed',
+                error: 'interrupted — cezar process exited during the run',
+                finishedAt,
+                currentStepId: undefined,
+            });
+            const resumed = this.continueRun(run.id, 'The cezar process restarted while you were working on this task. Read the handoff file (CEZ_HANDOFF_FILE) to recover context, then continue the task from where you left off.');
+            this.store.appendEvent(run.id, {
+                type: 'lifecycle',
+                message: resumed.ok
+                    ? 'cezar restarted — resuming the interrupted task from its last session'
+                    : `cezar restarted — could not resume the interrupted task (${resumed.error ?? 'unknown'})`,
+            });
+        }
+        void this.pump();
+    }
+    /** The persisted definition when it looks sane, else the catalog by name. */
+    async reviveWorkflow(run) {
+        const def = run.workflowDef;
+        if (def && Array.isArray(def.steps)) {
+            return def;
+        }
+        const { workflows } = await loadWorkflows(this.repoRoot);
+        return workflows.find((w) => w.name === run.workflow) ?? null;
+    }
+    /** Remove a run from the live registries — keeps `waiting ⊆ active`. */
+    dropActive(runId) {
+        this.waiting.delete(runId);
+        this.active.delete(runId);
+        this.memoryPausing.delete(runId);
+    }
     cancel(runId) {
         // Still waiting in the queue: just drop it there.
         const queuedAt = this.queue.indexOf(runId);
@@ -169,16 +365,24 @@ export class RunManager {
             .filter((b) => b.type === 'text')
             .map((b) => b.text)
             .join('\n');
-        const imageCount = content.filter((b) => b.type === 'image').length;
+        // Persist the attached images so the thread can render them (not just count them) — the same
+        // on-disk store + `/images/` route the agent's own screenshots use.
+        const images = content
+            .filter((b) => b.type === 'image')
+            .map((b) => this.persistImage(runId, state, b.source.media_type, b.source.data))
+            .filter((saved) => saved !== null)
+            .map((saved) => saved.url);
         this.store.appendEvent(runId, {
             type: 'user-message',
             stepId: state.currentStepId,
             text,
-            imageCount,
+            imageCount: content.filter((b) => b.type === 'image').length,
+            images,
         });
         const delivered = state.session.sendMessage(content);
         if (delivered) {
             this.clearIdleTimer(state);
+            this.waiting.delete(runId); // resumed — the run counts against slots again
             this.store.updateRun(runId, { status: 'running' });
             if (state.currentStepId) {
                 this.store.updateStep(runId, state.currentStepId, { status: 'running' });
@@ -236,7 +440,7 @@ export class RunManager {
                 error: `continue crashed: ${message}`,
                 finishedAt: new Date().toISOString(),
             });
-            this.active.delete(runId);
+            this.dropActive(runId);
             void this.pump();
         });
         return { ok: true };
@@ -268,6 +472,8 @@ export class RunManager {
         this.store.appendEvent(runId, { type: 'step-start', stepId, name: 'Continue', kind: 'agent', iteration: 1 });
         this.store.appendEvent(runId, { type: 'user-message', stepId, text: prompt, imageCount: 0 });
         let stepCost = 0;
+        let turnText = '';
+        const sink = this.makeUiSink(runId, stepId);
         const onEvent = (event) => {
             if (event.type === 'image') {
                 const saved = this.persistImage(runId, state, event.mediaType, event.data);
@@ -275,6 +481,13 @@ export class RunManager {
                     this.store.appendEvent(runId, { type: 'image', stepId, ...saved });
                 return;
             }
+            if (event.type === 'text') {
+                turnText += event.text;
+                const text = stripDoneMarker(event.text);
+                if (text)
+                    this.store.appendEvent(runId, { type: 'text', text, stepId });
+                return;
+            }
             this.store.appendEvent(runId, { ...event, stepId });
             if (event.type === 'session') {
                 this.store.updateStep(runId, stepId, { sessionId: event.sessionId });
@@ -287,18 +500,55 @@ export class RunManager {
                 this.store.updateStep(runId, stepId, { costUsd: stepCost });
             }
             if (event.type === 'turn-end') {
-                const waiting = !state.cancelled && state.session?.open;
-                if (waiting) {
-                    this.store.updateRun(runId, { status: 'waiting' });
-                    this.store.updateStep(runId, stepId, { status: 'waiting' });
-                    this.armIdleTimer(runId, state);
+                // Belt-and-braces: v2 `turn.completed` already flushed the delta
+                // coalescers; the v1 turn boundary flushes again (idempotent) so no
+                // buffered delta can outlive its turn.
+                sink.flushAll();
+                void this.recordTurnEnd(runId, turnText); // titleSummary + diffStat (#389)
+                const sessionOpen = !state.cancelled && state.session?.open;
+                const done = sessionOpen && DONE_MARKER_RE.test(turnText.trimEnd());
+                turnText = '';
+                if (done) {
+                    // Goal achieved (agent contract, #347) — same as in runAgentStep.
+                    this.store.appendEvent(runId, { type: 'lifecycle', message: 'goal achieved — session closed' });
+                    appendHandoffHeartbeat(this.dataDir, runId, 'turn complete — goal achieved, session closed');
+                    state.session?.end();
+                    return;
                 }
-                appendHandoffHeartbeat(this.dataDir, runId, `turn complete — status=${waiting ? 'waiting' : 'running'}`);
+                if (sessionOpen) {
+                    // Autonomous (#autonomous): never hand the ball back to the user. Nudge the agent to
+                    // keep going (bounded by MAX_AUTO_CONTINUES) instead of parking at `waiting`.
+                    const autoContinued = state.autonomous &&
+                        (state.autoContinues ?? 0) < MAX_AUTO_CONTINUES &&
+                        !state.cancelled &&
+                        (() => {
+                            const sent = state.session?.sendMessage([{ type: 'text', text: AUTONOMOUS_NUDGE }]);
+                            if (!sent)
+                                return false;
+                            state.autoContinues = (state.autoContinues ?? 0) + 1;
+                            this.store.appendEvent(runId, {
+                                type: 'note',
+                                message: `autonomous — continuing without pausing (${state.autoContinues}/${MAX_AUTO_CONTINUES})`,
+                            });
+                            return true;
+                        })();
+                    if (!autoContinued) {
+                        this.store.updateRun(runId, { status: 'waiting' });
+                        this.store.updateStep(runId, stepId, { status: 'waiting' });
+                        this.waiting.add(runId);
+                        this.armIdleTimer(runId, state);
+                        void this.pump();
+                    }
+                }
+                appendHandoffHeartbeat(this.dataDir, runId, `turn complete — status=${sessionOpen ? 'waiting' : 'running'}`);
             }
         };
         const runner = createRunner(record?.runner ?? 'claude');
         const session = runner.startSession({
-            systemPrompt: HANDOFF_INSTRUCTIONS,
+            // The Continue step is a fresh agent session on the same run — the
+            // run's extra system prompt (already resolved at execute time and
+            // echoed on the record) rides along with the handoff contract.
+            systemPrompt: composeSystemPrompt(record?.systemPrompt, HANDOFF_INSTRUCTIONS),
             userPrompt: prompt,
             cwd: state.cwd,
             allowedTools: DEFAULT_ALLOWED_TOOLS,
@@ -307,13 +557,16 @@ export class RunManager {
             sessionId,
             resume: true,
             timeoutMs: 0,
-        }, onEvent);
+        }, onEvent, { onUiEvent: (event) => sink.handle(event) });
         state.session = session;
         state.currentStepId = stepId;
         state.interrupt = () => session.interrupt();
+        if (session.pid !== undefined)
+            registerRunProcess(runId, session.pid);
         const finishedAt = () => new Date().toISOString();
         try {
             await session.result;
+            sink.sessionEnded(state.cancelled ? 'cancelled' : 'end_turn');
             if (state.cancelled) {
                 this.store.updateStep(runId, stepId, { status: 'cancelled', finishedAt: finishedAt() });
                 this.store.updateRun(runId, { status: 'cancelled', finishedAt: finishedAt(), currentStepId: undefined });
@@ -329,6 +582,7 @@ export class RunManager {
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
+            sink.sessionEnded('error', message);
             this.store.updateStep(runId, stepId, { status: 'failed', error: message, finishedAt: finishedAt() });
             appendHandoffHeartbeat(this.dataDir, runId, `step "${stepId}" complete — status=failed`);
             this.store.updateRun(runId, {
@@ -340,39 +594,56 @@ export class RunManager {
             this.store.appendEvent(runId, { type: 'lifecycle', message: `continue failed — ${message}` });
         }
         finally {
+            this.recordUsagePeaks(runId);
             this.clearIdleTimer(state);
             this.clearAutosaveTimer(state);
             if (state.cwd !== this.repoRoot)
                 await autosaveCommit(state.cwd);
-            this.active.delete(runId);
+            this.dropActive(runId);
             void this.pump();
         }
     }
     // ---- execution -----------------------------------------------------------
     async execute(runId, workflow, input) {
-        const state = { cancelled: false, interrupt: () => undefined, cwd: this.repoRoot };
+        const state = {
+            cancelled: false,
+            interrupt: () => undefined,
+            cwd: this.repoRoot,
+            autonomous: input.autonomous === true,
+            autoContinues: 0,
+        };
         this.active.set(runId, state);
         this.starting.delete(runId);
         const emit = (event) => this.store.appendEvent(runId, event);
         // Resolve the agent backend for this run: the task choice (GUI) wins over
         // the config default. Per-step `runner` can still override it below.
-        const taskBackend = input.runner ?? (await loadConfig(this.repoRoot)).defaultRunner;
+        const config = await loadConfig(this.repoRoot);
+        const taskBackend = input.runner ?? config.defaultRunner;
+        // Extra system prompt (R2 2.3): POST override > config default; echoed on
+        // the record so the UI/API can show what the run actually used.
+        const extraSystemPrompt = resolveExtraSystemPrompt(input.systemPrompt, config.systemPrompt);
         this.store.updateRun(runId, {
             status: 'running',
             startedAt: new Date().toISOString(),
             runner: taskBackend,
+            systemPrompt: extraSystemPrompt,
         });
         emit({ type: 'lifecycle', message: `run started — workflow "${workflow.name}" (runner: ${taskBackend})` });
         // Worktree per task (spec 006): the agent works on its own branch in
         // `.ai/cezar/worktrees/<id>`, never in the user's working tree. Not a git
         // repo, or worktree creation failed → degrade to running in place.
         const repo = await getRepoInfo(this.repoRoot);
-        if (repo) {
+        if (repo && input.worktree === false) {
+            // Composer opt-out: run in the repo working tree, no branch/worktree
+            // (read-only skills — review, summarize — that never need isolation).
+            emit({ type: 'note', message: 'worktree off — running in the repo working tree' });
+        }
+        else if (repo) {
             // Fork from the configured base branch (config.json `baseBranch`, e.g.
             // `develop`) — also the target of the eventual draft PR. Unresolvable
             // (typo, not fetched) → note + the currently checked-out branch.
             let base = repo.branch;
-            const configured = (await loadConfig(this.repoRoot)).baseBranch;
+            const configured = config.baseBranch;
             if (configured) {
                 const resolved = await resolveBaseRef(this.repoRoot, configured);
                 if (resolved) {
@@ -413,6 +684,17 @@ export class RunManager {
         const retriesUsed = new Map();
         let checkFailure = null;
         let runError = null;
+        // Persist the task's attached images so the thread's initial bubble can render them
+        // (#image-display); they still ride the first agent step's opening message below.
+        if (input.images?.length) {
+            const urls = input.images
+                .filter((b) => b.type === 'image')
+                .map((b) => this.persistImage(runId, state, b.source.media_type, b.source.data))
+                .filter((saved) => saved !== null)
+                .map((saved) => saved.url);
+            if (urls.length)
+                this.store.updateRun(runId, { taskImages: urls });
+        }
         // Task screenshots go with the FIRST agent step's opening message only —
         // later steps and retry loops run in fresh sessions without them.
         let startImages = input.images;
@@ -437,7 +719,7 @@ export class RunManager {
                 // The last agent step of the workflow is interactive: after its turn
                 // the session stays open for follow-ups until finish/idle/cancel.
                 const interactive = i === lastAgentIdx && i === workflow.steps.length - 1;
-                const failure = await this.runAgentStep(runId, state, step, input, skills, checkFailure, interactive, emit, startImages, taskBackend);
+                const failure = await this.runAgentStep(runId, state, step, input, skills, checkFailure, interactive, emit, startImages, taskBackend, extraSystemPrompt);
                 startImages = undefined;
                 checkFailure = null;
                 if (state.cancelled)
@@ -505,11 +787,11 @@ export class RunManager {
             await this.settleSuccess(runId);
         }
         this.clearIdleTimer(state);
-        this.active.delete(runId);
+        this.dropActive(runId);
         void this.pump();
     }
     /** Returns an error message, or null on success. */
-    async runAgentStep(runId, state, step, input, skills, checkFailure, interactive, emit, images, taskBackend) {
+    async runAgentStep(runId, state, step, input, skills, checkFailure, interactive, emit, images, taskBackend, extraSystemPrompt) {
         let systemPrompt;
         if (step.skill) {
             const skill = skills.find((s) => s.name === step.skill);
@@ -554,6 +836,8 @@ export class RunManager {
         const stepRecord = this.store.getRun(runId)?.steps.find((s) => s.id === step.id);
         const startTokens = stepRecord?.tokensUsed ?? 0;
         let stepCost = stepRecord?.costUsd ?? 0;
+        let turnText = '';
+        const sink = this.makeUiSink(runId, step.id);
         const onEvent = (event) => {
             if (event.type === 'image') {
                 const saved = this.persistImage(runId, state, event.mediaType, event.data);
@@ -561,6 +845,13 @@ export class RunManager {
                     emit({ type: 'image', stepId: step.id, ...saved });
                 return;
             }
+            if (event.type === 'text') {
+                turnText += event.text;
+                const text = stripDoneMarker(event.text);
+                if (text)
+                    emit({ type: 'text', text, stepId: step.id });
+                return;
+            }
             emit({ ...event, stepId: step.id });
             if (event.type === 'session') {
                 // Codex/OpenCode mint their own session id — persist it so resume works.
@@ -574,12 +865,29 @@ export class RunManager {
                 this.store.updateStep(runId, step.id, { costUsd: stepCost });
             }
             if (event.type === 'turn-end') {
-                const waiting = interactive && !state.cancelled && state.session?.open;
+                // v2 `turn.completed` already flushed the coalescers; the v1 turn
+                // boundary flushes again (idempotent) as a backstop.
+                sink.flushAll();
+                void this.recordTurnEnd(runId, turnText); // titleSummary + diffStat (#389)
+                const sessionOpen = !state.cancelled && state.session?.open;
+                const done = interactive && sessionOpen && DONE_MARKER_RE.test(turnText.trimEnd());
+                turnText = '';
+                if (done) {
+                    // Goal achieved (agent contract, #347): close the session instead
+                    // of parking at `waiting` — the run completes and frees its slot.
+                    emit({ type: 'lifecycle', message: 'goal achieved — session closed' });
+                    appendHandoffHeartbeat(this.dataDir, runId, 'turn complete — goal achieved, session closed');
+                    state.session?.end();
+                    return;
+                }
+                const waiting = interactive && sessionOpen;
                 if (waiting) {
                     // Turn over, session open: the ball is in the user's court.
                     this.store.updateRun(runId, { status: 'waiting' });
                     this.store.updateStep(runId, step.id, { status: 'waiting' });
+                    this.waiting.add(runId);
                     this.armIdleTimer(runId, state);
+                    void this.pump(); // the freed slot can start a queued run right away
                 }
                 // Cez's own heartbeat — the handoff stays current even when the
                 // agent forgets to write (spec 007).
@@ -590,10 +898,9 @@ export class RunManager {
         let session;
         try {
             session = runner.startSession({
-                // The handoff/todos contract rides along on every agent step.
-                systemPrompt: systemPrompt
-                    ? `${systemPrompt}\n\n---\n\n${HANDOFF_INSTRUCTIONS}`
-                    : HANDOFF_INSTRUCTIONS,
+                // Skill body, then the run's extra prompt (POST override or config
+                // default), then the handoff/todos contract — every agent step.
+                systemPrompt: composeSystemPrompt(systemPrompt, extraSystemPrompt, HANDOFF_INSTRUCTIONS),
                 userPrompt,
                 images,
                 cwd: state.cwd,
@@ -606,7 +913,7 @@ export class RunManager {
                 sessionId,
                 // Interactive sessions have no wall clock — the idle timer rules.
                 timeoutMs: interactive ? 0 : undefined,
-            }, onEvent, { autoEndAfterFirstTurn: !interactive });
+            }, onEvent, { autoEndAfterFirstTurn: !interactive, onUiEvent: (event) => sink.handle(event) });
         }
         catch (err) {
             return err instanceof Error ? err.message : String(err);
@@ -614,21 +921,97 @@ export class RunManager {
         state.session = session;
         state.currentStepId = step.id;
         state.interrupt = () => session.interrupt();
+        if (session.pid !== undefined)
+            registerRunProcess(runId, session.pid);
         try {
             const result = await session.result;
+            // v2 counterpart of v1's `done` (spec: the mappers leave session-close
+            // events to the RunManager — only it knows how the session settled).
+            sink.sessionEnded(state.cancelled ? 'cancelled' : 'end_turn');
             this.store.updateStep(runId, step.id, { tokensUsed: startTokens + result.tokensUsed });
             return null;
         }
         catch (err) {
-            return err instanceof Error ? err.message : String(err);
+            const message = err instanceof Error ? err.message : String(err);
+            sink.sessionEnded('error', message); // alongside v1's fatal `error`
+            return message;
         }
         finally {
+            this.recordUsagePeaks(runId);
             this.clearIdleTimer(state);
             state.session = undefined;
             state.currentStepId = undefined;
             state.interrupt = () => undefined;
         }
     }
+    /**
+     * Protocol-v2 sink for one agent session (R2 step 2.1): the runner's
+     * `onUiEvent` stream flows through here. Persisted snapshots ride the same
+     * NDJSON file as v1 (the store stamps `seq`/`ts`, `appendEvent` fans them
+     * out live too); coalesced `item.delta` flushes go out live-only via
+     * `emitEphemeral` — raw deltas never hit disk (spec §performance
+     * guardrails). One sink per session: cumulative usage dedup and the
+     * item-shape cache are session-scoped, like the mapper state feeding them.
+     */
+    makeUiSink(runId, stepId) {
+        return new UiEventSink({
+            persist: (event) => this.store.appendEvent(runId, { ...event, stepId }),
+            emitLive: (event) => this.store.emitEphemeral(runId, { ...event, stepId }),
+        });
+    }
+    /**
+     * Turn-end bookkeeping (#389), shared by `runAgentStep` and
+     * `runContinuation` — called (fire-and-forget) from every `turn-end` event:
+     *
+     *  - `titleSummary`: derived from the turn's text, set ONCE — only while the
+     *    record has none. A user's inline edit also lands in `titleSummary`
+     *    (see `PATCH /api/runs/:id`), so an edit is never overwritten either.
+     *  - `diffStat`: cheap `git diff --shortstat` vs the base, refreshed every
+     *    turn. Async and best-effort — a git failure becomes at most a `note`
+     *    event, NEVER a run failure. `updateRun` fans the record out over SSE,
+     *    so the list views pick both up with no extra wiring.
+     *
+     * Not `private` so the integration tests can drive a turn-end directly —
+     * a real agent session is the only other way to reach this path.
+     */
+    async recordTurnEnd(runId, turnText) {
+        try {
+            const run = this.store.getRun(runId);
+            if (!run)
+                return;
+            if (run.titleSummary === undefined) {
+                const summary = deriveTitleSummary(turnText, run.task);
+                if (summary)
+                    this.store.updateRun(runId, { titleSummary: summary });
+            }
+            if (!run.worktreePath || !existsSync(run.worktreePath))
+                return;
+            const stat = await worktreeShortstat(run.worktreePath, run.baseBranch ?? 'HEAD');
+            if (stat)
+                this.store.updateRun(runId, { diffStat: stat });
+            else
+                this.store.appendEvent(runId, { type: 'note', message: 'diff stat unavailable — git diff --shortstat failed in the worktree' });
+        }
+        catch {
+            // Bookkeeping only — nothing here may disturb the run.
+        }
+    }
+    /**
+     * End-of-session telemetry (#348): stop sampling the run's process tree and
+     * fold the session's peaks into the run record. `max` with existing values —
+     * a run can hold several sessions (multiple agent steps, Continue) and the
+     * record keeps the highest water mark across all of them.
+     */
+    recordUsagePeaks(runId) {
+        const peaks = unregisterRunProcess(runId);
+        if (!peaks)
+            return;
+        const run = this.store.getRun(runId);
+        this.store.updateRun(runId, {
+            peakRssBytes: Math.max(run?.peakRssBytes ?? 0, peaks.peakRssBytes),
+            peakProcCount: Math.max(run?.peakProcCount ?? 0, peaks.peakProcCount),
+        });
+    }
     /**
      * Diff-first review gate (spec 009), shared by `execute` and
      * `runContinuation`: a *successful* run whose worktree holds changes rests