flowviant 0.103.0 → 0.104.0

package/bin/lib/workAttachments.mjs

@@ -0,0 +1,93 @@
+/**
+ * FILES THE HUMAN ATTACHED, downloaded into the place a turn runs in.
+ *
+ * Split out of work.mjs (2026-09-26, SOLID F037). One trust boundary — a
+ * server-sent name becoming a path on somebody's machine — with its caps, its
+ * collision rule and its git exclude, reached only from the session lane.
+ * The name rule itself is safeFileName.mjs's.
+ */
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { FLEET_URL, FLEET_TOKEN, USER_AGENT } from './config.mjs';
+import { excludeInWorktree } from './git.mjs';
+import { FLOWVIANT_OWN_PATHS } from './knowledgeLibrary.mjs';
+import { safeFileName } from './safeFileName.mjs';
+import { fleetEndpoint } from './fleetWire.mjs';
+
+export function createWorkAttachments() {
+  const ATTACHMENT_URL = fleetEndpoint('attachment', FLEET_URL);
+  /**
+   * FILES THE HUMAN ATTACHED, brought to where a CLI can read them.
+   *
+   * A screenshot in a chat bubble is useless to an agent; a path is not. So the
+   * turn's attachments are downloaded into `.flowviant/uploads/` inside the
+   * session's own worktree and the prompt is handed the relative paths.
+   *
+   * `.flowviant/` rather than the repo proper, and gitignored-or-not it is
+   * never committed by us: these are the human's inputs to a conversation, not
+   * project files. The name is re-sanitized HERE even though the server already
+   * did it — this string becomes a path on someone's machine, and one place
+   * doing that check is one deploy away from being zero places.
+   */
+  const UPLOAD_DIR = '.flowviant/uploads';
+  const ATTACHMENT_MAX_BYTES = 10 * 1024 * 1024;
+  // `safeFileName` (bin/lib/safeFileName.mjs — the server's rule, one daemon
+  // home): THE EXTENSION SURVIVES A CUT, and it is idempotent over its own
+  // output, so re-applying it to what the server already sanitized is a no-op
+  // and the two sides never disagree about the cut. An empty name is
+  // `attachment`, the server's own fallback.
+  const safeUploadName = (raw) => safeFileName(raw, 'attachment');
+  /** @returns relative paths written, in the order the human attached them. */
+  const fetchAttachments = async (wt, attachments) => {
+    if (!Array.isArray(attachments) || attachments.length === 0) return [];
+    const dir = join(wt, UPLOAD_DIR);
+    try {
+      mkdirSync(dir, { recursive: true });
+    } catch {
+      return [];
+    }
+    // "Never committed by us" has to be true for GIT, not just for this code:
+    // an untracked `.flowviant/` makes the whole worktree dirty, which refuses
+    // every ship, exempts the tree from closed-tab retirement forever, and
+    // shows the human's own uploads in the rail as session changes. Same
+    // mechanism the materialized env files used until the vault was deleted —
+    // the exclude file git actually reads (git.mjs, where the helper moved when
+    // env.mjs shrank), which already skips lines it has written before, so
+    // calling it per fetch is idempotent. NARROWED 2026-09-23 to the paths
+    // this daemon writes (`FLOWVIANT_OWN_PATHS`, knowledgeLibrary.mjs says why): the
+    // whole-directory line also hid a repo's own new `.flowviant/check.json`
+    // from its agent's `git add -A`.
+    excludeInWorktree(wt, FLOWVIANT_OWN_PATHS);
+    const written = [];
+    for (const a of attachments.slice(0, 8)) {
+      if (!a?.id || typeof a.id !== 'string' || !/^[0-9a-f-]{8,64}$/i.test(a.id)) continue;
+      if (Number(a.size) > ATTACHMENT_MAX_BYTES) continue;
+      try {
+        const res = await fetch(`${ATTACHMENT_URL}/${a.id}`, {
+          headers: { Authorization: `Bearer ${FLEET_TOKEN}`, 'User-Agent': USER_AGENT },
+          signal: AbortSignal.timeout(60_000),
+        });
+        if (!res.ok) continue;
+        const buf = Buffer.from(await res.arrayBuffer());
+        if (buf.byteLength === 0 || buf.byteLength > ATTACHMENT_MAX_BYTES) continue;
+        // Collisions are real (two screenshots both named Screenshot.png), and
+        // silently overwriting one with the other loses a file the human sent.
+        let name = safeUploadName(a.name);
+        if (existsSync(join(dir, name))) {
+          const dot = name.lastIndexOf('.');
+          const stem = dot > 0 ? name.slice(0, dot) : name;
+          const ext = dot > 0 ? name.slice(dot) : '';
+          name = `${stem}-${String(a.id).slice(0, 6)}${ext}`;
+        }
+        writeFileSync(join(dir, name), buf);
+        written.push(`${UPLOAD_DIR}/${name}`);
+      } catch {
+        /* one file failing must not fail the turn — the prompt lists what
+           actually arrived, so the agent never chases a path that isn't there */
+      }
+    }
+    return written;
+  };
+
+  return { fetchAttachments };
+}

