flowviant 0.29.0 → 0.30.0

package/bin/lib/claude.mjs

@@ -16,11 +16,12 @@ server. There is NO interactive user and NO terminal to ask in. The ONLY way to
 reach a human is the blocker loop. Never ask the user directly; never wait on stdin.
 
 Operate this loop:
-1. Call claim_next_intent. If it returns claimed:false, output exactly ALL_CLEAR on
-   its own line and stop.
-2. Read the brief. If it has an existing "branch" (a REVISION the human bounced back),
-   \`git checkout <branch>\` to resume your prior work and address the review feedback in
-   the description (under "— Review feedback —"). Use get_module_files / search_wiki /
+1. Call claim_next_intent to PICK UP the next task someone @mentioned you on. If it
+   returns claimed:false, output exactly ALL_CLEAR on its own line and stop.
+2. Read the brief, and read its "thread" FIRST — that is the task conversation, and the
+   newest human message is usually the specific reason you were brought in. If the brief
+   has an existing "branch" (a REVISION), \`git checkout <branch>\` to resume your prior
+   work and address what the thread asks for. Use get_module_files / search_wiki /
    list_related_intents for context. Call report_progress as you go.
 3. If you hit ANYTHING only a human can decide, call report_blocker with a clear
    question (and options when you can), then call get_blocker_resolution. If it is
@@ -34,51 +35,62 @@ Operate this loop:
    the merge runs separately.
 5. Return to step 1.
 
-Keep every change scoped to the claimed intent. If a tool errors, report_progress with
-the error, then retry or report_blocker.
+Keep every change scoped to the task you picked up. If a tool errors, report_progress
+with the error, then retry or report_blocker.
 SECRETS: env files (.env, .dev.vars, …) hold the team's synced secrets. Their VALUES
 must NEVER appear in evidence, progress, summaries, commits, or PRs — reference keys
 by NAME only. Never commit an env file.`;
 
