@shipers-dev/multi 0.8.3 → 0.9.0

package/dist/index.js

@@ -5185,6 +5185,9 @@ async function runAcp(opts) {
     cwd: opts.cwd || process.cwd(),
     env: { ...cleanEnv, ACP_PERMISSION_MODE: permMode }
   });
+  try {
+    opts.onSpawn?.(child);
+  } catch {}
   const output = new WritableStream({
     write(chunk) {
       child.stdin.write(chunk);
@@ -5449,6 +5452,9 @@ async function runAcpx(opts) {
   args.push(opts.prompt);
   dlog(`[acpx] prompt: ${args.slice(0, 10).join(" ")} ... (prompt len=${opts.prompt.length})`);
   const proc = Bun.spawn(args, { stdout: "pipe", stderr: "pipe", stdin: "ignore" });
+  try {
+    opts.onSpawn?.(proc);
+  } catch {}
   let stopReason = "end_turn";
   (async () => {
     try {
@@ -5595,18 +5601,94 @@ function extractText2(content) {
   return "";
 }
 
+// src/worktree.ts
+import { spawn } from "child_process";
+import { existsSync as existsSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2, mkdirSync as mkdirSync2 } from "fs";
+import { join as join2 } from "path";
+async function run(cwd, cmd, args) {
+  return await new Promise((resolve) => {
+    const p = spawn(cmd, args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    p.stdout.on("data", (d) => {
+      stdout += d.toString();
+    });
+    p.stderr.on("data", (d) => {
+      stderr += d.toString();
+    });
+    p.on("close", (code) => resolve({ code: code ?? 0, stdout: stdout.trim(), stderr: stderr.trim() }));
+    p.on("error", (e) => resolve({ code: 1, stdout: "", stderr: String(e) }));
+  });
+}
+async function isGitRepo(dir) {
+  if (!existsSync2(dir))
+    return false;
+  const r = await run(dir, "git", ["rev-parse", "--is-inside-work-tree"]);
+  return r.code === 0 && r.stdout === "true";
+}
+async function branchExists(dir, branch) {
+  const r = await run(dir, "git", ["rev-parse", "--verify", "--quiet", `refs/heads/${branch}`]);
+  return r.code === 0;
+}
+function ensureGitignoreEntry(workingDir, entry) {
+  const gip = join2(workingDir, ".gitignore");
+  let body = "";
+  try {
+    body = existsSync2(gip) ? readFileSync2(gip, "utf8") : "";
+  } catch {
+    body = "";
+  }
+  const lines = body.split(`
+`);
+  if (lines.some((l) => l.trim() === entry))
+    return;
+  const nextBody = (body.endsWith(`
+`) || body === "" ? body : body + `
+`) + entry + `
+`;
+  try {
+    writeFileSync2(gip, nextBody, "utf8");
+  } catch {}
+}
+function normalizeKey(issueKey) {
+  return issueKey.toLowerCase().replace(/[^a-z0-9\-_\/]/g, "-");
+}
+async function ensureWorktree(workingDir, issueKey) {
+  if (!await isGitRepo(workingDir)) {
+    return { path: workingDir, branch: "", created: false };
+  }
+  ensureGitignoreEntry(workingDir, ".multi/");
+  const key = normalizeKey(issueKey);
+  const branch = `multi/${key}`;
+  const wtDir = join2(workingDir, ".multi", "worktrees");
+  const wtPath = join2(wtDir, key);
+  if (existsSync2(wtPath)) {
+    return { path: wtPath, branch, created: false };
+  }
+  try {
+    mkdirSync2(wtDir, { recursive: true });
+  } catch {}
+  const exists = await branchExists(workingDir, branch);
+  const args = exists ? ["worktree", "add", wtPath, branch] : ["worktree", "add", "-b", branch, wtPath, "HEAD"];
+  const r = await run(workingDir, "git", args);
+  if (r.code !== 0) {
+    throw new Error(`git worktree add failed: ${r.stderr || r.stdout}`);
+  }
+  return { path: wtPath, branch, created: true };
+}
+
 // src/index.ts
 import { parseArgs } from "util";
-import { mkdirSync as mkdirSync2, existsSync as existsSync2, writeFileSync as writeFileSync2, readFileSync as readFileSync2, appendFileSync as appendFileSync2, unlinkSync, readdirSync, statSync } from "fs";
-import { join as join2, dirname as dirname2 } from "path";
+import { mkdirSync as mkdirSync3, existsSync as existsSync3, writeFileSync as writeFileSync3, readFileSync as readFileSync3, appendFileSync as appendFileSync2, unlinkSync, readdirSync, statSync } from "fs";
+import { join as join3, dirname as dirname2 } from "path";
 var HOME2 = process.env.HOME || process.env.USERPROFILE || ".";
-var MULTI_DIR = join2(HOME2, ".multi");
-var CONFIG_PATH = join2(MULTI_DIR, "config.json");
-var PID_PATH = join2(MULTI_DIR, "agent.pid");
-var LOG_PATH2 = join2(MULTI_DIR, "logs", "agent.log");
-var SKILLS_DIR = join2(MULTI_DIR, "skills");
-var STOP_PATH = join2(MULTI_DIR, "stop.flag");
-var TASKS_DB_PATH = join2(MULTI_DIR, "tasks.db");
+var MULTI_DIR = join3(HOME2, ".multi");
+var CONFIG_PATH = join3(MULTI_DIR, "config.json");
+var PID_PATH = join3(MULTI_DIR, "agent.pid");
+var LOG_PATH2 = join3(MULTI_DIR, "logs", "agent.log");
+var SKILLS_DIR = join3(MULTI_DIR, "skills");
+var STOP_PATH = join3(MULTI_DIR, "stop.flag");
+var TASKS_DB_PATH = join3(MULTI_DIR, "tasks.db");
 var VERSION = "0.8.0";
 var COMMANDS = {
   setup: "Register this device with a workspace",
@@ -5617,9 +5699,9 @@ var COMMANDS = {
   logs: "View execution logs"
 };
 function ensureDirs() {
-  for (const d of [MULTI_DIR, join2(MULTI_DIR, "logs"), SKILLS_DIR]) {
-    if (!existsSync2(d))
-      mkdirSync2(d, { recursive: true });
+  for (const d of [MULTI_DIR, join3(MULTI_DIR, "logs"), SKILLS_DIR]) {
+    if (!existsSync3(d))
+      mkdirSync3(d, { recursive: true });
   }
 }
 function log(msg) {
@@ -5792,7 +5874,7 @@ async function syncSkills(apiUrl, workspaceId) {
     return;
   ensureDirs();
   for (const skill of res.data) {
-    writeFileSync2(join2(SKILLS_DIR, `${skill.name}.json`), JSON.stringify(skill, null, 2));
+    writeFileSync3(join3(SKILLS_DIR, `${skill.name}.json`), JSON.stringify(skill, null, 2));
   }
   if (res.data.length)
     console.log(`   Synced ${res.data.length} skill(s) \u2192 ${SKILLS_DIR}`);
@@ -5822,8 +5904,8 @@ async function cmdConnect(apiUrl, config) {
     console.log('\u274C Missing dispatch secret. Re-pair via "multi-agent setup".');
     process.exit(1);
   }
-  if (existsSync2(PID_PATH)) {
-    const pid = Number(readFileSync2(PID_PATH, "utf8").trim());
+  if (existsSync3(PID_PATH)) {
+    const pid = Number(readFileSync3(PID_PATH, "utf8").trim());
     if (pid && isRunning(pid)) {
       console.log(`\u274C Daemon already running (pid ${pid}).`);
       process.exit(1);
@@ -5831,21 +5913,46 @@ async function cmdConnect(apiUrl, config) {
     unlinkSync(PID_PATH);
   }
   ensureDirs();
-  writeFileSync2(PID_PATH, String(process.pid));
-  if (existsSync2(STOP_PATH))
+  writeFileSync3(PID_PATH, String(process.pid));
+  if (existsSync3(STOP_PATH))
     unlinkSync(STOP_PATH);
   const detected = await detectAgents();
   log(`\uD83D\uDE80 Starting daemon for device ${config.deviceId} (pid ${process.pid})`);
   log(`   runtimes: ${detected.map((d) => d.type).join(", ") || "stub"}`);
   const db = openTasksDb();
-  db.run("UPDATE tasks SET status = 'pending' WHERE status = 'running'");
-  let workerWake = null;
-  const notifyWorker = () => {
-    try {
-      workerWake?.();
-      workerWake = null;
-    } catch {}
-  };
+  db.run("UPDATE tasks SET status = 'queued' WHERE status = 'running'");
+  const MAX_DEVICE = Math.max(1, parseInt(process.env.MULTI_MAX_CONCURRENT ?? "3", 10) || 3);
+  const running = new Map;
+  function pickNext() {
+    const busyAgents = Array.from(running.values()).map((e) => e.agentId).filter(Boolean);
+    const notIn = busyAgents.length ? `AND (agent_id IS NULL OR agent_id NOT IN (${busyAgents.map(() => "?").join(",")}))` : "";
+    const sql = `SELECT id, payload, agent_id, issue_id FROM tasks WHERE status = 'queued' ${notIn} ORDER BY created_at ASC LIMIT 1`;
+    return db.query(sql).get(...busyAgents);
+  }
+  function schedule() {
+    while (running.size < MAX_DEVICE) {
+      const row = pickNext();
+      if (!row)
+        return;
+      db.run("UPDATE tasks SET status = 'running', started_at = unixepoch(), attempts = attempts + 1 WHERE id = ?", [row.id]);
+      const entry = { agentId: row.agent_id || "", startedAt: Date.now(), child: null, worktreePath: "" };
+      const issueKey = row.issue_id || row.id;
+      running.set(issueKey, entry);
+      (async () => {
+        try {
+          const task = JSON.parse(row.payload);
+          await handleRunTask(apiUrl, config.deviceId, task, detected, { runEntry: entry });
+          db.run("UPDATE tasks SET status = 'done', finished_at = unixepoch() WHERE id = ?", [row.id]);
+        } catch (e) {
+          log(`task ${row.id} error: ${String(e)}`);
+          db.run("UPDATE tasks SET status = 'failed', finished_at = unixepoch(), error = ? WHERE id = ?", [String(e), row.id]);
+        } finally {
+          running.delete(issueKey);
+          queueMicrotask(() => schedule());
+        }
+      })();
+    }
+  }
   const port = await pickFreePort();
   const expectedAuth = `Bearer ${config.dispatchSecret}`;
   const server = Bun.serve({
@@ -5861,15 +5968,50 @@ async function cmdConnect(apiUrl, config) {
         return (async () => {
           try {
             const body = await req.json();
-            const taskId = body?.task?.issue_id ? `${body.task.issue_id}-${Date.now()}` : crypto.randomUUID();
-            db.run("INSERT INTO tasks (id, status, payload) VALUES (?, ?, ?)", [taskId, "pending", JSON.stringify(body.task)]);
-            notifyWorker();
+            const t = body?.task || {};
+            const taskId = t.issue_id ? `${t.issue_id}-${Date.now()}` : crypto.randomUUID();
+            db.run("INSERT INTO tasks (id, status, payload, agent_id, issue_id) VALUES (?, 'queued', ?, ?, ?)", [taskId, JSON.stringify(t), t.agent_id ?? null, t.issue_id ?? null]);
+            const pos = db.query("SELECT COUNT(*) AS c FROM tasks WHERE status = 'queued' AND created_at <= (SELECT created_at FROM tasks WHERE id = ?)").get(taskId)?.c ?? 1;
+            if (t.issue_id) {
+              postStream(apiUrl, t.issue_id, "queued", { queue_position: pos });
+            }
+            queueMicrotask(() => schedule());
             return Response.json({ accepted: true, task_id: taskId }, { status: 202 });
           } catch (e) {
             return Response.json({ error: String(e) }, { status: 400 });
           }
         })();
       }
+      if (url.pathname === "/stop" && req.method === "POST") {
+        if (req.headers.get("authorization") !== expectedAuth)
+          return new Response("unauthorized", { status: 401 });
+        return (async () => {
+          try {
+            const { issue_id } = await req.json();
+            if (!issue_id)
+              return Response.json({ error: "issue_id required" }, { status: 400 });
+            const entry = running.get(issue_id);
+            if (!entry) {
+              db.run("UPDATE tasks SET status = 'failed', error = 'stopped before start', finished_at = unixepoch() WHERE issue_id = ? AND status = 'queued'", [issue_id]);
+              await markStopped(apiUrl, issue_id, "stopped before start");
+              return Response.json({ ok: true, state: "queued-cancelled" });
+            }
+            entry.stopped = true;
+            entry.stopReason = "user requested";
+            try {
+              entry.child?.kill("SIGTERM");
+            } catch {}
+            setTimeout(() => {
+              try {
+                entry.child?.kill("SIGKILL");
+              } catch {}
+            }, 5000);
+            return Response.json({ ok: true, state: "running-signalled" });
+          } catch (e) {
+            return Response.json({ error: String(e) }, { status: 400 });
+          }
+        })();
+      }
       return new Response("not found", { status: 404 });
     }
   });
@@ -5892,11 +6034,11 @@ async function cmdConnect(apiUrl, config) {
   }
   log(`\u2601\uFE0F  Tunnel up: ${tunnelUrl}`);
   await apiClient.post(`${apiUrl}/api/devices/${config.deviceId}/heartbeat`, { status: "online", tunnel_url: tunnelUrl });
-  let running = true;
+  let alive = true;
   const shutdown = async (reason) => {
-    if (!running)
+    if (!alive)
       return;
-    running = false;
+    alive = false;
     log(`\uD83D\uDED1 Shutting down (${reason})`);
     try {
       server.stop();
@@ -5907,9 +6049,9 @@ async function cmdConnect(apiUrl, config) {
     try {
       await apiClient.post(`${apiUrl}/api/devices/${config.deviceId}/heartbeat`, { status: "offline", tunnel_url: null });
     } catch {}
-    if (existsSync2(PID_PATH))
+    if (existsSync3(PID_PATH))
       unlinkSync(PID_PATH);
-    if (existsSync2(STOP_PATH))
+    if (existsSync3(STOP_PATH))
       unlinkSync(STOP_PATH);
     db.close();
     log("\uD83D\uDC4B Disconnected");
@@ -5917,30 +6059,10 @@ async function cmdConnect(apiUrl, config) {
   };
   process.on("SIGINT", () => shutdown("SIGINT"));
   process.on("SIGTERM", () => shutdown("SIGTERM"));
-  (async () => {
-    while (running) {
-      const row = db.query("SELECT id, payload FROM tasks WHERE status = 'pending' ORDER BY created_at ASC LIMIT 1").get();
-      if (!row) {
-        await new Promise((resolve) => {
-          workerWake = resolve;
-          setTimeout(resolve, 5000);
-        });
-        continue;
-      }
-      db.run("UPDATE tasks SET status = 'running', started_at = unixepoch(), attempts = attempts + 1 WHERE id = ?", [row.id]);
-      try {
-        const task = JSON.parse(row.payload);
-        await handleRunTask(apiUrl, config.deviceId, task, detected, {});
-        db.run("UPDATE tasks SET status = 'done', finished_at = unixepoch() WHERE id = ?", [row.id]);
-      } catch (e) {
-        log(`task ${row.id} error: ${String(e)}`);
-        db.run("UPDATE tasks SET status = 'failed', finished_at = unixepoch(), error = ? WHERE id = ?", [String(e), row.id]);
-      }
-    }
-  })();
-  while (running) {
+  schedule();
+  while (alive) {
     await sleep(20000);
-    if (existsSync2(STOP_PATH)) {
+    if (existsSync3(STOP_PATH)) {
       await shutdown("stop flag");
       break;
     }
@@ -5952,8 +6074,8 @@ async function cmdConnect(apiUrl, config) {
   }
 }
 async function cmdConnectDetached(apiUrl) {
-  if (existsSync2(PID_PATH)) {
-    const pid = Number(readFileSync2(PID_PATH, "utf8").trim());
+  if (existsSync3(PID_PATH)) {
+    const pid = Number(readFileSync3(PID_PATH, "utf8").trim());
     if (pid && isRunning(pid)) {
       console.log(`\u274C Daemon already running (pid ${pid}).`);
       process.exit(1);
@@ -6010,22 +6132,48 @@ async function parseTunnelUrl(stream2) {
   }
   return null;
 }
+async function markStopped(apiUrl, issueId, reason) {
+  try {
+    await apiClient.patch(`${apiUrl}/api/issues/${issueId}`, { status: "stopped" });
+  } catch {}
+  try {
+    await apiClient.post(`${apiUrl}/api/issues/${issueId}/comments`, {
+      author_type: "agent",
+      author_id: "daemon",
+      author_name: "daemon",
+      body: `\u23F9 Stopped: ${reason}`
+    });
+  } catch {}
+  await postStream(apiUrl, issueId, "stopped", { reason });
+}
 async function handleRunTask(apiUrl, deviceId, task, detected, ctx) {
   const issueId = task.issue_id;
   const isFollowup = !!task.followup;
-  const workingDir = task.working_dir && existsSync2(task.working_dir) ? task.working_dir : undefined;
-  log(`\u25B6 run_task ${task.key}: ${isFollowup ? "(follow-up) " : ""}${task.title}${workingDir ? ` [cwd: ${workingDir}]` : ""}`);
+  const baseWorkingDir = task.working_dir && existsSync3(task.working_dir) ? task.working_dir : undefined;
+  let workingDir = baseWorkingDir;
+  let worktreeBranch = "";
+  if (baseWorkingDir) {
+    try {
+      const wt = await ensureWorktree(baseWorkingDir, task.key || issueId);
+      workingDir = wt.path;
+      worktreeBranch = wt.branch;
+      await postStream(apiUrl, issueId, "worktree_created", { path: wt.path, branch: wt.branch, reused: !wt.created });
+    } catch (e) {
+      await postStream(apiUrl, issueId, "worktree_error", { message: String(e) });
+    }
+  }
+  log(`\u25B6 run_task ${task.key}: ${isFollowup ? "(follow-up) " : ""}${task.title}${workingDir ? ` [cwd: ${workingDir}${worktreeBranch ? ` @${worktreeBranch}` : ""}]` : ""}`);
   await apiClient.patch(`${apiUrl}/api/issues/${issueId}`, { status: "in_progress" });
   await postStream(apiUrl, issueId, "progress", { message: `Device ${deviceId} picked up ${isFollowup ? "follow-up" : "task"}` });
   let attachmentRefs = [];
   if (task.from_comment_id) {
-    const baseDir = workingDir || join2(MULTI_DIR, "tmp", issueId);
-    const inDir = join2(baseDir, ".multi-in", task.from_comment_id);
+    const baseDir = workingDir || join3(MULTI_DIR, "tmp", issueId);
+    const inDir = join3(baseDir, ".multi-in", task.from_comment_id);
     attachmentRefs = await downloadCommentAttachments(apiUrl, task.from_comment_id, inDir);
     if (attachmentRefs.length)
       log(`  fetched ${attachmentRefs.length} attachment(s) \u2192 ${inDir}`);
   }
-  const outDir = join2(workingDir || join2(MULTI_DIR, "tmp", issueId), ".multi-out");
+  const outDir = join3(workingDir || join3(MULTI_DIR, "tmp", issueId), ".multi-out");
   let liveCommentId;
   let liveBody = "";
   let hadError = false;
@@ -6333,6 +6481,7 @@ ${userPart}` : userPart;
       if (!adapterBin)
         throw new Error(`ACP adapter for ${chosen.type} not found`);
       log(`  adapter: ${chosen.type} \u2192 ${adapterBin.join(" ")}`);
+      const startedAt = Date.now();
       const { sessionId } = await runAcp({
         apiUrl,
         issueId,
@@ -6347,8 +6496,16 @@ ${userPart}` : userPart;
           try {
             await apiClient.post(`${apiUrl}/api/issues/${issueId}/session`, { session_id: sid });
           } catch {}
+        },
+        onSpawn: (child) => {
+          if (ctx?.runEntry) {
+            ctx.runEntry.child = child;
+            ctx.runEntry.worktreePath = workingDir || "";
+          }
+          postStream(apiUrl, issueId, "run_started", { pid: child?.pid, worktree_path: workingDir, branch: worktreeBranch, adapter: chosen.type });
         }
       });
+      postStream(apiUrl, issueId, "run_finished", { stopReason: typeof sessionId === "string" ? "ok" : "unknown", duration_ms: Date.now() - startedAt });
       log(`  acp session ${sessionId.slice(0, 8)}`);
     } else if (useAcpx) {
       let preamble = "";
@@ -6416,13 +6573,22 @@ Write generated files to: ${outDir}`;
 
 ${userPart}` : userPart;
       log(`  acpx runner: ${preferType}`);
+      const acpxStartedAt = Date.now();
       await runAcpx({
         agentType: preferType,
         prompt: full,
         cwd: workingDir,
         sessionName: `issue-${issueId}`,
-        onEvent: eventHandler
+        onEvent: eventHandler,
+        onSpawn: (child) => {
+          if (ctx?.runEntry) {
+            ctx.runEntry.child = child;
+            ctx.runEntry.worktreePath = workingDir || "";
+          }
+          postStream(apiUrl, issueId, "run_started", { pid: child?.pid, worktree_path: workingDir, branch: worktreeBranch, adapter: preferType });
+        }
       });
+      postStream(apiUrl, issueId, "run_finished", { stopReason: "ok", duration_ms: Date.now() - acpxStartedAt });
     } else {
       const runner = pickRunner(detected, preferType);
       for await (const event of runner(task))
@@ -6451,7 +6617,10 @@ ${userPart}` : userPart;
       await postComment(`\u26A0\uFE0F Agent returned no output (stopReason=${stopReason}). Adapter may be stuck on a stale session \u2014 try starting a new issue or clearing session_id.`);
       log(`  \u26A0 ${task.key} produced no assistant output (stopReason=${stopReason})`);
     }
-    if (hadError) {
+    if (ctx?.runEntry?.stopped) {
+      await markStopped(apiUrl, issueId, ctx.runEntry.stopReason || "stopped");
+      log(`  \u23F9 ${task.key} stopped`);
+    } else if (hadError) {
       await apiClient.post(`${apiUrl}/api/issues/${issueId}/fail`, {});
       log(`  \u2717 ${task.key} failed`);
     } else {
@@ -6459,10 +6628,15 @@ ${userPart}` : userPart;
       log(`  \u2713 ${task.key} complete`);
     }
   } catch (e) {
-    await postStream(apiUrl, issueId, "error", { message: String(e) });
-    await postComment(`\u274C spawn error: ${String(e)}`);
-    await apiClient.post(`${apiUrl}/api/issues/${issueId}/fail`, {});
-    log(`  \u2717 ${task.key} failed: ${String(e)}`);
+    if (ctx?.runEntry?.stopped) {
+      await markStopped(apiUrl, issueId, ctx.runEntry.stopReason || "stopped");
+      log(`  \u23F9 ${task.key} stopped (${String(e)})`);
+    } else {
+      await postStream(apiUrl, issueId, "error", { message: String(e) });
+      await postComment(`\u274C spawn error: ${String(e)}`);
+      await apiClient.post(`${apiUrl}/api/issues/${issueId}/fail`, {});
+      log(`  \u2717 ${task.key} failed: ${String(e)}`);
+    }
   }
 }
 async function buildPlanningPreamble(apiUrl, task) {
@@ -6634,29 +6808,36 @@ function statusIcon(status) {
   }
 }
 async function resolveAcpAdapter(agentType, detectedPath) {
-  if (agentType === "pi" && detectedPath && existsSync2(detectedPath)) {
+  if (agentType === "pi" && detectedPath && existsSync3(detectedPath)) {
     return [detectedPath, "--mode", "rpc"];
   }
   const adapterName = "claude-code-acp";
   const candidates = [
-    join2(HOME2, ".bun", "install", "global", "node_modules", ".bin", adapterName)
+    join3(HOME2, ".bun", "install", "global", "node_modules", ".bin", adapterName)
   ];
   try {
     const here = new URL(import.meta.url).pathname;
     let dir = here;
     for (let i = 0;i < 8; i++) {
       dir = dirname2(dir);
-      const bin = join2(dir, "node_modules", ".bin", adapterName);
-      if (existsSync2(bin))
+      const bin = join3(dir, "node_modules", ".bin", adapterName);
+      if (existsSync3(bin))
         return [bin];
     }
   } catch {}
   for (const c of candidates)
-    if (existsSync2(c))
+    if (existsSync3(c))
       return [c];
   return null;
 }
 async function postStream(apiUrl, issueId, event_type, payload) {
+  try {
+    ensureDirs();
+    const date = new Date().toISOString().slice(0, 10);
+    const path = join3(MULTI_DIR, "logs", `events-${date}.ndjson`);
+    appendFileSync2(path, JSON.stringify({ ts: Date.now(), issue_id: issueId, event_type, payload }) + `
+`);
+  } catch {}
   await apiClient.post(`${apiUrl}/api/streams/${issueId}`, { event_type, payload });
 }
 async function downloadCommentAttachments(apiUrl, commentId, destDir) {
@@ -6665,7 +6846,7 @@ async function downloadCommentAttachments(apiUrl, commentId, destDir) {
     const items = list.data?.results || list.data || [];
     if (!Array.isArray(items) || items.length === 0)
       return [];
-    mkdirSync2(destDir, { recursive: true });
+    mkdirSync3(destDir, { recursive: true });
     const token = authTokenHeader();
     const out = [];
     for (const it of items) {
@@ -6674,8 +6855,8 @@ async function downloadCommentAttachments(apiUrl, commentId, destDir) {
         continue;
       const buf = new Uint8Array(await res.arrayBuffer());
       const safe = it.filename.replace(/[^A-Za-z0-9._-]/g, "_");
-      const p = join2(destDir, safe);
-      writeFileSync2(p, buf);
+      const p = join3(destDir, safe);
+      writeFileSync3(p, buf);
       out.push({ filename: it.filename, path: p });
     }
     return out;
@@ -6688,14 +6869,14 @@ function authTokenHeader() {
   return cfg.token ? `Bearer ${cfg.token}` : null;
 }
 async function uploadOutputDir(apiUrl, commentId, dir) {
-  if (!existsSync2(dir))
+  if (!existsSync3(dir))
     return 0;
   const files = [];
   const walk = (d, depth = 0) => {
     if (depth > 3)
       return;
     for (const name of readdirSync(d)) {
-      const p = join2(d, name);
+      const p = join3(d, name);
       try {
         const st = statSync(p);
         if (st.isDirectory())
@@ -6712,7 +6893,7 @@ async function uploadOutputDir(apiUrl, commentId, dir) {
   let uploaded = 0;
   for (const f of files) {
     try {
-      const data = readFileSync2(f);
+      const data = readFileSync3(f);
       const form = new FormData;
       const blob = new Blob([data]);
       form.append("file", blob, f.split("/").pop() || "file");
@@ -6939,7 +7120,7 @@ async function cmdStatus(apiUrl, config) {
     process.exit(1);
   }
   const d = res.data;
-  const pid = existsSync2(PID_PATH) ? readFileSync2(PID_PATH, "utf8").trim() : null;
+  const pid = existsSync3(PID_PATH) ? readFileSync3(PID_PATH, "utf8").trim() : null;
   const daemon = pid && isRunning(Number(pid)) ? `running (pid ${pid})` : "stopped";
   console.log(`
 Device Status
@@ -6953,29 +7134,29 @@ Daemon:    ${daemon}
 `);
 }
 async function cmdStop() {
-  if (!existsSync2(PID_PATH)) {
+  if (!existsSync3(PID_PATH)) {
     console.log("No daemon running.");
     return;
   }
-  const pid = Number(readFileSync2(PID_PATH, "utf8").trim());
+  const pid = Number(readFileSync3(PID_PATH, "utf8").trim());
   if (!pid || !isRunning(pid)) {
     unlinkSync(PID_PATH);
     console.log("Cleaned stale pidfile.");
     return;
   }
   ensureDirs();
-  writeFileSync2(STOP_PATH, "1");
+  writeFileSync3(STOP_PATH, "1");
   try {
     process.kill(pid, "SIGTERM");
     console.log(`Sent SIGTERM to ${pid}`);
   } catch {}
 }
 async function cmdLogs() {
-  if (!existsSync2(LOG_PATH2)) {
+  if (!existsSync3(LOG_PATH2)) {
     console.log("No logs yet.");
     return;
   }
-  const content = readFileSync2(LOG_PATH2, "utf8");
+  const content = readFileSync3(LOG_PATH2, "utf8");
   console.log(content.split(`
 `).slice(-100).join(`
 `));
@@ -6994,7 +7175,7 @@ function openTasksDb() {
   db.exec(`
     CREATE TABLE IF NOT EXISTS tasks (
       id TEXT PRIMARY KEY,
-      status TEXT NOT NULL DEFAULT 'pending',
+      status TEXT NOT NULL DEFAULT 'queued',
       payload TEXT NOT NULL,
       attempts INTEGER NOT NULL DEFAULT 0,
       created_at INTEGER NOT NULL DEFAULT (unixepoch()),
@@ -7004,20 +7185,31 @@ function openTasksDb() {
     );
     CREATE INDEX IF NOT EXISTS idx_tasks_status ON tasks(status);
   `);
+  const cols = db.query("PRAGMA table_info(tasks)").all();
+  const have = new Set(cols.map((c) => c.name));
+  if (!have.has("agent_id"))
+    db.exec("ALTER TABLE tasks ADD COLUMN agent_id TEXT");
+  if (!have.has("issue_id"))
+    db.exec("ALTER TABLE tasks ADD COLUMN issue_id TEXT");
+  db.exec(`
+    CREATE INDEX IF NOT EXISTS idx_tasks_agent ON tasks(agent_id, status);
+    CREATE INDEX IF NOT EXISTS idx_tasks_issue ON tasks(issue_id);
+  `);
+  db.run("UPDATE tasks SET status = 'queued' WHERE status = 'pending'");
   return db;
 }
 function loadConfig() {
   try {
-    if (!existsSync2(CONFIG_PATH))
+    if (!existsSync3(CONFIG_PATH))
       return {};
-    return JSON.parse(readFileSync2(CONFIG_PATH, "utf8"));
+    return JSON.parse(readFileSync3(CONFIG_PATH, "utf8"));
   } catch {
     return {};
   }
 }
 function saveConfig(config) {
   ensureDirs();
-  writeFileSync2(CONFIG_PATH, JSON.stringify(config, null, 2));
+  writeFileSync3(CONFIG_PATH, JSON.stringify(config, null, 2));
 }
 function sleep(ms) {
   return new Promise((r) => setTimeout(r, ms));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipers-dev/multi",
-  "version": "0.8.3",
+  "version": "0.9.0",
   "type": "module",
   "bin": {
     "multi-agent": "./dist/index.js"

package/src/acp-runner.ts

@@ -27,6 +27,7 @@ export type AcpRunOpts = {
   autonomy?: 'manual' | 'ask' | 'auto';
   onEvent: (ev: AcpEvent) => void | Promise<void>;
   onSession?: (sessionId: string) => void | Promise<void>;
+  onSpawn?: (child: any) => void;
 };
 
 export async function runAcp(opts: AcpRunOpts): Promise<{ stopReason: string; sessionId: string }> {
@@ -45,6 +46,7 @@ export async function runAcp(opts: AcpRunOpts): Promise<{ stopReason: string; se
     cwd: opts.cwd || process.cwd(),
     env: { ...cleanEnv, ACP_PERMISSION_MODE: permMode },
   });
+  try { opts.onSpawn?.(child); } catch {}
 
   // Adapter expects plain newline-delimited JSON on stdio. Wrap child streams as Web Streams.
   const output = new WritableStream<Uint8Array>({

package/src/acpx-runner.ts

@@ -21,6 +21,7 @@ export interface AcpxRunOpts {
   cwd?: string;
   sessionName?: string; // reuse same session across follow-ups (e.g. "issue-<id>")
   onEvent: (ev: AcpEvent) => void | Promise<void>;
+  onSpawn?: (child: any) => void;
 }
 
 export async function runAcpx(opts: AcpxRunOpts): Promise<{ stopReason: string }> {
@@ -49,6 +50,7 @@ export async function runAcpx(opts: AcpxRunOpts): Promise<{ stopReason: string }
 
   dlog(`[acpx] prompt: ${args.slice(0, 10).join(' ')} ... (prompt len=${opts.prompt.length})`);
   const proc = Bun.spawn(args, { stdout: 'pipe', stderr: 'pipe', stdin: 'ignore' });
+  try { opts.onSpawn?.(proc); } catch {}
   let stopReason = 'end_turn';
 
   // Forward stderr to our progress stream so we can debug in the UI/logs

package/src/index.ts

@@ -5,6 +5,7 @@ import { apiClient, setAuthToken } from './client';
 import { Database } from 'bun:sqlite';
 import { runAcp } from './acp-runner';
 import { runAcpx } from './acpx-runner';
+import { ensureWorktree } from './worktree';
 import { parseArgs } from 'util';
 import { mkdirSync, existsSync, writeFileSync, readFileSync, appendFileSync, unlinkSync, readdirSync, statSync } from 'fs';
 import { join, dirname } from 'path';
@@ -252,10 +253,44 @@ async function cmdConnect(apiUrl: string, config: Config) {
   const db = openTasksDb();
 
   // Requeue orphaned 'running' tasks from previous crash
-  db.run("UPDATE tasks SET status = 'pending' WHERE status = 'running'");
+  db.run("UPDATE tasks SET status = 'queued' WHERE status = 'running'");
+
+  const MAX_DEVICE = Math.max(1, parseInt(process.env.MULTI_MAX_CONCURRENT ?? '3', 10) || 3);
+  const running = new Map<string, RunEntry>();
+
+  function pickNext(): { id: string; payload: string; agent_id: string | null; issue_id: string | null } | null {
+    const busyAgents = Array.from(running.values()).map((e) => e.agentId).filter(Boolean) as string[];
+    // Emulate NOT IN (:list) via string construction (safe: only ids from DB).
+    const notIn = busyAgents.length
+      ? `AND (agent_id IS NULL OR agent_id NOT IN (${busyAgents.map(() => '?').join(',')}))`
+      : '';
+    const sql = `SELECT id, payload, agent_id, issue_id FROM tasks WHERE status = 'queued' ${notIn} ORDER BY created_at ASC LIMIT 1`;
+    return db.query(sql).get(...busyAgents) as any;
+  }
 
-  let workerWake: (() => void) | null = null;
-  const notifyWorker = () => { try { workerWake?.(); workerWake = null; } catch {} };
+  function schedule() {
+    while (running.size < MAX_DEVICE) {
+      const row = pickNext();
+      if (!row) return;
+      db.run("UPDATE tasks SET status = 'running', started_at = unixepoch(), attempts = attempts + 1 WHERE id = ?", [row.id]);
+      const entry: RunEntry = { agentId: row.agent_id || '', startedAt: Date.now(), child: null, worktreePath: '' };
+      const issueKey = row.issue_id || row.id;
+      running.set(issueKey, entry);
+      void (async () => {
+        try {
+          const task = JSON.parse(row.payload);
+          await handleRunTask(apiUrl, config.deviceId!, task, detected, { runEntry: entry });
+          db.run("UPDATE tasks SET status = 'done', finished_at = unixepoch() WHERE id = ?", [row.id]);
+        } catch (e) {
+          log(`task ${row.id} error: ${String(e)}`);
+          db.run("UPDATE tasks SET status = 'failed', finished_at = unixepoch(), error = ? WHERE id = ?", [String(e), row.id]);
+        } finally {
+          running.delete(issueKey);
+          queueMicrotask(() => schedule());
+        }
+      })();
+    }
+  }
 
 
   // Local HTTP server on a free port
@@ -271,15 +306,45 @@ async function cmdConnect(apiUrl: string, config: Config) {
         return (async () => {
           try {
             const body = await req.json() as { task: any };
-            const taskId = body?.task?.issue_id ? `${body.task.issue_id}-${Date.now()}` : crypto.randomUUID();
-            db.run('INSERT INTO tasks (id, status, payload) VALUES (?, ?, ?)', [taskId, 'pending', JSON.stringify(body.task)]);
-            notifyWorker();
+            const t = body?.task || {};
+            const taskId = t.issue_id ? `${t.issue_id}-${Date.now()}` : crypto.randomUUID();
+            db.run(
+              "INSERT INTO tasks (id, status, payload, agent_id, issue_id) VALUES (?, 'queued', ?, ?, ?)",
+              [taskId, JSON.stringify(t), t.agent_id ?? null, t.issue_id ?? null],
+            );
+            const pos = (db.query("SELECT COUNT(*) AS c FROM tasks WHERE status = 'queued' AND created_at <= (SELECT created_at FROM tasks WHERE id = ?)").get(taskId) as any)?.c ?? 1;
+            if (t.issue_id) {
+              void postStream(apiUrl, t.issue_id, 'queued', { queue_position: pos });
+            }
+            queueMicrotask(() => schedule());
             return Response.json({ accepted: true, task_id: taskId }, { status: 202 });
           } catch (e) {
             return Response.json({ error: String(e) }, { status: 400 });
           }
         })();
       }
+      if (url.pathname === '/stop' && req.method === 'POST') {
+        if (req.headers.get('authorization') !== expectedAuth) return new Response('unauthorized', { status: 401 });
+        return (async () => {
+          try {
+            const { issue_id } = await req.json() as { issue_id: string };
+            if (!issue_id) return Response.json({ error: 'issue_id required' }, { status: 400 });
+            const entry = running.get(issue_id);
+            if (!entry) {
+              db.run("UPDATE tasks SET status = 'failed', error = 'stopped before start', finished_at = unixepoch() WHERE issue_id = ? AND status = 'queued'", [issue_id]);
+              await markStopped(apiUrl, issue_id, 'stopped before start');
+              return Response.json({ ok: true, state: 'queued-cancelled' });
+            }
+            entry.stopped = true;
+            entry.stopReason = 'user requested';
+            try { entry.child?.kill('SIGTERM'); } catch {}
+            setTimeout(() => { try { entry.child?.kill('SIGKILL'); } catch {} }, 5000);
+            return Response.json({ ok: true, state: 'running-signalled' });
+          } catch (e) {
+            return Response.json({ error: String(e) }, { status: 400 });
+          }
+        })();
+      }
       return new Response('not found', { status: 404 });
     },
   });
@@ -300,11 +365,11 @@ async function cmdConnect(apiUrl: string, config: Config) {
 
   await apiClient.post(`${apiUrl}/api/devices/${config.deviceId}/heartbeat`, { status: 'online', tunnel_url: tunnelUrl });
 
-  let running = true;
+  let alive = true;
 
   const shutdown = async (reason: string) => {
-    if (!running) return;
-    running = false;
+    if (!alive) return;
+    alive = false;
     log(`🛑 Shutting down (${reason})`);
     try { server.stop(); } catch {}
     try { cf.kill(); } catch {}
@@ -318,28 +383,11 @@ async function cmdConnect(apiUrl: string, config: Config) {
   process.on('SIGINT', () => shutdown('SIGINT'));
   process.on('SIGTERM', () => shutdown('SIGTERM'));
 
-  // Worker loop: drain pending tasks
-  (async () => {
-    while (running) {
-      const row = db.query("SELECT id, payload FROM tasks WHERE status = 'pending' ORDER BY created_at ASC LIMIT 1").get() as { id: string; payload: string } | null;
-      if (!row) {
-        await new Promise<void>(resolve => { workerWake = resolve; setTimeout(resolve, 5000); });
-        continue;
-      }
-      db.run("UPDATE tasks SET status = 'running', started_at = unixepoch(), attempts = attempts + 1 WHERE id = ?", [row.id]);
-      try {
-        const task = JSON.parse(row.payload);
-        await handleRunTask(apiUrl, config.deviceId!, task, detected, {});
-        db.run("UPDATE tasks SET status = 'done', finished_at = unixepoch() WHERE id = ?", [row.id]);
-      } catch (e) {
-        log(`task ${row.id} error: ${String(e)}`);
-        db.run("UPDATE tasks SET status = 'failed', finished_at = unixepoch(), error = ? WHERE id = ?", [String(e), row.id]);
-      }
-    }
-  })();
+  // Kick the scheduler on startup to drain any leftover queued rows.
+  schedule();
 
   // Heartbeat loop
-  while (running) {
+  while (alive) {
     await sleep(20000);
     if (existsSync(STOP_PATH)) { await shutdown('stop flag'); break; }
     try {
@@ -407,15 +455,52 @@ async function parseTunnelUrl(stream: ReadableStream<Uint8Array>): Promise<strin
   return null;
 }
 
+interface RunEntry {
+  agentId: string;
+  startedAt: number;
+  child: any | null;
+  worktreePath: string;
+  stopped?: boolean;
+  stopReason?: string;
+}
+
 interface RuntimeCtx {
-  // Reserved for future runtime-scoped helpers.
+  runEntry?: RunEntry;
+  refreshLocalAgents?: () => Promise<void>;
+}
+
+async function markStopped(apiUrl: string, issueId: string, reason: string) {
+  try {
+    await apiClient.patch(`${apiUrl}/api/issues/${issueId}`, { status: 'stopped' });
+  } catch {}
+  try {
+    await apiClient.post(`${apiUrl}/api/issues/${issueId}/comments`, {
+      author_type: 'agent', author_id: 'daemon', author_name: 'daemon', body: `⏹ Stopped: ${reason}`,
+    });
+  } catch {}
+  await postStream(apiUrl, issueId, 'stopped', { reason });
 }
 
 async function handleRunTask(apiUrl: string, deviceId: string, task: any, detected: { type: string; path: string }[], ctx?: RuntimeCtx) {
   const issueId = task.issue_id;
   const isFollowup = !!task.followup;
-  const workingDir = task.working_dir && existsSync(task.working_dir) ? task.working_dir : undefined;
-  log(`▶ run_task ${task.key}: ${isFollowup ? '(follow-up) ' : ''}${task.title}${workingDir ? ` [cwd: ${workingDir}]` : ''}`);
+  const baseWorkingDir = task.working_dir && existsSync(task.working_dir) ? task.working_dir : undefined;
+
+  // Per-issue worktree isolation. Falls back to baseWorkingDir on failure or non-git.
+  let workingDir = baseWorkingDir;
+  let worktreeBranch = '';
+  if (baseWorkingDir) {
+    try {
+      const wt = await ensureWorktree(baseWorkingDir, task.key || issueId);
+      workingDir = wt.path;
+      worktreeBranch = wt.branch;
+      await postStream(apiUrl, issueId, 'worktree_created', { path: wt.path, branch: wt.branch, reused: !wt.created });
+    } catch (e) {
+      await postStream(apiUrl, issueId, 'worktree_error', { message: String(e) });
+    }
+  }
+
+  log(`▶ run_task ${task.key}: ${isFollowup ? '(follow-up) ' : ''}${task.title}${workingDir ? ` [cwd: ${workingDir}${worktreeBranch ? ` @${worktreeBranch}` : ''}]` : ''}`);
 
   await apiClient.patch(`${apiUrl}/api/issues/${issueId}`, { status: 'in_progress' });
   await postStream(apiUrl, issueId, 'progress', { message: `Device ${deviceId} picked up ${isFollowup ? 'follow-up' : 'task'}` });
@@ -678,6 +763,7 @@ async function handleRunTask(apiUrl: string, deviceId: string, task: any, detect
       if (!adapterBin) throw new Error(`ACP adapter for ${chosen.type} not found`);
       log(`  adapter: ${chosen.type} → ${adapterBin.join(' ')}`);
 
+      const startedAt = Date.now();
       const { sessionId } = await runAcp({
         apiUrl, issueId, deviceId, prompt,
         sessionId: task.session_id || null,
@@ -688,7 +774,15 @@ async function handleRunTask(apiUrl: string, deviceId: string, task: any, detect
         onSession: async (sid) => {
           try { await apiClient.post(`${apiUrl}/api/issues/${issueId}/session`, { session_id: sid }); } catch {}
         },
+        onSpawn: (child) => {
+          if (ctx?.runEntry) {
+            ctx.runEntry.child = child;
+            ctx.runEntry.worktreePath = workingDir || '';
+          }
+          void postStream(apiUrl, issueId, 'run_started', { pid: child?.pid, worktree_path: workingDir, branch: worktreeBranch, adapter: chosen.type });
+        },
       });
+      void postStream(apiUrl, issueId, 'run_finished', { stopReason: (typeof sessionId === 'string' ? 'ok' : 'unknown'), duration_ms: Date.now() - startedAt });
       log(`  acp session ${sessionId.slice(0, 8)}`);
     } else if (useAcpx) {
       // Build prompt with preamble (same logic as ACP path, but as one string)
@@ -724,13 +818,22 @@ async function handleRunTask(apiUrl: string, deviceId: string, task: any, detect
       }
       const full = preamble ? `${preamble}\n---\n\n${userPart}` : userPart;
       log(`  acpx runner: ${preferType}`);
+      const acpxStartedAt = Date.now();
       await runAcpx({
         agentType: preferType!,
         prompt: full,
         cwd: workingDir,
         sessionName: `issue-${issueId}`,
         onEvent: eventHandler,
+        onSpawn: (child) => {
+          if (ctx?.runEntry) {
+            ctx.runEntry.child = child;
+            ctx.runEntry.worktreePath = workingDir || '';
+          }
+          void postStream(apiUrl, issueId, 'run_started', { pid: child?.pid, worktree_path: workingDir, branch: worktreeBranch, adapter: preferType });
+        },
       });
+      void postStream(apiUrl, issueId, 'run_finished', { stopReason: 'ok', duration_ms: Date.now() - acpxStartedAt });
     } else {
       const runner = pickRunner(detected, preferType);
       for await (const event of runner(task)) await eventHandler(event);
@@ -761,13 +864,21 @@ async function handleRunTask(apiUrl: string, deviceId: string, task: any, detect
       log(`  ⚠ ${task.key} produced no assistant output (stopReason=${stopReason})`);
     }
 
-    if (hadError) { await apiClient.post(`${apiUrl}/api/issues/${issueId}/fail`, {}); log(`  ✗ ${task.key} failed`); }
+    if (ctx?.runEntry?.stopped) {
+      await markStopped(apiUrl, issueId, ctx.runEntry.stopReason || 'stopped');
+      log(`  ⏹ ${task.key} stopped`);
+    } else if (hadError) { await apiClient.post(`${apiUrl}/api/issues/${issueId}/fail`, {}); log(`  ✗ ${task.key} failed`); }
     else { await apiClient.post(`${apiUrl}/api/issues/${issueId}/complete`, {}); log(`  ✓ ${task.key} complete`); }
   } catch (e) {
-    await postStream(apiUrl, issueId, 'error', { message: String(e) });
-    await postComment(`❌ spawn error: ${String(e)}`);
-    await apiClient.post(`${apiUrl}/api/issues/${issueId}/fail`, {});
-    log(`  ✗ ${task.key} failed: ${String(e)}`);
+    if (ctx?.runEntry?.stopped) {
+      await markStopped(apiUrl, issueId, ctx.runEntry.stopReason || 'stopped');
+      log(`  ⏹ ${task.key} stopped (${String(e)})`);
+    } else {
+      await postStream(apiUrl, issueId, 'error', { message: String(e) });
+      await postComment(`❌ spawn error: ${String(e)}`);
+      await apiClient.post(`${apiUrl}/api/issues/${issueId}/fail`, {});
+      log(`  ✗ ${task.key} failed: ${String(e)}`);
+    }
   }
 }
 
@@ -957,6 +1068,13 @@ async function resolveAcpAdapter(agentType: string, detectedPath?: string): Prom
 }
 
 async function postStream(apiUrl: string, issueId: string, event_type: string, payload: any) {
+  // Local ndjson sink for tail -f debugging.
+  try {
+    ensureDirs();
+    const date = new Date().toISOString().slice(0, 10);
+    const path = join(MULTI_DIR, 'logs', `events-${date}.ndjson`);
+    appendFileSync(path, JSON.stringify({ ts: Date.now(), issue_id: issueId, event_type, payload }) + '\n');
+  } catch {}
   await apiClient.post(`${apiUrl}/api/streams/${issueId}`, { event_type, payload });
 }
 
@@ -1260,7 +1378,7 @@ function openTasksDb(): Database {
   db.exec(`
     CREATE TABLE IF NOT EXISTS tasks (
       id TEXT PRIMARY KEY,
-      status TEXT NOT NULL DEFAULT 'pending',
+      status TEXT NOT NULL DEFAULT 'queued',
       payload TEXT NOT NULL,
       attempts INTEGER NOT NULL DEFAULT 0,
       created_at INTEGER NOT NULL DEFAULT (unixepoch()),
@@ -1270,6 +1388,17 @@ function openTasksDb(): Database {
     );
     CREATE INDEX IF NOT EXISTS idx_tasks_status ON tasks(status);
   `);
+  // Idempotent migrations: add agent_id/issue_id columns if missing.
+  const cols = db.query("PRAGMA table_info(tasks)").all() as { name: string }[];
+  const have = new Set(cols.map((c) => c.name));
+  if (!have.has('agent_id')) db.exec('ALTER TABLE tasks ADD COLUMN agent_id TEXT');
+  if (!have.has('issue_id')) db.exec('ALTER TABLE tasks ADD COLUMN issue_id TEXT');
+  db.exec(`
+    CREATE INDEX IF NOT EXISTS idx_tasks_agent ON tasks(agent_id, status);
+    CREATE INDEX IF NOT EXISTS idx_tasks_issue ON tasks(issue_id);
+  `);
+  // Old rows used 'pending'; normalize to 'queued'.
+  db.run("UPDATE tasks SET status = 'queued' WHERE status = 'pending'");
   return db;
 }
 

package/src/worktree.ts

@@ -0,0 +1,89 @@
+// Per-issue git worktree manager. Keeps agent work isolated so parallel runs
+// don't clobber each other. Worktrees live at <workingDir>/.multi/worktrees/<key>
+// on branch multi/<key>, created off the current HEAD of workingDir.
+//
+// No automatic teardown: branch + worktree are kept after done/fail for human
+// review.
+
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+export interface Worktree {
+  path: string;
+  branch: string;
+  created: boolean;
+}
+
+async function run(cwd: string, cmd: string, args: string[]): Promise<{ code: number; stdout: string; stderr: string }> {
+  return await new Promise((resolve) => {
+    const p = spawn(cmd, args, { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    p.stdout.on('data', (d) => { stdout += d.toString(); });
+    p.stderr.on('data', (d) => { stderr += d.toString(); });
+    p.on('close', (code) => resolve({ code: code ?? 0, stdout: stdout.trim(), stderr: stderr.trim() }));
+    p.on('error', (e) => resolve({ code: 1, stdout: '', stderr: String(e) }));
+  });
+}
+
+export async function isGitRepo(dir: string): Promise<boolean> {
+  if (!existsSync(dir)) return false;
+  const r = await run(dir, 'git', ['rev-parse', '--is-inside-work-tree']);
+  return r.code === 0 && r.stdout === 'true';
+}
+
+async function branchExists(dir: string, branch: string): Promise<boolean> {
+  const r = await run(dir, 'git', ['rev-parse', '--verify', '--quiet', `refs/heads/${branch}`]);
+  return r.code === 0;
+}
+
+function ensureGitignoreEntry(workingDir: string, entry: string): void {
+  const gip = join(workingDir, '.gitignore');
+  let body = '';
+  try { body = existsSync(gip) ? readFileSync(gip, 'utf8') : ''; } catch { body = ''; }
+  const lines = body.split('\n');
+  if (lines.some((l) => l.trim() === entry)) return;
+  const nextBody = (body.endsWith('\n') || body === '' ? body : body + '\n') + entry + '\n';
+  try { writeFileSync(gip, nextBody, 'utf8'); } catch {}
+}
+
+function normalizeKey(issueKey: string): string {
+  return issueKey.toLowerCase().replace(/[^a-z0-9\-_\/]/g, '-');
+}
+
+/**
+ * Ensure a worktree exists for this issue. Safe to call repeatedly.
+ *
+ * - Non-git workingDir: returns { path: workingDir, created: false } (no isolation).
+ * - Git workingDir: creates or reuses <workingDir>/.multi/worktrees/<key>
+ *   on branch multi/<key>. On failure returns workingDir fallback.
+ */
+export async function ensureWorktree(workingDir: string, issueKey: string): Promise<Worktree> {
+  if (!(await isGitRepo(workingDir))) {
+    return { path: workingDir, branch: '', created: false };
+  }
+
+  ensureGitignoreEntry(workingDir, '.multi/');
+
+  const key = normalizeKey(issueKey);
+  const branch = `multi/${key}`;
+  const wtDir = join(workingDir, '.multi', 'worktrees');
+  const wtPath = join(wtDir, key);
+
+  if (existsSync(wtPath)) {
+    return { path: wtPath, branch, created: false };
+  }
+
+  try { mkdirSync(wtDir, { recursive: true }); } catch {}
+
+  const exists = await branchExists(workingDir, branch);
+  const args = exists
+    ? ['worktree', 'add', wtPath, branch]
+    : ['worktree', 'add', '-b', branch, wtPath, 'HEAD'];
+  const r = await run(workingDir, 'git', args);
+  if (r.code !== 0) {
+    throw new Error(`git worktree add failed: ${r.stderr || r.stdout}`);
+  }
+  return { path: wtPath, branch, created: true };
+}