spexcode 0.6.1 → 0.6.5

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

@@ -1,91 +0,0 @@
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
-import { join } from 'node:path'
-import { sessionArtifactPath, sessionStoreDir } from './layout.js'
-import type { TimelineEvent } from './session-timeline.js'
-
-// @@@ session-cursors - a reader's durable place in a log. One `cursors.json` per session in its global store
-// dir: `follows` holds one entry per followed session, including the reader's own id when it watches its own
-// log. A position is an event INDEX into timeline.ndjson (lines already consumed), so it is also the index of
-// the next unread event. A position is NOT a work list: what a session still owes its agent is a debt, and it
-// lives in its own queue ([[delivery-queue]]). Binding both to one counter is what made a session's own status
-// lines get consumed as though they were mail, and made "anything outstanding?" a scan of all history.
-
-export type Cursors = { version: 1; follows: Record<string, number> }
-
-const cursorsPath = (id: string): string => sessionArtifactPath(id, 'cursors.json')
-const at = (v: unknown): number => (typeof v === 'number' && Number.isFinite(v) && v > 0 ? Math.floor(v) : 0)
-
-// Never throws: a missing, empty, or unparseable file reads as "nothing consumed", because re-showing a
-// message is the honest recovery for a lost position and skipping one is not. Followed entries whose target
-// store dir is gone are dropped here — expiry is this read, and the next write persists it.
-export function readCursors(id: string): Cursors {
-  let raw: { follows?: unknown } | null = null
-  try { raw = JSON.parse(readFileSync(cursorsPath(id), 'utf8')) } catch { /* no cursors yet */ }
-  const follows: Record<string, number> = {}
-  const stored = raw?.follows
-  if (stored && typeof stored === 'object') {
-    for (const [target, pos] of Object.entries(stored as Record<string, unknown>)) {
-      if (!target || !existsSync(sessionStoreDir(target))) continue
-      follows[target] = at(pos)
-    }
-  }
-  return { version: 1, follows }
-}
-
-// Written whole and atomically, one field per line — the same shape as the session record, so a position stays
-// readable by an exact whole-line match where a value regex would not be.
-function writeCursors(id: string, cursors: Cursors): void {
-  const dir = sessionStoreDir(id)
-  mkdirSync(dir, { recursive: true })
-  const tmp = join(dir, `.cursors.json.${process.pid}.tmp`)
-  writeFileSync(tmp, JSON.stringify(cursors, null, 2) + '\n')
-  renameSync(tmp, cursorsPath(id))
-}
-
-export const followCursor = (id: string, target: string): number | null => {
-  const stored = readCursors(id).follows[target]
-  return stored === undefined ? null : stored
-}
-
-// Start or advance a follow. Following IS this entry existing, so the first call registers the relationship.
-// Monotonic: a stale read can leave a position too low (an event read twice), never too high (one lost).
-export function advanceFollow(id: string, target: string, to: number): void {
-  const cursors = readCursors(id)
-  const stored = cursors.follows[target]
-  if (stored !== undefined && to <= stored) return
-  writeCursors(id, { ...cursors, follows: { ...cursors.follows, [target]: Math.max(0, Math.floor(to)) } })
-}
-
-export const followedSessions = (id: string): string[] => Object.keys(readCursors(id).follows)
-
-const sameStatus = (a: TimelineEvent, b: TimelineEvent): boolean =>
-  a.kind === 'status' && b.kind === 'status' && a.status === b.status
-  && (a.proposal ?? null) === (b.proposal ?? null) && (a.note ?? null) === (b.note ?? null)
-
-// @@@ edges, not lines - what a reader has not yet seen, with repeated status lines dropped. X→X IS NOT A
-// TRANSITION: the log is append-only and already holds runs of identical status lines from before the
-// timeline observer was deleted (every stray `spex serve` process ran an fs.watch over the same store and
-// re-recorded each real move, so ONE transition landed as up to 6 lines within ~200ms). Those bytes are
-// history and stay. Any consumer that decides "did it move?" must therefore compare VALUES, never adjacency,
-// and must compare against the last status the reader ALREADY saw — otherwise a duplicate straddling the
-// cursor boundary reads as a fresh move on the very next tick. `next` is where the cursor goes after consuming
-// the WHOLE slice: the full length, because a dropped duplicate is still consumed. `at[i]` is the absolute
-// index of `events[i]`, which is what lets a reader that STOPS on one event ([[session-follow]]'s take-one
-// wait) advance to exactly `at[i] + 1` and leave the lines behind it unread for the next reader.
-export function unreadSince(events: TimelineEvent[], from: number): { events: TimelineEvent[]; at: number[]; next: number } {
-  const start = Math.min(Math.max(0, Math.floor(from)), events.length)
-  let prev: TimelineEvent | null = null
-  for (let i = start - 1; i >= 0; i--) if (events[i].kind === 'status') { prev = events[i]; break }
-  const out: TimelineEvent[] = []
-  const at: number[] = []
-  for (let i = start; i < events.length; i++) {
-    const e = events[i]
-    if (e.kind === 'status') {
-      if (prev && sameStatus(prev, e)) continue
-      prev = e
-    }
-    out.push(e)
-    at.push(i)
-  }
-  return { events: out, at, next: events.length }
-}

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

