spexcode 0.6.1 → 0.6.5

package/README.md

@@ -18,211 +18,161 @@
 
 </div>
 
-Spec-driven development with AI agents in the loop. SpexCode keeps a versioned tree of specs inside
+Spec-driven orchestration for your coding agents. SpexCode keeps a versioned tree of specs inside
 your git repo, links every spec to the code it governs, and runs a session manager that dispatches
 coding agents into isolated worktrees. You review and merge; the tool keeps intent and
 implementation from drifting apart.
 
-[![Watch: this repo's spec tree grow from its git history](docs/spec-tree-poster.jpg)](https://spexcode.net/assets/spec-tree-growth.mp4)
-
-<sub>▶ This repo's own spec tree, replayed from its git history — 160 spec nodes growing over three weeks. Click for the [full video](https://spexcode.net/assets/spec-tree-growth.mp4).</sub>
-
 English | [中文](./docs/README.zh-CN.md) · Docs: [spexcode.net](https://spexcode.net) · License: MIT
 
-Quick links: [the model](#the-model) · [quick start](#quick-start) ·
-[agents](#working-with-agents) · [eval](#measuring-behavior-eval) · [config](#configuration)
+| Feature | Description |
+|---|---|
+| **Computable spec–code drift** | Every spec pins the file it governs, down to the function. Whether code moved without its spec is computed from commits and line ranges, the same way on every machine: advisory for the file, blocking when an anchored function changes. |
+| **Session & worktree management** | Each task runs in its own worktree and branch; independent tasks run in parallel. Sessions form a hierarchy: a session can dispatch and supervise workers of its own, so a worker can have a supervisor and that supervisor another. Workers propose; you review once, at merge time. |
+| **Shareable URLs** | Spec nodes, sessions, evals, live terminals: every dashboard view has a stable address you can send to a colleague. Two people can watch the same session board. |
+| **Modular layers** | Three separable layers: the spec↔code data asset (L0), the session substrate (L1), the dashboard (L2). Take what you need; L0 and L1 are building bricks for your own software factory. |
+| **Cross-harness support** | Claude Code, Codex, OpenCode, pi, each interactive or headless. One materialized workflow contract serves them all; adding a harness is a config entry. |
 
 ## The model
 
-<div align="center"><img src="docs/sdd-tuxedo-pooh.png" alt="spec-driven development meme" width="260"></div>
-
-A spec node is a directory under `.spec/` containing a `spec.md`: frontmatter (title, status, a
-`code:` pointer to the file it governs, a `related:` list for files it references) plus a prose
-body stating what that part of the system is supposed to do, right now. Nodes nest, so the tree
-mirrors how you think about the project rather than the file layout. The body can split into two
-labelled parts. The short **raw source** states the intent; changing it takes explicit
-human approval (an agent can draft it, a human signs off). The **expanded spec** is the agent's
-detailed reading of that intent; it iterates freely but must always match the raw source.
+A spec node is a directory under `.spec/` holding a `spec.md`: frontmatter naming the one file it
+governs (`code:` — optionally pinned to specific functions with `path#symbol`) and the files it
+references (`related:`), then a prose body stating what that part of the system is supposed to do,
+right now. Nodes nest, so the tree mirrors how you think about the project rather than the file
+layout. The body can split into two labelled parts: a short **raw source** a human signs off on, and
+an **expanded spec** the agent iterates freely — as long as it keeps matching the raw source.
 
-<img src="docs/readme-node.png" alt="spec node popup">
+<img src="docs/readme-model.svg" alt="a spec node governs one file, anchored at function level; related files are referenced; git is the only database">
 
-Two rules make this workable:
+Git is the only database: a node's versions are the commits that touched its
+`spec.md`. A change is one commit that updates both the spec and the code it justifies. When code
+moves alone, the linter notices:
 
-1. **Git is the database.** There is no separate store. A node's version count is the number of
-   commits that changed its `spec.md`, its history view is `git log` on that file, and each version
-   is attributed to an agent session through a `Session:` commit trailer. This is also why a spec
-   body always describes present intent and gets rewritten in place: changelog headings inside the
-   body are banned (the linter enforces it), because git already keeps the history.
-2. **Spec and code land together.** A change is one commit that updates both the `spec.md` and the
-   code it justifies. When code moves without its spec, the linter flags it,
+<img src="docs/readme-drift-flow.svg" alt="one real drift: spec and code land together, six days of code-only commits later a rename hits the anchored function — the commit is flagged and blocked">
 
-   ```
-   drift: spec-cli/src/graph.ts is 1 commit(s) ahead of spec 'graph-lean' (v12) — may be stale
-   ```
+The check compares plain git facts: which commits came after the spec's last version, and whether
+they intersect the anchored unit's lines. It cannot judge whether the new behavior is better, only
+that the spec stopped describing it. The commit in the diagram updated seven other specs in the
+same rename and missed this one; that kind of miss is normal work, and it is what a mechanical
+check catches.
 
-   and keeps flagging until the spec catches up.
+## Software as heuristic learning
 
-## The optimization loop
+Specs, commits, and evals compose into one optimization loop. The spec is the loss function: it
+states what you want, and it is the half a human signs off on. Commits are the optimizer. **eval**,
+the measurement subsystem, scores how far live behavior currently sits from the spec — an agent runs
+each scenario against the product's real surface, the way an end user would touch it, and files the
+result with evidence (a screenshot, a recording). The score's history lives in git like everything
+else, and a bug fix is expected to bracket: a failing eval that reproduces the bug, then a passing
+one on the same scenario.
 
-Specs, commits, and evals compose into one loop. The spec is the loss function: it states what you
-want, and it's the half a human signs off on. Commits are the optimizer. **eval**, the measurement
-subsystem, scores how far live behavior currently sits from the spec, and the
-score's history lives in git like everything else.
+<div align="center"><img src="docs/readme-loop.svg" alt="the spec/code optimization loop" width="560"></div>
 
-<img src="docs/readme-loop.png" alt="the spec/code optimization loop">
-
-It also settles where the human stands day to day: nobody reads a neural net by staring at its
-weights, and between merge gates you don't have to stare at agent diffs either. Attention goes to
-the spec and the evals; the diff gets read once, at merge time.
+Nobody reads a neural net by staring at its weights, and between merge gates you don't stare at
+agent diffs either. Attention goes to the two ends — the spec and the evals; the diff gets read
+once, at merge time.
 
 ## Quick start
 
-Requires Node ≥ 22 and git. This part is plain tooling — no AI involved yet.
+Requires Node ≥ 22 and git.
 
 ```sh
 npm i -g spexcode                              # installs the `spex` command
 cd your-repo
-spex init --harness claude,codex,opencode,pi,claude-headless,opencode-headless,pi-headless,codex-headless   # seeds .spec/, installs hooks, materializes the agent contracts
+spex init --harness claude,codex,opencode,pi,zcode,claude-headless,opencode-headless,pi-headless,codex-headless   # seeds .spec/, installs hooks, materializes the agent contracts
 ```
 
-That's the whole adoption. The example lists all the built-in harnesses — remove the ones you don't
-use: `--harness` is required, has no default, and takes any one id or comma-separated subset.
-`spex init` is additive: it works on any existing git repo and never
-overwrites your files — it creates a root `.spec/project/spec.md` and a starter `spexcode.json`,
-installs the git hooks, and writes the selected harness's managed contract, so any agent working in
-the repo discovers the workflow on its own.
+That's the whole adoption. The example lists all the built-in harnesses; remove the ones you don't
+use (`--harness` is required and takes any one id or comma-separated subset).
+`spex init` is additive: it works on any existing git repo, never overwrites your files, and does
+three things. It seeds a root `.spec/project/spec.md` plus a starter `spexcode.json`, installs the
+git hooks, and **materializes** the workflow rules into the files your agent already reads
+(`CLAUDE.md`, `AGENTS.md`): read the governing spec before the code, land spec and code in one
+commit, propose merges instead of performing them. Any agent that opens the repo discovers the
+workflow on its own.
 
-When you want the live board — the graph, sessions, evals — start the runtime:
+When you want the live board (the graph, sessions, evals), start the runtime:
 
 ```sh
-spex serve       # this project's backend — prints its URL, registers itself for your user
-spex dashboard   # once per user, any directory: the one dashboard — open the URL it prints
+npm i -g @spexcode/spec-dashboard # install the optional UI package once
+spex serve       # this project's backend — prints its URL
+spex dashboard   # the machine's one gateway — every project behind one URL
 ```
 
-Run `spex serve` from each project you want online. Every backend registers itself, and the single
-`spex dashboard` finds them all — backends already running and ones you start later, in any order.
-`/projects` switches and manages projects; each project's board lives under `/p/:id/`. There is no
-per-project dashboard process and no port pairing to remember: if a port is taken, give that
-backend its own with `spex serve --port <n>`, and trust the URL each command prints.
-
-Those are installed-user commands. Contributors working from this source checkout use `npm run api`
-for the reloadable backend and `npm run web` for the Vite/HMR frontend; see
-[Contributing](#contributing).
-
-Then grow the tree:
-
-1. Edit `.spec/project/spec.md` to describe the project.
-2. Add child nodes for the parts you want governed, each with a `code:` entry pointing at an
-   existing file (`related:` for the files it touches but doesn't own).
-3. Run `spex spec lint`. Coverage warnings list the source files no spec claims yet; that list is your
-   adoption TODO.
+The dashboard is a separate package so writing-only installs do not carry frontend build output. One `spex dashboard`
+per machine is enough: every project you serve shows up behind it, and its
+`/projects` page manages them from the browser.
+[Getting started](https://spexcode.net/getting-started/) walks the rest of the setup.
 
-You are not expected to hand-author all of this. The intended workflow is to have an agent do most
-of the spec writing; `spex guide spec` prints the exact file format it needs.
-[Getting started](https://spexcode.net/getting-started/) on the docs site walks the setup end to
-end.
+## How does this system work
 
-<img src="docs/readme-graph.png" alt="dashboard screenshot">
+Three stacked layers, and each is worth having without the ones above it:
 
-*SpexCode's own repo on its own board; the sessions top-left are agents building the tool.*
+<img src="docs/readme-layers.svg" alt="L0 the spec-code data asset, L1 the agent session substrate, L2 the dashboard workspace — an adoption ladder">
 
-## Working with agents
+L0 is the asset an organisation adopts and keeps: plain files in plain git, useful offline.
+([Watch this repo's own L0 grow from its git
+history](https://spexcode.net/assets/spec-tree-growth.mp4), 160 spec nodes over three weeks.)
+L1 puts agents to work on that asset: the session state machine below. L2 is the workspace you
+watch it all from, and because it is only a consumer of L1, anything the dashboard does, your
+scripts and agents can do through the same CLI.
 
-This part needs tmux and a logged-in [Claude Code](https://www.anthropic.com/claude-code) or Codex
-on the machine.
+## Working with agents (L1)
 
-```sh
-spex session new "[[settings]] make the settings page remember the last tab"
-```
-
-launches a worker session in its own worktree on branch `node/settings-…`. The prompt's first
-`[[settings]]` mention sets the branch name and board attribution; the
-worker still finds and reads the governing spec itself before touching code. It makes the change,
-rewrites the spec body to match, commits
-both (a hook stamps the `Session:` trailer), then proposes a merge and stops. Workers never merge
-themselves. The merge stays with the manager: when you fire it, the session's own agent runs the
-actual `git merge`, so conflicts land on the one who knows the work. The same dispatch is a
-button on the dashboard (the new-session box on the board); the command form is what agents
-themselves use when they delegate.
-
-You supervise from outside — on the board, or with the same commands your agent uses:
+This part needs tmux on the machine (on Windows, run inside WSL2).
 
 ```sh
-spex session watch              # stream session transitions: launched / review / done / needs-input ...
-spex session review settings    # commits ahead of trunk, merge-base diff, merge-conflict/lint gates
-spex session merge settings     # gated merge into the trunk
-spex session close settings
+spex session new "[[uploader]] retry failed chunks with backoff"
 ```
 
-Independent tasks run in parallel. Each worker is isolated in its own worktree, git serializes the
-merges, and a pre-commit guard blocks direct commits on the trunk, so everything flows through
-reviewable node branches.
+launches a worker session in its own worktree on branch `node/uploader-…`. The prompt's first
+`[[uploader]]` mention sets the branch name and board attribution; the worker finds and reads
+the governing spec before it changes code. It makes the change, rewrites the spec body to
+match, puts both in one commit, then files a merge proposal and stops:
 
-The process is enforced by mechanism, not prompt engineering: the backend creates the branch and a
-hook stamps the attribution; the materialized contract block carries the rest, so your dispatch
-prompt stays task-only. More on this mode of working:
-[working with agents](https://spexcode.net/working-with-agents/).
-
-## Measuring behavior: eval
-
-eval is the measuring half of
-[the loop](#the-optimization-loop), built on the YATU discipline (**You As The User**): you measure
-behavior from the product's real surface, the way a real end user would touch it, not through an
-internal helper or shortcut that makes the
-proof easy. A spec says what a part should do; an
-`eval.md` beside it says how to check. Each scenario is a plain description plus an expected
-result. eval itself runs nothing (no DSL, no runner). An agent runs the scenario however it can:
-a test file, a real browser, or just clicking through by hand and screenshotting. It compares
-actual to expected and files the eval with evidence:
+<img src="docs/readme-worker-flow.svg" alt="the eight-step worker loop: dispatch, read the spec, do the work, run evals, clear drift, propose a merge, human review, close">
 
 ```sh
-spex eval add settings --scenario remembers-tab --pass --image evidence.png
+spex session ls                  # the living table below
+spex session watch stream        # follow transitions: working → review → done …
+spex session review uploader     # commits ahead of trunk, merge-base diff, merge/lint gates
+spex session merge uploader      # hands the gated merge to the session's own agent
+spex session close uploader      # retire the worktree, branch, and record
 ```
 
-Evals live in a git-tracked ndjson next to the spec, so measurements get the same attribution
-and history as spec versions. Bug fixes are expected to bracket: file a failing eval that
-reproduces the bug, fix, then file a passing eval on the same scenario.
+<img src="docs/readme-sessions.svg" alt="animated terminal: spex session ls listing five sessions across working, review, asking and done states">
 
-<img src="docs/readme-eval.png" alt="eval view screenshot">
+Each rule has a mechanism enforcing it: the backend creates the branch, a git hook attributes
+every commit to its session, a pre-commit guard rejects direct commits to the trunk, and the
+remaining conventions live in the materialized `CLAUDE.md`/`AGENTS.md`. Your dispatch prompt only
+has to state the task. More: [working with agents](https://spexcode.net/working-with-agents/).
 
-*The eval view: scenario evals on the left; the selected eval's expected result, staleness,
-and recorded video evidence in the middle.*
+## The dashboard (L2)
 
-## What's in the repo
-
-| Package | Role |
-|---|---|
-| `spec-cli` | The `spex` CLI and the HTTP backend (Hono, runs via tsx, no build step). Reads `.spec` and git live; owns the session state machine and the linter. |
-| `spec-dashboard` | React board: the node graph, per-node spec/history/issues panes, and a real terminal onto each live agent session. |
-| `spec-eval` | Scenario definitions, evals, evidence. |
-| `spec-forge` | Read-only tracer that resolves a forge's open issues and PRs to the spec nodes they serve (GitHub and GitLab drivers today). An issue links itself with a `Spec: <node-id>` line in its body; a PR from a `node/<id>` branch links for free. |
+The spec tree, the sessions, and the evals each have a live page on the dashboard. Start `spex serve` and `spex dashboard`, then:
 
-## The linter
+<img src="docs/readme-graph.png" alt="the spec map: SpexCode's own repo on its own board — per-node version and eval chips, an agent avatar hovering on the node it is editing">
 
-`spex spec lint` checks the spec↔code graph and is the real gate (the git hook is fast local feedback):
+*Your whole repo as one map — SpexCode's own board shown. Each node carries its version and eval
+state, an agent's avatar hovers on the node it is editing right now, and the rail top-left is the
+live session console.*
 
-- **integrity** (error): a `code:` or `related:` path that doesn't exist
-- **living** (error): a changelog heading in a spec body
-- **coverage** (warn): unclaimed source files
-- **drift** (warn): governed code changed after its spec's last version, derived live from git
+<img src="docs/readme-node.png" alt="a node opened on the board: the raw source callout, the expanded spec body, the governed file, a drift badge, and tabs for history, issues, eval">
 
-plus naming and ownership rules (`one-govern`, `id-format`, `mention` as errors;
-`related-drift`, `owners`, `confusable-id` as warns) — `spex guide spec` lists them all.
+*Click a node: the raw source on top, the expanded spec below it, the file it governs, its current
+drift state, and tabs for the version history git already kept, its issues, and its evals.*
 
-`spex doctor` is the opt-in, read-only health diagnosis. Its altitude and breadth checks report bodies that
-look like implementation dumps and nodes with wide child fan-out, with per-node evidence and repair, without
-putting heuristic judgment in the lint or commit gate.
+<img src="docs/readme-eval.png" alt="an eval reading under review: verdict banner, the scenario's expected result, the agent's note, recorded video evidence, and the review queue">
 
-## Configuration
+*An eval reading under review: the verdict, the scenario's expected result, the agent's note and
+recorded video evidence. You can draw a region on the video to annotate it; the annotation is
+matched to its step automatically, and the timestamp and step are sent to the agent with your
+comment. The queue on the right leads to the next reading.*
 
-`spexcode.json` (committed, portable: layout, lint policy, doctor health budgets, project dashboard identity, launcher names) and
-`spexcode.local.json` (gitignored, host-specific: absolute launcher paths, cert paths) cover every
-setting. There is no imperative settings verb: you edit the two files by hand (or ask your agent
-to), and `spex guide settings` documents every field. The Projects admin UI writes a project's icon back
-to that same `dashboard.icon` field; the global gateway icon is the one separate host fact at
-`$SPEXCODE_HOME/config.json` `gateway.icon`, never copied into a repo. The other
-manuals are `spex guide` (the workflow), `spex guide spec`, `spex guide eval`, and
-`spex guide footprint`; `spex help` maps the commands.
+The whole workspace is served over HTTP, so every view (a spec node, a session, an eval reading, a
+live terminal) is a stable URL you can hand to a colleague; you can sit on the same board together.
+The terminal pane is a real tmux session: copy the printed command and attach from your own
+terminal.
 
 ## Contributing
 

package/bin/spex.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+// @@@ root release launcher ([[release-launcher]]) - the metapackage owns one command and delegates all
+// product behavior to the independently compiled CLI package.
+import '@spexcode/spec-cli/bin/spex.mjs'

package/node_modules/@spexcode/spec-cli/bin/spex.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+// @@@ spex launcher ([[release-launcher]]) - package installs execute the package's compiled CLI directly;
+// tsx remains a development tool and never enters an adopter's runtime closure.
+import { spawn, spawnSync } from 'node:child_process'
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+
+// Resolve from THIS package rather than cwd, so global and project-local installs run one compiled CLI.
+const pkg = join(dirname(fileURLToPath(import.meta.url)), '..') // spec-cli/
+const cli = join(pkg, 'dist', 'cli.js')
+const workspace = join(pkg, '..')
+
+// @@@ mid-merge guard ([[merge-tooling-resilience]]) - a released package contains no source to scan;
+// a source workspace does. Refuse to run its possibly stale dist while its imported source trees still
+// carry unresolved conflict markers, so hooks keep the retryable exit-75 contract during a merge.
+const sourceRoot = join(pkg, 'src')
+if (existsSync(sourceRoot)) {
+  const srcRoots = [sourceRoot, join(pkg, '..', 'packages', 'spec-core', 'src'), join(pkg, '..', 'spec-eval', 'src'), join(pkg, '..', 'spec-forge', 'src')]
+  const conflicted = srcRoots.flatMap((root) => {
+    if (!existsSync(root)) return []
+    return readdirSync(root, { recursive: true })
+      .filter((f) => /\.(ts|tsx|js|mjs)$/.test(String(f)))
+      .map((f) => join(root, String(f)))
+      .filter((path) => {
+        try { return /^<{7} /m.test(readFileSync(path, 'utf8')) } catch { return false }
+      })
+  })
+  if (conflicted.length) {
+    console.error('spex: paused mid-merge - unresolved conflict markers in the source SpexCode runs:')
+    for (const file of conflicted) console.error(`  ${file}`)
+    console.error('resolve the merge, rebuild SpexCode, then retry. (exit 75)')
+    process.exit(75)
+  }
+
+  // @@@ source-workspace build ([[release-launcher]]) - the git hooks invoke this launcher straight from a
+  // checkout, where dist is intentionally untracked. Rebuild the complete runtime closure before linting
+  // candidate source; an installed package has no src tree and stays a pure Node -> dist execution path.
+  const runtimeEntries = [
+    cli,
+    join(workspace, 'packages', 'spec-core', 'dist', 'index.js'),
+    join(workspace, 'spec-eval', 'dist', 'index.js'),
+    join(workspace, 'spec-forge', 'dist', 'index.js'),
+  ]
+  const newestSource = srcRoots.reduce((newest, root) => {
+    if (!existsSync(root)) return newest
+    for (const entry of readdirSync(root, { recursive: true })) {
+      const path = join(root, String(entry))
+      try {
+        if (/\.(ts|tsx|js|mjs)$/.test(path)) newest = Math.max(newest, statSync(path).mtimeMs)
+      } catch { /* a concurrent source edit can only make the next invocation rebuild again */ }
+    }
+    return newest
+  }, 0)
+  const rebuild = runtimeEntries.some((entry) => {
+    try { return statSync(entry).mtimeMs < newestSource } catch { return true }
+  })
+  if (rebuild) {
+    const build = spawnSync('npm', ['run', 'build'], { cwd: workspace, stdio: 'inherit' })
+    if (build.error || build.status !== 0 || !existsSync(cli)) {
+      console.error('spex: source workspace build failed; fix it, then retry.')
+      process.exit(build.status ?? 1)
+    }
+  }
+}
+const args = process.argv.slice(2)
+const env = { ...process.env }
+// A backend/dashboard is a project or host control plane, never the managed session that happened to start it.
+if (args[0] === 'serve' || args[0] === 'dashboard') {
+  const identityKeys = (env.SPEXCODE_SESSION_IDENTITY_VARS
+    || 'SPEXCODE_SESSION_ID,CLAUDE_CODE_SESSION_ID,CODEX_THREAD_ID,OPENCODE_SESSION_ID,PI_SESSION_ID')
+    .split(',').map((key) => key.trim()).filter(Boolean)
+  for (const key of identityKeys) delete env[key]
+}
+spawn(process.execPath, [cli, ...args], { stdio: 'inherit', env })
+  .on('exit', (code) => process.exit(code ?? 0))

package/node_modules/@spexcode/spec-cli/dist/attach.d.ts

@@ -0,0 +1,2 @@
+export declare function assertLocalBackend(): Promise<void>;
+export declare function attachSession(id: string): Promise<number>;

package/node_modules/@spexcode/spec-cli/dist/attach.js

@@ -0,0 +1,48 @@
+import { spawnSync } from 'node:child_process';
+import { networkInterfaces } from 'node:os';
+import { alive, apiBase, TMUX_SOCK } from './sessions.js';
+const AGENT_ALTERNATIVES = 'read the pane with `spex session show <SEL> --capture`, drive it with `session send` (plain text first; `--keys` only as a last resort)';
+// attach only makes sense on the machine that runs the tmux server — the backend's. The board the selector
+// resolved against IS that backend, so the test is: does the RESOLVED backend (see [[remote-client]]'s
+// ladder — flag / worker env / cwd record / fallback) point at this machine? Loopback and any address this
+// host owns count as local; anything else (a tailnet/LAN IP of another box, a hostname we can't claim)
+// fails loud with the reason and the remote-capable alternatives, never a silent local fallback onto a
+// tmux socket that holds no sessions.
+export async function assertLocalBackend() {
+    const base = await apiBase();
+    let host;
+    try {
+        host = new URL(base).hostname;
+    }
+    catch {
+        host = '';
+    }
+    const mine = new Set(['localhost', '127.0.0.1', '::1', '[::1]']);
+    for (const addrs of Object.values(networkInterfaces()))
+        for (const a of addrs ?? [])
+            mine.add(a.address);
+    if (mine.has(host))
+        return;
+    console.error(`spex session attach: attach is LOCAL-only, and the resolved backend is another machine (${base}).
+The tmux session lives on THAT machine — a terminal can't be attached over HTTP. Either run attach there
+(e.g. over ssh), or ${AGENT_ALTERNATIVES} — those work remotely.`);
+    process.exit(2);
+}
+// foreground takeover of the session's real tmux window; returns only via detach (C-b d) or the session
+// ending. Interactive and blocking by design — a caller without a terminal (an agent inside its turn, a
+// pipe) is refused up front and pointed at the remote-capable verbs instead of tmux's bare "not a terminal".
+export async function attachSession(id) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        console.error(`spex session attach: attach is INTERACTIVE and needs a terminal — it blocks until you detach.
+An agent must not run it inside a turn (it freezes you); ${AGENT_ALTERNATIVES}.`);
+        process.exit(2);
+    }
+    if (!(await alive(id))) {
+        console.error(`spex session attach: ${id} is offline — no live tmux session to attach.
+Bring it back with \`spex session resume ${id}\`, or read its record with \`spex session show ${id}\`.`);
+        return 1;
+    }
+    console.log(`attaching to ${id} — detach with C-b d (the session keeps running)`);
+    const r = spawnSync('tmux', ['-u', '-L', TMUX_SOCK, 'attach-session', '-t', id], { stdio: 'inherit' });
+    return r.status ?? 1;
+}

package/node_modules/@spexcode/spec-cli/dist/claude-headless.d.ts

@@ -0,0 +1,33 @@
+import type { DispatchResult, HarnessDeliveryRecord } from './harness.js';
+type ClaudeHeadlessDeliveryRecord = HarnessDeliveryRecord & {
+    status?: string;
+};
+export declare const claudeHeadlessSock: (id: string) => string;
+export declare function claudeHeadlessLaunchCommand(id: string, runtimeDir: string, claudeCmd: string): string;
+export declare const deliverViaClaudeHeadless: (rec: ClaudeHeadlessDeliveryRecord, text: string) => Promise<DispatchResult>;
+export declare const interruptClaudeHeadless: (rec: HarnessDeliveryRecord) => Promise<DispatchResult>;
+export declare class ClaudeHeadlessController {
+    private readonly id;
+    private readonly claudeCmd;
+    private readonly cwd;
+    private server;
+    private child;
+    private controlQueue;
+    private closing;
+    private readonly socketPath;
+    constructor(id: string, _runtimeDir: string, claudeCmd: string, cwd?: string);
+    start(initialPrompt?: string): Promise<void>;
+    close(): Promise<void>;
+    private accept;
+    private handle;
+    private interrupt;
+    private spawnTurn;
+    private observeEvent;
+    private ensureTurnExit;
+    private terminateTurn;
+    private waitForTurnExit;
+    private signalTurn;
+    private writeLine;
+}
+export declare function runClaudeHeadlessController(id: string, runtimeDir: string, claudeCmd: string, tail: string[]): Promise<void>;
+export {};