session-orchestrator 3.24.0 → 4.0.0

package/scripts/parse-config.mjs

@@ -3,10 +3,16 @@
  * parse-config.mjs — Parse ## Session Config from CLAUDE.md or AGENTS.md and output validated JSON.
  * Part of Session Orchestrator v3.0.0 (originally parse-config.sh in v2).
  *
- * Usage: node scripts/parse-config.mjs [path/to/CLAUDE.md|AGENTS.md]
+ * Usage: node scripts/parse-config.mjs [--json] [path/to/CLAUDE.md|AGENTS.md]
  *   If no path given, walks up from cwd to find project root and uses its CLAUDE.md (or AGENTS.md).
  *
  * Output: Single JSON object to stdout with ALL config fields (defaults applied).
+ *   `--json` is an explicit NO-OP alias for that default — accepted because
+ *   `docs/session-config-template.md` (lines 13 and 965) documents
+ *   `node scripts/parse-config.mjs --json` as THE validation command, and the
+ *   flag used to be swallowed by the positional-path slot and rejected with
+ *   `File not found: --json` (exit 1). `cli-design.md` § JSON-First Output also
+ *   requires every CLI to accept `--json`.
  * Exit codes: 0 success, 1 error (message to stderr)
  *
  * Unparsable lines inside `## Session Config` (#1097) are reported per line on
@@ -25,6 +31,7 @@ import { join, dirname, resolve, parse as parsePath } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseSessionConfig } from './lib/config.mjs';
 import { collectUnparsableLines } from './lib/config/section-extractor.mjs';
+import { findUnterminatedComment } from './lib/config/block-preprocess.mjs';
 import { ENFORCEMENT_VALUES } from './lib/config-schema.mjs';
 
 const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
@@ -93,10 +100,46 @@ function resolveConfigFile(argPath) {
 }
 
 // ---------------------------------------------------------------------------
-// Main
+// Main — argument parsing
 // ---------------------------------------------------------------------------
+//
+// Exactly two recognised flags plus one optional positional path. `--json` is
+// accepted and IGNORED: stdout is already a single JSON object, and the
+// documented validation command passes the flag. Anything else starting with
+// `-` is rejected rather than silently treated as a filename, so a typo cannot
+// masquerade as a missing file.
+
+const HELP_TEXT = `Usage: parse-config.mjs [--json] [path/to/CLAUDE.md|AGENTS.md]
+
+Parse the \`## Session Config\` block from CLAUDE.md (or AGENTS.md) and write
+the validated config to stdout as a single JSON object.
+
+Options:
+  --json     No-op alias for the default output (stdout is always JSON).
+  --help     Show this help and exit 0.
+
+Without a path, walks up from cwd to the project root and uses its CLAUDE.md,
+falling back to AGENTS.md. Exit codes: 0 success, 1 error (message on stderr).
+`;
+
+let argPath = null;
+for (const arg of process.argv.slice(2)) {
+  if (arg === '--help' || arg === '-h') {
+    process.stdout.write(HELP_TEXT);
+    process.exit(0);
+  } else if (arg === '--json') {
+    // no-op — the default output already IS JSON
+  } else if (arg.startsWith('-')) {
+    process.stderr.write(`parse-config.mjs: Unknown option: ${arg}\n\n${HELP_TEXT}`);
+    process.exit(1);
+  } else if (argPath === null) {
+    argPath = arg;
+  } else {
+    process.stderr.write(`parse-config.mjs: Unexpected extra argument: ${arg}\n\n${HELP_TEXT}`);
+    process.exit(1);
+  }
+}
 
-const argPath = process.argv[2] ?? null;
 const configFile = resolveConfigFile(argPath);
 
 let content;
@@ -107,6 +150,20 @@ try {
   process.exit(1);
 }
 
