crewforth 3.1.1 → 3.2.0-rc.2

package/kit/hooks/refuter-ledger.sh

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+# refuter-ledger.sh - the record of what crew-refuter concluded, written by the hook and not by the session.
+#
+# WHY. A findings document can say a finding was verified. That sentence is the session's own; the ledger is not.
+# When a crew-refuter agent stops, this hook reads the TASK it was given (the first record of its own transcript)
+# and the ANSWER it ended with (last_assistant_message), and adds one line when the two agree on the finding and
+# the lens:
+#
+#   ts  session  agent_id  finding  lens  verdict              .claude/state/crew-refuter.tsv
+#
+# kit/eval/lib/findings/findings.mjs `validate --ledger` holds a document to it: a medium-or-higher finding needs
+# verifiers, and every verifier it names must be a line here, with the same finding, lens and verdict.
+#
+# Wired to SubagentStop with a matcher on the agent type, so it starts for crew-refuter only; the type is checked
+# again here. It works whatever CREW_MODEL_ROUTING says: this is not model routing.
+# THIS NEVER BLOCKS. It exits 0 on every path: a stop hook that failed closed would keep an agent running.
+# The ledger is protected from the session the way the routing records are (guard-bash.sh, guard-write.sh): a plain
+# attempt to write it is refused; a determined one (an interpreter, a name built from pieces) is not, and that is
+# the stated scope of those guards.
+set -uo pipefail
+export LC_ALL=C
+_rl_here="${BASH_SOURCE%[/\\]*}"; [ "$_rl_here" = "${BASH_SOURCE}" ] && _rl_here=.
+[ -f "$_rl_here/guard-agent-model.sh" ] || exit 0
+. "$_rl_here/guard-agent-model.sh"
+declare -F _json_slice >/dev/null 2>&1 || exit 0
+
+IFS= read -r -d '' INPUT || true
+_json_slice "$INPUT" hook_event_name >/dev/null; [ "$_JS" = SubagentStop ] || exit 0
+_json_slice "$INPUT" agent_type >/dev/null; [ "${_JS##*:}" = crew-refuter ] || exit 0
+_json_slice "$INPUT" agent_id >/dev/null; AID="$_JS"
+case "$AID" in ''|*[!A-Za-z0-9._-]*) exit 0 ;; esac
+_json_slice "$INPUT" session_id >/dev/null; SID="$_JS"
+case "$SID" in ''|*[!A-Za-z0-9._-]*) SID=- ;; esac
+
+# One field of a text: the value after "<key>:" at the start of a line, first occurrence, trimmed.
+_rl_field(){  # $1 text, $2 key (any case) -> _RLF
+  local line k; _RLF=""
+  while IFS= read -r line; do
+    line="${line%$'\r'}"; line="${line#"${line%%[![:space:]]*}"}"
+    k="${line%%:*}"; [ "$k" = "$line" ] && continue
+    shopt -s nocasematch
+    if [[ "$k" == "$2" ]]; then shopt -u nocasematch
+      _RLF="${line#*:}"; _RLF="${_RLF#"${_RLF%%[![:space:]]*}"}"; _RLF="${_RLF%"${_RLF##*[![:space:]]}"}"; return 0
+    fi
+    shopt -u nocasematch
+  done <<< "$1"
+  return 1
+}
+
+# The task: the first record of the agent's own transcript (a string, or a list whose first block holds the text).
+_json_slice "$INPUT" agent_transcript_path >/dev/null; _json_unescape "$_JS" >/dev/null; ATP="${_JU//\\//}"
+[ -f "$ATP" ] || exit 0
+L1=""; IFS= read -r L1 < "$ATP" || true
+_json_slice "$L1" content >/dev/null; TXT="$_JS"
+[ -n "$TXT" ] || { _json_slice "$L1" text >/dev/null; TXT="$_JS"; }
+_json_unescape "${TXT:0:8000}" >/dev/null; TASK="$_JU"
+_rl_field "$TASK" finding || exit 0; F_TASK="$_RLF"
+_rl_field "$TASK" lens || exit 0; L_TASK="$_RLF"
+
+# The answer, and it must be about the same finding and lens.
+_json_slice "$INPUT" last_assistant_message >/dev/null; _json_unescape "$_JS" >/dev/null; ANS="$_JU"
+_rl_field "$ANS" finding || exit 0; F_ANS="$_RLF"
+_rl_field "$ANS" lens || exit 0; L_ANS="$_RLF"
+_rl_field "$ANS" verdict || exit 0; V="$_RLF"
+[ "$F_TASK" = "$F_ANS" ] && [ "$L_TASK" = "$L_ANS" ] || exit 0
+[[ "$F_TASK" =~ ^[a-z0-9][a-z0-9._:-]*$ ]] && [ "${#F_TASK}" -le 200 ] || exit 0
+case "$L_TASK" in reachability|protection|reproduction|exclusion|blast-radius|claim) ;; *) exit 0 ;; esac
+case "$V" in TRUE_POSITIVE|FALSE_POSITIVE|CANNOT_VERIFY) ;; *) exit 0 ;; esac
+
+P="${CLAUDE_PROJECT_DIR:-$PWD}"; P="${P//\\//}"; P="${P%/}"
+D="$P/.claude/state"; T="$D/crew-refuter.tsv"
+mkdir -p "$D" 2>/dev/null || exit 0
+# An agent that is resumed stops again: it answered once, and that answer stands.
+if [ -f "$T" ]; then
+  while IFS=$'\t' read -r _ _ a _; do [ "$a" = "$AID" ] && exit 0; done < "$T"
+fi
+[ -s "$T" ] || printf 'ts\tsession\tagent_id\tfinding\tlens\tverdict\n' > "$T" 2>/dev/null
+TS="$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null)"; case "$TS" in [0-9][0-9][0-9][0-9]-*Z) ;; *) TS=- ;; esac
+printf '%s\t%s\t%s\t%s\t%s\t%s\n' "$TS" "$SID" "$AID" "$F_TASK" "$L_TASK" "$V" >> "$T" 2>/dev/null
+exit 0

