spexcode 0.6.1 → 0.6.2

package/spec-cli/src/cli.ts

@@ -57,7 +57,7 @@ function flushExit(code = 0): Promise<never> {
 }
 const has = (name: string) => process.argv.includes(`--${name}`)
 // bare positionals after argv index `from`, skipping flags and their values (selectors for ls/watch).
-const VALUE_FLAGS = new Set(['--status', '--as', '--interval', '--propose', '--note', '--node', '--prompt', '--prompt-file', '--timeout', '--reason', '--out', '--password', '--tls-cert', '--tls-key', '--harness', '--launcher', '--harness-session', '--port', '--api', '--api-port', '--host', '--preset', '--limit', '--session', '--depth', '--focus', '--keys', '--allow-stop', '--allow-resume', '--ttl-ms', '--wait-ms', '--adapter', '--thread', '--tmux', '--worktree', '--branch'])
+const VALUE_FLAGS = new Set(['--status', '--as', '--interval', '--propose', '--note', '--node', '--prompt', '--prompt-file', '--timeout', '--reason', '--out', '--password', '--tls-cert', '--tls-key', '--harness', '--launcher', '--harness-session', '--port', '--api', '--api-port', '--host', '--preset', '--limit', '--session', '--depth', '--focus', '--keys', '--allow-stop', '--allow-resume', '--ttl-ms', '--wait-ms', '--adapter', '--thread', '--tmux', '--worktree', '--branch', '--to', '--name', '--base'])
 function positionals(from: number): string[] {
   const out: string[] = []
   for (let i = from; i < process.argv.length; i++) {
@@ -81,6 +81,51 @@ function rejectUnknownFlags(command: string, from: number, allowed: readonly str
   }
 }
 
+type SessionSendArgs =
+  | { selector: string; kind: 'text'; text: string }
+  | { selector: string; kind: 'keys'; keys: string[] }
+
+function sessionSendUsage(detail: string, keys = false): never {
+  console.error(`spex session send: ${detail}`)
+  console.error(keys
+    ? 'usage: spex session send <SEL> --keys "<keys>"   (e.g. "Up Up Enter", "C-r", single chars — last resort; try a plain send first)'
+    : 'usage: spex session send <SEL> "<msg>" [--api <url> | --port <n>]\n       spex session send <SEL> [--api <url> | --port <n>] -- <option-shaped-msg>')
+  process.exit(2)
+}
+
+function parseSessionSendArgs(args: string[]): SessionSendArgs {
+  const valueFlags = new Set(['--api', '--port', '--keys', '--password'])
+  const bareFlags = new Set(['--insecure'])
+  const values = new Map<string, string>()
+  const positionals: string[] = []
+  let endOfOptions = false
+  for (let i = 0; i < args.length; i++) {
+    const token = args[i]
+    if (!endOfOptions && token === '--') { endOfOptions = true; continue }
+    if (!endOfOptions && token.startsWith('--')) {
+      if (!valueFlags.has(token) && !bareFlags.has(token)) sessionSendUsage(`unknown flag ${token}`)
+      if (values.has(token)) sessionSendUsage(`${token} may appear only once`, token === '--keys')
+      values.set(token, '')
+      if (bareFlags.has(token)) continue
+      const value = args[++i]
+      if (value === undefined || value === '' || value.startsWith('--')) sessionSendUsage(`${token} expects one non-empty value`, token === '--keys')
+      values.set(token, value)
+      continue
+    }
+    positionals.push(token)
+  }
+  if (values.has('--api') && values.has('--port')) sessionSendUsage('--api and --port are alternate routes; choose one')
+  const rawKeys = values.get('--keys')
+  if (rawKeys !== undefined) {
+    if (positionals.length !== 1) sessionSendUsage('raw keys take one selector and no text message', true)
+    const keys = rawKeys.split(/\s+/).filter(Boolean)
+    if (!keys.length) sessionSendUsage('--keys expects one non-empty value', true)
+    return { selector: positionals[0], kind: 'keys', keys }
+  }
+  if (positionals.length !== 2) sessionSendUsage('plain send requires exactly one selector and one message')
+  return { selector: positionals[0], kind: 'text', text: positionals[1] }
+}
+
 const SIGNPOSTS: Record<string, string> = {
   search: 'spex spec search <query>',
   owner: 'spex spec owner <path>',
@@ -170,18 +215,22 @@ async function localWatchTargetsOrExit(selectors: string[], verb: string): Promi
   return targets
 }
 
-async function resolveSelectorOrExit(selector: string): Promise<string> {
+async function resolveSessionOrExit(selector: string): Promise<import('./sessions.js').Session> {
   if (!selector) { console.error('spex: missing session selector (id | id-prefix | node | branch | . for self)'); process.exit(2) }
   const { resolveClientSession } = await import('./client.js')
-  const { sessionLabel } = await import('./sessions.js')
+  const { sessionTitle } = await import('./sessions.js')
   const r = await resolveClientSession(selector)
-  if ('ok' in r) return r.ok.id
+  if ('ok' in r) return r.ok
   if ('none' in r) { console.error(`spex: no such session: ${selector}`); process.exit(2) }
   console.error(`spex: ambiguous selector "${selector}" matches ${r.ambiguous.length} sessions — be more specific:`)
-  for (const s of r.ambiguous) console.error(`  ${s.id.slice(0, 8)}  ${sessionLabel(s)}`)
+  for (const s of r.ambiguous) console.error(`  ${s.id.slice(0, 8)}  ${sessionTitle(s)}`)
   process.exit(2)
 }
 
+async function resolveSelectorOrExit(selector: string): Promise<string> {
+  return (await resolveSessionOrExit(selector)).id
+}
+
 // the [[session-eval]] EXPORT artifact behind `spex eval ls --session <SEL> --export`: fetch the
 // backend-rendered self-contained HTML, write it (--out, else a tmp file) or open it (--open). Never returns.
 async function evalExport(id: string): Promise<never> {
@@ -337,11 +386,11 @@ if (cmd === 'serve') {
     console.log(h)
   } else console.log(overviewHelp())
 } else if (cmd === 'guide') {
-  const { guideText } = await import('./guide.js')
+  const { guideText, guideTopics } = await import('./guide.js')
   if (process.argv[3] === 'config') signpost('spex guide config', 'spex guide settings')
   const text = guideText(process.argv[3])
   if (text === null) {
-    console.error(`spex guide: no topic '${process.argv[3]}'. Topics: spec, eval, settings, footprint. Run \`spex guide\` (no topic) for the setup workflow, \`spex help\` for the command map.`)
+    console.error(`spex guide: no topic '${process.argv[3]}'. Topics: ${guideTopics().join(', ')}. Run \`spex guide\` (no topic) for the setup workflow, \`spex help\` for the command map.`)
     process.exit(2)
   }
   console.log(text)
@@ -425,9 +474,25 @@ if (cmd === 'serve') {
       console.log(`${rel} — no spec claims this yet (uncovered). If your change is substantive, give it a home before it drifts.`)
     } else if (owners.length === 0) {
       // related-only: lint's coverage is satisfied, so the per-edit hook stays silent (lint-consistent) —
-      // but a human asking gets the honest nuance: nothing tracks this file's drift.
+      // but a human asking gets the honest nuance about what does and does not track this file.
       if (has('actionable')) process.exit(0)
-      console.log(`${rel} — not governed (no code: claim), but referenced by ${names(related)} (related: coverage only). Nothing tracks its drift; if your change is substantive, consider giving it a governing home.`)
+      // @@@ both axes - "nothing tracks its drift" is a verdict about the WHOLE tracking model
+      // ([[governed-related]]: spec nodes AND eval scenarios), so it cannot be spoken from the spec axis
+      // alone — a scenario's code: anchor drives eval freshness with no spec claim involved. Derived, never
+      // asserted: a message that enumerates one axis cannot report what the other holds. The empty
+      // nodeCode fallback is exact HERE and only here — reaching this branch means no spec node code:-claims
+      // the file, so no scenario can anchor to it by inheriting its node's claim, only by an explicit one.
+      const { evalNodes, scenarioCodeAxis } = await import('../../spec-eval/src/scenarios.js')
+      const anchored: string[] = []
+      for (const n of evalNodes(process.cwd())) {
+        for (const sc of n.scenarios) {
+          if (scenarioCodeAxis(sc.code).paths.includes(rel)) anchored.push(`'${n.id}' scenario '${sc.name}'`)
+        }
+      }
+      const tracking = anchored.length
+        ? `Its drift is tracked on the eval axis only: ${anchored.length} scenario${anchored.length === 1 ? '' : 's'} anchor${anchored.length === 1 ? 's' : ''} freshness to it (${anchored.join(', ')}), so changing it makes those readings stale — but no spec body says what it should do`
+        : 'Nothing tracks its drift'
+      console.log(`${rel} — not governed (no code: claim), but referenced by ${names(related)} (related: coverage only). ${tracking}; if your change is substantive, consider giving it a governing home.`)
     } else if (whole.length <= maxOwners) {
       // a sanely-owned file is NOT actionable: --actionable callers (the per-edit spec-of-file hook) stay
       // silent here, so the annotation fires only on an OVER-owned or uncovered file — rare and worth acting on.
@@ -440,16 +505,21 @@ if (cmd === 'serve') {
       console.log(`${rel} is governed whole-file by ${whole.length} specs (all claims: ${ids}) — more than one file should hold. This file does TOO MUCH: SPLIT it so each governor owns its own module (or merge the nodes if they're one concern, or give it a single foundation owner + relate the rest).${relLine}`)
     }
   } else if (sub === 'lint') {
-    const { specLint, pendingTouchesGoverned, DRIFT_GUIDANCE } = await import('./lint.js')
+    const { specLintReport, pendingTouchesGoverned, DRIFT_GUIDANCE } = await import('./lint.js')
     const pending = flag('pending')
     if (pending && process.env.SPEXCODE_GATE_SCOPE_ONLY === '1') {
       const touches = await pendingTouchesGoverned(process.cwd(), pending)
       if (!touches) process.exit(76)
     }
-    const findings = await specLint(undefined, undefined, {
+    const report = await specLintReport(undefined, undefined, {
       tip: pending || 'HEAD',
     })
+    const { findings } = report
     const errors = findings.filter((f) => f.level === 'error')
+    if (has('json')) {
+      console.log(JSON.stringify(report, null, 2))
+      await flushExit(errors.length ? 1 : 0)
+    }
     for (const f of findings) console.error(`  ${f.level === 'error' ? '✗' : '•'} ${f.rule}: ${f.msg}`)
     console.error(`spex spec lint: ${errors.length} error(s), ${findings.length - errors.length} warning(s)`)
     // drift teaches from the ONE `spex spec lint` (no flag). Unanchored drift stays advisory forever; the
@@ -513,7 +583,7 @@ if (cmd === 'serve') {
     const m = r.model
     const own = m.items.filter((item) => item.inSession).length
     console.log(`eval session  [${m.id}]`)
-    console.log(`  gates  : ${m.gates.map((g) => `${g.ok ? '✓' : '✗'} ${g.label} — ${g.detail}`).join(' · ')}`)
+    if (m.gates.length) console.log(`  gates  : ${m.gates.map((g) => `${g.ok ? '✓' : '✗'} ${g.label} — ${g.detail}`).join(' · ')}`)
     if (own) console.log(`  ✦      : ${own} scenario(s) measured by THIS session (unmarked rows = evals filed by other sessions)`)
     if (!m.items.length) console.log('\n  no affected scenarios to evaluate yet')
     let lastNode: string | null = null
@@ -597,7 +667,7 @@ if (cmd === 'serve') {
       console.error('spex session new: --node was removed — put a [[<id>]] mention in the prompt — the first mention binds')
       process.exit(2)
     }
-    rejectUnknownFlags('spex session new', 4, ['prompt', 'prompt-file', 'launcher', 'api', 'port'])
+    rejectUnknownFlags('spex session new', 4, ['prompt', 'prompt-file', 'launcher', 'name', 'base', 'api', 'port'])
     const { createSession } = await import('./sessions.js')
     const promptFile = flag('prompt-file')
     const inline = flag('prompt') ?? positionals(4)[0]
@@ -610,7 +680,7 @@ if (cmd === 'serve') {
       catch (e) { console.error(`spex session new: --prompt-file ${promptFile}: ${e instanceof Error ? e.message : e}`); process.exit(2) }
       if (!prompt.trim()) { console.error(`spex session new: --prompt-file ${promptFile === '-' ? 'stdin' : promptFile} is empty — refusing a promptless launch`); process.exit(2) }
     }
-    const created = await createSession(prompt, flag('launcher') ?? undefined)
+    const created = await createSession(prompt, flag('launcher') ?? undefined, flag('name') ?? undefined, flag('base') ?? undefined)
     const { ownSessionId, subscribeSessionWatch } = await import('./sessions.js')
     let watchEstablished = false
     if (created.parent && created.parent === ownSessionId()) {
@@ -642,6 +712,60 @@ if (cmd === 'serve') {
     const report = await clientResources()
     if (has('json')) console.log(JSON.stringify(report, null, 2))
     else console.log((await import('./host-resources.js')).formatResourceReport(report))
+  } else if (sub === 'files') {
+    rejectUnknownFlags('spex session files', 4, [])
+    const [verb, path, extra] = positionals(4)
+    if (extra || !verb || (verb !== 'ls' && !path) || (verb === 'ls' && path)) {
+      console.error('usage: spex session files add <path> | ls | retract <path>')
+      process.exit(2)
+    }
+    const { ownSessionId, withSessionRecordLockSync } = await import('./sessions.js')
+    const id = ownSessionId()
+    if (!id) {
+      console.error('spex session files: no governed caller session — run this from the agent session that produced the file')
+      process.exit(2)
+    }
+    const files = await import('./session-files.js')
+    if (verb === 'ls') {
+      for (const file of files.listSessionFiles(id)) console.log(file)
+    } else if (verb === 'add') {
+      const result = files.addSessionFile(id, path!, withSessionRecordLockSync)
+      console.log(result.added ? `posted ${result.path}` : `already posted ${result.path}`)
+    } else if (verb === 'retract') {
+      const result = files.retractSessionFile(id, path!, withSessionRecordLockSync)
+      if (!result.removed) { console.error(`spex session files retract: path is not posted: ${result.path}`); process.exit(2) }
+      console.log(`retracted ${result.path}`)
+    } else {
+      console.error(`spex session files: unknown verb '${verb}' — add | ls | retract  (spex help session)`)
+      process.exit(2)
+    }
+  } else if (sub === 'web') {
+    rejectUnknownFlags('spex session web', 4, [])
+    const [verb, url, extra] = positionals(4)
+    if (extra || !verb || (verb !== 'ls' && !url) || (verb === 'ls' && url)) {
+      console.error('usage: spex session web add <url> | ls | retract <url>')
+      process.exit(2)
+    }
+    const { ownSessionId, withSessionRecordLockSync } = await import('./sessions.js')
+    const id = ownSessionId()
+    if (!id) {
+      console.error('spex session web: no governed caller session — run this from the agent session that started the local service')
+      process.exit(2)
+    }
+    const web = await import('./session-web.js')
+    if (verb === 'ls') {
+      for (const entry of web.listSessionWebs(id)) console.log(entry.url)
+    } else if (verb === 'add') {
+      const result = web.addSessionWeb(id, url!, withSessionRecordLockSync)
+      console.log(result.added ? `posted ${result.url}` : `already posted ${result.url}`)
+    } else if (verb === 'retract') {
+      const result = web.retractSessionWeb(id, url!, withSessionRecordLockSync)
+      if (!result.removed) { console.error(`spex session web retract: URL is not posted: ${result.url}`); process.exit(2) }
+      console.log(`retracted ${result.url}`)
+    } else {
+      console.error(`spex session web: unknown verb '${verb}' — add | ls | retract  (spex help session)`)
+      process.exit(2)
+    }
   } else if (sub === 'watch') {
     const [verb, ...rest] = positionals(4)
     const { ownSessionId, subscribeSessionWatch, listSessionWatches, cancelSessionWatch } = await import('./sessions.js')
@@ -710,13 +834,13 @@ if (cmd === 'serve') {
     if (first === 'proof') signpost('spex review proof', 'spex eval ls --session <SEL> --export') // dead-words-ok: signpost — one-version tombstone teaching the renamed spelling (0.4.0 removes it)
     const { clientReview } = await import('./client.js')
     if (!first) { console.error('usage: spex session review <SEL>  (id | id-prefix | node | branch)'); process.exit(2) }
-    const id = await resolveSelectorOrExit(first)
-    const r = await clientReview(id)
-    if (!r) { console.error(`no such session ${id}`); process.exit(1) }
+    const session = await resolveSessionOrExit(first)
+    const r = await clientReview(session.id)
+    if (!r) { console.error(`no such session ${session.id}`); process.exit(1) }
     if (has('json')) { console.log(JSON.stringify(r, null, 2)) }
     else {
       const g = r.gates
-      console.log(`review ${r.label}  [${r.id}]`)
+      console.log(`review ${session.title}  [${r.id}]`)
       console.log(`  ahead of main : ${r.ahead} commit(s)`)
       console.log(`  uncommitted   : ${r.dirtyNonRuntime} non-runtime file(s)`)
       console.log(`  proposal      : ${r.proposal.kind ?? '—'}${r.proposal.note ? ` — ${r.proposal.note}` : ''}`)
@@ -732,11 +856,17 @@ if (cmd === 'serve') {
       for (const f of r.diff) console.log(`    ${f.status.padEnd(12)} +${f.additions} -${f.deletions}  ${f.path}`)
     }
   } else if (sub === 'merge') {
-    const { clientMerge } = await import('./client.js')
+    const [{ clientMerge, clientReview }, { createHash }] = await Promise.all([import('./client.js'), import('node:crypto')])
     const sel = positionals(4)[0]
     if (!sel) { console.error('usage: spex session merge <SEL>  (id | id-prefix | node | branch)'); process.exit(2) }
     const id = await resolveSelectorOrExit(sel)
-    const r = await clientMerge(id)
+    const review = await clientReview(id)
+    if (!review) { console.error(`merge dispatch failed: no such session ${id}`); process.exit(1) }
+    const r = await clientMerge(id, {
+      expectedBranchHead: review.branchHead,
+      expectedBaseHead: review.baseHead,
+      requestKey: createHash('sha256').update(`spexcode-cli-session-merge\0${id}\0${review.branchHead}\0${review.baseHead}`).digest('hex'),
+    })
     if (r.dispatched) console.log(`merge dispatched to ${id} — its agent is landing the merge`)
     else console.error(`merge dispatch failed: ${r.reason}`)
     process.exit(r.dispatched ? 0 : 1)
@@ -744,8 +874,9 @@ if (cmd === 'serve') {
     // `s` (sessions.ts) backs the state PRODUCERS that stay local (done/park/ask write the global record by
     // session_id) and the stateKit shared with `spex internal session-*`. `c` (client.ts) backs the
     // read/control subs that route through the backend. Lazily imported.
+    const sendArgs = sub === 'send' ? parseSessionSendArgs(process.argv.slice(4)) : null
     const c = await import('./client.js')
-    const id = process.argv[4]
+    const id = sendArgs?.selector ?? process.argv[4]
     if (sub === 'resume') {
       // bring the agent back up (relaunch ONLY if confirmed offline, the backend owns it); demotes a working
       // `active` to idle but leaves a standing declaration/proposal untouched (see sessions.ts resumeSession()).
@@ -822,18 +953,30 @@ if (cmd === 'serve') {
         const quarantined = await c.clientQuarantine(id, { adapter, thread: flag('thread') ?? null, tmux, worktree, branch })
         console.log(`quarantined ${quarantined.id} -> ${quarantined.bundle}`)
       }
+    } else if (sub === 'reparent') {
+      rejectUnknownFlags('spex session reparent', 4, ['to', 'api', 'port'])
+      const children = positionals(4)
+      const to = flag('to')
+      if (!children.length || !to) {
+        console.error('usage: spex session reparent <child-SEL...> --to <parent-SEL>')
+        process.exit(2)
+      }
+      const childIds = [...new Set(await Promise.all(children.map(resolveSelectorOrExit)))]
+      const parent = await resolveSelectorOrExit(to)
+      const { reparentSessions } = await import('./session-reparent.js')
+      const result = await reparentSessions(childIds, parent)
+      console.log(`reparented ${result.children.join(', ')} -> ${result.parent}`)
     } else if (sub === 'send') {
+      if (!sendArgs) sessionSendUsage('arguments were not parsed')
       const full = await resolveSelectorOrExit(id)
-      if (has('keys')) {
+      if (sendArgs.kind === 'keys') {
         // the LAST-RESORT face of send: forward raw nav-mode keystrokes (tmux send-keys, NEVER the prompt
         // socket) — how a manager drives a worker wedged in an interactive TUI dialog the prompt channel
         // can't reach (a select menu wanting one Enter/arrow). UNSTABLE, and able to confirm dangerous
         // dialogs — try plain `session send` text FIRST; reach for --keys only when text provably can't
         // land. Tokens = named keys, single chars, C-/M-/S- combos; whitespace-separated, delivered as ONE
         // ordered batch ([[nav-mode-key-ordering]]). Fail-loud: nothing delivered exits non-zero.
-        const keys = (flag('keys') ?? '').split(/\s+/).filter(Boolean)
-        if (keys.length === 0) { console.error('usage: spex session send <SEL> --keys "<keys>"   (e.g. "Up Up Enter", "C-r", single chars — last resort; try a plain send first)'); process.exit(2) }
-        if (await c.clientSendRawKeys(full, keys)) { console.log(`sent ${keys.length} key${keys.length === 1 ? '' : 's'} -> ${full}`); process.exit(0) }
+        if (await c.clientSendRawKeys(full, sendArgs.keys)) { console.log(`sent ${sendArgs.keys.length} key${sendArgs.keys.length === 1 ? '' : 's'} -> ${full}`); process.exit(0) }
         console.error(`spex session send --keys: nothing delivered to ${full} (offline, unknown session, or no valid key token)`)
         process.exit(1)
       }
@@ -853,7 +996,7 @@ if (cmd === 'serve') {
         // the board), NOT the stable sessionLabel that stops at the bare prompt-truncation title.
         sender = 'ok' in sr ? { id: sr.ok.id, label: s.sessionHeadline(sr.ok) } : { id: senderId, label: null }
       }
-      const r = await c.clientSend(full, s.withSenderHint(process.argv[5] ?? '', sender), senderId ?? undefined)
+      const r = await c.clientSend(full, s.withSenderHint(sendArgs.text, sender), senderId ?? undefined)
       console.log(r.ok ? 'sent' : `dispatch failed: ${r.error}`)
       process.exit(r.ok ? 0 : 1)
     } else if (sub === 'show') {
@@ -872,7 +1015,7 @@ if (cmd === 'serve') {
         if (has('json')) { console.log(JSON.stringify(r.session, null, 2)) }
         else {
           const x = r.session
-          console.log(`${x.label}  [${x.id}]`)
+          console.log(`${x.title}  [${x.id}]`)
           console.log(`  status   : ${x.status}  (lifecycle ${x.lifecycle} · liveness ${x.liveness})`)
           console.log(`  node     : ${x.node ?? '—'}`)
           console.log(`  branch   : ${x.branch ?? '—'}`)
@@ -901,7 +1044,7 @@ if (cmd === 'serve') {
       await assertLocalBackend()
       process.exit(await attachSession(await resolveSelectorOrExit(id)))
     } else {
-      console.error(`spex session: unknown verb '${sub}' — new | ls | show | watch | wait | review | merge | send | interrupt | rename | resume | stop | close | attach | done | park | ask  (spex help session)`)
+      console.error(`spex session: unknown verb '${sub}' — new | ls | files | web | show | watch | wait | review | merge | reparent | send | interrupt | rename | resume | stop | close | attach | done | park | ask  (spex help session)`)
       process.exit(2)
     }
   }

package/spec-cli/src/client.ts

@@ -2,26 +2,113 @@ import { existsSync } from 'node:fs'
 import { platform } from 'node:os'
 import { repoRoot } from './git.js'
 import { resourceBudgets, type ResourceReport } from './host-resources.js'
-import { listSessionIds, readPublicRecordEntry } from './layout.js'
+import { envSessionId, listSessionIds, readPublicRecordEntry } from './layout.js'
 import { cockpitReview, type CockpitReview } from './cockpit.js'
-import { apiBase, apiBaseInfo, assertProjectMatch, fromRaw, resolveSession, toSession, type DisplayStatus, type Session, type Resolved, type DispatchResult, type ReviewPayload } from './sessions.js'
+import { apiBaseInfo, assertProjectMatch, fromRaw, optionArgv, resolveSession, toSession, type DisplayStatus, type Session, type Resolved, type DispatchResult, type ReviewPayload } from './sessions.js'
 
 export class BackendError extends Error {
-  constructor(message: string, readonly status?: number) {
+  constructor(message: string, readonly status?: number, readonly transport?: unknown) {
     super(message)
     this.name = 'BackendError'   // cli.ts's top-level handler matches on the NAME, so it needs no import of this class
   }
 }
 
+const usageError = (message: string): Error => {
+  const error = new Error(message)
+  error.name = 'UsageError'
+  return error
+}
+
+const hasFlag = (name: string): boolean => optionArgv().includes(`--${name}`)
+function flagValue(name: string): string | null {
+  const argv = optionArgv()
+  const index = argv.indexOf(`--${name}`)
+  if (index < 0) return null
+  const value = argv[index + 1]
+  if (value === undefined || value.startsWith('--')) throw usageError(`--${name} expects a value`)
+  return value
+}
+
+let gatewayCookie: { base: string; value: string } | null = null
+
+function prepareTls(base: string): void {
+  if (!hasFlag('insecure')) return
+  if (new URL(base).protocol !== 'https:') throw usageError('--insecure requires an https --api endpoint')
+  process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0'
+}
+
+function passwordFor(target: Awaited<ReturnType<typeof apiBaseInfo>>): string | null {
+  const password = flagValue('password') ?? process.env.SPEXCODE_PASSWORD ?? null
+  if (!password) return null
+  if (target.source !== 'flag') throw usageError('--password and SPEXCODE_PASSWORD require explicit --api routing')
+  return password
+}
+
+function withCookie(init: RequestInit | undefined, cookie: string): RequestInit {
+  const headers = new Headers(init?.headers)
+  headers.set('cookie', cookie)
+  return { ...init, headers }
+}
+
+async function loginGateway(base: string, password: string): Promise<string> {
+  let response: Response
+  try {
+    response = await fetch(`${base}/login`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/x-www-form-urlencoded' },
+      body: new URLSearchParams({ password }).toString(),
+      redirect: 'manual',
+    })
+  } catch (error) {
+    throw new BackendError(`gateway login could not reach ${base}: ${(error as Error).message}`, undefined, error)
+  }
+  if (response.status < 200 || response.status >= 400) throw new BackendError(`gateway login rejected credentials at ${base}`, response.status)
+  const headers = response.headers as Headers & { getSetCookie?: () => string[] }
+  const cookies = headers.getSetCookie?.() ?? [response.headers.get('set-cookie') ?? '']
+  const cookie = cookies.map((value) => value.split(';', 1)[0]).find(Boolean)
+  if (!cookie) throw new BackendError(`gateway login at ${base} did not return an authorization cookie`, response.status)
+  return cookie
+}
+
 // the ONE seam where "no backend" becomes loud. A network failure (nothing listening at the resolved base)
 // is the only thing thrown; an HTTP Response of any status is returned for the caller to interpret.
 async function apiFetch(path: string, init?: RequestInit): Promise<Response> {
-  const base = await apiBase()
-  try {
-    return await fetch(`${base}${path}`, init)
-  } catch (e) {
-    throw new BackendError(`no backend reachable at ${base} — run \`spex serve\` in the project, or name one with --api <url> (${(e as Error).message})`)
+  const target = await apiBaseInfo()
+  const base = target.url
+  prepareTls(base)
+  const request = async (cookie?: string): Promise<Response> => {
+    try {
+      return await fetch(`${base}${path}`, cookie ? withCookie(init, cookie) : init)
+    } catch (error) {
+      throw new BackendError(`no backend reachable at ${base} — run \`spex serve\` in the project, or name one with --api <url> (${(error as Error).message})`, undefined, error)
+    }
   }
+  const existing = gatewayCookie?.base === base ? gatewayCookie.value : undefined
+  const response = await request(existing)
+  if (response.status !== 401) return response
+  if (existing) throw new BackendError(`gateway rejected the authenticated request at ${base}`, 401)
+  const password = passwordFor(target)
+  if (!password) throw new BackendError(`authentication required at ${base} — pass --password <pw> or set SPEXCODE_PASSWORD`, 401)
+  const cookie = await loginGateway(base, password)
+  gatewayCookie = { base, value: cookie }
+  const retried = await request(cookie)
+  if (retried.status === 401) throw new BackendError(`gateway rejected the authenticated request at ${base}`, 401)
+  return retried
+}
+
+export function backendConnectionRefused(error: unknown): boolean {
+  if (!(error instanceof BackendError)) return false
+  let current = error.transport
+  let sawRefusal = false
+  const seen = new Set<unknown>()
+  while (current && typeof current === 'object' && !seen.has(current)) {
+    seen.add(current)
+    const code = (current as NodeJS.ErrnoException).code
+    if (code && code !== 'ECONNREFUSED') return false
+    if (code === 'ECONNREFUSED') sawRefusal = true
+    current = (current as { cause?: unknown }).cause
+  }
+  return sawRefusal
 }
 // every MUTATING verb is project-bound ([[remote-client]]'s write guard): resolve the backend, compare its
 // served root to the cwd project, refuse loudly on a same-host mismatch — an explicit --api/--port skips it.
@@ -211,10 +298,14 @@ export async function clientEvals(id: string): Promise<EvalsResult> {
   throw new BackendError(`session eval pages changed while fetching ${id}; retry the command`)
 }
 
-// POST /api/sessions/:id/merge — the cockpit's merge DISPATCH (200 {dispatched:true} / 409 {reason}).
-export async function clientMerge(id: string): Promise<{ dispatched: boolean; reason?: string }> {
+// POST /api/sessions/:id/merge — the cockpit's merge DISPATCH. The caller returns the exact pair it just
+// reviewed and one durable request key; the backend accepts that decision once before ensuring the agent live.
+export async function clientMerge(id: string, options: { expectedBranchHead: string; expectedBaseHead: string; requestKey: string }): Promise<{ dispatched: boolean; replayed?: boolean; expectedBranchHead?: string; expectedBaseHead?: string; reason?: string; code?: string }> {
   await guarded('merge')
-  const r = await apiFetch(`/api/sessions/${seg(id)}/merge`, post({}))
+  const headers: Record<string, string> = { 'content-type': 'application/json', 'Idempotency-Key': options.requestKey }
+  const r = await apiFetch(`/api/sessions/${seg(id)}/merge`, {
+    method: 'POST', headers, body: JSON.stringify({ expectedBranchHead: options.expectedBranchHead, expectedBaseHead: options.expectedBaseHead }),
+  })
   return await r.json().catch(() => ({ dispatched: false, reason: `bad backend response (${r.status})` }))
 }
 
@@ -245,10 +336,11 @@ export async function clientInterrupt(id: string): Promise<DispatchResult> {
   return await r.json().catch(() => ({ ok: false, error: `bad backend response (${r.status})` })) as DispatchResult
 }
 
-// POST /api/sessions/:id/close — the human-only worktree removal. {ok:false} = no such session.
+// POST /api/sessions/:id/close — terminal worktree removal. A client-side session id is only an unverified claim.
 export async function clientClose(id: string): Promise<boolean> {
   await guarded('session close')
-  const r = await apiFetch(`/api/sessions/${seg(id)}/close`, post({}))
+  const source = envSessionId()
+  const r = await apiFetch(`/api/sessions/${seg(id)}/close`, post({ source: source ? { kind: 'unverified-session-claim', id: source } : { kind: 'user' } }))
   if (!r.ok) throw new BackendError(`backend refused to close ${id}: ${await r.text()}`, r.status)
   return !!(await r.json().catch(() => ({ ok: false })))?.ok
 }
@@ -291,6 +383,13 @@ export async function clientRename(id: string, name: string): Promise<boolean> {
   return !!(await r.json().catch(() => ({ ok: false })))?.ok
 }
 
+export async function clientReparent(children: string[], parent: string): Promise<import('./sessions.js').SessionReparentResult> {
+  await guarded('session reparent')
+  const r = await apiFetch('/api/sessions/reparent', post({ children, parent }))
+  if (!r.ok) throw new BackendError(`backend refused to reparent sessions: ${await r.text()}`, r.status)
+  return await r.json() as import('./sessions.js').SessionReparentResult
+}
+
 // POST /api/sessions/:id/input {kind:"keys"} — the LAST-RESORT raw nav-key face of send (tmux send-keys,
 // NEVER the prompt socket): an ordered token batch drives an interactive TUI menu
 // ([[nav-mode-key-ordering]]). {ok:false} = unknown session, no live pane, or no valid token delivered.

package/spec-cli/src/delivery-queue.ts

@@ -8,9 +8,16 @@ import { runtimeRoot, sessionArtifactPath, sessionStoreDir } from './layout.js'
 // or archived without changing what is owed. A session that predates this mechanism owes nothing, because a
 // queue is only ever filled by an enqueue — which is why no backlog migration exists.
 
-export type PendingMessage = { mid: string; text: string; from: string | null }
+export type PendingMessage = {
+  mid: string
+  text: string
+  from: string | null
+  dispatch?: { operation: 'merge'; requestDigest: string }
+}
 
 const queuePath = (id: string): string => sessionArtifactPath(id, 'pending.json')
+const revokedSenderRoot = (): string => join(runtimeRoot(), '.revoked-senders')
+const revokedSenderPath = (id: string): string => join(revokedSenderRoot(), id)
 
 // @@@ its own lock, deliberately NOT the record lock - the drain holds this across the adapter insert, which
 // is what makes "claim" real: two processes draining the same session cannot both hand over one message. The
@@ -53,7 +60,10 @@ function read(id: string): PendingMessage[] {
     return raw.filter((m): m is PendingMessage =>
       !!m && typeof m === 'object'
       && typeof (m as PendingMessage).mid === 'string'
-      && typeof (m as PendingMessage).text === 'string')
+      && typeof (m as PendingMessage).text === 'string'
+      && ((m as PendingMessage).dispatch === undefined
+        || ((m as PendingMessage).dispatch?.operation === 'merge'
+          && typeof (m as PendingMessage).dispatch?.requestDigest === 'string')))
   } catch { return [] }   // absent, empty, or unparseable all mean the honest thing: nothing owed
 }
 
@@ -68,17 +78,59 @@ function write(id: string, msgs: PendingMessage[]): void {
   renameSync(tmp, path)
 }
 
+// A closed sender may have left debt in many other sessions' queues. The marker is deliberately outside its
+// own store (which close removes) and is checked under the sender's record lock by dispatch: a close cannot
+// return while an old process can still append, and a later sweep cannot hand over what it sees here.
+export function revokeSenderDelivery(id: string): void {
+  mkdirSync(revokedSenderRoot(), { recursive: true })
+  writeFileSync(revokedSenderPath(id), `${id}\n`)
+}
+
+export const senderDeliveryRevoked = (id: string): boolean => existsSync(revokedSenderPath(id))
+
+export function pendingSnapshot(id: string): PendingMessage[] { return read(id) }
+
+// These two writes require the target's delivery lock. They are the queue half of a larger transaction
+// (currently reparent), which must be able to restore the exact previous debt if a later record write fails.
+export function replacePendingWhileLocked(id: string, msgs: PendingMessage[]): void { write(id, msgs) }
+export function revokePendingFromWhileLocked(id: string, sender: string): number {
+  const current = read(id)
+  const next = current.filter((msg) => msg.from !== sender)
+  write(id, next)
+  return current.length - next.length
+}
+
 // The enqueue rides the timeline append ([[dispatch]]): the caller holds the session's RECORD lock across
-// both, and the record is written first, so a crash between them leaves a message visible but undelivered —
-// never delivered but unrecorded.
+// both, and the record is written first, so delivery is never unrecorded. A keyed dispatch also carries its
+// exact delivery bytes in the timeline receipt, letting its retry restore a queue write lost to a crash.
 export function enqueue(id: string, msg: PendingMessage): void {
   write(id, [...read(id), msg])
 }
 
+// Caller holds this target's delivery lock. A retry may reach this after either side of the receipt->queue
+// crash boundary; exact mid identity makes reconstruction idempotent without inspecting message text.
+export function ensurePendingWhileLocked(id: string, msg: PendingMessage): boolean {
+  const current = read(id)
+  if (current.some((pending) => pending.mid === msg.mid)) return false
+  write(id, [...current, msg])
+  return true
+}
+
 export const pendingMessages = (id: string): PendingMessage[] => read(id)
 
 export const owesDelivery = (id: string): boolean => existsSync(queuePath(id))
 
+// Record transitions and queue mutations take locks in the same direction: record locks first, then these
+// target queue locks. A batch reparent needs all child queues held at once so its pointer/watch/debt change
+// either commits together or restores together.
+export async function withDeliveryLocks<T>(rawIds: string[], body: () => Promise<T>, index = 0, ids = [...new Set(rawIds)].sort()): Promise<T> {
+  if (index >= ids.length) return body()
+  const release = await acquire(ids[index], 30_000)
+  if (!release) throw new Error(`delivery queue ${ids[index]}: timed out waiting for transaction lock`)
+  try { return await withDeliveryLocks(ids, body, index + 1, ids) }
+  finally { release() }
+}
+
 // Hand over what is owed, in order, exactly once. `insert` reports whether the adapter took the message: only
 // then is the entry dropped. A refusal ENDS the pass with that entry still queued and everything behind it
 // still behind it — order is a property of a conversation, so a message is never skipped to deliver a later
@@ -95,6 +147,12 @@ export async function drain(
     for (;;) {
       const queued = read(id)
       if (!queued.length) return { delivered, remaining: 0 }
+      if (queued[0].from && senderDeliveryRevoked(queued[0].from)) {
+        // Closing a sender voids its undelivered output, not the recipient's immutable conversation history.
+        // Drop a revoked head and continue so it cannot permanently block the messages behind it.
+        write(id, read(id).filter((m) => m.mid !== queued[0].mid))
+        continue
+      }
       let ok = false
       try { ok = await insert(queued[0]) } catch { ok = false }
       if (!ok) return { delivered, remaining: queued.length }