+// Unterminated-comment gate — ONE line per session, not one per parser.
+// An `<!--` with no `-->` after it would put the shared HTML-comment skipper in
+// the swallowing state for the rest of the document; `stripHtmlCommentBlocks`
+// now fails CLOSED (returns the lines unfiltered) rather than letting every
+// later block disappear into its defaults, but the operator still has to learn
+// that the document has a defect. This is the surface that says so — never
+// fatal, exit code unchanged.
+const unterminatedCommentLine = findUnterminatedComment(content.split(/\r?\n/));
+if (unterminatedCommentLine !== null) {
+  process.stderr.write(
+    `⚠ ${parsePath(configFile).base}: unterminated <!-- at line ${unterminatedCommentLine} — comment stripping disabled for the whole document\n`,
+  );
+}
+
 let config;
 try {
   config = parseSessionConfig(content);

package/scripts/release.mjs

@@ -81,13 +81,14 @@ import {
   rmSync,
   realpathSync,
 } from 'node:fs';
-import { join } from 'node:path';
+import { join, relative as relativePath, sep } from 'node:path';
 import { tmpdir } from 'node:os';
 import { spawnSync } from 'node:child_process';
 import { parseArgs } from 'node:util';
 import { fileURLToPath } from 'node:url';
 
 import { resolveRepoSpec } from './lib/vcs-repo-spec.mjs';
+import { enumerateRepoFiles } from './lib/validate/enumerate-repo-files.mjs';
 
 const PACKAGE_NAME = 'session-orchestrator';
 const SPAWN_OPTS = { encoding: 'utf8', maxBuffer: 32 * 1024 * 1024 };
@@ -119,6 +120,15 @@ export const SURFACES = [
     file: '.claude-plugin/plugin.json',
     patterns: [/"version":\s*"(\d+\.\d+\.\d+)"/],
   },
+  {
+    // Root `plugin.json` — the agent-plugins.org 1.0.0 manifest, added in 4.0.0. It is a
+    // FOURTH manifest carrying the version, and it was missing from this table on the 4.0.0
+    // cut: `--set-version` bumped the other three and `validate-plugin` then failed with
+    // "plugin.json version '3.24.0' != package.json version '4.0.0'". Exactly the incident
+    // class the table exists for, caught one gate later than it should have been.
+    file: 'plugin.json',
+    patterns: [/"version":\s*"(\d+\.\d+\.\d+)"/],
+  },
   {
     file: '.claude-plugin/marketplace.json',
     patterns: [/"version":\s*"(\d+\.\d+\.\d+)"/g],
@@ -307,7 +317,18 @@ function hasPathSegment(path, segment) {
 
 export const LEAKAGE_PATTERNS = [
   { name: 'tests/', matches: (path) => hasPathSegment(path, 'tests') },
-  { name: '.orchestrator/', matches: (path) => /\.orchestrator\//.test(path) },
+  // `.orchestrator/policy/` is CARVED OUT and everything else under
+  // `.orchestrator/` still leaks: the destructive-guard FLOOR policy ships to npm
+  // consumers since 4.0.0 (Codex P1 — measured: `npm pack` carried 0 policy
+  // entries, so `loadEffectivePolicy` returned `rules:null` and the guard allowed
+  // everything on a consumer install). The carve-out is a `policy/` PATH segment,
+  // not a prefix: `.orchestrator/metrics/`, `.orchestrator/tmp/`,
+  // `.orchestrator/runtime/`, `*.lock` and the `.orchestrator/policy-backup/`
+  // prefix trick are all still caught.
+  {
+    name: '.orchestrator/',
+    matches: (path) => /\.orchestrator\//.test(path) && !/^\.orchestrator\/policy\//.test(path),
+  },
   { name: '.claude/', matches: (path) => hasPathSegment(path, '.claude') },
   { name: '.github/', matches: (path) => /\.github\//.test(path) },
   { name: 'node_modules', matches: (path) => /node_modules/.test(path) },
@@ -422,15 +443,55 @@ export const MIN_PACKED_ENTRIES = 400;
 // ---------------------------------------------------------------------------
 
 /**
- * Drift sweep verdict over a `git grep -l` result.
+ * Is EVERY occurrence of `literal` on this line a dependency range (`^X.Y.Z` / `~X.Y.Z`)?
+ *
+ * One bare occurrence anywhere on the line is enough to call the whole line drift — a comment
+ * that also happens to mention a ranged dep must not be excused by that mention.
  *
- * `git grep` exit codes: 0 = matches found, 1 = no match (the success case
- * here), anything else = it did not run. Measured on git 2.x: a bad regex and
- * a bad pathspec both exit 128; git also documents 2 for usage errors. The old
- * inline code read `.stdout` without ever looking at `.status`, so BOTH the
- * no-match case and the it-crashed case produced an empty hit list and the
- * same reassuring detail line, "no tracked file still carries X". A sweep that
- * never ran is not a clean sweep.
+ * @param {string} content — the matching line's text
+ * @param {string} literal — the previous release version, matched literally
+ * @returns {boolean}
+ */
+export function isDependencyRangeOnly(content, literal) {
+  let from = 0;
+  let seen = 0;
+  for (;;) {
+    const at = content.indexOf(literal, from);
+    if (at === -1) break;
+    seen += 1;
+    if (!(at > 0 && (content[at - 1] === '^' || content[at - 1] === '~'))) return false;
+    from = at + literal.length;
+  }
+  return seen > 0;
+}
+
+/**
+ * Drift sweep verdict over a grep-shaped result (`-l` file list or `-n` line hits).
+ *
+ * Exit-code contract, kept identical to `git grep`'s because that is what this
+ * evaluator was written against and what {@link collectDriftHits} now emits:
+ * 0 = matches found, 1 = no match (the success case here), anything else = it
+ * did not run. Measured on git 2.x: a bad regex and a bad pathspec both exit
+ * 128; git also documents 2 for usage errors. The old inline code read
+ * `.stdout` without ever looking at `.status`, so BOTH the no-match case and
+ * the it-crashed case produced an empty hit list and the same reassuring
+ * detail line, "no file still carries X". A sweep that never ran is not a
+ * clean sweep.
+ *
+ * ONE CLASS OF MATCH IS NOT OURS TO BUMP: a dependency RANGE that happens to equal our own
+ * previous version. `skills/vault-sync` pins `zod` at `^3.24.0` (the projects-baseline pin), so
+ * the 4.0.0 sweep collected two files whose literal belongs to zod and must NOT move when we
+ * release. The carve-out is deliberately a PREDICATE and not two allowlist rows: a per-path row
+ * fixes this instance and leaves the class open for the next dependency that lands on our version
+ * number — the unenumerable-table failure `.claude/rules/measurement-discipline.md` records. A
+ * caret- or tilde-prefixed literal is a range, and no version surface of this package is ever
+ * written as one (see SURFACES above: every pattern is an exact `"version": "X.Y.Z"`, `vX.Y.Z`
+ * or badge form), so the predicate cannot mask a stale surface.
+ *
+ * Accepts BOTH `git grep` output shapes. A bare `path` (from `-l`) carries no content and is
+ * therefore always a hit — the fail-closed reading, unchanged, and the shape {@link collectDriftHits}
+ * emits for a file it could not READ. `path:line:content` (from `-n`)
+ * is judged per line, and the file counts as drift as soon as ONE matching line is not a range.
  *
  * @param {{status: number, stdout?: string, stderr?: string}} grep
  * @param {string} prevTag — the previous release literal being swept for
@@ -441,21 +502,102 @@ export function evaluateDriftSweep(grep, prevTag, allowlist) {
   if (grep.status !== 0 && grep.status !== 1) {
     return {
       ok: false,
-      detail: `git grep did not run (exit ${grep.status}): ${(grep.stderr || '').trim().slice(0, 200)} — sweep for ${prevTag} is inconclusive`,
+      detail: `drift sweep did not run (exit ${grep.status}): ${(grep.stderr || '').trim().slice(0, 200)} — sweep for ${prevTag} is inconclusive`,
     };
   }
-  const hits = (grep.stdout || '')
-    .split('\n')
-    .filter(Boolean)
-    .filter((f) => !allowlist.test(f));
+  const hits = [];
+  for (const row of (grep.stdout || '').split('\n').filter(Boolean)) {
+    const withContent = row.match(/^(.+?):(\d+):(.*)$/);
+    const file = withContent ? withContent[1] : row;
+    if (allowlist.test(file)) continue;
+    if (withContent && isDependencyRangeOnly(withContent[3], prevTag)) continue;
+    if (!hits.includes(file)) hits.push(file);
+  }
   return {
     ok: hits.length === 0,
     detail: hits.length
       ? `still carry ${prevTag}: ${hits.slice(0, 5).join(', ')}`
-      : `no tracked file outside the allowlist still carries ${prevTag}`,
+      : `no file outside the allowlist still carries ${prevTag} (tracked + untracked-not-ignored)`,
   };
 }
 
+/**
+ * Bytes of a file inspected when deciding whether it is binary.
+ *
+ * A NUL byte in the first 8 KB is the same heuristic `git grep`/`grep` use to
+ * declare a file binary. NAMED CEILING (BV-004): a text file whose only NUL
+ * sits past 8 KB is scanned as text (harmless — it produces no version match),
+ * and a binary whose first 8 KB happen to be NUL-free is scanned as text and
+ * may emit mojibake rows. Revisit trigger: the first drift-sweep row naming a
+ * file nobody recognises as text.
+ */
+const BINARY_SNIFF_BYTES = 8192;
+
+/**
+ * Produce the drift-sweep hit list over the files that EXIST in the working
+ * tree — tracked or not — in the exact `{status, stdout, stderr}` shape
+ * {@link evaluateDriftSweep} already consumes.
+ *
+ * ## Why not `git grep` any more (#1248)
+ *
+ * `git grep` searches the INDEX: it is blind to an untracked file, so the
+ * moment a stale version literal is most likely to exist (a doc or manifest
+ * written for this release and not yet staged) is exactly the moment the sweep
+ * cannot see it and reports clean. The population is now
+ * `scripts/lib/validate/enumerate-repo-files.mjs`
+ * (`git ls-files --cached --others --exclude-standard`) — tracked PLUS
+ * untracked, minus everything `.gitignore` excludes, so `node_modules/` and
+ * the peer worktrees under `.claude/worktrees/` stay out without a prune list
+ * having to guess at them.
+ *
+ * What `git grep` bought — searching hidden directories a plain `rg` skips,
+ * which is how the forgotten `.codex-plugin` manifest was found — is kept:
+ * `git ls-files` lists dotted paths like any other.
+ *
+ * ## Fail-closed, in two places
+ *
+ * Enumeration itself throwing is reported as exit 128, which
+ * {@link evaluateDriftSweep} reads as "inconclusive" = FAIL — the same reading
+ * a crashed `git grep` got. A single file that enumerates but cannot be READ
+ * is emitted as a CONTENT-LESS row, which that evaluator already treats as a
+ * hit: a file we could not sweep is never silently a clean file.
+ *
+ * @param {object} options
+ * @param {string} options.repoRoot absolute repository root
+ * @param {string} options.prevTag the previous release literal to sweep for
+ * @param {(o: {repoRoot: string}) => string[]} [options.enumerate] injection seam for tests
+ * @param {(absolute: string) => Buffer} [options.read] injection seam for tests
+ * @returns {{status: number, stdout: string, stderr: string}}
+ */
+export function collectDriftHits({ repoRoot, prevTag, enumerate = enumerateRepoFiles, read = readFileSync }) {
+  let files;
+  try {
+    files = enumerate({ repoRoot });
+  } catch (err) {
+    return { status: 128, stdout: '', stderr: `enumerateRepoFiles failed: ${err && err.message}` };
+  }
+  const rows = [];
+  for (const absolute of files) {
+    const relative = relativePath(repoRoot, absolute).split(sep).join('/');
+    let buf;
+    try {
+      buf = read(absolute);
+    } catch {
+      // Content-less row = hit (see the evaluator's contract above).
+      rows.push(relative);
+      continue;
+    }
+    if (buf.subarray(0, BINARY_SNIFF_BYTES).includes(0)) continue;
+    const text = buf.toString('utf8');
+    if (!text.includes(prevTag)) continue;
+    const lines = text.split('\n');
+    for (let i = 0; i < lines.length; i += 1) {
+      if (lines[i].includes(prevTag)) rows.push(`${relative}:${i + 1}:${lines[i]}`);
+    }
+  }
+  return { status: rows.length ? 0 : 1, stdout: rows.length ? `${rows.join('\n')}\n` : '', stderr: '' };
+}
+
 /**
  * Registry-collision verdict over `npm view <pkg> versions --json`.
  *
@@ -589,6 +731,53 @@ export function evaluateNpmAuth(whoami) {
     : { ok: false, detail: 'npm whoami exited 0 with an empty identity — the token could not be confirmed' };
 }
 
+/**
+ * Turn a `checkCiStatus` result into the `ci-green-on-head` preflight row.
+ *
+ * Three input states since #1031, and the middle one is why this is a named
+ * function rather than a ternary: `degraded` means the check could NOT be READ.
+ * Interpolating `ci.status` there printed `status: undefined` — a red row whose
+ * detail names no cause, which reads as "CI is broken" when the truth is "we
+ * never found out". Only an actual `status: 'green'` reading passes; a release
+ * must never proceed on an unknown CI state.
+ *
+ * @param {null | {status?: string, failingJobName?: string, degraded?: string}} ci
+ * @returns {{ok: boolean, detail: string}}
+ */
+export function evaluateCiRow(ci) {
+  if (ci === null || ci === undefined) return { ok: false, detail: 'CI status unavailable' };
+  if (ci.degraded) return { ok: false, detail: `CI status unknown (${ci.degraded})` };
+  const job = ci.failingJobName ? ` (${ci.failingJobName})` : '';
+  return { ok: ci.status === 'green', detail: `status: ${ci.status}${job}` };
+}
+
+/**
+ * Turn the GitHub-mirror CI reading into the `ci-green-on-head-github` row.
+ *
+ * WHY A SECOND CI ROW AT ALL: `ci-green-on-head` reads whatever platform
+ * `detectVcsFamily` picks for `origin` — GitLab here — and the GitLab pipeline
+ * runs Linux only. The **macOS** matrix leg exists solely on the GitHub mirror
+ * (`.github/workflows/test.yml`), i.e. on the operator's own platform. A
+ * release could therefore go out fully green with the macOS leg red, and the
+ * release path would never have asked.
+ *
+ * SELF-DISABLING, and that is the one place this row is allowed to pass without
+ * evidence: a checkout with no `github` remote has no mirror to be red, so the
+ * row is `skipped` rather than red. Everything else keeps the three-state
+ * contract of `evaluateCiRow` unchanged — `unknown` and `degraded` FAIL, because
+ * "we could not read the mirror" is not "the mirror is green" (the fail-closed
+ * house rule at the top of this file).
+ *
+ * @param {string|undefined} repoSpec — `resolveRepoSpec({vcs:'github'})`, undefined when no github remote resolves
+ * @param {null | {status?: string, failingJobName?: string, degraded?: string}} ci
+ * @returns {{ok: boolean, detail: string}}
+ */
+export function evaluateGithubCiRow(repoSpec, ci) {
+  if (!repoSpec) return { ok: true, detail: 'skipped — no github remote' };
+  const row = evaluateCiRow(ci);
+  return { ok: row.ok, detail: `${repoSpec} — ${row.detail}` };
+}
+
 /**
  * Flag-combination gate, applied before any work.
  *
@@ -697,12 +886,18 @@ async function preflight(repoRoot, target, { skipCi = false } = {}) {
   const changelog = checkChangelogEntry(readFileSync(join(repoRoot, 'CHANGELOG.md'), 'utf8'), target);
   add('changelog-entry', changelog.ok, changelog.problems.join('; '));
 
-  // 3b. Drift sweep: no TRACKED file outside the surfaces table + allowlist
-  // may still carry the previous release's version literal. `git grep` (not
-  // rg) on purpose — it searches every tracked file including hidden
-  // directories, which is exactly how the forgotten .codex-plugin manifest
-  // was invisible to a plain rg census. Allowlisted: files that legitimately
-  // carry version HISTORY.
+  // 3b. Drift sweep: no file outside the surfaces table + allowlist may still
+  // carry the previous release's version literal.
+  //
+  // POPULATION (#1248, closed here): this used to be one `git grep`, which
+  // searches the INDEX and is therefore blind to UNTRACKED files — the sweep
+  // measured "no TRACKED file still carries X" while its row read as a
+  // whole-tree census. It now enumerates via
+  // `scripts/lib/validate/enumerate-repo-files.mjs` (tracked PLUS
+  // untracked-not-ignored) and greps in-process; see {@link collectDriftHits}
+  // for the fail-closed contract and why hidden directories (the forgotten
+  // .codex-plugin manifest) are still covered. Allowlisted: files that
+  // legitimately carry version HISTORY.
   const tagList = run('git', ['tag', '-l', 'v*', '--sort=-v:refname'], { cwd: repoRoot });
   const prevTag = (tagList.stdout || '')
     .split('\n').map((t) => t.trim().replace(/^v/, ''))
@@ -712,8 +907,11 @@ async function preflight(repoRoot, target, { skipCi = false } = {}) {
     // one of them means the sweep is unnecessary.
     add('drift-sweep', false, `git tag -l failed (exit ${tagList.status}) — cannot determine the previous release to sweep for`);
   } else if (prevTag) {
-    const grep = run('git', ['grep', '-l', '--fixed-strings', prevTag, '--', '.'], { cwd: repoRoot });
-    const sweep = evaluateDriftSweep(grep, prevTag, HISTORY_ALLOWLIST);
+    // Line-shaped rows (not a bare file list): the verdict needs the matching LINE, because a
+    // caret-ranged dependency that equals our previous version is not drift and a file list
+    // cannot show that.
+    const hits = collectDriftHits({ repoRoot, prevTag });
+    const sweep = evaluateDriftSweep(hits, prevTag, HISTORY_ALLOWLIST);
     add('drift-sweep', sweep.ok, sweep.detail);
   } else {
     add('drift-sweep', true, 'no previous tag to sweep against');
@@ -769,8 +967,29 @@ async function preflight(repoRoot, target, { skipCi = false } = {}) {
   } else {
     const { checkCiStatus } = await import('./lib/ci-status-banner.mjs');
     const ci = await checkCiStatus({ repoRoot, timeoutMs: 15000 });
-    const green = ci !== null && ci.status === 'green';
-    add('ci-green-on-head', green, ci === null ? 'CI status unavailable' : `status: ${ci.status}${ci.failingJobName ? ` (${ci.failingJobName})` : ''}`);
+    const row = evaluateCiRow(ci);
+    add('ci-green-on-head', row.ok, row.detail);
+  }
+
+  // 6b. CI green on the GitHub mirror too. The row above asks the platform
+  // `detectVcsFamily` picks for `origin` (GitLab), whose pipeline is Linux-only;
+  // the macOS matrix leg lives exclusively in `.github/workflows/test.yml`.
+  // `vcs: 'github'` forces the probe onto the mirror without touching the
+  // detection order. The GitHub check-runs path reads `commits/HEAD`, i.e. the
+  // mirror's default-branch head — which is HEAD only because `head-pushed-github`
+  // above proves github/main == local HEAD; that row is this one's precondition,
+  // not a duplicate of it.
+  if (skipCi) {
+    add('ci-green-on-head-github', true, 'SKIPPED via --skip-ci');
+  } else {
+    const githubSpec = resolveRepoSpec({ repoRoot, vcs: 'github' });
+    let githubCi = null;
+    if (githubSpec) {
+      const { checkCiStatus } = await import('./lib/ci-status-banner.mjs');
+      githubCi = await checkCiStatus({ repoRoot, vcs: 'github', timeoutMs: 15000 });
+    }
+    const row = evaluateGithubCiRow(githubSpec, githubCi);
+    add('ci-green-on-head-github', row.ok, row.detail);
   }
 
   // 7. Leakage gate over the actual pack file list.
@@ -952,6 +1171,37 @@ export function waitForRegistryPropagation(repoRoot, target, deps = {}) {
  * @param {{runImpl?: Function, waitImpl?: Function, attempts?: number, delaySeconds?: number}} [deps]
  * @returns {{receipt: {confirmed: boolean, target: string, detail: string}, propagation: ReturnType<typeof waitForRegistryPropagation>}}
  */
+/**
+ * The exact `npm publish` invocation: argv plus spawn options.
+ *
+ * WHY THE ENV PIN, AND WHY THIS IS A NAMED FUNCTION: `npm_config_loglevel` is
+ * INHERITED, and the `+ <pkg>@<version>` receipt line — the ONE piece of
+ * evidence `evaluatePublishReceipt` accepts as the irreversible boundary — is
+ * printed at `notice` level. Any ancestor that ran under `npm run --silent`
+ * (the husky pre-push gate does exactly that) therefore hands this child a
+ * silent loglevel, npm publishes successfully and prints nothing, the receipt
+ * reads as unconfirmed, `publish()` throws, and `main()` exits 2 = "pre-receipt,
+ * safe to rerun" while the registry already holds the version. That is the worst
+ * failure this file can produce, and it is the same inherited-silent trap the
+ * leakage gate's `npm pack --dry-run` was already pinned against (see preflight
+ * step 7). The pin makes the receipt independent of the caller's environment.
+ *
+ * Exported because `publish()` itself deliberately is not (it is the
+ * irreversible act) — the invocation it builds is pure, so the pin is testable
+ * without a publishable seam.
+ *
+ * @param {string} repoRoot
+ * @param {string} userconfigPath — the 0600 temp npmrc carrying the token
+ * @returns {{cmd: string, args: string[], opts: {cwd: string, env: object}}}
+ */
+export function publishInvocation(repoRoot, userconfigPath) {
+  return {
+    cmd: 'npm',
+    args: ['publish', '--access', 'public', '--userconfig', userconfigPath],
+    opts: { cwd: repoRoot, env: { ...process.env, npm_config_loglevel: 'notice' } },
+  };
+}
+
 // Deliberately NOT exported: this is the irreversible act, and every production
 // path to it runs through main() -> preflight() (leakage gate, CI gate, dirty-tree
 // gate). Exporting it made the whole gate chain bypassable by any importer, and no
@@ -959,9 +1209,10 @@ export function waitForRegistryPropagation(repoRoot, target, deps = {}) {
 function publish(repoRoot, target, deps = {}) {
   const token = loadNpmToken(repoRoot);
   const runImpl = deps.runImpl ?? run;
-  const res = withTempUserconfig(token, (tmpRc) =>
-    runImpl('npm', ['publish', '--access', 'public', '--userconfig', tmpRc], { cwd: repoRoot }),
-  );
+  const res = withTempUserconfig(token, (tmpRc) => {
+    const call = publishInvocation(repoRoot, tmpRc);
+    return runImpl(call.cmd, call.args, call.opts);
+  });
   const receipt = evaluatePublishReceipt(res, target);
   if (!receipt.confirmed) throw new Error(receipt.detail);
 
@@ -1099,6 +1350,46 @@ export async function runPublishRelease(repoRoot, target, deps = {}) {
   };
 }
 
+/**
+ * Render the partial tag/push state left behind by a failed post-receipt tail.
+ *
+ * Pure so the reconciliation lines are unit-testable against a synthetic
+ * outcome: the branch that produces them only exists after an irreversible npm
+ * publish, which no test may perform.
+ *
+ * Absent progress is reported as absent, never as "nothing happened": a
+ * `tagAndPushImpl` that threw before attaching `releaseProgress` leaves state
+ * genuinely unknown, and the operator must inspect rather than assume.
+ *
+ * @param {{tag?: string|null, localTagCreated?: boolean, remotes?: Array<{remote: string, mainPushed?: boolean, tagPushed?: boolean}>}} [tagProgress]
+ * @returns {string[]}
+ */
+export function describeTagProgress(tagProgress) {
+  const lines = ['\nPARTIAL TAG/PUSH STATE (the npm receipt is already irreversible):'];
+  if (!tagProgress || typeof tagProgress !== 'object') {
+    lines.push('  tag/push progress was not recorded — inspect `git tag -l` and both remotes manually.');
+    return lines;
+  }
+  const tag = tagProgress.tag || 'the release tag';
+  lines.push(
+    tagProgress.localTagCreated === true
+      ? `  local tag ${tag}: CREATED (the next \`--check\` will fail \`tag-free-local\` until it is pushed or deleted).`
+      : `  local tag ${tag}: not created.`,
+  );
+  const remotes = Array.isArray(tagProgress.remotes) ? tagProgress.remotes : [];
+  if (remotes.length === 0) {
+    lines.push('  no remote was reached — neither main nor the tag was pushed anywhere.');
+    return lines;
+  }
+  for (const remote of remotes) {
+    lines.push(
+      `  ${remote.remote}: main ${remote.mainPushed === true ? 'pushed' : 'NOT pushed'}, ` +
+        `tag ${remote.tagPushed === true ? 'pushed' : 'NOT pushed'}.`,
+    );
+  }
+  return lines;
+}
+
 /**
  * Print a completed publish-tail outcome and return the CLI exit code.
  *
@@ -1120,6 +1411,16 @@ export function printPublishOutcome(outcome, target, io = {}) {
   }
   if (!tagAndPushFailed) {
     log(`  tagged ${outcome.tag} (AFTER publish) and pushed main+tag to: ${outcome.pushed.join(', ')}.`);
+  } else {
+    // The npm receipt is already irreversible at this point, so the ONLY thing
+    // that helps the operator is the exact partial state tag-and-push reached.
+    // `runPublishRelease` collects it (`tagProgress.localTagCreated` plus a
+    // per-remote `{mainPushed, tagPushed}`); this printer used to reference
+    // none of it and suppressed the `pushed:` line as well, so the operator was
+    // told only THAT it failed. The local-tag line matters twice over: a
+    // created local tag makes the next `--check` fail `tag-free-local`, which
+    // reads as a mysterious collision unless it was announced here.
+    for (const line of describeTagProgress(outcome.tagProgress)) error(line);
   }
 
   if (outcome.release.skipped) {
@@ -1377,6 +1678,13 @@ async function main() {
     if (!values.publish) return 0;
 
     console.log(`\nPublishing ${PACKAGE_NAME}@${target} ...`);
+    // No spawn timeout is set anywhere in this file, on purpose: a kill in the
+    // middle of `npm publish` or a tag push is the very failure the receipt
+    // boundary exists to avoid. The wall-clock cost is real, though — each of
+    // the two `git push` remotes re-runs the husky pre-push full gate (~2.5 min
+    // each, measured) and the site poll waits up to 120 s.
+    console.log('  This tail can run ~7 minutes (pre-push gate x2 remotes + up to 120s site poll).');
+    console.log('  Run it with a >=600s command timeout or in the background — do NOT kill it mid-run.');
     const outcome = await runPublishRelease(repoRoot, target, { publishImpl: publish });
     return printPublishOutcome(outcome, target);
   }

package/scripts/repair-invalid-sessions.mjs

@@ -40,7 +40,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { repairLedger, CANONICAL_LEDGER_REL } from './lib/session-record-repair.mjs';
-import { SO_PROJECT_DIR } from './lib/platform.mjs';
+import { getProjectDir } from './lib/platform.mjs';
 
 const USAGE =
   'Usage: node scripts/repair-invalid-sessions.mjs [--dry-run|--apply] [--json]\n' +
@@ -52,7 +52,7 @@ const USAGE =
   CANONICAL_LEDGER_REL +
   ');\n' +
   '                must resolve inside <repo-root>/.orchestrator/metrics/\n' +
-  '  --repo-root   project root (default: resolved SO_PROJECT_DIR)\n' +
+  '  --repo-root   project root (default: resolved project dir)\n' +
   'Exit codes: 0 completed, 1 arg error, 2 system error, 3 post-verification failed\n';
 
 /**
@@ -168,7 +168,7 @@ async function main() {
 
   // --apply is an explicit opt-in; absent it (or with --dry-run) we never write.
   const apply = values.apply === true && values['dry-run'] !== true;
-  const repoRoot = values['repo-root'] || SO_PROJECT_DIR;
+  const repoRoot = values['repo-root'] || getProjectDir();
   const requestedFile = values.file || path.join(repoRoot, CANONICAL_LEDGER_REL);
 
   // MED-3: bound the target to <repoRoot>/.orchestrator/metrics/ BEFORE any I/O.