spexcode 0.4.1 → 0.5.0

package/spec-cli/src/sessions.ts

@@ -2,15 +2,15 @@ import { execFile } from 'node:child_process'
 import { promisify } from 'node:util'
 import { randomUUID } from 'node:crypto'
 import { readFileSync, writeFileSync, appendFileSync, existsSync, renameSync, mkdirSync, rmSync, readdirSync, realpathSync, statSync } from 'node:fs'
-import { join, dirname, relative, isAbsolute } from 'node:path'
+import { join, dirname, relative, isAbsolute, resolve, sep } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { seedWorktreeHostState } from './worktree-sources.js'
 import { git, gitA, gitTry, repoRoot, mergeBaseDiff, mergeConflicts, type ReviewDiffFile } from './git.js'
-import { loadSpecs } from './specs.js'
-import { defaultHarness, defaultLauncher, harnessById, resolveLauncher, rvSock, rendezvousListening, type Harness, type DispatchResult, type PaneProbe, type ProcTable } from './harness.js'
+import { loadConfig, loadSpecs, type ConfigPreset, type SpecLite } from './specs.js'
+import { defaultHarness, defaultLauncher, harnessById, procSnapshot, resolveLauncher, rvSock, rendezvousListening, type Harness, type DispatchResult, type PaneProbe, type ProcTable } from './harness.js'
 import { materialize } from './materialize.js'
 import { mainBranch, gitCommonDir, readConfig, runtimeRoot, treeSlotDir, sessionStoreDir, sessionRecordPath, sessionArtifactPath, listSessionIds, readAliasedRawRecord, envSessionId, type RawRecord } from './layout.js'
-import { recordSent } from './session-timeline.js'
+import { recordSent, lastHumanSendVia } from './session-timeline.js'
 import { stripRefSigil } from './mentions.js'
 
 // @@@ sessions - the WORKTREE is the durable unit; tmux is a disposable runtime handle. The per-session
@@ -44,9 +44,9 @@ import { stripRefSigil } from './mentions.js'
 // auto-disappears; to withdraw one you MESSAGE the session (mark-active clears it), and a relaunch (resume)
 // deliberately does NOT touch it. `merges` is METADATA (how many times merged), shown as a badge, not a state.
 //
-// Launch rules (CLAUDE.md / memory): private `tmux -L <label>` socket + `--dangerously-skip-permissions`.
-// SPEXCODE_TMUX overrides the tmux socket for tests; the launch COMMAND comes from the session's pinned
-// launcher ([[launcher-select]]), not an env var.
+// Launch rules: private `tmux -L <label>` socket + the session's pinned named-launcher command. The launcher
+// preserves its harness's normal permission model unless the user explicitly configured an automatic-permission
+// command. SPEXCODE_TMUX overrides the tmux socket for tests; no env var rewrites the launcher.
 
 const pexec = promisify(execFile)
 export const TMUX_SOCK = process.env.SPEXCODE_TMUX || 'spexcode'
