flowviant 0.78.0 → 0.79.0

package/bin/lib/git.mjs

@@ -1,11 +1,6 @@
 /** Git worktree helpers (fleet & static-fleet modes). */
 
 import { execFileSync } from 'node:child_process';
-import { existsSync, readFileSync, statSync } from 'node:fs';
-import { resolve, join } from 'node:path';
-import { rmSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { materializedFiles } from './env.mjs';
 
 export function git(args, cwd) {
   return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
@@ -144,161 +139,6 @@ export function baseBranchName(baseRef) {
   return String(baseRef || '').replace(/^origin\//, '') || 'main';
 }
 
-/**
- * Get a detached worktree at `wt`, creating it at `ref` if it isn't there.
- *
- * Returns `{ path, fresh }` — `fresh` is the whole point. A worktree that
- * ALREADY existed is one somebody was mid-way through, and the caller must not
- * reset it; a freshly created one is at base by construction and has nothing to
- * preserve. That single bit replaces the in-memory `resuming` flag and the
- * on-disk task marker for the common case, because once a worktree is named
- * after its task, "does this directory exist" IS "am I resuming".
- *
- * The prune-and-retry is not paranoia: `git worktree add` refuses a path that
- * is still REGISTERED even when the directory is gone (`flowviant clean` rm's
- * the dirs, `git worktree list` keeps the stale entries), and that failure is
- * permanent until pruned.
- */
-export function ensureWorktree(repoRoot, wt, ref) {
-  // Resolve first. `existsSync` answers relative to THIS process's cwd while
-  // `git worktree add` answers relative to repoRoot, so a relative path makes
-  // the two disagree: the check says "not there", the add says "already
-  // exists", and the prune-and-retry can't fix a path that was never the one
-  // we looked at. Callers pass absolute paths today; this makes that not matter.
-  wt = resolve(wt);
-  if (existsSync(wt)) return { path: wt, fresh: false };
-  try {
-    git(['worktree', 'add', '--detach', wt, ref], repoRoot);
-  } catch {
-    git(['worktree', 'prune'], repoRoot);
-    git(['worktree', 'add', '--detach', wt, ref], repoRoot);
-  }
-  return { path: wt, fresh: true };
-}
-
-// ── WIP checkpoints: the sandbox's state, on the remote ────────────────────
-//
-// A task's uncommitted work used to exist in exactly one place — a directory on
-// whichever machine claimed it. That made the checkout precious: losing the box
-// lost the work, so a task was pinned to a host, the host had to be named in the
-// UI, and a container could never be thrown away. Pushing the work somewhere
-// durable inverts all of that. The sandbox becomes a cache.
-//
-// These snapshots go to `refs/flowviant-wip/<intentId>`, NOT to a branch: they
-// are machine state, not history, and they must never appear in a PR, a branch
-// listing, or anyone's `git log`. Force-pushed, because only the latest matters.
-
-const wipRef = (intentId) => `refs/flowviant-wip/${intentId}`;
-
-/** git, with extra environment — for GIT_INDEX_FILE and a committer identity we
- *  can't assume the machine has configured. */
-function gitWithEnv(args, cwd, extraEnv) {
-  return execFileSync('git', args, {
-    cwd,
-    encoding: 'utf8',
-    stdio: ['ignore', 'pipe', 'pipe'],
-    env: { ...process.env, ...extraEnv },
-  }).trim();
-}
-
-/**
- * Snapshot everything in the worktree — staged, unstaged and untracked — and
- * push it, WITHOUT touching the agent's HEAD, index or files.
- *
- * That constraint is why this doesn't just commit. The agent is a live process
- * with its own git intentions; committing under it would rewrite state it is
- * mid-way through reasoning about, and `git stash` would rip the files out from
- * under an editor. Building the tree in a throwaway index leaves the agent's
- * world untouched — it cannot tell this happened.
- *
- * Returns the commit sha, or null if there was nothing dirty / no remote.
- *
- * This PUSHES, so what it stages is a security boundary, not a detail: the
- * daemon materializes plaintext env-vault secrets into this same worktree.
- * They are gitignored (materializeInto refuses to write them otherwise), and
- * `git add -A` honours .gitignore — but the whole point of the bug this guards
- * against was an exclusion mechanism that silently did nothing, so the paths
- * are ALSO subtracted by pathspec here. Two independent mechanisms, because one
- * of them failing quietly is exactly what put secrets on a remote branch.
- */
-export function checkpointWip(wt, intentId, baseRef) {
-  if (!isSafePathSegment(intentId)) return null;
-  const idx = join(tmpdir(), `flowviant-idx-${intentId}-${process.pid}`);
-  const env = {
-    GIT_INDEX_FILE: idx,
-    // A snapshot must never fail because the machine has no user.name — this is
-    // ours, not the user's, and it never lands in history anyone reads.
-    GIT_AUTHOR_NAME: 'Flowviant',
-    GIT_AUTHOR_EMAIL: 'daemon@flowviant.com',
-    GIT_COMMITTER_NAME: 'Flowviant',
-    GIT_COMMITTER_EMAIL: 'daemon@flowviant.com',
-  };
-  try {
-    const head = git(['rev-parse', 'HEAD'], wt);
-    gitWithEnv(['read-tree', head], wt, env);
-    gitWithEnv(
-      ['add', '-A', '--', '.', ...materializedFiles(wt).map((p) => `:(exclude)${p}`)],
-      wt,
-      env
-    );
-    const tree = gitWithEnv(['write-tree'], wt, env);
-    // Nothing changed since HEAD — no snapshot worth pushing.
-    if (tree === git(['rev-parse', `${head}^{tree}`], wt)) return null;
-    const commit = gitWithEnv(
-      ['commit-tree', tree, '-p', head, '-m', `flowviant wip ${intentId}`],
-      wt,
-      env
-    );
-    git(['push', '--force', 'origin', `${commit}:${wipRef(intentId)}`], wt);
-    return commit;
-  } catch {
-    // Offline, no push rights, a repo with no origin — a checkpoint is an
-    // optimisation, never a reason to fail a task.
-    return null;
-  } finally {
-    try {
-      rmSync(idx, { force: true });
-    } catch {
-      /* best-effort */
-    }
-    void baseRef;
-  }
-}
-
-/**
- * Rebuild a worktree from its last pushed checkpoint. Returns true if one was
- * found and applied.
- *
- * The reset is MIXED on purpose: it leaves the snapshot's content in the files
- * with HEAD back at the parent, which is what the agent had before — dirty
- * working tree, nothing staged it didn't stage itself. A soft reset would hand
- * it a fully-staged index it never created.
- */
-export function restoreWip(wt, intentId) {
-  if (!isSafePathSegment(intentId)) return false;
-  const ref = wipRef(intentId);
-  try {
-    git(['fetch', 'origin', `+${ref}:${ref}`], wt);
-    const commit = git(['rev-parse', ref], wt);
-    const parent = git(['rev-parse', `${commit}^`], wt);
-    git(['checkout', '--detach', commit], wt);
-    git(['reset', parent], wt);
-    return true;
-  } catch {
-    return false; // no checkpoint for this task, or it's unreachable
-  }
-}
-
-/** Drop a task's checkpoint once its work has landed somewhere real. */
-export function clearWip(wt, intentId) {
-  if (!isSafePathSegment(intentId)) return;
-  try {
-    git(['push', 'origin', '--delete', wipRef(intentId)], wt);
-  } catch {
-    /* already gone, or no remote */
-  }
-}
-
 export function resetWorktree(wt, baseRef) {
   try {
     git(['fetch', 'origin', '--quiet'], wt);
@@ -314,106 +154,3 @@ export function resetWorktree(wt, baseRef) {
   }
 }
 
-/**
- * What has changed in this worktree since `baseRef` — committed or not.
- *
- * The definition matters. `git diff --numstat <base>` (no `..HEAD`) compares the
- * base against the WORKING TREE, so it covers commits the agent has made, staged
- * work, and edits it has not committed yet. Anything narrower would go blank at
- * the exact moments you look: right after a commit, or before the first one.
- *
- * Untracked files are added separately — they are invisible to `git diff` and
- * are usually the most interesting thing an agent has done (a new module, a new
- * test). Their line counts are read here rather than inferred; a file too large
- * to be source is reported as a path with no counts instead of being read into
- * memory.
- *
- * PATHS AND COUNTS ONLY. Nothing in here returns file content.
- *
- * Both git calls are `-z`, for the reason gitRaw exists: git's line-based output
- * QUOTES any path that is not plain ASCII, so an accented filename arrives as
- * "n\303\251w.txt" — a string that is not the path, cannot be stat'd, and reads
- * as garbage in the tray. `-z` emits paths verbatim.
- */
-export function worktreeDiffstat(cwd, baseRef, { maxFiles = 200 } = {}) {
-  const files = [];
-  let additions = 0;
-  let deletions = 0;
-
-  const add = (path, added, removed) => {
-    additions += added;
-    deletions += removed;
-    files.push({ path, added, removed });
-  };
-
-  try {
-    // `--numstat -z` frames a normal change as one field, "added\tdeleted\tpath",
-    // but a RENAME as three: "added\tdeleted\t" (empty path), then the old path,
-    // then the new one. An empty path is therefore the rename marker, and the
-    // next two fields belong to it — read line-wise instead, a rename would
-    // report a file literally named "old => new".
-    const fields = splitNul(gitRaw(['diff', '--numstat', '-z', baseRef, '--'], cwd));
-    for (let i = 0; i < fields.length; i++) {
-      const [a, d, ...rest] = fields[i].split('\t');
-      let path = rest.join('\t');
-      if (!path) {
-        path = fields[i + 2] ?? fields[i + 1]; // the post-rename name is what exists now
-        i += 2;
-        if (!path) continue;
-      }
-      // Binary files report '-' for both counts; they changed, but not by lines.
-      add(path, a === '-' ? 0 : Number(a) || 0, d === '-' ? 0 : Number(d) || 0);
-    }
-  } catch {
-    // No base ref yet, or not a repo — nothing to report rather than a crash.
-    return null;
-  }
-
-  try {
-    const untracked = splitNul(
-      gitRaw(['ls-files', '--others', '--exclude-standard', '-z'], cwd)
-    );
-    for (const path of untracked) {
-      let added = 0;
-      // Past the cap this path will not be shown, so do not pay to read it.
-      // This is the one place the totals can undercount, and reaching it takes
-      // an untracked tree bigger than the list itself — a generated directory
-      // .gitignore missed. Statting and reading all of it on a 20s interval
-      // would block the roster poll and every other lane on this daemon.
-      if (files.length < maxFiles) {
-        try {
-          const st = statSync(join(cwd, path));
-          // Regular files ONLY. `git ls-files --others` will happily name a
-          // symlink or a fifo, and readFileSync on a fifo or a character device
-          // BLOCKS — on a 20s interval, on the daemon's single thread, that is
-          // the whole process wedged waiting for a device that may never write.
-          // 2 MB: past that it is a build artifact or a binary, and reading it
-          // to count newlines would be the most expensive thing this daemon does.
-          if (st.isFile() && st.size <= 2_000_000) {
-            const text = readFileSync(join(cwd, path), 'utf8');
-            // A NUL byte means binary. Counting "lines" in a PNG produces a
-            // number that is not wrong so much as meaningless, and it was being
-            // summed into the total shown beside git's real counts.
-            if (text.includes('\0')) throw new Error('binary');
-            // Lines, not segments. A file ending in a newline — i.e. essentially
-            // every source file an agent writes — splits into one more piece
-            // than it has lines, and that +1 was landing in the totals shown
-            // beside git's own counts.
-            added = text ? text.split('\n').length - (text.endsWith('\n') ? 1 : 0) : 0;
-          }
-        } catch {
-          /* vanished between listing and reading — report the path, no counts */
-        }
-      }
-      add(path, added, 0);
-    }
-  } catch {
-    /* untracked listing failed — the tracked half still stands */
-  }
-
-  if (files.length === 0) return null;
-  // Totals stay whole while the LIST is capped: a truncated list must never
-  // quietly shrink the number printed beside it.
-  const truncated = Math.max(0, files.length - maxFiles);
-  return { files: files.slice(0, maxFiles), additions, deletions, truncated };
-}

package/bin/lib/grant.mjs

@@ -171,12 +171,33 @@ export function safePathname(url) {
  * `//evil.com` and `/\evil.com` are protocol-relative to a browser, so a naive
  * "starts with /" check turns the callback into an open redirect on the tunnel
  * origin. Anything that is not a single-slash relative path becomes '/'.
+ *
+ * STRUCTURAL, NOT LEXICAL, and that distinction is the whole fix. This used to
+ * be `/^\/(?![/\\])/` plus a CR/LF check — and an audit walked through it with
+ * a TAB: browsers STRIP tab, CR and LF out of a URL before parsing, so
+ * `"/\t/evil.com"` passed the guard, was written verbatim into Location by the
+ * callback, and navigated to `//evil.com`. Parsing against a dummy base and
+ * re-serialising reproduces exactly what the browser will do — there is no
+ * second implementation of URL parsing here to drift, and the value returned
+ * is the one the parser produced. The lexical checks stay in front of it as
+ * the cheap first line; the origin comparison is the guarantee. Ported from
+ * the server twins (previewAuthorize.routes.ts, preview-relay util.ts), which
+ * closed the same hole the same way.
  */
 export function safeRelative(raw) {
   if (!raw) return '/';
   const s = String(raw);
   if (s.length > 512) return '/';
-  if (/[\r\n]/.test(s)) return '/';
-  if (!/^\/(?![/\\])/.test(s)) return '/';
-  return s;
+  if (!s.startsWith('/')) return '/';
+  if (/^\/[/\\]/.test(s)) return '/';
+  // Every C0 control, space and DEL — not just CR/LF.
+  // eslint-disable-next-line no-control-regex
+  if (/[\x00-\x20\x7f]/.test(s)) return '/';
+  try {
+    const u = new URL(s, 'https://x.invalid');
+    if (u.origin !== 'https://x.invalid') return '/';
+    return u.pathname + u.search + u.hash;
+  } catch {
+    return '/';
+  }
 }

package/bin/lib/landed.mjs

@@ -23,18 +23,19 @@
  * report nothing — ignorance is never turned into a state.
  */
 
+import { execFileSync } from 'node:child_process';
 import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
 import { createHash } from 'node:crypto';
 import { git, baseBranchName } from './git.mjs';
-import { taskIdsFromMessage } from './worktreeDiff.mjs';
+import { stripDelims, taskIdsFromMessage } from './worktreeDiff.mjs';
 import { warn } from './ui.mjs';
 import { FLEET_URL, FLEET_TOKEN, USER_AGENT } from './config.mjs';
 
 const LANDED_URL = FLEET_URL.replace(/\/agents\/?$/, '/base-landed');
 /** The server accepts 50 per report. A bigger range walks OLDEST-FIRST in
- *  batches: the persisted tip advances to the last commit actually reported,
+ *  batches: the persisted tip advances to the last commit actually walked,
  *  so the remainder is picked up on the next beat rather than skipped forever
  *  — a trailered card in commit 51 of a big catch-up still closes. */
 const MAX_COMMITS = 50;
@@ -74,27 +75,64 @@ export function createLandedObserver({ repoRoot, baseRef }) {
     }
   };
 
-  /** New non-merge commits in from..to, OLDEST FIRST. `--no-merges` for the
-   *  same reason branchCommits keeps it: a merge commit describes a range
-   *  rather than doing work, and its constituents are walked as themselves. */
+  /** git with the buffer the WALK needs. git.mjs's call takes execFileSync's
+   *  default 1MiB cap, and a catch-up range's `%B` bodies blew through it —
+   *  the throw landed in the reseed catch below, which skipped the whole range
+   *  and silently lost every trailer in it. 8MB is repoState's number for the
+   *  same reason; rev-list output at 41 bytes a commit clears ~200k commits
+   *  before it matters. */
+  const gitWide = (args) =>
+    execFileSync('git', args, {
+      cwd: repoRoot,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      maxBuffer: 8 * 1024 * 1024,
+    }).trim();
+
+  /** New non-merge commits in from..to, OLDEST FIRST — the next batch of at
+   *  most MAX_COMMITS, plus the tip the state should advance to when the range
+   *  held more. `--no-merges` for the same reason branchCommits keeps it: a
+   *  merge commit describes a range rather than doing work, and its
+   *  constituents are walked as themselves.
+   *
+   *  THE SHA LIST COMES FROM REV-LIST, NEVER FROM THE FORMATTED LOG. Git
+   *  preserves the 0x1e/0x1f delimiter bytes inside a commit BODY (verified
+   *  empirically), so a crafted message can fabricate whole records — an
+   *  arbitrary sha plus Flowviant-Task ids that /fleet/base-landed would close
+   *  cards on. rev-list prints nothing an author controls, so its output is
+   *  the set of commits that exist: a parsed record whose sha is not in the
+   *  batch is a forgery and is dropped, a repeated sha is the same forgery
+   *  wearing a real commit's name, and the delimiter bytes are stripped from
+   *  every surviving field.
+   *
+   *  BOUNDING THE BODY FETCH TO THE BATCH is what makes the header's batching
+   *  contract true at any range size: `%B` over the whole range grows without
+   *  bound, so the formatted log runs over exactly the shas being reported
+   *  this beat (`--no-walk=unsorted` shows precisely the commits named, in
+   *  argv order — measured). */
   const walk = (from, to) => {
-    const raw = git(
-      ['log', '--reverse', '--no-merges', '--format=%H%x1f%s%x1f%B%x1e', `${from}..${to}`],
-      repoRoot
-    );
+    const shas = gitWide(['rev-list', '--reverse', '--no-merges', `${from}..${to}`])
+      .split('\n')
+      .filter((s) => SHA_RE.test(s));
+    const batch = shas.slice(0, MAX_COMMITS);
+    const tipAfter = shas.length > MAX_COMMITS ? batch[batch.length - 1] : null;
+    if (batch.length === 0) return { commits: [], tipAfter };
+    const real = new Set(batch);
+    const raw = gitWide(['log', '--no-walk=unsorted', '--format=%H%x1f%s%x1f%B%x1e', ...batch]);
     const out = [];
     for (const rec of raw.split('\x1e')) {
       const line = rec.replace(/^\n+/, '');
       if (!line.trim()) continue;
-      const [sha, subject, body] = line.split('\x1f');
-      if (!SHA_RE.test(sha || '')) continue;
+      const [sha, subject, ...bodyParts] = line.split('\x1f');
+      if (!real.has(sha)) continue;
+      real.delete(sha);
       out.push({
         sha,
-        subject: String(subject || '').slice(0, 200),
-        taskIds: taskIdsFromMessage(body).slice(0, 8),
+        subject: stripDelims(subject).slice(0, 200),
+        taskIds: taskIdsFromMessage(stripDelims(bodyParts.join('\n'))).slice(0, 8),
       });
     }
-    return out;
+    return { commits: out, tipAfter };
   };
 
   /** Look at the base tip; if it moved, report the range. Call after anything
@@ -112,21 +150,30 @@ export function createLandedObserver({ repoRoot, baseRef }) {
       return;
     }
     if (st.tip === tip) return;
-    let all;
+    let walked;
     try {
-      all = walk(st.tip, ref);
+      walked = walk(st.tip, ref);
     } catch {
-      // The old tip is no longer answerable (force-push, gc) — reseed and
-      // report nothing rather than guess at a range.
-      writeState({ ref, tip });
+      // Two failures land here and only one may reseed. Probe the range
+      // directly: if rev-list cannot COUNT it, the old tip is genuinely gone
+      // (force-push, gc) and observation reseeds at the new one — ignorance is
+      // never turned into a state. Anything else (a transient spawn failure,
+      // an over-buffer) keeps the stored tip so the next beat retries the same
+      // range; reseeding on those was what skipped a whole catch-up range and
+      // permanently lost every trailer in it.
+      try {
+        git(['rev-list', '--count', `${st.tip}..${ref}`], repoRoot);
+      } catch {
+        writeState({ ref, tip });
+      }
       return;
     }
     // Oldest-first BATCH: a range past the server's cap advances the tip only
-    // to the last commit reported, so the remainder rides the next beat —
+    // to the last commit walked, so the remainder rides the next beat —
     // nothing is skipped forever. (A range of nothing but merge commits still
     // reports, tip-only: the tip moving is the fact deploy-on-merge rides.)
-    const commits = all.slice(0, MAX_COMMITS);
-    const reportedTip = all.length > MAX_COMMITS ? commits[commits.length - 1].sha : tip;
+    const commits = walked.commits;
+    const reportedTip = walked.tipAfter ?? tip;
     inFlight = true;
     try {
       const res = await fetch(LANDED_URL, {

package/bin/lib/preview.mjs

@@ -367,14 +367,17 @@ const TAIL_BYTES = 2000;
  * origin with 502, so without this the product would report "live" over a 502 —
  * Flowviant asserting a state it never measured.
  *
- * `stillServing` (optional, async → boolean) is the ATTRIBUTION re-check the
- * probe runs instead of a bare TCP connect. Ports are global to a box and a
- * worktree is not: when the driver's dev server dies and anything else — a
- * teammate's worktree, a database — binds the same number, a bare
- * `isListening` keeps the probe green and the existing URL+password serve the
- * NEW process, outside every consent gate. The caller passes the same
- * `listenersIn(worktree)` check the open path uses, so "the origin is alive"
- * keeps meaning "THIS session's origin".
+ * `stillServing` (optional, async → boolean) is the ATTRIBUTION check — the
+ * same `listenersIn(worktree)` predicate the caller ran at the boundary —
+ * and it guards EVERY gate in here, not just the probe: the open-time
+ * re-validation, one more look immediately before cloudflared spawns, and the
+ * recurring probe. Ports are global to a box and a worktree is not: when the
+ * driver's dev server dies and anything else — a teammate's worktree, a
+ * database — binds the same number, a bare `isListening` answers yes and the
+ * URL+password serve the NEW process, outside every consent gate. Three gates
+ * on one predicate, so "the origin is alive" always means "THIS session's
+ * origin"; a bare TCP connect stands in only when no predicate was given (an
+ * older caller).
  *
  * `onAbuse` fires when the gate closes itself after repeated failed password
  * attempts — AFTER the share is torn down locally — so the caller can report
@@ -400,10 +403,21 @@ export async function openTunnel({
   shareId,
   authorizeUrl,
 }) {
+  // ONE predicate for every liveness question this function asks. Attribution
+  // when the caller gave it, a bare TCP connect only when it did not; an
+  // attribution check that errors is not a "yes".
+  const serving = async () => {
+    try {
+      return stillServing ? await stillServing() : await isListening(port);
+    } catch {
+      return false;
+    }
+  };
+
   // Re-validate at the machine. The server checked this port against the last
   // report; reports are up to a minute old and a dev server is a process a
   // human can stop at any moment.
-  if (!(await isListening(port))) {
+  if (!(await serving())) {
     return { error: `nothing is listening on port ${port} in this worktree any more.` };
   }
 
@@ -464,6 +478,17 @@ export async function openTunnel({
     return { error: 'could not start the password gate for this preview, so nothing was published.' };
   }
 
+  // The last look BEFORE anything becomes public. Between the check above and
+  // here sit a possible cloudflared download and the gate's own bind — long
+  // enough for the dev server to die and an unrelated process to take the
+  // port, which a check that ran only at the top would never see again until
+  // the probe's first beat, up to probeMs later. Same predicate, so the moment
+  // the hostname exists it can only be pointing at THIS session's origin.
+  if (!(await serving())) {
+    stop();
+    return { error: `nothing is listening on port ${port} in this worktree any more.` };
+  }
+
   const args = ['tunnel', '--url', `http://localhost:${gate.port}`];
   // Send the origin the Host it expects. Vite and Next reject a Host they do
   // not recognise, so without this the tunnel resolves and then 403s.
@@ -513,13 +538,7 @@ export async function openTunnel({
       // share would keep serving a process nobody consented to publish.
       probe = setInterval(async () => {
         if (stopped) return;
-        let serving;
-        try {
-          serving = stillServing ? await stillServing() : await isListening(port);
-        } catch {
-          serving = false; // an attribution check that errors is not a "yes"
-        }
-        if (!serving) {
+        if (!(await serving())) {
           const dead = onDead;
           stop();
           try {

package/bin/lib/prompts.mjs

@@ -298,21 +298,16 @@ rules:
    it down: file_card the slice you are starting, raise_card the rest so the
    queue holds the plan instead of your context.
    FILL IN THE SHAPE when you do — \`points\`, \`acceptanceCriteria\` ("done
-   when", one line each), \`codeAnchors\` (the modules the card owns), and
-   \`priority\`. This is not bookkeeping: the forecast is computed from points and
-   anchors, and the ship review quiz is generated from the criteria. Leave them
-   empty and nothing breaks — the forecast quietly falls back to a flat default
-   and the review has less to ask about. A card you have just designed is the
-   only moment anyone knows those answers.
-   NAME THE FEATURE. When one ask becomes several cards, give them all the same
-   \`featureName\` — a short name a human would recognise ("Password reset",
-   "Billing export"). That is what lets the Board show them as one piece of work
-   instead of five loose rows. Reuse a name already on the board rather than
-   coining a synonym for it.
+   when", one line each), and \`codeAnchors\` (the modules the card owns). This
+   is not bookkeeping: points are how an agent's workload is budgeted when
+   cards are deployed, the ship review quiz is generated from the criteria,
+   and the anchors are what the planner reads. Leave them empty and nothing
+   breaks — the review just has less to ask about. A card you have just
+   designed is the only moment anyone knows those answers.
 10. YOU CAN CORRECT A CARD YOU ALREADY FILED. update_cards patches the SHAPE of
-   cards that exist — \`points\`, \`priority\`, \`featureName\` — up to 25 in one
-   call. This is the tool for "help me plan the backlog": list_cards, decide,
-   then send every change in ONE call. It cannot move a card, close one, assign
+   cards that exist — \`points\` and \`waitsOn\` — up to 25 in one call. This is
+   the tool for "help me plan the backlog": list_cards, decide, then send
+   every change in ONE call. It cannot move a card, close one, assign
    anyone or touch a receipt — organising a backlog is not working on it, so do
    not log_work or deliver anything you have not actually built. A card that is already delivered is refused, because its
    spec is what somebody's review is about. And when list_cards says
@@ -321,9 +316,11 @@ rules:
    SAY WHAT WAITS ON WHAT. \`waitsOn\` takes the task ids a card cannot start
    until, and it is what turns a feature from a heap into a sequence: the
    migration before the endpoint, the endpoint before the UI, the polish last.
-   The Board orders and bands cards from it — READY vs WAITING — so a person who
-   was not in this conversation can still see where to start. Declare it while
-   you are decomposing, because that is the one moment anyone knows.
+   When cards are deployed to agents, the split respects it — an agent holding
+   a card's prerequisite merges before the dependent one starts — and the task
+   page shows it, so a person who was not in this conversation can still see
+   where to start. Declare it while you are decomposing, because that is the
+   one moment anyone knows.
 11. DELIVER WITH RECEIPTS. When a card's work is committed, deliver_card with a
    one-paragraph summary and the commit shas. Delivered is ASSERTED; done is
    OBSERVED (the merge, on their word). Never claim done, and never deliver
@@ -483,8 +480,8 @@ export const WORK_TURN_KICKOFF_PLAIN = ({ sessionName, message, askedByName }) =
 
 
 /**
- * THE FEATURE NAME AND THE FILE LIST ARE FENCED, and they were the only two
- * unfenced strings left in this file.
+ * EVERY SERVER-CARRIED STRING HERE IS FENCED — the feature name, the file
+ * list, and the predicted-page list.
  *
  * A card title is member-authored, and worse: ticket triage falls back to the
  * REPORTER's ticket title verbatim, so a stranger can put words in it. That
@@ -496,9 +493,11 @@ export const WORK_TURN_KICKOFF_PLAIN = ({ sessionName, message, askedByName }) =
  * reset is the backstop, and it only cleans the wiki worktree. Anything written
  * outside it survives.
  *
- * Every other kickoff in this file already fences its untrusted input; this one
- * was simply missed. The file list is fenced for the same reason at lower
- * stakes — a path is attacker-influenceable too, and there is no cost to it.
+ * The predicted pages come off the roster exactly as the title does — a
+ * planner wrote them from card text, and card text is member-authored — so an
+ * unfenced `- <page>` line was the same injection lane with a different field
+ * name. The file list is fenced for the same reason at lower stakes: a path is
+ * attacker-influenceable too, and there is no cost to it.
  */
 export const REGROUND_KICKOFF = ({ sha, title, files, vaultDir, predictedPages = [] }) =>
   `A feature just merged. Re-ground the knowledge vault (${vaultDir}) for it.\n\n` +
@@ -510,10 +509,10 @@ export const REGROUND_KICKOFF = ({ sha, title, files, vaultDir, predictedPages =
   // 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`
+    ? `When this work was planned, the vault pages listed below were expected\n` +
+      `to go stale. Treat the list as a lead, not a fact — verify each against\n` +
+      `the code before editing, and ignore any that turned out to be unaffected:\n` +
+      `${fence('PREDICTED PAGES', 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` +