flowviant 0.29.0 → 0.31.0

package/bin/lib/live.mjs

@@ -29,10 +29,12 @@ import {
   FLEET_URL,
   FLEET_TOKEN,
   USER_AGENT,
+  ALLOW_PATCHES,
 } from './config.mjs';
 import { c, info, ok, warn } from './ui.mjs';
 import { sleep } from './claude.mjs';
 import { git, resetWorktree, isValidBranch } from './git.mjs';
+import { applyPatch, fileDiffs, ownerCurrentBranch, withPatchLock } from './patch.mjs';
 import { loadPreviewConfig, startPreview } from './preview.mjs';
 import { materializeInto, scrub as envScrub } from './env.mjs';
 
@@ -146,8 +148,17 @@ This IS your handover, so make it tangible; match the evidence to what you built
   works — write an e2e/integration test that DRIVES the flow (fill form → submit
   → assert the post-success state), attach its test_output, AND screenshot the
   end state. Never let a single static screenshot stand in for a flow.
-When the work is done: open ONE draft PR (git push +
-gh pr create --draft), call attach_pr, then call complete with a plain-language
+When the work is done, check the brief's "placement" FIRST.
+If placement is "patch": do NOT create a branch, do NOT push, do NOT open a PR.
+Commit your change in this worktree with a one-line message and stop there — the
+daemon carries it into the owner's own checkout and they keep or revert it. Then
+call complete with the summary + criteria self-report as normal.
+Otherwise (placement "branch", the default): create the branch named in the
+brief's "branchName" (git checkout -b <branchName> — use that exact name, do not
+invent one), open ONE draft PR (git push +
+gh pr create --draft; if the brief has a "baseBranch", target it with
+--base <baseBranch> so the stack stays reviewable), call attach_pr, then call
+complete with a plain-language
 summary of what you built AND a criteria self-report (index into the brief's
 "done when" list + met true/false + a short note per item). That summary +
 self-report becomes your DELIVERY CARD in the task thread — it's what the team
@@ -161,6 +172,35 @@ questions, delivery summaries, commits, or PRs — reference keys by NAME only
 (e.g. "set STRIPE_KEY"). Never screenshot a terminal or page that displays a
 credential, and never commit an env file.`;
 
+/** The brief minus the parts rendered as prose below (conversations, the ask). */
+function briefWithoutThread(brief) {
+  const {
+    thread: _thread,
+    lastMessageId: _lastMessageId,
+    plan: _plan,
+    asked: _asked,
+    ...rest
+  } = brief ?? {};
+  return rest;
+}
+
+/** The plan this task was carved out of, when there was one. A slice cannot
+ *  reconstruct WHY it was cut this way from its own spec. */
+function planContext(brief) {
+  const plan = brief?.plan;
+  if (!plan) return [];
+  const turns = (plan.recentTurns ?? [])
+    .map((m) => `${m.authorName || m.role}: ${m.content}`)
+    .join('\n');
+  return [
+    ``,
+    `This task is ONE SLICE of a larger plan: "${plan.title || 'untitled plan'}".`,
+    plan.description ? `The plan:\n${plan.description}` : '',
+    turns ? `How the team was talking about it, most recent last:\n${turns}` : '',
+    `Build only YOUR slice — the rest is there so its shape makes sense.`,
+  ].filter(Boolean);
+}
+
 function seedPrompt(runId, brief, transcript, resumedInPlace) {
   return [
     `Your run id is ${runId}. Use it for every flowviant MCP tool call.`,
@@ -168,15 +208,35 @@ function seedPrompt(runId, brief, transcript, resumedInPlace) {
       ? `You are RESUMING after a daemon restart: your worktree still contains your own uncommitted work from before the interruption. Run \`git status\` and \`git diff\` first, take stock, and CONTINUE from there — do not start over.`
       : brief?.branch
         ? `This is a REVISION — your prior branch "${brief.branch}" is checked out; address the review feedback and push to the SAME branch (the PR updates in place).`
