@shipers-dev/multi 0.17.2 → 0.20.0

package/README.md

@@ -0,0 +1,47 @@
+# @shipers-dev/multi
+
+CLI daemon (`multi-agent`) that pairs a device with a Multi workspace and runs assigned issues via ACP / acpx adapters.
+
+## Install
+
+```bash
+bun add -g @shipers-dev/multi
+# or
+npm i -g @shipers-dev/multi
+```
+
+## Quick start
+
+```bash
+multi-agent setup            # pair the device against prod
+multi-agent start            # foreground daemon
+multi-agent start -d         # detached
+multi-agent status
+multi-agent logs
+```
+
+## Pointing at a local API worker
+
+For local development against a wrangler-dev API worker, set `MULTI_API` to its base URL:
+
+```bash
+MULTI_API=http://localhost:8787 multi-agent setup
+MULTI_API=http://localhost:8787 multi-agent start
+```
+
+The resolved API base URL is printed at start. When the host is `localhost` / `127.0.0.1` / `[::1]`, the daemon:
+
+- skips spawning `cloudflared` (no quick-tunnel),
+- advertises `http://127.0.0.1:<port>` as its push endpoint, so the local worker can reach the daemon directly over loopback,
+- skips the tunnel self-heal + DNS probe loops.
+
+`MULTI_API_URL` is still accepted as a fallback alias. CLI flag `--api <url>` overrides both.
+
+## Common env vars
+
+| Var | Purpose |
+| --- | --- |
+| `MULTI_API` | API base URL (default `https://multi-api.adnb3r.workers.dev`) |
+| `MULTI_MAX_CONCURRENT` | Max concurrent tasks per device (default 3) |
+| `MULTI_TUNNEL_NAME` | Use a named cloudflared tunnel instead of quick tunnel |
+| `MULTI_TUNNEL_HOSTNAME` | Public hostname routed to the named tunnel |

package/dist/index.js

@@ -16071,9 +16071,86 @@ var StreamEventInputSchema = exports_external.object({
   event_type: StreamEventTypeSchema,
   payload: exports_external.unknown().optional()
 });
+// ../lib/memory.ts
+var MEMORY_ENTRY_KINDS = ["fact", "event", "instruction", "task"];
+var MemoryEntryKindSchema = exports_external.enum(MEMORY_ENTRY_KINDS);
+var MemoryEntrySchema = exports_external.object({
+  id: exports_external.string(),
+  project_id: exports_external.string(),
+  issue_id: exports_external.string().nullable().optional(),
+  kind: MemoryEntryKindSchema,
+  text: exports_external.string(),
+  source_event_id: exports_external.string().nullable().optional(),
+  source_comment_id: exports_external.string().nullable().optional(),
+  score: exports_external.number().optional(),
+  created_at: exports_external.number()
+});
+var MemoryCitationSchema = exports_external.object({
+  entry_id: exports_external.string(),
+  kind: MemoryEntryKindSchema,
+  issue_id: exports_external.string().nullable().optional(),
+  comment_id: exports_external.string().nullable().optional(),
+  snippet: exports_external.string(),
+  score: exports_external.number().optional()
+});
+var MemoryRecallRequestSchema = exports_external.object({
+  project_id: exports_external.string().min(1),
+  issue_id: exports_external.string().optional(),
+  query: exports_external.string().min(1),
+  k: exports_external.number().int().min(1).max(50).optional()
+});
+var MemoryRecallResponseSchema = exports_external.object({
+  synthesis: exports_external.string(),
+  citations: exports_external.array(MemoryCitationSchema),
+  entries: exports_external.array(MemoryEntrySchema)
+});
+var StreamSourceKind = exports_external.enum(["assistant_text", "result"]);
+var IngestBase = exports_external.object({
+  project_id: exports_external.string().min(1),
+  issue_id: exports_external.string().min(1),
+  ts: exports_external.number().int()
+});
+var MemoryIngestAssistantTextSchema = IngestBase.extend({
+  kind: exports_external.literal("assistant_text"),
+  event_id: exports_external.string(),
+  text: exports_external.string(),
+  final: exports_external.literal(true)
+});
+var MemoryIngestResultSchema = IngestBase.extend({
+  kind: exports_external.literal("result"),
+  event_id: exports_external.string(),
+  text: exports_external.string(),
+  status: exports_external.enum(["success", "error", "stopped"]).optional()
+});
+var MemoryIngestHumanCommentSchema = IngestBase.extend({
+  kind: exports_external.literal("human_comment"),
+  comment_id: exports_external.string(),
+  author_id: exports_external.string(),
+  body: exports_external.string()
+});
+var MemoryIngestIssueChangedSchema = IngestBase.extend({
+  kind: exports_external.literal("issue_changed"),
+  field: exports_external.enum(["title", "description"]),
+  before: exports_external.string().nullable(),
+  after: exports_external.string().nullable(),
+  actor_id: exports_external.string()
+});
+var MemoryIngestEventSchema = exports_external.discriminatedUnion("kind", [
+  MemoryIngestAssistantTextSchema,
+  MemoryIngestResultSchema,
+  MemoryIngestHumanCommentSchema,
+  MemoryIngestIssueChangedSchema
+]);
+var MemoryIngestRequestSchema = exports_external.object({
+  events: exports_external.array(MemoryIngestEventSchema).min(1).max(100)
+});
+var MemoryIngestResponseSchema = exports_external.object({
+  accepted: exports_external.number().int().nonnegative(),
+  rejected: exports_external.number().int().nonnegative()
+});
 // src/worktree.ts
 import { spawn } from "child_process";
