flowviant 0.125.4 → 0.125.6

package/bin/lib/work.mjs

@@ -55,9 +55,9 @@
  *   (and, split earlier: workDiffs, workPreviews, workPullRequests, workShip,
  *   workAgentPlans, workAgentCheck, workAgentPrecheck, workAgentReview,
  *   workAgentTurns, workAgentRecovery, workAgentMerges, workMergeBatch,
- *   workProcesses; and out of workAgentTurns,
- *   SOLID F036: workAgentTurnReports, workAgentTurnExecution, workAgentTurnBegun,
- *   workAgentTurnOutcome; repositoryPlaces + agentRepositories: multi-repo places; the live brief: workAgentBrief, workAgentBriefRunner)
+ *   workProcesses; out of workAgentTurns, SOLID F036: workAgentTurnReports,
+ *   workAgentTurnExecution, workAgentTurnBegun, workAgentTurnOutcome; out of that run (SOLID, 2026-10-18): workAgentTools, workAgentTurnShape, workAgentResume;
+ *   repositoryPlaces + agentRepositories: multi-repo places; the live brief: workAgentBrief, workAgentBriefRunner)
  */
 
 import { trackedRepositorySetup } from './repositorySetup.mjs';
@@ -65,6 +65,7 @@ import { createRepositoryPlaces } from './repositoryPlaces.mjs';
 import { createAgentRepositories } from './agentRepositories.mjs';
 import { createWorkProcesses } from './workProcesses.mjs';
 import { createWorkAgentMerges } from './workAgentMerges.mjs';
+import { createWorkMergeBatch } from './workMergeBatch.mjs';
 import { createWorkAgentTurns } from './workAgentTurns.mjs';
 import { createAgentRecovery } from './workAgentRecovery.mjs';
 import { createWorkAgentCheck } from './workAgentCheck.mjs';
