thinkpool-pair 0.7.96 → 0.7.98

package/bridge.mjs

@@ -32,13 +32,15 @@ import os from 'node:os'
 import fs from 'node:fs'
 import path from 'node:path'
 import readline from 'node:readline'
-import { spawn, execSync } from 'node:child_process'
+import { spawn, execSync, execFileSync } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
 import { randomUUID } from 'node:crypto'
 import { createClient } from '@supabase/supabase-js'
 import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk'
 import { z } from 'zod'
 import { startClaudeSession } from './claude-session.mjs'
+import { FLOW_CONDUCTOR_PROMPT, FLOW_LANE_PROMPT, buildConductorEnv } from './flow-conductor.mjs'
+import { createFlowWorktree } from './flow-worktree.mjs'
 import { formatPeek, PEEK, siblingsOf, resolveSibling, crossPostDecision, CROSSPOST, spawnDecision, CROSSROOM, formatPairRoster, crossRoomPostDecision } from './cross-terminal.mjs'
 import { turnInFlight } from './update-gate.mjs'
 import { saveSession, flushSession, deleteSession, loadAll, canResume, loadPtyId, savePtyId, loadNames, saveNames, appendDurableEvents, seedDurableEvents, readDurablePage, readDurableOldestSeq } from './session-store.mjs'
@@ -454,6 +456,15 @@ const channel = supabase.channel(`tpcode:${room}`, {
   config: { broadcast: { self: false }, presence: { key: `bridge:${name}` } },
 })
 
+// Thinkpool Flow rides its OWN topic, separate from the room's primary tpcode channel.
+// The web's useFlow hook is a child of CodeRoom, so its effect runs before the room's —
+// sharing tpcode meant useFlow created/owned/removed the room's channel and killed
+// realtime on room open (the 2026-06-30 snag). A dedicated topic keeps the two lifecycles
+// from colliding. The bridge is a separate client, so a second channel here is free.
+const flowChannel = supabase.channel(`tpflow:${room}`, {
+  config: { broadcast: { self: false } },
+})
+
 // ── terminal registry ──────────────────────────────────────────────
 // id → { term (pty), cmd, attached, scrollback, buf }
 const terms = new Map()
@@ -523,14 +534,14 @@ const defendFrame = (event, payload) => {
   return p
 }
 