@@ -1,182 +0,0 @@
-import { existsSync } from 'node:fs'
-import { sessionStoreDir } from './layout.js'
-import { advanceFollow, followCursor, unreadSince } from './session-cursors.js'
-import { timelineDisplay, timelineEvents, timelineStamp } from './session-timeline.js'
-import { sessionLabel, type DisplayStatus, type Session } from './sessions.js'
-
-// @@@ session-follow - supervision is FOLLOWING a log past a cursor, never polling a derived board. One tick
-// costs ONE stat per target: if timeline.ndjson has not grown, nothing is opened and nothing is parsed. No
-// call here reaches the backend, a rendezvous socket, or tmux, which is the whole point — M followers over N
-// sessions cost the control plane zero, where the old poll cost one board build (a connect + a tmux spawn per
-// live session) per follower per interval.
-
-// Actionable = a state whose arrival means "a human/supervisor must now act". `offline` is deliberately ABSENT
-// where the old poll had it: liveness is a present-tense probe derivation, never authored, so it can never
-// appear on a log ([[state]]). A follower learns what a session DECLARED and never that it died.
-const ACTIONABLE = new Set<DisplayStatus>(['review', 'done', 'close-pending', 'error', 'asking'])
-const NEXT: Record<string, string> = {
-  review: 'merge | close',
-  done: 'merge | close',
-  'close-pending': 'close',
-  error: 'resume (relaunch & retry) | show --capture | close',
-  asking: 'send "<msg>" | show --capture',
-  idle: 'send "<msg>" | show --capture',
-  queued: 'waiting for a free slot — starts automatically | close',
-}
-const trunc = (s: string, n: number): string => (s.length <= n ? s : `${s.slice(0, n - 1)}…`)
-
-export function sessionEvent(s: Session): string {
-  const note = s.note ? ` — note: ${s.note}` : ''
-  const asked = s.promptPreview ? ` · asked: ${s.promptPreview}` : ''
-  return `[spex] ${s.status} · ${sessionLabel(s)} — act: ${NEXT[s.status] || '—'}${note}${asked}  [id ${s.id}]`
-}
-// @@@ launchEvent - a session's FIRST sighting, emitted once per id whatever its status, so the stream is a
-// complete lifecycle feed: launched → [transitions] → closed. A launch's own first line is `active` (not
-// actionable), so without this the feed would be blind to new sessions starting.
-export function launchEvent(s: Session): string {
-  const note = s.note ? ` — note: ${s.note}` : ''
-  const asked = s.promptPreview ? ` · asked: ${s.promptPreview}` : ''
-  return `[spex] launched · ${sessionLabel(s)} — act: capture | send "<msg>"${note}${asked}  [id ${s.id}]`
-}
-
-// `targets` is re-read every tick so a BROAD follow picks up sessions that launch while it runs; an explicit
-// selector resolves once and hands back a fixed list. `self` is the follower's own session: its inbox rides the
-// same follow, and it is where the durable cursors live — a follower with no session record (a human shell)
-// keeps them in memory for the life of the process.
-export type FollowOpts = {
-  targets: () => string[]
-  self?: string | null
-  statuses?: string[]
-  includeIdle?: boolean
-  intervalMs?: number
-  as?: string
-  take?: boolean
-  timeoutMs?: number
-  onObserved?: (id: string, status: DisplayStatus, previous: DisplayStatus | null) => void
-  row?: (id: string, status: DisplayStatus, note: string | null) => Session | null
-}
-// Only `take` mode (what `spex session wait` runs) resolves; a stream follow never returns. There is no
-// transport outcome, because there is no transport: following is reading a file, so the failure that once
-// needed its own vocabulary — a backend that could not be reached, misread as a session verdict — cannot occur.
-export type FollowOutcome =
-  | { reached: DisplayStatus; id: string; path: DisplayStatus[] }
-  | { mail: { from: string | null; text: string } }
-  | { timedOut: true; path: DisplayStatus[] }
-  | { gone: string }
-
-type FollowState = { pos: number; prev: DisplayStatus | null; path: DisplayStatus[]; stamp: string | null }
-
-export async function followSessions(emit: (line: string) => void, opts: FollowOpts): Promise<FollowOutcome> {
-  const { targets, self = null, statuses, includeIdle = false, intervalMs = 1000, as, take = false, timeoutMs = 1_200_000, onObserved, row } = opts
-  const tag = as ? `[${as}] ` : ''
-  const state = new Map<string, FollowState>()
-  const memo = new Map<string, number>()   // cursors for a follower that has no record of its own to store them in
-  const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms))
-  // the no-hang wall: a fixed deadline computed ONCE, checked before EVERY sleep below.
-  const deadline = take ? Date.now() + Math.max(1000, timeoutMs) : 0
-  const isActionable = (st: DisplayStatus) => ACTIONABLE.has(st) || (includeIdle && st === 'idle')
-  const passes = (st: DisplayStatus) => !statuses?.length || statuses.includes(st)
-  const anyPath = (): DisplayStatus[] => {
-    for (const f of state.values()) if (f.path.length) return f.path
-    return []
-  }
-  const readCursor = (id: string): number | null => (self ? followCursor(self, id) : memo.get(id) ?? null)
-  const writeCursor = (id: string, to: number): void => { if (self) advanceFollow(self, id, to); else memo.set(id, to) }
-  const line = (id: string, st: DisplayStatus, note: string | null, first: boolean): void => {
-    const s = row?.(id, st, note)
-    if (!s) return
-    if (first) emit(tag + launchEvent(s))
-    else if (passes(st) && isActionable(st)) emit(tag + sessionEvent(s))
-  }
-  let first = true
-  let shown = -1   // stream mode: the last inbox line this process printed (see the INBOX read below)
-
-  for (;;) {
-    const ids = targets()
-    const seen = new Set<string>()
-    for (const id of ids) {
-      if (id === self) continue   // the follower's own log is its INBOX, followed below on its own cursor rule
-      seen.add(id)
-      if (!existsSync(sessionStoreDir(id))) {
-        if (state.delete(id)) emit(`${tag}[spex] closed · removed  [id ${id}]`)
-        if (take) return { gone: id }
-        continue
-      }
-      let f = state.get(id)
-      if (!f) {
-        const evs = timelineEvents(id)
-        // A stored cursor always wins — that IS the resume, losing nothing across a follower's death. With
-        // none: a target already present when the follow started predates it, so we begin at the log's END
-        // (its history is not news); a target that appears on a LATER tick genuinely just launched, so its
-        // whole log is read from 0 and its `launched` line reaches the feed.
-        const pos = readCursor(id) ?? (first ? evs.length : 0)
-        // The ARRIVAL state is the last status line BEFORE the cursor — a fact on the log, not whatever a poll
-        // happened to catch. With no such line the first status we read is the arrival instead.
-        let prev: DisplayStatus | null = null
-        for (let i = Math.min(pos, evs.length) - 1; i >= 0; i--) {
-          const e = evs[i]
-          if (e.kind === 'status') { prev = timelineDisplay(e); break }
-        }
-        f = { pos, prev, path: prev ? [prev] : [], stamp: null }
-        state.set(id, f)
-        if (prev) { onObserved?.(id, prev, null); line(id, prev, null, true) }
-      }
-      const stamp = timelineStamp(id)
-      if (stamp !== null && stamp === f.stamp) continue   // THE cheap tick: nothing appended, nothing parsed
-      f.stamp = stamp
-      const evs = timelineEvents(id)
-      const slice = unreadSince(evs, f.pos)
-      let hit: FollowOutcome | null = null
-      for (let k = 0; k < slice.events.length && !hit; k++) {
-        const e = slice.events[k]
-        if (e.kind === 'sent') {
-          const s = row?.(id, f.prev ?? 'unknown', null)
-          if (s) emit(`${tag}[spex] message · ${sessionLabel(s)} — from ${e.from ?? 'human'}: ${trunc(e.text, 120)}  [id ${id}]`)
-          continue
-        }
-        const st = timelineDisplay(e)
-        const was = f.prev
-        f.prev = st
-        f.path.push(st)
-        onObserved?.(id, st, was)
-        line(id, st, e.note, was === null)
-        // THE edge: a previously-observed NON-actionable status moving INTO an actionable one. An actionable
-        // ARRIVAL (was === null) is not an edge — that standing level is what a level-triggered wait falsely
-        // returned on; nor is an actionable→actionable hop (review→done). The rise OUT of non-actionable is the
-        // one signal that means "the target needs you AGAIN". The previous state is the previous LINE, so two
-        // moves inside one tick are two edges rather than one collapsed sample.
-        if (take && was !== null && !isActionable(was) && isActionable(st)) hit = { reached: st, id, path: f.path }
-        // Consume exactly up to the event we stopped on, so the lines behind it stay unread for the next wait.
-        if (hit) { f.pos = slice.at[k] + 1; writeCursor(id, f.pos) }
-      }
-      if (hit) return hit
-      f.pos = slice.next
-      writeCursor(id, f.pos)
-    }
-    for (const id of [...state.keys()]) {
-      if (seen.has(id)) continue
-      state.delete(id)
-      emit(`${tag}[spex] closed · removed  [id ${id}]`)
-    }
-    // THE FOLLOWER'S OWN LOG — watched exactly like any other target, on its own entry in `cursors.json`. It is
-    // a WATCH, not a delivery: a message reaches the agent as a prompt through the adapter ([[delivery-queue]]),
-    // so this position only decides what THIS process has already reported and can never make an agent miss
-    // mail. Never advanced here in take mode — the waiter stops on the event and the next wait resumes on it.
-    if (self && existsSync(sessionStoreDir(self))) {
-      const mine = unreadSince(timelineEvents(self), followCursor(self, self) ?? 0)
-      for (let k = 0; k < mine.events.length; k++) {
-        const e = mine.events[k]
-        if (e.kind !== 'sent') continue
-        if (take) return { mail: { from: e.from, text: e.text } }
-        // a stream has no turn boundary to advance that cursor, so its own high-water mark — process-local,
-        // never written — is what keeps an unread line from being re-printed on every tick.
-        if (mine.at[k] <= shown) continue
-        shown = mine.at[k]
-        emit(`${tag}[spex] message · you — from ${e.from ?? 'human'}: ${trunc(e.text, 120)}  [id ${self}]`)
-      }
-    }
-    first = false
-    if (take && Date.now() >= deadline) return { timedOut: true, path: anyPath() }
-    await sleep(intervalMs)
-  }
-}

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

