spexcode 0.5.7 → 0.5.9

package/spec-cli/src/shim-runtime.ts

@@ -116,21 +116,13 @@ const spexShimRuntime = (cfg) => {
     return args
   }
 
-  // the per-session rendezvous control socket: bind a line-JSON server on CLAUDE_BG_RENDEZVOUS_SOCK (handed
-  // by every ownsRendezvous launch; a self-launched bare harness has no env → no server) speaking the
-  // reclaude mini-protocol, so claude's deliverViaRendezvous and socket-listener liveness work UNCHANGED.
-  // MULTI-connection (unlike reclaude's daemon): a session-liveness probe connect can never kick a concurrent
-  // delivery, so the sender's atomic reply+repaint chunk always resolves on its own connection. The data
-  // handler is deliberately SYNCHRONOUS — a chunk's lines parse in one pass and repaint-done (the in-order
-  // parse barrier) flushes before any other event can run: confirmation means PARSED, not processed; the
-  // injection (a whole model turn on some hosts) runs BEHIND the confirm. A known-unable inject answers
-  // reply-rejected BEFORE repaint-done so the sender fails loud instead of confirming a prompt that can
-  // never land; a LATE inject failure best-effort reply-rejects (the sender has usually resolved and gone).
+  // The per-session rendezvous control socket is a best-effort same-turn poke. The timeline remains the
+  // message's durable copy, so this listener only receives reply lines and never confirms or rejects them.
   const serveRendezvous = (inject, opts) => {
     const sock = (process.env.CLAUDE_BG_RENDEZVOUS_SOCK || "").trim()
     if (!sock) return null
     try { __spexUnlink(sock) } catch { /* no stale socket — fine */ }
-    const reject = (c) => { try { c.write(JSON.stringify({ type: "reply-rejected" }) + "\\n") } catch { /* peer gone */ } }
+    const injected = new Set()
     const server = __spexCreateServer((c) => {
       let buf = ""
       c.on("error", () => { /* probes disconnect abruptly — expected */ })
@@ -143,13 +135,14 @@ const spexShimRuntime = (cfg) => {
           let msg
           try { msg = JSON.parse(line) } catch { continue }
           if (msg && msg.type === "reply" && typeof msg.text === "string") {
-            if (opts && opts.canInject && !opts.canInject()) { reject(c); continue }
+            if (opts && opts.canInject && !opts.canInject()) continue
+            const mid = typeof msg.mid === "string" ? msg.mid : ""
+            if (mid && injected.has(mid)) continue
+            if (mid) injected.add(mid)
             try {
               const p = inject(msg.text)
-              if (p && typeof p.catch === "function") p.catch(() => reject(c))
-            } catch { reject(c) }
-          } else if (msg && msg.type === "repaint") {
-            try { c.write(JSON.stringify({ type: "repaint-done" }) + "\\n") } catch { /* peer gone */ }
+              if (p && typeof p.catch === "function") p.catch(() => { if (mid) injected.delete(mid) })
+            } catch { if (mid) injected.delete(mid) }
           }
         }
       })

package/spec-cli/src/specs.ts

@@ -2,7 +2,7 @@ import { readFileSync, readdirSync, existsSync } from 'node:fs'
 import { readFile, readdir } from 'node:fs/promises'
 import { join, relative, basename } from 'node:path'
 import { repoRoot, historyIndex, rowsFor, historyStats, pathsStats, driftIndex, driftFor, fileDiffAt,
-  sourceIndexes, treeTextFiles, type HistoryIndex, type DriftIndex } from './git.js'
+  sourceIndexes, treeTextFiles, primeAncestorClosures, ancestorsOf, inAncestors, type HistoryIndex, type DriftIndex } from './git.js'
 import { parseCodeEntry, parseRelation, relationClaimsPath } from './anchors.js'
 
 // a node is any directory under .spec holding a spec.md; its parent is the nearest ancestor that also holds one.
@@ -257,9 +257,30 @@ export async function loadSpecs(root: string = ROOT, options: LoadSpecsOptions =
       options.drift === null ? Promise.resolve(null) : options.drift ?? driftIndex(root, tip),
     ])
   const [[idx, didx], allRaws] = await Promise.all([indexes, rawsAsync(root, tip, options.snapshot)])
+  const prepared = allRaws.map((r) => ({
+    r,
+    h: idx ? rowsFor(idx, r.relPath) : [],
+    codeRel: parseRelation(list(r.fm.code), 'code'),
+    relatedRel: parseRelation(list(r.fm.related), 'related'),
+  }))
+  if (didx) {
+    const queries: { hash: string; node: string }[] = []
+    for (const { r, h, codeRel, relatedRel } of prepared) {
+      if (!h[0]?.hash || (!codeRel.entries.length && !relatedRel.entries.some((entry) => !entry.selectors.length))) continue
+      queries.push({ hash: h[0].hash, node: r.id })
+    }
+    primeAncestorClosures(didx, queries.map(({ hash }) => hash))
+    // Only an ack named for this node and outside its version's ancestry becomes a cover. Discover that
+    // exact roster from the now-primed bases instead of retaining closures for older, non-covering acks.
+    const covers: string[] = []
+    for (const [hash, nodes] of didx.acks) if (queries.some(({ hash: baseHash, node }) => {
+      const base = ancestorsOf(didx, baseHash)
+      return !!base && nodes.has(node) && !inAncestors(didx, base, hash)
+    })) covers.push(hash)
+    primeAncestorClosures(didx, covers)
+  }
   const loaded = []
