spexcode 0.5.2 → 0.5.3

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

@@ -0,0 +1,63 @@
+import { createConnection, type Socket } from 'node:net'
+import type { DispatchResult } from './harness.js'
+
+export type ControlRequestLabel = {
+  name: string
+  session: string
+  timeoutMs: number
+  rejected: string
+}
+
+export 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) },
+    )
+  })
+}
+
+export function controlRequest(
+  sockPath: string,
+  request: object,
+  label: ControlRequestLabel,
+): Promise<DispatchResult> {
+  return new Promise((resolve) => {
+    let socket: Socket | undefined
+    let buffer = ''
+    let settled = false
+    const finish = (result: DispatchResult) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      socket?.destroy()
+      resolve(result)
+    }
+    const timer = setTimeout(
+      () => finish({ ok: false, error: `${label.name} control timed out for session ${label.session}` }),
+      label.timeoutMs,
+    )
+    try {
+      socket = createConnection(sockPath)
+    } catch (error) {
+      finish({ ok: false, error: `${label.name} controller connect failed for session ${label.session}: ${(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 || label.rejected })
+      } catch (error) {
+        finish({ ok: false, error: `${label.name} returned an invalid control response: ${(error as Error).message}` })
+      }
+    })
+    socket.on('error', (error) => finish({ ok: false, error: `${label.name} controller unreachable for session ${label.session}: ${error.message}` }))
+    socket.on('close', () => finish({ ok: false, error: `${label.name} controller closed before confirming session ${label.session}` }))
+  })
+}

package/spec-cli/src/help.ts

@@ -29,6 +29,97 @@ const MENTION_NOTE = `Mentions: @session · [[node]] · @new / @new:<launcher> w
 text passed as a CLI arg included. [[node]] names the topic node; @session hands the text to that live agent;
 @new spawns a fresh worker on the thread's node (bare = configured default; :<launcher> = that named profile).`
 
+type SessionVerbNote = 'selector' | 'project-bound'
+type SessionVerbHelp = readonly [usage: string | readonly string[], detail: string, notes?: readonly SessionVerbNote[]]
+
+// One definition feeds both the complete session drawer and exact `session <verb> --help` projections.
+// Keeping the behavioral prose here prevents a compact probe from becoming a second, drifting manual.
+function sessionHelpDefinitions(): Record<string, SessionVerbHelp> {
+  return {
+    new: ['spex session new "<prompt>" [--prompt-file <path>|-] [--launcher <name>]',
+      `Launch a worker in its own node worktree. The materialized system contract reaches it
+automatically; the prompt supplies the task context. Its first [[id]] mention binds the
+session to that node. --prompt-file <path>|- carries a long prompt without shell quoting
+(exclusive with the inline prompt). The successful receipt names what to read, monitor, and reply on.`],
+    ls: ['spex session ls [SEL…] [--status a,b] [--all] [--json]',
+      'One-shot table of living sessions. Shelved sessions ([[archive]]) are hidden; --all includes them, and naming one explicitly always shows it.', ['selector']],
+    resources: ['spex session resources [--json]', 'Read-only host/process ownership, budgets, shared refs, and findings.'],
+    watch: ['spex session watch [SEL…] [--as NAME] [--idle] [--interval N=5]',
+      'Streams lifecycle transitions and blocks until killed; `session wait` is the one-shot alternative.', ['selector']],
+    wait: ['spex session wait <SEL> [--timeout S=1200] [--interval S=2] [--idle]',
+      `EDGE-TRIGGERED wait on one session. Prints the current status immediately (stderr), then
+exits 0 only when it OBSERVES
+the session TRANSITION from a non-actionable status into an actionable one, printing the
+observed path on stdout (e.g. working→review — read the LAST token as the status reached).
+It NEVER returns just because the session is actionable ALREADY — for "what is it right NOW"
+use \`session ls\` / \`session review\` instead. --timeout is the guaranteed exit (code 1,
+observed path on stderr).`, ['selector']],
+    review: ['spex session review <SEL> [--json]', 'Reports ahead · uncommitted · proposal · gates · merge-base diff.', ['selector']],
+    merge: ['spex session merge <SEL>', 'Dispatches a gated merge to the session\'s own agent; it does not close the session.', ['selector', 'project-bound']],
+    send: [['spex session send <SEL> "<msg>"', 'spex session send <SEL> --keys "<keys>"'],
+      `Plain send delivers a message and fails loud when dispatch is dead. --keys is the LAST RESORT:
+raw nav-mode keystrokes to a TUI dialog ("Up Up Enter", C-/M-/S- combos). The raw key surface
+is UNSTABLE and can confirm dangerous dialogs — try a plain send first; use keys only when text
+provably cannot land.`, ['selector', 'project-bound']],
+    interrupt: ['spex session interrupt <SEL>', 'Hard-interrupt the current turn through native harness control.', ['selector', 'project-bound']],
+    rename: ['spex session rename <SEL> "<name>"', 'Set the display name; an empty name clears it.', ['selector', 'project-bound']],
+    show: ['spex session show <SEL> [--capture] [--json]', `The session record: status · node · branch · launcher · the full originating prompt.
+--capture prints the LIVE PANE as text instead (empty pane = exit 0; unknown session = exit 2).`, ['selector']],
+    resume: ['spex session resume <SEL> [--force]', 'Relaunch ONLY if confirmed offline; --force is for a wedged session.', ['selector', 'project-bound']],
+    stop: ['spex session stop <SEL>', 'Soft stop: kill the exact agent and KEEP the worktree resumable.', ['selector', 'project-bound']],
+    archive: ['spex session archive <SEL>', 'Cold-archive it: exact leaf/runtime stopped, worktree and conversation kept.', ['selector']],
+    unarchive: ['spex session unarchive <SEL>', 'Deprecated compatibility spelling: same behavior as resume, relaunching the same conversation.', ['selector']],
+    close: ['spex session close <SEL>', 'Retire the session and its worktree.', ['selector', 'project-bound']],
+    maintain: [[
+      'spex session maintain --allow-stop <SEL> [--allow-resume <SEL>[:force]] … -- <command> [args…]',
+      'spex session maintain --status',
+    ], `Hold one project maintenance lease around a bounded operator command. Only the exact one-shot
+stop/resume plan is brokered; ordinary session writes stay closed. The bearer never prints or enters
+argv/environment. --status is the sanitized read-only lease view.`, ['selector', 'project-bound']],
+    done: ['spex session done --propose merge|nothing|close [--note T]', 'Declare your own work committed and stop.'],
+    park: ['spex session park --note <what-you-await>', 'Declare that a real background task will wake your own session.'],
+    ask: ['spex session ask --note <your-question>', 'Declare that your own session is stopped on the human and resumes on reply.'],
+    attach: ['spex session attach <SEL>', `Attaches the current terminal to the worker's tmux (detach: C-b d) and blocks until detached.
+LOCAL-only (fails loud on a remote backend); show --capture and send are non-interactive.`, ['selector']],
+  }
+}
+
+const SESSION_HELP_GROUPS = [
+  { title: 'Manager verbs (dispatch, monitor, land)', verbs: ['new', 'ls', 'resources', 'watch', 'wait', 'review', 'merge'] },
+  { title: 'Control another session', verbs: ['send', 'interrupt', 'rename', 'show', 'resume', 'stop', 'archive', 'unarchive', 'close', 'maintain'] },
+  { title: 'Worker verbs (declare YOUR OWN state — a claim the graph and your supervisor act on)', verbs: ['done', 'park', 'ask'] },
+  { title: 'Human escape hatch', verbs: ['attach'] },
+] as const
+
+const SESSION_WRITE_NOTE = `Manager verbs that WRITE (send/interrupt/rename/resume/stop/close/maintain/merge) are PROJECT-BOUND: a backend serving
+another project's repo refuses loudly — name the target with --api <url> to drive it on purpose.`
+
+function indent(text: string, spaces: number): string {
+  const prefix = ' '.repeat(spaces)
+  return text.split('\n').map((line) => `${prefix}${line}`).join('\n')
+}
+
+function sessionDrawerHelp(): string {
+  const definitions = sessionHelpDefinitions()
+  const groups = SESSION_HELP_GROUPS.map(({ title, verbs }) => `${title}:\n${verbs.map((verb) => {
+    const [rawUsage, detail] = definitions[verb]
+    const usages = typeof rawUsage === 'string' ? [rawUsage] : rawUsage
+    return `${usages.map((usage) => `  ${usage}`).join('\n')}\n${indent(detail, 6)}`
+  }).join('\n')}`).join('\n\n')
+  return `${groups}\n\n${SEL_NOTE}\n${SESSION_WRITE_NOTE}\n${MENTION_NOTE}`
+}
+
+function sessionVerbHelp(verb: string): string | null {
+  const entry = sessionHelpDefinitions()[verb]
+  if (!entry) return null
+  const [rawUsage, detail, sharedNotes = []] = entry
+  const usages = typeof rawUsage === 'string' ? [rawUsage] : rawUsage
+  const notes = [detail]
+  if (sharedNotes.includes('selector')) notes.push(SEL_NOTE)
+  if (sharedNotes.includes('project-bound')) notes.push(SESSION_WRITE_NOTE)
+  return `${usages.map((line, index) => `${index === 0 ? 'Usage: ' : '       '}${line}`).join('\n')}\n\n${notes.join('\n\n')}`
+}
+
 const ENTRIES: Record<string, Entry> = {
   // ── project verbs (implicit object = this project) ────────────────────────
   graph: {
@@ -164,7 +255,7 @@ leaf id reused) · mention (a [[id]] naming no node). Warns: coverage · drift
 (UNANCHORED drift — always advisory, never blocks; on a scoped file's MISS, \`lint.scopedCodeMiss:
 "ignore"\` may silence it) · anchor (anchoring a type) · related-drift (a scoped related row warns
 per selector HIT, misses silent) · owners (whole-file governors only; scoped don't count) ·
-confusable-id (two leaf ids one edit apart). spec lint's errors BLOCK commits (the pre-commit shim; bypass SPEXCODE_SKIP_LINT=1);
+confusable-id (two leaf ids one edit apart). spec lint's errors BLOCK commits (the prepared reference hook; bypass SPEXCODE_SKIP_LINT=1);
 contrast \`spex eval lint\`, which is pure advisory and never blocks anyone.
 
 ack — stamp Spec-OK on HEAD (an empty stamp commit): the drift remedy when only MECHANICS changed
@@ -175,70 +266,18 @@ edit the spec instead — same commit as the code.`,
   },
   session: {
     line: 'session <verb>        the worktree state machine: new · ls · watch · wait · review · merge · send · …',
-    body: `Manager verbs (dispatch, monitor, land):
-  spex session new "<prompt>" [--prompt-file <path>|-] [--launcher <name>]
-      Launch a worker in its own node worktree. Give it ONLY its task — the dev-flow contract
-      reaches it through the materialized system prompt. The prompt's first [[id]] mention binds
-      the session to that node. --prompt-file <path>|- carries a long prompt
-      without shell quoting (exclusive with the inline prompt). Then MONITOR it (wait/watch below).
-  spex session ls [SEL…] [--status a,b] [--json]        one-shot table of living sessions
-  spex session watch [SEL…] [--as NAME] [--idle] [--interval N=5]
-      Streams lifecycle transitions until killed — it NEVER EXITS; the human's forever stream. An
-      agent must background it or use wait; blocking a turn on watch freezes you.
-  spex session wait <SEL> [--timeout S=1200] [--interval S=2] [--idle]
-      EDGE-TRIGGERED sleep on one session — ALWAYS run it in the BACKGROUND; its exit is your wake-up.
-      Prints the session's current status immediately (stderr), then exits 0 only when it OBSERVES
-      the session TRANSITION from a non-actionable status into an actionable one, printing the
-      observed path on stdout (e.g. working→review — read the LAST token as the status reached).
-      USE IT to sleep until a dispatched worker next needs you — including a dispatched MERGE
-      actually landing (review→working while the merge runs, then the edge back is your wake-up).
-      It NEVER returns just because the session is actionable ALREADY — for "what is it right NOW"
-      use \`session ls\` / \`session review\` instead. --timeout is the guaranteed exit (code 1,
-      observed path on stderr). Background one wait per worker.
-  spex session review <SEL> [--json]     the merge cockpit: ahead · uncommitted · proposal · gates ·
-                                         merge-base diff — decide from this, don't hand-run git
-  spex session merge <SEL>               gated merge, dispatched to the session's OWN agent; confirm
-                                         HEAD advanced before closing — closing unmerged discards work
-
-Control another session (all take SEL):
-  spex session send <SEL> "<msg>"        deliver a message (fail-loud: a dead dispatch exits non-zero)
-  spex session interrupt <SEL>           hard-interrupt the current turn through native harness control
-  spex session send <SEL> --keys "<keys>"
-      LAST RESORT: raw nav-mode keystrokes to a TUI dialog ("Up Up Enter", C-/M-/S- combos). The raw
-      key surface is UNSTABLE and can confirm dangerous dialogs — don't reach for it unless a plain
-      \`session send\` text provably cannot land.
-  spex session rename <SEL> "<name>"     set the display name ("" clears)
-  spex session show <SEL> [--capture] [--json]
-      The session record: status · node · branch · launcher · the full originating prompt.
-      --capture prints the LIVE PANE as text instead (empty pane = exit 0; unknown session = exit 2).
-  spex session resume <SEL> [--force]    relaunch ONLY if confirmed offline (--force for a wedged one)
-  spex session stop <SEL>                soft stop: kill the agent, KEEP the worktree (resumable)
-  spex session close <SEL>               retire the session and its worktree
-
-Worker verbs (declare YOUR OWN state — a claim the graph and your supervisor act on):
-  spex session done --propose merge|nothing|close [--note T]   committed and stopping
-  spex session park --note <what-you-await>                    a real background task will wake you
-  spex session ask  --note <your-question>                     stopped on the human; resumes on reply
-
-Human escape hatch:
-  spex session attach <SEL>              sit in the worker's REAL tmux (detach: C-b d). INTERACTIVE
-                                         AND BLOCKING — an agent must NEVER run it in a turn: use
-                                         show --capture / send. LOCAL-only (fails loud on a remote backend).
-
-${SEL_NOTE}
-Manager verbs that WRITE (send/interrupt/rename/resume/stop/close/merge) are PROJECT-BOUND: a backend serving
-another project's repo refuses loudly — name the target with --api <url> to drive it on purpose.
-${MENTION_NOTE}`,
+    body: sessionDrawerHelp(),
     see: 'spex eval ls --session <SEL> (the session’s measured loss) · spex help eval',
   },
   eval: {
-    line: 'eval <verb>           the measurement system: add · ls · scenario ls · matrix · lint · ok · retract · clean',
+    line: 'eval <verb>           the measurement system: add · ls · scenario ls/write · matrix · lint · ok · retract · clean',
     body: `Usage: spex eval add [<node>|.] [--scenario <name>] (--pass|--fail) [--note <text>]
                     [--image <png> …repeatable] [--result <path|->] [--video <webm|mp4>] [--timeline <json>]
        spex eval ls [<node>|.] [--json]                a node's eval timeline, newest first
        spex eval ls --session <SEL> [--json]           a session's aggregate: its changed nodes' scores
        spex eval ls --session <SEL> --export [--open | --out <path>]
-       spex eval scenario ls [<node>|.] [--unmeasured] [--json]   declared scenarios; bare = every node
+       spex eval scenario ls [<node>|.] [--unmeasured] [--json]   declared scenarios; JSON = canonical index
+       spex eval scenario write --mutation <json> < eval.md       propose one canonical metadata mutation
        spex eval matrix <launcher> [--node <id>] [--rows k1,k2]   the harness live-behavior matrix
        spex eval lint [--changed]                      measurement-layer findings (advisory, always exit 0)
        spex eval ok <node> [--scenario <name>]         the HUMAN sign-off on the scenario's latest measurement
@@ -251,12 +290,17 @@ the behaviour: MOVING/timed behaviour records a --video; a STATIC end state scre
 backend/CLI files a --result transcript. A fix's evidence is a fail→pass pair on the SAME scenario.
 
 ls — node-scoped bare (its per-scenario eval history); session-scoped with an EXPLICIT --session
-(never type-sniffed): every node the session's diff touches, blind spots first, its OWN measurements
-✦-marked ahead of the inherited baseline. --export writes that evaluation as ONE self-contained
+(never type-sniffed): filed evals are newest-first across nodes and source ownership; own measurements
+are ✦-marked, evals filed by other sessions are unmarked, and blind spots follow measured rows. --export writes ONE self-contained
 HTML artifact (diff · evidence inlined · gates) for CI/sharing.
 
-scenario ls — the DECLARED contracts (name · tags · normalized test reference · latest verdict), no evals: bare lists every
-measurable node's scenarios; --unmeasured keeps only the never-measured — the blind-spot worklist.
+scenario ls — the DECLARED contracts, no evals: text may show the latest verdict and --unmeasured is its blind-spot
+worklist; --json emits the complete canonical semantic/measurement index with stable hashes and fixed-tree provenance
+(--unmeasured is text-only because the JSON projection never reads the eval sidecar).
+
+scenario write — the fixed-tree declaration writer for an external measurement guard: stdin is the authoritative
+eval.md, --mutation is one closed JSON insert/delete request for one scenario's test metadata, and stdout is only
+the proposed eval.md bytes. It reads no worktree or runner and fails without stdout on malformed or ambiguous input.
 
 matrix — run the eight-row harness live-behavior matrix against a REAL dispatched session of the named
 launcher (the harness-adapter acceptance rule, defined once in spec-eval/src/matrix.ts): it syncs the
@@ -359,6 +403,7 @@ Machine plumbing — called by generated hooks and launch scripts, never typed b
   session-idle  --session <id>        the idle-prompt hook marks an active session idle
   commit-gate       the Stop gate's deterministic commit check (exit 0 = ready to declare done)
   nudge <node>      the post-merge hook prints the issue nudge for a merged node
+  shared-runtime-spawn <cwd> <log> <pid> <scope> <cmd> [args…]  detached adapter control plane (launch script)
   codex-launch <sock> <cwd> [prompt…]   backend-owned codex thread/start + first turn (launch script)
   codex-turn   <sock> <threadId> <text…>  fire a follow-up turn on an owned thread (tests/scripts)
   claude-headless-run <id> <runtime> <cmd> -- <tail…>  resident stream-json controller (launch script)
@@ -377,9 +422,13 @@ your own state is declared with spex session done|park|ask.`,
   },
 }
 
-// `spex <cmd> --help` must meet the user wherever they typed it: cli.ts intercepts the probe pre-verb and
-// asks for the FIRST token's entry, so `spex session send --help` answers with the session drawer's entry.
-export function commandHelp(name: string): string | null {
+// `spex <cmd> --help` must meet the user wherever they typed it: cli.ts intercepts the probe pre-verb.
+// Session's noun-verb shape gets one extra projection; a bare noun still returns the complete drawer.
+export function commandHelp(name: string, verb?: string): string | null {
+  if (name === 'session' && verb) {
+    const exact = sessionVerbHelp(verb)
+    if (exact) return `${exact}\n\nsee also: spex session (the complete drawer)\n\nmap: spex help · skills: spex guide`
+  }
   const e = ENTRIES[name]
   if (!e) return null
   const oneLiner = e.line.replace(/^\S+(\s+\S+)*?\s{2,}/, '')   // the map line minus its "cmd args" column
@@ -387,6 +436,13 @@ export function commandHelp(name: string): string | null {
   return `${header}${e.body}${e.see ? `\n\nsee also: ${e.see}` : ''}\n\nmap: spex help · skills: spex guide`
 }
 
+export function sessionLaunchReceipt(id: string): string {
+  return `spex: launched session ${id}
+  current result: the session JSON is on stdout now; \`spex session ls ${id}\` is the later one-shot snapshot
+  next lifecycle change: background \`spex session wait ${id}\` (edge-triggered; exits on the next non-actionable→actionable transition); \`spex session watch ${id}\` streams and NEVER EXITS
+  response channel: \`spex session send ${id} "<msg>"\`; \`send --keys\` is an UNSTABLE LAST RESORT after a plain send cannot land`
+}
+
 export function overviewHelp(): string {
   return `spex — SpexCode CLI (spec↔code graph + worktree session state machine)