flowviant 0.29.0 → 0.31.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,59 @@ 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 }) =>
+/**
+ * CONSULT — someone is planning and asked a question only the repo can answer.
+ *
+ * Strictly read-only, and strictly an ANSWER: no edits, no commits, no branch,
+ * no MCP tools. A consult is not a dispatch, and the prompt says so out loud
+ * because the model is otherwise very willing to start building the thing it was
+ * asked about.
+ */
+export const SYSTEM_CONSULT = `You are a Flowviant build agent, but you are NOT building anything right now.
+Someone is PLANNING a feature and has asked you a question, because you are the
+one with the actual repository in front of you. The planner they are talking to
+sees only a module manifest and wiki summaries — you see the code.
+
+Your entire job is to ANSWER, from files you actually read.
+
+RULES:
+- READ ONLY. Do not edit, create or delete any file. No git writes, no commits,
+  no branches, no PRs. Nothing you do here leaves a trace in the repo.
+- Do NOT start implementing what they are planning, and do not offer to. If the
+  answer is "this needs building", say that and stop — they will dispatch it in
+  its own task thread when they are ready.
+- Ground every claim in something you opened. Cite concrete paths
+  (\`apps/api/src/middleware/auth.ts\`) so the answer can be checked.
+- If it already EXISTS, say so plainly and point at it — that is the single most
+  valuable thing you can tell someone mid-plan, and it is the answer they are
+  least expecting.
+- If the repo genuinely does not settle the question, say THAT rather than
+  guessing. "I can't tell from the code" is a real answer and a useful one.
+- Be brief: a few sentences, or a short list. This lands in a chat thread that a
+  human is reading while they think, not in a document.
+
+Write plain Markdown for a person. No preamble, no restating the question.`;
+
+export const CONSULT_KICKOFF = ({ planTitle, question, askedByName }) =>
+  `${askedByName || 'A teammate'} is planning ${planTitle ? `"${planTitle}"` : 'a feature'} and asked you:\n\n` +
+  `${question}\n\n` +
+  `Read the repo you are running in and answer. Do not change anything.`;
+
+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 +571,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,7 +51,11 @@ import {
   SYSTEM_WIKI,
   WIKI_KICKOFF,
   SYSTEM_REGROUND,
+  SYSTEM_PLAN_CHECK,
+  PLAN_CHECK_KICKOFF,
   REGROUND_KICKOFF,
+  SYSTEM_CONSULT,
+  CONSULT_KICKOFF,
 } from './claude.mjs';
 import { runLiveWorker } from './live.mjs';
 import { reapOrphanPreviews } from './preview.mjs';
@@ -197,6 +204,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 +315,203 @@ 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;
+  };
+
+  /** A clean detached checkout at base — what "the real code" has to mean for a
+   *  question about the repo, rather than whatever half-finished state an agent
+   *  worktree happens to be in. Shared by the plan check and consults. */
+  const ensureWikiWorktree = () => {
+    if (existsSync(wikiWt)) return;
+    try {
+      git(['worktree', 'add', '--detach', wikiWt, baseRef], repoRoot);
+    } catch {
+      git(['worktree', 'prune'], repoRoot);
+      git(['worktree', 'add', '--detach', wikiWt, baseRef], repoRoot);
+    }
+  };
+
+  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…`)}`);
+          ensureWikiWorktree();
+          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);
+        }
+      })();
+    }
+  };
+
+  // Consults — a planning question aimed at THIS machine, answered by reading
+  // the repo. Deliberately the lightest job on the roster: same read-only
+  // detached checkout the plan check uses, no MCP, no writes, no run recorded.
+  const CONSULT_DONE_URL = FLEET_URL.replace(/\/agents\/?$/, '/consult-done');
+  const answering = new Set();
+  const processConsultJobs = (jobs) => {
+    for (const job of jobs ?? []) {
+      if (!job || typeof job.id !== 'string' || !job.question) continue;
+      if (answering.has(job.id)) continue;
+      answering.add(job.id);
+      (async () => {
+        try {
+          note(`${c.cyan('ask')} ${c.dim(`— ${job.askedByName || 'someone'} asked about "${job.planTitle || 'a plan'}"`)}`);
+          ensureWikiWorktree();
+          const out = await runTurn({
+            prompt: CONSULT_KICKOFF({
+              planTitle: job.planTitle,
+              question: job.question,
+              askedByName: job.askedByName,
+            }),
+            resume: false,
+            system: SYSTEM_CONSULT,
+            cwd: wikiWt,
+            wikiPerm: true, // read-only file perms — no MCP, no shell writes
+            label: c.cyan('[ask]'),
+          });
+          const answer = (out || '').trim();
+          await reportMergeOutcome(CONSULT_DONE_URL, {
+            consultId: job.id,
+            ok: answer.length > 0,
+            // Scrub: an answer can quote config or env-adjacent code.
+            answer: envScrub(answer).slice(0, 8000),
+          });
+          ok(`${c.cyan('ask')} ${c.dim('— answered in the plan thread')}`);
+        } catch (e) {
+          // Settle it either way. A question that cannot be answered must not
+          // re-burn a Claude turn on every poll, and silence would leave the
+          // human waiting on a machine that already gave up.
+          await reportMergeOutcome(CONSULT_DONE_URL, {
+            consultId: job.id,
+            ok: false,
+            answer: e?.message ?? 'the read failed',
+          });
+          warn(`consult failed: ${e?.message ?? e}`);
+        } finally {
+          answering.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 +534,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 +599,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 +743,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 +924,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 +1076,9 @@ export async function runFleetDaemon() {
       if (updating) return;
     }
     processMergeJobs(roster.mergeJobs);
+    processPatchRevertJobs(roster.patchRevertJobs);
+    processPlanCheckJobs(roster.planCheckJobs);
+    processConsultJobs(roster.consultJobs);
     processCleanupJobs(roster.cleanupJobs);
     const rosterIds = new Set(roster.agents.map((a) => a.agentId));
 
@@ -912,7 +1171,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);