@dzhechkov/harness-core 0.8.24 → 0.8.26

package/src/confirmation-file-gate.ts

@@ -0,0 +1,85 @@
+export type ConfirmationFileGateResult =
+  | { readonly verdict: 'pass'; readonly checked: readonly string[] }
+  | { readonly verdict: 'fail'; readonly missing: readonly string[] }
+  | { readonly verdict: 'skipped'; readonly reason: 'no-adr' }
+  | { readonly verdict: 'refused'; readonly reason: string };
+
+export type ConfirmationFileExists = (path: string) => boolean;
+
+const CONFIRMATION_HEADING = '## Confirmation';
+const TEST_FILE_TOKEN = /[A-Za-z0-9@._*-]+(?:\/[A-Za-z0-9@._*-]+)+\.(?:[cm]?[jt]sx?|py|sh)/g;
+
+function confirmationSections(text: string): string[] {
+  const lines = text.replace(/\r\n?/g, '\n').split('\n');
+  const starts: number[] = [];
+  for (let index = 0; index < lines.length; index++) {
+    const line = lines[index] ?? '';
+    if (line === CONFIRMATION_HEADING || line.startsWith(`${CONFIRMATION_HEADING} `)) {
+      starts.push(index);
+    }
+  }
+  if (starts.length !== 1) return [];
+  const start = starts[0] as number;
+  let end = lines.length;
+  for (let index = start + 1; index < lines.length; index++) {
+    if (/^## (?!#)\S/.test(lines[index] ?? '')) {
+      end = index;
+      break;
+    }
+  }
+  return [lines.slice(start + 1, end).join('\n')];
+}
+
+function testPaths(section: string): string[] {
+  const paths: string[] = [];
+  for (const match of section.matchAll(TEST_FILE_TOKEN)) {
+    const path = match[0];
+    const testNamed = /(?:^|\/)(?:test|tests)\//.test(path)
+      || /\.(?:test|spec)\.[cm]?[jt]sx?$/.test(path)
+      || /(?:^|\/)[A-Za-z0-9@._-]+-test\.(?:py|sh)$/.test(path);
+    if (testNamed && !paths.includes(path)) paths.push(path);
+  }
+  return paths;
+}
+
+/**
+ * Pure Step-8 policy. The caller owns filesystem access and injects a predicate that returns true
+ * only for a readable regular file. Throwing is a named refusal, never laundered into a skip.
+ */
+export function checkConfirmationFiles(
+  adrTexts: readonly string[],
+  exists: ConfirmationFileExists,
+): ConfirmationFileGateResult {
+  if (adrTexts.length === 0) return { verdict: 'skipped', reason: 'no-adr' };
+
+  const paths: string[] = [];
+  for (let index = 0; index < adrTexts.length; index++) {
+    const sections = confirmationSections(adrTexts[index] ?? '');
+    if (sections.length !== 1) {
+      return { verdict: 'refused', reason: `ADR ${index + 1} has no unique readable Confirmation section` };
+    }
+    const parsed = testPaths(sections[0] as string);
+    if (parsed.length === 0) {
+      return { verdict: 'refused', reason: `ADR ${index + 1} Confirmation contains no parseable test path` };
+    }
+    for (const path of parsed) {
+      if (path.includes('*')) {
+        return { verdict: 'refused', reason: `cannot inspect ${path}: test path is not literal` };
+      }
+      if (!paths.includes(path)) paths.push(path);
+    }
+  }
+
+  const missing: string[] = [];
+  for (const path of paths) {
+    try {
+      if (!exists(path)) missing.push(path);
+    } catch (error) {
+      const detail = error instanceof Error ? error.message : String(error);
+      return { verdict: 'refused', reason: `cannot inspect ${path}: ${detail}` };
+    }
+  }
+  return missing.length > 0
+    ? { verdict: 'fail', missing }
+    : { verdict: 'pass', checked: paths };
+}

package/src/contract-checklist.ts

