session-orchestrator 4.0.0 → 4.1.0

package/scripts/release.mjs

@@ -121,12 +121,10 @@ export const SURFACES = [
     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',
+    // Cursor's native manifest replaces the root Agent Plugins manifest so
+    // Codex can load its own component paths and cache version independently.
+    // It remains a required version surface for every release.
+    file: '.cursor-plugin/plugin.json',
     patterns: [/"version":\s*"(\d+\.\d+\.\d+)"/],
   },
   {
@@ -191,6 +189,14 @@ export const SURFACES = [
     patterns: [/data-metric="version"[^>]*>(\d+\.\d+\.\d+)</g],
     checkOnly: true,
   },
+  {
+    // The German landing page (2026-09-07 redesign) mirrors the EN metric cells
+    // one-to-one; same single writer (scripts/site-numbers.mjs --write), so it is
+    // checkOnly for the same reason as site/index.html above.
+    file: 'site/de/index.html',
+    patterns: [/data-metric="version"[^>]*>(\d+\.\d+\.\d+)</g],
+    checkOnly: true,
+  },
   {
     file: 'site/llms.txt',
     patterns: [/Version:\s*(\d+\.\d+\.\d+)/],
@@ -362,7 +368,18 @@ const INTENTIONAL_TEST_ASSET_PATHS = new Set([
 // tests/scripts/site-numbers.test.mjs, which forbids ANY vX.Y.Z and the current
 // package version outside a `data-metric` cell on EVERY shipped page, and
 // exempts exactly the lines marked `site-numbers:historical`.
-export const HISTORY_ALLOWLIST = /^(CHANGELOG\.md|README\.md|docs\/|tests\/|skills\/npm-publish\/|scripts\/release\.mjs|\.orchestrator\/|site\/leaderboard\.json|site\/guide\/index\.html|commands\/release\.md)/;
+// 4.0.1 (measured 2026-09-07): the 4.0.0 sweep would have flagged five files whose only literal
+// is PROSE HISTORY of the major ("moved out of agents/ in 4.0.0", "removed in 4.0.0",
+// "releases 4.0.0 would have blocked on itself") — CLAUDE.md, its generated twin AGENTS.md,
+// CONTRIBUTING.md, NOTICE and .husky/pre-push. None of them is a version SURFACE (no
+// `"version":`, badge or `vX.Y.Z` form), so they join the history allowlist rather than being
+// reworded to dodge the sweep.
+// Four more prose-history files surfaced once the detail line stopped truncating at five hits
+// (same 2026-09-07 sweep): site/llms-full.txt ("The v4.0.0 release REMOVES public surfaces" — its
+// version SURFACE is checked separately by the SURFACES row, so the sweep on it is redundant),
+// skills/architecture/references/domain-model.md ("Merged here in v4.0.0"), skills/autopilot/SKILL.md
+// ("4.0.0 — see docs/migration-v4.md") and templates/_shared/journey-manifest.md ("Retired … in 4.0.0").
+export const HISTORY_ALLOWLIST = /^(CHANGELOG\.md|README\.md|CLAUDE\.md|AGENTS\.md|CONTRIBUTING\.md|NOTICE|\.husky\/pre-push|docs\/|tests\/|skills\/npm-publish\/|skills\/architecture\/references\/domain-model\.md|skills\/autopilot\/SKILL\.md|templates\/_shared\/journey-manifest\.md|scripts\/release\.mjs|\.orchestrator\/|site\/leaderboard\.json|site\/guide\/index\.html|site\/llms-full\.txt|commands\/release\.md)/;
 
 /** Pure check over packed-entry lines. Returns violations: {name, line}[]. */
 export function checkLeakage(lines) {
@@ -443,28 +460,95 @@ export const MIN_PACKED_ENTRIES = 400;
 // ---------------------------------------------------------------------------
 
 /**
- * Is EVERY occurrence of `literal` on this line a dependency range (`^X.Y.Z` / `~X.Y.Z`)?
+ * A regex matching `literal` as a VERSION TOKEN, not as a substring.
+ *
+ * THE BUG (measured 2026-09-07, mid-release): the sweep matched the previous tag `4.0.0`
+ * inside `>=24.0.0` — `package.json`'s own engines field and a `scripts/lib/` string that
+ * quotes it — so a release could not be cut without either rewording an engines constraint or
+ * widening the allowlist over two files that carry no version surface at all. The boundary is
+ * therefore part of WHAT IS SWEPT FOR, not an allowlist row: `24.0.0`, `14.0.0` and `4.0.0.1`
+ * are different literals, at every path, forever.
+ *
+ * @param {string} literal — the previous release version
+ * @returns {RegExp} global regex; `4.0.0` matches only when not preceded by `[0-9.]` and not
+ *   continued by a further numeric component (`(?!\.?[0-9])`).
+ */
+function versionTokenRegex(literal) {
+  return new RegExp(`(?<![0-9.])${literal.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?!\\.?[0-9])`, 'g');
+}
+
+/**
+ * Is EVERY token 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.
+ * that also happens to mention a ranged dep must not be excused by that mention. Occurrences are
+ * counted with {@link versionTokenRegex}, so `>=24.0.0` is not an occurrence of `4.0.0` here
+ * either — otherwise a line pinning `^4.0.0` beside an engines constraint would read as drift.
  *
  * @param {string} content — the matching line's text
- * @param {string} literal — the previous release version, matched literally
+ * @param {string} literal — the previous release version, matched as a token
  * @returns {boolean}
  */
 export function isDependencyRangeOnly(content, literal) {
-  let from = 0;
+  const re = versionTokenRegex(literal);
   let seen = 0;
-  for (;;) {
-    const at = content.indexOf(literal, from);
-    if (at === -1) break;
+  for (let m = re.exec(content); m; m = re.exec(content)) {
     seen += 1;
-    if (!(at > 0 && (content[at - 1] === '^' || content[at - 1] === '~'))) return false;
-    from = at + literal.length;
+    const before = m.index > 0 ? content[m.index - 1] : '';
+    if (before !== '^' && before !== '~') return false;
   }
   return seen > 0;
 }
 
+/** Lockfiles whose dependency entries are third-party history, never our surface. */
+const LOCKFILE_BASENAMES = new Set(['package-lock.json', 'npm-shrinkwrap.json']);
+
+/** Code files in which a `//`, `*`, `/*` or `#` line is comment prose, never a version surface. */
+const CODE_COMMENT_EXTENSIONS = new Set(['.mjs', '.js', '.cjs', '.ts', '.sh']);
+
+/**
+ * Is this `path:line:content` row version HISTORY rather than a stale surface?
+ *
+ * Three classes, all measured on the 4.0.1 cut (2026-09-07) as FALSE POSITIVES of the raw
+ * substring sweep, and all expressed as PREDICATES for the same reason the range carve-out
+ * above is one: a per-path allowlist row fixes the instance and leaves the class open.
+ *
+ * 1. **Dependency range** — `^X.Y.Z` / `~X.Y.Z` (see {@link isDependencyRangeOnly}).
+ * 2. **Lockfile dependency entry** — `package-lock.json` carried 72 hits for `4.0.0`, every one
+ *    a third-party package version or an engines range. Our OWN entry there is still swept: the
+ *    root package's `"version"` line, which npm writes in the `packages[""]` record at the top
+ *    of the file. NAMED CEILING (BV-004): "at the top" is read as `line <= 20`, which covers
+ *    every lockfileVersion-3 file npm writes today (the root record starts at line 5). Revisit
+ *    trigger: a lockfile whose root `"version"` sits below line 20 — then key on the enclosing
+ *    JSON path instead of the line number.
+ * 3. **Comment prose in a code file** — `// (pre-4.0.0 checkouts, …)` and a `* since 4.0.0`
+ *    docblock line. No SURFACES pattern is ever a comment (every one is `"version": "X.Y.Z"`,
+ *    `vX.Y.Z` or a badge), so excusing comment lines cannot mask a stale surface.
+ *
+ * @param {string} file — repo-relative path
+ * @param {number} line — 1-based line number
+ * @param {string} content — the matching line's text
+ * @param {string} prevTag — the previous release literal being swept for
+ * @returns {boolean} true = history, skip the row
+ */
+function isHistoryRow(file, line, content, prevTag) {
+  if (!versionTokenRegex(prevTag).test(content)) return true;
+  if (isDependencyRangeOnly(content, prevTag)) return true;
+  const base = file.split('/').pop();
+  if (LOCKFILE_BASENAMES.has(base)) {
+    const isRootVersionLine = line <= 20 && new RegExp(`"version":\\s*"${prevTag.replace(/\./g, '\\.')}"`).test(content);
+    return !isRootVersionLine;
+  }
+  const dot = base.lastIndexOf('.');
+  const ext = dot === -1 ? '' : base.slice(dot);
+  if (CODE_COMMENT_EXTENSIONS.has(ext)) {
+    const trimmed = content.trim();
+    if (trimmed.startsWith('//') || trimmed.startsWith('/*') || trimmed.startsWith('*')) return true;
+    if (ext === '.sh' && trimmed.startsWith('#')) return true;
+  }
+  return false;
+}
+
 /**
  * Drift sweep verdict over a grep-shaped result (`-l` file list or `-n` line hits).
  *
@@ -488,6 +572,13 @@ export function isDependencyRangeOnly(content, literal) {
  * 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.
  *
+ * THREE FURTHER CLASSES are history for the same reason, all measured 2026-09-07 mid-release
+ * and all decided by {@link isHistoryRow}, never by an allowlist row: a literal that is only a
+ * SUBSTRING of a longer version (`4.0.0` inside `>=24.0.0`), a `package-lock.json` /
+ * `npm-shrinkwrap.json` row that is not the root package's own `"version"` line (72 of the 72
+ * lockfile hits on that cut were third-party), and COMMENT PROSE in a code file
+ * (`// (pre-4.0.0 checkouts, …)`). See that function for each one's ceiling.
+ *
  * 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`)
@@ -510,13 +601,13 @@ export function evaluateDriftSweep(grep, prevTag, allowlist) {
     const withContent = row.match(/^(.+?):(\d+):(.*)$/);
     const file = withContent ? withContent[1] : row;
     if (allowlist.test(file)) continue;
-    if (withContent && isDependencyRangeOnly(withContent[3], prevTag)) continue;
+    if (withContent && isHistoryRow(file, Number(withContent[2]), 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(', ')}`
+      ? `still carry ${prevTag} (${hits.length} file(s)): ${hits.slice(0, 5).join(', ')}${hits.length > 5 ? ', …' : ''}`
       : `no file outside the allowlist still carries ${prevTag} (tracked + untracked-not-ignored)`,
   };
 }
@@ -1429,10 +1520,15 @@ export function printPublishOutcome(outcome, target, io = {}) {
     log(`  ${outcome.release.detail}.`);
   } else {
     error(`\nRECONCILIATION: ${outcome.release.detail}`);
-    if (outcome.release.state === 'create-failed') {
-      error(`  Recover with: gh release create ${outcome.tag} --verify-tag --title ${outcome.tag} --notes-file <changelog excerpt>`);
+    const recovery = outcome.release.recovery;
+    if (recovery?.inspect) {
+      error(`  Inspect with: ${renderRecoveryCommand(recovery.inspect)}`);
+      if (outcome.release.state === 'create-failed' && recovery.create) {
+        error(`  Recover with: ${renderRecoveryCommand(recovery.create)}`);
+        error('  The notes file is retained for recovery; remove it after the release is reconciled.');
+      }
     } else {
-      error('  Inspect `gh release view` and its authentication/network state before attempting any create.');
+      error('  Resolve the GitHub repository identity before inspecting or creating the release.');
     }
   }
 
@@ -1462,6 +1558,11 @@ export function printPublishOutcome(outcome, target, io = {}) {
   return 0;
 }
 
+/** Render argv for a POSIX shell without interpreting paths as shell code. */
+function renderRecoveryCommand(argv) {
+  return argv.map((arg) => /^[\w./:@=+-]+$/.test(arg) ? arg : `'${arg.replaceAll("'", "'\\''")}'`).join(' ');
+}
+
 /**
  * Create the GitHub release for `v<target>`, or confirm the existing one.
  *
@@ -1491,18 +1592,23 @@ export function printPublishOutcome(outcome, target, io = {}) {
  * @param {string} repoRoot
  * @param {string} target
  * @param {{runImpl?: Function, repoSpec?: string}} [deps] — injection seam for tests
- * @returns {{ok: boolean, created: boolean, tag: string, state: 'exists'|'created'|'unknown'|'create-failed', detail: string, argv?: string[]}}
+ * @returns {{ok: boolean, created: boolean, tag: string, state: 'exists'|'created'|'unknown'|'create-failed', detail: string, argv?: string[], recovery?: {inspect: string[], create?: string[]}}}
  */
 export function ensureGithubRelease(repoRoot, target, deps = {}) {
   const runImpl = deps.runImpl ?? run;
   const tag = `v${target}`;
-  const spec = deps.repoSpec ?? resolveRepoSpec({ repoRoot, vcs: 'github' });
-  // resolveRepoSpec returns undefined when it cannot auto-detect; its contract
-  // is that callers OMIT the flag rather than pass `-R undefined`.
-  const repoFlag = spec ? ['--repo', spec] : [];
+  let recovery;
 
   try {
-    const existing = runImpl('gh', ['release', 'view', tag, ...repoFlag], { cwd: repoRoot });
+    const spec = deps.repoSpec ?? resolveRepoSpec({ repoRoot, vcs: 'github' });
+    if (typeof spec !== 'string' || !spec.trim()) {
+      return { ok: false, created: false, tag, state: 'unknown', detail: 'GitHub repository identity could not be resolved' };
+    }
+    // Recovery must carry the same resolved identity as the real invocation.
+    // An absent identity cannot safely fall back to the caller's ambient repo.
+    const repoFlag = ['--repo', spec];
+    recovery = { inspect: ['gh', 'release', 'view', tag, ...repoFlag] };
+    const existing = runImpl(recovery.inspect[0], recovery.inspect.slice(1), { cwd: repoRoot });
     const viewOutput = `${existing.stdout || ''}\n${existing.stderr || ''}`.trim();
     if (existing.status === 0 && viewOutput) {
       return { ok: true, created: false, tag, state: 'exists', detail: `GitHub release ${tag} already exists — no-op` };
@@ -1516,6 +1622,7 @@ export function ensureGithubRelease(repoRoot, target, deps = {}) {
         created: false,
         tag,
         state: 'unknown',
+        recovery,
         detail: `could not determine whether GitHub release ${tag} exists (gh release view exited ${existing.status}: ${viewOutput.slice(0, 300) || 'empty output'})`,
       };
     }
@@ -1523,26 +1630,31 @@ export function ensureGithubRelease(repoRoot, target, deps = {}) {
     const notesDir = mkdtempSync(join(tmpdir(), 'release-ghnotes-'));
     const notesFile = join(notesDir, 'notes.md');
     let argv;
+    let retainNotes = false;
     try {
       writeFileSync(notesFile, `${changelogExcerpt(repoRoot, target)}\n`);
       argv = ['release', 'create', tag, ...repoFlag, '--verify-tag', '--title', tag, '--notes-file', notesFile];
       const created = runImpl('gh', argv, { cwd: repoRoot });
       if (created.status !== 0) {
+        // A recovery argv pointing to a file deleted by finally is unusable.
+        // Preserve only this failed-create excerpt; successful runs still clean up.
+        retainNotes = true;
         return {
           ok: false,
           created: false,
           tag,
           state: 'create-failed',
           argv,
+          recovery: { ...recovery, create: ['gh', ...argv] },
           detail: `gh release create exited ${created.status}: ${(created.stderr || created.stdout || '').trim().slice(0, 300)}`,
         };
       }
       return { ok: true, created: true, tag, state: 'created', argv, detail: `GitHub release ${tag} created (--verify-tag)` };
     } finally {
-      rmSync(notesDir, { recursive: true, force: true });
+      if (!retainNotes) rmSync(notesDir, { recursive: true, force: true });
     }
   } catch (err) {
-    return { ok: false, created: false, tag, state: 'unknown', detail: `gh could not be run: ${err.message}` };
+    return { ok: false, created: false, tag, state: 'unknown', ...(recovery ? { recovery } : {}), detail: `gh could not be run: ${err.message}` };
   }
 }