-import { existsSync as existsSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2, mkdirSync as mkdirSync2, symlinkSync } from "fs";
+import { existsSync as existsSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2, mkdirSync as mkdirSync2, symlinkSync, rmSync } from "fs";
 import { dirname as dirname2, join as join3, resolve } from "path";
 async function run(cwd, cmd, args) {
   return await new Promise((resolve2) => {
@@ -16100,6 +16177,14 @@ async function branchExists(dir, branch) {
   const r = await run(dir, "git", ["rev-parse", "--verify", "--quiet", `refs/heads/${branch}`]);
   return r.code === 0;
 }
+async function hasOriginRemote(dir) {
+  const r = await run(dir, "git", ["remote", "get-url", "origin"]);
+  return r.code === 0 && !!r.stdout;
+}
+async function isDirty(dir) {
+  const r = await run(dir, "git", ["status", "--porcelain"]);
+  return r.code === 0 && r.stdout.length > 0;
+}
 function ensureGitignoreEntry(workingDir, entry) {
   const gip = join3(workingDir, ".gitignore");
   let body = "";
@@ -16123,7 +16208,45 @@ function ensureGitignoreEntry(workingDir, entry) {
 function normalizeKey(issueKey) {
   return issueKey.toLowerCase().replace(/[^a-z0-9\-_\/]/g, "-");
 }
-async function ensureWorktree(workingDir, issueKey) {
+function indexPath(workingDir) {
+  return join3(workingDir, ".multi", "worktrees", "_index.json");
+}
+function readIndex(workingDir) {
+  try {
+    const p = indexPath(workingDir);
+    if (!existsSync2(p))
+      return {};
+    return JSON.parse(readFileSync2(p, "utf8"));
+  } catch {
+    return {};
+  }
+}
+function writeIndex(workingDir, idx) {
+  try {
+    const p = indexPath(workingDir);
+    mkdirSync2(dirname2(p), { recursive: true });
+    writeFileSync2(p, JSON.stringify(idx, null, 2), "utf8");
+  } catch {}
+}
+function listWorktreeIndex(workingDir) {
+  const idx = readIndex(workingDir);
+  return Object.entries(idx).map(([key, issueId]) => ({ key, issueId }));
+}
+function removeWorktreeIndexEntry(workingDir, key) {
+  const idx = readIndex(workingDir);
+  if (key in idx) {
+    delete idx[key];
+    writeIndex(workingDir, idx);
+  }
+}
+function setWorktreeIndexEntry(workingDir, key, issueId) {
+  const idx = readIndex(workingDir);
+  if (idx[key] === issueId)
+    return;
+  idx[key] = issueId;
+  writeIndex(workingDir, idx);
+}
+async function ensureWorktree(workingDir, issueKey, issueId) {
   if (!await isGitRepo(workingDir)) {
     return { path: workingDir, branch: "", created: false };
   }
@@ -16133,6 +16256,8 @@ async function ensureWorktree(workingDir, issueKey) {
   const wtDir = join3(workingDir, ".multi", "worktrees");
   const wtPath = join3(wtDir, key);
   if (existsSync2(wtPath)) {
+    if (issueId)
+      setWorktreeIndexEntry(workingDir, key, issueId);
     return { path: wtPath, branch, created: false };
   }
   try {
@@ -16145,6 +16270,8 @@ async function ensureWorktree(workingDir, issueKey) {
     throw new Error(`git worktree add failed: ${r.stderr || r.stdout}`);
   }
   await linkIgnoredFiles(workingDir, wtPath);
+  if (issueId)
+    setWorktreeIndexEntry(workingDir, key, issueId);
   return { path: wtPath, branch, created: true };
 }
 async function linkIgnoredFiles(workingDir, wtPath) {
@@ -16177,9 +16304,61 @@ async function linkIgnoredFiles(workingDir, wtPath) {
     } catch {}
   }
 }
+async function removeWorktree(workingDir, issueKey, opts = {}) {
+  const result = { removedPath: false, pushed: false, skipped: null, errors: [] };
+  if (!await isGitRepo(workingDir)) {
+    result.skipped = "not_git";
+    return result;
+  }
+  const key = normalizeKey(issueKey);
+  const branch = `multi/${key}`;
+  const wtPath = join3(workingDir, ".multi", "worktrees", key);
+  if (existsSync2(wtPath)) {
+    const dirty = await isDirty(wtPath);
+    if (dirty && !opts.force) {
+      result.skipped = "dirty";
+      return result;
+    }
+  }
+  const noPush = opts.noPush || process.env.MULTI_GC_NO_PUSH === "1";
+  if (!noPush) {
+    if (await branchExists(workingDir, branch)) {
+      if (await hasOriginRemote(workingDir)) {
+        const push = await run(workingDir, "git", ["push", "--force-with-lease", "origin", `${branch}:${branch}`]);
+        if (push.code === 0) {
+          result.pushed = true;
+        } else {
+          result.errors.push(`push failed: ${push.stderr || push.stdout}`);
+        }
+      } else {
+        result.errors.push("no origin remote, skipped push");
+      }
+    }
+  }
+  await run(workingDir, "git", ["worktree", "prune"]);
+  if (existsSync2(wtPath)) {
+    const rm = await run(workingDir, "git", ["worktree", "remove", "--force", wtPath]);
+    if (rm.code === 0) {
+      result.removedPath = true;
+    } else {
+      result.errors.push(`worktree remove failed: ${rm.stderr || rm.stdout}`);
+      try {
+        rmSync(wtPath, { recursive: true, force: true });
+        result.removedPath = true;
+      } catch (e) {
+        result.errors.push(`fs rm failed: ${String(e)}`);
+      }
+    }
+    await run(workingDir, "git", ["worktree", "prune"]);
+  } else {
+    result.removedPath = true;
+  }
+  removeWorktreeIndexEntry(workingDir, key);
+  return result;
+}
 
 // src/materializer.ts
-import { mkdirSync as mkdirSync3, existsSync as existsSync3, writeFileSync as writeFileSync3, readFileSync as readFileSync3, rmSync, symlinkSync as symlinkSync2, lstatSync } from "fs";
+import { mkdirSync as mkdirSync3, existsSync as existsSync3, writeFileSync as writeFileSync3, readFileSync as readFileSync3, rmSync as rmSync2, symlinkSync as symlinkSync2, lstatSync } from "fs";
 import { join as join4, dirname as dirname3 } from "path";
 var HOME2 = process.env.HOME || process.env.USERPROFILE || ".";
 var MULTI_DIR = join4(HOME2, ".multi");
@@ -16210,17 +16389,17 @@ function safeRmManaged(path) {
   try {
     const st = lstatSync(path);
     if (st.isSymbolicLink()) {
-      rmSync(path);
+      rmSync2(path);
       return;
     }
     if (st.isDirectory() && existsSync3(join4(path, MARKER))) {
-      rmSync(path, { recursive: true, force: true });
+      rmSync2(path, { recursive: true, force: true });
       return;
     }
     if (st.isFile() && path.endsWith(".md")) {
       const head = readFileSync3(path, "utf8").slice(0, 200);
       if (head.includes("multi-managed: true"))
-        rmSync(path);
+        rmSync2(path);
     }
   } catch {}
 }
@@ -16324,7 +16503,7 @@ import { join as join5, dirname as dirname4 } from "path";
 // package.json
 var package_default = {
   name: "@shipers-dev/multi",
-  version: "0.17.2",
+  version: "0.20.0",
   type: "module",
   bin: {
     "multi-agent": "./dist/index.js"
@@ -16365,7 +16544,8 @@ var COMMANDS = {
   stop: "Stop the running daemon",
   restart: "Stop and relaunch the daemon in background",
   logs: "View execution logs",
-  reset: "Reset acpx session for an issue (--issue <id>)"
+  reset: "Reset acpx session for an issue (--issue <id>)",
+  worktree: "Worktree maintenance (subcommands: gc)"
 };
 function ensureDirs() {
   for (const d of [MULTI_DIR2, join5(MULTI_DIR2, "logs"), SKILLS_DIR]) {
@@ -16373,6 +16553,14 @@ function ensureDirs() {
       mkdirSync4(d, { recursive: true });
   }
 }
+function isLocalApi(url2) {
+  try {
+    const h = new URL(url2).hostname;
+    return h === "localhost" || h === "127.0.0.1" || h === "0.0.0.0" || h === "[::1]" || h === "::1";
+  } catch {
+    return false;
+  }
+}
 function log(msg) {
   ensureDirs();
   const line = `[${new Date().toISOString()}] ${msg}
@@ -16396,7 +16584,10 @@ async function main() {
       workspace: { type: "string" },
       agent: { type: "string" },
       api: { type: "string" },
-      issue: { type: "string" }
+      issue: { type: "string" },
+      key: { type: "string" },
+      force: { type: "boolean", default: false },
+      "no-push": { type: "boolean", default: false }
     },
     allowPositionals: true,
     strict: false
@@ -16406,7 +16597,7 @@ async function main() {
     printHelp();
     process.exit(0);
   }
-  const apiUrl = args.values.api || process.env.MULTI_API_URL || "https://multi-api.adnb3r.workers.dev";
+  const apiUrl = args.values.api || process.env.MULTI_API || process.env.MULTI_API_URL || "https://multi-api.adnb3r.workers.dev";
   const config2 = loadConfig();
   if (config2.token)
     setAuthToken(config2.token);
@@ -16440,6 +16631,11 @@ async function main() {
     case "reset":
       await cmdReset(args.values.issue);
       break;
+    case "worktree": {
+      const sub = args.positionals.slice(3)[0] || "help";
+      await cmdWorktree(sub, { force: !!args.values.force, noPush: !!args.values["no-push"], key: args.values.key });
+      break;
+    }
     default:
       console.error(`Unknown command: ${command}`);
       printHelp();
@@ -16461,6 +16657,7 @@ Commands:
   restart   ${COMMANDS.restart}
   logs      ${COMMANDS.logs}
   reset     ${COMMANDS.reset}
+  worktree  ${COMMANDS.worktree}
 
 Options:
   --name <name>       Device name
@@ -16588,12 +16785,15 @@ async function cmdConnect(apiUrl, config2) {
   if (existsSync4(STOP_PATH))
     unlinkSync(STOP_PATH);
   const detected = await detectAgents();
+  const localMode = isLocalApi(apiUrl);
   log(`\uD83D\uDE80 Starting daemon for device ${config2.deviceId} (pid ${process.pid})`);
+  log(`   API: ${apiUrl}${localMode ? " (local \u2014 cloudflared skipped)" : ""}`);
   log(`   runtimes: ${detected.map((d) => d.type).join(", ") || "stub"}`);
   const db = openTasksDb();
   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;
+  let triggerHeartbeat = () => {};
   function resolvePayloadIds(row) {
     let agent_id = row.agent_id;
     let issue_id = row.issue_id;
@@ -16636,6 +16836,7 @@ async function cmdConnect(apiUrl, config2) {
       db.run("UPDATE tasks SET status = 'running', started_at = unixepoch(), attempts = attempts + 1 WHERE id = ?", [row.id]);
       const entry = { agentId: ids.agent_id || "", issueId: ids.issue_id, startedAt: Date.now(), child: null, worktreePath: "" };
       running.set(row.id, entry);
+      triggerHeartbeat();
       (async () => {
         try {
           const task = JSON.parse(row.payload);
@@ -16646,6 +16847,7 @@ async function cmdConnect(apiUrl, config2) {
           db.run("UPDATE tasks SET status = 'failed', finished_at = unixepoch(), error = ? WHERE id = ?", [String(e), row.id]);
         } finally {
           running.delete(row.id);
+          triggerHeartbeat();
           queueMicrotask(() => schedule());
         }
       })();
@@ -16769,17 +16971,28 @@ async function cmdConnect(apiUrl, config2) {
   try {
     writeFileSync4(PORT_PATH, String(port));
   } catch {}
-  let tunnel = await startTunnel(port, log);
-  if (!tunnel) {
-    log("\u274C cloudflared did not emit a tunnel URL \u2014 is `cloudflared` installed? (`brew install cloudflared`)");
-    try {
-      server.stop();
-    } catch {}
-    process.exit(1);
+  let tunnel = null;
+  if (localMode) {
+    tunnel = { child: null, url: `http://127.0.0.1:${port}` };
+    log(`\uD83C\uDFE0 Local tunnel: ${tunnel.url}`);
+  } else {
+    tunnel = await startTunnel(port, log);
+    if (!tunnel) {
+      log("\u274C cloudflared did not emit a tunnel URL \u2014 is `cloudflared` installed? (`brew install cloudflared`)");
+      try {
+        server.stop();
+      } catch {}
+      process.exit(1);
+    }
+    log(`\u2601\uFE0F  Tunnel up: ${tunnel.url}`);
   }
-  log(`\u2601\uFE0F  Tunnel up: ${tunnel.url}`);
   const heartbeat = async () => {
-    const res = await apiClient.post(`${apiUrl}/api/devices/${config2.deviceId}/heartbeat`, { status: "online", tunnel_url: tunnel?.url });
+    const res = await apiClient.post(`${apiUrl}/api/devices/${config2.deviceId}/heartbeat`, {
+      status: "online",
+      tunnel_url: tunnel?.url,
+      running_count: running.size,
+      max_concurrent: MAX_DEVICE
+    });
     if (res.success && res.data) {
       const remoteRev = Number(res.data.agent_skill_revision ?? 0);
       if (remoteRev > 0 && remoteRev !== lastMaterializedRevision()) {
@@ -16792,6 +17005,15 @@ async function cmdConnect(apiUrl, config2) {
     }
     return res.success && res.data?.pending_dispatches || 0;
   };
+  let beatTimer = null;
+  triggerHeartbeat = () => {
+    if (beatTimer)
+      return;
+    beatTimer = setTimeout(() => {
+      beatTimer = null;
+      heartbeat().catch(() => {});
+    }, 200);
+  };
   {
     const pending = await heartbeat();
     if (pending > 0)
@@ -16828,7 +17050,7 @@ async function cmdConnect(apiUrl, config2) {
   schedule();
   let restarting = false;
   const restartTunnel = async (reason) => {
-    if (!alive || restarting)
+    if (!alive || restarting || localMode)
       return;
     restarting = true;
     try {
@@ -16860,20 +17082,21 @@ async function cmdConnect(apiUrl, config2) {
       restarting = false;
     }
   };
-  (async () => {
-    while (alive) {
-      const t = tunnel;
-      if (!t) {
-        await sleep(1000);
-        continue;
+  if (!localMode)
+    (async () => {
+      while (alive) {
+        const t = tunnel;
+        if (!t || !t.child) {
+          await sleep(1000);
+          continue;
+        }
+        const code = await t.child.exited;
+        if (!alive)
+          return;
+        if (tunnel === t)
+          await restartTunnel(`cloudflared exited code=${code}`);
       }
-      const code = await t.child.exited;
-      if (!alive)
-        return;
-      if (tunnel === t)
-        await restartTunnel(`cloudflared exited code=${code}`);
-    }
-  })();
+    })();
   let probeFailures = 0;
   let tick = 0;
   const PROBE_EVERY = 6;
@@ -16885,7 +17108,7 @@ async function cmdConnect(apiUrl, config2) {
     }
     tick++;
     const currentUrl = tunnel?.url;
-    if (currentUrl && tick % PROBE_EVERY === 0) {
+    if (!localMode && currentUrl && tick % PROBE_EVERY === 0) {
       const ok = await probeTunnel(currentUrl);
       if (!ok) {
         probeFailures++;
@@ -17066,6 +17289,25 @@ async function markStopped(apiUrl, issueId, reason) {
   } catch {}
   await postStream(apiUrl, issueId, "stopped", { reason });
 }
+async function gcWorktreeAfterTerminal(baseWorkingDir, issueKey) {
+  try {
+    const res = await removeWorktree(baseWorkingDir, issueKey);
+    if (res.skipped === "dirty") {
+      log(`  \uD83D\uDEB1 worktree gc ${issueKey}: skipped (dirty \u2014 uncommitted changes preserved)`);
+      return;
+    }
+    if (res.skipped === "not_git")
+      return;
+    const errs = res.errors.length ? ` (warn: ${res.errors.join("; ")})` : "";
+    if (res.removedPath) {
+      log(`  \uD83E\uDDF9 worktree gc ${issueKey}: pushed=${res.pushed} removed=true (branch kept)${errs}`);
+    } else if (res.errors.length) {
+      log(`  \u26A0 worktree gc ${issueKey}: ${res.errors.join("; ")}`);
+    }
+  } catch (e) {
+    log(`  \u26A0 worktree gc ${issueKey} threw: ${fmtError(e)}`);
+  }
+}
 async function handleRunTask(apiUrl, deviceId, task, detected, ctx) {
   const issueId = task.issue_id;
   const isFollowup = !!task.followup;
@@ -17074,7 +17316,7 @@ async function handleRunTask(apiUrl, deviceId, task, detected, ctx) {
   let worktreeBranch = "";
   if (baseWorkingDir) {
     try {
-      const wt = await ensureWorktree(baseWorkingDir, task.key || issueId);
+      const wt = await ensureWorktree(baseWorkingDir, task.key || issueId, issueId);
       workingDir = wt.path;
       worktreeBranch = wt.branch;
       await postStream(apiUrl, issueId, "worktree_created", { path: wt.path, branch: wt.branch, reused: !wt.created });
@@ -17387,6 +17629,7 @@ ${body}
       } catch (e) {
         log(`preamble fetch failed: ${String(e)}`);
       }
+      preamble += await fetchMemoryPreamble(apiUrl, task);
       preamble += await buildPlanningPreamble(apiUrl, task);
       const prompt = preamble ? `${preamble}
 ---
@@ -17452,6 +17695,7 @@ ${body}
           }
         }
       } catch {}
+      preamble += await fetchMemoryPreamble(apiUrl, task);
       preamble += await buildPlanningPreamble(apiUrl, task);
       const issueContext = `## Issue ${task.key}: ${task.title}${task.description ? `
 
@@ -17512,7 +17756,7 @@ ${userPart}` : userPart;
         await eventHandler(event);
     }
     if (liveCommentId) {
-      const n = await uploadOutputDir(apiUrl, liveCommentId, outDir);
+      const n = await uploadOutputDir(apiUrl, liveCommentId, outDir, task.issue_id);
       if (n > 0)
         log(`  \uD83D\uDCCE uploaded ${n} output file(s)`);
     }
@@ -17540,9 +17784,13 @@ ${userPart}` : userPart;
     } else if (hadError) {
       await apiClient.post(`${apiUrl}/api/issues/${issueId}/fail`, {});
       log(`  \u2717 ${task.key} failed`);
+      if (baseWorkingDir)
+        await gcWorktreeAfterTerminal(baseWorkingDir, task.key || issueId);
     } else {
       await apiClient.post(`${apiUrl}/api/issues/${issueId}/complete`, {});
       log(`  \u2713 ${task.key} complete`);
+      if (baseWorkingDir)
+        await gcWorktreeAfterTerminal(baseWorkingDir, task.key || issueId);
     }
   } catch (e) {
     const msg = fmtError(e);
@@ -17557,6 +17805,53 @@ ${userPart}` : userPart;
     }
   }
 }
+async function fetchMemoryPreamble(apiUrl, task) {
+  if (process.env.MULTI_MEMORY_ENABLED !== "1")
+    return "";
+  try {
+    const issueRes = await apiClient.get(`${apiUrl}/api/issues/${task.issue_id}`);
+    const projectId = issueRes.data?.project_id;
+    if (!projectId)
+      return "";
+    const title = String(task.title || "").trim();
+    const desc = String(task.description || "").trim();
+    const followup = String(task.followup || "").trim();
+    const query = [title, desc, followup].filter(Boolean).join(`
+`).slice(0, 4000);
+    if (!query)
+      return "";
+    const res = await apiClient.post(`${apiUrl}/api/memory/recall`, {
+      project_id: projectId,
+      issue_id: task.issue_id,
+      query,
+      k: 10
+    });
+    if (!res.success)
+      return "";
+    const synthesis = String(res.data?.synthesis || "").trim();
+    if (!synthesis)
+      return "";
+    const cites = Array.isArray(res.data?.citations) ? res.data.citations : [];
+    let block = `## Project memory
+
+${synthesis}
+`;
+    if (cites.length) {
+      block += `
+`;
+      for (let i = 0;i < cites.length; i++) {
+        const c = cites[i];
+        block += `[${i + 1}] ${String(c.snippet || "").replace(/\s+/g, " ").trim()}
+`;
+      }
+    }
+    return `${block}
+`;
+  } catch (e) {
+    log(`memory recall failed: ${String(e?.message || e)}`);
+    return "";
+  }
+}
 async function buildPlanningPreamble(apiUrl, task) {
   const depth = typeof task.planning_depth === "number" ? task.planning_depth : 0;
   if (depth >= PLANNING_DEPTH_LIMIT) {
@@ -17714,6 +18009,11 @@ async function executePlanActions(apiUrl, parentTask, actions, ctx) {
           continue;
         }
         lines.push(`- \u2713 updated ${res.data.key}`);
+        if ((a.status === "done" || a.status === "cancelled") && parentTask.working_dir && existsSync4(parentTask.working_dir)) {
+          const targetKey = res.data?.key;
+          if (targetKey)
+            await gcWorktreeAfterTerminal(parentTask.working_dir, targetKey);
+        }
       } else if (a.type === "delegate") {
         const res = await apiClient.post(`${apiUrl}/api/issues/agent/mutate`, { action: "update", id: a.id, assignee_type: "agent", assignee_id: a.assignee_id, status: "todo" }, { headers });
         if (!res.success) {
@@ -17918,7 +18218,7 @@ function authTokenHeader() {
   const cfg = loadConfig();
   return cfg.token ? `Bearer ${cfg.token}` : null;
 }
-async function uploadOutputDir(apiUrl, commentId, dir) {
+async function uploadOutputDir(apiUrl, commentId, dir, issueId) {
   if (!existsSync4(dir))
     return 0;
   const files = [];
@@ -17947,10 +18247,15 @@ async function uploadOutputDir(apiUrl, commentId, dir) {
       const form = new FormData;
       const blob = new Blob([data]);
       form.append("file", blob, f.split("/").pop() || "file");
+      const headers = {};
+      if (token)
+        headers.Authorization = token;
+      if (issueId)
+        headers["x-issue-id"] = issueId;
       const res = await fetch(`${apiUrl}/api/attachments/comments/${commentId}`, {
         method: "POST",
         body: form,
-        headers: token ? { Authorization: token } : {}
+        headers
       });
       if (res.ok) {
         uploaded++;
@@ -18228,6 +18533,40 @@ async function cmdReset(issueId) {
   }
   console.log(body);
 }
+async function cmdWorktree(sub, opts) {
+  const config2 = loadConfig();
+  const baseDir = process.cwd();
+  if (sub === "gc") {
+    const targets = opts.key ? [opts.key] : listWorktreeIndex(baseDir).map((e) => e.key);
+    if (!targets.length) {
+      console.log("No worktrees in index.");
+      return;
+    }
+    let kept = 0, gone = 0, dirty = 0;
+    for (const k of targets) {
+      const r = await removeWorktree(baseDir, k, { force: opts.force, noPush: opts.noPush });
+      if (r.skipped === "dirty") {
+        dirty++;
+        console.log(`  \uD83D\uDEB1 ${k}: skipped (dirty)`);
+        continue;
+      }
+      if (r.skipped === "not_git") {
+        console.log(`  \u26A0 ${k}: not a git repo`);
+        continue;
+      }
+      if (r.removedPath) {
+        gone++;
+        console.log(`  \uD83E\uDDF9 ${k}: pushed=${r.pushed} removed=true (branch kept)${r.errors.length ? " warn=" + r.errors.join("; ") : ""}`);
+      } else {
+        kept++;
+        console.log(`  \u26A0 ${k}: ${r.errors.join("; ") || "unchanged"}`);
+      }
+    }
+    console.log(`Done. removed=${gone} dirty=${dirty} kept=${kept}`);
+    return;
+  }
+  console.log("Usage: multi-agent worktree gc [--key <key>] [--force] [--no-push]");
+}
 async function cmdRestart(apiUrl) {
   if (existsSync4(PID_PATH)) {
     const pid = Number(readFileSync4(PID_PATH, "utf8").trim());

package/package.json

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