package/bin/lib/workBrain.mjs

@@ -0,0 +1,53 @@
+/**
+ * WHICH BRAIN, AT WHICH EFFORT — the one guard every turn's `--model` and
+ * `--effort` pass through before they ride argv.
+ *
+ * Split out of work.mjs (2026-09-26, SOLID F037). Two lanes read it — the
+ * Workbench tab (workSessionTurns.mjs) and the agent turn (workAgentTurns.mjs)
+ * — each importing it directly — and it is pure over the job and the runtime
+ * table, so its home is a module of its own rather than either lane.
+ */
+import { RUNTIMES } from './runtimes.mjs';
+
+/**
+ * The shape a per-tab model name must have before it rides argv as
+ * `--model <name>`. Conservative for the same reason the codex thread id is
+ * (below): it comes off the wire and lands in a child process's arguments —
+ * alphanumerics plus dot/dash/underscore, at most 40 characters, and NEVER a
+ * leading dash, which is an argv that parses as a flag.
+ */
+const WORK_MODEL_RE = /^[a-zA-Z0-9._][a-zA-Z0-9._-]{0,39}$/;
+
+/**
+ * WHICH BRAIN, AT WHICH EFFORT — the tab's own pick, off the roster.
+ *
+ * Absent is the resting state and it must stay genuinely absent: every tab ran
+ * with no `--model` and no `--effort` until now, so a job that names neither
+ * has to produce the byte-identical argv it produced yesterday — Claude falling
+ * back to the machine's MODEL pin, codex and agy to their own defaults. Hence
+ * an object with the key MISSING rather than one holding null: a null would
+ * reach the builders as a value and Claude's `model || MODEL` is the only one
+ * that would survive it.
+ *
+ * A value that fails its guard is DROPPED, not passed through and not an error.
+ * The honest outcome of "the server named a model this machine can't spell" is
+ * the machine's own default — a turn that runs — rather than a flag no CLI
+ * understands and a tab that fails every message.
+ */
+/**
+ * THE EFFORT IS CHECKED AGAINST THE CLI THAT WILL RUN THE TURN (2026-09-26).
+ * One global ladder once accepted `max` for every runtime, and Codex has no
+ * `max`: a skewed or previously queued Codex job reached argv as a
+ * `model_reasoning_effort` its CLI refuses. The per-CLI list lives beside each
+ * runtime's argv builder (`RUNTIMES[id].efforts`, runtime{Claude,Codex,Antigravity}.mjs); a runtime this
+ * daemon does not define runs nothing, so it spells no effort either.
+ */
+export function brainFor(job, runtimeId) {
+  const out = {};
+  const model = typeof job?.model === 'string' ? job.model.trim() : '';
+  if (model && WORK_MODEL_RE.test(model)) out.model = model;
+  const effort = typeof job?.effort === 'string' ? job.effort.trim() : '';
+  const efforts = RUNTIMES[runtimeId]?.efforts ?? [];
+  if (effort && efforts.includes(effort)) out.effort = effort;
+  return out;
+}

