thinkpool-pair 0.7.364 → 0.7.366

package/flow-context-store.mjs

@@ -1,387 +1 @@
-// Thinkpool Flow — durable per-lane context-offload store.
-//
-// Three design patterns fused (docs/specs/2026-06-30-flow-build-s1-context-offload.md):
-// • DBOS-style durable steps — each artifact write is idempotent + content-addressed by
-//   (taskKey, name) + sha256; a re-dispatched lane resumes instead of duplicating work.
-// • Headroom-style digest ceiling — the conductor reads one-line summary + pointers per
-//   closed slice, capped at CEILING bytes; never an unbounded transcript.
-// • Statewright-style structural containment — a hard path guard rejects any taskKey or
-//   name that would escape <worktreeDir>/.flow/artifacts/; structural, not an instruction.
-//   Reuses the approach from bridge/flow-assembly.mjs (inlineSingleHtml resolve) and
-//   bridge/flow-preview.mjs (resolveUnderRoot) — two existing containment sites.
-//
-// Pure module — canonical at src/lib/flow/contextStore.js, mirrored byte-identically
-// at bridge/flow-context-store.mjs (same reason as taskGraph / flowBudget: the bridge
-// ships as thinkpool-pair npm package and can't import across the bridge↔src boundary
-// at publish time). Sync: bridge/flow-context-store.sync.test.js.
-//
-// Node built-ins only (node:crypto, node:fs, node:path) — no new deps.
-// All fs calls are injectable ({fs} opts) so logic is unit-testable against temp dirs.
-
-import { createHash } from 'node:crypto'
-import nodeFs from 'node:fs'
-import path from 'node:path'
-
-// Hard ceiling for the conductor's assembled digest context (bytes of serialized JSON).
-// When accumulated size would exceed CEILING, each over-budget entry is truncated to
-// { taskKey, summary, pointers } — never drops a pointer, never silently grows past this.
-export const CEILING = 32 * 1024  // 32 KB
-
-// ── containment ──────────────────────────────────────────────────────────────
-// Resolve `segments` under `base`. Returns the absolute path iff it stays strictly
-// inside `base`, otherwise null. Same approach as flow-assembly.mjs (inlineSingleHtml
-// resolve) and flow-preview.mjs (resolveUnderRoot) — reused, not re-invented.
-//
-// STRUCTURAL (not ENOENT-based): every rejection is a pure string-level check that
-// fires before any filesystem call. Do not add fs.exists/stat calls here.
-function containedPath (base, ...segments) {
-  for (const seg of segments) {
-    if (!seg || typeof seg !== 'string') return null
-    if (path.isAbsolute(seg)) return null
-    if (seg.includes('\0')) return null
-    // STRUCTURAL: reject any segment that contains a path separator character.
-    // Prevents 'real/link/escape' and 'a/../../evil' from normalising into a valid
-    // sub-path without escaping the per-entry rel-check below. This is the key
-    // structural gate — no ENOENT dependency.
-    if (seg.includes('/') || seg.includes('\\')) return null
-    // STRUCTURAL: reject bare '.' and '..' as full segments (belt-and-suspenders;
-    // the rel.startsWith('..') check below would also catch '..' after path.join).
-    if (seg === '..' || seg === '.') return null
-    // Reject zero-width / Unicode format chars (ZWSP U+200B, ZWNJ U+200C, etc.):
-    // trim() does NOT strip them; require at least one real identifier char.
-    if (!/[A-Za-z0-9_.-]/.test(seg)) return null
-  }
-  const joined = path.join(...segments)
-  const abs = path.resolve(base, joined)
-  const rel = path.relative(base, abs)
-  // rel === '' means abs === base (the directory itself) — not a valid write target
-  if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) return null
-  return abs
-}
-
-// ── safeSegmentId ─────────────────────────────────────────────────────────────
-// Validate that `val` is a safe single path-segment identifier (used for flowId).
-// Rejects: null/non-string, empty, whitespace-only, null bytes, absolute paths,
-// path separators (/ or \), bare '.' or '..'. Prevents flowId from escaping the
-// digest base directory when interpolated into path.join calls.
-function safeSegmentId (val) {
-  if (!val || typeof val !== 'string') return false
-  if (!val.trim()) return false
-  if (val.includes('\0')) return false
-  if (path.isAbsolute(val)) return false
-  if (val.includes('/') || val.includes('\\')) return false
-  if (val === '..' || val === '.') return false
-  // Reject zero-width / Unicode format chars (ZWSP U+200B, ZWNJ U+200C, etc.):
-  // trim() does NOT strip them; require at least one real identifier char.
-  if (!/[A-Za-z0-9_.-]/.test(val)) return false
-  return true
-}
-
-// ── assertLeafContained ────────────────────────────────────────────────────────
-// Leaf-level (final-component) containment for a WRITE target — the artifact file or
-// the digest .jsonl. The dir-level realpathSync guards in the callers contain the
-// PARENT directory, but fs.writeFileSync / fs.appendFileSync follow a symlink planted
-// AT the leaf itself, so a symlink at <dest> would let the write escape an
-// already-contained directory. realpathSync(dir) never inspects the leaf's own type —
-// only lstatSync does, because it does NOT follow the final component. It reveals the
-// leaf as a symlink regardless of what the link points at, which is why one check
-// covers all three escape flavors:
-//   • ENOENT   → no leaf yet; the write will create a regular file → safe, return.
-//   • symlink  → reject (absolute-, relative-, AND chained-target symlinks alike —
-//                lstat stops at the first hop, so a symlink→symlink→victim chain and a
-//                relative "../../.." target are both caught here).
-//   • regular  → realpathSync must still resolve strictly under `canonicalDir`.
-// Must be called BEFORE any idempotency readFileSync of the leaf (which would itself
-// follow a leaf symlink). This is the leaf half of containment; the dir half stays in
-// the callers (writeLaneArtifact / appendDigest). (B5 breaks 1-3.)
-function assertLeafContained (fs, leafPath, canonicalDir) {
-  let st
-  try {
-    st = fs.lstatSync(leafPath)
-  } catch (e) {
-    if (e && e.code === 'ENOENT') return  // leaf absent — write creates a regular file
-    throw e
-  }
-  if (st.isSymbolicLink()) {
-    throw new Error(`symlink escape: refusing to write through a symlink at leaf "${leafPath}"`)
-  }
-  // Non-symlink leaf: re-verify its real path is still strictly inside the canonical dir.
-  const real = fs.realpathSync(leafPath)
-  if (!real.startsWith(canonicalDir + path.sep)) {
-    throw new Error(`symlink escape: resolved leaf "${real}" escapes canonical dir "${canonicalDir}"`)
-  }
-}
-
-// ── writeLaneArtifact ─────────────────────────────────────────────────────────
-// Write `content` (string | Buffer) under <worktreeDir>/.flow/artifacts/<taskKey>/<name>.
-// Returns { path, bytes, sha } where sha is the sha256 hex of the content.
-//
-// IDEMPOTENT: if (taskKey, name) already holds byte-identical content, skips the write
-// and returns the same { path, bytes, sha }. Safe to call multiple times on the same
-// artifact — a re-dispatched lane writing what's already there is a no-op.
-//
-// STRUCTURAL PATH GUARD: rejects any taskKey or name that would escape the artifacts
-// base (no '..', no absolute paths, no null bytes, no path separators, no whitespace-only).
-// Throws on violation before any filesystem call is made.
-//
-// REALPATH CONTAINMENT GUARD (directory level): after the structural string checks and
-// mkdirSync, resolves the real path of taskDir via fs.realpathSync and verifies it is
-// still inside the canonical artifacts root (fs.realpathSync(worktreeDir) +
-// '/.flow/artifacts'). Catches symlinks planted at any DIRECTORY level — .flow,
-// .flow/artifacts, or the taskKey dir — in one pass.
-//
-// LEAF CONTAINMENT GUARD (file level): the dir guard cannot see a symlink planted at the
-// dest file itself (realpathSync(dir) never inspects the leaf's type). assertLeafContained
-// lstat's the dest and rejects a leaf symlink — absolute-, relative-, or chained-target —
-// before fs.writeFileSync (or the idempotency readFileSync) can follow it out of the dir.
-export function writeLaneArtifact (flowId, taskKey, name, content, { worktreeDir, fs = nodeFs } = {}) {
-  if (!flowId || typeof flowId !== 'string') throw new Error('flowId required (string)')
-  if (!taskKey || typeof taskKey !== 'string' || !taskKey.trim()) throw new Error('taskKey required (non-empty string)')
-  if (!name || typeof name !== 'string' || !name.trim()) throw new Error('name required (non-empty string)')
-  if (!worktreeDir) throw new Error('worktreeDir required')
-
-  const artifactsBase = path.join(worktreeDir, '.flow', 'artifacts')
-
-  const taskDir = containedPath(artifactsBase, taskKey)
-  if (!taskDir) throw new Error(`taskKey "${taskKey}" rejected — path escapes artifacts base or is invalid`)
-
-  const dest = containedPath(artifactsBase, taskKey, name)
-  if (!dest) throw new Error(`name "${name}" rejected — path escapes artifacts base or is invalid`)
-
-  const buf = Buffer.isBuffer(content) ? content : Buffer.from(content)
-  const sha = createHash('sha256').update(buf).digest('hex')
-
-  fs.mkdirSync(taskDir, { recursive: true })
-
-  // REALPATH CONTAINMENT (directory level): after mkdirSync, resolve the real path of
-  // taskDir and verify it is still inside the canonical artifacts root.
-  // fs.realpathSync(worktreeDir) handles the case where the worktree itself lives under a
-  // legitimately-symlinked path; the canonical root is then built as a plain string (no
-  // further symlink-following), so a symlink planted at .flow, .flow/artifacts, or the
-  // taskKey directory is caught in one structural pass — its resolved path escapes the
-  // canonical root, and we throw.
-  // Replaces the per-position lstatSync whack-a-mole (was: check taskDir, check dest).
-  const canonicalWorktreeDir = fs.realpathSync(worktreeDir)
-  const canonicalRoot = path.join(canonicalWorktreeDir, '.flow', 'artifacts')
-  const canonicalTaskDir = fs.realpathSync(taskDir)
-  if (!canonicalTaskDir.startsWith(canonicalRoot + path.sep)) {
-    throw new Error(
-      `symlink escape: resolved path "${canonicalTaskDir}" escapes ` +
-      `canonical artifacts root "${canonicalRoot}"`
-    )
-  }
-
-  // LEAF CONTAINMENT (file level): the dir guard above contains the directory, but
-  // fs.writeFileSync follows a symlink planted AT the dest file itself — a symlink at
-  // <taskDir>/<name> (absolute-, relative-, or chained-target) would let the write escape
-  // the contained dir. Must run BEFORE the idempotency read below, which also follows a
-  // leaf symlink via readFileSync. (B5 breaks 1 & 3.)
-  assertLeafContained(fs, dest, canonicalTaskDir)
-
-  // Idempotency: if file already exists with identical bytes, skip the write.
-  // Safe now — assertLeafContained has proven dest is a regular file (or absent).
-  if (fs.existsSync(dest)) {
-    const existing = fs.readFileSync(dest)
-    if (existing.equals(buf)) return { path: dest, bytes: buf.length, sha }
-  }
-
-  fs.writeFileSync(dest, buf)
-  return { path: dest, bytes: buf.length, sha }
-}
-
-// ── digestSlice ───────────────────────────────────────────────────────────────
-// Pure (no fs): compute a digest entry for a closed task. Returns { taskKey, summary,
-// acceptanceProof, pointers }. Callers persist via appendDigest; the conductor reads
-// back via loadDigest with the CEILING compression applied.
-//
-// summary:  a single line, <= 120 chars: "[taskKey] title" optionally with the first
-//           line of acceptanceProof appended. Guaranteed to contain no newlines.
-// pointers: [{ taskKey, name, path, sha }] from the artifacts written during the task.
-//           Artifacts whose taskKey/name/path/sha are missing/empty/undefined are
-//           silently dropped — prevents String(undefined) = "undefined" from leaking
-//           into pointer fields (DG-3).
-export function digestSlice (task, { acceptanceProof = '', artifacts = [] } = {}) {
-  if (!task || !task.key) throw new Error('task with .key required')
-  const base = `[${task.key}] ${task.title ?? task.key}`
-  const firstLine = acceptanceProof ? String(acceptanceProof).split('\n')[0].trim() : ''
-  const summary = (firstLine ? `${base} — ${firstLine}` : base).slice(0, 120)
-  // DG-3: filter out artifacts with any missing/empty/undefined field before mapping.
-  // (artifacts ?? []) handles an explicit null — destructuring default only fires for
-  // undefined; passing artifacts:null leaves artifacts===null here, and null.filter throws.
-  // String(undefined) = "undefined" would produce bogus pointer field values.
-  const pointers = (artifacts ?? [])
-    .filter(a =>
-      a.taskKey != null && String(a.taskKey).trim() &&
-      a.name != null && String(a.name).trim() &&
-      a.path != null && String(a.path).trim() &&
-      a.sha != null && String(a.sha).trim()
-    )
-    .map(a => ({
-      taskKey: String(a.taskKey),
-      name: String(a.name),
-      path: String(a.path),
-      sha: String(a.sha),
-    }))
-  return { taskKey: task.key, summary, acceptanceProof: String(acceptanceProof), pointers }
-}
-
-// ── appendDigest ─────────────────────────────────────────────────────────────
-// Persist a digest entry (from digestSlice) to <baseDir>/.flow/digests/<flowId>.jsonl.
-// Append-only JSONL — insertion order is preserved for loadDigest.
-//
-// FLOWID CONTAINMENT: flowId is validated as a safe single path segment (no traversal,
-// separators, null bytes, or whitespace-only) before being interpolated into the path.
-// Prevents appendDigest('../../../victim', ...) from escaping baseDir (DG-1).
-//
-// LEAF CONTAINMENT: after the dir-level realpath check, assertLeafContained lstat's the
-// <flowId>.jsonl file and rejects a leaf symlink (absolute-, relative-, or chained-target)
-// before fs.appendFileSync can follow it out of the digests dir (B5 break 2).
-//
-// ZERO-POINTER guard: rejects any digest with an empty pointers array. Every persisted
-// entry must have >=1 artifact pointer (invariant d). A task with no artifacts must not
-// call appendDigest — the caller decides whether to skip or synthesize a pointer first.
-//
-// IDEMPOTENT: if the same (flowId, taskKey) is already persisted, this is a no-op.
-// Calling appendDigest twice with the same digest never creates duplicate entries.
-export function appendDigest (flowId, digest, { baseDir, fs = nodeFs } = {}) {
-  if (!safeSegmentId(flowId)) throw new Error(`flowId "${flowId}" rejected — must be a non-empty single path segment (no traversal, separators, or null bytes)`)
-  if (!baseDir) throw new Error('baseDir required')
-  if (!digest || !digest.taskKey) throw new Error('digest.taskKey required')
-  // ZERO-POINTER guard: every persisted digest must carry >=1 valid pointer (invariant d).
-  if (!digest.pointers || digest.pointers.length === 0) {
-    throw new Error(
-      `digest for "${digest.taskKey}" has no pointers — ` +
-      'a closed slice must produce >=1 artifact pointer before persisting'
-    )
-  }
-  const dir = path.join(baseDir, '.flow', 'digests')
-  fs.mkdirSync(dir, { recursive: true })
-
-  // REALPATH CONTAINMENT: verify the resolved digests directory is still under the
-  // canonical base — same one-pass approach as writeLaneArtifact. Catches symlinks
-  // planted at .flow or .flow/digests. fs.realpathSync(baseDir) handles a legitimately-
-  // symlinked base; canonicalDigestsDir is built as a plain string thereafter.
-  const canonicalBase = fs.realpathSync(baseDir)
-  const canonicalDigestsDir = path.join(canonicalBase, '.flow', 'digests')
-  const canonicalDir = fs.realpathSync(dir)
-  if (canonicalDir !== canonicalDigestsDir) {
-    throw new Error(
-      `symlink escape: resolved digests dir "${canonicalDir}" escapes ` +
-      `canonical digests root "${canonicalDigestsDir}"`
-    )
-  }
-
-  const file = path.join(dir, `${flowId}.jsonl`)
-
-  // LEAF CONTAINMENT (file level): the dir guard above contains the digests directory, but
-  // fs.appendFileSync follows a symlink planted AT the <flowId>.jsonl leaf — a symlink
-  // there (absolute-, relative-, or chained-target) would let the append escape the
-  // contained dir. Must run BEFORE the idempotency readFileSync below, which also follows
-  // a leaf symlink. (B5 break 2.)
-  assertLeafContained(fs, file, canonicalDir)
-
-  // IDEMPOTENCY: skip if the same taskKey is already persisted for this flowId.
-  // Re-digesting the same (flowId, taskKey) is a no-op — no duplicate lines.
-  if (fs.existsSync(file)) {
-    const lines = String(fs.readFileSync(file, 'utf8')).split('\n').filter(l => l.trim())
-    for (const line of lines) {
-      try {
-        if (JSON.parse(line).taskKey === digest.taskKey) return
-      } catch { /* skip malformed lines */ }
-    }
-  }
-  fs.appendFileSync(file, JSON.stringify(digest) + '\n')
-}
-
-// ── loadDigest ────────────────────────────────────────────────────────────────
-// Load all closed-slice digests for `flowId` from <baseDir>/.flow/digests/<flowId>.jsonl,
-// applying the hard CEILING compression:
-//   • While accumulated serialized size + full-entry length <= CEILING → include full entry
-//   • Else if slim (no acceptanceProof) fits → include slim
-//   • Else → drop the entry; never exceed CEILING
-//
-// FLOWID CONTAINMENT: flowId is validated as a safe single path segment before use
-// in path construction — same rule as appendDigest (DG-1).
-//
-// CEILING tracking is exact: accumulated == JSON.stringify(result).length at all times,
-// accounting for the outer '['/']' and comma separators between entries.
-//
-// Dedup by taskKey (first occurrence wins) and skips zero-pointer entries for safety
-// against old data that may pre-date the appendDigest zero-pointer guard.
-//
-// Returns digests in insertion order. Total JSON.stringify(result).length <= CEILING.
-export function loadDigest (flowId, { baseDir, fs = nodeFs } = {}) {
-  if (!safeSegmentId(flowId)) throw new Error(`flowId "${flowId}" rejected — must be a non-empty single path segment (no traversal, separators, or null bytes)`)
-  if (!baseDir) throw new Error('baseDir required')
-  const file = path.join(baseDir, '.flow', 'digests', `${flowId}.jsonl`)
-  if (!fs.existsSync(file)) return []
-  const lines = String(fs.readFileSync(file, 'utf8')).split('\n').filter(l => l.trim())
-  const result = []
-  const seen = new Set()  // dedup by taskKey — first occurrence wins
-  // Track exact JSON.stringify(result).length:
-  //   '[' entries.join(',') ']' = 2 + sum(entryLen) + (n-1 commas)
-  // Start at 2 for the outer brackets. Each entry adds (comma if not first) + entryLen.
-  // Invariant: accumulated === JSON.stringify(result).length after every push.
-  let accumulated = 2  // '[' + ']'
-  for (const line of lines) {
-    let entry
-    try { entry = JSON.parse(line) } catch { continue }
-    if (!entry.taskKey) continue
-    // Dedup: appendDigest should prevent duplicates, but guard here for old data
-    if (seen.has(entry.taskKey)) continue
-    // Safety: skip zero-pointer entries (appendDigest now rejects them, but old JSONL may have them)
-    if (!entry.pointers || entry.pointers.length === 0) continue
-    seen.add(entry.taskKey)
-    const slim = { taskKey: entry.taskKey, summary: entry.summary, pointers: entry.pointers }
-    const comma = result.length > 0 ? 1 : 0  // comma separator before every entry except the first
-    const fullLen = line.length
-    const slimLen = JSON.stringify(slim).length
-    if (accumulated + comma + fullLen <= CEILING) {
-      result.push(entry)
-      accumulated += comma + fullLen
-    } else if (accumulated + comma + slimLen <= CEILING) {
-      // Full would exceed ceiling: emit the slim form (never drop the pointer)
-      result.push(slim)
-      accumulated += comma + slimLen
-    }
-    // else: neither full nor slim fits within CEILING — drop this entry.
-    // The hard guarantee: JSON.stringify(result).length <= CEILING always holds.
-  }
-  return result
-}
-
-// ── resumeLane ────────────────────────────────────────────────────────────────
-// Re-read a lane's own prior artifacts from <worktreeDir>/.flow/artifacts/.
-// Returns an array of { taskKey, name, path, bytes, sha } — identical to what
-// writeLaneArtifact would have returned for each artifact originally written.
-//
-// IDEMPOTENT: calling multiple times on the same worktree gives the same result.
-// A re-dispatched lane calls this on startup to reconstruct its prior state without
-// redoing any writes. Artifacts whose files are unreadable are silently skipped.
-export function resumeLane (flowId, { worktreeDir, fs = nodeFs } = {}) {
-  if (!flowId) throw new Error('flowId required')
-  if (!worktreeDir) throw new Error('worktreeDir required')
-  const artifactsBase = path.join(worktreeDir, '.flow', 'artifacts')
-  if (!fs.existsSync(artifactsBase)) return []
-  // [SCOPE: accepted] The read path here is intentionally NOT realpath-checked.
-  // resumeLane reads artifacts but does not write; traversing a symlink-redirected path
-  // cannot exfiltrate data the caller couldn't already read by other means. The worktree
-  // is trusted, non-shared, and single-user by design (git worktree, browser-side flow).
-  // The WRITE path in writeLaneArtifact IS realpath-checked — that's where containment
-  // matters. If the threat model changes (multi-user, shared fs), add realpath here too.
-  const artifacts = []
-  for (const taskKey of fs.readdirSync(artifactsBase)) {
-    const taskDirPath = path.join(artifactsBase, taskKey)
-    let stat
-    try { stat = fs.statSync(taskDirPath) } catch { continue }
-    if (!stat.isDirectory()) continue
-    for (const name of fs.readdirSync(taskDirPath)) {
-      const filePath = path.join(taskDirPath, name)
-      let buf
-      try { buf = fs.readFileSync(filePath) } catch { continue }
-      const sha = createHash('sha256').update(buf).digest('hex')
-      artifacts.push({ taskKey, name, path: filePath, bytes: buf.length, sha })
-    }
-  }
-  return artifacts
-}
+import{createHash as t}from"node:crypto";import e from"node:fs";import r from"node:path";export const CEILING=32768;function n(t,...e){for(const t of e){if(!t||"string"!=typeof t)return null;if(r.isAbsolute(t))return null;if(t.includes("\0"))return null;if(t.includes("/")||t.includes("\\"))return null;if(".."===t||"."===t)return null;if(!/[A-Za-z0-9_.-]/.test(t))return null}const n=r.join(...e),i=r.resolve(t,n),s=r.relative(t,i);return""===s||s.startsWith("..")||r.isAbsolute(s)?null:i}function i(t){return!(!t||"string"!=typeof t||!t.trim()||t.includes("\0")||r.isAbsolute(t)||t.includes("/")||t.includes("\\")||".."===t||"."===t||!/[A-Za-z0-9_.-]/.test(t))}function s(t,e,n){let i;try{i=t.lstatSync(e)}catch(t){if(t&&"ENOENT"===t.code)return;throw t}if(i.isSymbolicLink())throw new Error(`symlink escape: refusing to write through a symlink at leaf "${e}"`);const s=t.realpathSync(e);if(!s.startsWith(n+r.sep))throw new Error(`symlink escape: resolved leaf "${s}" escapes canonical dir "${n}"`)}export function writeLaneArtifact(i,o,a,c,{worktreeDir:l,fs:f=e}={}){if(!i||"string"!=typeof i)throw new Error("flowId required (string)");if(!o||"string"!=typeof o||!o.trim())throw new Error("taskKey required (non-empty string)");if(!a||"string"!=typeof a||!a.trim())throw new Error("name required (non-empty string)");if(!l)throw new Error("worktreeDir required");const u=r.join(l,".flow","artifacts"),p=n(u,o);if(!p)throw new Error(`taskKey "${o}" rejected — path escapes artifacts base or is invalid`);const y=n(u,o,a);if(!y)throw new Error(`name "${a}" rejected — path escapes artifacts base or is invalid`);const h=Buffer.isBuffer(c)?c:Buffer.from(c),d=t("sha256").update(h).digest("hex");f.mkdirSync(p,{recursive:!0});const w=f.realpathSync(l),m=r.join(w,".flow","artifacts"),g=f.realpathSync(p);if(!g.startsWith(m+r.sep))throw new Error(`symlink escape: resolved path "${g}" escapes canonical artifacts root "${m}"`);return s(f,y,g),f.existsSync(y)&&f.readFileSync(y).equals(h)||f.writeFileSync(y,h),{path:y,bytes:h.length,sha:d}}export function digestSlice(t,{acceptanceProof:e="",artifacts:r=[]}={}){if(!t||!t.key)throw new Error("task with .key required");const n=`[${t.key}] ${t.title??t.key}`,i=e?String(e).split("\n")[0].trim():"",s=(i?`${n} — ${i}`:n).slice(0,120),o=(r??[]).filter(t=>null!=t.taskKey&&String(t.taskKey).trim()&&null!=t.name&&String(t.name).trim()&&null!=t.path&&String(t.path).trim()&&null!=t.sha&&String(t.sha).trim()).map(t=>({taskKey:String(t.taskKey),name:String(t.name),path:String(t.path),sha:String(t.sha)}));return{taskKey:t.key,summary:s,acceptanceProof:String(e),pointers:o}}export function appendDigest(t,n,{baseDir:o,fs:a=e}={}){if(!i(t))throw new Error(`flowId "${t}" rejected — must be a non-empty single path segment (no traversal, separators, or null bytes)`);if(!o)throw new Error("baseDir required");if(!n||!n.taskKey)throw new Error("digest.taskKey required");if(!n.pointers||0===n.pointers.length)throw new Error(`digest for "${n.taskKey}" has no pointers — a closed slice must produce >=1 artifact pointer before persisting`);const c=r.join(o,".flow","digests");a.mkdirSync(c,{recursive:!0});const l=a.realpathSync(o),f=r.join(l,".flow","digests"),u=a.realpathSync(c);if(u!==f)throw new Error(`symlink escape: resolved digests dir "${u}" escapes canonical digests root "${f}"`);const p=r.join(c,`${t}.jsonl`);if(s(a,p,u),a.existsSync(p)){const t=String(a.readFileSync(p,"utf8")).split("\n").filter(t=>t.trim());for(const e of t)try{if(JSON.parse(e).taskKey===n.taskKey)return}catch{}}a.appendFileSync(p,JSON.stringify(n)+"\n")}export function loadDigest(t,{baseDir:n,fs:s=e}={}){if(!i(t))throw new Error(`flowId "${t}" rejected — must be a non-empty single path segment (no traversal, separators, or null bytes)`);if(!n)throw new Error("baseDir required");const o=r.join(n,".flow","digests",`${t}.jsonl`);if(!s.existsSync(o))return[];const a=String(s.readFileSync(o,"utf8")).split("\n").filter(t=>t.trim()),c=[],l=new Set;let f=2;for(const t of a){let e;try{e=JSON.parse(t)}catch{continue}if(!e.taskKey)continue;if(l.has(e.taskKey))continue;if(!e.pointers||0===e.pointers.length)continue;l.add(e.taskKey);const r={taskKey:e.taskKey,summary:e.summary,pointers:e.pointers},n=c.length>0?1:0,i=t.length,s=JSON.stringify(r).length;f+n+i<=32768?(c.push(e),f+=n+i):f+n+s<=32768&&(c.push(r),f+=n+s)}return c}export function resumeLane(n,{worktreeDir:i,fs:s=e}={}){if(!n)throw new Error("flowId required");if(!i)throw new Error("worktreeDir required");const o=r.join(i,".flow","artifacts");if(!s.existsSync(o))return[];const a=[];for(const e of s.readdirSync(o)){const n=r.join(o,e);let i;try{i=s.statSync(n)}catch{continue}if(i.isDirectory())for(const i of s.readdirSync(n)){const o=r.join(n,i);let c;try{c=s.readFileSync(o)}catch{continue}const l=t("sha256").update(c).digest("hex");a.push({taskKey:e,name:i,path:o,bytes:c.length,sha:l})}}return a}

