spexcode 0.6.0 → 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>',
@@ -161,42 +206,31 @@ async function followKit(selectors: string[], verb: string): Promise<{
   return { watcher, follow: (emit, opts) => followSessions(emit, { ...opts, targets, self: watcher, row }) }
 }
 
-const greeted = new Set<string>()
-// Starting a STREAM follow on named live sessions announces itself ([[session-follow]]): one appended line per
-// target per process, so a stream never re-nags and a one-shot `wait` never announces at all. The append is the
-// delivery, taken locally, so the announce needs no backend either.
-async function greetWatchTargets(watcher: string, selectors: string[]): Promise<void> {
-  try {
-    const real = selectors.filter((sel) => sel && sel !== '@all')
-    if (!real.length) return
-    const { localCachedSessions } = await import('./client.js')
-    const { selectSessions, sendText, sessionHeadline } = await import('./sessions.js')
-    const board = localCachedSessions(true)
-    // name the watcher by its board HEADLINE (same as the reply-channel footer), delimited as a session title.
-    const mine = board.find((s) => s.id === watcher)
-    const me = mine ? sessionHeadline(mine) : watcher
-    const meWho = me && me !== watcher ? `session "${me}" (${watcher})` : `session ${watcher}`
-    for (const target of selectSessions(board, real).map((s) => s.id)) {
-      if (target === watcher || greeted.has(target)) continue
-      greeted.add(target)
-      const text = `🔭 ${meWho} is now supervising you — they started \`spex session watch\` over this session. To reach them directly, run: spex session send ${watcher} "<your message>". (One-time heads-up; reply only if you need to.)`
-      void sendText(target, text)   // no sender id → the connection notice is not double-counted as comms
-    }
-  } catch { /* greeting is best-effort — it must never disturb the watch */ }
+async function localWatchTargetsOrExit(selectors: string[], verb: string): Promise<string[]> {
+  if (!selectors.length) { console.error(`usage: ${verb} <SEL...>`); process.exit(2) }
+  const { localCachedSessions } = await import('./client.js')
+  const { selectSessions } = await import('./sessions.js')
+  const targets = selectSessions(localCachedSessions(true), selectors).map((session) => session.id)
+  if (!targets.length) { console.error(`${verb}: no such local session: ${selectors.join(' ')}`); process.exit(2) }
+  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> {
@@ -352,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)
@@ -440,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.
@@ -455,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
@@ -528,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
@@ -545,12 +600,12 @@ if (cmd === 'serve') {
       const stale = e.fresh ? '' : ` (stale: ${(e.staleAxes || []).join(',')})`
       console.log(`    ${e.inSession ? '✦' : ' '} ${verdict}${stale}  ${e.scenario}  — ${e.ts}${e.evaluator ? ` · ${e.evaluator}` : ''}`)
     }
-  } else if (['add', 'ls', 'scenario', 'matrix', 'lint', 'ok', 'retract', 'clean'].includes(sub)) {
+  } else if (['add', 'ls', 'scenario', 'lint', 'ok', 'retract', 'clean'].includes(sub)) {
     // node-scoped verbs — thin route; the logic lives in spec-eval.
     const { runEval } = await import('../../spec-eval/src/cli.js')
     await flushExit(await runEval(process.argv.slice(3)))
   } else {
-    console.error(`spex eval: unknown verb '${sub}' — add | ls | scenario ls/write | matrix | lint | ok | retract | clean  (spex help eval)`)
+    console.error(`spex eval: unknown verb '${sub}' — add | ls | scenario ls/write | lint | ok | retract | clean  (spex help eval)`)
     if (!sub.startsWith('--')) console.error(`  (the old \`spex eval <SEL>\` session read is now \`spex eval ls --session <SEL>\` [--export])`) // dead-words-ok: signpost — one-version tombstone teaching the renamed spelling (0.4.0 removes it)
     process.exit(2)
   }
@@ -612,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]
@@ -625,9 +680,19 @@ 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()) {
+      try {
+        await subscribeSessionWatch(created.parent, [created.id])
+        watchEstablished = true
+      } catch (error) {
+        console.error(`spex session new: child ${created.id} was created, but its managed watch was not established: ${error instanceof Error ? error.message : String(error)}`)
+      }
+    }
     console.log(JSON.stringify(created, null, 2))
