thinkpool-pair 0.7.362 → 0.7.363

package/bridge.mjs

@@ -98,6 +98,8 @@ function stopFlowPreviews (flowId, laneId = null) {
 }
 import { FLOW_REVIEWER_PROMPT, FLOW_CODEX_REVIEWER_PROMPT, revertLane, parseReviewVerdict, reviewVerdictToReflection } from './flow-review.mjs'
 import { createFlowReviewReceipt, createFlowReviewSingleFlight, isFlowReviewReceipt } from './flow-receipt.mjs'
+import { collectFlowScopeEvidence, normalizeFlowScopeEvidence } from './flow-scope-evidence.mjs'
+import { formatPastWorkSearch, searchPastWork } from './past-work-search.mjs'
 import { reviewGateDecision } from './flow-review-gate.mjs'
 import { IMMUTABLE_REVIEW_READ_TOOL_EXTRAS, UNSANDBOXED_REVIEW_CHECK_TOOL_EXTRAS, readReviewFile, runReviewCheck } from './review-check.mjs'
 import { pairAdjudicationPrompt, reviewReflectionDecision, REVIEW_DEFAULTS } from './flow-review-reflect.mjs'
@@ -125,12 +127,35 @@ const flowRedispatch = new Map()
 // wave BEFORE overrun. Lives bridge-side because waves dispatch across separate
 // broadcasts; without persistent state the cap can never bite.
 const flowBudgets = new Map()
+const changedFilesBetween = (cwd, baseSha, candidateSha) => {
+  if (!cwd || !baseSha || !candidateSha) return null
+  try {
+    return execFileSync('git', ['-C', cwd, 'diff', '--name-only', '--diff-filter=ACMRD', `${baseSha}..${candidateSha}`], {
+      encoding: 'utf8',
+      timeout: 5000,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).split('\n').map((line) => line.trim()).filter(Boolean)
+  } catch {
+    return null
+  }
+}
+const worktreeChanges = (cwd) => {
+  try {
+    return execFileSync('git', ['-C', cwd, 'status', '--porcelain=v1', '--untracked-files=all'], {
+      encoding: 'utf8',
+      timeout: 5000,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).split('\n').map((line) => line.trim()).filter(Boolean)
+  } catch {
+    return null
+  }
+}
 import { formatPeek, PEEK, readTerminalTurnBudgetDecision, siblingsOf, resolveSibling, crossPostDecision, CROSSPOST, spawnDecision, SPAWN, CROSSROOM, CROSSROOM_BUS, formatPairRoster, crossRoomPostDecision, formatRoomNow, formatClosableHint, closeLaneDecision, laneBusyOf, laneStatusOf, settleLaneBusy, settleLaneControl, nativeClaudeFallbackHint, buildDispatchPreview, authorizeDirectDispatch } from './cross-terminal.mjs'
 import { createStandalonePairResponder, standalonePairIdentity } from './direct-pair-room.mjs'
 import { dispatchPendingRecap, recoverInterruptedTurn, recoverMissingResumeOnce, sendInterruptedContinue, shouldAttemptNativeResume, supersedeInterruptedResume } from './interrupted-resume.mjs'
 import { supersedeDispatchLease } from './dispatch-lease.mjs'
 import { realtimeRecoveryDecision, turnInFlight } from './update-gate.mjs'
-import { saveSession, flushSession, deleteSession, loadAll, canResume, loadPtyId, savePtyId, loadNames, saveNames, appendDurableEvents, seedDurableEvents, readDurablePage, readDurableOldestSeq, hasDurableArchive, servesHistoryPage, acknowledgePendingScheduledOutcome, commitRecordedScheduledOutcome, deletePendingScheduledOutcome, loadPendingScheduledOutcome, loadPendingScheduledOutcomes, savePendingScheduledOutcome } from './session-store.mjs'
+import { saveSession, flushSession, deleteSession, loadAll, loadArchived, canResume, loadPtyId, savePtyId, loadNames, saveNames, appendDurableEvents, seedDurableEvents, readDurablePage, readDurableOldestSeq, hasDurableArchive, servesHistoryPage, acknowledgePendingScheduledOutcome, commitRecordedScheduledOutcome, deletePendingScheduledOutcome, loadPendingScheduledOutcome, loadPendingScheduledOutcomes, savePendingScheduledOutcome } from './session-store.mjs'
 import { stampEvent, makeSeqCounter, maxSeq, seqable, capReplayEvents, chunkReplayEvents, boundEventForBroadcast, inlineImageBlocks, ImageEventQueue, imageQueueConfig, uploadCodeImage as uploadCodeImageRequest, usageReportLine, codexUsageReportLine, appendCurrentPersonRequest, buildCheckpointFromLog, buildRecapFromLog, resolveCheckpointCarry, RECAP_CAP, trimmedBeforeSeq, firstSeq } from './event-id.mjs'
 import { createLatestReplayPump, requestedReplayIds } from './replay-transport.mjs'
 import { classifyCodeEvent, unknownCodeEventNotice } from './code-event-contract.mjs'
@@ -2682,6 +2707,25 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
     if (!reviewPass && entry.dispatchBaseSha && commitSha === entry.dispatchBaseSha) {
       return `Slice "${entry.flowTaskKey}" is not done: HEAD is still the dispatch base (${commitSha.slice(0, 8)}). Commit the verified implementation first.`
     }
+    if (!reviewPass) {
+      const dirty = worktreeChanges(entry.cwd || process.cwd())
+      if (dirty == null) return `Slice "${entry.flowTaskKey}" is not done: the bridge could not verify a clean worktree.`
+      if (dirty.length) return `Slice "${entry.flowTaskKey}" is not done: commit or remove every remaining worktree change before completion (${dirty.slice(0, 4).join(', ')}).`
+    }
+    let scopeEvidence = null
+    if (!reviewPass && entry.flowTaskContract?.scopePaths?.length) {
+      const changed = changedFilesBetween(entry.cwd || process.cwd(), entry.dispatchBaseSha, commitSha)
+      if (!changed) return `Slice "${entry.flowTaskKey}" is not done: the bridge could not derive its Git scope footprint.`
+      scopeEvidence = collectFlowScopeEvidence({
+        log: entry.log,
+        repoRoot: entry.cwd || process.cwd(),
+        declared: entry.flowTaskContract.scopePaths,
+        changed,
+      })
+      if (!scopeEvidence.held) {
+        return `Slice "${entry.flowTaskKey}" is not done: scope drift detected in ${scopeEvidence.unexpected.join(', ')}. The approved scope must be amended before these files can ship.`
+      }
+    }
     let previewUrl = null
     try { const pv = await startPreview({ dir: entry.cwd || process.cwd(), id: `lane:${entry.flowSessionId}:${id}` }); previewUrl = pv.url } catch { /* preview best-effort */ }
     // S1 (context-offload) — digest THIS closed slice into the durable store so the next
@@ -2712,8 +2756,10 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
       process.stderr.write(`\n  ${A.dim}◆ flow digest skip ${entry.flowTaskKey} — ${e?.message || e}${A.rst}\n`)
     }
     const completedContract = requiresBaselineReceipt
-      ? { ...entry.flowTaskContract, baseline: { ...entry.flowTaskContract.baseline, evidence: baselineReceipt } }
-      : entry.flowTaskContract || null
+      ? { ...entry.flowTaskContract, baseline: { ...entry.flowTaskContract.baseline, evidence: baselineReceipt }, ...(scopeEvidence ? { scopeEvidence } : {}) }
+      : entry.flowTaskContract
+        ? { ...entry.flowTaskContract, ...(scopeEvidence ? { scopeEvidence } : {}) }
+        : null
     bcast('flow-task-done', { term: id, flowId: entry.flowSessionId, taskKey: entry.flowTaskKey, laneId: id, commitSha, previewUrl, contract: completedContract, ...(reviewPass ? { reviewAction: 'pass' } : {}) }, flowChannel)
     process.stderr.write(`\n  ${A.cyan}◆ flow slice done — ${entry.flowTaskKey} (${commitSha ? commitSha.slice(0, 8) : 'no commit'})${previewUrl ? ` · preview ${previewUrl}` : ''}${A.rst}\n`)
     entry.flowDone = true   // FL-B3 — retire immediately so it drops from the ≤8 lane cap
@@ -2802,6 +2848,7 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
         rounds: round,
         candidateSha: targetSnapshot?.sha,
         acceptanceDigest,
+        scope: targetSnapshot?.scopeEvidence,
         reasons: receiptReasons,
       })
     } catch (error) {
@@ -2816,6 +2863,7 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
         rounds: round,
         candidateSha: targetSnapshot?.sha,
         acceptanceDigest,
+        scope: targetSnapshot?.scopeEvidence,
         reasons: receiptReasons,
       })
     }
