thinkpool-pair 0.7.364 → 0.7.366

package/flow-task-graph.mjs

@@ -1,562 +1 @@
-// 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',
-}
-
-// Gate-first Flow contracts are stored in flow_tasks.contract (JSONB). Keep every
-// free-text field bounded and single-line: this payload crosses the terminal MCP
-// boundary and is later injected into builder/reviewer prompts.
-export const FLOW_CONTRACT_LIMITS = Object.freeze({
-  maxNonGoals: 6,
-  maxNonGoalChars: 240,
-  maxBaselineGateChars: 600,
-  maxBaselineEvidenceChars: 1400,
-  maxScopePaths: 32,
-  maxScopePathChars: 180,
-})
-
-const BASELINE_NEGATIVE_SIGNAL = /\b(fail(?:s|ed|ing)?|absent|missing|not\s+(?:present|implemented|available|found)|does\s+not|404|empty)\b/i
-const CONTRACT_DIGEST = /^[a-f0-9]{64}$/
-const SHA256_K = [
-  0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
-  0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
-  0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
-  0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
-  0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
-  0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
-  0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
-  0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
-]
-const rotateRight = (value, bits) => (value >>> bits) | (value << (32 - bits))
-const hasDisallowedControl = (value) => {
-  for (const char of value) {
-    const code = char.charCodeAt(0)
-    if (code === 0x7f || (code < 0x20 && code !== 0x09)) return true
-  }
-  return false
-}
-
-function boundedLine (value, label, max, { required = false } = {}) {
-  if (value == null || value === '') {
-    if (required) throw new Error(`${label} is required`)
-    return ''
-  }
-  if (typeof value !== 'string') throw new Error(`${label} must be a string`)
-  const text = value.trim()
-  if (!text) {
-    if (required) throw new Error(`${label} is required`)
-    return ''
-  }
-  if (text.length > max) throw new Error(`${label} exceeds ${max} characters`)
-  if (hasDisallowedControl(text)) throw new Error(`${label} must be safe single-line text`)
-  return text
-}
-
-function normalizeScopePath (value) {
-  if (typeof value !== 'string') return null
-  const text = value.trim().replaceAll('\\', '/')
-  if (!text || text.length > FLOW_CONTRACT_LIMITS.maxScopePathChars || text.startsWith('/') || /^[A-Za-z]:\//.test(text)) return null
-  const directoryPattern = text.endsWith('/**')
-  if (text.includes('*') && !directoryPattern) return null
-  const bare = directoryPattern ? text.slice(0, -3) : text
-  if (!bare || bare.endsWith('/') || bare.split('/').some((part) => !part || part === '.' || part === '..')) return null
-  if (/(?:^|\/)(?:\.env(?:\.|$)|\.git(?:\/|$)|\.thinkpool(?:\/|$)|node_modules(?:\/|$))/.test(bare)) return null
-  const last = bare.split('/').at(-1)
-  if (!directoryPattern && !last.includes('.') && !/^(?:Dockerfile|Makefile|LICENSE|README)$/i.test(last)) return null
-  return directoryPattern ? `${bare}/**` : bare
-}
-
-export function normalizeTaskScopePaths (value, { fallbackScope = '', required = true } = {}) {
-  let values = value
-  if (values == null && fallbackScope) {
-    const inferred = normalizeScopePath(fallbackScope)
-    if (inferred) values = [inferred]
-  }
-  if (values == null) values = []
-  if (!Array.isArray(values)) throw new Error('scopePaths must be an array')
-  if (values.length > FLOW_CONTRACT_LIMITS.maxScopePaths) throw new Error(`scopePaths exceeds ${FLOW_CONTRACT_LIMITS.maxScopePaths} entries`)
-  const out = []
-  for (const item of values) {
-    const safe = normalizeScopePath(item)
-    if (!safe) throw new Error(`invalid scope path: ${JSON.stringify(item)}`)
-    if (!out.includes(safe)) out.push(safe)
-  }
-  if (required && out.length === 0) throw new Error('machine-readable scopePaths are required for builder/fix/scaffold tasks')
-  return out.sort()
-}
-
-export function normalizeBaselineEvidence (value) {
-  return boundedLine(value, 'baseline evidence receipt', FLOW_CONTRACT_LIMITS.maxBaselineEvidenceChars, { required: true })
-}
-
-// This is deliberately a small synchronous SHA-256 implementation instead of a
-// Node crypto import or WebCrypto: the task graph must stay byte-identical and run
-// in both the bridge's Node runtime and the browser bundle.
-function sha256Hex (message) {
-  const source = new TextEncoder().encode(message)
-  const totalLength = Math.ceil((source.length + 9) / 64) * 64
-  const bytes = new Uint8Array(totalLength)
-  bytes.set(source)
-  bytes[source.length] = 0x80
-  let bitLength = BigInt(source.length) * 8n
-  for (let index = totalLength - 1; index >= totalLength - 8; index--) {
-    bytes[index] = Number(bitLength & 0xffn)
-    bitLength >>= 8n
-  }
-
-  const hash = [0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19]
-  const words = new Uint32Array(64)
-  for (let offset = 0; offset < bytes.length; offset += 64) {
-    for (let index = 0; index < 16; index++) {
-      const start = offset + (index * 4)
-      words[index] = ((bytes[start] << 24) | (bytes[start + 1] << 16) | (bytes[start + 2] << 8) | bytes[start + 3]) >>> 0
-    }
-    for (let index = 16; index < 64; index++) {
-      const low = rotateRight(words[index - 15], 7) ^ rotateRight(words[index - 15], 18) ^ (words[index - 15] >>> 3)
-      const high = rotateRight(words[index - 2], 17) ^ rotateRight(words[index - 2], 19) ^ (words[index - 2] >>> 10)
-      words[index] = (words[index - 16] + low + words[index - 7] + high) >>> 0
-    }
-
-    let [a, b, c, d, e, f, g, h] = hash
-    for (let index = 0; index < 64; index++) {
-      const sigma1 = rotateRight(e, 6) ^ rotateRight(e, 11) ^ rotateRight(e, 25)
-      const choose = (e & f) ^ (~e & g)
-      const temp1 = (h + sigma1 + choose + SHA256_K[index] + words[index]) >>> 0
-      const sigma0 = rotateRight(a, 2) ^ rotateRight(a, 13) ^ rotateRight(a, 22)
-      const majority = (a & b) ^ (a & c) ^ (b & c)
-      const temp2 = (sigma0 + majority) >>> 0
-      h = g
-      g = f
-      f = e
-      e = (d + temp1) >>> 0
-      d = c
-      c = b
-      b = a
-      a = (temp1 + temp2) >>> 0
-    }
-    hash[0] = (hash[0] + a) >>> 0
-    hash[1] = (hash[1] + b) >>> 0
-    hash[2] = (hash[2] + c) >>> 0
-    hash[3] = (hash[3] + d) >>> 0
-    hash[4] = (hash[4] + e) >>> 0
-    hash[5] = (hash[5] + f) >>> 0
-    hash[6] = (hash[6] + g) >>> 0
-    hash[7] = (hash[7] + h) >>> 0
-  }
-  return hash.map((word) => word.toString(16).padStart(8, '0')).join('')
-}
-
-// The acceptance pack belongs to the builder target. A review task copies that
-// target's digest, so its inherited target is bound without re-hashing reviewer
-// prose or later baseline evidence receipts.
-function acceptancePack ({ key, title, scope, scopePaths, acceptance, sliceType, nonGoals, baselineGate, inheritedReviewerTarget = key, version = 2 }) {
-  const pack = {
-    version,
-    task: { key, title, scope, acceptance, sliceType },
-    nonGoals: [...nonGoals].sort(),
-    baselineGate,
-    inheritedReviewerTarget,
-  }
-  if (version >= 2) pack.task.scopePaths = normalizeTaskScopePaths(scopePaths, { fallbackScope: scope })
-  return pack
-}
-
-export function acceptancePackDigest (input) {
-  return sha256Hex(JSON.stringify(acceptancePack(input)))
-}
-
-function contractSource (task) {
-  const source = task?.contract && typeof task.contract === 'object' && !Array.isArray(task.contract)
-    ? { ...task.contract }
-    : {}
-  if (source.nonGoals === undefined) source.nonGoals = task?.nonGoals ?? task?.non_goals
-  if (source.baseline === undefined) source.baseline = task?.baseline ?? task?.baselineGate ?? task?.baseline_gate
-  if (source.scopePaths === undefined) source.scopePaths = task?.scopePaths ?? task?.scope_paths
-  return source
-}
-
-function normalizeProvidedContractDigest (source) {
-  if (source.digest === undefined) return null
-  if (typeof source.digest !== 'string' || !CONTRACT_DIGEST.test(source.digest)) {
-    throw new Error('contract digest must be a lowercase SHA-256 hex string')
-  }
-  return source.digest
-}
-
-function normalizeProvidedAcceptancePack (source) {
-  if (source.acceptancePack === undefined) return null
-  if (!source.acceptancePack || typeof source.acceptancePack !== 'object' || Array.isArray(source.acceptancePack)) {
-    throw new Error('contract acceptance pack must be an object')
-  }
-  return source.acceptancePack
-}
-
-// Strict for new terminal submissions. `legacy:true` is restore-only: old persisted
-// plans predate this contract and must remain runnable, but they can never be used to
-// submit a new incomplete plan.
-export function normalizeTaskContract (task, { sliceType, legacy = false } = {}) {
-  const source = contractSource(task)
-  const digest = normalizeProvidedContractDigest(source)
-  const sealedPack = normalizeProvidedAcceptancePack(source)
-  if (sliceType === SLICE_TYPE.review) return legacy ? null : { digest, acceptancePack: sealedPack }
-  const required = !legacy
-  const rawNonGoals = source.nonGoals
-  const values = rawNonGoals == null ? [] : (Array.isArray(rawNonGoals) ? rawNonGoals : [rawNonGoals])
-  if (values.length > FLOW_CONTRACT_LIMITS.maxNonGoals) throw new Error(`non-goals exceeds ${FLOW_CONTRACT_LIMITS.maxNonGoals} items`)
-  const nonGoals = values.map((value) => boundedLine(value, 'non-goal', FLOW_CONTRACT_LIMITS.maxNonGoalChars, { required: true }))
-  if (required && !nonGoals.length) throw new Error('explicit non-goals are required for builder/fix/scaffold tasks')
-
-  const rawBaseline = source.baseline
-  const baselineObject = typeof rawBaseline === 'string' ? { gate: rawBaseline } : rawBaseline
-  if (baselineObject != null && (typeof baselineObject !== 'object' || Array.isArray(baselineObject))) throw new Error('baseline gate must be a string or object')
-  const gate = boundedLine(baselineObject?.gate ?? baselineObject?.expectation, 'baseline gate', FLOW_CONTRACT_LIMITS.maxBaselineGateChars, { required })
-  if (gate && !BASELINE_NEGATIVE_SIGNAL.test(gate)) throw new Error('baseline gate must state what fails or is absent before implementation')
-  const evidence = baselineObject?.evidence == null || baselineObject?.evidence === ''
-    ? ''
-    : normalizeBaselineEvidence(baselineObject.evidence)
-  const scopePaths = normalizeTaskScopePaths(source.scopePaths, { fallbackScope: task?.scope ?? task?.description ?? '', required })
-  return { nonGoals, baseline: gate ? { gate, evidence } : null, scopePaths, digest, acceptancePack: sealedPack }
-}
-
-function bindContractDigest (task, { legacy = false } = {}) {
-  const sealedPack = acceptancePack({
-    key: task.key,
-    title: task.title,
-    scope: task.scope,
-    scopePaths: task.contract.scopePaths,
-    acceptance: task.acceptance,
-    sliceType: task.sliceType,
-    nonGoals: task.contract.nonGoals,
-    baselineGate: task.contract.baseline?.gate || '',
-    inheritedReviewerTarget: task.key,
-    version: legacy ? 1 : 2,
-  })
-  const digest = sha256Hex(JSON.stringify(sealedPack))
-  if (task.contract.digest && task.contract.digest !== digest) throw new Error(`task "${task.key}" contract digest does not match its acceptance pack`)
-  if (task.contract.acceptancePack && JSON.stringify(task.contract.acceptancePack) !== JSON.stringify(sealedPack)) {
-    throw new Error(`task "${task.key}" sealed acceptance pack does not match its task fields`)
-  }
-  task.contract.digest = digest
-  task.contract.acceptancePack = sealedPack
-}
-
-// The browser persists normalized task rows before approval, then later sends a
-// ready row back to the bridge for dispatch. Recompute the seal at that final
-// boundary so changed acceptance/scope/non-goals can never ride beside an old hash.
-export function validateTaskContractSeal (task, { legacy = false } = {}) {
-  const contract = task?.contract
-  if (!contract?.digest && legacy) return true
-  if (!contract || typeof contract !== 'object' || !contract.digest || !contract.acceptancePack) {
-    throw new Error('task is missing its sealed acceptance contract')
-  }
-  const pack = contract.acceptancePack
-  const packTask = pack?.task
-  if (!packTask || typeof packTask !== 'object' || !Array.isArray(pack.nonGoals)) {
-    throw new Error('task sealed acceptance pack is malformed')
-  }
-  const canonicalPack = acceptancePack({
-    key: packTask.key,
-    title: packTask.title,
-    scope: packTask.scope,
-    scopePaths: packTask.scopePaths,
-    acceptance: packTask.acceptance,
-    sliceType: packTask.sliceType,
-    nonGoals: pack.nonGoals,
-    baselineGate: pack.baselineGate,
-    inheritedReviewerTarget: pack.inheritedReviewerTarget,
-    version: pack.version === 1 ? 1 : 2,
-  })
-  if (JSON.stringify(pack) !== JSON.stringify(canonicalPack)) throw new Error('task sealed acceptance pack is not canonical')
-  if (acceptancePackDigest({
-    key: packTask.key,
-    title: packTask.title,
-    scope: packTask.scope,
-    scopePaths: packTask.scopePaths,
-    acceptance: packTask.acceptance,
-    sliceType: packTask.sliceType,
-    nonGoals: pack.nonGoals,
-    baselineGate: pack.baselineGate,
-    inheritedReviewerTarget: pack.inheritedReviewerTarget,
-    version: pack.version === 1 ? 1 : 2,
-  }) !== contract.digest) throw new Error('task acceptance digest does not match its sealed pack')
-
-  const sliceType = task.sliceType ?? task.slice_type
-  const key = task.key ?? task.task_key
-  const deps = Array.isArray(task.deps) ? task.deps : []
-  if (sliceType === SLICE_TYPE.review) {
-    if (contract.inheritedFrom !== packTask.key || deps.length !== 1 || deps[0] !== packTask.key) {
-      throw new Error('review task no longer targets its sealed builder')
-    }
-    if (pack.inheritedReviewerTarget !== packTask.key || task.acceptance !== packTask.acceptance) {
-      throw new Error(`review task "${key}" changed after its builder acceptance pack was sealed`)
-    }
-    return true
-  }
-  const livePack = acceptancePack({
-    key,
-    title: task.title,
-    scope: task.scope ?? '',
-    scopePaths: contract.scopePaths,
-    acceptance: task.acceptance ?? '',
-    sliceType,
-    nonGoals: contract.nonGoals || [],
-    baselineGate: contract.baseline?.gate || '',
-    inheritedReviewerTarget: key,
-    version: pack.version === 1 ? 1 : 2,
-  })
-  if (JSON.stringify(livePack) !== JSON.stringify(canonicalPack)) {
-    throw new Error(`task "${key}" changed after its acceptance pack was sealed`)
-  }
-  return true
-}
-
-// 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, contract = null }) {
-  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
-    contract,          // bounded gate-first contract; null only for legacy/restored rows
-    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, { legacy = false } = {}) {
-  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) => {
-    // Accept `id` as an alias for `key` and `description` for `scope` — conductors emit
-    // either naming. A task with NO key is rejected (was silently String(undefined) →
-    // task_key "undefined", which broke worktree/dispatch); throwing makes it re-emit.
-    const key = t.key ?? t.id
-    if (key == null || !String(key).trim()) throw new Error('a task is missing its "key"')
-    const sliceType = t.sliceType ?? t.slice_type
-    return makeTask({
-      key: String(key),
-      title: String(t.title ?? key),
-      scope: String(t.scope ?? t.description ?? ''),
-      acceptance: String(t.acceptance ?? ''),
-      deps: Array.isArray(t.deps) ? t.deps.map(String) : [],
-      sliceType: Object.values(SLICE_TYPE).includes(sliceType) ? sliceType : SLICE_TYPE.feature,
-      contract: normalizeTaskContract(t, { sliceType: Object.values(SLICE_TYPE).includes(sliceType) ? sliceType : SLICE_TYPE.feature, legacy }),
-    })
-  })
-  validateDag(tasks)
-  for (const task of tasks) {
-    if (task.sliceType !== SLICE_TYPE.review) bindContractDigest(task, { legacy })
-  }
-  for (const task of tasks) {
-    if (task.sliceType !== SLICE_TYPE.review) continue
-    // New review tasks verify exactly one builder contract. Legacy persisted reviews
-    // keep their prior multi-target shape for restore compatibility only.
-    if (legacy) continue
-    if (task.deps.length !== 1) throw new Error(`review task "${task.key}" must depend on exactly one builder task to inherit its contract`)
-    const target = tasks.find((candidate) => candidate.key === task.deps[0])
-    if (!target || target.sliceType === SLICE_TYPE.review) throw new Error(`review task "${task.key}" must target a builder/fix/scaffold task`)
-    if (task.contract.digest && task.contract.digest !== target.contract.digest) {
-      throw new Error(`review task "${task.key}" contract digest does not match target "${target.key}"`)
-    }
-    task.contract = {
-      nonGoals: [...(target.contract?.nonGoals || [])],
-      baseline: target.contract?.baseline ? { ...target.contract.baseline } : null,
-      scopePaths: [...(target.contract?.scopePaths || [])],
-      inheritedFrom: target.key,
-      digest: target.contract.digest,
-      acceptancePack: target.contract.acceptancePack,
-    }
-    // Reviewer-authored prose is not an authority boundary. Normalize the live
-    // review row to the builder's sealed acceptance so dispatch and the prompt
-    // cannot silently substitute a weaker criterion.
-    task.acceptance = target.contract.acceptancePack.task.acceptance
-  }
-  return { summary, tasks }
-}
-
-// Codex review protocol deliberately maps one reviewer lane to one builder target.
-// Claude's legacy Flow plans may review several deps and remain unchanged.
-export function validatePlanForRuntime (plan, runtime = 'claude') {
-  if (runtime !== 'codex' && runtime !== 'hermes') return plan
-  for (const task of plan?.tasks || []) {
-    if (task.sliceType === SLICE_TYPE.review && task.deps.length !== 1) {
-      throw new Error(`${runtime === 'hermes' ? 'Hermes' : 'Codex'} review task "${task.key}" must depend on exactly one builder task`)
-    }
-  }
-  return plan
-}
-
-export function validReviewTargetShape (task, runtime = 'claude') {
-  if (!task || task.slice_type !== SLICE_TYPE.review) return true
-  return (runtime !== 'codex' && runtime !== 'hermes') || (Array.isArray(task.deps) && task.deps.length === 1)
-}
-
-export function legacyBuilderCompletionAllowed ({ runtime, flowRole, eventKind, eventSubtype, interrupted = false } = {}) {
-  return runtime === 'claude' && flowRole === 'builder' && !interrupted && eventKind === 'result' && eventSubtype === 'success'
-}
-
-// ── Flow lane model tiers ───────────────────────────────────────────────────
-// Spec: docs/specs/2026-07-03-flow-lane-model-tiers.md
-// The conductor thinks; the worker lanes type. Running every lane on the same
-// expensive brain is wasteful — the tier map picks a model per slice_type so
-// intelligence matches the job:
-//   scaffold → sonnet   (boilerplate / project bootstrap — mechanical, cheap)
-//   feature  → opus     (real building — needs the smart brain)
-//   fix      → opus     (root-cause debugging — needs the smart brain)
-//   review   → opus     (adversarial verification is intelligence-SENSITIVE; never cheapen it)
-// Unknown/missing slice types fall to opus (safe default — never silently cheapen).
-// Dev-only, no product gating. The conductor's own model is untouched by this map
-// (bridge reads TP_FLOW_CONDUCTOR_MODEL at the conductor spawn site instead).
-//
-// Env overrides (checked FIRST, in order):
-//   TP_FLOW_LANE_MODEL='inherit'  → return undefined (no model key passed → today's exact behavior)
-//   TP_FLOW_LANE_MODEL=<model>    → blanket-override every lane to that model
-//   (empty-string / unset)        → fall through to the tier map
-const LANE_MODEL_TIERS = {
-  scaffold: 'sonnet',
-  feature: 'opus',
-  fix: 'opus',
-  review: 'opus',
-}
-
-export function laneModelFor (sliceType, env = process.env) {
-  const override = env.TP_FLOW_LANE_MODEL
-  if (override === 'inherit') return undefined          // sentinel — restore today's behavior exactly
-  if (override) return override                          // blanket override for all lanes (non-empty string)
-  return LANE_MODEL_TIERS[sliceType] || 'opus'           // tier map; unknown/missing → opus (never cheapen by accident)
-}
+export const FLOW_STATUS={planning:"planning",awaiting_approval:"awaiting_approval",approved:"approved",building:"building",reviewing:"reviewing",assembling:"assembling",done:"done",failed:"failed",cancelled:"cancelled"};export const TASK_STATUS={pending:"pending",ready:"ready",dispatched:"dispatched",reviewing:"reviewing",done:"done",failed:"failed",reverted:"reverted"};export const FLOW_MODE={steer:"steer",guide:"guide",autopilot:"autopilot"};export const SLICE_TYPE={feature:"feature",scaffold:"scaffold",review:"review",fix:"fix"};export const FLOW_CONTRACT_LIMITS=Object.freeze({maxNonGoals:6,maxNonGoalChars:240,maxBaselineGateChars:600,maxBaselineEvidenceChars:1400,maxScopePaths:32,maxScopePathChars:180});const e=/\b(fail(?:s|ed|ing)?|absent|missing|not\s+(?:present|implemented|available|found)|does\s+not|404|empty)\b/i,t=/^[a-f0-9]{64}$/,n=[1116352408,1899447441,3049323471,3921009573,961987163,1508970993,2453635748,2870763221,3624381080,310598401,607225278,1426881987,1925078388,2162078206,2614888103,3248222580,3835390401,4022224774,264347078,604807628,770255983,1249150122,1555081692,1996064986,2554220882,2821834349,2952996808,3210313671,3336571891,3584528711,113926993,338241895,666307205,773529912,1294757372,1396182291,1695183700,1986661051,2177026350,2456956037,2730485921,2820302411,3259730800,3345764771,3516065817,3600352804,4094571909,275423344,430227734,506948616,659060556,883997877,958139571,1322822218,1537002063,1747873779,1955562222,2024104815,2227730452,2361852424,2428436474,2756734187,3204031479,3329325298],r=(e,t)=>e>>>t|e<<32-t;function a(e,t,n,{required:r=!1}={}){if(null==e||""===e){if(r)throw new Error(`${t} is required`);return""}if("string"!=typeof e)throw new Error(`${t} must be a string`);const a=e.trim();if(!a){if(r)throw new Error(`${t} is required`);return""}if(a.length>n)throw new Error(`${t} exceeds ${n} characters`);if((e=>{for(const t of e){const e=t.charCodeAt(0);if(127===e||e<32&&9!==e)return!0}return!1})(a))throw new Error(`${t} must be safe single-line text`);return a}function s(e){if("string"!=typeof e)return null;const t=e.trim().replaceAll("\\","/");if(!t||t.length>FLOW_CONTRACT_LIMITS.maxScopePathChars||t.startsWith("/")||/^[A-Za-z]:\//.test(t))return null;const n=t.endsWith("/**");if(t.includes("*")&&!n)return null;const r=n?t.slice(0,-3):t;if(!r||r.endsWith("/")||r.split("/").some(e=>!e||"."===e||".."===e))return null;if(/(?:^|\/)(?:\.env(?:\.|$)|\.git(?:\/|$)|\.thinkpool(?:\/|$)|node_modules(?:\/|$))/.test(r))return null;const a=r.split("/").at(-1);return n||a.includes(".")||/^(?:Dockerfile|Makefile|LICENSE|README)$/i.test(a)?n?`${r}/**`:r:null}export function normalizeTaskScopePaths(e,{fallbackScope:t="",required:n=!0}={}){let r=e;if(null==r&&t){const e=s(t);e&&(r=[e])}if(null==r&&(r=[]),!Array.isArray(r))throw new Error("scopePaths must be an array");if(r.length>FLOW_CONTRACT_LIMITS.maxScopePaths)throw new Error(`scopePaths exceeds ${FLOW_CONTRACT_LIMITS.maxScopePaths} entries`);const a=[];for(const e of r){const t=s(e);if(!t)throw new Error(`invalid scope path: ${JSON.stringify(e)}`);a.includes(t)||a.push(t)}if(n&&0===a.length)throw new Error("machine-readable scopePaths are required for builder/fix/scaffold tasks");return a.sort()}export function normalizeBaselineEvidence(e){return a(e,"baseline evidence receipt",FLOW_CONTRACT_LIMITS.maxBaselineEvidenceChars,{required:!0})}function o(e){const t=(new TextEncoder).encode(e),a=64*Math.ceil((t.length+9)/64),s=new Uint8Array(a);s.set(t),s[t.length]=128;let o=8n*BigInt(t.length);for(let e=a-1;e>=a-8;e--)s[e]=Number(0xffn&o),o>>=8n;const c=[1779033703,3144134277,1013904242,2773480762,1359893119,2600822924,528734635,1541459225],i=new Uint32Array(64);for(let e=0;e<s.length;e+=64){for(let t=0;t<16;t++){const n=e+4*t;i[t]=(s[n]<<24|s[n+1]<<16|s[n+2]<<8|s[n+3])>>>0}for(let e=16;e<64;e++){const t=r(i[e-15],7)^r(i[e-15],18)^i[e-15]>>>3,n=r(i[e-2],17)^r(i[e-2],19)^i[e-2]>>>10;i[e]=i[e-16]+t+i[e-7]+n>>>0}let[t,a,o,l,p,d,f,u]=c;for(let e=0;e<64;e++){const s=u+(r(p,6)^r(p,11)^r(p,25))+(p&d^~p&f)+n[e]+i[e]>>>0,c=t&a^t&o^a&o;u=f,f=d,d=p,p=l+s>>>0,l=o,o=a,a=t,t=s+((r(t,2)^r(t,13)^r(t,22))+c>>>0)>>>0}c[0]=c[0]+t>>>0,c[1]=c[1]+a>>>0,c[2]=c[2]+o>>>0,c[3]=c[3]+l>>>0,c[4]=c[4]+p>>>0,c[5]=c[5]+d>>>0,c[6]=c[6]+f>>>0,c[7]=c[7]+u>>>0}return c.map(e=>e.toString(16).padStart(8,"0")).join("")}function c({key:e,title:t,scope:n,scopePaths:r,acceptance:a,sliceType:s,nonGoals:o,baselineGate:c,inheritedReviewerTarget:i=e,version:l=2}){const p={version:l,task:{key:e,title:t,scope:n,acceptance:a,sliceType:s},nonGoals:[...o].sort(),baselineGate:c,inheritedReviewerTarget:i};return l>=2&&(p.task.scopePaths=normalizeTaskScopePaths(r,{fallbackScope:n})),p}export function acceptancePackDigest(e){return o(JSON.stringify(c(e)))}export function normalizeTaskContract(n,{sliceType:r,legacy:s=!1}={}){const o=function(e){const t=e?.contract&&"object"==typeof e.contract&&!Array.isArray(e.contract)?{...e.contract}:{};return void 0===t.nonGoals&&(t.nonGoals=e?.nonGoals??e?.non_goals),void 0===t.baseline&&(t.baseline=e?.baseline??e?.baselineGate??e?.baseline_gate),void 0===t.scopePaths&&(t.scopePaths=e?.scopePaths??e?.scope_paths),t}(n),c=function(e){if(void 0===e.digest)return null;if("string"!=typeof e.digest||!t.test(e.digest))throw new Error("contract digest must be a lowercase SHA-256 hex string");return e.digest}(o),i=function(e){if(void 0===e.acceptancePack)return null;if(!e.acceptancePack||"object"!=typeof e.acceptancePack||Array.isArray(e.acceptancePack))throw new Error("contract acceptance pack must be an object");return e.acceptancePack}(o);if(r===SLICE_TYPE.review)return s?null:{digest:c,acceptancePack:i};const l=!s,p=o.nonGoals,d=null==p?[]:Array.isArray(p)?p:[p];if(d.length>FLOW_CONTRACT_LIMITS.maxNonGoals)throw new Error(`non-goals exceeds ${FLOW_CONTRACT_LIMITS.maxNonGoals} items`);const f=d.map(e=>a(e,"non-goal",FLOW_CONTRACT_LIMITS.maxNonGoalChars,{required:!0}));if(l&&!f.length)throw new Error("explicit non-goals are required for builder/fix/scaffold tasks");const u=o.baseline,g="string"==typeof u?{gate:u}:u;if(null!=g&&("object"!=typeof g||Array.isArray(g)))throw new Error("baseline gate must be a string or object");const h=a(g?.gate??g?.expectation,"baseline gate",FLOW_CONTRACT_LIMITS.maxBaselineGateChars,{required:l});if(h&&!e.test(h))throw new Error("baseline gate must state what fails or is absent before implementation");const y=null==g?.evidence||""===g?.evidence?"":normalizeBaselineEvidence(g.evidence);return{nonGoals:f,baseline:h?{gate:h,evidence:y}:null,scopePaths:normalizeTaskScopePaths(o.scopePaths,{fallbackScope:n?.scope??n?.description??"",required:l}),digest:c,acceptancePack:i}}function i(e,{legacy:t=!1}={}){const n=c({key:e.key,title:e.title,scope:e.scope,scopePaths:e.contract.scopePaths,acceptance:e.acceptance,sliceType:e.sliceType,nonGoals:e.contract.nonGoals,baselineGate:e.contract.baseline?.gate||"",inheritedReviewerTarget:e.key,version:t?1:2}),r=o(JSON.stringify(n));if(e.contract.digest&&e.contract.digest!==r)throw new Error(`task "${e.key}" contract digest does not match its acceptance pack`);if(e.contract.acceptancePack&&JSON.stringify(e.contract.acceptancePack)!==JSON.stringify(n))throw new Error(`task "${e.key}" sealed acceptance pack does not match its task fields`);e.contract.digest=r,e.contract.acceptancePack=n}export function validateTaskContractSeal(e,{legacy:t=!1}={}){const n=e?.contract;if(!n?.digest&&t)return!0;if(!n||"object"!=typeof n||!n.digest||!n.acceptancePack)throw new Error("task is missing its sealed acceptance contract");const r=n.acceptancePack,a=r?.task;if(!a||"object"!=typeof a||!Array.isArray(r.nonGoals))throw new Error("task sealed acceptance pack is malformed");const s=c({key:a.key,title:a.title,scope:a.scope,scopePaths:a.scopePaths,acceptance:a.acceptance,sliceType:a.sliceType,nonGoals:r.nonGoals,baselineGate:r.baselineGate,inheritedReviewerTarget:r.inheritedReviewerTarget,version:1===r.version?1:2});if(JSON.stringify(r)!==JSON.stringify(s))throw new Error("task sealed acceptance pack is not canonical");if(acceptancePackDigest({key:a.key,title:a.title,scope:a.scope,scopePaths:a.scopePaths,acceptance:a.acceptance,sliceType:a.sliceType,nonGoals:r.nonGoals,baselineGate:r.baselineGate,inheritedReviewerTarget:r.inheritedReviewerTarget,version:1===r.version?1:2})!==n.digest)throw new Error("task acceptance digest does not match its sealed pack");const o=e.sliceType??e.slice_type,i=e.key??e.task_key,l=Array.isArray(e.deps)?e.deps:[];if(o===SLICE_TYPE.review){if(n.inheritedFrom!==a.key||1!==l.length||l[0]!==a.key)throw new Error("review task no longer targets its sealed builder");if(r.inheritedReviewerTarget!==a.key||e.acceptance!==a.acceptance)throw new Error(`review task "${i}" changed after its builder acceptance pack was sealed`);return!0}const p=c({key:i,title:e.title,scope:e.scope??"",scopePaths:n.scopePaths,acceptance:e.acceptance??"",sliceType:o,nonGoals:n.nonGoals||[],baselineGate:n.baseline?.gate||"",inheritedReviewerTarget:i,version:1===r.version?1:2});if(JSON.stringify(p)!==JSON.stringify(s))throw new Error(`task "${i}" changed after its acceptance pack was sealed`);return!0}export function makeTask({key:e,title:t,scope:n="",acceptance:r="",deps:a=[],sliceType:s=SLICE_TYPE.feature,contract:o=null}){if(!e||"string"!=typeof e)throw new Error("task key required (string)");if(!t)throw new Error("task title required");if(!Array.isArray(a))throw new Error("deps must be an array of task keys");if(!Object.values(SLICE_TYPE).includes(s))throw new Error(`unknown sliceType: ${s}`);return{key:e,title:t,scope:n,acceptance:r,contract:o,deps:a,sliceType:s,status:TASK_STATUS.pending,laneId:null,commitSha:null,failCount:0}}export function validateDag(e){if(!Array.isArray(e)||0===e.length)throw new Error("at least one task required");const t=new Set(e.map(e=>e.key));if(t.size!==e.length)throw new Error("duplicate task keys");const n=new Map(e.map(e=>[e.key,e]));for(const n of e){if(n.deps.includes(n.key))throw new Error(`task "${n.key}" depends on itself`);for(const e of n.deps)if(!t.has(e))throw new Error(`task "${n.key}" depends on unknown task "${e}"`)}const r=new Map(e.map(e=>[e.key,0]));function a(e){r.set(e,1);for(const t of n.get(e).deps){const n=r.get(t);if(1===n)throw new Error(`cycle detected at "${e}" → "${t}"`);0===n&&a(t)}r.set(e,2)}for(const t of e)0===r.get(t.key)&&a(t.key);return e}export function readyTasks(e){const t=new Set(e.filter(e=>e.status===TASK_STATUS.done).map(e=>e.key));return e.filter(e=>e.status===TASK_STATUS.pending&&e.deps.every(e=>t.has(e)))}export function topoOrder(e){validateDag(e);const t=new Map(e.map(e=>[e.key,e.deps.length])),n=new Map(e.map(e=>[e.key,[]]));for(const t of e)for(const e of t.deps)n.get(e).push(t.key);const r=e.filter(e=>0===t.get(e.key)).map(e=>e.key),a=[];for(;r.length;){const e=r.shift();a.push(e);for(const a of n.get(e))t.set(a,t.get(a)-1),0===t.get(a)&&r.push(a)}if(a.length!==e.length)throw new Error("cycle detected (topo incomplete)");return a}export function makeFlowSession({prompt:e,mode:t=FLOW_MODE.guide,sessionRef:n=null,budgetCapAutopilot:r=null}){if(!e)throw new Error("prompt required");if(!Object.values(FLOW_MODE).includes(t))throw new Error(`unknown mode: ${t}`);return{prompt:e,mode:t,sessionRef:n,status:FLOW_STATUS.planning,budgetCapAutopilot:r,createdAt:null,tasks:[]}}export function normalizePlanOutput(e,{legacy:t=!1}={}){let n=e;if("string"==typeof e){let t=e.trim();const r=t.match(/```(?:json)?\s*([\s\S]*?)```/i);r&&(t=r[1].trim()),n=JSON.parse(t)}if(!n||"object"!=typeof n)throw new Error("plan output is not an object");const r="string"==typeof n.summary&&n.summary.trim()?n.summary.trim():"";if(!Array.isArray(n.tasks)||0===n.tasks.length)throw new Error("plan has no tasks");const a=n.tasks.map(e=>{const n=e.key??e.id;if(null==n||!String(n).trim())throw new Error('a task is missing its "key"');const r=e.sliceType??e.slice_type;return makeTask({key:String(n),title:String(e.title??n),scope:String(e.scope??e.description??""),acceptance:String(e.acceptance??""),deps:Array.isArray(e.deps)?e.deps.map(String):[],sliceType:Object.values(SLICE_TYPE).includes(r)?r:SLICE_TYPE.feature,contract:normalizeTaskContract(e,{sliceType:Object.values(SLICE_TYPE).includes(r)?r:SLICE_TYPE.feature,legacy:t})})});validateDag(a);for(const e of a)e.sliceType!==SLICE_TYPE.review&&i(e,{legacy:t});for(const e of a){if(e.sliceType!==SLICE_TYPE.review)continue;if(t)continue;if(1!==e.deps.length)throw new Error(`review task "${e.key}" must depend on exactly one builder task to inherit its contract`);const n=a.find(t=>t.key===e.deps[0]);if(!n||n.sliceType===SLICE_TYPE.review)throw new Error(`review task "${e.key}" must target a builder/fix/scaffold task`);if(e.contract.digest&&e.contract.digest!==n.contract.digest)throw new Error(`review task "${e.key}" contract digest does not match target "${n.key}"`);e.contract={nonGoals:[...n.contract?.nonGoals||[]],baseline:n.contract?.baseline?{...n.contract.baseline}:null,scopePaths:[...n.contract?.scopePaths||[]],inheritedFrom:n.key,digest:n.contract.digest,acceptancePack:n.contract.acceptancePack},e.acceptance=n.contract.acceptancePack.task.acceptance}return{summary:r,tasks:a}}export function validatePlanForRuntime(e,t="claude"){if("codex"!==t&&"hermes"!==t)return e;for(const n of e?.tasks||[])if(n.sliceType===SLICE_TYPE.review&&1!==n.deps.length)throw new Error(`${"hermes"===t?"Hermes":"Codex"} review task "${n.key}" must depend on exactly one builder task`);return e}export function validReviewTargetShape(e,t="claude"){return!e||e.slice_type!==SLICE_TYPE.review||"codex"!==t&&"hermes"!==t||Array.isArray(e.deps)&&1===e.deps.length}export function legacyBuilderCompletionAllowed({runtime:e,flowRole:t,eventKind:n,eventSubtype:r,interrupted:a=!1}={}){return"claude"===e&&"builder"===t&&!a&&"result"===n&&"success"===r}const l={scaffold:"sonnet",feature:"opus",fix:"opus",review:"opus"};export function laneModelFor(e,t=process.env){const n=t.TP_FLOW_LANE_MODEL;if("inherit"!==n)return n||l[e]||"opus"}