package/flow-host-revert.mjs

@@ -1,42 +1 @@
-// Host-owned Flow revert lifecycle. Supabase broadcast channels use self:false,
-// so a reviewer on this bridge must call this handler directly; remote broadcasts
-// delegate to the same function.
-export async function executeFlowRevert({
-  payload,
-  bridgeName,
-  lanes = [],
-  prepareLane,
-  rememberRedispatch,
-  endLane,
-  stopPreview,
-  revert,
-  broadcastReverted,
-  wait = () => Promise.resolve(),
-  onPrepError = () => {},
-} = {}) {
-  if (!payload?.flowId || !payload?.taskKey) return { ok: false, ignored: 'invalid' }
-  if (payload.host && payload.host !== bridgeName) return { ok: false, ignored: 'wrong-host' }
-  let killed = false
-  for (const [laneId, entry] of lanes) {
-    if (entry?.flowSessionId !== payload.flowId || entry?.flowTaskKey !== payload.taskKey || entry?.flowDone) continue
-    try {
-      const prepared = prepareLane?.(entry, payload)
-      if (prepared) rememberRedispatch?.(prepared, entry, payload)
-    } catch (error) { onPrepError(error, entry, payload) }
-    entry.flowDone = true
-    endLane?.(laneId, entry)
-    stopPreview?.(payload.flowId, laneId)
-    killed = true
-  }
-  if (killed) await wait()
-  const reverted = await revert(payload)
-  const result = {
-    ok: true,
-    flowId: payload.flowId,
-    taskKey: payload.taskKey,
-    reviewTaskKey: payload.reviewTaskKey || null,
-    branch: reverted?.branch || null,
-  }
-  await broadcastReverted(result)
-  return result
-}
+export async function executeFlowRevert({payload:e,bridgeName:o,lanes:r=[],prepareLane:a,rememberRedispatch:t,endLane:n,stopPreview:s,revert:i,broadcastReverted:l,wait:w=()=>Promise.resolve(),onPrepError:d=()=>{}}={}){if(!e?.flowId||!e?.taskKey)return{ok:!1,ignored:"invalid"};if(e.host&&e.host!==o)return{ok:!1,ignored:"wrong-host"};let f=!1;for(const[o,i]of r)if(i?.flowSessionId===e.flowId&&i?.flowTaskKey===e.taskKey&&!i?.flowDone){try{const o=a?.(i,e);o&&t?.(o,i,e)}catch(o){d(o,i,e)}i.flowDone=!0,n?.(o,i),s?.(e.flowId,o),f=!0}f&&await w();const c=await i(e),k={ok:!0,flowId:e.flowId,taskKey:e.taskKey,reviewTaskKey:e.reviewTaskKey||null,branch:c?.branch||null};return await l(k),k}

