spexcode 0.5.0 → 0.5.1

package/README.md

@@ -82,7 +82,7 @@ Requires Node ≥ 22 and git. This part is plain tooling — no AI involved yet.
 ```sh
 npm i -g spexcode                              # installs the `spex` command
 cd your-repo
-spex init --harness claude,codex,opencode,pi,claude-headless,opencode-headless,pi-headless   # seeds .spec/, installs hooks, materializes the agent contracts
+spex init --harness claude,codex,opencode,pi,claude-headless,opencode-headless,pi-headless,codex-headless   # seeds .spec/, installs hooks, materializes the agent contracts
 ```
 
 That's the whole adoption. The example lists all the built-in harnesses — remove the ones you don't

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spexcode",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "type": "module",
   "description": "SpexCode — a spec-driven, self-developing dev tool. The `spex` CLI + spec server reads the .spec tree and its git history, and serves the dashboard.",
   "license": "MIT",
@@ -39,7 +39,7 @@
     "@hono/node-server": "^1.13.7",
     "@hono/node-ws": "^1.0.4",
     "hono": "^4.6.14",
-    "node-pty": "^1.1.0",
+    "node-pty": "1.2.0-beta.14",
     "tsx": "^4.19.2"
   },
   "devDependencies": {

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

@@ -0,0 +1,13 @@
+import { codexLaunchCommand } from './harness.js'
+
+// Codex headless keeps the existing app-server bootstrap and backend-owned thread/start + first turn, but
+// deliberately omits the final interactive `--remote … resume` attach. The shared app-server remains the
+// durable home for the thread; follow-up delivery uses codexHarness' existing JSON-RPC transport.
+export function codexHeadlessLaunchCommand(
+  id: string,
+  codexCmd = 'codex',
+  serverCmd?: string,
+  dir?: string,
+): string {
+  return codexLaunchCommand(id, codexCmd, serverCmd, dir, false)
+}

package/spec-cli/src/guide.ts

@@ -14,7 +14,7 @@ the rest, you don't hand-author the spec tree or wire the dashboard yourself.
    startup commands.)
 
 2. Adopt a repo
-     cd <your-repo> && spex init --harness claude,codex,opencode,pi,claude-headless,opencode-headless,pi-headless   # seeds .spec/ + git hooks (additive, never overwrites)
+     cd <your-repo> && spex init --harness claude,codex,opencode,pi,claude-headless,opencode-headless,pi-headless,codex-headless   # seeds .spec/ + git hooks (additive, never overwrites)
    --harness is required and has no default — the explicit choice of which harness(es) materialize
    delivers into. The example lists every built-in; drop the ones you don't use (any one id or
    comma-separated subset is valid).
@@ -333,18 +333,19 @@ harness the adopter SELECTED (--harness), from the template pool
   "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" }
   "pi-headless" → { "harness": "pi-headless", "cmd": "pi" }
