session-orchestrator 3.20.0 → 3.22.0

package/scripts/lib/named-vault-resolver.mjs

@@ -16,6 +16,29 @@
  * IO is fully injectable (existsSync, realpathSync, env, gitRemote) so every
  * branch is unit-testable without touching disk or git.
  *
+ * ── Remote resolution (#1039) ────────────────────────────────────────────────
+ *
+ * The default `gitRemote` reads the repo's remote through the shared core in
+ * `vcs-repo-spec.mjs` ({@link resolvePreferredRemote}), VCS-LESS. Two properties
+ * of that call are load-bearing here and must not be "tidied":
+ *
+ *   1. **`vcs` is deliberately omitted.** This module needs a URL, not a
+ *      platform family, and the vcs-less preference order is `origin` first.
+ *      That order is what keeps the derived slug STABLE: in a repo carrying both
+ *      `origin` (→ `<group>/<repo>`) and `gitlab`/`github` mirrors under other
+ *      namespaces, a `gitlab`-first order would re-namespace — i.e. silently
+ *      RENAME — every vault note already written under the origin namespace.
+ *   2. **Absence and query-failure are kept apart.** The former
+ *      `git remote get-url origin` implementation returned `''` for *both* "no
+ *      remote configured" and "git blew up / this is not a repo", and a falsy
+ *      URL skips the walk-up entirely. The vault then resolved to the
+ *      single-vault fallback with no trace of why — one `source:'fallback'`
+ *      label covering a benign repo state and a broken measurement. The
+ *      fallback result now carries an optional `remoteError` (a
+ *      `REMOTE_RESOLUTION_REASONS` value) so the two are separable BY VALUE, and
+ *      only a query failure ({@link isQueryFailure}) WARNs — an absence is
+ *      normal and stays silent.
+ *
  * ── Exports ──────────────────────────────────────────────────────────────────
  *
  *   parseNamedVaults(ownerConfig)
@@ -28,7 +51,7 @@
 
 import { join, dirname } from 'node:path';
 import { existsSync as nodeExistsSync, realpathSync as nodeRealpathSync } from 'node:fs';
-import { spawnSync } from 'node:child_process';
+import { resolvePreferredRemote, isQueryFailure } from './vcs-repo-spec.mjs';
 
 // ---------------------------------------------------------------------------
 // Internal helpers
@@ -289,12 +312,31 @@ export function findRepoRoot(cwd = process.cwd(), { existsSync = nodeExistsSync,
  * `gitRemote(repoRoot)` is called ONLY in the walk-up path — injecting a
  * stub that throws proves the explicit path never calls it.
  *
+ * `gitRemote` keeps its `(repoRoot) => string` contract verbatim; the optional
+ * second argument is an OUT-parameter the default implementation uses to report
+ * WHY it returned `''`. A one-arg stub ignores it and classifies as
+ * `'no-remotes'` on `''` / `'git-error'` on a throw — so every pre-existing
+ * injection still works unchanged.
+ *
+ * `gitRun` is injected into the DEFAULT `gitRemote` only, and is ignored when
+ * `gitRemote` is supplied (the caller has replaced the thing that would use it).
+ * It exists so the default remote-resolution path — preference order, reason
+ * propagation — is testable at all; a `gitRemote` stub answers that question
+ * before the code under test runs and can only ever confirm itself.
+ *
+ * `remoteError` is present ONLY on a `source:'fallback'` result that was reached
+ * because the remote query produced nothing; it is absent when the fallback was
+ * reached for any other reason (no vaults configured, no repo root, the repo IS
+ * a vault, no org-prefix match). Additive — pre-#1039 readers see the identical
+ * four fields.
+ *
  * @param {{
  *   vaultName?: string|null,
  *   cwd?: string,
  *   ownerConfig?: object,
  *   env?: Record<string, string|undefined>,
- *   gitRemote?: (repoRoot: string) => string,
+ *   gitRemote?: (repoRoot: string, out?: {reason?: string}) => string,
+ *   gitRun?: (args: string[]) => {ok: boolean, stdout: string, stderr: string, status?: number, code?: string},
  *   existsSync?: Function,
  *   realpathSync?: Function,
  * }} [opts]
@@ -302,7 +344,8 @@ export function findRepoRoot(cwd = process.cwd(), { existsSync = nodeExistsSync,
  *   root: string|null,
  *   suffix: string,
  *   name: string|null,
- *   source: 'explicit'|'walkup'|'fallback'
+ *   source: 'explicit'|'walkup'|'fallback',
+ *   remoteError?: string
  * }}
  */
 export function resolveNamedVault({
@@ -310,11 +353,14 @@ export function resolveNamedVault({
   cwd = process.cwd(),
   ownerConfig,
   env = process.env,
-  gitRemote = _defaultGitRemote,
+  gitRemote,
+  gitRun,
   existsSync = nodeExistsSync,
   realpathSync = nodeRealpathSync,
 } = {}) {
   const vaults = parseNamedVaults(ownerConfig);
+  const readRemote =
+    typeof gitRemote === 'function' ? gitRemote : (root, out) => _defaultGitRemote(root, out, gitRun);
 
   // ── Path 1: explicit vault-name ──────────────────────────────────────────
   const trimmedName = typeof vaultName === 'string' ? vaultName.trim() : '';
@@ -330,18 +376,39 @@ export function resolveNamedVault({
   }
 
   // ── Path 2: walk-up org-prefix match ────────────────────────────────────
+  /** @type {string|undefined} — set ONLY when the remote query is why we fall through */
+  let remoteError;
+
   if (vaults.length > 0) {
     const repoRoot = findRepoRoot(cwd, { existsSync, realpathSync });
     if (repoRoot !== null) {
-      // Get the git remote for origin
+      // Resolve the repo's preferred remote (vcs-less → origin-first; see the
+      // module docblock for why that order must not move).
+      /** @type {{reason?: string, stderr?: string}} */
+      const remoteOut = {};
       let remoteUrl;
       try {
-        remoteUrl = gitRemote(repoRoot);
-      } catch {
+        remoteUrl = readRemote(repoRoot, remoteOut);
+      } catch (err) {
+        // A throwing gitRemote could not answer the question — that is a query
+        // failure, never "this repo has no remote".
         remoteUrl = '';
+        remoteOut.reason = 'git-error';
+        remoteOut.stderr = err instanceof Error ? err.message : String(err);
       }
 
-      if (remoteUrl) {
+      if (!remoteUrl) {
+        // Falsy URL: keep the REASON instead of collapsing it into a bare
+        // `source:'fallback'`. A one-arg stub that reported nothing means the
+        // benign "no remote configured" case.
+        remoteError = remoteOut.reason ?? 'no-remotes';
+        if (isQueryFailure(remoteError)) {
+          const detail = remoteOut.stderr ? `: ${String(remoteOut.stderr).trim()}` : '';
+          process.stderr.write(
+            `WARN named-vault-resolver: could not read the git remote of "${repoRoot}" (${remoteError})${detail}; falling back to the single-vault default\n`,
+          );
+        }
+      } else {
         // Derive org/repo from the remote URL (strip suffix/.git/scheme)
         const repoSlug = _deriveSlugFromRemote(remoteUrl);
 
@@ -366,11 +433,14 @@ export function resolveNamedVault({
   }
 
   // ── Path 3: single-vault fallback ────────────────────────────────────────
+  // `remoteError` is spread in only when set, so a fallback reached for any
+  // other reason keeps the exact pre-#1039 four-field shape.
   return {
     root: null,
     suffix: _resolveEnvSuffix(env) ?? DEFAULT_SUFFIX,
     name: null,
     source: 'fallback',
+    ...(remoteError === undefined ? {} : { remoteError }),
   };
 }
 
@@ -420,14 +490,33 @@ function _deriveSlugFromRemote(url) {
 }
 
 /**
- * Default gitRemote implementation: runs `git -C <repoRoot> remote get-url origin`.
+ * Default gitRemote implementation (#1039).
+ *
+ * Delegates to the shared {@link resolvePreferredRemote} core VCS-LESS, which
+ * makes this resolver work in the repos the old hard-coded
+ * `git remote get-url origin` was blind in — a repo whose remotes are named
+ * `gitlab`/`github`, a fork whose sole remote is `upstream`. The vcs-less
+ * preference order still tries `origin` FIRST, so the slug derived for a repo
+ * that has an `origin` is byte-identical to the pre-#1039 value.
+ *
+ * Return type stays `string` (the `gitRemote` DI contract depends on it). The
+ * failure reason travels through the optional `out` OUT-parameter instead:
+ * folding it into the return value would have meant changing that contract for
+ * every injected stub.
+ *
  * @param {string} repoRoot
- * @returns {string}
+ * @param {{reason?: string, stderr?: string}} [out] — populated with the
+ *   {@link REMOTE_RESOLUTION_REASONS} reason when the resolution failed
+ * @param {Function} [gitRun] — injectable git runner; `undefined` uses the real one
+ * @returns {string} the remote URL, or `''` when none resolved
  */
-function _defaultGitRemote(repoRoot) {
-  const res = spawnSync('git', ['-C', repoRoot, 'remote', 'get-url', 'origin'], {
-    encoding: 'utf8',
-  });
-  if (res.status !== 0) return '';
-  return res.stdout.trim();
+function _defaultGitRemote(repoRoot, out, gitRun) {
+  // `vcs` deliberately omitted — see the module docblock (origin-first order).
+  const resolved = resolvePreferredRemote({ repoRoot, gitRun });
+  if (resolved.ok) return resolved.url;
+  if (isPlainObject(out)) {
+    out.reason = resolved.reason;
+    if (resolved.stderr) out.stderr = resolved.stderr;
+  }
+  return '';
 }

package/scripts/lib/owner-interview.mjs

@@ -13,10 +13,16 @@
  *     to AskUserQuestion in the coordinator. Each object has the shape:
  *       { question, header, options: [{ label, description }], multiSelect }
  *
+ *   optionValue(label)
+ *     Maps a displayed option label to the value stored in owner.yaml by
+ *     stripping the trailing `(Recommended)` marker. The label and the stored
+ *     value are deliberately NOT the same string — see the function comment.
+ *
  *   applyInterviewAnswers(answers, { path? } = {})
  *     Accepts an array of selected option labels (one per question, same order
- *     as getInterviewQuestions()), validates the result against validateOwnerConfig,
- *     and writes owner.yaml via writeOwnerConfig.
+ *     as getInterviewQuestions()), resolves each through optionValue(), validates
+ *     the result against validateOwnerConfig, and writes owner.yaml via
+ *     writeOwnerConfig.
  *     Returns { ok, path, errors }.
  *
  *   runOwnerInterview({ skipIfExists?, force?, path? } = {})
@@ -37,6 +43,40 @@ import {
   getDefaults,
 } from './owner-yaml.mjs';
 
+// ---------------------------------------------------------------------------
+// Label ←→ stored value
+// ---------------------------------------------------------------------------
+
+/**
+ * A trailing recommendation marker on an option LABEL — the display half of a
+ * label, never part of the stored value.
+ *
+ * Anchored at the end and non-greedy about whitespace so it can only ever strip
+ * a suffix; a value that merely CONTAINS the word (there is none today) survives.
+ */
+const RECOMMENDED_SUFFIX = /\s*\((?:Recommended|Empfohlen|Default)\)\s*$/u;
+
+/**
+ * Map an AUQ option label back to the value that is written to owner.yaml.
+ *
+ * The label and the stored value used to be the SAME string, which made the
+ * label unchangeable: `applyInterviewAnswers()` matches the answer against
+ * closed enums (`['direct','neutral','friendly']` and friends) and falls back to
+ * a default on any miss. Adding the `(Recommended)` marker AUQ-003 requires
+ * would therefore have turned a picked `direct` into a silently-stored
+ * `neutral` — a wrong answer written to disk with no error anywhere.
+ *
+ * Splitting the two keeps the label free for the operator and the value pinned
+ * to the enum. Everything before the marker is the value, verbatim.
+ *
+ * @param {unknown} label — the option label as selected by the operator
+ * @returns {string} the enum value to store, or '' for a non-string input
+ */
+export function optionValue(label) {
+  if (typeof label !== 'string') return '';
+  return label.replace(RECOMMENDED_SUFFIX, '').trim();
+}
+
 // ---------------------------------------------------------------------------
 // Question definitions
 // ---------------------------------------------------------------------------
@@ -50,51 +90,51 @@ import {
 export function getInterviewQuestions() {
   return [
     {
-      question: 'Which language should the assistant use for its responses?',
-      header: 'Owner Interview — Language (1/5)',
+      question: 'Which language should the assistant answer in?',
+      header: 'Language 1/5',
       options: [
-        { label: 'de', description: 'German — responses, narration, and questions in Deutsch.' },
-        { label: 'en', description: 'English — responses, narration, and questions in English.' },
-        { label: 'other', description: 'Other — write your ISO-639-1 code when prompted.' },
+        { label: 'de', description: 'German — answers, narration and questions all in Deutsch.' },
+        { label: 'en', description: 'English — answers, narration and questions all in English.' },
+        { label: 'other', description: 'Stored as English either way — only de and en are accepted. Change it later in owner.yaml (your settings file).' },
       ],
       multiSelect: false,
     },
     {
-      question: 'What communication tone style do you prefer?',
-      header: 'Owner Interview — Tone Style (2/5)',
+      question: 'How should the assistant talk to you?',
+      header: 'Tone 2/5',
       options: [
-        { label: 'direct', description: '(Recommended for pros) No filler phrases, straight to the point.' },
-        { label: 'neutral', description: 'Balanced: professional without being terse.' },
-        { label: 'friendly', description: 'Warm and conversational — good for exploratory sessions.' },
+        { label: 'direct (Recommended)', description: 'No filler, no praise, straight to the point — fastest to read once you know the project.' },
+        { label: 'neutral', description: 'Professional without being terse. Pick this if direct reads too blunt.' },
+        { label: 'friendly', description: 'Warm and conversational. Costs a few lines per answer, and suits open-ended exploration.' },
       ],
       multiSelect: false,
     },
     {
-      question: 'How much output should the assistant produce by default?',
-      header: 'Owner Interview — Output Level (3/5)',
+      question: 'How much should the assistant write by default?',
+      header: 'Output 3/5',
       options: [
-        { label: 'lite', description: 'Verbose mode — articles, explanations, and context kept. Good for learning.' },
-        { label: 'full', description: '(Default) Terse but complete. Narration trimmed, data preserved.' },
-        { label: 'ultra', description: 'Telegraphic — code and decisions only, no narration.' },
+        { label: 'full (Recommended)', description: 'Terse but complete: narration trimmed, every fact kept. Safe default — you lose words, never data.' },
+        { label: 'lite', description: 'Keeps the explanations and background too. Slower to read, better while the codebase is still new to you.' },
+        { label: 'ultra', description: 'Code and decisions only, no narration. You will have to ask why more often.' },
       ],
       multiSelect: false,
     },
     {
-      question: 'How should the assistant handle preamble before taking actions?',
-      header: 'Owner Interview — Preamble (4/5)',
+      question: 'How much should the assistant explain before it starts working?',
+      header: 'Preamble 4/5',
       options: [
-        { label: 'minimal', description: 'One-line status updates only. Jump straight to execution.' },
-        { label: 'verbose', description: 'Explain plan + rationale before each major action.' },
+        { label: 'minimal (Recommended)', description: 'One line of status, then it works. Safe default — you can still ask for the reasoning afterwards.' },
+        { label: 'verbose', description: 'Plan and reasoning before each major action. Costs a few lines every step.' },
       ],
       multiSelect: false,
     },
     {
-      question: 'Hardware-sharing consent: may the plugin share anonymized hardware patterns to improve resource defaults? (Issue #173 C4)',
-      header: 'Owner Interview — Hardware Sharing Consent (5/5)',
+      question: 'May the plugin share anonymized hardware data to improve its resource defaults?',
+      header: 'Sharing 5/5',
       options: [
-        { label: 'No', description: '(Default) No data is shared. Fully private.' },
-        { label: 'Yes', description: 'Share anonymized patterns (hashed, no PII). Helps tune wave/session defaults.' },
-        { label: 'Preview', description: 'Show exactly what would be shared before deciding.' },
+        { label: 'No (Recommended)', description: 'Nothing leaves this machine. Safe default — you can switch it on later without redoing this interview.' },
+        { label: 'Yes', description: 'Shares hashed hardware patterns — never file names, paths or content. Helps tune the wave and session defaults.' },
+        { label: 'Preview', description: 'Shows exactly what would be sent, then asks again. Costs one extra step.' },
       ],
       multiSelect: false,
     },
@@ -108,12 +148,15 @@ export function getInterviewQuestions() {
 /**
  * Map interview answer labels to an owner.yaml config object and write it.
  *
+ * Each answer is the LABEL the operator picked, which may carry a trailing
+ * `(Recommended)` marker; optionValue() strips it before the enum match below.
+ *
  * @param {string[]} answers - Array of selected option labels, one per question (5 total).
- *   answers[0] = language label ('de' | 'en' | free-text)
- *   answers[1] = tone style label
- *   answers[2] = output level label
- *   answers[3] = preamble label
- *   answers[4] = hardware-sharing label ('Yes' | 'No' | 'Preview')
+ *   answers[0] = language label ('de' | 'en' | 'other')
+ *   answers[1] = tone style label ('direct' | 'neutral' | 'friendly', ± marker)
+ *   answers[2] = output level label ('full' | 'lite' | 'ultra', ± marker)
+ *   answers[3] = preamble label ('minimal' | 'verbose', ± marker)
+ *   answers[4] = hardware-sharing label ('Yes' | 'No' | 'Preview', ± marker)
  * @param {{ path?: string }} [opts]
  * @returns {{ ok: boolean, path: string, errors: string[] }}
  */
@@ -124,7 +167,10 @@ export function applyInterviewAnswers(answers, opts = {}) {
     return { ok: false, path: filePath, errors: ['applyInterviewAnswers requires exactly 5 answers'] };
   }
 
-  const [langRaw, toneRaw, outputLevelRaw, preambleRaw, hwConsentRaw] = answers;
+  // Strip the display-only `(Recommended)` marker before matching against the
+  // enums below — see optionValue(). A non-string answer becomes '' and falls
+  // through to the same default it always did.
+  const [langRaw, toneRaw, outputLevelRaw, preambleRaw, hwConsentRaw] = answers.map(optionValue);
 
   // --- Language ---
   // Accept 'de', 'en', or treat anything else as a free-text language code.

package/scripts/lib/peer-cards/schema.mjs

@@ -6,8 +6,12 @@
  * YAML frontmatter on read and before write.
  *
  * Design notes:
- *   - Follows the `mission-status-schema.mjs` convention (pure regex/checks)
- *     rather than `skills/vault-sync/validator.mjs` (zod). The repo root has
+ *   - Pure regex/checks rather than `skills/vault-sync/validator.mjs` (zod).
+ *     (This line used to cite `scripts/lib/mission-status-schema.mjs` as the
+ *     exemplar for that convention; that module was deleted on 2026-08-15 for
+ *     having zero production callers while three prose sites promised it ran.
+ *     The convention below stands on its own reason, stated next.)
+ *     The repo root has
  *     no `zod` dependency — only `skills/vault-sync/` does, scoped to that
  *     skill's own `node_modules`. Keeping this validator dependency-free lets
  *     callers from anywhere under `scripts/lib/` use it without extra setup.

package/scripts/lib/peer-discovery.mjs

@@ -67,6 +67,7 @@ import { discoverActiveSessions } from './session-discovery.mjs';
 import { readLock, isLockLive, LOCK_PATH } from './session-lock.mjs';
 import { checkPeerStateMd } from './state-md-peer-guard.mjs';
 import { listWorktreesChecked } from './worktree/listing.mjs';
+import { parseSessionId } from './session-id.mjs';
 
 /** Closed enum of provenance sources. */
 const SOURCE_DISCOVERED = 'discovered'; // lock + registry unified (irreversibly merged upstream)
@@ -120,24 +121,64 @@ function _peerFromDiscovered(s, nowMs) {
   return peer;
 }
 
+/**
+ * Resolve a semantic hint to the concrete local raw ID for discovered surfaces.
+ *
+ * Semantic labels are attribution, not ownership. A mapping is usable only when
+ * current-session.json names the hint and its raw id exactly matches the local
+ * readable session.lock. Otherwise return null so a potentially foreign record
+ * stays visible. Raw caller ids retain the legacy direct comparison unchanged.
+ *
+ * This is a consistency check on two repo-global files, NOT a proof of ownership;
+ * a colliding semantic label from a foreign live session satisfies it. See the
+ * call site in findPeers for the measured case and why it is not closed here.
+ *
+ * @param {string|null} mySessionId
+ * @param {string} repoRoot
+ * @returns {string|null}
+ */
+function _discoveredSelfSessionId(mySessionId, repoRoot) {
+  if (typeof mySessionId !== 'string' || mySessionId.length === 0) return null;
+  if (parseSessionId(mySessionId)?.format !== 'semantic') return mySessionId;
+
+  try {
+    const raw = fs.readFileSync(
+      path.join(repoRoot, '.orchestrator', 'current-session.json'),
+      'utf8',
+    );
+    const current = JSON.parse(raw);
+    const lock = readLock({ repoRoot });
+    if (
+      current &&
+      typeof current === 'object' &&
+      !Array.isArray(current) &&
+      typeof current.session_id === 'string' &&
+      current.session_id.length > 0 &&
+      current.semantic_session_id === mySessionId &&
+      lock !== null &&
+      typeof lock.session_id === 'string' &&
+      lock.session_id === current.session_id
+    ) {
+      return lock.session_id;
+    }
+  } catch {
+    // Missing or malformed local state cannot prove a semantic alias.
+  }
+  return null;
+}
+
 /**
  * findPeers — union of all 3 peer-discovery surfaces, fail-open per surface.
  *
  * @param {string} repoRoot  Absolute path to the repository root.
  * @param {object} [opts] passthrough seams shared with the underlying surfaces.
- * @param {string|null} [opts.mySessionId]      Current session id, used for
- *   self-exclusion on BOTH surfaces — but the two surfaces read different
- *   id-spaces. Surface A+B (discoverActiveSessions) compares against
- *   `session_id` from session.lock / the host registry, which is ALWAYS the
- *   UUID (never `semantic_session_id` — see session-lock.mjs). Surface C
- *   (checkPeerStateMd) compares against STATE.md's `session:` frontmatter
- *   field, which callers may populate with either id-space as long as it is
- *   the SAME id-space `mySessionId` was derived from (see the PRECONDITION
- *   note in state-md-peer-guard.mjs). Passing a semantic id here self-excludes
- *   correctly on Surface C but NOT on Surface A+B (the UUID lock/registry
- *   entry for the same session will still surface as a 'discovered' peer of
- *   itself) — callers that need both surfaces to self-exclude MUST pass the
- *   UUID.
+ * @param {string|null} [opts.mySessionId]      Current session id hint. Raw
+ *   ids self-exclude directly on Surface A+B. A semantic hint maps to a raw
+ *   discovered-surface id only after the local current-session.json semantic
+ *   label matches it AND that file's raw id exactly equals local
+ *   session.lock.session_id. Missing, malformed, or mismatched local state
+ *   maps nothing, leaving discovered entries visible. Surface C receives this
+ *   original hint unchanged and compares it to STATE.md's `session:` field.
  * @param {number}      [opts.now]              ms-since-epoch (test seam for freshness/age).
  * @param {number}      [opts.freshnessMin]     Registry-entry freshness threshold (minutes).
  * @param {number}      [opts.maxAgeHours]      STATE.md abandonment threshold (hours).
@@ -155,6 +196,7 @@ function _peerFromDiscovered(s, nowMs) {
 export async function findPeers(repoRoot, opts = {}) {
   const nowMs = typeof opts.now === 'number' ? opts.now : Date.now();
   const mySessionId = opts.mySessionId ?? null;
+  const discoveredSelfSessionId = _discoveredSelfSessionId(mySessionId, repoRoot);
 
   const peers = [];
 
@@ -172,15 +214,24 @@ export async function findPeers(repoRoot, opts = {}) {
     });
     if (Array.isArray(discovered)) {
       for (const s of discovered) {
-        // Self-exclusion (#798): discoverActiveSessions has no notion of "my
-        // session" — it returns every live lock/registry entry, including the
-        // caller's own SessionStart-hook heartbeat. Exclude it here so it
-        // never surfaces as a source:'discovered' peer of itself. Mirrors the
-        // same guard in session-registry.mjs detectPeers() and
-        // hooks/on-session-start.mjs. `mySessionId === null` needs no special
-        // case: `!==` against a string sessionId is always true when
-        // mySessionId is null, so a foreign entry is never filtered.
-        if (s && typeof s.sessionId === 'string' && s.sessionId !== mySessionId) {
+        // Self-exclusion (#798, #1085): discovered entries carry raw ids. A
+        // semantic caller hint filters one such id only after the local raw
+        // binding was verified above.
+        //
+        // The binding proves CONSISTENCY of the two local files, not OWNERSHIP.
+        // Both are repo-global, so if a foreign live session wrote them last and
+        // its semantic label collides with this hint (labels like
+        // `main-2026-08-21-session-2` are routinely shared — see
+        // hooks/on-session-start.mjs), that foreign raw id is filtered and the
+        // peer PSA-002 exists to surface goes missing. Measured 2026-08-21:
+        // null hint -> peer visible, colliding semantic hint -> peers: [].
+        // Closing it needs a per-process ownership proof, not a stronger read
+        // of the same two files.
+        if (
+          s &&
+          typeof s.sessionId === 'string' &&
+          s.sessionId !== discoveredSelfSessionId
+        ) {
           peers.push(_peerFromDiscovered(s, nowMs));
         }
       }

package/scripts/lib/project-hygiene.mjs

@@ -212,6 +212,21 @@ function duBytes(absPath) {
   }
 }
 
+/**
+ * Human-readable byte size. Sub-megabyte totals are the common case once the
+ * aged subset is sized correctly, and `Math.round(bytes / MB)` renders every
+ * one of them as "0 MB" — which is why the unit is chosen, not fixed.
+ * @param {number} bytes
+ * @returns {string}
+ */
+function formatBytes(bytes) {
+  const mb = bytes / (1024 * 1024);
+  if (mb >= 10) return `${Math.round(mb)} MB`;
+  if (mb >= 1) return `${mb.toFixed(2)} MB`;
+  if (bytes >= 1024) return `${Math.round(bytes / 1024)} KB`;
+  return `${bytes} B`;
+}
+
 /**
  * H3 — Aged orchestrator artifacts.
  *
@@ -219,17 +234,48 @@ function duBytes(absPath) {
  * 147 MB were Playwright test-run captures dating back seven weeks, plus
  * 592 files older than 30 days.
  *
+ * Counts and sizes ONLY untracked aged files. Two properties are load-bearing
+ * and were both defects until 2026-08-22:
+ *
+ *   1. The byte total describes the set the sentence names — the aged files —
+ *      not the whole directory. Sizing the directory overstated the reachable
+ *      win by a factor of ~18 in this repo (11 MB claimed, 0.68 MB real).
+ *   2. Version-tracked paths are excluded. `.orchestrator/policy/*.json` and
+ *      `.orchestrator/steering/*.md` are read at runtime by hooks and skills;
+ *      their age is a sign of stability, not decay. Proposing them for
+ *      "pruning" is proposing to delete source.
+ *
  * @param {string} repoRoot
  * @param {number} ageDays
  * @param {number} now
- * @returns {object|null}
+ * @returns {{check: string, fixable: boolean, agedFiles: number, agedBytes: number, message: string}|null}
  */
 export function checkStaleArtifacts(repoRoot, ageDays = DEFAULT_ARTIFACT_AGE_DAYS, now = Date.now()) {
   const dir = join(repoRoot, '.orchestrator');
   if (!existsSync(dir)) return null;
 
+  // Resolve the tracked set ONCE per call — `git ls-files --error-unmatch` per
+  // file would cost one process per candidate for the same answer.
+  //
+  // FAIL-SAFE, NOT FAIL-OPEN: when git cannot answer (no repo, git absent,
+  // non-zero exit) source and artifact are indistinguishable, so the probe
+  // stays SILENT rather than falling back to "nothing is tracked" — that
+  // fallback IS the defect this exclusion closes, and it would return
+  // invisibly. Losing an advisory finding costs nothing; proposing to delete
+  // versioned files costs a restore. `-z` suppresses git's path quoting, so
+  // non-ASCII and space-bearing paths compare byte-exactly.
+  const trackedRaw = git(['ls-files', '-z', '--', '.orchestrator'], repoRoot);
+  if (trackedRaw === null) return null;
+  const tracked = new Set(
+    trackedRaw
+      .split('\0')
+      .filter(Boolean)
+      .map((p) => join(repoRoot, p)),
+  );
+
   const cutoff = now - ageDays * 24 * 60 * 60 * 1000;
   let aged = 0;
+  let agedBytes = 0;
   let scanned = 0;
 
   /** @param {string} d @param {number} depth */
@@ -248,9 +294,16 @@ export function checkStaleArtifacts(repoRoot, ageDays = DEFAULT_ARTIFACT_AGE_DAY
       if (e.isDirectory()) {
         walk(full, depth + 1);
       } else if (e.isFile()) {
+        // Counted before the tracked-skip so the 20k bound still measures the
+        // walk, not the reportable subset.
         scanned++;
+        if (tracked.has(full)) continue;
         try {
-          if (statSync(full).mtimeMs < cutoff) aged++;
+          const st = statSync(full);
+          if (st.mtimeMs < cutoff) {
+            aged++;
+            agedBytes += st.size;
+          }
         } catch {
           /* vanished mid-scan — ignore */
         }
@@ -261,11 +314,18 @@ export function checkStaleArtifacts(repoRoot, ageDays = DEFAULT_ARTIFACT_AGE_DAY
 
   if (aged === 0) return null;
 
-  const mb = Math.round((duBytes(dir) ?? 0) / (1024 * 1024));
+  // `fixable: true` stays. The only consumer is skills/session-start/SKILL.md
+  // (Phase 4), which routes fixable findings to "safe batch work" instead of
+  // the operator Q&A — prose guidance to the coordinator, not an automatic
+  // deletion run; `grep -rn "fixable" scripts/ skills/ hooks/` finds no other
+  // reader than the `mechanical` count below. With tracked paths excluded the
+  // claim is now true: every reported path is an untracked artifact.
   return {
     check: 'stale-artifacts',
     fixable: true,
-    message: `${aged} file(s) under .orchestrator/ older than ${ageDays}d${mb > 0 ? ` (${mb} MB total)` : ''} — candidates for pruning`,
+    agedFiles: aged,
+    agedBytes,
+    message: `${aged} untracked file(s) under .orchestrator/ older than ${ageDays}d${agedBytes > 0 ? ` (${formatBytes(agedBytes)} total)` : ''} — candidates for pruning`,
   };
 }