package/flow-models.mjs

@@ -1,139 +1 @@
-// Runtime-aware model routing for Flow and ordinary room cascades.
-// Pure over the supplied environment/catalog so the bridge never sends a model slug
-// that the selected runtime did not advertise.
-
-const CLAUDE_TIERS = {
-  scaffold: 'sonnet',
-  feature: 'opus',
-  fix: 'opus',
-  review: 'opus',
-}
-
-const CODEX_SCAFFOLD = ['gpt-5.6-luna', 'gpt-5.4-mini', 'gpt-5.3-codex-spark']
-const CODEX_BALANCED = ['gpt-5.6-terra', 'gpt-5.4']
-const HERMES_REVIEW = ['nous:anthropic/claude-sonnet-4.6', 'nous:anthropic/claude-sonnet-4.5', 'nous:anthropic/claude-sonnet-4']
-const HERMES_MODEL_ALIASES = Object.freeze({
-  fable: 'nous:anthropic/claude-fable-5',
-})
-
-export function normalizeFlowRuntime(runtime, fallback = null) {
-  if (runtime === 'claude' || runtime === 'codex' || runtime === 'hermes') return runtime
-  return fallback === 'claude' || fallback === 'codex' || fallback === 'hermes' ? fallback : null
-}
-
-export function modelCatalogValues(catalog = []) {
-  return new Set((Array.isArray(catalog) ? catalog : []).map((model) => (
-    typeof model === 'string' ? model : model?.value || model?.slug
-  )).filter(Boolean))
-}
-
-const exactHermesModelId = (value) => /^[A-Za-z0-9._-]+:[A-Za-z0-9._-]+\/[A-Za-z0-9._:/-]+$/.test(value)
-const exactNousModelId = (value) => /^nous:/i.test(value) && exactHermesModelId(value)
-
-const expandHermesModelAlias = (value) => {
-  const named = HERMES_MODEL_ALIASES[value.toLowerCase()]
-  if (named) return named
-  if (/^glm[-_.]/i.test(value)) return `nous:z-ai/${value.toLowerCase()}`
-  const shorthand = value.match(/^([^:/]+):([^/]+)$/)
-  if (!shorthand) return value
-  const provider = shorthand[1].toLowerCase() === 'zai' ? 'z-ai' : shorthand[1].toLowerCase()
-  return `nous:${provider}/${shorthand[2]}`
-}
-
-/**
- * Resolve a Hermes model for any bridge opener. A Hermes parent has a live ACP
- * catalog and remains strict. Other runtimes may use a full id or unambiguous
- * shorthand; the child session acknowledges session/set_model before inference.
- * Omitting a model intentionally selects the isolated Hermes profile default.
- */
-export function resolveHermesOpenModel(model, catalog = [], { strictCatalog = false } = {}) {
-  const requested = String(model || '').trim()
-  if (!requested) return { ok: true, model: undefined, validatedBy: 'default' }
-  const values = [...modelCatalogValues(catalog)]
-  if (values.includes(requested) && exactNousModelId(requested)) return { ok: true, model: requested, validatedBy: 'catalog' }
-
-  const expanded = expandHermesModelAlias(requested)
-  const normalized = (value) => String(value).toLowerCase().replace(/[^a-z0-9]+/g, '')
-  const requestedKey = normalized(expanded).replace(/^nous/, '')
-  const aliases = values.filter((value) => normalized(value).replace(/^nous/, '') === requestedKey)
-  if (aliases.length === 1 && exactNousModelId(aliases[0])) return { ok: true, model: aliases[0], validatedBy: 'catalog' }
-  if (strictCatalog && values.length) return { ok: false, error: `Could not open a Hermes terminal on ${JSON.stringify(requested)} — that model is not in this session's ACP catalog.` }
-  if (!exactNousModelId(expanded)) return { ok: false, error: `Could not resolve Hermes model ${JSON.stringify(requested)}. ThinkPool Hermes only routes through Nous Portal; use a full ACP model ID such as "nous:z-ai/glm-5.2".` }
-  return { ok: true, model: expanded, validatedBy: 'child-runtime' }
-}
-
-function firstVisible(candidates, catalog) {
-  const visible = modelCatalogValues(catalog)
-  for (const candidate of candidates) if (visible.has(candidate)) return candidate
-  if (candidates === CODEX_SCAFFOLD) {
-    for (const model of visible) if (/spark/i.test(model)) return model
-  }
-  return undefined
-}
-
-function firstVisibleMatching(catalog, patterns) {
-  const visible = modelCatalogValues(catalog)
-  for (const pattern of patterns) for (const model of visible) if (pattern.test(model)) return model
-  return undefined
-}
-
-export function flowLaneModelFor({ sliceType, runtime = 'claude', catalog = [], env = process.env } = {}) {
-  if (normalizeFlowRuntime(runtime, 'claude') === 'codex') {
-    const override = env.TP_FLOW_CODEX_LANE_MODEL
-    if (override === 'inherit') return undefined
-    if (override) return modelCatalogValues(catalog).has(override) ? override : undefined
-    return firstVisible(sliceType === 'scaffold' ? CODEX_SCAFFOLD : CODEX_BALANCED, catalog)
-  }
-  if (normalizeFlowRuntime(runtime, 'claude') === 'hermes') {
-    const override = env.TP_FLOW_HERMES_LANE_MODEL
-    const visible = modelCatalogValues(catalog)
-    if (override === 'inherit') return undefined
-    if (override) return visible.has(override) ? override : undefined
-    if (sliceType === 'review') return firstVisible(HERMES_REVIEW, catalog)
-      || firstVisibleMatching(catalog, [/terra/i, /sonnet/i, /balanced/i])
-    if (sliceType === 'scaffold') return firstVisibleMatching(catalog, [/(?:luna|mini)/i])
-    return firstVisibleMatching(catalog, [/terra/i, /(?:luna|mini)/i])
-  }
-  const override = env.TP_FLOW_CLAUDE_LANE_MODEL || env.TP_FLOW_LANE_MODEL
-  if (override === 'inherit') return undefined
-  if (override) return override
-  return CLAUDE_TIERS[sliceType] || 'opus'
-}
-
-export function flowConductorModelFor({ runtime = 'claude', originModel, catalog = [], env = process.env } = {}) {
-  if (normalizeFlowRuntime(runtime, 'claude') === 'codex') {
-    const override = env.TP_FLOW_CODEX_CONDUCTOR_MODEL
-    if (override === 'inherit') return undefined
-    const visible = modelCatalogValues(catalog)
-    if (override) return visible.has(override) ? override : undefined
-    return originModel && visible.has(originModel) ? originModel : undefined
-  }
-  if (normalizeFlowRuntime(runtime, 'claude') === 'hermes') {
-    const override = env.TP_FLOW_HERMES_CONDUCTOR_MODEL
-    const visible = modelCatalogValues(catalog)
-    if (override === 'inherit') return undefined
-    if (override) return visible.has(override) ? override : undefined
-    return originModel && visible.has(originModel) ? originModel : undefined
-  }
-  const override = env.TP_FLOW_CLAUDE_CONDUCTOR_MODEL || env.TP_FLOW_CONDUCTOR_MODEL
-  if (override === 'inherit') return undefined
-  // Claude non-regression: the conductor historically inherited the host default,
-  // not the invoking lane's selected model.
-  return override || undefined
-}
-
-export function spawnedLaneModelFor({ explicitModel, sliceType, runtime = 'claude', catalog = [], env = process.env } = {}) {
-  return explicitModel || flowLaneModelFor({ sliceType, runtime, catalog, env })
-}
-
-export function resolveCodexModel(requested, catalog = []) {
-  if (!requested) return undefined
-  return modelCatalogValues(catalog).has(requested) ? requested : undefined
-}
-
-export function assertRuntimeModelCompatible({ runtime = 'claude', provider = null, model } = {}) {
-  if (runtime === 'claude' && (!provider || provider === 'anthropic') && /^gpt-/i.test(String(model || ''))) {
-    throw new Error(`Codex model ${JSON.stringify(model)} cannot run on the built-in Claude provider`)
-  }
-  return true
-}
+const e={scaffold:"sonnet",feature:"opus",fix:"opus",review:"opus"},o=["gpt-5.6-luna","gpt-5.4-mini","gpt-5.3-codex-spark"],t=["gpt-5.6-terra","gpt-5.4"],n=["nous:anthropic/claude-sonnet-4.6","nous:anthropic/claude-sonnet-4.5","nous:anthropic/claude-sonnet-4"],r=Object.freeze({fable:"nous:anthropic/claude-fable-5"});export function normalizeFlowRuntime(e,o=null){return"claude"===e||"codex"===e||"hermes"===e?e:"claude"===o||"codex"===o||"hermes"===o?o:null}export function modelCatalogValues(e=[]){return new Set((Array.isArray(e)?e:[]).map(e=>"string"==typeof e?e:e?.value||e?.slug).filter(Boolean))}const a=e=>/^nous:/i.test(e)&&(e=>/^[A-Za-z0-9._-]+:[A-Za-z0-9._-]+\/[A-Za-z0-9._:/-]+$/.test(e))(e);export function resolveHermesOpenModel(e,o=[],{strictCatalog:t=!1}={}){const n=String(e||"").trim();if(!n)return{ok:!0,model:void 0,validatedBy:"default"};const i=[...modelCatalogValues(o)];if(i.includes(n)&&a(n))return{ok:!0,model:n,validatedBy:"catalog"};const l=(e=>{const o=r[e.toLowerCase()];if(o)return o;if(/^glm[-_.]/i.test(e))return`nous:z-ai/${e.toLowerCase()}`;const t=e.match(/^([^:/]+):([^/]+)$/);return t?`nous:${"zai"===t[1].toLowerCase()?"z-ai":t[1].toLowerCase()}/${t[2]}`:e})(n),s=e=>String(e).toLowerCase().replace(/[^a-z0-9]+/g,""),u=s(l).replace(/^nous/,""),c=i.filter(e=>s(e).replace(/^nous/,"")===u);return 1===c.length&&a(c[0])?{ok:!0,model:c[0],validatedBy:"catalog"}:t&&i.length?{ok:!1,error:`Could not open a Hermes terminal on ${JSON.stringify(n)} — that model is not in this session's ACP catalog.`}:a(l)?{ok:!0,model:l,validatedBy:"child-runtime"}:{ok:!1,error:`Could not resolve Hermes model ${JSON.stringify(n)}. ThinkPool Hermes only routes through Nous Portal; use a full ACP model ID such as "nous:z-ai/glm-5.2".`}}function i(e,t){const n=modelCatalogValues(t);for(const o of e)if(n.has(o))return o;if(e===o)for(const e of n)if(/spark/i.test(e))return e}function l(e,o){const t=modelCatalogValues(e);for(const e of o)for(const o of t)if(e.test(o))return o}export function flowLaneModelFor({sliceType:r,runtime:a="claude",catalog:s=[],env:u=process.env}={}){if("codex"===normalizeFlowRuntime(a,"claude")){const e=u.TP_FLOW_CODEX_LANE_MODEL;if("inherit"===e)return;return e?modelCatalogValues(s).has(e)?e:void 0:i("scaffold"===r?o:t,s)}if("hermes"===normalizeFlowRuntime(a,"claude")){const e=u.TP_FLOW_HERMES_LANE_MODEL,o=modelCatalogValues(s);if("inherit"===e)return;return e?o.has(e)?e:void 0:"review"===r?i(n,s)||l(s,[/terra/i,/sonnet/i,/balanced/i]):l(s,"scaffold"===r?[/(?:luna|mini)/i]:[/terra/i,/(?:luna|mini)/i])}const c=u.TP_FLOW_CLAUDE_LANE_MODEL||u.TP_FLOW_LANE_MODEL;if("inherit"!==c)return c||e[r]||"opus"}export function flowConductorModelFor({runtime:e="claude",originModel:o,catalog:t=[],env:n=process.env}={}){if("codex"===normalizeFlowRuntime(e,"claude")){const e=n.TP_FLOW_CODEX_CONDUCTOR_MODEL;if("inherit"===e)return;const r=modelCatalogValues(t);return e?r.has(e)?e:void 0:o&&r.has(o)?o:void 0}if("hermes"===normalizeFlowRuntime(e,"claude")){const e=n.TP_FLOW_HERMES_CONDUCTOR_MODEL,r=modelCatalogValues(t);if("inherit"===e)return;return e?r.has(e)?e:void 0:o&&r.has(o)?o:void 0}const r=n.TP_FLOW_CLAUDE_CONDUCTOR_MODEL||n.TP_FLOW_CONDUCTOR_MODEL;if("inherit"!==r)return r||void 0}export function spawnedLaneModelFor({explicitModel:e,sliceType:o,runtime:t="claude",catalog:n=[],env:r=process.env}={}){return e||flowLaneModelFor({sliceType:o,runtime:t,catalog:n,env:r})}export function resolveCodexModel(e,o=[]){if(e)return modelCatalogValues(o).has(e)?e:void 0}export function assertRuntimeModelCompatible({runtime:e="claude",provider:o=null,model:t}={}){if("claude"===e&&(!o||"anthropic"===o)&&/^gpt-/i.test(String(t||"")))throw new Error(`Codex model ${JSON.stringify(t)} cannot run on the built-in Claude provider`);return!0}