spexcode 0.5.8 → 0.5.9

package/spec-cli/src/graphStream.ts

@@ -4,7 +4,7 @@ import { watch, mkdirSync, readdirSync, readFileSync, type FSWatcher } from 'nod
 import { join, dirname, relative, resolve } from 'node:path'
 import { sessionsRoot, gitCommonDir } from './layout.js'
 import { hotSignature, warmSignature, listSessions } from './sessions.js'
-import { getBoard, invalidateBoard, patrolBoard } from './graphCache.js'
+import { getBoard, getBoardForSessionRefresh, invalidateBoard, patrolBoard } from './graphCache.js'
 import { unitize, tagOf, diffUnits, type Units } from './graphDelta.js'
 import {
   holdSessionEvalProjectionObserver,
@@ -14,27 +14,6 @@ import {
   setSessionEvalProjectionWarmup,
 } from '../../spec-eval/src/sessioneval.js'
 
-// @@@ board-stream — the board's freshness is PUSHED, not polled. A dashboard subscribes here ONCE; in
-// plain mode it gets a bare `graph-changed` and refetches /api/graph (the legacy protocol, kept verbatim
-// for old clients); in DELTA mode (`?mode=delta`) the server itself rebuilds on change and streams the
-// hash-chained patch ([[graph-delta]]): a `graph-full {to, graph}` on connect, then `graph-delta
-// {from, to, set, del}` per change — a few KB against the ~600KB snapshot, with a full-snapshot send
-// whenever the patch wouldn't win (bigger than the board, or the unit decomposition's id-uniqueness
-// precondition failed), so a delta subscriber is NEVER worse off than a full refetch.
-//
-// Every source carries the DOMAIN of the change it saw — 'sessions' (only the session rows moved) or 'full'
-// (anything could have) — and fireChanged funnels them into ONE debounced pipeline, escalating to the max
-// scope seen in the window so the cache can splice sessions instead of rebuilding whole ([[graph-cache]]).
-// Sources: (1) fs.watch on the per-user session store — every lifecycle transition lands as a
-// sessions/<id>/session.json write → 'sessions'; (2) fs.watch on the shared git dir's refs (+
-// packed-refs/HEAD) — a commit/merge moves a ref, reshaping the tree → 'full'; (3) fs.watch on the git
-// worktree REGISTRY (+ each live worktree root and gitdir index) — dirty source/spec/sidecar/rename/stage → 'full';
-// (4) two subscriber-gated pollers of the tmux-derived signatures ([[sessions]]) that never touch a file —
-// a 100ms HOT syscall poll and a 1s WARM tmux poll, both → 'sessions'; (5) a delta-gated ~15s cold-tick
-// PATROL that asks graph-cache to validate its owned input revision — unchanged inputs reuse the anchor,
-// while moved inputs select sessions/full there and missed leaf signals stay loud through repair accounting.
-// Plain mode without delta subscribers keeps its zero-build behavior: sources just fan out `graph-changed`.
-
 type Scope = 'sessions' | 'full'
 type EvalTarget = 'all' | { id?: string; path?: string }
 type Notify = () => void
@@ -230,11 +209,19 @@ export class TreeWatcherRegistry {
 const plainSubs = new Set<Notify>()
 const deltaSubs = new Set<DeltaSend>()
 let debounce: ReturnType<typeof setTimeout> | null = null
-let pendingScope: Scope | null = null   // the MAX change scope accumulated across the current debounce window
-const maxScope = (a: Scope | null, b: Scope): Scope => (a === 'full' || b === 'full' ? 'full' : 'sessions')
+let pendingFull = false
+let pendingSessions = false
+export type PendingGraphChanges = { full: boolean; sessions: boolean }
+export const addPendingGraphChange = (pending: PendingGraphChanges, scope: Scope): PendingGraphChanges => ({
+  full: pending.full || scope === 'full',
+  sessions: pending.sessions || scope === 'sessions',
+})
 
 // under SPEXCODE_BOARD_DEBUG=1, every broadcast logs its changed unit keys + trigger tags + build ms.
 const DEBUG = process.env.SPEXCODE_BOARD_DEBUG === '1'
+function traceLatency(stage: 'sessions-signal' | 'session-projection-complete' | 'broadcast', detail: Record<string, unknown> = {}): void {
+  if (DEBUG) console.warn(`spec-cli: graph latency ${JSON.stringify({ at: Date.now(), stage, ...detail })}`)
+}
 // the set of trigger tags accrued SINCE THE LAST BROADCAST — each fireChanged adds its scope, the cold tick
 // adds 'patrol'. Cleared on every broadcast. Its job: prove WHO caused a broadcast, so a change that only
 // the patrol saw (tag set === {'patrol'}) is flagged as a repair — some leaf watcher was blind.
@@ -261,23 +248,60 @@ let lastFullFrame: Frame | null = null
 let building = false
 let dirty = false
 let patrolPending = false
+let sessionRefreshRequested = false
+let wakeSessionRefresh: (() => void) | null = null
 
-async function rebuildAndBroadcast(patrol = false): Promise<void> {
+async function rebuildAndBroadcast(patrol = false, sessions = false, full = false): Promise<void> {
   if (patrol) patrolPending = true
-  if (building) { dirty = true; return }
+  if (sessions) sessionRefreshRequested = true
+  if (building) {
+    dirty = true
+    if (sessions) {
+      wakeSessionRefresh?.()
+      wakeSessionRefresh = null
+    }
+    return
+  }
   building = true
   try {
     do {
       dirty = false
       const validate = patrolPending
       patrolPending = false
+      const sessionsFirst = sessionRefreshRequested
+      sessionRefreshRequested = false
+      let servedSessionProjection = sessionsFirst
       let board: unknown
       // share the route's single-flight build ([[graph-cache]]); fireChanged() already invalidated the
       // cache (at the accumulated scope), so this gets a fresh build/splice (or joins one a concurrent poll
       // already started). The patrol instead asks that same cache flight to validate its input revision;
       // equal inputs return the anchor without invoking a producer.
       const t0 = Date.now()
-      try { board = await (validate ? patrolBoard() : getBoard()) }
+      try {
+        let wake!: () => void
+        const sessionWake = new Promise<void>((resolve) => { wake = resolve })
+        wakeSessionRefresh = wake
+        // A sessions-first turn can still fall back to an active route-owned full. Keep its wait wakeable
+        // too: a later persisted session change must re-enter the cheap projection rather than queue behind it.
+        const boardWait = sessionsFirst
+          ? getBoardForSessionRefresh()
+          : validate ? patrolBoard() : getBoard()
+        const outcome = await Promise.race([
+          boardWait.then((value) => ({ value })),
+          sessionWake.then(() => ({ value: null as unknown })),
+        ])
+        if (wakeSessionRefresh === wake) wakeSessionRefresh = null
+        if (outcome.value === null) {
+          boardWait.catch(() => {})
+          board = await getBoardForSessionRefresh()
+          servedSessionProjection = true
+          if (validate) patrolPending = true
+          dirty = true // the full wait was preempted only for delivery; it remains owed.
+        } else {
+          board = outcome.value
+          if (sessionsFirst && validate) { patrolPending = true; dirty = true }
+        }
+      }
       catch {
         // A failed refresh consumes no cause: graph-cache restores the producer scope, so its stream-side
         // attribution must remain owed too. This also retains watcher causes that arrived while the failed
@@ -287,15 +311,18 @@ async function rebuildAndBroadcast(patrol = false): Promise<void> {
         continue
       }
       const buildMs = Date.now() - t0
+      if (servedSessionProjection) traceLatency('session-projection-complete', { patrol: validate })
       const boardJson = JSON.stringify(board)
       const { units, ok } = unitize(board as Record<string, unknown>)
       const tag = tagOf(units)
-      // the trigger set describes who caused THIS rebuild, so it is consumed by the rebuild — not by the
-      // broadcast. Clearing it only when content moved let a no-op fire (every poller's first sample is
-      // one) leave its tag behind forever, and the next genuine patrol repair then read as leaf-signalled
-      // and went silent — the alarm suppressing itself on the very machines that need it.
+      // A session-first frame consumes its own cause, but a full/patrol cause remains owed until structural
+      // convergence. Otherwise the first cheap projection would erase patrol accountability before the full
+      // result could name it. A normal frame consumes its whole trigger set, including a no-op frame.
       const tags = [...triggerTags]
       triggerTags.clear()
+      if (servedSessionProjection)
+        for (const tag of tags) if (tag === 'full' || tag === 'patrol') triggerTags.add(tag)
+      if (sessionsFirst && full) dirty = true
       if (tag === lastTag) continue
       // the changed unit keys — computed against the prior anchor when we have one (a first paint has no
       // anchor, so no repair claim can be made against it).
@@ -314,6 +341,7 @@ async function rebuildAndBroadcast(patrol = false): Promise<void> {
       // (stopSourcesIfIdle cleared the anchor; leaving lastTag/lastUnits stale-cleared is consistent —
       // rebuilds only run while delta subscribers exist, so nothing chains from them meanwhile).
       if (deltaSubs.size) { lastUnits = ok ? units : null; lastTag = tag; lastFullFrame = fullFrame }
+      traceLatency('broadcast', { event: frame.event, sessionProjection: servedSessionProjection, tags, changedKeys })
       for (const send of [...deltaSubs]) { try { send(frame) } catch { /* swept on abort */ } }
       for (const n of [...plainSubs]) { try { n() } catch { /* swept on abort */ } }
       // ---- repair accounting: a real (tag-moved) broadcast whose ONLY trigger was the cold-tick patrol
@@ -329,18 +357,21 @@ async function rebuildAndBroadcast(patrol = false): Promise<void> {
 }
 
 // a merge/launch/close touches several record files at once; collapse the burst into ONE signal. Each call
-// carries its change SCOPE; the window accumulates the MAX ([[graph-cache]] escalates none→sessions→full).
+// carries its own change SCOPE: full and sessions are independent obligations, not a max-scope replacement.
 // With delta subscribers the debounced fire rebuilds and broadcasts (plain subs then ride the same
 // tag-moved gate — no spurious refetches); without them it stays the zero-build legacy notify.
 function fireChanged(scope: Scope = 'full', evalTarget?: EvalTarget): void {
   // Advance eval input generations BEFORE invalidating/building the board, so the first frame caused by an
   // input event is `updating(lastKnown)`. Summary completion calls this function without a target.
+  if (scope === 'sessions') traceLatency('sessions-signal')
   if (evalTarget) invalidateSessionEvalProjections(evalTarget)
-  pendingScope = maxScope(pendingScope, scope)
-  // invalidate the route's board cache ([[graph-cache]]) on EVERY change signal, at the accumulated scope,
+  const pending = addPendingGraphChange({ full: pendingFull, sessions: pendingSessions }, scope)
+  pendingFull = pending.full
+  pendingSessions = pending.sessions
+  // invalidate the route's board cache ([[graph-cache]]) on EVERY change signal at its OWN scope,
   // before the debounce guard — a plain-mode client that polls /api/graph (no delta rebuild here) must
   // still see fresh data on its next poll, and a delta rebuild below re-reads the same now-stale cache.
-  invalidateBoard(pendingScope)
+  invalidateBoard(scope)
   triggerTags.add(scope)
   // DEBOUNCE = 25ms. Real fs-event bursts (a merge touching many records) were MEASURED to span 0–5ms, so a
   // 25ms window collapses them with room to spare while shaving ~125ms off the old 150ms lag; anything
@@ -349,8 +380,10 @@ function fireChanged(scope: Scope = 'full', evalTarget?: EvalTarget): void {
   if (debounce) return
   debounce = setTimeout(() => {
     debounce = null
-    pendingScope = null
-    if (deltaSubs.size) void rebuildAndBroadcast()
+    const full = pendingFull, sessions = pendingSessions
+    pendingFull = false
+    pendingSessions = false
+    if (deltaSubs.size) void rebuildAndBroadcast(false, sessions, full)
     else for (const notify of [...plainSubs]) { try { notify() } catch { /* swept on abort */ } }
   }, 25)
 }

package/spec-cli/src/guide.ts

@@ -39,8 +39,8 @@ the rest, you don't hand-author the spec tree or wire the dashboard yourself.
 Look these up on demand — the formats an agent authors, and the settings it configures:
   spex guide spec       the spec.md format (frontmatter + body + the rules lint enforces)
   spex guide eval       the eval.md format (scenario schema + how loss is measured and filed)
-  spex guide settings   the spexcode.json / spexcode.local.json settings (launchers, dashboard icon, lint
-                        budgets, layout) — every field, and which of the two files it belongs in
+  spex guide settings   the spexcode.json / spexcode.local.json settings (launchers, dashboard icon, upload,
+                        lint budgets, layout) — every field, and which of the two files it belongs in
   spex guide footprint  the footprint model — what SpexCode plants in a repo, and who sees it
                         (committed | ignored | hidden), and every migration recipe`
 
@@ -252,21 +252,23 @@ code file or the scenario (the eval.md) moves since it was filed.
   spex eval scenario ls [<node>] the declared contracts; text --unmeasured = blind-spot worklist; --json = canonical declaration index
   spex eval clean                GC the content-addressed evidence cache`
 
+const UPLOAD_DEFAULTS = uploadPolicyDefaults()
+
 const SETTINGS = `spex guide settings — SpexCode's runtime settings (spexcode.json / spexcode.local.json)
 
 SpexCode reads PROJECT runtime settings from TWO optional JSON files at the repo root. There is no imperative
 settings verb — an agent CONFIGURES SpexCode by EDITING these files directly. The two split by
 PORTABILITY, and picking the right one is the whole discipline:
 
-  spexcode.json         COMMITTED — portable, shared by everyone on the repo. Layout, policy, dashboard
-                        identity and launcher visibility, lint policy, resource and doctor health budgets, launcher NAMES. "Git is the database": tracked so the
+  spexcode.json         COMMITTED — portable, shared by everyone on the repo. Layout, upload policy,
+                        dashboard identity and launcher visibility, lint policy, resource and doctor health budgets, launcher NAMES. "Git is the database": tracked so the
                         team shares ONE configuration.
   spexcode.local.json   GITIGNORED — host-specific, never committed. Absolute launcher paths, cert/secret
                         paths. Layered OVER spexcode.json (see MERGE
                         below); a targeted env override (SPEXCODE_CODEX_SERVER_CMD, …) still wins at its read site.
 
 Rule of thumb — is the value TRUE FOR THE PROJECT or TRUE FOR THIS MACHINE? A branch name, a dashboard
-icon or launcher-visibility policy, lint policy, resource and doctor health budgets, and a launcher's name+harness are project facts → committed spexcode.json. The ABSOLUTE
+icon or launcher-visibility policy, upload policy, lint policy, resource and doctor health budgets, and a launcher's name+harness are project facts → committed spexcode.json. The ABSOLUTE
 PATH of a launcher wrapper or a TLS cert path are machine facts → gitignored spexcode.local.json.
 Both files are optional; omit any field to take its default, except \`sessions.defaultLauncher\` when using
 \`spex session new\` or the dashboard without an explicit launcher choice.
@@ -275,7 +277,7 @@ The host-wide gateway has one separate per-user setting, \`gateway.icon\` in
 \`$SPEXCODE_HOME/config.json\`. It is documented below and never belongs to either project file.
 
 MERGE: spexcode.local.json is layered over spexcode.json ONE LEVEL DEEP — per top-level section (dashboard,
-sessions, …), the two objects are shallow-merged with LOCAL WINNING per key; sections only one file names
+uploads, sessions, …), the two objects are shallow-merged with LOCAL WINNING per key; sections only one file names
 pass through untouched. This is exactly what lets a launcher's portable NAME reference (defaultLauncher)
 sit in the committed file while its host-specific DEFINITION (with the abs cmd) sits in the local file —
 see LAUNCHERS.
@@ -336,6 +338,26 @@ The report is read-only: \`spex session resources [--json]\`. Reclaim eligibilit
 projection never issues mutation authority or signals a process. Budgets are project policy and belong in committed spexcode.json;
 host-specific tuning may override this top-level section in spexcode.local.json.
 
+── UPLOADS (spexcode.json — portable transfer policy; local overrides are useful for one machine's disk/network) ──
+  uploads.maxBytes          maximum bytes in one attached file. Default ${UPLOAD_DEFAULTS.maxBytes}.
+  uploads.chunkBytes        maximum raw PATCH body and client slice size. Default ${UPLOAD_DEFAULTS.chunkBytes}.
+  uploads.concurrency       simultaneous attachment streams from one dashboard batch. Default ${UPLOAD_DEFAULTS.concurrency}.
+  uploads.requestTimeoutMs  browser timeout for one chunk or completion request. Default ${UPLOAD_DEFAULTS.requestTimeoutMs}.
+  uploads.retryLimit        automatic retries after the initial transient chunk failure. Default ${UPLOAD_DEFAULTS.retryLimit}.
+  uploads.retryDelayMs      wait between those retries. Default ${UPLOAD_DEFAULTS.retryDelayMs}.
+  uploads.incompleteTtlMs   idle staging lifetime before an unfinished transfer expires. Default ${UPLOAD_DEFAULTS.incompleteTtlMs}.
+  uploads.cleanupIntervalMs stale-staging reaper cadence. Default ${UPLOAD_DEFAULTS.cleanupIntervalMs}.
+  uploads.minFreeBytes      bytes retained on the backend filesystem while reserving a new attachment.
+                            Default ${UPLOAD_DEFAULTS.minFreeBytes}.
+  uploads.evidenceMaxBytes  retained POST-body ceiling for eval evidence. Default ${UPLOAD_DEFAULTS.evidenceMaxBytes}.
+All fields are positive integers except retryLimit, retryDelayMs, and minFreeBytes, which may be zero.
+The seed template is the one default source; omit a field to use it. The backend reads the merged files for
+each transfer and cleanup pass. The dashboard receives chunk, concurrency, timeout, and retry policy from
+the create/status response, so a portable project policy takes effect without another browser setting.
+Put team-wide transfer policy in committed spexcode.json; use the same keys in gitignored spexcode.local.json
+only when the backend machine needs a local override. The normal top-level shallow merge lets a local
+uploads.chunkBytes replace only that key.
+
 ── LAUNCHERS (the profile block, split across the two files) ──
 A named launcher profile fixes BOTH a session's harness AND its exact launch command; a create picks one
 by name with --launcher/the dashboard dropdown, and the chosen name is persisted on the record so a resume
@@ -566,3 +588,4 @@ export function guideText(topic?: string): string | null {
   const t = TOPICS[topic]
   return t ? t + FOOTER : null
 }
+import { uploadPolicyDefaults } from './layout.js'