@dzhechkov/harness-core 0.8.40 → 0.8.42

package/src/publish.ts

@@ -22,7 +22,7 @@ type ExecSyncOptionsWithStringEncoding = NonNullable<Parameters<typeof execSync>
 import { createHash } from 'node:crypto';
 
 import { claimCheck } from './claim-check.js';
-import { rewriteReleaseLine, isReleaseLineToken } from './release-line.js';
+import { findReleaseLine, rewriteReleaseLine, isReleaseLineToken, shortPackageName } from './release-line.js';
 import { packedTarballName } from './packed-install-smoke.js';
 
 export type ProbeOutcome = {
@@ -38,12 +38,29 @@ export type ProbeOutcome = {
 export const REGISTRY_PROBE_BUDGET = 90;
 export const REGISTRY_PROBE_INTERVAL_MS = 10_000;
 
+export type RegistryProbe =
+  | { kind: 'published'; version: string; scripted?: true }
+  | { kind: 'never-published'; scripted?: true }
+  | { kind: 'unknown'; reason: string; scripted?: true };
+
+/**
+ * Scripted registry seam for tests that spawn the REAL bin and therefore cannot inject `exec`
+ * (first-publish-not-offline AM-A; same shape as `WF_RUN_DISPATCH_SCRIPT_ENV`). Value: path to a JSON
+ * file `{ "<name>": "<x.y.z>" | "E404" | "<npm code>" }`. When set, no `npm view` runs at all and EVERY
+ * row carries `probeOverride: true` — a scripted plan can never read as a verified one.
+ */
+export const PUBLISH_PROBE_SCRIPT_ENV = 'DZ_PUBLISH_PROBE_SCRIPT';
+
 /** Result for a single package publish attempt. */
 export interface PublishResult {
   readonly name: string;
   readonly oldVersion: string;
   readonly newVersion: string;
   readonly status: 'published' | 'skipped' | 'error';
+  readonly firstPublish?: boolean;
+  readonly probe?: RegistryProbe['kind'];
+  /** Present (true) only when `DZ_PUBLISH_PROBE_SCRIPT` answered instead of the registry. */
+  readonly probeOverride?: boolean;
   readonly error?: string | undefined;
   /** Live publish only: how many registry probes were needed to confirm the exact new version. */
   readonly registryProbes?: number | undefined;
@@ -130,6 +147,13 @@ export interface MirrorEpilogue {
   readonly warning?: string | undefined;
 }
 
+export interface ReleaseLineReport {
+  readonly path: string;   // 'README.md' | 'packages/@dzhechkov/harness-cli/README.md'
+  readonly rewritten: readonly { readonly name: string; readonly from: string; readonly to: string }[];
+  readonly kept: readonly { readonly name: string; readonly version: string }[];
+  readonly wrapped: boolean;
+}
+
 /** Full publish report. */
 export interface PublishReport {
   readonly packages: readonly PublishResult[];
@@ -139,6 +163,7 @@ export interface PublishReport {
   readonly dryRun: boolean;
   /** Repo-relative README paths whose first joint core/CLI release line was rewritten. */
   readonly releaseLineSynced: readonly string[];
+  readonly releaseLineReport: readonly ReleaseLineReport[];
   /** Post-publication sync failures are warnings: registry-confirmed packages cannot be unpublished. */
   readonly warnings?: readonly string[] | undefined;
   /** CLI-owned command-hook outcome after a live publish; no transport logic lives in core. */
@@ -176,26 +201,54 @@ export function compareVersions(a: string, b: string): number {
   return a0 - b0 || a1 - b1 || a2 - b2;
 }
 
-/**
- * The version already published to npm for `name`, or `undefined` if the package
- * has never been published (or npm is unreachable). Used to bump from
- * max(local, published) so a locally-reverted version can't collide (audit #10).
- */
 type PublishExec = (command: string, options: ExecSyncOptionsWithStringEncoding) => string;
 
-function publishedVersion(name: string, exec: PublishExec = execSync): string | undefined {
+/** Only explicit npm absence signals establish that a package has never been published. */
+export function classifyRegistryProbe(stderr: string, message: string): RegistryProbe {
+  const detail = `${stderr}\n${message}`;
+  if (/\bcode E404\b/.test(detail) || /\b404 Not Found\b/.test(detail) || /is not in this registry/.test(detail)) {
+    return { kind: 'never-published' };
+  }
+  const reason = /npm error code (\S+)/.exec(detail)?.[1]
+    ?? stderr.split(/\r?\n/).map((line) => line.trim()).find((line) => line.length > 0)
+    ?? message;
+  return { kind: 'unknown', reason };
+}
+
+function scriptedProbe(name: string): RegistryProbe | undefined {
+  const scriptPath = process.env[PUBLISH_PROBE_SCRIPT_ENV];
+  if (typeof scriptPath !== 'string' || scriptPath === '') return undefined;
+  let table: Record<string, unknown>;
   try {
-    const out = exec(`npm view ${name} version --prefer-online`, { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf-8', timeout: 20000 }).trim();
-    return /^\d+\.\d+\.\d+/.test(out) ? out : undefined;
-  } catch {
-    return undefined; // 404 (never published) or offline → fall back to local
+    table = JSON.parse(readFileSync(scriptPath, 'utf-8')) as Record<string, unknown>;
+  } catch (err) {
+    return { kind: 'unknown', reason: `scripted probe unreadable: ${err instanceof Error ? err.message : String(err)}`, scripted: true };
+  }
+  const answer = table[name];
+  if (typeof answer !== 'string') return { kind: 'unknown', reason: `scripted probe has no entry for ${name}`, scripted: true };
+  if (/^\d+\.\d+\.\d+/.test(answer)) return { kind: 'published', version: answer, scripted: true };
+  if (answer === 'E404') return { kind: 'never-published', scripted: true };
+  return { kind: 'unknown', reason: answer, scripted: true };
+}
+
+function probeRegistry(name: string, exec: PublishExec = execSync): RegistryProbe {
+  const scripted = scriptedProbe(name);
+  if (scripted !== undefined) return scripted;
+  try {
+    const out = exec(`npm view ${name} version --prefer-online`, { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf-8', timeout: 20000 }).trim();
+    return /^\d+\.\d+\.\d+/.test(out)
+      ? { kind: 'published', version: out }
+      : { kind: 'unknown', reason: 'unparsable npm view output' };
+  } catch (err) {
+    const error = err as { stderr?: unknown; message?: unknown } | null | undefined;
+    return classifyRegistryProbe(String(error?.stderr ?? ''), String(error?.message ?? ''));
   }
 }
 
 /** The higher of the local version and the npm-published version (audit #10). */
 function maxPublished(name: string, localVersion: string, exec: PublishExec = execSync): string {
-  const pub = publishedVersion(name, exec);
-  return pub !== undefined && compareVersions(pub, localVersion) > 0 ? pub : localVersion;
+  const probe = probeRegistry(name, exec);
+  return probe.kind === 'published' && compareVersions(probe.version, localVersion) > 0 ? probe.version : localVersion;
 }
 
 // ── workspace-floor preflight (feature workspace-dep-protocol, Codex P1) ─────
@@ -829,6 +882,8 @@ export function publishPackages(
   opts: {
     dryRun?: boolean | undefined;
     filter?: string[] | undefined;
+    /** Exact CLI-selected batch; an empty list means no targets. Discovery remains unfiltered. */
+    targetNames?: readonly string[] | undefined;
     bumpOnly?: boolean | undefined;
     /**
      * Path to the Ed25519 signing key, OUTSIDE the repository. A pack that carries a
@@ -860,8 +915,8 @@ export function publishPackages(
     /**
      * Floor probe injection for the workspace-floor preflight (see
      * `findUnpublishedWorkspaceFloors`). Default: a real `npm view` probe, which runs only on LIVE
-     * publishes — dry-run stays offline, matching `maxPublished`. Injecting a probe also arms the
-     * preflight under dry-run, which is how the wiring test drives it without network.
+     * publishes. Injecting a probe also arms this floor preflight under dry-run. The package's
+     * own registry classification runs in both live and dry-run modes independently.
      */
     probeFloor?: ((name: string, version: string) => boolean) | undefined;
     /** Subprocess injection for tests; the default is Node's synchronous executor. */
@@ -907,9 +962,13 @@ export function publishPackages(
 
   const packages = discoverPackages(monorepoRoot);
   const results: PublishResult[] = [];
-  const filtered = opts.filter && opts.filter.length > 0
+  const registryProbes = new Map<string, RegistryProbe>();
+  const matching = opts.filter && opts.filter.length > 0
     ? packages.filter((p) => opts.filter!.some((f) => matchesPublishFilter(p, f, monorepoRoot)))
     : packages;
+  const filtered = opts.targetNames === undefined
+    ? matching
+    : matching.filter((p) => opts.targetNames!.includes(p.name));
   // Publish dependencies before dependents so pnpm rewrites workspace:* to the
   // freshly-bumped version, never a stale one (the harness-cli@0.3.122 breakage).
   const ordered = orderByDependencies(filtered);
@@ -1014,11 +1073,29 @@ export function publishPackages(
       failedInBatch.add(pkg.name);
       continue;
     }
-    // Bump from max(local, npm-published) so a locally-reverted version can't
-    // collide with an already-published one (audit #10). Dry-run stays offline
-    // (local only) to keep previews fast and network-free.
-    const base = opts.dryRun ? oldVersion : maxPublished(pkg.name, oldVersion, exec);
-    const newVersion = bumpPatch(base);
+    // Both modes establish registry state before planning: absence keeps the disk version,
+    // uncertainty refuses a bump, and an existing release bumps from max(local, published).
+    const registryProbe = probeRegistry(pkg.name, exec);
+    registryProbes.set(pkg.name, registryProbe);
+    if (registryProbe.kind === 'unknown') {
+      results.push({
+        name: pkg.name, oldVersion, newVersion: oldVersion,
+        status: opts.dryRun ? 'skipped' : 'error',
+        probe: 'unknown',
+        error: opts.dryRun
+          ? `NOT ESTABLISHED (registry unreachable: ${registryProbe.reason})`
+          : `registry unreachable: ${registryProbe.reason} — cannot tell "never published" from "offline"; not bumping blind`,
+      });
+      if (!opts.dryRun) failedInBatch.add(pkg.name);
+      continue;
+    }
+    const plan = {
+      base: registryProbe.kind === 'published' && compareVersions(registryProbe.version, oldVersion) > 0
+        ? registryProbe.version : oldVersion,
+      firstPublish: registryProbe.kind === 'never-published',
+      probe: registryProbe.kind,
+    };
+    const newVersion = plan.firstPublish ? oldVersion : bumpPatch(plan.base);
 
     // Preflight: refuse to publish a pack whose `files` whitelist would silently
     // drop a skill dir from the tarball (the bug that shipped skills-meta without
@@ -1113,7 +1190,7 @@ export function publishPackages(
     if (opts.dryRun) {
       // NOT a statement that the package would publish cleanly — only that the gates checked ABOVE
       // this line passed. Everything below it (build, re-sign, pack, the package's own
-      // `prepublishOnly`, the registry itself) is untouched by a dry run and is named as such.
+      // `prepublishOnly`, the registry's publish receipt) is untouched by a dry run and named as such.
       const NOT_VERIFIED_BY_DRY_RUN = Object.freeze([
         'prepublishOnly пакета (его собственный гейт публикации)',
         'сборка dist из исходников',
@@ -1441,63 +1518,89 @@ export function publishPackages(
   }
 
   const releaseLineSynced: string[] = [];
+  const releaseLineReport: ReleaseLineReport[] = [];
   const warnings: string[] = [];
-  const releasePackageNames = new Set(['@dzhechkov/harness-core', '@dzhechkov/harness-cli']);
-  const releasePackagePublished = results.some(
-    (result) => result.status === 'published' && releasePackageNames.has(result.name),
-  );
-  if (releasePackagePublished && opts.dryRun !== true && opts.bumpOnly !== true) {
-    const currentVersion = (name: string): string | null => {
-      const landed = results.find((result) => result.name === name && result.status === 'published');
-      if (landed !== undefined) return landed.newVersion;
-      const pkg = packages.find((candidate) => candidate.name === name);
-      if (pkg === undefined) return null;
-      try {
-        const parsed = JSON.parse(readFileSync(pathJoin(pkg.dir, 'package.json'), 'utf8')) as { version?: unknown };
-        return typeof parsed.version === 'string' ? parsed.version : null;
-      } catch {
-        return null;
+  const versions: Record<string, string> = {};
+  for (const result of results.filter((result) => result.status === 'published')) {
+    versions[shortPackageName(result.name)] = result.newVersion;
+  }
+  // Dry-run marks would-publish packages skipped, but records successful planning in landedInBatch.
+  const planned: Record<string, string> = opts.dryRun === true ? {} : versions;
+  if (opts.dryRun === true) {
+    for (const result of results) {
+      if (landedInBatch.has(result.name) && result.error === undefined) {
+        planned[shortPackageName(result.name)] = result.newVersion;
       }
-    };
-    const coreVersion = currentVersion('@dzhechkov/harness-core');
-    const cliVersion = currentVersion('@dzhechkov/harness-cli');
-    if (coreVersion === null || cliVersion === null) {
-      warnings.push('release-line sync skipped: could not read both harness-core and harness-cli package versions');
-    } else {
-      const readmes = [
-        { path: 'README.md', absolute: pathJoin(monorepoRoot, 'README.md') },
-        {
-          path: 'packages/@dzhechkov/harness-cli/README.md',
-          absolute: pathJoin(monorepoRoot, 'packages', '@dzhechkov', 'harness-cli', 'README.md'),
-        },
-      ] as const;
-      for (const readme of readmes) {
-        try {
-          const original = readFileSync(readme.absolute, 'utf8');
-          const updated = rewriteReleaseLine(original, coreVersion, cliVersion);
-          if (updated === null) {
-            warnings.push(`release-line sync skipped ${readme.path}: release line not found`);
-            continue;
+    }
+  }
+  const syncReleaseLine = Object.keys(versions).length > 0 && opts.dryRun !== true && opts.bumpOnly !== true;
+  if (Object.keys(planned).length > 0 && opts.bumpOnly !== true) {
+    const readmes = [
+      { path: 'README.md', absolute: pathJoin(monorepoRoot, 'README.md') },
+      {
+        path: 'packages/@dzhechkov/harness-cli/README.md',
+        absolute: pathJoin(monorepoRoot, 'packages', '@dzhechkov', 'harness-cli', 'README.md'),
+      },
+    ] as const;
+    for (const readme of readmes) {
+      try {
+        const original = readFileSync(readme.absolute, 'utf8');
+        const found = findReleaseLine(original);
+        if (found === null) {
+          // A repo without a joint release line is the NORMAL case for every consumer monorepo —
+          // only a run that was actually about to WRITE has something to report here. The report-only
+          // pass (dry-run) records an empty plan and says nothing, which is what keeps `dz publish`'s
+          // output free of the word the FR-11 proxy watches for (cli.test.ts, "independent of the
+          // release feature"). MEASURED 2026-09-22: widening the gate without this made every dry-run
+          // in a line-less repo print a release-line warning.
+          if (syncReleaseLine) warnings.push(`release-line sync skipped ${readme.path}: release line not found`);
+          continue;
+        }
+        const rewritten: { name: string; from: string; to: string }[] = [];
+        const kept: { name: string; version: string }[] = [];
+        for (const token of found.tokens) {
+          if (Object.hasOwn(planned, token.name) && planned[token.name] !== token.version) {
+            rewritten.push({ name: token.name, from: token.version, to: planned[token.name]! });
+          } else {
+            kept.push({ name: token.name, version: token.version });
           }
-          if (updated === original) continue;
-          const tmp = readme.absolute + '.sync-tmp';
-          writeFileSync(tmp, updated);
-          renameSync(tmp, readme.absolute);
-          releaseLineSynced.push(readme.path);
-        } catch (error) {
-          warnings.push(`release-line sync failed ${readme.path}: ${error instanceof Error ? error.message : String(error)}`);
         }
+        releaseLineReport.push({ path: readme.path, rewritten, kept, wrapped: found.wrapped });
+        const updated = rewriteReleaseLine(original, planned);
+        if (!syncReleaseLine || updated === null || updated === original) continue;
+        const tmp = readme.absolute + '.sync-tmp';
+        writeFileSync(tmp, updated);
+        renameSync(tmp, readme.absolute);
+        releaseLineSynced.push(readme.path);
+      } catch (error) {
+        // Same rule as the not-found branch above: only the pass that was actually going to WRITE
+        // reports. A README that does not exist at all is the normal state of a consumer monorepo,
+        // and a report-only pass must not turn that into a warning naming the release line
+        // (FR-11 proxy, harness-cli/test/cli.test.ts — MEASURED 2026-09-22: ENOENT on both READMEs
+        // of a tmp fixture made every dry-run print two release-line warnings).
+        if (syncReleaseLine) warnings.push(`release-line sync failed ${readme.path}: ${error instanceof Error ? error.message : String(error)}`);
       }
     }
   }
 
   return {
-    packages: results,
+    // Decorate every final path, including packed transport and gate failures. A dependency
+    // blocked before its own probe has unknown registry state; keep the deps-first short circuit.
+    packages: results.map((result) => {
+      const registryProbe = registryProbes.get(result.name);
+      return {
+        ...result,
+        probe: registryProbe?.kind ?? 'unknown',
+        ...(registryProbe?.kind === 'never-published' ? { firstPublish: true } : {}),
+        ...(registryProbe?.scripted === true ? { probeOverride: true } : {}),
+      };
+    }),
     published: results.filter((r) => r.status === 'published').length,
     skipped: results.filter((r) => r.status === 'skipped').length,
     errors: results.filter((r) => r.status === 'error').length,
     dryRun: opts.dryRun === true,
     releaseLineSynced,
+    releaseLineReport,
     ...(warnings.length > 0 ? { warnings } : {}),
   };
 }

package/src/registry.ts

@@ -11,6 +11,7 @@ import { existsSync, readdirSync, readFileSync, realpathSync, statSync, type Dir
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import { PACKAGE_SKILL_LAYOUTS } from './package-skill-layouts.js';
 import { stems } from './stem.js';
 
 /**
@@ -81,11 +82,13 @@ function readSkillDiscoveryConfig(cwd: string): { skillScopes: string[]; skillDi
 /** List `skills-*` pack directories across all base dirs, de-duplicated by pack name (first wins). */
 /**
  * Does this directory actually carry skills? Answers by LOOKING, so a pack is catalogued for what it
- * contains rather than for how it is named. Bounded on purpose: only the three layouts real packs
- * use (`skills/<id>/SKILL.md`, `<pack>/<id>/SKILL.md` for a single-skill pack, and a bare
- * `SKILL.md`), never a full-tree walk — an unbounded scan over `node_modules` would cost more than
- * the catalogue it builds. Templates are excluded: a template is a stamp for making skills, not an
- * installed skill, and counting it would list the same name twice.
+ * contains rather than for how it is named. Probes PACKAGE_SKILL_LAYOUTS — the ONE table that says
+ * where a package keeps its skills (backlog 86b787b8: the same three layouts used to be spelled out
+ * by hand here and in `buildRegistry`, so the next layout would land in one place and be forgotten
+ * in the other). Bounded on purpose: never a full-tree walk, because an unbounded scan over
+ * `node_modules` would cost more than the catalogue it builds. For the flat layout the package
+ * itself may also be a skill (a bare `SKILL.md`). `hasSkillMd` skips a `templates` child so a
+ * template stamp is not counted twice — it is reached only through its own allowed layout.
  */
 function packCarriesSkills(dir: string): boolean {
   const hasSkillMd = (d: string): boolean => {
@@ -98,13 +101,11 @@ function packCarriesSkills(dir: string): boolean {
     return false;
   };
   try {
-    if (existsSync(join(dir, 'SKILL.md'))) return true;
-    if (hasSkillMd(join(dir, 'skills'))) return true;
-    // A template pack ships the skills it will roll out into the user's project. From the
-    // catalogue's point of view those skills EXIST — `trip-planner` and `presentation-storyteller`
-    // are installable answers to a task — so hiding them makes the advisor deny a real capability.
-    if (hasSkillMd(join(dir, 'templates', '.claude', 'skills'))) return true;
-    return hasSkillMd(dir);
+    return PACKAGE_SKILL_LAYOUTS.some(({ rel }) => {
+      const root = rel === '.' ? dir : join(dir, rel);
+      if (rel === '.' && existsSync(join(root, 'SKILL.md'))) return true;
+      return hasSkillMd(root);
+    });
   } catch {
     return false;
   }
@@ -482,17 +483,22 @@ export function buildRegistry(cwd: string): Registry {
   const entries: RegistryEntry[] = [];
   const packs = discoverSkillCarryingDirs(cwd);
 
-  // A pack keeps its skills in one of three shapes, and reading only the first made 41 real skills
+  // The catalogue collects ALL allowed layouts, and reading only the first made 41 real skills
   // invisible (MEASURED 2026-09-01): the pack root (`skills-*` packs), a `skills/` subdirectory
   // (health-advisor and friends), and `templates/.claude/skills/` for packs that roll their skills
-  // out into the user's project. The catalogue answers "what can I use", so all three count.
-  const SKILL_LAYOUTS = [[], ['skills'], ['templates', '.claude', 'skills']] as const;
+  // out into the user's project. A template pack ships the skills it will roll out; from the
+  // catalogue's point of view those skills EXIST — `trip-planner` and `presentation-storyteller`
+  // are installable answers to a task — so hiding them would make the advisor deny a real
+  // capability. The layouts themselves now come from PACKAGE_SKILL_LAYOUTS so the knowledge lives
+  // in ONE place; resolvePackageSkillRoots deliberately selects only the FIRST non-empty root
+  // (installation semantics, plan AM-4) and therefore cannot serve this enumeration — calling it
+  // here would silently drop skills from a pack that fills two layouts (backlog 86b787b8).
   const seenSkillIds = new Set<string>();
 
   for (const { pack, dir: packDir } of packs) {
     const found: { name: string; root: string }[] = [];
-    for (const layout of SKILL_LAYOUTS) {
-      const root = layout.length === 0 ? packDir : join(packDir, ...layout);
+    for (const { rel } of PACKAGE_SKILL_LAYOUTS) {
+      const root = rel === '.' ? packDir : join(packDir, rel);
       if (!existsSync(root)) continue;
       try {
         for (const e of readdirSync(root, { withFileTypes: true })) {

package/src/release-line.ts

@@ -1,6 +1,19 @@
 export const RELEASE_LINE_RE = /`harness-core v(\d+\.\d+\.\d+)` · `harness-cli v(\d+\.\d+\.\d+)`/;
 
-export interface ReleaseLineMatch {
+export interface ReleaseLineToken {
+  readonly name: string;
+  readonly version: string;
+  readonly start: number;
+  readonly end: number;
+}
+
+export interface ReleaseLineParse {
+  readonly tokens: readonly ReleaseLineToken[];
+  readonly chainEnd: number;
+  readonly wrapped: boolean;
+}
+
+export interface ReleaseLineMatch extends ReleaseLineParse {
   readonly index: number;
   readonly line: string;
   readonly core: string;
@@ -11,25 +24,43 @@ export function findReleaseLine(text: string): ReleaseLineMatch | null {
   const lines = text.split('\n');
   for (let index = 0; index < lines.length; index++) {
     const line = lines[index]!;
-    const match = RELEASE_LINE_RE.exec(line);
-    if (match?.[1] !== undefined && match[2] !== undefined) {
-      return { index, line, core: match[1], cli: match[2] };
+    const parsed = parseReleaseLine(line);
+    if (parsed !== null) {
+      return { index, line, core: parsed.tokens[0]!.version, cli: parsed.tokens[1]!.version, ...parsed };
     }
   }
   return null;
 }
 
-export function rewriteReleaseLine(text: string, core: string, cli: string): string | null {
+export function rewriteReleaseLine(text: string, versions: Readonly<Record<string, string>>): string | null;
+export function rewriteReleaseLine(text: string, core: string, cli: string): string | null;
+export function rewriteReleaseLine(
+  text: string,
+  versionsOrCore: Readonly<Record<string, string>> | string,
+  cli?: string,
+): string | null {
+  const versions: Readonly<Record<string, string>> = typeof arguments[1] === 'string'
+    ? { 'harness-core': versionsOrCore as string, 'harness-cli': cli! }
+    : versionsOrCore as Readonly<Record<string, string>>;
   const found = findReleaseLine(text);
   if (found === null) return null;
+  let line = found.line;
+  // Tokens are ordered by start; work from the right so length changes preserve earlier offsets.
+  for (let index = found.tokens.length - 1; index >= 0; index--) {
+    const token = found.tokens[index]!;
+    if (!Object.hasOwn(versions, token.name)) continue;
+    const versionStart = token.end - 1 - token.version.length;
+    line = line.slice(0, versionStart) + versions[token.name]! + line.slice(token.end - 1);
+  }
   const lines = text.split('\n');
-  lines[found.index] = found.line.replace(
-    RELEASE_LINE_RE,
-    `\`harness-core v${core}\` · \`harness-cli v${cli}\``,
-  );
+  lines[found.index] = line;
   return lines.join('\n');
 }
 
+export function shortPackageName(name: string): string {
+  return name.replace(/^@[^/]+\//, '');
+}
+
 /**
  * A generic RELEASE-LINE token: a backtick-quoted `<pkg-short-name> vX` pair, anywhere on a line —
  * the shape `RELEASE_LINE_RE` names for the joint `harness-core`/`harness-cli` pair, generalised to
@@ -40,6 +71,24 @@ export function rewriteReleaseLine(text: string, core: string, cli: string): str
  */
 export const GENERIC_RELEASE_TOKEN_RE = /`[a-z][a-z0-9-]*\s+v\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.]+)?`/;
 
+export function parseReleaseLine(line: string): ReleaseLineParse | null {
+  const joint = RELEASE_LINE_RE.exec(line);
+  if (joint === null) return null;
+  // Keep the original sticky chain boundary: prose ends the release line's permission.
+  const chainTail = new RegExp(`(?:\\s*·\\s*${GENERIC_RELEASE_TOKEN_RE.source})*`, 'y');
+  chainTail.lastIndex = joint.index + joint[0].length;
+  const tail = chainTail.exec(line);
+  const chainEnd = joint.index + joint[0].length + (tail?.[0].length ?? 0);
+  const tokens: ReleaseLineToken[] = [];
+  const chain = line.slice(joint.index, chainEnd);
+  for (const match of chain.matchAll(new RegExp(GENERIC_RELEASE_TOKEN_RE.source, 'g'))) {
+    const [name, version] = match[0].slice(1, -1).split(/\s+v/);
+    const start = joint.index + match.index;
+    tokens.push({ name: name!, version: version!, start, end: start + match[0].length });
+  }
+  return { tokens, chainEnd, wrapped: /\s*·\s*$/.test(line.slice(chainEnd)) };
+}
+
 /**
  * Is the OLD-VERSION occurrence at `[start, end)` in `line` sitting inside a `` `<name> vX` ``
  * backtick token? A POSITIVE override for `planReadmeVersionSync`'s citation heuristic: a token
@@ -53,11 +102,6 @@ export function isReleaseLineToken(line: string, start: number, end: number): bo
   // Codex r3 HIGH (lead): the permission is the joint pair PLUS the CONTIGUOUS ` · `<name> vX``
   // chain that follows it — not the whole line. `` `harness-core vX` · `harness-cli vY` — historically
   // `memory vZ` `` moves the first two and keeps the third (prose broke the chain).
-  const joint = RELEASE_LINE_RE.exec(line);
-  if (joint === null) return false;
-  const chainTail = new RegExp(`(?:\\s*·\\s*${GENERIC_RELEASE_TOKEN_RE.source})*`, 'y');
-  chainTail.lastIndex = joint.index + joint[0].length;
-  const tail = chainTail.exec(line);
-  const chainEnd = joint.index + joint[0].length + (tail?.[0].length ?? 0);
-  return joint.index <= start && end <= chainEnd;
+  const p = parseReleaseLine(line);
+  return p !== null && p.tokens[0]!.start <= start && end <= p.chainEnd;
 }