flowviant 0.97.0 → 0.100.0

package/bin/lib/prompts.mjs

@@ -492,9 +492,10 @@ const kickoff = ({ message, askedByName, head, tail }) => {
  * A CAPTURE TAB (server: work_session.kind='capture', flagged on the job as
  * `capture: true`) — the board's "New task" conversation. Its whole job is
  * turning what the person says into STAGED cards a human lands; it edits
- * nothing, and the permission profile enforces that (PLAN_PERM: read-only +
- * MCP — the same fence the scratch planner runs behind). This prompt is the
- * QUALITY half; the token scope and the permission list are the safety.
+ * nothing, and the permission profile enforces that (`planPermFor`:
+ * read-only + MCP — the same fence the scratch planner runs behind). This
+ * prompt is the QUALITY half; the token scope and the permission list are
+ * the safety.
  *
  * THE CHAT ASKS IN CHIPS, AND SAYS WHAT IT ASSUMED (2026-09-23, 0.97.0). Rule
  * 5 used to be one sentence — "clarify before staging" — and the owner asked
@@ -600,7 +601,9 @@ MECHANICS OF THIS CHAT:
    something they said.
 10. REFERENCE WHAT THE PROJECT KEPT. When the ask names a kept design or
    write-up ("implement design A"), call list_library and pass its id as
-   \`references\` on the card you stage, so the agent reads it.`;
+   \`references\` on the card you stage, so the agent reads it. When the person's
+   message includes attached library items, pass those ids as \`references\` on
+   the cards you stage from that message.`;
 
 export const WORK_TURN_KICKOFF = ({ sessionId, sessionName, message, askedByName }) =>
   kickoff({
@@ -684,11 +687,11 @@ export const REGROUND_KICKOFF = ({ sha, title, files, vaultDir, predictedPages =
  * no code, edits no files and starts nothing: a person reads what it proposes,
  * edits it on the board, and accepting is what spawns anything.
  *
- * It runs READ-ONLY IN THE CHECKOUT under CONSULT_PERM — no Write, no Edit, no
- * mkdir, no rm, and no MCP at all. The proposal comes back as its final
- * message, not through a tool, which is what lets that permission set be this
- * narrow. A planner authors a decision, and there is no file on this machine it
- * has any business touching.
+ * It runs READ-ONLY IN THE CHECKOUT under `consultPermFor` — no Write, no
+ * Edit, no mkdir, no rm, and no MCP at all. The proposal comes back as its
+ * final message, not through a tool, which is what lets that permission set
+ * be this narrow. A planner authors a decision, and there is no file on this
+ * machine it has any business touching.
  *
  * The two facts it is asked to weigh are the only two that are actually
  * knowable here: what the cards SAY, and what each live agent has already
@@ -861,13 +864,15 @@ export const AGENT_PLAN_KICKOFF = ({ tasks, liveAgents, agentCap }) => {
  * a person one reply; a turn that guesses costs them a review, a rejection and
  * a second run — and the guess arrives wearing a confident summary.
  */
-export const SYSTEM_AGENT = `You are the human's own Claude, working one task in a git worktree of their
+export const SYSTEM_AGENT = `You are the human's own coding agent, working one task in a git worktree of their
 repository. Nobody is watching this run. You have the repo and nothing else —
 no project tools, no board, no chat.
 
 WHAT TO DO:
 
-1. Do the card you are given. Read whatever you need first. Follow the
+1. Do the card you are given. Read whatever you need first — including
+   CLAUDE.md and AGENTS.md at the repository root, when either exists: they are
+   the repository's own instructions, whichever CLI you are. Follow the
    repository's own conventions over anything you would do by default.
 
 2. COMMIT YOUR WORK before you finish. Small, real commit messages. Uncommitted

package/bin/lib/resources.mjs

@@ -46,7 +46,7 @@
 
 import { execFileSync } from 'node:child_process';
 import { readFileSync, readdirSync, statfsSync } from 'node:fs';
-import { freemem, loadavg, platform } from 'node:os';
+import { cpus, freemem, loadavg, platform } from 'node:os';
 import { MACHINE } from './config.mjs';
 
 const MiB = 1024 * 1024;
@@ -71,12 +71,38 @@ const readFile = (p) => {
 function memoryUsed() {
   const cur = readFile('/sys/fs/cgroup/memory.current');
   if (cur !== null) {
-    const n = Number(cur);
+    const n = cgroupWorkingSet(Number(cur), readFile);
     if (Number.isFinite(n) && n > 0) return n;
   }
   return Math.max(0, MACHINE.memBytes - freemem());
 }
 
+/**
+ * THE CGROUP'S WORKING SET, NOT ITS CHARGE.
+ *
+ * `memory.current` counts the page cache charged to the cgroup — every file a
+ * worktree add, an npm install or a repo read touched. On a container that has
+ * been up a while it sits just under `memory.max` while almost all of it is
+ * reclaimable, and the kernel reclaims only when something ALLOCATES. A guard
+ * reading the raw charge therefore defers every unattended turn, which spawns
+ * nothing, which allocates nothing, which never reclaims: a permanent refusal
+ * relaying a "low memory" figure that is false. This is the same trap
+ * `memAvailableBytes` rejects `freemem()` for, one layer down.
+ *
+ * So subtract `inactive_file` from `memory.stat`, which is what kubelet and
+ * `docker stats` call the working set. An unreadable or malformed stat leaves
+ * the charge as it was — the conservative direction, and never a guess.
+ */
+function cgroupWorkingSet(current, read) {
+  if (!Number.isFinite(current)) return current;
+  const stat = read('/sys/fs/cgroup/memory.stat');
+  const m = stat && stat.match(/^inactive_file\s+(\d+)$/m);
+  if (!m) return current;
+  const inactive = Number(m[1]);
+  if (!Number.isFinite(inactive) || inactive < 0) return current;
+  return Math.max(0, current - inactive);
+}
+
 /**
  * Resident memory of a process AND everything it spawned.
  *
@@ -176,7 +202,8 @@ export function memAvailableBytes(read = readFile) {
     const max = read('/sys/fs/cgroup/memory.max');
     if (max && max !== 'max') {
       const limit = Number(max);
-      const cur = Number(read('/sys/fs/cgroup/memory.current'));
+      const raw = read('/sys/fs/cgroup/memory.current');
+      const cur = raw === null ? NaN : cgroupWorkingSet(Number(raw), read);
       if (Number.isFinite(limit) && limit > 0 && Number.isFinite(cur)) {
         const room = Math.max(0, limit - cur);
         avail = avail === null ? room : Math.min(avail, room);
@@ -248,6 +275,21 @@ const sizeWord = (n) =>
 const PRESSURE_CACHE_MS = 2_000;
 let lastMeasure = { at: 0, m: null };
 
+/**
+ * THE CORES THE LOAD AVERAGE IS A LOAD ON.
+ *
+ * `/proc/loadavg` is not namespaced: inside a container it reports the whole
+ * HOST. `MACHINE.cores` is clamped to the cgroup's `cpu.max`, which is right
+ * for sizing how many turns this box runs and wrong as the divisor of a host
+ * figure — a `--cpus=2` container on a busy 32-core host read "load 10 on 2
+ * cores" and deferred every unattended turn over load it did not cause. Compare
+ * like with like: a host figure against the host's core count. Exported so the
+ * pairing can be pinned.
+ */
+export function loadCores(hostCores = cpus().length) {
+  return Number.isFinite(hostCores) && hostCores > 0 ? hostCores : MACHINE.cores;
+}
+
 /** What the box says about itself, cached briefly. Exported so a caller can
  *  hold one reading across several verdicts — and so tests can pass their own
  *  instead of depending on the machine they run on. */
@@ -260,7 +302,7 @@ export function measurePressure() {
     // Unix only; Windows reports zeroes, which are sent as null rather than as
     // a very calm-looking 0.00 — the same rule the snapshot keeps.
     load1: loadavg()[0] || null,
-    cores: MACHINE.cores,
+    cores: loadCores(),
   };
   lastMeasure = { at: now, m };
   return m;

package/bin/lib/runtimeOfferings.mjs

@@ -0,0 +1,75 @@
+/** Local, bounded Codex readouts. No agent turn is started for these reports. */
+import { execFileSync } from 'node:child_process';
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { readBaseTools } from './projectTools.mjs';
+
+const TTL = 5 * 60_000;
+let cachedAt = 0;
+let cached = null;
+let repoCached = null;
+const home = (env) => env.CODEX_HOME || join(homedir(), '.codex');
+const nameOk = (name) => typeof name === 'string' && /^[A-Za-z0-9_.:-]{1,80}$/.test(name) && name !== 'flowviant';
+const run = (args, env) => execFileSync('codex', args, {
+  encoding: 'utf8', timeout: 5000, maxBuffer: 128 * 1024,
+  stdio: ['ignore', 'pipe', 'ignore'], env,
+});
+
+export function localCodexOfferings({ env = process.env, runCodex = run, read = readFileSync, list = readdirSync } = {}) {
+  const result = {};
+  try {
+    const cachePath = join(home(env), 'models_cache.json');
+    if (read === readFileSync && statSync(cachePath).size > 2 * 1024 * 1024) throw Error('model cache too large');
+    const data = JSON.parse(read(cachePath, 'utf8'));
+    if (Array.isArray(data.models)) result.models = data.models
+      .filter((m) => m?.visibility === 'list' && nameOk(m.slug))
+      .slice(0, 60)
+      .map((m) => ({ slug: m.slug, displayName: String(m.display_name || m.slug).slice(0, 100),
+        efforts: Array.isArray(m.supported_reasoning_levels) ? m.supported_reasoning_levels
+          .map((e) => e?.effort).filter((e) => typeof e === 'string' && /^[a-z]{1,20}$/.test(e)).slice(0, 8) : [] }));
+  } catch { /* absent or unreadable is unknown */ }
+  try {
+    const lines = runCodex(['features', 'list'], env).split('\n');
+    result.capabilities = lines.some((line) => /^image_generation\s+\S+\s+true\s*$/.test(line)) ? ['image'] : [];
+  } catch { /* a failed local probe is unknown */ }
+  try {
+    result.skills = list(join(home(env), 'skills'), { withFileTypes: true })
+      .filter((entry) => entry.isDirectory() && nameOk(entry.name))
+      .map((entry) => entry.name).slice(0, 80);
+  } catch (error) { if (error?.code === 'ENOENT') result.skills = []; }
+  try {
+    const servers = JSON.parse(runCodex(['mcp', 'list', '--json'], env));
+    if (Array.isArray(servers)) result.mcp = servers
+      // Unknown/unsupported auth is not proof of disconnection. Keep their
+      // names local, just as connected servers stay local.
+      .filter((s) => nameOk(s?.name) && ['needs_auth', 'failed'].includes(s.auth_status))
+      .slice(0, 80)
+      .map((s) => ({ n: s.name, s: s.auth_status === 'needs_auth' ? 'needs-auth' : 'failed' }));
+  } catch { /* no read is unknown */ }
+  return result;
+}
+
+export function runtimeOfferings(repoRoot, baseRef, { refresh = false } = {}) {
+  if (!cached || refresh || Date.now() - cachedAt >= TTL) {
+    cached = localCodexOfferings();
+    cachedAt = Date.now();
+  }
+  const out = { rtm: {}, rtc: {}, rts: {}, rtp: {} };
+  if (cached.models) out.rtm.codex = cached.models;
+  if (cached.capabilities) out.rtc.codex = cached.capabilities;
+  if (cached.skills) out.rts.codex = cached.skills;
+  if (cached.mcp) out.rtp.codex = cached.mcp;
+  // Repo skills and MCP are read from the base commit, like the turn itself.
+  try {
+    if (!repoCached || repoCached.root !== repoRoot || repoCached.ref !== baseRef || refresh || Date.now() - repoCached.at >= TTL) {
+      repoCached = { root: repoRoot, ref: baseRef, at: Date.now(), snapshot: readBaseTools(repoRoot, baseRef) };
+    }
+    const snapshot = repoCached.snapshot;
+    if (out.rts.codex) out.rts.codex = [...new Set([...out.rts.codex, ...snapshot.skills.map((s) => s.path.split('/')[2])])].slice(0, 80);
+    if (out.rtp.codex) out.rtp.codex = [...new Map([...out.rtp.codex, ...snapshot.tools
+      .filter((t) => t.state !== 'ready' || t.config.type === 'sse')
+      .map((t) => ({ n: t.name, s: 'failed' }))].map((server) => [server.n, server])).values()].slice(0, 80);
+  } catch { /* keep local measurements */ }
+  return out;
+}

package/bin/lib/runtimes.mjs

@@ -342,11 +342,40 @@ function parseCodexLine(line, cwd) {
       const activity = humanizeCodexItem(item, cwd);
       // Only the agent's MESSAGES are sentinel-bearing text. Reasoning is not:
       // a model that muses "I could output NOTHING here" must not end the turn.
-      const text =
-        (item.item_type ?? item.type) === 'agent_message'
-          ? `${item.text ?? item.message ?? ''}\n`
-          : '';
-      return { activity, text };
+      const isMessage = (item.item_type ?? item.type) === 'agent_message';
+      const text = isMessage ? `${item.text ?? item.message ?? ''}\n` : '';
+      // `answer` is the SAME message, surfaced alone: `text` accumulates every
+      // message plus every error and stderr line, so a caller that needs "what
+      // the agent said LAST" (the agent lane's final JSON object) cannot recover
+      // it from `out`. Claude's stream has this for free under
+      // `answerFromResult`; codex needed it said.
+      return { activity, text, ...(isMessage ? { answer: String(item.text ?? item.message ?? '') } : {}) };
+    }
+    // THE TURN'S OWN TOKEN COUNT (2026-09-24). `codex exec --json` closes a
+    // turn with `turn.completed` carrying `usage` — the codex twin of Claude's
+    // `result.usage`, and until now dropped on the floor, so a codex agent
+    // reported no spend at all. Mapped onto the daemon's four counters:
+    // OpenAI's `input_tokens` INCLUDES the cached part, Claude's excludes it,
+    // so the cached share is subtracted out rather than counted twice. Codex
+    // has no cache-creation figure; zero is what it reported, not a guess.
+    // Output already includes reasoning tokens on OpenAI's side.
+    case 'turn.completed': {
+      const u = ev.usage;
+      if (!u || typeof u !== 'object') return null;
+      const n = (v) => (Number.isFinite(Number(v)) && Number(v) > 0 ? Math.floor(Number(v)) : 0);
+      const cached = n(u.cached_input_tokens);
+      return {
+        activity: null,
+        text: '',
+        // `usageFromResult`'s shape (claude.mjs), so every consumer of
+        // `onUsage` reads one vocabulary whichever CLI counted it.
+        usage: {
+          input: Math.max(0, n(u.input_tokens) - cached),
+          output: n(u.output_tokens),
+          cacheCreate: 0,
+          cacheRead: cached,
+        },
+      };
     }
     case 'turn.failed': {
       // An error is prose too, and the sentence that explains a failed turn is
@@ -367,7 +396,12 @@ function parseCodexLine(line, cwd) {
           label: oneLine(ev.error?.message ?? 'turn failed'),
           ...(msg.trim() ? { full: msg } : {}),
         },
-        text: '',
+        // THE FAILURE'S OWN WORDS REACH `text` (2026-09-24), the rule the bare
+        // `error` arm below already keeps. This returned '' — so a codex turn
+        // that failed on a usage limit handed the limit matcher nothing, the
+        // agent landed in Stuck as "produced no output", and every other codex
+        // agent kept spending into the same wall.
+        text: msg.trim() ? `${msg}\n` : '',
       };
     }
     // A bare `error` event — the shape an auth failure arrives in ("401
@@ -555,7 +589,7 @@ export const RUNTIMES = {
      * strongest form of it available anywhere: `--append-system-prompt` sits
      * above the conversation rather than inside it.
      */
-    args({ prompt, system, model, effort, resume, streamJson, perm, mcp = [], resultSchemaArgs = [], adoptResumeId, resumeThreadId, knowledgeDir }) {
+    args({ prompt, system, model, effort, resume, streamJson, perm, profile = 'build', mcp = [], resultSchemaArgs = [], adoptResumeId, resumeThreadId, knowledgeDir, agentTools }) {
       const a = [];
       // THREE ANSWERS TO ONE QUESTION — "what conversation is this?" — and they
       // are mutually exclusive, never combined.
@@ -582,6 +616,17 @@ export const RUNTIMES = {
       else if (resumeThreadId) a.push('--resume', resumeThreadId);
       else if (resume) a.push('--continue');
       a.push('-p', prompt, '--append-system-prompt', system);
+      if (agentTools) {
+        // Keep personal settings, but never load the agent-editable project's
+        // settings, hooks, skills or CLAUDE.md discovery. A resumed agent must
+        // render the CURRENT base snapshot, not the first turn's prompt cache.
+        a.push('--setting-sources', 'user', '--system-prompt-snapshot', 'off');
+        if (agentTools.pluginDir) a.push('--plugin-dir', agentTools.pluginDir);
+      }
+      // These fenced postures have no project MCP, even if Claude discovers a
+      // .mcp.json in the agent's worktree. Build gets its reviewed base config
+      // explicitly from the caller; the plan profile keeps its own principal.
+      if (['consult', 'wiki', 'design', 'research'].includes(profile)) a.push('--strict-mcp-config');
       a.push(...mcp, ...resultSchemaArgs);
       a.push('--model', model || MODEL);
       if (effort) a.push('--effort', effort);
@@ -634,6 +679,11 @@ export const RUNTIMES = {
      * user's repository, which is not a risk worth taking for a slightly
      * stickier instruction.
      *
+     * Agent turns additionally pass reviewed base instructions as a developer
+     * config override when the personal config has no developer instruction;
+     * the prompt always carries them too. Workbench tabs keep their normal
+     * checkout discovery.
+     *
      * `--skip-git-repo-check` is deliberately NOT passed: a task always builds
      * in a git worktree, and if it somehow is not one, failing loudly beats
      * silently editing files nobody can diff.
@@ -644,7 +694,7 @@ export const RUNTIMES = {
      * placed before it. Appending them after the positional is the kind of argv
      * that parses today and stops parsing on some future clap upgrade.
      */
-    args({ prompt, system, model, effort, resume, resumeThreadId, profile = 'build', vaultDir, mcp = [], resultSchemaArgs = [], adoptResumeId }) {
+    args({ prompt, system, model, effort, resume, resumeThreadId, profile = 'build', vaultDir, mcp = [], resultSchemaArgs = [], adoptResumeId, agentTools }) {
       // Adoption resumes a conversation in ITS OWN CLI's store (claude forks,
       // agy moves) — codex has no adoptable store wired yet. Reaching here
       // with an adopt id is a wiring mistake upstream, and it fails loudly on
@@ -661,6 +711,13 @@ export const RUNTIMES = {
       if (resumeThreadId) a.push('resume', resumeThreadId);
       else if (resume) a.push('resume', '--last');
       a.push('--json');
+      if (agentTools) {
+        a.push('-c', 'project_doc_max_bytes=0');
+        // A person's existing developer instructions keep their authority.
+        // The base snapshot is also present in the per-turn prompt preamble.
+        if (!agentTools.personalDeveloperInstructions)
+          a.push('-c', `developer_instructions=${JSON.stringify(agentTools.instructions)}`);
+      }
       if (model) a.push('--model', model);
       // Effort is a config value on Codex rather than a flag.
       if (effort) a.push('-c', `model_reasoning_effort="${effort}"`);
@@ -1462,9 +1519,14 @@ export function probeSkillsOnce(cwd) {
   timer.unref?.();
   child.on('error', () => finish(null));
   child.on('exit', () => finish(null));
+  // UTF-8 mode on the STREAM, not a per-chunk `.toString()` — a multi-byte
+  // character straddling a chunk boundary decodes to mojibake (or a stray
+  // replacement byte) when each chunk is decoded on its own; the stream's
+  // own decoder holds the partial sequence over to the next chunk instead.
+  child.stdout.setEncoding('utf8');
   child.stdout.on('data', (d) => {
     if (settled) return;
-    buf += d.toString();
+    buf += d;
     let nl;
     while (!settled && (nl = buf.indexOf('\n')) >= 0) {
       const line = buf.slice(0, nl);

package/bin/lib/shipMerge.mjs

@@ -1,4 +1,4 @@
-import { baseBranchName } from './git.mjs';
+import { baseBranchName, gitNet as gitNetDefault } from './git.mjs';
 
 /**
  * CARRY A SHIPPED TIP OUT ONTO BASE AND PUSH IT.
@@ -28,6 +28,10 @@ export function mergeOutward({
   baseRef,
   workingTree,
   warn,
+  // NETWORK calls only (push, fetch) — timed and non-interactive, so a
+  // stale credential or a half-open connection cannot freeze the ship
+  // path's writer lock. Injectable for tests; defaults to the real one.
+  gitNet = gitNetDefault,
 }) {
   const dropTmp = () => {
     try {
@@ -43,7 +47,7 @@ export function mergeOutward({
       ['merge', '--no-ff', tip, '-m', `ship(${label}): ${count} commit${count === 1 ? '' : 's'}`],
       tmpDir
     );
-    git(['push', 'origin', `HEAD:${baseBranchName(baseRef())}`], tmpDir);
+    gitNet(['push', 'origin', `HEAD:${baseBranchName(baseRef())}`], tmpDir, 120_000);
   };
   try {
     try {
@@ -74,7 +78,7 @@ export function mergeOutward({
       if (!isRaceRejection(e)) throw e;
       warn?.('ship: base moved under us — refetching and merging again');
       try {
-        git(['fetch', 'origin', '--quiet'], repoRoot);
+        gitNet(['fetch', 'origin', '--quiet'], repoRoot, 60_000);
       } catch {
         /* offline — the retry fails honestly on the same push */
       }
@@ -102,7 +106,7 @@ export function mergeOutward({
      */
     if (workingTree && branch && branch === baseBranchName(baseRef())) {
       try {
-        git(['fetch', 'origin', '--quiet'], repoRoot);
+        gitNet(['fetch', 'origin', '--quiet'], repoRoot, 60_000);
         git(['merge', '--ff-only', baseRef()], workingTree);
       } catch {
         /* a readout, not the ship — the merge already landed, and the next

package/bin/lib/trace.mjs

@@ -38,10 +38,15 @@
  * second attempt then opened at `seq: 0` against a mark of three hundred, so
  * every batch it sent was trimmed to nothing and the surface showed the
  * ABANDONED attempt's steps with the new one's tail welded on, no seam, no
- * `dropped` to say so. `run` is a nonce per relay: the server rebases an
- * unfamiliar one onto its current mark, so a second attempt appends AFTER the
- * first instead of being deleted by it, and a retry inside one run still trims
- * exactly as before.
+ * `dropped` to say so. `run` is a nonce per relay: EACH RUN KEEPS ITS OWN
+ * HIGH-WATER MARK IN ITS OWN SEQ SPACE (2026-09-24) — an unfamiliar one starts
+ * its own mark at the server's shared `hw` rather than being rebased onto it,
+ * so a second attempt appends AFTER the first instead of being deleted by it,
+ * and a retry inside one run still trims exactly as before. The first cut
+ * rebased an unfamiliar run onto the one shared mark, so a takeover's old box,
+ * still flushing its last seconds, spliced its late steps between the new
+ * run's — a superseded run's late steps are COUNTED against the shared mark
+ * now (the trace is not lost) and never SPLICED between the live run's.
  *
  * SCRUB EVERY STRING. This is the CLI's own stdout — a command echoing an env
  * var, a read of a config file — riding the same uplink the answer does. Prose
@@ -163,8 +168,13 @@ export function makeTraceRelay({ agentId, turnId, post, scrub = (s) => s, run =
         dirty = true;
         return;
       }
-      queue.splice(0, entries.length);
-      base += entries.length;
+      // Remove only what of the batch is STILL at the head: a push during the
+      // await may have shed some of it already (advancing `base`), and
+      // splicing the whole batch length would then drop entries that were
+      // never sent — a gap the buffer had room to avoid.
+      const drop = Math.max(0, seq + entries.length - base);
+      queue.splice(0, drop);
+      base += drop;
     }
   };