-// Single-task turn (FLEET mode): claim EXACTLY ONE intent, then stop. The daemon
+// Single-task turn (FLEET mode): pick up EXACTLY ONE task, then stop. The daemon
 // owns the loop so it can reset the worktree + start a fresh conversation per task.
 export const SYSTEM_SINGLE = `You are a Flowviant build agent running FULLY AUTONOMOUSLY via the "flowviant" MCP
 server. There is NO interactive user and NO terminal to ask in. The ONLY way to
 reach a human is the blocker loop. Never ask the user directly; never wait on stdin.
 
 Do EXACTLY ONE task this turn:
-1. Call claim_next_intent. If it returns claimed:false, output exactly NOTHING on its
-   own line and stop. Do NOT retry.
-2. Read the brief. If it has an existing "branch" (a REVISION the human bounced back),
-   first \`git fetch && git checkout <branch>\` to resume YOUR prior work, and address
-   the review feedback in the description (under "— Review feedback —"). Otherwise work
-   from the clean base checkout. Use get_module_files / search_wiki /
+1. Call claim_next_intent to PICK UP the task someone @mentioned you on. If it returns
+   claimed:false, output exactly NOTHING on its own line and stop. Do NOT retry.
+2. Read the brief, and read its "thread" FIRST — that is the task conversation, and the
+   newest human message is usually the specific reason you were brought in. If the brief
+   has an existing "branch" (a REVISION), first \`git fetch && git checkout <branch>\` to
+   resume YOUR prior work and address what the thread asks for. Otherwise work from the
+   clean base checkout. Use get_module_files / search_wiki /
    list_related_intents for context. report_progress as you go.
 3. If you hit ANYTHING only a human can decide, call report_blocker (with options when
    you can), then get_blocker_resolution. If unresolved, output exactly
    BLOCKED:<blockerId> on its own line and STOP. Do NOT guess past a real decision.
-4. Ship: if this is a revision, \`git push\` to the SAME existing branch (the open PR
-   updates in place) and re-call attach_pr with that same PR URL. Otherwise open ONE
-   draft PR (git push + \`gh pr create --draft\`) and call attach_pr. Then call complete
-   with a plain-language summary AND a criteria self-report (index into the brief's
-   "done when" list + met true/false + a short note) — your delivery card in the task
-   thread. NEVER merge. Then output exactly DONE on its own line and stop.
-
-Do NOT claim a second intent — exactly one per turn. Keep every change scoped to the
-claimed intent. If a tool errors, report_progress with the error, then retry or
+4. Ship — this depends on the brief's "placement":
+   - placement "patch" (a small, targeted change landing in the owner's own checkout):
+     do NOT create a branch, do NOT push, do NOT open a PR. Commit your change with a
+     one-line message and STOP there — the daemon applies it and the human keeps or
+     reverts it. Then call complete with a plain-language summary and the criteria
+     self-report.
+   - placement "branch" (the default): if this is a revision, \`git push\` to the SAME
+     existing branch (the open PR updates in place) and re-call attach_pr with that same
+     PR URL. Otherwise create the branch the brief names in "branchName" (\`git checkout
+     -b <branchName>\` — use that exact name, do not invent one), push it, open ONE draft
+     PR with \`gh pr create --draft\`, and call attach_pr. If the brief has a "baseBranch",
+     your worktree is already based on it — target the PR at it (\`--base <baseBranch>\`)
+     so the stack stays reviewable. Then call complete with a plain-language summary AND a
+     criteria self-report (index into the brief's "done when" list + met true/false + a
+     short note) — your delivery card in the task thread.
+   NEVER merge. Then output exactly DONE on its own line and stop.
+
+Do NOT pick up a second task — exactly one per turn. Keep every change scoped to the
+task you picked up. If a tool errors, report_progress with the error, then retry or
 report_blocker.
 SECRETS: env files (.env, .dev.vars, …) hold the team's synced secrets. Their VALUES
 must NEVER appear in evidence, progress, summaries, commits, or PRs — reference keys
 by NAME only. Never commit an env file.`;
 
 export const KICKOFF =
-  'Begin the loop: claim and complete all dispatched Flowviant intents per your instructions.';
+  'Begin the loop: pick up and complete every Flowviant task you have been @mentioned on, per your instructions.';
 export const RESUME =
   'Resume. First call get_blocker_resolution for any blocker you reported; if resolved, ' +
-  'apply the human’s answer and continue. Otherwise keep claiming and completing ' +
-  'dispatched intents per your instructions.';
+  'apply the human’s answer and continue. Otherwise keep picking up and completing ' +
+  'the tasks you were @mentioned on, per your instructions.';
 export const SINGLE_KICKOFF =
-  'Claim and complete exactly ONE dispatched Flowviant intent per your instructions, then stop.';
+  'Pick up and complete exactly ONE Flowviant task per your instructions, then stop.';
 export const SINGLE_RESUME =
   'Resume your current task. Call get_blocker_resolution for the blocker you reported; ' +
   'if resolved, apply the human’s answer and finish this one intent, then stop.';
