@dzhechkov/harness-core 0.8.40 → 0.8.41

package/src/pack-inventory.ts

@@ -0,0 +1,313 @@
+import { execSync } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import { closeSync, existsSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { scanSecretsChunked } from './guard.js';
+import { NamedLockTimeoutError, withDirLockSync } from './named-lock.js';
+import { listPackFiles, listSignablePackFiles } from './sign.js';
+
+export type PackerId = 'npm' | 'pnpm';
+export type InventorySource = 'tarball' | 'npm-dry-run' | 'cache' | 'fallback-walk';
+export type PackExec = (cmd: string, opts: { readonly cwd: string; readonly timeoutMs: number }) => {
+  readonly stdout: string;
+  readonly stderr: string;
+};
+export type ChunkReader = (absolutePath: string, chunkBytes: number) => Iterable<Buffer>;
+
+export interface ListPublishInventoryOptions {
+  readonly packer?: PackerId;
+  readonly tgzPath?: string;
+  readonly exec?: PackExec;
+  readonly cacheDir?: string;
+  readonly timeoutMs?: number;
+}
+
+export interface PublishInventory {
+  readonly files: readonly string[];
+  readonly source: InventorySource;
+  readonly reason?: string;
+  readonly packer: PackerId;
+  readonly packerVersion: string | null;
+}
+
+export interface PublishSecretSeams {
+  readonly listInventory?: typeof listPublishInventory;
+  readonly reader?: ChunkReader;
+  readonly tgzPathFor?: (dir: string) => string | undefined;
+}
+
+/** Scan the publish inventory as streams, retaining every coverage gap by name. */
+export function gatherPublishSecretFacts(root: string, packageDirs: readonly string[], seams: PublishSecretSeams = {}):
+  { readonly secretFindings: readonly { label: string; name: string }[];
+    readonly secretScan: { skipped: number; skippedPaths: string[]; scanned: number; inventory: string } } {
+  const listInventory = seams.listInventory ?? listPublishInventory;
+  const reader = seams.reader ?? readFileChunks;
+  const secretFindings: { label: string; name: string }[] = [];
+  const skippedPaths: string[] = [];
+  let scanned = 0;
+  const counts: Record<InventorySource, number> = { tarball: 0, cache: 0, 'npm-dry-run': 0, 'fallback-walk': 0 };
+  const fallbacks: string[] = [];
+  const skip = (label: string, reason: string): void => { skippedPaths.push(`${label} (${reason})`); };
+
+  for (const dir of packageDirs) {
+    const packageRoot = join(root, dir);
+    let inventory: PublishInventory;
+    try {
+      // Lead edit (tsc exactOptionalPropertyTypes): an absent tgzPath must be ABSENT, not `undefined`.
+      const tgz = seams.tgzPathFor?.(dir);
+      inventory = listInventory(packageRoot, {
+        cacheDir: join(root, '.dz', 'cache'),
+        ...(tgz !== undefined ? { tgzPath: tgz } : {}),
+      });
+    } catch { skip(dir, 'inventory unreadable'); continue; }
+    counts[inventory.source]++;
+    if (inventory.source === 'fallback-walk') fallbacks.push(`${dir} (${inventory.reason ?? 'unknown reason'})`);
+
+    for (const rel of inventory.files) {
+      const absolute = join(packageRoot, rel);
+      const label = relative(root, absolute).split(sep).join('/');
+      try {
+        if (!lstatSync(absolute).isFile()) { skip(label, 'not a regular file'); continue; }
+        let binary = false;
+        let unreadable = false;
+        function* textChunks(): Iterable<Buffer> {
+          let first = true;
+          try {
+            for (const chunk of reader(absolute, 1024 * 1024)) {
+              if (first && chunk.subarray(0, 8 * 1024).includes(0)) { binary = true; return; }
+              first = false;
+              yield chunk;
+            }
+          } catch {
+            // End the iterable normally so the scanner can return hits already found.
+            unreadable = true;
+            skip(label, first ? 'unreadable' : 'unreadable (partial)');
+          }
+        }
+        const findings = scanSecretsChunked(textChunks());
+        if (binary) { skip(label, 'binary'); continue; }
+        for (const { name } of findings) secretFindings.push({ label, name });
+        if (!unreadable) scanned++;
+      } catch { skip(label, 'unreadable'); }
+    }
+  }
+
+  const sources: InventorySource[] = ['tarball', 'cache', 'npm-dry-run', 'fallback-walk'];
+  const summary = sources.filter((source) => counts[source] > 0).map((source) => `${source}×${counts[source]}`).join(', ');
+  return { secretFindings, secretScan: {
+    skipped: skippedPaths.length, skippedPaths, scanned,
+    inventory: summary + (fallbacks.length > 0 ? `: ${fallbacks.join(', ')}` : ''),
+  } };
+}
+
+/** Reject malformed or empty listings so they cannot suppress scanning. */
+export function parseNpmPackListing(stdout: string): readonly string[] | null {
+  let listing: unknown;
+  try {
+    listing = JSON.parse(stdout);
+  } catch {
+    return null;
+  }
+  if (!Array.isArray(listing) || listing.length === 0) return null;
+  const paths = new Set<string>();
+  for (const entry of listing) {
+    if (entry === null || typeof entry !== 'object' || !Array.isArray(entry.files) || entry.files.length === 0) {
+      return null;
+    }
+    for (const file of entry.files) {
+      if (file === null || typeof file !== 'object' || typeof file.path !== 'string' || file.path.length === 0) {
+        return null;
+      }
+      paths.add(file.path);
+    }
+  }
+  return [...paths].sort();
+}
+
+/** Versioned key over packer identity, package metadata bytes, and the signable file walk. */
+export function computeInventoryCacheKey(packageRoot: string, packer: PackerId, packerVersion: string): string {
+  const hash = createHash('sha256');
+  hash.update(`pack-inventory/1\n${packer}@${packerVersion}\n`);
+  hash.update(readFileSync(join(packageRoot, 'package.json')));
+  hash.update('\n');
+  try {
+    hash.update(readFileSync(join(packageRoot, '.npmignore')));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+    hash.update('<absent>');
+  }
+  hash.update('\n');
+  for (const relpath of listSignablePackFiles(packageRoot).sort()) {
+    const { size, mtimeMs } = statSync(join(packageRoot, relpath));
+    hash.update(`${relpath}\0${size}\0${mtimeMs}\n`);
+  }
+  return hash.digest('hex');
+}
+
+/** Reuse the read buffer, yielding copies that remain valid after subsequent reads. */
+export function* readFileChunks(absolutePath: string, chunkBytes = 1024 * 1024): Iterable<Buffer> {
+  if (!Number.isSafeInteger(chunkBytes) || chunkBytes <= 0) {
+    throw new RangeError('chunkBytes must be a positive safe integer');
+  }
+  const buffer = Buffer.allocUnsafe(chunkBytes);
+  const fd = openSync(absolutePath, 'r');
+  try {
+    let bytesRead: number;
+    while ((bytesRead = readSync(fd, buffer, 0, buffer.length, null)) > 0) {
+      yield Buffer.from(buffer.subarray(0, bytesRead));
+    }
+  } finally {
+    closeSync(fd);
+  }
+}
+
+const defaultExec: PackExec = (cmd, { cwd, timeoutMs }) => ({
+  stdout: execSync(cmd, { cwd, timeout: timeoutMs, encoding: 'utf8', stdio: 'pipe' }),
+  stderr: '',
+});
+
+// Scope memoization to the executor as well as the packer so injected runtimes stay independent.
+const versions = new WeakMap<PackExec, Map<PackerId, string | null>>();
+
+function packerVersion(exec: PackExec, packer: PackerId, cwd: string, timeoutMs: number): string | null {
+  let memo = versions.get(exec);
+  if (!memo) { memo = new Map(); versions.set(exec, memo); }
+  if (memo.has(packer)) return memo.get(packer)!;
+  let version: string | null = null;
+  try {
+    const started = Date.now();
+    const stdout = exec(`${packer} --version`, { cwd, timeoutMs }).stdout.trim();
+    if (Date.now() - started <= timeoutMs && stdout.length > 0) version = stdout;
+  } catch { /* Unknown versions must never serve or populate the cache. */ }
+  memo.set(packer, version);
+  return version;
+}
+
+function repositoryRoot(packageRoot: string): string {
+  for (let dir = packageRoot; ; dir = dirname(dir)) {
+    if (existsSync(join(dir, 'pnpm-workspace.yaml')) || existsSync(join(dir, '.git', 'HEAD'))) return dir;
+    if (dirname(dir) === dir) return packageRoot; // standalone package
+  }
+}
+
+interface CacheEntry {
+  readonly key: string;
+  readonly files: readonly string[];
+  readonly packer: PackerId;
+  readonly packerVersion: string;
+  readonly writtenAt: string;
+}
+interface InventoryCache { schema: 1; entries: Record<string, CacheEntry> }
+
+function readCache(path: string): InventoryCache {
+  try {
+    const cache = JSON.parse(readFileSync(path, 'utf8')) as InventoryCache;
+    if (cache?.schema === 1 && cache.entries && typeof cache.entries === 'object' && !Array.isArray(cache.entries)) {
+      return cache;
+    }
+  } catch { /* Missing or unparsable cache is a miss. */ }
+  return { schema: 1, entries: {} };
+}
+
+/** Listings must stay relative to the package and cannot represent an empty successful scan. */
+function inventoryPaths(paths: readonly string[]): string[] | null {
+  const out = new Set<string>();
+  for (const path of paths) {
+    if (typeof path !== 'string') return null;
+    const normalized = path.replace(/\\/g, '/').replace(/^\.\//, '');
+    if (!normalized || normalized.startsWith('/') || /^[A-Za-z]:/.test(normalized)
+      || normalized.split('/').some((part) => part === '..' || part === '' || part === '.')) return null;
+    out.add(normalized);
+  }
+  return out.size > 0 ? [...out].sort() : null;
+}
+
+function firstErrorLine(error: unknown): string {
+  const stderr = (error as { stderr?: unknown } | null)?.stderr;
+  const text = typeof stderr === 'string' || Buffer.isBuffer(stderr) ? stderr.toString().trim() : '';
+  return (text || (error instanceof Error ? error.message : String(error))).split(/\r?\n/)[0]!;
+}
+
+/** Prefer the supplied artifact, then a tree/version cache, then stdout from the packer. */
+export function listPublishInventory(packageRoot: string, opts: ListPublishInventoryOptions = {}): PublishInventory {
+  packageRoot = resolve(packageRoot);
+  const packer = opts.packer ?? 'npm';
+  const exec = opts.exec ?? defaultExec;
+  const timeoutMs = opts.timeoutMs ?? 15_000;
+  let version: string | null = null;
+  const fallback = (reason: string): PublishInventory => {
+    const files = listPackFiles(packageRoot);
+    if (files.length === 0) throw new Error('inventory unreadable');
+    return { files, source: 'fallback-walk', reason, packer, packerVersion: version };
+  };
+
+  if (opts.tgzPath !== undefined) {
+    try {
+      const path = resolve(packageRoot, opts.tgzPath).replace(/'/g, "'\\''");
+      const stdout = exec(`tar -tzf '${path}'`, { cwd: packageRoot, timeoutMs }).stdout;
+      const entries = stdout.split(/\r?\n/).filter((entry) => entry.length > 0 && !entry.endsWith('/'));
+      if (entries.some((entry) => !entry.startsWith('package/'))) throw new Error('unparsable listing');
+      const files = inventoryPaths(entries.map((entry) => entry.slice('package/'.length)));
+      if (!files) throw new Error('unparsable listing');
+      return { files, source: 'tarball', packer, packerVersion: null };
+    } catch (error) {
+      return fallback(`tarball unreadable: ${firstErrorLine(error)}`);
+    }
+  }
+
+  version = packerVersion(exec, packer, packageRoot, timeoutMs);
+  const root = opts.cacheDir !== undefined ? dirname(dirname(resolve(opts.cacheDir))) : repositoryRoot(packageRoot);
+  const cacheDir = opts.cacheDir ?? join(root, '.dz', 'cache');
+  const cachePath = join(cacheDir, 'pack-inventory.json');
+  const packageDir = relative(root, packageRoot).split(sep).join('/') || '.';
+  let key: string | undefined;
+  if (version !== null) {
+    try { key = computeInventoryCacheKey(packageRoot, packer, version); }
+    catch { /* A tree that cannot be keyed must still be listed/scanned. */ }
+  }
+  if (key !== undefined) {
+    try {
+      const cached = withDirLockSync(dirname(cacheDir), 'pack-inventory', () => readCache(cachePath).entries[packageDir]);
+      const files = cached && Array.isArray(cached.files) ? inventoryPaths(cached.files) : null;
+      if (cached?.key === key && cached.packer === packer && cached.packerVersion === version && files) {
+        return { files, source: 'cache', packer, packerVersion: version };
+      }
+    } catch (error) {
+      if (!(error instanceof NamedLockTimeoutError)) throw error;
+      key = undefined; // A lock timeout is a miss, with no later write in this call.
+    }
+  }
+
+  let stdout: string;
+  const started = Date.now();
+  try {
+    stdout = exec(`${packer} pack --dry-run --json`, { cwd: packageRoot, timeoutMs }).stdout;
+  } catch (error) {
+    const timedOut = (error as NodeJS.ErrnoException | null)?.code === 'ETIMEDOUT' || Date.now() - started > timeoutMs;
+    return fallback(timedOut ? `packer timeout ${timeoutMs} ms` : `packer failed: ${firstErrorLine(error)}`);
+  }
+  if (Date.now() - started > timeoutMs) return fallback(`packer timeout ${timeoutMs} ms`);
+  const parsed = parseNpmPackListing(stdout);
+  const files = parsed && inventoryPaths(parsed);
+  if (!files) return fallback('unparsable listing');
+
+  if (key !== undefined && version !== null) {
+    const entry: CacheEntry = { key, files, packer, packerVersion: version, writtenAt: new Date().toISOString() };
+    try {
+      withDirLockSync(dirname(cacheDir), 'pack-inventory', () => {
+        // Re-read INSIDE the write transaction, preserving entries another package just added.
+        const cache = readCache(cachePath);
+        cache.entries[packageDir] = entry;
+        mkdirSync(cacheDir, { recursive: true });
+        const temp = `${cachePath}.${randomUUID()}.tmp`;
+        try {
+          writeFileSync(temp, JSON.stringify(cache));
+          renameSync(temp, cachePath);
+        } finally { rmSync(temp, { force: true }); }
+      });
+    } catch (error) {
+      if (!(error instanceof NamedLockTimeoutError)) throw error;
+    }
+  }
+  return { files, source: 'npm-dry-run', packer, packerVersion: version };
+}

package/src/package-skill-layouts.ts

@@ -1,7 +1,7 @@
 /**
  * Package skill-layout resolution — where an installed npm package keeps its skills.
  *
- * `dz install <pkg>` (and, later, `dz init`/`dz registry` — see the backlog note below)
+ * `dz install <pkg>` and `dz registry`
  * must find `SKILL.md` skill dirs inside an npm package. Packages in the wild ship three
  * on-disk arrangements; before this module existed, `cmdInstall` hard-coded exactly one
  * (`flat`), so every npx-init pack (`templates/.claude/skills/…`) and bare-`skills/`
@@ -51,7 +51,8 @@ export interface PackageSkillRoot {
 }
 
 /**
- * Ordered layout probe list. ORDER IS THE CONTRACT — first non-empty wins.
+ * Shared ordered layout probe list. The resolver selects the first non-empty root;
+ * the registry collects all roots, with the first occurrence of each skill id winning.
  *
  * `flat` is probed first so a classic pack can never be re-interpreted; `npx-template`
  * before `skills-dir` matches the measured census (13 vs 2 packages). Extending support

package/src/patterns.ts

@@ -49,6 +49,14 @@ export interface PatternRecord {
   readonly type: 'rule' | 'success-pattern' | 'lesson-learned';
   /** Reward signal in [0, 1]. */
   readonly reward: number;
+  /**
+   * Whether the reward was explicit or defaulted: measured rewards had only 7 distinct
+   * values, a median of 0.8, and covered 5.5% of impressions (338 / 6140).
+   * This field does NOT change the default reward value; absent means unknown for legacy records.
+   * Set at record creation and unchanged by subsequent reinforce/guard-reinforce calls,
+   * even with an explicit --reward, it describes the first invocation, not the latest.
+   */
+  readonly rewardSource?: 'explicit' | 'default';
   /** Domain tag (e.g. "performance", "api", "general"). */
   readonly domain: string;
   /** ISO-8601 timestamp the record was written. */
@@ -510,12 +518,16 @@ export function patternToRecord(p: PatternRecord): MemoryRecord {
     // the learn-loop write path.
     outcome: PATTERN_TYPES.has(p.type) ? p.type : 'lesson-learned',
     timestamp: p.ts,
-    metadata: { domain: p.domain ?? 'general', source: p.source ?? 'dz-teach', ...pairMetadata },
+    metadata: {
+      domain: p.domain ?? 'general', source: p.source ?? 'dz-teach', ...pairMetadata,
+      ...(p.rewardSource !== undefined ? { rewardSource: p.rewardSource } : {}),
+    },
   };
 }
 
 /** Anti-corruption mapping: canonical `MemoryRecord` → harness `PatternRecord`. */
 export function recordToPattern(r: MemoryRecord): PatternRecord {
+  const rewardSource = r.metadata?.['rewardSource'];
   const lessonForm = r.metadata?.['lessonForm'];
   const lessonPairId = r.metadata?.['lessonPairId'];
   const pair: { lessonForm?: LessonForm; lessonPairId?: string } = (lessonForm === 'specific' || lessonForm === 'class')
@@ -535,6 +547,7 @@ export function recordToPattern(r: MemoryRecord): PatternRecord {
     pattern: r.text,
     type: PATTERN_TYPES.has(r.outcome) ? (r.outcome as PatternRecord['type']) : 'lesson-learned',
     reward: r.score,
+    ...(rewardSource === 'explicit' || rewardSource === 'default' ? { rewardSource } : {}),
     domain: r.metadata?.['domain'] ?? 'general',
     ts: r.timestamp,
     source: r.metadata?.['source'] ?? 'dz-teach',
@@ -1130,6 +1143,10 @@ function migrationRecords(projectRoot: string): MemoryRecord[] {
  * JSON file is never deleted. Returns the total record count after the write.
  */
 export async function recordPattern(projectRoot: string, p: PatternRecord, opts: { quarantine?: boolean } = {}): Promise<number> {
+  // The WRITER creates the store, not the lock (lock-never-seeds-store, ADR-001 item 6). Guarded by
+  // existsSync so a fixture that plants a FILE at .dz/memory still reaches the real open error
+  // below instead of EEXIST here (patterns.test.ts, forced-sqlite cause).
+  if (!existsSync(join(projectRoot, '.dz', 'memory'))) mkdirSync(join(projectRoot, '.dz', 'memory'), { recursive: true });
   if (p.lessonForm === 'class') ensureClassFormMarker(projectRoot);
   const { sqliteBackend } = readLearningConfig(projectRoot);
   // lesson-quarantine: a fresh lesson is a HYPOTHESIS — mark it when the feature is on. Folded

package/src/publish.ts

@@ -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;
@@ -176,26 +193,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 +874,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 +907,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 +954,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 +1065,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 +1182,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 из исходников',
@@ -1492,7 +1561,17 @@ export function publishPackages(
   }
 
   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,

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 })) {