-  for (const r of allRaws) {
-    const h = idx ? rowsFor(idx, r.relPath) : []
+  for (const { r, h, codeRel, relatedRel } of prepared) {
     // session = the Session: trailer of the node's latest version; frontmatter `session:` is the fallback.
     const fmSession = str(r.fm.session)
     const session = h[0]?.session || (fmSession && fmSession !== 'null' ? fmSession : null)
@@ -268,12 +289,12 @@ export async function loadSpecs(root: string = ROOT, options: LoadSpecsOptions =
     // drift, claims, eval attribution — expects, file-level as before), the scoped entries (path +
     // selectors) ride separately for lint's anchor engine, and structural problems (duplicates,
     // bare/scoped mixing, glob selectors, the code cap) surface as lint integrity errors.
-    const codeRel = parseRelation(list(r.fm.code), 'code')
-    const relatedRel = parseRelation(list(r.fm.related), 'related')
-    const code = codeRel.entries.map((e) => e.path)
-    const codeScoped = codeRel.entries.filter((e) => e.selectors.length > 0)
-    const related = relatedRel.entries.map((e) => e.path)
-    const relatedScoped = relatedRel.entries.filter((e) => e.selectors.length > 0)
+    const codeEntries = codeRel.entries
+    const code = codeEntries.map((e) => e.path)
+    const codeScoped = codeEntries.filter((e) => e.selectors.length > 0)
+    const relatedEntries = relatedRel.entries
+    const related = relatedEntries.map((e) => e.path)
+    const relatedScoped = relatedEntries.filter((e) => e.selectors.length > 0)
     const relationProblems = [...codeRel.problems, ...relatedRel.problems]
     const S = h[0]?.hash || ''
     const driftFiles = []
@@ -287,7 +308,7 @@ export async function loadSpecs(root: string = ROOT, options: LoadSpecsOptions =
     // A SCOPED related entry is excluded here: its file-level movement is silent by design — only a
     // selector HIT warns, and that verdict needs the anchor engine, so lint derives it, not the loader.
     const relatedDriftFiles = []
-    for (const e of relatedRel.entries) {
+    for (const e of relatedEntries) {
       if (e.selectors.length) continue
       const d = didx ? { file: e.path, behind: driftFor(didx, S, e.path, r.id) } : { file: e.path, behind: 0 }
       if (d.behind > 0) relatedDriftFiles.push(d)
@@ -304,8 +325,10 @@ export async function loadSpecs(root: string = ROOT, options: LoadSpecsOptions =
       hue: Number(str(r.fm.hue, '210')),
       desc: str(r.fm.desc),
       code,
+      codeEntries,
       codeScoped,
       related,
+      relatedEntries,
       relatedScoped,
       relationProblems,
       version: h.length,

package/spec-cli/src/uninstall.ts

@@ -8,15 +8,6 @@ import { resolveHarnessTargets } from './harness-select.js'
 import { loadSkillConfig, loadAgentConfig } from './specs.js'
 import { dematerialize } from './materialize.js'
 
-// @@@ spex-uninstall - materialize(∅) plus the store: the in-tree/global-config backout IS dematerialize (the
-// same identity-stamped erase phase every materialize runs first — the forgetting law's empty policy), and this
-// command adds only what a materialize never owns per-run: the global per-project store, the plugin-bundle sweep,
-// and the optional git hooks. EVERY removal is gated on a SpexCode IDENTITY STAMP (the managed-block
-// sentinels, the shim's own dispatch.sh command line, the trust sentinels, the generated mark / name-scoped
-// on-demand paths, the plugin name stamp), so it can only ever delete what SpexCode itself generated. The one
-// inviolable rule: the user's tracked intent ASSET (.spec/.plugins + spexcode.json) is NEVER touched — uninstall
-// removes only generated WIRING and local runtime state, not the spec graph and adoption config they served.
-
 // the standard plugin-host folders a host agent scans (in addition to any named in spexcode.json's `harnesses`).
 const DEFAULT_PLUGIN_HOSTS = ['.claude', '.codex', '.zcode'] as const
 

package/spec-cli/src/uploads.ts

@@ -1,31 +1,253 @@
-import { mkdirSync, writeFileSync } from 'node:fs'
+import { randomUUID } from 'node:crypto'
+import { createWriteStream, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, statfsSync, truncateSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { basename, join } from 'node:path'
+import { Readable, Transform } from 'node:stream'
+import { pipeline } from 'node:stream/promises'
+import type { ReadableStream as NodeReadableStream } from 'node:stream/web'
+import { repoRoot } from './git.js'
+import { readUploadPolicy, type UploadPolicy } from './layout.js'
 
-// the backend's tmpdir — same /tmp home as the rendezvous sockets (sessions.ts), shared with the worker.
+// The backend's tmpdir is the worker's filesystem. Completed files stay directly under this sink; private
+// metadata and partial bytes live below .staging until an exact-length transfer is promoted atomically.
 const UPLOAD_DIR = join(tmpdir(), 'spexcode-uploads')
+const STAGING_DIR = join(UPLOAD_DIR, '.staging')
 
-// a generous ceiling so a stray huge upload can't quietly fill /tmp — over it we fail loud (the route 413s)
-// rather than write. Real screenshots/attachments sit far under this.
-export const MAX_UPLOAD_BYTES = 50 * 1024 * 1024
+type UploadMeta = {
+  version: 1
+  id: string
+  name: string
+  size: number
+  offset: number
+  createdAt: number
+  updatedAt: number
+}
+
+export type UploadStatus = Pick<UploadMeta, 'id' | 'name' | 'size' | 'offset'> & Pick<UploadPolicy,
+  'chunkBytes' | 'concurrency' | 'requestTimeoutMs' | 'retryLimit' | 'retryDelayMs'>
+
+export class UploadError extends Error {
+  constructor(readonly status: number, message: string, readonly offset?: number) {
+    super(message)
+  }
+}
+
+const uploadPolicy = (): UploadPolicy => readUploadPolicy(repoRoot())
+
+export const evidenceMaxBytes = (): number => uploadPolicy().evidenceMaxBytes
+
+function ensureDirs(): void {
+  mkdirSync(STAGING_DIR, { recursive: true })
+}
 
-// strip a client-supplied filename to a safe basename: no directory parts, only [A-Za-z0-9._-], no leading
-// dots — so a crafted name (`../../etc/x`, `.bashrc`) can never escape UPLOAD_DIR. The extension is kept for
-// readability; an empty/exotic name falls back to a generic stem.
 function safeName(name: string): string {
   const base = basename(name || '').replace(/[^A-Za-z0-9._-]/g, '_').replace(/^\.+/, '')
   return base || 'upload'
 }
 
-let seq = 0
+function validId(id: string): boolean {
+  return /^[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}$/i.test(id)
+}
+
+function metaPath(id: string): string {
+  return join(STAGING_DIR, `${id}.json`)
+}
+
+function partPath(id: string): string {
+  return join(STAGING_DIR, `${id}.part`)
+}
+
+function removeTransfer(id: string): void {
+  rmSync(metaPath(id), { force: true })
+  rmSync(partPath(id), { force: true })
+}
+
+function readMetaFile(id: string): UploadMeta | null {
+  if (!validId(id)) return null
+  try {
+    const meta = JSON.parse(readFileSync(metaPath(id), 'utf8')) as UploadMeta
+    if (meta.version !== 1 || meta.id !== id || typeof meta.name !== 'string' ||
+      !Number.isSafeInteger(meta.size) || meta.size <= 0 ||
+      !Number.isSafeInteger(meta.offset) || meta.offset < 0 || meta.offset > meta.size ||
+      !Number.isSafeInteger(meta.createdAt) || !Number.isSafeInteger(meta.updatedAt)) return null
+    return meta
+  } catch {
+    return null
+  }
+}
+
+function writeMeta(meta: UploadMeta): void {
+  const path = metaPath(meta.id)
+  const temp = `${path}.${process.pid}.${randomUUID()}.tmp`
+  writeFileSync(temp, JSON.stringify(meta) + '\n')
+  renameSync(temp, path)
+}
+
+function actualOffset(meta: UploadMeta): number {
+  try {
+    return statSync(partPath(meta.id)).size
+  } catch {
+    return 0
+  }
+}
+
+function status(meta: UploadMeta, policy: UploadPolicy): UploadStatus {
+  const { chunkBytes, concurrency, requestTimeoutMs, retryLimit, retryDelayMs } = policy
+  return { id: meta.id, name: meta.name, size: meta.size, offset: meta.offset, chunkBytes, concurrency, requestTimeoutMs, retryLimit, retryDelayMs }
+}
+
+function syncOffset(meta: UploadMeta): UploadMeta {
+  const offset = actualOffset(meta)
+  if (offset > meta.size) throw new UploadError(409, 'upload staging file exceeds its declared length')
+  if (offset !== meta.offset) {
+    meta.offset = offset
+    meta.updatedAt = Date.now()
+    writeMeta(meta)
+  }
+  return meta
+}
+
+function loadUpload(id: string, policy: UploadPolicy): UploadMeta {
+  const meta = readMetaFile(id)
+  if (!meta) throw new UploadError(404, 'upload not found')
+  if (Date.now() - meta.updatedAt > policy.incompleteTtlMs) {
+    removeTransfer(id)
+    throw new UploadError(404, 'upload expired')
+  }
+  return syncOffset(meta)
+}
+
+function reservedBytes(policy: UploadPolicy): number {
+  let total = 0
+  for (const entry of readdirSync(STAGING_DIR, { withFileTypes: true })) {
+    if (!entry.isFile() || !entry.name.endsWith('.json')) continue
+    const meta = readMetaFile(entry.name.slice(0, -5))
+    if (!meta || Date.now() - meta.updatedAt > policy.incompleteTtlMs) continue
+    total += Math.max(0, meta.size - actualOffset(meta))
+  }
+  return total
+}
+
+function reserveCapacity(size: number, policy: UploadPolicy): void {
+  let available = 0
+  try {
+    const fs = statfsSync(UPLOAD_DIR)
+    available = Number(fs.bavail) * Number(fs.bsize)
+  } catch {
+    // A filesystem that cannot report capacity will still fail loudly during the stream write.
+    return
+  }
+  if (size > Math.max(0, available - policy.minFreeBytes - reservedBytes(policy))) {
+    throw new UploadError(507, 'insufficient backend disk capacity for this upload')
+  }
+}
+
+export function cleanupExpiredUploads(policy = uploadPolicy()): void {
+  ensureDirs()
+  const now = Date.now()
+  for (const entry of readdirSync(STAGING_DIR, { withFileTypes: true })) {
+    if (!entry.isFile() || !entry.name.endsWith('.json')) continue
+    const id = entry.name.slice(0, -5)
+    const meta = readMetaFile(id)
+    if (!meta || now - meta.updatedAt > policy.incompleteTtlMs) removeTransfer(id)
+  }
+  for (const entry of readdirSync(STAGING_DIR, { withFileTypes: true })) {
+    if (!entry.isFile() || !entry.name.endsWith('.part')) continue
+    const id = entry.name.slice(0, -5)
+    if (readMetaFile(id)) continue
+    try {
+      if (now - statSync(partPath(id)).mtimeMs > policy.incompleteTtlMs) rmSync(partPath(id), { force: true })
+    } catch { /* raced a cancellation or another cleanup pass */ }
+  }
+}
+
+export function startUploadReaper(): void {
+  const sweep = () => {
+    const policy = uploadPolicy()
+    cleanupExpiredUploads(policy)
+    const timer = setTimeout(sweep, policy.cleanupIntervalMs)
+    timer.unref()
+  }
+  sweep()
+}
+
+export function createUpload(name: unknown, size: unknown): UploadStatus {
+  const policy = uploadPolicy()
+  if (typeof name !== 'string' || !name.trim()) throw new UploadError(400, 'file name is required')
+  if (typeof size !== 'number' || !Number.isSafeInteger(size) || size <= 0) throw new UploadError(400, 'file must not be empty')
+  if (size > policy.maxBytes) throw new UploadError(413, 'file exceeds the configured upload limit')
+  ensureDirs()
+  cleanupExpiredUploads(policy)
+  reserveCapacity(size, policy)
+  const now = Date.now()
+  const meta: UploadMeta = { version: 1, id: randomUUID(), name: safeName(name), size, offset: 0, createdAt: now, updatedAt: now }
+  writeMeta(meta)
+  return status(meta, policy)
+}
+
+export function uploadStatus(id: string): UploadStatus {
+  const policy = uploadPolicy()
+  return status(loadUpload(id, policy), policy)
+}
+
+export async function appendUpload(id: string, offset: unknown, body: ReadableStream<Uint8Array> | null, contentLength?: string): Promise<UploadStatus> {
+  const policy = uploadPolicy()
+  const meta = loadUpload(id, policy)
+  if (typeof offset !== 'number' || !Number.isSafeInteger(offset) || offset < 0) throw new UploadError(400, 'upload offset must be a non-negative integer')
+  if (offset !== meta.offset) throw new UploadError(409, 'upload offset does not match the committed bytes', meta.offset)
+  if (!body) throw new UploadError(400, 'upload chunk is required')
+  const declared = contentLength == null ? null : Number(contentLength)
+  if (declared != null && (!Number.isSafeInteger(declared) || declared <= 0)) throw new UploadError(400, 'content-length must be a positive integer')
+  if (declared != null && (declared > policy.chunkBytes || meta.offset + declared > meta.size)) {
+    throw new UploadError(413, 'upload chunk exceeds its declared bounds')
+  }
+
+  let written = 0
+  const before = meta.offset
+  const limiter = new Transform({
+    transform(chunk, _encoding, callback) {
+      written += chunk.length
+      if (written > policy.chunkBytes || before + written > meta.size) {
+        callback(new UploadError(413, 'upload chunk exceeds its declared bounds'))
+        return
+      }
+      callback(null, chunk)
+    },
+  })
+  try {
+    await pipeline(Readable.fromWeb(body as unknown as NodeReadableStream), limiter, createWriteStream(partPath(id), { flags: 'a' }))
+  } catch (error) {
+    if (error instanceof UploadError) {
+      truncateSync(partPath(id), before)
+      throw error
+    }
+    // An interrupted connection may have committed a valid prefix. The next GET reports its actual length.
+    meta.offset = actualOffset(meta)
+    meta.updatedAt = Date.now()
+    writeMeta(meta)
+    throw new UploadError(500, `upload write failed: ${(error as Error).message}`)
+  }
+  if (written === 0) throw new UploadError(400, 'upload chunk is empty')
+  meta.offset = actualOffset(meta)
+  meta.updatedAt = Date.now()
+  writeMeta(meta)
+  return status(meta, policy)
+}
+
+export function completeUpload(id: string): string {
+  const meta = loadUpload(id, uploadPolicy())
+  if (meta.offset !== meta.size) throw new UploadError(409, `upload is incomplete (${meta.offset} of ${meta.size} bytes)`, meta.offset)
+  const path = join(UPLOAD_DIR, `${Date.now().toString(36)}-${meta.id}-${safeName(meta.name)}`)
+  try {
+    renameSync(partPath(id), path)
+    rmSync(metaPath(id), { force: true })
+    return path
+  } catch (error) {
+    throw new UploadError(500, `upload completion failed: ${(error as Error).message}`)
+  }
+}
 
-// write one uploaded file into UPLOAD_DIR under a collision-proof `<time>-<seq>-<name>` stem and return its
-// absolute path — the string the dashboard splices into the prompt. Creates the dir on first use.
-export async function saveUpload(file: File): Promise<string> {
-  mkdirSync(UPLOAD_DIR, { recursive: true })
-  const buf = Buffer.from(await file.arrayBuffer())
-  const stamp = `${Date.now().toString(36)}-${(seq++).toString(36)}`
-  const path = join(UPLOAD_DIR, `${stamp}-${safeName(file.name)}`)
-  writeFileSync(path, buf)
-  return path
+export function cancelUpload(id: string): void {
+  loadUpload(id, uploadPolicy())
+  removeTransfer(id)
 }

package/spec-cli/src/worktree-sources.ts

@@ -2,22 +2,6 @@ import { appendFileSync, copyFileSync, existsSync, mkdirSync, readFileSync } fro
 import { dirname, join } from 'node:path'
 import { git } from './git.js'
 
-// @@@ worktree-sources ([[residence]]) - a fresh session worktree is fed by THREE transports, one per
-// source kind, and the kind decides the transport — never a mode branch:
-//   - TRACKED project state (`.spec`, `spexcode.json`) arrives by GIT CHECKOUT: the sources are always
-//     tracked (git is the database), so `git worktree add` alone delivers them. No symlink — a link is a
-//     WRITE-SEMANTICS declaration (write-through to the main tree), and spec writes go back through the
-//     branch/merge ritual, not through a side channel.
-//   - MATERIALIZED ARTIFACTS (contract blocks, shims, skills) are DERIVED — transported by re-materialize,
-//     not by link or copy:
-//     sessions.ts materializes into the worktree at creation, and the git-native anchors (pre-commit /
-//     post-checkout / post-merge — [[commit-surgery]]) re-materialize on change.
-//   - HOST state (`spexcode.local.json`, machine-local and never tracked) is COPIED — a snapshot: the worker
-//     reads the same launchers/policy the host had at dispatch, but its writes land on its own copy and die
-//     with the worktree, never on the host's real config (a worker once wrote "its" test config through the
-//     old symlink and wiped the host's launchers → every later dispatch 401'd).
-// This module owns only the third transport (plus hiding what it seeds). A failure degrades that worker
-// (default launchers/policy), so it is reported, not swallowed.
 export function seedWorktreeHostState(main: string, wt: string): void {
   const f = 'spexcode.local.json'
   try {

package/spec-cli/templates/spec/project/.plugins/commands/supervisor/spec.md

@@ -5,4 +5,4 @@ status: active
 hue: 280
 desc: Launch a supervisor agent that manages other agents from the main checkout to drive a goal to completion.
 ---
-You are a SpexCode supervisor — a **manager**, not a feature worker. Your work base is the main checkout (the repository root), NOT your own worktree: do all git via `git -C <root>`, everything else via the `spex` CLI, and never write feature code. This preset IS your complete playbook (dispatch → monitor → review → merge → close, and how to parallelize) — the CLI's own `spex help session` is the reference for every verb's exact semantics. Drive the goal: decompose it into worker-sized tasks and dispatch one worker per independent task (`spex session new "<task>"` — give each ONLY its task; a task about one specific node mentions it as `[[<id>]]`, which only sets the branch name and board attribution; the session's real node links come from what it edits), monitor with `spex session watch`, review proposals with `spex session review <id>`, dispatch the merge of good ones back to their own session (`spex session merge <id>`; the doer syncs the base into its own worktree first, so what reaches `<root>` is a trivial merge) and confirm it landed, then close. `<root>` is the fleet's ONE landing door — it takes one landing at a time, so a worker whose merge finds it mid-merge waits rather than racing, and you never fix up another lane's half-merged index yourself. Never let a worker self-merge; keep `spex spec lint` at 0 errors. To READ a worker's current state, use the one-shot snapshots (`spex session review <id>` or `spex session ls` — both return immediately); to WAIT for a worker, background `spex session wait <id>` — it is edge-triggered: it returns only when it OBSERVES the worker transition from non-actionable into an actionable status (an already-actionable arrival state does not return it), printing the observed status path — which is also how you wait for a dispatched merge to actually land; never block on `spex session watch`, which STREAMS forever and will freeze your turn. **Stay parked while your fleet runs:** after dispatching, background a `spex session wait <child>` per worker (per the manager loop) so that when you stop with children still working you land in `parked` — self-resuming on the next child transition — NOT `asking`; only go `asking` when you genuinely need the human. This matters because the dashboard **folds each child under you and shows YOUR own status for the whole group** (session-nesting, no child-status aggregation), so a supervisor that stays parked-while-they-run is what makes that folded group status honest. One footgun that bites a fresh supervisor: before `spex session close <id>`, confirm the merge landed (`git -C <root> log -1` shows HEAD at the new merge commit) — closing an unmerged branch discards the work. **DRAIN THE ISSUES** (issues / local-issues) as part of your loop: `spex issue ls` lists every open concern in one place — the taste concerns finished sessions recorded locally, AND the forge's issues, store-tagged. Cluster the same concern yourself (use judgment — duplicates are a recurrence SIGNAL, not noise; fold them into one) and weigh by recurrence AND novelty — **recurrence is salience, not importance, so never just fix the highest count**: a sharp single-voice concern can outrank a popular gripe. For the ones worth acting on, `spex session new "<task>"` a worker to land it (mention the concern's node as `[[<id>]]` if it has one), then `spex issue ls resolve <id> --as accepted|landed` (or `rejected`, with a reply saying why) so the store reflects the decision. Report progress as you go and when the goal is complete. Your goal follows:
+You are a SpexCode supervisor — a **manager**, not a feature worker. Your work base is the main checkout (the repository root), NOT your own worktree: do all git via `git -C <root>`, everything else via the `spex` CLI, and never write feature code. This preset IS your complete playbook (dispatch → monitor → review → merge → close, and how to parallelize) — the CLI's own `spex help session` is the reference for every verb's exact semantics. Drive the goal: decompose it into worker-sized tasks and dispatch one worker per independent task (`spex session new "<task>"` — give each ONLY its task; a task about one specific node mentions it as `[[<id>]]`, which only sets the branch name and board attribution; the session's real node links come from what it edits), monitor with `spex session watch`, review proposals with `spex session review <id>`, dispatch the merge of good ones back to their own session (`spex session merge <id>`; the doer syncs the base into its own worktree first, so what reaches `<root>` is a trivial merge) and confirm it landed, then close. `<root>` is the fleet's ONE landing door — it takes one landing at a time, so a worker whose merge finds it mid-merge waits rather than racing, and you never fix up another lane's half-merged index yourself. Never let a worker self-merge; keep `spex spec lint` at 0 errors. To READ a worker's current state, use the one-shot snapshots (`spex session review <id>` or `spex session ls` — both return immediately); to WAIT for a worker, background `spex session wait <id>` — it is edge-triggered: it returns only when it OBSERVES the worker transition from non-actionable into an actionable status (an already-actionable arrival state does not return it), printing the observed status path — which is also how you wait for a dispatched merge to actually land; never block on `spex session watch`, which STREAMS forever and will freeze your turn. **Stay parked while your fleet runs:** after dispatching, background a `spex session wait <child>` per worker (per the manager loop) so that when you stop with children still working you land in `parked` — self-resuming on the next child transition — NOT `asking`; only go `asking` when you genuinely need the human. This matters because the dashboard **folds each child under you and shows YOUR own status for the whole group** (session-nesting, no child-status aggregation), so a supervisor that stays parked-while-they-run is what makes that folded group status honest. Two footguns that bite a fresh supervisor. First: before `spex session close <id>`, confirm the merge landed (`git -C <root> log -1` shows HEAD at the new merge commit) — closing an unmerged branch discards the work. Second: `<id>` always names a WORKER YOU DISPATCHED, spelled out — never `.` and never your own id. `.` means the session running the command, so `close .` deletes your own worktree, branch and record mid-turn and takes your fleet's manager down with it; your own ending is a declaration (`done --propose close`), never a close you run on yourself. **DRAIN THE ISSUES** (issues / local-issues) as part of your loop: `spex issue ls` lists every open concern in one place — the taste concerns finished sessions recorded locally, AND the forge's issues, store-tagged. Cluster the same concern yourself (use judgment — duplicates are a recurrence SIGNAL, not noise; fold them into one) and weigh by recurrence AND novelty — **recurrence is salience, not importance, so never just fix the highest count**: a sharp single-voice concern can outrank a popular gripe. For the ones worth acting on, `spex session new "<task>"` a worker to land it (mention the concern's node as `[[<id>]]` if it has one), then `spex issue ls resolve <id> --as accepted|landed` (or `rejected`, with a reply saying why) so the store reflects the decision. Report progress as you go and when the goal is complete. Your goal follows:

package/spec-cli/templates/spec/project/.plugins/core/comment-altitude/spec.md

@@ -0,0 +1,28 @@
+---
+title: comment-altitude
+surface: system
+status: active
+hue: 200
+desc: A config plugin — code comments navigate non-obvious local reasoning; specs own product intent and contract.
+---
+Code comments are navigation aids, not a second specification. The owning spec body is the current contract:
+intent, invariants, externally observable behavior, and product policy belong there once, rather than being
+restated beside each implementation.
+
+Before retaining or adding a comment, ask in this order:
+
+1. Does it state intent or a contract? Put that fact in the owning spec body if it is not already there, then
+   remove the code comment.
+2. Does it explain a non-obvious local decision — ordering, a platform or library behavior, a measured pitfall,
+   or why an otherwise plausible implementation is unsafe? Keep a short comment beside the decision. It should
+   name the fact the reader cannot recover from code alone, not re-explain the whole feature.
+3. Does it merely translate the next line or restate a type/name? Remove it.
+
+Never turn subtraction into amnesia. A measured value, version-specific behavior, rejected alternative, or other
+implementation fact absent from the spec must remain in code unless it is truly product contract, in which case
+move the fact to the spec before deleting the comment. `@@@title - explanation` is reserved for the genuinely
+tricky local reasoning that survives this test; a tag is not a license to repeat the spec.
+
+This division gives each information channel one repair path: a changed product promise updates its spec; a changed
+implementation hazard updates its nearby comment; code that makes either false updates both as their distinct facts
+require. The rule complements [[spec-first]]: reading the contract first is what makes redundant code prose visible.

package/spec-cli/templates/spec/project/.plugins/core/mark-active/mark-active.sh

@@ -1,7 +1,9 @@
 #!/usr/bin/env bash
-# @@@ mark-active - the SINGLE freshness hook, wired to BOTH UserPromptSubmit and PreToolUse. It branches
-# on ONE structured signal read straight from the hook payload (stdin JSON), so the state is HARD — never
-# text-sniffed from the TUI:
+# @@@ mark-active - the SINGLE turn-boundary hook, wired to BOTH UserPromptSubmit and PreToolUse. It does two
+# jobs, both keyed off the session's global record dir: it keeps the declared FRESHNESS state honest, and it
+# delivers the session's unread MAIL.
+# Freshness branches on ONE structured signal read straight from the hook payload (stdin JSON), so the state is
+# HARD — never text-sniffed from the TUI:
 #   the agent is pausing to ask the HUMAN (hp_is_ask) → status: asking, with the question text as the note
 #                                  (the deterministic capture of a question).
 #   any other tool, or a prompt submit → the agent is working → status: active (drop a now-stale proposal/note).
@@ -34,6 +36,44 @@ rec="$sdir/session.json"
 # board-lifecycle gate: only a GOVERNED (dashboard-launched) session has a board state to maintain.
 grep -q '^[[:space:]]*"governed"[[:space:]]*:[[:space:]]*true,\?$' "$rec" 2>/dev/null || exit 0
 
+# @@@ the mail read - this hook is the ONE reader of the session's inbox ([[session-timeline]]): a message is
+# delivered by being appended to timeline.ndjson, and the agent finds it here, by mechanism, at a turn
+# boundary — never by remembering to run a command. `cursors.json` names how far this session has been shown
+# ([[session-cursors]]); everything past it is unread, the `sent` lines among it are printed as context, and
+# the cursor advances past ALL of it (a session's own status lines are not mail, but they are consumed, so
+# they can never come back as one).
+# Pure bash builtins, no forks: the common case is "no new lines", and the fast path must not cost a spawn.
+# The read is generous where it cannot be exact — an unparseable cursor reads as 0, which re-shows a message
+# rather than skipping one.
+mail() {
+  local tl="$sdir/timeline.ndjson" cur="$sdir/cursors.json" pos=0 i=0 line body unread=""
+  [ -f "$tl" ] || return 0
+  if [ -f "$cur" ]; then
+    while IFS= read -r line; do
+      case "$line" in
+        *'"inbox":'*) line="${line#*\"inbox\":}"; line="${line%%,*}"; line="${line// /}"; line="${line//$'\t'/}"
+                      case "$line" in ''|*[!0-9]*) ;; *) pos=$line ;; esac; break ;;
+      esac
+    done < "$cur"
+  fi
+  while IFS= read -r line; do
+    if [ "$i" -ge "$pos" ]; then
+      case "$line" in
+        *'"kind":"sent"'*) body=$(hp_field "$line" text)
+                           [ -n "$body" ] && unread="$unread$body"$'\n\n' ;;
+      esac
+    fi
+    i=$((i + 1))
+  done < "$tl"
+  # No mail → no cursor write. Unread STATUS lines alone leave the cursor where it is: they print nothing, so
+  # advancing past them would buy nothing and cost a spawn on almost every turn. The next scan re-reads them
+  # and still prints nothing.
+  [ -n "$unread" ] || return 0
+  printf 'Messages addressed to you (delivered to your session log while you were working):\n\n%s' "$unread"
+  ${SPEX:-spex} internal session-cursor inbox --session "$sid" --to "$i" >/dev/null 2>&1
+}
+mail
+
 # does FIELD's line hold exactly VALUE? The record is written one-field-per-line by the single writer
 # (sessions.ts writeRecord), so a whole-line match is exact — and, unlike a value regex, it cannot be fooled
 # by an escaped quote inside a neighbouring note.

package/spec-cli/templates/spec/project/.plugins/core/mark-active/spec.md

@@ -15,6 +15,8 @@ The state is read from ONE structured field in the hook payload, never sniffed f
 
 The one activity that does NOT count as the session acting is an IN-PROCESS SUBAGENT's tool call (the harness's Task tool — a sub-conversation inside the same process). Such a call fires the parent's hooks carrying the parent's `session_id`, so without a discriminator a supervising parent could never hold a declared state: its own subagents erased every park/ask within seconds and raced the stop-gate into "undeclared stop". The harness stamps subagent-executed calls with a top-level `agent_id` field the parent's own calls never carry; `hp_is_subagent` reads that stamp deterministically (scanning only the pre-`tool_input` payload prefix, where a tool parameter or file content can never fake an unescaped key), and this hook skips the flip entirely. A subagent working is its parent supervising, not the parent moving on — the parent's own next tool call still flips as before.
 
-It is a board-lifecycle hook, so it acts only on a GOVERNED (dashboard-launched) session — it resolves that session's record in the global per-session store from the payload's `session_id` and no-ops unless `governed: true`. The state it writes lives in that record's `session.json` (state), which it edits directly in shell (the hot path stays jq-free).
+It is a board-lifecycle hook, so it acts only on a GOVERNED (dashboard-launched) session — it resolves that session's record in the global per-session store from the payload's `session_id` and no-ops unless `governed: true`. The state it writes lives in that record's `session.json` (state), but it never edits that file itself: it READS it in pure shell (whole-line matches, the hot path stays jq-free) and hands every write to `spex internal session-state`, the one structured writer the CLI declarations use — an asking note is arbitrary prose, and a shell that substitutes prose into existing JSON eventually writes a record nothing can parse.
+
+This hook is also the session's MAIL READER, and that is the same job seen from the other side: a message is delivered by being appended to the session's log (session-timeline), and a turn boundary is exactly when the agent can be shown one. It reads the lines past its own inbox cursor (session-cursors), prints the message bodies so the harness injects them as context, and advances the cursor through `spex internal session-cursor`. So an agent finds its unread mail by mechanism, never by remembering to run a command — identical for a dashboard-launched and a self-launched agent. The scan is pure builtins and writes nothing when there is no mail, so the every-tool-call case still costs no spawn.
 
 This is the freshness half of the [[core]] discipline: it keeps the board honest about whether a session is working, waiting, or asking, so the gates and the dashboard read a true present state rather than a stale one.

package/spec-cli/templates/spec/project/.plugins/core/stop-gate/stop-gate.sh

@@ -129,7 +129,7 @@ fi
 # of the full-to-terse information gap is recoverable from the entry, none of it from memory.
 taught="$sdir/stop-gate-taught"
 if [ -f "$taught" ]; then
-  printf '{"decision":"block","reason":"undeclared stop — pick the ONE true state and declare it as the LAST call of your turn: `%s session <done --propose merge|nothing|close / park --note <what-you-await> / ask --note <your-question>>`. Which choice is true (and why park is never a default): `%s help session`."}\n' "$S" "$S"
+  printf '{"decision":"block","reason":"undeclared stop — declare the ONE true state as your LAST call: `%s session <done --propose merge (review; ONLY clickable merge)|nothing (done; no merge)|close (close-pending) / park (parked; real background wake-up) / ask (asking; human reply)>`. Conditions: `%s help session`."}\n' "$S" "$S"
   exit 0
 fi
 touch "$taught" 2>/dev/null || true
@@ -143,5 +143,5 @@ touch "$taught" 2>/dev/null || true
 # tool calls honestly re-flips the record to active (mark-active, by design) and re-blocks the next stop;
 # this block text is the one place every undeclared stopper is guaranteed to read, so the teaching that
 # kills the park->block->re-park loop at its source lives here.
-printf '{"decision":"block","reason":"Your session state is a CLAIM the graph, your supervisor, and other agents act on — not a box to tick to end the turn. Stopping undeclared makes your outcome a guess. Pick the ONE that is TRUE right now and run `%s session <choice>`, choosing the <choice> whose condition holds:\\n  • done --propose merge  — spec+code COMMITTED on the branch and genuinely ready for a human to review/merge (not just probably-done).\\n  • done --propose nothing — committed, but you are NOT proposing a merge; paused for the human to look.\\n  • park --note <what-you-await> — ONLY when a real BACKGROUND TASK will wake you (a spex session wait you backgrounded, a running build/job). If nothing is actually running to resume you, you are NOT parked — you are waiting on the human, so use ask; never use park as a default to clear this gate.\\n  • done --propose close — you propose discarding this worktree.\\n  • ask --note <your-question> — you need the human: a real question, or you are simply stopped awaiting direction; you resume only when they reply.\\n\\nDECLARE LAST, THEN STOP: finish everything else in the turn first — speak, send your messages, arm your background waits — and make the declaration your FINAL call. Any tool call AFTER it flips your record back to active (mark-active, by design: activity is activity), so the next stop re-blocks and demands a fresh declaration; declaring last kills that loop at its source.\\n\\n(This full explanation shows once per session; later undeclared stops get a one-line reminder. `%s help session` re-explains the choices any time.)"}\n' "$S" "$S"
+printf '{"decision":"block","reason":"Your session state is a CLAIM the graph, your supervisor, and other agents act on — not a box to tick to end the turn. Stopping undeclared makes your outcome a guess. Pick the ONE that is TRUE right now and run `%s session <choice>`, choosing the <choice> whose condition holds:\\n  • done --propose merge  — spec+code COMMITTED on the branch and genuinely ready for human review. It declares REVIEW and is the ONLY proposal that offers a clickable merge.\\n  • done --propose nothing — committed, but you are NOT proposing a merge; paused for the human to look. It declares DONE, never a merge.\\n  • done --propose close — you PROPOSE discarding this worktree; the human performs the close. It declares CLOSE-PENDING, not merge. This is how a session ends ITSELF — never run `session close` on your own id, which would delete your worktree mid-turn.\\n  • ask --note <your-question> — you need the human: a real question, or you are simply stopped awaiting direction. It declares ASKING and resumes only when they reply.\\n  • park --note <what-you-await> — ONLY when a real BACKGROUND TASK will wake you (a spex session wait you backgrounded, a running build/job). It declares PARKED and self-resumes. If nothing is actually running, you are waiting on the human: use ask, never park as a default.\\n\\nDECLARE LAST, THEN STOP: finish everything else in the turn first — speak, send your messages, arm your background waits — and make the declaration your FINAL call. Any tool call AFTER it flips your record back to active (mark-active, by design: activity is activity), so the next stop re-blocks and demands a fresh declaration; declaring last kills that loop at its source.\\n\\n(This full explanation shows once per session; later undeclared stops get a one-line reminder. `%s help session` re-explains the choices any time.)"}\n' "$S" "$S"
 exit 0

package/spec-cli/templates/spec/project/.plugins/skills/distill/spec.md

@@ -54,6 +54,11 @@ Only after verifying the salvage is present (or the branch truly merged), retire
 `spex session close <id>`, or remove a bare worktree and then its branch. If proof is incomplete, keep the
 resources and report why.
 
+`<id>` is the OLD session's id — the one you are inheriting, spelled out. It is never `.` and never your own
+id: `.` means THIS session (the rename step below relies on that), and closing yourself deletes the worktree
+you are running in, mid-turn, along with your branch and record. Retiring the source is the only close this
+skill asks for; your own ending stays a declaration.
+
 ## Rename yourself
 
 Last step: mark the inheritance on the board. If you run as a SpexCode session (inside a session

package/spec-cli/templates/spexcode.json

@@ -5,6 +5,18 @@
   "dashboard": {
     "showHeadlessLaunchers": false
   },
+  "uploads": {
+    "maxBytes": 2147483648,
+    "chunkBytes": 8388608,
+    "concurrency": 1,
+    "requestTimeoutMs": 120000,
+    "retryLimit": 2,
+    "retryDelayMs": 500,
+    "incompleteTtlMs": 86400000,
+    "cleanupIntervalMs": 3600000,
+    "minFreeBytes": 268435456,
+    "evidenceMaxBytes": 52428800
+  },
   "sessions": {
     "launchers": {
       "claude": { "harness": "claude", "cmd": "claude" },