spexcode 0.4.3 → 0.5.1

package/spec-cli/src/pi-headless.ts

@@ -0,0 +1,195 @@
+import { createConnection, createServer, type Server, type Socket } from 'node:net'
+import { spawn, type ChildProcess } from 'node:child_process'
+import { mkdirSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type { DispatchResult, HarnessDeliveryRecord } from './harness.js'
+
+type ControlRequest = { type: 'deliver'; text: string }
+type ChildTurn = { process: ChildProcess; exited: Promise<number | null> }
+
+const PKG = fileURLToPath(new URL('..', import.meta.url))
+const SPEX = join(PKG, 'bin', 'spex.mjs')
+const CONTROL_TIMEOUT_MS = 30_000
+const START_TIMEOUT_MS = 30_000
+
+const shQuote = (s: string) => `'${s.replace(/'/g, `'\\''`)}'`
+
+/** The resident controller socket is distinct from pi's per-turn rendezvous socket. */
+export const piHeadlessSock = (id: string) => join(tmpdir(), `spexcode-ph-${id}.sock`)
+
+export function piHeadlessLaunchCommand(id: string, runtimeDir: string, piCmd: string): string {
+  return [shQuote(SPEX), 'internal', 'pi-headless-run', shQuote(id), shQuote(runtimeDir), shQuote(piCmd), '--'].join(' ')
+}
+
+function withTimeout<T>(promise: Promise<T>, ms: number, message: string): Promise<T> {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error(message)), ms)
+    promise.then(
+      (value) => { clearTimeout(timer); resolve(value) },
+      (error) => { clearTimeout(timer); reject(error) },
+    )
+  })
+}
+
+function controlRequest(id: string, request: ControlRequest): Promise<DispatchResult> {
+  return new Promise((resolve) => {
+    let socket: Socket | undefined
+    let settled = false
+    let buffer = ''
+    const finish = (result: DispatchResult) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      socket?.destroy()
+      resolve(result)
+    }
+    const timer = setTimeout(() => finish({ ok: false, error: `pi-headless control timed out for session ${id}` }), CONTROL_TIMEOUT_MS)
+    try { socket = createConnection(piHeadlessSock(id)) } catch (error) {
+      finish({ ok: false, error: `pi-headless controller connect failed for session ${id}: ${(error as Error).message}` })
+      return
+    }
+    socket.setEncoding('utf8')
+    socket.on('connect', () => socket!.write(`${JSON.stringify(request)}\n`))
+    socket.on('data', (chunk) => {
+      buffer += chunk
+      const nl = buffer.indexOf('\n')
+      if (nl < 0) return
+      try {
+        const response = JSON.parse(buffer.slice(0, nl)) as DispatchResult
+        finish(response.ok ? { ok: true } : { ok: false, error: response.error || 'pi-headless controller rejected the request' })
+      } catch (error) {
+        finish({ ok: false, error: `pi-headless returned an invalid control response: ${(error as Error).message}` })
+      }
+    })
+    socket.on('error', (error) => finish({ ok: false, error: `pi-headless controller unreachable for session ${id}: ${error.message}` }))
+    socket.on('close', () => finish({ ok: false, error: `pi-headless controller closed before confirming session ${id}` }))
+  })
+}
+
+export const deliverViaPiHeadless = (rec: HarnessDeliveryRecord, text: string) =>
+  controlRequest(rec.session, { type: 'deliver', text })
+
+export class PiHeadlessController {
+  private server: Server | null = null
+  private child: ChildTurn | null = null
+  private controlQueue: Promise<void> = Promise.resolve()
+  private closing = false
+  private readonly socketPath: string
+
+  constructor(
+    private readonly id: string,
+    _runtimeDir: string,
+    private readonly piCmd: string,
+    private readonly cwd = process.cwd(),
+  ) {
+    this.socketPath = piHeadlessSock(id)
+  }
+
+  async start(initialPrompt?: string): Promise<void> {
+    try { rmSync(this.socketPath, { force: true }) } catch { /* stale control socket is replaced at startup */ }
+    this.server = createServer((socket) => this.accept(socket))
+    await new Promise<void>((resolve, reject) => {
+      const onError = (error: Error) => { this.server?.off('listening', onListening); reject(error) }
+      const onListening = () => { this.server?.off('error', onError); resolve() }
+      this.server!.once('error', onError)
+      this.server!.once('listening', onListening)
+      this.server!.listen(this.socketPath)
+    })
+    if (initialPrompt) void this.spawnTurn(initialPrompt, false).catch((error) => {
+      console.error(`[spex pi-headless] initial turn failed: ${(error as Error).message}`)
+    })
+  }
+
+  async close(): Promise<void> {
+    if (this.closing) return
+    this.closing = true
+    const child = this.child
+    if (child && child.process.exitCode === null) child.process.kill('SIGTERM')
+    await new Promise<void>((resolve) => {
+      if (!this.server) return resolve()
+      this.server.close(() => resolve())
+    })
+    try { rmSync(this.socketPath, { force: true }) } catch { /* best-effort cleanup after close */ }
+    const { rvSock } = await import('./harness.js')
+    try { rmSync(rvSock(this.id), { force: true }) } catch { /* pi may already have removed it */ }
+  }
+
+  private accept(socket: Socket): void {
+    socket.setEncoding('utf8')
+    let buffer = ''
+    let handled = false
+    socket.on('data', (chunk) => {
+      if (handled) return
+      buffer += chunk
+      const nl = buffer.indexOf('\n')
+      if (nl < 0) return
+      handled = true
+      let request: ControlRequest
+      try { request = JSON.parse(buffer.slice(0, nl)) as ControlRequest } catch (error) {
+        socket.end(`${JSON.stringify({ ok: false, error: `invalid control request: ${(error as Error).message}` })}\n`)
+        return
+      }
+      this.controlQueue = this.controlQueue.then(async () => {
+        const result = await this.handle(request).catch((error) => ({ ok: false, error: (error as Error).message }))
+        socket.end(`${JSON.stringify(result)}\n`)
+      })
+    })
+  }
+
+  private async handle(request: ControlRequest): Promise<DispatchResult> {
+    if (request.type !== 'deliver') return { ok: false, error: 'unknown pi-headless control request' }
+    if (!request.text) return { ok: false, error: 'empty prompt - nothing to deliver' }
+
+    // A live extension listener is an in-flight pi turn. The native steer path is parse-confirmed by the
+    // shared rendezvous protocol. Only a proven absent listener may cold-wake a saved session.
+    const { deliverViaRendezvous, rendezvousListening } = await import('./harness.js')
+    const listener = await rendezvousListening(this.id)
+    if (listener === 'live') return deliverViaRendezvous(this.id, request.text)
+    if (listener === 'unproven') return { ok: false, error: `could not determine whether pi turn ${this.id} is live — prompt NOT delivered` }
+
+    if (this.child) await withTimeout(this.child.exited, 5_000, `previous pi-headless turn did not exit for session ${this.id}`)
+    await this.spawnTurn(request.text, true)
+    return { ok: true }
+  }
+
+  private async spawnTurn(text: string, resume: boolean): Promise<void> {
+    if (this.closing) throw new Error('pi-headless controller is closing')
+    const mode = resume ? ['--session', this.id] : ['--session-id', this.id]
+    // Keep pi's default text mode. `--mode json` is intentionally omitted: it can hang in this runtime.
+    const args = ['-p', ...mode, text]
+    const command = `exec ${this.piCmd} ${args.map(shQuote).join(' ')}`
+    const childProcess = spawn('/bin/sh', ['-lc', command], { cwd: this.cwd, env: process.env, stdio: ['ignore', 'pipe', 'pipe'] })
+    let resolveExit!: (code: number | null) => void
+    const exited = new Promise<number | null>((resolve) => { resolveExit = resolve })
+    const turn: ChildTurn = { process: childProcess, exited }
+    this.child = turn
+    childProcess.stdout?.pipe(process.stdout)
+    childProcess.stderr?.pipe(process.stderr)
+    childProcess.once('error', (error) => console.error(`[spex pi-headless] child spawn failed: ${error.message}`))
+    childProcess.once('close', (code) => {
+      if (this.child === turn) this.child = null
+      resolveExit(code)
+    })
+    await withTimeout(new Promise<void>((resolve, reject) => {
+      childProcess.once('spawn', () => resolve())
+      childProcess.once('error', reject)
+    }), START_TIMEOUT_MS, `pi-headless child did not start for session ${this.id}`)
+  }
+}
+
+export async function runPiHeadlessController(id: string, runtimeDir: string, piCmd: string, tail: string[]): Promise<void> {
+  // runtimeDir is retained in the command shape for parity with claude-headless and future per-session output.
+  mkdirSync(join(runtimeDir, 'sessions', id), { recursive: true })
+  const controller = new PiHeadlessController(id, runtimeDir, piCmd)
+  const resume = tail[0] === '--session'
+  const prompt = resume ? undefined : tail[0] === '--session-id' ? tail.slice(2).join(' ') : tail.join(' ')
+  await controller.start(prompt)
+  await new Promise<void>((resolve) => {
+    const stop = () => void controller.close().finally(resolve)
+    process.once('SIGINT', stop)
+    process.once('SIGTERM', stop)
+    process.once('SIGHUP', stop)
+  })
+}

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

@@ -22,9 +22,10 @@ import type { Lifecycle, Proposal } from './sessions.js'
 // is recorded — liveness (offline/starting/unknown) is a present-tense derivation ([[state]]), re-derived
 // per probe and never history, so it stays off the durable log; a surface shows the CURRENT liveness from
 // the board row. The timeline lives and dies with the session record (close sweeps the store dir), like
-// comms.ndjson. `sent` events are appended by sendText on a CONFIRMED delivery (all prompt deliveries flow
-// through it: dashboard/phone input, `spex session send`, the merge dispatch); `from` is the sending
-// session's id, null = a human surface.
+// comms.ndjson. `sent` events are appended by sendText on a CONFIRMED post-launch delivery (dashboard/phone
+// input, `spex session send`, merge and issue dispatch); the initial launch prompt passes through the same
+// composition seam but has no adapter confirmation to record here. `from` is the sending session's id,
+// null = a human surface.
 
 export type TimelineEvent =
   | { ts: string; kind: 'status'; status: Lifecycle; proposal: Proposal | null; note: string | null; display?: string }
@@ -134,7 +135,8 @@ export function lastHumanSendVia(id: string): 'note' | null {
 
 // record a CONFIRMED prompt delivery (called by sendText after the harness accepted it). `text` is the
 // caller's message BEFORE any mechanism insert (the note-reply hint is transport, not conversation);
-// `replyVia` marks that the hint rode along so a surface can badge it.
+// `replyVia` is the effective channel chosen by the shared prompt seam, whether explicit or derived from the
+// target adapter, so the durable history records where the reply was actually readable.
 export function recordSent(id: string, text: string, from: string | null, replyVia?: 'note'): void {
   try { if (!readAliasedRawRecord(id)?.governed) return } catch { return }
   append(id, { ts: new Date().toISOString(), kind: 'sent', text, from, ...(replyVia ? { replyVia } : {}) })

package/spec-cli/src/sessions.ts

@@ -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
@@ -565,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 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).
@@ -611,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
@@ -890,12 +892,12 @@ export function withSenderHint(text: string, sender: MsgSender | null): string {
   const who = sender.label && sender.label !== sender.id ? `session "${sender.label}" (${sender.id})` : `session ${sender.id}`
   return `${text}\n\n— from ${who}. To reply: spex session send ${sender.id} "<your reply>"`
 }
-// @@@ withNoteReplyHint - the TERMINAL-FREE sender's insert, withSenderHint's sibling: a phone (or any
-// no-terminal surface, [[mobile-ui]]) cannot read the pane, so the only text that ever reaches its human is
-// 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. The notice declares itself
+// @@@ withNoteReplyHint - the HEADLESS TARGET's insert, withSenderHint's sibling: a session with no readable
+// terminal can return text to its human only through its 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 output stream. composeSessionPrompt is the only production caller
+// deciding whether it applies; a surface may explicitly request note, but the target adapter owns the
+// default. 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.
@@ -994,6 +996,30 @@ export async function resolveCommandPrompt(raw: string, loadedSpecs?: CommandSpe
   const specs = loadedSpecs ?? (nodeFromPrompt(raw) ? await loadSpecs() : [])
   return composeCommandPrompt(raw, [preset], specs)
 }
+
+type SessionPromptTarget = Pick<SessRec, 'session' | 'harness'>
+type SessionPromptOptions = {
+  from?: string
+  replyVia?: 'note'
+  loadedSpecs?: CommandSpec[]
+  suffix?: string
+}
+export type ComposedSessionPrompt = { text: string; replyVia?: 'note' }
+
+// @@@ composeSessionPrompt - the ONE prompt-delivery seam: raw caller text + target session become the
+// exact text handed to an adapter. Launch, ordinary input, CLI send, issue dispatch, watch greetings, and
+// merge all enter here (directly or through sendText). `replyVia` is target readability: an explicit note
+// request wins; otherwise a headless adapter defaults to note. This function alone decides and appends the
+// note/terminal inserts, so clients never own the policy or duplicate the phrase.
+export async function composeSessionPrompt(raw: string, target: SessionPromptTarget, opts: SessionPromptOptions = {}): Promise<ComposedSessionPrompt> {
+  const resolved = await resolveCommandPrompt(raw, opts.loadedSpecs)
+  const prompt = opts.suffix ? `${resolved}${opts.suffix}` : resolved
+  const h = harnessById(target.harness || defaultHarness.id)
+  const replyVia = opts.replyVia ?? (h.headless ? 'note' : undefined)
+  const text = replyVia === 'note' ? withNoteReplyHint(prompt)
+    : !opts.from && lastHumanSendVia(target.session) === 'note' ? withTerminalReplyHint(prompt) : prompt
+  return { text, ...(replyVia ? { replyVia } : {}) }
+}
 // @@@ 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
@@ -1055,7 +1081,10 @@ export function launchScript(id: string, tail: string, harness: Harness = HARNES
   // retry window, so liveness stays 'starting' and waitForReady keeps holding the slot across retries. This
   // only closes startup unready failures — it adds no fallback and never masks a genuinely dead agent (3
   // attempts, then give up).
-  writeFileSync(file, [
+  // A one-shot adapter (currently codex-headless) deliberately exits after its first turn while the shared
+  // app-server stays alive. Retrying that successful fast exit would mint a duplicate thread/prompt, so the
+  // retry loop is a runtime capability rather than a harness-id branch.
+  const launchBody = harness.launchOneShot ? [born, ''] : [
     `for __spex_try in 1 2 3; do`,
     `  __spex_t0=$SECONDS`,
     `  ${born}`,
@@ -1066,7 +1095,8 @@ export function launchScript(id: string, tail: string, harness: Harness = HARNES
     `done`,
     `exit $__spex_rc`,
     ``,
-  ].join('\n'))
+  ]
+  writeFileSync(file, launchBody.join('\n'))
   return file
 }
 async function launch(id: string, path: string, tail: string, harness: Harness = HARNESS, cmd?: string): Promise<void> {
@@ -1284,19 +1314,25 @@ export async function newSession(prompt: string, parent: string | null = null, l
   const chosen = resolveLauncher(lname)
   const h = harnessById(chosen.harness)
   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)
+  // Compose the FINAL launch text before making the worktree, preserving fail-before-side-effects if live
+  // preset resolution breaks. The optional spec pointer is a seam input; the note insert remains last.
+  const spec = ref ? launchSpecs?.find((n) => n.id === ref) : undefined
+  const suffix = spec
+    ? `\n\nThe spec node \`${ref}\` is your ground truth — read its spec at ${join(path, spec.path)}.`
+    : undefined
+  const launchPrompt = (await composeSessionPrompt(rawPrompt, { session: id, harness: h.id }, {
+    loadedSpecs: launchSpecs ?? undefined,
+    suffix,
+  })).text
   await gitA(['-C', mainRoot(), 'worktree', 'add', '-b', branch, path, mainBranch()])
   // the checkout delivers the tracked spec sources and the materialize below delivers the materialized
   // artifacts; the ONE
@@ -1329,21 +1365,15 @@ export async function newSession(prompt: string, parent: string | null = null, l
   // --append-system-prompt / --settings, and why we no longer hide CLAUDE.md: hiding it suppressed the agent's
   // own memory load too.
   bootstrapMaterialize(rec)
-  if (ref) {
-    // @@@ 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 = 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
@@ -1645,14 +1675,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
@@ -1992,22 +2021,26 @@ 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 */ }
   }
-  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)
+  const prompt = await composeSessionPrompt(text, rec, { from, replyVia: opts.replyVia })
+  const r = await h.deliver({ ...rec, runtimeDir: runtimeRoot() }, prompt.text)
   // 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)
   // the durable interaction history ([[session-timeline]]): every confirmed delivery is a `sent` event.
-  if (r.ok) recordSent(id, text, from ?? null, opts.replyVia)
+  if (r.ok) recordSent(id, text, from ?? null, prompt.replyVia)
   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

package/spec-cli/templates/spexcode.json

@@ -2,12 +2,19 @@
   "lint": {
     "governedRoots": ["."]
   },
+  "dashboard": {
+    "showHeadlessLaunchers": false
+  },
   "sessions": {
     "launchers": {
       "claude": { "harness": "claude", "cmd": "claude" },
+      "claude-headless": { "harness": "claude-headless", "cmd": "claude" },
       "codex": { "harness": "codex", "cmd": "codex" },
+      "codex-headless": { "harness": "codex-headless", "cmd": "codex --yolo" },
       "opencode": { "harness": "opencode", "cmd": "opencode" },
-      "pi": { "harness": "pi", "cmd": "pi" }
+      "opencode-headless": { "harness": "opencode-headless", "cmd": "opencode --auto" },
+      "pi": { "harness": "pi", "cmd": "pi" },
+      "pi-headless": { "harness": "pi-headless", "cmd": "pi" }
     },
     "defaultLauncher": "claude"
   }