-        : `Start from the clean base checkout and open a fresh draft PR when done.`,
+        : brief?.placement === 'patch'
+          ? `This is a PATCH: commit your change in this worktree and STOP — no branch, no push, no PR. The daemon lands it in the owner's checkout.`
+          : `Start from the clean base checkout. Create the branch named in the brief ("${brief?.branchName ?? 'flowviant/…'}") and open a fresh draft PR when done.`,
     ``,
     `Task brief:`,
-    JSON.stringify(brief ?? {}, null, 2),
+    // The conversation is rendered below as readable turns, not dumped twice as
+    // JSON — it is the longest thing in the brief and the least useful as data.
+    JSON.stringify(briefWithoutThread(brief), null, 2),
+    ...(brief?.asked
+      ? [
+          ``,
+          `What the human originally asked for, in their words:`,
+          `  "${brief.asked}"`,
+          `The specification above is someone's reading of that sentence, written`,
+          `without access to the repo. Where the two disagree, this is the one with`,
+          `a person behind it — say so rather than quietly picking one.`,
+        ]
+      : []),
+    ...planContext(brief),
     ...(transcript
-      ? [``, `Conversation so far (you may be resuming — pick up where this left off):`, transcript]
+      ? [
+          ``,
+          `The task conversation — what the team actually said, oldest first. The`,
+          `newest human message is usually why you were brought in:`,
+          transcript,
+        ]
       : []),
     ``,
-    `${transcript ? 'Continue' : 'Begin'}. Post a short plan first as a Markdown list (one numbered line per step), then: report_progress as you go; attach_evidence for each "done when" criterion as you satisfy it — a real screenshot for UI (run the dev server, then \`flowviant shot <url> --out shot.png\`), or test output / a request-response / a data sample for backend, so it's reviewable without running anything; report_blocker + stop if you hit a human decision; open a draft PR, attach_pr, then complete (summary + criteria self-report — your delivery card) when done.`,
+    `${transcript ? 'Continue' : 'Begin'}. Post a short plan first as a Markdown list (one numbered line per step), then: report_progress as you go; attach_evidence for each "done when" criterion as you satisfy it — a real screenshot for UI (run the dev server, then \`flowviant shot <url> --out shot.png\`), or test output / a request-response / a data sample for backend, so it's reviewable without running anything; report_blocker + stop if you hit a human decision; then finish per the brief's "placement" (patch: commit only, no PR; branch: draft PR + attach_pr) and call complete (summary + criteria self-report — your delivery card).`,
   ].join('\n');
 }
 
@@ -371,12 +431,120 @@ async function parkUntilReset(resetAt, { mcpUrl, getToken, runId, isAlive }) {
   }
 }
 