package/kit/hooks/session-update-check.sh

@@ -44,7 +44,9 @@
 set -uo pipefail
 # The 2.x names of the variables a user can set still work (one helper: eval/lib/crew-env.sh).
 _crew_d="${BASH_SOURCE%/*}"; [ "$_crew_d" = "${BASH_SOURCE}" ] && _crew_d=.
-[ -f "$_crew_d/../eval/lib/crew-env.sh" ] && . "$_crew_d/../eval/lib/crew-env.sh"; unset _crew_d
+[ -f "$_crew_d/../eval/lib/crew-env.sh" ] && . "$_crew_d/../eval/lib/crew-env.sh"
+# How an install's own version is read and ordered (an rc before its final): one definition, eval/lib/version.sh.
+[ -f "$_crew_d/../eval/lib/version.sh" ] && . "$_crew_d/../eval/lib/version.sh"; unset _crew_d
 
 URL="${CREW_UPDATE_URL:-https://registry.npmjs.org/-/package/crewforth/dist-tags}"
 # plugin-stable, not main: the marketplace installs the plugin from that branch, and only an approved release
@@ -139,7 +141,10 @@ PJSON="$PR_ROOT/.claude-plugin/plugin.json"
 # plugin's copy steps aside whenever a project install is present, instead of asking the project's question too.
 if [ "$IS_PLUGIN" = 1 ] && [ -f "$CL/VERSION" ]; then exit 0; fi
 if [ -f "$CL/VERSION" ]; then
-  read -r _cv < "$CL/VERSION" 2>/dev/null || _cv=""; CUR="$(sane_version "$_cv")" || exit 0
+  # The install's own file, so an rc (X.Y.Z-rc.N) is a version here; what npm answers is still held to X.Y.Z.
+  read -r _cv < "$CL/VERSION" 2>/dev/null || _cv=""
+  declare -F crew_local_version >/dev/null || exit 0
+  CUR="$(crew_local_version "$_cv")" || exit 0
   STATE="$CL/.state"                                            # repo-local: the install lives in the repo
   FEED="${CREW_UPDATE_URL:-$URL}"; KEY=latest; EDITION=project
   ANSWER='bash .claude/hooks/session-update-check.sh --answer'
@@ -186,12 +191,8 @@ fi
 [ -n "$LATEST" ] || exit 0
 LATEST="$(sane_version "$LATEST")" || exit 0
 
-# Numeric field compare, one awk. Pre-release suffixes degrade to their numeric prefix (`1-rc2` -> 1), which is
-# the harmless direction: it can suppress a question, never invent one.
-awk -v a="$LATEST" -v b="$CUR" 'BEGIN{
-  split(a,x,"."); split(b,y,".");
-  for(i=1;i<=3;i++){ if(x[i]+0 > y[i]+0) exit 0; if(x[i]+0 < y[i]+0) exit 1 }
-  exit 1 }' || exit 0
+# One awk, eval/lib/version.sh's order: 3.2.0 is newer than an installed 3.2.0-rc.1, so the rc's user is asked.
+awk -v a="$LATEST" -v b="$CUR" "${CREW_VCMP_AWK:-}"' BEGIN { exit !(vcmp(a, b) > 0) }' 2>/dev/null || exit 0
 
 # Skipped for good? Asked (or answered "later") within the last day?
 if [ -f "$STATE/update-skip" ]; then read -r _sk < "$STATE/update-skip" 2>/dev/null || _sk=""; [ "${_sk//[!0-9.]/}" = "$LATEST" ] && exit 0; fi

package/kit/owned-blobs.tsv