@@ -3148,6 +3196,44 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
           return { content: [{ type: 'text', text }] }
         },
       ),
+      ...(!entry.flowRole ? [tool(
+        'search_past_work',
+        'Search bounded saved terminal work from THIS ThinkPool room. Returns privacy-filtered excerpts for prior decisions, failed attempts, commands, checks, and Flow receipts. Every hit cites the room, terminal, date, and event sequence. It never searches another room, exposes prompts or host paths, or changes state.',
+        {
+          query: z.string().min(2).max(160).describe('specific terms from the prior decision, failure, command, check, or feature'),
+          limit: z.number().int().min(1).max(8).optional().describe('maximum cited hits; default 8'),
+        },
+        async (args) => {
+          if (entry.pastWorkSearchTurnRev !== entry._turnRev) {
+            entry.pastWorkSearchTurnRev = entry._turnRev
+            entry.pastWorkSearchCount = 0
+          }
+          if ((entry.pastWorkSearchCount || 0) >= 3) {
+            return { content: [{ type: 'text', text: 'Past-work search limit reached for this turn (3). Use the cited results already returned or narrow the next room turn.' }] }
+          }
+          entry.pastWorkSearchCount = (entry.pastWorkSearchCount || 0) + 1
+          const records = new Map()
+          for (const record of loadArchived(room, 40)) {
+            if (!record?.id || !Array.isArray(record.log)) continue
+            records.set(record.id, { id: record.id, name: termNames[record.id] || record.name || 'Archived terminal', savedAt: record.savedAt || record._archivedAt, log: record.log })
+          }
+          for (const [terminalId, terminalEntry] of sessions) {
+            records.set(terminalId, {
+              id: terminalId,
+              name: termNames[terminalId] || `Terminal ${String(terminalId).slice(0, 8)}`,
+              savedAt: terminalEntry.openedAt || Date.now(),
+              log: terminalEntry.log || [],
+            })
+          }
+          let results
+          try {
+            results = searchPastWork([...records.values()], args?.query || '', { room, limit: args?.limit })
+          } catch (error) {
+            return { content: [{ type: 'text', text: `Past-work search rejected: ${error?.message || error}` }] }
+          }
+          return { content: [{ type: 'text', text: formatPastWorkSearch(results, args?.query || '') }] }
+        },
+      )] : []),
       // Tier 1 cross-ROOM peek — list_sessions / read_session. Read-only reach into the
       // account's OTHER rooms (this session's sibling SESSIONS, not just sibling terminals),
       // routed through the account supervisor over IPC (pairRequest). Auto-allowed by the
