openplanr 2.2640.1 → 2.2640.3

package/dist/services/upgrade-report.js

@@ -0,0 +1,90 @@
+import { display, logger } from '../utils/logger.js';
+import { joinNames } from './runtime-change-summary.js';
+const HIGHLIGHTS_PER_RELEASE = 5;
+function releaseNotesUrl(version) {
+    return `https://github.com/openplanr/OpenPlanr/releases/tag/openplanr%40${version}`;
+}
+/** The first sentence of a changelog entry, or the whole entry when it has one sentence. */
+export function firstSentence(text) {
+    return /^(.+?[.!?])\s+(?=[A-Z`"(*])/s.exec(text)?.[1] ?? text;
+}
+/** Word-wraps `text` to lines of at most `width` columns; a longer word gets its own line. */
+export function wrapText(text, width) {
+    const lines = [];
+    let line = '';
+    for (const word of text.split(/\s+/).filter(Boolean)) {
+        if (line && line.length + 1 + word.length > width) {
+            lines.push(line);
+            line = word;
+        }
+        else {
+            line = line ? `${line} ${word}` : word;
+        }
+    }
+    if (line)
+        lines.push(line);
+    return lines;
+}
+function terminalWidth() {
+    return Math.min(process.stdout.columns || 80, 100);
+}
+/** Per release, up to five first sentences in `highlights` mode, or every entry in full. */
+export function printReleaseNotes(sections, installedVersion, mode) {
+    if (sections.length === 0)
+        return;
+    display.blank();
+    display.heading("What's new");
+    const width = terminalWidth() - 6;
+    for (const section of sections) {
+        display.line(`  ${section.version}`);
+        const entries = mode === 'full'
+            ? section.entries
+            : section.entries.slice(0, HIGHLIGHTS_PER_RELEASE).map(firstSentence);
+        for (const entry of entries) {
+            const [first, ...rest] = wrapText(entry, width);
+            display.line(`    • ${first}`);
+            for (const line of rest)
+                display.line(`      ${line}`);
+        }
+        const hidden = section.entries.length - entries.length;
+        if (hidden > 0)
+            display.line(`    … and ${hidden} more`);
+    }
+    display.line(`  Full notes: ${releaseNotesUrl(installedVersion)}`);
+}
+/** The commands that bring each installed coding agent up to date, then the restart. */
+export function printNextSteps(steps, error) {
+    display.blank();
+    display.heading('Next');
+    if (error) {
+        logger.warn(`${error} Run \`planr upgrade status\` to see what else needs updating.`);
+        return;
+    }
+    if (steps.length === 0) {
+        logger.success('Your coding agents are up to date.');
+        return;
+    }
+    steps.forEach((step, index) => {
+        display.numbered(index + 1, step.command);
+        display.line(`       ${step.host}: ${step.detail}`);
+    });
+    const hosts = [...new Set(steps.filter((step) => step.runtime).map((step) => step.host))];
+    display.line(hosts.length > 0
+        ? `  Then restart ${joinNames(hosts)} and check with \`planr upgrade status\`.`
+        : '  Then check with `planr upgrade status`.');
+}
+/** How `planr upgrade apply` and the inline upgrade offer report an upgrade. */
+export function printUpgradeReport(result, mode) {
+    if (!result.ok) {
+        logger.error(result.failure?.message ?? 'The upgrade did not complete.');
+        if (result.restoredTo)
+            logger.info(`Restored the previous version ${result.restoredTo}.`);
+        return;
+    }
+    logger.success(`Upgraded OpenPlanr from ${result.previousVersion} to ${result.installedVersion}.`);
+    if (result.releaseNotesError)
+        logger.warn(result.releaseNotesError);
+    printReleaseNotes(result.releaseNotes, result.installedVersion, mode);
+    printNextSteps(result.nextSteps, result.nextStepsError);
+}
+//# sourceMappingURL=upgrade-report.js.map

package/dist/services/upgrade-report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upgrade-report.js","sourceRoot":"","sources":["../../src/services/upgrade-report.ts"],"names":[],"mappings":"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"}

