flowviant 0.125.4 → 0.125.6

package/bin/lib/orchestratorNative.mjs

@@ -0,0 +1,58 @@
+/**
+ * WHAT A NATIVE SPAWN OR FOLLOW-UP HOOK PAYLOAD SAYS (2026-10-18 SOLID pass).
+ *
+ * The per-CLI field readings left orchestrator.mjs's run closure, where the
+ * 2026-10-17 review fixed four of them: Codex V1 `items`, V2 `task_name`
+ * receipts, Claude SendMessage as a follow-up, and collaborationspawn_agent.
+ * A vendor release changes these for a reason of its own, apart from the
+ * run's slot and note rules. Pure: no record, alias or slot is read here, so
+ * a CLI release that changes a field is a row in orchestratorNative.test.mjs.
+ * Words the model reads stay in orchestrator.mjs, and so do its refusals:
+ * these return fields, or null.
+ */
+import { isBackgroundSpawnTool, isClaudeFollowupTool } from './nativeAgentTools.mjs';
+
+/** A spawn's prompt and the fields a waiting record is matched and named by,
+ * or null when the gate cannot hold it (no call id or no text prompt). */
+export function readSpawn(event) {
+  // A child stays in the card's worktree on this machine, inside the pool.
+  const { isolation, cwd, ...input } = event.tool_input ?? {}, callId = event.tool_use_id;
+  // Codex 0.163 V1 spawn_agent takes `items` in place of `message`.
+  const items = Array.isArray(input.items) ? input.items : null;
+  const key = ['prompt', 'message'].find(k => typeof input[k] === 'string') ?? (items ? 'items' : null);
+  if (!callId || !key) return null;
+  const brief = key === 'items' ? items.filter(i => i?.type === 'text' && typeof i.text === 'string').map(i => i.text).join('\n') : input[key];
+  return { callId, input, items, key, brief, relocated: isolation !== undefined || cwd !== undefined,
+    resume: typeof input.resume === 'string' ? input.resume : null,
+    title: input.description ?? input.task_name, kind: input.subagent_type ?? input.agent_type,
+    names: [input.name, input.task_name] };
+}
+
+/** The spawn's input as the gate rewrites it: the contract appended to its
+ * prompt, and a Claude child sent to the background. */
+export const withChildContract = (event, spawn, contract) => ({ ...spawn.input, ...(isBackgroundSpawnTool(event.tool_name) ? { run_in_background: true } : {}),
+  ...(spawn.key === 'items' ? { items: [...spawn.items, { type: 'text', text: contract.trimStart() }] } : { [spawn.key]: spawn.input[spawn.key] + contract }) });
+
+/** Every native id a spawn or follow-up's receipt names, and whether it says
+ * the call failed. */
+export function spawnReceipt(event) {
+  let output = event.tool_response;
+  try { if (typeof output === 'string') output = JSON.parse(output); } catch { /* native plain output */ }
+  if (Array.isArray(output)) output = output.map(b => b.text ?? '').join('');
+  try { if (typeof output === 'string') output = JSON.parse(output); } catch { /* native prose */ }
+  const blocks = Array.isArray(output?.content) ? output.content.map(b => { try { return JSON.parse(b.text); } catch { return null; } }) : [];
+  const ids = [];
+  // Every id the receipt names: Codex V1 agent_id, V2's canonical task_name, Claude's agentId.
+  for (const receipt of [output, ...blocks]) for (const key of ['thread_id', 'agent_path', 'agent_id', 'agentId', 'task_name'])
+    if (typeof receipt?.[key] === 'string') ids.push(receipt[key]);
+  return { ids, failed: Boolean(output?.is_error || output?.isError || event.error) };
+}
+
+/** Which child a follow-up addresses (null when it names none in bounds), and
+ * whether it is Claude's SendMessage. */
+export function followupTarget(event) {
+  const input = event.tool_input ?? {}, claude = isClaudeFollowupTool(event.tool_name);
+  // Measured Claude 2.1.302 PreToolUse SendMessage input: {to, message, recipient, content, …}.
+  const native = claude ? input.to ?? input.recipient ?? input.target ?? input.id : input.target ?? input.id;
+  return { claude, native: typeof native === 'string' && native.length <= 160 ? native : null };
+}

package/bin/lib/orchestratorPrompt.mjs

