hilos-agent 0.1.16 → 0.5.1

package/README.md

@@ -1,6 +1,6 @@
 # hilos-agent
 
-Run **your own** coding agent — Claude Code, Codex, Cursor, or any command — as
+Run **your own** coding agent — Claude Code, Codex, Cursor, Hermes, or any command — as
 an autonomous teammate inside a [hilos](https://hilos.sh) channel.
 
 It connects to hilos over MCP, watches for `@mentions` of your agent in a
@@ -42,8 +42,8 @@ Running from elsewhere, or want to map several repos explicitly? Use a config:
   "url": "https://hilos.sh/api/mcp",
   "token": "mgo_…",
   "repos": { "your-org/your-repo": "/Users/you/code/your-repo" },
-  "codingCmd": "claude -p --permission-mode acceptEdits",  // safe default; see Permissions / autonomy. or "codex exec", "cursor-agent", any command
-  "chatCmd": "claude -p --model claude-haiku-4-5",  // FAST command for chat replies + the plan-ack (set if your stack isn't Claude)
+  "codingCmd": "claude -p --permission-mode acceptEdits",  // safe default; see Permissions / autonomy. or "codex exec", "cursor-agent -p --output-format text", "agy -p", any command
+  "chatCmd": "",  // FAST command for chat replies + the plan-ack. Empty = derived from codingCmd's tool (codex daemons chat with codex, etc.); set to override
   "defaultBranch": "main",
   "gate": false,               // default: open a PR directly. true = approve-before-push
   "heartbeatMs": 180000,       // long runs post one "still working…" thread reply this often (0 = off, min 15s)
@@ -60,7 +60,8 @@ then edits it in place with elapsed time + the CLI's latest line — so the chan
 shows it's alive without thread spam. When the run ends, that message is retired
 to a short "done" line. A run that **times out or errors** says so honestly (with
 a stderr tail) instead of claiming "no changes". Chat replies use the faster
-`chatCmd` (default Haiku; falls back to `codingCmd` if unset) bounded by
+`chatCmd` (when unset, derived from `codingCmd`'s tool — a Claude daemon chats
+with Haiku, a Codex daemon with `codex exec`, and so on) bounded by
 `chatTimeoutMs`. The responsive surface needs a hilos server new enough to expose
 `edit_message`; older servers just skip the live edits.
 
@@ -87,6 +88,89 @@ hilos-agent --channel <id>   # scope to one channel
   card and polls for your decision; **Approve** pushes + opens the PR, **Reject**
   discards the branch, **Request changes** re-runs with your note (bounded rounds).
 
+## Local folders (no repo required)
+
+A channel doesn't need a linked GitHub repo to get coding work done. Map a channel
+to a plain **local folder** and the agent works in it **directly** — it edits the
+files in place (no branch, no commit, no PR), then posts a report of what changed.
+It's your own machine, so this is the same trust as running the CLI yourself.
+
+```jsonc
+// hilos-agent.json
+{
+  "folders": { "<channelId>": "/Users/you/notes-site" }
+}
+```
+
+- **Trigger** — an `@mention` in a channel with **no linked repo** but a `folders`
+  mapping. The same LLM router decides chat vs. code; a coding ask runs in the
+  folder.
+- **Git folders** — if the folder is a git repo, the agent snapshots `git status`
+  before/after and reports the exact files it created/changed/removed plus a
+  `git diff --stat`. It **never** touches your index, branches, pushes, or runs
+  `gh`. On the report card: **Approve** keeps the changes (they're already live),
+  **Request changes** re-runs in place with your note (bounded by `maxRounds`),
+  **Reject** reverts *only what this run changed* (`git checkout` the files it
+  modified, delete the files it created) — your pre-existing local edits are left
+  untouched.
+- **Non-git folders** — it still runs, but says up front it can't show a file-level
+  diff or auto-undo; a reject asks you to revert by hand.
+- A **linked repo always wins** — the folder map is only consulted when the channel
+  has no repo link.
+- **Folder link registration** — on startup the daemon registers each `folders`
+  mapping with hilos (over the `link_folder` MCP tool) so the channel shows a
+  folder chip — the folder's name, its full path, and which machine it lives on —
+  without any manual step. It's best-effort and capability-gated: older servers
+  that don't expose `link_folder` are skipped silently, and a failed registration
+  only logs a line, never blocking the daemon. Registration happens once at
+  startup, so a `folders` entry added while the daemon is running needs a restart
+  to appear.
+
+### Deploy the folder with your own hosting CLI
+
+Add an optional per-channel deploy target next to `folders`:
+
+```jsonc
+{
+  "folders": { "<channelId>": "/Users/you/notes-site" },
+  "deploy": { "<channelId>": { "provider": "vercel", "prod": false } }
+}
+```
+
+`prod:false` means a preview deployment; `prod:true` means production. If the
+setting is absent, the daemon detects `.vercel/` / `vercel.json` or `.netlify/`
+/ `netlify.toml`; with no marker, deploy stays off. Install and sign in to the
+matching CLI yourself (`vercel login` or `netlify login`). hilos stores no host
+credential and never deploys silently: ask explicitly to put the folder live,
+or use the report card's clearly labeled deploy action. The live URL comes back
+on the same report card. CLI output is secret-redacted, the child receives no
+`HILOS_*` variables, and failures remain caveats rather than false successes.
+
+## Embedding the daemon
+
+`run(cfg, opts)` is the poll loop, and it's embeddable. Beyond `handler`/`log` it
+accepts:
+
+```js
+import { run } from "hilos-agent/src/run.mjs";
+
+const controller = new AbortController();
+await run(cfg, {
+  signal: controller.signal,   // abort → interrupts the poll sleep, cancels the
+                               //         active job, and returns cleanly
+  onEvent: (e) => {            // lifecycle events for a host UI (wrapped in
+    // e.type: "status" | "task-start" | "task-done" | "task-error"
+    console.log(e);            //   try/catch — a bad listener can't crash the loop)
+  },
+});
+// later: controller.abort();  // run() resolves once the active job tears down
+```
+
+Event shapes: `{ type: "status", text }`, `{ type: "task-start", channelId,
+messageId, text }`, `{ type: "task-done", channelId, status }`, and
+`{ type: "task-error", channelId, error }`. Both options are optional and fully
+backward compatible — omit them and the CLI behaves exactly as before.
+
 ## Model & permissions
 
 You don't have to hand-write `codingCmd`: the agent's **Connect via MCP** panel in
@@ -125,6 +209,47 @@ The default stays `acceptEdits`. Reach for `--dangerously-skip-permissions` when
 you want a truly hands-off teammate, and keep `gate:true` if you'd rather review
 before anything is pushed.
 
+## Hooks — stream a raw Claude Code session
+
+Don't want to run a persistent daemon? You can still make your Claude Code CLI
+sessions visible to your team in real time. **Claude Code hooks** (shipped in
+0448) let every tool call your session makes stream directly into your agent's
+live status card in hilos — no daemon, no extra process.
+
+```sh
+# Inside the repo you want to stream:
+npx hilos-agent hooks install
+
+# Or stream all your Claude Code sessions, everywhere:
+npx hilos-agent hooks install --global
+```
+
+This writes `PostToolUse`, `Stop`, and `SessionEnd` hook entries into
+`.claude/settings.json` (project) or `~/.claude/settings.json` (global),
+preserving any hooks you already have. Preview the block without writing anything:
+
+```sh
+npx hilos-agent hooks print
+```
+
+**Requirements:**
+- `npm i -g hilos-agent` so the `hilos-agent hook` command resolves at hook time.
+- A `~/.hilos/agent.json` with `url`, `token`, and `channelId`. Generate these in
+  the agent's **Connect via MCP** panel in hilos (same panel as `--join`).
+
+**What you get:**
+- Team members see "Editing lib/x.ts" or "Running pnpm test" on the agent's live
+  card as each tool fires — without you doing anything beyond the install.
+- Steps are coalesced into ~2s batches to keep traffic light.
+- When a turn ends (`Stop`), the card settles to done. The next turn revives the
+  same card — one card per session, not one per turn.
+- Up to 20 unique files touched are surfaced so reviewers can glance at the scope
+  before the report card arrives.
+
+**Privacy:** project-level by default (only repos you opt into stream). Global
+kill switch: `HILOS_HOOKS=off`. The hook always exits 0 — it will never interrupt
+or break your CLI session.
+
 ## Security
 
 The daemon runs a coding agent that can execute code in your repo — exactly as if

package/bin/hilos-agent.mjs

@@ -18,6 +18,7 @@
 
 import { resolveConfig, decodeJoin, writeStarterConfig, GLOBAL_CONFIG } from "../src/config.mjs";
 import { run } from "../src/run.mjs";
+import { hookMain, hooksMain } from "../src/hook.mjs";
 
 function parseArgs(argv) {
   const flags = {};
@@ -34,10 +35,11 @@ function parseArgs(argv) {
     else if (a === "--once") flags.once = true;
     else if (a === "--backfill") flags.backfill = true;
     else if (a === "--no-gate") flags.gate = false;
+    else if (a === "--global") flags.global = true;
     else if (a === "-h" || a === "--help") flags.help = true;
     else positional.push(a);
   }
-  return { cmd: positional[0] || "run", flags };
+  return { cmd: positional[0] || "run", flags, positional };
 }
 
 const HELP = `hilos-agent — your coding agent as a teammate in hilos
@@ -45,13 +47,20 @@ const HELP = `hilos-agent — your coding agent as a teammate in hilos
   hilos-agent --join <blob>      connect using a link copied from hilos
   hilos-agent init               write a starter config to ~/.hilos/agent.json
   hilos-agent                    run the daemon (watch @mentions, propose diffs)
+  hilos-agent hooks install      stream this repo's Claude Code sessions to your
+                                 hilos channel (writes .claude/settings.json;
+                                 --global for every repo). "hooks print" shows
+                                 the snippet; HILOS_HOOKS=off pauses streaming.
 
 Options:
   --channel <id>     watch only one channel (per-channel override)
   --config <path>    use a specific config file
-  --coding-cmd <cmd> the coding agent to run (default: "claude -p")
-  --chat-cmd <cmd>   fast command for chat replies + the plan-ack
-                     (default: "claude -p --model claude-haiku-4-5")
+  --coding-cmd <cmd> the coding agent to run — claude -p, codex exec,
+                     cursor-agent -p, agy -p, hermes, or any command that
+                     takes a prompt as its last arg (default: "claude -p")
+  --chat-cmd <cmd>   fast command for chat replies + the plan-ack (default:
+                     derived from the coding command, so a Codex or Cursor
+                     daemon chats with its own tool)
   --once             one poll then exit (cron-friendly)
   --backfill         also act on mentions that predate startup
   --no-gate          propose only; don't wait for approval / push
@@ -60,12 +69,24 @@ Options:
 Docs: https://hilos.sh  ·  https://www.npmjs.com/package/hilos-agent`;
 
 async function main() {
-  const { cmd, flags } = parseArgs(process.argv.slice(2));
+  const { cmd, flags, positional } = parseArgs(process.argv.slice(2));
   if (flags.help || cmd === "help") {
     console.log(HELP);
     return;
   }
 
+  // `hook` is invoked BY Claude Code on every tool call (0448) — it must be
+  // fast, silent, and always exit 0, so it short-circuits before any daemon
+  // machinery.
+  if (cmd === "hook") {
+    await hookMain();
+    return;
+  }
+  if (cmd === "hooks") {
+    hooksMain(positional[1], { global: Boolean(flags.global) });
+    return;
+  }
+
   const joinPayload = flags.join ? decodeJoin(flags.join) : undefined;
   if (flags.join && !joinPayload) {
     console.error("That --join link is invalid. Re-copy it from hilos.");
@@ -73,7 +94,11 @@ async function main() {
   }
 
   if (cmd === "init") {
-    const path = writeStarterConfig(joinPayload ? GLOBAL_CONFIG : flags.config, joinPayload || {});
+    // Carry an explicit --coding-cmd into the starter file so an init run from a
+    // non-Claude connect command doesn't write the Claude default over it.
+    const starter = { ...(joinPayload || {}) };
+    if (flags.codingCmd) starter.codingCmd = flags.codingCmd;
+    const path = writeStarterConfig(joinPayload ? GLOBAL_CONFIG : flags.config, starter);
     console.log(`Wrote ${path}.`);
     console.log(joinPayload ? "Token + endpoint set from your link." : "Fill in token + repos, then run `hilos-agent`.");
     console.log('Map your repos: "repos": { "owner/name": "/abs/path/to/checkout" }');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hilos-agent",
-  "version": "0.1.16",
+  "version": "0.5.1",
   "description": "Run your own coding agent (Claude Code / Codex / Cursor) as an autonomous teammate in a hilos channel. Picks up @mentions in channels and threads, makes the change, and opens a PR for review — your code and credentials never leave your machine. (Approve-before-push is available via gate:true.)",
   "type": "module",
   "bin": {

package/src/cli.mjs

@@ -7,6 +7,88 @@
 
 import { spawn } from "node:child_process";
 
+// ── Environment isolation ────────────────────────────────────────────────────
+// The coding/chat CLI we spawn (`claude -p`, `codex`, …) is a model with tool
+// use: it can run `env`/`printenv` and echo whatever it sees into the channel.
+// So hilos's OWN workspace bearer token (HILOS_TOKEN and the rest of the HILOS_*
+// connection vars) must NEVER be in the child's environment — the coding tool
+// never needs it (the DAEMON talks to hilos, the child only edits files), and
+// leaking it would hand a reader the keys to the workspace. We strip HILOS_* by
+// default on every spawn. Note the common `--join` paste-one-command flow keeps
+// the token in daemon memory (never in env), so this is a no-op there and only
+// bites the env-auth path (`HILOS_TOKEN=… hilos-agent`) — which is exactly where
+// the leak was. Hooks read the token from the config file, so they're unaffected.
+
+// Control flags (not secrets) that must survive the scrub: the documented
+// HILOS_HOOKS=off kill switch is read by the hook helper INSIDE the spawned
+// CLI's process tree, so stripping it would silently re-enable hook sends
+// from daemon-spawned sessions. Nothing here carries workspace access.
+const HILOS_CONTROL_KEYS = new Set(["HILOS_HOOKS"]);
+
+/**
+ * True for a hilos-owned connection var the coding tool must never inherit.
+ * @param {string} key
+ */
+function isHilosSecretKey(key) {
+  return /^HILOS_/i.test(key) && !HILOS_CONTROL_KEYS.has(key.toUpperCase());
+}
+
+/**
+ * A shallow copy of `base` (default `process.env`) with every hilos-owned env
+ * var (HILOS_*) removed. Applied to every child by runCli so the model can't
+ * read — and therefore can't echo — hilos's workspace token.
+ * @param {Record<string, string | undefined>} [base]
+ * @returns {Record<string, string>}
+ */
+export function scrubHilosEnv(base = process.env) {
+  const out = {};
+  for (const [k, v] of Object.entries(base)) {
+    if (v === undefined) continue;
+    if (isHilosSecretKey(k)) continue;
+    out[k] = v;
+  }
+  return out;
+}
+
+// Strict-isolation allowlist: what a coding CLI genuinely needs to start and
+// authenticate to ITS OWN provider — nothing else. Everything outside this list
+// (AWS/GCP/DB creds, PATs, SSH-agent sockets, arbitrary secrets in the user's
+// shell) is dropped so a task can't sweep them up. Opt-in via `codingEnv:
+// "minimal"`; users can widen it with `codingEnvAllow: ["FOO", …]`.
+const MINIMAL_ENV_EXACT = new Set([
+  "PATH", "HOME", "USER", "LOGNAME", "SHELL", "TERM", "TMPDIR", "TMP", "TEMP",
+  "TZ", "PWD", "LANG", "LC_ALL", "LC_CTYPE", "COLUMNS", "LINES", "COLORTERM",
+]);
+// Prefixes the coding tools use for their own config/auth (never hilos's).
+const MINIMAL_ENV_PREFIXES = [
+  "LC_", "XDG_", "NODE_", "NPM_", "npm_", "NVM_", "VOLTA_", "FNM_",
+  "ANTHROPIC_", "CLAUDE_", "OPENAI_", "CODEX_", "CURSOR_", "QWEN_", "DASHSCOPE_",
+  "SSL_", "NODE_EXTRA_CA_",
+];
+
+/**
+ * A curated child environment for strict isolation: only the vars a coding CLI
+ * needs to run and reach its own model provider, plus any `extraAllow` names the
+ * user opted into. HILOS_* is always excluded. Use for `codingEnv: "minimal"`.
+ * @param {Record<string, string | undefined>} [base]
+ * @param {string[]} [extraAllow]
+ * @returns {Record<string, string>}
+ */
+export function minimalEnv(base = process.env, extraAllow = []) {
+  const allowExtra = new Set(extraAllow || []);
+  const out = {};
+  for (const [k, v] of Object.entries(base)) {
+    if (v === undefined || isHilosSecretKey(k)) continue;
+    const ok =
+      MINIMAL_ENV_EXACT.has(k) ||
+      HILOS_CONTROL_KEYS.has(k.toUpperCase()) ||
+      allowExtra.has(k) ||
+      MINIMAL_ENV_PREFIXES.some((p) => k.startsWith(p));
+    if (ok) out[k] = v;
+  }
+  return out;
+}
+
 /** Human-readable elapsed time: "45s", "2m 3s". */
 export function fmtElapsed(ms) {
   const total = Math.max(0, Math.round(ms / 1000));
@@ -62,6 +144,9 @@ const MAX_CAPTURE_BYTES = 50 * 1024 * 1024;
  *   whole process group: SIGTERM, then SIGKILL after a short grace)
  * @property {(chunk: string) => void} [onData] - called with each stdout chunk as
  *   it arrives (lets a caller track the latest output line for a heartbeat)
+ * @property {Record<string, string>} [env] - base environment for the child. Any
+ *   hilos-owned var (HILOS_*) is stripped from it regardless. Omit to inherit the
+ *   daemon's environment minus HILOS_* (the safe default).
  */
 
 /**
@@ -86,6 +171,7 @@ export function runCli(opts) {
     log = console,
     signal,
     onData,
+    env,
   } = opts || {};
   return new Promise((resolve) => {
     // Already cancelled before we even start.
@@ -98,7 +184,17 @@ export function runCli(opts) {
       // detached:true makes the child its own process-group leader, so we can
       // kill the WHOLE tree (claude → node → git …) with process.kill(-pid) on
       // cancel/timeout instead of orphaning its subprocesses.
-      child = spawn(cmd, args, { cwd, detached: true });
+      // stdin MUST be 'ignore' (/dev/null → instant EOF), never a dangling pipe:
+      // `codex exec` appends piped stdin to its prompt and blocks until EOF, so
+      // an open pipe hangs it until the run timeout ("Reading additional input
+      // from stdin…"). Nothing we spawn is ever fed via stdin.
+      // Always strip hilos's own token from the child's env (see scrubHilosEnv).
+      child = spawn(cmd, args, {
+        cwd,
+        detached: true,
+        stdio: ["ignore", "pipe", "pipe"],
+        env: scrubHilosEnv(env || process.env),
+      });
     } catch (error) {
       resolve({ status: null, stdout: "", stderr: "", error });
       return;

package/src/config.mjs

@@ -43,15 +43,36 @@ const DEFAULTS = {
   token: "",
   channelId: "", // when set, watch only this channel (the per-channel override)
   repos: {},
+  // Local-folder mode (0322): map a channelId → an absolute folder path so a
+  // channel with NO linked GitHub repo can still get coding work done in a plain
+  // folder on this machine. Changes apply directly (no branch/PR). Live-reloadable
+  // like `repos`. Shape: { "<channelId>": "/abs/path" }.
+  folders: {},
+  // Optional local-folder deploy target. Outward deploys are always triggered
+  // explicitly by a request or report-card action; this only chooses provider
+  // and preview (default) vs production. Shape:
+  // { "<channelId>": { provider: "vercel" | "netlify", prod: false } }.
+  deploy: {},
   // acceptEdits lets the CLI make file edits without prompting (bias to action);
   // it still won't run arbitrary commands. Override in hilos-agent.json if you
   // want a stricter (or `--dangerously-skip-permissions`) command.
   codingCmd: "claude -p --permission-mode acceptEdits",
-  // Chat replies + the code-task plan-ack use a FAST one-shot model so a casual
+  // Environment handed to the coding/chat CLI. hilos's own token (HILOS_*) is
+  // ALWAYS stripped either way. "inherit" (default) passes the rest of your
+  // shell env so the coding tool behaves exactly as if you ran it yourself.
+  // "minimal" hands the child only what it needs to run + reach its own model
+  // provider (PATH/HOME/locale + ANTHROPIC_*/OPENAI_*/… ), dropping unrelated
+  // secrets (AWS/DB/SSH-agent/etc.) so a task can't sweep them up. Widen minimal
+  // mode with codingEnvAllow: ["MY_VAR", …].
+  codingEnv: "inherit",
+  codingEnvAllow: [],
+  // Chat replies + the code-task plan-ack use a FAST one-shot command so a casual
   // reply (or "I see it, here's my plan") comes back in seconds, not minutes.
   // Bounded by chatTimeoutMs with a template fallback so it can never dead-air.
-  // If your coding stack isn't Claude, set this to your own fast reply command.
-  chatCmd: "claude -p --model claude-haiku-4-5",
+  // Empty = derive from codingCmd's vendor (fastChatCmd in progress-emitter.mjs),
+  // so a Codex/Cursor daemon chats with ITS OWN tool — Claude Code is never
+  // required just because it's hilos's default. Set explicitly to override.
+  chatCmd: "",
   defaultBranch: "main",
   // Bias to action: open a PR directly for review (approve = merge on the card).
   // Set gate:true for the older approve-before-push flow (propose a diff, wait).
@@ -111,6 +132,9 @@ export function resolveConfig({ flags = {}, join: joinPayload } = {}) {
   }
   for (const [k, v] of Object.entries(flags)) if (v !== undefined) merged[k] = v;
   merged.repos = { ...DEFAULTS.repos, ...(file.repos || {}) };
+  // Local-folder map, merged like `repos` (an object, not a scalar overlay).
+  merged.folders = { ...DEFAULTS.folders, ...(file.folders || {}) };
+  merged.deploy = { ...DEFAULTS.deploy, ...(file.deploy || {}) };
   // Remember where the file lives so reloadConfig can re-read it live.
   merged.configPath = findConfigPath(flags.config) || null;
   return merged;
@@ -122,6 +146,8 @@ export function resolveConfig({ flags = {}, join: joinPayload } = {}) {
 const LIVE_FIELDS = [
   "codingCmd",
   "chatCmd",
+  "codingEnv",
+  "codingEnvAllow",
   "defaultBranch",
   "gate",
   "maxRounds",
@@ -135,6 +161,11 @@ const LIVE_FIELDS = [
   // NOT queueConcurrency: the queue is built once at startup, so it can't change
   // live. queueAcks IS live (intake() reads it per-mention from liveCfg).
   "queueAcks",
+  // folders is an object map; it's listed here for documentation, but the actual
+  // live merge (with DEFAULTS) happens in the special-cased block below, exactly
+  // like `repos`, so a partial edit doesn't drop the defaults.
+  "folders",
+  "deploy",
 ];
 
 /**
@@ -160,6 +191,10 @@ export function reloadConfig(prev) {
   if (next.heartbeatMs > 0) next.heartbeatMs = Math.max(15000, Number(next.heartbeatMs) || 0);
   next.progressMs = Math.max(750, Number(next.progressMs) || 2000);
   if (file.repos) next.repos = { ...DEFAULTS.repos, ...file.repos };
+  // Merge the folder map like repos (overriding the raw scalar-loop assignment
+  // above with a proper DEFAULTS-merged object).
+  if (file.folders) next.folders = { ...DEFAULTS.folders, ...file.folders };
+  if (file.deploy) next.deploy = { ...DEFAULTS.deploy, ...file.deploy };
   return next;
 }
 

package/src/daemon.mjs

@@ -31,6 +31,55 @@ export function resolveRepoPath(config, repoFullName) {
   return (config && config.repos && config.repos[repoFullName]) || null;
 }
 
+/** Local folder path for a channel from config (folder mode, 0322), or null.
+ *  Mirrors resolveRepoPath — a channel with no linked repo can still map to a
+ *  plain folder on this machine where the agent works directly. */
+export function resolveFolderPath(config, channelId) {
+  return (config && config.folders && config.folders[channelId]) || null;
+}
+
+/** Parse `git status --porcelain` (v1) into a Map(path → "XY" status code).
+ *  Handles renames ("old -> new" → keeps the new name) and quoted paths. */
+function parsePorcelain(text) {
+  const map = new Map();
+  for (const raw of String(text || "").split("\n")) {
+    if (!raw.trim()) continue;
+    const code = raw.slice(0, 2); // two status columns
+    let path = raw.slice(3); // skip the single separating space
+    const arrow = path.indexOf(" -> ");
+    if (arrow >= 0) path = path.slice(arrow + 4); // a rename reports old -> new
+    path = path.replace(/^"(.*)"$/, "$1"); // unquote paths with special chars
+    if (path) map.set(path, code);
+  }
+  return map;
+}
+
+/**
+ * What changed between two `git status --porcelain` snapshots taken before and
+ * after a run: files the run created (new/untracked/added), modified, or deleted.
+ * Pure + unit-testable. A path whose status is identical in both snapshots is a
+ * PRE-EXISTING local change (dirty before the run) and is excluded. Returns
+ * `{ modified, created, deleted }`, each a sorted string[].
+ */
+export function diffStatusSets(before, after) {
+  const b = parsePorcelain(before);
+  const a = parsePorcelain(after);
+  const created = [];
+  const modified = [];
+  const deleted = [];
+  for (const [path, code] of a) {
+    if (b.get(path) === code) continue; // unchanged since before the run
+    const c = code.trim();
+    if (code.includes("?") || c === "A" || c === "AM") created.push(path);
+    else if (c.startsWith("D")) deleted.push(path);
+    else modified.push(path);
+  }
+  created.sort();
+  modified.sort();
+  deleted.sort();
+  return { modified, created, deleted };
+}
+
 /** Parse `git diff --shortstat` output into counts. */
 export function parseShortstat(s) {
   const files = /(\d+) files? changed/.exec(s || "");