@ekanos/cli 0.22.0 → 0.23.0

package/dist/commands/upgrade.js

@@ -1,3 +1,4 @@
+import { discoverRepo, isRepoRoot } from '@ekanos/integration-schema/repo';
 import { spawn } from 'node:child_process';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
@@ -7,7 +8,7 @@ import { cliVersion } from '../compatibility.js';
 import { invalidStateError, networkError, preconditionError, validationError, } from '../errors.js';
 import { EXIT_CODES } from '../exit-codes.js';
 import { readInstalledPackageManifest } from '../harness-scaffold.js';
-import { detectPackageManager, installExactArgs, lockfileName, } from '../package-manager.js';
+import { detectPackageManager, frozenInstallArgs, installExactArgs, isMultiPackageWorkspaceRoot, lockfileNames, } from '../package-manager.js';
 import { ensureBuildScriptsAnswered, skippedBuildScriptsHint, findIgnoredBuilds, ignoredBuildsHint, isIgnoredBuildsFailure, WORKSPACE_FILE, } from '../pnpm-builds.js';
 import { loadProject } from '../project.js';
 import { classifyPath, writeFileNoFollow } from '../safe-fs.js';
@@ -18,18 +19,72 @@ import { displayPath } from '../ui.js';
 import { collectAllFindings } from '../validate-findings.js';
 import { AGENT_CONTEXT_FILES, DOCS_GROUNDING_FILES, copyBundledSkillTrees, } from './init.js';
 import { promptYesNo } from './publish.js';