@@ -1,14 +1,17 @@
+import { SAFE_POINT_AFTER_EDIT } from './orchestratorProtocol.mjs';
+
 export const ORCHESTRATOR_CONTRACT = `CARD ORCHESTRATOR — this applies to this card's one CLI and worktree.
 You are the model the person chose and remain responsible for the card and its final JSON.
-Work yourself when the card spans one area. Only split work spanning several areas into native in-process subagents by kind (Backend/UI/Tests…). This is authorization to use those native agents on this card. Give each a concrete title, prompt and kind, and post short updates of your own. Do not create extra branches or Flowviant agents. Use a native agent type that can call card_orchestrator MCP (Claude general-purpose); keep the work yourself if none can. After spawning, use describe_agent to report the kind and title you chose when its native role is generic.
+Work yourself when the card spans one area. Only split work spanning several areas into native in-process subagents by kind (Backend/UI/Tests…). This is authorization to use those native agents on this card. Give each a concrete title, prompt and kind, and post short updates of your own. Do not create extra branches or Flowviant agents. Use a native agent type that can call card_orchestrator MCP (Claude general-purpose); keep the work yourself if none can. Never give a child isolation or a different cwd: children share this card's worktree on this machine. After spawning, use describe_agent to report the kind and title you chose when its native role is generic.
 
-The daemon gates every native spawn against this project's Turns at once pool, shared with its other turns. Claude children run in the background so you remain available for messages and their questions; Codex spawns are already asynchronous. A refused spawn with a waiting id has not started. Keep working yourself; do not wait for it. When notified of a free slot, retry its native spawn with the same prompt. Never bypass this gate with another CLI process. The orchestrator itself also holds a slot. If no slot becomes available, finish the work yourself.
+The daemon gates every native spawn against this project's Turns at once pool, shared with its other turns. Claude children run in the background so you remain available for messages and their questions; Codex spawns are already asynchronous. A refused spawn with a waiting id has not started. Keep working yourself; do not wait for it. When notified of a free slot, retry its native spawn (the same or a reworded prompt) or its native follow-up; the slot is held for about a minute, then offered again later. Never bypass this gate with another CLI process. The orchestrator itself also holds a slot. If no slot becomes available, finish the work yourself.
+On Claude you may end your turn while native children run: Claude keeps this process alive and wakes you on each child's completion and on the person's notes. Follow-ups and answers to a Claude child go through SendMessage to its agent id. Write the card's final JSON only after every child has finished or been stopped; your last answer is the card's answer.
 
 The card_orchestrator MCP tools report routing and child questions. A live person’s note has a Message id. Report each note using route_message:
 - Handle it yourself: taken.
-- Delegate it: queued, with the native agent id, its kind, and the safePoint chosen FOR THIS NOTE: "when it finishes", "after its current edit", or a precise stated checkpoint.
+- Delegate it: queued, with the native agent id, its kind, and the safePoint chosen FOR THIS NOTE: "when it finishes", "${SAFE_POINT_AFTER_EDIT}", or a precise stated checkpoint.
 - When it finishes: wait for that child's completion, then put the note in its next native task/follow-up.
-- After its current edit: the gate pauses further tool use at the next boundary. Use the native stop/interrupt tool, preserve its work so far, and resume it or start a follow-up with that context and the note. Do not interrupt in the middle of an edit.
+- After its current edit: the gate pauses further tool use at the next boundary and tells you. Deliver the note with a native follow-up (Claude: SendMessage to its agent id, which arrives at its next tool round; Codex: stop/interrupt it, then resume it or follow up with its work so far and the note). Do not interrupt in the middle of an edit.
 - Only after native delivery at that checkpoint: handed with that agent id/kind/safePoint. This appends "From {orchestrator} …" to its stream. Never report a handoff before doing it.
 Use the tools' agent record id when one is supplied by a native spawn gate. Keep a later native id with that record.
 

package/bin/lib/orchestratorProtocol.mjs

@@ -1,12 +1,34 @@
+/** The one safe point the gate itself enforces: orchestrator.mjs's checkpoint
+ * pauses a child at its next tool boundary when a note's safePoint says these
+ * words. route_message and the contract (orchestratorPrompt.mjs) say them in
+ * the same words (2026-10-18 SOLID pass). */
+export const SAFE_POINT_AFTER_EDIT = 'after its current edit';
+
+/** The name a card turn mounts the orchestrator's server under, so the prefix
+ *  its tools carry (`mcp__card_orchestrator__…` on Claude, `card_orchestrator.…`
+ *  on Codex). The checkpoint exempts the server's own calls by it and the mount
+ *  (workAgentTools.mjs) names it with it; the prompts say it in their own words
+ *  (2026-10-18, the SOLID pass). */
+export const ORCHESTRATOR_SERVER = 'card_orchestrator';
+
+/** A note's route states and a route report's field caps: copies of the shared
+ *  `agentOrchestration.ts` ones (2026-10-18, the SOLID pass), held there by
+ *  the release parity gate (scripts/check-app-parity.mjs, rule 40). A machine
+ *  reports only these three; the server refuses a route over a cap. */
+export const MACHINE_MESSAGE_ROUTE_STATES = ['queued', 'handed', 'taken'];
+export const OPEN_MESSAGE_ROUTE_STATES = ['deciding', 'queued'];
+export const MESSAGE_ROUTE_FIELD_MAX = { id: 160, kind: 80, safePoint: 200 };
+
 /** The run-scoped MCP vocabulary; safe to load in a credential-free client. */
+
 export const ORCHESTRATOR_TOOLS = [
   { name: 'register_agent', description: 'A native child calls this first with the agent record id in its prompt, before working. It binds native events to that record.',
     inputSchema: { type: 'object', properties: { agentId: { type: 'string' } }, required: ['agentId'], additionalProperties: false } },
   { name: 'describe_agent', description: 'The orchestrator reports the kind and title it chose for a child when the native role is generic. Use Backend, UI, Tests or the actual area of work.',
     inputSchema: { type: 'object', properties: { agentId: { type: 'string' }, kind: { type: 'string' }, title: { type: 'string' } }, required: ['agentId', 'kind', 'title'], additionalProperties: false } },
-  { name: 'route_message', description: 'Report where you routed a person’s live note. Choose its safe point per note. Report handed only after native delivery at that checkpoint; taken means you handled it yourself.',
-    inputSchema: { type: 'object', properties: { messageId: { type: 'string' }, state: { enum: ['queued', 'handed', 'taken'] },
-      agentId: { type: 'string' }, kind: { type: 'string' }, safePoint: { type: 'string' } }, required: ['messageId', 'state'], additionalProperties: false } },
+  { name: 'route_message', description: `Report where you routed a person’s live note. Choose its safe point per note: "when it finishes" or "${SAFE_POINT_AFTER_EDIT}" (the gate pauses the child at its next tool boundary), or a precise stated checkpoint. Report handed only after native delivery at that checkpoint; taken means you handled it yourself.`,
+    inputSchema: { type: 'object', properties: { messageId: { type: 'string' }, state: { enum: [...MACHINE_MESSAGE_ROUTE_STATES] },
+      agentId: { type: 'string' }, kind: { type: 'string' }, safePoint: { type: 'string', description: `"when it finishes", "${SAFE_POINT_AFTER_EDIT}", or a precise stated checkpoint.` } }, required: ['messageId', 'state'], additionalProperties: false } },
   { name: 'agent_question', description: 'A child asks its orchestrator before asking the person. Call again to read an answer. The orchestrator answers from the card/code/earlier notes or escalates a real person-only decision.',
     inputSchema: { type: 'object', properties: { agentId: { type: 'string' }, question: { type: 'string' } }, required: ['agentId', 'question'], additionalProperties: false } },
   { name: 'answer_agent', description: 'Answer a child question from known facts, or mark it for escalation to the person. An escalation returns the attribution to put on the existing blocked question card.',

package/bin/lib/postureTools.mjs

@@ -60,29 +60,74 @@ Delegation is disabled by policy on fenced turns; tool names may still be listed
 
 const list = (names) => names.join(', ');
 
+/** Claude may list an MCP server's tools by name only until loaded (tool
+ *  search). A card that did not look once said Flowviant gave it no MCP tools
+ *  while its servers were mounted (2026-10-17). */
+const DEFERRED = {
+  claude: ' A mounted server’s tools may be deferred: when one is not in your tool list, load it with ToolSearch (its server name, or select:mcp__<server>__<tool>) before concluding it is absent.',
+  codex: '',
+};
+
+/** The machine's servers by their configured names — configuration, never a
+ *  claim that one connects. Null names (the CLI's file could not be read)
+ *  say nothing; an empty list keeps the general sentence. */
+const named = (runtime, names) => (Array.isArray(names) && names.length
+  ? `${runtime === 'claude' ? ' This machine’s Claude Code servers on this card' : ' This machine’s Codex servers on this card'}: ${list(names)}.`
+  : '');
+
 /**
  * The note for a turn, or '' when its posture withholds nothing to say.
  * `mounted` is the names of the base `.mcp.json` servers this turn mounted;
  * `machine` whether the machine's own servers were mounted beside them (a
  * Claude turn whose `.mcp.json` walk could not be bounded mounts the base copy
- * alone); `unmounted` is `[{ name, reason, source }]` for the servers it
- * could not mount — `source` 'project' (the base `.mcp.json`) or 'machine'.
+ * alone); `machineNames` those servers' names as this machine's CLI config
+ * lists them (null when unread — unknown, so unnamed); `unmounted` is
+ * `[{ name, reason, source }]` for the servers it could not mount — `source`
+ * 'project' (the base `.mcp.json`) or 'machine' — and, with `partial: true`,
+ * a machine server mounted with a limit (tools the person set to ask).
+ * `orchestrated` a code card whose contract authorizes native children
+ * (ORCHESTRATOR_CONTRACT), which the build note then does not contradict.
+ *
+ * EACH SENTENCE STANDS ALONE (2026-10-17). "The base branch’s .mcp.json lists
+ * no MCP server. So are the MCP servers …" read as the machine's servers
+ * being absent too; a base entry that could not mount was listed as missing
+ * while the machine's server of that name was mounted in its place; and "a
+ * server added to .mcp.json only in this worktree is not mounted" read as
+ * covering a machine server of that name, which stays mounted (measured,
+ * claudeMachineMcp.test.mjs). Codex's list is the servers actually mounted,
+ * so an empty one says none is, and a code card is told which base servers
+ * it could not mount, as a fenced card is (the review, same day).
  */
-export function postureToolsNote({ posture, runtime, mounted = [], machine = true, unmounted = [] }) {
+export function postureToolsNote({ posture, runtime, mounted = [], machine = true, machineNames, unmounted = [], orchestrated = false }) {
   const row = POSTURES[posture]?.[runtime];
-  if (!row) return posture === 'build' ? `TOOLS ON THIS CARD. Use the tools actually exposed by this CLI and its configuration. ${SUPPORTING_CAPABILITIES.replace('Delegation is disabled by policy on fenced turns; tool names may still be listed. Complete the work in this turn.', 'Delegate only when the person explicitly requests it.')} ` : '';
-  const fromProject = unmounted.filter((u) => u.source !== 'machine');
-  const fromMachine = unmounted.filter((u) => u.source === 'machine');
+  const own = machine && Array.isArray(machineNames) ? new Set(machineNames) : new Set();
+  const fromProject = unmounted.filter((u) => u.source !== 'machine' && !own.has(u.name));
+  const replaced = unmounted.filter((u) => u.source !== 'machine' && own.has(u.name));
+  const fromMachine = unmounted.filter((u) => u.source === 'machine' && !u.partial);
+  const limited = unmounted.filter((u) => u.source === 'machine' && u.partial);
+  const why = (rows) => list(rows.map(({ name, reason }) => `${name} (${reason})`));
+  const missing = (rows, where) => (rows.length ? ` ${where}, but not mounted here: ${why(rows)}.` : '');
+  const instead = replaced.length ? ` Listed in the base branch’s .mcp.json but not mountable from it, so mounted from this machine’s configuration instead: ${why(replaced)}.` : '';
+  const base = `${missing(fromProject, 'Listed in the base branch’s .mcp.json')}${instead}`;
+  if (!row) return posture === 'build' ? `TOOLS ON THIS CARD. Use the tools actually exposed by this CLI and its configuration.${named(runtime, machineNames)}${base}${DEFERRED[runtime] ?? ''} ${SUPPORTING_CAPABILITIES.replace('\nDelegation is disabled by policy on fenced turns; tool names may still be listed. Complete the work in this turn.', orchestrated ? '' : '\nDelegate only when the person explicitly requests it.')} ` : '';
   const project = mounted.length
     ? `The project’s MCP servers from the base branch’s .mcp.json are mounted: ${list(mounted)}.`
-    : fromProject.length
-      ? 'None of the project’s MCP servers is mounted on this machine.'
+    : fromProject.length || replaced.length
+      ? 'None of the project’s MCP servers from the base branch’s .mcp.json is mounted on this turn.'
       : 'The base branch’s .mcp.json lists no MCP server.';
-  const own = machine
-    ? ` So are ${MACHINE[runtime]}.`
-    : ` ${MACHINE[runtime][0].toUpperCase()}${MACHINE[runtime].slice(1)} are not mounted on this turn.`;
-  const missing = (rows, where) => (rows.length ? ` ${where}, but not mounted here: ${list(rows.map(({ name, reason }) => `${name} (${reason})`))}.` : '');
-  return `TOOLS ON THIS CARD. You have ${row.has}. You have ${row.lacks}. ${project}${own}${missing(fromProject, 'Listed in the base branch’s .mcp.json')}${missing(fromMachine, `In ${MACHINE[runtime]}`)} A server added to .mcp.json only in this worktree is not mounted; the base branch’s file is the one that counts.
+  const Machine = `${MACHINE[runtime][0].toUpperCase()}${MACHINE[runtime].slice(1)}`;
+  const mine = machine && runtime === 'codex' && Array.isArray(machineNames) && !machineNames.length
+    ? ' No MCP server from this machine’s Codex config is mounted on this turn.'
+    : machine && machineNames !== null
+      ? ` ${Machine} are also mounted on this turn (configured; not proof of a live connection).${named(runtime, machineNames)}`
+      : machine
+        ? runtime === 'claude'
+          ? ' This machine’s Claude Code configuration (.claude.json) could not be read, so its user and local servers are not mounted on this turn.'
+          : ' This machine’s Codex configuration could not be read, so its servers are not mounted on this turn.'
+        : ` ${Machine} are not mounted on this turn.`;
+  const limits = limited.length ? ` In ${MACHINE[runtime]}, mounted with a limit on this turn: ${why(limited)}.` : '';
+  const worktree = machine ? ' is not mounted from that file (a machine server of the same name still is);' : ' is not mounted;';
+  return `TOOLS ON THIS CARD. You have ${row.has}. You have ${row.lacks}. ${project}${mine}${base}${missing(fromMachine, `In ${MACHINE[runtime]}`)}${limits}${machine ? DEFERRED[runtime] ?? '' : ''} A server added to .mcp.json only in this worktree${worktree} the base branch’s file is the one that counts.
 There is no Flowviant setting that adds a tool, so never invent one. A missing
 server can be configured in the base branch's .mcp.json or the machine's CLI.
 ${SUPPORTING_CAPABILITIES}`;

