@dfosco/storyboard 0.7.0 → 0.8.1

package/src/core/canvas/server.test.js

@@ -14,7 +14,7 @@ function setup() {
   const canvasDir = path.join(root, 'src', 'canvas')
   fs.mkdirSync(canvasDir, { recursive: true })
 
-  const lastResponse = { status: null, body: null }
+  const lastResponse = { status: null, body: null, bytes: null, headers: null }
 
   const ctx = {
     root,
@@ -26,8 +26,24 @@ function setup() {
 
   const handler = createCanvasHandler(ctx)
 
+  // Streaming mock for binary GET responses (image fetches). Records the
+  // bytes + headers so tests can assert without coupling to real http.
+  function makeRes() {
+    let buf = Buffer.alloc(0)
+    return {
+      writeHead(status, headers) {
+        lastResponse.status = status
+        lastResponse.headers = headers
+      },
+      end(data) {
+        if (data) buf = Buffer.concat([buf, Buffer.isBuffer(data) ? data : Buffer.from(data)])
+        lastResponse.bytes = buf
+      },
+    }
+  }
+
   const invoke = (routePath, method, body = {}) =>
-    handler(null, null, { path: routePath, method, body })
+    handler(null, makeRes(), { path: routePath, method, body })
 
   return { invoke, root, canvasDir, lastResponse }
 }
@@ -377,3 +393,350 @@ describe('POST /batch', () => {
     expect(refs['1']).toMatch(/^connector-/)
   })
 })