+const TOOLCHAIN_NAMES = Object.values(TOOLCHAIN_PACKAGES);
+function dependsOnToolchain(dir) {
+    const manifestPath = path.join(dir, 'package.json');
+    if (!fs.existsSync(manifestPath))
+        return false;
+    const manifest = readManifest(manifestPath);
+    return ['dependencies', 'devDependencies'].some((field) => {
+        const deps = manifest[field];
+        return (typeof deps === 'object' &&
+            deps !== null &&
+            TOOLCHAIN_NAMES.some((name) => name in deps));
+    });
+}
+function planUpgrade(ctx, dir) {
+    const absolute = path.resolve(dir);
+    if (!isRepoRoot(absolute)) {
+        const loaded = loadProject(dir);
+        return {
+            baseDir: loaded.projectDir,
+            repo: false,
+            targets: [
+                {
+                    dir: loaded.projectDir,
+                    relDir: '',
+                    slug: loaded.primary.slug,
+                    validate: true,
+                },
+            ],
+        };
+    }
+    const repo = discoverRepo(absolute);
+    for (const problem of repo.problems) {
+        ctx.warn(`${problem.where}: ${problem.message}`);
+    }
+    const targets = [
+        ...(dependsOnToolchain(repo.root)
+            ? [{ dir: repo.root, relDir: '', slug: null, validate: false }]
+            : []),
+        ...repo.packages
+            .filter((pkg) => dependsOnToolchain(pkg.dir))
+            .map((pkg) => ({
+            dir: pkg.dir,
+            relDir: pkg.relDir,
+            slug: pkg.kind === 'integration' ? pkg.name : null,
+            validate: pkg.kind === 'integration',
+        })),
+    ];
+    return { baseDir: repo.root, repo: true, targets };
+}
 export async function runUpgrade(ctx, args, deps = {}) {
-    var _a, _b, _c, _d, _e, _f, _g;
-    const loaded = loadProject(args.dir);
-    const pm = detectPackageManager(loaded.projectDir);
+    var _a, _b, _c, _d, _e, _f, _g, _h;
+    const plan = planUpgrade(ctx, args.dir);
+    const pm = detectPackageManager(plan.baseDir);
     // Captured BEFORE anything installs: the templates the project's CURRENT
     // (pre-upgrade) local `@ekanos/cli` ships, which is what actually
     // generated the agent-context files on disk — not necessarily this
     // process's own bundled templates, since `upgrade` is a machine-level verb
     // that never delegates and is routinely invoked via a DIFFERENT (global)
     // install. See `regenerateAgentContextFiles`.
-    const oldAgentTemplates = captureAgentTemplates(loaded.projectDir);
-    const current = readCurrentToolchain(loaded.projectDir);
+    const oldAgentTemplates = new Map(plan.targets
+        .filter((target) => target.slug !== null)
+        .map((target) => [
+        target.dir,
+        captureAgentTemplates(cliTemplatesDir(target.dir, pm.root)),
+    ]));
+    const current = readCurrentToolchain(plan.baseDir, pm.root);
     const session = resolveSessionQuietly(ctx, args);
     const resolveTarget = (_a = deps.resolveTarget) !== null && _a !== void 0 ? _a : resolveToolchainTarget;
     const resolution = await resolveTarget({
@@ -55,16 +110,19 @@ export async function runUpgrade(ctx, args, deps = {}) {
     }
     const target = resolution.target;
     const deltas = computeDeltas(current, target);
+    const scope = Object.assign({ packageManager: { name: pm.name, root: pm.root } }, (plan.repo
+        ? { packages: plan.targets.map((t) => t.relDir || '.') }
+        : {}));
     if (args.check) {
-        return ctx.succeed(Object.assign({ source: resolution.source, current,
+        return ctx.succeed(Object.assign(Object.assign({ source: resolution.source, current,
             target,
-            deltas }, (resolution.source === 'host'
+            deltas }, scope), (resolution.source === 'host'
             ? { minimum: resolution.minimum, notes: resolution.notes }
             : {})), checkSummary(ctx.ui, resolution.source, deltas));
     }
     const changedKeys = Object.keys(deltas).filter((key) => deltas[key].changed);
     if (changedKeys.length === 0) {
-        return ctx.succeed({ source: resolution.source, current, target, deltas }, ctx.ui.result({
+        return ctx.succeed(Object.assign({ source: resolution.source, current, target, deltas }, scope), ctx.ui.result({
             title: 'Already up to date',
             rows: [['Target', `resolved from ${resolution.source}`]],
         }));
@@ -86,11 +144,12 @@ export async function runUpgrade(ctx, args, deps = {}) {
                 'modified.');
         }
     }
-    const packageJsonPath = path.join(loaded.projectDir, 'package.json');
-    const manifest = readManifest(packageJsonPath);
-    const specs = buildInstallSpecs(manifest, target, changedKeys);
-    if (specs.length === 0) {
-        return ctx.succeed({ source: resolution.source, current, target, deltas }, ctx.ui.result({
+    const work = plan.targets.map((t) => ({
+        target: t,
+        specs: buildInstallSpecs(readManifest(path.join(t.dir, 'package.json')), target, changedKeys),
+    }));
+    if (work.every((item) => item.specs.length === 0)) {
+        return ctx.succeed(Object.assign({ source: resolution.source, current, target, deltas }, scope), ctx.ui.result({
             title: 'Nothing to install',
             tone: 'warn',
             notes: [
@@ -99,18 +158,27 @@ export async function runUpgrade(ctx, args, deps = {}) {
             ],
         }));
     }
-    const snapshot = snapshotProject(loaded.projectDir, pm);
+    const snapshot = snapshotFiles([
+        ...plan.targets.map((t) => path.join(t.dir, 'package.json')),
+        ...lockfileNames(pm).map((name) => path.join(pm.root, name)),
+        path.join(plan.baseDir, WORKSPACE_FILE),
+        path.join(pm.root, WORKSPACE_FILE),
+    ]);
+    const hadLockfile = lockfileNames(pm).some((name) => snapshot.existed(path.join(pm.root, name)));
+    const runInstall = (_d = deps.runInstall) !== null && _d !== void 0 ? _d : defaultRunInstall;
+    const rollback = (failure) => failAndRollback(ctx, snapshot, pm, hadLockfile, runInstall, failure);
     let answeredBuildScripts = [];
     let buildScriptsSkipped;
     try {
-        const runInstall = (_d = deps.runInstall) !== null && _d !== void 0 ? _d : defaultRunInstall;
         // pnpm 10+ refuses dependency build scripts nobody has answered, and a
         // new toolchain release can grow that list (0.4.0 added @swc/core and
         // @parcel/watcher via next-intl). A project scaffolded under an older
         // CLI has no line for them, so answer the closure BEFORE `pnpm add`, or
-        // the install writes placeholders and exits ERR_PNPM_IGNORED_BUILDS.
+        // the install writes placeholders and exits ERR_PNPM_IGNORED_BUILDS. A
+        // package inside someone else's workspace is told which file to edit
+        // rather than having that file edited for it.
         const buildScripts = pm.name === 'pnpm'
-            ? ensureBuildScriptsAnswered(loaded.projectDir)
+            ? ensureBuildScriptsAnswered(plan.baseDir)
             : { changed: [] };
         answeredBuildScripts = buildScripts.changed;
         if (buildScripts.skipped) {
@@ -120,92 +188,147 @@ export async function runUpgrade(ctx, args, deps = {}) {
         if (answeredBuildScripts.length > 0) {
             ctx.log(ctx.ui.dim(`Answered dependency build scripts in pnpm-workspace.yaml: ${answeredBuildScripts.join(', ')}.`));
         }
-        for (const group of [
-            specs.filter((s) => !s.dev),
-            specs.filter((s) => s.dev),
-        ]) {
-            if (group.length === 0)
-                continue;
-            const argv = installExactArgs(pm, group.map((s) => `${s.name}@${s.version}`), group[0].dev);
-            ctx.log(ctx.ui.dim(`Running "${pm.bin} ${argv.join(' ')}" in ${displayPath(loaded.projectDir, process.cwd())}…`));
-            const result = await runInstall(argv, pm.bin, loaded.projectDir);
-            if (result.code !== 0) {
-                return await failAndRollback(ctx, snapshot, pm, loaded.projectDir, runInstall, {
-                    step: 'install',
-                    exitCode: EXIT_CODES.PRECONDITION_FAILED,
-                    message: isIgnoredBuildsFailure(result.output)
-                        ? `"${pm.bin} ${argv.join(' ')}" exited with code ${result.code}: ${ignoredBuildsHint(findIgnoredBuilds(result.output))}`
-                        : `"${pm.bin} ${argv.join(' ')}" exited with code ${result.code}.`,
-                    output: result.output,
-                });
+        const atWorkspaceRoot = isMultiPackageWorkspaceRoot(pm.root);
+        for (const { target: t, specs } of work) {
+            for (const group of [
+                specs.filter((s) => !s.dev),
+                specs.filter((s) => s.dev),
+            ]) {
+                if (group.length === 0)
+                    continue;
+                const argv = installExactArgs(pm, group.map((s) => `${s.name}@${s.version}`), group[0].dev, atWorkspaceRoot && t.dir === pm.root);
+                ctx.log(ctx.ui.dim(`Running "${pm.bin} ${argv.join(' ')}" in ${displayPath(t.dir, process.cwd())}…`));
+                const result = await runInstall(argv, pm.bin, t.dir);
+                if (result.code !== 0) {
+                    return await rollback({
+                        step: 'install',
+                        exitCode: EXIT_CODES.PRECONDITION_FAILED,
+                        message: isIgnoredBuildsFailure(result.output)
+                            ? `"${pm.bin} ${argv.join(' ')}" exited with code ${result.code}: ${ignoredBuildsHint(findIgnoredBuilds(result.output))}`
+                            : `"${pm.bin} ${argv.join(' ')}" exited with code ${result.code}.`,
+                        output: result.output,
+                    });
+                }
             }
         }
         if (!args.noVerify) {
             const runValidateStep = (_e = deps.runValidateStep) !== null && _e !== void 0 ? _e : defaultRunValidateStep;
-            const validateResult = await runValidateStep(loaded.projectDir);
-            if (!validateResult.ok) {
-                return await failAndRollback(ctx, snapshot, pm, loaded.projectDir, runInstall, {
-                    step: 'validate',
-                    exitCode: EXIT_CODES.VALIDATION,
-                    message: 'The upgraded toolchain fails "ekanos validate" against this ' +
-                        "project's own integration definition.",
-                    output: JSON.stringify((_f = validateResult.findings) !== null && _f !== void 0 ? _f : [], null, 2),
-                });
+            for (const t of plan.targets.filter((item) => item.validate)) {
+                const validateResult = await runValidateStep(t.dir);
+                if (!validateResult.ok) {
+                    return await rollback({
+                        step: 'validate',
+                        exitCode: EXIT_CODES.VALIDATION,
+                        message: 'The upgraded toolchain fails "ekanos validate" against ' +
+                            (plan.repo
+                                ? `${t.relDir}'s integration definition.`
+                                : "this project's own integration definition."),
+                        output: JSON.stringify((_f = validateResult.findings) !== null && _f !== void 0 ? _f : [], null, 2),
+                    });
+                }
             }
+            // A single project always runs its test script. In a repo, each
+            // package that declares one runs it; the root holds no tests.
+            const testTargets = plan.repo
+                ? plan.targets.filter((t) => t.relDir !== '' && hasTestScript(t.dir))
+                : plan.targets;
             const runTestStep = (_g = deps.runTestStep) !== null && _g !== void 0 ? _g : defaultRunTestStep;
-            const testResult = await runTestStep(loaded.projectDir, pm);
-            if (testResult.code !== 0) {
-                return await failAndRollback(ctx, snapshot, pm, loaded.projectDir, runInstall, {
-                    step: 'test',
-                    exitCode: testResult.code,
-                    message: `The project's test script exited with code ${testResult.code} on the upgraded toolchain.`,
-                    output: testResult.output,
-                });
+            for (const t of testTargets) {
+                const testResult = await runTestStep(t.dir, pm);
+                if (testResult.code !== 0) {
+                    return await rollback({
+                        step: 'test',
+                        exitCode: testResult.code,
+                        message: `${plan.repo ? `${t.relDir}: the` : "The project's"} test script exited with code ${testResult.code} on the upgraded toolchain.`,
+                        output: testResult.output,
+                    });
+                }
             }
         }
     }
     finally {
         snapshot.dispose();
     }
-    const newTemplatesDir = path.join(loaded.projectDir, 'node_modules', '@ekanos', 'cli', 'templates');
-    const regenerated = regenerateAgentContextFiles({
-        projectDir: loaded.projectDir,
-        slug: loaded.primary.slug,
-        oldTemplates: oldAgentTemplates,
-        newTemplatesDir,
-    });
-    // The regenerated AGENTS.md and skills may now REFERENCE artifacts this
-    // project predates (docs/api-notes.md, .mcp.json, bundled skill trees) —
-    // instructions pointing at files that don't exist are exactly the stale-docs
-    // failure the docs-grounding feature closes, so create what's missing.
-    // Create-if-missing ONLY: these files are partner/agent-authored after the
-    // scaffold and are never regenerated.
-    const scaffolded = scaffoldMissingDocsArtifacts({
-        projectDir: loaded.projectDir,
-        slug: loaded.primary.slug,
-        newTemplatesDir,
-    });
+    const regenerated = {
+        updated: [],
+        unchanged: [],
+        needsAttention: [],
+        skipped: [],
+    };
+    const scaffolded = {
+        created: [],
+        needsAttention: [],
+    };
+    const under = (relDir, file) => relDir === '' ? file : `${relDir}/${file}`;
+    for (const t of plan.targets) {
+        if (t.slug === null)
+            continue;
+        const newTemplatesDir = cliTemplatesDir(t.dir, pm.root);
+        const report = regenerateAgentContextFiles({
+            projectDir: t.dir,
+            slug: t.slug,
+            oldTemplates: (_h = oldAgentTemplates.get(t.dir)) !== null && _h !== void 0 ? _h : new Map(),
+            newTemplatesDir,
+        });
+        regenerated.updated.push(...report.updated.map((f) => under(t.relDir, f)));
+        regenerated.unchanged.push(...report.unchanged.map((f) => under(t.relDir, f)));
+        regenerated.needsAttention.push(...report.needsAttention.map((f) => under(t.relDir, f)));
+        regenerated.skipped.push(...report.skipped.map((s) => (Object.assign(Object.assign({}, s), { file: under(t.relDir, s.file) }))));
+        // The regenerated AGENTS.md and skills may now REFERENCE artifacts this
+        // project predates (docs/api-notes.md, .mcp.json, bundled skill trees) —
+        // instructions pointing at files that don't exist are exactly the
+        // stale-docs failure the docs-grounding feature closes, so create what's
+        // missing. Create-if-missing ONLY: these files are partner/agent-authored
+        // after the scaffold and are never regenerated.
+        const docs = scaffoldMissingDocsArtifacts({
+            projectDir: t.dir,
+            slug: t.slug,
+            newTemplatesDir,
+        });
+        scaffolded.created.push(...docs.created.map((f) => under(t.relDir, f)));
+        scaffolded.needsAttention.push(...docs.needsAttention.map((f) => under(t.relDir, f)));
+    }
     // `specs` only ever covers DIRECT dependencies (see `buildInstallSpecs`) —
     // a changed key with no spec is transitive and was never actually
     // installed here, so the report (and the human summary) must say so
     // explicitly rather than implying every changed key was upgraded. This
-    // matters most for exactly the scenario this PR's own delegation feature
-    // targets: a globally-installed `ekanos` with no local `@ekanos/cli`
-    // devDependency, where `cli` changes in `deltas` but the running global
-    // binary itself is untouched by this command.
-    const installedKeys = specs.map((spec) => spec.key);
+    // matters most for a globally-installed `ekanos` with no local
+    // `@ekanos/cli` devDependency, where `cli` changes in `deltas` but the
+    // running global binary itself is untouched by this command.
+    const installedKeys = [
+        ...new Set(work.flatMap((item) => item.specs.map((spec) => spec.key))),
+    ];
     const skippedKeys = changedKeys.filter((key) => !installedKeys.includes(key));
-    return ctx.succeed({
-        source: resolution.source,
-        current,
+    return ctx.succeed(Object.assign(Object.assign({ source: resolution.source, current,
         target,
-        deltas,
-        installed: installedKeys,
-        skippedTransitive: skippedKeys,
-        buildScripts: Object.assign({ answered: answeredBuildScripts }, (buildScriptsSkipped ? { skipped: buildScriptsSkipped } : {})),
-        regenerated,
-        scaffolded,
-    }, successSummary(ctx.ui, installedKeys, skippedKeys, deltas, regenerated, scaffolded));
+        deltas }, scope), { installed: installedKeys, skippedTransitive: skippedKeys, buildScripts: Object.assign({ answered: answeredBuildScripts }, (buildScriptsSkipped ? { skipped: buildScriptsSkipped } : {})), regenerated,
+        scaffolded }), successSummary(ctx.ui, installedKeys, skippedKeys, deltas, regenerated, scaffolded));
+}
+function hasTestScript(dir) {
+    const scripts = readManifest(path.join(dir, 'package.json')).scripts;
+    return typeof scripts === 'object' && scripts !== null && 'test' in scripts;
+}
+/**
+ * The nearest `node_modules/@ekanos/cli/templates` from `dir` up to `top`
+ * (the workspace root): pnpm links it into each package, npm and yarn hoist
+ * it to the root. Falls back to the package's own path, where a missing
+ * directory just means "cannot verify" to the regeneration below.
+ */
+function cliTemplatesDir(dir, top) {
+    const own = path.join(dir, 'node_modules', '@ekanos', 'cli', 'templates');
+    let current = path.resolve(dir);
+    const stop = path.resolve(top);
+    for (;;) {
+        const candidate = path.join(current, 'node_modules', '@ekanos', 'cli', 'templates');
+        if (fs.existsSync(candidate))
+            return candidate;
+        if (current === stop)
+            return own;
+        const parent = path.dirname(current);
+        if (parent === current)
+            return own;
+        current = parent;
+    }
 }
 /**
  * Best-effort host/session resolution — NEVER throws. `upgrade` must work for
@@ -225,11 +348,24 @@ function resolveSessionQuietly(ctx, args) {
         return null;
     }
 }
-function readCurrentToolchain(projectDir) {
+/**
+ * The installed toolchain, read from the nearest `node_modules` holding each
+ * package between `projectDir` and `top` (the workspace root): npm and yarn
+ * hoist a workspace package's dependencies to the root.
+ */
+function readCurrentToolchain(projectDir, top) {
     var _a;
     const result = {};
+    const dirs = [];
+    for (let dir = path.resolve(projectDir);; dir = path.dirname(dir)) {
+        dirs.push(dir);
+        if (dir === path.resolve(top) || path.dirname(dir) === dir)
+            break;
+    }
     for (const [key, pkg] of Object.entries(TOOLCHAIN_PACKAGES)) {
-        const installed = readInstalledPackageManifest(projectDir, pkg);
+        const installed = dirs
+            .map((dir) => readInstalledPackageManifest(dir, pkg))
+            .find((manifest) => manifest !== null);
         result[key] = (_a = installed === null || installed === void 0 ? void 0 : installed.version) !== null && _a !== void 0 ? _a : (key === 'cli' ? cliVersion() : null);
     }
     return result;
@@ -289,45 +425,31 @@ function readManifest(packageJsonPath) {
     return parsed;
 }
 /**
- * Copy `package.json`, `pnpm-workspace.yaml` and the lockfile to a temp directory before anything
- * installs. `restore()` copies them back (and removes a lockfile that did not
- * exist before, if the failed install created one); `dispose()` cleans up the
- * temp copies once the run is over, success or failure.
+ * Copy every file in `files` that exists to a temp directory before anything
+ * installs: each target's `package.json`, the lockfile and
+ * `pnpm-workspace.yaml` at the package manager's root (the WORKSPACE root
+ * for a workspace package — that is where an install writes them).
+ * `restore()` copies them back and removes any of them the failed run
+ * created; `dispose()` cleans up the temp copies once the run is over,
+ * success or failure.
  */
-function snapshotProject(projectDir, pm) {
+function snapshotFiles(files) {
     const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ekanos-upgrade-'));
-    const packageJsonPath = path.join(projectDir, 'package.json');
-    // bun has shipped both a text (`bun.lock`) and a legacy binary
-    // (`bun.lockb`) lockfile; snapshot whichever is actually present.
-    const lockCandidates = pm.name === 'bun' ? ['bun.lock', 'bun.lockb'] : [lockfileName(pm)];
-    const lockName = lockCandidates.find((name) => fs.existsSync(path.join(projectDir, name)));
-    const lockfilePath = lockName
-        ? path.join(projectDir, lockName)
-        : path.join(projectDir, lockfileName(pm));
-    const lockfileExisted = lockName !== undefined;
-    const workspacePath = path.join(projectDir, WORKSPACE_FILE);
-    const workspaceExisted = fs.existsSync(workspacePath);
-    fs.copyFileSync(packageJsonPath, path.join(tmpDir, 'package.json'));
-    if (workspaceExisted) {
-        fs.copyFileSync(workspacePath, path.join(tmpDir, 'workspace.snapshot'));
-    }
-    if (lockfileExisted) {
-        fs.copyFileSync(lockfilePath, path.join(tmpDir, 'lockfile.snapshot'));
-    }
+    const entries = [...new Set(files.map((file) => path.resolve(file)))].map((file, index) => {
+        const copy = path.join(tmpDir, String(index));
+        const existed = fs.existsSync(file);
+        if (existed)
+            fs.copyFileSync(file, copy);
+        return { file, copy, existed };
+    });
     return {
+        existed: (file) => { var _a; var _b; return (_b = (_a = entries.find((entry) => entry.file === path.resolve(file))) === null || _a === void 0 ? void 0 : _a.existed) !== null && _b !== void 0 ? _b : false; },
         restore: () => {
-            fs.copyFileSync(path.join(tmpDir, 'package.json'), packageJsonPath);
-            if (workspaceExisted) {
-                fs.copyFileSync(path.join(tmpDir, 'workspace.snapshot'), workspacePath);
-            }
-            else if (fs.existsSync(workspacePath)) {
-                fs.rmSync(workspacePath);
-            }
-            if (lockfileExisted) {
-                fs.copyFileSync(path.join(tmpDir, 'lockfile.snapshot'), lockfilePath);
-            }
-            else if (fs.existsSync(lockfilePath)) {
-                fs.rmSync(lockfilePath);
+            for (const { file, copy, existed } of entries) {
+                if (existed)
+                    fs.copyFileSync(copy, file);
+                else if (fs.existsSync(file))
+                    fs.rmSync(file);
             }
         },
         dispose: () => {
@@ -337,35 +459,55 @@ function snapshotProject(projectDir, pm) {
 }
 /**
  * The one rollback path every failure funnels through: restore the snapshot,
- * reinstall to put `node_modules` back in sync with the restored
- * `package.json`/lockfile, and report exactly which step failed and what it
- * said — with an explicit statement that the project was restored, so a
- * partner (or an agent) never has to wonder whether they are looking at a
- * half-upgraded tree.
+ * then reinstall with the SAME package manager, frozen to the restored
+ * lockfile, at its root — so `node_modules` matches the restored
+ * `package.json`/lockfile again. npm run inside a pnpm workspace is what
+ * broke a project once; it is never used for a project another manager owns.
+ *
+ * The report says exactly which step failed and what it said, and states the
+ * project's real state: restored when the reinstall succeeded, and when it
+ * did not, that `node_modules` is NOT consistent, with the command to repair
+ * it by hand. Never a success claim the reinstall did not earn.
  */
-async function failAndRollback(ctx, snapshot, pm, projectDir, runInstall, failure) {
+async function failAndRollback(ctx, snapshot, pm, hadLockfile, runInstall, failure) {
     ctx.warn(`ekanos: the "${failure.step}" step failed — rolling back package.json ` +
-        'and the lockfile, then reinstalling to restore node_modules…');
+        `and the lockfile, then reinstalling with ${pm.name} to restore node_modules…`);
     snapshot.restore();
     // The SAME injectable installer seam used for the forward install — a test
     // that mocks it never shells out for the rollback path either.
-    const restore = await runInstall(['install'], pm.bin, projectDir);
+    const reinstallArgs = frozenInstallArgs(pm, hadLockfile);
+    const reinstall = await runInstall(reinstallArgs, pm.bin, pm.root);
+    const reinstallCommand = `${pm.bin} ${reinstallArgs.join(' ')}`;
+    const manual = `cd ${pm.root} && ${reinstallCommand}`;
+    const restored = reinstall.code === 0;
     return ctx.failWith({
         code: `upgrade_${failure.step}_failed`,
-        message: failure.message,
-        hint: `The project HAS BEEN RESTORED to its pre-upgrade state (package.json, ` +
-            `lockfile and node_modules all rolled back${restore.code === 0
-                ? ''
-                : ' — though the restore install itself also failed with code ' +
-                    `${restore.code}; run "${pm.bin} install" by hand to finish ` +
-                    'repairing node_modules'}). Read the output in data.output, fix the underlying issue, and ` +
-            're-run "ekanos upgrade".',
+        message: restored
+            ? failure.message
+            : `${failure.message} The rollback reinstall ("${reinstallCommand}") ALSO failed with code ${reinstall.code}.`,
+        hint: restored
+            ? 'The project HAS BEEN RESTORED to its pre-upgrade state (package.json, ' +
+                'lockfile and node_modules all rolled back). Read the output in ' +
+                'data.output, fix the underlying issue, and re-run "ekanos upgrade".'
+            : 'package.json and the lockfile were restored, but node_modules was NOT ' +
+                'reinstalled and does not match them. Repair it by hand before ' +
+                `anything else: ${manual}. Then read data.output and data.rollback, ` +
+                'fix the underlying issue, and re-run "ekanos upgrade".',
         exitCode: failure.exitCode,
-        data: { step: failure.step, output: failure.output },
+        data: {
+            step: failure.step,
+            output: failure.output,
+            rollback: Object.assign({ filesRestored: true, nodeModulesRestored: restored, command: reinstallCommand, cwd: pm.root, exitCode: reinstall.code }, (restored ? {} : { output: reinstall.output, manual })),
+        },
     });
 }
+/**
+ * Spawn the package manager. A spawn failure (the binary is missing) resolves
+ * as exit 127, the shell's "command not found", rather than rejecting: the
+ * caller must still roll back, and a rejection would skip straight past it.
+ */
 async function defaultRunInstall(argv, bin, cwd) {
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve) => {
         var _a, _b;
         const child = spawn(bin, argv, { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
         let output = '';
@@ -375,7 +517,9 @@ async function defaultRunInstall(argv, bin, cwd) {
         (_b = child.stderr) === null || _b === void 0 ? void 0 : _b.on('data', (chunk) => {
             output += chunk.toString();
         });
-        child.on('error', reject);
+        child.on('error', (error) => {
+            resolve({ code: 127, output: `${output}${error.message}` });
+        });
         child.on('close', (code) => resolve({ code: code !== null && code !== void 0 ? code : 1, output }));
     });
 }
@@ -410,8 +554,7 @@ async function defaultRunTestStep(projectDir, pm) {
  * just means every file below is treated conservatively — see
  * `regenerateAgentContextFiles`.
  */
-function captureAgentTemplates(projectDir) {
-    const templatesDir = path.join(projectDir, 'node_modules', '@ekanos', 'cli', 'templates');
+function captureAgentTemplates(templatesDir) {
     const captured = new Map();
     for (const { template } of AGENT_CONTEXT_FILES) {
         const templatePath = path.join(templatesDir, template);