package/bin/lib/prWorkflow.mjs

@@ -73,11 +73,22 @@ export const ghFirstLine = (e) =>
  * A FAILURE LINE FIT TO LEAVE THIS MACHINE — userinfo stripped and every
  * known secret scrubbed. Every git or gh failure relayed to a team-visible
  * record (a card's activity, the tab chat, an agent's mergeError) goes
- * through here: the session PR lane relayed git's push stderr unscrubbed
- * while the agent lane scrubbed the same line (audit 2026-10-10, F153/F167).
+ * through here or `relayedText`: the session PR lane relayed git's push
+ * stderr unscrubbed while the agent lane scrubbed the same line (audit
+ * 2026-10-10, F153/F167).
  */
 export const relayedFailure = (e) => scrub(ghFirstLine(e));
 
+/**
+ * A WHOLE TEXT fit to leave this machine — userinfo stripped, then every
+ * known secret scrubbed. The door for any git or gh output a lane relays
+ * whole or line by line; `relayedFailure` is its first-line form for an
+ * error. Each caller keeps its own line choice, joining and cap (2026-10-18,
+ * the SOLID pass: the composition was spelled by hand at six sites in three
+ * lanes, and F153 was one of those copies missing its first half).
+ */
+export const relayedText = (text) => scrub(stripUrlUserinfo(text));
+
 /** A pull request URL worth storing. Anything else gh printed is not one. */
 export const PR_URL_RE = /^https:\/\/github\.com\/[^\s/]+\/[^\s/]+\/pull\/\d+$/;
 

package/bin/lib/projectRepositories.mjs

@@ -3,7 +3,7 @@ import { existsSync, realpathSync } from 'node:fs';
 import { printableLine } from './printable.mjs';
 import { listStoredProjects } from './credentials.mjs';
 import { checkoutIdentity } from './checkoutIdentity.mjs';
-import { detectBaseRef, gitOrNull, usableBaseRef, baseBranchName } from './git.mjs';
+import { baseRefFor, gitOrNull } from './git.mjs';
 
 export function storedProject(token) {
   return listStoredProjects().find((entry) => entry.fleetToken === token) ?? null;
@@ -42,7 +42,7 @@ export function createProjectRepositories({ entry, repoRoot, getEntry = () => en
       const checkout = root && gitOrNull(['rev-parse', '--show-toplevel'], root);
       const available = checkout && realpathSync(checkout) === realpathSync(root);
       return { ...repo, repoRoot: available ? root : null,
-        baseRef: available ? (repo.baseBranch ? usableBaseRef(root, `origin/${baseBranchName(repo.baseBranch)}`) : detectBaseRef(root)) : null };
+        baseRef: available ? baseRefFor(root, repo.baseBranch) : null };
     });
   };
   const targets = (job) => {