@@ -391,9 +392,8 @@ export function createWorkManager({
     fetchAgentFiles,
   });
   const { processAgentMergeJobs, agentMerges } = createWorkAgentMerges({
-    runCheck, workChildren, groupKillChildren, admit,
-    repositoryPlaces,
-    repoRoot,
+    runBatch: createWorkMergeBatch({ repositoryPlaces, repoRoot, baseDir, inPlace, runCheck, workChildren, groupKillChildren, admit, onRepoChanged, landed }),
+    repositoryPlaces, repoRoot,
     inPlace,
     baseDir,
     gitNet,

package/bin/lib/workAgentMerges.mjs

@@ -1,13 +1,12 @@
-import { createWorkMergeBatch } from './workMergeBatch.mjs';
 import { mergeRepositoryPlace } from './repositoryMerge.mjs';
 import { fleetRequest } from './fleetPost.mjs';
 /** Agent merge claims, pull-request approval, and branch cleanup. */
-import { ensureOpenPr, ghReady, mergeAndVerifyTip, PR_URL_RE, relayedFailure } from './prWorkflow.mjs';
+import { ensureOpenPr, ghReady, mergeAndVerifyTip, PR_URL_RE, relayedFailure, relayedText } from './prWorkflow.mjs';
 import { existsSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import { join } from 'node:path';
 import { FLEET_URL, DAEMON_INSTANCE } from './config.mjs';
-import { git, gitOrNull, gitNet as gitNetIn, baseBranchName, isSafePathSegment, sessionBranch, stripUrlUserinfo } from './git.mjs';
+import { git, gitOrNull, gitNet as gitNetIn, baseBranchName, isSafePathSegment, sessionBranch } from './git.mjs';
 import { isPublishRef, publishPushArgs, publishDeleteArgs, publishErrorText } from './agentPublish.mjs';
 import { mergeOutward as shipMergeOutward } from './shipMerge.mjs';
 import { gitMergeIn } from './gitMergeIdentity.mjs';
@@ -29,11 +28,11 @@ export function agentMergeFailureDetail(error) {
     .map((value) => String(value ?? '').trim())
     .filter(Boolean)
     .join('\n');
-  return envScrub(stripUrlUserinfo(output || String(error?.message || error))).slice(0, 2000);
+  return relayedText(output || String(error?.message || error)).slice(0, 2000);
 }
 
 export function createWorkAgentMerges({
-  runCheck, workChildren = new Map(), groupKillChildren = new Set(), admit,
+  runBatch,
   repositoryPlaces,
   repoRoot,
   inPlace,
@@ -116,7 +115,7 @@ export function createWorkAgentMerges({
     const report = async (body) => {
       reported = true;
       if (body?.ok === true) landedRef = job.publishedRef ?? null;
-      await postAgentMerge({ ...body, ...(body.detail ? { detail: envScrub(stripUrlUserinfo(String(body.detail))).slice(0, 2000) } : {}) });
+      await postAgentMerge({ ...body, ...(body.detail ? { detail: relayedText(String(body.detail)).slice(0, 2000) } : {}) });
     };
 
     // A WRITER on the place, exactly as a ship is. It folds base in and pushes
@@ -436,7 +435,6 @@ export function createWorkAgentMerges({
     }
   };
 
-  const runBatch = createWorkMergeBatch({ repositoryPlaces, repoRoot, baseDir, inPlace, runCheck, workChildren, groupKillChildren, admit, onRepoChanged, landed });
   const processAgentMergeJobs = (jobs) => {
     if (!Array.isArray(jobs) || jobs.length === 0) return;
     for (const job of jobs.slice(0, 2)) {

package/bin/lib/workAgentPrecheck.mjs

@@ -106,11 +106,11 @@ export function createWorkAgentPrecheck({ baseRef, admit, sessionMetaPath, workC
   /**
    * THE BRANCH'S OWN COMMITS, subject + trailers, and the card ids they name.
    *
-   * MEASURED, never asserted — the same reason `commitsBetween` exists. The
-   * trailer ids are what let the prompt say "N earlier cards' specs are not on
-   * this box" honestly: the difference between the cards this branch claims and
-   * the specs this disk holds is a fact, and a box that adopted the agent
-   * mid-run is exactly the case where it is non-zero.
+   * MEASURED, never asserted — the same reason `commitsSince` exists
+   * (turnReceipts.mjs). The trailer ids are what let the prompt say "N earlier
+   * cards' specs are not on this box" honestly: the difference between the
+   * cards this branch claims and the specs this disk holds is a fact, and a box
+   * that adopted the agent mid-run is exactly the case where it is non-zero.
    *
    * IT CANNOT THROW. `baseRef()` is free text an owner typed and may name no
    * ref at all; an unreadable range costs the reviewer its context, never the

package/bin/lib/workAgentRecovery.mjs

@@ -4,6 +4,7 @@ import { isSafePathSegment, sessionBranchRef, gitNetAsync } from './git.mjs';
 import { begunTurnRefusal } from './workAgentTurnBegun.mjs';
 import { fleetEndpoint } from './fleetWire.mjs';
 import { fleetRequest } from './fleetPost.mjs';
+import { AGENT_PLACE_PREFIX } from './workPlaces.mjs';
 
 /** Inspect before any cut or CLI. A failed request waits for the next poll. */
 export function createAgentRecovery({
@@ -32,7 +33,7 @@ export function createAgentRecovery({
     for (const job of [...jobs.slice(next), ...jobs.slice(0, next)]) {
       if (!job || !isSafePathSegment(job.agentId) || !isSafePathSegment(job.placeId) ||
           sessionBranchRef(job.placeId) === null || typeof job.sourceKey !== 'string' ||
-          !job.sourceBoxId || job.sourceBoxId === id || job.placeId !== `a-${job.agentId}`) continue;
+          !job.sourceBoxId || job.sourceBoxId === id || job.placeId !== `${AGENT_PLACE_PREFIX}${job.agentId}`) continue;
       const key = `${job.sourceBoxId}:${job.sourceKey}`;
       if (ready.get(job.agentId) === key) { ready.delete(job.agentId); continue; }
       blocked.add(job.agentId);

package/bin/lib/workAgentResume.mjs

@@ -0,0 +1,121 @@
+/**
+ * AN AGENT'S RESUME ACROSS TURNS — which conversation its next turn speaks
+ * in, and the kept Codex home that conversation is filed under (2026-10-18,
+ * the SOLID pass).
+ *
+ * The seam ARCHITECTURE named for workAgentTurnExecution.mjs ("the
+ * resume-marker read and write is its seam"), taken. Resume mechanics have
+ * changed four times — the Codex thread pin (2026-09-24), the ran marker only
+ * a Claude turn writes (2026-09-24), the kept Codex home (2026-09-29), the
+ * per-agent Claude session marker (2026-10-14) — and each time across six
+ * separated sites of the run: the reads and the resume decision, the home,
+ * the session pinned at init, the thread seen mid-turn, the fresh retry's
+ * reset, and the writes after the turn. They sit together here, the per-CLI
+ * arms moved verbatim, so neither the decision nor the write order can shift;
+ * giving another CLI an agent resume by id is an edit to this file. The read
+ * and write procedure is resumeMarker.mjs's, and the id shapes and the
+ * Claude marker name are conversationIds.mjs's; the agent's own marker names
+ * are spelled here alone.
+ *
+ * THE RUN KEEPS THE ORDERING: it calls `agentTurnResume` where the reads
+ * stood, before the turn's files are fetched, and `persist()` where the
+ * writes stood — after the CLI's children are dropped and the trace tail is
+ * flushed, before the worktree is re-measured.
+ */
+import { existsSync, writeFileSync } from 'node:fs';
+import { CLAUDE_SESSION_RE, CODEX_THREAD_RE, RESUME_MARKERS } from './conversationIds.mjs';
+import { pinId, readPinnedId } from './resumeMarker.mjs';
+
+/**
+ * One agent turn's resume. `sessionMetaPath` is the lane's (a path in the
+ * worktree's private git dir, or null). Returns the turn's `resume` and
+ * `resumeThreadId`, the kept `codexHome`, and what the run tells it as the
+ * CLI speaks: `sawSession` (Claude's init), `sawThread` (Codex's
+ * `thread.started`), `forgetThread` (a lost resume retried fresh), `threadNow`
+ * and, once the turn is over, `persist`.
+ */
+export function agentTurnResume({ rt, wt, agentId, sessionMetaPath }) {
+  // 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.
+  //
+  // IT MEANS "CLAUDE HAS SPOKEN HERE", and since 2026-09-24 only a Claude
+  // turn writes it: an agent can be switched between CLIs, and a marker a
+  // codex turn left behind would send the first Claude turn to
+  // `--continue` a directory holding no Claude conversation at all.
+  const ranMarker = sessionMetaPath(wt, 'flowviant-agent-ran');
+  /**
+   * CODEX RESUMES BY ITS OWN THREAD ID, PINNED PER AGENT (2026-09-24).
+   *
+   * Resume was Claude-only, because codex's `resume --last` is
+   * MACHINE-GLOBAL and would cross-resume whichever conversation spoke
+   * last anywhere on the box. The cost was that every codex card started
+   * a stranger: no memory of the card before it, and — worse — an answer
+   * to the agent's own question arrived at a codex that never asked it.
+   * The Workbench solved the same problem in 0.69.0 by pinning the id
+   * `thread.started` announces; this is that, keyed by the AGENT rather
+   * than a tab. The id is shape-checked before it rides argv.
+   */
+  const codexThreadMarker =
+    rt === 'codex' ? sessionMetaPath(wt, 'flowviant-agent-codex-thread', agentId) : null;
+  // An unreadable or misshapen marker is unknown: run fresh (resumeMarker.mjs).
+  const codexResumeId = readPinnedId(codexThreadMarker, CODEX_THREAD_RE);
+  let seenThreadId = null;
+  const claudeMarker = rt === 'claude' ? sessionMetaPath(wt, RESUME_MARKERS.claude, agentId) : null;
+  const claudeResumeId = readPinnedId(claudeMarker, CLAUDE_SESSION_RE);
+  const resume =
+    rt === 'codex'
+      ? Boolean(codexResumeId)
+      : rt === 'claude' && (Boolean(claudeResumeId) || Boolean(ranMarker && existsSync(ranMarker)));
+  /**
+   * …AND THE HOME THAT THREAD IS FILED UNDER, KEPT PER AGENT (2026-09-29).
+   *
+   * Codex's thread index records each rollout under the CODEX_HOME the turn
+   * ran with, as that path — not the personal store the link leads to — so
+   * the per-turn home in /tmp every turn used to get died with its turn and
+   * took the pinned thread with it: the next card's `resume` failed "no
+   * rollout found" and the agent went to Stuck. Beside the thread marker,
+   * in the worktree's private git dir: outside the working tree (never
+   * committed, never seen by `git add -A`), refreshed by every turn and
+   * removed only with the worktree, when the agent retires and its threads
+   * stop mattering. One agent runs one turn at a time (its place's writer
+   * lock), so no two turns refresh it at once. Null (no git dir to hold it)
+   * is the per-turn home again, and a lost resume then runs once fresh.
+   */
+  const codexAgentHome =
+    rt === 'codex' ? sessionMetaPath(wt, 'flowviant-agent-codex-home', agentId) : null;
+
+  return {
+    resume,
+    resumeThreadId: codexResumeId || claudeResumeId || undefined,
+    codexHome: codexAgentHome,
+    /** Claude's session id from its init, pinned at once (a Claude turn only). */
+    sawSession(id) {
+      pinId(claudeMarker, CLAUDE_SESSION_RE, id);
+    },
+    /** The thread Codex announced; a blank one keeps the last. */
+    sawThread(id) {
+      seenThreadId = String(id ?? '').trim() || seenThreadId;
+    },
+    /** A lost resume runs fresh: the thread it had seen is not its own. */
+    forgetThread() {
+      seenThreadId = null;
+    },
+    threadNow: () => seenThreadId,
+    persist() {
+      if (ranMarker && rt === 'claude') {
+        try {
+          writeFileSync(ranMarker, '1');
+        } catch {
+          /* a missing marker only costs one un-resumed turn */
+        }
+      }
+      // The thread THIS turn spoke under, pinned so the next card, answer
+      // or merge-resolve resumes it. After the turn, like the tab lane: an
+      // id learned mid-turn is only true once the turn that learned it ends.
+      // Best-effort — the next turn runs fresh.
+      pinId(codexThreadMarker, CODEX_THREAD_RE, seenThreadId);
+    },
+  };
+}

package/bin/lib/workAgentTools.mjs

@@ -0,0 +1,111 @@
+/**
+ * WHAT A CARD TURN MOUNTS, AND WHAT IT IS TOLD (2026-10-18, the SOLID pass).
+ *
+ * Split out of workAgentTurnExecution.mjs, where it had become a second
+ * vocabulary inside one agent turn's run: the base-branch snapshot read across
+ * the card's repository sources, the daemon's own turn servers, Claude's
+ * machine servers beside the base copy or Codex's fenced mount, and the TOOLS
+ * note that says all of it to the agent. Those change together — three
+ * 2026-10-17 commits (703750746, 2cc52e42c, 65051ac42) edited this block and
+ * nothing else of the run — and for reasons the run does not share. Whether a
+ * CLI takes MCP at all is asked of the tool table (`runnerToolCapabilities`,
+ * projectToolRuntimes.mjs) rather than listed again here, and the daemon's
+ * server names are spelled once (`CARD_TURN_SERVERS`), so a base `.mcp.json`
+ * that reuses one is still never told to the agent as a project server.
+ *
+ * THE RUN KEEPS THE ORDERING: it calls this after `createOrchestrator` (whose
+ * config is one of the turn servers), inside the try whose finally cleans the
+ * prepared tools up, and merges the returned `env` into the CLI's `mcpEnv`
+ * ahead of the repository tool's and the orchestrator's. Until this returns
+ * the run holds no handle to clean, so a throw after the tools are prepared
+ * cleans them up here.
+ */
+import { mcpJsonServerNamesAbove, readBaseTools, prepareAgentTools } from './projectTools.mjs';
+import { runnerToolCapabilities } from './projectToolRuntimes.mjs';
+import { TURN_PROFILES } from './turnProfile.mjs';
+import { postureToolsNote } from './postureTools.mjs';
+import { machineMcpServers } from './claudeMachineMcp.mjs';
+import { ORCHESTRATOR_SERVER } from './orchestratorProtocol.mjs';
+
+/** The servers the daemon itself mounts on a card turn, by the names the
+ *  agent calls them: a multi-repository card's add_repository, and an
+ *  orchestrated card's routing. Never a project server's, whatever the base
+ *  `.mcp.json` names. */
+export const CARD_TURN_SERVERS = Object.freeze({ repositories: 'card_repositories', orchestrator: ORCHESTRATOR_SERVER });
+
+/**
+ * The card turn's tools, prepared, and what it is told of them.
+ *
+ * `baseRef` is the lane's own function, read only when the card's worktree is
+ * none of its repository sources. `env` is the environment the turn expands
+ * from and `machineServers` claudeMachineMcp.mjs's reader: the process's own in
+ * the lane, a scratch home in a test. Returns `{ projectTools, toolsNote, env,
+ * envNeeded, mountArgs }` — the prepared tools (the caller cleans them up
+ * from here), the note, the mount's part of the CLI's `mcpEnv` and whether it
+ * needs one, and the keys the runner takes the mount as.
+ */
+export function prepareCardTools({ rt, posture, wt, repoRoot, baseRef, sources = [], repositoryTool = null, orchestratorConfig = null, orchestrated = false, codexHome = null, env = process.env, machineServers = machineMcpServers }) {
+  // A turn reads the base ref afresh. Changes the agent has made to its
+  // own worktree cannot silently change the next turn's tools.
+  const source = sources.find((r) => r.wt === wt);
+  const snapshot = readBaseTools(source?.repoRoot ?? repoRoot, source?.baseRef ?? baseRef());
+  for (const other of sources.filter((r) => r !== source)) {
+    const base = readBaseTools(other.repoRoot, other.baseRef);
+    snapshot.instructions.push(...[...base.instructions, ...base.skillFiles].map((file) => ({ ...file, path: `repositories/${other.folder}/${file.path}` })));
+  }
+  const projectTools = prepareAgentTools(snapshot, rt, env, wt, { codexHome, fenced: posture !== 'build', turnServers: {
+    ...(repositoryTool ? { [CARD_TURN_SERVERS.repositories]: repositoryTool.config } : {}),
+    ...(orchestratorConfig ? { [CARD_TURN_SERVERS.orchestrator]: orchestratorConfig } : {}),
+  } });
+  try {
+    const mountsProjectMcp = TURN_PROFILES[posture]?.projectMcp === true && runnerToolCapabilities(rt).mcp;
+    // A fenced posture on a runner that ignores its own file there (Codex's
+    // `--ignore-user-config`) takes the servers as `fencedMount` instead.
+    const fencedMount = mountsProjectMcp && posture !== 'build' ? projectTools.fencedMount : null;
+    // THE MACHINE'S OWN SERVERS ON CLAUDE (2026-10-11, the owner): the turn
+    // is not strict, and every `.mcp.json` name from the worktree up is
+    // disabled so only the base copy speaks for the project. Null (an
+    // unboundable walk) mounts strictly: the base copy alone.
+    const claudeDisabled = mountsProjectMcp && rt === 'claude' ? mcpJsonServerNamesAbove(wt) : null;
+    // The machine's servers by name, as its CLI's own config lists them
+    // (2026-10-17): a card that is told only "the machine's servers" and
+    // finds none in a deferred tool list concludes it has no MCP at all.
+    // A Codex code card's are the ones its kept config.toml mounts
+    // (2026-10-18), never the fenced mount's narrower list.
+    const baseNames = projectTools.mcpServers.filter((name) => !Object.values(CARD_TURN_SERVERS).includes(name));
+    const claudeMachine = claudeDisabled != null ? machineServers({ user: true, checkout: source?.repoRoot ?? repoRoot, env }) : {};
+    const machineNames = !mountsProjectMcp ? [] : rt === 'claude'
+      ? (claudeMachine == null ? null : Object.keys(claudeMachine).filter((name) => !projectTools.mcpServers.includes(name)))
+      : posture !== 'build' ? (projectTools.fencedMount ? projectTools.fencedMount.machine : []) : projectTools.codexMachineServers;
+    // What this card's posture withholds, said to the agent — with the
+    // servers it did and did not mount, and why — so it relays the fence
+    // instead of inventing a setting (postureTools.mjs). Empty for a code card.
+    const toolsNote = postureToolsNote({
+      posture,
+      runtime: rt,
+      orchestrated,
+      mounted: !mountsProjectMcp ? [] : fencedMount ? fencedMount.mounted : baseNames,
+      machine: mountsProjectMcp && (rt === 'codex' || claudeDisabled != null),
+      machineNames,
+      unmounted: [...projectTools.mcpUnmounted.map((u) => ({ ...u, source: 'project' })), ...(fencedMount ? fencedMount.unmounted : [])],
+    });
+    return {
+      projectTools,
+      toolsNote,
+      env: { ...(projectTools.codexHome ? { CODEX_HOME: projectTools.codexHome } : {}), ...(fencedMount?.env ?? {}) },
+      envNeeded: Boolean(projectTools.codexHome || fencedMount),
+      // Reviewed project servers and the machine's configured servers, on
+      // initial cards, answers and review iterations alike.
+      mountArgs: mountsProjectMcp && rt === 'claude'
+        ? {
+            mcpArgs: [...(claudeDisabled ? [] : ['--strict-mcp-config']), '--mcp-config', projectTools.mcpPath],
+            projectMcpServers: projectTools.mcpServers,
+            ...(claudeDisabled ? { machineMcp: claudeDisabled, mcpCheckout: source?.repoRoot ?? repoRoot } : {}),
+          }
+        : fencedMount ? { mcpArgs: fencedMount.args } : {},
+    };
+  } catch (e) {
+    projectTools.cleanup();
+    throw e;
+  }
+}