flowviant 0.6.1 → 0.8.0

package/README.md

@@ -38,14 +38,16 @@ Prefer an explicit token? Create a fleet credential in the app and pass it direc
 FLOWVIANT_FLEET=fva_… npx flowviant
 ```
 
-## Live mode (opt-in)
+## Live mode (the default)
+
+Each task runs a **persistent** Claude session you can talk to mid-task from the app: the agent streams its work into the task's conversation, you `@`-mention it to steer or answer questions, and it resumes in place. Blockers park the session at zero cost until you answer. When it finishes, it posts a delivery card (summary + checklist self-report) in the thread — a human confirms done by merging there.
+
+Prefer the legacy one-shot poll mode (no streaming, no previews)? Escape hatch:
 
 ```bash
-FLOWVIANT_LIVE=1 npx flowviant
+FLOWVIANT_POLL=1 npx flowviant
 ```
 
-Each task runs a **persistent** Claude session you can talk to mid-task from the app: the agent streams its work into the task's conversation, you `@`-mention it to steer or answer questions, and it resumes in place. Blockers park the session at zero cost until you answer.
-
 ### Live previews
 
 For UI/API tasks, the daemon can start the branch's dev server in the agent's worktree and open a [cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) quick tunnel so you can drive the real running change during review — no Cloudflare account needed (it's auto-fetched if missing). Configure it once per repo, or let it infer common setups:

package/bin/lib/claude.mjs

@@ -25,13 +25,14 @@ Operate this loop:
 3. If you hit ANYTHING only a human can decide, call report_blocker with a clear
    question (and options when you can), then call get_blocker_resolution. If it is
    not yet resolved, output exactly BLOCKED:<blockerId> on its own line and STOP.
-4. Before finishing: for EACH acceptance criterion, call attach_evidence with concrete
-   proof it is met. This is what the human reviews instead of the diff.
-5. Ship: on a revision, \`git push\` to the SAME existing branch (the PR updates in place)
+4. Ship: on a revision, \`git push\` to the SAME existing branch (the PR updates in place)
    and re-call attach_pr with that PR URL; otherwise open ONE draft PR (git push +
-   \`gh pr create --draft\`) and call attach_pr. Then complete. NEVER merge — the human
-   approves the PR in Flowviant.
-6. Return to step 1.
+   \`gh pr create --draft\`) and call attach_pr. Then call complete with a plain-language
+   summary of what you built AND a criteria self-report (index into the brief's
+   "done when" list + met true/false + a short note) — that becomes your delivery
+   card in the task thread. NEVER merge — a human confirms done in the thread and
+   the merge runs separately.
+5. Return to step 1.
 
 Keep every change scoped to the claimed intent. If a tool errors, report_progress with
 the error, then retry or report_blocker.`;
@@ -53,12 +54,12 @@ Do EXACTLY ONE task this turn:
 3. If you hit ANYTHING only a human can decide, call report_blocker (with options when
    you can), then get_blocker_resolution. If unresolved, output exactly
    BLOCKED:<blockerId> on its own line and STOP. Do NOT guess past a real decision.