@@ -1,10 +1,10 @@
-# Generated by packaging/gen-legacy-blobs.sh from the final release tags v1.0.0..v3.1.0 (below VERSION 3.1.1) — do not edit by hand.
+# Generated by packaging/gen-legacy-blobs.sh from the final release tags v1.0.0..v3.1.1 (below VERSION 3.2.0) — do not edit by hand.
 # The flat files Crewforth owns: a copy whose bytes (CR aside) are one of these ids was never edited.
 # install_path	blob_sha1	first_tag	last_tag
 .claude/AGENT_TEMPLATE.md	075e2c26706c06f56af01652cd24c36918513bee	v3.0.0	v3.0.4
 .claude/AGENT_TEMPLATE.md	3fdc551d221ee3665b21ef8cc3563de861a9abe6	v1.4.0	v1.6.3
 .claude/AGENT_TEMPLATE.md	686fed306c873b45c245c77a95a8e6de6ee383d5	v1.7.0	v2.11.0
-.claude/AGENT_TEMPLATE.md	7ab19417b6ff3ac732e2c894be17ffb3ec091f7d	v3.1.0	v3.1.0
+.claude/AGENT_TEMPLATE.md	7ab19417b6ff3ac732e2c894be17ffb3ec091f7d	v3.1.0	v3.1.1
 .claude/AGENT_TEMPLATE.md	981df9ea27b6f1c5ab5cb509d40875a07603858d	v2.12.0	v2.13.0
 .claude/AGENT_TEMPLATE.md	b38b9c9b799156e07280ca886230524563acc75c	v1.0.5	v1.3.0
 .claude/AGENT_TEMPLATE.md	faec09e45543b75763c43bb24114a7b6355649ec	v1.0.0	v1.0.4
@@ -26,7 +26,7 @@
 .claude/DISCIPLINE.md	76d73a4e25c559ea361618862cde8480b1a6d8c2	v3.0.0	v3.0.0
 .claude/DISCIPLINE.md	b1ab7549b571dd2fc80d5777e0ae3185d29bd7b6	v2.13.0	v2.13.0
 .claude/DISCIPLINE.md	b7e1066451a8590e0a2607ad0a6fe80b21599c53	v1.1.3	v1.1.8
-.claude/DISCIPLINE.md	b90a067ee323a08146862b889293f8feb49f8e7e	v3.1.0	v3.1.0
+.claude/DISCIPLINE.md	b90a067ee323a08146862b889293f8feb49f8e7e	v3.1.0	v3.1.1
 .claude/DISCIPLINE.md	bf062c2b51a9cf3cc4d0caac389c148cf6fdc977	v2.12.0	v2.12.0
 .claude/DISCIPLINE.md	c693f1bd5832ce570058c6eedcacb5dff13d89e8	v1.10.0	v1.10.0
 .claude/DISCIPLINE.md	d63a01a183c9a80d739c840a511d338dc2765820	v1.4.0	v1.4.4
@@ -43,4 +43,4 @@
 .claude/README.md	97d4dd1f7f1695052cc1d06cc43f5bcdc603c989	v1.0.0	v1.0.4
 .claude/README.md	a3419891cfda7385564008e4befc1007bc5364cb	v1.1.1	v1.7.0
 .claude/README.md	a3b76e0fa31267610d28b742c122a962f6db59c4	v3.0.1	v3.0.4
-.claude/README.md	b6c9b57a67d25b7e4781e4eb61ff9637e6abe5ef	v3.1.0	v3.1.0
+.claude/README.md	b6c9b57a67d25b7e4781e4eb61ff9637e6abe5ef	v3.1.0	v3.1.1

package/kit/settings.json

@@ -108,6 +108,17 @@
             "timeout": 600
           }
         ]
+      },
+      {
+        "matcher": "AskUserQuestion",
+        "hooks": [
+          {
+            "type": "command",
+            "shell": "bash",
+            "command": "cd \"$CLAUDE_PROJECT_DIR\" 2>/dev/null; bash .claude/hooks/guard-question.sh",
+            "timeout": 600
+          }
+        ]
       }
     ],
     "UserPromptSubmit": [
@@ -168,6 +179,17 @@
             "timeout": 600
           }
         ]
+      },
+      {
+        "matcher": "(.*:)?crew-refuter",
+        "hooks": [
+          {
+            "type": "command",
+            "shell": "bash",
+            "command": "cd \"$CLAUDE_PROJECT_DIR\" 2>/dev/null; bash .claude/hooks/refuter-ledger.sh",
+            "timeout": 30
+          }
+        ]
       }
     ],
     "PostToolUse": [
@@ -181,6 +203,17 @@
             "timeout": 60
           }
         ]