@@ -21,6 +21,7 @@ export interface ContractSourceArtifact {
 export interface ContractChecklistSource {
   readonly requirements: ContractSourceArtifact;
   readonly adrs: readonly ContractSourceArtifact[];
+  readonly adrsOptional?: boolean;
 }
 
 export interface ContractItem {
@@ -127,6 +128,7 @@ export interface ContractVerification {
 }
 
 const REQUIREMENTS_HEADING = '## Acceptance criteria';
+const REQUIREMENTS_HEADINGS = [REQUIREMENTS_HEADING, '## Критерии приёмки'] as const;
 const CONFIRMATION_HEADING = '## Confirmation';
 const VERDICT_HEADING = '## Contract checklist';
 const REQUIREMENTS_FORMAT_LINE = 'Format: Every acceptance criterion below is exactly one physical line matching `^AC-([1-9][0-9]*): (\\S.*)$`; identifiers are contiguous from `AC-1`, and only the literal H2 `## Acceptance criteria` establishes this source section.';
@@ -139,10 +141,11 @@ function linesOf(text: string): string[] {
   return text.replace(/\r\n?/g, '\n').split('\n');
 }
 
-function h2Indexes(lines: readonly string[], heading: string): number[] {
+function h2Indexes(lines: readonly string[], heading: string | ((line: string) => boolean)): number[] {
   const indexes: number[] = [];
   for (let index = 0; index < lines.length; index++) {
-    if (lines[index] === heading) indexes.push(index);
+    const line = lines[index] ?? '';
+    if (typeof heading === 'string' ? line === heading : heading(line)) indexes.push(index);
   }
   return indexes;
 }
@@ -176,7 +179,9 @@ function acceptanceItems(
   diagnostics: ContractDiagnostic[],
 ): PendingContractItem[] {
   const lines = linesOf(artifact.text);
-  const headings = h2Indexes(lines, REQUIREMENTS_HEADING);
+  const headings = h2Indexes(lines, (line) => REQUIREMENTS_HEADINGS.includes(
+    line as (typeof REQUIREMENTS_HEADINGS)[number],
+  ));
   if (headings.length !== 1) {
     diagnostics.push(diagnostic(
       headings.length === 0 ? 'requirements-section-missing' : 'requirements-section-duplicate',
@@ -275,7 +280,8 @@ function confirmationItem(
     return null;
   }
   const lines = linesOf(artifact.text);
-  const headings = h2Indexes(lines, CONFIRMATION_HEADING);
+  const headings = h2Indexes(lines, (line) => line === CONFIRMATION_HEADING
+    || line.startsWith(`${CONFIRMATION_HEADING} `));
   if (headings.length !== 1) {
     diagnostics.push(diagnostic(
       headings.length === 0 ? 'confirmation-section-missing' : 'confirmation-section-duplicate',
@@ -349,7 +355,7 @@ export function extractContractChecklist(input: ContractChecklistSource): Contra
   const requirements = acceptanceItems(input.requirements, diagnostics);
   validateAcceptanceIds(requirements, input.requirements, diagnostics);
 
-  if (input.adrs.length === 0) {
+  if (input.adrs.length === 0 && input.adrsOptional !== true) {
     diagnostics.push(diagnostic(
       'adr-input-empty',
       'at least one direct canonical ADR Markdown file is required',

package/src/core-boundary.ts

@@ -0,0 +1,43 @@
+import ts from 'typescript';
+
+/** Internal test scanner: parsing keeps comments and literal text out of code visits. */
+export function findProcessAccessInCode(source: string): Array<{ line: number; kind: string }> {
+  const file = ts.createSourceFile('boundary.ts', source, ts.ScriptTarget.Latest, true);
+  const hits: Array<{ line: number; kind: string }> = [];
+  function visit(node: ts.Node): void {
+    if (ts.isPropertyAccessExpression(node) && ts.isIdentifier(node.expression)
+      && node.expression.text === 'process' && ['argv', 'exit'].includes(node.name.text)) {
+      hits.push({ line: file.getLineAndCharacterOfPosition(node.getStart(file)).line + 1, kind: node.name.text });
+    }
+    ts.forEachChild(node, visit);
+  }
+  visit(file);
+  return hits;
+}
+
+/** Count import declarations, import-equals, require and dynamic imports, not mentions. */
+export function countIoImports(
+  source: string,
+  modules: readonly string[] = ['node:fs', 'fs', 'node:child_process', 'child_process', 'node:https', 'https'],
+): { files: number; imports: number } {
+  const file = ts.createSourceFile('boundary.ts', source, ts.ScriptTarget.Latest, true);
+  let imports = 0;
+  function visit(node: ts.Node): void {
+    let specifier: ts.Node | undefined;
+    if (ts.isImportDeclaration(node)) specifier = node.moduleSpecifier;
+    else if (ts.isImportEqualsDeclaration(node) && ts.isExternalModuleReference(node.moduleReference)) {
+      specifier = node.moduleReference.expression;
+    } else if (ts.isCallExpression(node)
+      && (node.expression.kind === ts.SyntaxKind.ImportKeyword
+        || (ts.isIdentifier(node.expression) && node.expression.text === 'require'))) {
+      specifier = node.arguments[0];
+    }
+    if (specifier && ts.isStringLiteralLike(specifier)
+      && modules.some((name) => specifier.text === name || specifier.text.startsWith(`${name}/`))) {
+      imports += 1;
+    }
+    ts.forEachChild(node, visit);
+  }
+  visit(file);
+  return { files: imports > 0 ? 1 : 0, imports };
+}

package/src/feature-adr-landing.ts

@@ -1,3 +1,5 @@
+import { probePid } from './run-registry.js';
+
 /** Pure decisions for the Step-7.5 Codex companion liveness barrier. */
 
 export const DEFAULT_CODE_LANDING_CEILING_MS = 7_200_000;
@@ -24,7 +26,8 @@ export type CodeLandingLivenessReason =
 
 export interface CodeLandingLivenessInput {
   readonly companionStatus: unknown;
-  readonly recordedPidAlive: boolean | null;
+  readonly recordedPidAlive?: boolean | null;
+  readonly recordedPid?: number;
   readonly targetsChanged: boolean | null;
   readonly elapsedMs: number;
   readonly ceilingMs: number;
@@ -43,17 +46,18 @@ export interface CodeLandingLivenessDecision {
   readonly reason: CodeLandingLivenessReason;
 }
 
-export function decideCodeLandingLiveness(input: CodeLandingLivenessInput): CodeLandingLivenessDecision {
+export function decideCodeLandingLiveness(input: CodeLandingLivenessInput, pidProbe = probePid): CodeLandingLivenessDecision {
   const status = typeof input.companionStatus === 'string' ? input.companionStatus.trim().toLowerCase() : ''
   const elapsedMs = Number.isFinite(input.elapsedMs) ? Math.max(0, input.elapsedMs) : 0
   const ceilingMs = Number.isFinite(input.ceilingMs) && input.ceilingMs > 0 ? input.ceilingMs : DEFAULT_CODE_LANDING_CEILING_MS
+  const recordedPidAlive = input.recordedPidAlive === undefined ? (input.recordedPid === undefined ? null : pidProbe(input.recordedPid)) : input.recordedPidAlive
   const live = status === 'running' || status === 'queued'
   const terminal = status === 'completed' || status === 'failed' || status === 'cancelled'
 
-  if (live && input.recordedPidAlive === false) {
+  if (live && recordedPidAlive === false) {
     return { verdict: 'dead-worker', reason: 'recorded-pid-absent' }
   }
-  if (live && input.recordedPidAlive === true) {
+  if (live && recordedPidAlive === true) {
     if (elapsedMs >= ceilingMs) return { verdict: 'inconclusive', reason: 'ceiling-exceeded' }
     return { verdict: 'coder-running', reason: 'recorded-pid-alive' }
   }

package/src/feature-tier.ts

@@ -0,0 +1,56 @@
+import type { FeatureTier } from './guard-volume.js';
+
+function tiersAfterMarkers(line: string): FeatureTier[] {
+  if (!/^\s*(?:##\s*)?(?:\*\*)?(?:Tier|Тир)(?=$|[\s:*])/iu.test(line)) return [];
+  const tiers: FeatureTier[] = [];
+  for (const marker of line.matchAll(/Tier|Тир/giu)) {
+    const markerIndex = marker.index ?? 0;
+    const previous = line[markerIndex - 1];
+    if (previous !== undefined && /[\p{L}\p{N}_]/u.test(previous)) continue;
+    const tail = line.slice(markerIndex + marker[0].length);
+    // A template line lists several tiers after one marker («Tier: S / M / L / XL», «Tier: S|M») — every
+    // listed token is a candidate, so the caller sees the ambiguity instead of the first token (QE 08c #1).
+    const match = tail.match(/^(?:\s*:\s*|\s+)(?:\*\*)?\s*(XL|[SML])((?:\s*[/|,]\s*(?:XL|[SML]))*)(?=$|[\s.*)—–-])/iu);
+    if (match?.[1] !== undefined) {
+      tiers.push(match[1].toUpperCase() as FeatureTier);
+      for (const extra of (match[2] ?? '').matchAll(/XL|[SML]/giu)) tiers.push(extra[0].toUpperCase() as FeatureTier);
+    }
+  }
+  return tiers;
+}
+
+function tierAtContinuationStart(line: string): FeatureTier | null {
+  const match = line.match(/^\s*(?:\*\*)?\s*(XL|[SML])(?=$|[\s:.*)—–-])/iu);
+  return match?.[1] === undefined ? null : match[1].toUpperCase() as FeatureTier;
+}
+
+export function parseFeatureTier(text: string): FeatureTier | null {
+  const lines = text.split(/\r?\n/);
+  const candidates = new Set<FeatureTier>();
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index]!;
+    for (const inline of tiersAfterMarkers(line)) candidates.add(inline);
+
+    if (!/^\s*##\s*(?:Tier|Тир)\s*$/iu.test(line)) continue;
+    const continuation = lines.slice(index + 1).find((next) => next.trim() !== '');
+    if (continuation === undefined) continue;
+    const continuedTiers = tiersAfterMarkers(continuation);
+    if (continuedTiers.length > 0) {
+      for (const nextTier of continuedTiers) candidates.add(nextTier);
+    } else {
+      const nextTier = tierAtContinuationStart(continuation);
+      if (nextTier !== null) candidates.add(nextTier);
+    }
+  }
+
+  return candidates.size === 1 ? [...candidates][0]! : null;
+}
+
+export function readFeatureTier(
+  read: (rel: string) => string | null,
+  slug: string,
+): FeatureTier | null {
+  const text = read(`features/${slug}/00_complexity_assessment.md`);
+  return text === null ? null : parseFeatureTier(text);
+}

package/src/index.ts

@@ -134,7 +134,7 @@ export { tokenize, stemToken, stems } from './stem.js';
 export * from './package-skill-layouts.js';
 export { recommend } from './recommend.js';
 export { pretrain } from './pretrain.js';
-export { loadPatterns, loadSessions, computePatternBoost, readLearningConfig, readMemoryLearningConfig, BOOST_CAP, recordPattern, recordLessonForms, loadStorePatternsSync, loadStoreRecords, patternToRecord, recordToPattern, patternRecordId, patternIdentityOf, dreamRecordId, isMirrorableLearning, consolidateSessions, recallPatterns, pruneNoisePatterns, removePatternsByIds, snapshotStore, readReinforcementState, encodeReinforcementState, reinforcePattern, updateReinforcementState, storeStats, lessonDeltaReport, lessonDeltaMap, readQuarantineState, encodeQuarantineState, promotePatterns, quarantineExpiryCandidates, pruneQuarantinePatterns } from './patterns.js';
+export { loadPatterns, loadSessions, computePatternBoost, readLearningConfig, readMemoryLearningConfig, BOOST_CAP, recordPattern, recordLessonForms, loadStorePatternsSync, loadStoreRecords, findExactLesson, patternToRecord, recordToPattern, patternRecordId, patternIdentityOf, dreamRecordId, isMirrorableLearning, consolidateSessions, recallPatterns, pruneNoisePatterns, removePatternsByIds, snapshotStore, readReinforcementState, encodeReinforcementState, reinforcePattern, updateReinforcementState, storeStats, lessonDeltaReport, lessonDeltaMap, readQuarantineState, encodeQuarantineState, promotePatterns, quarantineExpiryCandidates, pruneQuarantinePatterns } from './patterns.js';
 export { normalizeLessonForms, validateClassTemplate, lessonPairIdOf, mergeLessonFormHits, mergeLessonMatchedForms } from './lesson-generalization.js';
 export { withStoreLock, withStoreLockSync, storeLockPath, StoreLockTimeoutError, StoreLockCompromisedError, STALE_LOCK_MS, LOCK_TIMEOUT_MS } from './store-lock.js';
 export type { StoreLockOptions } from './store-lock.js';
@@ -464,6 +464,7 @@ export type {
   ContractVerificationCounts,
   ContractVerification,
 } from './contract-checklist.js';
+export * from './feature-tier.js';
 export {
   DOMAIN_LIFT_EXACT,
   DOMAIN_LIFT_RELATED,
@@ -1153,3 +1154,10 @@ export type { ClaudeHookAssetOptions } from './claude-hooks-assets.js';
 export { harnessCoreDistDir, harnessCoreModuleDir } from './harness-core-location.js';
 
 export { maskMarkdown } from './markdown-masker.js';
+export * from './confirmation-file-gate.js';
+
+export * from './run-registry.js';
+
+export { JOURNAL_KINDS, formatLine, parseLine, selectWindow, appendWitnessed } from './journal.js';
+export type { JournalKind, JournalEvent, JournalLine, JournalIo } from './journal.js';
+export * from './run-cleanup.js';

package/src/journal.ts

@@ -0,0 +1,54 @@
+/** Existing Markdown day files; no migration or alternate event store. */
+export const JOURNAL_KINDS = ['decision', 'verdict', 'run', 'error', 'block'] as const;
+export type JournalKind = typeof JOURNAL_KINDS[number];
+const labels: Record<JournalKind, string> = {
+  decision: 'решение', verdict: 'вердикт', run: 'запуск', error: 'ошибка', block: 'блокировка',
+};
+export interface JournalEvent { time: string; kind: JournalKind; text: string; ref: string }
+export type JournalLine = ({ status: 'parsed'; raw: string } & JournalEvent) | { status: 'unparsed'; raw: string };
+export interface JournalIo { read(path: string): string; append(path: string, body: string): void }
+
+export function formatLine(event: JournalEvent): string {
+  if (!JOURNAL_KINDS.includes(event.kind)) throw new Error(`Категория: ${JOURNAL_KINDS.join(', ')}`);
+  if (!/^(?:[01]\d|2[0-3]):[0-5]\d$/.test(event.time)) throw new Error('Время должно быть HH:MM UTC');
+  if (!event.text.trim() || /[\r\n\0]/.test(event.text + event.ref) || event.ref.includes('·')) {
+    throw new Error('Текст и след должны занимать одну строку; след не содержит ·');
+  }
+  return `- ${event.time} · ${labels[event.kind]}: ${event.text.trim()} · ${event.ref.trim()}`;
+}
+
+export function parseLine(raw: string): JournalLine {
+  const unparsed = { status: 'unparsed', raw } as const;
+  const first = raw.indexOf('·'); const last = raw.lastIndexOf('·');
+  if (first < 0 || last === first) return unparsed;
+  const time = /^- ((?:[01]\d|2[0-3]):[0-5]\d)\s*$/.exec(raw.slice(0, first))?.[1];
+  const body = raw.slice(first + 1, last).trim(); const colon = body.indexOf(':');
+  if (!time || colon < 0) return unparsed;
+  const category = body.slice(0, colon).trim();
+  const kind = JOURNAL_KINDS.find(k => category === k || category === labels[k]
+    || (k === 'decision' && category.startsWith('решение владельца'))
+    || (k === 'error' && category === 'ошибка ведущего')
+    || (k === 'run' && ['падение', 'запуск / падение'].includes(category)));
+  if (!kind || !body.slice(colon + 1).trim()) return unparsed;
+  return { status: 'parsed', raw, time, kind, text: body.slice(colon + 1).trim(), ref: raw.slice(last + 1).trim() };
+}
+
+/** Inclusive UTC window ending on at; week means the trailing seven calendar days. */
+export function selectWindow(days: readonly string[], at: string, week: boolean): string[] {
+  const end = new Date(`${at}T00:00:00Z`);
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(at) || !Number.isFinite(end.getTime()) || end.toISOString().slice(0, 10) !== at) {
+    throw new Error('Дата должна быть существующим днём YYYY-MM-DD');
+  }
+  const start = new Date(end.getTime() - (week ? 6 : 0) * 86400000).toISOString().slice(0, 10);
+  return days.filter(day => day >= start && day <= at).sort();
+}
+
+/** The receipt is based on bytes read AFTER append, never on append returning normally. */
+export function appendWitnessed(io: JournalIo, path: string, line: string): void {
+  io.append(path, `${line}\n`);
+  try {
+    if (!io.read(path).endsWith(`${line}\n`)) throw new Error('хвост не совпадает');
+  } catch (error) {
+    throw new Error(`Запись не засвидетельствована: ${String(error)}`);
+  }
+}

package/src/loop-blobs.generated.ts

@@ -25,7 +25,7 @@ export interface LoopBlob {
   code: string;
 }
 
-export const LOOP_BLOB_NAMES = ["checkpoints","training-pairs","model-resolver","usage-probes","codex-dispatch","challenge-panel","stage-line","trace","loop-semantics","ha-consult-router"] as const;
+export const LOOP_BLOB_NAMES = ["run-registry","checkpoints","training-pairs","model-resolver","usage-probes","codex-dispatch","challenge-panel","stage-line","trace","loop-semantics","ha-consult-router"] as const;
 
 /** Workflow files the regen-diff gate covers TODAY (AM-5 honest scope): exactly the files
  * carrying BEGIN BLOB markers. Stage B (whole-file regeneration of feature-adr.js) is a
@@ -40,6 +40,15 @@ export const BLOB_COVERAGE_MANIFEST: { coveredWorkflows: string[] } = {
 };
 
 export const BLOBS: Record<string, LoopBlob> = {
+  "run-registry": {
+    name: "run-registry",
+    version: "1.0.0",
+    contentHash: "a4187c278260e8f8285fc494da2a6d82923efe4465fabba20ce1d3141df7fef3",
+    sourcePath: "packages/@dzhechkov/harness-core/src/run-registry.ts",
+    requires: [],
+    exports: ["runRecordCommand"],
+    code: "function runRecordCommand(dz, root, event, runId, slug, pid, parentRunId, outcome) {\n    const quote = (s) => \"'\" + s.replace(/'/g, \"'\\\\''\") + \"'\";\n    let cmd = dz + ' runs-record --project ' + quote(root) + ' --event ' + quote(event) + (runId ? ' --run-id ' + quote(runId) : '');\n    if (event === 'started') {\n        cmd += ' --kind feature-adr --slug ' + quote(slug);\n        cmd += ' --pid ' + quote(pid === null ? 'host' : String(pid));\n        if (parentRunId)\n            cmd += ' --parent-run-id ' + quote(parentRunId);\n    }\n    if (event === 'finished')\n        cmd += ' --outcome ' + quote(outcome);\n    return cmd + ' --json';\n}",
+  },
   "checkpoints": {
     name: "checkpoints",
     version: "1.2.0",

package/src/patterns.ts

@@ -642,6 +642,24 @@ export function loadStoreRecords(projectRoot: string): MemoryRecord[] {
   }
 }
 
+/** Find the earliest lesson whose normalized text and optional domain match exactly. */
+export function findExactLesson(
+  records: readonly MemoryRecord[],
+  text: string,
+  domain?: string,
+): { id: string; quarantined: boolean } | null {
+  const normalizedText = text.trim().replace(/\s+/g, ' ');
+  let earliest: MemoryRecord | undefined;
+  for (const record of records) {
+    if (record.text.trim().replace(/\s+/g, ' ') !== normalizedText) continue;
+    if (domain !== undefined && record.metadata?.['domain'] !== domain) continue;
+    if (earliest === undefined || record.timestamp < earliest.timestamp) earliest = record;
+  }
+  return earliest === undefined
+    ? null
+    : { id: earliest.id, quarantined: earliest.metadata?.['qStatus'] === 'quarantined' };
+}
+
 /** Write one record through the backend cascade. CALLER HOLDS THE STORE LOCK — every
  * caller (reinforce / updateReinforcementState / promote) wraps its whole read-modify-write
  * in `withStoreLock`; taking the (non-reentrant) lock here as well would deadlock. */

package/src/publish.ts

@@ -11,6 +11,9 @@ import { join as pathJoin, relative as pathRelative, resolve as pathResolve } fr
 import { decidePublishSigning, decidePostSigningVerification } from './publish-signing.js';
 import { join } from 'node:path';
 import { execSync } from 'node:child_process';
+// Structural twin of node's ExecSyncOptionsWithStringEncoding — a type-only import of node:child_process
+// still counts as an IO import for the core-boundary ratchet (measured 66 → 67), so the shape is spelled here.
+type ExecSyncOptionsWithStringEncoding = NonNullable<Parameters<typeof execSync>[1]> & { encoding: 'utf-8' };
 
 import { claimCheck } from './claim-check.js';
 
@@ -21,6 +24,8 @@ export interface PublishResult {
   readonly newVersion: string;
   readonly status: 'published' | 'skipped' | 'error';
   readonly error?: string | undefined;
+  /** Live publish only: how many registry probes were needed to confirm the exact new version. */
+  readonly registryProbes?: number | undefined;
   /**
    * Pre-publish claim-check summary for this package's README, present only when the
    * opt-in `claimCheck` gate ran (`'warn'`/`'block'`). Additive: absent by default so an
@@ -85,9 +90,11 @@ export function compareVersions(a: string, b: string): number {
  * 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).
  */
-function publishedVersion(name: string): string | undefined {
+type PublishExec = (command: string, options: ExecSyncOptionsWithStringEncoding) => string;
+
+function publishedVersion(name: string, exec: PublishExec = execSync): string | undefined {
   try {
-    const out = execSync(`npm view ${name} version`, { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf-8', timeout: 20000 }).trim();
+    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
@@ -95,8 +102,8 @@ function publishedVersion(name: string): string | undefined {
 }
 
 /** The higher of the local version and the npm-published version (audit #10). */
-function maxPublished(name: string, localVersion: string): string {
-  const pub = publishedVersion(name);
+function maxPublished(name: string, localVersion: string, exec: PublishExec = execSync): string {
+  const pub = publishedVersion(name, exec);
   return pub !== undefined && compareVersions(pub, localVersion) > 0 ? pub : localVersion;
 }
 
@@ -153,9 +160,9 @@ export function findUnpublishedWorkspaceFloors(opts: {
 }
 
 /** Registry probe: is exactly `name@version` published? Empty output / 404 / offline ⇒ no. */
-function versionPublished(name: string, version: string): boolean {
+function versionPublished(name: string, version: string, exec: PublishExec = execSync): boolean {
   try {
-    const out = execSync(`npm view ${name}@${version} version`, { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf-8', timeout: 20000 }).trim();
+    const out = exec(`npm view ${name}@${version} version --prefer-online`, { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf-8', timeout: 20000 }).trim();
     return out === version;
   } catch {
     return false;
@@ -541,11 +548,22 @@ export function publishPackages(
      * preflight under dry-run, which is how the wiring test drives it without network.
      */
     probeFloor?: ((name: string, version: string) => boolean) | undefined;
+    /** Subprocess injection for tests; the default is Node's synchronous executor. */
+    exec?: PublishExec | undefined;
+    /** Post-publish receipt probe. The default asks npm for exactly `name@version`. */
+    probe?: ((name: string, version: string) => boolean) | undefined;
+    /** Pause injection between receipt probes. The default blocks for the requested milliseconds. */
+    sleep?: ((milliseconds: number) => void) | undefined;
   } = {},
 ): PublishReport {
   // Decide ONCE, before the batch: `--provenance` in an incapable environment must fail here, not on
   // package 7 of 45 (recalled lesson: a failed publish that retries with a bump orphans version numbers).
   const publishCmd = publishArgv(opts.provenance ?? 'auto', process.env);
+  const exec = opts.exec ?? execSync;
+  const probe = opts.probe ?? ((name: string, version: string) => versionPublished(name, version, exec));
+  const sleep = opts.sleep ?? ((milliseconds: number): void => {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
+  });
 
   const packages = discoverPackages(monorepoRoot);
   const results: PublishResult[] = [];
@@ -570,7 +588,7 @@ export function publishPackages(
     // 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);
+    const base = opts.dryRun ? oldVersion : maxPublished(pkg.name, oldVersion, exec);
     const newVersion = bumpPatch(base);
 
     // Preflight: refuse to publish a pack whose `files` whitelist would silently
@@ -678,7 +696,9 @@ export function publishPackages(
       // Build if has build script
       const parsed = JSON.parse(readFileSync(pkgJsonPath, 'utf-8')) as { scripts?: Record<string, string> };
       if (parsed.scripts?.['build']) {
-        execSync('pnpm build', { cwd: pkg.dir, stdio: 'pipe', encoding: 'utf-8' });
+        const buildOptions = { cwd: pkg.dir, stdio: 'pipe' as const, encoding: 'utf-8' as const };
+        if (opts.exec) opts.exec('pnpm build', buildOptions);
+        else execSync('pnpm build', buildOptions);
       }
 
       // Re-sign AFTER the bump, the README sync and the build, and BEFORE the tarball is built.
@@ -755,14 +775,30 @@ export function publishPackages(
       }
 
       // Publish
-      execSync(publishCmd, {
+      const publishOptions = {
         cwd: pkg.dir,
-        stdio: 'pipe',
-        encoding: 'utf-8',
+        stdio: 'pipe' as const,
+        encoding: 'utf-8' as const,
         env: { ...process.env },
-      });
+      };
+      if (opts.exec) opts.exec(publishCmd, publishOptions);
+      else execSync(publishCmd, publishOptions);
+
+      let registryProbes = 0;
+      let confirmed = false;
+      while (registryProbes < 30) {
+        registryProbes++;
+        if (probe(pkg.name, newVersion)) {
+          confirmed = true;
+          break;
+        }
+        if (registryProbes < 30) sleep(10_000);
+      }
+      if (!confirmed) {
+        throw new Error(`registry did not confirm ${pkg.name}@${newVersion} after ${registryProbes} probes`);
+      }
 
-      results.push({ name: pkg.name, oldVersion, newVersion, status: 'published', claimCheck: claimCheckSummary });
+      results.push({ name: pkg.name, oldVersion, newVersion, status: 'published', registryProbes, claimCheck: claimCheckSummary });
       landedInBatch.add(pkg.name); // only an ACTUAL publish covers dependents (Codex P1)
     } catch (err) {
       // The version was written BEFORE build+publish; on any failure restore the

package/src/run-cleanup.ts

@@ -0,0 +1,38 @@
+/** Pure cleanup decisions: the CLI gathers facts and executes the explicit apply selection. */
+export type WorktreeFact = {
+  path: string; branch: string | null; detached: boolean; isMain: boolean;
+  merged: boolean | null; dirtyFiles: string[]; lastCommitTs: number | null;
+};
+export type WorktreeCleanupPlan = {
+  now: number;
+  remove: WorktreeFact[];
+  keep: { fact: WorktreeFact; reason: 'main' | 'unmerged' | `dirty (${number})` | 'younger than retention' | 'merged-unknown' }[];
+};
+
+export function planWorktreeCleanup(facts: WorktreeFact[], opts: { now: number; retentionMs: number }): WorktreeCleanupPlan {
+  const plan: WorktreeCleanupPlan = { now: opts.now, remove: [], keep: [] };
+  for (const fact of facts) {
+    let reason: WorktreeCleanupPlan['keep'][number]['reason'] | undefined;
+    if (fact.isMain) reason = 'main';
+    else if (fact.dirtyFiles.length > 0) reason = `dirty (${fact.dirtyFiles.length})`;
+    else if (fact.merged === null) reason = 'merged-unknown';
+    else if (!fact.merged) reason = 'unmerged';
+    else if (fact.lastCommitTs === null || !(opts.now - fact.lastCommitTs > opts.retentionMs)) reason = 'younger than retention';
+    if (reason) plan.keep.push({ fact, reason });
+    else plan.remove.push(fact);
+  }
+  return plan;
+}
+
+/** The apply boundary is independently mutable while all filesystem work stays in the CLI. */
+export function worktreeRemovalsToApply(plan: WorktreeCleanupPlan, apply: boolean): WorktreeFact[] {
+  return apply ? plan.remove : [];
+}
+
+export function renderCleanupPlan(plan: WorktreeCleanupPlan): string[] {
+  return [
+    ...plan.remove.map(fact => `remove ${fact.path} (${fact.branch ?? 'detached'}, ${Math.floor((plan.now - fact.lastCommitTs!) / 86400000)}d)`),
+    ...plan.keep.map(({ fact, reason }) => `keep ${fact.path} — ${reason}` +
+      (reason.startsWith('dirty (') ? ': ' + fact.dirtyFiles.slice(0, 5).join(', ') + (fact.dirtyFiles.length > 5 ? ' …' : '') : '')),
+  ];
+}