@dzhechkov/harness-core 0.8.41 → 0.8.43

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 = {
@@ -147,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[];
@@ -156,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. */
@@ -1510,52 +1518,67 @@ 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)}`);
       }
     }
   }
@@ -1577,6 +1600,7 @@ export function publishPackages(
     errors: results.filter((r) => r.status === 'error').length,
     dryRun: opts.dryRun === true,
     releaseLineSynced,
+    releaseLineReport,
     ...(warnings.length > 0 ? { warnings } : {}),
   };
 }

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;
 }

package/src/session-retro.ts

@@ -547,6 +547,14 @@ export const RETRO_PENDING_FILE = 'retro-pending.json';
 const MAX_TAIL_SCAN_BYTES = 8 * 1024 * 1024;
 /** Without a session id to compare, a sentinel older than this is stale (fallback freshness only). */
 const SENTINEL_FRESH_MS = 30 * 60 * 1000;
+const MAX_AWAITING_TEACHES = 16;
+
+export interface AdmissionDebt {
+  readonly snippet: string;
+  /** Paired call ids issued against THIS debt, in registration order (oldest first).
+   * Absent, rather than an empty array, when no calls await confirmation. */
+  readonly awaiting?: readonly string[];
+}
 
 export interface RetroPendingSentinel {
   readonly schema: 1;
@@ -554,6 +562,7 @@ export interface RetroPendingSentinel {
   readonly transcript: string;  // absolute transcript path — the debt belongs to THIS session
   readonly snippet: string;     // ≤200 chars around the admission marker
   readonly ts: string;          // ISO time of the scan that recorded the debt
+  readonly awaiting?: readonly string[];
 }
 
 /** Where the Stop-hook scan got its transcript path — or why it has none. */
@@ -643,20 +652,27 @@ const RETRO_SCAN_LOCK_TIMEOUT_MS = 2_000;
  */
 export function foldAdmissionDebt(
   events: readonly SessionEvent[],
-  prior: { snippet: string } | null,
-): { snippet: string } | null {
+  prior: AdmissionDebt | null,
+): AdmissionDebt | null {
   let pending = prior;
   // EVERY teach issued against the live debt and still awaiting its own result, by `tool_use_id`.
   // Round 3, P1-2: a single `lastPaid` slot lost the FIRST of two parallel teaches — the second call
   // saw an already-cleared `pending` and overwrote the slot with null, so when both results came back
   // receipt-less neither could re-arm and the debt was silently forgiven. A set, and settlement moved
   // to the RECEIPT, removes the whole class: the CALL now registers a candidate and changes nothing.
-  const awaiting = new Set<string>();
+  // Old or malformed sentinels mean no candidates, without skipping the rest of the scan.
+  const saved = prior?.awaiting;
+  const awaiting = new Set<string>(
+    Array.isArray(saved) && saved.every((id): id is string => typeof id === 'string') ? saved : [],
+  );
   for (const e of events) {
     if (isTeachCommand(e)) {
       if (typeof e.toolUseId === 'string') {
         // Registered, not settled. The debt stands until this call's own result carries a receipt.
-        if (pending !== null) awaiting.add(e.toolUseId);
+        if (pending !== null) {
+          awaiting.add(e.toolUseId);
+          if (awaiting.size > MAX_AWAITING_TEACHES) awaiting.delete(awaiting.values().next().value!);
+        }
       } else {
         // No pairing key ⇒ no result can ever confirm OR refute this call, so it pays on the command
         // alone — the pre-ADR-004 behaviour, kept deliberately so every id-less fixture and every
@@ -679,10 +695,16 @@ export function foldAdmissionDebt(
       const snippet = admissionSnippet(e.text);
       // A NEW admission supersedes every teach still in flight: those calls were issued against the
       // OLDER debt, so their receipts must not settle this one (ADR-001 D4 asymmetry).
-      if (snippet !== null) { pending = { snippet }; awaiting.clear(); }
+      if (snippet !== null) {
+        if (pending === null || pending.snippet !== snippet) awaiting.clear();
+        pending = { snippet };
+      }
     }
   }
-  return pending;
+  return pending === null ? null : {
+    snippet: pending.snippet,
+    ...(awaiting.size > 0 ? { awaiting: [...awaiting] } : {}),
+  };
 }
 
 const writeJsonAtomic = (path: string, value: unknown): void => {
@@ -735,11 +757,14 @@ function scanTailUnderLock(dzDir: string, transcriptPath: string, nowIso?: strin
     // Prior debt carries over ONLY for the same session; a stale sentinel (another session's debt)
     // is dropped — the PreCompact/SessionEnd retro of THAT session was its collector, and injecting
     // an old session's debt into a new one is noise (acid A9).
-    let prior: { snippet: string } | null = null;
+    let prior: AdmissionDebt | null = null;
     let hadSentinel = false;
     try {
       const s = JSON.parse(readFileSync(pendingPath, 'utf8')) as Partial<RetroPendingSentinel>;
-      if (s.transcript === transcriptPath && typeof s.snippet === 'string') { prior = { snippet: s.snippet }; hadSentinel = true; }
+      if (s.transcript === transcriptPath && typeof s.snippet === 'string') {
+        prior = { snippet: s.snippet, ...(s.awaiting !== undefined ? { awaiting: s.awaiting } : {}) };
+        hadSentinel = true;
+      }
       else { try { unlinkSync(pendingPath); } catch { /* already gone */ } }
     } catch { /* no sentinel */ }
 
@@ -778,7 +803,7 @@ function scanTailUnderLock(dzDir: string, transcriptPath: string, nowIso?: strin
     const next = foldAdmissionDebt(events, prior);
     const newOffset = offset + consumed;
     mkdirSync(dzDir, { recursive: true });
-    writeJsonAtomic(statePath, { schema: 1, transcript: transcriptPath, offset: newOffset });
+    let outcome: TailScanOutcome;
     if (next !== null) {
       const sentinel: RetroPendingSentinel = {
         schema: 1,
@@ -786,15 +811,26 @@ function scanTailUnderLock(dzDir: string, transcriptPath: string, nowIso?: strin
         transcript: transcriptPath,
         snippet: next.snippet.replace(/\s+/g, ' ').trim().slice(0, 200),
         ts: nowIso ?? new Date().toISOString(),
+        ...(next.awaiting !== undefined ? { awaiting: next.awaiting } : {}),
       };
       writeJsonAtomic(pendingPath, sentinel);
-      return { status: 'pending', snippet: sentinel.snippet, scannedBytes: consumed, offset: newOffset };
+      outcome = { status: 'pending', snippet: sentinel.snippet, scannedBytes: consumed, offset: newOffset };
+    } else if (hadSentinel) {
+      // Step-8 finding (23.09.2026, HIGH): swallowing EVERY unlink failure here and then advancing
+      // the offset anyway recreates the very loss this feature removes — the sentinel survives, the
+      // receipt that paid it is consumed, and every later scan re-arms the SAME stale snippet
+      // forever. Only "already gone" is benign; any other failure must leave the bytes replayable,
+      // so it propagates and the offset write below never runs. This makes the CLEAR branch
+      // symmetric with the ARM branch, which already blocks the offset on a failed write.
+      try { unlinkSync(pendingPath); }
+      catch (e) { if ((e as NodeJS.ErrnoException).code !== 'ENOENT') throw e; }
+      outcome = { status: 'cleared', scannedBytes: consumed, offset: newOffset };
+    } else {
+      outcome = { status: 'none', scannedBytes: consumed, offset: newOffset };
     }
-    if (hadSentinel) {
-      try { unlinkSync(pendingPath); } catch { /* already gone */ }
-      return { status: 'cleared', scannedBytes: consumed, offset: newOffset };
-    }
-    return { status: 'none', scannedBytes: consumed, offset: newOffset };
+    // Commit the debt BEFORE its offset: an interruption must leave these bytes replayable.
+    writeJsonAtomic(statePath, { schema: 1, transcript: transcriptPath, offset: newOffset });
+    return outcome;
   } catch {
     return { status: 'none', scannedBytes: 0, offset: 0 };
   }

package/src/text-mangling.ts

@@ -0,0 +1,29 @@
+/** Symptoms of text already damaged by shell expansion; these are warnings, never refusals. */
+export type MangleKind = 'teach' | 'backlog';
+export type MangleSymptom = {
+  kind: 'empty-substitution-hole' | 'dangling-arrow' | 'empty-brackets' | 'short-for-kind';
+  /** UTF-16 code-unit index, as used by JavaScript strings (not a UTF-8 byte offset). */
+  at: number;
+  excerpt: string;
+};
+
+const TEACH_MIN_CHARS = 40;
+const BACKLOG_MIN_CHARS = 20;
+
+export function detectMangledText(text: string, kind: MangleKind): readonly MangleSymptom[] {
+  // Literal backticks and $( are NOT symptoms: the shell left those characters intact.
+  const symptoms: MangleSymptom[] = [];
+  const add = (kind: MangleSymptom['kind'], at: number): void => {
+    symptoms.push({ kind, at, excerpt: text.slice(at, at + 40) });
+  };
+  const holes = /(?<=\S) {2,}(?=\S)|(?<=\S) +(?=[.,)»;:])/g;
+  const arrows = /(?:→|->)[\s\p{P}]*?(?=[.!?。！？]|$)/gu;
+  const brackets = /\(\s*\)|\[\s*\]|\{\s*\}|«\s*»|"\s*"|'\s*'/g;
+  for (const match of text.matchAll(holes)) add('empty-substitution-hole', match.index);
+  for (const match of text.matchAll(arrows)) add('dangling-arrow', match.index);
+  for (const match of text.matchAll(brackets)) add('empty-brackets', match.index);
+  if (text.trim().length < (kind === 'teach' ? TEACH_MIN_CHARS : BACKLOG_MIN_CHARS)) {
+    add('short-for-kind', 0);
+  }
+  return symptoms.sort((a, b) => a.at - b.at);
+}

package/src/tree-sync.ts

@@ -0,0 +1,17 @@
+/** File states shared by skill-tree producers. Extra target files are preserved. */
+export type FileState = 'match' | 'missing' | 'diverged' | 'extra';
+
+/** Compare relative-path → SHA-256 maps without reading or changing either tree. */
+export function compareTrees(
+  source: ReadonlyMap<string, string>,
+  target: ReadonlyMap<string, string>,
+): Map<string, FileState> {
+  const states = new Map<string, FileState>();
+  for (const [path, hash] of source) {
+    states.set(path, !target.has(path) ? 'missing' : target.get(path) === hash ? 'match' : 'diverged');
+  }
+  for (const path of target.keys()) {
+    if (!source.has(path)) states.set(path, 'extra');
+  }
+  return states;
+}