session-orchestrator 5.12.0 → 5.13.0

package/hooks/wave-scope-commit-guard.mjs

@@ -33,6 +33,11 @@
 //     through, so this guard is the only hard PSA-004 stop left for a
 //     lint-staged sweep — softening it would weaken detection for the very
 //     class it exists to catch.
+//   - A path outside allowedPaths that an EARLIER wave of this session
+//     declared (`filescopes/wave-<k>.scopes.json`, k < the manifest's wave,
+//     mtime not older than the session start) passes with an info line
+//     (#1680): the coordinator commits after the last wave, when the active
+//     manifest names only that wave's paths.
 //   - EMPTY allowedPaths is no longer a silent pass: a Discovery (read-only)
 //     manifest means no agent is committing, i.e. a coordinator commit between
 //     waves → allow with a note; a manifest older than the newest session
@@ -49,7 +54,7 @@
 
 import { execSync } from 'node:child_process';
 import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from 'node:fs';
-import { isAbsolute, join, relative, sep } from 'node:path';
+import { dirname, isAbsolute, join, relative, sep } from 'node:path';
 
 // Re-use existing helpers from scripts/lib/hardening.mjs.
 // IMPORTANT: import is resolved relative to THIS file's location (the hook
@@ -59,12 +64,14 @@ import { isAbsolute, join, relative, sep } from 'node:path';
 import { pathMatchesPattern } from '../scripts/lib/hardening.mjs';
 import { withStagingFenceLock } from '../scripts/lib/session-lock.mjs';
 import { isMainModule } from '../scripts/lib/is-main-module.mjs';
-import { resolveSessionRoot } from '../scripts/lib/platform.mjs';
-import { classifyEmptyScope, findOwnScopeFile, sessionAgeMs } from '../scripts/lib/scope-gate.mjs';
+import { resolveEventsLedgerRoot, resolveSessionRoot } from '../scripts/lib/platform.mjs';
+import { classifyEmptyScope, findOwnScopeFile, sessionAgeMs, unionFileScopes } from '../scripts/lib/scope-gate.mjs';
+import { readTailWindow } from '../scripts/lib/tail-window.mjs';
 import {
   classifyManifestSession,
   readProcessLocalSessionIds,
 } from '../scripts/lib/session-identity/own-session.mjs';
+import { resolveOwnLockRoot } from './_lib/hook-root.mjs';
 
 // Resolve the "current" agent id from SO_WAVE_AGENT_ID (when set by the
 // caller) or fall back to a PID-derived marker. The fence files themselves