-    console.error((await import('./help.js')).sessionLaunchReceipt(created.id))
+    console.error((await import('./help.js')).sessionLaunchReceipt(created.id, watchEstablished))
   } else if (sub === 'ls') {
     // pretty list of living sessions + states. `spex session ls [SEL...] [--status a,b] [--json]`
     // the board comes from the backend (so it shows the sessions of whatever SPEXCODE_API_URL points at,
@@ -647,16 +712,90 @@ 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 selectors = positionals(4)
-    const kit = await followKit(selectors, 'spex session watch')
-    if (kit.watcher) void greetWatchTargets(kit.watcher, selectors)
-    await kit.follow((line) => console.log(line), {
-      statuses: flag('status')?.split(','),
-      includeIdle: has('idle'),
-      as: flag('as'),
-      intervalMs: (Number(flag('interval')) || 1) * 1000,
-    })
+    const [verb, ...rest] = positionals(4)
+    const { ownSessionId, subscribeSessionWatch, listSessionWatches, cancelSessionWatch } = await import('./sessions.js')
+    const watcher = ownSessionId()
+    if (verb === 'stream') {
+      const kit = await followKit(rest, 'spex session watch stream')
+      await kit.follow((line) => console.log(line), {
+        statuses: flag('status')?.split(','),
+        includeIdle: has('idle'),
+        as: flag('as'),
+        intervalMs: (Number(flag('interval')) || 1) * 1000,
+      })
+    } else if (verb === 'list') {
+      if (!watcher) { console.error('spex session watch list: no governed caller session — this caller has no durable watch relation'); process.exit(2) }
+      for (const watch of listSessionWatches(watcher)) console.log(`${watch.target}\t${watch.createdAt}`)
+    } else if (verb === 'cancel') {
+      if (!watcher) { console.error(`spex session watch cancel: no governed caller session — run \`spex session wait ${rest.join(' ')}\` in the background instead`); process.exit(2) }
+      const targets = await localWatchTargetsOrExit(rest, 'spex session watch cancel')
+      console.log(`cancelled ${cancelSessionWatch(watcher, targets)} watch${targets.length === 1 ? '' : 'es'}`)
+    } else {
+      const selectors = [verb, ...rest].filter(Boolean)
+      if (!watcher) {
+        if (!selectors.length) { console.error('usage: spex session watch <SEL...>'); process.exit(2) }
+        console.error(`spex session watch: no governed caller session — run \`spex session wait ${selectors.join(' ')}\` in the BACKGROUND to receive the next actionable transition`)
+      } else {
+        const targets = await localWatchTargetsOrExit(selectors, 'spex session watch')
+        const result = await subscribeSessionWatch(watcher, targets)
+        console.log(`watching ${result.watched.join(' ')}`)
+      }
+    }
   } else if (sub === 'wait') {
     const selectors = positionals(4)
     const kit = await followKit(selectors, 'spex session wait')
@@ -695,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}` : ''}`)
@@ -717,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)
@@ -729,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()).
@@ -807,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)
       }
@@ -838,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') {
@@ -857,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 ?? '—'}`)
@@ -886,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)
     }
   }
@@ -923,25 +1081,31 @@ if (cmd === 'serve') {
     delete env.SPEXCODE_SESSION_ID
     const runtime = await spawnDetachedRuntime({ cwd, logFile, pidFile, receiptFile, command, args, env })
     console.log(runtime.pid)
-  } else if (sub === 'codex-generation-current') {
-    const [root, command] = process.argv.slice(4, 6)
-    if (!root || !command) { console.error('usage: spex internal codex-generation-current <runtime-root> <codex-command>'); process.exit(2) }
-    const { ensureCodexCurrentGeneration } = await import('./codex-runtime-generations.js')
+  } else if (sub === 'codex-generation-current' || sub === 'codex-generation-session') {
+    // Both launch spellings resolve ONE endpoint and print it as shell assignments. Starting a root is the same
+    // detached spawn either way — a session identity must never ride into the shared, project-scoped daemon.
+    const resume = sub === 'codex-generation-session'
+    const [root, ...rest] = process.argv.slice(4)
+    const [sessionId, threadId, sessionCommand] = rest
+    const command = resume ? sessionCommand : rest[0]
+    if (!root || !command || (resume && (!sessionId || !threadId))) {
+      console.error(resume
+        ? 'usage: spex internal codex-generation-session <runtime-root> <session-id> <thread-id> <codex-command>'
+        : 'usage: spex internal codex-generation-current <runtime-root> <codex-command>')
+      process.exit(2)
+    }
+    const { ensureCodexCurrentGeneration, resolveCodexGenerationForResume } = await import('./codex-runtime-generations.js')
     const { spawnDetachedRuntime } = await import('./runtime-ownership.js')
     const { sessionIdentityEnvVars } = await import('./harness.js')
     const env = { ...process.env }
     for (const key of sessionIdentityEnvVars()) delete env[key]
-    const endpoint = await ensureCodexCurrentGeneration(root, async (candidate) => {
+    const start = async (candidate: { logFile: string; pidFile: string; receiptFile: string; socketPath: string }) => {
       await spawnDetachedRuntime({ cwd: root, logFile: candidate.logFile, pidFile: candidate.pidFile, receiptFile: candidate.receiptFile,
         command, args: ['app-server', '--listen', `unix://${candidate.socketPath}`], env })
-    })
-    const quote = (value: string) => `'${value.replace(/'/g, `'\\''`)}'`
-    console.log(`sock=${quote(endpoint.socketPath)}; pid=${quote(endpoint.pidFile)}; receipt=${quote(endpoint.receiptFile)}; log=${quote(endpoint.logFile)}; export SPEXCODE_CODEX_GENERATION=${quote(endpoint.id)}`)
-  } else if (sub === 'codex-generation-session') {
-    const [root, sessionId, threadId] = process.argv.slice(4, 7)
-    if (!root || !sessionId || !threadId) { console.error('usage: spex internal codex-generation-session <runtime-root> <session-id> <thread-id>'); process.exit(2) }
-    const { resolveCodexGenerationForSession } = await import('./codex-runtime-generations.js')
-    const endpoint = resolveCodexGenerationForSession(root, sessionId, threadId)
+    }
+    const endpoint = resume
+      ? await resolveCodexGenerationForResume(root, sessionId!, threadId!, start)
+      : await ensureCodexCurrentGeneration(root, start)
     if (!endpoint) { console.error(`no exact Codex generation binding for session ${sessionId} thread ${threadId}`); process.exit(1) }
     const quote = (value: string) => `'${value.replace(/'/g, `'\\''`)}'`
     console.log(`sock=${quote(endpoint.socketPath)}; pid=${quote(endpoint.pidFile)}; receipt=${quote(endpoint.receiptFile)}; log=${quote(endpoint.logFile)}; export SPEXCODE_CODEX_GENERATION=${quote(endpoint.id)}`)