crewforth 0.0.1 → 3.0.0-rc.2

package/kit/skills/threat-model/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: threat-model
+description: |
+  Scope a security audit BEFORE scanning, to cut false positives: map assets, entry points, trust boundaries
+  and 5-8 domain-specific attack classes into a parseable THREAT_MODEL.md. A threat survives a patch; a
+  vulnerability is only evidence for one. Feeds security-scan.
+---
+
+# Threat Model
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "threat model", "attack surface", "scope the audit", "trust boundary"
+
+Scope first, scan second. A security scan with no map produces noise; a threat model tells the scanner (and
+`security-scan`) **where to look and what matters** — the single biggest lever on false positives.
+
+The one idea to keep — the litmus test: **if patching one line of code makes an entry disappear, it was a
+vulnerability, not a threat.** Threats survive patching (they name *what an attacker wants and the surface they
+arrive through*); a vulnerability is only **evidence** that raises a threat's likelihood.
+
+> **Crewforth adaptation (local, .claude/):** `crew-security-expert` runs this to scope before `security-scan`. Output
+> `docs/THREAT_MODEL.md` is internal (§4.3). Stack-agnostic. §4 Prohibitions apply.
+
+## When
+- Before a first `security-scan` of a system, or when scan output is noisy / unscoped.
+- After a significant new surface — a new API, a new integration, a new trust boundary.
+
+## Two modes
+- **interview** — the owner is available: ask the four questions below, one at a time.
+- **bootstrap** — no owner: derive the model from code + past advisories, then flag what only the owner can confirm.
+
+## Method — the four questions (Shostack), one at a time
+Never dump a questionnaire; ask, capture into the schema, move on. Mirror the user's language.
+1. **What are we building?** system context, assets worth protecting, entry points and trust boundaries.
+2. **What can go wrong?** open-ended first; then, per entry point, fall back to **STRIDE**; derive **5-8
+   domain-specific attack classes** at the right granularity — "IDOR on dataset rows", "integer overflow on
+   length fields" — not "web vulnerabilities".
+3. **What are we doing about it?** impact · residual likelihood · status · controls per threat; "accept the
+   risk, with a written reason" (`risk_accepted`) is a valid answer.
+4. **Did we do a good job?** read the ranked table back; coverage-check that every entry point appears.
+
+Tag every fact **`[Code-verified]`** or **`[Owner-states]`**; each owner claim that moves a score becomes an
+open question with a "Verify by:" note.
+
+## Output
+Write `docs/THREAT_MODEL.md` to the parseable contract in **`references/schema.md`** (fixed sections; a threats
+table with enumerated columns; residual-likelihood scoring; class-level mitigations). The interview flow, the
+STRIDE table, and the bootstrap steps live in **`references/interview.md`**.
+
+## Principles
+- **Evidence raises likelihood; it is not the threat.** Score the *residual* likelihood after current controls;
+  a stated-but-unverified control does not lower it — it becomes an open question.
+- **Prefer a control that survives the next bug** over a patch for the last one (class-level mitigations).
+- **Feeds forward:** `security-scan` reads `THREAT_MODEL.md` to scope its fronts and bias severity.
+
+## DoD
+- `docs/THREAT_MODEL.md` exists; every entry point covered; each threat scored; provenance tagged; scope handed to `security-scan`.

package/kit/skills/threat-model/references/interview.md

