spexcode 0.6.0 → 0.6.2

package/spec-cli/src/reviews.ts

@@ -1,7 +1,7 @@
 import { createHash } from 'node:crypto'
 import { listSessions } from './sessions.js'
 import { getBoard, getBoardForForgeRevision } from './graphCache.js'
-import { buildSessionEvals, type SessionEvals } from '../../spec-eval/src/sessioneval.js'
+import { type SessionEvalOrderRow, buildSessionEvals, type SessionEvals } from '../../spec-eval/src/sessioneval.js'
 import { evalTimeline } from '../../spec-eval/src/evaltab.js'
 import { issuesEnabled as issuesEnabledForReview } from './localIssues.js'
 import { issueStores as issueStoresForReview } from './issues.js'
@@ -42,6 +42,9 @@ export type PagedReview<T extends ReviewItem = ReviewItem> = {
 
 export type EvalDetailReview = {
   scope: string | null
+  requestedScope: string | null
+  scopeFallback: 'trunk' | null
+  availability: 'measured' | 'unmeasured' | 'missing'
   selected: ReviewItem | null
   history: ReviewItem[]
   neighbors: {
@@ -56,6 +59,16 @@ export type EvalDetailReview = {
   evalRevision?: SessionEvals['evalRevision']
 }
 
+type EvalDetailMetadata = {
+  scope?: string | null
+  requestedScope?: string | null
+  scopeFallback?: 'trunk' | null
+  summary?: SessionEvals['summary']
+  evalRevision?: SessionEvals['evalRevision']
+  // the scope's whole measured sequence, when `items` deliberately holds only the rendered window
+  sequence?: { node: string; scenario: string }[]
+}
+
 const revisionOf = (value: unknown): string => createHash('sha256').update(JSON.stringify(value)).digest('hex')
 
 export function reviewPageNumber(value: unknown): number {
@@ -113,7 +126,7 @@ export function paginateReview<T extends ReviewItem>(
     pageCount,
     prev: page > 1 ? page - 1 : null,
     next: page < pageCount || overflow ? page + 1 : null,
-    revision: revisionOf(revisionInputs),
+    revision: revisionOf({ page, source: revisionInputs }),
     ...responseModel(model),
   }
 }
@@ -217,15 +230,26 @@ export function scopedEvalReviewItems(model: SessionEvals): ReviewItem[] {
 
 const evalItemKey = (item: any): string => `${String(item?.node ?? '')}\0${String(item?.scenario ?? '')}`
 
-function evalNeighbor(item: any): EvalNeighbor {
+function evalNeighbor(item: any, stateOf: (row: { node: string; scenario: string }) => string): EvalNeighbor {
   return {
     node: String(item.node),
     scenario: String(item.scenario),
-    state: String(item.state ?? evalReviewState(item)),
+    state: stateOf(item),
   }
 }
 
-export function boundedEvalNeighbors(items: ReviewItem[], node: string, scenario: string, want = 5) {
+// `sequence` is the whole measured population in list order; `stateOf` answers only for rows whose freshness
+// was actually computed. On a focused build those are two different sets — the sequence spans the scope, the
+// states cover the selected row and its window — which is exactly why the state is looked up rather than
+// carried: a row this response does not render contributes its POSITION and nothing else.
+export function boundedEvalNeighbors(
+  sequence: { node: string; scenario: string }[],
+  node: string,
+  scenario: string,
+  stateOf: (row: { node: string; scenario: string }) => string,
+  want = 5,
+) {
+  const items = sequence
   const key = `${node}\0${scenario}`
   const index = items.findIndex((item) => evalItemKey(item) === key)
   if (index < 0) return { prev: [], next: [], total: items.length, index: null, order: 'default' as const }
@@ -235,8 +259,8 @@ export function boundedEvalNeighbors(items: ReviewItem[], node: string, scenario
   const nextN = Math.min(after, Math.max(Math.ceil(take / 2), take - before))
   const prevN = Math.min(before, take - nextN)
   return {
-    prev: items.slice(index - prevN, index).reverse().map(evalNeighbor),
-    next: items.slice(index + 1, index + 1 + nextN).map(evalNeighbor),
+    prev: items.slice(index - prevN, index).reverse().map((item) => evalNeighbor(item, stateOf)),
+    next: items.slice(index + 1, index + 1 + nextN).map((item) => evalNeighbor(item, stateOf)),
     total: items.length,
     index,
     order: 'default' as const,
@@ -248,59 +272,102 @@ export function projectEvalDetail(
   historySource: ReviewItem[],
   node: string,
   scenario: string,
-  metadata: { scope?: string | null; summary?: SessionEvals['summary']; evalRevision?: SessionEvals['evalRevision'] } = {},
+  metadata: EvalDetailMetadata = {},
 ): EvalDetailReview {
   const results = items.filter((item: any) => item.filterKind === EVAL_FILTER_KIND.RESULT)
   const selected = results.find((item) => evalItemKey(item) === `${node}\0${scenario}`) ?? null
+  const availability = selected
+    ? 'measured'
+    : items.some((item: any) => evalItemKey(item) === `${node}\0${scenario}` && item.filterKind === EVAL_FILTER_KIND.BLIND)
+      ? 'unmeasured'
+      : 'missing'
   const history = historySource.filter((reading: any) => String(reading.scenario) === scenario)
-  const neighbors = boundedEvalNeighbors(results, node, scenario)
+  const stateByKey = new Map(results.map((item: any) => [evalItemKey(item), String(item.state ?? evalReviewState(item))]))
+  const sequence = metadata.sequence
+    ?? results.map((item: any) => ({ node: String(item.node), scenario: String(item.scenario) }))
+  const neighbors = boundedEvalNeighbors(sequence, node, scenario,
+    (row) => stateByKey.get(evalItemKey(row)) ?? 'empty')
   const scope = metadata.scope ?? null
+  const requestedScope = metadata.requestedScope ?? scope
+  const scopeFallback = metadata.scopeFallback ?? null
   return {
     scope,
+    requestedScope,
+    scopeFallback,
+    availability,
     selected,
     history,
     neighbors,
-    revision: revisionOf({ scope, selected, history, neighbors, summary: metadata.summary, evalRevision: metadata.evalRevision }),
+    revision: revisionOf({ scope, requestedScope, scopeFallback, availability, selected, history, neighbors, summary: metadata.summary, evalRevision: metadata.evalRevision }),
     ...(metadata.summary ? { summary: metadata.summary } : {}),
     ...(metadata.evalRevision ? { evalRevision: metadata.evalRevision } : {}),
   }
 }
 
-export async function evalDetailReview(node: string, scenario: string, scope?: string | null): Promise<EvalDetailReview | null> {
+// the measured population in list order, from the freshness-free rows: a filed reading leads (newest first),
+// and the tie-breaks are the identity ones — the SAME comparison `byNewest` applies, over the only fields it
+// actually reads. Blind rows never enter, exactly as the detail's own `results` filter excludes them.
+export function measuredSequence(order: SessionEvalOrderRow[]): { node: string; scenario: string }[] {
+  return order.filter((row) => row.ts)
+    .sort((a, b) => String(b.ts ?? '').localeCompare(String(a.ts ?? ''))
+      || a.node.localeCompare(b.node) || a.scenario.localeCompare(b.scenario))
+    .map((row) => ({ node: row.node, scenario: row.scenario }))
+}
+
+// the nodes whose verdicts the response will publish: the selected row's, plus a window wide enough to
+// contain any neighbour boundedEvalNeighbors can choose (it takes at most five, split around the index).
+export function focusNodes(order: SessionEvalOrderRow[], node: string, scenario: string): string[] {
+  const sequence = measuredSequence(order)
+  const index = sequence.findIndex((row) => row.node === node && row.scenario === scenario)
+  if (index < 0) return [node]
+  return [...new Set([node, ...sequence.slice(Math.max(0, index - 6), index + 7).map((row) => row.node)])]
+}
+
+async function trunkEvalDetailReview(node: string, scenario: string, metadata: EvalDetailMetadata = {}): Promise<EvalDetailReview> {
+  await getBoard()
+  const snapshot = readReviewSnapshot()
+  const sourceNode = snapshot.evalNodes.find((candidate) => candidate.id === node)
+  return projectEvalDetail(trunkEvalReviewItems(snapshot.evalNodes), sourceNode?.readings ?? [], node, scenario, metadata)
+}
+
+export async function evalDetailReview(node: string, scenario: string, scope?: string | null): Promise<EvalDetailReview> {
   if (scope) {
-    const model = await buildSessionEvals(scope)
-    if (!model) return null
+    // A detail renders ONE row plus at most five neighbours, but owes the whole population's index/total.
+    // So name the window from the freshness-free sequence and let only those nodes pay the freshness pass;
+    // a build that finds a full cached model ignores the pick and answers from it instead.
+    const model = await buildSessionEvals(scope, (order) => focusNodes(order, node, scenario))
+    if (!model) return trunkEvalDetailReview(node, scenario, { requestedScope: scope, scopeFallback: 'trunk' })
     const sourceNode = model.nodes.find((candidate) => candidate.id === node)
     return projectEvalDetail(scopedEvalReviewItems(model), sourceNode?.evals ?? [], node, scenario, {
       scope,
+      requestedScope: scope,
       summary: model.summary,
       evalRevision: model.evalRevision,
+      ...(model.order ? { sequence: measuredSequence(model.order) } : {}),
     })
   }
-  await getBoard()
-  const snapshot = readReviewSnapshot()
-  const sourceNode = snapshot.evalNodes.find((candidate) => candidate.id === node)
-  return projectEvalDetail(trunkEvalReviewItems(snapshot.evalNodes), sourceNode?.readings ?? [], node, scenario)
+  return trunkEvalDetailReview(node, scenario)
 }
 
-async function timelineEvalReview(text: string, requestedPage: unknown) {
-  const node = readToken(text, 'node')
-  if (!node) return null
-  const [timeline, sessions] = await Promise.all([evalTimeline(node), listSessions()])
-  const measured = new Set(timeline.readings.map((reading) => reading.scenario))
-  const items = [
-    ...timeline.scenarios.filter((scenario) => !measured.has(scenario.name)).map((scenario) => ({
+export function timelineEvalReviewItems(timeline: Awaited<ReturnType<typeof evalTimeline>>, node: string): ReviewItem[] {
+  const declared = new Set(timeline.scenarios.map((scenario) => scenario.name))
+  const latest = new Map<string, any>()
+  for (const reading of timeline.readings) {
+    if (declared.has(reading.scenario) && !latest.has(reading.scenario)) latest.set(reading.scenario, reading)
+  }
+  return [
+    ...timeline.scenarios.filter((scenario) => !latest.has(scenario.name)).map((scenario) => ({
       ...scenario,
       scenario: scenario.name,
       node,
       filterKind: EVAL_FILTER_KIND.UNMEASURED,
     })),
-    ...timeline.readings.map((reading, index) => ({
+    ...[...latest.values()].map((reading) => ({
       ...reading,
       state: evalReviewState(reading),
       node,
       filterKind: EVAL_FILTER_KIND.RESULT,
-      filterKey: `${EVAL_FILTER_KIND.RESULT}:${index}`,
+      filterKey: `${EVAL_FILTER_KIND.RESULT}:${reading.scenario}`,
     })),
     ...(timeline.dangling ?? []).map((track) => ({
       ...track,
@@ -309,6 +376,13 @@ async function timelineEvalReview(text: string, requestedPage: unknown) {
       filterKey: `${EVAL_FILTER_KIND.DANGLING}:${track.threadId}`,
     })),
   ]
+}
+
+async function timelineEvalReview(text: string, requestedPage: unknown) {
+  const node = readToken(text, 'node')
+  if (!node) return null
+  const [timeline, sessions] = await Promise.all([evalTimeline(node), listSessions()])
+  const items = timelineEvalReviewItems(timeline, node)
   const filtered = evalFilterModel(items, tokenFilterState(text, 'eval'), { sessions, defaultKind: 'all', defaultSection: '' })
   return {
     scope: null,
@@ -335,14 +409,13 @@ export async function evalsReview(query: string | undefined, requestedPage: unkn
     const filtered = evalFilterModel(items, tokenFilterState(text, 'eval'), { sessions, defaultKind: 'all', defaultSection: '' })
     return {
       scope,
-      gates: model.gates,
+      gates: [],
       unknown: model.nodes.reduce((count, node) => count + (node.unknownCoverage?.length ?? 0), 0),
       summary: model.summary,
       evalRevision: model.evalRevision,
-      impact: model.impact,
       ...paginateReview(items, filtered.shown, filtered, requestedPage, {
-        domain: 'evals', scope, items, gates: model.gates, summary: model.summary,
-        evalRevision: model.evalRevision, impact: model.impact, sessions: sessions.map((session) => session.id),
+        domain: 'evals', scope, query: text, gates: [], summary: model.summary,
+        evalRevision: model.evalRevision, sessions: sessions.map((session) => session.id),
       }),
     }
   }

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

@@ -0,0 +1,68 @@
+import { streamSSE } from 'hono/streaming'
+import type { Context } from 'hono'
+import { harnessById } from './harness.js'
+import { readAliasedRawRecord } from './layout.js'
+import { currentHumanTurn } from './session-timeline.js'
+import type { ExecutionStep, ExecutionTurn } from './execution-trace.js'
+
+export type SessionExecution = Readonly<{
+  revision: string
+  turnId: string | null
+  workingNote: string | null
+  steps: readonly ExecutionStep[]
+}>
+
+const absentExecution = (turn: ExecutionTurn | null = null): SessionExecution => ({ revision: `turn:${turn?.token ?? '0'}`, turnId: turn?.token ?? null, workingNote: null, steps: [] })
+
+// This is deliberately a read projection. Native transcript bytes stay within the adapter, while the API owns
+// only enough information for the frontend's fixed renderer to paint the current execution slice.
+export function readSessionExecution(id: string): SessionExecution | null {
+  let record: ReturnType<typeof readAliasedRawRecord>
+  try { record = readAliasedRawRecord(id) } catch { return null }
+  if (!record?.governed) return null
+  const turn = currentHumanTurn(id)
+  const threadId = typeof record.harness_session_id === 'string' ? record.harness_session_id : ''
+  if (!threadId) return absentExecution(turn)
+  try {
+    const trace = harnessById(typeof record.harness === 'string' && record.harness ? record.harness : 'claude')
+      .executionTrace(threadId, turn)
+    return trace || absentExecution(turn)
+  } catch {
+    // A missing/unreadable native source is an absent transient trace, not a synthetic conversation failure.
+    return absentExecution(turn)
+  }
+}
+
+const TRACE_TICK_MS = 500
+const HEARTBEAT_TICKS = 20
+
+export async function sessionExecutionStream(c: Context) {
+  const id = c.req.param('id') || ''
+  if (!readSessionExecution(id)) return c.json({ error: 'no such session' }, 404)
+  return streamSSE(c, async (stream) => {
+    let aborted = false
+    let lastRevision = ''
+    let ticks = 0
+    const publish = async (): Promise<boolean> => {
+      const execution = readSessionExecution(id)
+      if (!execution) return false
+      if (execution.revision === lastRevision) return true
+      lastRevision = execution.revision
+      await stream.writeSSE({ event: 'execution', data: JSON.stringify(execution) })
+      return true
+    }
+
+    stream.onAbort(() => { aborted = true })
+    try {
+      if (!await publish()) return
+      while (!aborted) {
+        await stream.sleep(TRACE_TICK_MS)
+        if (aborted) break
+        if (!await publish()) break
+        if (++ticks % HEARTBEAT_TICKS === 0) await stream.writeSSE({ event: 'ping', data: 'x' })
+      }
+    } catch {
+      // EventSource reconnects a dropped stream. A native trace read must never take down the session server.
+    }
+  })
+}

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)
+  }
+}