+      },
+      {
+        "matcher": "AskUserQuestion",
+        "hooks": [
+          {
+            "type": "command",
+            "shell": "bash",
+            "command": "cd \"$CLAUDE_PROJECT_DIR\" 2>/dev/null; bash .claude/hooks/prompt-approval.sh",
+            "timeout": 60
+          }
+        ]
       }
     ],
     "SessionStart": [

package/kit/skills/crew-approve/SKILL.md

@@ -26,4 +26,11 @@ Read the line Crewforth added to this turn and do what it says:
   the argument was not `commit`, `push` or `commit+push`. Say which, and in the first case run the command and let
   the gate's own prompt ask.
 
+In `auto` the same approval can be given with one click: the gate's refusal prints a fixed AskUserQuestion, and
+the user's answer is recorded exactly like this command. Where a `PermissionRequest` hook may be wired (in the
+user's, the project's or a plugin's settings, or in a skill's or an agent's front matter), that question is closed,
+and so is the gate's own prompt in `default` / `acceptEdits`, because such a hook answers a prompt before the user
+does. This command is then the one approval left, in those modes too. Settings passed with `--settings` and
+managed settings delivered by a server cannot be read, so a hook there is past the check.
+
 Force-push and the rest of §4.5 are not opened by this.

package/kit/skills/crew-doctor/SKILL.md

@@ -24,7 +24,7 @@ Verify Crewforth is actually *active* in this project (not just present on disk)
 5. Summarise: **healthy**, or the precise fixes applied/needed, plus the readiness score. If it's not a git repo,
    note that the commit-time gates need `git init` + `git config core.hooksPath .claude/hooks`.
    If the output contains a line starting with ⭐, pass it to the user verbatim as the LAST line of your summary —
-   it prints once per Crewforth version, and it is meant for the user, not for you.
+   it prints once per Crewforth version here (the installer has its own once), and it is meant for the user, not for you.
 
 If `.claude/eval/doctor.sh` doesn't exist, this is not a full (start.sh / adopt.sh) install — Crewforth is likely
 running as a **plugin**, whose hooks are managed by Claude Code itself; there's nothing for the doctor to check,
@@ -52,3 +52,7 @@ found no Git Bash: tell the user the gates do not run and that the fix is Git fo
 scripts are developer instruments: they inspect an installation from outside it, and the plugin edition has no
 installation to inspect. Say this plainly when someone asks why `/crew-doctor` reports only the listing (and, on Windows, Git Bash) on a plugin install,
 rather than treating it as a defect. The Studio panel ships in both editions (`/crew-studio`).
+
+**On a plugin install, end with the star line** the full install's doctor prints: `bash "${CLAUDE_PLUGIN_ROOT}/eval/lib/star.sh" --once . doctor`
+(Bash tool, not PowerShell). It prints once per plugin version, or nothing; if it prints a line starting with ⭐, pass it to the
+user verbatim as the LAST line of your summary.

package/kit/skills/crew-handoff/SKILL.md

@@ -6,8 +6,9 @@ metadata:
 ---
 # /crew-handoff
 applies the `handoff` skill:
-1. Read the measured fill: the `🔋 Session` line, or `bash .claude/hooks/context-usage.sh --verbose` (Bash tool, not PowerShell).
-2. Write an actionable handover to `docs/SESSION_STATE.md`: Done · In progress (exactly where) · Next step · Open decisions · File pointers · Blockers.
+1. **crew-session-manager** (@agent-crew-session-manager) measures the fill (`context-usage.sh`, never a guess), gives the
+   recommendation and drafts the handover. The steps below work from its draft.
+2. Write the handover to `docs/SESSION_STATE.md`: Done · In progress (exactly where) · Next step · Open decisions · File pointers · Blockers.
 3. Preserve decision rationale; the next session should not start from scratch.
 4. **Cold-reader pass** (`handoff/references/cold-reader.md`): the questions are written from the work BEFORE the
    file, then answered from the file alone. Anything unanswerable goes back into the handover and is re-checked.

package/kit/skills/crew-map/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: crew-map
+description: Map the project — modules, what they touch, the gaps between them — and describe each module from the lines the scan cites.
+disable-model-invocation: true
+metadata:
+  kind: command
+---
+# /crew-map
+
+Write `.crewforth/crew-map.json`, then describe it. The scanner draws the map from the files; you add only what
+it cannot: a sentence or two on what each module is for, and a short overview. Every description points at lines
+the scan itself read, and a gate holds it to that. **Never commit.** Show the diff and stop.
+
+1. **Resolve the scanner.** Both editions carry it, in different places:
+
+   ```
+   PLUGIN_MAP=${CLAUDE_PLUGIN_ROOT}/eval/lib/crew-map/crew-map.sh
+   ```
+
+   Claude Code replaces `${CLAUDE_PLUGIN_ROOT}` in this text before you read it, and only in the plugin. If the
+   line above names a real path, that is the scanner; if it still shows `${CLAUDE_PLUGIN_ROOT}`, this is a full
+   install and the scanner is `.claude/eval/lib/crew-map/crew-map.sh`. Below, `MAP` is whichever it is.
+
+2. **Scan:** `bash MAP` at the project root (Bash tool, not PowerShell). It writes the map and keeps the
+   descriptions of an earlier run that still cite only lines this scan cites; it says how many it kept and dropped.
+   rc 3 is no usable Node: say so and stop, it is not a pass.
+
+3. **Describe.** Read `.crewforth/crew-map.json`, and as much of the cited source as you need. Then edit that
+   file, changing ONLY these fields:
+   - each `module` node's `narrative`: `{ "text": "…", "cites": ["file:line", …] }`. What the module is for, in
+     at most two sentences. Every cite is a `file:line` from THAT node's own `evidence`; cite at least one. Leave a
+     node `null` when its evidence does not tell you what it is for: an honest gap beats a guess.
+   - the document's `overview`: the same shape, at most 2000 characters, for someone new to the project: the entry
+     points, where data goes, the risky places. Its cites may be any node's evidence.
+   Describe what the cited lines show. A connection, a purpose or a risk the scan did not find is not added here:
+   say it to the user instead.
+
+4. **Validate:** `bash MAP --validate` (Bash tool, not PowerShell). It refuses a description that cites a line
+   the scan did not read, cites nothing, or runs past two sentences, and a map whose scanner fields were changed.
+   Fix what it names, in the descriptions only, until it holds.
+
+5. **Hand over:** the scan's summary line, how many modules you described and how many you left `null` and why,
+   then `git diff --stat .crewforth/crew-map.json`. Studio's **Map** view (`/crew-studio`) draws the result.
+   Committing it is the user's call.

package/kit/skills/crew-review/SKILL.md

@@ -9,6 +9,8 @@ Run the change set through the review trio (read-only). **The audits go out in p
 1. **At once, in ONE message** — several `Agent` calls, because none of these writes code and so there is
    nothing to serialise:
    - @agent-crew-security-expert (security-scan) — auth/IDOR/injection/secret; findings with severity.
+     Each `medium`-or-higher one then goes to **crew-refuter** (@agent-crew-refuter; claim + `file:line`, one call per lens, in
+     parallel) before it is reported; `findings.sh write --verified` refuses one its ledger does not back.
    - @agent-crew-performance-expert (`performance`) — hot path, query/loop, render, payload. Reports
      **candidates** (reasoned) and **findings** (measured) separately; an unmeasured claim is never a verdict.
    - @agent-crew-privacy-agent (`privacy-compliance`) — **when the diff touches personal data**: legal basis,

package/kit/skills/crew-update/SKILL.md

@@ -32,7 +32,7 @@ Bring the Crewforth install up to the latest published version:
    (no flags) in **their own terminal**, where both the npx and the interactive prompts work.
 7. **After:** run `bash .claude/eval/update-guard.sh post` (Bash tool, not PowerShell) and show the user its lists — added, changed, moved,
    removed.
-8. **Verify:** run `/crew-doctor` (or `bash .claude/eval/doctor.sh` — Bash tool, not PowerShell) so a bad/partial update surfaces immediately.
+8. **Verify:** run `CREW_NO_STAR=1 bash .claude/eval/doctor.sh` (Bash tool, not PowerShell) so a bad/partial update surfaces immediately; the updater has already shown the star line, if it was due.
    If the updater's or doctor's output contains a line starting with ⭐, pass it to the user verbatim as the LAST
    line of your summary — it prints once per Crewforth version, and it is meant for the user, not for you.
 9. **Report** old → new + the headline changes. Take them from `.claude/.state/whats-new.md` — the updater writes

package/kit/skills/incident-runbook/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: incident-runbook
 description: |
-  Production incident response: diagnose → mitigate → resolve, then a blameless postmortem and a repeatable
+  Incident response: diagnose → mitigate → resolve, then a blameless postmortem and a repeatable
   runbook. Stop the impact first, root cause second.
-  Use when production is degraded or broken, and again for the postmortem afterwards.
+  Use when production is degraded or broken, an outage keeps recurring, or for the postmortem.
 ---
 
 # Incident Response & Runbook

package/kit/skills/security-scan/references/verify.md

@@ -19,9 +19,12 @@ audit). Each verifier:
 Three passes inside one context window are not three verifiers. The second pass has already read the first one's
 reasoning; the blindness above is then a wish, not a property, and the agreement it produces is one argument
 counted three times. So:
