@planu/cli 4.13.0 → 5.0.0

package/dist/engine/auto-updater/atomic-upgrade.js

@@ -0,0 +1,381 @@
+import { readFile, rm } from 'node:fs/promises';
+import { isAbsolute } from 'node:path';
+import { atomicWriteFile } from '../safety/atomic-write-file.js';
+import { readInstallationManifest, } from '../../cli/commands/install.js';
+import { buildPinnedEntry } from './config-patcher.js';
+import { stageAndVerifyRelease } from './release-verifier.js';
+import { assertVersionNotQuarantined, markUpgradeVerified, quarantineUpgradeVersion, readUpgradeTrustState, upgradeTrustStatePath, } from './upgrade-trust-state.js';
+import { withUpgradeLock } from './upgrade-lock.js';
+import { redactFailureMessage, reportClassifiedDegradation, } from '../../errors/classified-degradation.js';
+const PACKAGE_PREFIX = '@planu/cli@';
+const EXACT_VERSION = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)$/;
+export class UpgradeInterruptionError extends Error {
+    constructor(message = 'Simulated process interruption during upgrade') {
+        super(message);
+        this.name = 'UpgradeInterruptionError';
+    }
+}
+export function upgradeJournalPath(manifestPath) {
+    return `${manifestPath}.upgrade-journal.json`;
+}
+// eslint-disable-next-line complexity -- every persisted journal field is fail-closed
+function parseJournal(raw, manifestPath) {
+    const parsed = JSON.parse(raw);
+    const adapterPaths = parsed.adapters?.map((item) => item.configPath) ?? [];
+    if (parsed.schemaVersion !== 2 ||
+        !['prepared', 'switching', 'trust-switched', 'committed'].includes(parsed.state ?? '') ||
+        parsed.manifestPath !== manifestPath ||
+        !EXACT_VERSION.test(parsed.previousVersion ?? '') ||
+        !EXACT_VERSION.test(parsed.targetVersion ?? '') ||
+        typeof parsed.originalManifest !== 'string' ||
+        parsed.trustStatePath !== upgradeTrustStatePath(manifestPath) ||
+        (parsed.originalTrustState !== null && typeof parsed.originalTrustState !== 'string') ||
+        !Array.isArray(parsed.adapters) ||
+        parsed.adapters.some((item) => !isAbsolute(item.configPath) || typeof item.original !== 'string') ||
+        new Set(adapterPaths).size !== adapterPaths.length ||
+        !Array.isArray(parsed.switchedPaths) ||
+        parsed.switchedPaths.some((path) => !adapterPaths.includes(path)) ||
+        typeof parsed.updatedAt !== 'string') {
+        throw new Error('[Planu upgrade] Persisted upgrade journal is unsafe or corrupt');
+    }
+    return parsed;
+}
+async function writeJournal(path, journal, writeFile) {
+    await writeFile(path, `${JSON.stringify(journal, null, 2)}\n`);
+}
+async function readUpgradeFile(path, code, message) {
+    try {
+        return await readFile(path, 'utf8');
+    }
+    catch (error) {
+        /* reliability-optional: UPGRADE_FILE_READ_FAILED */
+        reportClassifiedDegradation(code, error);
+        throw new Error(message, { cause: error });
+    }
+}
+async function recoverInterruptedUpgradeLocked(manifestPath, assertFence, dependencies = {}) {
+    const path = upgradeJournalPath(manifestPath);
+    const raw = await readFile(path, 'utf8').catch((error) => {
+        if (error.code === 'ENOENT') {
+            return null;
+        }
+        /* reliability-optional: UPGRADE_JOURNAL_READ_FAILED */
+        reportClassifiedDegradation('UPGRADE_JOURNAL_READ_FAILED', error);
+        throw new Error('[Planu upgrade] Persisted upgrade journal is unreadable');
+    });
+    if (raw === null) {
+        return false;
+    }
+    const journal = parseJournal(raw, manifestPath);
+    if (journal.state === 'committed') {
+        await assertFence();
+        await rm(path, { force: true });
+        return true;
+    }
+    const writeFile = dependencies.writeFile ??
+        ((target, content) => atomicWriteFile(target, content, { mode: 0o600 }));
+    for (const adapter of journal.adapters) {
+        await assertFence();
+        await writeFile(adapter.configPath, adapter.original);
+    }
+    await assertFence();
+    await writeFile(manifestPath, journal.originalManifest);
+    await assertFence();
+    if (journal.originalTrustState === null) {
+        await rm(journal.trustStatePath, { force: true });
+    }
+    else {
+        await writeFile(journal.trustStatePath, journal.originalTrustState);
+    }
+    await rm(path, { force: true });
+    return true;
+}
+export async function recoverInterruptedUpgrade(manifestPath, dependencies = {}) {
+    return withUpgradeLock(manifestPath, (assertFence) => recoverInterruptedUpgradeLocked(manifestPath, assertFence, dependencies));
+}
+function exactConfiguredVersion(record, config) {
+    if (typeof config !== 'object' || config === null || Array.isArray(config)) {
+        return null;
+    }
+    const root = config;
+    let command;
+    let args;
+    if (record.format === 'zed') {
+        const servers = root.context_servers;
+        const planu = servers?.planu;
+        const commandEntry = planu?.command;
+        command = commandEntry?.path;
+        args = commandEntry?.args;
+    }
+    else {
+        const servers = root.mcpServers;
+        const planu = servers?.planu;
+        command = planu?.command;
+        args = planu?.args;
+    }
+    if (command !== 'npx' || !Array.isArray(args)) {
+        return null;
+    }
+    const packageArgs = args.filter((arg) => typeof arg === 'string' && arg.startsWith(PACKAGE_PREFIX));
+    return packageArgs.length === 1 ? (packageArgs[0]?.slice(PACKAGE_PREFIX.length) ?? null) : null;
+}
+function buildUpdatedConfig(record, raw, version) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error('[Planu upgrade] An inventoried adapter contains invalid JSON', {
+            cause: error,
+        });
+    }
+    if (exactConfiguredVersion(record, parsed) !== record.version) {
+        throw new Error('[Planu upgrade] An inventoried adapter no longer matches the verified inventory version');
+    }
+    const root = parsed;
+    const entry = buildPinnedEntry(version);
+    if (record.format === 'zed') {
+        const servers = root.context_servers ?? {};
+        root.context_servers = {
+            ...servers,
+            planu: { command: { path: entry.command, args: entry.args } },
+        };
+    }
+    else {
+        const servers = root.mcpServers ?? {};
+        root.mcpServers = { ...servers, planu: entry };
+    }
+    return `${JSON.stringify(root, null, 2)}\n`;
+}
+async function prepareAdapters(installations, version) {
+    const seen = new Set();
+    const prepared = [];
+    for (const record of installations) {
+        if (seen.has(record.configPath)) {
+            throw new Error('[Planu upgrade] Installation inventory contains a duplicate adapter');
+        }
+        seen.add(record.configPath);
+        const original = await readUpgradeFile(record.configPath, 'UPGRADE_ADAPTER_READ_FAILED', '[Planu upgrade] An inventoried adapter is unreadable');
+        prepared.push({ record, original, updated: buildUpdatedConfig(record, original, version) });
+    }
+    return prepared;
+}
+async function inject(dependencies, context) {
+    await dependencies.faultInjector?.(context);
+}
+async function rollback(prepared, manifestPath, originalManifest, trustStatePath, originalTrustState, writeFile, assertFence) {
+    const failures = [];
+    for (const adapter of prepared) {
+        try {
+            await writeFile(adapter.record.configPath, adapter.original);
+        }
+        catch (error) {
+            /* reliability-cleanup: ADAPTER_ROLLBACK_FAILURE — aggregate failure throws below */
+            reportClassifiedDegradation('ADAPTER_ROLLBACK_FAILURE', error);
+            failures.push(`adapter rollback: ${redactFailureMessage(error)}`);
+        }
+    }
+    try {
+        await writeFile(manifestPath, originalManifest);
+    }
+    catch (error) {
+        /* reliability-cleanup: MANIFEST_ROLLBACK_FAILURE — aggregate failure throws below */
+        reportClassifiedDegradation('MANIFEST_ROLLBACK_FAILURE', error);
+        failures.push(`manifest rollback: ${redactFailureMessage(error)}`);
+    }
+    try {
+        if (originalTrustState === null) {
+            await assertFence();
+            await rm(trustStatePath, { force: true });
+        }
+        else {
+            await writeFile(trustStatePath, originalTrustState);
+        }
+    }
+    catch (error) {
+        /* reliability-cleanup: TRUST_ROLLBACK_FAILURE — aggregate failure throws below */
+        reportClassifiedDegradation('TRUST_ROLLBACK_FAILURE', error);
+        failures.push(`trust rollback: ${redactFailureMessage(error)}`);
+    }
+    if (failures.length > 0) {
+        throw new Error(`Global rollback was incomplete: ${failures.join('; ')}`);
+    }
+}
+// eslint-disable-next-line max-lines-per-function -- one ordered transaction keeps journal and rollback phases auditable
+async function upgradeInventoriedAdaptersLocked(manifestPath, version, dependencies, assertFence) {
+    if (!EXACT_VERSION.test(version)) {
+        throw new Error(`Upgrade target must be an exact semantic version: ${version}`);
+    }
+    await recoverInterruptedUpgradeLocked(manifestPath, assertFence, dependencies);
+    const originalManifest = await readUpgradeFile(manifestPath, 'UPGRADE_MANIFEST_READ_FAILED', '[Planu upgrade] Installation inventory is unreadable');
+    const trustPath = upgradeTrustStatePath(manifestPath);
+    const originalTrustState = await readFile(trustPath, 'utf8').catch((error) => {
+        if (error.code === 'ENOENT') {
+            return null;
+        }
+        /* reliability-optional: UPGRADE_TRUST_READ_FAILED */
+        reportClassifiedDegradation('UPGRADE_TRUST_READ_FAILED', error);
+        throw new Error('[Planu upgrade] Last-known-good trust state is unreadable');
+    });
+    let manifest;
+    try {
+        manifest = readInstallationManifest(manifestPath);
+    }
+    catch (error) {
+        /* reliability-optional: UPGRADE_MANIFEST_PARSE_FAILED */
+        reportClassifiedDegradation('UPGRADE_MANIFEST_PARSE_FAILED', error);
+        throw new Error('[Planu upgrade] Installation inventory is invalid', {
+            cause: error,
+        });
+    }
+    if (manifest.installations.length === 0) {
+        throw new Error('Cannot upgrade: installation inventory is empty.');
+    }
+    const versions = new Set(manifest.installations.map((record) => record.version));
+    if (versions.size !== 1) {
+        throw new Error('Cannot establish a single previously verified version from the inventory.');
+    }
+    const previousVersion = manifest.installations[0]?.version;
+    if (previousVersion === undefined || !EXACT_VERSION.test(previousVersion)) {
+        throw new Error('Cannot establish the previously verified version.');
+    }
+    const trustState = await readUpgradeTrustState(manifestPath);
+    if (trustState !== null && trustState.lastKnownGoodVersion !== previousVersion) {
+        throw new Error(`Cannot upgrade: inventory ${previousVersion} differs from last-known-good ${trustState.lastKnownGoodVersion}.`);
+    }
+    assertVersionNotQuarantined(trustState, version);
+    const prepared = await prepareAdapters(manifest.installations, version);
+    const now = dependencies.now ?? (() => new Date());
+    let verification;
+    try {
+        verification = await (dependencies.stageAndVerify ?? stageAndVerifyRelease)(version);
+    }
+    catch (error) {
+        await assertFence();
+        await quarantineUpgradeVersion(manifestPath, previousVersion, version, 'verification-failed', now());
+        throw error;
+    }
+    if (verification.version !== version) {
+        await assertFence();
+        await quarantineUpgradeVersion(manifestPath, previousVersion, version, 'verification-failed', now());
+        throw new Error(`Release verifier returned ${verification.version}; expected exact target ${version}.`);
+    }
+    await inject(dependencies, { phase: 'after-runtime-verification', switchedAdapters: 0 });
+    const writeFile = dependencies.writeFile ??
+        ((path, content) => atomicWriteFile(path, content, { mode: 0o600 }));
+    const fencedWriteFile = async (path, content) => {
+        await assertFence();
+        await writeFile(path, content);
+    };
+    let switchedAdapters = 0;
+    const journalPath = upgradeJournalPath(manifestPath);
+    let journal = {
+        schemaVersion: 2,
+        state: 'prepared',
+        manifestPath,
+        previousVersion,
+        targetVersion: version,
+        originalManifest,
+        trustStatePath: trustPath,
+        originalTrustState,
+        adapters: prepared.map((adapter) => ({
+            configPath: adapter.record.configPath,
+            original: adapter.original,
+        })),
+        switchedPaths: [],
+        updatedAt: now().toISOString(),
+    };
+    await writeJournal(journalPath, journal, fencedWriteFile);
+    try {
+        for (const adapter of prepared) {
+            await inject(dependencies, {
+                phase: 'before-adapter-switch',
+                adapter: adapter.record,
+                switchedAdapters,
+            });
+            await fencedWriteFile(adapter.record.configPath, adapter.updated);
+            switchedAdapters += 1;
+            journal = {
+                ...journal,
+                state: 'switching',
+                switchedPaths: [...journal.switchedPaths, adapter.record.configPath],
+                updatedAt: now().toISOString(),
+            };
+            await writeJournal(journalPath, journal, fencedWriteFile);
+            await inject(dependencies, {
+                phase: 'after-adapter-switch',
+                adapter: adapter.record,
+                switchedAdapters,
+            });
+        }
+        await inject(dependencies, { phase: 'before-manifest-switch', switchedAdapters });
+        const installedAt = now().toISOString();
+        const updatedManifest = {
+            ...manifest,
+            updatedAt: installedAt,
+            installations: manifest.installations.map((record) => ({
+                ...record,
+                version,
+                offline: false,
+                installedAt,
+            })),
+        };
+        await fencedWriteFile(manifestPath, `${JSON.stringify(updatedManifest, null, 2)}\n`);
+        await inject(dependencies, { phase: 'after-manifest-switch', switchedAdapters });
+        await assertFence();
+        await markUpgradeVerified(manifestPath, version, verification.verifiedAt);
+        journal = {
+            ...journal,
+            state: 'trust-switched',
+            updatedAt: installedAt,
+        };
+        await writeJournal(journalPath, journal, fencedWriteFile);
+        await inject(dependencies, { phase: 'after-trust-switch', switchedAdapters });
+        journal = {
+            ...journal,
+            state: 'committed',
+            updatedAt: installedAt,
+        };
+        await writeJournal(journalPath, journal, fencedWriteFile);
+        await assertFence();
+        await rm(journalPath, { force: true });
+        return {
+            previousVersion,
+            version,
+            switchedAdapters,
+            manifest: updatedManifest,
+            verification,
+        };
+    }
+    catch (error) {
+        if (error instanceof UpgradeInterruptionError) {
+            throw error;
+        }
+        try {
+            await rollback(prepared, manifestPath, originalManifest, trustPath, originalTrustState, fencedWriteFile, assertFence);
+            await assertFence();
+            await rm(journalPath, { force: true });
+        }
+        catch (rollbackError) {
+            /* reliability-cleanup: UPGRADE_ROLLBACK_INCOMPLETE */
+            reportClassifiedDegradation('UPGRADE_ROLLBACK_INCOMPLETE', rollbackError);
+            throw new AggregateError([new Error(redactFailureMessage(error)), new Error(redactFailureMessage(rollbackError))], `Upgrade to ${version} failed and global rollback was incomplete.`, { cause: rollbackError });
+        }
+        try {
+            await assertFence();
+            await quarantineUpgradeVersion(manifestPath, previousVersion, version, 'activation-failed', now());
+        }
+        catch (quarantineError) {
+            /* reliability-cleanup: UPGRADE_QUARANTINE_FAILED */
+            reportClassifiedDegradation('UPGRADE_QUARANTINE_FAILED', quarantineError);
+            throw new AggregateError([new Error(redactFailureMessage(error)), new Error(redactFailureMessage(quarantineError))], `Upgrade to ${version} rolled back but quarantine persistence failed.`, { cause: quarantineError });
+        }
+        reportClassifiedDegradation('UPGRADE_ACTIVATION_FAILED', error);
+        const symptom = new Error(`Upgrade to ${version} failed; all adapters restored to ${previousVersion}.`);
+        throw symptom;
+    }
+}
+export async function upgradeInventoriedAdapters(manifestPath, version, dependencies = {}) {
+    return withUpgradeLock(manifestPath, (assertFence) => upgradeInventoriedAdaptersLocked(manifestPath, version, dependencies, assertFence));
+}
+//# sourceMappingURL=atomic-upgrade.js.map

