spectoflow 0.32.0 → 0.34.0

package/README.md

@@ -307,8 +307,9 @@ off by default):
 - **Info** — a project-at-a-glance summary.
 - **Documentation** — the live supported-agents table (your own install status + links) plus the CLI
   command reference.
-- **Second brain** — what spectoflow has learned about you, shared by all your projects: read, add, fix,
-  confirm (see [Second brain](#second-brain)). Local only.
+- **Second brain** — two sections: **You** (what spectoflow has learned about you, shared by all your projects,
+  local only) and **This project** (the project memory, committed). Read, add, fix, confirm, move a fact to the
+  other one (see [Second brain](#second-brain)).
 - **Personalize** — autonomy mode, language, design, the active agent, **navigation tabs**, **slash
   commands**, and **Extend spectoflow** (see *Customize* below).
 
@@ -339,6 +340,34 @@ drawer is served by the one read-only endpoint, `GET /api/agentfile?path=` (scop
 `.spectoflow/agents/**` + `.spectoflow/skills/**`, path-traversal-safe) — the framework's only other
 server surface is unchanged.
 
+### Isolated work on a task
+
+In a git project, open a task and click **Work on it in isolation**. The agent works in its own copy of the
+repository — a git worktree on the branch `spectoflow/<task>` — so your working tree stays untouched, and several
+tasks can run at once without stepping on each other or blocking the chat.
+
+```
+  task T-012 ── Work on it in isolation ──►  its own copy, branch spectoflow/T-012   (task: in progress)
+                                                    │  the agent finishes
+                                                    ▼
+                                   task drawer: what changed + the diff             (task: to validate)
+                                   ├─ Merge          into your current branch, copy removed    → done
+                                   ├─ Open a PR      push + gh pr create                        → link on the task
+                                   ├─ Send feedback  the agent works again on the same copy
+                                   └─ Discard        copy and branch removed — the rollback     → to do
+```
+
+- **Nothing to learn:** no command, no setting. Chat runs and orchestration keep working as before.
+- **The agent's last message** shows in the drawer, so a run that changed nothing still says why.
+- **Merge never half-happens:** on a conflict it is aborted, nothing changes, and the drawer shows git's reason —
+  send feedback to the agent, or resolve it yourself.
+- **Open a PR** appears when `gh` is installed and signed in and the repository has a remote.
+- The copies live in `~/.spectoflow/worktrees/`, outside your project (no tool sees a second copy of the code) and
+  outside `.git` (agents refuse to write there). Uncommitted changes in your working tree aren't in the copy; the
+  drawer tells you how many.
+- **Online:** members with write access can start, review, send feedback and discard; merging and opening a pull
+  request stay on the owner's machine.
+
 ### Slash commands
 
 Type `/` in either chat surface to open an autocomplete of reusable **prompt macros** — pick one,
@@ -412,11 +441,37 @@ agents then read and grow your second brain through that server: nothing is copi
   `::spectoflow learn category=… msg=…` line instead. Those always wait in *To confirm*, whatever the setting:
   that output also carries command output and file contents, so a line hidden in a repository can't slip
   in unseen.
-- **Private:** the Second brain tab and its API answer this machine only — not the online dashboard
+- **Private:** the *You* section and its API answer this machine only — not the online dashboard
   (`server/` refuses them for everyone, the project owner included), and not other machines or websites.
   A run started from either of those can't write into it, and a learned fact never goes into a project's chat
   log.
 
+### Project memory
+
+Some facts aren't about you but about **one project**: its conventions, what breaks, its vocabulary, its
+constraints. Those go in `.spectoflow/memory.md`, **committed with the code**, so your team and their agents
+share them — and your other projects don't inherit them.
+
+```markdown
+# Project memory
+
+## Conventions
+- Tests run with `npm test -- --runInBand` (shared DB fixtures)
+
+## Glossary
+- "Ticket" means a customer support case, never a Jira issue
+```
+
+- **Four categories:** Conventions, Pitfalls, Glossary, Constraints.
+- **The agent reads and writes the file directly** — no setup. About you → second brain; about the project →
+  this file. Never anything personal in it.
+- **Facts the agent adds land directly by default.** To review them first, untick *Add what the agent learns
+  directly* in the *This project* section: that sets `memoryAutoAdd: false` in `.spectoflow/config.json`, for
+  the whole team.
+- **Wrong memory?** *Move to…* on any fact sends it to the other one, in the category you pick (local dashboard
+  only).
+- Created on the first fact; `spectoflow update` never touches it.
+
 ## A workflow that fits the project
 
 The workflow (`.spectoflow/workflow.md`) isn't one-size-fits-all anymore.

package/lib/adapters.js

@@ -30,6 +30,11 @@ learn one (a stated preference, a correction of how you work, their role), recor
 \`::spectoflow learn category=<profile|preferences|workflow|avoid> msg=<fact>\` if that tool is unavailable. Never
 secrets or sensitive data.
 
+**Project memory.** Facts about *this project* (conventions, pitfalls, domain vocabulary, constraints) live in
+\`.spectoflow/memory.md\`, committed — read it at session start and apply it. When you learn one, add a line under
+its section (or under \`## To confirm\` as \`- [category] fact\` when \`.spectoflow/config.json\` → \`memoryAutoAdd\` is
+\`false\`). About the user → second brain; about the project → this file. Never anything personal there.
+
 **Workflow.** If a request needs a step that is disabled in \`.spectoflow/workflow.md\` (e.g. writing code while
 *Develop* is off): enable it yourself and say so when \`.spectoflow/config.json\` → \`workflowAutoEnable\` is \`true\`;
 otherwise ask first. Never disable a step without the user.
@@ -53,6 +58,11 @@ learn one (a stated preference, a correction of how you work, their role), recor
 \`::spectoflow learn category=<profile|preferences|workflow|avoid> msg=<fact>\` if that tool is unavailable. Never
 secrets or sensitive data.
 
+**Project memory.** Facts about *this project* (conventions, pitfalls, domain vocabulary, constraints) live in
+\`.spectoflow/memory.md\`, committed — read it at session start and apply it. When you learn one, add a line under
+its section (or under \`## To confirm\` as \`- [category] fact\` when \`.spectoflow/config.json\` → \`memoryAutoAdd\` is
+\`false\`). About the user → second brain; about the project → this file. Never anything personal there.
+
 **Workflow.** If a request needs a step that is disabled in \`.spectoflow/workflow.md\` (e.g. writing code while
 *Develop* is off): enable it yourself and say so when \`.spectoflow/config.json\` → \`workflowAutoEnable\` is \`true\`;
 otherwise ask first. Never disable a step without the user.
@@ -73,6 +83,11 @@ learn one (a stated preference, a correction of how you work, their role), recor
 \`::spectoflow learn category=<profile|preferences|workflow|avoid> msg=<fact>\` if that tool is unavailable. Never
 secrets or sensitive data.
 
+**Project memory.** Facts about *this project* (conventions, pitfalls, domain vocabulary, constraints) live in
+\`.spectoflow/memory.md\`, committed — read it at session start and apply it. When you learn one, add a line under
+its section (or under \`## To confirm\` as \`- [category] fact\` when \`.spectoflow/config.json\` → \`memoryAutoAdd\` is
+\`false\`). About the user → second brain; about the project → this file. Never anything personal there.
+
 **Workflow.** If a request needs a step that is disabled in \`.spectoflow/workflow.md\` (e.g. writing code while
 *Develop* is off): enable it yourself and say so when \`.spectoflow/config.json\` → \`workflowAutoEnable\` is \`true\`;
 otherwise ask first. Never disable a step without the user.

package/lib/brain.js

@@ -2,256 +2,25 @@
 /*
  * The second brain — what spectoflow has learned about the user, shared by all their projects.
  * One markdown file, ~/.spectoflow/brain.md (never inside a project, never copied), read and written
- * by the dashboard page, the `spectoflow mcp` server and the `::spectoflow learn` run line. Zero
- * dependency.
- *
- *   # Second brain
- *   ## Profile
- *   - Scrum master and full-stack developer <!-- id:b7k2 by:agent at:2026-09-16 -->
- *   ## To confirm
- *   - [preferences] Prefers pnpm over npm <!-- id:b7k6 by:agent at:2026-09-16 -->
- *
- * The file is the user's too: every line spectoflow doesn't change is written back byte for byte —
- * titles, blank lines, comments, code blocks, unknown sections and their order, hand-written entries.
- * Writers in different processes (hub, MCP servers, runs) take a lock file, then write-then-rename.
+ * by the dashboard page, the `spectoflow mcp` server and the `::spectoflow learn` run line. Facts about
+ * one project go to the project memory instead (lib/project-memory.js). The file format, its fidelity
+ * and its lock live in lib/memory-store.js.
  */
-const fs = require('fs');
 const path = require('path');
-const crypto = require('crypto');
 const globalConfig = require('./global-config');
-
-const CATEGORIES = ['profile', 'preferences', 'workflow', 'avoid'];
-const HEADINGS = { profile: 'Profile', preferences: 'Preferences', workflow: 'Working style', avoid: 'Avoid' };
-const PENDING = 'To confirm';
-const MAX_TEXT = 500;
-const FALLBACK_CATEGORY = 'preferences';
+const { createMemoryStore } = require('./memory-store');
 
 function brainPath() { return path.join(globalConfig.homeDir(), 'brain.md'); }
 
-const normCategory = (c) => (CATEGORIES.includes(String(c || '').trim().toLowerCase()) ? String(c).trim().toLowerCase() : FALLBACK_CATEGORY);
-// One line, no HTML-comment delimiters (they would break the metadata), capped.
-function cleanText(t) {
-  return String(t == null ? '' : t).replace(/<!--|-->/g, '').replace(/\s+/g, ' ').trim().slice(0, MAX_TEXT);
-}
-const newId = () => 'b' + Date.now().toString(36) + crypto.randomBytes(3).toString('hex');
-// A hand-written line has no id: derive a stable one. `n` tells identical lines of a category apart.
-const derivedId = (category, text, n) => 'h' + crypto.createHash('sha1').update(`${category}\n${text}\n${n}`).digest('hex').slice(0, 10);
-const today = () => new Date().toISOString().slice(0, 10);
-const isBlank = (it) => it.raw !== undefined && !it.raw.trim();
-
-function headingKind(title) {
-  const t = title.trim().toLowerCase();
-  if (t === PENDING.toLowerCase()) return { kind: 'pending' };
-  const cat = CATEGORIES.find((c) => c === t || HEADINGS[c].toLowerCase() === t);
-  return cat ? { kind: 'category', id: cat } : { kind: 'unknown' };
-}
-
-const ENTRY_RE = /^-\s+(?:\[([\w-]+)\]\s+)?(.*?)\s*(?:<!--\s*(.*?)\s*-->)?\s*$/;
-function parseMeta(s) {
-  const out = {};
-  for (const m of String(s || '').matchAll(/(\w+):(\S+)/g)) out[m[1]] = m[2];
-  return out;
-}
-
-// → { title, blocks: [{ kind: preamble|category|pending|unknown, id?, heading?, items: [...] }] }
-// item = { raw } (a line kept verbatim) or an entry { id, category, text, by, at, status, line }.
-function parse(text) {
-  const lines = String(text || '').split(/\r?\n/);
-  while (lines.length && !lines[lines.length - 1].trim()) lines.pop();
-  const model = { title: null, eol: /\r\n/.test(String(text || '')) ? '\r\n' : '\n', blocks: [{ kind: 'preamble', items: [] }] };
-  let block = model.blocks[0], inFence = false;
-  const seen = new Map();
-  for (const line of lines) {
-    if (/^\s*(```|~~~)/.test(line)) { inFence = !inFence; block.items.push({ raw: line }); continue; }
-    if (inFence) { block.items.push({ raw: line }); continue; }
-    if (model.title === null && model.blocks.length === 1 && block.items.every(isBlank) && /^#\s+/.test(line)) { model.title = line; continue; }
-    const h = line.match(/^##\s+(.*)$/);
-    if (h) {
-      block = { ...headingKind(h[1]), heading: line, items: [] };
-      model.blocks.push(block);
-      continue;
-    }
-    const m = (block.kind === 'category' || block.kind === 'pending') && line.match(ENTRY_RE);
-    const meta = m ? parseMeta(m[3]) : null;
-    // A trailing comment is never part of the fact (a user's own comment stays hidden: the line itself is
-    // written back verbatim while the entry is untouched; editing the entry replaces the line).
-    const body = m ? m[2] : '';
-    if (m && cleanText(body)) {
-      const pending = block.kind === 'pending';
-      const category = pending ? normCategory(m[1]) : block.id;
-      const entryText = cleanText(pending || !m[1] ? body : `[${m[1]}] ${body}`);
-      let id = meta.id;
-      if (!id) { const k = `${category}\n${entryText}`; const n = seen.get(k) || 0; seen.set(k, n + 1); id = derivedId(category, entryText, n); }
-      block.items.push({ id, category, text: entryText, by: meta.by || 'user', at: meta.at || null, status: pending ? 'pending' : 'confirmed', line });
-    } else {
-      block.items.push({ raw: line });
-    }
-  }
-  return model;
-}
-
-function entryLine(e) {
-  const meta = `id:${e.id} by:${e.by}${e.at ? ' at:' + e.at : ''}`;
-  return `- ${e.status === 'pending' ? `[${e.category}] ` : ''}${e.text} <!-- ${meta} -->`;
-}
-function serialize(model) {
-  const out = [model.title || '# Second brain'];
-  for (const b of model.blocks) {
-    if (b.kind === 'pending' && !b.items.some((it) => it.raw === undefined) && b.items.every(isBlank)) continue;
-    if (b.kind !== 'preamble') {
-      if (out[out.length - 1].trim()) out.push(''); // a section always follows a blank line
-      out.push(b.heading || `## ${b.kind === 'pending' ? PENDING : HEADINGS[b.id]}`);
-    }
-    for (const it of b.items) out.push(it.raw !== undefined ? it.raw : (it.line && !it.dirty ? it.line : entryLine(it)));
-  }
-  while (out.length > 1 && !out[out.length - 1].trim()) out.pop();
-  const eol = model.eol || '\n';
-  return out.join(eol) + eol;
-}
-
-function emptyModel() {
-  return { title: null, blocks: [{ kind: 'preamble', items: [] }, ...CATEGORIES.map((id) => ({ kind: 'category', id, heading: null, items: [] }))] };
-}
-function load(file = brainPath()) {
-  let text = '';
-  try { text = fs.readFileSync(file, 'utf8'); } catch (e) { if (e.code !== 'ENOENT') throw e; }
-  return text.trim() ? parse(text) : emptyModel();
-}
-function save(model, file = brainPath()) {
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  const tmp = `${file}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`;
-  fs.writeFileSync(tmp, serialize(model));
-  fs.renameSync(tmp, file);
-}
-
-// Cross-process lock: the hub, any number of `spectoflow mcp` processes and runs may write in the
-// same instant. A lock older than 10s is a crashed writer's and is taken over.
-const sleepSync = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-function withLock(file, fn) {
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  const lock = `${file}.lock`, deadline = Date.now() + 3000;
-  for (;;) {
-    try { fs.writeFileSync(lock, String(process.pid), { flag: 'wx' }); break; }
-    catch (e) {
-      if (e.code !== 'EEXIST') throw e;
-      try { if (Date.now() - fs.statSync(lock).mtimeMs > 10000) { fs.unlinkSync(lock); continue; } } catch (_) {}
-      if (Date.now() > deadline) throw Object.assign(new Error('The second brain is busy, try again.'), { status: 503 });
-      sleepSync(15);
-    }
-  }
-  try { return fn(); } finally { try { fs.unlinkSync(lock); } catch (_) {} }
-}
-// Read, change, save — under the lock. `fn` returns { result, changed }.
-function mutate(file, fn) {
-  return withLock(file, () => {
-    const model = load(file);
-    const { result, changed } = fn(model);
-    if (changed) save(model, file);
-    return result;
-  });
-}
-
-const entriesOf = (model) => model.blocks.flatMap((b) => b.items.filter((it) => it.raw === undefined));
-function find(model, id) {
-  for (const b of model.blocks) {
-    const i = b.items.findIndex((it) => it.raw === undefined && it.id === id);
-    if (i >= 0) return { block: b, i, entry: b.items[i] };
-  }
-  return null;
-}
-// Append before the block's trailing blank lines, so the spacing before the next heading stays.
-function append(block, entry) {
-  let i = block.items.length;
-  while (i > 0 && isBlank(block.items[i - 1])) i--;
-  block.items.splice(i, 0, entry);
-}
-function blockFor(model, status, category) {
-  const want = status === 'pending' ? (b) => b.kind === 'pending' : (b) => b.kind === 'category' && b.id === category;
-  let b = model.blocks.find(want);
-  if (!b) {
-    b = status === 'pending' ? { kind: 'pending', heading: null, items: [] } : { kind: 'category', id: category, heading: null, items: [] };
-    const at = status === 'pending' ? -1 : model.blocks.findIndex((x) => x.kind === 'pending');
-    if (at < 0) model.blocks.push(b); else model.blocks.splice(at, 0, b);
-  }
-  return b;
-}
-const notFound = () => Object.assign(new Error('Entry not found.'), { status: 404 });
-const emptyText = () => Object.assign(new Error('Text is required.'), { status: 400 });
-
-// { entries (confirmed, in category order), pending, autoAdd }
-function read(file = brainPath()) {
-  const all = entriesOf(load(file));
-  return {
-    entries: CATEGORIES.flatMap((c) => all.filter((e) => e.status === 'confirmed' && e.category === c)),
-    pending: all.filter((e) => e.status === 'pending'),
-    autoAdd: autoAdd(),
-  };
-}
-
-// Adds one fact. status 'confirmed' or 'pending'. A case-insensitive duplicate of any entry is not
-// added again: → { duplicate: true, entry: <the existing one> }.
-function add({ category, text, by = 'user', status = 'confirmed' }, file = brainPath()) {
-  const t = cleanText(text);
-  if (!t) throw emptyText();
-  return mutate(file, (model) => {
-    const existing = entriesOf(model).find((e) => e.text.toLowerCase() === t.toLowerCase());
-    if (existing) return { result: { duplicate: true, entry: existing }, changed: false };
-    const entry = { id: newId(), category: normCategory(category), text: t, by, at: today(), status: status === 'pending' ? 'pending' : 'confirmed' };
-    append(blockFor(model, entry.status, entry.category), entry);
-    return { result: { duplicate: false, entry }, changed: true };
-  });
-}
-
-// What the agent learned through MCP: confirmed right away, or "to confirm", per brain.autoAdd.
-function learn({ category, text }, file = brainPath()) {
-  return add({ category, text, by: 'agent', status: autoAdd() ? 'confirmed' : 'pending' }, file);
-}
-
-function update(id, { text, category } = {}, file = brainPath()) {
-  const t = text === undefined ? undefined : cleanText(text);
-  if (text !== undefined && !t) throw emptyText();
-  return mutate(file, (model) => {
-    const hit = find(model, id); if (!hit) throw notFound();
-    const e = hit.entry;
-    if (t !== undefined) e.text = t;
-    if (category !== undefined) {
-      const c = normCategory(category);
-      if (c !== e.category && e.status === 'confirmed') { hit.block.items.splice(hit.i, 1); append(blockFor(model, 'confirmed', c), e); }
-      e.category = c;
-    }
-    e.dirty = true;
-    return { result: e, changed: true };
-  });
-}
-
-function remove(id, file = brainPath()) {
-  return mutate(file, (model) => {
-    const hit = find(model, id); if (!hit) throw notFound();
-    hit.block.items.splice(hit.i, 1);
-    return { result: { ok: true }, changed: true };
-  });
-}
-
-function confirm(id, file = brainPath()) {
-  return mutate(file, (model) => {
-    const hit = find(model, id); if (!hit) throw notFound();
-    if (hit.entry.status !== 'pending') return { result: hit.entry, changed: false };
-    hit.block.items.splice(hit.i, 1);
-    hit.entry.status = 'confirmed'; hit.entry.dirty = true;
-    append(blockFor(model, 'confirmed', hit.entry.category), hit.entry);
-    return { result: hit.entry, changed: true };
-  });
-}
-
-// Confirmed entries as markdown, grouped by category — what an agent is given.
-function renderForAgent(file = brainPath()) {
-  const { entries } = read(file);
-  return CATEGORIES.map((c) => {
-    const items = entries.filter((e) => e.category === c);
-    return items.length ? `## ${HEADINGS[c]}\n${items.map((e) => `- ${e.text}`).join('\n')}` : '';
-  }).filter(Boolean).join('\n\n');
-}
-
-function autoAdd() { return globalConfig.get('brain.autoAdd').value !== false; }
-
-module.exports = { CATEGORIES, HEADINGS, MAX_TEXT, brainPath, parse, serialize, read, add, learn, update, remove, confirm, renderForAgent, autoAdd };
+const store = createMemoryStore({
+  name: 'second brain',
+  title: 'Second brain',
+  categories: ['profile', 'preferences', 'workflow', 'avoid'],
+  headings: { profile: 'Profile', preferences: 'Preferences', workflow: 'Working style', avoid: 'Avoid' },
+  fallback: 'preferences',
+  idPrefix: 'b',
+  defaultFile: brainPath,
+  autoAdd: () => globalConfig.get('brain.autoAdd').value !== false,
+});
+
+module.exports = { ...store, brainPath };

package/lib/dashboard/handlers.js

@@ -69,6 +69,7 @@ function createHandlers(root) {
     // so the 409 guard in orchestrate.start can't wedge forever. Not a resume — just un-wedging.
     try { orchestrator.reconcileOnBoot(root); } catch (_) {}
     try { require('./runner').reconcileRunsOnBoot(root); } catch (_) {}
+    try { require('./isolation').reconcileOnBoot(root); } catch (_) {}
   }
   return {
     handleApi,

package/lib/dashboard/isolation.js

@@ -0,0 +1,177 @@
+'use strict';
+/*
+ * The delivery loop (D79, docs/delivery-loop-design.md): a task worked on in isolation. One path, riding on the
+ * task's existing status:
+ *
+ *   start     → git worktree + branch spectoflow/<id>, the agent runs there         task: in progress
+ *   run ends  → what it left uncommitted is committed on the branch                 task: to validate
+ *   diff      → files and patch, for review in the task drawer
+ *   feedback  → the comment is added to the task, the agent runs again, same worktree
+ *   merge     → merged into the working tree's branch, worktree and branch removed  task: done
+ *   pr        → branch pushed, pull request opened with gh, worktree removed         (link added to the task)
+ *   discard   → worktree and branch removed — the rollback                          task: to do
+ *
+ * State lives in runtime.json → worktrees[<id>] = { branch, base, status, runId, startedAt, endedAt,
+ * uncommitted, prUrl }; git itself stays the source of truth (boot drops an entry whose branch is gone).
+ */
+const store = require('../store');
+const worktree = require('../worktree');
+const { startRun, stopRuns, isRunning } = require('./runner');
+
+const group = (id) => `task:${id}`;
+const OUTPUT_TAIL = 4000;
+// What the agent said last (its plain output, sentinel lines left out) — shown in the drawer, so a run that
+// changed nothing still says why (a question, a refusal, an error).
+function tailOutput(child) {
+  let text = '';
+  const keep = (d) => { text = (text + d.toString()).slice(-OUTPUT_TAIL * 2); };
+  if (child.stdout) child.stdout.on('data', keep);
+  return () => text.split('\n').filter((l) => !/^::spectoflow\s/.test(l.trim())).join('\n').trim().slice(-OUTPUT_TAIL);
+}
+const fail = (status, message) => { throw new worktree.GitError(status, message); };
+
+function findTask(root, id) {
+  for (const pl of store.readPlans(root)) for (const ph of pl.phases) {
+    const task = ph.tasks.find((t) => t.id === id);
+    if (task) return { task, file: pl.file };
+  }
+  return fail(404, `Task ${id} not found.`);
+}
+function readState(root) { return store.readRuntime(root).worktrees || {}; }
+function setState(root, id, patch) {
+  const rt = store.readRuntime(root);
+  rt.worktrees = rt.worktrees || {};
+  if (patch === null) delete rt.worktrees[id];
+  else rt.worktrees[id] = { ...(rt.worktrees[id] || {}), ...patch };
+  store.writeRuntime(root, rt);
+  return rt.worktrees[id] || null;
+}
+const setStatus = (root, file, id, status) => { try { store.updateTaskLine(root, file, id, { status }); } catch (_) {} };
+
+function promptFor(id, task, file, branch, feedback) {
+  const lines = [
+    `Work on task ${id}: ${task.title} (from plans/${file}).`,
+    `You are in an isolated git worktree of this project, on branch ${branch}. The user reviews the diff before anything reaches their own working tree.`,
+    "Don't edit this task's line or its status in plans/ — the dashboard tracks it. Don't push, don't switch or create branches.",
+    'The user started this work from the dashboard: that is their go-ahead to do this task now. If it needs a workflow step that is disabled, enable it in .spectoflow/workflow.md and say so — the change shows in the diff they review.',
+  ];
+  const notes = (task.comments || []).filter((c) => !/^PR: /.test(c));
+  if (notes.length) lines.push(`Notes on the task:\n${notes.map((c) => `- ${c}`).join('\n')}`);
+  if (feedback) lines.push(`Review feedback on your previous change — address it:\n${feedback}`);
+  lines.push('When done, summarize what you changed.');
+  return lines.join('\n\n');
+}
+
+// Start (or restart, with feedback) the agent on a task in its worktree.
+function start(root, { id, feedback }, emit, { remote } = {}) {
+  const { task, file } = findTask(root, id);
+  if (isRunning(root, group(id))) fail(409, `An agent is already working on ${id}.`);
+  const made = worktree.create(root, id);
+  const prev = readState(root)[id] || null;
+  const was = prev || {};
+  // Marked running before the agent starts: startRun's own events must never show the previous run's result.
+  setState(root, id, {
+    branch: made.branch, base: was.base || made.base, status: 'running', runId: null,
+    startedAt: new Date().toISOString(), endedAt: null, error: null, output: null, prUrl: was.prUrl || null,
+    uncommitted: made.created ? worktree.uncommitted(root, [store.resolvePlansDir(root, store.readConfig(root))]).length : (was.uncommitted || 0),
+  });
+  const run = startRun(root, {
+    prompt: promptFor(id, task, file, made.branch, feedback),
+    display: `⎇ ${id} — ${feedback ? 'feedback: ' + feedback : task.title}`,
+    task: id, cwd: made.cwd, learn: !remote,
+  }, emit);
+  if (run.error) {
+    setState(root, id, prev);
+    if (made.created) { try { worktree.discard(root, id); } catch (_) {} }
+    fail(400, run.error);
+  }
+  setState(root, id, { runId: run.runId });
+  setStatus(root, file, id, 'in_progress');
+  const output = run.child ? tailOutput(run.child) : () => '';
+  const finish = (code, signal) => {
+    let error = null;
+    try { worktree.commitAll(made.path, `${id}: ${task.title}`); } catch (e) { error = e.message; }
+    const status = signal ? 'stopped' : code === 0 && !error ? 'ready' : 'failed';
+    setState(root, id, { status, endedAt: new Date().toISOString(), error, output: output() || null });
+    setStatus(root, file, id, 'to_validate');
+    emit({ type: 'change' });
+  };
+  if (run.child) run.child.on('close', finish); else finish(1, null);
+  emit({ type: 'change' });
+  return { runId: run.runId, branch: made.branch, uncommitted: readState(root)[id].uncommitted };
+}
+
+function requireIdle(root, id) {
+  if (isRunning(root, group(id))) fail(409, `An agent is still working on ${id}: stop it first.`);
+}
+// Anything left uncommitted in the worktree (a stopped run, a crash, a hand edit) is part of the change.
+function commitLeftovers(root, id, title) {
+  const wt = worktree.list(root)[id];
+  if (wt) worktree.commitAll(wt, `${id}: ${title}`);
+}
+
+function diff(root, { id }, { remote } = {}) {
+  const { task } = findTask(root, id);
+  const state = readState(root)[id] || {};
+  if (!isRunning(root, group(id))) commitLeftovers(root, id, task.title);
+  const d = worktree.diff(root, id, state.base);
+  return { ...d, running: isRunning(root, group(id)), pr: remote ? { ok: false, reason: 'local dashboard only' } : prReadyCached(root) };
+}
+
+function merge(root, { id }) {
+  const { task, file } = findTask(root, id);
+  requireIdle(root, id);
+  commitLeftovers(root, id, task.title);
+  const r = worktree.merge(root, id, `Merge ${worktree.branchOf(id)}: ${id} ${task.title}`);
+  setState(root, id, null);
+  setStatus(root, file, id, 'done');
+  return r;
+}
+
+function openPr(root, { id }) {
+  const { task, file } = findTask(root, id);
+  requireIdle(root, id);
+  commitLeftovers(root, id, task.title);
+  const r = worktree.openPr(root, id, { title: `${id}: ${task.title}`, body: `Task ${id} from \`plans/${file}\`, worked on with spectoflow.` });
+  setState(root, id, { status: 'pr', prUrl: r.url });
+  try { store.addTaskComment(root, file, id, `PR: ${r.url}`); } catch (_) {}
+  return r;
+}
+
+function discard(root, { id }) {
+  const { file } = findTask(root, id);
+  requireIdle(root, id);
+  const r = worktree.discard(root, id);
+  setState(root, id, null);
+  setStatus(root, file, id, 'todo');
+  return r;
+}
+
+const stop = (root, { id }) => ({ stopped: stopRuns(root, group(id)) });
+
+// After a restart nothing runs: a 'running' entry was interrupted; an entry whose branch is gone is dropped.
+function reconcileOnBoot(root) {
+  const state = readState(root);
+  const ids = Object.keys(state);
+  if (!ids.length) return;
+  const rt = store.readRuntime(root);
+  for (const id of ids) {
+    const exists = worktree.isRepo(root) && worktree.list(root)[id] !== undefined;
+    const branchKept = exists || state[id].status === 'pr';
+    if (!branchKept) { delete rt.worktrees[id]; continue; }
+    if (state[id].status === 'running') rt.worktrees[id] = { ...state[id], status: 'stopped', endedAt: new Date().toISOString() };
+  }
+  store.writeRuntime(root, rt);
+}
+
+// `gh auth status` is slow-ish: remember the answer for a minute per project.
+const prCache = new Map();
+function prReadyCached(root) {
+  const hit = prCache.get(root);
+  if (hit && Date.now() - hit.at < 60000) return hit.value;
+  const value = worktree.prReady(root);
+  prCache.set(root, { at: Date.now(), value });
+  return value;
+}
+
+module.exports = { start, diff, merge, openPr, discard, stop, reconcileOnBoot, promptFor };