-- **Each verifier is its own subagent** (`Agent`, one call per verifier, run in parallel). A subagent has its own
-  context window: it cannot see what the others concluded, which is the whole point. Read-only work, so no
-  `worktree` is needed — nothing is being written.
+- **Each verifier is its own `crew-refuter` call** (one call per verifier and lens, run in parallel). A subagent
+  has its own context window: it cannot see what the others concluded, which is the whole point. Read-only work,
+  so no `worktree` is needed — nothing is being written. Its task is the card, then `finding:`, `lens:`, `cite:`
+  and `claim:` (its agent file has the exact form); when it stops, `hooks/refuter-ledger.sh` records the verdict
+  in the refuter ledger, and `findings.sh write --verified` refuses a `medium`-or-higher finding whose verifiers
+  are not there. The ledger is the gate; the prompt that carries no reasoning is still discipline.
 - **Give it the finding and the file:line, never your reasoning.** Not "I think X is exploitable because Y" —
   just "claim: X at file:line. Try to refute it."
 - **If you did not isolate, say so.** Write `verifiers: 1 (single pass, not isolated)` in the verdict block. A

package/kit/studio/README.md

@@ -198,6 +198,18 @@ 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.
 
+## Remote viewers
+
+A viewer is a second token that reads and changes nothing, for watching the
+panel from another device without handing that device the panel. Add one in the
+Machines tab; its link is shown once. The server refuses a viewer's every
+request that is not a `GET`, and its reads of `/api/remote`, with 403 before any
+handler runs (`server/lib/remote.js`). Revoke ends the token and closes a
+stream it holds open. Viewers live in memory and end with the server.
+
+The server still binds to loopback. Reaching it from a phone is a tunnel the
+user runs, an ssh forward or `tailscale serve 7777`; Studio starts none.
+
 ## What Crewforth already measured
 
 The panel does not recompute any of it. Selecting the session node opens what

