create-principles-disciple 1.131.2 → 1.132.1

package/console/dist/server/routes/update.js

@@ -713,8 +713,148 @@ function depsMeaningfullyChanged(oldDeps, newDeps) {
     return aKeys.some((k, i) => bKeys[i] !== k || a[k] !== b[k]);
 }
 /**
- * Create the node_modules resolution links for the installed components, if
- * missing.
+ * Move the current occupant of a dependency slot aside (same-directory
+ * rename: same volume, atomic, reversible). The quarantine name starts with
+ * a dot and is not a valid package name, so npm module resolution ignores it.
+ */
+function quarantineSlot(slot) {
+    try {
+        const quarantinePath = path.join(path.dirname(slot), `.${path.basename(slot)}.update-quarantine-${Date.now()}`);
+        fs.renameSync(slot, quarantinePath);
+        return { slot, quarantinePath };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Restore quarantined slots to their original locations (update failure
+ * path). The slot at that point holds the link reconciliation created —
+ * unlink removes the link itself, never its target. Best-effort, never
+ * throws; failures are logged (rc-9: observable degradation).
+ */
+function restoreQuarantined(quarantined) {
+    for (const entry of [...quarantined].reverse()) {
+        try {
+            try {
+                fs.unlinkSync(entry.slot);
+            }
+            catch { /* slot may already be gone */ }
+            fs.renameSync(entry.quarantinePath, entry.slot);
+        }
+        catch (error) {
+            console.error(`[pd-console:update] failed to restore quarantined dependency entry ${entry.slot}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+}
+/**
+ * Discard quarantined slots (update success path). The quarantined entries
+ * are stale pre-update copies of internal @principles packages; the new
+ * canonical components are installed by the copy steps. Best-effort,
+ * failures are logged and non-fatal (rc-9).
+ */
+function cleanupQuarantined(quarantined) {
+    for (const entry of quarantined) {
+        try {
+            fs.rmSync(entry.quarantinePath, { recursive: true, force: true });
+        }
+        catch (error) {
+            console.warn(`[pd-console:update] failed to clean quarantined dependency entry ${entry.quarantinePath}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+}
+/**
+ * True when the link at linkPath resolves to exactly `target` (string
+ * comparison — the target dir may legitimately not exist yet at
+ * reconciliation time). Windows paths compare case-insensitively.
+ */
+function linkPointsAt(linkPath, target) {
+    const resolved = path.resolve(path.dirname(linkPath), fs.readlinkSync(linkPath));
+    const expected = path.resolve(target);
+    return process.platform === 'win32'
+        ? resolved.toLowerCase() === expected.toLowerCase()
+        : resolved === expected;
+}
+function createResolutionLink(linkPath, target) {
+    try {
+        fs.mkdirSync(path.dirname(linkPath), { recursive: true });
+        if (process.platform === 'win32') {
+            fs.symlinkSync(target, linkPath, 'junction');
+        }
+        else {
+            fs.symlinkSync(path.relative(path.dirname(linkPath), target), linkPath, 'dir');
+        }
+        return undefined;
+    }
+    catch (error) {
+        return `Failed to create runtime resolution link at ${linkPath}: ${error instanceof Error ? error.message : String(error)}`;
+    }
+}
+/**
+ * Reconcile ONE deployed dependency slot against its canonical target
+ * (PRI-665, 2026-09-03 incident). The previous "existsSync → skip" logic
+ * silently kept stale PHYSICAL copies of internal @principles packages that
+ * legacy installs had left in these slots, so the updated dist resolved the
+ * old components and crashed at startup. Semantics:
+ *
+ *   - missing slot              → create the link (fresh installs);
+ *   - link pointing at target   → keep (npm- or installer-created);
+ *   - wrong-target link         → quarantine + replace;
+ *   - physical dir / plain file → quarantine + replace (the incident shape).
+ *
+ * Returns an error message on failure (the slot is rolled back first), or
+ * undefined; a successful quarantine is recorded in `quarantined` for the
+ * caller to restore on failure / discard on success.
+ */
+function reconcileResolutionLink(linkPath, target, quarantined) {
+    let stat;
+    try {
+        stat = fs.lstatSync(linkPath);
+    }
+    catch {
+        stat = undefined; // ENOENT — create below
+    }
+    if (stat === undefined) {
+        return createResolutionLink(linkPath, target);
+    }
+    if (stat.isSymbolicLink()) {
+        try {
+            if (linkPointsAt(linkPath, target))
+                return undefined; // correct link — keep
+        }
+        catch {
+            // Unreadable link target — fall through to replace.
+        }
+    }
+    const entry = quarantineSlot(linkPath);
+    if (entry === undefined) {
+        return `Failed to quarantine the existing dependency entry at ${linkPath} (required to install the canonical resolution link). Resolve any file locks and retry the update.`;
+    }
+    const error = createResolutionLink(linkPath, target);
+    if (error) {
+        // Roll this slot back before failing — the install stays untouched
+        // (the PRI-561 fail-closed ordering contract).
+        try {
+            fs.unlinkSync(linkPath);
+        }
+        catch { /* nothing we created */ }
+        try {
+            fs.renameSync(entry.quarantinePath, entry.slot);
+        }
+        catch {
+            // The in-slot rename failed (e.g. a transient lock). Hand the entry to
+            // the outer rollback so it retries the restore — restoreQuarantined
+            // tolerates a missing slot when unlinking before renaming back.
+            quarantined.push(entry);
+        }
+        return error;
+    }
+    quarantined.push(entry);
+    return undefined;
+}
+/**
+ * Create or RECONCILE the node_modules resolution links for the installed
+ * components.
  *
  * Mirrors installer.ts syncPdCli: junction on Windows (no elevation needed),
  * relative symlink elsewhere. Fresh installs get these links via npm install
@@ -738,8 +878,11 @@ function depsMeaningfullyChanged(oldDeps, newDeps) {
  *      host-runtime/node_modules/@principles/install-layout missing and
  *      every pd-cli runtime command failing with ERR_MODULE_NOT_FOUND.
  *
- * Returns undefined on success, or an error message (rc-9: observable, never
- * silent — a missing link means the updated console cannot start).
+ * Returns { error } on failure with every quarantine rolled back (rc-9:
+ * observable, never silent — a missing or unreconciled link means the
+ * updated console cannot start), or { quarantined } listing the dependency
+ * entries replaced during reconciliation. The caller restores the
+ * quarantined entries if a LATER step fails, and discards them on success.
  */
 function ensureRuntimeResolutionLinks(layout, tempDir) {
     const links = [
@@ -784,47 +927,35 @@ function ensureRuntimeResolutionLinks(layout, tempDir) {
         }
     };
     const fileDepSpecs = collectFileDepLinkSpecs(stagedComponents, readStagedDependencies);
-    const createResolutionLink = (linkPath, target) => {
-        // Idempotent: never overwrite an existing link or directory (fresh
-        // installs have npm-created real dirs in these slots).
-        if (fs.existsSync(linkPath))
-            return undefined;
-        try {
-            fs.mkdirSync(path.dirname(linkPath), { recursive: true });
-            if (process.platform === 'win32') {
-                fs.symlinkSync(target, linkPath, 'junction');
-            }
-            else {
-                fs.symlinkSync(path.relative(path.dirname(linkPath), target), linkPath, 'dir');
-            }
-            return undefined;
-        }
-        catch (error) {
-            return `Failed to create runtime resolution link at ${linkPath}: ${error instanceof Error ? error.message : String(error)}`;
-        }
-    };
+    const quarantined = [];
     // Pass 1 — explicit known-critical links, fail-closed BEFORE any byte is
-    // swapped (a link-creation failure aborts with the installed packages
-    // untouched: the PRI-561 ordering contract).
+    // swapped (a link-reconciliation failure aborts with the installed packages
+    // untouched: the PRI-561 ordering contract). Existing entries are
+    // RECONCILED, not skipped: a correct link is kept, but a stale physical
+    // copy or a wrong-target link is quarantined and replaced (PRI-665,
+    // 2026-09-03: legacy installs left physical @principles copies in these
+    // slots and updated dists crashed resolving them).
     for (const { linkPath, target } of links) {
         if (!fs.existsSync(target))
             continue;
-        const error = createResolutionLink(linkPath, target);
-        if (error)
-            return error;
+        const error = reconcileResolutionLink(linkPath, target, quarantined);
+        if (error) {
+            restoreQuarantined(quarantined);
+            return { error, quarantined: [] };
+        }
     }
     // Pass 2 — data-driven derived links. Their deployed target dir may be
     // created by the copy steps that follow (a brand-new component's dir does
     // not exist yet); each staged target's existence was already proven by the
     // extraction, and the copies below run unconditionally.
     for (const spec of fileDepSpecs) {
-        if (fs.existsSync(spec.linkPath))
-            continue;
-        const error = createResolutionLink(spec.linkPath, spec.target);
-        if (error)
-            return error;
+        const error = reconcileResolutionLink(spec.linkPath, spec.target, quarantined);
+        if (error) {
+            restoreQuarantined(quarantined);
+            return { error, quarantined: [] };
+        }
     }
-    return undefined;
+    return { quarantined };
 }
 async function doInlineFullUpdate(workspaceDir) {
     const layout = resolveUpdateLayout();
@@ -861,6 +992,9 @@ async function doInlineFullUpdate(workspaceDir) {
     // overwrites it (PR #1332 companion — see reapplySkillLanguage).
     const skillLanguage = detectInstalledSkillLanguage(extDir);
     let tempDir;
+    // Dependency entries quarantined during resolution-link reconciliation;
+    // restored on failure, discarded on success (PRI-665).
+    let reconciledQuarantine = [];
     try {
         // 2. Fetch installer package info from npm
         const response = await fetchWithRetry(NPM_REGISTRY_INSTALLER, 'Installer registry check');
@@ -1018,7 +1152,8 @@ async function doInlineFullUpdate(workspaceDir) {
             if (fs.existsSync(path.join(installLayoutSrc, 'package.json')) && fs.existsSync(path.join(installLayoutSrc, 'dist'))) {
                 copyDirRecursive(installLayoutSrc, layout.installLayoutDir, SKIP_DIRS);
             }
-            const linkError = ensureRuntimeResolutionLinks(layout, tempDir);
+            const { error: linkError, quarantined } = ensureRuntimeResolutionLinks(layout, tempDir);
+            reconciledQuarantine = quarantined;
             if (linkError) {
                 appendUpdateHistory(workspaceDir, {
                     fromVersion,
@@ -1078,6 +1213,13 @@ async function doInlineFullUpdate(workspaceDir) {
         if (tempDir && fs.existsSync(tempDir)) {
             fs.rmSync(tempDir, { recursive: true, force: true });
         }
+        // 6.5 Discard the quarantined stale dependency copies — the canonical
+        // components are in place now (PRI-665). Both the success return and the
+        // version-drift failure return flow through here with files already
+        // swapped, so restoring the stale copies would re-break resolution.
+        if (reconciledQuarantine.length > 0) {
+            cleanupQuarantined(reconciledQuarantine);
+        }
         // 7. Version-advance check (drift guard). The full update installs the
         // plugin bundled inside the installer. If the installer is stale (its
         // bundled plugin is NOT newer than what is installed), the "update" is a
@@ -1122,6 +1264,12 @@ async function doInlineFullUpdate(workspaceDir) {
         };
     }
     catch (error) {
+        // PRI-665: restore any dependency slots quarantined during link
+        // reconciliation FIRST — a failed update must not leave the install
+        // half-migrated (new dist with the old resolution quarantined away).
+        if (reconciledQuarantine.length > 0) {
+            restoreQuarantined(reconciledQuarantine);
+        }
         // Clean up temp dir on failure
         if (tempDir && fs.existsSync(tempDir)) {
             try {

package/dist/installer.d.ts

@@ -3,6 +3,7 @@ import { type ComponentStatus, type VerificationResult } from './mvp-config.js';
 import { type HostTarget } from './installers/index.js';
 import type { HostInstallResult } from '@principles/core/host';
 import { type SkillLanguage } from './skill-language.js';
+import { type ReleaseMetadataDigestSource, type TransactionState } from './update/transaction-journal.js';
 /** PRI-343: Keep in sync with @principles/core CONVERSATION_ACCESS_CONFIG_KEY */
 export declare const CONVERSATION_ACCESS_CONFIG_KEY: 'allowConversationAccess';
 /**
@@ -137,6 +138,19 @@ export interface InstallResult {
     consoleUrl?: string;
     /** ADR-0020 §2.3: Host-side install results (one per HostInstaller). */
     hostResults?: HostInstallResult[];
+    /** ADR-0024 D-2 (PRI-664): transaction journal record for this install.
+     * Undefined when the mutation never began (pre-mutation refusal/throw). */
+    journal?: InstallJournalRecord;
+}
+/** Observability record for one installer transaction (ADR-0024 D-2). */
+export interface InstallJournalRecord {
+    readonly transactionId: string;
+    /** Journal file: `~/.pd/transactions/<transactionId>.jsonl` (D-6, runtime scope). */
+    readonly journalPath: string;
+    /** True when a mid-flight journal append failed (Tier-2 degradation) and
+     * later transitions were skipped — the backup/restore safety net remained
+     * authoritative for this transaction. */
+    readonly degraded: boolean;
 }
 export interface InstallRunMode {
     /** Suppress human output (spinner / progress). True under --json. */
@@ -144,6 +158,28 @@ export interface InstallRunMode {
     /** No interactive prompts. True under --yes / --non-interactive / --json. */
     nonInteractive?: boolean;
 }
+interface InstallerJournal {
+    readonly transactionId: string;
+    readonly journalPath: string;
+    readonly releaseId: string;
+    readonly productVersion: string;
+    readonly releaseMetadataDigest: string;
+    /** PRI-664 review: provenance of releaseMetadataDigest ('manifest' | 'package_manifest' | 'fallback'). */
+    readonly releaseMetadataDigestSource: ReleaseMetadataDigestSource;
+    degraded: boolean;
+    /** Last successfully journaled state — the `from` for failure-path transitions. */
+    lastState: TransactionState | null;
+}
+/** Opens one installer transaction: `~/.pd/transactions/<transactionId>.jsonl`. */
+export declare function beginInstallerJournal(pluginDir: string): InstallerJournal;
+/**
+ * Append one transition durably (append + fsync) BEFORE the side effect it
+ * describes. Throws on failure — the caller decides Tier-1 (refuse before
+ * mutation) vs Tier-2 (degrade and continue).
+ */
+export declare function journalInstallerTransition(journal: InstallerJournal, from: TransactionState | null, to: TransactionState, detail: string): void;
+/** Tier-2 wrapper: on append failure, degrade (mark + warn) instead of throwing. */
+export declare function journalInstallerTransitionDegrading(journal: InstallerJournal, from: TransactionState | null, to: TransactionState, detail: string): void;
 export declare function install(options: InstallOptions, pluginDir: string, mode?: InstallRunMode): Promise<InstallResult>;
 export {};
 //# sourceMappingURL=installer.d.ts.map

package/dist/installer.d.ts.map

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

package/dist/installer.js

@@ -1,4 +1,5 @@
 import { existsSync, readdirSync, statSync, readFileSync, writeFileSync, mkdirSync, rmSync, copyFileSync, cpSync, renameSync, chmodSync, symlinkSync } from 'fs';
+import { createHash, randomUUID } from 'node:crypto';
 import fse from 'fs-extra';
 import * as path from 'path';
 import * as http from 'http';
@@ -13,6 +14,7 @@ import { getHostInstallers } from './installers/index.js';
 import { mergeInstallManifestWorkspaces, parseInstallManifest } from '@principles/install-layout';
 import { applySkillLanguageSelection } from './skill-language.js';
 import { parseReleaseAssetIdentity, parseReleaseAssetManifest, ReleaseAssetManifestError, verifyReleaseAssetManifestAsync, verifyReleaseAssetTarget, } from './update/release-asset-manifest.js';
+import { appendJournalTransition } from './update/transaction-journal.js';
 /** PRI-343: Keep in sync with @principles/core CONVERSATION_ACCESS_CONFIG_KEY */
 export const CONVERSATION_ACCESS_CONFIG_KEY = 'allowConversationAccess';
 function isRecord(value) {
@@ -1645,6 +1647,98 @@ async function runHostInstallers(host, ctx) {
     }
     return results;
 }
+function sha256File(filePath) {
+    return createHash('sha256').update(readFileSync(filePath)).digest('hex');
+}
+/**
+ * Identity of the payload being installed. Prefers the self-contained asset
+ * manifest (covers the whole payload); falls back to the bundled pd-cli
+ * package manifest. Both are REAL digests — the journal never stores a
+ * placeholder where a verifiable value is available (same discipline as
+ * legacy-migration.ts). The last-resort fallback hashes the literal reason
+ * string only to satisfy the journal's 64-hex format requirement; it is not
+ * part of any release-metadata identity chain.
+ */
+function resolveInstallerPayloadIdentity(pluginDir) {
+    let productVersion = 'unknown';
+    const pdCliPkgPath = path.join(pluginDir, 'pd-cli', 'package.json');
+    if (existsSync(pdCliPkgPath)) {
+        try {
+            const parsed = JSON.parse(readFileSync(pdCliPkgPath, 'utf8'));
+            if (typeof parsed.version === 'string' && parsed.version.length > 0)
+                productVersion = parsed.version;
+        }
+        catch {
+            // Identity falls back to 'unknown'; journaling must not brick install.
+        }
+    }
+    const assetManifestPath = path.join(pluginDir, '_release', 'manifest.json');
+    let releaseMetadataDigest;
+    let releaseMetadataDigestSource;
+    if (existsSync(assetManifestPath)) {
+        releaseMetadataDigest = sha256File(assetManifestPath);
+        releaseMetadataDigestSource = 'manifest';
+    }
+    else if (existsSync(pdCliPkgPath)) {
+        releaseMetadataDigest = sha256File(pdCliPkgPath);
+        releaseMetadataDigestSource = 'package_manifest';
+    }
+    else {
+        releaseMetadataDigest = createHash('sha256').update('installer-payload-missing-identity').digest('hex');
+        releaseMetadataDigestSource = 'fallback';
+    }
+    return { productVersion, releaseMetadataDigest, releaseMetadataDigestSource };
+}
+/** Opens one installer transaction: `~/.pd/transactions/<transactionId>.jsonl`. */
+export function beginInstallerJournal(pluginDir) {
+    const { productVersion, releaseMetadataDigest, releaseMetadataDigestSource } = resolveInstallerPayloadIdentity(pluginDir);
+    const transactionId = `install-${Date.now()}-${randomUUID().slice(0, 8)}`;
+    const journalPath = path.join(getPdDir(), 'transactions', `${transactionId}.jsonl`);
+    const releaseId = `bundled-${productVersion}-${releaseMetadataDigest.slice(0, 12)}`;
+    return { transactionId, journalPath, releaseId, productVersion, releaseMetadataDigest, releaseMetadataDigestSource, degraded: false, lastState: null };
+}
+/**
+ * Append one transition durably (append + fsync) BEFORE the side effect it
+ * describes. Throws on failure — the caller decides Tier-1 (refuse before
+ * mutation) vs Tier-2 (degrade and continue).
+ */
+// eslint-disable-next-line @typescript-eslint/max-params -- (from, to, detail) mirrors the JournalTransition shape it appends
+export function journalInstallerTransition(journal, from, to, detail) {
+    appendJournalTransition(journal.journalPath, {
+        at: new Date().toISOString(),
+        from,
+        to,
+        transactionId: journal.transactionId,
+        releaseId: journal.releaseId,
+        productVersion: journal.productVersion,
+        releaseMetadataDigest: journal.releaseMetadataDigest,
+        releaseMetadataDigestSource: journal.releaseMetadataDigestSource,
+        // The installer model has no active.json generation chain yet (it never
+        // writes active.json); generation continuity becomes ReleaseManager's
+        // responsibility when it takes over mutations (PRI-661).
+        generation: 1,
+        detail,
+    });
+    journal.lastState = to;
+}
+/** Tier-2 wrapper: on append failure, degrade (mark + warn) instead of throwing. */
+// eslint-disable-next-line @typescript-eslint/max-params -- (from, to, detail) mirrors the JournalTransition shape it appends
+export function journalInstallerTransitionDegrading(journal, from, to, detail) {
+    if (journal.degraded)
+        return;
+    try {
+        journalInstallerTransition(journal, from, to, detail);
+    }
+    catch (error) {
+        journal.degraded = true;
+        logger.error(`Transaction journal append failed at '${to}' — continuing under the backup/restore safety net; `
+            + `this transaction is partially journaled (ADR-0024 D-2 Tier-2 degradation): `
+            + `${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function installerJournalRecord(journal) {
+    return { transactionId: journal.transactionId, journalPath: journal.journalPath, degraded: journal.degraded };
+}
 export async function install(options, pluginDir, mode = {}) {
     // `quiet` (= jsonMode) suppresses human output / spinner. `nonInteractive`
     // (--yes/--non-interactive/--json) gates PROMPTING. They differ for `--yes`
@@ -1726,6 +1820,8 @@ export async function install(options, pluginDir, mode = {}) {
     const spinner = quiet ? null : ora('Installing...').start();
     let backupDir = null;
     let runtimeBackupDir = null;
+    // ADR-0024 D-2: non-null once the transaction is planned (first mutation is imminent).
+    let journal = null;
     let installManifestHosts;
     const components = { plugin: 'skipped', cli: 'skipped', console: 'skipped' };
     const verification = { features: 'skipped', storyA: 'skipped' };
@@ -1767,6 +1863,34 @@ export async function install(options, pluginDir, mode = {}) {
         stepIndex++;
         if (spinner)
             updateProgress(spinner, stepIndex, 'Backing up existing install...');
+        // ADR-0024 D-2 (PRI-664): journal-first — record 'planned' BEFORE the
+        // first runtime mutation (the backup rename). Tier-1 policy: if the
+        // journal cannot be written at all, refuse before mutating (fail loud,
+        // zero side effects) rather than performing an unjournaled mutation
+        // (refusal over silent degradation, ADR-0024 §2.4 rule 4).
+        journal = beginInstallerJournal(pluginDir);
+        try {
+            journalInstallerTransition(journal, null, 'planned', `host=${options.host} mode=${options.mode}`);
+        }
+        catch (journalError) {
+            if (spinner)
+                spinner.fail('Install failed');
+            const journalDetail = journalError instanceof Error ? journalError.message : String(journalError);
+            logger.error(`Transaction journal unavailable — refusing to mutate the runtime unjournaled (ADR-0024 D-2): ${journalDetail}`);
+            return {
+                success: false,
+                workspaceDir: options.workspaceDir,
+                configYamlPath: getConfigYamlPath(options.workspaceDir),
+                templatesCount: 0,
+                components,
+                verification,
+                enabledChannels: options.channels,
+                nextAction: 'Resolve write access to ~/.pd/transactions (disk space / permissions), then re-run the installer. No changes were made.',
+                reason: `transaction_journal_unavailable: ${journalDetail}`,
+                error: `Could not write the transaction journal — refusing to mutate the runtime unjournaled (ADR-0024 D-2). No changes were made.`,
+                journal: { transactionId: journal.transactionId, journalPath: journal.journalPath, degraded: true },
+            };
+        }
         // Validate the existing host-ownership record before mutating runtime or
         // host config. A malformed manifest must not be discovered only after the
         // old installation has already been replaced (rc-3/rc-9).
@@ -1847,6 +1971,9 @@ export async function install(options, pluginDir, mode = {}) {
             updateProgress(spinner, stepIndex, 'Validating bundled console dependencies...');
         await installConsoleDependencies();
         stepIndex++;
+        // ADR-0024 D-2: all runtime content is laid down — the new installation
+        // is staged (nothing has been discarded yet; backups still hold the old one).
+        journalInstallerTransitionDegrading(journal, journal.lastState, 'staged', 'runtime components installed');
         if (spinner)
             updateProgress(spinner, stepIndex, 'Verifying pd-console...');
         const consoleVerify = await verifyConsole(options.workspaceDir);
@@ -1859,6 +1986,8 @@ export async function install(options, pluginDir, mode = {}) {
             throw new Error(`Console verification failed: ${consoleVerify.reason ?? 'unknown'}. Installation rolled back — plugin and CLI are not activated.`);
         }
         stepIndex++;
+        // ADR-0024 D-2: the console probe passed — the staged installation is live.
+        journalInstallerTransitionDegrading(journal, journal.lastState, 'probed', `console verified at ${consoleVerify.url}`);
         if (spinner)
             updateProgress(spinner, stepIndex, 'Copying templates...');
         const templatesCount = await copyCoreTemplates({
@@ -1965,7 +2094,13 @@ export async function install(options, pluginDir, mode = {}) {
             throw new Error(`Host installation failed: ${hostFailures.join(' | ')}`);
         }
         writeInstallManifest(installManifestHosts, resolveInstallManifestWorkspaces(options.workspaceDir));
+        // ADR-0024 D-2: host installers completed and the install manifest is
+        // written — the new installation is fully activated (backups not yet
+        // discarded, so a crash here still recovers via the backup).
+        journalInstallerTransitionDegrading(journal, journal.lastState, 'activated', 'host installers completed; install manifest written');
         cleanupBackup(backupDir, runtimeBackupDir);
+        // ADR-0024 D-2: backup cleanup is the commit point of the transaction.
+        journalInstallerTransitionDegrading(journal, journal.lastState, 'confirmed', 'backup cleaned up; install complete');
         if (spinner) {
             spinner.succeed('Install complete!');
         }
@@ -2015,14 +2150,35 @@ export async function install(options, pluginDir, mode = {}) {
             nextAction: nextActions.join(' | '),
             consoleUrl: launchResult.consoleUrl,
             hostResults,
+            journal: installerJournalRecord(journal),
         };
     }
     catch (error) {
         if (spinner)
             spinner.fail('Install failed');
         killConsoleChild();
+        // ADR-0024 D-2: record the outcome (journal may be null when the throw
+        // happened before the transaction was planned — zero side effects then).
+        // `failed` and `rolled_back` are BOTH terminal states and one journal
+        // file must end at exactly one terminal state (the strict reader rejects
+        // any transition after a terminal one), so the outcome is either-or:
+        // - backup restored (a real rollback happened) → `rolled_back`
+        // - no backup existed (mutation never started) or restore failed → `failed`
+        const errorMsgRaw = error instanceof Error ? error.message : String(error);
         const restoreResult = restoreBackup(backupDir, runtimeBackupDir);
-        const errorMsg = error instanceof Error ? error.message : String(error);
+        if (journal) {
+            const restoreFailed = Boolean(backupDir || runtimeBackupDir) && !restoreResult.restored;
+            const detail = restoreFailed
+                ? `${errorMsgRaw}; backup restore FAILED: ${restoreResult.error ?? 'unknown'}`
+                : errorMsgRaw;
+            if ((backupDir || runtimeBackupDir) && restoreResult.restored) {
+                journalInstallerTransitionDegrading(journal, journal.lastState, 'rolled_back', detail);
+            }
+            else {
+                journalInstallerTransitionDegrading(journal, journal.lastState, 'failed', detail);
+            }
+        }
+        const errorMsg = errorMsgRaw;
         // ERR-046 / rc-9: never claim a restore that didn't happen. When backupDir
         // is null, the backup step never completed (it threw — e.g. EPERM — or
         // there was no existing install), so the existing install was never moved
@@ -2074,6 +2230,7 @@ export async function install(options, pluginDir, mode = {}) {
             component: error instanceof SelfContainedDependencyError ? error.component : undefined,
             dependency: error instanceof SelfContainedDependencyError ? error.dependency : undefined,
             error: `${errorMsg} — ${rollbackSuffix}`,
+            journal: journal ? installerJournalRecord(journal) : undefined,
         };
     }
     finally {