-The interactive profiles preserve each harness's normal permission model. \`opencode-headless\` is the one
-deliberate seed exception: its terminal-free run requires \`opencode --auto\`; interactive \`opencode\` stays
-plain. Other automatic-permission commands are NEVER clean-init defaults: define and select one explicitly
-only when that access is intended. To run workers under an auth
+The interactive profiles preserve each harness's normal permission model. \`opencode-headless\` and
+\`codex-headless\` are deliberate seed exceptions: their terminal-free runs require \`opencode --auto\` and
+\`codex --yolo\`; interactive profiles stay plain. Other automatic-permission commands are NEVER clean-init
+defaults: define and select one explicitly only when that access is intended. To run workers under an auth
 wrapper (e.g. reclaude), point a launcher's \`cmd\` at it in spexcode.local.json — there is no environment
 override that rewrites a launcher's command. Add more profiles when a project needs named auth/config-dir or
 permission variants. Shape:
-  "launchers": { "<name>": { "harness": "claude" | "codex" | "opencode" | "pi" | "claude-headless" | "opencode-headless" | "pi-headless",
+  "launchers": { "<name>": { "harness": "claude" | "codex" | "opencode" | "pi" | "claude-headless" | "codex-headless" | "opencode-headless" | "pi-headless",
                              "cmd": "<launch command>" } }
 \`harness\` defaults to "claude"; \`cmd\` is required and embedded whole. A portable plain command may live
 in committed spexcode.json (as the init seeds do). A host-specific command — an absolute wrapper path,
@@ -453,7 +454,7 @@ Example — tune opt-in health diagnosis without changing the lint gate:
   preset      the SELECTED init preset — which cumulative .plugins tier \`spex init\` seeds (default
               'default'; seed-time only, read by init.ts).
   harnesses   which harness targets \`spex materialize\` delivers into — native ids
-              ("claude"|"codex"|"opencode"|"pi"|"claude-headless"|"opencode-headless"|"pi-headless") or a
+              ("claude"|"codex"|"opencode"|"pi"|"claude-headless"|"codex-headless"|"opencode-headless"|"pi-headless") or a
               { "plugin": "<folder>" } bundle. REQUIRED — there is no default set: \`spex init --harness\`
               stamps the explicit choice, and a missing field fails materialize loud. PERSISTENT and
               git-transactional: the edit takes effect at the next git-native materialize anchor (the commit

package/spec-cli/src/harness.ts

@@ -10,6 +10,7 @@ import { claudeSlashCommands, codexSlashCommands, opencodeSlashCommands, piSlash
 import { OPENCODE_EVENTS, opencodePluginSource } from './opencode.js'
 import { piExtensionSource, writePiTrust, removePiTrust } from './pi-harness.js'
 import { claudeHeadlessLaunchCommand, claudeHeadlessSock, deliverViaClaudeHeadless, interruptClaudeHeadless } from './claude-headless.js'
+import { codexHeadlessLaunchCommand } from './codex-headless.js'
 import { opencodeHeadlessLaunchCommand, spawnOpenCodeHeadlessTurn } from './opencode-headless.js'
 import { piHeadlessLaunchCommand, piHeadlessSock, deliverViaPiHeadless } from './pi-headless.js'
 import { runtimeRoot, mainCheckout, readConfig } from './layout.js'
@@ -27,7 +28,7 @@ import { git } from './git.js'
 // payload shape. On the TS side the harness is derived from the selected launcher or ALL adapters at once
 // (materialize writes every harness's artifacts).
 
-export type HarnessId = 'claude' | 'codex' | 'opencode' | 'pi' | 'claude-headless' | 'opencode-headless' | 'pi-headless'
+export type HarnessId = 'claude' | 'codex' | 'opencode' | 'pi' | 'claude-headless' | 'codex-headless' | 'opencode-headless' | 'pi-headless'
 export type HarnessLivenessRecord = { session: string; harnessSessionId?: string | null }
 // the per-pane runtime probe the caller snapshots ONCE for the whole session list and hands liveness():
 // the pane's root pid (tmux `#{pane_pid}`), the hot-tier `pidAlive` verdict, and — ONLY on the legacy path —
