flowviant 0.61.0 → 0.63.0

package/bin/lib/claude.mjs

@@ -236,7 +236,17 @@ function handleStreamLine(line, { cwd, emit, onActivity, appendText, answerFromR
     //
     // 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) });
+    // `sessionId` rides along for one reason: a `-p` turn WRITES a transcript,
+    // and `localSessions.mjs` offers the newest ended session per directory as
+    // ADOPTABLE — so any headless turn we run for our own purposes would leave
+    // a phantom untitled session in the `+` menu. The caller that needs to
+    // clean up after itself cannot do so without this id.
+    if (Array.isArray(ev.skills) || typeof ev.session_id === 'string') {
+      onInit?.({
+        skills: Array.isArray(ev.skills) ? ev.skills.map(String) : undefined,
+        sessionId: typeof ev.session_id === 'string' ? ev.session_id : undefined,
+      });
+    }
   } else if (ev.type === 'result') {
     // The final assistant text (carries WIKI_DONE / REGROUND_DONE).
     if (typeof ev.result === 'string') appendText(ev.result + '\n');

package/bin/lib/devResolve.mjs

@@ -0,0 +1,167 @@
+/**
+ * WHAT STARTS THIS PROJECT — asked of a Claude, on the machine, in the
+ * background.
+ *
+ * WHY THIS EXISTS. Starting a dev server used to require a command a human had
+ * typed into a sheet, prefilled `npm run dev`. That prefill is a guess about
+ * somebody else's stack, and it was called out as one: "the option to run or
+ * start the dev server shouldnt be npm run dev or show it as npm run dev
+ * because thats not agnostic to everyones set up. no need to show that."
+ *
+ * The mechanism is the driver's own: "we are literally asking a claude session
+ * to start it for us" — and, decisively, "i still want claude to start the
+ * server for me but i dont want it to literally open a chat. have it do it in
+ * the background." So this is a headless turn. It reaches no transcript, spends
+ * no tab, and leaves no message anybody has to read.
+ *
+ * IT ANSWERS WITH A STRING AND STARTS NOTHING. The server parses what comes
+ * back, through the same `parseDevCommand` a human's answer goes through, and
+ * hands the machine an ordinary start job on the next poll. That split is the
+ * whole safety story: the policy for what may execute has exactly one
+ * implementation, and it lives in the component this repo can actually upgrade.
+ * A daemon that decided for itself what counted as a legal command would be a
+ * second copy of that policy, free to drift, published, and unrecallable.
+ *
+ * IT MAY INSTALL. That is not a loophole in the install refusal — it is the
+ * refusal's own stated remedy. `parseDevCommand` refuses `npm install` because
+ * a SPAWNED command runs lifecycle scripts from the repo and every transitive
+ * dependency with no agent in the loop; the file says the remedy is "a turn in
+ * the tab: a human asking, an agent doing it". This is exactly that turn, with
+ * the human asking by pressing the button. And it is the case that matters: a
+ * fresh worktree has no `node_modules` (they are gitignored, so they never come
+ * across with the branch), which is precisely the dead end that produced "it
+ * was stuck on 'working', does it really take that long to run dev?"
+ *
+ * IT CLEANS UP AFTER ITSELF. A `-p` turn writes a transcript, and
+ * `localSessions.mjs` offers the newest ended session per directory as
+ * adoptable — left behind, every resolve would drop a phantom untitled session
+ * into the `+` menu.
+ */
+
+import { runTurn } from './claude.mjs';
+import { removeProbeTranscript } from './runtimes.mjs';
+
+/** Long, because an install can sit in front of the answer. The SERVER holds
+ *  the real ceiling (`RESOLVE_TTL_MS`); this is the machine giving up first so
+ *  a wedged child does not hold a slot until then. */
+export const DEV_RESOLVE_TIMEOUT_MS = 10 * 60_000;
+
+/** The sentinel for "I could not tell", so an honest failure is distinguishable
+ *  from a model padding an answer it does not have. */
+export const NO_COMMAND = 'NONE';
+
+/**
+ * The argv0s the server will accept. Named in the prompt NOT as a security
+ * control — the server enforces it either way, and would refuse anything else
+ * with the parser's own words — but because a model that knows the shape of an
+ * acceptable answer gives one, and a refused proposal costs the asker a whole
+ * round trip to learn nothing.
+ */
+const ALLOWED = [
+  'npm', 'pnpm', 'yarn', 'bun', 'node', 'deno', 'go', 'python', 'python3',
+  'make', 'cargo', 'rails', 'php', 'dotnet',
+];
+
+export function resolvePrompt() {
+  return [
+    'Work out the ONE command that starts this project’s development server, and reply with only that command.',
+    '',
+    'How to work it out: read the repo. Check package.json scripts, Makefile, Procfile, docker-compose, pyproject.toml, Cargo.toml, README — whatever this project actually uses. Prefer the script the project itself documents for local development.',
+    '',
+    'You MAY install dependencies first if they are missing (for example a worktree with no node_modules). Do that before answering.',
+    '',
+    'Rules for the answer:',
+    `- It must begin with one of: ${ALLOWED.join(', ')} — or a ./path to a script in this repo.`,
+    '- One line. No shell operators (&&, |, ;, >, $, backticks). If the project needs several steps, name a script in the repo that does them.',
+    '- Not an install command. Install as part of your work above if needed; the answer is the command that RUNS the server.',
+    '- It must not daemonize or background itself. It should stay in the foreground; something else supervises it.',
+    `- If you genuinely cannot tell, reply exactly ${NO_COMMAND}.`,
+    '',
+    'Reply with the command alone — no explanation, no backticks, no prose.',
+  ].join('\n');
+}
+
+/**
+ * Last plausible command line out of whatever the model said.
+ *
+ * DELIBERATELY FORGIVING, because the cost of being wrong is low and asymmetric:
+ * the server parses this and refuses anything outside the policy, naming what
+ * was proposed. Being strict here would turn a model that wrapped its answer in
+ * backticks into a failure the asker cannot act on, having already paid for the
+ * turn.
+ */
+export function pickCommand(text) {
+  const lines = String(text ?? '')
+    .split('\n')
+    .map((l) => l.trim())
+    // Fence markers and bullet/quote decoration, which are formatting rather
+    // than part of anybody's command.
+    .filter((l) => l && !/^```/.test(l))
+    .map((l) => l.replace(/^[-*>\s]+/, '').replace(/^`+|`+$/g, '').trim())
+    .filter(Boolean);
+  if (lines.length === 0) return null;
+  // The LAST such line: a model that explains before complying puts the answer
+  // at the end, and one that complies exactly has only one line anyway.
+  const last = lines[lines.length - 1];
+  if (!last || last === NO_COMMAND) return null;
+  // A sentence is not a command. Cheap shape check so obvious prose becomes
+  // "could not work it out" rather than a refusal quoting a paragraph back.
+  if (last.split(/\s+/).length > 8 || /[.!?]$/.test(last)) return null;
+  return last;
+}
+
+/**
+ * Run the turn. Resolves `{ command }` or `{ error }` — never throws, because
+ * the caller's only job with a failure is to relay it, and an exception at this
+ * boundary would strand the row.
+ */
+export async function resolveDevCommandOnMachine({ cwd, model, log, onActivity }) {
+  let sessionId = null;
+  let timer;
+  try {
+    const out = await Promise.race([
+      runTurn({
+        prompt: resolvePrompt(),
+        cwd,
+        streamJson: true,
+        answerFromResult: true,
+        model,
+        label: 'dev',
+        /**
+         * THE TURN'S OWN HUMANIZED TAIL, forwarded so a browser can watch it.
+         *
+         * This is the only feature in the product where a Claude does work
+         * nobody can see — no transcript, by design — and the driver's answer
+         * to that is the right one: "we could have it stream the output for
+         * transparency on the menu." So the same `read …` / `+ npm install …`
+         * lines a tab relays are forwarded here. It is the CLI's own stdout
+         * humanized, never an inference about it, which is the standing rule
+         * for every activity readout in this product.
+         */
+        onActivity,
+        onInit: (i) => {
+          if (i?.sessionId) sessionId = i.sessionId;
+        },
+      }),
+      new Promise((r) => {
+        timer = setTimeout(() => r(null), DEV_RESOLVE_TIMEOUT_MS);
+        timer.unref?.();
+      }),
+    ]);
+    if (out === null) {
+      return { error: 'your Claude did not finish working out how to start this project in time.' };
+    }
+    const command = pickCommand(out);
+    if (!command) {
+      return { error: 'your Claude could not work out how to start this project.' };
+    }
+    log?.(`dev: resolved start command — ${command}`);
+    return { command };
+  } catch (e) {
+    return { error: `your Claude could not be run here: ${e?.message ?? 'unknown error'}` };
+  } finally {
+    clearTimeout(timer);
+    // After the turn, so the delete does not race a child still writing.
+    if (sessionId) setTimeout(() => removeProbeTranscript(cwd, sessionId), 750).unref?.();
+  }
+}

package/bin/lib/runtimes.mjs

@@ -1054,7 +1054,18 @@ function transcriptCandidates(cwd, sessionId) {
   return out;
 }
 
-function removeProbeTranscript(cwd, sessionId) {
+/**
+ * Delete the transcript a headless `-p` turn left behind.
+ *
+ * EXPORTED because the skills probe is no longer the only thing that runs one:
+ * resolving a project's dev command is a background Claude turn too, and every
+ * such turn has the same footprint. `claude -p` writes
+ * `~/.claude/projects/<munged-cwd>/<id>.jsonl` at startup, and
+ * `localSessions.mjs` offers the newest ENDED session per directory as
+ * ADOPTABLE — so anything we run for our own purposes would put a phantom
+ * untitled session in somebody's `+` menu.
+ */
+export function removeProbeTranscript(cwd, sessionId) {
   if (!sessionId || !/^[A-Za-z0-9_-]{8,64}$/.test(sessionId)) return;
   for (const f of transcriptCandidates(cwd, sessionId)) {
     try {

package/bin/lib/work.mjs

@@ -36,11 +36,13 @@ import {
   USER_AGENT,
   REFRESH_BEFORE_SECONDS,
   DAEMON_INSTANCE,
+  MODEL,
 } from './config.mjs';
 import { git, gitRaw, splitNul, baseBranchName, isSafePathSegment } from './git.mjs';
 import { listenersIn, listenersSupported } from './listeners.mjs';
 import { openTunnel } from './preview.mjs';
 import { startDevServer, reapOrphanDevRuns, killDevRunEntry } from './devServer.mjs';
+import { resolveDevCommandOnMachine } from './devResolve.mjs';
 import { c, note, ok, warn } from './ui.mjs';
 import { mcpFor, runTurn } from './claude.mjs';
 import {
@@ -109,6 +111,8 @@ export function createWorkManager({ repoRoot, baseDir, baseRef, getMcpUrl, getLe
   const PREVIEW_DONE_URL = FLEET_URL.replace(/\/agents\/?$/, '/preview-done');
   const DEV_RUN_CLAIM_URL = FLEET_URL.replace(/\/agents\/?$/, '/dev-run-claim');
   const DEV_RUN_DONE_URL = FLEET_URL.replace(/\/agents\/?$/, '/dev-run-done');
+  const DEV_RUN_RESOLVED_URL = FLEET_URL.replace(/\/agents\/?$/, '/dev-run-resolved');
+  const DEV_RUN_PROGRESS_URL = FLEET_URL.replace(/\/agents\/?$/, '/dev-run-progress');
   const SESSION_COMMANDS_URL = FLEET_URL.replace(/\/agents\/?$/, '/session-commands');
   const ATTACHMENT_URL = FLEET_URL.replace(/\/agents\/?$/, '/attachment');
   const workAnswering = new Set(); // turn ids currently queued/running here
@@ -774,6 +778,89 @@ export function createWorkManager({ repoRoot, baseDir, baseRef, getMcpUrl, getLe
     }
   };
 
+  /**
+   * The answer to a `resolve`, handed up as a STRING for the server to parse.
+   *
+   * Never argv: `parseDevCommand` is the single owner of what may execute, and
+   * a second implementation of that policy inside the one component a deploy
+   * cannot upgrade is exactly the drift this product keeps closing.
+   */
+  /**
+   * THE RESOLVE TURN'S OUTPUT, streamed while it happens.
+   *
+   * A headless turn is the one place in this product where a Claude works and
+   * nobody can see it — deliberately, since it must not reach the transcript —
+   * and the answer to that is transparency rather than a promise: "we could
+   * have it stream the output for transparency on the menu."
+   *
+   * THROTTLED, and the tail is BOUNDED at the machine. This is a per-line hook
+   * on a turn that may run for minutes; posting each line would be hundreds of
+   * requests, and sending the whole transcript would grow without limit. Same
+   * shape as the session activity relay, for the same reasons.
+   */
+  const devProgress = new Map(); // sessionId → { lines, at, timer }
+  const DEV_PROGRESS_MS = 2_000;
+  const DEV_PROGRESS_LINES = 40;
+
+  const flushDevProgress = async (sessionId) => {
+    const st = devProgress.get(sessionId);
+    if (!st || !st.lines.length) return;
+    st.at = Date.now();
+    const logTail = st.lines.join('\n').slice(-4000);
+    try {
+      await fetch(DEV_RUN_PROGRESS_URL, {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${FLEET_TOKEN}`,
+          'User-Agent': USER_AGENT,
+          'Content-Type': 'application/json',
+        },
+        signal: AbortSignal.timeout(15_000),
+        body: JSON.stringify({ sessionId, instance: DAEMON_INSTANCE, logTail }),
+      });
+    } catch {
+      /* progress is best-effort — the row's own state is the truth */
+    }
+  };
+
+  const noteDevProgress = (sessionId, label) => {
+    if (!label) return;
+    const st = devProgress.get(sessionId) ?? { lines: [], at: 0, timer: null };
+    st.lines.push(String(label).slice(0, 300));
+    if (st.lines.length > DEV_PROGRESS_LINES) st.lines.splice(0, st.lines.length - DEV_PROGRESS_LINES);
+    devProgress.set(sessionId, st);
+    // Leading-edge post, then a trailing one — so the FIRST line appears at
+    // once (an empty panel for two seconds reads as nothing happening) and the
+    // last line is never left unsent.
+    if (Date.now() - st.at > DEV_PROGRESS_MS) {
+      void flushDevProgress(sessionId);
+      return;
+    }
+    if (st.timer) return;
+    st.timer = setTimeout(() => {
+      st.timer = null;
+      void flushDevProgress(sessionId);
+    }, DEV_PROGRESS_MS);
+    st.timer.unref?.();
+  };
+
+  const postDevResolved = async (body) => {
+    try {
+      await fetch(DEV_RUN_RESOLVED_URL, {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${FLEET_TOKEN}`,
+          'User-Agent': USER_AGENT,
+          'Content-Type': 'application/json',
+        },
+        signal: AbortSignal.timeout(30_000),
+        body: JSON.stringify({ ...body, instance: DAEMON_INSTANCE }),
+      });
+    } catch {
+      /* the row's own TTL is the backstop */
+    }
+  };
+
   const stopDevRun = async (sessionId, reason) => {
     const live = liveDevRuns.get(sessionId);
     liveDevRuns.delete(sessionId);
@@ -798,6 +885,69 @@ export function createWorkManager({ repoRoot, baseDir, baseRef, getMcpUrl, getLe
         continue;
       }
 
+      /**
+       * RESOLVE — ask a Claude what starts this project, and say so. Starts
+       * NOTHING.
+       *
+       * It exists because the sheet used to open with a text field prefilled
+       * `npm run dev`, which presumes a stack. The turn is headless and reaches
+       * no transcript: "i still want claude to start the server for me but i
+       * dont want it to literally open a chat. have it do it in the
+       * background."
+       *
+       * IT TAKES THE PLACE LOCK, through the same `chainFor` every turn goes
+       * through, and that is deliberate rather than incidental. The turn reads
+       * the repo and may `npm install` into this worktree; running it beside a
+       * tab turn editing the same directory is the exact collision the chain
+       * exists to prevent. The cost is that a resolve makes the tab wait, which
+       * is honest — you cannot usefully build while an install is running
+       * anyway — and it is bounded, because this turn ENDS. That is the whole
+       * reason it answers with a command instead of running one: a foreground
+       * `npm run dev` would never return, and the lock would be held for as
+       * long as the server lived.
+       */
+      if (job?.action === 'resolve') {
+        if (liveDevRuns.has(sessionId)) continue;
+        if (devRunClaiming.has(sessionId)) continue;
+        devRunClaiming.add(sessionId);
+        void (async () => {
+          try {
+            if (!(await claimDevRun(sessionId))) return; // somebody else has it
+            const wt = placeDir(sessionId);
+            const out = await chainFor(placeOf(sessionId), () =>
+              resolveDevCommandOnMachine({
+                cwd: wt,
+                // The machine's own pin, exactly as a tab turn gets — never
+                // the user's global default, which for Claude may be a
+                // long-context tier their subscription cannot bill autonomous
+                // work on. This turn is autonomous by definition.
+                model: MODEL,
+                log: (m) => note(`${sessionId.slice(0, 8)}: ${m}`),
+              })
+            );
+            // The last lines, before the row leaves the resolving state.
+            await flushDevProgress(sessionId);
+            await postDevResolved({
+              sessionId,
+              command: out?.command ?? null,
+              error: out?.error ?? null,
+            });
+          } catch (e) {
+            await postDevResolved({
+              sessionId,
+              command: null,
+              error: `the machine could not run that turn: ${e?.message ?? 'unknown error'}`,
+            });
+          } finally {
+            const st = devProgress.get(sessionId);
+            if (st?.timer) clearTimeout(st.timer);
+            devProgress.delete(sessionId);
+            devRunClaiming.delete(sessionId);
+          }
+        })();
+        continue;
+      }
+
       // RE-VALIDATE THE SHAPE at this boundary. The server parsed the string
       // and owns the policy; the machine owns the refusal to execute something
       // malformed, because one place doing a check is one deploy away from

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowviant",
-  "version": "0.61.0",
+  "version": "0.63.0",
   "description": "Run your own coding CLIs as build agents for Flowviant — 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": {