session-orchestrator 4.2.0 → 5.0.0

package/scripts/lib/auq/schema.mjs

@@ -186,8 +186,9 @@ export const CRITERIA = Object.freeze({
     appliesTo: 'block',
     hurdle: 'H1',
     measures:
-      'Zeichen der Kopfzeile. Über 12 schneidet das Tool selbst ab — das ist keine ' +
-      'Stilfrage, sondern eine harte Grenze.',
+      'Zeichen der Kopfzeile. 12 ist das von der Tool-Beschreibung genannte Budget ' +
+      '(`max 12 chars`) — in VORLAGEN eine harte Grenze, weil Kürzen dort nichts ' +
+      'kostet; zur Laufzeit nur beratend (siehe `evidence` an HURDLES.H1).',
   }),
   K6: Object.freeze({
     id: 'K6',
@@ -251,7 +252,13 @@ export const HURDLES = Object.freeze({
     criterion: 'K5',
     evidence:
       'Gemessen 2026-08-22: 26 von 42 Kopfzeilen-Literalen reißen diese Grenze (62 %), ' +
-      'Spitzenwert 54 Zeichen. Das Tool schneidet ab — der Operator sieht den Rest nie.',
+      'Spitzenwert 54 Zeichen. Die 12 ist die Stilangabe der Tool-Beschreibung ' +
+      '(`max 12 chars`), KEINE erzwungene Grenze: im Bundle 2.1.268 steht die Zahl nur ' +
+      'in ebendieser Beschreibung, es gibt kein `.max(12)` im Zod-Schema und keinen ' +
+      'Render-Pfad, der sie liest — 125 längere Kopfzeilen wurden vom Tool angenommen ' +
+      'und beantwortet (gemessen 2026-09-11). Deshalb gilt H1 nur für VORLAGEN, wo ein ' +
+      'Autor kostenlos kürzen kann; zur Laufzeit meldet der Hook sie und blockt nicht ' +
+      '(siehe BLOCKING_HURDLES in hooks/pre-auq-clarity.mjs).',
   }),
   H2: Object.freeze({
     id: 'H2',

package/scripts/lib/ci-status-banner.mjs

@@ -531,7 +531,9 @@ async function checkGitlab(repoRoot, now, deps = {}) {
     return null;
   }
 
-  const currentSha = await getHeadSha(repoRoot, deps);
+  // #1332: an explicit `deps.sha` (validated full hex SHA, see checkCiStatus)
+  // replaces the local HEAD lookup — the caller asks about a NAMED commit.
+  const currentSha = deps.sha ?? (await getHeadSha(repoRoot, deps));
   const apiDeps = { ...deps, repoHost: project.host };
   const projectPath = `projects/${project.encodedProjectPath}`;
   // `'array'` is load-bearing, not decoration: before it, a `glab api` that
@@ -700,8 +702,11 @@ async function checkGitlab(repoRoot, now, deps = {}) {
  * (cross-family guard, unsafe-argv guard), and `normalizeGithubSpec` falls
  * back to the raw URL on an unrecognised remote shape.
  *
+ * `deps.sha` (#1332): when set, the check-runs query names THAT commit
+ * instead of the literal `HEAD` ref.
+ *
  * @param {string} repoRoot
- * @param {{ execFile?: Function, timeoutMs?: number, repoSpec?: string, repoHost?: string }} deps
+ * @param {{ execFile?: Function, timeoutMs?: number, repoSpec?: string, repoHost?: string, sha?: string }} deps
  * @returns {Promise<object|null>}
  */
 async function checkGithub(repoRoot, deps = {}) {
@@ -726,7 +731,7 @@ async function checkGithub(repoRoot, deps = {}) {
   );
 
   const data = await ghApi(
-    `repos/${nameWithOwner}/commits/HEAD/check-runs`,
+    `repos/${nameWithOwner}/commits/${deps.sha ?? 'HEAD'}/check-runs`,
     repoRoot,
     deps,
     'object',
@@ -807,7 +812,12 @@ async function checkGithub(repoRoot, deps = {}) {
  *   vcs?: 'gitlab'|'github',
  *   timeoutMs?: number,
  *   now?: number,
- * }} opts
+ *   sha?: string,
+ * }} opts  `sha` (#1332): query the verdict for THIS commit instead of the
+ *   local HEAD. Must be a full hex object id (40 or 64 chars) — it is matched
+ *   against GitLab's full pipeline SHAs and interpolated into a `gh api` path,
+ *   so anything else is refused as `query-failed` before any spawn. Absent →
+ *   behaviour identical to before the option existed.
  * @param {{
  *   execFile?: Function,
  *   resolveRepoSpec?: (opts: { repoRoot: string, vcs: 'gitlab'|'github' }) => string|undefined,
@@ -842,8 +852,21 @@ export async function checkCiStatus(opts = {}, deps = {}) {
     vcs: forcedVcs,
     timeoutMs = DEFAULT_TIMEOUT_MS,
     now = Date.now(),
+    sha: rawSha,
   } = opts;
 
+  // Validate at the boundary (#1332): the value reaches an API path and an
+  // equality match against full SHAs. A short or non-hex SHA would silently
+  // match nothing (GitLab) or re-route the request path (GitHub).
+  let sha;
+  if (rawSha !== undefined) {
+    const candidate = typeof rawSha === 'string' ? rawSha.trim().toLowerCase() : '';
+    if (!/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(candidate)) {
+      return degradedResult('query-failed', 'sha must be a full hex commit id');
+    }
+    sha = candidate;
+  }
+
   const execFileDep = deps.execFile
     ? promisify(deps.execFile)
     : execFileAsync;
@@ -914,13 +937,13 @@ export async function checkCiStatus(opts = {}, deps = {}) {
           'a GitLab remote was detected but its host/project path could not be derived',
         );
       }
-      return await checkGitlab(repoRoot, now, { ...depsWithExec, gitlabProject });
+      return await checkGitlab(repoRoot, now, { ...depsWithExec, gitlabProject, sha });
     }
 
     if (vcs === 'github') {
       const repoSpec = resolveRepoSpecDep({ repoRoot, vcs });
       const repoHost = resolveRepoHostDep({ repoRoot, vcs });
-      return await checkGithub(repoRoot, { ...depsWithExec, repoSpec, repoHost });
+      return await checkGithub(repoRoot, { ...depsWithExec, repoSpec, repoHost, sha });
     }
 
     // Unknown VCS value — silent no-op.

package/scripts/lib/claude-md-budget-lint.mjs

@@ -63,7 +63,8 @@
 
 import { readFileSync, existsSync, statSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
-import { basename, resolve } from 'node:path';
+import { basename, resolve, sep } from 'node:path';
+import { homedir } from 'node:os';
 import { resolveInstructionFile } from './common.mjs';
 import { isSessionConfigHeading } from './config/section-extractor.mjs';
 
@@ -317,6 +318,36 @@ export function lintClaudeMd(opts = {}) {
  * @param {number} [opts.maxLineChars] forwarded to lintClaudeMd (default DEFAULT_MAX_LINE_CHARS).
  * @returns {{ severity: 'warn', message: string } | null}
  */
+/**
+ * Replace a leading home-directory prefix with the literal `$HOME`.
+ *
+ * Why `$HOME` and not `~`: the banner emits the path inside DOUBLE QUOTES, and
+ * no POSIX shell expands a tilde inside double quotes — `node "~/x.mjs"` fails,
+ * `node "$HOME/x.mjs"` works. Why not `path.relative(repoRoot, __filename)`
+ * (the first proposal): measured 2026-09-11, it only redacts when the repo and
+ * the plugin share a home ancestor —
+ *   repoRoot `~/Projects/bewerbungs-assistent`, plugin under `~/.claude/plugins`
+ *     → `../../.claude/plugins/…` (private, 98 chars)
+ *   repoRoot on a tmp/other volume, plugin under the home dir
+ *     → `../../../../Users/<name>/.claude/…` (LEAKS, and longer)
+ * and it is cwd-bound, which contradicts the `--repo-root` echo whose whole
+ * purpose is cwd-independence. `$HOME` collapse is unconditional, cwd-free, and
+ * leaks nothing in either case.
+ *
+ * A path OUTSIDE the home directory is returned unchanged — it carries no
+ * username to redact, and rewriting it would break the command.
+ *
+ * @param {string} p absolute path
+ * @returns {string} `p` with a leading `homedir()` replaced by `$HOME`
+ */
+function homeCollapsed(p) {
+  const home = homedir();
+  if (typeof p !== 'string' || home.length === 0) return p;
+  if (p === home) return '$HOME';
+  if (p.startsWith(home + sep)) return '$HOME' + p.slice(home.length);
+  return p;
+}
+
 export function checkClaudeMdBudgetLint(opts = {}) {
   const repoRoot = opts.repoRoot ?? process.cwd();
 
@@ -343,9 +374,28 @@ export function checkClaudeMdBudgetLint(opts = {}) {
   if (!result || result.violations.length === 0) return null;
 
   const ruleNames = [...new Set(result.violations.map((v) => v.rule))].join(', ');
+  // The hint MUST name a path the operator can actually run — `scripts/lib/…`
+  // repo-root-relative is only valid inside THIS repo's own checkout. A
+  // consumer repo has no such file: it either has no `scripts/lib/` at all,
+  // or a foreign one. `__filename` (module-scope, see the CLI section below)
+  // is the absolute path of the module that is EXECUTING RIGHT NOW — it is
+  // never wrong, because we could not be inside this function otherwise, and
+  // it needs no plugin-root lookup at all (no env var, no marketplace-cache
+  // scan, no "not resolvable" case to handle — see plugin-update-banner.mjs's
+  // module docstring for why guessing a plugin root from an env var is the
+  // WRONG move here: `$CLAUDE_PLUGIN_ROOT` can name a checkout that differs
+  // from the code that is actually loaded and running). `repoRoot` is echoed
+  // back too, so the copied command re-lints the exact file this banner
+  // reports on regardless of the operator's cwd when they paste it.
+  // PRIVACY (2026-09-11): the same message line already redacts `filePath` via
+  // `basename()`, while `__filename` and `repoRoot` went out verbatim — both
+  // CP1-shaped (`/Users/<name>/…`) on a personal host. The banner's route into
+  // public view is copy-paste into an issue or an agent report, the documented
+  // "agent reports carry private slugs" class. `homeCollapsed()` keeps the
+  // command EXECUTABLE (so #1302 stays closed) while dropping the username.
   const message =
     `⚠ CLAUDE.md budget lint: ${result.violations.length} violation(s) (${ruleNames}) in ${basename(filePath)} — ` +
-    `run \`node scripts/lib/claude-md-budget-lint.mjs --mode warn\` for details.`;
+    `run \`node "${homeCollapsed(__filename)}" --repo-root "${homeCollapsed(repoRoot)}" --mode warn\` for details.`;
 
   return { severity: 'warn', message };
 }

package/scripts/lib/config.mjs

@@ -208,7 +208,18 @@ export function parseSessionConfig(mdContent, { hostPaths } = {}) {
     _getVal(kv, 'ecosystem-health', undefined) !== undefined
       ? _coerceBoolean(kv, 'ecosystem-health', false)
       : (_parseEcosystemHealthBlockEnabled(mdContent) ?? false);
-  const discoveryOnClose = _coerceBoolean(kv, 'discovery-on-close', false);
+  // discovery-on-close alone accepts `auto` (= true) and defaults to true when
+  // absent: the template recommends `auto` and the 2026-07-29 doc decision made
+  // close-time discovery the default. Other booleans stay strict (#1340).
+  // Ceiling (BV-004): a one-key tri-state kept inline; revisit (move into
+  // coercers.mjs as a shared auto-boolean coercer) when a second key accepts `auto`.
+  const discoveryOnCloseRaw = (_getVal(kv, 'discovery-on-close', 'auto')).toLowerCase();
+  if (!['true', 'false', 'auto'].includes(discoveryOnCloseRaw)) {
+    throw new Error(
+      `config.mjs: invalid boolean for 'discovery-on-close': '${_getVal(kv, 'discovery-on-close', '')}' (expected true, false or auto)`,
+    );
+  }
+  const discoveryOnClose = discoveryOnCloseRaw !== 'false';
   const reasoningOutput = _coerceBoolean(kv, 'reasoning-output', false);
   const groundingCheck = _coerceBoolean(kv, 'grounding-check', true);
   const allowDestructiveOps = _coerceBoolean(kv, 'allow-destructive-ops', false);

package/scripts/lib/eval/engine.mjs

@@ -37,6 +37,7 @@ import path from 'node:path';
 import { resolvePluginRoot } from '../common.mjs';
 import { readJsonlFile } from '../io.mjs';
 import { readCanonicalSessions } from '../sessions-canonical.mjs';
+import { isCoordinatorDirectHousekeeping } from '../session-schema/filters.mjs';
 import { buildRunId, CURRENT_STANDARD_VERSION, VALID_MODEL_SOURCES } from './schema.mjs';
 import { resolveSession, computeWindow, findPeerOverlap } from './session-resolve.mjs';
 
@@ -250,7 +251,12 @@ function scoreGateHealth(ctx) {
     const totalWaves = typeof ctx.record.total_waves === 'number' ? ctx.record.total_waves : null;
     const wavesEmpty =
       totalWaves === 0 || !Array.isArray(ctx.record.waves) || ctx.record.waves.length === 0;
-    if (wavesEmpty) {
+    // Since the metrics-collection writer rule (#1321), a session with no
+    // dispatched waves is recorded as ONE coordinator-direct Housekeeping wave
+    // with total_waves 1 — still "no waves ran" per rubric-v1's clarification.
+    // Only that wave SHAPE counts, never session_type: a housekeeping session
+    // that ran real waves stays cannot-determine (the pre-registered formula).
+    if (wavesEmpty || isCoordinatorDirectHousekeeping(ctx.record)) {
       return {
         id,
         method,

package/scripts/lib/file-lock.mjs

@@ -30,6 +30,18 @@
  *   - Overrides always go through writeJsonAtomicSync (tmp + renameSync).
  *   - #1284 serializes acquisition and takeover: a stale observation must not
  *     replace a different process's newly acquired lock.
+ *   - #1285 serializes owner-guarded release with takeover: release runs its
+ *     read → owner-match → unlink under the same `${lock}.acquire` guard, so an
+ *     old holder's delayed release can never delete the lock a successor took
+ *     over after the old lease expired.
+ *
+ * Lease semantics (`staleCheck: 'mtime' | 'heartbeat'`): lease expiry prevents
+ * a STUCK lock; it does NOT protect the critical section. After `staleMs` the
+ * next acquirer takes over whether or not the old holder is still running, and
+ * neither mode renews the lease (`heartbeat` ages from `acquiredAt`, `mtime`
+ * from the file's last write). A `not-owner` release under a lease mode means
+ * YOUR lease expired during your critical section and a successor may have run
+ * concurrently — keep critical sections well below `staleMs`.
  *
  * No external dependencies — Node 20+ stdlib + io.mjs only.
  */
@@ -249,6 +261,25 @@ function serializeBody(body, indent) {
   return JSON.stringify(body, null, indent) + '\n';
 }
 
+/**
+ * Create the exclusive `${lockPath}.acquire` sibling guard that serializes every
+ * acquisition, takeover and owner-guarded release pass on `lockPath` (#1284,
+ * #1285). The caller owns the guard only when `ok` is true and must unlink it
+ * in a `finally`; an existing guard is NEVER replaced (see tryAcquireFileLock).
+ *
+ * @param {string} lockPath
+ * @param {string} tmpPrefix — tmp-file prefix; `.acquire` is appended.
+ * @returns {{ ok: true } | { ok: false, reason: 'exists' } | { ok: false, reason: 'fs-error', error: string }}
+ */
+function createAcquireGuard(lockPath, tmpPrefix) {
+  return createExclusive(`${lockPath}.acquire`, {
+    pid: process.pid,
+    host: os.hostname(),
+    acquiredAt: new Date().toISOString(),
+    kind: 'acquisition-guard',
+  }, { indent: 2, tmpPrefix: `${tmpPrefix}.acquire` });
+}
+
 // ---------------------------------------------------------------------------
 // Exported primitive
 // ---------------------------------------------------------------------------
@@ -264,13 +295,18 @@ function serializeBody(body, indent) {
  * Every acquisition pass owns the exclusive sibling `${lockPath}.acquire`
  * from before create/read through any takeover. This prevents a waiter from
  * reading an old holder, observing its exit, then replacing a newer holder.
+ * Owner-guarded releases (releaseFileLock) take the SAME guard for their
+ * read → owner-match → unlink pass (#1285), so a release can never unlink a
+ * lock that a takeover replaced after the releaser read its own body.
  * All contenders must use this guarded implementation; legacy writers that
  * ignore the sibling guard cannot participate safely in the same protocol.
  *
- * Crash-liveness tradeoff: the guard is held only for this synchronous pass,
- * not for the caller's critical section. If its owner dies during the pass or
- * cleanup fails, the guard remains and attempts return `held` immediately;
- * withFileLock's normal deadline bounds polling. Even a dead-PID or malformed
+ * Crash-liveness tradeoff: the guard is held only for one synchronous pass
+ * (acquire or release), not for the caller's critical section. If its owner
+ * dies during a pass or cleanup fails, the guard remains: acquire attempts
+ * return `held` immediately (withFileLock's normal deadline bounds polling) and
+ * owner-guarded releases return `busy` after their bounded retry, leaving the
+ * primary lock to its stale policy. Even a dead-PID or malformed
  * guard is NEVER stolen, because stale-guard replacement would repeat the same
  * race. Recovery requires quiescing every process that can acquire this lock,
  * verifying the guard is abandoned, then explicitly removing only that sibling.
@@ -303,12 +339,7 @@ function serializeBody(body, indent) {
  */
 export function tryAcquireFileLock(lockPath, opts = {}) {
   const guardPath = `${lockPath}.acquire`;
-  const guard = createExclusive(guardPath, {
-    pid: process.pid,
-    host: os.hostname(),
-    acquiredAt: new Date().toISOString(),
-    kind: 'acquisition-guard',
-  }, { indent: 2, tmpPrefix: `${opts.tmpPrefix ?? '.file.lock'}.acquire` });
+  const guard = createAcquireGuard(lockPath, opts.tmpPrefix ?? '.file.lock');
   if (!guard.ok) {
     return guard.reason === 'exists'
       ? { acquired: false, reason: 'held', existing: null }
@@ -418,21 +449,35 @@ function tryAcquireGuardedFileLock(lockPath, opts) {
  * match. This reproduces the agent-status / state-lock / staging-fence owner
  * guard (PSA-003: never delete a lock another holder owns).
  *
+ * Guaranteed (#1285): the owner-guarded read → owner-match → unlink runs under
+ * the same `${lockPath}.acquire` guard as acquisition and takeover, so an old
+ * holder's release can never delete a replacement's lock. Without the guard, a
+ * holder that read its own body, then paused while its lease expired and a
+ * successor took over, unlinked the successor's lock and let a third process
+ * acquire beside a live holder. Under `staleCheck: 'mtime' | 'heartbeat'`, a
+ * `not-owner` answer means your lease expired during your critical section —
+ * see the module header § Lease semantics. The guard is never stolen: when it
+ * stays taken past the budget the release returns `busy` and leaves the lock
+ * untouched for its stale policy to reclaim.
+ *
  * With `ownerGuard: false` the file is unlinked unconditionally, ENOENT
  * ignored — reproducing memory-proposals/store.mjs's `releaseProposalsLock`.
+ * That path takes no guard (its callers never run a takeover).
  *
  * @param {string} lockPath
  * @param {object} [opts]
  * @param {string} [opts.holder]            — expected holder for the owner guard.
  * @param {boolean} [opts.ownerGuard=true]
+ * @param {number} [opts.guardTimeoutMs=1000] — owner-guarded path only: how long
+ *        to retry for the `.acquire` guard before answering `busy`.
  * @param {(errToken: string) => void} [opts.warn] — sink for unexpected fs
  *        errors on the ownerGuard:false path. Receives the raw
  *        `err.code ?? err.message` token; the call-site formats the message.
  * @returns {{ ok: true }
- *   | { ok: false, reason: 'not-found'|'not-owner'|'fs-error', error?: string }}
+ *   | { ok: false, reason: 'not-found'|'not-owner'|'busy'|'fs-error', error?: string }}
  */
 export function releaseFileLock(lockPath, opts = {}) {
-  const { holder, ownerGuard = true, warn } = opts;
+  const { holder, ownerGuard = true, warn, guardTimeoutMs } = opts;
 
   if (ownerGuard === false) {
     // Unconditional unlink; ENOENT ignored. Other fs errors surfaced via warn.
@@ -448,6 +493,53 @@ export function releaseFileLock(lockPath, opts = {}) {
     }
   }
 
+  // Nothing to release → answer without the guard. Taking it would create the
+  // lock's directory (createExclusive mkdirs) and contend with live acquirers
+  // for a pass that can never unlink anything. Only ENOENT short-cuts; every
+  // other stat error falls through to the guarded read, which reports it.
+  try {
+    fs.statSync(lockPath);
+  } catch (err) {
+    if (err.code === 'ENOENT') return { ok: false, reason: 'not-found' };
+  }
+
+  const budget = typeof guardTimeoutMs === 'number' && guardTimeoutMs >= 0
+    ? guardTimeoutMs
+    : DEFAULT_RELEASE_GUARD_MS;
+  const deadline = Date.now() + budget;
+  for (;;) {
+    const guard = createAcquireGuard(lockPath, '.file.lock');
+    if (guard.ok) break;
+    if (guard.reason === 'fs-error') return { ok: false, reason: 'fs-error', error: guard.error };
+    // Never steal the guard (same rule as acquisition): wait, then give up.
+    if (Date.now() >= deadline) return { ok: false, reason: 'busy' };
+    sleepSync(RELEASE_GUARD_POLL_MS);
+  }
+
+  try {
+    return releaseGuardedFileLock(lockPath, holder);
+  } finally {
+    // Only this pass owns the guard; an unlink failure fails closed exactly
+    // like the acquisition path (see tryAcquireFileLock § recovery).
+    try { fs.unlinkSync(`${lockPath}.acquire`); } catch { /* fail closed */ }
+  }
+}
+
+/**
+ * Budget for an owner-guarded release to obtain the `.acquire` guard.
+ *
+ * CEILING (BV-004): a live contender holds the guard for one synchronous pass
+ * (a handful of fs syscalls), so the wait is normally sub-millisecond; the full
+ * 1000 ms is only spent on an ABANDONED guard (owner crashed mid-pass), where
+ * waiting longer cannot help. REVISIT if a `busy` release is ever observed on a
+ * host without a crash.
+ */
+const DEFAULT_RELEASE_GUARD_MS = 1000;
+/** Poll cadence while a release waits for the `.acquire` guard. */
+const RELEASE_GUARD_POLL_MS = 5;
+
+/** Caller must hold the acquisition guard throughout this synchronous pass. */
+function releaseGuardedFileLock(lockPath, holder) {
   let raw;
   try {
     raw = fs.readFileSync(lockPath, 'utf8');
@@ -523,6 +615,11 @@ function delay(ms) {
  * @param {boolean} [opts.sync=false]  — true → synchronous busy-wait poll +
  *        synchronous fn (agent-status variant). false → async poll.
  * @param {boolean} [opts.ownerGuard=true]  — passed to releaseFileLock.
+ * @param {(release: ReturnType<typeof releaseFileLock>) => void} [opts.onRelease]
+ *        — receives the releaseFileLock result from the finally (#1336). The
+ *        only reader of `busy` / `not-owner` (a lease that expired mid-`fn`);
+ *        the return value of withFileLock is unchanged. A throwing callback is
+ *        swallowed so it can mask neither `value` nor an error thrown by `fn`.
  * @param {...*} [opts.acquireOpts]  — remaining keys forwarded to tryAcquireFileLock.
  * @returns {Promise<{ ok: true, value: T }
  *   | { ok: false, reason: 'timeout'|'fs-error', error?: string, existing?: object|null }>}
@@ -534,6 +631,7 @@ export async function withFileLock(lockPath, fn, opts = {}) {
     pollMs = 100,
     sync = false,
     ownerGuard = true,
+    onRelease,
     ...acquireOpts
   } = opts;
 
@@ -567,6 +665,9 @@ export async function withFileLock(lockPath, fn, opts = {}) {
     const value = await fn(acquired.body);
     return { ok: true, value };
   } finally {
-    releaseFileLock(lockPath, { holder: releaseHolder, ownerGuard });
+    const released = releaseFileLock(lockPath, { holder: releaseHolder, ownerGuard });
+    if (typeof onRelease === 'function') {
+      try { onRelease(released); } catch { /* diagnostic sink — never masks fn */ }
+    }
   }
 }

package/scripts/lib/git-porcelain.mjs

@@ -0,0 +1,113 @@
+/**
+ * git-porcelain.mjs — the ONE parser for `git status --porcelain -z` output.
+ *
+ * Three consumers used to hand-roll this: `quality-gate.mjs` (hardened),
+ * `project-hygiene.mjs` (inline, R/C-aware) and `pre-dispatch-check.mjs`
+ * (non-`-z`, hand-unquoting only `\"` and `\\`, so any path carrying a TAB or a
+ * non-ASCII byte resolved to a NON-EXISTENT path — #1354). They now share this
+ * module.
+ *
+ * `-z` is not a convenience flag here — it is the only shape of this command
+ * whose paths are unambiguous. Measured 2026-08-23 (git 2.53.0) on a fixture
+ * carrying a space, a non-ASCII name, a literal `"` and a rename:
+ *
+ * ```
+ *   git status --porcelain            git status --porcelain -z
+ *   ------------------------------    ---------------------------------
+ *    M "scripts/lib/old name.mjs"      M scripts/lib/old name.mjs
+ *    M "scripts/lib/\303\274ml.mjs"    M scripts/lib/üml.mjs
+ *   ?? "scripts/lib/quo\"te.mjs"      ?? scripts/lib/quo"te.mjs
+ *   R  old.mjs -> new.mjs             R  new.mjs \0 old.mjs
+ * ```
+ *
+ * The non-`-z` form C-quotes any path containing a space, a `"` or — under the
+ * default `core.quotePath=true` — a non-ASCII byte. `-c core.quotePath=false`
+ * repairs only the non-ASCII third of that (measured: the space and the `"`
+ * stayed quoted). A field-splitting parser over the non-`-z` form fails three
+ * separate ways on one input — measured `awk '{print $2}'` output for the four
+ * lines above: `"scripts/lib/old` (truncated at the space), the undecoded
+ * `\303\274` octal escape, and `old.mjs` (the PRE-rename path) for the `R`
+ * line. `-z` emits every path verbatim, so there is no unquoting step to get
+ * wrong.
+ *
+ * Rename/copy entries carry their ORIGINAL path as the NEXT NUL field, with NO
+ * `XY ` prefix. Consuming that extra field is mandatory, not optional: a naive
+ * per-field `slice(3)` would emit `.mjs`-suffixed garbage (`d.mjs` for
+ * `old.mjs`) as if it were a real path. `R`/`C` are checked in BOTH status
+ * columns because git-status(1) documents `R `/`C ` (renamed/copied in index)
+ * as well as ` R`/` C` (renamed/copied in work tree).
+ *
+ * Ceiling (BV-004): this parses **porcelain v1** (`--porcelain` / `--porcelain=v1`)
+ * with `-z`, as emitted by git ≥ 2.x — the `XY <path>` entry shape plus the
+ * bare original-path field for `R`/`C`. It also accepts the `!!` entries that
+ * `--ignored` adds and the individual-file entries `-uall` produces. It does
+ * NOT parse porcelain **v2** (`--porcelain=v2`), whose entries are
+ * space-delimited records beginning with `1`/`2`/`u`/`?`/`!`, and it does not
+ * decode C-quoting, because `-z` never emits any. Revisit trigger: the first
+ * caller that needs v2's per-entry metadata (mode bits, object ids, submodule
+ * state) or that must parse output produced without `-z`.
+ */
+
+/**
+ * @typedef {Object} PorcelainEntry
+ * @property {string} x        first status column (index)
+ * @property {string} y        second status column (work tree)
+ * @property {string} status   both columns, e.g. `??`, `!!`, `R `, ` M`
+ * @property {string} path     path as git emitted it (verbatim, never quoted)
+ * @property {string|null} original  source path for a rename/copy, else `null`
+ */
+
+/**
+ * Parse `git status --porcelain -z` stdout into structured entries.
+ *
+ * Malformed fields are DROPPED rather than guessed at: `XY P` is the shortest
+ * well-formed entry, so anything shorter — including the empty trailing field
+ * `split` always produces — is not an entry header, and the `[2] === ' '`
+ * check rejects a stray original-path field that a malformed stream could
+ * leave unconsumed.
+ *
+ * @param {string} raw — raw stdout of `git status --porcelain -z …`.
+ * @returns {PorcelainEntry[]} entries, in git's emission order.
+ */
+export function parsePorcelainEntries(raw) {
+  const fields = String(raw ?? '').split('\0');
+  /** @type {PorcelainEntry[]} */
+  const entries = [];
+  for (let i = 0; i < fields.length; i += 1) {
+    const entry = fields[i];
+    if (typeof entry !== 'string' || entry.length < 4 || entry[2] !== ' ') continue;
+    const x = entry[0];
+    const y = entry[1];
+    let original = null;
+    if (x === 'R' || x === 'C' || y === 'R' || y === 'C') {
+      i += 1;
+      const src = fields[i];
+      if (typeof src === 'string' && src) original = src;
+    }
+    entries.push({ x, y, status: `${x}${y}`, path: entry.slice(3), original });
+  }
+  return entries;
+}
+
+/**
+ * Parse `git status --porcelain -z` stdout into repo-root-relative paths.
+ *
+ * Both halves of a rename/copy are kept — a file moved OUT of a watched
+ * directory is as much a touch as one moved in, and a fixer needs the old path
+ * to make sense of the new one.
+ *
+ * Untracked DIRECTORIES are not a case this function has to handle when the
+ * caller passes `-uall`, which expands them to individual files (measured:
+ * `?? nd/` became `?? nd/a.mjs` + `?? nd/b.mjs`).
+ *
+ * @param {string} raw — raw stdout of `git status --porcelain -z …`.
+ * @returns {string[]} repo-root-relative paths, in git's emission order.
+ */
+export function parsePorcelainZ(raw) {
+  const paths = [];
+  for (const entry of parsePorcelainEntries(raw)) {
+    if (entry.path) paths.push(entry.path);
+    if (entry.original) paths.push(entry.original);
+  }
+  return paths;
+}