package/kit/studio/server/index.js

@@ -21,7 +21,10 @@ import { projectDir, listSessions, findSession, listProjects, sessionCwd, agentM
 import { agentOrigins } from './lib/agent-origin.js';
 import { buildGraph, agentDetail, conversation, STALE_MS } from './lib/graph.js';
 import { cachedUsage } from './lib/usage.js';
-import { readModels, readRecord, readCosts } from './lib/model-outcomes.js';
+import { streamOwned } from './lib/owned-stream.js';
+import { stampAtStart } from './lib/code-stamp.js';
+import { readModels, readRecord, readCosts, readAboveCosts } from './lib/model-outcomes.js';
+import { readMap, behindOf, compareMaps, mapSummary, MAP_FILE } from './lib/crew-map.js';
 
 const USAGE_BATCH = 12;
 import { palette } from './lib/palette.js';
@@ -35,11 +38,14 @@ import { open as openTerminal, plan as terminalPlan } from './lib/terminal.js';
 import { gateLog, gateReport, sessionStats, board } from './lib/kit-telemetry.js';
 import { writeState, clearStateSync, findRunning } from './lib/instance.js';
 import { remoteRoster } from './lib/roster.js';
+import { addViewer, listViewers, viewerByToken, revokeViewer, noteRequest, viewerMay, MAX_VIEWERS } from './lib/remote.js';
 import { randomUUID } from 'node:crypto';
 import { spawn } from 'node:child_process';
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const WEB_ROOT = path.resolve(HERE, '..', 'web');
+// The server's own code as it was when it started: an update on disk since then is said to the page (code-stamp.js).
+const codeChanged = stampAtStart(HERE);
 const LOOPBACK = '127.0.0.1';
 
 const MIME = {
@@ -108,15 +114,28 @@ function sendJson(res, status, value) {
 const TOKEN = process.env.CREW_STUDIO_TOKEN || randomUUID();
 const TOKEN_GENERATED = !process.env.CREW_STUDIO_TOKEN;
 
+/** For the self-check, which asks a real server as the owner and as a viewer. */
+export const _internals = { token: TOKEN };
+
 // Peers are other machines running Studio, reached over a forwarded port. This
 // server still listens on loopback only; a peer never widens that.
 let PEERS = [];
 let SELF_NAME = 'this machine';
 
-function authorised(req, url) {
+/**
+ * Whose request this is: the owner's, a read-only viewer's (lib/remote.js), or nobody's.
+ * The token is read from the same two places for both, so a viewer's link works exactly as the owner's does.
+ */
+function whoAsks(req, url) {
   const header = req.headers['authorization'];
-  if (header === `Bearer ${TOKEN}`) return true;
-  return url.searchParams.get('token') === TOKEN;
+  const bearer = typeof header === 'string' && header.startsWith('Bearer ') ? header.slice(7) : null;
+  const given = [bearer, url.searchParams.get('token')].filter(Boolean);
+  if (given.includes(TOKEN)) return { role: 'owner' };
+  for (const t of given) {
+    const viewer = viewerByToken(t);
+    if (viewer) return { role: 'viewer', viewer };
+  }
+  return null;
 }
 
 /**
@@ -167,10 +186,16 @@ async function modelCosts(cwd) {
     for (const s of (await listSessions(dir)).filter((x) => x.modifiedAt >= since).slice(0, MODELS_SESSIONS_MAX)) {
       const u = await cachedUsage(s);
       read += 1;
-      for (const [id, a] of Object.entries(u.agents ?? {})) per.set(id, a.cost);
+      for (const [id, a] of Object.entries(u.agents ?? {})) per.set(id, a);
     }
   }
-  return { measured: true, costs: readCosts(cwd, (id) => (per.has(id) ? per.get(id) : null)), sessionsRead: read };
+  return {
+    measured: true,
+    costs: readCosts(cwd, (id) => per.get(id)?.cost ?? null,
+      (id) => (per.get(id)?.advisorCalls ? { calls: per.get(id).advisorCalls, cost: per.get(id).advisorCost } : null)),
+    above: readAboveCosts(cwd, (id) => (per.has(id) ? { cost: per.get(id).cost, atNormal: per.get(id).costAtNormal } : null)),
+    sessionsRead: read,
+  };
 }
 const MODELS_SESSIONS_MAX = 60;
 
@@ -214,23 +239,35 @@ async function serveStatic(res, urlPath) {
   }
 }
 
-async function handle(req, res) {
+export async function handle(req, res) {
   const url = new URL(req.url, `http://${LOOPBACK}`);
 
   // The token guards data and actions, not the app shell. A browser does not
   // carry the page's query string into its sub-resource requests, so demanding
   // it for /style.css served an unstyled page and protected nothing: the shell
   // holds no secrets, and every /api/ path below is still gated.
-  if (url.pathname.startsWith('/api/') && !authorised(req, url)) {
+  const who = url.pathname.startsWith('/api/') ? whoAsks(req, url) : null;
+  if (url.pathname.startsWith('/api/') && !who) {
     return sendJson(res, 403, { ok: false, reason: 'token required' });
   }
+  // A viewer is refused HERE, before any handler: no route below has to remember that a viewer exists, and a
+  // route added tomorrow is read-only for a viewer without anyone writing a line for it.
+  if (who?.role === 'viewer') {
+    const may = viewerMay(req.method, url.pathname);
+    if (!may.ok) return sendJson(res, 403, { ok: false, reason: may.reason });
+    noteRequest(who.viewer, req, res);
+  }
 
   if (url.pathname === '/api/health') {
     return sendJson(res, 200, {
       ok: true,
+      role: who.role,
       node: process.version,
       pid: process.pid,
       uptimeMs: Math.round(process.uptime() * 1000),
+      // `changed`: the server's files on disk are not the ones it started with. A page that finds no `code` at all
+      // is talking to a server older than this field, which is the same thing.
+      code: codeChanged(),
     });
   }
 
@@ -288,7 +325,12 @@ async function handle(req, res) {
     // dead time whenever the feed hung, measured. The refresh runs behind this response.
     const latest = latestVersionCached();
     const projects = await listProjects({ currentCwd: cwd, kitOf: (c) => kitStatus(c, latest) });
-    for (const p of projects) { p.origin = SELF_NAME; p.local = true; }
+    for (const p of projects) {
+      p.origin = SELF_NAME; p.local = true;
+      // The navigator's Map entry and its count: the findings the map shows unasked. A stat per project; the map
+      // is parsed again only when its file changes (crew-map.js).
+      p.map = p.exists && p.cwd ? mapSummary(p.cwd) : null;
+    }
 
     const origins = [{ name: SELF_NAME, local: true, ok: true, projects: projects.length }];
     if (PEERS.length) {
@@ -339,7 +381,7 @@ async function handle(req, res) {
     const sid = url.searchParams.get('session');
     const session = sid ? await findSession(sid) : null;
     const cwd = url.searchParams.get('cwd') || (session ? await sessionCwd(session.file, session.bytes) : null);
-    if (!cwd) return sendJson(res, 200, { measured: false, reason: 'no project named', classes: [], suggestions: [], byAgent: {} });
+    if (!cwd) return sendJson(res, 200, { measured: false, reason: 'no project named', classes: [], suggestions: [], above: [], byAgent: {} });
     return sendJson(res, 200, readModels(cwd, { agents: await agentIdsOf(session) }));
   }
 
@@ -347,10 +389,29 @@ async function handle(req, res) {
     const sid = url.searchParams.get('session');
     const session = sid ? await findSession(sid) : null;
     const cwd = url.searchParams.get('cwd') || (session ? await sessionCwd(session.file, session.bytes) : null);
-    if (!cwd) return sendJson(res, 200, { measured: false, reason: 'no project named', costs: {}, sessionsRead: 0 });
+    if (!cwd) return sendJson(res, 200, { measured: false, reason: 'no project named', costs: {}, above: {}, sessionsRead: 0 });
     return sendJson(res, 200, await modelCosts(cwd));
   }
 
+  // The project's crew map, as Crewforth's scanner wrote it, and how far HEAD has moved since. Nothing is scanned here.
+  // `compare` names another project of this machine by its directory; only a project the panel lists, with a map
+  // of its own, is read, so the route cannot be pointed at an arbitrary path.
+  if (url.pathname === '/api/map') {
+    const sid = url.searchParams.get('session');
+    const session = sid ? await findSession(sid) : null;
+    const cwd = url.searchParams.get('cwd') || (session ? await sessionCwd(session.file, session.bytes) : null);
+    if (!cwd) return sendJson(res, 200, { measured: false, reason: 'no project named', others: [] });
+    const map = readMap(cwd);
+    const others = (await listProjects({ currentCwd: cwd })).filter((p) => p.cwd && p.cwd !== cwd && readMap(p.cwd).measured)
+      .map((p) => ({ label: p.label, cwd: p.cwd }));
+    if (!map.measured) return sendJson(res, 200, { ...map, cwd, others });
+    const asked = url.searchParams.get('compare');
+    const peer = asked ? others.find((o) => o.cwd === asked) : null;
+    const compare = peer ? { label: peer.label, cwd: peer.cwd, clients: compareMaps(map.doc, readMap(peer.cwd).doc) }
+      : asked ? { label: null, cwd: asked, clients: [], reason: 'not a project of this machine with a crew map' } : null;
+    return sendJson(res, 200, { ...map, cwd, behind: await behindOf(cwd, map.doc.source?.commit), others, compare });
+  }
+
   if (url.pathname === '/api/kit') {
     const cwd = url.searchParams.get('cwd') || process.cwd();
     const sid = url.searchParams.get('session');
@@ -463,6 +524,30 @@ async function handle(req, res) {
     return stream(req, res, url);
   }
 
+  /* --------------------------------------------------------- remote ---
+     Read-only viewers: who holds a link, and the way to take it back. Only
+     the owner reaches this far; a viewer was refused above. */
+
+  if (url.pathname === '/api/remote' && req.method === 'GET') {
+    return sendJson(res, 200, { measured: true, viewers: listViewers(), max: MAX_VIEWERS, now: Date.now() });
+  }
+
+  const remoteMatch = url.pathname.match(/^\/api\/remote(?:\/([^/]+))?$/);
+  if (remoteMatch) {
+    const gate = writeAllowed(req);
+    if (!gate.ok) return sendJson(res, 403, { ok: false, reason: gate.reason });
+    if (req.method === 'POST' && !remoteMatch[1]) {
+      const body = await readBody(req);
+      if (!body) return sendJson(res, 400, { ok: false, reason: 'body was not JSON' });
+      const made = addViewer(body.label);
+      return sendJson(res, made.ok ? 201 : 409, { ...made, viewers: listViewers() });
+    }
+    if (req.method === 'DELETE' && remoteMatch[1]) {
+      return sendJson(res, 200, { ...revokeViewer(decodeURIComponent(remoteMatch[1])), viewers: listViewers() });
+    }
+    return sendJson(res, 405, { ok: false, reason: 'POST to add a viewer, or DELETE a viewer id' });
+  }
+
   /* ---------------------------------------------------------- owned ---
      Sessions the panel started. Their transcripts land in the usual place,
      so the graph endpoints already cover them; only the conversation needs
@@ -525,6 +610,10 @@ async function handle(req, res) {
     return sendJson(res, out.ok ? 200 : 400, out);
   }
 
+  // Every open conversation on ONE connection (lib/owned-stream.js). Reading, so it sits beside /events, not
+  // behind the write gate.
+  if (url.pathname === '/api/owned-events') return streamOwned(req, res, url, { getSession, stateAfter: STATE_AFTER });
+
   const ownedMatch = url.pathname.match(/^\/api\/owned\/([^/]+)(?:\/(message|stop|events|mode))?$/);
   if (ownedMatch) {
     const s = getSession(decodeURIComponent(ownedMatch[1]));
@@ -830,6 +919,28 @@ async function selftest() {
     fleet.measured ? `${fleet.sessions.length} session(s)` : `not measured: ${fleet.reason}`,
   );
 
+  // The Map view: its files are installed, and the reader takes a crew map and refuses one of another schema. On a
+  // scratch map of its own, so the verdict does not depend on whether this project has one; this project's own map,
+  // when there is one, is reported beside it.
+  check('map view installed', ['map.js', 'map-plan.js', 'viewport.js'].every((f) => fs.existsSync(path.join(WEB_ROOT, f))), null);
+  {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'crew-studio-map-'));
+    try {
+      fs.mkdirSync(path.join(dir, '.crewforth'));
+      const doc = { schema: 'crewforth.crew-map/1', nodes: [{ id: 'mod:x:a', kind: 'module', name: 'a' }], edges: [], findings: [], notMeasured: [] };
+      fs.writeFileSync(path.join(dir, MAP_FILE), JSON.stringify(doc));
+      const read = readMap(dir);
+      // A different size, not only a different schema: the reader caches on mtime and size, and on Windows both writes
+      // land on one timestamp, so a same-size rewrite read back the first map (seen on a CI runner).
+      fs.writeFileSync(path.join(dir, MAP_FILE), JSON.stringify({ ...doc, schema: 'crewforth.crew-map/99' }));
+      const other = readMap(dir);
+      check('map read', read.measured === true && read.doc.nodes.length === 1 && other.measured === false,
+        read.measured ? `a scratch map read; one of another schema refused (${other.reason ?? 'read'})` : read.reason);
+    } finally { fs.rmSync(dir, { recursive: true, force: true }); }
+    const own = readMap(process.cwd());
+    process.stdout.write(`INFO this project's map — ${own.measured ? `${own.doc.nodes.length} node(s), ${own.doc.findings.length} finding(s)` : own.reason}\n`);
+  }
+
   const cost = await measureSpawnCost(3);
   if (cost === null) skip('spawn cost measured', 'claude CLI absent');
   else check('spawn cost measured', true, `min ${cost.minMs}ms · median ${cost.medianMs}ms · max ${cost.maxMs}ms`);
@@ -877,6 +988,9 @@ async function main() {
         '  --help       this text\n\n' +
         'Set CREW_STUDIO_TOKEN to require a bearer token, CREW_STUDIO_PEERS for a\n' +
         'comma-separated peer list.\n\n' +
+        'To watch from another device, add a viewer under Machines in the panel\n' +
+        'and open its link through a tunnel of your own. A viewer reads and\n' +
+        'changes nothing, and the server stays on loopback.\n\n' +
         'Peers are normally reached over a forwarded port, which keeps every\n' +
         'Studio on loopback:\n' +
         '  ssh -N -L 7778:127.0.0.1:7777 other-machine\n' +