session-orchestrator 3.20.0 → 3.22.0

package/scripts/lib/scope-gate.mjs

@@ -917,3 +917,661 @@ export function suggestForScopeViolation(relPath, allowedCsv) {
     `If '${relPath}' belongs to this wave, add its directory to the plan's wave scope and restart.`
   );
 }
+
+/**
+ * Merge many agents' declared file scopes into ONE deduplicated, order-stable
+ * list — the mechanical form of "allowedPaths is the UNION of all agent file
+ * scopes" (#1020, wave-loop.md § Scope Manifest #3).
+ *
+ * Motivation: today the coordinator writes `wave-scope.json` `allowedPaths` from
+ * one hand-kept list and the agent briefs from a SECOND, separately formulated
+ * list. Nothing couples them; they diverged five times in one session (#1020).
+ * Deriving the union FROM the per-agent declarations makes that divergence
+ * structurally impossible instead of discipline-dependent.
+ *
+ * Accepts BOTH input shapes, because the two call sites differ:
+ *   - `[['a.mjs','b.mjs'], ['c.mjs']]`                 — bare scope arrays
+ *   - `[{id:'W1-D1', files:['a.mjs']}, {id:'W1-D2', …}]` — the CLI/plan record
+ *     shape, which is also {@link findScopeCollisions}' input (one source object
+ *     feeding both consumers is the whole point of #1020).
+ *
+ * Order is INSERTION order (first-seen wins), never sorted: the union is written
+ * into a manifest that a human reads next to the plan, and a stable order keeps
+ * its diff readable across re-unions (#796 rewrites it mid-wave).
+ *
+ * Fail-closed & no-throw (module convention): a non-array input returns `[]`;
+ * non-array / non-object members and non-string, empty entries are skipped.
+ * Pure, sync, no I/O — hook-safe per the module header.
+ *
+ * @param {Array<string[]|{id?: string, files?: string[]}>} scopes
+ * @returns {string[]} deduplicated union in first-seen order
+ */
+export function unionFileScopes(scopes) {
+  if (!Array.isArray(scopes)) return [];
+  const out = [];
+  const seen = new Set();
+  for (const scope of scopes) {
+    let files = null;
+    if (Array.isArray(scope)) files = scope;
+    else if (scope !== null && typeof scope === 'object' && Array.isArray(scope.files)) {
+      files = scope.files;
+    }
+    if (files === null) continue;
+    for (const entry of files) {
+      if (typeof entry !== 'string' || entry.length === 0) continue;
+      if (seen.has(entry)) continue;
+      seen.add(entry);
+      out.push(entry);
+    }
+  }
+  return out;
+}
+
+/**
+ * Is this scope entry RECURSIVE — does it grant everything below a directory?
+ * `**` is the explicit form; a trailing `/` is the implicit one, because
+ * {@link pathMatchesPattern} matches a `dir/` prefix with `startsWith`, i.e. at
+ * ANY depth. Both must count, or `tests/` vs `tests/lib/*.mjs` reads as disjoint.
+ * @param {string} entry
+ * @returns {boolean}
+ */
+function isRecursiveScopeEntry(entry) {
+  return entry.includes('**') || entry.endsWith('/');
+}
+
+/**
+ * Literal SUFFIX of a glob entry — the text after its last `*` metachar
+ * (`src/**\/*.mjs` → `.mjs`, `src/**` → `''`). Returns `null` for an entry with
+ * no `*` at all (a `dir/` prefix), where the concept does not apply: such an
+ * entry constrains only the head of a path, never its tail.
+ * @param {string} entry
+ * @returns {string|null}
+ */
+function literalScopeSuffix(entry) {
+  const star = entry.lastIndexOf('*');
+  return star === -1 ? null : entry.slice(star + 1);
+}
+
+/**
+ * Normalize the `agentScopes` input of {@link findScopeCollisions} into
+ * `{id, declaredId, files}` records. Never throws; malformed members are
+ * repaired rather than dropped.
+ *
+ * A member with NO usable `id` keeps its files in the check under a synthetic
+ * `<unnamed#i>` id (i = its index). Dropping it instead would be a FALSE
+ * NEGATIVE — the whole point of this function is that an unreviewed scope is
+ * exactly the one that collides.
+ *
+ * @param {Array<{id?: string, files?: string[]}>} agentScopes
+ * @returns {Array<{id: string, declaredId: string|null, files: string[]}>}
+ */
+function normalizeAgentScopes(agentScopes) {
+  const out = [];
+  for (let i = 0; i < agentScopes.length; i++) {
+    const raw = agentScopes[i];
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) continue;
+    const declaredId = typeof raw.id === 'string' && raw.id.length > 0 ? raw.id : null;
+    const files = Array.isArray(raw.files)
+      ? raw.files.filter((f) => typeof f === 'string' && f.length > 0)
+      : [];
+    out.push({ id: declaredId ?? `<unnamed#${i}>`, declaredId, files });
+  }
+  return out;
+}
+
+/**
+ * Classify a SINGLE cross-agent entry pair, in the binding three-stage order.
+ * Returns the collision `kind`, or `null` when the two entries are disjoint.
+ *
+ * Stage order is not cosmetic — see {@link findScopeCollisions} for why the two
+ * exact stages must run BEFORE the approximate one.
+ *
+ * @param {string} x — an entry from agent A
+ * @param {string} y — an entry from agent B
+ * @param {(glob: string) => Set<string>} expand — memoized KNOWN-set expander
+ * @returns {'concrete'|'glob-expanded'|'glob-prefix'|null}
+ */
+function classifyEntryCollision(x, y, expand) {
+  // Stage 1 — exact string equality. The commonest real case (#1020 Vorfall 3),
+  // and the ONLY stage that works for a file that does not exist yet.
+  if (x === y) return 'concrete';
+
+  const xIsGlob = isGlobScopeEntry(x);
+  const yIsGlob = isGlobScopeEntry(y);
+
+  // Stage 2 — concrete vs glob. `pathMatchesPattern` is DIRECTED (arg 1 is a
+  // literal path, arg 2 becomes the regex); used in that one correct direction
+  // it is exact and needs no filesystem witness.
+  if (!xIsGlob && yIsGlob) return pathMatchesPattern(x, y) ? 'concrete' : null;
+  if (xIsGlob && !yIsGlob) return pathMatchesPattern(y, x) ? 'concrete' : null;
+  if (!xIsGlob && !yIsGlob) return null; // two distinct concrete paths: disjoint
+
+  // Stage 3a — glob ∩ glob, decided by a shared WITNESS from the KNOWN set.
+  const xHits = expand(x);
+  for (const witness of expand(y)) {
+    if (xHits.has(witness)) return 'glob-expanded';
+  }
+
+  // Stage 3b — prefix fallback, for the intersection that exists only in files
+  // NOT YET on disk (the KNOWN set cannot witness those).
+  const xPrefix = literalScopePrefix(x);
+  const yPrefix = literalScopePrefix(y);
+  if (!(xPrefix.startsWith(yPrefix) || yPrefix.startsWith(xPrefix))) return null;
+  if (!(isRecursiveScopeEntry(x) || isRecursiveScopeEntry(y))) return null;
+  // Suffix compatibility is a NECESSARY condition, so filtering on it adds no
+  // false negative: a string ending in both `sx` and `sy` forces the shorter to
+  // be a suffix of the longer. It removes the obvious false positive
+  // `scripts/**\/*.ts` vs `scripts/**\/*.mjs`, which share a prefix and are both
+  // recursive yet can never match the same path.
+  const xSuffix = literalScopeSuffix(x);
+  const ySuffix = literalScopeSuffix(y);
+  if (
+    xSuffix !== null &&
+    ySuffix !== null &&
+    !(xSuffix.endsWith(ySuffix) || ySuffix.endsWith(xSuffix))
+  ) {
+    return null;
+  }
+  return 'glob-prefix';
+}
+
+/**
+ * Detect files claimed by TWO agents of the SAME wave, BEFORE dispatch (#1020).
+ *
+ * ## The bug this closes
+ * `tests/scripts/sweep-expired-learnings-cli.test.mjs` was handed to two agents
+ * of one wave (#1020 Vorfall 3). Nothing caught it up front: the pre-dispatch
+ * assertion {@link assertFileScopeSubset} checks each agent against the union
+ * (a SUBSET relation, which two overlapping agents both satisfy), and the
+ * commit-time `wave-scope-commit-guard` only sees the union as well. It surfaced
+ * afterwards, from an agent's own PSA-002 report. Per
+ * `.claude/rules/parallel-sessions.md` § Decision Tree a file inside two
+ * declared scopes of one dispatch round is never a benign sibling signal — it is
+ * a deconfliction gap, and that round ended well by luck, not construction.
+ *
+ * ## The three stages, and why the order is binding
+ *  1. **Exact string equality** → `concrete`. Covers the commonest real case AND
+ *     every file that does not exist yet (no filesystem witness required).
+ *  2. **Concrete vs glob** via {@link pathMatchesPattern} → `concrete`. Exact and
+ *     I/O-free, because the matcher is used in its one correct direction.
+ *  3. **Glob vs glob** — expand both against
+ *     `KNOWN = opts.knownFiles ∪ {every concrete entry of every agent}`;
+ *     a non-empty intersection is `glob-expanded`. As a fallback for files not
+ *     yet on disk, a literal-prefix containment plus at least one recursive
+ *     entry is `glob-prefix`.
+ *
+ * Stage 3 must come LAST because {@link pathMatchesPattern} is DIRECTED and
+ * therefore useless for glob∩glob: it compiles argument 2 into a regex and tests
+ * argument 1 as a literal string. Measured:
+ * `pathMatchesPattern('scripts/**\/*.mjs', 'scripts/lib/*.mjs') === false`, even
+ * though both match `scripts/lib/x.mjs`. {@link assertFileScopeSubset} documents
+ * that boundary at its own glob branch and OVER-approximates coverage, which is
+ * the safe direction for a subset check. For a COLLISION check the sign flips:
+ * the same over-approximation becomes a FALSE NEGATIVE — a missed collision,
+ * i.e. exactly the incident. Hence stages 1 and 2 decide first, and stage 3 is
+ * reached only for pairs neither of them can settle.
+ *
+ * ## Duplicate ids are a SEPARATE finding, not a collision
+ * Two records carrying the same `id` are a malformed plan, not two agents
+ * fighting over a file; reporting them as a self-collision (`a === b`) would be
+ * noise. They are listed in `duplicateIds` and such pairs are skipped in the
+ * pairwise scan. `duplicateIds` is always present (empty when clean) so
+ * consumers need no conditional-key handling.
+ *
+ * ## `knownFiles` is INJECTED, never discovered
+ * The module header's hook-safe invariant (pure, sync, no I/O, no process spawn)
+ * is binding: `hooks/enforce-scope.mjs` reaches this module on a hot path, and
+ * under the exit-0/stdout-JSON protocol a throw here reads as "no decision" =
+ * ALLOW. So `git ls-files` belongs to the CLI layer and its result arrives as a
+ * parameter. An absent/invalid `knownFiles` is not an error — stage 3a simply
+ * has fewer witnesses and stage 3b carries the load.
+ *
+ * Fail-closed & no-throw: a non-array `agentScopes` returns
+ * `{ ok: false, collisions: [], duplicateIds: [] }` ("cannot assert → treat as
+ * failure", the same convention as {@link assertFileScopeSubset}).
+ *
+ * Output ordering is deterministic: agent pairs in input order, then kinds in
+ * stage order (`concrete` → `glob-expanded` → `glob-prefix`); `evidence` holds
+ * the involved entries of that kind, deduplicated in first-seen order.
+ *
+ * @param {Array<{id?: string, files?: string[]}>} agentScopes — one wave's agents
+ * @param {{knownFiles?: string[]}} [opts] — existing repo files (injected)
+ * @returns {{ok: boolean,
+ *            collisions: Array<{a: string, b: string, evidence: string[],
+ *                               kind: 'concrete'|'glob-expanded'|'glob-prefix'}>,
+ *            duplicateIds: string[]}}
+ */
+export function findScopeCollisions(agentScopes, opts = {}) {
+  if (!Array.isArray(agentScopes)) return { ok: false, collisions: [], duplicateIds: [] };
+  const options = opts !== null && typeof opts === 'object' ? opts : {};
+  const agents = normalizeAgentScopes(agentScopes);
+
+  // Duplicate DECLARED ids (synthetic `<unnamed#i>` ids are unique by index).
+  const seenIds = new Set();
+  const dupIds = new Set(); // Set preserves insertion order → stable report
+  for (const agent of agents) {
+    if (agent.declaredId === null) continue;
+    if (seenIds.has(agent.declaredId)) dupIds.add(agent.declaredId);
+    else seenIds.add(agent.declaredId);
+  }
+  const duplicateIds = [...dupIds];
+
+  // KNOWN = injected repo files ∪ every concrete entry of every agent. The
+  // second half matters: a file the wave is about to CREATE is not in
+  // `git ls-files`, but if one agent names it concretely it can still witness
+  // another agent's glob.
+  const known = [];
+  const knownSeen = new Set();
+  const addKnown = (f) => {
+    if (typeof f !== 'string' || f.length === 0 || knownSeen.has(f)) return;
+    knownSeen.add(f);
+    known.push(f);
+  };
+  if (Array.isArray(options.knownFiles)) options.knownFiles.forEach(addKnown);
+  for (const agent of agents) {
+    for (const entry of agent.files) if (!isGlobScopeEntry(entry)) addKnown(entry);
+  }
+
+  const expansions = new Map();
+  const expand = (glob) => {
+    let hits = expansions.get(glob);
+    if (hits === undefined) {
+      hits = new Set(known.filter((f) => pathMatchesPattern(f, glob)));
+      expansions.set(glob, hits);
+    }
+    return hits;
+  };
+
+  const KIND_ORDER = ['concrete', 'glob-expanded', 'glob-prefix'];
+  const collisions = [];
+  for (let i = 0; i < agents.length; i++) {
+    for (let j = i + 1; j < agents.length; j++) {
+      const a = agents[i];
+      const b = agents[j];
+      if (a.id === b.id) continue; // duplicate-id record: reported separately
+      const buckets = new Map();
+      for (const x of a.files) {
+        for (const y of b.files) {
+          const kind = classifyEntryCollision(x, y, expand);
+          if (kind === null) continue;
+          let evidence = buckets.get(kind);
+          if (evidence === undefined) {
+            evidence = new Set();
+            buckets.set(kind, evidence);
+          }
+          evidence.add(x);
+          evidence.add(y);
+        }
+      }
+      for (const kind of KIND_ORDER) {
+        const evidence = buckets.get(kind);
+        if (evidence !== undefined) {
+          collisions.push({ a: a.id, b: b.id, evidence: [...evidence], kind });
+        }
+      }
+    }
+  }
+
+  return { ok: collisions.length === 0 && duplicateIds.length === 0, collisions, duplicateIds };
+}
+
+// ---------------------------------------------------------------------------
+// Empty-`allowedPaths` classification (#1057)
+// ---------------------------------------------------------------------------
+//
+// ## The bug this fixes — and the one it deliberately does NOT
+//
+// FIVE distinct repository states produce `allowedPaths.length === 0`, and the
+// DENY VERDICT IS CORRECT IN ALL FIVE. What collapses is the REASON: every one
+// of them printed the single sentence {@link suggestForScopeViolation} emits for
+// an empty allowlist — "update the session plan and restart the wave".
+//
+//   1. A Discovery wave, where `[]` is the deliberate read-only contract
+//      (`skills/session-plan/SKILL.md`, `wave-loop.md` § Scope Manifest #5, and
+//      the #256 NO-OP regression lock in tests/hooks/enforce-scope.test.mjs).
+//      There the sentence is CORRECT but misleading — nothing is broken.
+//   2. Corrupt JSON, which `hooks/enforce-scope.mjs` folds onto `scope = {}`
+//      (#794 GAP-5), and malformed `allowedPaths` shapes, which `Array.isArray`
+//      folds onto `[]` (#558). There the sentence is USELESS — the plan is fine,
+//      the file is not.
+//   3. A leftover manifest from a session that crashed before deleting it.
+//      There the sentence is ACTIVELY WRONG: restarting the wave does not remove
+//      a file the previous session left behind — only the coordinator can clear
+//      it, and the branch says so WITHOUT handing over the command (see "The
+//      channel belongs to the AGENT" below, which is why).
+//   4. A writable role whose union came out empty because the coordinator's
+//      `--union` step did not complete. There the operator must re-run `--union`,
+//      not restart.
+//
+// The classifier below is the discriminator. It changes NO verdict — see
+// {@link suggestForEmptyScope}, which only ever selects a different sentence.
+//
+// ## The channel belongs to the AGENT — no branch may carry a runnable command
+//
+// Every string {@link suggestForEmptyScope} returns travels in
+// `permissionDecisionReason`, which the harness feeds to the CLAUDE whose Edit
+// was just denied. A remediation command placed there is an instruction the
+// DENIED AGENT can run — and for this guard the remediation IS the disarm:
+// removing `wave-scope.json` drops `hooks/enforce-scope.mjs` at Gate 3
+// (`if (!scopePath) return emitAllow()`), which takes out project-root
+// containment (Gate 6) as well as the allowlist check (Gate 7), for the rest of
+// the session. Measured 2026-08-19 against HEAD 55279a2: `rm -f <manifest>`
+// exits 0 with no envelope from `hooks/pre-bash-destructive-guard.mjs` (its
+// only rm rule is `rm-rf-destructive`, which needs `-r`), and with the manifest
+// gone a `Write` to `/etc` is ALLOWED. The first shape of this branch shipped
+// exactly that command, so the guard was handing the agent the key to itself.
+//
+// The rule this leaves behind: a branch may DIAGNOSE without limit and may name
+// the manifest as the SUBJECT of its diagnosis; it may never carry a runnable
+// command, and never present the manifest as a removal TARGET. Operator
+// remediation stays where the operator already looks —
+// `skills/session-end/SKILL.md` § 3.0 Defensive Cleanup and
+// `skills/wave-executor/wave-loop.md` steps 5/7 — not in a channel whose reader
+// is the denied agent.
+//
+// `emitDeny`'s `opts.systemMessage` is NOT the escape hatch this wants: the repo
+// documents its audience two ways that contradict each other — `scripts/lib/io.mjs`
+// § "Emitted payload" calls it "what the operator sees";
+// `skills/hook-development/SKILL.md` § "PreToolUse output schema" calls it
+// "Explanation shown to Claude". A session-wide guard disarm is not the payload
+// to bet on whichever of the two is right. Locked by
+// tests/lib/scope-gate.test.mjs § "no branch carries a runnable shell command".
+//
+// ## …and the reader may not be the OWNER (measured 2026-08-19)
+//
+// The staleness comparison is per-WORKING-COPY, not per-session. Both clocks
+// `sessionAgeMs` reads — `.orchestrator/current-session.json` `timestamp` and
+// `.orchestrator/session.lock` `started_at` — are shared by every session in the
+// checkout, and it takes the MINIMUM AGE, i.e. the NEWEST of the two. So a second
+// session starting at 18:51 moves the clock forward for EVERYONE, and every
+// manifest written before 18:51 — including the live one the first session is
+// using right now — classifies as `stale-manifest` for every subsequent reader.
+//
+// Measured in this repo at HEAD 55279a2: `session.lock` `started_at`
+// 2026-08-19T12:02:57Z (the running deep session) vs. `current-session.json`
+// `timestamp` 2026-08-19T18:51:54Z (a parallel session) — 6h49m apart, effective
+// `sessionStartMs` 18:51:54. Every wave manifest that session wrote between 12:02
+// and 18:51 is `mtime < sessionStartMs`. It is not hypothetical either: a
+// parallel session in this working copy was shown this very branch for the
+// coordinator's LIVE wave-4 manifest and told to delete it; it declined because
+// the operator works carefully, which is not a control.
+//
+// That is why the branch says "either a leftover or a parallel session's live
+// manifest" and routes to `blocked` instead of to a repair: the classifier cannot
+// distinguish the two, and the reader is frequently not the owner. PSA-001's
+// question — "Did I create this file? If not, it is not mine to touch" — is the
+// only safe posture a string in this channel can carry.
+//
+// Revisit trigger: a manifest that records its OWNING session id, which would let
+// this compare ownership instead of clocks. Until then the ambiguity is stated in
+// the text rather than resolved by a guess.
+//
+// ## Named ceiling (BV-004)
+//
+//   - This buys a CORRECT DIAGNOSIS, never an unlock and never a command. A
+//     writable wave with a broken union still denies every write; the reader is
+//     told WHICH of the five states it is in, and who owns the repair.
+//   - It cannot see a union that is NON-EMPTY but WRONG. That is
+//     `--assert-subset`'s job and stays there.
+//   - `stale-manifest` degrades to `'unknown'` when no session clock is
+//     readable — never to an allow. Absence is preserved, never guessed.
+//   - There is NO age threshold and no TTL. The comparison is a PROVENANCE
+//     subtraction (manifest mtime vs. this session's start), so a legitimate
+//     14-hour deep session never ages into a blind spot. Deliberately NOT
+//     `IN_FLIGHT_TTL_MS` — see `hooks/post-bash-write-verify.mjs` § "Why the
+//     minimum, and why NOT a staleness cap" for the argument this inherits.
+//   - Revisit trigger: a second read-only wave role, or a manifest written by a
+//     process whose clock is not this repo's `.orchestrator/` pair.
+// ---------------------------------------------------------------------------
+
+/**
+ * The closed set of {@link classifyEmptyScope} verdicts. Shaped after
+ * `DEGRADED_REASONS` in `scripts/lib/mirror-issues-banner.mjs`: a frozen array
+ * so a consumer can enumerate the states rather than re-listing them in prose.
+ *
+ * `'unknown'` is a first-class member, not an error — it is what the classifier
+ * returns when the inputs do not DECIDE, and it maps to the pre-#1057 generic
+ * sentence. Absence-preserving by construction.
+ *
+ * @type {ReadonlyArray<'unreadable'|'read-only-role'|'stale-manifest'|'writer-defect'|'unknown'>}
+ */
+export const EMPTY_SCOPE_REASONS = Object.freeze([
+  'unreadable',
+  'read-only-role',
+  'stale-manifest',
+  'writer-defect',
+  'unknown',
+]);
+
+/**
+ * Wave roles for which an EMPTY `allowedPaths` is the intended contract rather
+ * than a defect. THE list — `skills/session-plan/SKILL.md` § Discovery and
+ * `skills/wave-executor/wave-loop.md` § Scope Manifest #5 describe it; they do
+ * not restate it.
+ *
+ * Canonical casing; comparison is trimmed + case-insensitive (see
+ * {@link isReadOnlyWaveRole}) for the same reason
+ * {@link TEST_SIBLING_EXPANSION_ROLES} is: the manifest on disk is written by
+ * LLM prose and by hand, and `"discovery"` vs `Discovery` must not silently
+ * change which sentence the operator reads.
+ *
+ * @type {ReadonlyArray<string>}
+ */
+export const READ_ONLY_WAVE_ROLES = Object.freeze(['Discovery']);
+
+/** Lower-cased lookup for {@link isReadOnlyWaveRole}. @type {ReadonlyMap<string, string>} */
+const READ_ONLY_ROLE_KEYS = new Map(READ_ONLY_WAVE_ROLES.map((r) => [r.toLowerCase(), r]));
+
+/**
+ * Is this wave role one for which `allowedPaths: []` is BY DESIGN?
+ *
+ * Trimmed + case-insensitive; a non-string role is never read-only (fail-closed
+ * in the direction that produces a MORE alarming message, never a quieter one).
+ *
+ * @param {unknown} role
+ * @returns {boolean}
+ */
+export function isReadOnlyWaveRole(role) {
+  if (typeof role !== 'string') return false;
+  return READ_ONLY_ROLE_KEYS.has(role.trim().toLowerCase());
+}
+
+/**
+ * Classify WHY a wave manifest grants zero paths. Pure, sync, no I/O — every
+ * observation is passed in, exactly like {@link testSiblingExpansionApplies}.
+ * Never throws.
+ *
+ * Modelled on `readLockDetailed` (`scripts/lib/session-lock.mjs`): a small
+ * closed status union, where "cannot tell" is its own member instead of being
+ * folded into the most alarming one.
+ *
+ * ## Precedence (each rung is load-bearing)
+ *
+ *   1. `parseOk === false` → `'unreadable'`. FIRST, because a manifest that did
+ *      not parse has no trustworthy `role` either — reading `role` off `{}` and
+ *      reporting "writer defect" would blame the coordinator for a corrupt file.
+ *      Only an EXPLICIT `false` classifies; `undefined` means "caller did not
+ *      observe it" and falls through.
+ *   2. `role` ∈ {@link READ_ONLY_WAVE_ROLES} → `'read-only-role'`. Before the
+ *      clock comparison ON PURPOSE: for a Discovery wave the empty scope is the
+ *      contract whether the manifest is one second or one day old, so a stale
+ *      Discovery leftover reports the read-only sentence. The cost is named
+ *      rather than hidden — it is the one state where a leftover manifest is
+ *      described by its role instead of by its age.
+ *   3. `scopeMtimeMs < sessionStartMs` → `'stale-manifest'`. Requires BOTH
+ *      clocks to be finite numbers; either one absent ⇒ `'unknown'`, never a
+ *      guess in either direction.
+ *   4. A writable role with a manifest at least as new as this session ⇒
+ *      `'writer-defect'`.
+ *   5. Everything else ⇒ `'unknown'`.
+ *
+ * @param {{role?: unknown, parseOk?: unknown, scopeMtimeMs?: unknown, sessionStartMs?: unknown}} [input]
+ * @returns {'unreadable'|'read-only-role'|'stale-manifest'|'writer-defect'|'unknown'}
+ */
+export function classifyEmptyScope(input = {}) {
+  if (input === null || typeof input !== 'object') return 'unknown';
+
+  if (input.parseOk === false) return 'unreadable';
+  if (isReadOnlyWaveRole(input.role)) return 'read-only-role';
+
+  const mtime = typeof input.scopeMtimeMs === 'number' && Number.isFinite(input.scopeMtimeMs)
+    ? input.scopeMtimeMs
+    : null;
+  const started = typeof input.sessionStartMs === 'number' && Number.isFinite(input.sessionStartMs)
+    ? input.sessionStartMs
+    : null;
+  if (mtime === null || started === null) return 'unknown';
+
+  if (mtime < started) return 'stale-manifest';
+  return typeof input.role === 'string' && input.role.trim().length > 0
+    ? 'writer-defect'
+    : 'unknown';
+}
+
+/**
+ * The suggestion half of a scope-violation deny, when `allowedPaths` is EMPTY.
+ *
+ * A strict superset of {@link suggestForScopeViolation}'s empty-allowlist
+ * branch: `'unknown'` delegates to it verbatim, so the pre-#1057 sentence has
+ * exactly one copy and every other branch is an ADDITION. Pure, sync, never
+ * throws.
+ *
+ * @param {string} relPath — the project-relative path that was blocked
+ * @param {string} reason — a {@link EMPTY_SCOPE_REASONS} member; anything else
+ *   is treated as `'unknown'` (fail-safe toward the generic text)
+ * @param {{role?: unknown, scopePath?: unknown}} [opts]
+ *   `scopePath` is the manifest's location, project-relative where possible. It
+ *   is named as the SUBJECT of a diagnosis ("this file is a leftover") and never
+ *   as the target of a removal — see the module block above, § "The channel
+ *   belongs to the AGENT".
+ * @returns {string}
+ */
+export function suggestForEmptyScope(relPath, reason, opts = {}) {
+  const bag = opts !== null && typeof opts === 'object' ? opts : {};
+  const scopeHint = typeof bag.scopePath === 'string' && bag.scopePath.length > 0
+    ? bag.scopePath
+    : '<state-dir>/wave-scope.json';
+  const rawRole = typeof bag.role === 'string' ? bag.role.trim() : '';
+
+  switch (reason) {
+    case 'unreadable':
+      return (
+        `wave-scope.json is unreadable — failing closed. ` +
+        `The manifest exists but did not parse into a usable scope record, so NO path can be granted. ` +
+        `Inspect '${scopeHint}'; a truncated or half-written manifest is repaired by re-running the ` +
+        `coordinator's scope-manifest step, not by editing the plan — report \`blocked\` and leave the ` +
+        `manifest to the coordinator.`
+      );
+
+    case 'read-only-role': {
+      // Canonical casing from the list, so ' DISCOVERY ' and 'discovery' both
+      // render the documented sentence.
+      const canonical = READ_ONLY_ROLE_KEYS.get(rawRole.toLowerCase()) ?? rawRole;
+      return (
+        `${canonical} wave is read-only — no writes permitted. ` +
+        `An empty allowedPaths is this role's deliberate contract (#256), not a misconfiguration: ` +
+        `report '${relPath}' as a finding instead of editing it.`
+      );
+    }
+
+    case 'stale-manifest':
+      // NO COMMAND, and the manifest is never a removal TARGET here. Two reasons,
+      // both measured (module block, § "The channel belongs to the AGENT" and
+      // § "…and the reader may not be the owner"): the string is read by the agent
+      // whose Edit was just denied, and clearing the manifest disarms the whole
+      // gate — and the file may belong to a PARALLEL session in this working copy
+      // that is still using it. The diagnosis, which is what #1057 bought, stays.
+      return (
+        `'${scopeHint}' was written before the most recent session-start clock in this working copy — ` +
+        `either a leftover from a crashed session, or the live manifest of a PARALLEL session that is ` +
+        `still using it. This guard cannot tell which, and restarting the wave clears neither. ` +
+        `Treat the file as not yours (PSA-001): report \`blocked\` to your coordinator and name it. ` +
+        `Do NOT remove, move or edit it yourself (PSA-003/PSA-007).`
+      );
+
+    case 'writer-defect':
+      return (
+        `the wave's allowedPaths union is empty for role \`${rawRole}\` — ` +
+        `the coordinator's \`--union\` step did not complete. Re-run it; do not hand-edit.`
+      );
+
+    default:
+      return suggestForScopeViolation(relPath, '');
+  }
+}
+
+/**
+ * Milliseconds since one of this session's clocks was written, or `null` when
+ * none is readable — the MINIMUM over `.orchestrator/current-session.json`
+ * `timestamp` and `.orchestrator/session.lock` `started_at`.
+ *
+ * MOVED here from `hooks/post-bash-write-verify.mjs` (#1057) so both consumers
+ * share ONE implementation: a lib module may be imported by a hook, but a hook
+ * must never be imported by another hook or by this lib (module header, #554
+ * A2). Behaviour is byte-identical to the original — including the `Math.min`
+ * choice and the dropping of NEGATIVE (future-dated) ages, both of which that
+ * hook's docblock argues at length under "Why the minimum, and why NOT a
+ * staleness cap". That argument is the reason this repo has no TTL here either.
+ *
+ * Sync fs reads at CALL time only (same shape as {@link getEnforcementLevel});
+ * no I/O at import time. Never throws — an unreadable or malformed clock is
+ * simply absent.
+ *
+ * @param {string} repoRoot
+ * @param {number} [now]
+ * @returns {number|null}
+ */
+export function sessionAgeMs(repoRoot, now = Date.now()) {
+  const dir = path.join(repoRoot, '.orchestrator');
+  const ages = [
+    clockAgeMs(path.join(dir, 'current-session.json'), 'timestamp', now),
+    clockAgeMs(path.join(dir, 'session.lock'), 'started_at', now),
+  ].filter((age) => age !== null);
+  return ages.length > 0 ? Math.min(...ages) : null;
+}
+
+/**
+ * Age in ms of one JSON clock file's ISO timestamp field, or `null` when the
+ * file is missing, unparseable, carries no parseable timestamp, or is dated in
+ * the FUTURE. Private helper of {@link sessionAgeMs}; moved verbatim with it.
+ *
+ * @param {string} file
+ * @param {string} field
+ * @param {number} now
+ * @returns {number|null}
+ */
+function clockAgeMs(file, field, now) {
+  try {
+    const parsed = JSON.parse(readFileSync(file, 'utf8'));
+    const startedAt = Date.parse(parsed?.[field]);
+    if (!Number.isFinite(startedAt)) return null;
+    const age = now - startedAt;
+    return age >= 0 ? age : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Absolute epoch-ms at which this session started, or `null` when no clock is
+ * readable — the value {@link classifyEmptyScope} compares a manifest's mtime
+ * against.
+ *
+ * Derived from {@link sessionAgeMs} rather than re-reading the files, so there
+ * is ONE clock policy: `now - min(ages)` is the LATEST of the two recorded start
+ * times, which is exactly the freshness `Math.min` was chosen to express (a
+ * leftover `current-session.json` from a previous session is outvoted by a
+ * freshly-acquired `session.lock`). `now` is threaded through so both halves see
+ * the same instant.
+ *
+ * Never throws. No clock ⇒ `null` ⇒ the caller cannot decide staleness and must
+ * fall back to `'unknown'`.
+ *
+ * @param {string} repoRoot
+ * @param {number} [now]
+ * @returns {number|null}
+ */
+export function sessionStartedAtMs(repoRoot, now = Date.now()) {
+  const age = sessionAgeMs(repoRoot, now);
+  return age === null ? null : now - age;
+}