flowviant 0.125.5 → 0.125.7

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;
+  }
+}