flowviant 0.51.1 → 0.52.0

package/bin/lib/claude.mjs

@@ -197,7 +197,7 @@ const oneLine = (s, n = 160) => String(s).replace(/\s+/g, ' ').trim().slice(0, n
 // every intermediate text block still NARRATES, but only the final `result`
 // event contributes text — otherwise the same sentences arrive twice, once as
 // they stream and once in the result, and the tab posts the duplicate.
-function handleStreamLine(line, { cwd, emit, onActivity, appendText, answerFromResult }) {
+function handleStreamLine(line, { cwd, emit, onActivity, appendText, answerFromResult, onInit }) {
   let ev;
   try {
     ev = JSON.parse(line);
@@ -224,6 +224,19 @@ function handleStreamLine(line, { cwd, emit, onActivity, appendText, answerFromR
         push(humanizeToolUse(b.name, b.input || {}, cwd));
       }
     }
+  } else if (ev.type === 'system' && ev.subtype === 'init') {
+    // WHAT THIS MACHINE'S CLI CAN BE ASKED FOR BY NAME. The init event is the
+    // CLI's OWN answer — it has already resolved personal skills, this repo's
+    // skills, plugins and whatever the project settings enable or disable — so
+    // reading it costs nothing and cannot drift the way a `~/.claude/skills`
+    // scan of our own would. `skills` (rather than `slash_commands`) is the
+    // deliberate narrowing: the 50-odd commands beside it are the CLI's own
+    // interactive furniture (/clear, /model, /compact), and offering those in a
+    // relayed tab would be an offer wired to nothing.
+    //
+    // Only ever REPORTED, never enforced. Flowviant does not decide what your
+    // Claude can do; it relays what your Claude said it has.
+    if (Array.isArray(ev.skills)) onInit?.({ skills: ev.skills.map(String) });
   } else if (ev.type === 'result') {
     // The final assistant text (carries WIKI_DONE / REGROUND_DONE).
     if (typeof ev.result === 'string') appendText(ev.result + '\n');
@@ -247,7 +260,7 @@ function handleStreamLine(line, { cwd, emit, onActivity, appendText, answerFromR
 // returned string for sentinel detection, and each activity is handed to
 // `onActivity` so the caller can forward progress. Build-agent turns leave it
 // off and keep the raw text passthrough + line sentinels.
-export function runTurn({ prompt, resume, system, cwd, mcpConfig, mcpArgs, mcpEnv, runtime = 'claude', label, onSpawn, streamJson, answerFromResult, onActivity, onThreadId, wikiPerm, readOnly, planPerm, vaultDir, resultSchemaArgs, model, effort, adoptResumeId, resumeThreadId, resumeConversationId }) {
+export function runTurn({ prompt, resume, system, cwd, mcpConfig, mcpArgs, mcpEnv, runtime = 'claude', label, onSpawn, streamJson, answerFromResult, onActivity, onInit, onThreadId, wikiPerm, readOnly, planPerm, vaultDir, resultSchemaArgs, model, effort, adoptResumeId, resumeThreadId, resumeConversationId }) {
   return new Promise((resolve) => {
     const rt = runtimeById(runtime);
     if (!rt.args) {
@@ -359,7 +372,7 @@ export function runTurn({ prompt, resume, system, cwd, mcpConfig, mcpArgs, mcpEn
       /** One line of the child's stdout, in whichever dialect it speaks. */
       const onLine = (line) => {
         if (!rt.parse)
-          return handleStreamLine(line, { cwd, emit, onActivity, appendText, answerFromResult });
+          return handleStreamLine(line, { cwd, emit, onActivity, appendText, answerFromResult, onInit });
         const ev = rt.parse(line, cwd);
         if (!ev) return;
         // The conversation id, when the runtime announces one (codex's

package/bin/lib/fleet.mjs

@@ -60,6 +60,7 @@ import {
   REGROUND_KICKOFF,
 } from './claude.mjs';
 import { reapOrphanPreviews } from './preview.mjs';
+import { acquireInstanceLock } from './instance.mjs';
 import { preflight } from './preflight.mjs';
 import { connectStream } from './stream.mjs';
 import { ensureVault, syncVault } from './vault.mjs';
@@ -72,7 +73,7 @@ import {
 } from './env.mjs';
 import { processDeployJobs, reportDeployConfig } from './deploy.mjs';
 import { machineSnapshot } from './resources.mjs';
-import { detectRuntimes, pickRuntimeFor, RUNTIMES } from './runtimes.mjs';
+import { detectRuntimes, knownSkills, pickRuntimeFor, RUNTIMES } from './runtimes.mjs';
 import { createWorkManager } from './work.mjs';
 import { scanLocalSessions } from './localSessions.mjs';
 
@@ -117,6 +118,21 @@ async function fetchRoster(haveIds) {
   } catch {
     /* detection is best-effort — a probe must never fail the poll */
   }
+  // WHAT THE CLI CAN BE ASKED FOR BY NAME, so the composer can autocomplete a
+  // `/` the way the terminal does. Learned from the init event of a turn we
+  // already ran (runtimes.mjs) — never probed, because spawning a CLI to fill a
+  // dropdown would spend the operator's quota on an affordance.
+  //
+  // NOT SENT until a turn has taught us: absent means "no turn has run here
+  // yet", and the app renders no menu rather than asserting this machine has no
+  // skills. An empty report, though, IS a fact and is sent as such — hence the
+  // null check rather than a truthiness check on the array.
+  try {
+    const skills = knownSkills();
+    if (skills !== null) url.searchParams.set('skills', skills.join(','));
+  } catch {
+    /* best-effort — the poll must never fail on a readout */
+  }
   // Env-sync identity + materialized version (the Settings "env vN" chip).
   try {
     for (const [k, v] of Object.entries(await envQueryParams())) {
@@ -261,6 +277,32 @@ export async function runFleetDaemon() {
   );
   info(`server · ${FLEET_URL}`);
   console.log('');
+
+  // ONE DAEMON PER CREDENTIAL. Before preflight, before the preview reap,
+  // before anything with a side effect — a second daemon must not so much as
+  // install a CLI or clear a registry on its way to being refused. Keyed on the
+  // credential rather than the repo, because two checkouts on one credential is
+  // the SAME project served twice, and the worst version of this: their session
+  // worktrees are in different directories, so the per-turn lock cannot even see
+  // across them. See instance.mjs for why that lock is not enough on its own.
+  const instance = acquireInstanceLock(FLEET_TOKEN, repoRoot);
+  if (!instance.ok) {
+    const h = instance.holder;
+    console.log('');
+    fail('a flowviant daemon is already running for this credential.');
+    if (h?.pid) info(`holder · pid ${h.pid}${h.repoRoot ? ` in ${h.repoRoot}` : ''}`);
+    // The two-checkouts case is the one nobody spots on their own: both tabs
+    // look healthy, and the damage is doubled cards and doubled edits in a repo
+    // you are not looking at. Name the other repo when it is a different one.
+    if (h?.repoRoot && h.repoRoot !== repoRoot)
+      warn('that is a DIFFERENT checkout — one credential serves one project, so both would answer the same tabs.');
+    note('stop the other one first, or run this one with FLOWVIANT_ALLOW_MULTI=1 if you know what you are doing.');
+    console.log('');
+    process.exit(1);
+  }
+  if (instance.unguarded)
+    warn('could not take the single-instance lock (unwritable ~/.flowviant) — running unguarded');
+
   await preflight({ needGit: true });
   // Kill any preview dev-server/tunnel groups a previously-crashed daemon left
   // running (detached children survive an ungraceful exit) before we start fresh.

package/bin/lib/instance.mjs

@@ -0,0 +1,152 @@
+/**
+ * ONE DAEMON PER CREDENTIAL, refused at startup.
+ *
+ * WHY THIS EXISTS. Nothing stopped two daemons before, and the server hands
+ * work out by READING, never claiming: `listWorkTurnJobs` selects every pending
+ * turn for the fleet token, `listShipJobs` reads a flag. So two daemons on one
+ * credential are offered the SAME turn — and the ProjectRoom nudges every
+ * connected daemon socket at once, so they do not even drift out of phase.
+ *
+ * The per-worktree `flowviant-turn.lock` cannot save it. That lock is written
+ * AFTER the work token is minted and the attachments are fetched — a window
+ * containing a network round trip — so both daemons clear the check and both
+ * spawn a CLI into one held conversation. It was built for a RESTARTED daemon
+ * (its own comment says so, work.mjs), where the holder is already live when
+ * the successor looks; it was never a concurrency primitive.
+ *
+ * What the duplicate run costs, all of it invisible in the tab: two Claudes
+ * editing one worktree, two cards from one `file_card` (no idempotency key),
+ * the session write budget spent twice, quota spent twice — and then exactly
+ * ONE answer survives, because `settleWorkTurn` is atomic. The side effects
+ * land twice and the transcript shows one turn.
+ *
+ * KEYED ON THE CREDENTIAL, NOT THE REPO. The credential is stored once, at
+ * ~/.flowviant/credentials.json, so `flowviant` in two DIFFERENT checkouts is
+ * still one project served twice — and that case is strictly worse, because the
+ * two daemons have different worktree roots and the turn lock cannot even see
+ * across them. Keying on the token catches both, and still lets a second
+ * credential run a second project on the same machine.
+ *
+ * IT FAILS OPEN. A home directory we cannot write to is not a reason to refuse
+ * to start; it is a reason to say so and carry on unguarded.
+ */
+
+import { closeSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync, writeSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+
+/** Deliberately a HASH: a credential must never become a filename. */
+export function instanceLockPath(fleetToken) {
+  const key = createHash('sha256').update(String(fleetToken || 'anon')).digest('hex').slice(0, 12);
+  return join(homedir(), '.flowviant', `daemon-${key}.lock`);
+}
+
+/** Signal 0 — a liveness probe, not a kill. EPERM means alive and not ours. */
+function alive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e.code === 'EPERM';
+  }
+}
+
+function readHolder(path) {
+  try {
+    const v = JSON.parse(readFileSync(path, 'utf8'));
+    return v && Number.isInteger(v.pid) && v.pid > 0 ? v : null;
+  } catch {
+    return null; // absent, truncated, or half-written — treat as no holder
+  }
+}
+
+const record = (repoRoot) =>
+  JSON.stringify({ pid: process.pid, repoRoot, startedAt: new Date().toISOString() });
+
+/**
+ * Take the lock, or report who holds it.
+ *
+ * Returns `{ ok: true, release }` — call `release()` to drop it, and it is
+ * already wired to process exit — or `{ ok: false, holder }` with the other
+ * daemon's pid and repo so the caller can say something useful.
+ *
+ * `wx` is the whole guarantee: create-exclusive is one atomic syscall, which is
+ * the property the turn lock's check-then-write does not have.
+ */
+export function acquireInstanceLock(fleetToken, repoRoot) {
+  if (process.env.FLOWVIANT_ALLOW_MULTI === '1') return { ok: true, release: () => {} };
+  const path = instanceLockPath(fleetToken);
+  try {
+    mkdirSync(join(homedir(), '.flowviant'), { recursive: true });
+  } catch {
+    return { ok: true, release: () => {}, unguarded: true };
+  }
+
+  // Two passes at most: one to clear a stale holder, one to take the lock. A
+  // loop here would spin against a peer that keeps re-taking it.
+  for (let attempt = 0; attempt < 2; attempt++) {
+    let fd;
+    try {
+      fd = openSync(path, 'wx');
+    } catch (e) {
+      if (e.code !== 'EEXIST') return { ok: true, release: () => {}, unguarded: true };
+      const holder = readHolder(path);
+      if (!holder || !alive(holder.pid)) {
+        // A crashed daemon's leftover. Clear it and take it on the next pass.
+        try {
+          rmSync(path, { force: true });
+        } catch {
+          return { ok: true, release: () => {}, unguarded: true };
+        }
+        continue;
+      }
+      // OUR OWN PARENT, which is not a second daemon — it is this one, mid
+      // re-exec. The SELF-UPDATE is the case: a live daemon holding this lock
+      // installs a new version, spawns it, and stays alive as a proxy awaiting
+      // it (update.mjs), so the successor's ppid IS the holder. Refusing there
+      // would brick every auto-update. Adopt instead; the parent's release is
+      // ownership-checked, so it will not delete the lock it handed over.
+      // (`flowviant login` also proxies a child, but that parent never reached
+      // the daemon and holds nothing — the child simply acquires.)
+      if (holder.pid === process.ppid) {
+        try {
+          writeFileSync(path, record(repoRoot));
+        } catch {
+          return { ok: true, release: () => {}, unguarded: true };
+        }
+        return { ok: true, release: makeRelease(path) };
+      }
+      return { ok: false, holder };
+    }
+    try {
+      writeSync(fd, record(repoRoot));
+    } finally {
+      closeSync(fd);
+    }
+    return { ok: true, release: makeRelease(path) };
+  }
+  // Both passes lost to something re-creating the file — assume a peer.
+  return { ok: false, holder: readHolder(path) };
+}
+
+/** Release ONLY what we still own: a successor that adopted the lock (see the
+ *  ppid branch) must not have it deleted out from under it when we exit. */
+function makeRelease(path) {
+  let released = false;
+  const release = () => {
+    if (released) return;
+    released = true;
+    const holder = readHolder(path);
+    if (holder && holder.pid !== process.pid) return; // handed over — leave it
+    try {
+      rmSync(path, { force: true });
+    } catch {
+      /* best-effort; a stale file is cleared by the next acquire */
+    }
+  };
+  // 'exit' covers the SIGINT/SIGTERM handlers too — both call process.exit().
+  process.on('exit', release);
+  return release;
+}

package/bin/lib/prompts.mjs

@@ -304,6 +304,12 @@ rules:
    spec is what somebody's review is about. And when list_cards says
    \`truncated\` is above zero, the queue is LONGER than the list you were
    handed — say so rather than letting a short list read as the whole board.
+   SAY WHAT WAITS ON WHAT. \`waitsOn\` takes the task ids a card cannot start
+   until, and it is what turns a feature from a heap into a sequence: the
+   migration before the endpoint, the endpoint before the UI, the polish last.
+   The Board orders and bands cards from it — READY vs WAITING — so a person who
+   was not in this conversation can still see where to start. Declare it while
+   you are decomposing, because that is the one moment anyone knows.
 11. DELIVER WITH RECEIPTS. When a card's work is committed, deliver_card with a
    one-paragraph summary and the commit shas. Delivered is ASSERTED; done is
    OBSERVED (the merge, on their word). Never claim done, and never deliver
@@ -391,24 +397,73 @@ for work, do it.
 
 Write plain Markdown for a person reading your reply in a chat tab.`;
 
+/**
+ * A LEADING SLASH COMMAND, which the CLI will only expand at position 0.
+ *
+ * Claude Code parses `/name …` as a command ONLY when it opens the prompt. Every
+ * turn here wraps the human's words in the scaffolding below, so a `/code-review`
+ * typed into a tab used to arrive on line 6 of a fenced block — inert text that
+ * looked like it should have worked. That is the product telling you no for
+ * bookkeeping reasons, which is the one thing it never does.
+ *
+ * SHAPE, NOT MEMBERSHIP. We do not check the name against the machine's skill
+ * list: that list is only learned after a turn has run (runtimes.mjs), so
+ * gating on it would make the first `/foo` of a machine's life behave
+ * differently from the second. Instead this matches what a command can LOOK
+ * like — one segment, no second slash — which leaves `/home/user/x.ts is
+ * broken` fenced as the prose it is. Measured on 2.1.238: an unknown command
+ * is treated as ordinary text, so a false positive costs nothing anyway.
+ */
+const LEADING_SLASH_COMMAND = /^\/[A-Za-z0-9][A-Za-z0-9_:-]*(?=\s|$)/;
+
+/**
+ * The kickoff, in the two orders it can be written.
+ *
+ * ORDINARY: scaffolding first, the human's words fenced inside it. The speaker
+ * is the tab's OWNER — the same person who owns this machine — so this is the
+ * one prompt whose author is fully trusted. The fence stays anyway: it costs
+ * nothing and keeps the shape identical everywhere, and repo content this turn
+ * READS is as untrusted as ever.
+ *
+ * SLASH: the human's words go FIRST, verbatim and unfenced, because that is the
+ * only position the CLI expands a command from — and the scaffolding follows,
+ * LABELLED as ours so the trailing lines cannot read as more of what the person
+ * typed. The fence is what is traded away, and only for the one author already
+ * trusted above; nothing else about the turn changes.
+ */
+const kickoff = ({ message, askedByName, head, tail }) => {
+  const scaffold =
+    `${head}\n\n` +
+    `${fence('WHO IS TALKING', askedByName || 'the tab owner')}\n\n`;
+  if (LEADING_SLASH_COMMAND.test(message.trim()))
+    return (
+      `${message.trim()}\n\n` +
+      `---\n` +
+      `[FLOWVIANT SESSION CONTEXT — written by Flowviant, not typed by the person above]\n` +
+      `${scaffold}${tail}`
+    );
+  return `${scaffold}${fence('WHAT THEY SAID', message)}\n\n${tail}`;
+};
+
 export const WORK_TURN_KICKOFF = ({ sessionId, sessionName, message, askedByName }) =>
-  // The speaker is the tab's OWNER — the same person who owns this machine —
-  // so this is the one prompt whose author is fully trusted. The fence stays
-  // anyway: it costs nothing and keeps the shape identical everywhere, and repo
-  // content this turn READS is as untrusted as ever.
-  `Continue the session${sessionName ? ` "${sessionName}"` : ''}.\n\n` +
-  `SESSION ID (pass this to stream_session_turn / update_session): ${sessionId}\n\n` +
-  `${fence('WHO IS TALKING', askedByName || 'the tab owner')}\n\n` +
-  `${fence('WHAT THEY SAID', message)}\n\n` +
-  `Stream your reply with stream_session_turn as you work.`;
+  kickoff({
+    message,
+    askedByName,
+    head:
+      `Continue the session${sessionName ? ` "${sessionName}"` : ''}.\n\n` +
+      `SESSION ID (pass this to stream_session_turn / update_session): ${sessionId}`,
+    tail: `Stream your reply with stream_session_turn as you work.`,
+  });
 
 /** The plain tab's kickoff: no session id (there is no tool to pass it to)
  *  and no streaming instruction — the final message is the reply. */
 export const WORK_TURN_KICKOFF_PLAIN = ({ sessionName, message, askedByName }) =>
-  `Continue the session${sessionName ? ` "${sessionName}"` : ''}.\n\n` +
-  `${fence('WHO IS TALKING', askedByName || 'the tab owner')}\n\n` +
-  `${fence('WHAT THEY SAID', message)}\n\n` +
-  `Reply with your complete report when the work is done.`;
+  kickoff({
+    message,
+    askedByName,
+    head: `Continue the session${sessionName ? ` "${sessionName}"` : ''}.`,
+    tail: `Reply with your complete report when the work is done.`,
+  });
 
 
 export const REGROUND_KICKOFF = ({ sha, title, files, vaultDir, predictedPages = [] }) =>

package/bin/lib/runtimes.mjs

@@ -903,3 +903,50 @@ export function detectRuntimes({ refresh = false } = {}) {
   });
   return detectedCache;
 }
+
+/**
+ * WHAT THE CLI SAID IT CAN BE ASKED FOR BY NAME — the machine's skills.
+ *
+ * Learned, never scanned. Claude Code's `system.init` event names its own
+ * resolved skill set on every stream-json turn, and the daemon already parses
+ * that stream (claude.mjs), so this costs nothing and is authoritative: it has
+ * plugins, this repo's `.claude/skills`, and whatever project settings enabled
+ * or disabled already folded in. A `~/.claude/skills` scan of our own would be
+ * a second implementation of the CLI's resolution rules, and would drift.
+ *
+ * THE PRICE OF LEARNING RATHER THAN PROBING is that a machine which has not run
+ * a turn yet knows nothing, and says nothing. That is the honest answer: the
+ * app renders no menu rather than an empty one, and a slash typed into a tab
+ * still reaches the CLI either way — the menu is an autocomplete, never a gate.
+ * We do NOT probe for it: a `claude -p` run purely to populate a dropdown would
+ * spend the operator's quota on a UI affordance.
+ *
+ * PER MACHINE, not per session. Every session worktree is a checkout of the one
+ * repo this daemon serves, so project skills are identical across tabs and
+ * personal skills are machine-wide. Last turn wins, which is what makes a skill
+ * added mid-run show up on the next poll.
+ */
+let skillsCache = null;
+
+/** Claude Code's own names: letters, digits, dash, underscore, and the colon a
+ *  plugin skill wears (`plugin:skill`). Anything else is not a name we could
+ *  put after a `/` anyway, so it is dropped rather than relayed as garbage. */
+const SKILL_NAME = /^[A-Za-z0-9][A-Za-z0-9_:-]{0,63}$/;
+
+/** Record what a turn's init event reported. Bounded and sorted so the poll's
+ *  query param has a stable length and a stable order — an unstable order would
+ *  make the server write a "change" on every single poll. */
+export function recordSkills(names) {
+  if (!Array.isArray(names)) return;
+  const clean = [...new Set(names.map((n) => String(n).trim()).filter((n) => SKILL_NAME.test(n)))]
+    .sort()
+    .slice(0, 100);
+  // An empty report is a FACT (a machine with no skills installed), so it is
+  // recorded as []. Never conflated with null, which stays "no turn has run".
+  skillsCache = clean;
+}
+
+/** What to send on the roster poll — null until a turn has taught us. */
+export function knownSkills() {
+  return skillsCache;
+}

package/bin/lib/work.mjs

@@ -41,7 +41,7 @@ import {
   WORK_TURN_KICKOFF_PLAIN,
 } from './prompts.mjs';
 import { materializeInto, excludeInWorktree, scrub as envScrub } from './env.mjs';
-import { detectRuntimes, canRun, RUNTIMES } from './runtimes.mjs';
+import { detectRuntimes, canRun, recordSkills, RUNTIMES } from './runtimes.mjs';
 import { isTerminalSessionLive, isAgyConversationLive } from './localSessions.mjs';
 import { worktreeDiff } from './worktreeDiff.mjs';
 import { homedir } from 'node:os';
@@ -1353,6 +1353,12 @@ export function createWorkManager({ repoRoot, baseDir, baseRef, getMcpUrl, getLe
               streamJson: true,
               answerFromResult: true,
               onActivity: (a) => narrator.line(a?.label),
+              // What this CLI says it can be asked for by name. Harvested off
+              // the init event the stream already carries — no probe, no scan,
+              // no extra spawn — and reported on the next roster poll so the
+              // composer can autocomplete a `/`. See runtimes.mjs for why it is
+              // learned from a turn rather than looked up.
+              onInit: (i) => recordSkills(i.skills),
               cwd: dir.wt,
               mcpArgs: mcp.args,
               mcpEnv: mcp.env,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowviant",
-  "version": "0.51.1",
+  "version": "0.52.0",
   "description": "Run your own coding CLIs as build agents for Flowviant \u2014 Claude Code, Codex or Antigravity, on your own credentials. Holds your sessions, keeps a worktree per tab, and ships branches on your word.",
   "type": "module",
   "bin": {