package/dist/services/upgrade-service.d.ts

@@ -1,19 +1,18 @@
 /**
  * `planr upgrade`: reconciles the installed CLI, bundled pipeline and host plugin with the
  * published compatible set (npm `latest`, cached, short fetch timeout), upgrades the CLI half
- * with verify-after-install and restore, runs crossed migrations and prescribes the plugin
- * commands for the user to run. Entry points: `reconcileInstalledTuple`, `planCliUpgrade`,
+ * with verify-after-install and restore, runs crossed migrations and reports the command that
+ * updates each installed coding agent. Entry points: `reconcileInstalledTuple`, `planCliUpgrade`,
  * `executeCliHalfUpgrade`. It never changes the host plugin itself.
  */
-import { type ClaudeCommandRunner, type ClaudePluginOperation } from './claude-plugin-service.js';
+import { type ClaudeCommandRunner } from './claude-plugin-service.js';
+import { type RuntimeId } from './runtime-manager-service.js';
 /**
  * The command that registers the bundled `openplanr-local` marketplace and installs
- * `planr@openplanr-local` from it. Prescribed instead of raw `claude plugin` commands when
+ * `planr@openplanr-local` from it. Prescribed instead of `planr runtime update` when
  * Claude Code has no such marketplace yet, because only setup records the installation.
  */
 export declare const CLAUDE_PLUGIN_SETUP_COMMAND = "planr setup --runtime claude --scope user";
-/** Shown above the prescribed plugin-half commands by `planr upgrade apply` and the inline offer. */
-export declare const PLUGIN_HALF_INSTRUCTION = "Run these yourself, in order, or ask the agent to run planr-doctor\u2019s upgrade skill. They bring the plugin `planr setup` installs, `planr@openplanr-local`, up to the version bundled with this CLI:";
 /**
  * One component of the published compatibility manifest (`ecosystem.json`'s
  * `components.*`). Each artifact carries its own version plus the mutual
@@ -120,19 +119,36 @@ export declare function planCliUpgrade(reconciliation: UpgradeReconciliation): U
  * version header so a summary can never reach back past the target's section.
  */
 export declare function summarizeChangelogBetween(oldVersion: string, newVersion: string): string[];
+/** One released version's changelog entries. */
+export interface ReleaseNoteSection {
+    version: string;
+    entries: string[];
+}
+/** `parseReleaseNotes` over the changelog this CLI ships, or nothing when it ships none. */
+export declare function summarizeReleaseNotes(oldVersion: string, newVersion: string): ReleaseNoteSection[];
+/**
+ * The changelog entries released after `oldVersion` up to `newVersion`, newest first, without
+ * commit hashes or dependency bumps. Without an `oldVersion` header only the target's own
+ * section is returned.
+ */
+export declare function parseReleaseNotes(changelog: string, oldVersion: string, newVersion: string): ReleaseNoteSection[];
+/**
+ * A command that brings one installed coding agent up to what this CLI bundles.
+ * Without `runtime` it concerns OpenPlanr's own runtime state rather than one agent.
+ */
+export interface UpgradeNextStep {
+    runtime?: RuntimeId;
+    host: string;
+    command: string;
+    detail: string;
+}
 /**
- * The manifest-refresh guarantee: the marketplace refresh is printed FIRST —
- * "without which the installer reinstalls the stale version." A stable sort keeps
- * every other operation in the order the bundled inspection produced, and each is
- * rendered by `formatClaudePluginOperationCommand` (the same argv setup would run),
- * so the prescription can never drift from what would actually execute. A missing
- * `openplanr-local` marketplace means `planr setup` never ran on this machine, and
- * setup is the one command that both registers it and records the installation.
- * A retired plugin beside it needs `--replace-managed`: setup refuses the removal
- * without the flag, and `--runtime` skips the guided prompt that would offer it.
- * This is a pure formatter — it prints the plugin half, it never runs it.
+ * One command per installed coding agent whose OpenPlanr files or plugin trail this CLI,
+ * planned with the same preview `planr runtime update` applies.
  */
