thinkpool-pair 0.7.216 → 0.7.217

package/bridge.mjs

@@ -65,6 +65,7 @@ import { writeLaneArtifact, digestSlice, appendDigest, resumeLane } from './flow
 import { createFlowWorktree, worktreeSpec } from './flow-worktree.mjs'
 import { startPreview, stopAllPreviews, previews } from './flow-preview.mjs'
 import { ViewportManager, createViewportTools, sharedViewportBrowser } from './viewport.mjs'
+import { designPrompt, resolveDesignSource, validateDesignRequest } from './design-edit.mjs'
 // FL-M9 — per-lane preview servers leak (one per done lane, never stopped until shutdown).
 // Lane previews are keyed `lane:<flowId>:<laneId>`; stop a whole flow's set when it assembles
 // (the assembled preview supersedes them) or when a lane is reverted.
@@ -838,6 +839,12 @@ const flowChannel = supabase.channel(`tpflow:${room}`, {
   config: { broadcast: { self: false } },
 })
 
+// Source-changing Design Mode control never rides the public tpcode topic.
+// Membership RLS on realtime.messages gates join, receive, and send.
+const designChannel = supabase.channel(`tpdesign:${room}`, {
+  config: { private: true, broadcast: { self: false } },
+})
+
 // ── terminal registry ──────────────────────────────────────────────
 // id → { term (pty), cmd, attached, scrollback, buf }
 const terms = new Map()
@@ -1213,13 +1220,73 @@ try {
 } catch { /* mockups stay local if the outbox can't be made */ }
 
 const mockupSeen = new Map()   // `${term}/${slug}` → mtimeMs of the last manifest processed
+// Host-only provenance and edit coordination. The browser receives opaque ids
+// and content hashes only; source/cwd never leave this process.
+const designArtifacts = new Map() // previewId → trusted source record
+const designQueues = new Map()    // producer term → validated requests
+const designActive = new Map()    // producer term → request awaiting result + proof
+const designRestore = new Map()   // current previewId → immediately previous verified record/edit
+const designStatus = (payload) => designChannel.send({
+  type: 'broadcast', event: 'design-status', payload: { ts: Date.now(), ...payload },
+})
+
+const finishDesign = (term, state, extra = {}) => {
+  const active = designActive.get(term)
+  if (!active) return
+  if (active.timer) clearTimeout(active.timer)
+  designActive.delete(term)
+  designStatus({ previewId: active.record.previewId, requestId: active.request.cid, state, ...extra })
+  // An element locator belongs to one DOM revision. Never guess queued targets
+  // forward after a successful edit; both people must reselect on the new render.
+  if (state === 'verified-live') {
+    const queue = designQueues.get(term) || []
+    for (const stale of queue.splice(0)) designStatus({ previewId: stale.record.previewId, requestId: stale.request.cid, state: 'stale', message: 'The artifact changed. Reselect the element on the new revision.' })
+  }
+  queueMicrotask(() => pumpDesign(term))
+}
+
+const maybeVerifyDesign = (term) => {
+  const active = designActive.get(term)
+  if (!active?.resultOk || !active.proof) return
+  finishDesign(term, 'verified-live', { message: 'Verified at desktop and mobile.', artifact: active.proof, canRestore: true })
+}
+
+function pumpDesign(term) {
+  if (designActive.has(term)) return
+  const queue = designQueues.get(term) || []
+  const next = queue[0]
+  if (!next) return
+  const lane = sessions.get(term)
+  if (!lane) {
+    queue.shift()
+    designStatus({ previewId: next.record.previewId, requestId: next.request.cid, state: 'needs-lane', message: 'The producing lane is no longer available.' })
+    return pumpDesign(term)
+  }
+  // sendTurn steers a busy Codex App Server turn; wait for the real idle edge.
+  if (lane.session?.turnActive) return
+  queue.shift()
+  const current = designArtifacts.get(next.record.previewId)
+  const live = current && resolveDesignSource(current.sourcePath, current.workspaceRoot)
+  if (!current || !live || live.revision !== next.record.revision) {
+    designStatus({ previewId: next.record.previewId, requestId: next.request.cid, state: 'stale', message: 'The artifact changed. Reselect the element.' })
+    return pumpDesign(term)
+  }
+  const active = { ...next, resultOk: false, proof: null, timer: null }
+  designActive.set(term, active)
+  designStatus({ previewId: next.record.previewId, requestId: next.request.cid, state: 'applying' })
+  // Safe transcript summary: never include host paths or the full locator packet.
+  const visible = { kind: 'you', text: `Design edit · ${next.request.target.name || next.request.target.tag}: ${next.request.mode === 'text' ? 'replace text' : next.request.intent}`, cid: next.request.cid, by: next.by }
+  stampEvent(visible); pushLog(lane, visible); bcast('code-event', { term, evt: visible })
+  try { lane.session.sendTurn(designPrompt({ record: next.record, request: next.request, by: next.by, restore: !!next.restoreRecord, priorRecord: next.restoreRecord })) }
+  catch { finishDesign(term, 'failed', { message: 'The producing lane could not start the edit.' }) }
+}
 // Push one manifest file into the room, attributed to `term`. The owner is
 // resolved by the WATCHER, not guessed here — each session/terminal writes to
 // its OWN outbox (handed in via TP_MOCKUP_OUTBOX), so the directory the file
 // landed in *is* its provenance. (Before: a per-room outbox + a "first session
 // in the Map" guess meant closing the generating terminal moved the cards to
 // whatever terminal was now first — they leaked into Terminal 1.)