package/bin/lib/workChildren.mjs

@@ -0,0 +1,110 @@
+/**
+ * THE MACHINE'S LIVE CLI CHILDREN — the registry every lane adds its spawn
+ * to, the teardown that SIGTERMs them, the count the concurrency ceiling is
+ * on, and the admission built over that count.
+ *
+ * Split out of work.mjs (2026-09-26, SOLID F037). Six lanes write
+ * `workChildren` (tab turns, agent turns, plans, the check, the pre-review)
+ * and three things read it (teardown, `liveTurnCount`, the machine snapshot's
+ * per-task RSS), so the map and everything that reads it as "what is running
+ * on this box" belong together — and apart from any one lane.
+ */
+import { createAdmission } from './admission.mjs';
+
+export function createWorkChildren({ extraLiveTurns }) {
+  /**
+   * Live session-turn CLI children. The daemon's teardown SIGTERMs them: an
+   * orphaned CLI keeps editing the session worktree and burning quota after
+   * the daemon is gone. Each child's pid-lock is deliberately LEFT IN PLACE —
+   * a CLI can trap SIGTERM to finish an in-flight request and outlive this
+   * loop by seconds, and removing the lock in the same tick handed the
+   * restarted daemon a green light to spawn a second CLI into the same held
+   * context. turnLockedByLivePid already covers both outcomes: it waits while
+   * the pid lives and clears the lock once it is dead.
+   *
+   * THE VALUE IS THE ID THE CHILD SERVES, and it used to be the pid-lock path —
+   * which nothing in this file has ever read. A write-only value is not free:
+   * the machine snapshot's per-task RSS (`/fleet/machine`) is the one readout
+   * that answers "which task is holding nine gigabytes", and it was being built
+   * from the dispatch-era `workers` map, which nothing has `.set()` since that
+   * lane was deleted — so the column its own server handler calls the
+   * load-bearing half of the report had never been populated once. This map is
+   * the only place that knows both the pid and whose work it is, so it carries
+   * both. `null` where there is no id to name (a Deploy press is not a task).
+   */
+  const workChildren = new Map(); // child process -> sessionId | agentId | null
+  /**
+   * Children whose whole PROCESS GROUP must go, not just the child.
+   *
+   * The standing rule is the opposite — teardown SIGTERMs the CLI child and
+   * never its group, precisely so an unattended auto-update does not kill the
+   * driver's dev server, which a turn started INTO the CLI's group. That rule
+   * is about the CLI's group and stays.
+   *
+   * A project CHECK is a different group entirely: the daemon spawns it itself,
+   * `detached` with `shell: true`, so its group holds the check command and
+   * nothing else — no dev server of anybody's. And `shell: true` is exactly
+   * what makes signalling only the child useless: a compound command like
+   * `npm run lint && npm test` leaves `/bin/sh` as the child, so SIGTERM killed
+   * the shell and the test runner underneath it carried on holding the
+   * worktree — and that place's WRITER lock — through every stop, takeover and
+   * auto-update. The check's own ten-minute timer already kills `-child.pid`
+   * for this reason; teardown simply did not.
+   */
+  const groupKillChildren = new Set();
+  const shutdownWork = () => {
+    for (const [ch] of workChildren) {
+      try {
+        if (groupKillChildren.has(ch) && ch.pid) process.kill(-ch.pid, 'SIGTERM');
+        else ch.kill('SIGTERM');
+      } catch {
+        // A group that has already gone, or a pid that is no longer a leader.
+        try {
+          ch.kill('SIGTERM');
+        } catch {
+          /* best-effort */
+        }
+      }
+    }
+    workChildren.clear();
+    groupKillChildren.clear();
+  };
+
+  /**
+   * HOW MANY CLIs THIS MACHINE IS RUNNING RIGHT NOW — the number
+   * `MAX_CONCURRENT` is a ceiling on, and the thing that had no counter.
+   *
+   * Every lane, because the bound is on the BOX and not on a lane: session
+   * turns, an agent's turn, a Deploy press's planner, a project check — all of
+   * them land in `workChildren` — plus whatever the caller reports on top of it
+   * (the wiki cartographer, wikiRunner.mjs).
+   *
+   * THE PROJECT CHECK COUNTS, deliberately. It is not a model turn, but it is a
+   * full test or build run in a worktree, which is exactly the kind of process
+   * this ceiling exists to stop stacking. Nothing gates a check, so counting it
+   * cannot deadlock: it only ever delays the NEXT spawn.
+   */
+  const liveTurnCount = () => {
+    const extra = Number(extraLiveTurns() ?? 0);
+    return workChildren.size + (Number.isFinite(extra) && extra > 0 ? extra : 0);
+  };
+
+  /** The live turn children with the id each one serves — what the machine
+   *  snapshot charges its per-task RSS to. Children with no id (the planner)
+   *  are still counted above; they just have nothing to be charged TO. */
+  const liveTurns = () => {
+    const out = [];
+    for (const [ch, id] of workChildren) if (ch?.pid) out.push({ id: id ?? null, pid: ch.pid });
+    return out;
+  };
+
+  /**
+   * WHETHER TO START ONE MORE. See admission.mjs for the whole argument: a
+   * runaway bound on a machine, read at the spawn, surfaced only as the
+   * machine's own measured sentence at the thing that is waiting, and never a
+   * reason to settle a job — a deferred job is re-offered next poll.
+   */
+  const admit = createAdmission({ liveTurnCount });
+
+  return { workChildren, groupKillChildren, shutdownWork, liveTurnCount, liveTurns, admit };
+}

