symbiot 0.33.0 → 0.35.0

package/README.md

@@ -12,17 +12,17 @@ symbiot            your last 7 days, written up   (same as: symbiot week)
 symbiot standup    yesterday + today, for standup
 symbiot todo       what's still on your plate
 symbiot app        open the visual app in your browser
-symbiot drift      what's out of sync / at risk across your repos
 symbiot push       write tasks into each repo for your coding agent
-symbiot mail       add the mail you sent to your write-ups (local, no API)
-symbiot models     recommend AI models for your hardware
-symbiot setup-local  set up a free local model (Ollama), one command
+symbiot drift      what's out of sync / at risk across your repos
 symbiot login      connect it to an AI (once)
 symbiot whoami     show how it's connected
 symbiot logout     forget saved credentials
 symbiot help
 ```
 
+A few newer extras (email, CI checks, local-model setup) are
+[experimental](#experimental).
+
 ## Install
 
 ```bash
@@ -54,7 +54,7 @@ Tabs:
   **no AI key**; reviews and suggestions use your chosen model. While the scan runs
   the Map shows its progress.
 - **Drift** — the [`symbiot drift`](#whats-out-of-sync-symbiot-drift) report, with
-  "fetch latest" and "check CI" toggles.
+  a "fetch latest" toggle (and an [experimental](#experimental) "check CI").
 - **Week / Standup / Todo** — the write-ups (these use your chosen AI).
 - **Tasks** — a checklist, grouped by kind (Fixes, Tests & CI, Docs, …). Filter by
   type or repo, then **Send to repos** to hand just those to your agent (see
@@ -71,9 +71,9 @@ Tabs:
   did** — files changed and commits made, read from git, whichever agent it was.
   When an agent leaves **questions, options or ideas** for you, they show up on its
   block (see [Questions from your agent](#questions-from-your-agent)).
-- **Settings** — your AI, the folders to scan, your agent command, your
-  [email](#your-email-without-an-api-symbiot-mail), model recommendations and a
-  one-click local model.
+- **Settings** — your AI, the folders to scan and your agent command, plus the
+  [experimental](#experimental) email, model recommendations and one-click local
+  model.
 
 **Stays current by itself.** The app checks npm for a newer Symbiot every couple of
 minutes (and whenever you come back to the window); the version you're on is shown
@@ -82,7 +82,10 @@ version, relaunches the app on the same address, and the open window reloads its
 onto it. Restart `symbiot app` yourself and the open window reconnects the same way.
 
 The app listens on port **7391** so its address survives restarts; set
-`SYMBIOT_PORT` to use another (it falls back to a free port if that one is busy).
+`SYMBIOT_PORT` to use another. **One app at a time:** running `symbiot app` while
+it's already running just opens the existing window instead of starting a second
+copy (`SYMBIOT_FORCE_NEW=1` starts one anyway). If something else holds the port,
+it falls back to a free one.
 It works on **Linux, macOS and Windows**; with no Chromium-family browser to open
 the chrome-less window, it uses your default browser.
 
@@ -122,6 +125,12 @@ size of the uncommitted change and a **Show diff** button. For each repo:
 
 Tasks waiting for review aren't re-sent to the agent.
 
+If a repo you sent tasks to has uncommitted changes but no ticked task (say the
+agent made a fix and didn't tick anything), it still shows up here, with
+**Approve changes without a task → PR**. That ships the changes the same way, on
+a `symbiot/changes-<date>` branch, and leaves your tasks as they are. It also
+lists your own uncommitted work in those repos, so check the diff first.
+
 ### Run your agent automatically
 
 Set an **agent command** in Settings (*Hand off to your agent*), and every
@@ -130,7 +139,7 @@ a template — `{dir}` is the repo path, `{prompt}` is the instruction to read
 `TASKS.md` — so it works with any agent or editor:
 
 ```
-claude -p "{prompt}" --permission-mode acceptEdits
+claude -p "{prompt}" --permission-mode acceptEdits --allowedTools "Bash(npm test:*)" "Bash(node:*)"
 aider --message "{prompt}" --yes
 code {dir}
 ```
@@ -139,18 +148,36 @@ Settings shows **one-click presets** for what's installed on your machine. A
 preset only fills in the command box; the saved command is what runs.
 
 - **Agents** (all make changes, ready for your review): Claude Code, Codex
-  (OpenAI), Aider, Cursor agent, Gemini CLI.
+  (OpenAI), Aider, Cursor agent, Gemini CLI. The Claude preset may also run
+  `npm test` and `node`, so it can check its own work; a command saved from the
+  older preset is upgraded automatically, and an edited one is left alone.
+  The others run as-is, with their own limits: Codex (`--full-auto`) can run
+  tests but has no network in its sandbox, so tests that download packages
+  fail; Gemini (`--yolo`) approves every shell command, tests included; Aider
+  doesn't run shell commands unattended, so it can't check its own work.
 - **Orca IDE** (any OS): opens the repo in Orca — either just the repo, to use
-  Orca's own agent, or with Claude running in a new tab. It launches Orca if it's
-  closed and waits for it to be ready first.
-- **Editors:** VS Code, Cursor, Windsurf, Zed, Sublime Text, IntelliJ IDEA, Neovim
-  (on macOS, also found as `.app` bundles when the CLI isn't on your PATH).
+  Orca's own agent, or with Claude running in a new tab (allowed `npm test` and
+  `node` like the Claude preset, and upgraded the same way). It launches Orca if
+  it's closed and waits for it to be ready first.
+- **Editors — opens only, no review:** VS Code, Cursor, Windsurf, Zed, Sublime
+  Text, IntelliJ IDEA, Neovim (on macOS, also found as `.app` bundles when the CLI
+  isn't on your PATH). They just open the repo. Nothing comes back for review unless
+  you run an agent there yourself, and Neovim needs a terminal to open in.
 
 Each run is logged to `.symbiot/agent.log` in the repo and shown live in the
 **Agents** tab. The command is saved as `agentCmd` in
 `~/.config/symbiot/config.json` — it's your command, Symbiot only fills in
 `{dir}` and `{prompt}`. A command saved from an older preset keeps working as-is.
 
+One agent per repo: while a run is still going (tracked in
+`.symbiot/agent.pid`, so the app and `symbiot push --open` both see it), sending
+again doesn't start a second agent there, and doesn't rewrite the `TASKS.md` it's
+working from either: the new tasks wait in `.symbiot/TASKS.next.md` and replace
+`TASKS.md` when it finishes, keeping anything it ticked. Send again then to start
+an agent on them. Orca and editor presets only open a tab and exit, so Symbiot
+can't see the agent you run in them. Send to repos stays disabled until its
+handoffs have started, so a double click can't send twice.
+
 ### Questions from your agent
 
 An agent working in your terminal or IDE stops to ask you things: which way to go,
@@ -184,7 +211,6 @@ committed.
 ```bash
 symbiot drift          # local git facts only — fast, no network
 symbiot drift --fetch  # fetch from origin first, so "behind" is current
-symbiot drift --ci     # also check GitHub Actions state (needs gh)
 ```
 
 A **deterministic** report of what's out of sync, stuck, or at risk across your
@@ -195,10 +221,9 @@ not new work), **uncommitted work**, **behind upstream**, **multiple worktrees**
 branch** (the "merged but main didn't move" trap — split into *likely never
 landed*, when files the PR added are missing from main, and *probably re-done*,
 when they're all there), and — if you configure it — **production running code
-that isn't on your default branch**. With `--ci` it tells a real failing run apart
-from **CI that isn't running at all** (jobs never started — usually a billing or
-spending limit), quoting GitHub's reason when it can. Works on local-only repos
-too: without a remote it compares against your local default branch.
+that isn't on your default branch**. Works on local-only repos too: without a
+remote it compares against your local default branch. (CI checks with `--ci` are
+[experimental](#ci-status-symbiot-drift---ci).)
 
 For the production check, add a per-repo deploy command to
 `~/.config/symbiot/deploys.json` (read only from your own config, never from a
@@ -206,31 +231,6 @@ repo), keyed by repo path or folder name, that prints the deployed commit sha:
 `{ "/path/to/repo": "ssh prod cat ~/app/.deployed-sha" }`. Also the **Drift** tab
 in the app.
 
-## Which model? Ask your machine
-
-```bash
-symbiot models
-```
-
-Reads your RAM / CPU / GPU and recommends **local models by tier** (min / med / max,
-marking which fit your RAM) to run free & private via [Ollama](https://ollama.com),
-plus **paid** options (Claude / OpenAI / Gemini, cheap → top). Also available as
-a button in the app's Settings.
-
-### A free local model in one command: `symbiot setup-local`
-
-```bash
-symbiot setup-local                      # the best model for your RAM
-symbiot setup-local --model llama3.2:3b  # or pick one
-```
-
-Starts Ollama if it isn't running, downloads the model (with progress), and
-switches Symbiot over to it — free, private, nothing leaves your machine. If
-Ollama isn't installed yet it prints the one-line install for your OS (Homebrew on
-macOS, winget on Windows, the official script on Linux) and you re-run it after.
-Also the **Set up a free local model** button in Settings, where the download shows
-in the Agents tab and Symbiot switches over when it finishes.
-
 ## Connect it (once)
 
 Pick the AI you want it to write with:
@@ -270,34 +270,6 @@ It summarises the commits **you** authored — matching all your identities in e
 repo (per-repo and global email, your GitHub noreply address, your name), and
 counting everyone if that filter would drop almost all of an active repo's history.
 
-## Your email, without an API: `symbiot mail`
-
-```bash
-symbiot mail                 # what mail it can read, and what you sent this week
-symbiot mail --on            # use it in week / standup   (--off to stop)
-symbiot mail --add ~/Takeout/Mail/All\ mail.mbox   # an export, or any mail folder
-```
-
-Much of a week's work happens over email, so Week and Standup can include **what
-you sent**. There's no Gmail or Outlook API, no OAuth, no app to register and no
-password. Symbiot reads the mail a desktop client already keeps on your computer,
-so anyone can link theirs the same way:
-
-- **Thunderbird** (Linux, macOS, Windows, including Snap and Flatpak installs),
-  **Apple Mail**, **Evolution**, **KMail**, and **mutt/neomutt** or any
-  `~/Maildir` / `~/mail` are found automatically. Symbiot only looks at their
-  **Sent** folders.
-- **Webmail only?** Add an export. Google Takeout gives you an `.mbox`, and Symbiot
-  keeps just the messages with Gmail's *Sent* label (or from one of your
-  addresses). You can also point it at any `.mbox` file or a folder of `.eml`
-  files.
-
-It reads **headers only** (date, recipients, subject), never a message body. It's
-**off until you switch it on**, in Settings (*Email*) or with `symbiot mail --on`.
-**Preview** shows exactly what a write-up would see. On macOS, reading Apple Mail
-needs Full Disk Access for your terminal. Outlook for Windows keeps mail in `.pst`
-files, which Symbiot can't read, so export to `.mbox` or use Thunderbird.
-
 ## Where it looks
 
 By default Symbiot scans your **home folder**. To point it at where your work
@@ -327,7 +299,7 @@ instead of hanging. The CLI shows scan progress on one line as it goes.
 
 - **Reads:** your local git — commit messages and changed-file names, plus
   `TODO`/`FIXME` markers and uncommitted changes for `todo`. If you switch
-  [email](#your-email-without-an-api-symbiot-mail) on, it also reads the headers
+  [email](#your-sent-email-without-an-api-symbiot-mail) on, it also reads the headers
   of mail you sent (subject, recipients, date). All local.
 - **Sends to the AI:** commit messages and dates, changed-file **names**, the
   folder structure, `TODO`/`FIXME` lines, and (for a repo review) an excerpt of
@@ -341,47 +313,70 @@ instead of hanging. The CLI shows scan progress on one line as it goes.
 - **Runs only what you set:** the agent command is yours, and deploy commands are
   read only from your own `~/.config/symbiot/`, never from a repo.
 
-## Config
+## Experimental
+
+These work and are tested, but are newer or depend on things Symbiot can't fully
+check, so they may change. Everything above works without them.
+
+### Your sent email, without an API: `symbiot mail`
+
+```bash
+symbiot mail                 # what mail it can read, and what you sent this week
+symbiot mail --on            # use it in week / standup   (--off to stop)
+symbiot mail --add ~/Takeout/Mail/All\ mail.mbox   # an export, or any mail folder
+```
+
+Week and Standup can include **what you sent**. It needs no Gmail or Outlook API,
+OAuth, app registration or password: Symbiot reads the mail a desktop client
+already keeps on your computer, so anyone can link theirs the same way.
+**Thunderbird** (including Snap and Flatpak), **Apple Mail**, **Evolution**,
+**KMail**, and **mutt/neomutt** or any `~/Maildir` / `~/mail` are found
+automatically, and only their **Sent** folders are read. Webmail only? Add an
+export: Google Takeout gives you an `.mbox`, and Symbiot keeps just the messages
+with Gmail's *Sent* label (or from one of your addresses). Any `.mbox` file or
+folder of `.eml` files works too.
+
+It reads **headers only** (date, recipients, subject), never a message body, and
+it's **off until you switch it on** in Settings (*Email*) or with
+`symbiot mail --on`. **Preview** shows exactly what a write-up would see. Why it's
+experimental: the tests cover mbox and Maildir, but it hasn't been tried against
+real Apple Mail, Evolution or KMail stores. On macOS, reading Apple Mail needs Full
+Disk Access for your terminal. Outlook for Windows (`.pst`) isn't supported:
+export to `.mbox` or use Thunderbird.
+
+### CI status: `symbiot drift --ci`
 
-Everything lives in `~/.config/symbiot/`: `config.json` (your AI, `scanRoots`,
-`agentCmd`, `mail`; readable only by you), `tasks.json` (your tasks),
-`deploys.json` (optional, for drift's production check) and `rules.md` (optional
-conventions every repo review must respect, alongside each repo's own
-`CLAUDE.md` / `AGENTS.md` / `CONTRIBUTING.md`).
+```bash
+symbiot drift --ci     # also check GitHub Actions state (needs gh)
+```
 
-- `SYMBIOT_MODEL` — override the model for any provider (e.g. `gpt-4o`,
-  `claude-haiku-4-5`, `gemini-1.5-pro`).
-- `SYMBIOT_SCAN_TIMEOUT` — the scan time limit, in seconds (default 60).
-- `SYMBIOT_PORT` — the app's port (default 7391).
-- `symbiot whoami` shows the active provider, model, and where the credential
-  came from. `symbiot logout` forgets saved credentials.
+Adds CI to the drift report, telling a real failing run apart from **CI that isn't
+running at all** (jobs never started, usually a billing or spending limit) and
+quoting GitHub's reason when it can. Also the **check CI** toggle in the Drift tab.
+Why it's experimental: it needs the GitHub CLI (`gh`), only covers GitHub Actions,
+and spotting "not running" is a heuristic.
 
-## Development
+### Local models: `symbiot models` and `symbiot setup-local`
 
 ```bash
-npm test
+symbiot models                           # recommend models for this machine
+symbiot setup-local                      # the best local model for your RAM
+symbiot setup-local --model llama3.2:3b  # or pick one
 ```
 
-Runs four suites, all against throwaway repos and an isolated `HOME`:
-
-- `test/load.mjs` — the shipped files parse and load: `node --check` on each
-  module, `ui.mjs` imported on its own with its page's JavaScript parsed, every
-  local import listed in package.json `"files"`, and the `bin` entry point shipped.
-- `test/fixtures.mjs` — accuracy fixtures: the facts Symbiot collects (identity
-  matching, stale checkouts, worktrees, drift) and the `symbiot drift` report as
-  printed, the scan time limit, the agent handoff, and the review → approve cycle.
-- `test/smoke.mjs` — boots `symbiot app`, runs the page's own JavaScript against
-  a fake DOM (every tab, every button), hits every endpoint the UI calls with the
-  method the UI uses, and checks POST-only endpoints refuse GET and `/api` needs
-  the token.
-- `test/install.mjs` — runs the CLI through a bin symlink, then `npm pack` +
-  global install into a temp prefix: `symbiot help`, every shipped file present,
-  and the installed `symbiot app` serving its page. Needs npm registry access for
-  dependencies; `SYMBIOT_SKIP_INSTALL_TEST=1` skips that part.
-
-`SYMBIOT_NO_OPEN=1` stops `symbiot app` opening a window (the tests set it).
-Releases publish from a version tag via `.github/workflows/publish.yml`, and only
-after the full suite passes in CI.
+`models` reads your RAM / CPU / GPU and recommends **local models by tier** (min /
+med / max, marking which fit your RAM) to run free and private via
+[Ollama](https://ollama.com), plus **paid** options (Claude / OpenAI / Gemini,
+cheap → top). `setup-local` starts Ollama if it isn't running, downloads the model
+with progress, and switches Symbiot over to it. If Ollama isn't installed it prints
+the one-line install for your OS and you re-run it after. Both are buttons in
+Settings, where the download shows in the Agents tab. You can always pick a model
+yourself with `symbiot login`.
+
+## Config, development and releasing
+
+Config files, environment variables (`SYMBIOT_MODEL`, `SYMBIOT_PORT`, …), the test
+suites and how releases are cut are in [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ---
 

package/agents.mjs

@@ -0,0 +1,308 @@
+// Handing a repo to the user's agent: the saved command template, the one-click
+// presets (and the Orca IDE one), the background-job registry behind the Agents
+// tab, and the questions an unattended agent leaves for the user.
+import { spawn } from "node:child_process";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { readFileSync, writeFileSync, mkdirSync, existsSync, openSync, writeSync, unlinkSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { loadConfig, saveConfig, loadTasks, sh, hasCmd } from "./core.mjs";
+
+const HANDOFFS = []; // live registry of agents Symbiot has handed work to
+// ---- hand a repo (+ its tasks) to the user's agent — generic, settings-based
+// ONE code path, whatever the agent. The handoff is a command TEMPLATE the user
+// saves (`agentCmd`), with {dir} (repo path) and {prompt} (the task
+// instruction), and it is the only thing that ever runs:
+//   handoffCmd() -> fillHandoff() -> runHandoff() -> track()
+// Everything else in this section only helps pick a template: one-click presets
+// for what's installed (detectHandoffs), the Orca preset (a template too, kept
+// current by migrateOrcaCmd) and the cross-platform lookups behind them.
+//   claude -p "{prompt}"      · aider --message "{prompt}"      · code {dir}
+//   gnome-terminal --working-directory={dir} -- claude "{prompt}"
+// Not tied to any one tool — you decide what runs.
+const shSingle = (s) => "'" + String(s).replace(/'/g, "'\\''") + "'";
+const escDq = (s) => String(s).replace(/[\\"$`]/g, "\\$&");
+// Plain words only: in the Orca preset this passes through two shells, so no
+// backticks or $ (escDq covers one level).
+const HANDOFF_PROMPT = "Read .symbiot/TASKS.md and implement the unchecked items in this repo. Tick each item [x] in that file as you finish it and leave your changes uncommitted, so they can be reviewed and approved. If you need a decision, or have ideas or options for the user, write them to .symbiot/QUESTIONS.md as TASKS.md explains, and read .symbiot/ANSWERS.md first if it exists. Confirm before anything destructive.";
+function handoffCmd() { const cfg = loadConfig(); return migrateOrcaCmd(migrateClaudeCmd(cfg.agentCmd)) || (cfg.ide ? `${cfg.ide} {dir}` : ""); } // ide = legacy
+// Save the template ("" clears it). Either way the legacy `ide` key goes.
+function setHandoffCmd(cmd) {
+  const cfg = loadConfig(); const v = String(cmd || "").trim();
+  if (v) cfg.agentCmd = v; else delete cfg.agentCmd;
+  delete cfg.ide; saveConfig(cfg);
+  return { ok: true, cmd: cfg.agentCmd || "" };
+}
+const fillHandoff = (tmpl, repoPath) => tmpl.replace(/\{dir\}/g, shSingle(repoPath)).replace(/\{prompt\}/g, escDq(HANDOFF_PROMPT));
+// One agent per folder: two identical runs once started on the same repo 6s
+// apart and raced each other. The registry catches a second click in this
+// process; .symbiot/agent.pid catches another one (`symbiot push --open` while
+// the app is up). Returns the job, null (no command set) or { busy, id, pid }.
+// A preset that only opens a tab (Orca, editors) exits at once, so it holds
+// the folder only that long.
+function runHandoff(repoPath) {
+  const tmpl = handoffCmd(); if (!tmpl || !repoPath) return null;
+  const busy = runningHandoff(repoPath); if (busy) return { busy: true, id: busy.id || "", pid: busy.pid };
+  releaseHeldTasks(repoPath); // held for an agent another process started, which has since exited
+  const lock = join(repoPath, ".symbiot", LOCK);
+  const e = track(repoPath.split("/").pop(), fillHandoff(tmpl, repoPath), repoPath, () => {
+    try { if (JSON.parse(readFileSync(lock, "utf8")).pid === e.pid) unlinkSync(lock); } catch {}
+    releaseHeldTasks(repoPath);
+  });
+  if (!e) return null;
+  e.handoff = true;
+  if (e.pid) try { writeFileSync(lock, JSON.stringify({ pid: e.pid, id: e.id, startedAt: e.startedAt })); } catch {}
+  return e;
+}
+const LOCK = "agent.pid";
+const LOCK_MAX_AGE = 12 * 3600 * 1000; // older than this, the pid has probably been reused
+const pidAlive = (pid) => { try { process.kill(pid, 0); return true; } catch (err) { return !!err && err.code === "EPERM"; } };
+// The agent still running in this folder, if any.
+function runningHandoff(path) {
+  const e = HANDOFFS.find((x) => x.handoff && x.path === path && x.status === "running");
+  if (e) return { id: e.id, pid: e.pid, startedAt: e.startedAt };
+  try {
+    const l = JSON.parse(readSymbiot(path, LOCK));
+    if (l && Number.isInteger(l.pid) && Date.now() - l.startedAt < LOCK_MAX_AGE && pidAlive(l.pid)) return l;
+  } catch {}
+  return null;
+}
+// Send to repos while an agent is still running in the folder doesn't rewrite
+// the TASKS.md it's working from: the new brief waits in TASKS.next.md and
+// replaces TASKS.md once that agent exits. Returns true if it was held.
+const HELD = "TASKS.next.md";
+function writeTasks(path, md) {
+  const dir = join(path, ".symbiot"); mkdirSync(dir, { recursive: true });
+  if (runningHandoff(path)) { writeFileSync(join(dir, HELD), md); return true; }
+  writeFileSync(join(dir, "TASKS.md"), md);
+  try { unlinkSync(join(dir, HELD)); } catch {} // superseded by this brief
+  return false;
+}
+// Swap the held brief in, keeping the ticks the agent made meanwhile: a tick
+// is how a task reaches review, so dropping one would lose that task's work.
+function releaseHeldTasks(path) {
+  const held = readSymbiot(path, HELD); if (!held || runningHandoff(path)) return false;
+  const isTick = /^\s*-\s*\[x\]\s*/i, key = (l) => l.replace(/^\s*-\s*\[[ x]\]\s*/i, "").trim().toLowerCase();
+  const ticked = new Set(readSymbiot(path, "TASKS.md").split("\n").filter((l) => isTick.test(l)).map(key));
+  const md = held.split("\n").map((l) => /^\s*-\s*\[ \]/.test(l) && ticked.has(key(l)) ? l.replace("[ ]", "[x]") : l).join("\n");
+  try { writeFileSync(join(path, ".symbiot", "TASKS.md"), md); unlinkSync(join(path, ".symbiot", HELD)); return true; } catch { return false; }
+}
+// Presets. [cmd, label, macAppName] — macApp used to launch GUI editors on macOS
+// where the CLI isn't on PATH (they're .app bundles).
+const IDE_LIST = [["code", "VS Code", "Visual Studio Code"], ["cursor", "Cursor", "Cursor"], ["windsurf", "Windsurf", "Windsurf"], ["zed", "Zed", "Zed"], ["subl", "Sublime Text", "Sublime Text"], ["idea", "IntelliJ IDEA", "IntelliJ IDEA"], ["nvim", "Neovim", ""]];
+// [cmd, label, template]. Only agents that leave changes to review: a handoff
+// runs unattended, so a "plan only" run can't ask anything and leaves nothing to
+// approve — that preset was dropped (a saved one still runs as-is).
+// Claude: acceptEdits alone still blocks every shell command, so a run could
+// never run its own tests and had to leave test work unticked. Allow just the
+// test runner and node.
+const CLAUDE_CMD = 'claude -p "{prompt}" --permission-mode acceptEdits --allowedTools "Bash(npm test:*)" "Bash(node:*)"';
+const CLAUDE_CMD_OLD = 'claude -p "{prompt}" --permission-mode acceptEdits'; // ≤0.33
+const AGENT_LIST = [
+  ["claude", "Claude Code — make changes", CLAUDE_CMD],
+  ["codex", "Codex (OpenAI/GPT) — make changes", 'codex exec --full-auto "{prompt}"'],
+  ["aider", "Aider — make changes", 'aider --message "{prompt}" --yes'],
+  ["gemini", "Gemini — make changes", 'gemini --yolo -p "{prompt}"'],
+  ["cursor-agent", "Cursor agent", 'cursor-agent -p "{prompt}"'],
+];
+function detectHandoffs() {
+  const editors = [];
+  for (const [cmd, label, app] of IDE_LIST) {
+    if (hasCmd(cmd)) editors.push({ label, tmpl: `${cmd} {dir}`, kind: "editor" });
+    else { const a = macApp(app); if (a) editors.push({ label, tmpl: `open -a ${JSON.stringify(a)} {dir}`, kind: "editor" }); }
+  }
+  const agents = AGENT_LIST.filter(([cmd]) => hasCmd(cmd)).map(([cmd, label, tmpl]) => ({ label, tmpl, kind: "agent" }));
+  // Orca IDE (any OS): register the repo + open a terminal tab. Two variants —
+  // one that just opens the repo (use Orca's own agent, e.g. GPT), and one that
+  // runs Claude in the tab for Claude users. Not Claude-only.
+  // `<orca> open` first: it launches Orca AND blocks until the runtime is
+  // reachable, so this works even when Orca is closed (its CLI can't talk to a
+  // dead app). Use the full orca-ide path, never bare `orca` (that's a different
+  // tool on PATH). If Orca is already up, `open` returns fast.
+  const orca = findOrcaCli();
+  if (orca) {
+    const q = JSON.stringify(orca);
+    agents.unshift(
+      { label: "Orca IDE — open repo (use your Orca agent)", tmpl: orcaHandoffCmd(q, ""), kind: "agent" },
+      { label: "Orca IDE — run Claude in a tab", tmpl: orcaHandoffCmd(q, ORCA_CLAUDE_CMD), kind: "agent" },
+    );
+  }
+  return { agents, editors };
+}
+// The Orca preset. Build the full Orca handoff, cold-start safe. `bin` is the
+// quoted orca-ide path; `commandPart` is e.g. ORCA_CLAUDE_CMD or "" (open only).
+// open launches Orca & waits for the runtime to be REACHABLE, but on a cold
+// start the workspace graph isn't ready yet (runtime.state=graph_not_ready) and
+// `terminal create` times out — so we poll `status` until state=ready, then add
+// the repo and create the terminal (retry: the worktree can lag a beat behind).
+// {prompt} needs its own (escaped) quotes: the outer shell strips the --command
+// quotes and Orca re-runs the string in the tab, so an unquoted prompt reached
+// the agent as just its first word ("Read"). Same test-runner rules as
+// CLAUDE_CMD, so a run in the tab can test its own work too.
+const ORCA_CLAUDE_INNER = `claude \\"{prompt}\\" --allowedTools \\"Bash(npm test:*)\\" \\"Bash(node:*)\\"`;
+const ORCA_CLAUDE_INNER_OLD = `claude \\"{prompt}\\"`; // ≤0.34
+const ORCA_CLAUDE_CMD = ` --command "${ORCA_CLAUDE_INNER}"`;
+function orcaHandoffCmd(bin, commandPart) {
+  const waitReady = `for i in $(seq 1 40); do ${bin} status --json 2>/dev/null | grep -q '"state": *"ready"' && break; sleep 1; done`;
+  const mkTerm = `for j in 1 2 3; do ${bin} terminal create --worktree path:{dir}${commandPart} --focus && break; sleep 2; done`;
+  return `${bin} open; ${waitReady}; ${bin} repo add --path {dir}; ${mkTerm}`;
+}
+// Normalise an Orca command saved by an older version (no launch / no wait-for-
+// ready) to the current cold-start-safe form, preserving its binary path and any
+// custom `--command`. Idempotent: already-current commands are left untouched.
+function migrateOrcaCmd(cmd) {
+  if (!cmd || typeof cmd !== "string") return cmd;
+  if (!/orca-ide/.test(cmd) || !/\brepo add\b/.test(cmd)) return cmd;
+  const cm = cmd.match(/--command\s+"((?:[^"\\]|\\.)*)"/); // preserve a custom agent command
+  // ≤0.26 saved a bare {prompt} here (truncated to one word) — quote it; the
+  // ≤0.34 Claude preset (exact match only) gains the test-runner rules
+  const quoted = cm ? cm[1].replace(/(^|\s)\{prompt\}(?=\s|$)/g, '$1\\"{prompt}\\"') : "";
+  const inner = quoted === ORCA_CLAUDE_INNER_OLD ? ORCA_CLAUDE_INNER : quoted;
+  if (/status --json/.test(cmd) && /grep -q/.test(cmd) && (!cm || inner === cm[1])) return cmd; // already current
+  const bm = cmd.match(/^\s*("[^"]*"|'[^']*'|\S+)/); // leading orca-ide binary token
+  const bin = bm ? bm[1] : "";
+  const commandPart = cm ? ` --command "${inner}"` : "";
+  const rebuilt = bin ? orcaHandoffCmd(bin, commandPart) : cmd;
+  if (rebuilt !== cmd) { try { const cfg = loadConfig(); if (cfg.agentCmd === cmd) { cfg.agentCmd = rebuilt; saveConfig(cfg); } } catch {} }
+  return rebuilt;
+}
+// Upgrade a saved Claude preset from ≤0.33 to the current one. Exact match only:
+// a command the user edited is theirs and runs as-is.
+function migrateClaudeCmd(cmd) {
+  if (typeof cmd !== "string" || cmd.trim() !== CLAUDE_CMD_OLD) return cmd;
+  try { const cfg = loadConfig(); if (cfg.agentCmd === cmd) { cfg.agentCmd = CLAUDE_CMD; saveConfig(cfg); } } catch {}
+  return CLAUDE_CMD;
+}
+// Cross-platform detection for the presets (hasCmd lives in core.mjs).
+function macApp(name) { if (process.platform !== "darwin" || !name) return ""; for (const base of ["/Applications", join(homedir(), "Applications")]) { try { if (existsSync(join(base, name + ".app"))) return name; } catch {} } return ""; }
+// Find the Orca IDE CLI across OSes (known locations, then a bounded search).
+let ORCA_CLI; // cached per process: undefined=unchecked, ""=none, string=path
+function findOrcaCli() {
+  if (ORCA_CLI !== undefined) return ORCA_CLI;
+  ORCA_CLI = _findOrcaCli();
+  return ORCA_CLI;
+}
+function _findOrcaCli() {
+  const home = homedir(); const cands = [];
+  if (process.platform === "linux") cands.push(join(home, ".local/share/orca-ide/app/resources/bin/orca-ide"));
+  if (process.platform === "darwin") { cands.push(join(home, "Library/Application Support/orca-ide/app/resources/bin/orca-ide"), "/Applications/Orca.app/Contents/Resources/app/resources/bin/orca-ide", join(home, "Applications/Orca.app/Contents/Resources/app/resources/bin/orca-ide")); }
+  if (process.platform === "win32") { const la = process.env.LOCALAPPDATA || ""; cands.push(join(la, "orca-ide", "app", "resources", "bin", "orca-ide"), join(la, "Programs", "orca-ide", "resources", "app", "resources", "bin", "orca-ide")); }
+  for (const c of cands) { try { if (existsSync(c)) return c; } catch {} }
+  const roots = process.platform === "darwin" ? [join(home, "Library/Application Support"), "/Applications", join(home, "Applications")]
+    : process.platform === "win32" ? [process.env.LOCALAPPDATA || "", process.env.PROGRAMFILES || ""]
+    : [join(home, ".local/share"), "/opt", join(home, ".config")];
+  for (const r of roots) { if (!r) continue; const hit = sh(`find ${JSON.stringify(r)} -maxdepth 6 -name orca-ide -type f 2>/dev/null | head -1`).trim(); if (hit) return hit; }
+  return "";
+}
+// ---- background jobs --------------------------------------------------------
+// Run a shell command as a tracked, logged background job that shows up live in
+// the Agents tab. Shared by the agent handoff and the local-model setup.
+function track(name, cmd, cwd, onExit) {
+  try {
+    const dir = join(cwd, ".symbiot"); mkdirSync(dir, { recursive: true });
+    const logp = join(dir, "agent.log");
+    let fd = "ignore"; try { fd = openSync(logp, "a"); writeSync(fd, `\n=== ${name} ${new Date().toISOString()} ===\n$ ${cmd}\n`); } catch {}
+    const entry = { id: randomBytes(4).toString("hex"), name, path: cwd, log: logp, startedAt: Date.now(), status: "running", exitCode: null, endedAt: null };
+    const child = spawn(cmd, { shell: true, cwd, detached: true, stdio: ["ignore", fd === "ignore" ? "ignore" : fd, fd === "ignore" ? "ignore" : fd] });
+    entry.pid = child.pid;
+    child.on("exit", (code) => { entry.status = code === 0 ? "done" : "failed"; entry.exitCode = code; entry.endedAt = Date.now(); if (onExit) try { onExit(code); } catch {} });
+    child.on("error", () => { entry.status = "failed"; entry.endedAt = Date.now(); });
+    child.unref();
+    HANDOFFS.unshift(entry);
+    if (HANDOFFS.length > 30) HANDOFFS.length = 30;
+    return entry;
+  } catch { return null; }
+}
+// Agent-agnostic "what did it do": read it straight from git, so it works the
+// same whoever the agent was (Claude, Codex/GPT, Aider, Gemini, Cursor…). Shows
+// current working-tree changes + any commits the agent made since it started.
+function agentChanges(path, startedAt) {
+  try {
+    const q = JSON.stringify(path);
+    const porcelain = sh(`git -C ${q} status --porcelain`).trim();
+    // Don't count Symbiot's own .symbiot/ dir (agent.log, TASKS.md) as the agent's work.
+    const dirty = porcelain ? porcelain.split("\n").filter((l) => { const p = l.slice(3); return p !== ".symbiot" && p !== ".symbiot/" && p.indexOf(".symbiot/") !== 0; }).length : 0;
+    const stat = (sh(`git -C ${q} diff --shortstat`).trim() || sh(`git -C ${q} diff --cached --shortstat`).trim()).replace(/^\s+/, "");
+    const since = new Date(startedAt || Date.now()).toISOString();
+    const raw = sh(`git -C ${q} log --since=${JSON.stringify(since)} --pretty=%h\u0001%s`).trim();
+    const commits = raw ? raw.split("\n").slice(0, 8).map((l) => { const i = l.indexOf("\u0001"); return { hash: l.slice(0, i), msg: l.slice(i + 1) }; }) : [];
+    return { dirty, stat, commits };
+  } catch { return { dirty: 0, stat: "", commits: [] }; }
+}
+// ---- agent questions: decisions, options and ideas, from ANY agent ---------
+// A handoff runs unattended (claude -p, codex exec, aider --message, …), so the
+// agent can't stop and ask in chat. TASKS.md tells it to write
+// .symbiot/QUESTIONS.md instead — questions with options, plus ideas — which
+// the Agents tab shows on that agent's block. The user's answers are appended to
+// .symbiot/ANSWERS.md for the next run to read. Plain files, so it works the
+// same whichever model or tool the agent is.
+const QUESTIONS_MAX = 5;
+const qKey = (s) => String(s || "").trim().toLowerCase().replace(/\s+/g, " ");
+const readSymbiot = (path, f) => { try { return readFileSync(join(path, ".symbiot", f), "utf8"); } catch { return ""; } };
+// "## Questions" → "### question", context lines, "- option" bullets;
+// "## Suggestions" (or Ideas / Follow-ups) → "- idea" bullets. Forgiving: a bare
+// bullet under Questions is a question with no options.
+function parseQuestions(md) {
+  const questions = [], suggestions = []; let sec = "q", cur = null;
+  const clip = (s) => String(s).trim().slice(0, 300);
+  for (const raw of String(md || "").split(/\r?\n/)) {
+    const l = raw.trim(); if (!l) continue;
+    let m;
+    if ((m = l.match(/^###\s+(.+)$/))) {
+      if (sec === "s") { suggestions.push(clip(m[1])); cur = null; }
+      else { cur = { q: clip(m[1]), context: "", options: [] }; questions.push(cur); }
+      continue;
+    }
+    if ((m = l.match(/^##\s+(.+)$/))) { sec = /suggest|idea|follow|option/i.test(m[1]) ? "s" : "q"; cur = null; continue; }
+    if (/^#\s/.test(l)) continue;
+    const b = l.match(/^(?:[-*+]|\d+[.)])\s+(?:\[[ xX]\]\s+)?(.+)$/);
+    if (sec === "s") { if (b) suggestions.push(clip(b[1])); continue; }
+    if (b) { if (cur) cur.options.push(clip(b[1])); else questions.push({ q: clip(b[1]), context: "", options: [] }); continue; }
+    if (cur) cur.context = clip((cur.context ? cur.context + " " : "") + l);
+  }
+  return { questions: questions.filter((x) => x.q).slice(0, 20).map((x) => ({ ...x, options: x.options.slice(0, 6) })), suggestions: suggestions.filter(Boolean).slice(0, 10) };
+}
+// The OPEN questions (not yet in ANSWERS.md) and the agent's ideas, each marked
+// if it's already on the task list for this repo.
+function agentQuestions(path, repo) {
+  const p = parseQuestions(readSymbiot(path, "QUESTIONS.md"));
+  const done = new Set([...readSymbiot(path, "ANSWERS.md").matchAll(/^###\s+(.+)$/gm)].map((m) => qKey(m[1])));
+  const open = p.questions.filter((x) => !done.has(qKey(x.q)));
+  const tasks = p.suggestions.length ? loadTasks() : [];
+  return {
+    questions: open.slice(0, QUESTIONS_MAX), answered: p.questions.length - open.length,
+    suggestions: p.suggestions.map((text) => ({ text, added: tasks.some((t) => t.repo === repo && qKey(t.text) === qKey(text)) })),
+  };
+}
+// Save answers to .symbiot/ANSWERS.md; opts.rerun hands the repo back to the
+// agent (same saved command) so it carries on with them.
+function answerQuestions(path, answers, opts = {}) {
+  path = String(path || "");
+  if (!path || !HANDOFFS.some((e) => e.path === path)) return { error: "No agent has run in that folder." };
+  const open = new Map(agentQuestions(path, "").questions.map((x) => [qKey(x.q), x.q]));
+  const rows = (Array.isArray(answers) ? answers : [])
+    .map((x) => ({ q: open.get(qKey(x && x.q)), a: String((x && x.a) || "").replace(/^\s*#+/gm, "").trim().slice(0, 2000) }))
+    .filter((x) => x.q && x.a);
+  if (!rows.length) return { error: "Pick or type at least one answer." };
+  const prev = readSymbiot(path, "ANSWERS.md") || "# Answers from the user\nAnswers to the questions in QUESTIONS.md, newest last. Follow them; ask again in QUESTIONS.md if one is unclear.\n";
+  const day = new Date().toISOString().slice(0, 10);
+  try {
+    mkdirSync(join(path, ".symbiot"), { recursive: true });
+    writeFileSync(join(path, ".symbiot", "ANSWERS.md"), prev.replace(/\s*$/, "\n") + rows.map((x) => `\n### ${x.q}\n${x.a}\n_answered ${day}_\n`).join(""));
+  } catch (e) { return { error: "Couldn't write ANSWERS.md: " + ((e && e.message) || e) }; }
+  const out = { ok: true, saved: rows.length };
+  if (opts.rerun) { const e = runHandoff(path); if (e && e.busy) out.note = "Answers saved. An agent is still running in that folder, so another wasn't started. Send them again once it finishes."; else if (e) out.rerun = e.id; else out.note = "Answers saved. Set an agent command in Settings to have the agent pick them up automatically."; }
+  return out;
+}
+// The Agents tab: every tracked job, its log tail, what it changed, and — on the
+// newest job per folder — the questions/ideas it left.
+function agentsList() {
+  const seen = new Set();
+  return HANDOFFS.map((e) => {
+    let tail = ""; try { tail = readFileSync(e.log, "utf8").slice(-1200); } catch {}
+    const first = !seen.has(e.path); seen.add(e.path);
+    return { id: e.id, name: e.name, path: e.path, status: e.status, elapsed: (e.endedAt || Date.now()) - e.startedAt, exitCode: e.exitCode, tail, changed: agentChanges(e.path, e.startedAt), ask: first ? agentQuestions(e.path, e.name) : null };
+  });
+}
+
+export { HANDOFFS, HANDOFF_PROMPT, QUESTIONS_MAX, shSingle, CLAUDE_CMD, ORCA_CLAUDE_CMD, handoffCmd, setHandoffCmd, fillHandoff, runHandoff, runningHandoff, writeTasks, releaseHeldTasks, detectHandoffs, orcaHandoffCmd, migrateOrcaCmd, migrateClaudeCmd, track, agentChanges, parseQuestions, agentQuestions, answerQuestions, agentsList };