-4. Before finishing: for EACH acceptance criterion call attach_evidence with concrete
-   proof it is met.
-5. Ship: if this is a revision, \`git push\` to the SAME existing branch (the open PR
+4. Ship: if this is a revision, \`git push\` to the SAME existing branch (the open PR
    updates in place) and re-call attach_pr with that same PR URL. Otherwise open ONE
-   draft PR (git push + \`gh pr create --draft\`) and call attach_pr. Then complete.
-   NEVER merge. Then output exactly DONE on its own line and stop.
+   draft PR (git push + \`gh pr create --draft\`) and call attach_pr. Then call complete
+   with a plain-language summary AND a criteria self-report (index into the brief's
+   "done when" list + met true/false + a short note) — your delivery card in the task
+   thread. NEVER merge. Then output exactly DONE on its own line and stop.
 
 Do NOT claim a second intent — exactly one per turn. Keep every change scoped to the
 claimed intent. If a tool errors, report_progress with the error, then retry or

package/bin/lib/config.mjs

@@ -4,7 +4,7 @@ import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
 
-export const VERSION = '0.6.1';
+export const VERSION = '0.8.0';
 
 // Credential stored by `flowviant login` (device auth) — the no-token,
 // no-env-var path. An explicit --fleet flag or FLOWVIANT_FLEET env still wins.
@@ -35,10 +35,12 @@ export const RECONCILE_SECONDS = Number(process.env.RECONCILE_SECONDS || 10);
 // so a long-lived daemon never silently 401s on an expired token.
 export const REFRESH_BEFORE_SECONDS = Number(process.env.REFRESH_BEFORE_SECONDS || 3600);
 export const SAFE = process.env.FLOWVIANT_SAFE === '1';
-// Opt-in phase-2 live mode: persistent Agent-SDK session per task (streams into
-// the task channel, injectable, blocker-parks in place) instead of one-shot
-// `claude -p` turns. Off = the proven poll/sentinel path, untouched.
-export const LIVE = process.env.FLOWVIANT_LIVE === '1';
+// Live mode (DEFAULT since 0.8.0): persistent Agent-SDK session per task —
+// streams into the task channel, injectable mid-task, blocker-parks in place,
+// delivery card on complete, branch preview tunnels. The legacy poll/sentinel
+// path (one-shot `claude -p` turns) survives behind FLOWVIANT_POLL=1 as the
+// escape hatch; FLOWVIANT_LIVE=1 is still honored for old scripts.
+export const LIVE = process.env.FLOWVIANT_POLL !== '1';
 // Sent on the daemon's own HTTP calls so Cloudflare Bot Fight Mode doesn't 403
 // them (Node's default UA is treated as a bot). Claude Code sends its own UA.
 export const USER_AGENT = `flowviant/${VERSION}`;

package/bin/lib/fleet.mjs

@@ -128,8 +128,11 @@ async function runFleetWorker({ agentId, label, cwd, baseRef, getToken, getHasWo
     // don't fake a blocker or a completion.
     enter('reconnect', warn, `${c.yellow('no result')}${c.dim(' — refreshing token, retrying')}`);
     onTokenSuspect?.(agentId);
-    resuming = false;
-    needsReset = true;
+    // A no-sentinel turn while RESUMING a blocked task is a transient MCP/token
+    // failure, not completion — retry in place and KEEP the worktree. Resetting
+    // here would wipe the blocked task's uncommitted changes. Only a fresh-task
+    // turn (not resuming) warrants a clean slate next time.
+    if (!resuming) needsReset = true;
     await sleep(IDLE_SECONDS);
   }
   info(`${label} stopped`);
@@ -186,17 +189,19 @@ export async function runFleetDaemon() {
   // Merge jobs (Flowvy-commanded): approved PRs to squash-merge to main on the
   // user's own gh. `merging` guards against re-processing a job mid-flight.
   const MERGE_DONE_URL = FLEET_URL.replace(/\/agents\/?$/, '/merge-done');
+  const MERGE_FAILED_URL = FLEET_URL.replace(/\/agents\/?$/, '/merge-failed');
   const merging = new Set();
-  const reportMerged = async (intentId) => {
+  const mergeAttempts = new Map(); // job.id -> transient-failure count
+  const reportMergeOutcome = async (url, body) => {
     try {
-      await fetch(MERGE_DONE_URL, {
+      await fetch(url, {
         method: 'POST',
         headers: {
           Authorization: `Bearer ${FLEET_TOKEN}`,
           'User-Agent': USER_AGENT,
           'Content-Type': 'application/json',
         },
-        body: JSON.stringify({ intentId }),
+        body: JSON.stringify(body),
       });
     } catch {
       /* best-effort — the job reappears next poll if this failed */
@@ -210,6 +215,7 @@ export async function runFleetDaemon() {
         try {
           note(`${c.cyan('merge')} ${c.dim(`— ${job.title}`)}`);
           let merged = false;
+          let failedReason = null; // permanent — tell the thread, clear the flag
           try {
             execFileSync('gh', ['pr', 'merge', job.prUrl, '--squash', '--delete-branch'], {
               cwd: repoRoot,
@@ -218,14 +224,33 @@ export async function runFleetDaemon() {
             merged = true;
           } catch (e) {
             const err = e.stderr?.toString?.() || e.message || '';
+            const line = err.split('\n')[0] || 'gh pr merge failed';
             if (/already merged|not open|closed/i.test(err)) merged = true;
-            else if (/conflict|not mergeable|CONFLICTING/i.test(err))
-              warn(`"${job.title}" has a merge conflict — rebase the branch, then it'll merge.`);
-            else warn(`merge failed for "${job.title}": ${err.split('\n')[0]} — will retry`);
+            else if (/conflict|not mergeable|CONFLICTING/i.test(err)) {
+              // Permanent until a human/agent acts — don't spin on it.
+              failedReason = `merge conflict with ${baseRef} — the branch needs a rebase`;
+            } else {
+              // Transient (auth hiccup, network, CI requirement): retry a few
+              // polls, then surface it instead of silently looping forever.
+              const n = (mergeAttempts.get(job.id) ?? 0) + 1;
+              mergeAttempts.set(job.id, n);
+              if (n >= 3) failedReason = line;
+              else warn(`merge failed for "${job.title}": ${line} — will retry`);
+            }
           }
           if (merged) {
-            await reportMerged(job.id);
+            mergeAttempts.delete(job.id);
+            await reportMergeOutcome(MERGE_DONE_URL, { intentId: job.id });
             ok(`${c.cyan('merged')} ${c.dim(`— ${job.title} → ${baseRef}`)}`);
+          } else if (failedReason) {
+            // Report into the thread (server narrates + re-arms the merge
+            // button + notifies) — the job disappears from the roster.
+            mergeAttempts.delete(job.id);
+            await reportMergeOutcome(MERGE_FAILED_URL, {
+              intentId: job.id,
+              message: failedReason,
+            });
+            warn(`merge failed for "${job.title}": ${failedReason} — reported to the thread`);
           }
         } finally {
           merging.delete(job.id);
@@ -234,6 +259,56 @@ export async function runFleetDaemon() {
     }
   };
 
