spexcode 0.6.1 → 0.6.2

package/spec-cli/src/session-files.ts

@@ -0,0 +1,121 @@
+import { accessSync, constants, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs'
+import { basename, isAbsolute, resolve } from 'node:path'
+import { readRecordEntry, sessionArtifactPath } from './layout.js'
+
+export class SessionFileError extends Error {
+  constructor(readonly status: 400 | 403 | 404 | 500, message: string) {
+    super(message)
+    this.name = 'SessionFileError'
+  }
+}
+
+type SessionFileLock = <T>(id: string, body: () => T) => T
+
+export const SESSION_FILE_PREVIEW_MAX_BYTES = 2 * 1024 * 1024
+export type SessionFilePreviewKind = 'text' | 'image'
+const TEXT_EXTENSIONS = new Set(['.txt', '.md', '.markdown', '.json', '.yaml', '.yml', '.toml', '.ini', '.log', '.csv', '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.css', '.html', '.xml', '.py', '.go', '.rs', '.java', '.sh', '.sql'])
+const IMAGE_TYPES: Record<string, string> = {
+  '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.webp': 'image/webp',
+}
+
+const filesPath = (id: string) => sessionArtifactPath(id, 'files.json')
+
+function requireSession(id: string): void {
+  const record = readRecordEntry(id)
+  if (record.kind === 'absent') throw new SessionFileError(404, `session ${id} does not exist`)
+  if (record.kind === 'corrupt') throw new SessionFileError(500, `session ${id} has an unreadable record: ${record.error}`)
+}
+
+function readFiles(id: string): string[] {
+  const path = filesPath(id)
+  let parsed: unknown
+  try { parsed = JSON.parse(readFileSync(path, 'utf8')) }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return []
+    throw new SessionFileError(500, `session file list is unreadable: ${path} — ${error instanceof Error ? error.message : String(error)}`)
+  }
+  if (!Array.isArray(parsed) || parsed.some((value) => typeof value !== 'string' || !isAbsolute(value)))
+    throw new SessionFileError(500, `session file list is invalid: ${path}`)
+  return [...new Set(parsed)]
+}
+
+function writeFiles(id: string, files: string[]): void {
+  const path = filesPath(id)
+  const tmp = `${path}.${process.pid}.tmp`
+  try {
+    writeFileSync(tmp, `${JSON.stringify(files, null, 2)}\n`)
+    renameSync(tmp, path)
+  } finally {
+    try { unlinkSync(tmp) } catch { /* rename already consumed the temporary file */ }
+  }
+}
+
+function currentFile(path: string): void {
+  try {
+    if (!statSync(path).isFile()) throw new SessionFileError(400, `not a regular file: ${path}`)
+    accessSync(path, constants.R_OK)
+  } catch (error) {
+    if (error instanceof SessionFileError) throw error
+    const code = (error as NodeJS.ErrnoException).code
+    if (code === 'ENOENT' || code === 'ENOTDIR') throw new SessionFileError(404, `file does not exist: ${path}`)
+    throw new SessionFileError(403, `file is not readable: ${path}`)
+  }
+}
+
+export function listSessionFiles(id: string): string[] {
+  requireSession(id)
+  return readSessionFiles(id)
+}
+
+// Session projections already hold a parsed record; re-checking session.json here would make an in-memory
+// projection depend on the public route's existence guard. The route-facing list keeps that guard above.
+export function readSessionFiles(id: string): string[] {
+  return readFiles(id)
+}
+
+export function addSessionFile(id: string, input: string, lock: SessionFileLock, cwd = process.cwd()): { path: string; added: boolean } {
+  const path = resolve(cwd, input)
+  currentFile(path)
+  return lock(id, () => {
+    requireSession(id)
+    const files = readFiles(id)
+    if (files.includes(path)) return { path, added: false }
+    writeFiles(id, [...files, path])
+    return { path, added: true }
+  })
+}
+
+export function retractSessionFile(id: string, input: string, lock: SessionFileLock, cwd = process.cwd()): { path: string; removed: boolean } {
+  const path = resolve(cwd, input)
+  return lock(id, () => {
+    requireSession(id)
+    const files = readFiles(id)
+    if (!files.includes(path)) return { path, removed: false }
+    writeFiles(id, files.filter((file) => file !== path))
+    return { path, removed: true }
+  })
+}
+
+export function openSessionFile(id: string, path: string): { path: string; name: string; size: number } {
+  requireSession(id)
+  if (!readFiles(id).includes(path)) throw new SessionFileError(403, 'that path was not posted by this session')
+  try {
+    const stat = statSync(path)
+    if (!stat.isFile()) throw new SessionFileError(404, `file no longer exists: ${path}`)
+    accessSync(path, constants.R_OK)
+    return { path, name: basename(path) || 'download', size: stat.size }
+  } catch (error) {
+    if (error instanceof SessionFileError) throw error
+    throw new SessionFileError(404, `file no longer exists: ${path}`)
+  }
+}
+
+export function sessionFilePreviewKind(path: string): { kind: SessionFilePreviewKind; contentType: string } | null {
+  const extension = basename(path).toLowerCase().match(/\.[^.]+$/)?.[0]
+  if (!extension) return null
+  if (TEXT_EXTENSIONS.has(extension)) return { kind: 'text', contentType: 'text/plain; charset=utf-8' }
+  const contentType = IMAGE_TYPES[extension]
+  return contentType ? { kind: 'image', contentType } : null
+}
+
+export const sessionFilesPath = (id: string) => filesPath(id)