-export async function runLiveTask({ mcpUrl, token, cwd, baseRef, isAlive, resumeIntentId, onChild }) {
+/**
+ * Carry a completed patch into the owner's checkout, then narrate what happened
+ * in the thread.
+ *
+ * Serialised through withPatchLock so two agents can never write the tree at
+ * once, and refused outright when the owner is editing the same files — a
+ * collision becomes a blocker for a human, never a silent overwrite. Failure to
+ * land is reported honestly rather than being folded into a successful-looking
+ * delivery: the human must know the change is NOT in their tree.
+ */
+/** Where the patch base is remembered — inside the worktree's git dir, so
+ *  `git clean` can't take it (same reasoning as the task marker). */
+function patchBaseFile(cwd) {
+  return join(git(['rev-parse', '--absolute-git-dir'], cwd), 'flowviant-patch-base');
+}
+function writePatchBase(cwd, branch) {
+  try {
+    writeFileSync(patchBaseFile(cwd), branch ?? '', 'utf8');
+  } catch {
+    /* best effort */
+  }
+}
+function readPatchBase(cwd) {
+  try {
+    const v = readFileSync(patchBaseFile(cwd), 'utf8').trim();
+    return v || null;
+  } catch {
+    return null;
+  }
+}
+
+async function landPatch({ mcpUrl, token, runId, intentId, repoRoot, cwd, patchBase, baseRef }) {
+  // Everything here runs AFTER the agent called `complete`, which finalizes the
+  // run server-side. stream_turn and report_blocker are active-run gated, so
+  // they would be silently rejected — report_patch is deliberately not, and the
+  // server does the narrating.
+  const report = (body) =>
+    mcpCall(mcpUrl, token, 'report_patch', { runId, ...body }).catch(() => {});
+
+  if (!repoRoot) {
+    await report({ shas: [], ok: false, reason: 'this daemon has no main checkout to land it in' });
+    return;
+  }
+
+  // Computed from the AGENT's worktree, so it is the same set of hunks whether
+  // or not the cherry-pick lands. A declined patch still deserves to show what
+  // it would have done — that's what the human needs to unblock it.
+  // Where the agent's commits start. Normally the owner's branch we mirrored;
+  // when we could NOT mirror it (they were in a detached HEAD, or the fetch
+  // failed) the worktree was reset to base instead, so that is the honest
+  // starting point. Diffing against 'HEAD' here silently produced an empty range
+  // and a "the agent committed nothing" refusal over real work.
+  const commitsFrom = patchBase ?? baseRef ?? 'HEAD';
+  let diffs = [];
+  try {
+    diffs = fileDiffs(cwd, commitsFrom);
+  } catch {
+    /* evidence is best-effort; never block landing on it */
+  }
+
+  const res = await withPatchLock(() =>
+    Promise.resolve(applyPatch({ repoRoot, cwd, basedOnBranch: patchBase, commitsFrom }))
+  );
+
+  if (res.ok) {
+    await report({ shas: res.shas, files: res.files, diffs, ok: true });
+    ok(`${c.cyan('patch')} ${c.dim(`— applied ${res.files.length} file(s) in your checkout`)}`);
+    return;
+  }
+
+  const reason =
+    res.reason === 'conflict'
+      ? `you have uncommitted edits in ${res.paths.join(', ')}`
+      : res.reason === 'branch_moved'
+        ? `you switched from ${res.expected} to ${res.actual ?? 'a detached HEAD'} mid-run`
+        : res.reason === 'no_commits'
+          ? 'the agent committed nothing to apply'
+          : (res.error ?? 'the cherry-pick failed');
+
+  // A rollback that itself failed leaves commits in their history — never
+  // report that as "unchanged".
+  if (res.partiallyApplied) {
+    await report({
+      shas: res.appliedShas ?? [],
+      diffs,
+      ok: false,
+      reason: `${reason}. Some commits could not be rolled back and are still in your history`,
+    });
+    warn(`patch partially applied for intent ${intentId} — rollback failed; commits remain`);
+    return;
+  }
+
+  // Diffs go up even on a refusal: "you have uncommitted edits in X" is only
+  // actionable if you can see what the agent wanted to put there.
+  await report({ shas: [], diffs, ok: false, reason });
+  warn(`patch not applied: ${reason}`);
+}
+
+export async function runLiveTask({
+  mcpUrl,
+  token,
+  cwd,
+  baseRef,
+  repoRoot,
+  isAlive,
+  resumeIntentId,
+  onChild,
+}) {
   const claim = await mcpCall(mcpUrl, token, 'claim_next_intent', {}).catch(() => null);
   if (!claim || claim.claimed !== true) return { outcome: 'nothing' };
   const { runId, intentId } = claim;
   const brief = claim.brief ?? {};
   const title = brief.title ?? 'a task';
+
   // Re-claiming the SAME intent this worker was just working — either this
   // daemon's own memory (parked on a blocker, now resuming) or the persistent
   // task marker (the daemon restarted mid-task). Its worktree holds hours of
@@ -384,6 +552,41 @@ export async function runLiveTask({ mcpUrl, token, cwd, baseRef, isAlive, resume
   const resuming = !!resumeIntentId && intentId === resumeIntentId;
   const resumedInPlace = !resuming && readTaskMarker(cwd) === intentId;
 
+  // CONSENT. A patch writes commits into the working checkout of whoever runs
+  // this daemon — chosen by a model, and triggerable by any teammate who
+  // @mentions one of your agents. Whether that is allowed at all belongs to the
+  // person whose disk it is, so `--no-patches` turns it into an ordinary branch
+  // + PR. The work is never refused, only routed the long way round, and the
+  // thread is told so nobody is left wondering where their Keep/Revert card is.
+  //
+  // Applies at PICKUP only. A patch run already underway keeps its placement:
+  // its worktree is based on the owner's current branch, so converting it to a
+  // PR mid-flight would open one whose diff carries the owner's unrelated
+  // commits — and resetting to base instead would throw away the agent's work.
+  // The setting refuses new patches; it does not retroactively rewrite consent
+  // that was already given when the task was picked up.
+  if (!ALLOW_PATCHES && brief.placement === 'patch' && !resuming && !resumedInPlace) {
+    brief.placement = 'branch';
+    info(`${c.dim('patch declined by this machine (--no-patches) — building a PR instead')}`);
+    await mcpCall(mcpUrl, token, 'report_progress', {
+      runId,
+      kind: 'status',
+      message:
+        'This machine does not accept patches, so this is going up as a branch + PR ' +
+        'instead of landing in the checkout directly.',
+    }).catch(() => {});
+  }
+
+  // Placement decides where the work lands: its own branch + PR (the default),
+  // or a patch cherry-picked straight into the owner's checkout.
+  const isPatch = brief.placement === 'patch';
+  // Persisted next to the task marker: a patch run that PARKS (rate limit, a
+  // blocker) or survives a daemon restart resumes without re-entering the
+  // checkout branch, and an in-memory base would be null by the time the
+  // cherry-pick runs — applyPatch would diff HEAD..HEAD and report no_commits,
+  // silently dropping the work.
+  let patchBase = isPatch ? readPatchBase(cwd) : null;
+
   // Revision resumes its PR branch; a genuinely fresh task gets a clean base
   // checkout; a resume (in-memory or marker) keeps its dirty worktree untouched.
   // The branch is server-supplied — validate it's a well-formed non-base ref
@@ -396,8 +599,50 @@ export async function runLiveTask({ mcpUrl, token, cwd, baseRef, isAlive, resume
     } catch {
       if (!resuming && !resumedInPlace) resetWorktree(cwd, baseRef);
     }
+  } else if (isPatch && !resuming && !resumedInPlace) {
+    // PATCH placement: base off the branch the human is ACTUALLY on, so the
+    // change lands on their work rather than on main. Nothing is pushed and no
+    // PR is opened — the daemon cherry-picks the result across at the end.
+    patchBase = repoRoot ? ownerCurrentBranch(repoRoot) : null;
+    try {
+      if (!patchBase) throw new Error('owner is in a detached HEAD');
+      git(['fetch', 'origin', '--quiet'], cwd);
+      git(['checkout', '--detach', patchBase], cwd);
+      git(['reset', '--hard', patchBase], cwd);
+      git(['clean', '-fd'], cwd);
+    } catch {
+      // Can't mirror the owner's tree — fall back to a normal base checkout and
+      // let the apply step decline rather than landing something unexpected.
+      patchBase = null;
+      resetWorktree(cwd, baseRef);
+    }
+    writePatchBase(cwd, patchBase);
   } else if (!resuming && !resumedInPlace) {
-    resetWorktree(cwd, baseRef);
+    // STACKING (0.29.x): when the collision pass sequenced this intent behind
+    // one that shares its code, the server sends the blocker's branch as
+    // `baseBranch`. Basing off it means this agent sees that work immediately
+    // instead of waiting for a merge — the shared-checkout benefit, without a
+    // shared checkout. Same validation as `branch`: a server-supplied ref is
+    // never handed to git unchecked. Anything unusable falls back to the base,
+    // which is exactly the pre-stacking behaviour.
+    const stackOn =
+      brief.baseBranch && isValidBranch(brief.baseBranch, cwd, baseRef)
+        ? brief.baseBranch
+        : null;
+    let stacked = false;
+    if (stackOn) {
+      try {
+        git(['fetch', 'origin', '--quiet'], cwd);
+        git(['checkout', '--detach', `origin/${stackOn}`], cwd);
+        git(['reset', '--hard', `origin/${stackOn}`], cwd);
+        git(['clean', '-fd'], cwd);
+        stacked = true;
+      } catch {
+        // The blocker hasn't pushed yet — the wave ordering is what stops this
+        // being dispatched early, so falling back to base is safe, not wrong.
+      }
+    }
+    if (!stacked) resetWorktree(cwd, baseRef);
   }
   materializeInto(cwd); // resets wipe the synced env files — rewrite them
   writeTaskMarker(cwd, intentId);
@@ -421,15 +666,22 @@ export async function runLiveTask({ mcpUrl, token, cwd, baseRef, isAlive, resume
   delete env.ANTHROPIC_AUTH_TOKEN;
   delete env.ANTHROPIC_BASE_URL;
 
-  // Prior channel transcript — present when resuming a parked/re-claimed task;
-  // seed it so a fresh session picks up where the conversation left off. afterId
-  // starts at the last existing message so we never re-inject old ones as "new".
-  const prior = await mcpCall(mcpUrl, token, 'poll_channel', { runId }).catch(() => null);
-  const priorMsgs = prior?.messages ?? [];
+  // The conversation arrives WITH the brief (0.30.0) — the claim already read
+  // it, so asking again over poll_channel was a round-trip that told us nothing
+  // new. Older servers don't send it; fall back so a daemon ahead of the server
+  // still resumes with its transcript instead of silently starting cold.
+  let priorMsgs = brief.thread ?? null;
+  if (!priorMsgs) {
+    const prior = await mcpCall(mcpUrl, token, 'poll_channel', { runId }).catch(() => null);
+    priorMsgs = prior?.messages ?? [];
+  }
   const transcript = priorMsgs
     .map((m) => `${m.authorName || m.role}: ${m.content}`)
     .join('\n');
-  let afterId = priorMsgs.length ? priorMsgs[priorMsgs.length - 1].id : null;
+  // Where to resume polling from, so nothing already in the seed is re-injected
+  // as if it just arrived.
+  let afterId =
+    brief.lastMessageId ?? (priorMsgs.length ? priorMsgs[priorMsgs.length - 1].id : null);
 
   const input = makeInput(seedPrompt(runId, brief, transcript, resumedInPlace));
   const session = query({
@@ -547,6 +799,9 @@ export async function runLiveTask({ mcpUrl, token, cwd, baseRef, isAlive, resume
         // attempt's dirty files).
         if (completed) {
           clearTaskMarker(cwd);
+          if (isPatch) {
+            await landPatch({ mcpUrl, token, runId, intentId, repoRoot, cwd, patchBase, baseRef });
+          }
           return { outcome: 'done', title, intentId };
         }
 
@@ -607,7 +862,11 @@ export async function runLiveTask({ mcpUrl, token, cwd, baseRef, isAlive, resume
         // Idle turn with no completion — nudge a couple of times, then stop.
         if (nudges < 2) {
           nudges++;
-          input.push('Continue until the task is complete: open a draft PR and call complete, or report a blocker.');
+          input.push(
+            isPatch
+              ? 'Continue until the task is complete: commit your change (no branch, no push, no PR) and call complete, or report a blocker.'
+              : 'Continue until the task is complete: open a draft PR and call complete, or report a blocker.'
+          );
           continue;
         }
         return { outcome: 'stalled', title, intentId };
@@ -823,6 +1082,7 @@ export async function runLiveWorker({
         token,
         cwd,
         baseRef,
+        repoRoot,
         isAlive,
         resumeIntentId: lastIntentId,
         onChild,

package/bin/lib/patch.mjs

@@ -0,0 +1,295 @@
+/**
+ * Patch placement — landing a small change in the OWNER's own checkout.
+ *
+ * The motivating case: a teammate wants the login button to read "Sign in"
+ * while you are mid-work on auth. A clone → branch → push → PR → review → merge
+ * → pull cycle for a nine-character diff is absurd, and it blocks THEM on YOU.
+ *
+ * The naive version of this — let their agent write into your working directory
+ * — is the one thing we will not do. Two writers in one directory produce silent
+ * lost edits: the agent reads a file, thinks for forty seconds, and writes it
+ * back over the change you made in between. No conflict marker, nothing to
+ * resolve, and you find out three tasks later.
+ *
+ * So the agent still works in its OWN worktree, branched off your current
+ * branch, and the daemon carries the result across with a cherry-pick:
+ *
+ *   1. the agent commits in its worktree (no push, no PR)
+ *   2. we check the files it touched against YOUR uncommitted edits
+ *   3. only if they are disjoint do we cherry-pick into your checkout
+ *
+ * Step 2 is the whole safety argument. A collision is reported as a blocker for
+ * a human to sort out — never resolved by guessing, and never applied anyway.
+ *
+ * One patch at a time per daemon: `withPatchLock` serialises every apply in this
+ * process, so two agents can't race to write your tree. (Two daemons on one repo
+ * would still race — nothing in the daemon guards that today.)
+ */
+
+import { git, gitRaw, splitNul, isValidSha } from './git.mjs';
+
+/** Serialises applies within this process. */
+let patchChain = Promise.resolve();
+
+export function withPatchLock(fn) {
+  const run = patchChain.then(fn, fn);
+  // Keep the chain alive regardless of outcome, but don't swallow the result.
+  patchChain = run.then(
+    () => {},
+    () => {}
+  );
+  return run;
+}
+
+/** The branch the human is actually on, or null in a detached head. */
+export function ownerCurrentBranch(repoRoot) {
+  try {
+    const name = git(['rev-parse', '--abbrev-ref', 'HEAD'], repoRoot);
+    return name && name !== 'HEAD' ? name : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Repo-relative paths with uncommitted changes in the owner's checkout.
+ *
+ * `-z` on purpose. The line-based form quotes any path that isn't plain ASCII
+ * ("src/caf\303\251.ts") while `git diff --name-only` renders the same file
+ * differently — so the collision check, which is the entire safety argument for
+ * patch placement, quietly stopped matching for anyone with an accent in a
+ * filename and let the cherry-pick land on top of their edits. NUL-separated
+ * output is verbatim on both sides.
+ */
+export function dirtyPaths(repoRoot) {
+  let out = '';
+  try {
+    out = gitRaw(['status', '--porcelain', '-z'], repoRoot);
+  } catch {
+    return [];
+  }
+  // Porcelain -z is "XY path\0", and a RENAME is "R  new\0old\0" — the extra
+  // entry is the source, which we skip: the destination is what gets clobbered.
+  const entries = splitNul(out);
+  const paths = [];
+  for (let i = 0; i < entries.length; i++) {
+    const entry = entries[i];
+    // "XY " — two status columns and a space — then the path, verbatim.
+    if (entry.length < 4) continue;
+    const code = entry.slice(0, 2);
+    paths.push(entry.slice(3));
+    if (code.includes('R') || code.includes('C')) i += 1; // consume the source
+  }
+  return paths;
+}
+
+/** Commits the agent made on top of `base`, oldest first. */
+export function commitsSince(cwd, base) {
+  try {
+    const out = git(['rev-list', '--reverse', `${base}..HEAD`], cwd);
+    return out.split('\n').map((l) => l.trim()).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+/** Files those commits touch. `-z` to match dirtyPaths byte for byte. */
+export function filesChanged(cwd, base) {
+  try {
+    return splitNul(gitRaw(['diff', '--name-only', '-z', `${base}..HEAD`], cwd));
+  } catch {
+    return [];
+  }
+}
+
+// A patch never reaches GitHub, so the server has no provider to read a diff
+// back from — these commits exist only here. Without carrying it across, the
+// delivery card asks the human to Keep or Revert on the agent's word alone,
+// which is the review we skipped the PR to avoid needing.
+//
+// Capped because it crosses the wire and lands in a row read on every card
+// render: 40 files, 24KB of hunks each. Truncation is stated in the patch text
+// rather than silently trimmed — "no diff shown" is honest, a diff that lies
+// about its own extent is not.
+const MAX_DIFF_FILES = 40;
+const MAX_PATCH_BYTES = 24_000;
+
+const DIFF_STATUS = { A: 'added', D: 'removed', M: 'modified' };
+
+/**
+ * The per-file unified diffs for the agent's commits, in the same shape the PR
+ * path returns so the delivery card renders both through one component.
+ *
+ * Rename detection is deliberately OFF (no -M): with it on, `--numstat` writes
+ * the path as `dir/{old => new}.ts`, which no longer matches anything you can
+ * pass back to `git diff -- <path>`. A rename showing up as a delete plus an add
+ * is a slightly longer diff and a correct one.
+ */
+export function fileDiffs(cwd, base) {
+  let numstat = '';
+  let names = '';
+  try {
+    numstat = git(['diff', '--numstat', '--no-renames', `${base}..HEAD`], cwd);
+    names = git(['diff', '--name-status', '--no-renames', `${base}..HEAD`], cwd);
+  } catch {
+    return [];
+  }
+
+  const statusOf = new Map();
+  for (const line of names.split('\n')) {
+    const [letter, path] = line.split('\t');
+    if (!letter || !path) continue;
+    statusOf.set(path.trim(), letter.trim().charAt(0));
+  }
+
+  const out = [];
+  for (const line of numstat.split('\n')) {
+    if (out.length >= MAX_DIFF_FILES) break;
+    const m = /^(\d+|-)\t(\d+|-)\t(.+)$/.exec(line.replace(/\n$/, ''));
+    if (!m) continue;
+    const path = m[3].trim();
+    // A "-" count means binary — git has no textual hunks to give us.
+    const binary = m[1] === '-' || m[2] === '-';
+
+    let patch = null;
+    if (!binary) {
+      try {
+        const full = git(['diff', `${base}..HEAD`, '--', path], cwd);
+        // Drop git's own "diff --git a/… b/…" preamble; the card shows the path.
+        const at = full.indexOf('@@');
+        const hunks = at === -1 ? full : full.slice(at);
+        patch =
+          hunks.length > MAX_PATCH_BYTES
+            ? `${hunks.slice(0, MAX_PATCH_BYTES)}\n… diff truncated (${hunks.length} bytes)`
+            : hunks;
+      } catch {
+        patch = null;
+      }
+    }
+
+    out.push({
+      path,
+      status: DIFF_STATUS[statusOf.get(path)] ?? 'modified',
+      additions: binary ? 0 : Number(m[1]),
+      deletions: binary ? 0 : Number(m[2]),
+      patch,
+    });
+  }
+  return out;
+}
+
+/**
+ * Carry the agent's commits into the owner's checkout.
+ *
+ * Returns one of:
+ *   { ok: true, shas, files }                — applied
+ *   { ok: false, reason: 'no_commits' }      — the agent committed nothing
+ *   { ok: false, reason: 'branch_moved' }    — the owner switched branches mid-run
+ *   { ok: false, reason: 'conflict', paths } — the owner is editing those files
+ *   { ok: false, reason: 'apply_failed', error }
+ *
+ * Never leaves a half-applied state: a failed cherry-pick is aborted and the
+ * already-applied commits are rolled back, so the owner's tree is either fully
+ * patched or untouched.
+ */
+export function applyPatch({ repoRoot, cwd, basedOnBranch, commitsFrom }) {
+  // NB: uses revertPatch (declared below — hoisted) for its rollback path.
+  //
+  // Two different refs, and conflating them lost work. `basedOnBranch` is the
+  // owner's branch, used ONLY to check they haven't moved since we mirrored it;
+  // it is null when we couldn't mirror it at all (detached HEAD, a failed
+  // fetch). `commitsFrom` is where the agent's commits start, which in that case
+  // is the base ref the worktree actually got reset to. Defaulting the diff to
+  // 'HEAD' meant HEAD..HEAD — an empty range reported as "the agent committed
+  // nothing", which is a lie about work that is sitting right there.
+  const base = commitsFrom ?? basedOnBranch ?? 'HEAD';
+  const shas = commitsSince(cwd, base);
+  if (shas.length === 0) return { ok: false, reason: 'no_commits' };
+
+  // The tree we branched from must still be the tree we're landing in.
+  const current = ownerCurrentBranch(repoRoot);
+  if (basedOnBranch && current !== basedOnBranch) {
+    return { ok: false, reason: 'branch_moved', expected: basedOnBranch, actual: current };
+  }
+
+  const files = filesChanged(cwd, base);
+  const dirty = new Set(dirtyPaths(repoRoot));
+  const collisions = files.filter((f) => dirty.has(f));
+  if (collisions.length > 0) {
+    return { ok: false, reason: 'conflict', paths: collisions };
+  }
+
+  // Make the agent's commits reachable from the main checkout. Worktrees of the
+  // same repo share an object store, so this needs no network and no remote.
+  const applied = [];
+  try {
+    for (const sha of shas) {
+      git(['cherry-pick', '--allow-empty', '-x', sha], repoRoot);
+      applied.push(sha);
+    }
+  } catch (e) {
+    try {
+      git(['cherry-pick', '--abort'], repoRoot);
+    } catch {
+      /* nothing in progress */
+    }
+    let rolledBack = true;
+    if (applied.length > 0) {
+      // Roll back the ones that did land — by REVERTING them, never by
+      // resetting. `git reset --hard HEAD~n` would restore every tracked file
+      // in the repo, silently destroying the owner's uncommitted work in files
+      // this patch never touched. The pre-flight guard above only clears the
+      // patch's OWN file set, so a reset here is unbounded damage for a bounded
+      // mistake. A revert touches only the files in those commits.
+      const rev = revertPatch({ repoRoot, shas: applied });
+      rolledBack = rev.ok;
+    }
+    return {
+      ok: false,
+      reason: 'apply_failed',
+      error: e?.message ?? String(e),
+      // The caller must NOT claim "your tree is untouched" when part of the
+      // patch is still sitting in the owner's history.
+      partiallyApplied: !rolledBack,
+      appliedShas: rolledBack ? [] : applied,
+    };
+  }
+
+  // The landed shas differ from the source shas (cherry-pick rewrites them);
+  // report the ones now in the owner's history, since Revert acts on those.
+  let landed = applied;
+  try {
+    const out = git(['rev-list', `-n${applied.length}`, 'HEAD'], repoRoot);
+    landed = out.split('\n').map((l) => l.trim()).filter(Boolean).reverse();
+  } catch {
+    /* keep the source shas as a best-effort record */
+  }
+  return { ok: true, shas: landed, files };
+}
+
+/**
+ * Undo a landed patch. `git revert` rather than `reset` on purpose: the owner
+ * has almost certainly committed or edited on top by now, and rewriting their
+ * history to take something back would be far worse than the patch was.
+ */
+export function revertPatch({ repoRoot, shas }) {
+  // These arrive over the roster and go straight into git argv. Anything that
+  // isn't a bare object id — a revision range, a leading-dash option — is
+  // refused here rather than trusted because the server said so.
+  const clean = (shas ?? []).filter(isValidSha);
+  if (clean.length === 0 || clean.length !== (shas ?? []).length) {
+    return { ok: false, error: 'refused: patch revert carried a non-sha value' };
+  }
+  const ordered = [...clean].reverse(); // newest first
+  try {
+    for (const sha of ordered) git(['revert', '--no-edit', sha], repoRoot);
+    return { ok: true };
+  } catch (e) {
+    try {
+      git(['revert', '--abort'], repoRoot);
+    } catch {
+      /* nothing in progress */
+    }
+    return { ok: false, error: e?.message ?? String(e) };
+  }
+}