flowviant 0.75.0 → 0.77.0

package/bin/lib/work.mjs

@@ -28,7 +28,7 @@ import {
   mkdirSync,
   cpSync,
 } from 'node:fs';
-import { execFileSync } from 'node:child_process';
+import { execFileSync, spawn } from 'node:child_process';
 import { join, dirname } from 'node:path';
 import {
   FLEET_URL,
@@ -44,6 +44,7 @@ import { listenersIn, measureListeners, listenersSupported } from './listeners.m
 import { measureProcesses, liveGroups, processesSupported } from './processes.mjs';
 import { mutateRegistry, processAlive, readRegistry } from './procRegistry.mjs';
 import { createPlaceLock } from './placeLock.mjs';
+import { parseProposal, parseTurnResult } from './agentPlan.mjs';
 import { sweepMergedBranch } from './shipSweep.mjs';
 import { mergeOutward as shipMergeOutward } from './shipMerge.mjs';
 import { openTunnel } from './preview.mjs';
@@ -54,9 +55,21 @@ import {
   WORK_TURN_KICKOFF,
   SYSTEM_WORK_PLAIN,
   WORK_TURN_KICKOFF_PLAIN,
+  SYSTEM_PLAN,
+  AGENT_PLAN_KICKOFF,
+  SYSTEM_AGENT,
+  AGENT_TASK_KICKOFF,
+  AGENT_HUMAN_KICKOFF,
 } from './prompts.mjs';
 import { materializeInto, hasMaterialized, excludeInWorktree, scrub as envScrub } from './env.mjs';
-import { detectRuntimes, canRun, recordSkills, toolEventOf, RUNTIMES } from './runtimes.mjs';
+import {
+  detectRuntimes,
+  canRun,
+  pickRuntimeFor,
+  recordSkills,
+  toolEventOf,
+  RUNTIMES,
+} from './runtimes.mjs';
 
 /** The place id meaning "the checkout", not a worktree. Must match the
  *  server's REPO_PLACE — it is a wire value, not a local convention. */
@@ -142,6 +155,14 @@ export function createWorkManager({
   const ATTACHMENT_URL = FLEET_URL.replace(/\/agents\/?$/, '/attachment');
   const PR_CLAIM_URL = FLEET_URL.replace(/\/agents\/?$/, '/pr-claim');
   const PR_DONE_URL = FLEET_URL.replace(/\/agents\/?$/, '/pr-done');
+  const AGENT_PLAN_CLAIM_URL = FLEET_URL.replace(/\/agents\/?$/, '/agent-plan-claim');
+  const AGENT_PLAN_DONE_URL = FLEET_URL.replace(/\/agents\/?$/, '/agent-plan-done');
+  const AGENT_TURN_DONE_URL = FLEET_URL.replace(/\/agents\/?$/, '/agent-turn-done');
+  const AGENT_ACTIVITY_URL = FLEET_URL.replace(/\/agents\/?$/, '/agent-activity');
+  const AGENT_PARKED_URL = FLEET_URL.replace(/\/agents\/?$/, '/agent-parked');
+  const AGENT_CHECK_DONE_URL = FLEET_URL.replace(/\/agents\/?$/, '/agent-check-done');
+  const AGENT_MERGE_CLAIM_URL = FLEET_URL.replace(/\/agents\/?$/, '/agent-merge-claim');
+  const AGENT_MERGE_DONE_URL = FLEET_URL.replace(/\/agents\/?$/, '/agent-merge-done');
   // What arrived on base, whichever road it took — observed after every beat
   // that can move origin/<base>: the sweep's fetch, a ship's push, a PR merge
   // this daemon performed. See landed.mjs for the seeding and delivery rules.
@@ -3375,8 +3396,997 @@ export function createWorkManager({
    * self-delete when a place goes quiet); the other collections are belt over
    * braces for the windows around it.
    */
+  // ── AGENT PLAN JOBS: the Deploy press ──────────────────────────────────────
+  //
+  // Somebody selected cards and pressed Deploy. This turn works out HOW THE
+  // WORK SHOULD BE SPLIT across agents and stops — a person edits what it
+  // proposes on the board, and ACCEPTING is what spawns anything. Nothing here
+  // creates a worktree, a branch or a card.
+  //
+  // READ-ONLY IN THE CHECKOUT. `readOnly: true` selects CONSULT_PERM (Read,
+  // Grep, Glob and a few `git` reads — no Write, no Edit, no mkdir, no rm) and
+  // NO MCP is passed at all, so this turn has no control plane to reach even if
+  // the repository it reads tries to steer it. The proposal comes back as the
+  // turn's final message rather than through a tool, which is exactly what lets
+  // that permission set be this narrow.
+  //
+  // It takes the checkout's place lock as a READER, beside the operator's own
+  // tabs. It writes nothing, so a writer lock would only starve real work.
+  const planning = new Set(); // press ids in flight on this tick
+
+  const postAgentPlan = async (body) => {
+    try {
+      await fetch(AGENT_PLAN_DONE_URL, {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${FLEET_TOKEN}`,
+          'User-Agent': USER_AGENT,
+          'Content-Type': 'application/json',
+        },
+        signal: AbortSignal.timeout(30_000),
+        body: JSON.stringify({ ...body, instance: DAEMON_INSTANCE }),
+      });
+    } catch {
+      /* unsettled, and the server expires it — the asker is told, never spun */
+    }
+  };
+
+  const claimAgentPlan = async (id) => {
+    try {
+      const res = await fetch(AGENT_PLAN_CLAIM_URL, {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${FLEET_TOKEN}`,
+          'User-Agent': USER_AGENT,
+          'Content-Type': 'application/json',
+        },
+        signal: AbortSignal.timeout(15_000),
+        body: JSON.stringify({ id, instance: DAEMON_INSTANCE }),
+      });
+      const j = await res.json().catch(() => null);
+      return j?.data?.claimed === true;
+    } catch {
+      return false; // the peer may hold it; doing nothing is the safe answer
+    }
+  };
+
+  /**
+   * What a live agent has already TOUCHED, measured here rather than sent.
+   *
+   * The server could have shipped a copy of this, and deliberately does not:
+   * these are directories on THIS machine, and a server-side copy would be a
+   * second, staler source of truth for a fact the daemon is standing on top of.
+   *
+   * Uncommitted work AND commits against base, because a planner asking "will
+   * these collide" cares about both — a file this agent has already rewritten
+   * and merged into its own branch collides exactly as hard as one it is
+   * editing now.
+   */
+  const agentChangedFiles = (placeId) => {
+    if (!placeId || !isSafePathSegment(placeId)) return [];
+    const wt = join(baseDir, 'sessions', placeId);
+    if (!existsSync(wt)) return [];
+    const out = new Set();
+    for (const args of [
+      ['diff', '--name-only', 'HEAD'],
+      ['diff', '--name-only', `${baseRef()}...HEAD`],
+      ['ls-files', '--others', '--exclude-standard'],
+    ]) {
+      const r = git(args, wt);
+      if (typeof r !== 'string') continue;
+      for (const line of r.split('\n')) {
+        const f = line.trim();
+        if (f) out.add(f);
+        if (out.size >= 60) return [...out];
+      }
+    }
+    return [...out];
+  };
+
+  const runAgentPlan = async (job) => {
+    const id = String(job.id);
+    const tasks = Array.isArray(job.tasks) ? job.tasks : [];
+    // CLAIM BEFORE ANYTHING — including before the cheap refusal below.
+    //
+    // The settle is rejected unless the caller HOLDS the lease, so posting an
+    // error first meant the server discarded it and the press sat open forever,
+    // holding its cards out of Deploy. That is the opposite of the ordering a
+    // kill keeps (refuse cheaply, then claim) and it is because these two
+    // lanes settle differently: a kill's settle does not check a lease for the
+    // not-found case, and a plan's always does.
+    if (!(await claimAgentPlan(id))) return;
+    if (tasks.length === 0) {
+      // The press named cards the doc no longer has. A real answer, and one the
+      // board can explain, rather than a turn that plans nothing.
+      await postAgentPlan({ id, error: 'those cards are no longer on the board' });
+      return;
+    }
+
+    /**
+     * WHICH CLI PLANS. `pickRuntimeFor('consult')`, the same picker every other
+     * turn nobody @mentioned already uses — Claude when it is here (the prompts
+     * were written against it), otherwise whatever can express the profile.
+     *
+     * Deliberately NOT the project's runtime order: that order is about AGENTS,
+     * which hold a conversation across many turns and whose value is that held
+     * context. A planner runs once and reads; it takes what the machine has.
+     */
+    const rt = pickRuntimeFor('consult');
+    if (!rt) {
+      await postAgentPlan({ id, error: 'no CLI on this machine can run a read-only turn' });
+      return;
+    }
+    const liveAgents = (Array.isArray(job.liveAgents) ? job.liveAgents : []).map((a) => ({
+      id: String(a?.id ?? ''),
+      name: String(a?.name ?? ''),
+      status: String(a?.status ?? ''),
+      changedFiles: agentChangedFiles(a?.placeId),
+    }));
+
+    let out = '';
+    /** REMOVED IN A `finally`. `workChildren` is what `workBusy()` counts, and
+     *  a leaked entry keeps the daemon permanently "busy" — which blocks every
+     *  auto-update from that moment on, silently, until a restart. */
+    let planChild = null;
+    try {
+      await inPlace(REPO_PLACE, false, async () => {
+        out = await runTurn({
+          prompt: AGENT_PLAN_KICKOFF({
+            tasks,
+            liveAgents,
+            agentCap: Number.isInteger(job.agentCap) && job.agentCap > 0 ? job.agentCap : 3,
+          }),
+          system: SYSTEM_PLAN,
+          // READ-ONLY, and no MCP: `mcpArgs` is omitted entirely rather than
+          // passed empty, so there is no control plane on this turn at all.
+          readOnly: true,
+          cwd: repoRoot,
+          runtime: rt,
+          streamJson: true,
+          answerFromResult: true,
+          label: c.cyan('[plan]'),
+          onSpawn: (ch) => {
+            planChild = ch;
+            workChildren.set(ch, null);
+          },
+        });
+      });
+    } catch (e) {
+      await postAgentPlan({ id, error: envScrub(String(e?.message || e)).slice(0, 500) });
+      return;
+    } finally {
+      if (planChild) workChildren.delete(planChild);
+    }
+
+    const proposal = parseProposal(out);
+    if (!proposal) {
+      await postAgentPlan({
+        id,
+        // The CLI's own words when it has any — a turn that explained why it
+        // could not plan is far more use than "planning failed".
+        error: out.trim()
+          ? `the plan did not come back as JSON: ${envScrub(out).slice(0, 300)}`
+          : 'the planning turn produced no output — the CLI may be signed out',
+      });
+      return;
+    }
+    await postAgentPlan({ id, proposal, sessionRef: repoRoot });
+  };
+
+  const processAgentPlanJobs = (jobs) => {
+    if (!Array.isArray(jobs) || jobs.length === 0) return;
+    // ONE AT A TIME, and the cap is 1 rather than 5: a planning turn is a real
+    // model call, and a machine handed three at once would run three CLIs to
+    // answer questions nobody asked in that order.
+    for (const job of jobs.slice(0, 1)) {
+      const id = String(job?.id || '');
+      if (!id || planning.has(id)) continue;
+      planning.add(id);
+      void runAgentPlan(job).finally(() => planning.delete(id));
+    }
+  };
+
+  // ── AGENT TURNS: one task per prompt ───────────────────────────────────────
+  //
+  // An agent is one CLI in one worktree on one branch, working its cards ONE AT
+  // A TIME. The server types the next prompt when this one lands; this side
+  // does the work and reports what happened.
+  //
+  // NO MCP ON THIS TURN AT ALL. Everything the agent needs to say fits in its
+  // final JSON object, and everything it needs to PROVE is measured from git
+  // here afterwards — an agent naming its own commit shas would be a receipt
+  // pointing at whatever it liked. That is also what keeps this feature from
+  // adding a token kind to a scope map that has silently shipped empty twice.
+  //
+  // UNLEASED, unlike a plan or a kill. The server hands out at most one turn
+  // per agent per poll and its settle is conditional on the row still being
+  // pending, so a second daemon cannot advance the queue twice. What it could
+  // do is run a CLI twice in one worktree, which is what this in-flight set and
+  // the place lock prevent — the same discipline `processWorkTurns` keeps.
+  const agentTurns = new Set(); // turn ids in flight on this tick
+
+  /** Returns the server's reply, because it carries ONE instruction the machine
+   *  can act on immediately: `review: true` means the agent's queue just
+   *  emptied, so run the project's own check in the worktree we are already
+   *  standing in. A job lane for that would need a claim, a floor and a settle
+   *  to say something this reply already can. */
+  /** Turn ids whose work is DONE but whose report has not landed. The same
+   *  skip-guard `pendingWorkReports` is for a tab, and for the same reason: a
+   *  settle that fails to POST must not re-run the turn — that is a second CLI,
+   *  a second set of commits, and the operator's quota spent again. */
+  const agentReported = new Set();
+
+  const postAgentTurn = async (body) => {
+    agentReported.add(String(body.turnId));
+    try {
+      const res = await fetch(AGENT_TURN_DONE_URL, {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${FLEET_TOKEN}`,
+          'User-Agent': USER_AGENT,
+          'Content-Type': 'application/json',
+        },
+        signal: AbortSignal.timeout(30_000),
+        body: JSON.stringify(body),
+      });
+      const j = await res.json().catch(() => null);
+      // Landed. Forgetting it keeps the guard from growing without bound; a
+      // re-offer of a settled turn is refused server-side anyway.
+      if (res.ok) agentReported.delete(String(body.turnId));
+      return j?.data ?? null;
+    } catch {
+      // Unsettled, and the id STAYS in the guard: the server expires the turn
+      // and the agent lands in Stuck saying nobody ran it, which is far better
+      // than running it again for six hours.
+      return null;
+    }
+  };
+
+  const postAgentActivity = async (agentId, text) => {
+    try {
+      await fetch(AGENT_ACTIVITY_URL, {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${FLEET_TOKEN}`,
+          'User-Agent': USER_AGENT,
+          'Content-Type': 'application/json',
+        },
+        signal: AbortSignal.timeout(15_000),
+        body: JSON.stringify({ agentId, text }),
+      });
+    } catch {
+      /* narration is a readout; losing a line costs nothing */
+    }
+  };
+
+  /**
+   * DID THE ACCOUNT HIT A LIMIT?
+   *
+   * Deliberately a LITERAL MATCH on the few sentences the CLIs actually print,
+   * and the matched line is relayed VERBATIM. It is a trigger, not a
+   * classifier: nothing here decides what an error "means" or writes a sentence
+   * of its own, because the product's own rule is that it relays and never
+   * infers. The honest limit is that a phrasing nobody listed reads as an
+   * ordinary failed turn — which lands the agent in Stuck with the CLI's words
+   * attached, and is a perfectly survivable second-best.
+   */
+  const LIMIT_PHRASES = [
+    /usage limit reached/i,
+    /rate limit/i,
+    /you've reached your .* limit/i,
+    /quota exceeded/i,
+    /insufficient_quota/i,
+  ];
+  const limitLine = (text) => {
+    for (const line of String(text ?? '').split('\n')) {
+      const t = line.trim();
+      if (t && LIMIT_PHRASES.some((re) => re.test(t))) return envScrub(t).slice(0, 300);
+    }
+    return null;
+  };
+
+  /** Every sha that landed on this branch between two points. Measured, never
+   *  asserted — this is the whole reason an agent is not asked for its own. */
+  const commitsBetween = (wt, from) => {
+    if (!from) return [];
+    /**
+     * `--not <base>` and `--no-merges`, because `from..HEAD` alone reports
+     * BASE'S commits as this turn's receipts the moment anything folds base in
+     * — which the stale path does on purpose before a merge. A receipt naming
+     * somebody else's commit is worse than a missing one.
+     */
+    const out = git(
+      ['log', '--format=%H', '--no-merges', `${from}..HEAD`, '--not', baseRef()],
+      wt
+    );
+    return typeof out === 'string'
+      ? out.split('\n').map((x) => x.trim()).filter(Boolean).slice(0, 50)
+      : [];
+  };
+
+  const runAgentTurn = async (job) => {
+    const turnId = String(job.id);
+    const agentId = String(job.agentId || '');
+    const place = String(job.placeId || '');
+    if (!isSafePathSegment(place)) {
+      await postAgentTurn({ turnId, outcome: 'nothing' });
+      return;
+    }
+    /**
+     * A TASK TURN WITH NO CARD IS REFUSED, NOT IMPROVISED.
+     *
+     * The kickoff below branches on `job.kind === 'task' && job.task` and falls
+     * through to the HUMAN kickoff otherwise — and a task turn's body is empty
+     * by design, because the daemon composes the prompt from the card's own
+     * spec. So a card deleted while its agent held it spawned a real CLI on a
+     * prompt whose entire content was "a member of this project said: (nothing).
+     * Carry on, and end with the JSON object." Nothing on either side refused
+     * it, and an ordinary gesture reached it: the board's Delete.
+     *
+     * The server now declines to hand out such a job at all. This is the
+     * backstop, and it is worth having on its own: it costs one comparison and
+     * it is the layer that cannot be skipped by a server on an older deploy.
+     * `nothing` is the honest outcome — the agent goes to Stuck saying the turn
+     * produced nothing, which is exactly what happened.
+     */
+    if (job.kind === 'task' && !job.task) {
+      await postAgentTurn({
+        turnId,
+        outcome: 'nothing',
+        answer: 'the card this turn was for no longer exists',
+      });
+      return;
+    }
+
+    await inPlace(place, false, async () => {
+      const dir = placeWtFor(place);
+      if (!dir) {
+        // No worktree and none could be cut. `nothing` rather than an invented
+        // error: the board says the machine went quiet, which is true.
+        await postAgentTurn({ turnId, outcome: 'nothing' });
+        return;
+      }
+      const wt = dir.wt;
+      // WHERE THE BRANCH WAS BEFORE THIS TURN, so the commits reported are the
+      // ones this turn actually made.
+      const before = (git(['rev-parse', 'HEAD'], wt) || '').trim() || null;
+      const branch = (git(['symbolic-ref', '--quiet', '--short', 'HEAD'], wt) || '').trim() || null;
+
+      const rt = job.runtime || 'claude';
+      if (!canRun(RUNTIMES[rt], 'build')) {
+        await postAgentTurn({
+          turnId,
+          outcome: 'nothing',
+          answer: `this machine cannot run ${rt}`,
+          branch,
+          worktree: wt,
+        });
+        return;
+      }
+
+      // ONE AGENT IS ONE DIRECTORY, so the CLI's own cwd-keyed resume is exactly
+      // right here — the ambiguity that forced per-tab session pinning in the
+      // Workbench (many tabs, one place) cannot arise. The marker is what
+      // distinguishes the first turn from every later one across restarts.
+      const ranMarker = sessionMetaPath(wt, 'flowviant-agent-ran');
+      /**
+       * RESUME IS CLAUDE-ONLY, and that is a correctness rule rather than a
+       * preference. Claude's `--continue` is CWD-keyed and one agent is one
+       * directory, so it resumes exactly this agent. Codex's `resume --last` is
+       * MACHINE-GLOBAL: it would cross-resume whichever conversation spoke most
+       * recently anywhere on the box, which is the bug the Workbench fixed in
+       * 0.69.0 by pinning per-tab ids. Until an agent pins its own thread id,
+       * a codex agent starts fresh each turn — a worse turn, not a wrong one.
+       */
+      const resume = rt === 'claude' && Boolean(ranMarker && existsSync(ranMarker));
+
+      let out = '';
+      let child = null;
+      try {
+        out = await runTurn({
+          prompt:
+            job.kind === 'task' && job.task
+              ? AGENT_TASK_KICKOFF({
+                  agentName: job.agentName,
+                  task: job.task,
+                  position: job.position ?? 1,
+                  total: job.total ?? 1,
+                })
+              : AGENT_HUMAN_KICKOFF({
+                  agentName: job.agentName,
+                  message: job.body ?? '',
+                  askedByName: job.askedByName,
+                  task: job.task,
+                  position: job.position ?? 1,
+                  total: job.total ?? 1,
+                }),
+          system: SYSTEM_AGENT,
+          cwd: wt,
+          runtime: rt,
+          resume,
+          streamJson: true,
+          answerFromResult: true,
+          label: c.cyan('[agent]'),
+          // The CLI's own tail, relayed. Throttled by the same rule the tab's
+          // narrator keeps: overwritten, never appended, and ignored by the
+          // board past ~90 seconds.
+          onActivity: (a) => {
+            const line = a?.label;
+            if (!line) return;
+            const now = Date.now();
+            if (now - (lastAgentBeat.get(agentId) ?? 0) < 2_000) return;
+            lastAgentBeat.set(agentId, now);
+            void postAgentActivity(agentId, envScrub(String(line)).slice(0, 400));
+          },
+          onSpawn: (ch) => {
+            child = ch;
+            workChildren.set(ch, null);
+            noteSessionGroup(agentId, ch.pid);
+          },
+        });
+      } finally {
+        if (child) workChildren.delete(child);
+        if (ranMarker) {
+          try {
+            writeFileSync(ranMarker, '1');
+          } catch {
+            /* a missing marker only costs one un-resumed turn */
+          }
+        }
+      }
+
+      const commits = commitsBetween(wt, before);
+      const res = parseTurnResult(out);
+      /**
+       * A LIMIT IS ONLY A LIMIT WHEN THE TURN PRODUCED NOTHING.
+       *
+       * `limitLine` is a literal phrase match over the CLI's output, and the
+       * output of a successful turn contains whatever the agent wrote — so a
+       * card about rate limiting, or a summary mentioning one, parked every
+       * agent on the project. Gating on "the turn declared no outcome" is what
+       * makes the match mean what it says: the CLI failed and this is the
+       * sentence it failed with.
+       */
+      const limit = res ? null : limitLine(out);
+      if (limit) {
+        // EVERY agent parks, because the account is shared: one hitting the
+        // limit means all of them have. The turn itself is reported as
+        // `nothing` — it did not deliver and it did not ask.
+        await postAgentParked(limit);
+        await postAgentTurn({ turnId, outcome: 'nothing', answer: limit, branch, worktree: wt });
+        return;
+      }
+
+      if (!res) {
+        await postAgentTurn({
+          turnId,
+          outcome: 'nothing',
+          // The CLI's own words when it produced any. A turn that explained why
+          // it stopped is far more use than "the agent stopped".
+          answer: out.trim()
+            ? envScrub(out).slice(-1500)
+            : 'the turn produced no output on the machine — its CLI may be signed out',
+          ...(commits.length ? { commits } : {}),
+          branch,
+          worktree: wt,
+        });
+        return;
+      }
+      const reply = await postAgentTurn({
+        turnId,
+        outcome: res.outcome,
+        answer: envScrub(res.answer ?? '').slice(0, 8000),
+        ...(commits.length ? { commits } : {}),
+        ...(res.raised?.length ? { raised: res.raised } : {}),
+        branch,
+        worktree: wt,
+      });
+      // The queue just emptied. Run the project's own check HERE, in the
+      // worktree we are already standing in and still hold the lock on.
+      if (reply?.review === true) await runCheck(agentId, wt);
+    });
+  };
+
+  const lastAgentBeat = new Map(); // agentId -> last activity POST, ms
+
+  const postAgentParked = async (reason) => {
+    try {
+      await fetch(AGENT_PARKED_URL, {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${FLEET_TOKEN}`,
+          'User-Agent': USER_AGENT,
+          'Content-Type': 'application/json',
+        },
+        signal: AbortSignal.timeout(15_000),
+        body: JSON.stringify({ reason }),
+      });
+    } catch {
+      /* the next turn will hit the same limit and try again */
+    }
+  };
+
+  const processAgentTurnJobs = (jobs) => {
+    if (!Array.isArray(jobs) || jobs.length === 0) return;
+    for (const job of jobs.slice(0, 4)) {
+      const id = String(job?.id || '');
+      if (!id || agentTurns.has(id)) continue;
+      // Already RAN here; only the report is outstanding. Re-running it would
+      // spend the operator's quota again and write a second set of commits.
+      if (agentReported.has(id)) continue;
+      if (!job.agentId || !job.placeId) continue;
+      agentTurns.add(id);
+      void runAgentTurn(job).finally(() => agentTurns.delete(id));
+    }
+  };
+
+  // ── THE PROJECT'S OWN CHECK, and the MERGE ─────────────────────────────────
+  //
+  // The check runs in the agent's own worktree the moment its queue empties, so
+  // a reviewer knows before they start reading whether they are reviewing
+  // working code. It LABELS the review row; it never blocks it.
+  //
+  // IT IS THE REPO'S COMMAND, DECLARED IN THE REPO. `.flowviant/check.json`,
+  // beside `deploy.json`, because a check travels with the code and changes
+  // with it — a setting in the app would go stale the first time somebody
+  // renamed a script. An absent file is a MEASURED answer ('none'), not a nag:
+  // plenty of projects have no single command that means "is this alright".
+  //
+  // It runs through a shell, and that is no wider than what already happens in
+  // that directory: every turn in this worktree spawns a CLI with build
+  // permissions, so a repository that can run arbitrary code during a turn can
+  // run it here too. What this is NOT is the deleted dev-run supervisor —
+  // nothing here resolves a command, guesses a stack, or starts a server.
+  const CHECK_TIMEOUT_MS = 10 * 60_000;
+  const CHECK_OUTPUT_CAP = 4000;
+
+  const readCheckCommand = () => {
+    try {
+      const raw = readFileSync(join(repoRoot, '.flowviant', 'check.json'), 'utf8');
+      const cfg = JSON.parse(raw);
+      const cmd = typeof cfg?.command === 'string' ? cfg.command.trim() : '';
+      return cmd ? cmd.slice(0, 500) : null;
+    } catch {
+      return null; // absent, unreadable or not JSON — all mean "no check"
+    }
+  };
+
+  const postCheck = async (body) => {
+    try {
+      await fetch(AGENT_CHECK_DONE_URL, {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${FLEET_TOKEN}`,
+          'User-Agent': USER_AGENT,
+          'Content-Type': 'application/json',
+        },
+        signal: AbortSignal.timeout(30_000),
+        body: JSON.stringify(body),
+      });
+    } catch {
+      /* the row simply keeps its previous answer, which is null the first time */
+    }
+  };
+
+  const runCheck = async (agentId, wt) => {
+    const cmd = readCheckCommand();
+    const headSha = (git(['rev-parse', 'HEAD'], wt) || '').trim() || undefined;
+    if (!cmd) {
+      await postCheck({ agentId, status: 'none', ...(headSha ? { headSha } : {}) });
+      return;
+    }
+    const out = await new Promise((resolve) => {
+      let text = '';
+      let done = false;
+      const finish = (status) => {
+        if (done) return;
+        done = true;
+        resolve({ status, text });
+      };
+      let child;
+      try {
+        // DETACHED, so the child's pid is its PROCESS GROUP. A check is almost
+        // always a shell that spawns the real runner, and signalling the shell
+        // alone leaves the runner holding the worktree — and this place's
+        // WRITER lock — for as long as it likes.
+        child = spawn(cmd, {
+          cwd: wt,
+          shell: true,
+          detached: true,
+          stdio: ['ignore', 'pipe', 'pipe'],
+        });
+      } catch (e) {
+        // TEXT BEFORE FINISH: `finish` captures `text` by value into the
+        // resolved object, so assigning afterwards threw the spawn error away
+        // and the surface showed an empty failure.
+        text = String(e?.message || e);
+        finish('failed');
+        return;
+      }
+      // The TAIL, not the head: a failing check says why at the end.
+      const keep = (buf) => {
+        text = (text + buf.toString()).slice(-CHECK_OUTPUT_CAP);
+      };
+      child.stdout?.on('data', keep);
+      child.stderr?.on('data', keep);
+      const timer = setTimeout(() => {
+        try {
+          // The GROUP, not the child: killing the shell leaves whatever it
+          // started running, which is the thing actually taking ten minutes.
+          process.kill(-child.pid, 'SIGKILL');
+        } catch {
+          try {
+            child.kill('SIGKILL');
+          } catch {
+            /* already gone */
+          }
+        }
+        text += '\n[flowviant] the check ran past ten minutes and was stopped';
+        // RESOLVE HERE TOO. Waiting for 'close' after a kill is the shape that
+        // hangs: if the group is already gone the event never arrives, and this
+        // promise holds the place's writer lock forever.
+        finish('failed');
+      }, CHECK_TIMEOUT_MS);
+      child.on('error', (e) => {
+        clearTimeout(timer);
+        text += String(e?.message || e);
+        finish('failed');
+      });
+      child.on('close', (code) => {
+        clearTimeout(timer);
+        finish(code === 0 ? 'passed' : 'failed');
+      });
+    });
+    await postCheck({
+      agentId,
+      status: out.status,
+      output: envScrub(out.text).slice(-CHECK_OUTPUT_CAP),
+      ...(headSha ? { headSha } : {}),
+    });
+  };
+
+  // ── THE MERGE ──────────────────────────────────────────────────────────────
+  //
+  // LEASED, because two `git merge --no-ff` and two pushes over one branch is
+  // the loudest duplicate this system can produce. It reuses `mergeOutward`
+  // verbatim — the same throwaway-worktree merge, the same once-only retry when
+  // two people land at the same moment — because an agent's branch is not
+  // special: it is a branch, and this repo already knows how to land one.
+  //
+  // A SUCCESS CLOSES NOTHING. Done stays OBSERVED: the merge reaches base, the
+  // landed observer's own fetch sees it, and the cards close there.
+  const agentMerges = new Set(); // agent ids in flight on this tick
+
+  const claimAgentMerge = async (agentId) => {
+    try {
+      const res = await fetch(AGENT_MERGE_CLAIM_URL, {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${FLEET_TOKEN}`,
+          'User-Agent': USER_AGENT,
+          'Content-Type': 'application/json',
+        },
+        signal: AbortSignal.timeout(15_000),
+        body: JSON.stringify({ agentId, instance: DAEMON_INSTANCE }),
+      });
+      const j = await res.json().catch(() => null);
+      return j?.data?.claimed === true;
+    } catch {
+      return false; // the peer may hold it; doing nothing is the safe answer
+    }
+  };
+
+  const postAgentMerge = async (body) => {
+    try {
+      await fetch(AGENT_MERGE_DONE_URL, {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${FLEET_TOKEN}`,
+          'User-Agent': USER_AGENT,
+          'Content-Type': 'application/json',
+        },
+        signal: AbortSignal.timeout(30_000),
+        body: JSON.stringify({ ...body, instance: DAEMON_INSTANCE }),
+      });
+    } catch {
+      /* the lease lapses and the job is re-offered — a merge is idempotent
+         against an already-merged branch, which mergeOutward detects */
+    }
+  };
+
+  /**
+   * A merge COMMIT needs a git identity and the machine may have none. Prefer
+   * the operator's own config; fall back to the daemon's, the same fallback
+   * `checkpointWip` and ship both use, so a bare machine does not fail the fold
+   * with "Please tell me who you are".
+   */
+  const gitMerge = (args, cwd) => {
+    let idEnv = null;
+    try {
+      git(['config', 'user.email'], repoRoot);
+    } catch {
+      idEnv = {
+        GIT_AUTHOR_NAME: 'Flowviant',
+        GIT_AUTHOR_EMAIL: 'daemon@flowviant.com',
+        GIT_COMMITTER_NAME: 'Flowviant',
+        GIT_COMMITTER_EMAIL: 'daemon@flowviant.com',
+      };
+    }
+    return execFileSync('git', args, {
+      cwd,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      ...(idEnv ? { env: { ...process.env, ...idEnv } } : {}),
+    });
+  };
+
+  const runAgentMerge = async (job) => {
+    const agentId = String(job.agentId);
+    const place = String(job.placeId || '');
+    if (!isSafePathSegment(place)) {
+      await postAgentMerge({ agentId, ok: false, detail: 'the agent has no worktree here' });
+      return;
+    }
+    if (!(await claimAgentMerge(agentId))) return;
+
+    // A WRITER on the place, exactly as a ship is. It folds base in and pushes
+    // with git in that directory, and no CLI can coordinate with something it
+    // does not know exists.
+    await inPlace(place, true, async () => {
+      const wt = join(baseDir, 'sessions', place);
+      if (!existsSync(wt)) {
+        await postAgentMerge({ agentId, ok: false, detail: 'the worktree is gone' });
+        return;
+      }
+      try {
+        git(['fetch', 'origin', '--quiet'], repoRoot);
+      } catch {
+        /* offline — the merge fails honestly below */
+      }
+      // STALE means base moved under this branch while it sat in review. Fold
+      // base IN first so the merge that follows is against what is actually
+      // there; a conflict here is the same conflict the merge would hit, found
+      // one step earlier and in the agent's own directory where it can be
+      // resolved.
+      if (job.stale) {
+        try {
+          gitMerge(['merge', '--no-edit', baseRef()], wt);
+        } catch (e) {
+          await postAgentMerge({
+            agentId,
+            ok: false,
+            detail: envScrub(String(e?.message || e)).slice(0, 2000),
+          });
+          return;
+        }
+        // The branch changed, so the previous check answered about a different
+        // tree. Re-run it before anything merges.
+        await runCheck(agentId, wt);
+      }
+      // `git()` THROWS on a non-zero exit, and `symbolic-ref` exits non-zero on
+      // a detached HEAD — so the guard below was unreachable and the throw
+      // escaped the claimed merge, leaving it unsettled until its lease lapsed.
+      let branch = '';
+      try {
+        branch = (git(['symbolic-ref', '--quiet', '--short', 'HEAD'], wt) || '').trim();
+      } catch {
+        branch = '';
+      }
+      if (!branch) {
+        // A detached HEAD names no branch, so there is nothing to merge and
+        // nothing to record. An ambiguity in git, not a rule of ours.
+        await postAgentMerge({ agentId, ok: false, detail: 'this worktree is on a detached HEAD' });
+        return;
+      }
+      const tip = (git(['rev-parse', 'HEAD'], wt) || '').trim();
+      const countOut = git(['rev-list', '--count', `${baseRef()}..HEAD`], wt);
+      const count = Number((countOut || '0').trim()) || 0;
+      if (count === 0) {
+        // Already on base — an idempotent re-offer, or an agent that changed
+        // nothing. Reported as a SUCCESS: the branch's work is on base, which
+        // is what the caller is asking about.
+        await postAgentMerge({ agentId, ok: true, sha: tip || undefined });
+        return;
+      }
+      /**
+       * THIS PROJECT MERGES THROUGH A PULL REQUEST.
+       *
+       * PR mode existed for sessions and was simply not honoured for agents:
+       * nothing read the project's merge mode on this path and the direct
+       * merge below ran unconditionally. On the repos PR mode exists FOR —
+       * branch protection refuses a direct push of a merge commit — every
+       * agent approval failed at the push and came back to review carrying
+       * git's refusal, forever.
+       *
+       * PUSH, CREATE, MERGE, in that order, and each step's reasoning is the
+       * session PR job's: push first because GitHub merges the REMOTE tip;
+       * `--fill` titles from the branch's own commits so nothing is invented;
+       * `--merge` and never squash, because the cards' receipts are commit
+       * shas and a squash rewrites them off base, orphaning every receipt and
+       * blinding the landed observer's trailer read. Adopt only an OPEN PR:
+       * gh's branch finder falls back to the most recent merged one, and
+       * adopting a dead PR would report success over work that never moves.
+       */
+      if (job.prMode) {
+        try {
+          execFileSync('gh', ['auth', 'status'], { stdio: ['ignore', 'pipe', 'pipe'] });
+        } catch (e) {
+          await postAgentMerge({
+            agentId,
+            ok: false,
+            detail:
+              e?.code === 'ENOENT'
+                ? 'this project merges through pull requests, and the GitHub CLI (gh) is not installed on this machine'
+                : `this project merges through pull requests, and gh is not signed in here: ${ghFirstLine(e)}`,
+          });
+          return;
+        }
+        const prBase = baseBranchName(baseRef());
+        if (branch === prBase) {
+          await postAgentMerge({
+            agentId,
+            ok: false,
+            detail: `this agent is on the base branch (${prBase}) — there is nothing to open a pull request from`,
+          });
+          return;
+        }
+        try {
+          git(['push', '-u', 'origin', branch], wt);
+        } catch (e) {
+          await postAgentMerge({ agentId, ok: false, detail: ghFirstLine(e) });
+          return;
+        }
+        let prUrl = null;
+        try {
+          const j = JSON.parse(
+            execFileSync('gh', ['pr', 'view', branch, '--json', 'url,state'], {
+              cwd: repoRoot,
+              stdio: ['ignore', 'pipe', 'pipe'],
+            }).toString()
+          );
+          if (j?.state === 'OPEN' && typeof j?.url === 'string') prUrl = j.url.trim();
+        } catch {
+          /* no PR for this branch at all — created below */
+        }
+        if (!prUrl) {
+          try {
+            const out = execFileSync(
+              'gh',
+              // baseBranchName, not baseRef: gh 422s on a remote-tracking name.
+              ['pr', 'create', '--head', branch, '--base', prBase, '--fill'],
+              { cwd: repoRoot, stdio: ['ignore', 'pipe', 'pipe'] }
+            )
+              .toString()
+              .trim();
+            prUrl = out.split('\n').filter(Boolean).pop() ?? null;
+          } catch (e) {
+            await postAgentMerge({ agentId, ok: false, detail: ghFirstLine(e) });
+            return;
+          }
+        }
+        try {
+          execFileSync('gh', ['pr', 'merge', branch, '--merge'], {
+            cwd: repoRoot,
+            stdio: ['ignore', 'pipe', 'pipe'],
+          });
+        } catch (e) {
+          const line = ghFirstLine(e);
+          // Already merged is a SUCCESS: a re-offered job, or somebody merged
+          // it in the browser. The observer closes the cards either way.
+          if (!/already merged/i.test(line)) {
+            await postAgentMerge({
+              agentId,
+              ok: false,
+              detail:
+                prUrl && PR_URL_RE.test(prUrl) ? `${line} — the pull request is at ${prUrl}` : line,
+            });
+            return;
+          }
+        }
+        // THE TIP, not a merge commit: the merge commit was made on GitHub and
+        // this machine has not fetched it. It identifies the state we asked to
+        // be merged, which is what the receipt is for — the cards themselves
+        // close when the landed observer sees the commits arrive on base.
+        await postAgentMerge({ agentId, ok: true, sha: tip });
+        onRepoChanged();
+        landed.observe();
+        return;
+      }
+      try {
+        shipMergeOutward({
+          tip,
+          count,
+          branch,
+          label: job.agentName || place.slice(0, 12),
+          git,
+          gitMerge,
+          repoRoot,
+          tmpDir: join(baseDir, 'ship', place),
+          baseRef,
+          workingTree: wt,
+          warn,
+        });
+      } catch (e) {
+        await postAgentMerge({
+          agentId,
+          ok: false,
+          detail: envScrub(String(e?.message || e)).slice(0, 2000),
+        });
+        return;
+      }
+      await postAgentMerge({ agentId, ok: true, sha: tip });
+      onRepoChanged();
+      landed.observe();
+    });
+  };
+
+  const processAgentMergeJobs = (jobs) => {
+    if (!Array.isArray(jobs) || jobs.length === 0) return;
+    for (const job of jobs.slice(0, 2)) {
+      const id = String(job?.agentId || '');
+      if (!id || agentMerges.has(id)) continue;
+      agentMerges.add(id);
+      void runAgentMerge(job).finally(() => agentMerges.delete(id));
+    }
+  };
+
+  /**
+   * KEEP EACH PERSON'S MANUAL WORKTREE FRESH.
+   *
+   * Every teammate's Workbench tabs share one directory of their own on a
+   * branch of their own — which is not a preference, it is what git allows:
+   * two worktrees cannot have the same branch checked out, so "everyone works
+   * on main" is only true for the machine's OPERATOR, whose place is the
+   * checkout itself. Everyone else needs a branch, and a branch left alone
+   * drifts behind main until the first thing they do in a new tab is a merge
+   * they did not ask for.
+   *
+   * FAST-FORWARD ONLY, and that is the whole safety argument. If their branch
+   * has no commits of its own it simply catches up, which is the ordinary case
+   * and the one worth automating. The moment it HAS diverged, this stops and
+   * leaves it exactly as it is: their commits are theirs, a rebase would
+   * rewrite them under somebody who is not looking, and a merge would put a
+   * commit in their history that they did not make. Their own Claude can fold
+   * base in whenever they ask it to.
+   *
+   * Guarded three ways: a DIRTY tree is left alone (uncommitted work outranks
+   * freshness), a place with a live lock is skipped (a turn is standing in it),
+   * and the whole thing is silent — nothing here reports, warns or blocks.
+   */
+  const freshenManualPlaces = () => {
+    let dir;
+    try {
+      dir = readdirSync(join(baseDir, 'sessions'));
+    } catch {
+      return; // no worktrees yet
+    }
+    for (const place of dir) {
+      // Only a PERSON's manual place. An agent's own worktree (`a-<id>`) is
+      // deliberately not touched: its branch is the reviewable unit, and
+      // moving it under a review would change what somebody is deciding about.
+      if (!place.startsWith('u-') || !isSafePathSegment(place)) continue;
+      if (placeLocks.has(place)) continue;
+      const wt = join(baseDir, 'sessions', place);
+      try {
+        if (git(['status', '--porcelain'], wt).trim() !== '') continue;
+        git(['merge', '--ff-only', baseRef()], wt);
+      } catch {
+        /* diverged, or something else is going on in there. Leave it. */
+      }
+    }
+  };
+
   const workBusy = () =>
     placeLocks.size > 0 ||
+    // A planning turn is a live CLI child of ours, and an auto-update that
+    // SIGTERMs it mid-flight would leave a press claimed, unsettled and
+    // waiting out its lease while somebody watches a spinner.
+    planning.size > 0 ||
+    // An agent turn is real work in a real worktree. Killed mid-flight it
+    // leaves uncommitted edits and a turn the server will eventually expire
+    // into a card nobody can explain.
+    agentTurns.size > 0 ||
+    agentMerges.size > 0 ||
     shipping.size > 0 ||
     workChildren.size > 0 ||
     workAnswering.size > 0 ||
@@ -3400,5 +4410,9 @@ export function createWorkManager({
     reportWorktrees,
     shutdownWork,
     workBusy,
+    processAgentPlanJobs,
+    processAgentTurnJobs,
+    processAgentMergeJobs,
+    freshenManualPlaces,
   };
 }