+  // Cleanup jobs (task restarts): close the abandoned PR + delete its remote
+  // branch on the user's own gh, so a restart doesn't litter the repo.
+  const CLEANUP_DONE_URL = FLEET_URL.replace(/\/agents\/?$/, '/cleanup-done');
+  const cleaning = new Set();
+  const processCleanupJobs = (jobs) => {
+    for (const job of jobs ?? []) {
+      if (cleaning.has(job.id)) continue;
+      cleaning.add(job.id);
+      (async () => {
+        try {
+          note(`${c.cyan('cleanup')} ${c.dim(`— ${job.title} (restarted)`)}`);
+          if (job.prUrl) {
+            try {
+              execFileSync(
+                'gh',
+                [
+                  'pr',
+                  'close',
+                  job.prUrl,
+                  '--comment',
+                  'Task restarted in Flowviant — this attempt was discarded.',
+                  '--delete-branch',
+                ],
+                { cwd: repoRoot, stdio: ['ignore', 'pipe', 'pipe'] }
+              );
+            } catch (e) {
+              // Already closed/merged/missing = fine; anything else we still
+              // report done — a restart must never wedge on stale remotes.
+              const err = e.stderr?.toString?.() || e.message || '';
+              warn(`cleanup for "${job.title}": ${err.split('\n')[0] || 'gh pr close failed'}`);
+            }
+          } else if (job.branch) {
+            try {
+              execFileSync('git', ['push', 'origin', '--delete', job.branch], {
+                cwd: repoRoot,
+                stdio: ['ignore', 'pipe', 'pipe'],
+              });
+            } catch {
+              /* branch already gone — fine */
+            }
+          }
+          await reportMergeOutcome(CLEANUP_DONE_URL, { intentId: job.id });
+          ok(`${c.cyan('cleaned')} ${c.dim(`— ${job.title}`)}`);
+        } finally {
+          cleaning.delete(job.id);
+        }
+      })();
+    }
+  };
+
   let connected = false; // log the first successful poll once
   let rosterSig = null; // last roster membership, to log changes only
   let idleBeatAt = 0; // throttle the "still alive" idle heartbeat
