session-orchestrator 5.12.0 → 5.13.0

package/mods/so-hud/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "compilerOptions": {
+    "target": "es2023", "lib": ["es2023"], "types": [], "module": "esnext",
+    "moduleResolution": "bundler", "strict": true, "noUncheckedIndexedAccess": true,
+    "noEmit": true, "skipLibCheck": true, "jsx": "react", "jsxFactory": "h", "jsxFragmentFactory": "Fragment"
+  },
+  "include": [".claude-plugin/types", "hooks", "types", "tests"]
+}

package/mods/so-hud/types/index.d.ts

@@ -0,0 +1,36 @@
+/** Standalone public wire contract; null means unmeasured. Engine nouns are asynchronous. */
+export type SoProfile = 'locker' | 'ausgewogen' | 'streng'
+export type SoState = 'arbeitet' | 'wartet' | 'bereit' | 'blockiert' | 'unbekannt'
+export interface SoBeacon {
+  schema_version: 1; session_id: string; name: string | null; repo_name: string | null
+  branch: string | null; pid: number | null; zustand: SoState; seit: string
+  warte_grund: 'dialog' | 'freigabe' | 'frage' | null; heuristisch: boolean
+  kontext_prozent: number | null; letzter_request_at: string | null; modell: string | null
+  welle: number | null; aktualisiert_at: string
+}
+export interface SoSnapshot {
+  schema_version: 1; measured_at: string; age_ms: number
+  repo: { root: string; name: string }
+  lock: { session_id: string | null; live: boolean; last_heartbeat: string | null } | null
+  session: { session_id: string; semantic_session_id: string | null } | null
+  wave: { running: boolean | null; number: number | null; role: string | null; agents_total: number | null; source: string | null }
+  agents: { entries: { id: string; typ: string | null; modellfamilie: string | null; status: string | null; tokens: null; letzter_request_at: null; quelle: string }[]; source: string | null; at: string | null; degraded: unknown
+    /** Running agents of this session; null when unknown (see stale_reason). Absent from collectors before #1580. */
+    running?: number | null
+    /** Why `running` is null: 'no-session', 'cache-unverifiable', 'no-session-start' or 'older-than-session'; null when measured. */
+    stale_reason?: string | null
+    /** Agents still running without a Stop past 24 h, counted apart from `running`; absent from older collectors. */
+    decayed?: number | null }
+  state: { status: string | null; session_type: string | null; current_wave: number | null; total_waves: number | null }
+  gate: { last: { variant: string | null; passed: boolean | null; check_failed: boolean | null; exit_code: number | null; at: string | null } | null; last_green_sha: string | null }
+  peers: { session_id: string; branch: string | null; status: string | null; current_wave: number | null; last_heartbeat: string | null; gleiches_working_copy: boolean; scope_paths: string[] | null }[]
+  vault: { enabled: boolean | null; mode: string | null; last_run: { at: string | null; created: number | null; updated: number | null; failed: number | null; aborted: string | null } | null; board: { action: string | null; at: string | null } | null }
+  degraded: string[]
+}
+export interface So {
+  version(): 1
+  snapshot(): Promise<SoSnapshot | null>
+  beacons(): Promise<SoBeacon[]>
+  profile(): SoProfile
+}
+declare module 'claude-code' { interface EngineInterface { so: So } }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "session-orchestrator",
-  "version": "5.12.0",
-  "description": "Your coding agents get an agreed plan, a check after each round of changes and a handover to the next session. Plan, Go, Close: /session reads your repo and agrees the scope, /go runs the work in waves with your tests and typecheck after each implementation wave, /close runs the full gate, verifies, commits and files the rest as issues. Scope and destructive-command guards, crash-safe resume, learnings you approve. For Claude Code, Codex CLI, Cursor and Pi.",
+  "version": "5.13.0",
+  "description": "Your coding agents get an agreed plan, a check after each round of changes and a handover to the next session. For Claude Code, Codex CLI, Cursor and Pi.",
   "type": "module",
   "homepage": "https://session-orchestrator.com",
   "keywords": [
@@ -43,6 +43,8 @@
     "evals/",
     "!evals/results/**",
     "!assets/marketing/**",
+    "mods/so-hud/",
+    "!mods/so-hud/tests/**",
     ".claude-plugin/",
     ".codex-plugin/",
     ".cursor-plugin/",

package/rules/_index.md

@@ -39,7 +39,7 @@ baseline project type (`nextjs-saas`, `express-service`, `docker-service`,
 - `always-on/test-value.md` — TV-001..005: name the bug a test catches, or do not write it; deletion is a feature
 - `always-on/build-value.md` — BV-001..004: the seven-rung build ladder, the four protections never simplified away
 - `always-on/cross-session-messaging.md` — CSM-001..005: messaging is transport, not shared state; no permission laundering
-- `always-on/loop-and-monitor.md` — LM-001..008: routing between `/goal`, Workflows, Channels, Monitor, `/loop`, and Routines
+- `always-on/loop-and-monitor.md` — LM-001..008: routing between `/goal`, Workflows, Channels, Monitor, `/loop`, and Routines (short form ≤ 4 kB; long form with filter examples in `docs/reference/loop-and-monitor-routing.md`, not vendored — #1624)
 - `always-on/bash-harness-pitfalls.md` — six false-green shell-harness failure classes (path-scoped via `globs:` + `paths:` frontmatter carrying identical lists — `paths:` is what Claude Code reads, `globs:` what `rule-loader.mjs` reads first; #1449)
 
 ## opt-in-stack (vendored on match)

package/rules/always-on/ask-via-tool.md

@@ -30,7 +30,7 @@ AskUserQuestion({ questions: [{
   ], multiSelect: false }]})
 ```
 
-Option 1 is the recommendation, labelled `(Recommended)`. 2–4 options, 1–4 questions per call. A description that only restates its label is a rule break.
+Weigh every realistic option, not just two: 2–4 options, 1–4 questions per call. Option 1 is the recommendation, labelled `(Recommended)`. Each description gives reason, cost and consequence; one that only restates its label is a rule break. One plain-words (eli5) sentence in the question or a description carries the core and drops no fact (AUQ-006).
 
 - ✓ "Blocker for the next wave; ~20 min; freezes plan scope until it lands."
 - ✗ "Fix the bug now."

package/rules/always-on/loop-and-monitor.md

@@ -1,220 +1,43 @@
 <!-- source: session-orchestrator plugin (canonical: rules/always-on/loop-and-monitor.md) -->
 # Loop & Monitor Routing (Always-on)
 
-`/goal`, `/loop`, `Monitor`, `Workflow`, Channels, and cloud Routines /
-scheduled desktop tasks share the "recurring, polling-style, or keep-going-
-until-done work" slot but are **not interchangeable**. Picking the wrong
-primitive wastes tokens, masks failures, or loses durability. This rule
-encodes the routing decision once so future sessions do not re-derive it.
-
-Version gates move; the routing does not. Check the primitive's availability in
-your harness before wiring anything load-bearing onto it, and keep a fallback.
+`/goal`, Workflow, Channels, Monitor, `/loop` and Routines share the "keep going / keep watching" slot but are not interchangeable. Check each primitive's availability in your harness before relying on it, and keep a fallback.
 
 ## LM-001: Decision Tree — Pick the Primitive First
-
-```
-Is the work a FINITE objective with a recognizable done-condition that
-the model's OWN surfaced output can demonstrate (refactor until the tests
-referenced in the transcript pass, drain a worklist, reach a state you
-can describe in a few thousand characters)?
-│
-├─ Yes → /goal.
-│        Continuation across turns until the condition is model-evaluated.
-│        (Completion-condition axis — see LM-008.)
-│        Pair with deterministic gates — /goal judges; it never verifies.
-│        NOT: "until CI goes green" — that is an EXTERNAL stream the
-│        evaluator cannot see → Monitor (next branch).
-│
-└─ No  → Is this a ONE-SHOT fan-out across many independent units (codebase-
-         wide audit, large migration, multi-angle cross-checked research)
-         needing dozens-to-hundreds of subagents one conversation cannot
-         coordinate?
-         │
-         ├─ Yes → dynamic Workflow.
-         │        Codifies the plan as a rerunnable script; the main context
-         │        holds only the final result, not the per-agent chatter.
-         │        NOT a recurring primitive — for repeated polling stay on the
-         │        axes below. (Fan-out axis — see LM-002b.)
-         │
-         └─ No  → Is the event PUSHABLE from an external system (CI webhook,
-                  error tracker, chat)?
-                  │
-                  ├─ Yes → Channels.
-                  │        The source pushes the event into the open session via
-                  │        a channel plugin — zero polling, reacts while you're
-                  │        away. (Push-based sibling of Monitor — see LM-002a.)
-                  │
-                  └─ No  → Is the watched thing a STREAM I can tail (logs, file
-                           changes, CI status transitions, a JSONL telemetry
-                           file)?
-                           │
-                           ├─ Yes → Monitor.
-                           │        Each stdout line = one notification. Zero
-                           │        polling tokens.
-                           │
-                           └─ No  → Is the watched thing PERIODIC and bounded by
-                                    THIS conversation (days, not weeks;
-                                    resume/continue restoration acceptable)?
-                                    │
-                                    ├─ Yes → /loop.
-                                    │        Use dynamic mode unless the cadence
-                                    │        is genuinely fixed.
-                                    │
-                                    └─ No  → Cloud Routines or desktop scheduled
-                                             tasks. Daily notes, weekly audits,
-                                             cross-repo sweeps. /loop CANNOT
-                                             cover these — it fires only while
-                                             the agent runtime is running.
-```
+In order, first match wins:
+1. Finite objective whose done-condition the model's own surfaced output can demonstrate: `/goal` (LM-008). External CI-green is invisible to its evaluator: use Monitor.
+2. One-shot fan-out over many independent units, too large for one conversation: Workflow (LM-002b).
+3. Event the source can push (CI webhook, error tracker, chat): Channels (LM-002a).
+4. Stream you can tail (logs, file changes, CI transitions, JSONL): Monitor (LM-002).
+5. Periodic and bound to THIS conversation (days, resume acceptable): `/loop`, dynamic unless the cadence is truly fixed (LM-003).
+6. Durable, offline, overnight or cross-repo: cloud Routines or desktop scheduled tasks (LM-004).
 
 ## LM-002: Use Monitor When …
-
-Use Monitor when the watched thing is a STREAM you can tail — a long-running
-build/test suite emitting progress to stdout, a CI pipeline you poll-then-stream
-(`glab ci status`, `gh pr checks --watch`), an accumulating error log
-(`tail -f` + `grep --line-buffered`), a JSONL telemetry stream, or a filesystem
-event (`inotifywait -m`). Each stdout line is one notification; zero polling
-tokens.
-
-**Coverage rule (load-bearing).** A Monitor filter must match every terminal
-state, not just the happy path. *Silence is not success.*
-
-```bash
-# WRONG — silent on crash, hang, or any non-success exit
-tail -f run.log | grep --line-buffered "elapsed_steps="
-
-# RIGHT — alternation covers progress + every failure signature
-tail -f run.log | grep -E --line-buffered "elapsed_steps=|Traceback|Error|FAILED|assert|Killed|OOM"
-```
-
-If you cannot enumerate failure signatures, broaden the alternation rather than
-narrow it. Some extra noise beats missing a crashloop.
+Tailing builds, tests, CI, logs or file events. The filter MUST match progress AND every terminal failure state; silence is not success. If failure signatures cannot be enumerated, broaden the filter. A watch expires; expiry is an exit notice, never success, so re-arm if still needed. In unattended `-p` runs, wait in bounded foreground commands and read the real exit: background tasks and Monitor watches do not keep the run alive after the turn ends.
 
 ## LM-002a: Use Channels When …
-
-Channels is the **push-based sibling of Monitor**: an external system pushes the
-event into your open session via a channel plugin (CI webhook, error tracker,
-chat) — zero polling, reacts while you are away. Choose Channels over Monitor
-when the source can PUSH (you register a webhook endpoint) rather than be TAILED
-(`tail -f` / `glab ci status`); when it can only be polled or tailed, stay on
-Monitor. Treat it as preview-grade — do not wire a load-bearing automation onto
-it without a Monitor or `/loop` fallback.
+The source can push. Research preview: never load-bearing without a Monitor or `/loop` fallback. Session-to-session text is messaging, not Channels.
 
 ## LM-002b: Use Workflows When …
-
-Dynamic **Workflows** is the **one-shot fan-out** primitive — distinct from every
-recurring/polling axis. Reach for it when a single objective decomposes into many
-independent units one conversation cannot coordinate: a codebase-wide audit, a
-large migration, a multi-angle research sweep. The model plans once, codifies a
-rerunnable script, fans out subagents, and returns only the final result.
-
-**Never reimplement a one-shot fan-out as `/loop`.** A `/loop` body re-runs a
-single coordinator prompt on an interval; it has no native fan-out, no
-agent-count cap, and no rerunnable-script artifact.
-
-**Distinct from in-run agent teams.** Workflows' one-shot fan-out is unrelated to
-experimental in-run multi-agent coordination within a single live session — see
-`parallel-sessions.md` § PSA Scope Axes for that boundary.
-
-**Do not swap a purpose-built wave orchestrator for a bare Workflow.** A
-Workflow's agent-count caps are bounds, not kill-switches, and it ships no
-per-run telemetry artifact. If your orchestration has stop conditions and an
-audit trail, a Workflow does not replace them.
+One-shot independent fan-out. Never emulate fan-out with `/loop`; never replace an orchestrator that owns kill-switches and telemetry with a bare Workflow.
 
 ## LM-003: Use `/loop` When …
-
-Use `/loop` when the check is genuinely periodic (no streamable trigger) and
-bounded by THIS conversation — a staleness check during a multi-hour session, a
-backlog snapshot during long-running work, branch-tending while waiting on
-review. Wire a custom maintenance loop into `.claude/loop.md` (project) or
-`~/.claude/loop.md` (user). Scheduled tasks fire only while the agent runtime is
-running; unexpired tasks restore on `--resume`/`--continue`.
-
-**Cadence — pick by observation-rate, not by the cache.** Choose the interval
-from how fast the watched thing changes: about a minute to a few minutes when a
-state transition is imminent, five to twenty minutes for steady-state polling,
-twenty minutes to an hour for idle maintenance. The runtime clamps a self-paced
-wakeup to roughly [60s, 3600s]. Under a short (5-minute) prompt-cache TTL, avoid
-a cadence that lands exactly on the cache cliff — you pay the miss without
-amortising it.
-
-**Limits & kill-switches (load-bearing).** A single environment variable
-(`CLAUDE_CODE_DISABLE_CRON=1`) disables the cron scheduler AND `/loop` entirely —
-not just one task. Each session is capped at a few dozen scheduled tasks. Both
-`.claude/loop.md` and `~/.claude/loop.md` are TRUNCATED past **25,000 bytes** —
-keep the loop body lean; a bloated body silently loses its tail rather than
-erroring.
+Periodic, no stream, this conversation. Pace by observation rate: imminent change 60–270 s, steady polling 300–1200 s, idle 1200–3600 s. Loop body files truncate past 25,000 bytes; keep them lean. `CLAUDE_CODE_DISABLE_CRON=1` disables `/loop` and the scheduler entirely.
 
 ## LM-004: Use Routines / Scheduled Tasks When …
-
-Use cloud Routines or desktop scheduled tasks when the work must run when no
-session is open (overnight, weekly, monthly), spans repos no single session can
-witness, or must persist across machine restarts. `/loop` is the wrong tool here
-— it fires only while the agent runtime is running; `--resume`/`--continue`
-restoration is not durable unattended scheduling.
+Work must survive the session: nightly, weekly, cross-repo, restart-durable. Resume restoration is not unattended scheduling.
 
 ## LM-005: Never Reimplement These as `/loop`
-
-- **A driver that already has its own kill-switches and telemetry.** Wrapping it
-  in `/loop` loses both. Pair them — never replace.
-- **Synchronous inter-wave checkpoints.** They are synchronous by design.
-- **Quality gates** (typecheck, test, lint). These block on purpose. Run them
-  once, sequentially.
-- **Hook-served events.** `PostToolUse`, `Stop`, `SubagentStop` already fire at
-  the right moment. A `/loop` poll on top is redundant.
-- **`/goal`.** Do not hand-roll a per-turn Stop-hook prompt evaluator to keep
-  working until a condition holds — `/goal` IS that mechanism, natively.
-  Re-implementing it as a custom Stop hook or a `/loop` body duplicates the
-  machinery and loses the built-in restore and clear lifecycle. See LM-008.
-- **One-shot subagent fan-out.** A codebase-wide audit / large migration /
-  multi-angle research sweep is a dynamic Workflow, not a `/loop`. See LM-002b.
+Autonomous drivers with their own kill-switches, synchronous inter-step quality gates, hook events you already receive, and `/goal` itself (never rebuild it as a custom Stop hook). Pair with them instead.
 
 ## LM-006: Destructive-Action Safeguards Apply
-
-A `/loop` body is a coordinator prompt that runs every iteration. Treat it as you
-would any coordinator action:
-
-- **No destructive operations** (`git push`, `git reset`, `rm`, merging an MR,
-  closing an issue) without explicit transcript authorisation for the specific
-  action.
-- **Track your footprint.** A loop that "tidies up" untracked files may delete
-  another session's work-in-progress. See `parallel-sessions.md`.
-- **Read-only first.** When in doubt, observe and report.
+Every loop iteration is an ordinary action: no push, reset, delete, merge or issue close without explicit authorization for that action. When unsure, observe and report read-only.
 
 ## LM-007: Anti-Patterns
-
-- Fixed `/loop 5m …` to babysit a CI run — use Monitor on `glab ci status` or `gh pr checks --watch` instead (LM-002).
-- `/loop 1d …` for a daily note — use Routines or desktop tasks; `/loop` does not fire while the agent runtime is stopped (LM-004).
-- A Monitor filter matching only the success marker — silence from a crash is indistinguishable from success (LM-002 coverage rule).
-- `/loop` wrapping an autonomous driver — duplicates loop semantics and hides its kill-switches (LM-005).
-- A cadence sitting exactly on a short prompt-cache TTL boundary — you pay the cache miss without amortising it (LM-003).
-- Using `/goal` as a quality gate — the evaluator reads the transcript only; pair `/goal` with a deterministic exit-code gate (LM-008).
-- Unbounded `/goal` with no turn/time-bound clause — always embed "or stop after N turns / M minutes" (LM-008).
-- Hand-rolling a one-shot fan-out as a `/loop` body — use a Workflow (LM-002b).
+Wrong routing, success-only filters, unbounded goals, a goal used as a gate, and caps mistaken for kill-switches.
 
 ## LM-008: Use `/goal` When …
-
-`/goal <condition>` keeps the model working across turns until a stated
-completion condition is confirmed — a session-scoped, prompt-based Stop hook
-where a small, fast evaluator reads the condition plus the conversation each turn
-and returns yes/no with a reason. Cost is typically negligible. Use it for a
-**finite objective** that needs multiple turns to converge and whose
-done-condition is **demonstrable from the model's own surfaced output** — the
-evaluator runs NO tools, so surface the evidence (paste the test summary, echo
-the worklist, print the state). Write conditions the transcript can demonstrate
-("all referenced tests show as passing in the output" works; "the production
-database is consistent" does not). **Always embed a bound** ("or stop after 20
-turns / 30 minutes") so a non-converging goal terminates.
-
-**The load-bearing caveat — `/goal` provides CONTINUATION plus model-evaluated
-JUDGMENT, never deterministic VERIFICATION.** The evaluator judges the condition
-from the transcript; it does not run verification tools. Deterministic quality
-gates remain the source of truth: the project's test, typecheck, and lint
-commands and their **exit codes** decide whether work is correct. Never replace
-an exit-code gate with a model vote. The correct pattern is a goal whose
-condition references freshly-run gate output ("…until the test command prints 0
-failures **in this turn's output**"), backed by an actual gate run each turn —
-not a goal that asserts success on its own.
+Finite multi-turn objective. The evaluator runs no tools: surface fresh evidence (test summary, worklist, state) in the transcript, and always embed a bound ("or stop after 20 turns / 30 minutes"). `/goal` gives continuation and model judgment, never verification: fresh test/typecheck/lint exit codes decide, run each turn.
 
 ## See Also
 

package/rules/always-on/parallel-sessions.md

@@ -157,6 +157,8 @@ The git index and stash are **shared resources of the working copy**, not a priv
 
 **The only write channel a subagent has is editing files inside its own declared file scope.** All VCS operations — staging, committing, pushing — belong to the coordinator. This makes the PSA-004 guarantee structural rather than behavioural at the subagent layer: an agent that never touches the index cannot violate PSA-004 by construction.
 
+**Sole exception — worktree mode (`code-implementer` only).** It may stage its own files one by one (`git add <file>`) and `git commit` only when its prompt carries a line `WORKTREE-MODE: <absolute path> <branch>` AND `git rev-parse --show-toplevel` and `git branch --show-current` match that path and branch; otherwise the ban applies unchanged. A linked worktree has its own index, so the index race above does not exist there. The commit hook briefly adds an entry to the shared stash via lint-staged; the agent itself never runs `git stash`. Coordinator duty: never grant the coordinator's own worktree, never put two agents in one worktree. The wave-executor never sets the line. `git push`, merge, `git reset`, `git stash` and `git clean` stay banned in every mode, and the coordinator still publishes.
+
 **Anti-patterns:**
 - A subagent running `git add <its own files>` "to be helpful" before reporting done — even scoped to its own files, it races the coordinator's staging pass and any sibling's concurrent index write.
 - A subagent running `git stash` to "save progress" before switching tasks — report `blocked` and let the coordinator decide, never stash.
@@ -170,4 +172,4 @@ The git index and stash are **shared resources of the working copy**, not a priv
 - Using `git add .` in a shared workspace — you will commit another session's partial work.
 - Reverting "broken" commits without asking — another session may have intentionally pushed incremental progress.
 - Pausing at PSA-001 signals when your scope is unaffected — unnecessary interruptions slow the session.
-- A subagent staging or committing its own work (PSA-007).
+- A subagent staging or committing without a matching `WORKTREE-MODE` line, or as any agent other than `code-implementer` (PSA-007).

package/rules/opt-in-stack/backend-data.md

@@ -193,4 +193,4 @@ async function updateUser(id: string, data: Partial<User>): Promise<void> {
 - Batch operations: use `.upsert()` or `.insert()` with arrays instead of individual inserts in loops.
 
 ## See Also
-security-web.md · frontend.md · backend.md · swift.md · parallel-sessions.md
+security-web.md · frontend.md · backend.md · parallel-sessions.md

package/rules/opt-in-stack/backend.md

@@ -393,4 +393,4 @@ export async function askAI(prompt: string, options?: { model?: string; maxToken
 - Checking budget after the LLM call (check before, enforce before spending)
 
 ## See Also
-security-web.md · frontend.md · backend-data.md · swift.md · parallel-sessions.md
+parallel-sessions.md · vendored only for some archetypes, so possibly absent in this repo: security-web.md [nextjs-saas, nextjs-minimal, express-service] · frontend.md [nextjs-saas, nextjs-minimal] · backend-data.md [nextjs-saas]

package/rules/opt-in-stack/security-web.md

@@ -1,12 +1,16 @@
 ---
 globs:
   - src/middleware*.ts
+  - proxy.ts
+  - src/proxy.ts
   - src/app/**
   - next.config.*
   - src/lib/csp*
   - src/lib/cors*
 paths:
   - src/middleware*.ts
+  - proxy.ts
+  - src/proxy.ts
   - src/app/**
   - next.config.*
   - src/lib/csp*
@@ -197,4 +201,4 @@ securityMiddleware(app);
 - **Template Literals**: Never use tagged template literals with user input for SQL, HTML, or shell commands. Use parameterized queries, DOMPurify, or `child_process.execFile()` respectively.
 
 ## See Also
-frontend.md · backend.md · backend-data.md · swift.md · parallel-sessions.md
+parallel-sessions.md · vendored only for some archetypes, so possibly absent in this repo: frontend.md [nextjs-saas, nextjs-minimal] · backend.md [nextjs-saas, express-service, docker-service] · backend-data.md [nextjs-saas]

package/scripts/agent-usage-census.mjs

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+/**
+ * agent-usage-census.mjs — CLI shell over scripts/lib/agent-usage-census.mjs (#1617).
+ *
+ * Reads Claude Code subagent transcripts (read-only) and reports per agent type:
+ * dispatches, observed models, turns and output per run, cache rebuilds after
+ * idle gaps, and the median start context. Definitions: see the lib header.
+ *
+ * Usage: agent-usage-census.mjs [--days N] [--root DIR] [--json] [--top N]
+ * Exit:  0 measured · 1 bad argument · 2 root unreadable / measurement failed
+ */
+
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'node:fs';
+
+import { DEFAULT_DAYS, formatTable, runCensus } from './lib/agent-usage-census.mjs';
+import { writeStdoutLineSync } from './lib/io.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
+
+const USAGE = 'Usage: agent-usage-census.mjs [--days N] [--root DIR] [--json] [--top N] [--help]';
+
+export function parseArgs(argv) {
+  const out = { days: DEFAULT_DAYS, root: path.join(os.homedir(), '.claude', 'projects'), json: false, top: 25, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--json') out.json = true;
+    else if (a === '--help') out.help = true;
+    else if (a === '--days' || a === '--top') {
+      const v = Number(argv[++i]);
+      if (!Number.isFinite(v) || v <= 0) return { error: `${a} requires a positive number` };
+      out[a.slice(2)] = v;
+    } else if (a === '--root') {
+      const v = argv[++i];
+      if (!v) return { error: '--root requires a directory' };
+      out.root = path.resolve(v);
+    } else return { error: `Unknown argument: ${a}` };
+  }
+  return out;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.error) {
+    console.error(`Error: ${args.error}`);
+    console.error(USAGE);
+    process.exit(1);
+  }
+  if (args.help) {
+    console.log(USAGE);
+    console.log('');
+    console.log('Per agent type over the subagent transcripts of the last N days (read-only):');
+    console.log('  dispatches, observed models (share of turns), turns/run and output tokens/run (median),');
+    console.log('  cache rebuilds after > 5 min gaps, median start context.');
+    console.log('');
+    console.log(`  --days N   window in days (default ${DEFAULT_DAYS})`);
+    console.log('  --root D   transcript root (default ~/.claude/projects)');
+    console.log('  --json     machine-readable envelope on stdout');
+    console.log('  --top N    rows in the table (default 25)');
+    console.log('');
+    console.log('Exit: 0 measured · 1 bad argument · 2 root unreadable / measurement failed');
+    process.exit(0);
+  }
+  if (!fs.existsSync(args.root)) {
+    console.error(`Error: transcript root does not exist: ${args.root}`);
+    process.exit(2);
+  }
+  let result;
+  try {
+    result = await runCensus({ root: args.root, days: args.days });
+  } catch (err) {
+    console.error(`Error: census failed: ${err?.message ?? err}`);
+    process.exit(2);
+  }
+  writeStdoutLineSync(args.json ? JSON.stringify(result, null, 2) : formatTable(result, { top: args.top }));
+  process.exit(0);
+}
+
+if (isMainModule(import.meta.url)) main();

package/scripts/apply-session-learnings.mjs

@@ -73,12 +73,15 @@
  *      prune/rewrite, store lock not acquired). Unparseable store lines are
  *      NOT an error: they are kept verbatim, counted as `malformed` in the
  *      summary, and WARNed on stderr with their line numbers.
+ *   4  Refused: this host's learnings store role is invalid (owner.yaml
+ *      `learnings` or SO_LEARNINGS_STORE_ROLE, #1516/#1686) — nothing written
  */
 
 import { readFileSync, realpathSync } from 'node:fs';
 import path from 'node:path';
 import { validatePathInsideProject } from './lib/path-utils.mjs';
 import { LearningsLockError, readLearnings, withLearningsLock } from './lib/learnings/io.mjs';
+import { LearningsStoreRoleError } from './lib/learnings/store-role.mjs';
 import { pruneLearnings } from './lib/learnings/expiry-sweep.mjs';
 import {
   CURRENT_SCHEMA_VERSION,
@@ -87,6 +90,8 @@ import {
 } from './lib/learnings/schema.mjs';
 import { parseSessionConfig, readConfigFile } from './lib/config.mjs';
 import { isMainModule } from './lib/is-main-module.mjs';
+import { resolveLedgerPath } from './lib/ledger-path.mjs';
+import { resolveEventsLedgerRoot } from './lib/platform.mjs';
 
 const DEFAULT_FILE = '.orchestrator/metrics/learnings.jsonl';
 const ARCHIVE_BASENAME = 'learnings-archive.jsonl';
@@ -334,15 +339,22 @@ async function emitSessionWriteApplied({ repoRoot, filePath, payload }) {
   // inside the repo but living outside it is refused, and a root spelled
   // through a symlink (macOS /var → /private/var) still accepts the store
   // inside it. Runs after the write, so the store exists and resolves.
+  //
+  // #1722: the default store of a linked worktree that gitignores it lives in
+  // the main checkout, so the ledger root (resolveEventsLedgerRoot) is accepted
+  // too; a store outside BOTH roots is still refused.
   const file = canonicalPath(filePath);
-  const rel = path.relative(canonicalPath(repoRoot), file);
-  if (!validatePathInsideProject(file, repoRoot, { canonicalizeRoot: true }).ok) {
+  const root = [repoRoot, resolveEventsLedgerRoot(repoRoot)].find(
+    (r) => validatePathInsideProject(file, r, { canonicalizeRoot: true }).ok,
+  );
+  if (root === undefined) {
     process.stderr.write(
       `apply-session-learnings: skipped ${SESSION_WRITE_EVENT} — ${filePath} lies outside ` +
         `--repo-root ${repoRoot}\n`,
     );
     return;
   }
+  const rel = path.relative(canonicalPath(root), file);
   try {
     const { emitEvent, sessionAttribution } = await import('./lib/events.mjs');
     await emitEvent(
@@ -385,7 +397,9 @@ async function main(argv) {
   }
 
   const repoRoot = path.resolve(opts.repoRoot ?? process.cwd());
-  const filePath = path.resolve(repoRoot, opts.file ?? DEFAULT_FILE);
+  // #1722: only the DEFAULT store routes through the ledger resolver; an
+  // explicit --file stays exactly what the caller asked for.
+  const filePath = opts.file !== null ? path.resolve(repoRoot, opts.file) : resolveLedgerPath(DEFAULT_FILE, repoRoot);
   const archivePath = path.join(path.dirname(filePath), ARCHIVE_BASENAME);
   const decayRate = opts.decayRate ?? (await resolveDecayRate(repoRoot));
   const now = new Date();
@@ -429,6 +443,10 @@ async function main(argv) {
       // Joins the lock held below reentrantly; takes none on a dry run.
       res = await pruneLearnings({ filePath, archivePath, entries: built.next, now, dryRun: !opts.apply });
     } catch (err) {
+      if (err instanceof LearningsStoreRoleError) {
+        process.stderr.write(`apply-session-learnings: ${err.message}\n`);
+        return { code: 4 };
+      }
       process.stderr.write(`apply-session-learnings: prune/rewrite failed: ${err.message}\n`);
       return { code: 2 };
     }
@@ -443,6 +461,10 @@ async function main(argv) {
       process.stderr.write(`apply-session-learnings: ${err.message}\n`);
       return 2;
     }
+    if (err instanceof LearningsStoreRoleError) {
+      process.stderr.write(`apply-session-learnings: ${err.message}\n`);
+      return 4;
+    }
     throw err;
   }
   if ('code' in outcome) return outcome.code;
@@ -466,14 +488,20 @@ async function main(argv) {
     archived: res.archived,
     kept: res.kept,
     by_reason: byReason,
-    written: opts.apply ? res.kept : 0,
+    // On an inbox-role host (#1516) the live store is not rewritten: only
+    // records with new ids reach learnings-inbox.jsonl, so `kept` is no count
+    // of written records there (io.mjs prints the real numbers on stderr).
+    written: opts.apply && !res.skipped ? res.kept : 0,
+    ...(res.skipped ? { skipped: res.skipped } : {}),
   };
 
   // The event's presence is documented as proof the write ran
   // (docs/events-schema.md). pruneLearnings() returns early WITHOUT writing
   // exactly when the store and the next generation are both empty — the only
   // path that reports `scanned: 0` — so no store + empty input emits nothing.
-  if (opts.apply && res.scanned > 0) {
+  // No event on an inbox-role host (#1516): the store write it attests to did
+  // not happen there.
+  if (opts.apply && res.scanned > 0 && !res.skipped) {
     await emitSessionWriteApplied({
       repoRoot,
       filePath,
@@ -494,7 +522,7 @@ async function main(argv) {
       `${summary.dry_run ? '[dry-run] ' : ''}learnings: read ${summary.read}, confirmed ${summary.confirmed}, ` +
         `contradicted ${summary.contradicted}, appended ${summary.appended}, decayed ${summary.decayed} ` +
         `(rate ${decayRate}), pruned ${pruned}, consolidated ${summary.consolidated}, kept ${summary.kept}` +
-        `${summary.dry_run ? ' — nothing written' : ` — wrote ${summary.written}`}\n`,
+        `${summary.dry_run ? ' — nothing written' : summary.skipped ? ` — ${summary.skipped}: live store not rewritten` : ` — wrote ${summary.written}`}\n`,
     );
   }
   return 0;

package/scripts/archive-closed-prds.mjs

@@ -50,7 +50,7 @@ import { glabRun as defaultGlabRun } from './lib/vault-backfill/glab.mjs';
 import { archiveFileToVault, titleFromMarkdown } from './lib/vault-archive.mjs';
 import { defaultGlabRepo } from './lib/vcs-repo-spec.mjs';
 import { readLock } from './lib/session-lock.mjs';
-import { resolveStateMdPath } from './lib/state-md/frontmatter-mutators.mjs';
+import { resolveStateMdWriteTarget, warnForeignStateMd } from './lib/state-md/frontmatter-mutators.mjs';
 import { parseStateMd } from './lib/state-md/yaml-parser.mjs';
 import { isMainModule } from './lib/is-main-module.mjs';
 
@@ -224,6 +224,24 @@ export function classifyOwnership({ repoRoot, rel, sessionStartedAt, gitRunFn })
   return committedMs >= startedMs ? 'foreign' : 'mine';
 }
 
+/**
+ * Read THIS session's STATE.md frontmatter, or null. #1636: the write side's
+ * ownership rule — another platform's STATE.md not proven to be this process's
+ * (#1618) counts as absent, so it never lends its `started_at` / `issues:` to
+ * this run's `--apply` (both callers fail closed on null).
+ *
+ * @param {string} repoRoot
+ * @returns {Record<string, unknown>|null}
+ */
+function readOwnStateFrontmatter(repoRoot) {
+  const { path: stateMdPath, rejected } = resolveStateMdWriteTarget(repoRoot);
+  if (rejected) {
+    warnForeignStateMd('archive-closed-prds', rejected, stateMdPath);
+    return null;
+  }
+  return parseStateMd(readFileSync(stateMdPath, 'utf8'))?.frontmatter ?? null;
+}
+
 /**
  * Resolve THIS session's `started_at` (ISO-8601): the session lock first, the
  * STATE.md frontmatter as fallback.
@@ -239,8 +257,7 @@ export function readSessionStartedAt(repoRoot) {
     // fall through to STATE.md
   }
   try {
-    const parsed = parseStateMd(readFileSync(resolveStateMdPath(repoRoot), 'utf8'));
-    const startedAt = parsed?.frontmatter?.started_at;
+    const startedAt = readOwnStateFrontmatter(repoRoot)?.started_at;
     if (typeof startedAt === 'string' && !Number.isNaN(Date.parse(startedAt))) return startedAt;
   } catch {
     // no STATE.md, or unreadable → null (fail-closed at the call site)
@@ -255,8 +272,7 @@ export function readSessionStartedAt(repoRoot) {
  */
 function readSessionIssues(repoRoot) {
   try {
-    const parsed = parseStateMd(readFileSync(resolveStateMdPath(repoRoot), 'utf8'));
-    const issues = parsed?.frontmatter?.issues;
+    const issues = readOwnStateFrontmatter(repoRoot)?.issues;
     if (Array.isArray(issues)) return new Set(issues.map((n) => String(n)));
   } catch {
     // absent/unreadable → empty set