@orkestrel/scaffold 0.0.103 → 0.0.104

package/dist/agents/skills/orkestrel-publish/scripts/wave.js

@@ -1,8 +1,9 @@
 import { spawnSync } from 'node:child_process';
-import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'node:fs';
-import { basename, dirname, extname, join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { copyFileSync, existsSync, lstatSync, readFileSync, mkdirSync, realpathSync, renameSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { parseJsonRecord, readJsonObject, readMissingFlags, readOption, readString, runNpm, } from "../../orkestrel-dispatch/scripts/helpers.js";
+import { parseJsonRecord, isRecord, normalizeSlashes, removeTree, scanLocalSpecs, readJsonObject, readMissingFlags, readOption, readString, runNpm, } from "../../orkestrel-dispatch/scripts/helpers.js";
 const STEPS = [
     'pin',
     'commit',
@@ -11,6 +12,7 @@ const STEPS = [
     'install',
     'pins',
     'format',
+    'record',
     'gates',
     'compare',
 ];
@@ -102,8 +104,8 @@ function describeFailure(result) {
     if (note !== undefined)
         return note;
     return result.stderr
-        .trim()
         .split(/\r\n|\n/)
+        .filter((line) => line.trim() !== '')
         .slice(-3)
         .join(' | ');
 }
@@ -112,7 +114,7 @@ function readVerdict(result) {
 }
 // A judge reads the finished command and answers the exit and note its one log entry carries, so no
 // entry is amended after it is appended.
-function runStep(runner, step, file, args, cwd, judge = readVerdict) {
+function runStep(runner, step, file, args, cwd, judge = readVerdict, input) {
     const command = describeCommand(file, args);
     if (runner.dry) {
         runner.steps.push({ step, command, exit: undefined, durationMs: 0, note: 'dry run' });
@@ -124,10 +126,11 @@ function runStep(runner, step, file, args, cwd, judge = readVerdict) {
         encoding: 'utf8',
         windowsHide: true,
         maxBuffer: 64 * 1024 * 1024,
+        ...(input === undefined ? {} : { input }),
     });
     const durationMs = Date.now() - started;
     const verdict = judge(result);
-    runner.steps.push({ step, command, exit: verdict.exit, durationMs, note: verdict.note });
+    appendResult(runner, step, command, result, durationMs, verdict);
     return result;
 }
 // The audit exits 1 on the drift the pin step exists to close, so its exit is a reading here.
@@ -161,34 +164,361 @@ function judgeVerify(result, own) {
         ? { exit: 0, note: 'foreign-path findings are expected on the scaffold checkout' }
         : readVerdict(result);
 }
-function runNpmStep(runner, step, args) {
+function runNpmStep(runner, step, args, judge = readVerdict) {
     const command = `npm ${args.join(' ')}`;
     if (runner.dry) {
-        runner.steps.push({ step, command, exit: undefined, durationMs: 0, note: 'dry run' });
+        runner.steps.push({
+            step,
+            command,
+            exit: undefined,
+            durationMs: 0,
+            note: runner.regenerate && args[0] === 'install'
+                ? 'dry run (regenerates on ERESOLVE)'
+                : 'dry run',
+        });
         return undefined;
     }
     const started = Date.now();
     const result = runNpm(args, runner.target);
+    appendResult(runner, step, command, result, Date.now() - started, judge(result));
+    return result;
+}
+function writeJournal(runner, step, command, exit, stdout, stderr) {
+    if (runner.directory === undefined)
+        return {};
+    const path = join(runner.directory, `${String(runner.steps.length + 1).padStart(2, '0')}-${step}.log`);
+    try {
+        validateWavePath(runner.target, path);
+        mkdirSync(runner.directory, { recursive: true });
+        validateWavePath(runner.target, path);
+        writeFileSync(path, `command: ${command}\nexit: ${String(exit)}\nstdout:\n${stdout}\nstderr:\n${stderr}\n`);
+        return { path };
+    }
+    catch (error) {
+        return { failure: `journal failed: ${path}: ${String(error)}` };
+    }
+}
+function appendResult(runner, step, command, result, durationMs, verdict) {
+    const journal = writeJournal(runner, step, command, result.status ?? undefined, result.stdout ?? '', result.stderr ?? '');
     runner.steps.push({
         step,
         command,
-        exit: result.status ?? undefined,
-        durationMs: Date.now() - started,
-        note: describeFailure(result),
+        durationMs,
+        ...(journal.path === undefined ? {} : { journal: journal.path }),
+        ...(journal.failure === undefined
+            ? verdict
+            : {
+                exit: 1,
+                note: [verdict.note, journal.failure].filter((value) => value !== undefined).join('; '),
+            }),
     });
-    return result;
 }
-function recordStep(runner, step, command, note) {
-    runner.steps.push({ step, command, exit: runner.dry ? undefined : 0, durationMs: 0, note });
+function appendStep(runner, step, command, note, exit = 0) {
+    const journal = runner.dry ? {} : writeJournal(runner, step, command, exit, note, '');
+    runner.steps.push({
+        step,
+        command,
+        exit: runner.dry ? undefined : journal.failure === undefined ? exit : 1,
+        durationMs: 0,
+        note: journal.failure === undefined ? note : `${note}; ${journal.failure}`,
+        ...(journal.path === undefined ? {} : { journal: journal.path }),
+    });
 }
 function failed(runner) {
-    return runner.steps.some((entry) => entry.exit !== undefined &&
+    return runner.steps.some((entry) => entry.superseded !== true &&
+        entry.exit !== undefined &&
         entry.exit !== 0 &&
         entry.step !== 'pins' &&
         entry.step !== 'compare');
 }
-// A release moves a declared range to its registry caret when the range differs, and a later release
-// of the same name reads the range the earlier one wrote.
+function extractConflict(result) {
+    const output = `${result.stdout}\n${result.stderr}`;
+    if (!/\bcode ERESOLVE\b/u.test(output))
+        return undefined;
+    const lines = output.split(/\r\n|\n/);
+    return ((lines.find((line) => line.includes('Conflicting peer dependency:')) ??
+        lines.find((line) => line.includes('Could not resolve dependency:')))?.replace(/^npm (?:error|ERR!)\s*/u, '') ?? 'the install could not move a locked peer');
+}
+function runInstall(runner, step) {
+    // npm can unlink a node_modules junction before reporting its resolution failure.
+    if (!runner.dry &&
+        runner.regenerate &&
+        existsSync(join(runner.target, 'node_modules')) &&
+        lstatSync(join(runner.target, 'node_modules')).isSymbolicLink()) {
+        appendStep(runner, step, 'regenerate lock and modules', 'ERESOLVE; regeneration refused: node_modules is a link', 1);
+        return;
+    }
+    const installed = runNpmStep(runner, step, ['install'], (result) => {
+        const conflict = extractConflict(result);
+        return conflict === undefined || result.status === 0
+            ? readVerdict(result)
+            : {
+                exit: result.status ?? 1,
+                note: `ERESOLVE (${conflict}): pass --regenerate and resume with --from ${step} to replace package-lock.json and node_modules from the manifest`,
+                ...(runner.regenerate ? { superseded: true } : {}),
+            };
+    });
+    if (installed !== undefined &&
+        installed.status !== 0 &&
+        extractConflict(installed) !== undefined &&
+        runner.regenerate)
+        regenerateLock(runner, step, installed);
+}
+function refuseLocalSpecs(runner, step) {
+    const specs = scanLocalSpecs(readManifest(runner.target) ?? {});
+    if (specs.length === 0)
+        return false;
+    appendStep(runner, step, 'scan manifest specs', `local dependency specs: ${specs.map(([path, spec]) => `${path}: ${spec}`).join(', ')}; restore the pins first`, 1);
+    return true;
+}
+function readRegenerationRefusal(runner) {
+    if (runStep(runner, 'regenerate', 'git', ['ls-files', '--error-unmatch', 'package-lock.json'], runner.target)?.status !== 0)
+        return 'package-lock.json is untracked';
+    const status = runStep(runner, 'regenerate', 'git', ['status', '--porcelain', '--', 'package-lock.json'], runner.target);
+    if (status?.status !== 0 || status.stdout.trim() !== '')
+        return 'package-lock.json carries uncommitted changes';
+    const manifest = readManifest(runner.target);
+    const specs = scanLocalSpecs(manifest ?? {});
+    if (specs.length > 0)
+        return `local dependency specs: ${specs.map(([path, spec]) => `${path}: ${spec}`).join(', ')}`;
+    if (manifest !== undefined && 'workspaces' in manifest)
+        return 'the manifest declares workspaces';
+    if (runStep(runner, 'regenerate', 'git', ['check-ignore', '-q', 'tmp/units/wave/probe'], runner.target)?.status !== 0)
+        return 'tmp/ is not git-ignored';
+    const root = runStep(runner, 'regenerate', 'git', ['rev-parse', '--show-toplevel'], runner.target);
+    if (root?.status !== 0 ||
+        normalizeSlashes(resolve(root.stdout.trim())) !== normalizeSlashes(resolve(runner.target)))
+        return 'the target is not the root of its work tree';
+    return undefined;
+}
+function moveModules(source, target, attempt = 0) {
+    try {
+        renameSync(source, target);
+    }
+    catch (error) {
+        if (!isRecord(error) || (error.code !== 'EBUSY' && error.code !== 'EPERM') || attempt >= 9)
+            throw error;
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 100);
+        moveModules(source, target, attempt + 1);
+    }
+}
+function regenerateLock(runner, step, conflict) {
+    const refusal = readRegenerationRefusal(runner);
+    if (refusal !== undefined || runner.directory === undefined) {
+        appendStep(runner, step, 'regenerate lock and modules', `ERESOLVE; regeneration refused: ${refusal ?? 'tmp/ is not git-ignored'}`, 1);
+        return;
+    }
+    const lock = join(runner.target, 'package-lock.json');
+    const modules = join(runner.target, 'node_modules');
+    const backup = join(runner.directory, 'package-lock.before.json');
+    const moved = join(runner.directory, 'node_modules.before');
+    const manifest = readFileSync(join(runner.target, 'package.json'));
+    const before = createHash('sha256').update(readFileSync(lock)).digest('hex');
+    try {
+        for (const path of [backup, moved, lock, modules])
+            validateWavePath(runner.target, path);
+        mkdirSync(runner.directory, { recursive: true });
+        for (const path of [backup, moved, lock, modules])
+            validateWavePath(runner.target, path);
+        copyFileSync(lock, backup);
+        moveModules(modules, moved);
+    }
+    catch (error) {
+        appendStep(runner, step, 'regenerate lock and modules', `ERESOLVE; regeneration refused: ${isRecord(error) ? String(error.code) : ''} in use; stop the processes that hold it; ${String(error)}`, 1);
+        return;
+    }
+    const result = regenerateTree(runner.target, manifest, before);
+    const restored = result.exit === 0 ? undefined : restoreLock(runner.target, moved, backup, before);
+    const cleanup = result.exit === 0 ? discardBackup(runner.target, moved, backup) : undefined;
+    const names = [
+        ...new Set([
+            ...`${conflict.stdout}\n${conflict.stderr}`.matchAll(/(?:node_modules\/)((?:@[^/\s]+\/)?[^/\s]+)/gu),
+        ].flatMap((match) => (match[1] === undefined ? [] : [match[1]]))),
+    ];
+    const versions = result.exit === 0
+        ? names
+            .map((name) => `${name}@${readString(readManifest(join(modules, name)), 'version') ?? 'absent'}`)
+            .join(', ')
+        : undefined;
+    appendStep(runner, step, 'regenerate lock and modules', [result.note, restored, versions === undefined ? undefined : `installed ${versions}`, cleanup]
+        .filter((value) => value !== undefined)
+        .join('; '), cleanup === undefined ? result.exit : 1);
+    if (result.installed !== undefined)
+        appendResult(runner, step, 'npm install (regenerated)', result.installed, result.duration ?? 0, readVerdict(result.installed));
+    if (result.listed !== undefined)
+        appendResult(runner, step, 'npm ls --all --json', result.listed, 0, readVerdict(result.listed));
+}
+// Journal writes and backup disposal cannot enter the transaction's rollback boundary.
+function regenerateTree(target, manifest, before) {
+    const lock = join(target, 'package-lock.json');
+    try {
+        unlinkSync(lock);
+        const started = Date.now();
+        const installed = runNpm(['install'], target);
+        const duration = Date.now() - started;
+        const listed = installed.status === 0 ? runNpm(['ls', '--all', '--json'], target) : undefined;
+        const unchanged = manifest.equals(readFileSync(join(target, 'package.json')));
+        const proved = installed.status === 0 && existsSync(lock) && listed?.status === 0 && unchanged;
+        const after = existsSync(lock)
+            ? createHash('sha256').update(readFileSync(lock)).digest('hex')
+            : 'absent';
+        return {
+            exit: proved ? 0 : 1,
+            note: `${proved ? '' : 'ERESOLVE; '}lock SHA-256 ${before} -> ${after}${unchanged ? '' : '; manifest bytes changed'}`,
+            installed,
+            ...(listed === undefined ? {} : { listed }),
+            duration,
+        };
+    }
+    catch (error) {
+        return { exit: 1, note: `ERESOLVE; ${String(error)}` };
+    }
+}
+function discardBackup(target, moved, backup) {
+    try {
+        for (const path of [moved, backup, join(target, 'node_modules')])
+            validateWavePath(target, path);
+        removeTree(moved);
+        return undefined;
+    }
+    catch (error) {
+        return `backup cleanup failed: ${String(error)}; proved installation retained; backups: ${backup}; ${moved}`;
+    }
+}
+function restoreLock(target, moved, backup, before) {
+    try {
+        for (const path of [
+            moved,
+            backup,
+            join(target, 'node_modules'),
+            join(target, 'package-lock.json'),
+        ])
+            validateWavePath(target, path);
+        if (!lstatSync(moved).isDirectory() || !lstatSync(backup).isFile())
+            throw new Error('no recoverable backup');
+        const saved = readFileSync(backup);
+        if (createHash('sha256').update(saved).digest('hex') !== before)
+            throw new Error('backup lock digest changed');
+        removeTree(join(target, 'node_modules'));
+        moveModules(moved, join(target, 'node_modules'));
+        writeFileSync(join(target, 'package-lock.json'), saved);
+        return 'tree and lock restored';
+    }
+    catch (error) {
+        return `rollback failed: ${String(error)}; backups: ${backup}; ${moved}`;
+    }
+}
+function validateWavePath(target, destination) {
+    const root = resolve(target);
+    const path = resolve(destination);
+    const location = relative(root, path);
+    if (location === '..' || location.startsWith(`..${sep}`) || isAbsolute(location))
+        throw new Error(`unsafe wave path: ${path} resolves outside ${root}`);
+    const physical = realpathSync(root);
+    const segments = location === '' ? [] : location.split(sep);
+    for (const entry of [
+        root,
+        ...segments.map((_, index) => join(root, ...segments.slice(0, index + 1))),
+    ]) {
+        const status = lstatSync(entry, { throwIfNoEntry: false });
+        if (status === undefined)
+            continue;
+        if (status.isSymbolicLink())
+            throw new Error(`unsafe wave path: ${entry} is a link`);
+        if (entry !== path && !status.isDirectory())
+            throw new Error(`unsafe wave path: ${entry} is not a directory`);
+        const actual = relative(physical, realpathSync(entry));
+        if (actual === '..' || actual.startsWith(`..${sep}`) || isAbsolute(actual))
+            throw new Error(`unsafe wave path: ${entry} resolves outside ${physical}`);
+    }
+}
+function readDirtyPaths(text) {
+    const [entry, ...rest] = text.split('\0');
+    if (entry === undefined || entry === '')
+        return [];
+    const renamed = /[RC]/u.test(entry.slice(0, 2));
+    const original = renamed ? rest[0] : undefined;
+    return [
+        entry.slice(3),
+        ...(original === undefined ? [] : [original]),
+        ...readDirtyPaths((renamed ? rest.slice(1) : rest).join('\0')),
+    ];
+}
+function readReceipt(target) {
+    try {
+        const value = parseJsonRecord(readFileSync(join(target, 'tmp', 'units', 'wave', 'overwrite.json'), 'utf8'));
+        if (value === undefined ||
+            typeof value.head !== 'string' ||
+            typeof value.version !== 'string' ||
+            typeof value.offline !== 'boolean' ||
+            !Array.isArray(value.written) ||
+            !value.written.every((path) => typeof path === 'string') ||
+            !Array.isArray(value.removed) ||
+            !value.removed.every((path) => typeof path === 'string'))
+            return undefined;
+        return {
+            head: value.head,
+            version: value.version,
+            offline: value.offline,
+            written: value.written,
+            removed: value.removed,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function runRecord(runner, name) {
+    if (name === SCAFFOLD) {
+        appendStep(runner, 'record', 'git commit', `skipped: ${SCAFFOLD}`);
+        return;
+    }
+    if (refuseLocalSpecs(runner, 'record'))
+        return;
+    if (runner.dry) {
+        runStep(runner, 'record', 'git', ['add', '-A', '--pathspec-from-file=-', '--pathspec-file-nul'], runner.target);
+        runStep(runner, 'record', 'git', ['commit', '-m', 'Overwrite with scaffold <version>'], runner.target);
+        return;
+    }
+    const status = runStep(runner, 'record', 'git', ['status', '--porcelain=v1', '-z', '--untracked-files=all'], runner.target);
+    if (status?.status !== 0)
+        return;
+    const dirty = [...new Set(readDirtyPaths(status.stdout))];
+    if (dirty.length === 0) {
+        appendStep(runner, 'record', 'git commit', 'nothing to commit');
+        return;
+    }
+    const receipt = readReceipt(runner.target);
+    const head = runStep(runner, 'record', 'git', ['rev-parse', 'HEAD'], runner.target);
+    if (receipt === undefined || head?.status !== 0 || receipt.head !== head.stdout.trim()) {
+        appendStep(runner, 'record', 'attribute overwrite paths', `uncommitted changes the visit cannot attribute to an overwrite at HEAD: ${dirty.join(', ')}`, 1);
+        return;
+    }
+    if (receipt.offline) {
+        appendStep(runner, 'record', 'git commit', 'an offline overwrite stays uncommitted until scaffold publishes');
+        return;
+    }
+    const allowed = [...receipt.written, ...receipt.removed, 'package.json', 'package-lock.json'].map((path) => normalizeSlashes(relative(runner.target, resolve(runner.target, path))));
+    const outside = dirty.filter((path) => !allowed.some((entry) => entry !== '' &&
+        entry !== '..' &&
+        !entry.startsWith('../') &&
+        !isAbsolute(entry) &&
+        path === entry));
+    if (outside.length > 0) {
+        appendStep(runner, 'record', 'contain overwrite paths', `dirty paths outside the overwrite: ${outside.join(', ')}`, 1);
+        return;
+    }
+    runStep(runner, 'record', 'git', ['--literal-pathspecs', 'add', '-A', '--pathspec-from-file=-', '--pathspec-file-nul'], runner.target, readVerdict, `${dirty.join('\0')}\0`);
+    if (failed(runner))
+        return;
+    runStep(runner, 'record', 'git', ['commit', '-m', `Overwrite with scaffold ${receipt.version}`], runner.target);
+    if (failed(runner))
+        return;
+    runStep(runner, 'record', 'git', ['status', '--porcelain'], runner.target, (result) => result.status === 0 && result.stdout.trim() !== ''
+        ? { exit: 1, note: `tree remains dirty: ${result.stdout}` }
+        : readVerdict(result));
+}
+// A later release of the same name reads the range the earlier reading wrote.
 function computeRanges(ranges, releases) {
     return releases.reduce((state, release) => {
         if (release.latest === undefined || !(release.name in state.ranges))
@@ -229,14 +559,16 @@ function runPin(runner, scaffoldFile, scaffoldPrefix, offline) {
         if (releases === undefined || (audit.status !== 0 && audit.status !== 1))
             return;
         const moved = writeRanges(runner.target, releases);
-        recordStep(runner, 'pin', 'rewrite @orkestrel ranges to the registry caret', moved.length === 0 ? 'no range moved' : moved.join(', '));
+        appendStep(runner, 'pin', 'rewrite audit release ranges to the registry caret', moved.length === 0 ? 'no range moved' : moved.join(', '));
     }
     else {
-        recordStep(runner, 'pin', 'rewrite @orkestrel ranges to the registry caret', 'dry run');
+        appendStep(runner, 'pin', 'rewrite audit release ranges to the registry caret', 'dry run');
     }
-    runNpmStep(runner, 'pin', ['install']);
+    runInstall(runner, 'pin');
 }
 function runCommit(runner) {
+    if (refuseLocalSpecs(runner, 'commit'))
+        return;
     const status = runStep(runner, 'commit', 'git', ['status', '--porcelain', '--', 'package.json', 'package-lock.json'], runner.target);
     if (status === undefined || status.stdout.trim() !== '') {
         runStep(runner, 'commit', 'git', [
@@ -250,11 +582,34 @@ function runCommit(runner) {
         ], runner.target);
     }
     else {
-        recordStep(runner, 'commit', 'git commit', 'manifest and lockfile already committed');
+        appendStep(runner, 'commit', 'git commit', 'manifest and lockfile already committed');
     }
 }
 function runOverwrite(runner, scaffoldFile, scaffoldPrefix, offline) {
-    runStep(runner, 'overwrite', scaffoldFile, [...scaffoldPrefix, 'overwrite', '--json', ...offline], runner.target, (result) => judgeOverwrite(result, runner.offline));
+    const overwrite = runStep(runner, 'overwrite', scaffoldFile, [...scaffoldPrefix, 'overwrite', '--json', ...offline], runner.target, (result) => judgeOverwrite(result, runner.offline));
+    if (overwrite !== undefined && !failed(runner) && runner.directory !== undefined) {
+        const receipt = readJsonObject(overwrite.stdout);
+        const head = runStep(runner, 'overwrite', 'git', ['rev-parse', 'HEAD'], runner.target);
+        const installed = readManifest(join(runner.target, 'node_modules', '@orkestrel', 'scaffold'));
+        const version = readString(installed, 'version');
+        if (head?.status === 0 &&
+            version !== undefined &&
+            Array.isArray(receipt?.written) &&
+            receipt.written.every((path) => typeof path === 'string') &&
+            Array.isArray(receipt.removed) &&
+            receipt.removed.every((path) => typeof path === 'string')) {
+            const path = join(runner.target, 'tmp', 'units', 'wave', 'overwrite.json');
+            try {
+                validateWavePath(runner.target, path);
+                mkdirSync(dirname(path), { recursive: true });
+                validateWavePath(runner.target, path);
+                writeFileSync(path, `${JSON.stringify({ head: head.stdout.trim(), version, offline: runner.offline, written: receipt.written, removed: receipt.removed })}\n`);
+            }
+            catch (error) {
+                appendStep(runner, 'overwrite', 'write overwrite receipt', String(error), 1);
+            }
+        }
+    }
     if (!failed(runner)) {
         runStep(runner, 'overwrite', scaffoldFile, [...scaffoldPrefix, 'audit', ...offline], runner.target);
     }
@@ -267,17 +622,11 @@ function runVerify(runner, scaffoldFile, scaffoldPrefix, offline, own) {
     if (releases === undefined)
         return;
     const drift = releases.filter((release) => release.latest !== undefined && release.range !== `^${release.latest}`);
-    runner.steps.push({
-        step: 'verify',
-        command: 'compare every declared range with the registry',
-        exit: drift.length === 0 ? 0 : 1,
-        durationMs: 0,
-        note: drift.length === 0
-            ? undefined
-            : drift
-                .map((release) => `${release.name} ${release.range} vs ${String(release.latest)}`)
-                .join(', '),
-    });
+    appendStep(runner, 'verify', 'compare every declared range with the registry', drift.length === 0
+        ? 'all declared ranges match'
+        : drift
+            .map((release) => `${release.name} ${release.range} vs ${String(release.latest)}`)
+            .join(', '), drift.length === 0 ? 0 : 1);
 }
 function runPins(runner, before, version) {
     const after = readRanges(readManifest(runner.target) ?? {}, RANGE_FIELDS);
@@ -285,7 +634,7 @@ function runPins(runner, before, version) {
         .filter(([name, range]) => after.get(name) !== range)
         .flatMap(([, range]) => ['--range', range]);
     if (version === undefined) {
-        recordStep(runner, 'pins', basename(PINS), 'no prior version to sweep for; pass --prior');
+        appendStep(runner, 'pins', basename(PINS), 'no prior version to sweep for; pass --prior');
         return undefined;
     }
     const swept = runStep(runner, 'pins', process.execPath, [PINS, '--version', version, ...prior], runner.target);
@@ -303,7 +652,7 @@ function runCompare(runner, name) {
                 ? false
                 : undefined;
     if (name === undefined) {
-        recordStep(runner, 'compare', 'npm view', 'the manifest names no package to read');
+        appendStep(runner, 'compare', 'npm view', 'the manifest names no package to read');
         return { distMoved, rangesMoved: undefined, ranges: undefined, hits: undefined };
     }
     const view = runNpmStep(runner, 'compare', ['view', name, '--json']);
@@ -331,12 +680,6 @@ function runVisit(argv) {
     const [scaffoldFile, ...scaffoldPrefix] = scaffold;
     if (scaffoldFile === undefined)
         return undefined;
-    const runner = {
-        target,
-        dry: argv.includes('--dry-run'),
-        offline: argv.includes('--offline'),
-        steps: [],
-    };
     const from = STEPS.indexOf(readOption(argv, '--from') ?? 'pin');
     const to = STEPS.indexOf(readOption(argv, '--to') ?? 'compare');
     const selected = new Set(STEPS.slice(from, to + 1));
@@ -347,15 +690,34 @@ function runVisit(argv) {
     }
     const name = readString(manifest, 'name');
     const version = readString(manifest, 'version');
+    const runner = {
+        target: resolve(target),
+        dry: argv.includes('--dry-run'),
+        offline: argv.includes('--offline'),
+        regenerate: argv.includes('--regenerate'),
+        directory: argv.includes('--dry-run') ||
+            (name === SCAFFOLD && from === STEPS.indexOf('record') && to === from)
+            ? undefined
+            : readJournalDirectory(resolve(target)),
+        steps: [],
+    };
+    if (runner.directory !== undefined) {
+        try {
+            validateWavePath(runner.target, runner.directory);
+        }
+        catch (error) {
+            appendStep(runner, 'journal', 'validate wave destination', String(error), 1);
+        }
+    }
     const before = readRanges(manifest, RANGE_FIELDS);
     const offline = runner.offline ? ['--offline'] : [];
-    if (selected.has('pin'))
+    if (selected.has('pin') && !failed(runner))
         runPin(runner, scaffoldFile, scaffoldPrefix, offline);
     if (selected.has('commit') && !failed(runner))
         runCommit(runner);
     if (selected.has('overwrite') && !failed(runner)) {
         if (name === SCAFFOLD) {
-            recordStep(runner, 'overwrite', describeCommand(scaffoldFile, [...scaffoldPrefix, 'overwrite', '--json', ...offline]), `skipped with its audit: ${SCAFFOLD} is the package whose checkout the vendored host is staged from`);
+            appendStep(runner, 'overwrite', describeCommand(scaffoldFile, [...scaffoldPrefix, 'overwrite', '--json', ...offline]), `skipped with its audit: ${SCAFFOLD} is the package whose checkout the vendored host is staged from`);
         }
         else
             runOverwrite(runner, scaffoldFile, scaffoldPrefix, offline);
@@ -364,12 +726,14 @@ function runVisit(argv) {
         runVerify(runner, scaffoldFile, scaffoldPrefix, offline, name === SCAFFOLD);
     }
     if (selected.has('install') && !failed(runner))
-        runNpmStep(runner, 'install', ['install']);
+        runInstall(runner, 'install');
     const hits = selected.has('pins') && !failed(runner)
         ? runPins(runner, before, readOption(argv, '--prior') ?? version)
         : undefined;
     if (selected.has('format') && !failed(runner))
         runNpmStep(runner, 'format', ['run', 'format']);
+    if (selected.has('record') && !failed(runner))
+        runRecord(runner, name);
     if (selected.has('gates') && !failed(runner)) {
         for (const gate of GATES) {
             if (failed(runner))
@@ -396,6 +760,23 @@ function runVisit(argv) {
         row: `| ${name ?? target} | ${version ?? '?'} | ${bump} | ${reading} | round |`,
     };
 }
+function readJournalDirectory(target) {
+    const inside = spawnSync('git', ['rev-parse', '--is-inside-work-tree'], {
+        cwd: target,
+        encoding: 'utf8',
+        windowsHide: true,
+    });
+    if (inside.status !== 0 || inside.stdout.trim() !== 'true')
+        return undefined;
+    const ignored = spawnSync('git', ['check-ignore', '-q', 'tmp/units/wave/probe'], {
+        cwd: target,
+        encoding: 'utf8',
+        windowsHide: true,
+    });
+    return ignored.status === 0
+        ? join(target, 'tmp', 'units', 'wave', new Date().toISOString().replace(/[:.]/gu, '-'))
+        : undefined;
+}
 function readLayers(catalogPath) {
     if (!existsSync(catalogPath))
         return undefined;
@@ -419,7 +800,7 @@ function readLayers(catalogPath) {
 }
 function renderVisit(visit) {
     const lines = [
-        ...visit.steps.map((entry) => `wave: ${entry.step.padEnd(9)} exit=${entry.exit === undefined ? 'dry' : String(entry.exit)} ${String(entry.durationMs).padStart(7)} ms  ${entry.command}${entry.note === undefined ? '' : `  (${entry.note})`}`),
+        ...visit.steps.map((entry) => `wave: ${entry.step.padEnd(9)} exit=${entry.exit === undefined ? 'dry' : String(entry.exit)} ${String(entry.durationMs).padStart(7)} ms  ${entry.command}${entry.note === undefined ? '' : `  (${entry.note})`}${entry.journal === undefined ? '' : `  journal=${entry.journal}`}`),
         `wave: ruling dist ${describeReading(visit.ruling.distMoved, 'moved', 'same')}, ranges ${describeReading(visit.ruling.rangesMoved, 'moved', 'same')}${visit.ruling.hits === undefined ? '' : `, ${visit.ruling.hits} self-pin hit(s)`}`,
         ...(visit.ruling.ranges ?? []).map((range) => `wave: range ${range}`),
         visit.row,
@@ -444,6 +825,10 @@ function main(argv) {
         return 64;
     }
     if (argv.includes('--plan')) {
+        if (argv.includes('--regenerate')) {
+            console.error('wave: --regenerate requires --visit, not --plan');
+            return 64;
+        }
         const layers = readLayers(readOption(argv, '--catalog') ?? CATALOG);
         if (layers === undefined) {
             console.error('wave: no marker-bounded catalog table; run scaffold catalog first');
@@ -457,7 +842,7 @@ function main(argv) {
         return 0;
     }
     if (!argv.includes('--visit')) {
-        console.error('usage: wave.ts --visit [--target DIR] [--offline] [--from STEP] [--to STEP] [--prior VERSION] [--dry-run] [--json] [--out FILE] | --plan [--catalog PATH] [--json]');
+        console.error('usage: wave.ts --visit [--target DIR] [--offline] [--regenerate] [--from STEP] [--to STEP] [--prior VERSION] [--dry-run] [--json] [--out FILE] | --plan [--catalog PATH] [--json]');
         return 64;
     }
     const from = STEPS.indexOf(readOption(argv, '--from') ?? 'pin');
@@ -483,7 +868,8 @@ function main(argv) {
         writeFileSync(out, output);
         console.log(`wave: wrote ${out}`);
     }
-    return visit.steps.some((entry) => entry.exit !== undefined &&
+    return visit.steps.some((entry) => entry.superseded !== true &&
+        entry.exit !== undefined &&
         entry.exit !== 0 &&
         entry.step !== 'pins' &&
         entry.step !== 'compare')

package/dist/agents/skills/orkestrel-publish/scripts/window.js

@@ -72,7 +72,8 @@ function readManifestName(directory) {
 function publishPackage(directory, otp) {
     const manifest = readManifestName(directory);
     const journal = `tmp/units/publish-${(manifest.name ?? directory).replace(/[^A-Za-z0-9.-]+/gu, '-')}.log`;
-    const result = runNpm(['publish', '--ignore-scripts', '--browser=false', `--otp=${otp}`], directory);
+    // The refusal code must survive an inherited silent npm log level.
+    const result = runNpm(['publish', '--ignore-scripts', '--browser=false', '--loglevel=error', `--otp=${otp}`], directory);
     writeFileSync(journal, `${result.stdout}\n${result.stderr}\nexit=${result.status ?? 'null'}\n`);
     const match = `${result.stdout}\n${result.stderr}`.match(ACCEPTED);
     const accepted = result.status === 0 && match !== null;