@@ -87,7 +87,7 @@ const rvEnv = (id: string, harness = HARNESS) => {
   // start from the payload thread id and alias through harness_session_id, while the short-lived codex-launch
   // process uses this env only to store the freshly started thread id on the governed record. The CLAUDE_BG
   // rendezvous control socket is the reclaude prompt-delivery path and exists ONLY for harnesses that own one
-  // (claude) — codex has no such daemon, so it's omitted there.
+  // (claude/pi/opencode) — codex has no such daemon, so it is omitted there.
   const parts = [`SPEXCODE_SESSION_ID=${id}`]
   if (harness.ownsRendezvous) parts.push(`CLAUDE_BG_BACKEND=daemon`, `CLAUDE_BG_RENDEZVOUS_SOCK=${rvSock(id)}`)
   for (const v of ['SPEXCODE_HOME', 'CODEX_HOME']) { const val = process.env[v]; if (val) parts.push(`${v}=${val}`) }
@@ -117,6 +117,7 @@ export type Session = {
   raw: { name: string | null; title: string | null }   // the bare parts, for explicit consumers only (rename prefill)
   parent: string | null   // the SPAWNING session's id ([[session-nesting]]) — set once at creation when `spex session new` ran inside another session, else null; the frontend folds a child under it at read time
   harness: string   // which harness (claude|codex) runs this session — carried so liveness/occupancy route through its adapter
+  capabilities: { headless: boolean; messageStream: boolean }   // stable adapter projection; console surfaces consume data, never harness ids
   launcher: string | null   // the launcher profile this session launched under ([[launcher-select]]); null only for old records predating launchers
   lifecycle: Lifecycle; proposal: Proposal | null; merges: number; status: DisplayStatus; liveness: Liveness; note: string | null
   prompt: string | null; promptPreview: string | null; created: number; activity: string | null
@@ -229,9 +230,34 @@ export type SessRec = {
   sortKey: number | null; createdAt: number; harness: string; harnessSessionId: string | null
   launcher: string | null   // the launcher profile this session launches under ([[launcher-select]]); null only for old records predating launchers
   launchCmd: string | null  // the RESOLVED base launcher command pinned at creation ([[launcher-select]] resume-launcher-pin); null → old record → fall back to the launcher name / ambient
+  launchOwner: string | null // stable public-backend authority while queued; null for active/legacy records
 }
 const LIFECYCLES = new Set<Lifecycle>(['active', 'idle', 'awaiting', 'parked', 'error', 'asking', 'queued'])
 const PROPOSALS = new Set<Proposal>(['merge', 'nothing', 'close'])
+export const OWNED_QUEUE_RAW_STATUS = 'launch-queued'
+
+// @@@ stable launch authority - the supervisor injects its PUBLIC proxy URL into every replaceable child.
+// That URL survives child hot reload/restart; PORT inside a supervised child is private and ephemeral, so it
+// is only the fallback for a directly-run server with no injected API URL. Credentials/query/fragment are
+// not authority and may contain secrets, so they are stripped before the value reaches session.json.
+export function backendLaunchAuthority(env: { SPEXCODE_API_URL?: string; PORT?: string } = process.env): string {
+  const raw = env.SPEXCODE_API_URL?.trim() || `http://127.0.0.1:${env.PORT?.trim() || '8787'}`
+  const url = new URL(raw)
+  url.username = ''
+  url.password = ''
+  url.search = ''
+  url.hash = ''
+  url.pathname = url.pathname.replace(/\/+$/, '') || '/'
+  return url.toString().replace(/\/$/, '')
+}
+
+export function rawLifecycleStatus(rec: Pick<SessRec, 'status' | 'launchOwner'>): string {
+  return rec.status === 'queued' && rec.launchOwner ? OWNED_QUEUE_RAW_STATUS : rec.status
+}
+
+export function canDrainQueued(rec: Pick<SessRec, 'status' | 'launchOwner'>, authority = backendLaunchAuthority()): boolean {
+  return rec.status === 'queued' && (rec.launchOwner === null || rec.launchOwner === authority)
+}
 
 // typed read of a session's record from the global store (null if it has none — a self-launched session that
 // only ever wrote spec-discipline sentinels has a store dir but no session.json). Goes through layout's
@@ -242,8 +268,13 @@ function readRecord(id: string): SessRec | null {
   if (!raw) return null
   return fromRaw(raw)
 }
-function fromRaw(raw: RawRecord): SessRec {
-  const status = LIFECYCLES.has(raw.status as Lifecycle) ? raw.status as Lifecycle : 'active'
+// the loose on-disk fields validated into the typed shape. Exported so the old-record defaults (harness →
+// claude, absent pin → null) are unit-auditable without a store on disk.
+export function fromRaw(raw: RawRecord & { launch_owner?: string }): SessRec {
+  const ownedQueue = raw.status === OWNED_QUEUE_RAW_STATUS
+  const status = ownedQueue ? 'queued' : LIFECYCLES.has(raw.status as Lifecycle) ? raw.status as Lifecycle : 'active'
+  const launchOwner = ownedQueue ? raw.launch_owner?.trim() : null
+  if (ownedQueue && !launchOwner) throw new Error(`owned queue record '${raw.session_id}' has no launch_owner`)
   const proposal = raw.proposal && PROPOSALS.has(raw.proposal as Proposal) ? raw.proposal as Proposal : null
   const sk = raw.sortkey
   const sortKey = typeof sk === 'number' && Number.isFinite(sk) ? sk : null
@@ -255,6 +286,7 @@ function fromRaw(raw: RawRecord): SessRec {
     harnessSessionId: raw.harness_session_id || null,
     launcher: raw.launcher || null,     // records written before launchers → null → old-record fallback
     launchCmd: raw.launch_cmd || null,  // records written before the pin → null → fall back to launcher name / ambient
+    launchOwner: launchOwner || null,
   }
 }
 // @@@ session.json format - written one-field-per-line (JSON.stringify(_, null, 2)) with EVERY key ALWAYS
@@ -271,7 +303,10 @@ function writeRecord(rec: SessRec): void {
     title: rec.title ?? '',
     name: rec.name ?? '',
     parent: rec.parent ?? '',
-    status: rec.status,
+    // A leased queue uses a raw token older drainers do not recognize as `queued`; current readers map it
+    // back to the unchanged public lifecycle. This version fence is what keeps an orphaned old backend from
+    // stealing the entry before it can even inspect the new launch_owner field.
+    status: rawLifecycleStatus(rec),
     proposal: rec.proposal ?? '',
     merges: rec.merges,
     note: rec.note ?? '',
@@ -281,6 +316,7 @@ function writeRecord(rec: SessRec): void {
     harness_session_id: rec.harnessSessionId ?? '',
     launcher: rec.launcher ?? '',
     launch_cmd: rec.launchCmd ?? '',
+    launch_owner: rec.status === 'queued' ? rec.launchOwner ?? '' : '',
   }
   mkdirSync(sessionStoreDir(rec.session), { recursive: true })
   writeFileSync(sessionRecordPath(rec.session), JSON.stringify(obj, null, 2) + '\n')
@@ -323,16 +359,7 @@ async function listWorktrees(): Promise<{ path: string; branch: string | null }[
 // wrapper, even while the TUI renders, so the foreground name is NOT the signal). CLAUDE ignores the probe —
 // its workers launch through the `reclaude` wrapper, which runs claude as a CHILD, so claude liveness stays
 // its rendezvous socket. The per-session alive() above stays for the single-session ops (capture / rawKey).
-async function procSnapshot(): Promise<ProcTable> {
-  const t: ProcTable = new Map()
-  let out = ''
-  try { ({ stdout: out } = await pexec('ps', ['-eo', 'pid=,ppid=,comm='], { timeout: TMUX_PROBE_TIMEOUT_MS, killSignal: 'SIGKILL' })) } catch { return t }
-  for (const line of out.split('\n')) {
-    const m = /^\s*(\d+)\s+(\d+)\s+(.*)$/.exec(line)
-    if (m) t.set(Number(m[1]), { ppid: Number(m[2]), comm: m[3].trim() })
-  }
-  return t
-}
+// (the whole-box ps snapshot itself — procSnapshot — lives in harness.ts beside its tree-walk consumers.)
 // @@@ LiveSnap - the ONE liveness snapshot the whole session list shares, built from a SINGLE tmux spawn
 // (`list-panes -a` yields every session's window presence, pane pid, AND pane title at once — every session has
 // ≥1 pane). `windows` = our live tmux windows (id → PaneProbe: pane pid + the hot-tier `pidAlive` verdict + the
@@ -520,7 +547,7 @@ export function selfSummary(paneTitle: string): string | null {
 // instead of 'offline' for BOOT_GRACE_MS after launch — so 'offline' only ever means genuinely dead. In-
 // memory in the single server process (lost on restart, which is fine: a restart has nothing in flight).
 const launchedAt = new Map<string, number>()
-const BOOT_GRACE_MS = 45000   // > SOCKET_READY_TIMEOUT_MS, and spans launchScript's bounded fast-fail retry
+export const BOOT_GRACE_MS = 45000   // > SOCKET_READY_TIMEOUT_MS, and spans launchScript's bounded fast-fail retry
                               // window (~3 attempts) so a relaunching session reads 'starting', not 'offline'
 const LAUNCH_FAST_FAIL_S = 12 // launchScript retries the agent command when it exits faster than this: fast
                               // exit before readiness is retryable, but it is not proof of one specific cause
@@ -539,13 +566,13 @@ const LAUNCH_FAST_FAIL_S = 12 // launchScript retries the agent command when it
 // for the grace window; only past it (still not online) is it genuinely 'offline'.
 export function liveness(rec: SessRec, snap: LiveSnap): Liveness {
   if (!rec.session) return 'offline'
-  if (snap.probeFailed) return 'unknown'   // the probe failed — we can't tell, and MUST NOT guess offline
-  // ask the ADAPTER ([[harness-adapter]]): claude = tmux up AND a live listener on its rendezvous socket; codex
-  // = tmux up AND a codex-ish process live among the pane pid's descendants (not the bare shell a failed launch
-  // dropped back to). The 'starting' grace stays here (a launcher concern): a just-launched agent whose
-  // online-signal hasn't appeared yet reads 'starting' for the boot window, only past it 'offline'.
+  // Ask the resolved ADAPTER ([[harness-adapter]]): claude/pi/opencode prove their rendezvous listener;
+  // codex proves its launch-registered pid (with the legacy descendant-tree fallback). The 'starting' grace
+  // stays here: a just-launched agent whose online signal has not appeared yet reads 'starting', only past it
+  // 'offline'.
   const h = harnessById(rec.harness || defaultHarness.id)
   if (h.liveness(rec, snap.windows.has(rec.session), runtimeRoot(), snap.windows.get(rec.session), snap.sockets.has(rec.session)) === 'online') return 'online'
+  if (snap.probeFailed) return 'unknown'   // the probe failed — we can't tell, and MUST NOT guess offline
   // not provably online — but if this session's LISTENER probe couldn't conclude (timeout under load / EAGAIN
   // off a full-but-alive backlog), death is UNPROVEN: `unknown`, never a false `offline` a supervisor would
   // act on (issue #40 — a wedged-but-alive worker must not read as an actionable corpse).
@@ -585,7 +612,8 @@ export function toSession(rec: SessRec, status: DisplayStatus, lv: Liveness, act
   const act = showActivity ? activity : null
   const pp = prompt ? promptPreview(prompt) : null
   const parts = { id: rec.session, name: rec.name, node: rec.node, title: rec.title, branch: rec.branch, activity: act, promptPreview: pp }
-  return { id: rec.session, node: rec.node, branch: rec.branch, label: deriveLabel(parts), headline: deriveHeadline(parts), raw: { name: rec.name, title: rec.title }, path: rec.worktreePath, parent: rec.parent, harness: rec.harness, launcher: rec.launcher, lifecycle: rec.status, proposal: rec.proposal, merges: rec.merges, note: rec.note, status, liveness: lv, prompt, promptPreview: pp, created: rec.createdAt, activity: act, sortKey: rec.sortKey }
+  const harness = harnessById(rec.harness || defaultHarness.id)
+  return { id: rec.session, node: rec.node, branch: rec.branch, label: deriveLabel(parts), headline: deriveHeadline(parts), raw: { name: rec.name, title: rec.title }, path: rec.worktreePath, parent: rec.parent, harness: harness.id, capabilities: { headless: harness.headless, messageStream: harness.messageStream }, launcher: rec.launcher, lifecycle: rec.status, proposal: rec.proposal, merges: rec.merges, note: rec.note, status, liveness: lv, prompt, promptPreview: pp, created: rec.createdAt, activity: act, sortKey: rec.sortKey }
 }
 
 // @@@ renameSession - set (or clear) a session's human display NAME: the user-chosen override that wins
@@ -869,9 +897,20 @@ export function withSenderHint(text: string, sender: MsgSender | null): string {
 // the declaration NOTE ([[session-timeline]]). This one-line insert tells the agent exactly that, so its
 // next stop carries the complete answer in `--note` instead of prose that dies in an unseen terminal.
 // Appended server-side (the input route passes replyVia:'note'), so the phrase lives in ONE place and any
-// surface — desktop included, later — can opt in with the same flag.
+// surface — desktop included, later — can opt in with the same flag. The notice declares itself
+// PER-MESSAGE, and withTerminalReplyHint (below) is its counter-signal: without both, an agent that
+// note-replied a few times keeps note-replying from context inertia long after the human is back at a
+// terminal — the sticky-note failure this pair exists to prevent.
 export const withNoteReplyHint = (text: string): string =>
-  `${text}\n\n— sent from a terminal-free client: the sender CANNOT see your terminal output. When you next stop (done/ask/park), put your COMPLETE reply to this message in the declaration's --note (e.g. spex session done --note "<full answer>") — the note is the only text that reaches them.`
+  `${text}\n\n— sent from a terminal-free client: the sender CANNOT see your terminal output. When you next stop (done/ask/park), put your COMPLETE reply to this message in the declaration's --note (e.g. spex session done --note "<full answer>") — the note is the only text that reaches them. This notice is PER-MESSAGE: a later message arriving WITHOUT it means the sender is back at a terminal and reads your normal output again.`
+// @@@ withTerminalReplyHint - the BACK-AT-A-TERMINAL counter-insert, appended exactly once at the
+// note→terminal transition (a human send with no note flag whose previous human send carried one —
+// [[session-timeline]] lastHumanSendVia). It explicitly countermands the note-reply instruction: telling
+// the agent once beats hoping it scopes the earlier per-message notice correctly (it demonstrably doesn't —
+// codex especially). Not repeated on later terminal sends: once the transition send is recorded, the last
+// human channel is no longer note, so ordinary conversation stays insert-free.
+export const withTerminalReplyHint = (text: string): string =>
+  `${text}\n\n— sent from a terminal-attached client: the sender now reads your terminal output directly. Reply in your normal conversation output from here on — stop putting replies in declaration --notes (the earlier terminal-free notices no longer apply; a --note can go back to being a short status line).`
 async function postJSON(path: string, body: unknown): Promise<void> {
   try {
     await fetch(`${await apiBase()}${path}`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) })
@@ -905,10 +944,10 @@ export const isBackendUnreachable = (e: unknown): boolean =>
 export const slugify = (s: string | null) =>
   (s || 'session').normalize('NFC').replace(/[^\p{L}\p{N}_-]+/gu, '-').replace(/-+/g, '-').replace(/^-+|-+$/g, '') || 'session'
 
-// @@@ node + title from the prompt - the spec node a session works on is whatever it @-mentions, NOT a UI
-// "focused node": the dashboard prefills `@<focused> ` as a deletable convenience, so the node the user
-// actually left in the prompt (changed it, or deleted it for a node-agnostic prompt) is the truth. We read
-// the FIRST `[[<id>]]` topic reference ([[mentions]]: `[[node]]` is a topic, `@` is now an actor/session).
+// @@@ node + title from the prompt - the spec node a session works on is the FIRST `[[<id>]]` topic
+// reference in the raw prompt ([[mentions]]: `[[node]]` is a topic, `@` is an actor/session). The node the
+// user actually left in the prompt is the truth: there is no focused-node/API/function argument that can
+// grant a binding outside the task text. Changing or deleting the mention changes or removes the binding.
 // When there is none, the session is node-agnostic and we label it by the first few words of the prompt.
 // The OPTIONAL leading dot is load-bearing: a node id is its dir basename, so a dot-prefixed config root
 // (`.plugins`) keeps the dot — without `\.?` here `[[.plugins]]` captures nothing and never resolves to a node.
@@ -916,7 +955,47 @@ export const slugify = (s: string | null) =>
 // id, so `[[中文节点]]` must bind the session exactly like an ASCII id — ASCII-only here silently launched
 // node-agnostic.
 const MENTION = /\[\[(\.?[\p{L}\p{N}_-]+)\]\]/u
-const mentionedNode = (prompt: string): string | null => prompt.match(MENTION)?.[1] ?? null
+export const nodeFromPrompt = (prompt: string): string | null => prompt.match(MENTION)?.[1] ?? null
+
+type CommandPreset = Pick<ConfigPreset, 'name' | 'body'>
+type CommandSpec = Pick<SpecLite, 'id' | 'path'>
+
+// @@@ command invocation - turn the raw `/<preset> [[node]]… free text` into the ONE agent prompt.
+// This is deliberately server-side: dashboard, phone, CLI, direct API, and the in-process fallback all call
+// the launch/send boundary, so no client gets its own command interpreter. Launch keeps the RAW prompt for
+// session identity/history; only the agent payload uses this expansion, preventing a plugin body's own
+// [[links]] from becoming the session node. With no mention, a preset remains targetless.
+export function composeCommandPrompt(raw: string, presets: CommandPreset[], specs: CommandSpec[]): string {
+  const match = raw.match(/^\/(\S+)\s*([\s\S]*)$/)
+  if (!match) return raw
+  const preset = presets.find((p) => p.name === match[1])
+  if (!preset) return raw
+
+  const ids: string[] = []
+  const allMentions = new RegExp(MENTION.source, 'gu')
+  const free = match[2].replace(allMentions, (_, id: string) => { ids.push(id); return '' }).trim()
+  const targets = ids.length
+    ? ids.map((id) => {
+        const spec = specs.find((s) => s.id === id)
+        const path = spec?.path.replace(/^\.spec\//, '').replace(/\/spec\.md$/, '')
+        return path ? `- [[${id}]] — ${path}` : `- [[${id}]]`
+      }).join('\n')
+    : '(No target was mentioned. If the prompt names the scope, use it; otherwise ask the human to define the scope before proceeding — unless this task needs no scope, in which case proceed.)'
+  const body = preset.body.includes('{{targets}}')
+    ? preset.body.replace('{{targets}}', targets)
+    : ids.length ? `${preset.body}\n\n${targets}` : preset.body
+  return free ? `${body}\n\n${free}` : body
+}
+
+// Load only the one live preset named by the raw invocation. Both newSession and sendText call this seam, so
+// launch and an existing session's inbox resolve identical plugin data with identical target semantics.
+export async function resolveCommandPrompt(raw: string, loadedSpecs?: CommandSpec[]): Promise<string> {
+  const commandName = raw.match(/^\/(\S+)/)?.[1]
+  const preset = commandName ? loadConfig().find((p) => p.name === commandName) : undefined
+  if (!preset) return raw
+  const specs = loadedSpecs ?? (nodeFromPrompt(raw) ? await loadSpecs() : [])
+  return composeCommandPrompt(raw, [preset], specs)
+}
 // @@@ identity-token strip - an `@session` actor mention ([[mentions]]) or a bare UUID-shaped token in the
 // prompt is ANOTHER session's identity, never this one's name. A title/slug wearing it misleads every
 // board/git surface — and a worker tasked with cleaning that session can match its OWN worktree and delete
@@ -1014,7 +1093,7 @@ function isOccupying(s: Session, snap: LiveSnap): boolean {
   if (!OCCUPIES_SLOT.has(s.status)) return false                          // waiting-on-human / proposed / queued / dead → free
   const rec = readRecord(s.id)
   if (!rec) return false
-  return harnessById(rec.harness || defaultHarness.id).liveness(rec, snap.windows.has(rec.session), runtimeRoot(), snap.windows.get(rec.session), snap.sockets.has(rec.session)) === 'online'  // and only while the agent is genuinely live (its adapter's channel)
+  return harnessById(rec.harness || defaultHarness.id).liveness(rec, snap.windows.has(rec.session), runtimeRoot(), snap.windows.get(rec.session), snap.sockets.has(rec.session)) === 'online'
 }
 // sessions we've JUST launched whose agent hasn't come online yet. During that boot window reconcile reads them
 // `offline` (the adapter's online-signal not up yet) and isOccupying would miss them, so the drainer would
@@ -1030,6 +1109,7 @@ let draining = false   // re-entrancy guard: only one drain pass runs at a time
 async function startQueued(id: string): Promise<boolean> {
   const wt = await findWorktree(id)
   if (!wt) return false
+  if (!canDrainQueued(wt.rec)) return false
   const launchPrompt = readLaunchFile(id)
   if (launchPrompt == null) return false   // a queued session always has one; if it's gone, don't spin on it
   launching.add(id)   // hold the slot across the boot window BEFORE we launch, so a concurrent count can't race us
@@ -1041,7 +1121,7 @@ async function startQueued(id: string): Promise<boolean> {
     launching.delete(id)
     return false   // launch failed → stays `queued`, retried on the next drain tick
   }
-  writeRecord({ ...wt.rec, status: 'active', proposal: null })
+  writeRecord({ ...wt.rec, status: 'active', proposal: null, launchOwner: null })
   removeLaunchFile(id)   // consumed
   // release the boot-window hold once the socket is up (then isOccupying takes over) or after the bounded
   // wait — so a launch that never booted reads offline and the drainer reclaims the slot instead of pinning it.
@@ -1068,7 +1148,12 @@ export async function drainQueue(): Promise<void> {
       if (snap.probeFailed) break
       const occupied = sessions.reduce((n, s) => n + (launching.has(s.id) || isOccupying(s, snap) ? 1 : 0), 0)
       if (occupied >= cap) break
-      const next = sessions.find((s) => s.status === 'queued' && !launching.has(s.id))
+      const authority = backendLaunchAuthority()
+      const next = sessions.find((s) => {
+        if (s.status !== 'queued' || launching.has(s.id)) return false
+        const rec = readRecord(s.id)
+        return !!rec && canDrainQueued(rec, authority)
+      })
       if (!next) break
       if (!(await startQueued(next.id))) break   // launch failed → stop this pass; a later tick retries
     }
@@ -1125,6 +1210,29 @@ export async function assertProjectMatch(verb: string): Promise<void> {
   }
 }
 
+type SessionCreateFn = (prompt: string, parent: string | null, launcher?: string) => Promise<Session>
+export type SessionCreateRequestResult =
+  | { status: 201; session: Session }
+  | { status: 400; error: string }
+
+// The API create boundary accepts one small, closed object shape. Unknown fields fail through this generic
+// contract before any worktree is made; removed or misspelled inputs never disappear into defaults.
+export async function sessionCreateRequest(body: unknown, create: SessionCreateFn = newSession): Promise<SessionCreateRequestResult> {
+  if (!body || typeof body !== 'object' || Array.isArray(body)) return { status: 400, error: 'body must be a JSON object' }
+  const input = body as Record<string, unknown>
+  const unknown = Object.keys(input).filter((key) => !['prompt', 'parent', 'launcher'].includes(key)).sort()
+  if (unknown.length) return { status: 400, error: `unknown session-create field${unknown.length === 1 ? '' : 's'}: ${unknown.join(', ')}` }
+  const prompt = typeof input.prompt === 'string' ? input.prompt : ''
+  if (!prompt.trim()) return { status: 400, error: 'empty prompt' }
+  const launcher = typeof input.launcher === 'string' && input.launcher.trim() ? input.launcher.trim() : undefined
+  const parent = typeof input.parent === 'string' && input.parent.trim() ? input.parent.trim() : null
+  try {
+    return { status: 201, session: await create(prompt, parent, launcher) }
+  } catch (e) {
+    return { status: 400, error: String((e as Error).message || e) }
+  }
+}
+
 // @@@ createSession (dispatch via backend) - `spex session new` must launch the worker in the
 // BACKEND's process, not the caller's, because the backend is the single owner of the concurrency cap and the
 // launch QUEUE (drainQueue). An in-process launch by an agent that runs `spex session new` (e.g. a supervisor) would
@@ -1133,7 +1241,7 @@ export async function assertProjectMatch(verb: string): Promise<void> {
 // either process.) So the CLI POSTs to the running backend whenever one answers. Only when NO backend is
 // reachable do we fall back to launching in this process (with a stderr warning) — the backend's own POST
 // handler calls newSession directly, so it never re-enters this path.
-export async function createSession(node: string | null, prompt: string, launcher?: string): Promise<Session> {
+export async function createSession(prompt: string, launcher?: string): Promise<Session> {
   await assertProjectMatch('spex session new')
   // @@@ parent = the CALLER's own session ([[session-nesting]]). Resolve it HERE, in the caller's process,
   // via the SAME ownSessionId env read [[agent-reply-channel]] uses for its sender hint — NOT inside the
@@ -1145,11 +1253,11 @@ export async function createSession(node: string | null, prompt: string, launche
     res = await fetch(`${await apiBase()}/api/sessions`, {
       method: 'POST',
       headers: { 'content-type': 'application/json' },
-      body: JSON.stringify({ node, prompt, parent, launcher }),
+      body: JSON.stringify({ prompt, parent, launcher }),
     })
   } catch {
     console.error('spex: no backend reachable — launching in-process (caller env owns auth, no concurrency cap)')
-    return newSession(node, prompt, parent, launcher)
+    return newSession(prompt, parent, launcher)
   }
   if (!res.ok) {
     const text = await res.text().catch(() => '')
@@ -1169,7 +1277,7 @@ export async function createSession(node: string | null, prompt: string, launche
 // launched agent does itself (the composer's nn/dd chords just prefill a plain instruction). So the server
 // only ever launches a session; it never mutates the spec tree ([[mentions]]: the issue store is the sole
 // programmatic surface, every other surface is prompt only).
-export async function newSession(node: string | null, prompt: string, parent: string | null = null, launcher?: string): Promise<Session> {
+export async function newSession(prompt: string, parent: string | null = null, launcher?: string): Promise<Session> {
   const id = randomUUID()
   // a launcher ([[launcher-select]]) fixes BOTH the launch command (persisted below) AND the harness — so
   // picking one is the ONLY launch choice. Explicit --launcher wins, else the configured defaultLauncher.
@@ -1177,10 +1285,17 @@ export async function newSession(node: string | null, prompt: string, parent: st
   const lname = launcher ?? defaultLauncher(mainRoot())
   const chosen = resolveLauncher(lname)
   const h = harnessById(chosen.harness)
-  // node identity + label: explicit --node wins, else the prompt's first `[[id]]` topic ref; a prompt with
-  // none is node-agnostic and labeled by its first few words.
-  const ref = node || mentionedNode(prompt)
-  const title = ref ? null : titleFromPrompt(prompt)
+  const pinned = h.baseCmd(chosen.cmd)
+  // Resolve a command preset at the shared backend prompt boundary, before any worktree exists. The RAW prompt remains the
+  // identity + originating-prompt source; only `launchPrompt` is expanded for the agent. This preserves the
+  // no-target rule even when the plugin body itself contains `[[links]]`.
+  const rawPrompt = prompt
+  // node identity + label: the RAW prompt's first `[[id]]` topic ref is the only binding channel; expanded
+  // plugin prose is payload only and can never invent scope.
+  const ref = nodeFromPrompt(rawPrompt)
+  const launchSpecs = ref ? await loadSpecs() : null
+  let launchPrompt = await resolveCommandPrompt(rawPrompt, launchSpecs ?? undefined)
+  const title = ref ? null : titleFromPrompt(rawPrompt)
   const slug = `${slugify(ref || title)}-${id.slice(0, 4)}`
   const branch = `node/${slug}`
   const path = join(mainRoot(), '.worktrees', slug)
@@ -1202,35 +1317,38 @@ export async function newSession(node: string | null, prompt: string, parent: st
     node: ref || null, title, name: null, parent: parent && parent !== id ? parent : null,
     status: 'queued', proposal: null, merges: 0, note: null, sortKey: null, createdAt: Date.now(),
     harness: h.id, harnessSessionId: null, launcher: chosen.name,
-    // PIN the resolved base launcher command NOW ([[launcher-select]] resume-launcher-pin) so every future
+    // PIN the resolved launch command NOW ([[launcher-select]] resume-launcher-pin) so every future
     // (re)launch replays THIS exact launcher — the one whose config-dir env holds the conversation — instead of
     // re-resolving against a default that may have flipped (a backend restarted under a different launcher).
-    launchCmd: h.baseCmd(chosen.cmd),
+    launchCmd: pinned,
+    launchOwner: backendLaunchAuthority(),
   }
   writeRecord(rec)
-  writePromptFile(id, prompt)   // capture the ORIGINATING prompt (the human/manager's ask) as store metadata (best-effort)
+  writePromptFile(id, rawPrompt)   // capture the ORIGINATING prompt (the human/manager's ask), not expanded plugin prose
   // materialize the harness-discovered artifacts INTO the worktree (CLAUDE.md/AGENTS.md contract block, .claude/.codex
   // shims, manifest to the global store) so the launched agent gets the contract + hooks the SAME way a
   // self-launched one does — by auto-discovery, not CLI injection. This is why the launch line below carries no
   // --append-system-prompt / --settings, and why we no longer hide CLAUDE.md: hiding it suppressed the agent's
-  // own memory load too. One delivery path for both launch modes ([[harness-delivery]]).
+  // own memory load too.
   bootstrapMaterialize(rec)
-  let launchPrompt = prompt
   if (ref) {
-    // @@@ spec pointer - the ref (explicit --node, else the prompt's first [[id]] ref) named an EXISTING node.
+    // @@@ spec pointer - the prompt's first [[id]] ref named an EXISTING node.
     // Append ONE line pointing the agent at that node's spec.md as an ABSOLUTE path INSIDE its own worktree, so
     // it reads the LIVE file (never a stale snapshot we'd inject). relPath already carries the .spec/ prefix and
     // is identical in this freshly-branched worktree, so the absolute path is just join(worktree, relPath). Only
     // a real node gets a pointer; an unknown id resolves to nothing and we fail quiet (no pointer appended).
-    const spec = (await loadSpecs()).find((n) => n.id === ref)
-    if (spec) launchPrompt = `${prompt}\n\nThe spec node \`${ref}\` is your ground truth — read its spec at ${join(path, spec.path)}.`
+    const spec = launchSpecs?.find((n) => n.id === ref)
+    if (spec) launchPrompt = `${launchPrompt}\n\nThe spec node \`${ref}\` is your ground truth — read its spec at ${join(path, spec.path)}.`
   }
   writeLaunchFile(id, launchPrompt)     // park the exact launch prompt for the drainer (consumed at launch)
   await drainQueue()                    // launch now if under the cap, else leave it queued for a free slot
   const after = readRecord(id) ?? rec   // 'active' if the drain launched it, else still 'queued'
-  // queued → no process yet (offline liveness); just-launched → its socket is still booting (starting).
+  // Every adapter answers from its own truth. Asking with no process facts distinguishes a record-backed
+  // adapter (online immediately) from process-backed queued/booting adapters (offline/starting) without an
+  // extra whole-box tmux snapshot on the creation hot path.
+  const recordOnline = h.liveness(after, false, runtimeRoot()) === 'online'
   const queued = after.status === 'queued'
-  return toSession(after, queued ? 'queued' : 'working', queued ? 'offline' : 'starting')
+  return toSession(after, queued ? 'queued' : 'working', recordOnline ? 'online' : queued ? 'offline' : 'starting')
 }
 
 // @@@ bootstrapMaterialize - the creation-time materialize is BOOTSTRAP, not best-effort: it is what writes
@@ -1297,7 +1415,7 @@ async function waitForReady(id: string, harness: Harness, timeoutMs = SOCKET_REA
 //     session that is proposing a merge must NOT silently withdraw it. Only applied when we actually relaunch;
 //     a refusal leaves the record wholly untouched.
 // Fail-loud is unchanged: if the agent never comes online, the later deliver() fails loud.
-export async function resumeSession(id: string, opts: { force?: boolean; guard?: boolean } = {}): Promise<{ ok: boolean; error?: string; refused?: boolean }> {
+export async function resumeSession(id: string, opts: { force?: boolean; guard?: boolean } = {}): Promise<{ ok: boolean; error?: string; refused?: boolean; info?: string }> {
   const { force = false, guard = true } = opts
   const wt = await findWorktree(id)
   if (!wt) return { ok: false, error: `no such session ${id}` }
@@ -1312,7 +1430,7 @@ export async function resumeSession(id: string, opts: { force?: boolean; guard?:
   writeRecord({ ...wt.rec, status: wt.rec.status === 'active' ? 'idle' : wt.rec.status })
   if (force || lv === 'offline') {
     await tmuxOk(['kill-session', '-t', id])   // drop a dead/offline pane (or a force-killed live one)
-    await launch(id, wt.path, h.resumeArg(wt.rec).trim(), h, launcherCmd(wt.rec))   // resume under the SAME persisted launcher ([[launcher-select]])
+    await launch(id, wt.path, h.resumeArg(wt.rec).trim(), h, launcherCmd(wt.rec))
     await waitForReady(id, h)   // a relaunched agent is "ready" only once the adapter reads it online
   }
   return { ok: true }
@@ -1532,14 +1650,13 @@ export async function mergeSession(id: string): Promise<{ dispatched: boolean; r
 
 // @@@ stopAgentProcess - the shared teardown both stop and close begin with, so there is ONE kill path, not
 // two: kill the agent's tmux client, drop its boot-window stamp (else a just-launched id lingers in the grace
-// window reading `starting` instead of `offline`), and sweep its rendezvous socket. The socket lives in the OS
-// tmpdir (NOT the worktree), so worktree removal alone would leave it behind — closing many sessions over time
-// would accumulate stale `spexcode-rv-*.sock` files; we unlink it here (force = no error if claude/OS already
-// removed it). Deliberately does NOT drainQueue — the caller drains once, after it has settled the worktree.
+// window reading `starting` instead of `offline`), and ask the resolved adapter to sweep its ephemeral runtime
+// transport. Deliberately does NOT drainQueue — the caller drains once, after it has settled the worktree.
 async function stopAgentProcess(id: string): Promise<void> {
+  const rec = readRecord(id)
   await tmuxOk(['kill-session', '-t', id])
   launchedAt.delete(id)
-  try { rmSync(rvSock(id), { force: true }) } catch { /* best-effort sweep; tmpdir socket, claude/OS may already be gone */ }
+  harnessById(rec?.harness || defaultHarness.id).cleanupRuntime(rec ?? { session: id })
 }
 
 // @@@ stopSession - the SOFT stop (vs closeSession's removal): stops the agent process but LEAVES the durable
@@ -1611,26 +1728,31 @@ const ANSI: Record<DisplayStatus, string> = {
 }
 
 // @@@ session selectors - the ONE matcher every session command shares (see [[session-selectors]]). A
-// selector matches a session iff it is the session's full id, an id-PREFIX, its node, or its branch. This is
+// selector matches a session iff it is the session's full id, an id-PREFIX, its node, its branch, or `.` for
+// the caller's own launched session. This is
 // the single predicate; selectSessions (MANY) and resolveSession (ONE) both call it, so id-prefix/node/branch
 // resolution can never drift between "which sessions ls/watch/wait/graph show" and "which session
 // review/merge/send/close act on".
-export function matchesSelector(s: Session, q: string): boolean {
+export function matchesSelector(s: Session, q: string, own = ownSessionId(), cwd = process.cwd()): boolean {
   // a selector may be a comma-separated list (the same convention as `--status a,b`): it matches iff ANY part
   // names the session, so `watch a,b` and `watch a b` are equivalent. A single name is the one-part case. This
   // is what stops a comma-joined selector from silently matching nothing — an id/node/branch never holds a
   // comma, so without the split `a,b` would be one literal selector that matches no session and streams in
   // silence forever. Each part sheds an optional reference sigil (stripRefSigil): `@<sel>` / `[[<sel>]]` name
   // the same session as the bare token, so the dashboard's mention grammar is tolerated in every CLI selector.
+  const sessionPath = s.path ? resolve(s.path) : null
+  const callerPath = resolve(cwd)
+  const self = Boolean(own) && s.id === own
+    || Boolean(sessionPath) && (callerPath === sessionPath || callerPath.startsWith(`${sessionPath}${sep}`))
   return q.split(',').map((p) => stripRefSigil(p.trim())).filter(Boolean)
-    .some((p) => s.id === p || s.id.startsWith(p) || s.node === p || s.branch === p)
+    .some((p) => p === '.' ? self : s.id === p || s.id.startsWith(p) || s.node === p || s.branch === p)
 }
 
 // no selectors (or '@all') = everything. Optional status filter on top. This IS the ls/watch subscription.
-export function selectSessions(all: Session[], selectors: string[], statuses?: string[]): Session[] {
+export function selectSessions(all: Session[], selectors: string[], statuses?: string[], own = ownSessionId(), cwd = process.cwd()): Session[] {
   let out = all
   const sel = selectors.filter((x) => x && x !== '@all')
-  if (sel.length) out = out.filter((s) => sel.some((q) => matchesSelector(s, q)))
+  if (sel.length) out = out.filter((s) => sel.some((q) => matchesSelector(s, q, own, cwd)))
   if (statuses && statuses.length) out = out.filter((s) => statuses.includes(s.status))
   return out
 }
@@ -1642,11 +1764,11 @@ export function selectSessions(all: Session[], selectors: string[], statuses?: s
 // precisely: an exact full-id hit wins outright (never reported ambiguous just for prefixing a longer id);
 // otherwise a lone match is `ok`, several is `ambiguous` (a prefix/node hitting many), none is `none`.
 export type Resolved = { ok: Session } | { ambiguous: Session[] } | { none: true }
-export function resolveSession(selector: string, sessions: Session[]): Resolved {
+export function resolveSession(selector: string, sessions: Session[], own = ownSessionId(), cwd = process.cwd()): Resolved {
   // the exact-id check sheds the optional sigil too, so `@<full-id>` keeps the exact-wins-over-prefix rule
   const exact = sessions.find((s) => s.id === stripRefSigil(selector))
   if (exact) return { ok: exact }
-  const hits = sessions.filter((s) => matchesSelector(s, selector))
+  const hits = sessions.filter((s) => matchesSelector(s, selector, own, cwd))
   if (hits.length === 1) return { ok: hits[0] }
   return hits.length ? { ambiguous: hits } : { none: true }
 }
@@ -1874,10 +1996,14 @@ export async function sendText(id: string, text: string, from?: string, opts: {
       if (blocked) return { ok: false, error: blocked }
     } catch { /* no pane to consult — let the delivery channel decide */ }
   }
-  // a terminal-free sender's dispatch carries the note-reply insert ([[session-timeline]]); appended here,
-  // beside the delivery, so every input surface shares the one phrase and the timeline records the message
-  // WITHOUT it (the hint is transport, not conversation).
-  const r = await h.deliver({ ...rec, runtimeDir: runtimeRoot() }, opts.replyVia === 'note' ? withNoteReplyHint(text) : text)
+  const prompt = await resolveCommandPrompt(text)
+  // a terminal-free sender's dispatch carries the note-reply insert; a human send WITHOUT the flag whose
+  // previous human send carried it is the note→terminal transition and gets the one-shot counter-insert
+  // ([[session-timeline]]). Both appended here, beside the delivery, so every input surface shares the one
+  // phrase pair and the timeline records the message WITHOUT it (the hint is transport, not conversation).
+  const wrapped = opts.replyVia === 'note' ? withNoteReplyHint(prompt)
+    : !from && lastHumanSendVia(id) === 'note' ? withTerminalReplyHint(prompt) : prompt
+  const r = await h.deliver({ ...rec, runtimeDir: runtimeRoot() }, wrapped)
   // record the delivered agent-to-agent message ([[comms-edge]]): only when it carries a sender (an agent
   // send, not a raw human dispatch) and actually landed. Fire-and-forget — never gates the send result.
   if (r.ok && from) void recordComms(id, from)
@@ -1886,11 +2012,21 @@ export async function sendText(id: string, text: string, from?: string, opts: {
   return r
 }
 
+// Hard interrupt is adapter-native control, distinct from stop's process teardown. A harness without a
+// confirmed native primitive refuses loudly; there is no signal/PTY fallback that could target the wrong turn.
+export async function interruptSession(id: string): Promise<DispatchResult> {
+  const rec = readRecord(id)
+  if (!rec) return { ok: false, error: `no session record for ${id} - nothing to interrupt` }
+  const h = harnessById(rec.harness || defaultHarness.id)
+  if (!h.interrupt) return { ok: false, error: `harness ${h.id} has no native hard-interrupt control` }
+  return h.interrupt({ ...rec, runtimeDir: runtimeRoot() })
+}
+
 // @@@ rawKey - the RAW-KEYSTROKE nav path, kept DELIBERATELY on `tmux send-keys` and NEVER the rendezvous
 // socket. Two channels, two jobs: the socket INJECTS a whole prompt (text + submit), which can drive the
 // agent's normal prompt but CANNOT navigate an interactive TUI select menu (e.g. `/model`'s list — ↑/↓ to
 // move, ←/→ to adjust, Enter to set, `s` for this-session, Esc to cancel). When the agent is in that
-// keystroke-navigation state its input box is replaced by the menu, so the dashboard's type mode forwards
+// keystroke-navigation state its input box is replaced by the menu, so the CLI raw-key fallback forwards
 // each key here in real time. send-keys is exactly right for single raw keys: named keys map to tmux's own
 // key names; a single printable char is sent literally (`-l`) so tmux doesn't reinterpret it. The dashboard
 // also drives the agent with MODIFIER COMBOS — a terminal's three modifiers carried as a `C-`/`M-`/`S-`