package/dist/engine/auto-updater/config-detector.js

@@ -5,6 +5,7 @@ import { readFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { PLANU_VERSION } from '../../config/version.js';
+import { reportClassifiedDegradation } from '../../errors/classified-degradation.js';
 // ---------------------------------------------------------------------------
 // Config path resolution
 // ---------------------------------------------------------------------------
@@ -34,8 +35,11 @@ export async function findMcpConfig() {
             await readFile(candidate.path, 'utf-8');
             return { configPath: candidate.path, configType: candidate.type };
         }
-        catch {
-            // File does not exist or is not readable — try next
+        catch (error) {
+            /* reliability-optional: MCP_CONFIG_CANDIDATE_UNREADABLE */
+            if (error.code !== 'ENOENT') {
+                reportClassifiedDegradation('MCP_CONFIG_CANDIDATE_UNREADABLE', error);
+            }
         }
     }
     return { configPath: null, configType: null };
@@ -84,7 +88,9 @@ export async function detectPlanuInstall() {
         const raw = await readFile(location.configPath, 'utf-8');
         config = JSON.parse(raw);
     }
-    catch {
+    catch (error) {
+        /* reliability-optional: MCP_CONFIG_PARSE_FAILED */
+        reportClassifiedDegradation('MCP_CONFIG_PARSE_FAILED', error);
         return {
             method: 'unknown',
             currentVersion: PLANU_VERSION,

package/dist/engine/auto-updater/config-patcher.d.ts

@@ -14,10 +14,6 @@ export declare function patchPlanuEntry(configPath: string, newEntry: McpServerE
     backupPath: string;
     previousEntry: McpServerEntry | null;
 }>;
-/**
- * Returns the standard npx @latest entry for Planu.
- */
-export declare function buildNpxLatestEntry(): McpServerEntry;
 /**
  * Returns an npx entry pinned to a specific version.
  */

package/dist/engine/auto-updater/config-patcher.js

@@ -2,7 +2,9 @@
 // engine/auto-updater/config-patcher.ts — Patches the MCP config file to enable auto-update.
 // SPEC-443
 // Creates a backup before any modification. Restores backup on write failure.
-import { readFile, writeFile } from 'node:fs/promises';
+import { readFile } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { atomicWriteFile } from '../safety/atomic-write-file.js';
 export const PLANU_MCP_STARTUP_TIMEOUT_SEC = 120;
 // ---------------------------------------------------------------------------
 // Helpers
@@ -11,7 +13,7 @@ function dateStr() {
     return new Date().toISOString().slice(0, 10);
 }
 function backupPathFor(configPath) {
-    return configPath.replace(/\.json$/, `.backup-${dateStr()}.json`);
+    return configPath.replace(/\.json$/, `.backup-${dateStr()}-${randomUUID()}.json`);
 }
 // ---------------------------------------------------------------------------
 // Patch operations
@@ -39,7 +41,7 @@ export async function patchPlanuEntry(configPath, newEntry) {
     const previousEntry = config.mcpServers?.planu ?? null;
     // Create backup BEFORE modifying anything
     const backupPath = backupPathFor(configPath);
-    await writeFile(backupPath, raw, 'utf-8');
+    await atomicWriteFile(backupPath, raw, { mode: 0o600 });
     // Patch
     const updated = {
         ...config,
@@ -49,29 +51,22 @@ export async function patchPlanuEntry(configPath, newEntry) {
         },
     };
     try {
-        await writeFile(configPath, JSON.stringify(updated, null, 2) + '\n', 'utf-8');
+        await atomicWriteFile(configPath, JSON.stringify(updated, null, 2) + '\n', { mode: 0o600 });
     }
     catch (writeErr) {
         // Restore from backup
-        await writeFile(configPath, raw, 'utf-8');
+        await atomicWriteFile(configPath, raw, { mode: 0o600 });
         throw new Error(`Failed to write updated config to ${configPath}. Restored original from backup. Error: ${String(writeErr)}`, { cause: writeErr });
     }
     return { backupPath, previousEntry };
 }
-/**
- * Returns the standard npx @latest entry for Planu.
- */
-export function buildNpxLatestEntry() {
-    return {
-        command: 'npx',
-        args: ['-y', '@planu/cli@latest'],
-        startup_timeout_sec: PLANU_MCP_STARTUP_TIMEOUT_SEC,
-    };
-}
 /**
  * Returns an npx entry pinned to a specific version.
  */
 export function buildPinnedEntry(version) {
+    if (!/^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)$/.test(version)) {
+        throw new Error(`[Planu] Refusing non-exact CLI version: ${version}`);
+    }
     return {
         command: 'npx',
         args: ['-y', `@planu/cli@${version}`],

package/dist/engine/auto-updater/index.d.ts

@@ -1,10 +1,12 @@
 import type { EnableAutoUpdateResult, PinVersionResult, UpdateCheckResult } from '../../types/auto-update.js';
+export { upgradeInventoriedAdapters } from './atomic-upgrade.js';
+export { stageAndVerifyRelease } from './release-verifier.js';
 /**
  * Checks the current install info and npm registry for update availability.
  */
 export declare function checkForUpdates(): Promise<UpdateCheckResult>;
 /**
- * Enables auto-update by patching the MCP config to use npx @planu/cli@latest.
+ * Resolves a verified release and pins the MCP config to that exact version.
  * If confirm is false (default), returns a preview of changes without applying.
  * If confirm is true, applies the change immediately.
  */

package/dist/engine/auto-updater/index.js

@@ -1,9 +1,14 @@
 // engine/auto-updater/index.ts — Public API for the auto-updater engine.
 // SPEC-443
+import { existsSync } from 'node:fs';
 import { detectPlanuInstall } from './config-detector.js';
-import { buildNpxLatestEntry, buildPinnedEntry, patchPlanuEntry } from './config-patcher.js';
+import { buildPinnedEntry } from './config-patcher.js';
 import { fetchLatestVersion } from './npm-registry.js';
 import { PLANU_VERSION } from '../../config/version.js';
+import { resolveStorageLayout } from '../../storage/storage-layout.js';
+import { upgradeInventoriedAdapters } from './atomic-upgrade.js';
+export { upgradeInventoriedAdapters } from './atomic-upgrade.js';
+export { stageAndVerifyRelease } from './release-verifier.js';
 // ---------------------------------------------------------------------------
 // check_update_status
 // ---------------------------------------------------------------------------
@@ -16,20 +21,21 @@ export async function checkForUpdates() {
         fetchLatestVersion(),
     ]);
     const isUpToDate = latestVersion === null ? true : latestVersion === installInfo.currentVersion;
-    const autoUpdateActive = installInfo.method === 'npx-latest';
+    // Legacy @latest entries are detected but never considered a safe active mode.
+    const autoUpdateActive = false;
     let updateCommand;
-    if (autoUpdateActive) {
+    if (installInfo.method === 'npx-latest') {
         updateCommand =
-            'Auto-update is active — Planu updates automatically on each Claude session start.';
+            'Legacy unpinned entry detected; run enable_auto_update to pin an exact release.';
     }
     else if (installInfo.method === 'global') {
-        updateCommand = 'npm install -g @planu/cli@latest';
+        updateCommand = `npm install -g @planu/cli@${latestVersion ?? PLANU_VERSION}`;
     }
     else if (installInfo.method === 'local-path') {
         updateCommand = 'Update your local installation and rebuild.';
     }
     else {
-        updateCommand = 'Run enable_auto_update to switch to npx @latest for automatic updates.';
+        updateCommand = 'Run enable_auto_update to resolve and pin the latest verified version.';
     }
     return {
         currentVersion: installInfo.currentVersion,
@@ -44,11 +50,19 @@ export async function checkForUpdates() {
 // enable_auto_update
 // ---------------------------------------------------------------------------
 /**
- * Enables auto-update by patching the MCP config to use npx @planu/cli@latest.
+ * Resolves a verified release and pins the MCP config to that exact version.
  * If confirm is false (default), returns a preview of changes without applying.
  * If confirm is true, applies the change immediately.
  */
 export async function enableAutoUpdate(confirm, overrideConfigPath) {
+    if (process.env.PLANU_OFFLINE === '1') {
+        throw new Error('Auto-update is unavailable while PLANU_OFFLINE=1. Pin an installed version.');
+    }
+    const latestVersion = await fetchLatestVersion();
+    if (latestVersion === null) {
+        throw new Error('Could not resolve an exact Planu version; no config changes were made.');
+    }
+    const resolvedEntry = buildPinnedEntry(latestVersion);
     let installInfo;
     if (overrideConfigPath !== undefined) {
         // Build a minimal install info using the override path
@@ -62,21 +76,11 @@ export async function enableAutoUpdate(confirm, overrideConfigPath) {
     else {
         installInfo = await detectPlanuInstall();
     }
-    if (installInfo.method === 'npx-latest') {
-        return {
-            configPath: installInfo.configPath ?? '(unknown)',
-            previousEntry: installInfo.mcpEntry,
-            newEntry: buildNpxLatestEntry(),
-            backupPath: '',
-            alreadyOptimal: true,
-            message: 'Auto-update is already active. Planu uses npx @planu/cli@latest — it updates automatically on each Claude session start.',
-        };
-    }
     if (installInfo.configPath === null) {
         throw new Error('Could not find MCP config file (~/.claude.json or Claude Desktop config). ' +
             'Please specify the path manually using the configPath parameter.');
     }
-    const newEntry = buildNpxLatestEntry();
+    const newEntry = resolvedEntry;
     if (!confirm) {
         return {
             configPath: installInfo.configPath,
@@ -85,20 +89,27 @@ export async function enableAutoUpdate(confirm, overrideConfigPath) {
             backupPath: '',
             alreadyOptimal: false,
             message: `Preview: The planu entry in ${installInfo.configPath} will be updated to use ` +
-                `"command": "npx", "args": ["-y", "@planu/cli@latest"]. ` +
+                `"command": "npx", "args": ["-y", "@planu/cli@${latestVersion}"]. ` +
                 'Call enable_auto_update with confirm=true to apply.',
         };
     }
-    const { backupPath, previousEntry } = await patchPlanuEntry(installInfo.configPath, newEntry);
+    if (overrideConfigPath !== undefined) {
+        throw new Error('Direct config-path updates are not recoverable. Run planu install to inventory the adapter first.');
+    }
+    const manifestPath = resolveStorageLayout().installationManifest;
+    if (!existsSync(manifestPath)) {
+        throw new Error('Auto-update requires an installation inventory and last-known-good rollback target. Run planu install first.');
+    }
+    const upgraded = await upgradeInventoriedAdapters(manifestPath, latestVersion);
     return {
         configPath: installInfo.configPath,
-        previousEntry,
+        previousEntry: installInfo.mcpEntry,
         newEntry,
-        backupPath,
+        backupPath: '',
         alreadyOptimal: false,
-        message: `Auto-update enabled. Config updated at ${installInfo.configPath}. ` +
-            `Backup saved to ${backupPath}. ` +
-            'Restart Claude to activate the change.',
+        message: `Verified version ${latestVersion} staged and smoke-tested. ` +
+            `${String(upgraded.switchedAdapters)} inventoried adapter(s) switched atomically; ` +
+            `global rollback target was ${upgraded.previousVersion}. Restart your AI tools to activate.`,
     };
 }
 // ---------------------------------------------------------------------------
@@ -113,7 +124,6 @@ export async function pinVersion(version, confirm) {
     if (installInfo.configPath === null) {
         throw new Error('Could not find MCP config file. Please ensure Claude Code or Claude Desktop is configured.');
     }
-    const pinnedEntry = buildPinnedEntry(version);
     if (!confirm) {
         return {
             configPath: installInfo.configPath,
@@ -124,14 +134,18 @@ export async function pinVersion(version, confirm) {
                 'To return to auto-update, call enable_auto_update.',
         };
     }
-    const { backupPath } = await patchPlanuEntry(installInfo.configPath, pinnedEntry);
+    const manifestPath = resolveStorageLayout().installationManifest;
+    if (!existsSync(manifestPath)) {
+        throw new Error('Pinning requires an installation inventory and last-known-good rollback target. Run planu install first.');
+    }
+    await upgradeInventoriedAdapters(manifestPath, version);
     return {
         configPath: installInfo.configPath,
         pinnedVersion: version,
-        backupPath,
+        backupPath: '',
         message: `Version pinned to @planu/cli@${version} in ${installInfo.configPath}. ` +
-            `Backup saved to ${backupPath}. ` +
-            'Restart Claude to activate. To return to auto-update, call enable_auto_update.',
+            'The previously verified release remains available for rollback. ' +
+            'Restart your AI tools to activate. To return to auto-update, call enable_auto_update.',
     };
 }
 //# sourceMappingURL=index.js.map