package/spec-cli/src/session-follow.ts

@@ -2,7 +2,7 @@ import { existsSync } from 'node:fs'
 import { sessionStoreDir } from './layout.js'
 import { advanceFollow, followCursor, unreadSince } from './session-cursors.js'
 import { timelineDisplay, timelineEvents, timelineStamp } from './session-timeline.js'
-import { sessionLabel, type DisplayStatus, type Session } from './sessions.js'
+import { sessionTitle, type DisplayStatus, type Session } from './sessions.js'
 
 // @@@ session-follow - supervision is FOLLOWING a log past a cursor, never polling a derived board. One tick
 // costs ONE stat per target: if timeline.ndjson has not grown, nothing is opened and nothing is parsed. No
@@ -28,7 +28,7 @@ const trunc = (s: string, n: number): string => (s.length <= n ? s : `${s.slice(
 export function sessionEvent(s: Session): string {
   const note = s.note ? ` — note: ${s.note}` : ''
   const asked = s.promptPreview ? ` · asked: ${s.promptPreview}` : ''
-  return `[spex] ${s.status} · ${sessionLabel(s)} — act: ${NEXT[s.status] || '—'}${note}${asked}  [id ${s.id}]`
+  return `[spex] ${s.status} · ${sessionTitle(s)} — act: ${NEXT[s.status] || '—'}${note}${asked}  [id ${s.id}]`
 }
 // @@@ launchEvent - a session's FIRST sighting, emitted once per id whatever its status, so the stream is a
 // complete lifecycle feed: launched → [transitions] → closed. A launch's own first line is `active` (not
@@ -36,7 +36,7 @@ export function sessionEvent(s: Session): string {
 export function launchEvent(s: Session): string {
   const note = s.note ? ` — note: ${s.note}` : ''
   const asked = s.promptPreview ? ` · asked: ${s.promptPreview}` : ''
-  return `[spex] launched · ${sessionLabel(s)} — act: capture | send "<msg>"${note}${asked}  [id ${s.id}]`
+  return `[spex] launched · ${sessionTitle(s)} — act: capture | send "<msg>"${note}${asked}  [id ${s.id}]`
 }
 
 // `targets` is re-read every tick so a BROAD follow picks up sessions that launch while it runs; an explicit
@@ -131,7 +131,7 @@ export async function followSessions(emit: (line: string) => void, opts: FollowO
         const e = slice.events[k]
         if (e.kind === 'sent') {
           const s = row?.(id, f.prev ?? 'unknown', null)
-          if (s) emit(`${tag}[spex] message · ${sessionLabel(s)} — from ${e.from ?? 'human'}: ${trunc(e.text, 120)}  [id ${id}]`)
+          if (s) emit(`${tag}[spex] message · ${sessionTitle(s)} — from ${e.from ?? 'human'}: ${trunc(e.text, 120)}  [id ${id}]`)
           continue
         }
         const st = timelineDisplay(e)

package/spec-cli/src/session-reparent.ts

@@ -0,0 +1,33 @@
+import { apiBaseInfo, reparentSessionRecords, type SessionReparentResult } from './sessions.js'
+import { BackendError, backendConnectionRefused, clientReparent } from './client.js'
+
+export class SessionReparentRequestError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'SessionReparentRequestError'
+  }
+}
+
+export function parseReparentRequest(body: unknown): { children: string[]; parent: string } {
+  if (!body || typeof body !== 'object') throw new SessionReparentRequestError('reparent body must be JSON')
+  const raw = body as { children?: unknown; parent?: unknown }
+  if (!Array.isArray(raw.children) || !raw.children.length || raw.children.some((id) => typeof id !== 'string' || !id.trim()))
+    throw new SessionReparentRequestError('reparent children must be one or more session ids')
+  if (typeof raw.parent !== 'string' || !raw.parent.trim()) throw new SessionReparentRequestError('reparent parent must be a session id')
+  return { children: raw.children.map((id) => id.trim()), parent: raw.parent.trim() }
+}
+
+export async function reparentRequest(body: unknown): Promise<SessionReparentResult> {
+  const request = parseReparentRequest(body)
+  return reparentSessionRecords(request.children, request.parent)
+}
+
+export async function reparentSessions(children: string[], parent: string): Promise<SessionReparentResult> {
+  try {
+    return await clientReparent(children, parent)
+  } catch (error) {
+    if (!(error instanceof BackendError) || (await apiBaseInfo()).source === 'flag' || !backendConnectionRefused(error)) throw error
+    console.error('spex: no backend reachable — reparenting in-process under the session record locks')
+    return reparentSessionRecords(children, parent)
+  }
+}

package/spec-cli/src/session-timeline.ts

@@ -1,7 +1,9 @@
 import { randomUUID } from 'node:crypto'
-import { existsSync, readFileSync, appendFileSync, mkdirSync, statSync } from 'node:fs'
+import { existsSync, readFileSync, appendFileSync, mkdirSync, statSync, readdirSync, openSync, closeSync, readSync } from 'node:fs'
+import { basename, join } from 'node:path'
 import { sessionStoreDir, sessionArtifactPath, readAliasedRawRecord } from './layout.js'
 import type { Lifecycle, Proposal } from './sessions.js'
+import type { ExecutionTurn } from './execution-trace.js'
 
 // @@@ session-timeline - the session's append-only log in its global store dir: every authored-lifecycle
 // transition (status + proposal + the FULL note text) and every message addressed to it. It is what a
@@ -17,11 +19,97 @@ export type TimelineEvent =
   | { ts: string; kind: 'status'; status: Lifecycle; proposal: Proposal | null; note: string | null; display?: string }
   | { ts: string; kind: 'sent'; mid: string; text: string; from: string | null; replyVia?: 'note' }
 
+export type SentDispatchReceipt = {
+  operation: 'merge'
+  requestDigest: string
+  payloadHash: string
+  delivery?: { text: string; from: string | null }
+}
+type DispatchSettlement = { ts: string; kind: 'dispatch-settled'; operation: 'merge'; requestDigest: string; mid: string }
+type StoredTimelineEvent =
+  | Extract<TimelineEvent, { kind: 'status' }>
+  | (Extract<TimelineEvent, { kind: 'sent' }> & { dispatchReceipt?: SentDispatchReceipt })
+  | DispatchSettlement
+
 const timelinePath = (id: string): string => sessionArtifactPath(id, 'timeline.ndjson')
+const segmentsDir = (id: string): string => sessionArtifactPath(id, 'timeline')
+const SEGMENT = /^(\d+)\.ndjson$/
+const SEGMENT_NAME_WIDTH = 12
+const TAIL_BLOCK_BYTES = 64 * 1024
+
+// One logical timeline is legacy timeline.ndjson followed by immutable numbered segments. The directory
+// listing is its only index: numbering is append order, so there is no mutable manifest to repair.
+function segmentFiles(id: string): string[] {
+  try {
+    const dir = segmentsDir(id)
+    const names = readdirSync(dir).filter((name) => SEGMENT.test(name)).sort((a, b) => {
+      const an = BigInt(SEGMENT.exec(a)![1]), bn = BigInt(SEGMENT.exec(b)![1])
+      return an < bn ? -1 : an > bn ? 1 : 0
+    })
+    return names.map((name) => join(dir, name))
+  } catch { /* no numbered segments yet */ }
+  return []
+}
 
-function append(id: string, ev: TimelineEvent): void {
+function timelineFiles(id: string): string[] {
+  const files: string[] = []
+  const legacy = timelinePath(id)
+  if (existsSync(legacy)) files.push(legacy)
+  files.push(...segmentFiles(id))
+  return files
+}
+
+const segmentLimit = (): number => {
+  const configured = Number(process.env.SPEXCODE_TIMELINE_SEGMENT_BYTES)
+  return Number.isFinite(configured) ? Math.max(1024, Math.floor(configured)) : 4 * 1024 * 1024
+}
+
+function activeSegment(id: string, bytes: number): string {
+  const dir = segmentsDir(id)
+  mkdirSync(dir, { recursive: true })
+  const segments = segmentFiles(id)
+  const current = segments.at(-1)
+  if (!current) return join(dir, `${String(1).padStart(SEGMENT_NAME_WIDTH, '0')}.ndjson`)
+  try {
+    if (statSync(current).size === 0 || statSync(current).size + bytes <= segmentLimit()) return current
+  } catch { /* a vanished active segment is recreated under its next number */ }
+  const n = BigInt(SEGMENT.exec(basename(current))![1]) + 1n
+  return join(dir, `${String(n).padStart(SEGMENT_NAME_WIDTH, '0')}.ndjson`)
+}
+
+function append(id: string, ev: StoredTimelineEvent): void {
   mkdirSync(sessionStoreDir(id), { recursive: true })
-  appendFileSync(timelinePath(id), JSON.stringify(ev) + '\n')
+  const line = JSON.stringify(ev) + '\n'
+  appendFileSync(activeSegment(id, Buffer.byteLength(line)), line)
+}
+
+function parseLines(lines: string[]): StoredTimelineEvent[] {
+  return lines.map((l) => {
+    try { return JSON.parse(l) as StoredTimelineEvent } catch { return null }
+  }).filter((e): e is StoredTimelineEvent => e != null && (e.kind === 'status' || e.kind === 'sent' || e.kind === 'dispatch-settled'))
+}
+
+function tailPublicEvents(path: string, limit: number): Exclude<StoredTimelineEvent, DispatchSettlement>[] {
+  let fd: number | null = null
+  try {
+    const size = statSync(path).size
+    fd = openSync(path, 'r')
+    let start = size
+    let text = ''
+    while (start > 0) {
+      const next = Math.max(0, start - TAIL_BLOCK_BYTES)
+      const buf = Buffer.alloc(start - next)
+      readSync(fd, buf, 0, buf.length, next)
+      text = buf.toString('utf8') + text
+      const publicCount = parseLines(text.split('\n').filter(Boolean)).filter((event) => event.kind !== 'dispatch-settled').length
+      if (publicCount >= limit || next === 0) break
+      start = next
+    }
+    return parseLines(text.split('\n').filter(Boolean))
+      .filter((event): event is Exclude<StoredTimelineEvent, DispatchSettlement> => event.kind !== 'dispatch-settled')
+      .slice(-limit)
+  } catch { return [] }
+  finally { if (fd !== null) closeSync(fd) }
 }
 
 // Record a lifecycle value that has already landed in session.json. TypeScript state writers call this
@@ -37,28 +125,70 @@ export function recordStatus(id: string, status: Lifecycle, proposal: Proposal |
 // the caller reports the throw rather than a false success. `text` is the message BEFORE any mechanism insert
 // (hints are transport, not conversation); `replyVia` is the effective channel the prompt seam chose. Returns
 // the new line's `mid`, which a best-effort poke carries.
-export function appendSent(id: string, text: string, from: string | null, replyVia?: 'note'): { mid: string } {
+export function appendSent(id: string, text: string, from: string | null, replyVia?: 'note', dispatchReceipt?: SentDispatchReceipt): { mid: string } {
   const mid = randomUUID()
-  append(id, { ts: new Date().toISOString(), kind: 'sent', mid, text, from, ...(replyVia ? { replyVia } : {}) })
+  append(id, { ts: new Date().toISOString(), kind: 'sent', mid, text, from, ...(replyVia ? { replyVia } : {}), ...(dispatchReceipt ? { dispatchReceipt } : {}) })
   return { mid }
 }
 
+export type SentDispatchState = {
+  mid: string
+  payloadHash: string
+  delivery: SentDispatchReceipt['delivery'] | null
+  delivered: boolean
+}
+
+export function sentDispatchReceipt(id: string, operation: SentDispatchReceipt['operation'], requestDigest: string): SentDispatchState | null {
+  let found: Omit<SentDispatchState, 'delivered'> | null = null
+  const settled = new Set<string>()
+  for (const path of timelineFiles(id)) {
+    for (const event of parseLines(readFileSync(path, 'utf8').split('\n').filter(Boolean))) {
+      if (event.kind === 'sent' && !found && event.dispatchReceipt?.operation === operation && event.dispatchReceipt.requestDigest === requestDigest) {
+        found = { mid: event.mid, payloadHash: event.dispatchReceipt.payloadHash, delivery: event.dispatchReceipt.delivery ?? null }
+      } else if (event.kind === 'dispatch-settled' && event.operation === operation && event.requestDigest === requestDigest) {
+        settled.add(event.mid)
+      }
+    }
+  }
+  return found ? { ...found, delivered: settled.has(found.mid) } : null
+}
+
+export function settleSentDispatch(id: string, mid: string): void {
+  let receipt: SentDispatchReceipt | null = null
+  let settled = false
+  for (const path of timelineFiles(id)) {
+    for (const event of parseLines(readFileSync(path, 'utf8').split('\n').filter(Boolean))) {
+      if (event.kind === 'sent' && event.mid === mid && event.dispatchReceipt?.delivery) receipt = event.dispatchReceipt
+      if (event.kind === 'dispatch-settled' && event.mid === mid) settled = true
+    }
+  }
+  if (!receipt || settled) return
+  append(id, { ts: new Date().toISOString(), kind: 'dispatch-settled', operation: receipt.operation, requestDigest: receipt.requestDigest, mid })
+}
+
 // The unowned read: any process may take it with nothing but filesystem access, and taking it perturbs
 // nothing. Index = event position, which is what a cursor names ([[session-cursors]]).
 export function timelineEvents(id: string): TimelineEvent[] {
   try {
-    const p = timelinePath(id)
-    if (!existsSync(p)) return []
-    return readFileSync(p, 'utf8').split('\n').filter(Boolean).map((l) => {
-      try { return JSON.parse(l) as TimelineEvent } catch { return null }
-    }).filter((e): e is TimelineEvent => e != null && (e.kind === 'status' || e.kind === 'sent'))
+    return timelineFiles(id).flatMap((path) => parseLines(readFileSync(path, 'utf8').split('\n').filter(Boolean)))
+      .flatMap((stored): TimelineEvent[] => {
+        if (stored.kind === 'dispatch-settled') return []
+        if (stored.kind === 'status') return [stored]
+        const { dispatchReceipt: _receipt, ...event } = stored
+        return [event]
+      })
   } catch { return [] }
 }
 
 // the same L0 read taken as CHEAPLY as it can be: a follower ([[session-follow]]) ticks over many logs, so it
 // stats first and parses only what grew. null = no log yet (a session that has authored nothing).
 export function timelineStamp(id: string): string | null {
-  try { const s = statSync(timelinePath(id)); return `${s.size}:${s.mtimeMs}` }
+  try {
+    const path = timelineFiles(id).at(-1)
+    if (!path) return null
+    const s = statSync(path)
+    return `${path}:${s.size}:${s.mtimeMs}`
+  }
   catch { return null }
 }
 
@@ -86,13 +216,32 @@ export function lastHumanSendVia(id: string): 'note' | null {
   return null
 }
 
+// The current human turn is a durable fact from the accepted-message log, not a backend-local generation.
+export function currentHumanTurn(id: string): ExecutionTurn | null {
+  const evs = timelineEvents(id)
+  for (let i = evs.length - 1; i >= 0; i--) {
+    const e = evs[i]
+    if (e.kind === 'sent' && e.from == null) return { token: e.mid, acceptedAt: e.ts }
+  }
+  return null
+}
+
 // the read surface behind GET /api/sessions/:id/timeline: the last `limit` events, oldest first, each status
 // event carrying its composed display word. null = no such session (the route 404s).
 export function readTimeline(id: string, limit = 500): { events: TimelineEvent[] } | null {
   let raw: ReturnType<typeof readAliasedRawRecord>
   try { raw = readAliasedRawRecord(id) } catch { return null }
   if (!raw || !raw.governed) return null
-  const evs = timelineEvents(id)
-  const tail = evs.slice(Math.max(0, evs.length - Math.max(1, limit)))
-  return { events: tail.map((e) => (e.kind === 'status' ? { ...e, display: timelineDisplay(e) } : e)) }
+  const wanted = Math.max(1, limit)
+  const tail: Exclude<StoredTimelineEvent, DispatchSettlement>[] = []
+  for (const path of timelineFiles(id).reverse()) {
+    const remaining = wanted - tail.length
+    if (remaining <= 0) break
+    tail.unshift(...tailPublicEvents(path, remaining))
+  }
+  return { events: tail.map((e) => {
+    if (e.kind === 'status') return { ...e, display: timelineDisplay(e) }
+    const { dispatchReceipt: _receipt, ...event } = e
+    return event
+  }) }
 }

package/spec-cli/src/session-web.ts

@@ -0,0 +1,135 @@
+import { createHash } from 'node:crypto'
+import { readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { readRecordEntry, sessionArtifactPath, sessionStoreDir } from './layout.js'
+import { projectRuntimeRoot } from './project-store.js'
+
+export class SessionWebError extends Error {
+  constructor(readonly status: 400 | 403 | 404 | 500, message: string) {
+    super(message)
+    this.name = 'SessionWebError'
+  }
+}
+
+type SessionWebLock = <T>(id: string, body: () => T) => T
+export type SessionWeb = { url: string; key: string }
+
+const webPath = (id: string, projectRoot?: string): string => projectRoot
+  ? join(projectRuntimeRoot(join(projectRoot, '.git')), 'sessions', id, 'web.json')
+  : sessionArtifactPath(id, 'web.json')
+
+const recordPath = (id: string, projectRoot?: string): string => projectRoot
+  ? join(projectRuntimeRoot(join(projectRoot, '.git')), 'sessions', id, 'session.json')
+  : join(sessionStoreDir(id), 'session.json')
+
+function validSessionId(id: string): boolean {
+  return /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(id)
+}
+
+function requireSession(id: string, projectRoot?: string): void {
+  if (!validSessionId(id)) throw new SessionWebError(404, `session ${id} does not exist`)
+  if (!projectRoot) {
+    const record = readRecordEntry(id)
+    if (record.kind === 'absent') throw new SessionWebError(404, `session ${id} does not exist`)
+    if (record.kind === 'corrupt') throw new SessionWebError(500, `session ${id} has an unreadable record: ${record.error}`)
+    return
+  }
+  const path = recordPath(id, projectRoot)
+  let record: unknown
+  try { record = JSON.parse(readFileSync(path, 'utf8')) }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') throw new SessionWebError(404, `session ${id} does not exist`)
+    throw new SessionWebError(500, `session ${id} has an unreadable record: ${error instanceof Error ? error.message : String(error)}`)
+  }
+  if (!record || typeof record !== 'object' || (record as { session_id?: unknown }).session_id !== id)
+    throw new SessionWebError(500, `session ${id} has an unreadable record`)
+}
+
+export function canonicalSessionWebUrl(input: string): string {
+  let url: URL
+  try { url = new URL(input.trim()) }
+  catch { throw new SessionWebError(400, `invalid local web URL: ${input}`) }
+  const host = url.hostname.toLowerCase().replace(/^\[|\]$/g, '')
+  if (url.protocol !== 'http:' || !['127.0.0.1', 'localhost', '::1'].includes(host) || !url.port || url.username || url.password) {
+    throw new SessionWebError(400, 'web URL must be http://127.0.0.1:<port>/..., http://localhost:<port>/..., or http://[::1]:<port>/...')
+  }
+  if (url.search || url.hash) throw new SessionWebError(400, 'web URL must not include a query or fragment; publish the service base URL')
+  return url.href
+}
+
+export function sessionWebKey(url: string): string {
+  return createHash('sha256').update(url).digest('base64url')
+}
+
+function readWebs(id: string, projectRoot?: string): string[] {
+  const path = webPath(id, projectRoot)
+  let parsed: unknown
+  try { parsed = JSON.parse(readFileSync(path, 'utf8')) }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return []
+    throw new SessionWebError(500, `session web list is unreadable: ${path} — ${error instanceof Error ? error.message : String(error)}`)
+  }
+  if (!Array.isArray(parsed) || parsed.some((value) => typeof value !== 'string'))
+    throw new SessionWebError(500, `session web list is invalid: ${path}`)
+  try {
+    if (parsed.some((value) => canonicalSessionWebUrl(value) !== value)) throw new Error('not canonical')
+  } catch {
+    throw new SessionWebError(500, `session web list is invalid: ${path}`)
+  }
+  return [...new Set(parsed)]
+}
+
+function writeWebs(id: string, webs: string[]): void {
+  const path = webPath(id)
+  const tmp = `${path}.${process.pid}.tmp`
+  try {
+    writeFileSync(tmp, `${JSON.stringify(webs, null, 2)}\n`)
+    renameSync(tmp, path)
+  } finally {
+    try { unlinkSync(tmp) } catch { /* rename already consumed the temporary file */ }
+  }
+}
+
+const toWeb = (url: string): SessionWeb => ({ url, key: sessionWebKey(url) })
+
+export function listSessionWebs(id: string, projectRoot?: string): SessionWeb[] {
+  requireSession(id, projectRoot)
+  return readSessionWebs(id, projectRoot)
+}
+
+// Session projections already hold a parsed record; re-checking session.json here would make an in-memory
+// projection depend on the public route's existence guard. The route-facing list keeps that guard above.
+export function readSessionWebs(id: string, projectRoot?: string): SessionWeb[] {
+  return readWebs(id, projectRoot).map(toWeb)
+}
+
+export function addSessionWeb(id: string, input: string, lock: SessionWebLock): { url: string; added: boolean } {
+  const url = canonicalSessionWebUrl(input)
+  return lock(id, () => {
+    requireSession(id)
+    const webs = readWebs(id)
+    if (webs.includes(url)) return { url, added: false }
+    writeWebs(id, [...webs, url])
+    return { url, added: true }
+  })
+}
+
+export function retractSessionWeb(id: string, input: string, lock: SessionWebLock): { url: string; removed: boolean } {
+  const url = canonicalSessionWebUrl(input)
+  return lock(id, () => {
+    requireSession(id)
+    const webs = readWebs(id)
+    if (!webs.includes(url)) return { url, removed: false }
+    writeWebs(id, webs.filter((web) => web !== url))
+    return { url, removed: true }
+  })
+}
+
+export function postedSessionWeb(id: string, key: string, projectRoot?: string): URL {
+  requireSession(id, projectRoot)
+  const web = readWebs(id, projectRoot).map(toWeb).find((entry) => entry.key === key)
+  if (!web) throw new SessionWebError(403, 'that web service was not posted by this session')
+  return new URL(web.url)
+}
+
+export const sessionWebsPath = (id: string) => webPath(id)