@@ -157,7 +164,8 @@ function findOverlaps(fenceJsonPath, ourStaged) {
 /** Remediation for an allowedPaths violation, printed once per commit. */
 const ALLOWED_PATHS_HINT = [
   '',
-  'These files were likely added by lint-staged eslint --fix / prettier --write.',
+  'Each path is either from a previous session or wave that no wave scope of this',
+  'session declares, or a file lint-staged (eslint --fix / prettier --write) re-staged.',
   'To proceed:',
   '  1) git restore --staged <path>   # for each foreign path',
   '  2) git commit                    # retry',
@@ -186,6 +194,110 @@ function mtimeMsOf(file) {
   }
 }
 
+/** Emitted by `hooks/_lib/lock-bootstrap.mjs` on every session-lock acquire. */
+const LOCK_ACQUIRED_EVENT = 'orchestrator.session.lock.acquired';
+
+/**
+ * Tail window of events.jsonl searched for the genesis anchor (1 MiB, the same
+ * window `session-id.mjs` reads). CEILING (BV-004): a session whose first
+ * acquire scrolled out of it gets its re-acquires only, i.e. a later start —
+ * fewer earlier waves count, the guard blocks (safe direction). Revisit when a
+ * compacted session reports a block on its own earlier-wave path.
+ */
+const GENESIS_TAIL_BYTES = 1024 * 1024;
+
+/**
+ * Epoch ms of the FIRST `orchestrator.session.lock.acquired` event carrying one
+ * of this process's raw session ids, or `null` (#1681). A compact re-acquires
+ * the lock under the SAME raw id and rewrites both session clocks
+ * (`.claude/rules/identity-and-locks.md`); the first acquire is the start that
+ * survives it. Same anchor as `ownGenesisMs()` in
+ * `scripts/lib/sessions-staleness-banner.mjs`. Raw ids only, never the semantic
+ * label (two sessions can mint the same one, #1066). Never throws: a missing,
+ * unreadable or non-regular ledger yields `null`.
+ *
+ * @param {string} lockRoot root holding this session's lock
+ * @param {Set<string>} ownIds this process's raw session ids
+ * @returns {number|null}
+ */
+function ownGenesisMs(lockRoot, ownIds) {
+  if (ownIds.size === 0) return null;
+  let window;
+  try {
+    const ledger = join(resolveEventsLedgerRoot(lockRoot), '.orchestrator', 'metrics', 'events.jsonl');
+    window = readTailWindow(ledger, GENESIS_TAIL_BYTES, { noFollow: true });
+  } catch {
+    return null;
+  }
+  const lines = window.text.split('\n');
+  if (window.cut) lines.shift(); // the window began mid-record
+  let genesis = null;
+  for (const line of lines) {
+    if (!line.includes(LOCK_ACQUIRED_EVENT)) continue;
+    let record;
+    try {
+      record = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (record?.event !== LOCK_ACQUIRED_EVENT || !ownIds.has(record.session_id)) continue;
+    const ms = Date.parse(record.timestamp);
+    if (Number.isFinite(ms) && (genesis === null || ms < genesis)) genesis = ms;
+  }
+  return genesis;
+}
+
+/**
+ * The declared files of every EARLIER wave of this session, read from the
+ * per-wave aggregate sidecars `<manifest dir>/filescopes/wave-<k>.scopes.json`
+ * (`scripts/materialize-wave-scope.mjs`) for k < the manifest's `wave` (#1680).
+ * The coordinator commits after the LAST wave, when the active manifest names
+ * only that wave's paths; without this, a file an earlier wave of the same
+ * session changed blocked the commit.
+ *
+ * A sidecar counts only when its mtime is not older than this session's start
+ * (`now - sessionAge`); an unknown session clock reads none — fail closed, the
+ * pre-#1680 behaviour — so a stale `filescopes/` of an earlier session never
+ * widens the scope. Peer records are dropped by `unionFileScopes` (the same
+ * exclusion `--union` applies). An unreadable or malformed sidecar is skipped.
+ *
+ * CEILING (BV-004): consulted for every non-foreign manifest — own AND unknown
+ * (unbound, or a shell without a session id) — so a peer session sharing this
+ * working copy that materializes sidecars in the same state dir after our
+ * session start widens our coverage: the sidecars carry no session binding.
+ * Revisit when they gain one.
+ *
+ * #1681: `sessionAge` follows the NEWEST clock, and a compact rewrites both
+ * (`current-session.json.timestamp`, `session.lock.started_at`), so the start
+ * is pulled back to `genesisMs` — the first lock acquire of this session's raw
+ * id ({@link ownGenesisMs}). Only ever pulled back, never forward; without a
+ * genesis the clock alone decides, as before. A `/clear` mints a NEW raw id, so
+ * the waves before it stay outside (safe direction: the guard blocks).
+ *
+ * @param {string} scopePath absolute path of the active manifest
+ * @param {unknown} wave the manifest's `wave` field
+ * @param {number|null} sessionAge ms since the newest session clock
+ * @param {number|null} [genesisMs] epoch ms of this session's first lock acquire
+ * @returns {Array<{wave: number, files: string[]}>}
+ */
+function earlierWaveScopes(scopePath, wave, sessionAge, genesisMs = null, now = Date.now()) {
+  if (typeof sessionAge !== 'number' || !Number.isInteger(wave) || wave < 2) return [];
+  const sessionStartMs = typeof genesisMs === 'number' ? Math.min(now - sessionAge, genesisMs) : now - sessionAge;
+  const out = [];
+  for (let k = 1; k < wave; k++) {
+    const sidecar = join(dirname(scopePath), 'filescopes', `wave-${k}.scopes.json`);
+    const mtime = mtimeMsOf(sidecar);
+    if (mtime === null || mtime < sessionStartMs) continue;
+    try {
+      const files = unionFileScopes(JSON.parse(readFileSync(sidecar, 'utf8')));
+      if (files.length > 0) out.push({ wave: k, files });
+    } catch {
+      // unreadable / malformed: grants nothing
+    }
+  }
+  return out;
+}
+
 /**
  * Sub-mode B's decision, pure: which lines to print and whether to block.
  *
@@ -211,11 +323,14 @@ function mtimeMsOf(file) {
  * @param {Set<string>} p.ownIds this process's session ids
  * @param {number|null} p.scopeMtimeMs
  * @param {number|null} p.sessionAge ms since the newest session clock
+ * @param {Array<{wave: number, files: string[]}>} [p.earlierWaves] declared
+ *   files of this session's earlier waves (`earlierWaveScopes`, #1680); a
+ *   violating path one of them covers passes with an info line
  * @returns {{action: 'pass'|'report'|'block', lines: string[], hint?: string[]}}
  *   `hint` = the remediation block; `main()` prints it ONCE after every
  *   manifest was judged, so two blocking manifests do not repeat it (#1514.3).
  */
-function scopeCommitVerdict({ scope, stagedFiles, scopePathOf = (f) => f, scopeRel, ownIds, scopeMtimeMs, sessionAge }) {
+function scopeCommitVerdict({ scope, stagedFiles, scopePathOf = (f) => f, scopeRel, ownIds, scopeMtimeMs, sessionAge, earlierWaves = [] }) {
   if (stagedFiles.length === 0) return { action: 'pass', lines: [] };
 
   // Same classifier and same disposition as enforce-scope Gate 3b: only a
@@ -232,18 +347,25 @@ function scopeCommitVerdict({ scope, stagedFiles, scopePathOf = (f) => f, scopeR
 
   const allowedPaths = Array.isArray(scope.allowedPaths) ? scope.allowedPaths : [];
   if (allowedPaths.length > 0) {
-    const violations = stagedFiles.filter(
-      (f) => {
-        const scoped = scopePathOf(f);
-        return scoped === null || !allowedPaths.some((pattern) => pathMatchesPattern(scoped, pattern));
-      },
-    );
-    if (violations.length === 0) return { action: 'pass', lines: [] };
+    const violations = [];
+    const notes = [];
+    for (const f of stagedFiles) {
+      const scoped = scopePathOf(f);
+      if (scoped !== null && allowedPaths.some((pattern) => pathMatchesPattern(scoped, pattern))) continue;
+      // #1680: declared files only — no test-sibling expansion, no widening.
+      const earlier = scoped === null
+        ? undefined
+        : earlierWaves.find((w) => w.files.some((pattern) => pathMatchesPattern(scoped, pattern)));
+      if (earlier) notes.push(`wave-scope-commit-guard: ${f} belongs to wave ${earlier.wave} of this session — allowed.`);
+      else violations.push(f);
+    }
+    if (violations.length === 0) return { action: 'pass', lines: notes };
     // Blocks under `warn` too — see the header: in a warn-mode wave this is
     // the only hard stop a lint-staged sweep meets before the commit exists.
     return {
       action: 'block',
       lines: [
+        ...notes,
         `✗ wave-scope-commit-guard: staged paths outside wave-scope.allowedPaths (${scopeRel}):`,
         ...violations.map((v) => `  - ${v}`),
       ],
@@ -398,14 +520,21 @@ async function main() {
       process.exit(1);
     }
 
+    const manifest = scope !== null && typeof scope === 'object' ? scope : {};
+    // #1634: read the clock beside this session's own lock (its
+    // `session_root` after ExitWorktree), not at the commit's root.
+    const lockRoot = resolveOwnLockRoot({ session_id: [...ownIds][0] ?? null, cwd: root }, root);
+    const sessionAge = sessionAgeMs(lockRoot);
     const verdict = scopeCommitVerdict({
-      scope: scope !== null && typeof scope === 'object' ? scope : {},
+      scope: manifest,
       stagedFiles,
       scopePathOf,
       scopeRel,
       ownIds,
       scopeMtimeMs: mtimeMsOf(scopePath),
-      sessionAge: sessionAgeMs(root),
+      sessionAge,
+      // Consulted for any non-foreign (own or unknown) manifest: the verdict returns on a foreign one first.
+      earlierWaves: earlierWaveScopes(scopePath, manifest.wave, sessionAge, ownGenesisMs(lockRoot, ownIds)),
     });
     for (const line of verdict.lines) process.stderr.write(`${line}\n`);
     if (verdict.hint) hint = verdict.hint;

package/mods/so-hud/.claude-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "so-hud",
+  "version": "0.2.0",
+  "author": { "name": "session-orchestrator contributors" },
+  "description": "See Session Orchestrator status, warnings and session beacons in Claude Code ($.so contract v1), with protection gates for secret-printing commands, rule traps, outward actions and scope collisions.",
+  "types": "./types/index.d.ts",
+  "userConfig": {
+    "strictness": { "title": "Strictness profile", "type": "string", "description": "Strictness profile shown in the status line and returned by $.so.profile(). locker: rule traps and scope collisions only warn. ausgewogen (default): rule traps are refused and a scope collision asks first. streng: rule traps and scope collisions are refused. On every profile, secret-printing commands are refused and outward actions ask twice in an interactive session.", "options": ["locker", "ausgewogen", "streng"], "default": "ausgewogen" },
+    "soRoot": { "title": "Session Orchestrator path", "type": "string", "description": "Optional absolute path to the Session Orchestrator installation", "required": false }
+  }
+}

package/mods/so-hud/README.md

@@ -0,0 +1,57 @@
+# so-hud 0.2.0
+
+A native Session Orchestrator display for Claude Code (package A, #1508): a status line for the running session, a warning band when something needs attention, and one beacon file per session that other sessions can read through `$.so.beacons()`. The status line shows how many peer sessions are running (from the session registry). Since 0.2.0 it also checks tool calls before they run (#1551, see [Protection gates](#protection-gates)).
+
+## Requirements
+
+- Claude Code with mod support; tested with **2.1.296**. Claude Code only — Codex, Cursor and Pi do not load this mod.
+- **Node.js 24** or later.
+- **Session Orchestrator** from the release that ships this mod or later, as the plugin or as a checkout set through `soRoot`: the mod reads all state through its `scripts/so-hud.mjs`, which earlier releases do not have.
+
+## Install
+
+```text
+/plugin marketplace add Kanevry/session-orchestrator
+/plugin install so-hud@kanevry
+```
+
+The mod finds the Session Orchestrator installation in this order: the `soRoot` setting (an absolute path), then the path cached from an earlier lookup, then a root registered with `node scripts/so-hud.mjs --register-root` inside that installation, then `claude plugin list --json`. The first hit is cached, so after a move only `soRoot` replaces it. None of these install actions is run by the development tests. For a local checkout you can also load this directory directly with `claude --plugin-dir ./mods/so-hud`.
+
+Settings: `strictness` is `locker` (relaxed), `ausgewogen` (balanced, the default) or `streng` (strict); it is shown in the status line, returned by `$.so.profile()` and decides how the protection gates react. Until one is chosen, a band above the prompt shows the current profile with one button per profile (no hotkeys: a digit typed into an empty prompt would press one); a press saves it in this mod's `strictness` row of `/config`, used by every new session. `/profile` shows the profile and its effect without a model turn and opens the band, with `Schließen` to hide it for the session (#1552). The profile steers only these gates, not Session Orchestrator's own guards. `soRoot` is optional.
+
+**Upgrading from 0.1.0:** 0.1.0 only displayed state; 0.2.0 adds the [protection gates](#protection-gates), so outward actions such as push, merge, release and publish ask for two confirmations within 30 seconds, and commands that would print a secret are refused. `/plugin install` uses scope `user` by default, and an update at that scope changes every Claude Code session on the host at once, including lead sessions that merge through the API on the owner's word. Set `strictness` per host first (0.1.0 already has the row in `/config`), try 0.2.0 in one session (`claude --plugin-dir ./mods/so-hud`, or an install at project scope), and only then update the user-scope install: [docs/mods.md § Upgrading from 0.1.0 with scope user](../../docs/mods.md#upgrading-from-010-with-scope-user).
+
+## What it does
+
+Session Orchestrator state comes only from `scripts/so-hud.mjs`, called as `--json --repo-root <cwd> --session-id <raw-uuid>` every 15 seconds with a 3-second timeout. With `--session-id` the collector counts the session's agents beside its own `session.lock`, which can sit in another checkout than the cwd (#1730). A collector older than #1730 rejects the flag with exit 2; the mod then calls it without the flag for the rest of the session. STATE.md, locks, dispatch and events are never changed. The mod writes only its own beacon file, its install-path cache, the receipt lines in `aktionen.jsonl` (see below), and, when a profile is picked in the band, its own `strictness` row in `/config` and the store key `profile-chosen`. Without a Session Orchestrator root it asks `claude plugin list` at most once every 5 minutes.
+
+The status line says `nicht eingerichtet` for a part that is not set up (no Session Orchestrator installation found, no `vault-integration` block) and `noch kein Lauf` for an enabled vault mirror that never ran; a repository where no session has written events yet is not shown as `teilweise gemessen`.
+
+`$.so.version()` is 1; `snapshot()` and `beacons()` are asynchronous engine calls (`await`); `profile()` returns `locker`, `ausgewogen` or `streng`. A cold snapshot is `null`; an old one keeps its measurement time and carries `age_ms`; after a failed refresh it is kept and marked `degraded`.
+
+**Language:** the status texts and the texts of the protection gates are German. An English text table is prepared but not selectable yet, because JSON v1 has no field for the owner's language.
+
+Beacons: the `$.fs` API of this Claude Code build offers no rename, chmod or unlink, so `hooks/beacon-io.mjs` is called through `$.process.run` with argv and JSON on stdin: temporary file plus rename, mode 0600, beacon directory 0700, at most 4 KB. `hud/` and `hud/beacons/` must be real directories owned by the user, not symlinks, checked through an `O_NOFOLLOW` handle; where Node has no `O_NOFOLLOW` (native Windows) an `lstat` check stands in, and a link swapped in between check and `chmod` would be followed. Removing a beacon follows no symlink. The helper's parent PID stands for the starting engine process; that mapping still has to be confirmed in a real engine host. Foreign beacons are validated; one older than 120 seconds whose PID cannot be shown to be alive becomes state unknown. `tool.check: ask` means handing the decision on (also in auto mode), not proof that a dialog was shown.
+
+## Protection gates
+
+Before a shell command (`Bash`, `Monitor`, `PowerShell`) or a file edit runs, so-hud checks it, and it checks tool results before they reach the model (#1551). This is a behaviour change against 0.1.0: outward actions now ask twice by default, secret-printing commands are refused, and on the default profile `ausgewogen` rule traps such as `git add -A` are refused too.
+
+- **SEC-008 traps** (commands that would print a secret, such as `cat .env`, a bare `env`, `echo $TOKEN`, `docker inspect` without `--format`, a token in curl arguments or in a curl URL) are refused on every profile; the refusal names the safe replacement command.
+- **Rule traps** (`git add .`/`-A`/`--all`, `claude -p` without `env -u ANTHROPIC_API_KEY`, `${PIPESTATUS[`, `grep -c … || echo 0`) show a toast on `locker` and are refused on `ausgewogen` and `streng`.
+- **Outward actions** (push to `main`/`master`, force, tags or delete; merge; release; publish; production deploy) are held wherever a surface is attached (terminal, desktop, IDE, phone) until the owner confirms twice within 30 seconds; declining, closing the dialog or letting the time run out refuses the call. Only a plain push of a feature branch runs without a question (#1569): `git push [-u] origin feat/x`, `HEAD` or a bare `git push`; exact options; every earlier command on the line a local git call from an allowlist (`fetch` with no option and no `::` word, `log`/`show`/`diff` with display options only — `--output`, `--ext-diff`, `--textconv`, `--upload-pack` ask), so any earlier command that is not git (`npm test && git push origin feat/x`), and any earlier output redirection other than onto exactly `/dev/null` or between stdout and stderr (`git log … >> .git/config`, also on `cd`, an assignment or `exec`), makes every push form ask; after `add`, `commit`, `status`, `diff`, `fetch` or `checkout -- <paths>` on the line, only when so-hud measured that none of the hooks those steps can fire exists (a hook file of that name, in husky v9 the user's `.husky/<name>`, or a `hook.*` config entry for that event; see docs/mods.md § Limits) and the step ran in the push's own folder as written (`git -C ../b commit && git push …` asks; in a husky repository with a `.husky/pre-commit`, `git commit … && git push …` on one line asks); behind any git call, only when that call ran in the push's own folder as written and every key of the repository's own git config is on an allowlist (`core.fsmonitor`, `diff.external`, filters, textconv, `core.sshCommand`, `credential.helper`, `include.path` and any other key ask, and so does any submodule or embedded repository in the index, #1573); no earlier step that changes the branch, git config or the folder; harmless variable names only; a remote defined in git config; and the standard push configuration (`push.*`, `remote.<r>.push`, `remote.<r>.mirror`, push remotes and `submodule.recurse` are read). Lowercase `head`, `--no-verify` and every other shape ask. A run with no surface at all (a plain `claude -p`) cannot ask: so-hud writes a receipt and lets the call run, and there merges, releases, publishes and deploys are checked by no Session Orchestrator gate.
+- **Collision guard:** an edit of a file in the declared wave scope of another live Session Orchestrator session in the same working copy gives a toast on `locker`, a question on `ausgewogen` and a refusal on `streng`. Sessions that do not run Session Orchestrator are invisible to it.
+- **Secret shield:** a token in a tool result reaches the model as `[<kind> entfernt · sha256:<12 hex>]`, with a toast to rotate it.
+
+Every decision on an outward action appends one receipt line per held action, and every asked collision one line, to `~/.config/session-orchestrator/hud/aktionen.jsonl` (0600, append-only, a regular file with one link); it carries the SHA-256 of `JSON.stringify([tool, command])` — `[tool, file path]` for a collision — never the command. If the gate itself fails, the call is refused, except on `locker` for calls that are neither outward nor SEC-008. The gates are a hurdle, not the authority: pre-push hook, destructive-command guard and CI stay authoritative where they exist. Profiles, receipt fields, the full list of checked commands and the limits: [docs/mods.md](../../docs/mods.md).
+
+## Limits
+
+- A status without a session or wave binding is not attributed to the current wave.
+- Dispatch records do not always carry agent type or model; those fields stay null.
+- Peer scope is unknown when either scope source is missing or the scope signals have gaps.
+- Events are read only from the last 512 KB, reported as `events:tail-only`. There is no complete history.
+
+## Checks
+
+`npx vitest --run tests/so-hud` in the Session Orchestrator repo (CI job `test`). The CI job `mods:plugin` runs `claude plugin validate --strict --json` and `claude plugin test` for every mod. Engine integration separately with `claude plugin test mods/so-hud`; under Claude Code 2.1.296 the kit tests pass. `tsconfig.json` follows the header of the type file; the engine creates `.claude-plugin/types` when it loads the mod. No rollout, no commands from later packages and no second Session Orchestrator state.

package/mods/so-hud/hooks/beacon-io.mjs

@@ -0,0 +1,101 @@
+// Host-only helper: $.fs in build 2.1.296 has no append, rename, chmod or unlink.
+import fs from 'node:fs/promises';
+import { constants } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+// Closed receipt shape: no free-text field, so a command (which can carry a token) never reaches the file —
+// argv_sha256 is its only reference. Allowlist via Set, never `in` (that would admit `toString` and friends).
+const RECEIPT_KEYS = new Set(['zeit', 'session_id', 'vorgang', 'aktion', 'argv_sha256', 'exit', 'profil', 'ergebnis', 'art']);
+const RECEIPT_ENUMS = { vorgang: ['pane-aktion'], aktion: ['aussenwirkung', 'kollision'], profil: ['locker', 'ausgewogen', 'streng'], ergebnis: ['ausgefuehrt', 'abgelehnt', 'verfallen', 'ohne-zeichenflaeche', 'fehler'] };
+const validReceipt = (r, id) => r !== null && typeof r === 'object' && !Array.isArray(r)
+  && Object.keys(r).every(k => RECEIPT_KEYS.has(k)) && r.session_id === id
+  && Object.entries(RECEIPT_ENUMS).every(([k, allowed]) => allowed.includes(r[k]))
+  && typeof r.zeit === 'string' && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,3})?(Z|[+-]\d{2}:\d{2})$/.test(r.zeit) && Number.isFinite(Date.parse(r.zeit))
+  && typeof r.argv_sha256 === 'string' && /^[0-9a-f]{64}$/.test(r.argv_sha256)
+  && (r.exit === null || Number.isSafeInteger(r.exit))
+  && (r.art === undefined || (typeof r.art === 'string' && /^[a-z][a-z0-9-]{0,39}$/.test(r.art)));
+// A planted symlink (or a foreign-owned directory) at hud/ or hud/beacons/ would otherwise receive our chmod and our
+// writes. `uid` is undefined on native Windows (no process.getuid), where only the symlink/directory check applies.
+const ownDir = (st, uid) => {
+  if (st.isSymbolicLink() || !st.isDirectory() || (uid !== undefined && st.uid !== uid)) throw new Error('not a private directory');
+};
+async function privateDir(dir, { noFollow, uid }) {
+  await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+  if (noFollow) {
+    // The handle pins the checked inode: a symlink at `dir` fails this open, so check and chmod hit one directory.
+    const fh = await fs.open(dir, constants.O_RDONLY | constants.O_DIRECTORY | noFollow);
+    try { ownDir(await fh.stat(), uid); await fh.chmod(0o700); } finally { await fh.close(); }
+    return;
+  }
+  // No O_NOFOLLOW (native Windows): lstat, then chmod by path. Ceiling: a link swapped in between the two is followed;
+  // creating one needs admin or Developer Mode there. Revisit if Node exposes O_NOFOLLOW on Windows.
+  ownDir(await fs.lstat(dir), uid);
+  await fs.chmod(dir, 0o700);
+}
+// Ceiling for every path below a checked directory: Node has no openat(), so a process that can rename entries in
+// ~/.config/session-orchestrator could swap hud/ between the check and the file open. That is the user's own config
+// directory today; revisit if a shared or world-writable parent is ever supported.
+export async function beaconIO(action, id, input, { home = os.homedir(), pid = process.ppid, noFollow = constants.O_NOFOLLOW, uid = process.getuid?.() } = {}) {
+  if (action === 'identity') return { pid };
+  if (action === 'alive') {
+    const alive = [];
+    for (const p of input ?? []) {
+      if (!Number.isSafeInteger(p) || p <= 0) continue;
+      try { process.kill(p, 0); alive.push(p); } catch (e) { if (e.code === 'EPERM') alive.push(p); }
+    }
+    return alive;
+  }
+  if (!/^[a-zA-Z0-9_-]{1,200}$/.test(id ?? '')) throw new Error('invalid session');
+  const hud = path.join(home, '.config/session-orchestrator/hud');
+  if (action === 'aktion') {
+    if (!validReceipt(input, id)) throw new Error('invalid receipt');
+    const line = `${JSON.stringify(input)}\n`;
+    if (Buffer.byteLength(line) > 1024) throw new Error('receipt too large');
+    await privateDir(hud, { noFollow, uid });
+    const file = path.join(hud, 'aktionen.jsonl');
+    if (!noFollow) {
+      // Without O_NOFOLLOW, refuse a planted link or non-regular file by lstat first. Ceiling: same window as privateDir.
+      const st = await fs.lstat(file).catch(e => { if (e.code === 'ENOENT') return null; throw e; });
+      if (st && (st.isSymbolicLink() || !st.isFile() || st.nlink !== 1)) throw new Error('receipt path is not a regular file');
+    }
+    // Shared with other writers (owner-inbox): append-only, never read-modify-write; O_NOFOLLOW refuses a planted symlink.
+    const fh = await fs.open(file, constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | (noFollow || 0), 0o600);
+    try {
+      // A hard link planted at the path is a second name for a foreign file: refuse it before chmod or write touch it.
+      const st = await fh.stat();
+      if (!st.isFile() || st.nlink !== 1) throw new Error('receipt path is not a private regular file');
+      await fh.chmod(0o600);
+      await fh.write(line);
+    } finally { await fh.close(); }
+    return null;
+  }
+  const dir = path.join(hud, 'beacons');
+  const target = path.join(dir, `${id}.json`);
+  if (action === 'remove') {
+    // Never unlink through a planted link: check both directories, but create nothing.
+    try { for (const d of [hud, dir]) ownDir(await fs.lstat(d), uid); } catch (e) { if (e.code === 'ENOENT') return null; throw e; }
+    await fs.unlink(target).catch(e => { if (e.code !== 'ENOENT') throw e; });
+    return null;
+  }
+  if (action !== 'write' || input?.session_id !== id) throw new Error('invalid action');
+  const body = JSON.stringify(input);
+  if (Buffer.byteLength(body) > 4096) throw new Error('beacon too large');
+  await privateDir(hud, { noFollow, uid });
+  await privateDir(dir, { noFollow, uid });
+  // `wx` refuses a link planted at the temp name (EEXIST), and rename replaces a link at the target instead of following it.
+  const temp = `${target}.${process.pid}.tmp`;
+  try {
+    await fs.writeFile(temp, body, { mode: 0o600, flag: 'wx' });
+    await fs.rename(temp, target);
+  } finally { await fs.unlink(temp).catch(() => {}); }
+  return null;
+}
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    let input = '';
+    for await (const chunk of process.stdin) { input += chunk; if (input.length > 65536) throw new Error('input too large'); }
+    const out = await beaconIO(process.argv[2], process.argv[3], input ? JSON.parse(input) : null);
+    process.stdout.write(JSON.stringify(out));
+  } catch { process.stderr.write('so-hud: beacon I/O failed\n'); process.exitCode = 2; }
+}