package/bin/lib/workCommandAudit.mjs

@@ -0,0 +1,62 @@
+/**
+ * THE COMMAND AUDIT — the durable record of every `$ …` a tab's CLI ran on the
+ * shared machine, batched to `/fleet/session-commands`.
+ *
+ * Split out of work.mjs's session turn (2026-09-26, SOLID F037). One per turn;
+ * the lane feeds it the stream's activity and flushes it at settle. It carries
+ * commands only, scrubbed, and a failed post drops the batch rather than
+ * blocking the turn.
+ */
+import { FLEET_URL, FLEET_TOKEN, USER_AGENT } from './config.mjs';
+import { scrub as envScrub } from './uplinkScrub.mjs';
+import { fleetEndpoint } from './fleetWire.mjs';
+
+// THE COMMAND AUDIT — every `$ …` the CLI's stream reports, batched
+// to the server verbatim so an admin can read what actually ran on
+// this box. Same events the narrator renders and forgets; this is
+// the durable copy, and it carries ONLY commands — no prose, no
+// thinking, no file reads (the session stays private; what executed
+// on the shared machine is the machine's own fact to relay).
+// Flushed mid-turn every 25 so a long turn is not one giant loss on
+// a kill, and again at settle. Best-effort: a failed post drops the
+// batch rather than blocking the turn — the surface says it is the
+// machine's report, not a syscall trace.
+export function createCommandAudit({ sessionId, turnId, runtime, cwd }) {
+  const SESSION_COMMANDS_URL = fleetEndpoint('session-commands', FLEET_URL);
+  const auditBatch = [];
+  const flushAudit = () => {
+    if (auditBatch.length === 0) return;
+    const commands = auditBatch.splice(0, auditBatch.length);
+    void fetch(SESSION_COMMANDS_URL, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${FLEET_TOKEN}`,
+        'User-Agent': USER_AGENT,
+        'Content-Type': 'application/json',
+      },
+      signal: AbortSignal.timeout(30_000),
+      body: JSON.stringify({
+        sessionId,
+        turnId,
+        runtime,
+        cwd,
+        commands,
+      }),
+    }).catch(() => {
+      /* best-effort — the audit records what reached it */
+    });
+  };
+  const auditCommand = (a) => {
+    if (a?.kind !== 'bash' || !a.command) return;
+    // Scrubbed like every other string that leaves this box (the
+    // narrator label, the settle answer, commit subjects, ship/merge
+    // lines, the per-tab process report). A command line is exactly
+    // where a secret leaks — `curl -H "authorization: <token>"`,
+    // `PGPASSWORD=… psql` — and the audit is stored 30 days and rendered
+    // in the admin view, so the one uplink that omitted scrub was the
+    // one most likely to carry a plaintext secret.
+    auditBatch.push({ command: envScrub(a.command), at: new Date().toISOString() });
+    if (auditBatch.length >= 25) flushAudit();
+  };
+  return { flushAudit, auditCommand };
+}

package/bin/lib/workDiffs.mjs

@@ -1,9 +1,10 @@
 /** Commit diff requests and their bounded reports. */
 import { FLEET_URL, FLEET_TOKEN, USER_AGENT } from './config.mjs';
 import { git } from './git.mjs';
+import { fleetEndpoint } from './fleetWire.mjs';
 
 export function createWorkDiffs({ repoRoot }) {
-  const DIFF_DONE_URL = FLEET_URL.replace(/\/agents\/?$/, '/diff-done');
+  const DIFF_DONE_URL = fleetEndpoint('diff-done', FLEET_URL);
 
   /**
    * COMMIT DIFFS, on request — the one PULL-shaped thing this daemon does.

package/bin/lib/workNarration.mjs

@@ -0,0 +1,152 @@
+/**
+ * THE TAB'S LIVE LINE — the CLI's own stdout relayed while a turn runs, and
+ * the machine's one sentence when it defers a turn the tab is waiting on.
+ *
+ * Split out of work.mjs (2026-09-26, SOLID F037). Both ride
+ * `/fleet/session-activity`, both are throttled decoration that must never
+ * fail a turn, and both change for the same reason (what the tab shows while
+ * nothing has settled). The session lane builds one narrator per turn and
+ * clears the deferral clock when a turn actually starts.
+ */
+import { FLEET_URL, FLEET_TOKEN, USER_AGENT } from './config.mjs';
+import { scrub as envScrub } from './uplinkScrub.mjs';
+import { fleetEndpoint } from './fleetWire.mjs';
+
+export function createWorkNarration() {
+  const ACTIVITY_URL = fleetEndpoint('session-activity', FLEET_URL);
+  /**
+   * THE TAB'S LIVE NARRATION — the terminal's own stdout, relayed.
+   *
+   * A turn used to be a spinner: the tab said "working…" for minutes and the
+   * only thing that ever appeared was the finished reply. The CLI is printing
+   * the whole time (thinking, reads, greps, commands), so the honest fix is to
+   * FORWARD that, not to invent a progress model on the server. Flowviant
+   * relays; it does not narrate on its own behalf.
+   *
+   * Best-effort by construction: throttled to one POST per window (a turn can
+   * emit hundreds of lines), never awaited by the turn, and every failure is
+   * swallowed. A spinner must never be able to fail a build. The server clears
+   * the line at settle, so a daemon killed mid-turn cannot leave one stuck.
+   */
+  const ACTIVITY_MIN_MS = 1_500;
+  const ACTIVITY_KEEP = 4; // the last few lines — a tail, not a log
+  /** `turnId` scopes the narration to the turn that produced it: a POST
+   *  already on the wire when the turn settles must not re-stamp a "working…"
+   *  line over the finished reply — the server drops narration for a turn
+   *  that is no longer pending. (A session-level pending count can't tell the
+   *  settled turn's stale line from the queued NEXT turn's fresh one.) */
+  const makeNarrator = (sessionId, turnId, getTools) => {
+    const recent = [];
+    let lastSent = 0;
+    let dirty = false;
+    let timer = null;
+    let sending = false;
+    let stopped = false;
+    const send = async () => {
+      if (sending || stopped) return;
+      sending = true;
+      dirty = false;
+      lastSent = Date.now();
+      const lines = recent.slice(-ACTIVITY_KEEP);
+      try {
+        await fetch(ACTIVITY_URL, {
+          method: 'POST',
+          headers: {
+            Authorization: `Bearer ${FLEET_TOKEN}`,
+            'User-Agent': USER_AGENT,
+            'Content-Type': 'application/json',
+          },
+          signal: AbortSignal.timeout(10_000),
+          body: JSON.stringify({
+            sessionId,
+            turnId,
+            lines,
+            // The structured tool log so far, riding the same throttled beat.
+            // Same lifecycle as the lines: overwritten as the turn moves,
+            // cleared server-side at settle. Absent until something ran.
+            ...(getTools ? { tools: getTools() } : {}),
+          }),
+        });
+      } catch {
+        /* narration is decoration — a dropped line is not an incident */
+      }
+      sending = false;
+      if (dirty && !stopped) schedule();
+    };
+    const schedule = () => {
+      if (timer || stopped) return;
+      const wait = Math.max(0, ACTIVITY_MIN_MS - (Date.now() - lastSent));
+      timer = setTimeout(() => {
+        timer = null;
+        void send();
+      }, wait);
+      timer.unref?.(); // never hold the process open for a spinner
+    };
+    return {
+      line(label) {
+        // Scrub, like every string that leaves this machine: a narration line
+        // is the CLI's own stdout — a command echoing an env var, a read of a
+        // config file — and it rides the same uplink the final answer does.
+        const s = envScrub(String(label ?? ''))
+          .replace(/\s+/g, ' ')
+          .trim()
+          .slice(0, 200);
+        if (!s || stopped) return;
+        recent.push(s);
+        if (recent.length > ACTIVITY_KEEP * 2) recent.shift();
+        dirty = true;
+        schedule();
+      },
+      stop() {
+        stopped = true;
+        if (timer) {
+          clearTimeout(timer);
+          timer = null;
+        }
+      },
+    };
+  };
+
+  /**
+   * TELL THE TAB IT IS WAITING ON THE BOX, not on its Claude.
+   *
+   * A deferred turn is invisible from a browser: the composer says "working…"
+   * and the machine simply does not spawn, which looks exactly like a slow
+   * model. So the deferral rides the narration channel the turn would have used
+   * anyway — the turn is still pending, so the server accepts the line — and
+   * says the measured reason and what happens next. The machine's own voice,
+   * for a moment only this side can see; the same shape the planner's "waiting
+   * for the checkout" already keeps.
+   *
+   * ONCE PER SESSION PER WINDOW, because the roster re-offers the same turn on
+   * every poll and restating an unchanged sentence every ten seconds is a POST
+   * loop, not a readout. The clock is cleared the moment a turn for that session
+   * actually starts, so the next stall speaks immediately rather than inheriting
+   * a window from an unrelated one.
+   */
+  const DEFER_SAY_MS = 30_000;
+  const lastDeferSaid = new Map(); // sessionId -> ms
+  const sayTurnDeferred = (sessionId, turnId, reason) => {
+    const now = Date.now();
+    if (now - (lastDeferSaid.get(sessionId) ?? 0) < DEFER_SAY_MS) return;
+    lastDeferSaid.set(sessionId, now);
+    void fetch(ACTIVITY_URL, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${FLEET_TOKEN}`,
+        'User-Agent': USER_AGENT,
+        'Content-Type': 'application/json',
+      },
+      signal: AbortSignal.timeout(10_000),
+      body: JSON.stringify({
+        sessionId,
+        turnId,
+        lines: [`Deferred — ${reason}. The machine retries on its next poll.`],
+      }),
+    }).catch(() => {
+      /* a readout — a dropped line is not an incident */
+    });
+  };
+
+  return { makeNarrator, sayTurnDeferred, lastDeferSaid };
+}