-const handleManifest = async (box, file, term) => {
+const handleManifest = async (box, file, term, trustedDesignSource = false) => {
   // Ignore our own delivery receipts — writing <slug>.receipt.json into the
   // watched outbox re-fires fs.watch; without this guard it would re-trigger
   // handleManifest in a loop (it still ends in .json). Must come first.
@@ -1246,6 +1313,10 @@ const handleManifest = async (box, file, term) => {
   let m
   try { m = JSON.parse(fs.readFileSync(full, 'utf8')) } catch { return }
   if (!m?.slug) return
+  const producer = trustedDesignSource ? sessions.get(term) : null
+  const designRecord = producer && m.source
+    ? resolveDesignSource(m.source, producer.cwd || process.cwd())
+    : null
   // 2026-07-07: these used to swallow read errors silently — a transient
   // unreadable file (race with the render script, permissions, mid-write)
   // meant the manifest still POSTed with that field missing, and nothing
@@ -1271,15 +1342,40 @@ const handleManifest = async (box, file, term) => {
       headers: mockupHeaders,
       body: JSON.stringify({
         code: room, slug: m.slug, title: m.title, cid, ts: m.ts, term,
-        desktopPng: readB64(m.desktop), mobilePng: readB64(m.mobile), html: readTxt(m.html),
+        desktopPng: readB64(m.desktop), mobilePng: readB64(m.mobile), html: designRecord ? designRecord.source : readTxt(m.html),
+        ...(designRecord ? { previewId: designRecord.previewId, revision: designRecord.revision, sourceKnown: true } : {}),
       }),
     })
     if (!res.ok) {
       writeReceipt(false, res.status)
       process.stderr.write(`\n  ◇ mockup "${m.slug}" upload failed (${res.status}).\n`); return
     }
-    const { paths } = await res.json()
-    bcast('code-event', { term, evt: { kind: 'mockup', __struct: true, cid, term, slug: m.slug, title: m.title || m.slug, ts: m.ts, paths } })
+    const uploaded = await res.json()
+    const { paths } = uploaded
+    const designAccepted = !!(designRecord && uploaded?.payload?.sourceKnown)
+    const artifact = { kind: 'mockup', __struct: true, cid, term, slug: m.slug, title: m.title || m.slug, ts: m.ts, paths,
+      ...(designAccepted ? { previewId: designRecord.previewId, revision: designRecord.revision, sourceKnown: true } : {}) }
+    if (designAccepted) {
+      Object.assign(designRecord, { term, slug: m.slug, title: m.title || m.slug, desktop: m.desktop, mobile: m.mobile })
+      try {
+        const backupDir = path.join(box, '.design-revisions')
+        fs.mkdirSync(backupDir, { recursive: true })
+        designRecord.backupPath = path.join(backupDir, `${designRecord.revision}.html`)
+        if (!fs.existsSync(designRecord.backupPath)) fs.writeFileSync(designRecord.backupPath, designRecord.source)
+      } catch { /* restore stays unavailable if the host backup cannot be written */ }
+      designArtifacts.set(designRecord.previewId, designRecord)
+      const active = designActive.get(term)
+      const correlated = active && m.designRequestId === active.request.cid && m.parentRevision === active.record.revision
+      const dual = !!(paths?.html && paths?.desktop && paths?.mobile && m.desktop && m.mobile)
+      const expectedRevision = active?.restoreRecord?.revision
+      const revisionProvesChange = expectedRevision ? designRecord.revision === expectedRevision : designRecord.revision !== active?.record?.revision
+      if (correlated && dual && designRecord.sourcePath === active.record.sourcePath && revisionProvesChange) {
+        designRestore.set(designRecord.previewId, { priorRecord: active.record, request: active.request })
+        active.proof = artifact
+        maybeVerifyDesign(term)
+      }
+    }
+    bcast('code-event', { term, evt: artifact })
     writeReceipt(true, 200)
     process.stderr.write(`\n  ◆ mockup "${m.title || m.slug}" pushed to the room.\n`)
   } catch (e) {
@@ -1290,9 +1386,9 @@ const handleManifest = async (box, file, term) => {
 // Watch one outbox dir; `ownerFn()` resolves which terminal owns a manifest
 // dropped there (lazily, per event). Returns the FSWatcher so per-session/term
 // watchers can be torn down when their owner ends. Safe to call repeatedly.
-function watchOutbox(box, ownerFn) {
+function watchOutbox(box, ownerFn, trustedDesignSource = false) {
   try { fs.mkdirSync(box, { recursive: true }) } catch { return null }
-  try { return fs.watch(box, (_evt, file) => { handleManifest(box, file, ownerFn()).catch(() => {}) }) }
+  try { return fs.watch(box, (_evt, file) => { handleManifest(box, file, ownerFn(), trustedDesignSource).catch(() => {}) }) }
   catch { return null }   // fs.watch unsupported — mockups simply won't auto-surface
 }
 // A per-owner outbox lives at MOCKUP_OUTBOX/<kind>/<id> and is handed to that
@@ -1758,7 +1854,7 @@ function openStructured({ id, runtime = 'claude', model, effort, resume, log, co
   // TP_MOCKUP_OUTBOX below) and the watcher attributes every card to THIS id, so
   // they land on this session even after other terminals open/close.
   const mockupOutbox = ownerOutbox('sessions', id)
-  entry.mockupWatcher = watchOutbox(mockupOutbox, () => id)
+  entry.mockupWatcher = watchOutbox(mockupOutbox, () => id, true)
   // Visual QA runs in the bridge process, outside either agent runtime's sandbox.
   // It remains scoped to this lane's cwd and private mockup outbox.
   entry.viewport = new ViewportManager({ workspaceRoot: cwd || process.cwd(), ownerId: id, outbox: mockupOutbox })
@@ -2392,6 +2488,20 @@ function openStructured({ id, runtime = 'claude', model, effort, resume, log, co
       // _turnStart is cleared unconditionally so a stray post-settle event can't
       // re-notify off a stale stamp.
       if (evt.kind === 'result' || evt.kind === 'error') {
+        const edit = designActive.get(id)
+        if (edit) {
+          const successful = evt.kind === 'result' && (!evt.subtype || evt.subtype === 'success')
+          if (!successful) finishDesign(id, 'failed', { message: 'The producing lane did not complete the edit.' })
+          else {
+            edit.resultOk = true
+            designStatus({ previewId: edit.record.previewId, requestId: edit.request.cid, state: 'verifying', message: 'Waiting for correlated desktop and mobile renders…' })
+            edit.timer = setTimeout(() => finishDesign(id, 'failed', { message: 'The edit finished without a correlated desktop and mobile render.' }), 120_000)
+            edit.timer.unref?.()
+            maybeVerifyDesign(id)
+          }
+        } else if ((designQueues.get(id) || []).length) {
+          queueMicrotask(() => pumpDesign(id))
+        }
         if (entry.sideHandback) {
           const request = entry.sideHandback
           entry.sideHandback = null
@@ -2667,6 +2777,13 @@ function endStructured(id) {
     try { s.session?.end() } catch { /* noop */ }
     try { s.mockupWatcher?.close() } catch { /* noop */ }
     try { void s.viewport?.stop()?.catch(() => {}) } catch { /* noop */ }
+    const activeDesign = designActive.get(id)
+    if (activeDesign?.timer) clearTimeout(activeDesign.timer)
+    designActive.delete(id)
+    designQueues.delete(id)
+    for (const [previewId, record] of designArtifacts) if (record.term === id) designArtifacts.delete(previewId)
+    for (const [previewId, restore] of designRestore) if (restore.priorRecord?.term === id) designRestore.delete(previewId)
+    try { fs.rmSync(ownerOutbox('sessions', id), { recursive: true, force: true }) } catch { /* best-effort host artifact cleanup */ }
     sessions.delete(id)
     bcast('term-exit', { id })
     reapTerminalRow(id)    // bridge-side reap: delete the code_terminals row ourselves — the
@@ -3745,6 +3862,64 @@ flowChannel
     }
   })
 
+// Design control is a separate PRIVATE channel. The browser cannot target a
+// lane or path: both are derived from the host-only artifact registry.
+const seenDesignRequests = new Set()
+designChannel
+  .on('broadcast', { event: 'design-capability' }, ({ payload }) => {
+    const record = payload?.previewId && designArtifacts.get(String(payload.previewId))
+    const live = record && resolveDesignSource(record.sourcePath, record.workspaceRoot)
+    const ok = !!record && !!live && live.revision === record.revision && record.revision === payload?.revision && sessions.has(record.term)
+    designChannel.send({ type: 'broadcast', event: 'design-capability-res', payload: { previewId: String(payload?.previewId || ''), revision: String(payload?.revision || ''), ok } })
+  })
+  .on('broadcast', { event: 'design-apply' }, ({ payload }) => {
+    const verdict = validateDesignRequest(payload, designArtifacts)
+    const previewId = String(payload?.previewId || '')
+    const requestId = String(payload?.cid || '').slice(0, 80)
+    if (!verdict.ok) {
+      designStatus({ previewId, requestId, state: verdict.error === 'stale-preview' ? 'stale' : 'failed', message: verdict.error })
+      return
+    }
+    if (!requestId || seenDesignRequests.has(requestId)) return
+    seenDesignRequests.add(requestId)
+    if (seenDesignRequests.size > 500) seenDesignRequests.delete(seenDesignRequests.values().next().value)
+    const term = verdict.record.term
+    const queue = designQueues.get(term) || []
+    designQueues.set(term, queue)
+    if (queue.length >= 8) {
+      designStatus({ previewId, requestId, state: 'failed', message: 'Too many Design edits are queued for this lane.' })
+      return
+    }
+    queue.push({ ...verdict, by: 'A room member' })
+    designStatus({ previewId, requestId, state: 'queued' })
+    pumpDesign(term)
+  })
+  .on('broadcast', { event: 'design-restore' }, ({ payload }) => {
+    const previewId = String(payload?.previewId || '')
+    const requestId = String(payload?.cid || '').slice(0, 80)
+    const record = designArtifacts.get(previewId)
+    const restore = designRestore.get(previewId)
+    const live = record && resolveDesignSource(record.sourcePath, record.workspaceRoot)
+    if (!requestId || !record || !restore?.priorRecord?.backupPath || !live || live.revision !== record.revision || payload?.revision !== record.revision) {
+      designStatus({ previewId, requestId, state: 'stale', message: 'That verified revision can no longer be restored safely.' })
+      return
+    }
+    if (seenDesignRequests.has(requestId)) return
+    seenDesignRequests.add(requestId)
+    const queue = designQueues.get(record.term) || []
+    designQueues.set(record.term, queue)
+    if (queue.length >= 8) {
+      designStatus({ previewId, requestId, state: 'failed', message: 'Too many Design edits are queued for this lane.' })
+      return
+    }
+    queue.push({ record, restoreRecord: restore.priorRecord, request: { previewId, revision: record.revision, mode: 'restore', intent: 'restore previous verified revision', target: restore.request.target, cid: requestId }, by: 'A room member' })
+    designStatus({ previewId, requestId, state: 'queued', message: 'Restore queued in the producing lane.' })
+    pumpDesign(record.term)
+  })
+  .subscribe((status) => {
+    if (status === 'CHANNEL_ERROR' || status === 'TIMED_OUT' || status === 'CLOSED') process.stderr.write(`\n  ⚠ design realtime ${status} (tpdesign:${room}).\n`)
+  })
+
 // Watchdog — if the realtime channel is stuck (never connected, or dropped and
 // not recovered) for >60s, exit non-zero so a supervisor/launchd restarts a
 // clean process. Healthy long-lived connections never trip this (brokenSince=0).
@@ -3904,6 +4079,7 @@ async function shutdown(code = 0, farewell = true) {
   // topic (no presence to untrack, but the subscription + socket join outlived the
   // process teardown). Close it too so shutdown is symmetric.
   try { await supabase.removeChannel(flowChannel) } catch { /* noop */ }
+  try { await supabase.removeChannel(designChannel) } catch { /* noop */ }
   setTimeout(() => process.exit(code), 250)   // grace for the leave/close frames to flush
 }
 process.on('SIGINT', () => shutdown(0))

package/design-edit.mjs

@@ -0,0 +1,81 @@
+import crypto from 'node:crypto'
+import fs from 'node:fs'
+import path from 'node:path'
+
+const MAX_SOURCE_BYTES = 2 * 1024 * 1024
+const MAX_INTENT = 2_000
+const MAX_TEXT = 4_000
+
+const clean = (value, max) => String(value ?? '').replace(/\0/g, '').trim().slice(0, max)
+
+export function sourceRevision(source) {
+  return crypto.createHash('sha256').update(String(source)).digest('hex').slice(0, 24)
+}
+
+export function resolveDesignSource(file, workspaceRoot) {
+  if (!file || !workspaceRoot) return null
+  let sourcePath, root
+  try {
+    sourcePath = fs.realpathSync(file)
+    root = fs.realpathSync(workspaceRoot)
+    const stat = fs.statSync(sourcePath)
+    if (!stat.isFile() || stat.size > MAX_SOURCE_BYTES) return null
+  } catch { return null }
+  const rel = path.relative(root, sourcePath)
+  if (!rel || rel.startsWith('..') || path.isAbsolute(rel) || path.extname(sourcePath).toLowerCase() !== '.html') return null
+  // Generated bundles are evidence, not editable source. The agent may only receive
+  // an exact authored HTML artifact; it must never be pointed at dist output.
+  if (rel.split(path.sep).some((part) => ['dist', 'build', '.next', '.git', 'coverage', 'node_modules'].includes(part))) return null
+  const source = fs.readFileSync(sourcePath, 'utf8')
+  const revision = sourceRevision(source)
+  const previewId = crypto.createHash('sha256')
+    .update(`${sourcePath}\0${revision}`)
+    .digest('base64url').slice(0, 32)
+  return { previewId, revision, sourcePath, workspaceRoot: root, source }
+}
+
+function safeTarget(value) {
+  if (!value || typeof value !== 'object') return null
+  const rect = value.rect && typeof value.rect === 'object' ? {
+    x: Number(value.rect.x) || 0,
+    y: Number(value.rect.y) || 0,
+    width: Math.max(0, Number(value.rect.width) || 0),
+    height: Math.max(0, Number(value.rect.height) || 0),
+  } : null
+  return {
+    selector: clean(value.selector, 600),
+    xpath: clean(value.xpath, 600),
+    tag: clean(value.tag, 40).toLowerCase(),
+    role: clean(value.role, 80),
+    name: clean(value.name, 240),
+    text: clean(value.text, MAX_TEXT),
+    canEditText: value.canEditText === true,
+    rect,
+  }
+}
+
+export function validateDesignRequest(payload, registry) {
+  if (!payload || typeof payload !== 'object') return { ok: false, error: 'invalid-request' }
+  const previewId = clean(payload.previewId, 64)
+  const record = registry.get(previewId)
+  if (!record) return { ok: false, error: 'preview-unavailable' }
+  if (clean(payload.revision, 64) !== record.revision) return { ok: false, error: 'stale-preview' }
+  const target = safeTarget(payload.target)
+  if (!target?.selector && !target?.xpath) return { ok: false, error: 'select-an-element' }
+  const mode = payload.mode === 'text' ? 'text' : payload.mode === 'prompt' ? 'prompt' : null
+  if (!mode) return { ok: false, error: 'invalid-mode' }
+  const intent = clean(payload.intent, mode === 'text' ? MAX_TEXT : MAX_INTENT)
+  if (!intent) return { ok: false, error: mode === 'text' ? 'enter-text' : 'describe-change' }
+  if (mode === 'text' && !target.canEditText) return { ok: false, error: 'text-edit-not-safe' }
+  return { ok: true, record, request: { previewId, revision: record.revision, mode, intent, target, cid: clean(payload.cid, 80) } }
+}
+
+export function designPrompt({ record, request, by, restore = false, priorRecord = null }) {
+  const target = JSON.stringify(request.target, null, 2)
+  const action = restore
+    ? `Restore only the immediately previous Design Mode change by comparing the current artifact with this bridge-created verified backup: ${priorRecord?.backupPath || '(backup unavailable)'}. Do not overwrite unrelated changes.`
+    : request.mode === 'text'
+    ? `Replace only this element's visible text with:\n${request.intent}`
+    : `Apply this visual change to only the selected element unless the instruction explicitly requires its immediate context:\n${request.intent}`
+  return `A room member used ThinkPool Design Mode on the artifact below. This is an authorized source edit in your current workspace.\n\nArtifact source: ${record.sourcePath}\nWorkspace: ${record.workspaceRoot}\nExpected source revision: ${record.revision}\nRequested by: ${clean(by || 'A room member', 120)}\nOperation: ${restore ? 'restore the immediately previous verified Design Mode revision' : request.mode}\n\nSelected element:\n${target}\n\n${action}\n\nRules:\n- Re-read the exact artifact source and confirm its revision/content still matches the selected element before editing.\n- Edit the canonical source above; do not search for or edit a different plausible file.\n- Preserve unrelated content and styling.\n- Use the existing mockup render workflow to produce both desktop and mobile captures after the edit. Run it with TP_DESIGN_REQUEST_ID=${request.cid} and TP_DESIGN_PARENT_REVISION=${record.revision} in the command environment so the proof correlates to this request.\n- Do not claim this is live until both captures succeed and the room receives the manifest.\n- If the target is stale or ambiguous, stop without editing and explain that the person must reselect it.`
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thinkpool-pair",
-  "version": "0.7.216",
+  "version": "0.7.217",
   "description": "Share a local coding-agent CLI (Claude Code, Codex, Gemini, Aider, …) into a ThinkPool Code room, live.",
   "type": "module",
   "bin": {
@@ -38,6 +38,7 @@
     "flow-task-graph.mjs",
     "flow-preview.mjs",
     "viewport.mjs",
+    "design-edit.mjs",
     "flow-review.mjs",
     "flow-review-gate.mjs",
     "flow-review-reflect.mjs",