@@ -259,11 +271,21 @@ Steps:
 Ground every claim in files you actually read. Be efficient — look only at the
 changed area, not the whole repo; spend little quota.`;
 
-export const REGROUND_KICKOFF = ({ sha, title, files, vaultDir }) =>
+export const REGROUND_KICKOFF = ({ sha, title, files, vaultDir, predictedPages = [] }) =>
   `A feature just merged. Re-ground the knowledge vault (${vaultDir}) for it.\n\n` +
   `Feature: ${title}\n` +
   `Grounded commit: ${sha}\n` +
   `Changed files:\n${files.map((f) => `- ${f}`).join('\n')}\n\n` +
+  // The plan's own prediction, made when this work was drafted. Overlapping
+  // changed files against each page's frontmatter finds most of what moved, but
+  // misses a page whose file list has drifted or that documents a CONCEPT rather
+  // than a directory. This is a hint to CHECK, never a list to trust.
+  (predictedPages.length
+    ? `When this work was planned, these vault pages were expected to go stale.\n` +
+      `Treat it as a lead, not a fact — verify each against the code before\n` +
+      `editing, and ignore any that turned out to be unaffected:\n` +
+      `${predictedPages.map((p) => `- ${p}`).join('\n')}\n\n`
+    : '') +
   `Follow your instructions: update the touched vault pages (and any docs/\n` +
   `chapter that covers them), append the feature-history entry to log.md,\n` +
   `then output REGROUND_DONE.`;
@@ -511,3 +533,44 @@ export function runTurn({ prompt, resume, system, cwd, mcpConfig, label, onSpawn
     child.on('close', () => resolve(out));
   });
 }
+
+/**
+ * Plan check — the ground-truth pass.
+ *
+ * Generation runs on the server, where the repo does not exist. It grounds
+ * itself in proxies: a module manifest (names and file counts) and wiki pages
+ * (summaries of code). Those are good enough to draft a plan and not good
+ * enough to be sure of one — the summary can be stale, the anchors can be
+ * guesses, and "you already have this" can be wrong in the direction that
+ * wastes a day.
+ *
+ * This turn runs where the checkout is. It opens the actual files and corrects
+ * the plan. It is READ-ONLY by construction: it reports, it never edits.
+ */
+export const SYSTEM_PLAN_CHECK = `You are Flowviant's plan checker, running FULLY AUTONOMOUSLY in a real checkout of this repository.
+
+You are given a set of PROPOSED tasks that were drafted by a planner with no access to this repo. Your job is to check them against the actual code and report corrections. You are READ-ONLY: read files, search, and report. Do NOT edit, create, delete, commit, or run builds.
+
+For each proposed task, verify three things by opening real files:
+1. ALREADY BUILT — does this already exist? Only say so when you have SEEN the implementation; name the file and symbol. A similar-but-different capability is NOT already built.
+2. ANCHORS — are the listed module paths the ones this work would actually touch? Correct them to real directories that exist in this repo. Drop invented ones. Add the obvious misses.
+3. SIZE — is the points estimate plausible given how much code this really involves? Only comment when it is clearly wrong (a "1" that spans six files, an "8" that is a one-line constant).
+
+Respond with ONLY a JSON object on the final line, no markdown fence:
+{"checks":[{"id":"<the task id you were given>","alreadyBuilt":false,"evidence":"<file:symbol proving it, when alreadyBuilt>","anchors":["<corrected module paths>"],"points":<number or null>,"note":"<one short sentence, or empty>"}]}
+
+Rules:
+- Include an entry ONLY for tasks you actually have a correction or confirmation for. An empty "checks" array is a valid answer meaning "the plan looks right".
+- "anchors" must be paths that EXIST in this repo. Verify before listing.
+- "note" is read by a developer in a chat thread. One sentence, concrete, no preamble.
+- Never invent a file path or symbol. If you could not check something, leave it out.`;
+
+export const PLAN_CHECK_KICKOFF = ({ title, intents }) =>
+  `Check this plan against the real code.\n\nPLAN: ${title}\n\nPROPOSED TASKS:\n${intents
+    .map(
+      (i) =>
+        `- id: ${i.id}\n  title: ${i.title}\n  claimed anchors: ${
+          i.anchors.length ? i.anchors.join(', ') : '(none)'
+        }\n  points: ${i.points}`
+    )
+    .join('\n')}\n\nOpen the files these tasks claim to touch, verify each of the three checks, then output the JSON object on the final line.`;

package/bin/lib/config.mjs

@@ -43,6 +43,11 @@ function argFlag(name) {
   return i >= 0 ? process.argv[i + 1] : undefined;
 }
 
+/** A bare boolean flag (no value follows it). */
+function hasFlag(name) {
+  return process.argv.includes(name);
+}
+
 const API_BASE = process.env.FLOWVIANT_API_URL || 'https://api.flowviant.com/api/v2';
 export const MCP_URL = process.env.FLOWVIANT_MCP_URL || `${API_BASE}/mcp`;
 export const FLEET_URL = process.env.FLOWVIANT_FLEET_URL || `${API_BASE}/fleet/agents`;
@@ -73,6 +78,22 @@ export const AUTO_UPDATE = process.env.FLOWVIANT_NO_UPDATE !== '1';
 // path (one-shot `claude -p` turns) survives behind FLOWVIANT_POLL=1 as the
 // escape hatch; FLOWVIANT_LIVE=1 is still honored for old scripts.
 export const LIVE = process.env.FLOWVIANT_POLL !== '1';
+/**
+ * Does this machine accept PATCHES — commits cherry-picked straight into your
+ * working checkout, with no PR and no review?
+ *
+ * Patch placement is chosen by a model, and any teammate who @mentions one of
+ * your agents can trigger it, so whether it happens at all belongs to whoever
+ * owns the checkout. Turning it off does not lose the work: the task falls back
+ * to branch placement and arrives as a PR like anything else.
+ *
+ * On by default — the guard that actually protects you (never touching a file
+ * you have uncommitted edits in) is enforced at apply time, and the whole point
+ * of patches is to spare you a review cycle for a nine-character diff.
+ * `--no-patches` or FLOWVIANT_PATCHES=0 to refuse them.
+ */
+export const ALLOW_PATCHES =
+  !hasFlag('--no-patches') && process.env.FLOWVIANT_PATCHES !== '0';
 // Sent on the daemon's own HTTP calls so Cloudflare Bot Fight Mode doesn't 403
 // them (Node's default UA is treated as a bot). Claude Code sends its own UA.
 export const USER_AGENT = `flowviant/${VERSION}`;

package/bin/lib/fleet.mjs

@@ -23,6 +23,7 @@ import {
   REFRESH_BEFORE_SECONDS,
   LIVE,
   AUTO_UPDATE,
+  ALLOW_PATCHES,
 } from './config.mjs';
 import { handleVersionSignal } from './update.mjs';
 import {
@@ -31,11 +32,13 @@ import {
   repoRootOrDie,
   detectBaseRef,
   originSlug,
+  baseBranchName,
   isValidPrUrl,
   isValidBranch,
   isSafePathSegment,
 } from './git.mjs';
 import { c, LABEL_COLORS, info, note, ok, warn, fail } from './ui.mjs';
+import { revertPatch, withPatchLock } from './patch.mjs';
 import {
   sleep,
   mcpConfigFor,
@@ -48,6 +51,8 @@ import {
   SYSTEM_WIKI,
   WIKI_KICKOFF,
   SYSTEM_REGROUND,
+  SYSTEM_PLAN_CHECK,
+  PLAN_CHECK_KICKOFF,
   REGROUND_KICKOFF,
 } from './claude.mjs';
 import { runLiveWorker } from './live.mjs';
@@ -197,6 +202,13 @@ export async function runFleetDaemon() {
   info(SAFE ? 'mode   · safe (restricted toolset)' : 'mode   · unattended (skips permission prompts)');
   info(`repo   · ${repoRoot}`);
   info(`base   · ${baseRef}`);
+  // Stated out loud because it is the one setting that lets something else write
+  // into the checkout you are sitting in.
+  info(
+    ALLOW_PATCHES
+      ? 'patches· accepted — small changes land in your checkout for Keep/Revert (--no-patches to refuse)'
+      : 'patches· refused — everything arrives as a branch + PR'
+  );
   info(`server · ${FLEET_URL}`);
   console.log('');
   await preflight({ needGit: true });
@@ -301,6 +313,149 @@ export async function runFleetDaemon() {
       /* best-effort — the job reappears next poll if this failed */
     }
   };
+  // Patch reverts: a patch landed straight in this checkout, and a human took it
+  // back. The commits are HERE, not on the server, so the reverse-apply happens
+  // here too — a revert, never a reset, because the owner has almost certainly
+  // worked on top by now. Serialised through the same lock as applies.
+  const PATCH_REVERT_DONE_URL = FLEET_URL.replace(/\/agents\/?$/, '/patch-revert-done');
+  const reverting = new Set();
+  const processPatchRevertJobs = (jobs) => {
+    for (const job of jobs ?? []) {
+      if (!job || typeof job.id !== 'string' || !Array.isArray(job.shas)) continue;
+      if (reverting.has(job.id)) continue;
+      reverting.add(job.id);
+      (async () => {
+        try {
+          note(`${c.cyan('revert')} ${c.dim(`— ${job.title}`)}`);
+          const res = await withPatchLock(() =>
+            Promise.resolve(revertPatch({ repoRoot, shas: job.shas }))
+          );
+          if (res.ok) ok(`${c.dim('reverted')} ${job.title}`);
+          else warn(`revert failed for "${job.title}": ${res.error}`);
+          // ALWAYS report, success or not. Without this the flag stays set, the
+          // roster re-serves the job every poll, and each pass reverts the
+          // revert — the change flapping in and out of the owner's tree forever.
+          await reportMergeOutcome(PATCH_REVERT_DONE_URL, {
+            intentId: job.id,
+            ok: res.ok,
+            error: res.ok ? undefined : String(res.error ?? 'revert failed'),
+          });
+        } finally {
+          reverting.delete(job.id);
+        }
+      })();
+    }
+  };
+
+  // Plan checks: the ground-truth pass. Generation drafted these against a
+  // module manifest and wiki summaries — proxies for the repo. This runs where
+  // the checkout is, opens the real files, and reports corrections back into the
+  // thread. Read-only by construction; it never edits.
+  /**
+   * Pull the plan-check JSON off the tail of a Claude turn.
+   *
+   * The model is told to end with a bare JSON object, but a turn can trail
+   * prose, a fence, or a stray newline. Scan backwards for the last balanced
+   * object and validate it hard: anything shaped wrong is dropped rather than
+   * written into someone's plan. Returns null when nothing usable was found.
+   */
+  const parsePlanChecks = (out, intents) => {
+    const text = String(out ?? '');
+    const known = new Set(intents.map((i) => i.id));
+    const end = text.lastIndexOf('}');
+    if (end === -1) return null;
+    // NOTE: `lastIndexOf(x, -1)` returns 0, NOT -1 — the position argument is
+    // clamped, so the obvious `start = lastIndexOf('{', start - 1)` loop spins
+    // forever once it reaches index 0 and the parse fails. That hangs the
+    // daemon's event loop, not just this job. Walk with an explicit stop, and
+    // cap the attempts so a pathological turn can't burn the poll cycle either.
+    let start = text.lastIndexOf('{', end);
+    for (let attempts = 0; start !== -1 && attempts < 200; attempts++) {
+      let parsed = null;
+      try {
+        parsed = JSON.parse(text.slice(start, end + 1));
+      } catch {
+        /* not a complete object at this offset — step back and retry */
+      }
+      if (!parsed || !Array.isArray(parsed.checks)) {
+        if (start === 0) break;
+        start = text.lastIndexOf('{', start - 1);
+        continue;
+      }
+      return parsed.checks
+        .filter((ch) => ch && typeof ch.id === 'string' && known.has(ch.id))
+        .map((ch) => ({
+          id: ch.id,
+          alreadyBuilt: ch.alreadyBuilt === true,
+          evidence: typeof ch.evidence === 'string' ? ch.evidence.slice(0, 300) : '',
+          anchors: Array.isArray(ch.anchors)
+            ? ch.anchors.filter((a) => typeof a === 'string' && a.length < 200).slice(0, 6)
+            : [],
+          points:
+            typeof ch.points === 'number' && Number.isFinite(ch.points)
+              ? Math.max(0, Math.min(13, Math.round(ch.points)))
+              : null,
+          note: typeof ch.note === 'string' ? ch.note.slice(0, 400) : '',
+        }))
+        .slice(0, 30);
+    }
+    return null;
+  };
+
+  const PLAN_CHECK_DONE_URL = FLEET_URL.replace(/\/agents\/?$/, '/plan-check-done');
+  const checkingPlans = new Set();
+  const processPlanCheckJobs = (jobs) => {
+    for (const job of jobs ?? []) {
+      if (!job || typeof job.id !== 'string' || !Array.isArray(job.intents)) continue;
+      if (checkingPlans.has(job.id)) continue;
+      if (job.intents.length === 0) continue;
+      checkingPlans.add(job.id);
+      (async () => {
+        try {
+          note(`${c.cyan('plan')} ${c.dim(`— checking "${job.title}" against your code…`)}`);
+          // Reuse the wiki worktree: a clean detached checkout at base, which is
+          // what "the real code" should mean here — not whatever half-finished
+          // state an agent worktree happens to be in.
+          if (!existsSync(wikiWt)) {
+            try {
+              git(['worktree', 'add', '--detach', wikiWt, baseRef], repoRoot);
+            } catch {
+              git(['worktree', 'prune'], repoRoot);
+              git(['worktree', 'add', '--detach', wikiWt, baseRef], repoRoot);
+            }
+          }
+          const out = await runTurn({
+            prompt: PLAN_CHECK_KICKOFF({ title: job.title, intents: job.intents }),
+            resume: false,
+            system: SYSTEM_PLAN_CHECK,
+            cwd: wikiWt,
+            wikiPerm: true, // read-only file perms — no MCP, no shell writes
+            label: c.cyan('[plan]'),
+          });
+          const checks = parsePlanChecks(out, job.intents);
+          if (checks === null) {
+            warn(`plan check for "${job.title}": no usable JSON — leaving the plan as drafted`);
+          }
+          await reportMergeOutcome(PLAN_CHECK_DONE_URL, {
+            intentId: job.id,
+            checks: checks ?? [],
+          });
+          if (checks?.length) {
+            ok(`${c.cyan('plan')} ${c.dim(`— ${checks.length} correction${checks.length === 1 ? '' : 's'} for "${job.title}"`)}`);
+          } else {
+            ok(`${c.cyan('plan')} ${c.dim(`— "${job.title}" checks out against your code`)}`);
+          }
+        } catch (e) {
+          warn(`plan check failed for "${job.title}": ${e?.message ?? e}`);
+          // Clear the flag anyway — a stuck job would re-run every poll forever.
+          await reportMergeOutcome(PLAN_CHECK_DONE_URL, { intentId: job.id, checks: [] });
+        } finally {
+          checkingPlans.delete(job.id);
+        }
+      })();
+    }
+  };
+
   const processMergeJobs = (jobs) => {
     for (const job of jobs ?? []) {
       if (!job || typeof job.id !== 'string') continue; // a null element would wedge the loop
@@ -323,6 +478,35 @@ export async function runFleetDaemon() {
             warn(`merge REFUSED for "${job.title}": untrusted PR URL ${String(job.prUrl)}`);
             return;
           }
+          // STACKED PR: it targets its blocker's branch so the review shows only
+          // its own diff. The server holds this job until that blocker merged, so
+          // by now the blocker's commits are in the base ref — re-point before
+          // squashing, or the change lands in the blocker's branch and never
+          // reaches the trunk while the card cheerfully says "Merged".
+          if (job.retargetToBase) {
+            try {
+              // baseBranchName, not baseRef: `gh pr edit --base` needs a branch
+              // that exists in the repo, and detectBaseRef hands back a
+              // remote-tracking ref (origin/main) that GitHub 422s on.
+              execFileSync('gh', ['pr', 'edit', job.prUrl, '--base', baseBranchName(baseRef)], {
+                cwd: repoRoot,
+                stdio: ['ignore', 'pipe', 'pipe'],
+              });
+            } catch (e) {
+              // Already targeting base is the common no-op; anything else is
+              // reported rather than merged into the wrong place.
+              const err = e.stderr?.toString?.() || e.message || '';
+              if (!/no changes|already/i.test(err)) {
+                mergeAttempts.delete(job.id);
+                await reportMergeOutcome(MERGE_FAILED_URL, {
+                  intentId: job.id,
+                  message: `could not retarget the stacked PR onto ${baseBranchName(baseRef)} — merging it now would land in the branch below it, not ${baseBranchName(baseRef)}`,
+                });
+                warn(`merge held for "${job.title}": retarget failed — ${err.split('\n')[0]}`);
+                return;
+              }
+            }
+          }
           try {
             execFileSync('gh', ['pr', 'merge', job.prUrl, '--squash', '--delete-branch'], {
               cwd: repoRoot,
@@ -359,7 +543,7 @@ export async function runFleetDaemon() {
             // Direct enqueue = immediacy; the server's durable regroundJobs list
             // (created by merge-done above, cleared by our reground-done report)
             // is the restart-safe backstop — dedup'd here by groundedIntents.
-            enqueueReground(job.id, job.prUrl, job.title);
+            enqueueReground(job.id, job.prUrl, job.title, job.dirtiesPages);
           } else if (failedReason) {
             // Report into the thread (server narrates + re-arms the merge
             // button + notifies) — the job disappears from the roster.
@@ -503,10 +687,20 @@ export async function runFleetDaemon() {
     wikiQueue.push({ type: 'sweep' });
     void drainWiki();
   };
-  const enqueueReground = (intentId, prUrl, title) => {
+  const enqueueReground = (intentId, prUrl, title, dirtiesPages) => {
     if (!intentId || groundedIntents.has(intentId)) return;
     groundedIntents.add(intentId);
-    wikiQueue.push({ type: 'reground', intentId, prUrl, title: title || 'a delivered task' });
+    wikiQueue.push({
+      type: 'reground',
+      intentId,
+      prUrl,
+      title: title || 'a delivered task',
+      // What the PLAN thought this would invalidate. A hint, not the truth —
+      // the turn still reads the real changed files; this catches pages whose
+      // frontmatter file list has drifted, or that document a concept rather
+      // than a directory.
+      dirtiesPages: Array.isArray(dirtiesPages) ? dirtiesPages : [],
+    });
     void drainWiki();
   };
 
@@ -674,7 +868,13 @@ export async function runFleetDaemon() {
             } else {
               note(`${c.cyan('wiki')} ${c.dim(`— re-grounding after "${task.title}"…`)}`);
               const out = await runTurn({
-                prompt: REGROUND_KICKOFF({ sha, title: task.title, files, vaultDir }),
+                prompt: REGROUND_KICKOFF({
+                  sha,
+                  title: task.title,
+                  files,
+                  vaultDir,
+                  predictedPages: task.dirtiesPages ?? [],
+                }),
                 resume: false,
                 system: SYSTEM_REGROUND(vaultDir),
                 cwd: wikiWt,
@@ -820,6 +1020,8 @@ export async function runFleetDaemon() {
       if (updating) return;
     }
     processMergeJobs(roster.mergeJobs);
+    processPatchRevertJobs(roster.patchRevertJobs);
+    processPlanCheckJobs(roster.planCheckJobs);
     processCleanupJobs(roster.cleanupJobs);
     const rosterIds = new Set(roster.agents.map((a) => a.agentId));
 
@@ -912,7 +1114,7 @@ export async function runFleetDaemon() {
     enqueueSweep(roster.codeMapJob);
     for (const j of roster.regroundJobs ?? []) {
       if (!j || typeof j.intentId !== 'string') continue; // a null element would throw + wedge the loop
-      enqueueReground(j.intentId, j.prUrl, j.title);
+      enqueueReground(j.intentId, j.prUrl, j.title, j.dirtiesPages);
     }
     void drainWiki();
 

package/bin/lib/git.mjs

@@ -6,6 +6,26 @@ export function git(args, cwd) {
   return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
 }
 
+/**
+ * Same call, UNTRIMMED — for `-z` (NUL-separated) output, where trimming would
+ * eat the final separator and the leading space of a status code.
+ *
+ * Anything that COMPARES two path lists has to use this. Git's default
+ * line-based output quotes and escapes any path that isn't plain ASCII, and it
+ * does so inconsistently between commands — so a comparison of `git status`
+ * paths against `git diff` paths silently stops matching the moment a filename
+ * has an accent in it. For the patch collision check, "silently stops matching"
+ * means "overwrites the edits it exists to protect".
+ */
+export function gitRaw(args, cwd) {
+  return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+}
+
+/** Split NUL-separated git output into entries. */
+export function splitNul(out) {
+  return String(out).split('\0').filter(Boolean);
+}
+
 export function repoRootOrDie() {
   try {
     return git(['rev-parse', '--show-toplevel'], process.cwd());
@@ -53,6 +73,14 @@ export function isValidBranch(branch, repoRoot, baseRef) {
   }
 }
 
+/** A commit sha from the server, before it reaches `git revert` argv. Server
+ *  values reaching git are validated here by convention (see isValidBranch,
+ *  isValidPrUrl) — a revision RANGE ("HEAD~10..HEAD") or a leading-dash option
+ *  must never pass, whatever the roster says. */
+export function isValidSha(sha) {
+  return typeof sha === 'string' && /^[0-9a-f]{7,40}$/.test(sha);
+}
+
 /** A roster agent id used as a filesystem path segment — strict allowlist so
  *  it can't traverse (`..`, `/`) out of the worktrees dir. */
 export function isSafePathSegment(id) {
@@ -72,6 +100,19 @@ export function detectBaseRef(repoRoot) {
   }
 }
 
+/**
+ * The BRANCH NAME behind a base ref.
+ *
+ * `detectBaseRef` returns a remote-tracking ref (`origin/main`) because that is
+ * what you check out and reset against. GitHub's API has never heard of it: a PR
+ * base must be a branch that exists in the repo, so `gh pr edit --base
+ * origin/main` 422s every time. Anything that talks to the provider needs this
+ * form, not the ref.
+ */
+export function baseBranchName(baseRef) {
+  return String(baseRef || '').replace(/^origin\//, '') || 'main';
+}
+
 export function resetWorktree(wt, baseRef) {
   try {
     git(['fetch', 'origin', '--quiet'], wt);

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,12 @@ 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 conversation — that is rendered as prose, not JSON. */
+function briefWithoutThread(brief) {
+  const { thread: _thread, lastMessageId: _lastMessageId, ...rest } = brief ?? {};
+  return rest;
+}
+
 function seedPrompt(runId, brief, transcript, resumedInPlace) {
   return [
     `Your run id is ${runId}. Use it for every flowviant MCP tool call.`,
@@ -168,15 +185,24 @@ 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),
     ...(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 +397,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 +518,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 +565,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 +632,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 +765,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 +828,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 +1048,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) };
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowviant",
-  "version": "0.29.0",
+  "version": "0.30.0",
   "description": "Run your own Claude Code as headless build agents for Flowviant — on your own credentials. Claims dispatched work, opens PRs, captures review evidence, and routes questions back to you.",
   "type": "module",
   "bin": {