@@ -273,6 +348,7 @@ export async function runFleetDaemon() {
     if (roster.mcpUrl) mcpUrl = roster.mcpUrl;
     if (roster.leaseTtlSeconds) leaseTtlSeconds = roster.leaseTtlSeconds;
     processMergeJobs(roster.mergeJobs);
+    processCleanupJobs(roster.cleanupJobs);
     const rosterIds = new Set(roster.agents.map((a) => a.agentId));
 
     // Announce roster size only when it changes (not every poll).

package/bin/lib/live.mjs

@@ -1,5 +1,5 @@
 /**
- * Live mode (phase 2, opt-in via FLOWVIANT_LIVE=1). Instead of one-shot
+ * Live mode (the DEFAULT since 0.8.0; FLOWVIANT_POLL=1 = legacy path). Instead of one-shot
  * `claude -p` turns + sentinels, each task runs a PERSISTENT Agent-SDK session:
  * the daemon claims, seeds the session with the brief, mirrors the model's
  * streamed reply into the task channel (stream_turn), injects human @-messages
@@ -78,12 +78,15 @@ answered…" or teammate line as a new instruction and adapt. There is NO termin
 and NO interactive prompt — your only channel to a human is the flowviant MCP
 tools. When you hit a decision only a human can make, call report_blocker (with
 options when you can) and then STOP your turn — do not spin or guess; you will be
-resumed with the answer. When the work is done: call attach_evidence for EACH
-acceptance criterion (this is the floor the human reviews against); open ONE draft
-PR (git push + gh pr create --draft), call attach_pr, then call complete. A live
-preview of your branch is started for you automatically for the review — you do
-NOT need to open a tunnel or register a live target. NEVER merge — the human
-reviews and merging is handled separately.`;
+resumed with the answer. When the work is done: open ONE draft PR (git push +
+gh pr create --draft), call attach_pr, then call complete with a plain-language
+summary of what you built AND a criteria self-report (index into the brief's
+"done when" list + met true/false + a short note per item). That summary +
+self-report becomes your DELIVERY CARD in the task thread — it's what the team
+reads to confirm done, so write it for them, not for a log. A live preview of
+your branch is started for you automatically — you do NOT need to open a tunnel
+or register a live target. NEVER merge — a human confirms done in the thread
+(the merge card) and the merge runs separately.`;
 
 function seedPrompt(runId, brief, transcript) {
   return [
@@ -98,7 +101,7 @@ function seedPrompt(runId, brief, transcript) {
       ? [``, `Conversation so far (you may be resuming — pick up where this left off):`, transcript]
       : []),
     ``,
-    `${transcript ? 'Continue' : 'Begin'}. Post a short plan first, then: report_progress as you go; report_blocker + stop if you hit a human decision; attach_evidence, open a draft PR, attach_pr, then complete when done.`,
+    `${transcript ? 'Continue' : 'Begin'}. Post a short plan first, then: report_progress as you go; report_blocker + stop if you hit a human decision; open a draft PR, attach_pr, then complete (summary + criteria self-report — your delivery card) when done.`,
   ].join('\n');
 }
 
@@ -216,22 +219,26 @@ async function waitForMessage(mcpUrl, token, runId, afterId, isAlive) {
 
 // One task: claim → seed → stream/mirror/inject/park → complete. Returns
 // { outcome: 'nothing' | 'done' | 'blocked' | 'stalled' | 'error' }.
-export async function runLiveTask({ mcpUrl, token, cwd, baseRef, isAlive }) {
+export async function runLiveTask({ mcpUrl, token, cwd, baseRef, isAlive, resumeIntentId, onChild }) {
   const claim = await mcpCall(mcpUrl, token, 'claim_next_intent', {}).catch(() => null);
   if (!claim || claim.claimed !== true) return { outcome: 'nothing' };
   const { runId, intentId } = claim;
   const brief = claim.brief ?? {};
   const title = brief.title ?? 'a task';
+  // Re-claiming the SAME intent this worker was just working (parked on a blocker,
+  // now resuming) — its worktree holds hours of uncommitted work. Do NOT reset.
+  const resuming = !!resumeIntentId && intentId === resumeIntentId;
 
-  // Revision resumes its PR branch; otherwise a clean base checkout.
+  // Revision resumes its PR branch; a genuinely fresh task gets a clean base
+  // checkout; a resume keeps its dirty worktree untouched.
   if (brief.branch) {
     try {
       git(['fetch', 'origin', '--quiet'], cwd);
       git(['checkout', brief.branch], cwd);
     } catch {
-      resetWorktree(cwd, baseRef);
+      if (!resuming) resetWorktree(cwd, baseRef);
     }
-  } else {
+  } else if (!resuming) {
     resetWorktree(cwd, baseRef);
   }
 
@@ -267,6 +274,25 @@ export async function runLiveTask({ mcpUrl, token, cwd, baseRef, isAlive }) {
     },
   });
 
+  // Mark this worker BUSY for the daemon's reconcile loop: buildHave keeps the
+  // worker's token while a session is live (never rotate a credential out from
+  // under it), and teardown/agent-removal can interrupt the SDK session via this
+  // marker's kill(). Cleared in finally. Mirrors poll mode's onChild(child).
+  onChild?.({
+    kill: () => {
+      try {
+        session.interrupt?.();
+      } catch {
+        /* already ending */
+      }
+      try {
+        session.return?.();
+      } catch {
+        /* already closed */
+      }
+    },
+  });
+
   let turnId = null;
   let turnText = '';
   let turnAt = null;
