spexcode 0.5.0 → 0.5.2

package/spec-cli/src/pty-bridge.ts

@@ -20,6 +20,7 @@ type Subscription = {
   bridge?: Bridge
   lingerTimer?: ReturnType<typeof setTimeout>
   restoreTimer?: ReturnType<typeof setTimeout>
+  startupError?: string
 }
 
 type Bridge = {
@@ -37,6 +38,7 @@ type Bridge = {
   refreshRunning: boolean
   refreshOffset?: number
   deliveryTimer?: ReturnType<typeof setTimeout>
+  startupError?: string
 }
 
 const subscribers = new Map<string, Map<Viewer, Subscription>>()
@@ -103,6 +105,8 @@ function onHelperStderr(bridge: Bridge, chunk: Buffer): void {
     const ready = line.match(/^READY (\d+)$/)
     if (ready) {
       bridge.ptyPid = Number(ready[1])
+      const subscription = currentSubscription(bridge.id, bridge.viewer)
+      if (subscription) subscription.startupError = undefined
       if (bridge.delivery === 'initial') {
         armDeliveryBoundary(bridge)
         queueRefresh(bridge)
@@ -117,11 +121,28 @@ function onHelperStderr(bridge: Bridge, chunk: Buffer): void {
         queueRefresh(bridge)
       }
     } else if (line) {
+      const failed = line.match(/^ERROR (.+)$/)
+      if (failed) reportStartupError(bridge, failed[1])
       console.error(`[terminal helper ${bridge.id}/${bridge.ptyPid ?? 'starting'}] ${line}`)
     }
   }
 }
 
+function reportStartupError(bridge: Bridge, detail: string): void {
+  const subscription = currentSubscription(bridge.id, bridge.viewer)
+  if (!subscription || subscription.bridge !== bridge) return
+  const message = boundedStartupError(detail)
+  bridge.startupError = message
+  if (!message || subscription.startupError === message) return
+  subscription.startupError = message
+  deliver(bridge, Buffer.from(`\r\n[SpexCode terminal unavailable] ${message}\r\n`, 'utf8'))
+}
+
+function boundedStartupError(detail: unknown): string {
+  return (detail instanceof Error ? detail.message : String(detail))
+    .replace(/[\x00-\x1f\x7f]+/g, ' ').trim().slice(0, 500) || 'native PTY failed to start'
+}
+
 function ensureBridge(id: string, viewer: Viewer, subscription: Subscription, cols: number, rows: number): { bridge: Bridge | null; created: boolean } {
   if (subscription.bridge) return { bridge: subscription.bridge, created: false }
   let proc: ChildProcessWithoutNullStreams | undefined
@@ -130,8 +151,13 @@ function ensureBridge(id: string, viewer: Viewer, subscription: Subscription, co
       stdio: ['pipe', 'pipe', 'pipe'],
       env: process.env,
     })
-  } catch {
+  } catch (error) {
     try { proc?.kill() } catch { /* spawn did not complete */ }
+    const detail = boundedStartupError(error)
+    if (subscription.startupError !== detail) {
+      subscription.startupError = detail
+      try { viewer.send(Buffer.from(`\r\n[SpexCode terminal unavailable] ${detail}\r\n`, 'utf8')) } catch { /* socket closed */ }
+    }
     return { bridge: null, created: false }
   }
   const bridge: Bridge = {
@@ -142,18 +168,19 @@ function ensureBridge(id: string, viewer: Viewer, subscription: Subscription, co
   proc.stdout.on('data', (data: Buffer) => onHelperOutput(bridge, data))
   proc.stderr.on('data', (data: Buffer) => onHelperStderr(bridge, data))
   let reaped = false
-  const gone = () => {
+  const gone = (detail?: string) => {
     if (reaped) return
     reaped = true
     const current = currentSubscription(id, viewer)
     if (current?.bridge !== bridge) return
+    if (!bridge.ptyPid && !bridge.startupError) reportStartupError(bridge, detail || 'helper exited before native PTY startup')
     current.bridge = undefined
     clearDelivery(bridge)
     try { bridge.proc.kill() } catch { /* already gone */ }
     scheduleRestore(id, viewer, current)
   }
-  proc.on('exit', gone)
-  proc.on('error', gone)
+  proc.on('exit', (code, signal) => gone(`helper exited before native PTY startup (${signal ? `signal ${signal}` : `code ${code ?? 'unknown'}`})`))
+  proc.on('error', (error) => gone(`helper process failed: ${error.message}`))
   return { bridge, created: true }
 }
 

package/spec-cli/src/pty-helper.mjs

@@ -1,5 +1,6 @@
 import * as pty from 'node-pty'
 import { execFileSync } from 'node:child_process'
+import { ensureExecutableIfPresent, nodePtySpawnHelperPath } from './pty-native-helper.mjs'
 
 const [id, colsArg, rowsArg] = process.argv.slice(2)
 const cols = Number(colsArg)
@@ -40,12 +41,21 @@ try {
   }
 } catch { /* attach below fails loudly if the tmux server/session is unavailable */ }
 
-const terminal = pty.spawn('tmux', ['-u', '-L', socket, 'attach-session', '-t', id], {
-  name: 'xterm-256color',
-  cols,
-  rows,
-  env: { ...process.env, LANG: process.env.LANG || 'en_US.UTF-8' },
-})
+let terminal
+try {
+  ensureExecutableIfPresent(nodePtySpawnHelperPath(pty.native))
+  terminal = pty.spawn('tmux', ['-u', '-L', socket, 'attach-session', '-t', id], {
+    name: 'xterm-256color',
+    cols,
+    rows,
+    env: { ...process.env, LANG: process.env.LANG || 'en_US.UTF-8' },
+  })
+} catch (error) {
+  const detail = (error instanceof Error ? error.message : String(error))
+    .replace(/[\x00-\x1f\x7f]+/g, ' ').trim().slice(0, 500)
+  process.stderr.write(`ERROR ${detail || 'native PTY failed to start'}\n`)
+  process.exit(1)
+}
 
 terminal.onData((data) => process.stdout.write(Buffer.from(data, 'utf8')))
 terminal.onExit(({ exitCode }) => process.exit(exitCode === 0 ? 0 : 1))

package/spec-cli/src/pty-native-helper.mjs

@@ -0,0 +1,22 @@
+import { chmodSync, statSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+
+const require = createRequire(import.meta.url)
+
+export function nodePtySpawnHelperPath(nativeModule) {
+  const nativeAddon = Object.values(require.cache).find((loaded) => loaded?.exports === nativeModule)?.filename
+  if (!nativeAddon) throw new Error('cannot locate node-pty loaded native addon')
+  return join(dirname(nativeAddon), 'spawn-helper')
+}
+
+export function ensureExecutableIfPresent(path) {
+  let mode
+  try {
+    mode = statSync(path).mode & 0o777
+  } catch (error) {
+    if (error?.code === 'ENOENT') return
+    throw error
+  }
+  if ((mode & 0o111) !== 0o111) chmodSync(path, mode | 0o111)
+}

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

@@ -8,23 +8,23 @@ import type { Lifecycle, Proposal } from './sessions.js'
 // [[mobile-ui]]) renders instead of a live pane: without the terminal, the declaration notes ARE the agent's
 // replies, and the timeline is the whole conversation.
 //
-// WHY an observer, not writer instrumentation: the lifecycle has a writer the TS layer never sees — the
-// mark-active hook value-replaces status/proposal/note in session.json with pure-shell sed ([[state]]).
-// Instrumenting every writer would always miss that one, so the recorder OBSERVES the store instead: one
-// fs.watch on the sessions root (debounced) plus a slow reconcile tick (the fs.watch is best-effort, same
-// stance as [[graph-stream]]'s source 1), and on each tick it diffs every governed record's
-// (status, proposal, note) against the last seen and appends what moved. One mechanism covers every writer
-// by construction. Granularity is the debounce window — a flap faster than ~100ms can collapse, exactly like
-// the board itself.
+// A declaration note is conversation content, so TS lifecycle writes append moved state at the same write
+// boundary instead of asking a later sample of mutable session.json to reconstruct it. The observer remains
+// because the lifecycle also has a writer the TS layer never sees: the mark-active hook value-replaces
+// status/proposal/note with pure-shell sed ([[state]]). One fs.watch on the sessions root (debounced) plus a
+// slow reconcile tick repairs those external writes. Direct append + observation may duplicate one move;
+// readTimeline folds adjacent duplicates without making history mutable.
 //
-// The recorder runs ONLY in the serve process (superviseTimeline is called from index.ts) so exactly one
-// process appends; timestamps are observation times, honest to within the debounce. Only the AUTHORED axis
-// 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.
+// The observer runs ONLY in the serve process (superviseTimeline is called from index.ts); lifecycle writers
+// and confirmed senders append from whichever process owns that write. Direct events use the write time;
+// observed shell events use an observation time honest to within the debounce. Only the AUTHORED axis 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 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 }
@@ -39,6 +39,13 @@ function append(id: string, ev: TimelineEvent): void {
   } catch { /* best-effort: a failed history append must never break the state machine or a delivery */ }
 }
 
+// Record a lifecycle value that has already landed in session.json. TypeScript state writers call this
+// synchronously before returning, so a later write cannot erase an intermediate declaration note from the
+// conversation. The serve observer calls the same sink for shell-authored state.
+export function recordStatus(id: string, status: Lifecycle, proposal: Proposal | null, note: string | null): void {
+  append(id, { ts: new Date().toISOString(), kind: 'status', status, proposal, note })
+}
+
 function readEvents(id: string): TimelineEvent[] {
   try {
     const p = timelinePath(id)
@@ -89,7 +96,7 @@ function scan(): void {
         if (last && fpOf(last.status, last.proposal ?? null, last.note ?? null) === fp) { lastSeen.set(id, fp); continue }
       }
       lastSeen.set(id, fp)
-      append(id, { ts: new Date().toISOString(), kind: 'status', status, proposal, note })
+      recordStatus(id, status, proposal, note)
     } catch { /* one bad record must not stall the sweep */ }
   }
   const live = new Set(ids)
@@ -134,7 +141,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 } : {}) })
@@ -142,9 +150,9 @@ export function recordSent(id: string, text: string, from: string | null, replyV
 
 // the read surface behind GET /api/sessions/:id/timeline: the last `limit` events, oldest first, each
 // status event carrying its composed display word. null = no such session (the route 404s).
-// Adjacent status lines with identical (status, proposal, note) fold into their first: TWO serve processes
-// observing one store (a throwaway worktree/eval serve beside the live one) each keep their own lastSeen,
-// so a single record move can append twice — cross-process write locking isn't worth buying, so the log
+// Adjacent status lines with identical (status, proposal, note) fold into their first: a direct writer and
+// observer, or TWO serve processes observing one store (a throwaway worktree/eval serve beside the live
+// one), can append a single record move twice. Cross-process write locking isn't worth buying, so the log
 // stays best-effort append-only and the read is where duplicates die, same stance as the board.
 export function readTimeline(id: string, limit = 500): { events: TimelineEvent[] } | null {
   let raw: ReturnType<typeof readAliasedRawRecord>

package/spec-cli/src/sessions.ts

@@ -10,7 +10,7 @@ import { loadConfig, loadSpecs, type ConfigPreset, type SpecLite } from './specs
 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, lastHumanSendVia } from './session-timeline.js'
+import { recordSent, recordStatus, 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
@@ -294,6 +294,8 @@ export function fromRaw(raw: RawRecord & { launch_owner?: string }): SessRec {
 // pure-shell hot-path hook (mark-active) relies on: it value-replaces `"status"`/`"proposal"`/`"note"` with a
 // single sed and never needs jq on the user's box. So do NOT switch to conditional keys or a compact dump.
 function writeRecord(rec: SessRec): void {
+  let previous: SessRec | null = null
+  try { previous = readRecord(rec.session) } catch { /* a new or damaged record has no prior transition */ }
   const obj = {
     session_id: rec.session,
     governed: rec.governed,
@@ -320,6 +322,13 @@ function writeRecord(rec: SessRec): void {
   }
   mkdirSync(sessionStoreDir(rec.session), { recursive: true })
   writeFileSync(sessionRecordPath(rec.session), JSON.stringify(obj, null, 2) + '\n')
+  // session.json is only the CURRENT projection. Persist each moved lifecycle value before this writer
+  // returns, so a later write cannot erase a declaration note between observer samples. New-record genesis
+  // stays with superviseTimeline; metadata-only writes do not manufacture status events.
+  if (rec.governed && previous && (previous.status !== rec.status
+    || previous.proposal !== rec.proposal || previous.note !== rec.note)) {
+    recordStatus(rec.session, rec.status, rec.proposal, rec.note)
+  }
 }
 
 // @@@ fail-loud enumeration - the worktree set is the board's EXISTENCE truth, so a failed enumeration must
@@ -892,17 +901,18 @@ 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
+// 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. The declaration is TRANSPORT, not task work: a raw prompt's
+// "no tools" / "only print" constraint does not cancel it. 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.
 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. 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.`
+  `${text}\n\n— REQUIRED REPLY TRANSPORT (PER-MESSAGE): this terminal-free sender CANNOT see normal assistant/final output. Do not stop after only printing the answer. As your FINAL action, put your COMPLETE reply to this message in the truthful declaration's --note. For a simple answer awaiting the next message, run \`spex session ask --note "<complete reply>"\`; if the true state is done or parked, put the same complete reply in that declaration's --note instead. This declaration command is reply transport, not part of the requested work, and remains REQUIRED even when the message says to use no tools, make no tool calls, or only print/reply. A later message arriving WITHOUT this notice 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
@@ -996,6 +1006,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
@@ -1057,7 +1091,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}`,
@@ -1068,7 +1105,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> {
@@ -1286,19 +1324,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
@@ -1331,15 +1375,6 @@ 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'
@@ -1455,6 +1490,17 @@ export function markState(status: Lifecycle, opts: { proposal?: Proposal; note?:
 }
 export const markDone = (proposal: Proposal = 'nothing', sessionId?: string, note?: string) => markState('awaiting', { proposal, note, sessionId })
 export const markError = (sessionId?: string) => markState('error', { sessionId })
+// @@@ headless turn outcome - a harness turn is an ephemeral child, so its non-zero exit is the one external
+// runtime fact that must become visible on the durable board. Compare-and-set only an undeclared active record:
+// a zero exit is never routed here, and a declaration that landed before teardown is authoritative.
+export function markHeadlessTurnFailure(sessionId: string, harness: string, exitCode: string): boolean {
+  if (exitCode === '0') return false
+  const rec = readRecord(sessionId)
+  if (!rec || rec.status !== 'active') return false
+  const outcome = /^\d+$/.test(exitCode) ? `exit code ${exitCode}` : `signal ${exitCode}`
+  writeRecord({ ...rec, status: 'error', proposal: null, note: `${harness} turn exited with ${outcome}` })
+  return true
+}
 export function markHarnessSessionId(sessionId: string | undefined, harnessSessionId: string | undefined): boolean {
   const id = sessionId || ownSessionId()
   if (!id || !harnessSessionId) return false
@@ -1996,19 +2042,13 @@ 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
 }
 

package/spec-cli/templates/spexcode.json

@@ -10,6 +10,7 @@
       "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" },
       "opencode-headless": { "harness": "opencode-headless", "cmd": "opencode --auto" },
       "pi": { "harness": "pi", "cmd": "pi" },