@pat-lewczuk/cezar 0.1.0 → 0.1.1

package/dist/workflows/run.js

@@ -1,47 +1,149 @@
 import { randomUUID } from 'node:crypto';
 import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { ClaudeCliRunner } from '../core/claude-cli-runner.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, worktreeDiff } from '../git-worktree.js';
+import { getRepoInfo } from '../server/git.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;
+/** Periodic "cezar autosave" commit in the task worktree (spec 006). */
+export const AUTOSAVE_INTERVAL_MS = 90_000;
+/** 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'];
+const VARIANT_HINTS = {
+    A: undefined,
+    B: 'Approach hint: prefer the minimal, surgical change.',
+    C: 'Approach hint: prefer a thorough, structural approach.',
+};
 /**
  * The mini workflow engine: executes a `WorkflowDef` against a repo, one step
  * at a time, persisting every event to the RunStore (which the SSE endpoints
  * relay live to the GUI). No GitHub choreography — agent steps and shell
  * checks with bounded retry loops, plus live sessions: the last agent step
  * stays open for follow-ups (`waiting`) until "finish", idle timeout, or
- * cancel.
+ * cancel. Runs queue behind `maxParallel` slots and each run executes in its
+ * own git worktree on a `cez/<id8>` branch (spec 006), autosave-committed
+ * every 90 s — the user's working tree is never touched.
  */
 export class RunManager {
     store;
     repoRoot;
     active = new Map();
+    // Queue + `starting` set (spec 006, janitor's pump() pattern): `starting`
+    // covers the window between shifting a run off the queue and the run
+    // registering in `active`, so parallel-slot counting is never racy.
+    queue = [];
+    starting = new Set();
+    pendingJobs = new Map();
+    pumping = false;
+    /** `.ai/cezar` — where the per-task handoff files and todos.json live. */
+    dataDir;
     constructor(store, repoRoot) {
         this.store = store;
         this.repoRoot = repoRoot;
+        this.dataDir = join(repoRoot, '.ai/cezar');
     }
-    startRun(workflow, input) {
+    /** Env the spawned claude gets so the agent can find its handoff file and
+     *  the global inbox (spec 007). */
+    agentEnv(runId) {
+        return {
+            CEZ_HANDOFF_FILE: handoffPath(this.dataDir, runId),
+            CEZ_TODOS_FILE: todosPath(this.dataDir),
+            CEZ_TASK_ID: runId,
+        };
+    }
+    startRun(workflow, input, group) {
         const run = this.store.createRun({
-            title: makeTitle(input.task),
+            title: makeTitle(input.task) + (group ? ` (${group.variant})` : ''),
             workflow: workflow.name,
             task: input.task,
             model: input.model,
+            groupId: group?.groupId,
+            variant: group?.variant,
             steps: workflow.steps.map((s) => ({ id: s.id, name: s.name ?? s.id, kind: stepKind(s) })),
         });
-        void this.execute(run.id, workflow, input).catch((err) => {
-            const message = err instanceof Error ? err.message : String(err);
-            this.store.updateRun(run.id, {
-                status: 'failed',
-                error: `engine crashed: ${message}`,
-                finishedAt: new Date().toISOString(),
-            });
-            this.active.delete(run.id);
-        });
+        this.pendingJobs.set(run.id, { workflow, input });
+        this.queue.push(run.id);
+        void this.pump();
         return run;
     }
+    /**
+     * Parallel variants (spec 010): N runs of the same workflow on the same
+     * task, sharing a groupId. Variant A gets the task verbatim; B and C get a
+     * fixed one-line approach hint appended to the *task input* (not the step
+     * template), so diversification works with any workflow. The normal queue
+     * applies — with maxParallel=2 a third variant simply waits.
+     */
+    startVariants(workflow, input, count) {
+        const groupId = randomUUID();
+        return VARIANT_LETTERS.slice(0, Math.min(Math.max(count, 1), VARIANT_LETTERS.length)).map((variant) => {
+            const hint = VARIANT_HINTS[variant];
+            const task = hint ? `${input.task}\n\n${hint}` : input.task;
+            return this.startRun(workflow, { ...input, task }, { groupId, variant });
+        });
+    }
+    /**
+     * Start queued runs while parallel slots are free. `maxParallel` comes from
+     * `.ai/cezar/config.json` (default 2); a non-git directory degrades to 1
+     * sequential run in the repo root (spec 006 degradation rule).
+     */
+    async pump() {
+        if (this.pumping)
+            return;
+        this.pumping = true;
+        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) {
+                const runId = this.queue.shift();
+                if (!runId)
+                    break;
+                const job = this.pendingJobs.get(runId);
+                this.pendingJobs.delete(runId);
+                if (!job)
+                    continue;
+                this.starting.add(runId);
+                void this.execute(runId, job.workflow, job.input).catch((err) => {
+                    const message = err instanceof Error ? err.message : String(err);
+                    this.store.updateRun(runId, {
+                        status: 'failed',
+                        error: `engine crashed: ${message}`,
+                        finishedAt: new Date().toISOString(),
+                    });
+                    const state = this.active.get(runId);
+                    if (state) {
+                        this.clearIdleTimer(state);
+                        this.clearAutosaveTimer(state);
+                    }
+                    this.starting.delete(runId);
+                    this.active.delete(runId);
+                    void this.pump();
+                });
+            }
+        }
+        finally {
+            this.pumping = false;
+        }
+    }
     cancel(runId) {
+        // Still waiting in the queue: just drop it there.
+        const queuedAt = this.queue.indexOf(runId);
+        if (queuedAt >= 0) {
+            this.queue.splice(queuedAt, 1);
+            this.pendingJobs.delete(runId);
+            this.store.updateRun(runId, { status: 'cancelled', finishedAt: new Date().toISOString() });
+            this.store.appendEvent(runId, { type: 'lifecycle', message: 'cancelled while queued' });
+            return true;
+        }
         const state = this.active.get(runId);
         if (!state)
             return false;
@@ -51,7 +153,7 @@ export class RunManager {
         return true;
     }
     isActive(runId) {
-        return this.active.has(runId);
+        return this.active.has(runId) || this.starting.has(runId) || this.queue.includes(runId);
     }
     /**
      * Deliver a user message into the run's live claude session (mid-turn or
@@ -83,15 +185,26 @@ export class RunManager {
         }
         return delivered;
     }
-    /** Close the open session gracefully — the run then completes as `done`. */
+    /** Close the open session gracefully — the run then completes as `done`
+     *  (or rests at `review` when the worktree holds changes, spec 009).
+     *  On a run already resting at `review` (no session — the engine loop is
+     *  over), "Finish" is the third review exit: accept the changes without a
+     *  PR and flip straight to `done`. */
     finish(runId) {
         const state = this.active.get(runId);
-        if (!state?.session?.open)
-            return false;
-        this.clearIdleTimer(state);
-        this.store.appendEvent(runId, { type: 'lifecycle', message: 'session closed by user' });
-        state.session.end();
-        return true;
+        if (state?.session?.open) {
+            this.clearIdleTimer(state);
+            this.store.appendEvent(runId, { type: 'lifecycle', message: 'session closed by user' });
+            state.session.end();
+            return true;
+        }
+        const run = this.store.getRun(runId);
+        if (run?.status === 'review' && !this.isActive(runId)) {
+            this.store.updateRun(runId, { status: 'done' });
+            this.store.appendEvent(runId, { type: 'lifecycle', message: 'review accepted — finished without a PR' });
+            return true;
+        }
+        return false;
     }
     /**
      * "Continue" (spec 003): reopen a finished run's claude session in-process
@@ -105,7 +218,8 @@ export class RunManager {
         const run = this.store.getRun(runId);
         if (!run)
             return { ok: false, error: 'not found' };
-        if (!['done', 'failed', 'cancelled'].includes(run.status)) {
+        // `review` is continuable too — that's the "Send back" path (spec 009).
+        if (!['done', 'failed', 'cancelled', 'review'].includes(run.status)) {
             return { ok: false, error: `cannot continue a ${run.status} run` };
         }
         const sessionId = [...run.steps].reverse().find((s) => s.sessionId)?.sessionId;
@@ -122,12 +236,22 @@ export class RunManager {
                 finishedAt: new Date().toISOString(),
             });
             this.active.delete(runId);
+            void this.pump();
         });
         return { ok: true };
     }
     async runContinuation(runId, stepId, sessionId, prompt) {
-        const state = { cancelled: false, interrupt: () => undefined };
+        // Continuation runs in the task's worktree when it still exists (spec
+        // 006) — the resumed session sees exactly what the original run left.
+        const record = this.store.getRun(runId);
+        const cwd = record?.worktreePath && existsSync(record.worktreePath)
+            ? record.worktreePath
+            : this.repoRoot;
+        const state = { cancelled: false, interrupt: () => undefined, cwd };
         this.active.set(runId, state);
+        this.armAutosave(state);
+        if (record)
+            seedHandoffFile(this.dataDir, record); // idempotent — normally already there
         this.store.updateRun(runId, {
             status: 'running',
             error: undefined,
@@ -144,6 +268,12 @@ export class RunManager {
         this.store.appendEvent(runId, { type: 'user-message', stepId, text: prompt, imageCount: 0 });
         let stepCost = 0;
         const onEvent = (event) => {
+            if (event.type === 'image') {
+                const saved = this.persistImage(runId, state, event.mediaType, event.data);
+                if (saved)
+                    this.store.appendEvent(runId, { type: 'image', stepId, ...saved });
+                return;
+            }
             this.store.appendEvent(runId, { ...event, stepId });
             if (event.type === 'token-usage') {
                 this.store.updateStep(runId, stepId, { tokensUsed: event.tokensUsed });
@@ -152,17 +282,24 @@ export class RunManager {
                 stepCost += event.usd;
                 this.store.updateStep(runId, stepId, { costUsd: stepCost });
             }
-            if (event.type === 'turn-end' && !state.cancelled && state.session?.open) {
-                this.store.updateRun(runId, { status: 'waiting' });
-                this.store.updateStep(runId, stepId, { status: 'waiting' });
-                this.armIdleTimer(runId, state);
+            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);
+                }
+                appendHandoffHeartbeat(this.dataDir, runId, `turn complete — status=${waiting ? 'waiting' : 'running'}`);
             }
         };
         const runner = new ClaudeCliRunner();
         const session = runner.startSession({
+            systemPrompt: HANDOFF_INSTRUCTIONS,
             userPrompt: prompt,
-            cwd: this.repoRoot,
+            cwd: state.cwd,
             allowedTools: DEFAULT_ALLOWED_TOOLS,
+            additionalDirectories: [join(this.dataDir, 'runs')],
+            env: this.agentEnv(runId),
             sessionId,
             resume: true,
             timeoutMs: 0,
@@ -177,17 +314,19 @@ export class RunManager {
                 this.store.updateStep(runId, stepId, { status: 'cancelled', finishedAt: finishedAt() });
                 this.store.updateRun(runId, { status: 'cancelled', finishedAt: finishedAt(), currentStepId: undefined });
                 this.store.appendEvent(runId, { type: 'lifecycle', message: 'run cancelled' });
+                appendHandoffHeartbeat(this.dataDir, runId, `step "${stepId}" complete — status=cancelled`);
             }
             else {
                 this.store.updateStep(runId, stepId, { status: 'done', finishedAt: finishedAt() });
-                this.store.updateRun(runId, { status: 'done', finishedAt: finishedAt(), currentStepId: undefined });
                 this.store.appendEvent(runId, { type: 'step-end', stepId, status: 'done' });
-                this.store.appendEvent(runId, { type: 'lifecycle', message: 'run finished' });
+                await this.settleSuccess(runId);
+                appendHandoffHeartbeat(this.dataDir, runId, `step "${stepId}" complete — status=done`);
             }
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
             this.store.updateStep(runId, stepId, { status: 'failed', error: message, finishedAt: finishedAt() });
+            appendHandoffHeartbeat(this.dataDir, runId, `step "${stepId}" complete — status=failed`);
             this.store.updateRun(runId, {
                 status: 'failed',
                 error: `continue failed: ${message}`,
@@ -198,20 +337,57 @@ export class RunManager {
         }
         finally {
             this.clearIdleTimer(state);
+            this.clearAutosaveTimer(state);
+            if (state.cwd !== this.repoRoot)
+                await autosaveCommit(state.cwd);
             this.active.delete(runId);
+            void this.pump();
         }
     }
     // ---- execution -----------------------------------------------------------
     async execute(runId, workflow, input) {
-        const state = { cancelled: false, interrupt: () => undefined };
+        const state = { cancelled: false, interrupt: () => undefined, cwd: this.repoRoot };
         this.active.set(runId, state);
+        this.starting.delete(runId);
         const emit = (event) => this.store.appendEvent(runId, event);
         this.store.updateRun(runId, { status: 'running', startedAt: new Date().toISOString() });
         emit({ type: 'lifecycle', message: `run started — workflow "${workflow.name}"` });
+        // 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) {
+            try {
+                const wt = await createWorktree(this.repoRoot, runId, repo.branch);
+                state.cwd = wt.path;
+                this.store.updateRun(runId, {
+                    worktreePath: wt.path,
+                    branch: wt.branch,
+                    baseBranch: wt.baseBranch,
+                });
+                emit({ type: 'note', message: `worktree ready — branch ${wt.branch} (base ${wt.baseBranch})` });
+                this.armAutosave(state);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                emit({ type: 'note', message: `worktree creation failed (${message}) — running in the repo working tree` });
+            }
+        }
+        else {
+            emit({ type: 'note', message: 'not a git repository — running in place, one task at a time' });
+        }
+        // Handoff journal (spec 007) — seeded after the worktree exists so the
+        // header can name the branch. Idempotent: an existing file stays as-is.
+        const seeded = this.store.getRun(runId);
+        if (seeded)
+            seedHandoffFile(this.dataDir, seeded);
         const skills = await discoverSkills(this.repoRoot);
         const retriesUsed = new Map();
         let checkFailure = null;
         let runError = null;
+        // 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;
         const lastAgentIdx = findLastAgentStepIndex(workflow);
         let i = 0;
         while (i < workflow.steps.length) {
@@ -233,7 +409,8 @@ 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);
+                const failure = await this.runAgentStep(runId, state, step, input, skills, checkFailure, interactive, emit, startImages);
+                startImages = undefined;
                 checkFailure = null;
                 if (state.cancelled)
                     break;
@@ -277,6 +454,10 @@ export class RunManager {
             runError = `check "${step.id}" failed${step.onFail ? ` after ${used + 1} attempts` : ''}`;
             break;
         }
+        // Final autosave: the branch always ends holding the finished state.
+        this.clearAutosaveTimer(state);
+        if (state.cwd !== this.repoRoot)
+            await autosaveCommit(state.cwd);
         const finishedAt = new Date().toISOString();
         if (state.cancelled) {
             const run = this.store.getRun(runId);
@@ -293,25 +474,39 @@ export class RunManager {
             emit({ type: 'lifecycle', message: `run failed — ${runError}` });
         }
         else {
-            this.store.updateRun(runId, { status: 'done', finishedAt, currentStepId: undefined });
-            emit({ type: 'lifecycle', message: 'run finished' });
+            await this.settleSuccess(runId);
         }
         this.clearIdleTimer(state);
         this.active.delete(runId);
+        void this.pump();
     }
     /** Returns an error message, or null on success. */
-    async runAgentStep(runId, state, step, input, skills, checkFailure, interactive, emit) {
+    async runAgentStep(runId, state, step, input, skills, checkFailure, interactive, emit, images) {
         let systemPrompt;
         if (step.skill) {
             const skill = skills.find((s) => s.name === step.skill);
             if (skill) {
                 systemPrompt = skill.body.trim();
+                // Directory team skills (SKILL.md + references/) get materialized
+                // into <cwd>/.claude/skills/<name>/ — the run's worktree when there
+                // is one — so claude sees the companion files on disk; the shared
+                // info/exclude keeps them out of git (and out of autosave commits).
+                if (skill.source === 'team' && skill.team?.dir) {
+                    const seeded = await materializeSkillDir(state.cwd, skill).catch(() => false);
+                    if (seeded) {
+                        emit({
+                            type: 'note',
+                            stepId: step.id,
+                            message: `team skill "${skill.name}" materialized to .claude/skills/${skill.name}/`,
+                        });
+                    }
+                }
             }
             else {
                 emit({
                     type: 'note',
                     stepId: step.id,
-                    message: `skill "${step.skill}" not found in .ai/cezar/skills or .ai/skills — running with the plain prompt`,
+                    message: `skill "${step.skill}" not found in .ai/cezar/skills, .ai/skills or the team skills repo — running with the plain prompt`,
                 });
             }
         }
@@ -319,12 +514,25 @@ export class RunManager {
         if (checkFailure) {
             userPrompt += `\n\nA verification command failed after the previous attempt. Fix the cause. Failing output:\n\n${checkFailure}`;
         }
+        if (images?.length) {
+            emit({
+                type: 'note',
+                stepId: step.id,
+                message: `${images.length} screenshot${images.length > 1 ? 's' : ''} attached to the task`,
+            });
+        }
         const sessionId = randomUUID();
         this.store.updateStep(runId, step.id, { sessionId });
         const stepRecord = this.store.getRun(runId)?.steps.find((s) => s.id === step.id);
         const startTokens = stepRecord?.tokensUsed ?? 0;
         let stepCost = stepRecord?.costUsd ?? 0;
         const onEvent = (event) => {
+            if (event.type === 'image') {
+                const saved = this.persistImage(runId, state, event.mediaType, event.data);
+                if (saved)
+                    emit({ type: 'image', stepId: step.id, ...saved });
+                return;
+            }
             emit({ ...event, stepId: step.id });
             if (event.type === 'token-usage') {
                 this.store.updateStep(runId, step.id, { tokensUsed: startTokens + event.tokensUsed });
@@ -333,22 +541,35 @@ export class RunManager {
                 stepCost += event.usd;
                 this.store.updateStep(runId, step.id, { costUsd: stepCost });
             }
-            if (event.type === 'turn-end' && interactive && !state.cancelled && state.session?.open) {
-                // 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.armIdleTimer(runId, state);
+            if (event.type === 'turn-end') {
+                const waiting = interactive && !state.cancelled && state.session?.open;
+                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.armIdleTimer(runId, state);
+                }
+                // Cez's own heartbeat — the handoff stays current even when the
+                // agent forgets to write (spec 007).
+                appendHandoffHeartbeat(this.dataDir, runId, `turn complete — status=${waiting ? 'waiting' : 'running'}`);
             }
         };
         const runner = new ClaudeCliRunner();
         let session;
         try {
             session = runner.startSession({
-                systemPrompt,
+                // The handoff/todos contract rides along on every agent step.
+                systemPrompt: systemPrompt
+                    ? `${systemPrompt}\n\n---\n\n${HANDOFF_INSTRUCTIONS}`
+                    : HANDOFF_INSTRUCTIONS,
                 userPrompt,
-                cwd: this.repoRoot,
+                images,
+                cwd: state.cwd,
                 allowedTools: step.allowedTools ?? DEFAULT_ALLOWED_TOOLS,
                 bashAllowlist: step.bashAllowlist,
+                // The handoff file lives outside the worktree — grant access.
+                additionalDirectories: [join(this.dataDir, 'runs')],
+                env: this.agentEnv(runId),
                 model: step.model ?? input.model,
                 sessionId,
                 // Interactive sessions have no wall clock — the idle timer rules.
@@ -376,6 +597,57 @@ export class RunManager {
             state.interrupt = () => undefined;
         }
     }
+    /**
+     * Diff-first review gate (spec 009), shared by `execute` and
+     * `runContinuation`: a *successful* run whose worktree holds changes rests
+     * at `review` instead of `done` — the user inspects the diff first, then
+     * sends feedback back, opens a draft PR, or just finishes. Failed/cancelled
+     * runs never enter review; no worktree or an empty diff means plain `done`.
+     */
+    async settleSuccess(runId) {
+        const run = this.store.getRun(runId);
+        let review = false;
+        if (run?.worktreePath && existsSync(run.worktreePath)) {
+            const diff = await worktreeDiff(run.worktreePath, run.baseBranch ?? 'HEAD');
+            review = diff.trim().length > 0 && !diff.startsWith('(diff failed');
+        }
+        this.store.updateRun(runId, {
+            status: review ? 'review' : 'done',
+            finishedAt: new Date().toISOString(),
+            currentStepId: undefined,
+        });
+        this.store.appendEvent(runId, {
+            type: 'lifecycle',
+            message: review
+                ? 'changes ready for review — send feedback, open a draft PR, or finish'
+                : 'run finished',
+        });
+    }
+    /**
+     * Agent screenshot (an image block inside a tool result): the base64 data
+     * never enters the NDJSON event log — it lands as a file under
+     * `.ai/cezar/runs/<id>-images/` and the transcript event carries only the
+     * name + serving URL. Best effort: on failure the screenshot is dropped,
+     * the transcript still shows the tool result's `[screenshot]` placeholder.
+     */
+    persistImage(runId, state, mediaType, data) {
+        try {
+            const ext = /png/.test(mediaType) ? 'png'
+                : /jpe?g/.test(mediaType) ? 'jpg'
+                    : /webp/.test(mediaType) ? 'webp'
+                        : /gif/.test(mediaType) ? 'gif'
+                            : 'img';
+            state.imageSeq = (state.imageSeq ?? 0) + 1;
+            const name = `screenshot-${state.imageSeq}.${ext}`;
+            const dir = join(this.dataDir, 'runs', `${runId}-images`);
+            mkdirSync(dir, { recursive: true });
+            writeFileSync(join(dir, name), Buffer.from(data, 'base64'));
+            return { name, url: `/api/runs/${runId}/images/${name}` };
+        }
+        catch {
+            return null;
+        }
+    }
     armIdleTimer(runId, state) {
         this.clearIdleTimer(state);
         state.idleTimer = setTimeout(() => {
@@ -395,11 +667,27 @@ export class RunManager {
             state.idleTimer = undefined;
         }
     }
+    /** Autosave-commit the worktree every 90 s while the run lives (spec 006). */
+    armAutosave(state) {
+        if (state.cwd === this.repoRoot || state.autosaveTimer)
+            return;
+        state.autosaveTimer = setInterval(() => {
+            void autosaveCommit(state.cwd);
+        }, AUTOSAVE_INTERVAL_MS);
+        state.autosaveTimer.unref?.();
+    }
+    clearAutosaveTimer(state) {
+        if (state.autosaveTimer) {
+            clearInterval(state.autosaveTimer);
+            state.autosaveTimer = undefined;
+        }
+    }
     runCheckStep(state, step, emit) {
         const command = step.command;
         emit({ type: 'note', stepId: step.id, message: `$ ${command}` });
         return new Promise((resolve) => {
-            const child = spawn('bash', ['-lc', command], { cwd: this.repoRoot, env: process.env });
+            // Check steps run in the same cwd as the agent steps — the worktree.
+            const child = spawn('bash', ['-lc', command], { cwd: state.cwd, env: process.env });
             state.interrupt = () => child.kill('SIGTERM');
             let output = '';
             const collect = (chunk) => {
@@ -432,6 +720,7 @@ export class RunManager {
             finishedAt: new Date().toISOString(),
         });
         emit({ type: 'step-end', stepId, status, ...(error ? { error } : {}) });
+        appendHandoffHeartbeat(this.dataDir, runId, `step "${stepId}" complete — status=${status}`);
     }
 }
 function findLastAgentStepIndex(workflow) {