@@ -342,6 +368,11 @@ export async function runLiveTask({ mcpUrl, token, cwd, baseRef, isAlive }) {
           runId,
           ...(afterId ? { afterId } : {}),
         }).catch(() => null);
+        // Torn down out from under us (restart / reassign in Flowviant): the
+        // server killed this run — abandon the session, don't keep building.
+        if (poll && poll.ok === false && poll.reason === 'run_not_active') {
+          return { outcome: 'torn_down', title, intentId };
+        }
         const fresh = (poll?.messages ?? []).filter((x) => x.role === 'user');
 
         if (fresh.some((f) => STOP_RE.test(f.content))) {
@@ -380,6 +411,7 @@ export async function runLiveTask({ mcpUrl, token, cwd, baseRef, isAlive }) {
   } catch (e) {
     return { outcome: 'error', error: e?.message ?? String(e), title, intentId };
   } finally {
+    onChild?.(null); // no longer busy — token may rotate between tasks
     input.close();
     try {
       await session.interrupt?.();
@@ -406,7 +438,12 @@ export async function runLiveWorker({
   getMcpUrl,
   isAlive,
   onTokenSuspect,
+  onChild,
 }) {
+  // The intent this worker is holding across iterations. When a task parks on a
+  // blocker its worktree keeps uncommitted work; on the resume claim we must NOT
+  // reset it. Cleared once the task finishes or the worker goes idle.
+  let lastIntentId = null;
   let phase = '';
   const enter = (p, fn, msg) => {
     if (phase !== p) {
@@ -462,13 +499,28 @@ export async function runLiveWorker({
     }
     let res;
     try {
-      res = await runLiveTask({ mcpUrl: getMcpUrl() ?? MCP_URL, token, cwd, baseRef, isAlive });
+      res = await runLiveTask({
+        mcpUrl: getMcpUrl() ?? MCP_URL,
+        token,
+        cwd,
+        baseRef,
+        isAlive,
+        resumeIntentId: lastIntentId,
+        onChild,
+      });
     } catch (e) {
       enter('error', warn, `${c.yellow('error')} ${c.dim(`— ${e?.message ?? e}`)}`);
       await sleep(IDLE_SECONDS);
       continue;
     }
     if (!isAlive()) break;
+    // Keep the held intent only while a task is genuinely in flight (parked /
+    // stalled / errored → same worktree resumes). Finishing or finding no work
+    // clears it so the next fresh task starts from a clean base.
+    lastIntentId =
+      res.outcome === 'parked' || res.outcome === 'stalled' || res.outcome === 'error'
+        ? res.intentId
+        : null;
     if (res.outcome === 'nothing') {
       enter('idle', info, 'idle — no work assigned');
       await sleep(IDLE_SECONDS);
@@ -480,6 +532,13 @@ export async function runLiveWorker({
       await startReviewPreview(res.intentId);
       continue;
     }
+    if (res.outcome === 'torn_down') {
+      // The human restarted/reassigned the task in Flowviant. Drop everything —
+      // the next fresh claim resets the worktree to base.
+      info(`${label} ${c.dim(`"${res.title}" was restarted/reassigned — abandoned this attempt`)}`);
+      phase = '';
+      continue;
+    }
     if (res.outcome === 'parked') {
       // Idle-parked too long on a blocker: we freed the Claude process. The intent
       // stays claimed; a later poll re-claims + resumes (with transcript) once the

package/bin/lib/preview.mjs

@@ -137,14 +137,36 @@ export async function startPreview({ worktree, kind, cmd, port, log, timeoutMs =
   const cf = await ensureCloudflared(log);
   if (!cf) return null; // fall back to captured evidence
   return new Promise((resolve) => {
-    const server = spawn(cmd, { cwd: worktree, shell: true, stdio: ['ignore', 'ignore', 'ignore'] });
+    // detached so each gets its own process group — `bun run dev` via a shell
+    // spawns a grandchild dev server that would otherwise SURVIVE a kill of the
+    // shell, keep port bound, and get silently re-fronted by the NEXT task's
+    // tunnel (reviewer sees the wrong branch). We kill the whole group instead.
+    const server = spawn(cmd, {
+      cwd: worktree,
+      shell: true,
+      detached: true,
+      stdio: ['ignore', 'ignore', 'ignore'],
+    });
     const tunnel = spawn(cf, ['tunnel', '--url', `http://localhost:${port}`], {
+      detached: true,
       stdio: ['ignore', 'pipe', 'pipe'],
     });
     let settled = false;
+    const killGroup = (child) => {
+      if (!child.pid) return;
+      try {
+        process.kill(-child.pid, 'SIGKILL'); // negative pid = the whole group
+      } catch {
+        try {
+          child.kill('SIGKILL');
+        } catch {
+          /* gone */
+        }
+      }
+    };
     const stop = () => {
-      try { server.kill('SIGKILL'); } catch { /* gone */ }
-      try { tunnel.kill('SIGKILL'); } catch { /* gone */ }
+      killGroup(server);
+      killGroup(tunnel);
     };
     const finish = (val) => {
       if (settled) return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowviant",
-  "version": "0.6.1",
+  "version": "0.8.0",
   "description": "Run your own Claude Code as headless build agents for Flowviant — on your own credentials. Claims dispatched work, opens PRs, captures review evidence, and routes questions back to you.",
   "type": "module",
   "bin": {