@@ -0,0 +1,51 @@
+# Threat-model interview + bootstrap
+
+## Interview mode — Shostack four questions, ONE at a time
+Never present a questionnaire. Ask, capture into the schema, move on. Mirror the user's language.
+
+### 1 · What are we building?
+System context, assets, entry points, trust boundaries. Draw the boundary explicitly: *"untrusted input crosses
+into trusted code HERE."* List every entry point — this becomes section 3 and the coverage checklist.
+
+### 2 · What can go wrong?
+Open-ended first ("what would hurt most if it broke?"). Then, per entry point with nothing yet, walk **STRIDE**:
+
+| STRIDE | asks |
+|---|---|
+| **S**poofing | can someone pretend to be another principal? |
+| **T**ampering | can data / requests be modified in transit or at rest? |
+| **R**epudiation | can an action be denied, or does it go unlogged? |
+| **I**nformation disclosure | can data leak across a trust boundary? |
+| **D**enial of service | can availability be exhausted (beyond plain volumetric floods)? |
+| **E**levation of privilege | can a lower role reach a higher-privilege action? |
+
+Derive **5-8 domain-specific attack classes** at the right granularity — "IDOR on dataset rows", "integer
+overflow on length fields", "tenant bleed via a missing scope check" — **not** "web vulnerabilities". Granularity
+test: a class should name *a surface + a mechanism*, so the scanner knows exactly what to grep for.
+
+### 3 · What are we doing about it?
+For each threat: `impact`, residual `likelihood`, `status`, `controls`. "Accept the risk, with a written reason"
+(`risk_accepted`) is a legitimate status — record the reason verbatim in section 6.
+
+### 4 · Did we do a good job?
+Read the ranked table back to the owner. **Coverage check:** every entry point from Q1 appears in ≥1 threat's
+`surface`. Add anything missing before you emit.
+
+**Provenance discipline:** tag every fact **`[Code-verified]`** (you read it) or **`[Owner-states]`** (they said
+it). Every owner claim that changes a score becomes an open question in section 6 with **"Verify by: <how>."**
+
+## Bootstrap mode — no owner available
+1. **Map** (in parallel where the codebase is large): docs, the entry-point surface, infra / IAM, the assets,
+   and past advisories — `git log --all -i --grep=<stack keywords>`, `gh api repos/<o>/<r>/security-advisories`.
+2. **Generalize** each past vulnerability into a *threat*: cluster by `(entry point, bug class, asset reached)`.
+   Run a **variant scan** — grep for siblings of each vulnerable pattern — to estimate how much of the surface
+   shares it (more siblings → higher likelihood; sibling locations become **scan leads, not evidence**).
+3. **Gap-fill with STRIDE** for every entry point that still has no threat ("past vulnerabilities are biased
+   toward what has already been found"). Invariant: the final table must contain **≥1 threat with empty
+   evidence**, or the gap-fill step did not actually run.
+4. **Flag** every scored owner-would-know claim as an open question, so a later 10-minute interview closes it.
+
+## Handing scope to security-scan
+`security-scan` reads `docs/THREAT_MODEL.md`: section 3 (entry points) and section 5 (attack classes) become its
+focus areas; the threat `impact`/`likelihood` bias which findings it treats as high severity. No threat model →
+`security-scan` falls back to its own Front 0 discovery.

package/kit/skills/threat-model/references/schema.md

@@ -0,0 +1,42 @@
+# THREAT_MODEL.md — parseable contract
+
+A **map, not a bug list.** Fixed sections in this order so `security-scan` and a reviewer can parse it.
+
+## Sections
+1. **System** — one paragraph: what it does, who uses it, where it runs.
+2. **Assets** — what is worth protecting (data · money · availability · reputation/trust), each with a *why*.
+3. **Entry points & trust boundaries** — every place untrusted input crosses into more-trusted code
+   (route · API · form · file upload · CLI arg · queue message · webhook · IAM/role boundary). This is the surface.
+4. **Threats** — the ranked table (below).
+5. **Attack classes** — the 5-8 domain-specific classes derived, each mapped to the entry points it applies to.
+6. **Open questions** — owner claims still to verify, each with a "Verify by: <how>".
+7. **Mitigations** — class-level controls (table below).
+8. **Coverage** — assert every section-3 entry point appears in ≥1 threat's `surface`.
+
+## Threats table
+Pipe-separated columns:
+
+`id | threat | actor | surface | asset | impact | likelihood | status | controls | evidence`
+
+Enumerated value sets (keep parseable):
+- **actor** ∈ `external-anon · external-auth · insider · supply-chain · operator · automated · physical`
+- **impact** ∈ `low · moderate · high · severe · existential`
+- **likelihood** ∈ `very_rare · rare · possible · likely · almost_certain`
+- **status** ∈ `unmitigated · partial · mitigated · risk_accepted`
+
+Rules:
+- Sort by `(impact, likelihood)` descending — worst first.
+- **`evidence` raises `likelihood`; it is not the threat.** A row may have empty evidence (a threat with no
+  found vulnerability yet is still real). Score the **residual** likelihood *after* current `controls`.
+- `risk_accepted` requires a reason recorded verbatim in section 6.
+
+## Scoring guide
+| axis | how to score |
+|---|---|
+| **impact** | realistic worst case for *this* asset. `low`=cosmetic · `moderate`=recoverable loss · `high`=serious breach/outage · `severe`=major data/financial loss · `existential`=business-ending. |
+| **likelihood** | *after* current controls (residual). A control the owner *states* but that is not code-verified does **not** lower it — record it as an open question instead. |
+
+## Mitigations table
+`mitigation | threat_ids | closes_class (yes/no) | effort`
+
+Prefer a control that **closes a whole class** (`closes_class = yes`) over a one-line patch for the last bug.

package/kit/skills/token-budget/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: token-budget
+description: |
+  Context/token discipline: subagent isolation, output = summary, move-to-file, delegation threshold, lean skills.
+---
+
+# Token & Context Discipline
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "token budget", "token cost", "context window", "context management", "context is full", "clear context", "running out of context"
+
+A subagent exists for context management: it runs in its own window and returns **only its summary**
+to the main thread — intermediate noise (file reads, searches, logs) never enters the main context.
+
+**Warning — measured, not guessed.** Each subagent re-pays its **full context from scratch**: in a real
+transcript the first turn was `cache_read=0`, every token `cache_creation` — nothing is shared with the main
+thread's cache. A **no-op** subagent (task = "reply DONE") already cost **~10k tokens with restricted tools and
+~16k with full tool access**; that floor is base system prompt + tool schemas, paid fresh every time. Of the
+always-on material only the **skill listing (~2.5–3k tokens) is inherited** by a subagent — the discipline
+(`DISCIPLINE.md`/CLAUDE.md) and the agent descriptions are **not** injected into it. So a delegation is worth it
+for **isolation / parallelism / a clean window**, or when the isolated work would otherwise cost the main thread
+**more than that ~10–16k floor** — never by default.
+
+## Rules
+1. **Output = summary.** The agent returns a short, structured summary to the main thread; it does **not** return raw logs / file dumps / long code.
+2. **Move to a file.** Heavy output (a plan, scan report, inventory) is written to `docs/*.md`; a **summary + pointer** comes back. (local, in gitignore)
+3. **Delegation threshold.** Noisy/heavy work (reading many files, scanning, research) → subagent. A single tool-call / small work → **main thread**. Concretely: if the isolated work won't save the main thread more than the **~10–16k fresh-context floor** a subagent costs, keep it on the main thread — delegate for isolation, not to shave a few reads.
+4. **A RESUMED agent re-pays its GROWN context, not its floor.** Continuing an agent that already ran keeps its
+   whole history, so the next turn starts from wherever it got to. Measured across four turns of one agent:
+   167k → 187k → 207k → **211k tokens**, and that last turn was a single word of seed text. The floor in rule 3
+   is the cost of a FRESH agent; a long-running one passes it many times over. Continue it for the context it
+   holds — a running verification, a migration it is mid-way through — and open a fresh one, or stay on the main
+   thread, for a small correction that does not need any of that history.
+5. **Built-in agents are on this budget too.** `Explore`, `general-purpose` and the rest cost exactly what a Crewforth
+   agent costs; one repo-mapping `Explore` measured 520 s and ~150k tokens. Crewforth owns no search agent, so
+   reaching for a built-in is correct — just size the request the way rule 3 sizes any other delegation.
+6. **Least tooling.** An agent holds only the tools it needs; extras accidentally pollute the context + burn the limit.
+7. **Lean SKILL.md.** Skills load into the main context; heavy reference goes to a separate file, only when needed.
+8. **Targeted reading.** Instead of reading a whole file, pinpoint with Grep/Glob.
+9. **Measure fill, don't guess.** `bash .claude/hooks/context-usage.sh` reads it from the transcript; crew-session-manager recommends continue or handoff+clear; the user runs `/clear` at a phase boundary.
+10. **Bound what a command hands back.** All of the rules above govern the context's own footprint; none of them
+   govern what a single `Bash` call dumps into it. A `find` over a monorepo, an unfiltered log, a full test run —
+   each returns everything to the main thread whether or not any of it is read. Ask for the answer, not the
+   corpus: `grep -c` over `grep`, `| tail -20` over the whole file, `--quiet`/`--porcelain` where the tool has
+   one, and a redirect to a file plus a pointer when the output is genuinely needed later (rule 2).
+11. **Cut what nothing reaches — with evidence, not a hunch.** Every installed skill spends its name and
+   description in EVERY session, forever. `bash .claude/eval/utilization.sh` reports which skills actually fired
+   in this project's transcripts and how many bytes the cold ones cost, which is the list `doctor.sh` §4a's
+   `skillOverrides: name-only` advice needs and never had. Read it as evidence, not a verdict: a skill that only
+   fires during an incident is doing its job by existing. `--all-projects` widens the scope; by default it reads
+   this project only and prints names and counts, never paths or content.

package/kit/skills/trace-scan/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: trace-scan
+description: |
+  Trace scan (§4.1/§4.2): before a commit, scans the staged changes and the message for AI traces (co-author
+  trailers, footers, robot emoji, tool names) and vendor template names. The git hooks apply it automatically.
+---
+
+# Trace Scan (trace-scan)
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "scan traces", "trace scan", "AI trace", "check vendor name", "pre-commit audit"
+
+Purpose: to bind §4.1/§4.2 to a *gate* rather than to *memory*. If the rule lives only in text,
+a trace leaks sooner or later; this skill + the hooks stop the leak at commit time.
+
+## When
+- Before every commit (automatic: `pre-commit` + `commit-msg` hooks).
+- Before crew-commit-agent proposes a message (manual verification).
+
+## How
+Pattern list: `./.claude/hooks/trace-blocklist.txt` (grep -iE, one pattern per line).
+- **Defaults are high-hit:** co-author trailers, auto-generation footers, robot emoji, and AI-assistant/tool
+  brand names. Standalone words that occur too often (model/assistant) are DELIBERATELY excluded. See trace-blocklist.txt for the exact list.
+- **Vendor name is project-specific:** ADD the name of the third-party template in use to the list (§4.2).
+
+Manual scan (a quick look without the hook):
+```bash
+git diff --cached --unified=0 | grep -E '^\+' | grep -Ev '^\+\+\+' \
+  | grep -iEf .claude/hooks/trace-blocklist.txt
+```
+
+## Hook setup
+`start.sh` sets `git config core.hooksPath .claude/hooks` (if there is a git repo). The hooks live
+under `.claude` → they are in gitignore and stay local (§4.3). To do it later for a repo:
+```bash
+git config core.hooksPath .claude/hooks
+chmod +x .claude/hooks/pre-commit .claude/hooks/commit-msg
+```
+
+## Rules
+- If there is a finding, the commit STOPS; the phrase is removed and the real rationale is written in the project's commit language (CLAUDE.md).
+- Skipping with `--no-verify` only on an EXPLICIT request (§4.5); the hook is not skipped silently.
+- On a false positive, narrow/remove the pattern — the list is set up by the project owner.

package/kit/skills/worktree/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: worktree
+description: |
+  Isolate risky or parallel file-mutating work in a git worktree so the main tree's uncommitted changes are never
+  clobbered. For fan-out agents that edit files, throwaway experiments, or any change you may want to discard cleanly.
+---
+
+# Worktree Isolation
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "worktree", "git worktree", "isolate the changes", "sandbox this work", "parallel file edits"
+
+One rule: **never let risky or parallel work run on top of uncommitted changes in the shared tree.** A git worktree
+gives a second working copy of the same repo on its own branch — you experiment or fan out agents there, and the main
+tree (with your in-progress edits) is physically untouched. Throw the worktree away and nothing you cared about is lost.
+
+> **Crewforth adaptation (local, .claude/):** this exists because verification/fan-out subagents have discarded a session's
+> **uncommitted** work by running a destructive git command over the shared tree. Those commands (`reset --hard`,
+> `clean -f`, `checkout -- .`, `restore`) are §4.5-gated — but the real fix is to not put them near unsaved work.
+> The Agent tool's `isolation: "worktree"` does this automatically for parallel mutating agents; reach for it there.
+
+## When to isolate
+- **Fan-out that writes files** — two+ agents editing the same repo in parallel would collide; give each its own worktree.
+- **A throwaway experiment** — you might keep it or bin it; a worktree makes "bin it" a one-liner, not a `reset --hard`.
+- **A dirty tree you can't commit yet** — you have unsaved work but need to try something risky; isolate rather than stash-and-pray.
+- Skip it for a single, in-place edit on a clean tree — a worktree is overhead there.
+
+## How
+1. **Detect** — are you already in a worktree? `[ "$(git rev-parse --git-dir)" != "$(git rev-parse --git-common-dir)" ]` is true inside one; don't nest.
+2. **Create** — `git worktree add ../wt-<name> -b <branch>` (new branch) or `git worktree add ../wt-<name> <existing>`. It shares the object store, so it's cheap.
+3. **Work there** — cd into it; edits, builds, and agent runs stay local to that copy.
+4. **Fold back or discard** — keep: commit on its branch, then merge. Discard: `git worktree remove ../wt-<name>` (add `--force` only if you mean to drop its changes).
+5. **Clean up** — `git worktree prune` removes stale entries. Never leave orphaned worktrees around.
+
+## Invariant rules
+1. **Isolate before risk, don't revert after** — a worktree replaces "run `checkout -- .` to undo"; the undo is `worktree remove`.
+2. **One worktree per parallel writer** — never two agents mutating the same tree at once.
+3. **Don't nest** — creating a worktree from inside a worktree; detect first.
+4. **Commit or isolate before delegating file-mutating work** — a subagent must never be able to discard the main tree's unsaved changes.
+5. **Remove what you add** — no orphaned worktrees; `remove` + `prune` when done.

package/kit/studio/README.md

@@ -0,0 +1,266 @@
+# Crewforth Studio
+
+A visual orchestration panel for Claude Code: which agent is running, what it is
+doing right now, what it has spent, and which gates fired.
+
+Studio **is installed into your project**, because it lives inside the payload:
+this directory is `kit/studio/`, and `kit/` is what every
+channel already ships. `start.sh` and `adopt.sh` copy it to `.claude/studio/`,
+beside `agents`, `skills`, `commands`, `hooks` and `eval` — the sixth of six.
+
+That was the other way round until a real project updated with `/crew-update`,
+ran the documented command and got ENOENT: the project had no `package.json`,
+and nothing had ever installed the panel into it. Excluding it from every
+channel was a decision; a documented command that cannot work is a defect.
+
+## Run
+
+From any project that has Crewforth:
+
+```bash
+/crew-studio                                  # the command; probes node, starts it, reports the URL
+node .claude/studio/server/index.js --open   # the same thing without the picker
+```
+
+**`node` may not be on your PATH, and that is on purpose.** When Crewforth fetched the runtime for you
+(`ensure-node.sh --install`), it promised to touch nothing outside `~/.claude/studio-runtime` — no PATH edit,
+no shell profile, no admin rights. Measured on a stock Windows 11 machine: after a successful install
+`node --version` reports v24.21.0 through the full path while `command -v node` finds nothing, which is the
+promise being kept rather than a broken install. So every `node …` line on this page means "the node Crewforth
+can find". Ask for it instead of assuming it:
+
+```bash
+NODE="$(bash .claude/studio/ensure-node.sh)"   # prints an absolute path, exits 1 if there is none
+"$NODE" .claude/studio/server/index.js --open
+```
+
+`/crew-studio` does exactly this for you, which is why it is the first line above and not the second.
+
+Other flags, same file:
+
+```bash
+node .claude/studio/server/index.js --port 8080
+node .claude/studio/server/index.js --selftest     # offline checks, no browser
+```
+
+**Started per project, scoped to the machine.** Studio reads
+`~/.claude/projects`, which holds every session on this machine. The count is
+whatever that directory holds; the panel prints it rather than claiming it here,
+because a number measured on one machine describes only that machine. So a
+running panel already sees a kit-installed project without being started inside
+it, and the working directory only decides which project the panel opens on.
+Run it from wherever is convenient, or run it once and leave it up.
+
+`--open` exists so the URL is not copied by hand: the token is generated per run
+and the panel refuses requests without it. When a browser cannot be opened — over
+SSH, or headless — the server says so rather than looking like it worked, and
+`/crew-studio` reports the URL either way.
+
+**Both editions carry the panel, in different places.** A full install has it
+at `.claude/studio/`; the plugin edition has it at `studio/` in the plugin's own
+root. One `/crew-studio` file serves both, and its first step tells them apart
+by reading `${CLAUDE_PLUGIN_ROOT}/studio/server/index.js` literally: Claude Code
+replaces that placeholder before the command is read, and only when the command
+came from the plugin. A real absolute path is the plugin's panel; the
+placeholder left standing means a full install. Neither path on disk means an
+install older than the panel, which `/crew-update` brings up to date.
+In the plugin the command is namespaced: `/crewforth:crew-studio`.
+
+**What the plugin edition cannot show.** A plugin install puts no
+`.claude/VERSION`, `kit.conf` or Crewforth scripts into a project. That project's row
+in the list has no version badge, and for the project the panel was opened from, the
+inspector's gates, stats and board tabs say "Not measured" with the reason rather
+than zero. The gates tab can still list what the gate log observed: the plugin's
+Bash guard records its blocks, approval prompts and pre-authorised git actions,
+and its gate-file write guard its blocks, in `.claude/gate-log.tsv` when the
+project has a `.claude/` directory, the file is git-ignored or the project is
+not a repo, and `CREW_GATE_LOG` does not send the log elsewhere.
+Everything else — the live
+agent graph, owned sessions, the permission bridge — works the same in both
+editions.
+
+**The suite is not here.** It lives in `packaging/studio-test/`, beside the
+repo's other gates, and asserts things about this *repository* — the root
+`package.json`, the payload beside it — which an installed project does not
+have. Keeping it under `kit/` would also have shipped 104 KB of test
+code through all four channels only for the installer to delete it on arrival.
+The installed diagnostic is `--selftest`, which lives in `server/index.js`.
+
+There is no install step. Studio has **zero dependencies** — `node:http` and
+`node:child_process` are the whole stack, matching Crewforth's own promise. If
+`node_modules` ever appears here, something has gone wrong.
+
+Requires Node 18+. In Crewforth's own repository `bash packaging/verify.sh studio`
+runs the same checks CI runs; a machine without node reports a skip rather than a
+pass, and a missing `kit/studio/` is a failure rather than a skip.
+
+## What it does
+
+**Watches.** The delegation graph of any session on this machine, live: one node
+per agent, what it is doing right now, what it has spent, what it reported.
+Nodes are draggable and their positions are remembered; a workflow run is a
+container you can fold.
+
+**Talks.** Sessions the panel starts are driven over stdin/stdout, so you can
+write to one and watch its agents appear beneath it. They are given a session id
+up front, which means their transcripts land where every other session's do and
+the graph reads them without a special case.
+
+**Shows every conversation, drives only its own.** Selecting any session opens
+what was said in it, read from the transcript. A session the panel did not start
+has no channel to write to, so that pane says so and offers the two things that
+do work: continue it here, or open it in a real terminal.
+
+**Asks before it acts.** Every tool call in an owned session is parked by a
+PreToolUse hook and shown in the panel — the command itself, not just the tool's
+name — until you allow it, allow that tool for the session, or deny it.
+
+**Runs several at once.** Each session the panel starts is a tab that keeps its
+own stream open whether or not it is on screen, so work continuing in the
+background is continuing, not replayed when you look back.
+
+**Hands a session to a real terminal.** The panel cannot drive a session it did
+not start, so for an observed one it offers the only thing that is true: a
+button that opens it where it can be driven. What it will run is shown before
+anything launches.
+
+**Reaches other machines.** Transcripts are local files and nothing enumerates
+another machine's sessions, so a peer is another Studio.
+
+## What it reads
+
+| Source | What it gives |
+|---|---|
+| `claude agents --json` | Live sessions on this machine: name, cwd, busy/waiting/idle, what it is waiting for |
+| `<session>.jsonl` and `<session>/subagents/` | The delegation graph, nested workflow runs included |
+| `.claude/VERSION` per project | Which projects run an old Crewforth, against the npm dist-tags feed |
+
+That call spawns a process, so it is cached rather than repeated. The browser
+polls every 2 s and the server caches for 1 s, which bounds the cost at one
+spawn per poll. What the spawn costs is a property of the machine, not of this
+file — two machines here measured 131 ms and 164 ms medians — so `--selftest`
+measures it wherever it runs and prints that number instead of quoting one.
+
+More sources land in later sprints: the transcript tree (per-agent live JSONL),
+the owned-session event stream, `gate-log.tsv`, and the team board.
+
+## Two honesty rules
+
+These are load-bearing, not stylistic.
+
+**"Not measured" is never drawn as zero.** If the `claude` CLI is missing or a
+read fails, the panel says so and names the reason. An empty list would read as
+a quiet, healthy machine — which is the kind of lie this panel exists to stop
+telling.
+
+**Unknown data is never coerced into something familiar.** An unrecognised
+status keeps a neutral ring; an unrecognised field is carried through untouched
+rather than dropped. Claude Code's event shapes are undocumented and move with
+the version, so the panel is built to notice that rather than to guess.
+
+## Sessions on other machines
+
+The fleet lists them under **Reachable elsewhere**, with the time they were
+seen. That wording is the whole of it: this is a snapshot, not a feed.
+
+Only a session connected to Remote Control can see peers on other machines.
+Measured: a headless session's `ListAgents` returns the local peers where a
+connected one returns those plus five remote, and passing `--remote-control` to
+a headless session does not change that — the flag starts an *interactive*
+session. There is no documented API or non-interactive command that enumerates
+them; `/list-agents` is an in-session tool, `--cloud` refuses without a TTY, and
+the Claude API's `/v1/sessions` belongs to Managed Agents, a different product.
+
+So the panel does not try to be that session. It reads what one already wrote:
+a connected session's `ListAgents` result lands in its transcript as structured
+text, and that is where this comes from. When no session here has ever asked,
+that is reported as not measured — which is not the same as having no peers.
+
+Listed, not opened. Those sessions' transcripts are on those machines' disks,
+so the panel can name them but cannot draw their graphs. For that, run Studio
+there too:
+
+## Other machines
+
+```bash
+# on the other machine
+node .claude/studio/server/index.js
+
+# here — forward its port, then point at the forwarded one
+ssh -N -L 7778:127.0.0.1:7777 other-machine
+node .claude/studio/server/index.js --peer http://127.0.0.1:7778 --name mac
+```
+
+Sessions, projects, graphs and agent reports from a peer appear alongside local
+ones, tagged with the machine they came from. A peer that cannot be reached is
+reported as unreachable, never as empty.
+
+Nothing listens on a network interface in this arrangement: both Studios stay on
+loopback and the tunnel does the crossing.
+
+## What Crewforth already measured
+
+The panel does not recompute any of it. Selecting the session node opens what
+Crewforth's own tools say, including when they say they cannot answer:
+
+| Tab | Source |
+|---|---|
+| gates | `gate-report.sh --json` for the rule inventory, `.claude/gate-log.tsv` for what fired |
+| stats | `session-stats.sh --raw` — fifteen metrics over this transcript |
+| board | `board.sh status` |
+
+One distinction is carried all the way to the screen. A gate event from a
+session the panel started arrives through `--include-hook-events` and carries
+the moment it happened, so it is listed under **Happened**. A line in
+`gate-log.tsv` does not — that format has no timestamp column — so those are
+listed under **Observed**, with the reason written out. Drawing the second as
+the first would be the first untrue thing in this panel.
+
+`gate-report.sh` finds the hooks relative to where it runs: `./.claude/hooks`
+in an installed project, `./hooks` otherwise. Both layouts are handed what they
+expect rather than the script being asked to guess. Where it still cannot
+answer — a directory with no Crewforth install, a project with no log — that is reported as
+not measured, never as zero.
+
+## The permission gate
+
+A hook injected through `--settings` parks each tool call, writes it into a
+spool, and waits for the panel's answer. Exit 0 allows, exit 2 blocks.
+
+It answers at 45 seconds against a 90-second harness timeout, and that gap is
+the whole design. Measured here: a hook killed at its timeout emits nothing and
+**the tool proceeds** — `permission_denials` came back 0 and the command ran. A
+hook the harness never has to kill fails closed instead, so a shut panel is a
+denial rather than an opening.
+
+The waiting costs no processes. A bounded read on a fifo held open read-write
+blocks for its timeout and never sees EOF; the alternative, a `sleep` per poll,
+spends seconds of fork overhead on Git Bash. Both the fifo and the shell's
+support for fractional timeouts are probed with exactly what the loop will run —
+bash 3.2 ignores a fractional `-t` and turns the poll into a hot spin, which is
+how the first version passed while spinning 185,000 times in five seconds.
+
+Interactive prompts have a limit worth stating: `AskUserQuestion`, `ExitPlanMode`
+and `EnterPlanMode` are absent from a headless session's 78-tool list, in every
+permission mode, while an interactive session has them. So there is no
+structured choice to render. When a reply offers options in prose the panel
+makes them clickable, which sends that text — a shortcut for typing it, not a
+channel that does not exist.
+
+## Security
+
+The server binds to `127.0.0.1` only, and the host is deliberately not
+configurable — it reads a developer's live sessions and can start new ones.
+
+A token is always required for `/api/`. Supply one, or let the server generate
+one and print it with the URL:
+
+```bash
+CREW_STUDIO_TOKEN=$(uuidgen) node .claude/studio/server/index.js
+```
+
+Anything that changes state needs, on top of the token, a header no cross-origin
+page can attach without a preflight this server never answers. Permission modes
+are an allow-list — `plan` (the default), `acceptEdits`, `default` — so a mode
+that skips Crewforth's gates cannot be requested, and the panel never has to name
+one to refuse it.