spexcode 0.5.1 → 0.5.2

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

@@ -8,20 +8,19 @@ 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
+// 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,
@@ -40,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)
@@ -90,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)
@@ -144,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
@@ -894,15 +903,16 @@ export function withSenderHint(text: string, sender: MsgSender | null): string {
 }
 // @@@ 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
+// 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
@@ -1480,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