@@ -47,6 +48,9 @@ export interface Harness {
   // whether this harness runs without an interactive TUI. The dashboard launcher picker hides headless
   // adapters by default ([[launcher-visibility]]); CLI launcher resolution never consumes that policy.
   readonly headless: boolean
+  // whether the launch command intentionally exits after its first turn instead of owning a resident process.
+  // One-shot adapters must not be mistaken for a failed fast boot and retried with a duplicate prompt.
+  readonly launchOneShot?: boolean
   // whether this harness persists a native event stream that the console may expose as an optional
   // full-process drill-down ([[message-stream]]). This is adapter data, never a harness-id branch in UI.
   readonly messageStream: boolean
@@ -446,7 +450,7 @@ export function codexSupportsBypassHookTrust(binary: string): boolean {
   bypassProbe.set(binary, ok)
   return ok
 }
-export function codexLaunchCommand(_id: string, codexCmd = 'codex', serverCmd?: string, dir = runtimeRoot()): string {
+export function codexLaunchCommand(_id: string, codexCmd = 'codex', serverCmd?: string, dir = runtimeRoot(), attachTui = true): string {
   const server = process.env.SPEXCODE_CODEX_SERVER_CMD || serverCmd || codexBinary(codexCmd)
   // The bypass flag ONLY reaches a thread's hook trust as a per-request `config` override, NOT as a CLI flag on
   // the shared `app-server` process (the app-server never reads its own `--dangerously-bypass-hook-trust` for a
@@ -516,11 +520,17 @@ export function codexLaunchCommand(_id: string, codexCmd = 'codex', serverCmd?:
     // rollout has landed (resume-ready), so a fail-loud (empty output / non-zero) must ABORT — never `resume ""`.
     `if [ "$1" = "--resume" ]; then`,
     `  tid=$2`,
+    ...(attachTui ? [] : [
+      // A headless forced reopen has no TUI to attach and the shared app-server already owns the thread. Keep it
+      // a no-op instead of calling codex-launch without a prompt (which would mint an unrelated empty thread).
+      `elif [ "$#" -eq 0 ]; then`,
+      `  exit 0`,
+    ]),
     `else`,
     `  tid=$(${SPEX} internal codex-launch "$sock" "$PWD" "$@") || exit 1`,
     `fi`,
     `[ -n "$tid" ] || { echo "[spex] codex-launch produced no resumable thread" >&2; exit 1; }`,
-    `exec ${codexCmd}${tuiBypass} --remote unix://"$sock" resume "$tid"`,
+    ...(attachTui ? [`exec ${codexCmd}${tuiBypass} --remote unix://"$sock" resume "$tid"`] : []),
   ].join('\n')
   return `bash -lc ${shQuote(script)} spexcode-codex`
 }
@@ -1230,6 +1240,24 @@ export const codexHarness: Harness = {
   resumeArg: (rec) => (rec.harnessSessionId ? `--resume ${rec.harnessSessionId}` : ''),
 }
 
+// Codex headless is an independent adapter: its materialization and app-server delivery are exactly Codex's,
+// while launch only runs the backend-owned thread/start + first turn. There is no TUI to attach after that turn;
+// the shared project app-server keeps the thread addressable and idle sends use the inherited JSON-RPC channel.
+export const codexHeadlessHarness: Harness = {
+  ...codexHarness,
+  id: 'codex-headless',
+  headless: true,
+  launchOneShot: true,
+  messageStream: false,
+  launchCmd: (id, runtimeDir, cmd) => codexHeadlessLaunchCommand(id, codexBaseCmd(cmd), undefined, runtimeDir ?? runtimeRoot()),
+  // Record-backed liveness is the family contract for sleeping headless threads. A broken app-server or missing
+  // thread is surfaced by the inherited delivery call rather than converted into a speculative offline state.
+  liveness: () => 'online',
+  // There is no TUI to restart and the project app-server keeps the thread addressable. A forced reopen therefore
+  // runs the headless launch's empty-tail no-op; normal resume remains guarded by record-backed online liveness.
+  resumeArg: () => '',
+}
+
 // @@@ piHarness - the pi adapter (@earendil-works/pi-coding-agent). pi is the CLOSEST to claude of the four:
 // the caller pins the session id at launch (`--session-id <id>`, creating the session if missing), the shim
 // lives IN the worktree, and the rendezvous prompt/liveness channel is REUSED wholesale — pi has no external
@@ -1367,7 +1395,7 @@ export const opencodeHeadlessHarness: Harness = {
 }
 
 // every adapter — materialize iterates this to write each harness's artifacts in one pass.
-export const HARNESSES: readonly Harness[] = [claudeHarness, codexHarness, opencodeHarness, piHarness, claudeHeadlessHarness, opencodeHeadlessHarness, piHeadlessHarness]
+export const HARNESSES: readonly Harness[] = [claudeHarness, codexHarness, opencodeHarness, piHarness, claudeHeadlessHarness, opencodeHeadlessHarness, piHeadlessHarness, codexHeadlessHarness]
 
 // the legacy/default adapter for old records and config defaults. New launches derive harness from a launcher.
 export const defaultHarness: Harness = claudeHarness

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

@@ -892,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.
@@ -996,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
@@ -1057,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}`,
@@ -1068,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> {
@@ -1286,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
@@ -1331,15 +1365,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'
@@ -1996,19 +2021,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" },