-const bcast = (event, payload) => {
+const bcast = (event, payload, ch = channel) => {
   if (event === 'pty-out' || event === 'code-event') lastActivity = Date.now()
   payload = defendFrame(event, payload)
   try {
-    if (channel.channelAdapter?.canPush?.() ?? true) {
-      channel.send({ type: 'broadcast', event, payload })
+    if (ch.channelAdapter?.canPush?.() ?? true) {
+      ch.send({ type: 'broadcast', event, payload })
     } else {
-      channel.httpSend(event, payload).catch(() => { /* offline — replay covers it */ })
+      ch.httpSend(event, payload).catch(() => { /* offline — replay covers it */ })
     }
   } catch { /* noop */ }
 }
@@ -1015,12 +1026,12 @@ function restoredTurnOpen(log) {
 // relay STRUCTURED events. onEvent → broadcast `code-event` + print locally +
 // persist to the host file; tool calls round-trip through the perm card; the
 // rolling log replays to joiners and survives bridge restarts (session-store).
-function openStructured({ id, model, resume, log, commands, mode, spawnedBy }) {
+function openStructured({ id, model, resume, log, commands, mode, spawnedBy, rolePrompt, flowSessionId, flowTaskKey, cwd }) {
   if (sessions.has(id)) return
   // spawnedBy: set when this lane was Dispatched (spawn_terminal). Restored from the
   // session store so the Ensemble flag survives a bridge restart (else a respin
   // stripped it and the lane reverted to a plain tab — the t6 "no chip" bug).
-  const entry = { cmd: 'claude', kind: 'structured', log: Array.isArray(log) ? log.slice(-STRUCTURED_LOG_MAX) : [], pending: new Map(), session: null, recovered: false, commands: Array.isArray(commands) ? commands : undefined, mode, spawnedBy: spawnedBy || undefined }
+  const entry = { cmd: 'claude', kind: 'structured', log: Array.isArray(log) ? log.slice(-STRUCTURED_LOG_MAX) : [], pending: new Map(), session: null, recovered: false, commands: Array.isArray(commands) ? commands : undefined, mode, spawnedBy: spawnedBy || undefined, flowSessionId: flowSessionId || null, flowTaskKey: flowTaskKey || null, cwd: cwd || null }
   // C1 (RT-2): per-term contiguous seq counter. Seeded from the restored log's max
   // so a bridge restart resumes ABOVE every persisted seq — fresh events never reuse
   // an old seq, which is what keeps the between-turns restart dup-free (see
@@ -1280,10 +1291,28 @@ function openStructured({ id, model, resume, log, commands, mode, spawnedBy }) {
           return okText(`Closed agent lane ${target.ref}${target.name ? ` ("${target.name}")` : ''}.`)
         },
       ),
+      // Flow lane → mark this slice done (lane-done return path). Reads the lane's
+      // worktree HEAD as commit_sha (the atomic-revert target) + broadcasts
+      // flow-task-done → the room flips the task done + dispatches the next wave
+      // (slices whose deps just got satisfied).
+      tool(
+        'mark_flow_done',
+        "ThinkPool Flow ONLY — call this ONCE when your slice is built, RUNS, and meets its acceptance criteria. Records your latest commit as the slice's atomic-revert target and signals the room that this slice is done (which unblocks slices that depended on you). No arguments: your commit is read from your worktree. Do not call before your slice actually runs + meets acceptance.",
+        {},
+        async () => {
+          const okText = (t) => ({ content: [{ type: 'text', text: t }] })
+          if (!entry.flowSessionId || !entry.flowTaskKey) return okText('Not a Flow lane — nothing to mark done.')
+          let commitSha = null
+          try { commitSha = execFileSync('git', ['-C', entry.cwd || process.cwd(), 'rev-parse', 'HEAD'], { encoding: 'utf8' }).trim() } catch { /* no commits yet */ }
+          bcast('flow-task-done', { term: id, flowId: entry.flowSessionId, taskKey: entry.flowTaskKey, laneId: id, commitSha }, flowChannel)
+          process.stderr.write(`\n  ${A.cyan}◆ flow slice done — ${entry.flowTaskKey} (${commitSha ? commitSha.slice(0, 8) : 'no commit'})${A.rst}\n`)
+          return okText(`Slice "${entry.flowTaskKey}" marked done${commitSha ? ` (commit ${commitSha.slice(0, 8)})` : ' (no commit yet — commit, then re-call)'}. The room records it + dispatches any slices that depended on you.`)
+        },
+      ),
     ],
   })
   entry.session = startClaudeSession({
-    cwd: process.cwd(), model, resume, mode,
+    cwd: cwd || process.cwd(), model, resume, mode, rolePrompt,
     mcpServers: { thinkpool: peekServer },
     // Tier C precheck — the PreToolUse gate calls this BEFORE raising a card, so a
     // disabled/looping/over-cap post never bothers a person. Closes over `entry`.
@@ -1291,7 +1320,7 @@ function openStructured({ id, model, resume, log, commands, mode, spawnedBy }) {
     // Tier 3 — the SENDER-side gate for post_to_session (the receipt card lives in
     // the target room). roomHop/crossRoomPostCount reset on a real human turn (code-turn).
     crossRoomPostGate: () => crossRoomPostDecision({ roomHop: entry.roomHop || 0, postCount: entry.crossRoomPostCount || 0, disabled: process.env.TP_PAIRBUS_OFF === '1' }),
-    env: { ...process.env, TP_MOCKUP_OUTBOX: mockupOutbox },
+    env: { ...process.env, ...buildConductorEnv({ flowSessionId, mode }), TP_MOCKUP_OUTBOX: mockupOutbox },
     onEvent: (evt) => {
       // Self-heal a stale resume — the saved SDK session expired. Reopen fresh,
       // keeping the transcript (scrollback survives; live context is gone).
@@ -1349,6 +1378,16 @@ function openStructured({ id, model, resume, log, commands, mode, spawnedBy }) {
       emitTail(evt)
     },
     requestPermission: (req) => new Promise((resolve) => {
+      // FLOW conductor plan → intercept (no generic card). The plan JSON rides
+      // ExitPlanMode's `plan` arg. Broadcast to the room; its useFlow persists the
+      // task-graph + flips status → awaiting_approval → FlowPlanCard renders. Park
+      // the conductor ('keep' = stay in plan mode, idle; lane dispatch is Step 2).
+      if (entry.flowSessionId && req.risk === 'plan') {
+        bcast('flow-plan', { term: id, flowId: entry.flowSessionId, plan: req.plan || '' }, flowChannel)
+        process.stderr.write(`\n  ${A.mag}◆ flow plan ready — flow ${String(entry.flowSessionId).slice(0, 8)}.${A.rst}\n`)
+        resolve('keep')
+        return
+      }
       // Keep the broadcast payload with the resolver so a reconnect can re-send it
       // (replay-request handler) — pending cards never enter the replayed event log.
       const payload = { term: id, id: req.id, toolName: req.toolName, input: req.input, risk: req.risk, plan: req.plan, questions: req.questions }
@@ -1743,6 +1782,72 @@ channel
     }
   })
 
+// ── Thinkpool Flow control channel (tpflow:<room>) ──────────────────────────
+// Separate from the room channel above so the web's useFlow hook can own its own
+// topic without colliding with the room's tpcode channel (see the flowChannel def +
+// useFlow.js for the 2026-06-30 collision this fixes). Inbound: flow-start (launch a
+// conductor) + flow-dispatch (spawn lanes). Outbound (via bcast(..., flowChannel)):
+// flow-plan, flow-dispatched, flow-task-done.
+flowChannel
+  .on('broadcast', { event: 'flow-start' }, ({ payload }) => {
+    // Ensemble Flow — the room asks this bridge to launch a CONDUCTOR for a Flow run.
+    // The room already created the flow_sessions row (flowId); the conductor opens in
+    // plan mode (so ExitPlanMode is permitted), seeded with the build prompt. It
+    // decomposes → calls ExitPlanMode(planJson) → the requestPermission flow-plan branch
+    // broadcasts flow-plan back. `host` routes to one bridge in multi-machine rooms.
+    if (!payload?.flowId) return
+    if (payload.host && payload.host !== name) return
+    for (const [, e] of sessions) if (e.flowSessionId === payload.flowId) return   // already conducting this flow
+    const cid = randomUUID()
+    termNames[cid] = `Flow · ${String(payload.flowId).slice(0, 6)}`
+    saveNames(room, termNames)
+    openStructured({ id: cid, mode: 'plan', rolePrompt: FLOW_CONDUCTOR_PROMPT, flowSessionId: payload.flowId })
+    const ce = sessions.get(cid)
+    if (ce?.session) { try { ce.session.sendTurn(payload.prompt || '') } catch { /* session still starting */ } }
+    process.stderr.write(`\n  ${A.mag}◆ flow conductor launched — flow ${String(payload.flowId).slice(0, 8)} (plan mode).${A.rst}\n`)
+    announce()
+  })
+  .on('broadcast', { event: 'flow-dispatch' }, ({ payload }) => {
+    // Ensemble Flow — the room approved the plan + sends the READY tasks. Spawn one
+    // worktree-isolated lane per task (FLOW_LANE_PROMPT, its own git tree so lanes
+    // never collide — M57). Seed each lane with its slice spec, then echo the
+    // assignments back so the room marks the tasks dispatched + flips the flow to
+    // building (DB writes stay room-side, member-authed).
+    if (!payload?.flowId || !Array.isArray(payload.tasks)) return
+    if (payload.host && payload.host !== name) return
+    const assignments = []
+    for (const t of payload.tasks) {
+      try {
+        const { dir } = createFlowWorktree({ flowId: payload.flowId, taskKey: t.task_key })
+        const laneId = randomUUID()
+        termNames[laneId] = `Flow · ${t.task_key}`
+        saveNames(room, termNames)
+        openStructured({ id: laneId, cwd: dir, mode: 'acceptEdits', rolePrompt: FLOW_LANE_PROMPT, flowSessionId: payload.flowId, flowTaskKey: t.task_key, spawnedBy: `flow:${payload.flowId}` })
+        const le = sessions.get(laneId)
+        if (le?.session) {
+          const spec =
+            `[Flow lane — slice "${t.task_key}" of flow ${String(payload.flowId).slice(0, 8)}]\n` +
+            `TITLE: ${t.title}\n` +
+            `SCOPE (files you OWN — edit ONLY these): ${t.scope || '(none stated)'}\n` +
+            `ACCEPTANCE (done = this runs + proves it): ${t.acceptance || '(meet the title)'}\n` +
+            (t.deps && t.deps.length ? `DEPENDS ON (already built): ${t.deps.join(', ')}\n` : '') +
+            `\nProject (context): ${payload.flowPrompt || ''}\n\n` +
+            `Build your slice. Own only your files. Done = it runs + meets acceptance. Commit when done.`
+          try { le.session.sendTurn(spec) } catch { /* session still starting */ }
+        }
+        assignments.push({ task_key: t.task_key, laneId })
+      } catch (e) {
+        process.stderr.write(`\n  ${A.yel}◆ flow dispatch failed for ${t.task_key}: ${e?.message || e}${A.rst}\n`)
+      }
+    }
+    if (assignments.length) {
+      bcast('flow-dispatched', { term: 'flow', flowId: payload.flowId, assignments }, flowChannel)
+      process.stderr.write(`\n  ${A.mag}◆ flow dispatched ${assignments.length} lane(s) — flow ${String(payload.flowId).slice(0, 8)}.${A.rst}\n`)
+      announce()
+    }
+  })
+  .subscribe()
+
 // Watchdog — if the realtime channel is stuck (never connected, or dropped and
 // not recovered) for >60s, exit non-zero so a supervisor/launchd restarts a
 // clean process. Healthy long-lived connections never trip this (brokenSince=0).

package/claude-session.mjs

@@ -120,7 +120,7 @@ const simplifyBlocks = (blocks = []) => blocks.map((b) => {
  */
 const MODES = new Set(['default', 'acceptEdits', 'plan', 'bypassPermissions'])
 
-export function startClaudeSession({ cwd, model, resume, env, mode: initialMode = 'default', onEvent, requestPermission, mcpServers, crossPostGate, crossRoomPostGate }) {
+export function startClaudeSession({ cwd, model, resume, env, mode: initialMode = 'default', onEvent, requestPermission, mcpServers, crossPostGate, crossRoomPostGate, rolePrompt }) {
   const ac = new AbortController()
   let input = makeInputStream()   // `let`: auto-restart swaps in a fresh stream
   let sessionId = resume || null
@@ -423,6 +423,7 @@ export function startClaudeSession({ cwd, model, resume, env, mode: initialMode
     // a bypass session still planned. Bias the room session to DO the work; only
     // plan when the room is actually in Plan mode (⇧⇥) or the user explicitly asks.
     appendSystemPrompt: [
+      ...(rolePrompt ? [rolePrompt] : []),
       'ENVIRONMENT (authoritative — overrides any user-global CLAUDE.md or memory that claims otherwise): You are Claude running inside a ThinkPool Code room, driven live by a user (and possibly a partner) from a phone or browser, via the thinkpool-pair bridge.',
       'You are NOT in cmux. cmux may be installed on this machine and appear in $PATH, but it did not spawn you and its automation/orchestration rules do not apply. If any loaded memory says "Claude Code lives inside cmux," it is describing direct terminal use, not this room — disregard it here. The runtime truth is the env: THINKPOOL_PAIR_ACCOUNT_CHILD / npm_lifecycle_script=thinkpool-pair mark a ThinkPool Code session.',
       'Bias strongly toward DOING the work, not planning it. For a normal "add / fix / change / build X" request, just make the change directly.',

package/flow-conductor.mjs

@@ -0,0 +1,91 @@
+// Thinkpool Flow — the conductor brain.
+//
+// The conductor is a Claude agent session (run via startClaudeSession with
+// `rolePrompt: FLOW_CONDUCTOR_PROMPT`) whose Step-1 job is to DECOMPOSE a "build me
+// X" prompt into a task-graph of RUNNABLE slices + dependencies, then submit that
+// plan for human approval. It does not build or spawn lanes yet — dispatch is Step 2.
+// The plan lives in the task-graph store (DB), not in the conductor's chat context
+// (research move #1). Spec: docs/specs/2026-06-29-thinkpool-flow.md.
+
+// Bridge-local MIRROR of src/lib/flow/taskGraph.js — NOT a cross-package import.
+// The bridge ships as its own npm package (thinkpool-pair); `../src/...` does not
+// exist in the published tarball, only in a checkout. flow-task-graph.mjs is a
+// byte-identical copy, kept honest by bridge/flow-task-graph.sync.test.js (fails if
+// it drifts from the canonical src module). One logical source, two reachable copies.
+import { FLOW_MODE, FLOW_STATUS, normalizePlanOutput } from './flow-task-graph.mjs'
+
+// Re-export the shared plan normalizer so bridge callers import Flow pieces from one
+// place. The implementation lives in the shared model (src/lib/flow/taskGraph.js).
+export { normalizePlanOutput }
+
+// Prepended to the room's standard appendSystemPrompt for a Flow conductor session.
+// This prompt IS the moat — decomposition intelligence. Grounded in the Flow research
+// (docs/specs/2026-06-29-thinkpool-flow.md §Research sources): runtime-per-lane is the
+// moat, partition by file ownership, plan-in-store-not-context, right-size the slice
+// count (3 focused beats 7 scattered), explicit acyclic deps.
+export const FLOW_CONDUCTOR_PROMPT = [
+  'THINKPOOL FLOW — you are the CONDUCTOR of an ensemble build. Your job RIGHT NOW (Step 1) is to decompose the user\'s build request into a TASK-GRAPH: a set of RUNNABLE slices with explicit dependencies, then submit that plan for human approval. Do NOT start building and do NOT spawn lanes yet — that happens only after the user approves the plan (Step 2+).',
+
+  'DECOMPOSE INTO RUNNABLE SLICES. Each slice must be something ONE lane can build, RUN in its own browser-side WebContainer sandbox, observe, and self-correct INDEPENDENTLY. A slice that cannot run on its own is not a slice — split it or merge it until it is. The runtime (a lane running what it built) is the moat; slices that can\'t run break the whole model.',
+
+  'PARTITION BY FILE OWNERSHIP. Each slice MUST own a disjoint set of files/components — state the exact paths in `scope`. Two lanes editing the same file collide (a branch is NOT isolation when two lanes share a tree). If two slices want the same file, one depends on the other, or you split the file. State ownership precisely.',
+
+  'EXPLICIT ACYCLIC DEPENDENCIES. Every slice lists the keys of slices it depends on. Dependencies must form a DAG. A slice needing another\'s output (an API contract, a shared type, a layout component) depends on it. Minimize coupling — prefer independent slices that build in parallel.',
+
+  'ACCEPTANCE CRITERIA per slice: how does the lane know it is DONE AND RUNNING? A lane is done when its slice runs in its WebContainer and meets the criteria — not when it has merely written code. State the observable, runnable proof (e.g. "GET /api/todos returns 200 + []", "submitting the form adds a row to the list that persists across reload").',
+
+  'RIGHT-SIZE THE SLICE COUNT. Bias to FEW slices that each carry real weight, not many tiny ones. For a small app: 2-3 slices. Concurrent lanes are bounded (a low dispatch ceiling), so a flat fan-out of well-chosen slices beats a sprawling one. Three focused slices outperform seven scattered ones.',
+
+  'SUBMIT VIA ExitPlanMode — when the decomposition is ready, CALL the ExitPlanMode tool, passing your plan as ONE JSON object (a JSON string) in its `plan` argument. The room intercepts that call, validates the plan is a real DAG (acyclic, all deps resolve), persists it to the task-graph store, and shows a plan-approval card. A malformed plan is rejected and you will be asked to re-emit. Do not also narrate the plan in prose. The exact shape:',
+  '{ "summary": "<one line: what we are building>", "tasks": [ { "key": "<short-unique-kebab-key>", "title": "<imperative title>", "scope": "<files/components this lane owns>", "acceptance": "<runnable proof it is done>", "deps": ["<other-task-key>", ...], "sliceType": "feature|scaffold|review|fix" } ] }',
+  '`key` values are stable short kebab-case identifiers. `deps` references other tasks\' keys. Put ONLY the JSON in the ExitPlanMode plan argument (no surrounding prose, no markdown fences).',
+
+  'PLAN LIVES IN THE STORE, NOT THE CHAT. Your JSON plan is the artifact — it gets persisted to the task-graph (flow_sessions / flow_tasks) and rendered as an approval card. Do not ALSO narrate a long plan in prose. You may add 1-2 sentences framing the decomposition choice (why these slices, what was coupled), nothing more.',
+
+  'MODE-AWARE. The user picked a mode — steer (watch every lane live), guide (DEFAULT: approve this plan, then review at phase boundaries), or autopilot (full-auto with a budget cap + adaptive escalation that pulls them in only if a lane stalls). Produce the full plan now regardless; the mode changes how much the human intervenes later, not how you decompose.',
+].join(' ')
+
+// Env vars handed to a conductor session via startClaudeSession({ env }). The conductor
+// reads these to know which Flow run it owns + what mode the human picked.
+export function buildConductorEnv ({ flowSessionId, mode, budgetCapAutopilot = null }) {
+  return {
+    TP_FLOW_SESSION: flowSessionId,
+    TP_FLOW_MODE: mode,
+    ...(mode === FLOW_MODE.autopilot && budgetCapAutopilot != null
+      ? { TP_FLOW_BUDGET_CAP: String(budgetCapAutopilot) }
+      : {}),
+  }
+}
+
+// Status the FlowSession moves to once the conductor emits + the client validates a
+// plan (i.e. the plan-approval card can now be shown). Kept here so bridge + client
+// import the same transition target.
+export const PLAN_READY_STATUS = FLOW_STATUS.awaiting_approval
+
+// ── Lane builder ────────────────────────────────────────────────────────────
+// The conductor DECOMPOSES; a lane BUILDS one slice. Lanes dispatch after the human
+// approves the plan (Step 2). Each lane runs in its own git worktree (disjoint tree,
+// atomic-revert target). This prompt is the lane's rolePrompt (via startClaudeSession).
+export const FLOW_LANE_PROMPT = [
+  'THINKPOOL FLOW — you are ONE LANE in an ensemble build. The conductor already decomposed the project into RUNNABLE slices; you own exactly ONE. Your task (scope + acceptance + deps) arrives as your first message.',
+
+  'OWN YOUR FILES ONLY. The `scope` names the files/components this lane OWNS — they are DISJOINT from every other lane. Edit ONLY those. Touching another lane\'s files is a collision that breaks the merge — never do it. If you genuinely need a file outside your scope, STOP and say so instead of editing it.',
+
+  'DONE MEANS RUNS. You are not done when you\'ve written code — you\'re done when your slice RUNS and meets the `acceptance` criteria (the observable, runnable proof). Verify it yourself before declaring done. State the proof (the command, the output) when you finish.',
+
+  'COMMIT WHEN DONE, THEN SIGNAL. You are in your own git worktree on your own branch. When your slice meets acceptance — it RUNS and you have verified the proof — commit it atomically (one focused commit); that commit is the revert target if review later rejects it. Then call the `mark_flow_done` tool ONCE: it records your commit as this slice\'s revert target and tells the room the slice is done (which unblocks any slices depending on you). Do not push. Do NOT call mark_flow_done before your slice actually runs + meets acceptance.',
+
+  'STAY IN YOUR LANE. Do NOT spawn further lanes (one hop only — the fork-bomb breaker). Do NOT edit other worktrees. If you\'re blocked on a dependency that isn\'t ready, say so + stop — another lane is building it.',
+
+  'BE RIGOROUS, NOT VIBES. Trace the data path, root-cause before fixing, verify before claiming done. A lane that ships a guess costs the whole ensemble.',
+].join(' ')
+
+// Env vars handed to a lane session so it knows its Flow run + which task it owns.
+export function buildLaneEnv ({ flowSessionId, taskKey, laneId }) {
+  return {
+    TP_FLOW_SESSION: flowSessionId,
+    TP_FLOW_TASK_KEY: taskKey,
+    TP_FLOW_LANE_ID: laneId,
+  }
+}
+

package/flow-task-graph.mjs

@@ -0,0 +1,166 @@
+// Thinkpool Flow — task-graph data model.
+//
+// A Flow run = one FlowSession (the "build me X" prompt + mode + status) decomposed
+// by the conductor into FlowTasks (RUNNABLE slices + dependencies). The plan lives
+// HERE, in the store, not in the conductor's chat context — research move #1
+// (docs/specs/2026-06-29-thinkpool-flow.md): "move the plan out of the context
+// window into a task-graph." Pure module — shared by the bridge (conductor) and the
+// client (room UI), and mirrored by CHECK constraints in the
+// 20260629120000_flow_sessions_tasks migration (one source of truth).
+
+export const FLOW_STATUS = {
+  planning: 'planning',                // conductor is decomposing
+  awaiting_approval: 'awaiting_approval', // plan submitted, waiting on the human
+  approved: 'approved',                // human approved; lanes may dispatch (Step 2+)
+  building: 'building',                // lanes are running
+  reviewing: 'reviewing',              // adversarial-review phase
+  assembling: 'assembling',            // merging worktrees
+  done: 'done',
+  failed: 'failed',
+  cancelled: 'cancelled',
+}
+
+export const TASK_STATUS = {
+  pending: 'pending',
+  ready: 'ready',                      // deps satisfied, awaiting dispatch
+  dispatched: 'dispatched',            // a lane is running it
+  reviewing: 'reviewing',              // adversarial-review lane is checking it
+  done: 'done',
+  failed: 'failed',
+  reverted: 'reverted',                // rolled back by the atomic-revert net
+}
+
+export const FLOW_MODE = {
+  steer: 'steer',                      // human watches every lane, live
+  guide: 'guide',                      // phase-gated (DEFAULT): approve plan + phase reviews
+  autopilot: 'autopilot',              // full-auto, adaptive escalation + budget cap
+}
+
+export const SLICE_TYPE = {
+  feature: 'feature',
+  scaffold: 'scaffold',                // project bootstrap / shared foundation
+  review: 'review',                    // adversarial-review lane
+  fix: 'fix',
+}
+
+// A FlowTask slice. Each is RUNNABLE — a lane can build + run + self-correct it in
+// its own WebContainer (research: the runtime is the moat). Partition by file
+// ownership (scope) so two lanes never edit the same file (a branch is NOT isolation).
+export function makeTask ({ key, title, scope = '', acceptance = '', deps = [], sliceType = SLICE_TYPE.feature }) {
+  if (!key || typeof key !== 'string') throw new Error('task key required (string)')
+  if (!title) throw new Error('task title required')
+  if (!Array.isArray(deps)) throw new Error('deps must be an array of task keys')
+  if (!Object.values(SLICE_TYPE).includes(sliceType)) throw new Error(`unknown sliceType: ${sliceType}`)
+  return {
+    key,
+    title,
+    scope,            // files/components this lane OWNS (disjoint from other slices)
+    acceptance,       // runnable proof the lane + reviewer use to call it done
+    deps,             // task keys this depends on (must form a DAG)
+    sliceType,
+    status: TASK_STATUS.pending,
+    laneId: null,     // the spawned lane's terminal id, once dispatched
+    commitSha: null,  // per-lane atomic commit (revert target)
+    failCount: 0,     // adaptive-escalation counter (Autopilot pulls human in at N)
+  }
+}
+
+// Validate that tasks form a real DAG: unique keys, every dep references an existing
+// key, no self-deps, no cycles. Throws on invalid. Returns the tasks (chainable).
+export function validateDag (tasks) {
+  if (!Array.isArray(tasks) || tasks.length === 0) throw new Error('at least one task required')
+  const keys = new Set(tasks.map(t => t.key))
+  if (keys.size !== tasks.length) throw new Error('duplicate task keys')
+  const byKey = new Map(tasks.map(t => [t.key, t]))
+  for (const t of tasks) {
+    if (t.deps.includes(t.key)) throw new Error(`task "${t.key}" depends on itself`)
+    for (const d of t.deps) {
+      if (!keys.has(d)) throw new Error(`task "${t.key}" depends on unknown task "${d}"`)
+    }
+  }
+  // Cycle detection (DFS, three-color). byKey guaranteed complete by the checks above.
+  const WHITE = 0, GRAY = 1, BLACK = 2
+  const color = new Map(tasks.map(t => [t.key, WHITE]))
+  function visit (k) {
+    color.set(k, GRAY)
+    for (const d of byKey.get(k).deps) {
+      const c = color.get(d)
+      if (c === GRAY) throw new Error(`cycle detected at "${k}" → "${d}"`)
+      if (c === WHITE) visit(d)
+    }
+    color.set(k, BLACK)
+  }
+  for (const t of tasks) if (color.get(t.key) === WHITE) visit(t.key)
+  return tasks
+}
+
+// Tasks whose deps are all DONE → ready to dispatch. Pure.
+export function readyTasks (tasks) {
+  const done = new Set(tasks.filter(t => t.status === TASK_STATUS.done).map(t => t.key))
+  return tasks.filter(t =>
+    t.status === TASK_STATUS.pending &&
+    t.deps.every(d => done.has(d))
+  )
+}
+
+// Topological order (Kahn's algorithm). Returns keys. Throws if not a DAG.
+export function topoOrder (tasks) {
+  validateDag(tasks)
+  const indeg = new Map(tasks.map(t => [t.key, t.deps.length]))
+  const dependents = new Map(tasks.map(t => [t.key, []])) // dep-key → keys that depend on it
+  for (const t of tasks) for (const d of t.deps) dependents.get(d).push(t.key)
+  const queue = tasks.filter(t => indeg.get(t.key) === 0).map(t => t.key)
+  const order = []
+  while (queue.length) {
+    const k = queue.shift()
+    order.push(k)
+    for (const m of dependents.get(k)) {
+      indeg.set(m, indeg.get(m) - 1)
+      if (indeg.get(m) === 0) queue.push(m)
+    }
+  }
+  if (order.length !== tasks.length) throw new Error('cycle detected (topo incomplete)')
+  return order
+}
+
+// A FlowSession (the run). `tasks` is the decomposed plan (FlowTask[]).
+export function makeFlowSession ({ prompt, mode = FLOW_MODE.guide, sessionRef = null, budgetCapAutopilot = null }) {
+  if (!prompt) throw new Error('prompt required')
+  if (!Object.values(FLOW_MODE).includes(mode)) throw new Error(`unknown mode: ${mode}`)
+  return {
+    prompt,
+    mode,
+    sessionRef,            // the /code room session id this Flow runs in
+    status: FLOW_STATUS.planning,
+    budgetCapAutopilot,    // token/step cap (Autopilot only); null in guide/steer
+    createdAt: null,       // stamped by the DB
+    tasks: [],
+  }
+}
+
+// Normalize the conductor's raw plan output into a validated { summary, tasks }.
+// Accepts a parsed object OR a JSON string (optionally ```json-fenced). Throws if the
+// tasks don't form a real DAG. Lives in this shared module so neither the bridge nor
+// the client has to import across the bridge↔src boundary.
+export function normalizePlanOutput (raw) {
+  let obj = raw
+  if (typeof raw === 'string') {
+    let s = raw.trim()
+    const fence = s.match(/```(?:json)?\s*([\s\S]*?)```/i)
+    if (fence) s = fence[1].trim()
+    obj = JSON.parse(s)
+  }
+  if (!obj || typeof obj !== 'object') throw new Error('plan output is not an object')
+  const summary = typeof obj.summary === 'string' && obj.summary.trim() ? obj.summary.trim() : ''
+  if (!Array.isArray(obj.tasks) || obj.tasks.length === 0) throw new Error('plan has no tasks')
+  const tasks = obj.tasks.map((t) => makeTask({
+    key: String(t.key),
+    title: String(t.title ?? t.key),
+    scope: String(t.scope ?? ''),
+    acceptance: String(t.acceptance ?? ''),
+    deps: Array.isArray(t.deps) ? t.deps.map(String) : [],
+    sliceType: Object.values(SLICE_TYPE).includes(t.sliceType) ? t.sliceType : SLICE_TYPE.feature,
+  }))
+  validateDag(tasks)
+  return { summary, tasks }
+}

package/flow-worktree.mjs

@@ -0,0 +1,53 @@
+// Thinkpool Flow — per-lane git worktree isolation.
+//
+// A Flow task-lane builds its slice in its OWN worktree. A branch is NOT isolation
+// when ≥2 lanes share one working tree (M57) — two lanes editing files in the shared
+// checkout collide. A worktree gives each lane a disjoint tree + its own branch, and
+// that branch is the atomic-revert target (commit_sha on flow_tasks, Step 4).
+//
+// Pure over injected git/fs so it's unit-testable against a temp repo.
+// Spec: docs/specs/2026-06-29-thinkpool-flow.md (Step 2).
+
+import { execFileSync } from 'node:child_process'
+import path from 'node:path'
+import fs from 'node:fs'
+
+const ROOT = process.cwd()   // the bridge's checkout (the shared main repo root)
+
+// The lane's branch + directory for a (flowId, taskKey). Deterministic so a
+// re-dispatch of the same task reuses the same worktree.
+export function worktreeSpec ({ flowId, taskKey, root = ROOT }) {
+  const wtRoot = path.join(root, '.claude', 'worktrees')
+  const short = String(flowId).replace(/-/g, '').slice(0, 8)
+  const safeKey = String(taskKey).toLowerCase().replace(/[^a-z0-9-]/g, '-').slice(0, 40).replace(/^-+|-+$/g, '') || 'task'
+  const branch = `flow/${short}/${safeKey}`
+  const dir = path.join(wtRoot, `flow-${short}-${safeKey}`)
+  return { branch, dir, wtRoot }
+}
+
+// Create a worktree for a task-lane off `base` (default origin/main). Idempotent: if
+// the dir already holds a worktree, reuse it. Returns { dir, branch, created }.
+export function createFlowWorktree ({ flowId, taskKey, base = 'origin/main', root = ROOT, git = runGit }) {
+  const { branch, dir, wtRoot } = worktreeSpec({ flowId, taskKey, root })
+  if (fs.existsSync(path.join(dir, '.git'))) return { dir, branch, created: false }
+  fs.mkdirSync(wtRoot, { recursive: true })
+  try {
+    git(['worktree', 'add', '-b', branch, dir, base], root)
+  } catch {
+    // Branch already exists (a prior dispatch of this task) — check it out instead.
+    git(['worktree', 'add', dir, branch], root)
+  }
+  return { dir, branch, created: true }
+}
+
+// Remove a lane's worktree + delete its branch (on revert / cancel / flow cancel).
+// Best-effort: missing worktree/branch is not an error.
+export function removeFlowWorktree ({ flowId, taskKey, root = ROOT, git = runGit }) {
+  const { branch, dir } = worktreeSpec({ flowId, taskKey, root })
+  try { git(['worktree', 'remove', dir, '--force'], root) } catch { /* already gone */ }
+  try { git(['branch', '-D', branch], root) } catch { /* already gone */ }
+}
+
+function runGit (args, cwd) {
+  return execFileSync('git', args, { cwd, stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8' })
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thinkpool-pair",
-  "version": "0.7.96",
+  "version": "0.7.98",
   "description": "Share a local coding-agent CLI (Claude Code, Codex, Gemini, Aider, …) into a ThinkPool Code room, live.",
   "type": "module",
   "bin": {
@@ -16,6 +16,9 @@
     "transcript-sanitize.mjs",
     "session-store.mjs",
     "cross-terminal.mjs",
+    "flow-conductor.mjs",
+    "flow-worktree.mjs",
+    "flow-task-graph.mjs",
     "serve-dir.mjs",
     "service.mjs",
     "presence.mjs",