@@ -1,98 +0,0 @@
-import { randomUUID } from 'node:crypto'
-import { existsSync, readFileSync, appendFileSync, mkdirSync, statSync } from 'node:fs'
-import { sessionStoreDir, sessionArtifactPath, readAliasedRawRecord } from './layout.js'
-import type { Lifecycle, Proposal } from './sessions.js'
-
-// @@@ session-timeline - the session's append-only log in its global store dir: every authored-lifecycle
-// transition (status + proposal + the FULL note text) and every message addressed to it. It is what a
-// terminal-free surface renders as the conversation, and it is the DELIVERY itself — a message is delivered
-// when its bytes are in this file.
-//
-// There is exactly ONE writer path for the authored axis: every lifecycle hook shells to `spex internal
-// session-*`, the same TypeScript writer the CLI declarations use, so no move reaches session.json without
-// reaching this log. That is why there is no observer process, no repair tick, and no read-time folding of a
-// move recorded twice — nothing writes state behind this module's back.
-
-export type TimelineEvent =
-  | { ts: string; kind: 'status'; status: Lifecycle; proposal: Proposal | null; note: string | null; display?: string }
-  | { ts: string; kind: 'sent'; mid: string; text: string; from: string | null; replyVia?: 'note' }
-
-const timelinePath = (id: string): string => sessionArtifactPath(id, 'timeline.ndjson')
-
-function append(id: string, ev: TimelineEvent): void {
-  mkdirSync(sessionStoreDir(id), { recursive: true })
-  appendFileSync(timelinePath(id), JSON.stringify(ev) + '\n')
-}
-
-// 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. Best-effort: history is an accessory to the state machine, and failing to write it must never
-// break the transition that already happened.
-export function recordStatus(id: string, status: Lifecycle, proposal: Proposal | null, note: string | null): void {
-  try { append(id, { ts: new Date().toISOString(), kind: 'status', status, proposal, note }) }
-  catch { /* the record already moved; the history line is the only loss */ }
-}
-
-// The DELIVERY ([[dispatch]]): appending this line IS the send, so unlike a status line it must fail LOUD —
-// the caller reports the throw rather than a false success. `text` is the message BEFORE any mechanism insert
-// (hints are transport, not conversation); `replyVia` is the effective channel the prompt seam chose. Returns
-// the new line's `mid`, which a best-effort poke carries.
-export function appendSent(id: string, text: string, from: string | null, replyVia?: 'note'): { mid: string } {
-  const mid = randomUUID()
-  append(id, { ts: new Date().toISOString(), kind: 'sent', mid, text, from, ...(replyVia ? { replyVia } : {}) })
-  return { mid }
-}
-
-// The unowned read: any process may take it with nothing but filesystem access, and taking it perturbs
-// nothing. Index = event position, which is what a cursor names ([[session-cursors]]).
-export function timelineEvents(id: string): TimelineEvent[] {
-  try {
-    const p = timelinePath(id)
-    if (!existsSync(p)) return []
-    return readFileSync(p, 'utf8').split('\n').filter(Boolean).map((l) => {
-      try { return JSON.parse(l) as TimelineEvent } catch { return null }
-    }).filter((e): e is TimelineEvent => e != null && (e.kind === 'status' || e.kind === 'sent'))
-  } catch { return [] }
-}
-
-// the same L0 read taken as CHEAPLY as it can be: a follower ([[session-follow]]) ticks over many logs, so it
-// stats first and parses only what grew. null = no log yet (a session that has authored nothing).
-export function timelineStamp(id: string): string | null {
-  try { const s = statSync(timelinePath(id)); return `${s.size}:${s.mtimeMs}` }
-  catch { return null }
-}
-
-// the display word for an authored state — the SAME vocabulary every other surface speaks (awaiting → its
-// proposal's label, active → working), duplicated here as a tiny read-time map rather than importing the state
-// machine (sessions.ts imports THIS module for appendSent; a value import back would be a cycle — the
-// Lifecycle/Proposal imports above are type-only, erased at runtime).
-const PROPOSAL_DISPLAY: Record<string, DisplayWord> = { merge: 'review', nothing: 'done', close: 'close-pending' }
-type DisplayWord = 'working' | 'idle' | 'review' | 'done' | 'close-pending' | 'parked' | 'error' | 'asking' | 'queued'
-export const timelineDisplay = (e: { status: Lifecycle; proposal: Proposal | null }): DisplayWord =>
-  e.status === 'awaiting' ? (PROPOSAL_DISPLAY[e.proposal ?? 'nothing'] ?? 'done')
-  : e.status === 'active' ? 'working' : e.status
-
-// the channel of the LAST HUMAN send (from == null): 'note' when the note-reply hint rode along, else null.
-// This is what makes the reply-channel hints SYMMETRIC ([[session-timeline]]): a human send with no note flag
-// arriving after a note-send is the "back at a terminal" transition, and the delivery gets the counter-insert.
-// Derived from the durable log — no new state, and it survives a server restart. Agent senders (`from` set)
-// say nothing about where the HUMAN is reading, so they neither set nor clear it.
-export function lastHumanSendVia(id: string): 'note' | null {
-  const evs = timelineEvents(id)
-  for (let i = evs.length - 1; i >= 0; i--) {
-    const e = evs[i]
-    if (e.kind === 'sent' && e.from == null) return e.replyVia === 'note' ? 'note' : null
-  }
-  return null
-}
-
-// 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).
-export function readTimeline(id: string, limit = 500): { events: TimelineEvent[] } | null {
-  let raw: ReturnType<typeof readAliasedRawRecord>
-  try { raw = readAliasedRawRecord(id) } catch { return null }
-  if (!raw || !raw.governed) return null
-  const evs = timelineEvents(id)
-  const tail = evs.slice(Math.max(0, evs.length - Math.max(1, limit)))
-  return { events: tail.map((e) => (e.kind === 'status' ? { ...e, display: timelineDisplay(e) } : e)) }
-}