-export declare function prescribePluginHalfCommands(operations: ClaudePluginOperation[], marketplaceRoot: string): string[];
+export declare function upgradeNextSteps(projectDir: string, options?: {
+    claudeCommandRunner?: ClaudeCommandRunner;
+}): Promise<UpgradeNextStep[]>;
 /** One migration's outcome as the injected registry runner reports it. */
 export interface MigrationRunResult {
     id: string;
@@ -150,23 +166,20 @@ export interface MigrationRunResult {
 export type MigrationRunner = (fromVersion: string, toVersion: string, ctx: {
     projectDir: string;
 }) => Promise<MigrationRunResult[]>;
-/**
- * The plugin-half prescription, derived independently of whether the CLI half moved.
- *
- * Two situations need these commands: a completed CLI upgrade, and a tuple where the CLI
- * is already current but the plugins trail (the state every release creates for anyone
- * who upgrades the npm half first). The second path used to reach no prescription at all
- * while its own message promised one. Deriving the commands here means both surfaces read
- * from one place and can never print different instructions for the same machine.
- */
-export declare function pluginHalfPrescription(claudeCommandRunner?: ClaudeCommandRunner): string[];
+/** Runs the OpenPlanr CLI now installed on disk with the given arguments. */
+export type InstalledCliRunner = (args: string[]) => NpmCommandResult;
+/** The next steps as the upgraded CLI reports them from `planr upgrade status --json`. */
+export declare function readInstalledCliNextSteps(projectDir: string, runner?: InstalledCliRunner): {
+    nextSteps: UpgradeNextStep[];
+    error?: string;
+};
 export interface ExecuteCliHalfUpgradeInput {
     projectDir: string;
     targetCliVersion: string;
     /** Injectable npm runner; defaults to the real (or `OPENPLANR_NPM_BIN`) npm. */
     npmCommandRunner?: NpmCommandRunner;
-    /** Injectable `claude` runner for the prescription's inspection (hermetic tests). */
-    claudeCommandRunner?: ClaudeCommandRunner;
+    /** Injectable runner for the upgraded CLI; defaults to a new process of this entry point. */
+    installedCliRunner?: InstalledCliRunner;
     /**
      * Migration runner, run after the CLI half verifies. Omitted (no runner)
      * means no migrations are attempted; the `apply` command injects the real
@@ -177,9 +190,15 @@ export interface ExecuteCliHalfUpgradeInput {
 export interface ExecuteCliHalfUpgradeResult {
     ok: boolean;
     cliUpgraded: boolean;
+    previousVersion: string;
     installedVersion: string;
     restoredTo?: string;
     changelogBullets: string[];
+    releaseNotes: ReleaseNoteSection[];
+    releaseNotesError?: string;
+    nextSteps: UpgradeNextStep[];
+    nextStepsError?: string;
+    /** The commands of `nextSteps`, for readers of the older field. */
     pluginHalfCommands: string[];
     /** Per-migration results for every registered migration this upgrade crossed. */
     migrations: MigrationRunResult[];

package/dist/services/upgrade-service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"upgrade-service.d.ts","sourceRoot":"","sources":["../../src/services/upgrade-service.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAUH,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAI3B,MAAM,4BAA4B,CAAC;AAKpC;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,8CAA8C,CAAC;AAEvF,qGAAqG;AACrG,eAAO,MAAM,uBAAuB,6MACmK,CAAC;AAExM;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,kBAAkB,CAAC;IACxB,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,MAAM,EAAE,kBAAkB,CAAC;IAC3B,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC;;;;OAIG;IACH,KAAK,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;CACjC;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,OAAO,GAAG,aAAa,GAAG,aAAa,CAAC;AAElF,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,SAAS,GAAG,mBAAmB,GAAG,cAAc,GAAG,SAAS,CAAC;IACrE,SAAS,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IAC3E,SAAS,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACtC,eAAe,EAAE,eAAe,CAAC;IACjC,4GAA4G;IAC5G,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,wGAAwG;IACxG,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B,qEAAqE;IACrE,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;IAC1C,iEAAiE;IACjE,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,oEAAoE;IACpE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,wBAAwB,gDAAgD,CAAC;AAgRtF;;;;;;GAMG;AACH,wBAAsB,uBAAuB,CAC3C,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,qBAAqB,CAAC,CAmEhC;AAQD,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAED,MAAM,MAAM,gBAAgB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,gBAAgB,CAAC;AA0CpE,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,cAAc,EAAE,qBAAqB,GAAG,WAAW,CA6CjF;AA2CD;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,CA6B1F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,2BAA2B,CACzC,UAAU,EAAE,qBAAqB,EAAE,EACnC,eAAe,EAAE,MAAM,GACtB,MAAM,EAAE,CAcV;AAED,0EAA0E;AAC1E,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,OAAO,CAAC;IACjB,cAAc,EAAE,OAAO,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,CAC5B,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,KACxB,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAC;AAEnC;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,mBAAmB,CAAC,EAAE,mBAAmB,GAAG,MAAM,EAAE,CAM1F;AAED,MAAM,WAAW,0BAA0B;IACzC,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;IACzB,gFAAgF;IAChF,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,qFAAqF;IACrF,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;IAC1C;;;;OAIG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC;AAED,MAAM,WAAW,2BAA2B;IAC1C,EAAE,EAAE,OAAO,CAAC;IACZ,WAAW,EAAE,OAAO,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,iFAAiF;IACjF,UAAU,EAAE,kBAAkB,EAAE,CAAC;IACjC,OAAO,CAAC,EAAE;QACR,IAAI,EAAE,aAAa,GAAG,QAAQ,GAAG,WAAW,GAAG,WAAW,CAAC;QAC3D,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CACH;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,0BAA0B,GAChC,OAAO,CAAC,2BAA2B,CAAC,CA+FtC"}
+{"version":3,"file":"upgrade-service.d.ts","sourceRoot":"","sources":["../../src/services/upgrade-service.ts"],"names":[],"mappings":"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"}

package/dist/services/upgrade-service.js

@@ -1,8 +1,8 @@
 /**
  * `planr upgrade`: reconciles the installed CLI, bundled pipeline and host plugin with the
  * published compatible set (npm `latest`, cached, short fetch timeout), upgrades the CLI half
- * with verify-after-install and restore, runs crossed migrations and prescribes the plugin
- * commands for the user to run. Entry points: `reconcileInstalledTuple`, `planCliUpgrade`,
+ * with verify-after-install and restore, runs crossed migrations and reports the command that
+ * updates each installed coding agent. Entry points: `reconcileInstalledTuple`, `planCliUpgrade`,
  * `executeCliHalfUpgrade`. It never changes the host plugin itself.
  */
 import { spawnSync } from 'node:child_process';
@@ -13,18 +13,17 @@ import { fileURLToPath } from 'node:url';
 import { z } from 'zod';
 import { parseExternalJson } from '../utils/external-json.js';
 import { logger } from '../utils/logger.js';
-import { formatClaudePluginOperationCommand, inspectBundledClaudePluginIntegration, OPENPLANR_CLAUDE_PLUGIN, } from './claude-plugin-service.js';
+import { inspectBundledClaudePluginIntegration, OPENPLANR_CLAUDE_PLUGIN, } from './claude-plugin-service.js';
 import { resolvePipelinePackage } from './pipeline-package-service.js';
 import { readOpenPlanrVersion } from './provenance-service.js';
-import { bundledHostRoot, classifyComponentDrift, runtimeRoot } from './runtime-manager-service.js';
+import { RUNTIME_LABELS, summarizeRuntimeChanges } from './runtime-change-summary.js';
+import { bundledHostRoot, classifyComponentDrift, installedRuntimeScopes, previewSetup, RuntimeManagerError, runtimeRoot, } from './runtime-manager-service.js';
 /**
  * The command that registers the bundled `openplanr-local` marketplace and installs
- * `planr@openplanr-local` from it. Prescribed instead of raw `claude plugin` commands when
+ * `planr@openplanr-local` from it. Prescribed instead of `planr runtime update` when
  * Claude Code has no such marketplace yet, because only setup records the installation.
  */
 export const CLAUDE_PLUGIN_SETUP_COMMAND = 'planr setup --runtime claude --scope user';
-/** Shown above the prescribed plugin-half commands by `planr upgrade apply` and the inline offer. */
-export const PLUGIN_HALF_INSTRUCTION = 'Run these yourself, in order, or ask the agent to run planr-doctor’s upgrade skill. They bring the plugin `planr setup` installs, `planr@openplanr-local`, up to the version bundled with this CLI:';
 /**
  * The published compatible set is the npm registry's `latest` document for the
  * CLI: its version is what a global install lands, and its exact `planr-pipeline`
@@ -406,7 +405,7 @@ export function planCliUpgrade(reconciliation) {
         return {
             proceed: false,
             targetCliVersion: null,
-            reason: 'The published compatibility manifest is unavailable; no upgrade target can be determined.',
+            reason: 'The latest OpenPlanr version could not be checked; the npm registry is unreachable.',
         };
     }
     const target = published.cli.version;
@@ -414,34 +413,34 @@ export function planCliUpgrade(reconciliation) {
         return {
             proceed: false,
             targetCliVersion: null,
-            reason: 'The installed tuple already matches the published compatible set; nothing to upgrade.',
+            reason: `OpenPlanr ${installed.cli} is up to date.`,
         };
     }
     if (status === 'upgrade-available') {
         return {
             proceed: true,
             targetCliVersion: target,
-            reason: `An upgrade is available: the CLI can move from ${installed.cli} to ${target}.`,
+            reason: `OpenPlanr ${target} is available; ${installed.cli} is installed.`,
         };
     }
     if (status === 'incompatible' && compareStableVersions(installed.cli, target) < 0) {
         return {
             proceed: true,
             targetCliVersion: target,
-            reason: `The tuple is incompatible and the CLI is behind; moving the CLI from ${installed.cli} to ${target}.`,
+            reason: `OpenPlanr ${target} is available, and the installed ${installed.cli} no longer matches its plugins.`,
         };
     }
     if (status === 'incompatible') {
         return {
             proceed: false,
             targetCliVersion: null,
-            reason: `The tuple is incompatible but the CLI (${installed.cli}) is not behind the published ${target}; the plugin half must move — run the prescribed commands below.`,
+            reason: `OpenPlanr ${installed.cli} is current, but a coding agent's plugin is behind it. Run the commands below.`,
         };
     }
     return {
         proceed: false,
         targetCliVersion: null,
-        reason: 'The tuple could not be judged.',
+        reason: 'The installed OpenPlanr version could not be judged.',
     };
 }
 /**
@@ -528,44 +527,211 @@ export function summarizeChangelogBetween(oldVersion, newVersion) {
         endIndex = firstHeaderAfterStart;
     return extractChangelogBullets(lines.slice(startIndex + 1, endIndex));
 }
+const CHANGESET_COMMIT_PREFIX = /^(?:\[`?[0-9a-f]{7,40}`?\]\([^)]*\):?|[0-9a-f]{7,40}:)\s+/;
+/** `parseReleaseNotes` over the changelog this CLI ships, or nothing when it ships none. */
+export function summarizeReleaseNotes(oldVersion, newVersion) {
+    const changelogPath = locateChangelog();
+    if (!changelogPath)
+        return [];
+    return parseReleaseNotes(readFileSync(changelogPath, 'utf8'), oldVersion, newVersion);
+}
 /**
- * The manifest-refresh guarantee: the marketplace refresh is printed FIRST —
- * "without which the installer reinstalls the stale version." A stable sort keeps
- * every other operation in the order the bundled inspection produced, and each is
- * rendered by `formatClaudePluginOperationCommand` (the same argv setup would run),
- * so the prescription can never drift from what would actually execute. A missing
- * `openplanr-local` marketplace means `planr setup` never ran on this machine, and
- * setup is the one command that both registers it and records the installation.
- * A retired plugin beside it needs `--replace-managed`: setup refuses the removal
- * without the flag, and `--runtime` skips the guided prompt that would offer it.
- * This is a pure formatter — it prints the plugin half, it never runs it.
+ * The changelog entries released after `oldVersion` up to `newVersion`, newest first, without
+ * commit hashes or dependency bumps. Without an `oldVersion` header only the target's own
+ * section is returned.
  */
-export function prescribePluginHalfCommands(operations, marketplaceRoot) {
-    if (operations.some((operation) => operation.kind === 'add-marketplace')) {
-        const retiresLegacyPlugin = operations.some((operation) => operation.kind === 'remove');
-        return [
-            retiresLegacyPlugin
-                ? `${CLAUDE_PLUGIN_SETUP_COMMAND} --replace-managed`
-                : CLAUDE_PLUGIN_SETUP_COMMAND,
-        ];
-    }
-    const rank = (operation) => operation.kind === 'refresh-marketplace' ? 0 : 1;
-    return [...operations]
-        .sort((a, b) => rank(a) - rank(b))
-        .map((operation) => formatClaudePluginOperationCommand(operation, marketplaceRoot));
+export function parseReleaseNotes(changelog, oldVersion, newVersion) {
+    const lines = changelog.split(/\r?\n/);
+    const startIndex = lines.findIndex((line) => changelogHeaderMatches(line, newVersion));
+    if (startIndex === -1)
+        return [];
+    const hasOldSection = lines.some((line) => changelogHeaderMatches(line, oldVersion));
+    const sections = [];
+    let entry;
+    let skipEntry = false;
+    const closeEntry = () => {
+        if (entry && !skipEntry)
+            sections[sections.length - 1]?.entries.push(entry.join(' '));
+        entry = undefined;
+        skipEntry = false;
+    };
+    for (const line of lines.slice(startIndex)) {
+        const header = /^##\s+\[?([^\]\s]+)\]?$/.exec(line.trim());
+        if (header) {
+            closeEntry();
+            if (header[1] === oldVersion || (!hasOldSection && sections.length > 0))
+                break;
+            sections.push({ version: header[1], entries: [] });
+            continue;
+        }
+        const item = /^-\s+(.*\S)\s*$/.exec(line);
+        if (item) {
+            closeEntry();
+            const text = item[1].replace(CHANGESET_COMMIT_PREFIX, '');
+            skipEntry = /^Updated dependencies\b/.test(text);
+            entry = [text];
+        }
+        else if (entry && /^\s+\S/.test(line)) {
+            entry.push(line.trim().replace(/^-\s+/, ''));
+        }
+    }
+    closeEntry();
+    return sections.filter((section) => section.entries.length > 0);
+}
+const RUNTIME_COMMAND_NAMES = {
+    'claude-code': 'claude',
+    codex: 'codex',
+    cursor: 'cursor',
+};
+function nextStepCommand(runtime, scope, skillMode, operations) {
+    const claudeKinds = operations
+        .filter((operation) => operation.runtime === 'claude-code')
+        .map((operation) => operation.kind);
+    // Only setup registers the local marketplace and may remove a retired plugin.
+    if (claudeKinds.includes('add-marketplace') || claudeKinds.includes('remove')) {
+        return `${CLAUDE_PLUGIN_SETUP_COMMAND}${claudeKinds.includes('remove') ? ' --replace-managed' : ''} --yes`;
+    }
+    // `runtime update` has no skill-mode flag and would move a unified-plugin install to direct skills.
+    if (runtime === 'codex' && skillMode === 'unified-plugin') {
+        return `planr setup --runtime codex --scope ${scope} --skill-mode unified-plugin --yes`;
+    }
+    return `planr runtime update ${RUNTIME_COMMAND_NAMES[runtime]} --scope ${scope} --yes`;
+}
+/** Recorded installs, plus a Claude plugin installed without a record of it. */
+async function nextStepCandidates(projectDir, claudeCommandRunner) {
+    let candidates = [];
+    let stateError;
+    try {
+        candidates = await installedRuntimeScopes(projectDir);
+    }
+    catch (error) {
+        if (!(error instanceof RuntimeManagerError))
+            throw error;
+        stateError = error;
+    }
+    if (!candidates.some(({ runtime, scope }) => runtime === 'claude-code' && scope === 'user')) {
+        const plugin = inspectBundledHostPlugin(claudeCommandRunner).plugins.find((entry) => entry.name === OPENPLANR_CLAUDE_PLUGIN);
+        if (plugin?.installed)
+            candidates.unshift({ runtime: 'claude-code', scope: 'user' });
+    }
+    return { candidates, ...(stateError ? { stateError } : {}) };
+}
+/** The step one install needs, or `undefined` when it already matches this CLI. */
+async function planNextStep({ runtime, scope, skillMode }, projectDir, claudeCommandRunner) {
+    const preview = await previewSetup({
+        projectDir,
+        cliVersion: readOpenPlanrVersion(),
+        runtime,
+        scope,
+        dryRun: true,
+        ...(skillMode ? { skillMode } : {}),
+        ...(claudeCommandRunner ? { claudeCommandRunner } : {}),
+    });
+    const change = summarizeRuntimeChanges(preview, {
+        bookkeepingRoot: runtimeRoot(),
+        applied: false,
+    }).find((entry) => entry.runtime === runtime);
+    if (!change?.changed)
+        return undefined;
+    return {
+        runtime,
+        host: change.host,
+        command: nextStepCommand(runtime, scope, skillMode, preview.runtimeOperations),
+        detail: change.summary,
+    };
 }
 /**
- * The plugin-half prescription, derived independently of whether the CLI half moved.
- *
- * Two situations need these commands: a completed CLI upgrade, and a tuple where the CLI
- * is already current but the plugins trail (the state every release creates for anyone
- * who upgrades the npm half first). The second path used to reach no prescription at all
- * while its own message promised one. Deriving the commands here means both surfaces read
- * from one place and can never print different instructions for the same machine.
+ * One command per installed coding agent whose OpenPlanr files or plugin trail this CLI,
+ * planned with the same preview `planr runtime update` applies.
  */
-export function pluginHalfPrescription(claudeCommandRunner) {
-    const marketplaceRoot = bundledHostRoot('claude');
-    return prescribePluginHalfCommands(inspectBundledClaudePluginIntegration(marketplaceRoot, claudeCommandRunner).operations, marketplaceRoot);
+export async function upgradeNextSteps(projectDir, options = {}) {
+    const steps = [];
+    const doctorStep = (error, runtime) => {
+        if (steps.some((step) => step.detail === error.message))
+            return;
+        steps.push({
+            ...(runtime ? { runtime } : {}),
+            host: runtime ? RUNTIME_LABELS[runtime] : 'OpenPlanr',
+            command: 'planr doctor',
+            detail: error.message,
+        });
+    };
+    const { candidates, stateError } = await nextStepCandidates(projectDir, options.claudeCommandRunner);
+    if (stateError)
+        doctorStep(stateError);
+    for (const candidate of candidates) {
+        try {
+            const step = await planNextStep(candidate, projectDir, options.claudeCommandRunner);
+            if (step)
+                steps.push(step);
+        }
+        catch (error) {
+            if (!(error instanceof Error))
+                throw error;
+            doctorStep(error, candidate.runtime);
+        }
+    }
+    return steps;
+}
+// After `npm install -g` this process still executes the previous version's modules,
+// so only a fresh process of the same entry point runs the upgraded code.
+function defaultInstalledCliRunner(args) {
+    const entry = process.argv[1];
+    if (!entry) {
+        return {
+            status: null,
+            stdout: '',
+            stderr: '',
+            error: new Error('The entry point of the running CLI is unknown.'),
+        };
+    }
+    const result = spawnSync(process.execPath, [...process.execArgv, entry, ...args], {
+        encoding: 'utf8',
+        windowsHide: true,
+        timeout: 120_000,
+    });
+    return {
+        status: result.status,
+        stdout: result.stdout ?? '',
+        stderr: result.stderr ?? '',
+        ...(result.error ? { error: result.error } : {}),
+    };
+}
+const nextStepsReportSchema = z.object({
+    nextSteps: z.array(z.object({
+        runtime: z.enum(['claude-code', 'codex', 'cursor']).optional(),
+        host: z.string(),
+        command: z.string(),
+        detail: z.string(),
+    })),
+});
+const installedStatusSchema = z.union([
+    nextStepsReportSchema,
+    z.object({ ok: z.literal(false), problem: z.string() }),
+]);
+/** The next steps as the upgraded CLI reports them from `planr upgrade status --json`. */
+export function readInstalledCliNextSteps(projectDir, runner = defaultInstalledCliRunner) {
+    const result = runner(['--project-dir', projectDir, 'upgrade', 'status', '--json']);
+    if (result.error) {
+        return { nextSteps: [], error: `The upgraded CLI could not be run: ${result.error.message}.` };
+    }
+    const report = result.stdout.trim().split(/\r?\n/).pop() ?? '';
+    try {
+        const parsed = parseExternalJson(report, installedStatusSchema, 'planr upgrade status --json');
+        if ('nextSteps' in parsed)
+            return { nextSteps: parsed.nextSteps };
+        return {
+            nextSteps: [],
+            error: `The upgraded CLI could not list its next steps: ${parsed.problem}`,
+        };
+    }
+    catch (error) {
+        const detail = result.stderr.trim() || (error instanceof Error ? error.message : String(error));
+        return {
+            nextSteps: [],
+            error: `The upgraded CLI did not report its next steps (exit ${result.status}): ${detail}`,
+        };
+    }
 }
 /**
  * Execute the one half the CLI owns — a global npm install — and
@@ -593,7 +759,10 @@ export async function executeCliHalfUpgrade(input) {
             ok: false,
             cliUpgraded: false,
             installedVersion: readOpenPlanrVersion(),
+            previousVersion,
             changelogBullets: [],
+            releaseNotes: [],
+            nextSteps: [],
             pluginHalfCommands: [],
             migrations: [],
             failure: {
@@ -618,7 +787,10 @@ export async function executeCliHalfUpgrade(input) {
             cliUpgraded: false,
             installedVersion: restoredVersion,
             restoredTo: previousVersion,
+            previousVersion,
             changelogBullets: [],
+            releaseNotes: [],
+            nextSteps: [],
             pluginHalfCommands: [],
             migrations: [],
             failure: { step: 'verify', message },
@@ -644,7 +816,10 @@ export async function executeCliHalfUpgrade(input) {
             ok: false,
             cliUpgraded: true,
             installedVersion: verifiedVersion,
+            previousVersion,
             changelogBullets: [],
+            releaseNotes: [],
+            nextSteps: [],
             pluginHalfCommands: [],
             migrations,
             failure: {
@@ -659,13 +834,26 @@ export async function executeCliHalfUpgrade(input) {
     // "no entries", not as a failed upgrade (which would misreport a machine that
     // is, in fact, upgraded).
     const changelogBullets = summarizeChangelogBetween(previousVersion, verifiedVersion);
-    const pluginHalfCommands = pluginHalfPrescription(input.claudeCommandRunner);
+    let releaseNotes = [];
+    let releaseNotesError;
+    try {
+        releaseNotes = summarizeReleaseNotes(previousVersion, verifiedVersion);
+    }
+    catch (error) {
+        releaseNotesError = `The release notes could not be read: ${error instanceof Error ? error.message : String(error)}`;
+    }
+    const next = readInstalledCliNextSteps(input.projectDir, input.installedCliRunner);
     return {
         ok: true,
         cliUpgraded: true,
+        previousVersion,
         installedVersion: verifiedVersion,
         changelogBullets,
-        pluginHalfCommands,
+        releaseNotes,
+        ...(releaseNotesError ? { releaseNotesError } : {}),
+        nextSteps: next.nextSteps,
+        ...(next.error ? { nextStepsError: next.error } : {}),
+        pluginHalfCommands: next.nextSteps.map((step) => step.command),
         migrations,
     };
 }