+
+describe('POST /undo and POST /redo (event-id targeting)', () => {
+  let root, canvasDir, invoke, lastResponse
+
+  beforeEach(() => {
+    ({ invoke, root, canvasDir, lastResponse } = setup())
+    writeCanvas(canvasDir, 'undo-canvas', { title: 'Undo Canvas' })
+  })
+
+  afterEach(() => {
+    fs.rmSync(root, { recursive: true, force: true })
+  })
+
+  async function addSticky(text) {
+    await invoke('/widget', 'POST', {
+      name: 'undo-canvas',
+      type: 'sticky-note',
+      props: { text },
+      position: { x: 0, y: 0 },
+    })
+    return { widgetId: lastResponse.body.widget.id, eventId: lastResponse.body.eventId }
+  }
+
+  async function readState() {
+    await invoke('/read?name=undo-canvas', 'GET', {})
+    return lastResponse.body
+  }
+
+  it('appends an event id on every mutation', async () => {
+    const { eventId } = await addSticky('a')
+    expect(eventId).toMatch(/^evt_/)
+  })
+
+  it('reproduces the cq-enablement scenario: 3 deletes + undo restores only the most recent', async () => {
+    const a = await addSticky('a')
+    const b = await addSticky('b')
+    const c = await addSticky('c')
+
+    await invoke('/widget', 'DELETE', { name: 'undo-canvas', widgetId: a.widgetId })
+    const delAEventId = lastResponse.body.eventId
+    await invoke('/widget', 'DELETE', { name: 'undo-canvas', widgetId: b.widgetId })
+    const delBEventId = lastResponse.body.eventId
+    await invoke('/widget', 'DELETE', { name: 'undo-canvas', widgetId: c.widgetId })
+    const delCEventId = lastResponse.body.eventId
+
+    expect((await readState()).widgets).toEqual([])
+
+    // Undo only the LAST delete (c).
+    await invoke('/undo', 'POST', { name: 'undo-canvas', eventId: delCEventId })
+    expect(lastResponse.status).toBe(200)
+    expect(lastResponse.body.inverseEvent.event).toBe('widget_added')
+    expect(lastResponse.body.inverseEvent.meta).toEqual({ kind: 'undo', of: delCEventId })
+
+    const after = await readState()
+    expect(after.widgets).toHaveLength(1)
+    expect(after.widgets[0].id).toBe(c.widgetId)
+    // a and b stay deleted — the bug class would have resurrected them too.
+    expect(after.widgets.map((w) => w.id)).not.toContain(a.widgetId)
+    expect(after.widgets.map((w) => w.id)).not.toContain(b.widgetId)
+
+    // Tracking that we don't leave delAEventId / delBEventId mentioned.
+    void delAEventId
+    void delBEventId
+  })
+
+  it('undo of widget_updated reverts the props using prevProps', async () => {
+    const { widgetId } = await addSticky('original')
+
+    await invoke('/widget', 'PATCH', {
+      name: 'undo-canvas',
+      widgetId,
+      props: { text: 'edited' },
+    })
+    const editEventId = lastResponse.body.eventIds[0]
+
+    let state = await readState()
+    expect(state.widgets[0].props.text).toBe('edited')
+
+    await invoke('/undo', 'POST', { name: 'undo-canvas', eventId: editEventId })
+    state = await readState()
+    expect(state.widgets[0].props.text).toBe('original')
+  })
+
+  it('undo of widget_moved reverts the position using prevPosition', async () => {
+    const { widgetId } = await addSticky('a')
+
+    await invoke('/widget', 'PATCH', {
+      name: 'undo-canvas',
+      widgetId,
+      position: { x: 500, y: 600 },
+    })
+    const moveEventId = lastResponse.body.eventIds[0]
+
+    let state = await readState()
+    expect(state.widgets[0].position).toEqual({ x: 500, y: 600 })
+
+    await invoke('/undo', 'POST', { name: 'undo-canvas', eventId: moveEventId })
+    state = await readState()
+    expect(state.widgets[0].position).toEqual({ x: 0, y: 0 })
+  })
+
+  it('redo of an undone delete re-removes the widget', async () => {
+    const { widgetId } = await addSticky('a')
+    await invoke('/widget', 'DELETE', { name: 'undo-canvas', widgetId })
+    const delEventId = lastResponse.body.eventId
+
+    await invoke('/undo', 'POST', { name: 'undo-canvas', eventId: delEventId })
+    const undoEventId = lastResponse.body.eventId
+    expect((await readState()).widgets).toHaveLength(1)
+
+    // Redo with the undo event id — server emits the inverse of the undo,
+    // which is a fresh widget_removed.
+    await invoke('/redo', 'POST', { name: 'undo-canvas', eventId: undoEventId })
+    expect(lastResponse.body.inverseEvent.event).toBe('widget_removed')
+    expect(lastResponse.body.inverseEvent.meta).toEqual({ kind: 'redo', of: undoEventId })
+
+    expect((await readState()).widgets).toEqual([])
+  })
+
+  it('rejects undo on an unknown event id with 404', async () => {
+    await invoke('/undo', 'POST', { name: 'undo-canvas', eventId: 'evt_does_not_exist' })
+    expect(lastResponse.status).toBe(404)
+  })
+
+  it('rejects undo on a non-undoable event (widgets_replaced) with 400', async () => {
+    // Trigger a widgets_replaced via PUT /update with replaceAll
+    await invoke('/update', 'PUT', {
+      name: 'undo-canvas',
+      widgets: [],
+      replaceAll: true,
+    })
+    // Read the file to get the event id of the widgets_replaced event.
+    const filePath = path.join(canvasDir, 'undo-canvas.canvas.jsonl')
+    const lines = fs.readFileSync(filePath, 'utf-8').trim().split('\n').map((l) => JSON.parse(l))
+    const replacedEvt = lines.find((l) => l.event === 'widgets_replaced')
+    expect(replacedEvt?.id).toBeTruthy()
+
+    await invoke('/undo', 'POST', { name: 'undo-canvas', eventId: replacedEvt.id })
+    expect(lastResponse.status).toBe(400)
+    expect(lastResponse.body.error).toMatch(/cannot be undone/i)
+  })
+})
+
+describe('runaway-session hard ceiling compaction', () => {
+  let root, canvasDir, invoke, lastResponse
+
+  beforeEach(() => {
+    ({ invoke, root, canvasDir, lastResponse } = setup())
+    writeCanvas(canvasDir, 'big-canvas', { title: 'Big Canvas' })
+  })
+
+  afterEach(() => {
+    fs.rmSync(root, { recursive: true, force: true })
+  })
+
+  // setImmediate-based test helper
+  function flushSetImmediate() {
+    return new Promise((resolve) => setImmediate(resolve))
+  }
+
+  it('does not compact a small file (under the 2 MB threshold)', async () => {
+    const filePath = path.join(canvasDir, 'big-canvas.canvas.jsonl')
+    await invoke('/widget', 'POST', {
+      name: 'big-canvas',
+      type: 'sticky-note',
+      props: { text: 'hello' },
+      position: { x: 0, y: 0 },
+    })
+    await flushSetImmediate()
+    const sizeAfter = fs.statSync(filePath).size
+    expect(sizeAfter).toBeLessThan(2 * 1024 * 1024)
+    // File should still contain both canvas_created + widget_added events.
+    const events = fs.readFileSync(filePath, 'utf-8').trim().split('\n').map((l) => JSON.parse(l))
+    expect(events.length).toBe(2)
+    expect(events[0].event).toBe('canvas_created')
+    expect(events[1].event).toBe('widget_added')
+  })
+
+  it('compacts the file once it exceeds the runaway threshold', async () => {
+    const filePath = path.join(canvasDir, 'big-canvas.canvas.jsonl')
+
+    // Pre-bloat the file past 2 MB by appending raw garbage events. Each
+    // event has a unique id so the materializer treats it as valid.
+    const padding = 'x'.repeat(4000)
+    const bloatLines = []
+    for (let i = 0; i < 600; i++) {
+      bloatLines.push(JSON.stringify({
+        id: `evt_bloat_${i}`,
+        event: 'widget_added',
+        timestamp: '2026-01-01',
+        widget: { id: `bloat-${i}`, type: 'sticky-note', position: { x: 0, y: 0 }, props: { text: padding } },
+      }))
+    }
+    fs.appendFileSync(filePath, bloatLines.join('\n') + '\n')
+    const sizeBefore = fs.statSync(filePath).size
+    expect(sizeBefore).toBeGreaterThan(2 * 1024 * 1024)
+
+    // Trigger appendEvent — this should detect the runaway size and kick
+    // off a compaction.
+    await invoke('/widget', 'POST', {
+      name: 'big-canvas',
+      type: 'sticky-note',
+      props: { text: 'trigger' },
+      position: { x: 0, y: 0 },
+    })
+    // Compaction runs on setImmediate; flush it.
+    await flushSetImmediate()
+    await flushSetImmediate()
+
+    const sizeAfter = fs.statSync(filePath).size
+    expect(sizeAfter).toBeLessThan(sizeBefore)
+
+    // After compaction, file should be a single canvas_created event
+    // containing all the materialized widgets.
+    const lines = fs.readFileSync(filePath, 'utf-8').trim().split('\n')
+    expect(lines.length).toBe(1)
+    const baseline = JSON.parse(lines[0])
+    expect(baseline.event).toBe('canvas_created')
+    // 600 bloat widgets + 1 from the triggering append = 601.
+    expect(baseline.widgets.length).toBe(601)
+    // Sanity: state still reads cleanly via the normal /read endpoint.
+    await invoke('/read?name=big-canvas', 'GET', {})
+    expect(lastResponse.status).toBe(200)
+    expect(lastResponse.body.widgets.length).toBe(601)
+  })
+})
+
+describe('image routes — drafts/ subdirectory privacy layer', () => {
+  // Minimal 1x1 PNG (base64) for upload tests.
+  const PNG_DATA_URL =
+    'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR4nGNgAAIAAAUAAeImBZsAAAAASUVORK5CYII='
+
+  it('routes a draft-canvas upload into images/drafts/ and returns the drafts/ prefix', async () => {
+    const { invoke, root, lastResponse } = setup()
+
+    await invoke('/image', 'POST', { dataUrl: PNG_DATA_URL, canvasName: 'drafts/storyboarding' })
+
+    expect(lastResponse.status).toBe(201)
+    expect(lastResponse.body.success).toBe(true)
+    expect(lastResponse.body.filename).toMatch(/^drafts\//)
+    const filename = lastResponse.body.filename
+    const basename = filename.slice('drafts/'.length)
+    const draftFile = path.join(root, 'assets', 'canvas', 'images', 'drafts', basename)
+    const publicFile = path.join(root, 'assets', 'canvas', 'images', basename)
+    expect(fs.existsSync(draftFile)).toBe(true)
+    expect(fs.existsSync(publicFile)).toBe(false)
+  })
+
+  it('routes a non-draft-canvas upload into images/ as before', async () => {
+    const { invoke, root, lastResponse } = setup()
+
+    await invoke('/image', 'POST', { dataUrl: PNG_DATA_URL, canvasName: 'storyboarding' })
+
+    expect(lastResponse.status).toBe(201)
+    expect(lastResponse.body.filename).not.toMatch(/^drafts\//)
+    const filename = lastResponse.body.filename
+    const publicFile = path.join(root, 'assets', 'canvas', 'images', filename)
+    expect(fs.existsSync(publicFile)).toBe(true)
+  })
+
+  it('treats a canvas with `drafts` anywhere in its segments as draft', async () => {
+    const { invoke, root, lastResponse } = setup()
+
+    await invoke('/image', 'POST', { dataUrl: PNG_DATA_URL, canvasName: 'widget/drafts/v6' })
+
+    expect(lastResponse.status).toBe(201)
+    expect(lastResponse.body.filename).toMatch(/^drafts\//)
+    const draftFile = path.join(root, 'assets', 'canvas', 'images', 'drafts',
+      lastResponse.body.filename.slice('drafts/'.length))
+    expect(fs.existsSync(draftFile)).toBe(true)
+  })
+
+  it('GET /images/drafts/<basename> serves a draft image', async () => {
+    const { invoke, root, lastResponse } = setup()
+    const draftsDir = path.join(root, 'assets', 'canvas', 'images', 'drafts')
+    fs.mkdirSync(draftsDir, { recursive: true })
+    const payload = Buffer.from([1, 2, 3])
+    fs.writeFileSync(path.join(draftsDir, 'hello.png'), payload)
+
+    await invoke('/images/drafts/hello.png', 'GET', {})
+    expect(lastResponse.status).toBe(200)
+    expect(lastResponse.bytes).toEqual(payload)
+  })
+
+  it('GET /images/<basename> does NOT fall back to drafts/', async () => {
+    const { invoke, root, lastResponse } = setup()
+    const draftsDir = path.join(root, 'assets', 'canvas', 'images', 'drafts')
+    fs.mkdirSync(draftsDir, { recursive: true })
+    fs.writeFileSync(path.join(draftsDir, 'leak.png'), Buffer.from([1, 2, 3]))
+
+    await invoke('/images/leak.png', 'GET', {})
+    expect(lastResponse.status).toBe(404)
+  })
+
+  it('GET rejects deeper paths than one optional drafts/ segment', async () => {
+    const { invoke, lastResponse } = setup()
+
+    await invoke('/images/drafts/sub/foo.png', 'GET', {})
+    expect(lastResponse.status).toBe(400)
+  })
+
+  it('GET rejects path traversal even with drafts prefix', async () => {
+    const { invoke, lastResponse } = setup()
+
+    await invoke('/images/drafts/../etc.png', 'GET', {})
+    expect(lastResponse.status).toBe(400)
+  })
+
+  it('toggle-private preserves drafts/ prefix in returned filename', async () => {
+    const { invoke, root, lastResponse } = setup()
+    const draftsDir = path.join(root, 'assets', 'canvas', 'images', 'drafts')
+    fs.mkdirSync(draftsDir, { recursive: true })
+    fs.writeFileSync(path.join(draftsDir, 'foo.png'), Buffer.from([1, 2, 3]))
+
+    await invoke('/image/toggle-private', 'POST', { filename: 'drafts/foo.png' })
+
+    expect(lastResponse.status).toBe(200)
+    expect(lastResponse.body).toEqual({ success: true, filename: 'drafts/~foo.png', private: true })
+    expect(fs.existsSync(path.join(draftsDir, '~foo.png'))).toBe(true)
+    expect(fs.existsSync(path.join(draftsDir, 'foo.png'))).toBe(false)
+  })
+
+  it('toggle-private still works on bare basenames in images/', async () => {
+    const { invoke, root, lastResponse } = setup()
+    const imagesDir = path.join(root, 'assets', 'canvas', 'images')
+    fs.mkdirSync(imagesDir, { recursive: true })
+    fs.writeFileSync(path.join(imagesDir, 'bar.png'), Buffer.from([1, 2, 3]))
+
+    await invoke('/image/toggle-private', 'POST', { filename: 'bar.png' })
+
+    expect(lastResponse.status).toBe(200)
+    expect(lastResponse.body.filename).toBe('~bar.png')
+    expect(fs.existsSync(path.join(imagesDir, '~bar.png'))).toBe(true)
+  })
+
+  it('duplicate preserves drafts/ prefix', async () => {
+    const { invoke, root, lastResponse } = setup()
+    const draftsDir = path.join(root, 'assets', 'canvas', 'images', 'drafts')
+    fs.mkdirSync(draftsDir, { recursive: true })
+    fs.writeFileSync(path.join(draftsDir, 'storyboarding--2026-01-01--12-00-00.png'), Buffer.from([1, 2, 3]))
+
+    await invoke('/image/duplicate', 'POST', { filename: 'drafts/storyboarding--2026-01-01--12-00-00.png' })
+
+    expect(lastResponse.status).toBe(201)
+    expect(lastResponse.body.filename).toMatch(/^drafts\/storyboarding--/)
+  })
+})

package/src/core/canvas/terminal-server.js

@@ -23,7 +23,7 @@
  */
 
 import { execSync } from 'node:child_process'
-import { readFileSync, mkdirSync, writeFileSync, renameSync, existsSync, unlinkSync, rmSync } from 'node:fs'
+import { readFileSync, mkdirSync, writeFileSync, renameSync, existsSync, unlinkSync, rmSync, readdirSync } from 'node:fs'
 import { resolve, join, dirname } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { tmpdir } from 'node:os'
@@ -409,6 +409,110 @@ function publicSnapshotDir() {
   return join(process.cwd(), 'assets', '.storyboard-public', 'terminal-snapshots')
 }
 
+/** Public snapshot index filenames (single consolidated files for all agents). */
+const SNAPSHOT_INDEX_JSON = 'agents.snapshot.json'
+const SNAPSHOT_INDEX_TXT = 'agents-txt.snapshot.json'
+
+/** Max entries kept in the snapshot indexes before GC drops the oldest by timestamp. */
+const SNAPSHOT_INDEX_MAX_ENTRIES = 50
+
+/** In-memory cache of the snapshot indexes to avoid re-reading on every capture. */
+let snapshotIndexCache = null
+let snapshotTxtIndexCache = null
+let snapshotLegacyFilesCleaned = false
+
+function emptyIndex() {
+  return { version: 1, updatedAt: null, agents: {} }
+}
+
+function readIndexFile(filePath) {
+  try {
+    if (!existsSync(filePath)) return emptyIndex()
+    const parsed = JSON.parse(readFileSync(filePath, 'utf8'))
+    if (parsed && typeof parsed === 'object' && parsed.agents && typeof parsed.agents === 'object') {
+      return { version: parsed.version || 1, updatedAt: parsed.updatedAt || null, agents: parsed.agents }
+    }
+  } catch { /* fall through */ }
+  return emptyIndex()
+}
+
+function loadSnapshotIndexes() {
+  if (!snapshotIndexCache) {
+    snapshotIndexCache = readIndexFile(join(publicSnapshotDir(), SNAPSHOT_INDEX_JSON))
+  }
+  if (!snapshotTxtIndexCache) {
+    snapshotTxtIndexCache = readIndexFile(join(publicSnapshotDir(), SNAPSHOT_INDEX_TXT))
+  }
+  return { jsonIndex: snapshotIndexCache, txtIndex: snapshotTxtIndexCache }
+}
+
+/**
+ * Garbage-collect index entries to keep size manageable.
+ * Drops oldest entries by timestamp until under the cap. Operates on both
+ * indexes together so they stay in sync.
+ */
+function gcSnapshotIndexes(jsonIndex, txtIndex) {
+  const keys = Object.keys(jsonIndex.agents)
+  if (keys.length <= SNAPSHOT_INDEX_MAX_ENTRIES) return
+  const sorted = keys
+    .map((k) => ({ k, t: jsonIndex.agents[k]?.timestamp || '' }))
+    .sort((a, b) => (a.t < b.t ? -1 : a.t > b.t ? 1 : 0))
+  const dropCount = keys.length - SNAPSHOT_INDEX_MAX_ENTRIES
+  for (let i = 0; i < dropCount; i++) {
+    const id = sorted[i].k
+    delete jsonIndex.agents[id]
+    delete txtIndex.agents[id]
+  }
+}
+
+function atomicWriteJson(filePath, data) {
+  const tmpPath = filePath + '.tmp'
+  try {
+    writeFileSync(tmpPath, JSON.stringify(data, null, 2), 'utf8')
+    renameSync(tmpPath, filePath)
+  } catch (err) {
+    try { if (existsSync(tmpPath)) unlinkSync(tmpPath) } catch {} // eslint-disable-line no-empty
+    throw err
+  }
+}
+
+function writeSnapshotIndexes(jsonIndex, txtIndex) {
+  const sDir = publicSnapshotDir()
+  try { mkdirSync(sDir, { recursive: true }) } catch {} // eslint-disable-line no-empty
+  const now = new Date().toISOString()
+  jsonIndex.updatedAt = now
+  txtIndex.updatedAt = now
+  try {
+    atomicWriteJson(join(sDir, SNAPSHOT_INDEX_JSON), jsonIndex)
+  } catch (err) {
+    devLog().logEvent('error', 'Failed to write agents.snapshot.json', { error: err.message })
+  }
+  try {
+    atomicWriteJson(join(sDir, SNAPSHOT_INDEX_TXT), txtIndex)
+  } catch (err) {
+    devLog().logEvent('error', 'Failed to write agents-txt.snapshot.json', { error: err.message })
+  }
+}
+
+/**
+ * One-time cleanup: remove legacy per-widget snapshot files left in the
+ * public dir from before the consolidated-index format. Runs on first call.
+ */
+function cleanupLegacySnapshotFiles() {
+  if (snapshotLegacyFilesCleaned) return
+  snapshotLegacyFilesCleaned = true
+  const sDir = publicSnapshotDir()
+  if (!existsSync(sDir)) return
+  try {
+    for (const file of readdirSync(sDir)) {
+      if (file === SNAPSHOT_INDEX_JSON || file === SNAPSHOT_INDEX_TXT) continue
+      if (file.endsWith('.snapshot.json') || file.endsWith('.snapshot.txt')) {
+        try { unlinkSync(join(sDir, file)) } catch {} // eslint-disable-line no-empty
+      }
+    }
+  } catch { /* empty */ }
+}
+
 /**
  * Read the `private` prop for a widget from the terminal config.
  * Returns true if the widget has props.private === true.
@@ -496,39 +600,28 @@ function captureSnapshot({ tmuxName, widgetId, canvasId, prettyName, cols, rows,
     try { if (existsSync(txtTmpPath)) unlinkSync(txtTmpPath) } catch {} // eslint-disable-line no-empty
   }
 
-  // ── Public snapshot (assets/.storyboard-public/terminal-snapshots/) ──
+  // ── Public snapshot index (assets/.storyboard-public/terminal-snapshots/) ──
+  // We maintain two consolidated index files keyed by widgetId:
+  //   - agents.snapshot.json     → structured data
+  //   - agents-txt.snapshot.json → human-readable text payloads
+  cleanupLegacySnapshotFiles()
   const isPrivate = isWidgetPrivate(widgetId, canvasId)
-  const sDir = publicSnapshotDir()
-  const snapshotPath = join(sDir, `${widgetId}.snapshot.json`)
-  const snapshotTxtPath = join(sDir, `${widgetId}.snapshot.txt`)
-  const tildeSnapshotPath = join(sDir, `~${widgetId}.snapshot.json`)
-  const tildeSnapshotTxtPath = join(sDir, `~${widgetId}.snapshot.txt`)
+  const { jsonIndex, txtIndex } = loadSnapshotIndexes()
 
   if (isPrivate) {
-    // Rename existing public snapshots to tilde-prefixed (gitignored) versions
-    if (existsSync(snapshotPath)) {
-      try { renameSync(snapshotPath, tildeSnapshotPath) } catch {} // eslint-disable-line no-empty
-    }
-    if (existsSync(snapshotTxtPath)) {
-      try { renameSync(snapshotTxtPath, tildeSnapshotTxtPath) } catch {} // eslint-disable-line no-empty
-    }
+    let changed = false
+    if (jsonIndex.agents[widgetId]) { delete jsonIndex.agents[widgetId]; changed = true }
+    if (txtIndex.agents[widgetId]) { delete txtIndex.agents[widgetId]; changed = true }
+    if (changed) writeSnapshotIndexes(jsonIndex, txtIndex)
     return
   }
 
-  // If un-privated, restore from tilde if the public files don't exist yet
-  if (existsSync(tildeSnapshotPath) && !existsSync(snapshotPath)) {
-    try { renameSync(tildeSnapshotPath, snapshotPath) } catch {} // eslint-disable-line no-empty
-  }
-  if (existsSync(tildeSnapshotTxtPath) && !existsSync(snapshotTxtPath)) {
-    try { renameSync(tildeSnapshotTxtPath, snapshotTxtPath) } catch {} // eslint-disable-line no-empty
-  }
-
   const snapshotScrollback = getRollingBufferContent(tmuxName, SNAPSHOT_MAX_AGE_MS)
   const strippedPane = stripAnsi(paneContent)
   const strippedScrollback = stripAnsi(snapshotScrollback)
 
-  // ── JSON snapshot ──
-  const snapshotData = {
+  // ── JSON entry ──
+  jsonIndex.agents[widgetId] = {
     widgetId,
     canvasId,
     prettyName: prettyName || null,
@@ -539,24 +632,7 @@ function captureSnapshot({ tmuxName, widgetId, canvasId, prettyName, cols, rows,
     scrollback: strippedScrollback,
   }
 
-  try {
-    mkdirSync(sDir, { recursive: true })
-  } catch (err) {
-    devLog().logEvent('error', 'Failed to create public snapshot dir', { dir: sDir, error: err.message })
-    return
-  }
-
-  const snapshotTmpPath = snapshotPath + '.tmp'
-  try {
-    writeFileSync(snapshotTmpPath, JSON.stringify(snapshotData, null, 2), 'utf8')
-    renameSync(snapshotTmpPath, snapshotPath)
-  } catch (err) {
-    devLog().logEvent('error', 'Failed to write public snapshot JSON', { widgetId, error: err.message, path: snapshotPath })
-    try { if (existsSync(snapshotTmpPath)) unlinkSync(snapshotTmpPath) } catch {} // eslint-disable-line no-empty
-  }
-
-  // ── Human-readable text snapshot ──
-  const snapshotTxtTmpPath = snapshotTxtPath + '.tmp'
+  // ── Text entry ──
   try {
     const screenText = strippedPane.replace(/\r\n/g, '\n').replace(/\n+$/, '')
     const scrollText = strippedScrollback.replace(/\r\n/g, '\n').replace(/\n+$/, '')
@@ -583,12 +659,13 @@ function captureSnapshot({ tmuxName, widgetId, canvasId, prettyName, cols, rows,
       snpTxt += scrollText + '\n'
     }
 
-    writeFileSync(snapshotTxtTmpPath, snpTxt, 'utf8')
-    renameSync(snapshotTxtTmpPath, snapshotTxtPath)
+    txtIndex.agents[widgetId] = snpTxt
   } catch (err) {
-    devLog().logEvent('error', 'Failed to write public snapshot txt', { widgetId, error: err.message })
-    try { if (existsSync(snapshotTxtTmpPath)) unlinkSync(snapshotTxtTmpPath) } catch {} // eslint-disable-line no-empty
+    devLog().logEvent('error', 'Failed to build snapshot text entry', { widgetId, error: err.message })
   }
+
+  gcSnapshotIndexes(jsonIndex, txtIndex)
+  writeSnapshotIndexes(jsonIndex, txtIndex)
 }
 
 /** Start periodic snapshot capture for a session */
@@ -1209,11 +1286,15 @@ function handleConnection(ws, widgetId, canvasId, prettyName, widgetStartupComma
           const finalize = () => {
             if (completed) return
             completed = true
+            // Identity/role MUST be injected before postStartup. Commands like
+            // `/autopilot` flip the agent into a mode where the next message is
+            // consumed as a task — so we want canvas context in conversation
+            // history *first*, then the mode-toggling slash command.
+            injectIdentityMessage(tmuxName, { widgetId, displayName: prettyName, canvasId, branch, serverUrl })
+            injectRoleMessageForWidget(tmuxName, widgetId)
             if (postStartup) {
               tmuxSubmit(tmuxName, postStartup)
             }
-            injectIdentityMessage(tmuxName, { widgetId, displayName: prettyName, canvasId, branch, serverUrl })
-            injectRoleMessageForWidget(tmuxName, widgetId)
             // Bind to messaging bus for live delivery + backfill missed messages
             setTimeout(() => {
               migratePendingMessages(widgetId, branch, canvasId).then(() => {
@@ -1408,11 +1489,15 @@ function handleConnection(ws, widgetId, canvasId, prettyName, widgetStartupComma
                   clearInterval(pollInterval)
                   try { rmSync(readyFilePath, { force: true }) } catch { /* empty */ }
                   setTimeout(() => {
+                    // Identity/role/messaging-bind MUST happen BEFORE postStartup.
+                    // Slash commands like `/autopilot` flip the agent into a mode
+                    // where the next message is consumed as a task — so we want
+                    // canvas context (widgetId, configFile, role) in conversation
+                    // history first, then the mode-toggling slash command last.
+                    softBind()
                     if (postStartup) {
-                      tmuxSubmit(tmuxName, postStartup)
+                      setTimeout(() => tmuxSubmit(tmuxName, postStartup), 1500)
                     }
-                    // Ensure identity/bind happened (no-op if already soft-bound)
-                    softBind()
                   }, 500)
                   if (reason === 'soft-bind-timeout') {
                     devLog(`[terminal-server] readiness slow for ${widgetId} (${tmuxName}); soft-binding now, will run postStartup when .ready arrives`)
@@ -1765,15 +1850,17 @@ export function readTerminalBuffer(widgetId, { maxLength } = {}) {
 }
 
 /**
- * Read a terminal public snapshot by widget ID.
- * Checks new path first, falls back to legacy path.
+ * Read a terminal public snapshot by widget ID from the consolidated index.
+ * Falls back to legacy nested path if not present.
  */
 export function readTerminalSnapshot(widgetId, canvasId) {
-  // New path: assets/.storyboard-public/terminal-snapshots/<widgetId>.snapshot.json
-  const newPath = join(publicSnapshotDir(), `${widgetId}.snapshot.json`)
+  // New: consolidated index at agents.snapshot.json
+  const indexPath = join(publicSnapshotDir(), SNAPSHOT_INDEX_JSON)
   try {
-    if (existsSync(newPath)) {
-      return JSON.parse(readFileSync(newPath, 'utf8'))
+    if (existsSync(indexPath)) {
+      const parsed = JSON.parse(readFileSync(indexPath, 'utf8'))
+      const entry = parsed?.agents?.[widgetId]
+      if (entry) return entry
     }
   } catch { /* empty */ }