@@ -3528,7 +3614,7 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
       // (slices whose deps just got satisfied).
       ...(entry.flowRole === 'builder' ? [tool(
         'mark_flow_done',
-        "ThinkPool Flow ONLY — call this ONCE when your slice is built, RUNS, and meets its acceptance criteria. For a gate-first task, pass `baselineEvidence`: the real, bounded pre-edit command/behavior receipt proving the assigned failure/absence. Never fabricate a RED sentence. 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). Do not call before the slice actually runs + meets acceptance.",
+        "ThinkPool Flow ONLY — call this ONCE when your slice is built, RUNS, and meets its acceptance criteria. For a gate-first task, pass `baselineEvidence`: the real, bounded pre-edit command/behavior receipt proving the assigned failure/absence. Never fabricate a RED sentence. The bridge derives the edited-file footprint from Git, compares it with the sealed scopePaths, and refuses unexpected touches. 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). Do not call before the slice actually runs + meets acceptance.",
         { baselineEvidence: z.string().max(1400).optional().describe('real single-line pre-edit baseline command/behavior receipt; required for new gate-first tasks') },
         async (args) => ({ content: [{ type: 'text', text: await markFlowDone({ baselineEvidence: args?.baselineEvidence || '' }) }] }),
       )] : []),
@@ -3540,14 +3626,14 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
       // reject malformed plans back to the conductor so it re-emits.
       ...(entry.flowRole === 'conductor' ? [tool(
         'submit_flow_plan',
-        'ThinkPool Flow CONDUCTOR ONLY — submit your decomposition for human approval. Call this ONCE when your task-graph is ready. Pass it as `plan`: a JSON string {"summary":"<one line; assumptions: …>","tasks":[{"key":"<kebab>","title":"…","scope":"…","acceptance":"observable proof","nonGoals":["bounded exclusion"],"baseline":{"gate":"what fails/is absent before edits","evidence":"optional observed receipt"},"deps":["<key>"],"sliceType":"feature|scaffold|review|fix"}]}. Each builder/fix/scaffold needs acceptance, nonGoals, and a safe bounded baseline gate; review tasks inherit one builder contract. When uncertain, choose and record a safe reversible default; ask only when a choice materially expands scope or authority. The room validates and persists the graph, then shows approval. Do NOT use ExitPlanMode or write a plan file.',
+        'ThinkPool Flow CONDUCTOR ONLY — submit your decomposition for human approval. Call this ONCE when your task-graph is ready. Pass it as `plan`: a JSON string {"summary":"<one line; assumptions: …>","tasks":[{"key":"<kebab>","title":"…","scope":"human-readable ownership","scopePaths":["repo/file.js","repo/directory/**"],"acceptance":"observable proof","nonGoals":["bounded exclusion"],"baseline":{"gate":"what fails/is absent before edits","evidence":"optional observed receipt"},"deps":["<key>"],"sliceType":"feature|scaffold|review|fix"}]}. Each builder/fix/scaffold needs acceptance, machine-readable repo-relative scopePaths, nonGoals, and a safe bounded baseline gate; review tasks inherit one builder contract. When uncertain, choose and record a safe reversible default; ask only when a choice materially expands scope or authority. The room validates and persists the graph, then shows approval. Do NOT use ExitPlanMode or write a plan file.',
         { plan: z.string().describe('the task-graph as a JSON string (the {summary, tasks:[…]} object)') },
         async (args) => {
           const okText = (t) => ({ content: [{ type: 'text', text: t }] })
           if (!entry.flowSessionId || entry.flowRole !== 'conductor') return okText('Not a Flow conductor — there is no flow to submit a plan for.')
           let norm
           try { norm = validatePlanForRuntime(normalizePlanOutput(args?.plan || ''), entry.runtime) }
-          catch (e) { return okText(`Plan REJECTED: ${e?.message || e}. Re-call submit_flow_plan with valid JSON: a non-empty acyclic tasks array; each builder/fix/scaffold has observable acceptance, bounded nonGoals, and a safe baseline gate that says what fails/is absent; each review targets exactly one builder contract.`) }
+          catch (e) { return okText(`Plan REJECTED: ${e?.message || e}. Re-call submit_flow_plan with valid JSON: a non-empty acyclic tasks array; each builder/fix/scaffold has observable acceptance, repo-relative scopePaths, bounded nonGoals, and a safe baseline gate that says what fails/is absent; each review targets exactly one builder contract.`) }
           bcast('flow-plan', { term: id, flowId: entry.flowSessionId, plan: JSON.stringify(norm) }, flowChannel)
           process.stderr.write(`\n  ${A.mag}◆ flow plan submitted — flow ${String(entry.flowSessionId).slice(0, 8)} (${norm.tasks.length} slice${norm.tasks.length === 1 ? '' : 's'}).${A.rst}\n`)
           return okText(`Plan submitted (${norm.tasks.length} slice${norm.tasks.length === 1 ? '' : 's'}) with gate-first contracts. Safe reversible assumptions belong in the summary; user steering remains authoritative. The room is showing approval. You are DONE; stop here and wait for approval (lane dispatch is the room's job).`)
@@ -5593,7 +5679,26 @@ flowChannel
           const cwd = worktreeSpec({ flowId: payload.flowId, taskKey: dep }).dir
           let sha = null
           try { sha = execFileSync('git', ['-C', cwd, 'rev-parse', 'HEAD'], { encoding: 'utf8', timeout: 3000, stdio: ['ignore', 'pipe', 'ignore'] }).trim() } catch { /* target is not safely reviewable */ }
-          return { taskKey: dep, cwd, sha }
+          let scopeEvidence = null
+          if (sha && t.contract?.scopePaths?.length) {
+            let baseSha = null
+            try {
+              baseSha = execFileSync('git', ['-C', cwd, 'merge-base', sha, 'origin/main'], {
+                encoding: 'utf8',
+                timeout: 3000,
+                stdio: ['ignore', 'pipe', 'ignore'],
+              }).trim()
+            } catch { /* missing immutable base holds the review below */ }
+            const changed = changedFilesBetween(cwd, baseSha, sha)
+            if (changed) {
+              const mechanical = collectFlowScopeEvidence({ log: [], repoRoot: cwd, declared: t.contract.scopePaths, changed })
+              const observed = normalizeFlowScopeEvidence(t.contract.scopeEvidence)
+              scopeEvidence = observed
+                ? { ...mechanical, read: observed.read, verified: observed.verified }
+                : mechanical
+            }
+          }
+          return { taskKey: dep, cwd, sha, ...(scopeEvidence ? { scopeEvidence } : {}) }
         }).filter((item) => item.sha) : []
         // Lanes build autonomously in their own worktree — bypassPermissions so they
         // don't stall on a card for every write/bash (matches the user's expectation that

package/flow-receipt.mjs

@@ -3,6 +3,8 @@
 // admits the evidence a pair can act on. Prompts, environment, paths, logs, and
 // hidden reasoning never have a field in the public shape.
 
+import { normalizeFlowScopeEvidence } from './flow-scope-evidence.mjs'
+
 export const FLOW_REVIEW_RECEIPT_KIND = 'flow-review-receipt'
 
 const MAX_TASK_KEY = 120
@@ -75,6 +77,7 @@ export function createFlowReviewReceipt(input = {}) {
   }
   const candidateSha = cleanSha(input.candidateSha)
   const acceptanceDigest = cleanDigest(input.acceptanceDigest)
+  const scope = normalizeFlowScopeEvidence(input.scope)
   // Presence, not truthiness, is intentional: deployments are never inferred
   // from a pass/reject outcome or from a candidate SHA.
   const deployment = Object.hasOwn(input, 'deployment') ? cleanText(input.deployment, MAX_LINE) : null
@@ -84,6 +87,10 @@ export function createFlowReviewReceipt(input = {}) {
   if (outcome === 'pass' && !receipt.verified) {
     throw new TypeError('Passing flow review receipt requires an exact candidate and acceptance digest')
   }
+  if (scope) receipt.scope = scope
+  if (outcome === 'pass' && !scope?.held) {
+    throw new TypeError('Passing flow review receipt requires a held scope footprint')
+  }
   if (deployment) receipt.deployment = deployment
   return receipt
 }

package/flow-scope-evidence.mjs

@@ -0,0 +1,117 @@
+import path from 'node:path'
+
+const MAX_SCOPE_PATHS = 32
+const MAX_PATH = 180
+const MAX_OBSERVED = 32
+const MAX_CHECKS = 8
+const MAX_CHECK = 220
+const PRIVATE_PATH = /(?:^|\/)(?:\.env(?:\.|$)|\.git(?:\/|$)|\.thinkpool(?:\/|$)|node_modules(?:\/|$))/
+const SECRET = /(?:sk[_-](?:proj[_-])?[a-z0-9_-]{8,}|github_pat_[a-z0-9_]{20,}|gh[pousr]_[a-z0-9_-]{8,}|(?:AKIA|ASIA)[0-9A-Z]{16}|npm_[a-z0-9]{24,}|bearer\s+[a-z0-9._-]{8,}|(?:api[_-]?key|access[_-]?token|auth(?:orization)?|token|secret)\s*[=:]\s*\S+)/i
+const VERIFY_COMMAND = /(?:^|\s)(?:npm|pnpm|yarn|bun)\s+(?:run\s+)?(?:test|build|lint|check|typecheck|verify)\b|(?:^|\s)node\s+--test\b|(?:vitest|jest|playwright|eslint|tsc)\b/i
+
+function uniqueSorted(values, max = MAX_OBSERVED) {
+  return [...new Set(values)].sort().slice(0, max)
+}
+
+function repoPath(value, { allowPattern = false } = {}) {
+  if (typeof value !== 'string') return null
+  let text = value.trim().replaceAll('\\', '/')
+  if (!text || text.length > MAX_PATH || text.startsWith('/') || /^[A-Za-z]:\//.test(text)) return null
+  const directoryPattern = allowPattern && 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 (PRIVATE_PATH.test(bare)) return null
+  const last = bare.split('/').at(-1)
+  if (allowPattern && !directoryPattern && !last.includes('.') && !/^(?:Dockerfile|Makefile|LICENSE|README)$/i.test(last)) return null
+  text = directoryPattern ? `${bare}/**` : bare
+  return text
+}
+
+export function normalizeFlowScopePaths(value) {
+  if (!Array.isArray(value) || value.length === 0 || value.length > MAX_SCOPE_PATHS) {
+    throw new TypeError(`scope paths must contain 1-${MAX_SCOPE_PATHS} repo-relative entries`)
+  }
+  const paths = []
+  for (const item of value) {
+    const safe = repoPath(item, { allowPattern: true })
+    if (!safe) throw new TypeError(`invalid scope path: ${JSON.stringify(item)}`)
+    if (!paths.includes(safe)) paths.push(safe)
+  }
+  return paths.sort()
+}
+
+export function classifyFlowScope({ declared, changed } = {}) {
+  const safeDeclared = normalizeFlowScopePaths(declared)
+  const safeChanged = uniqueSorted((Array.isArray(changed) ? changed : []).map((item) => repoPath(item)).filter(Boolean))
+  const unexpected = safeChanged.filter((file) => !safeDeclared.some((scope) =>
+    scope.endsWith('/**') ? file.startsWith(scope.slice(0, -2)) : file === scope
+  ))
+  return { declared: safeDeclared, changed: safeChanged, unexpected, held: unexpected.length === 0 }
+}
+
+function observedPath(value, repoRoot) {
+  if (typeof value !== 'string' || !value.trim()) return null
+  const absoluteRoot = path.resolve(repoRoot)
+  const absolute = path.isAbsolute(value) ? path.resolve(value) : path.resolve(absoluteRoot, value)
+  const relative = path.relative(absoluteRoot, absolute).replaceAll('\\', '/')
+  if (!relative || relative.startsWith('../') || path.isAbsolute(relative)) return null
+  return repoPath(relative)
+}
+
+function safeCheck(value, repoRoot) {
+  if (typeof value !== 'string') return null
+  let command = value.replaceAll(path.resolve(repoRoot), '.').replace(/\s+/g, ' ').trim()
+  if (!command || command.length > MAX_CHECK || SECRET.test(command) || !VERIFY_COMMAND.test(command)) return null
+  return command
+}
+
+export function collectFlowScopeEvidence({ log = [], repoRoot, declared, changed } = {}) {
+  const classified = classifyFlowScope({ declared, changed })
+  const reads = []
+  const checks = new Map()
+  const successful = new Set()
+  for (const event of Array.isArray(log) ? log : []) {
+    if (event?.kind === 'assistant') {
+      for (const block of event.blocks || []) {
+        if (block?.type !== 'tool_use') continue
+        const name = String(block.name || '').toLowerCase()
+        if (['read', 'read_file', 'edit', 'write'].includes(name)) {
+          const candidate = block.input?.file_path ?? block.input?.path
+          const safe = observedPath(candidate, repoRoot)
+          if (safe) reads.push(safe)
+        }
+        if (name === 'bash' || name === 'exec_command' || name === 'command_execution') {
+          const command = safeCheck(block.input?.command ?? block.input?.cmd, repoRoot)
+          if (block.id && command) checks.set(block.id, command)
+        }
+      }
+    } else if (event?.kind === 'tool_result' && event.toolUseId && event.isError !== true) {
+      successful.add(event.toolUseId)
+    }
+  }
+  return {
+    declared: classified.declared,
+    read: uniqueSorted(reads),
+    changed: classified.changed,
+    verified: uniqueSorted([...checks].filter(([id]) => successful.has(id)).map(([, command]) => command), MAX_CHECKS),
+    unexpected: classified.unexpected,
+    held: classified.held,
+  }
+}
+
+export function normalizeFlowScopeEvidence(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null
+  try {
+    const classified = classifyFlowScope({ declared: value.declared, changed: value.changed })
+    const read = uniqueSorted((Array.isArray(value.read) ? value.read : []).map((item) => repoPath(item)).filter(Boolean))
+    const verified = uniqueSorted((Array.isArray(value.verified) ? value.verified : [])
+      .map((item) => typeof item === 'string' && item.length <= MAX_CHECK && !SECRET.test(item) && VERIFY_COMMAND.test(item) ? item.trim() : null)
+      .filter(Boolean), MAX_CHECKS)
+    if (Boolean(value.held) !== classified.held) return null
+    if (JSON.stringify(uniqueSorted(Array.isArray(value.unexpected) ? value.unexpected : [])) !== JSON.stringify(classified.unexpected)) return null
+    return { declared: classified.declared, read, changed: classified.changed, verified, unexpected: classified.unexpected, held: classified.held }
+  } catch {
+    return null
+  }
+}

package/flow-task-graph.mjs

@@ -51,6 +51,8 @@ export const FLOW_CONTRACT_LIMITS = Object.freeze({
   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
@@ -90,6 +92,39 @@ function boundedLine (value, label, max, { required = false } = {}) {
   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 })
 }
@@ -154,14 +189,16 @@ function sha256Hex (message) {
 // 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, acceptance, sliceType, nonGoals, baselineGate, inheritedReviewerTarget = key }) {
-  return {
-    version: 1,
+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) {
@@ -174,6 +211,7 @@ function contractSource (task) {
     : {}
   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
 }
 
@@ -216,19 +254,22 @@ export function normalizeTaskContract (task, { sliceType, legacy = false } = {})
   const evidence = baselineObject?.evidence == null || baselineObject?.evidence === ''
     ? ''
     : normalizeBaselineEvidence(baselineObject.evidence)
-  return { nonGoals, baseline: gate ? { gate, evidence } : null, digest, acceptancePack: sealedPack }
+  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) {
+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`)
@@ -257,22 +298,26 @@ export function validateTaskContractSeal (task, { legacy = false } = {}) {
     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
@@ -291,11 +336,13 @@ export function validateTaskContractSeal (task, { legacy = false } = {}) {
     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`)
@@ -433,7 +480,7 @@ export function normalizePlanOutput (raw, { legacy = false } = {}) {
   })
   validateDag(tasks)
   for (const task of tasks) {
-    if (task.sliceType !== SLICE_TYPE.review) bindContractDigest(task)
+    if (task.sliceType !== SLICE_TYPE.review) bindContractDigest(task, { legacy })
   }
   for (const task of tasks) {
     if (task.sliceType !== SLICE_TYPE.review) continue
@@ -449,6 +496,7 @@ export function normalizePlanOutput (raw, { legacy = false } = {}) {
     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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thinkpool-pair",
-  "version": "0.7.362",
+  "version": "0.7.363",
   "description": "Connect Claude Code, Codex, or Hermes on your computer to a Thinkpool Code room.",
   "type": "module",
   "bin": {
@@ -94,6 +94,8 @@
     "design-source-contract.mjs",
     "flow-review.mjs",
     "flow-receipt.mjs",
+    "flow-scope-evidence.mjs",
+    "past-work-search.mjs",
     "review-check.mjs",
     "flow-review-gate.mjs",
     "flow-review-reflect.mjs",

package/past-work-search.mjs

@@ -0,0 +1,105 @@
+const MAX_QUERY = 160
+const MAX_RESULTS = 8
+const MAX_RECORDS = 48
+const MAX_EVENTS = 800
+const MAX_EXCERPT = 260
+const SECRET_VALUE = /(?:sk[_-](?:proj[_-])?[a-z0-9_-]{8,}|gsk_[a-z0-9_-]{8,}|AIza[a-z0-9_-]{8,}|gh[pousr]_[a-z0-9_-]{8,}|github_pat_[a-z0-9_]{20,}|glpat-[a-z0-9_-]{8,}|x(?:ox[baprsce]|app)-[a-z0-9_-]{8,}|(?:AKIA|ASIA)[0-9A-Z]{16}|npm_[a-z0-9]{24,}|bearer\s+[a-z0-9._-]{8,}|(?:api[_-]?key|access[_-]?token|auth(?:orization)?|token|secret)\s*[=:]\s*\S+)/i
+const PRIVATE_WORDS = /(?:system\s+prompt|hidden\s+reasoning|chain[ -]of[ -]thought|\bpassword\b|private[_ -]?key|\.env\b)/i
+const HOST_PATH = /(?:^|[\s=("'`])(?:~\/|\/(?:Users|home|var|tmp|private|workspace)\/|[A-Za-z]:\\|\\\\)[^\s)"'`]*/i
+
+function textContent(content) {
+  if (typeof content === 'string') return content
+  if (!Array.isArray(content)) return ''
+  return content.map((item) => typeof item === 'string' ? item : item?.text || '').join(' ')
+}
+
+function safeExcerpt(value) {
+  if (typeof value !== 'string') return null
+  const line = value.replace(/\s+/g, ' ').trim()
+  if (!line || SECRET_VALUE.test(line) || PRIVATE_WORDS.test(line) || HOST_PATH.test(line)) return null
+  return line.slice(0, MAX_EXCERPT)
+}
+
+function eventCandidates(event) {
+  if (!event || typeof event !== 'object') return []
+  if (event.kind === 'flow-review-receipt') {
+    const scope = event.scope
+    return [
+      `Flow ${event.outcome || 'review'}: ${event.taskKey || ''}`,
+      ...(event.checks || []).map((line) => `Check: ${line}`),
+      ...(event.reasons || []).map((line) => `Finding: ${line}`),
+      ...((scope?.changed || []).map((line) => `Edited: ${line}`)),
+      ...((scope?.unexpected || []).map((line) => `Unexpected: ${line}`)),
+    ]
+  }
+  if (event.kind === 'assistant') {
+    const out = []
+    for (const block of event.blocks || []) {
+      if (block?.type === 'text') out.push(block.text)
+      if (block?.type === 'tool_use') {
+        const name = String(block.name || '')
+        if (/^(?:bash|exec_command|command_execution)$/i.test(name)) {
+          const command = block.input?.command ?? block.input?.cmd
+          if (command) out.push(`Command: ${command}`)
+        }
+      }
+    }
+    return out
+  }
+  if (event.kind === 'you') return [event.text]
+  if (event.kind === 'tool_result') return [`Result: ${textContent(event.content)}`]
+  if (event.kind === 'result') return [event.resultText]
+  return []
+}
+
+function queryParts(query) {
+  const text = String(query || '').replace(/\s+/g, ' ').trim()
+  if (text.length < 2 || text.length > MAX_QUERY) throw new TypeError(`past-work query must contain 2-${MAX_QUERY} characters`)
+  if (SECRET_VALUE.test(text) || PRIVATE_WORDS.test(text) || HOST_PATH.test(text)) return null
+  return { text, lower: text.toLowerCase(), tokens: text.toLowerCase().split(/[^a-z0-9._/-]+/).filter((token) => token.length > 1) }
+}
+
+export function searchPastWork(records, query, { room, limit = MAX_RESULTS } = {}) {
+  const parsed = queryParts(query)
+  if (!parsed) return []
+  const boundedLimit = Math.max(1, Math.min(MAX_RESULTS, Number(limit) || MAX_RESULTS))
+  const results = []
+  for (const record of (Array.isArray(records) ? records : []).slice(0, MAX_RECORDS)) {
+    const terminal = safeExcerpt(record?.name) || 'Unnamed terminal'
+    const events = Array.isArray(record?.log) ? record.log.slice(-MAX_EVENTS) : []
+    for (const event of events) {
+      for (const raw of eventCandidates(event)) {
+        const excerpt = safeExcerpt(raw)
+        if (!excerpt) continue
+        const lower = excerpt.toLowerCase()
+        const tokenHits = parsed.tokens.filter((token) => lower.includes(token)).length
+        if (!lower.includes(parsed.lower) && (!parsed.tokens.length || tokenHits !== parsed.tokens.length)) continue
+        results.push({
+          room: String(room || '').trim() || 'current',
+          terminal,
+          terminalId: String(record?.id || '').slice(0, 80),
+          ts: Number(event?.ts) || Number(record?.savedAt) || 0,
+          seq: Number.isFinite(Number(event?.seq)) ? Number(event.seq) : null,
+          excerpt,
+          score: (lower.includes(parsed.lower) ? 10 : 0) + tokenHits + (excerpt.startsWith('Command:') ? 0 : 1),
+        })
+      }
+    }
+  }
+  return results
+    .sort((a, b) => b.score - a.score || b.ts - a.ts)
+    .slice(0, boundedLimit)
+    .map(({ score, ...result }) => result)
+}
+
+export function formatPastWorkSearch(results, query) {
+  const safeQuery = safeExcerpt(String(query || '').trim())
+  if (!results.length) return safeQuery
+    ? `No cited past work matched “${safeQuery}” in this room.`
+    : 'No cited past work matched that privacy-filtered query in this room.'
+  return results.map((result, index) => {
+    const date = result.ts ? new Date(result.ts).toISOString().slice(0, 10) : 'date unavailable'
+    const event = result.seq == null ? 'saved transcript' : `event ${result.seq}`
+    return `${index + 1}. ${result.excerpt}\n   [Room ${result.room} · ${result.terminal} · ${date} · ${event}]`
+  }).join('\n')
+}

package/session-store.mjs

@@ -426,6 +426,28 @@ export function loadAll(room) {
   return listRecs(room).sort((a, b) => (a.savedAt || 0) - (b.savedAt || 0))
 }
 
+// Closed terminal snapshots stay recoverable under .archive/. Past-work search
+// reads only these already-bounded snapshots, never the unbounded JSONL logs.
+export function loadArchived(room, limit = 40) {
+  try {
+    return fs.readdirSync(archiveDir(room))
+      .map((name) => {
+        const file = path.join(archiveDir(room), name)
+        try {
+          const stat = fs.statSync(file)
+          if (!stat.isFile()) return null
+          const record = JSON.parse(fs.readFileSync(file, 'utf8'))
+          return record && Array.isArray(record.log) ? { ...record, _archivedAt: stat.mtimeMs || 0 } : null
+        } catch { return null }
+      })
+      .filter(Boolean)
+      .sort((a, b) => (b._archivedAt || b.savedAt || 0) - (a._archivedAt || a.savedAt || 0))
+      .slice(0, Math.max(1, Math.min(100, Number(limit) || 40)))
+  } catch {
+    return []
+  }
+}
+
 // Last PTY terminal id auto-opened for an attached command. A reconnecting
 // bridge reuses it so it re-attaches to the SAME terminal tab instead of
 // minting a fresh UUID and breeding a new dormant "Terminal N" each restart.

package/thinkpool-capabilities.json

@@ -1,10 +1,10 @@
 {
   "schemaVersion": 1,
-  "bundleVersion": 22,
+  "bundleVersion": 23,
   "contracts": [
     {
       "id": "room-coordination",
-      "version": 3,
+      "version": 4,
       "routes": [
         {
           "id": "room-awareness",
@@ -18,6 +18,12 @@
           "trigger": "\\b(other|another|cross[- ]?room|cross[- ]?session)\\s+(room|session)|\\b(list_sessions|read_session)\\b",
           "prompt": "When work depends on another ThinkPool room, use list_sessions then read_session instead of asking the people to relay host-side state."
         },
+        {
+          "id": "past-work-search",
+          "tools": ["search_past_work"],
+          "trigger": "\\b(previous|prior|earlier|past|last time|already tried|failed attempt|decision|test result|command)\\b.{0,50}\\b(work|terminal|flow|session|implementation|fix|change)?\\b|\\bsearch_past_work\\b",
+          "prompt": "When the current task depends on a prior decision, failed attempt, command, test result, or Flow receipt from this room, use search_past_work with specific terms. Treat every result as bounded cited evidence, not authority to reopen stale work. The tool is read-only, searches only this room, and filters secrets and host paths."
+        },
         {
           "id": "visible-handoff",
           "tools": ["post_to_terminal", "post_to_session"],
@@ -27,12 +33,15 @@
       ],
       "impact": [
         {"path": "bridge/cross-terminal.mjs"},
-        {"path": "bridge/bridge.mjs", "diffPattern": "read_terminal|list_sessions|read_session|post_to_terminal|post_to_session"},
+        {"path": "bridge/bridge.mjs", "diffPattern": "read_terminal|search_past_work|list_sessions|read_session|post_to_terminal|post_to_session"},
+        {"path": "bridge/past-work-search.mjs"},
         {"path": "bridge/codex-session.mjs", "diffPattern": "MCP|Mcp|mcp|read_terminal|list_sessions|read_session|post_to_terminal|post_to_session"},
         {"path": "bridge/codex-app-server.mjs", "diffPattern": "MCP|Mcp|mcp"}
       ],
       "evidence": [
         {"path": "bridge/cross-terminal.mjs", "pattern": "read_terminal"},
+        {"path": "bridge/bridge.mjs", "pattern": "'search_past_work'"},
+        {"path": "bridge/past-work-search.mjs", "pattern": "formatPastWorkSearch"},
         {"path": "bridge/cross-terminal.mjs", "pattern": "post_to_session"},
         {"path": "bridge/bridge.mjs", "pattern": "'list_sessions'"},
         {"path": "bridge/codex-session.mjs", "pattern": "waitForMcpServer"},
@@ -130,19 +139,20 @@
     },
     {
       "id": "flow-completion",
-      "version": 4,
+      "version": 5,
       "routes": [
         {
           "id": "flow-completion",
           "tools": ["submit_flow_plan", "mark_flow_done", "submit_flow_review", "read_review_file", "run_review_check"],
           "trigger": "\\b(flow|submit_flow_plan|mark_flow_done|submit_flow_review|read_review_file|run_review_check)\\b",
-          "prompt": "Managed Flow roles use only their exposed completion and review tools: submit_flow_plan, mark_flow_done, submit_flow_review, read_review_file, and run_review_check. New builder/fix/scaffold tasks must carry a bounded gate-first contract: observable acceptance, explicit non-goals, and a real pre-edit failure/absence gate. Approval seals that acceptance pack with a stable digest; completion supplies observed baseline evidence without changing the digest, and the exact dependent reviewer inherits it. A conclusive pass binds one bounded terminal receipt to the exact reviewed candidate SHA and acceptance digest; missing proof holds the Flow instead of completing it. When a bounded detail is ambiguous or the user is unsure, choose the least-invasive reversible default, state the assumption, and continue; ask only when the choice would materially expand scope or authority. read_review_file is approval-free pinned-source access. run_review_check executes target-defined code without OS filesystem or network isolation and therefore remains subject to the runtime's normal approval boundary; approvalPolicy=never reviewers must not call it and must report the skipped check."
+          "prompt": "Managed Flow roles use only their exposed completion and review tools: submit_flow_plan, mark_flow_done, submit_flow_review, read_review_file, and run_review_check. New builder/fix/scaffold tasks must carry a bounded gate-first contract: observable acceptance, explicit non-goals, machine-readable repo-relative scopePaths, and a real pre-edit failure/absence gate. Approval seals that acceptance pack with a stable digest. Completion supplies observed baseline evidence without changing the digest, derives edited files from Git, and refuses unexpected touches. The exact dependent reviewer inherits the contract and the bridge recomputes the scope footprint from the immutable candidate. A conclusive pass binds one bounded terminal receipt to the exact reviewed candidate SHA, acceptance digest, and held scope; missing or drifted proof holds the Flow instead of completing it. When a bounded detail is ambiguous or the user is unsure, choose the least-invasive reversible default, state the assumption, and continue; ask only when the choice would materially expand scope or authority. read_review_file is approval-free pinned-source access. run_review_check executes target-defined code without OS filesystem or network isolation and therefore remains subject to the runtime's normal approval boundary; approvalPolicy=never reviewers must not call it and must report the skipped check."
         }
       ],
       "impact": [
         {"path": "bridge/bridge.mjs", "diffPattern": "submit_flow_plan|mark_flow_done|submit_flow_review|read_review_file|run_review_check"},
         {"path": "bridge/flow-review.mjs"},
         {"path": "bridge/flow-receipt.mjs"},
+        {"path": "bridge/flow-scope-evidence.mjs"},
         {"path": "bridge/flow-review-gate.mjs"},
         {"path": "bridge/flow-task-graph.mjs"}
       ],
@@ -151,7 +161,8 @@
         {"path": "bridge/bridge.mjs", "pattern": "'mark_flow_done'"},
         {"path": "bridge/bridge.mjs", "pattern": "'submit_flow_review'"},
         {"path": "bridge/flow-task-graph.mjs", "pattern": "acceptancePackDigest"},
-        {"path": "bridge/flow-receipt.mjs", "pattern": "Passing flow review receipt requires an exact candidate and acceptance digest"}
+        {"path": "bridge/flow-receipt.mjs", "pattern": "Passing flow review receipt requires a held scope footprint"},
+        {"path": "bridge/flow-scope-evidence.mjs", "pattern": "classifyFlowScope"}
       ]
     },
     {