create-principles-disciple 1.133.13 → 1.134.1

package/console/dist/server/update/legacy-mutation-journal.js

@@ -0,0 +1,220 @@
+/**
+ * PRI-709 P0-3 — journal coverage for the legacy console updater (ADR-0024 D-2).
+ *
+ * PRI-698 Phase 0 Audit finding F-3: the console updater performed runtime
+ * mutations with **zero** journal writes. Under ADR-0024 D-2 an unjournaled
+ * runtime mutation is the one thing that must never happen, so the legacy
+ * updater had to be brought under the SAME journal as the installer and the
+ * ReleaseManager before the legacy path can be retired.
+ *
+ * Design rules (all load-bearing):
+ *
+ * - **No new journal implementation.** This module reuses
+ *   `create-principles-disciple`'s `transaction-journal` — one JSONL file per
+ *   transaction under `~/.pd/transactions/`, append + fsync, strict reader.
+ *   Nothing here parses, formats or rotates journals.
+ * - **The ReleaseManager path is never double-journaled.** ReleaseManager
+ *   `apply-full` orchestrates the installer, which journals the whole
+ *   lifecycle; the console dispatch for that path never reaches the legacy
+ *   handlers this module wraps. When the ReleaseManager explicitly falls back
+ *   to legacy, the legacy handler is the ONLY writer — one transaction per
+ *   mutation, whichever authority served it.
+ * - **Explicit degradation, never a blocked mutation.** The journal module is
+ *   loaded dynamically: the console runs in installations where the
+ *   create-principles-disciple dist may be absent (the same delivery-surface
+ *   gap the ReleaseManager authority loader already handles). A missing module
+ *   is reported and the mutation proceeds unjournaled — refusing the Owner's
+ *   update would be worse than an unaudited one, and the gap is observable.
+ * - **No fabricated digests.** The legacy updater does not verify signed
+ *   release metadata, so its digest provenance is `fallback`: a synthetic
+ *   sha256 over a literal marker, readable but explicitly NOT verifiable. It
+ *   never claims `manifest` / `signed_channel` it cannot back.
+ *
+ * Transition strategy for legacy kinds:
+ *
+ *   apply / apply-full / rollback:  `planned` → `confirmed` | `failed`
+ *
+ * `planned` is appended immediately before the mutation (after all request
+ * validation, so rejected requests leave no transaction); `confirmed` or
+ * `failed` after it. `rolled_back` is NOT used for the rollback kind — a
+ * rollback restores a previous deployment and is itself a forward transition
+ * to a known-good state, whereas `rolled_back` means "this transaction was
+ * undone".
+ *
+ * Two documented trade-offs (PRI-709 review, deliberate):
+ *
+ * - **`generation` stays at the standalone default `1`.** Legacy console
+ *   transactions do not participate in the dual-slot generation lineage — they
+ *   never move the active record — so recording a real `active.json.generation
+ *   + 1` would CLAIM a lineage the console does not actually advance. Recovery
+ *   is unaffected either way: `recoverUnfinishedTransaction` keys on
+ *   `activeRecord.transactionId`, which a console transaction never matches, so
+ *   it resolves to "the previously confirmed release stands".
+ * - **The legacy path leaves `active.json` untouched.** The legacy updater
+ *   replaces the runtime without the installer's dual-slot swap, so after a
+ *   legacy `apply-full` the active record describes the PREVIOUS deployment.
+ *   Making the console a second writer of the deployment identity would be a
+ *   worse violation (one source of truth); the honest fix is retiring the
+ *   legacy path (ADR-0024 D-1), which is exactly what this journal coverage
+ *   unblocks.
+ */
+import { createHash, randomUUID } from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+/** Load the shared journal; `null` when the delivery surface lacks the module. */
+async function loadJournalPort() {
+    try {
+        const module = await import('create-principles-disciple/dist/update/transaction-journal.js');
+        return { appendJournalTransition: module.appendJournalTransition };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Product version of the currently installed runtime.
+ *
+ * Same rule as the installer (PRI-709 P0-2): the PRODUCT manifest is
+ * `pluginDir/package.json`; `pd-cli` versions independently and is only a
+ * fallback.
+ */
+function resolveInstalledProductVersion(pluginDir) {
+    for (const candidate of [path.join(pluginDir, 'package.json'), path.join(pluginDir, 'pd-cli', 'package.json')]) {
+        try {
+            const parsed = JSON.parse(fs.readFileSync(candidate, 'utf8'));
+            if (typeof parsed.version === 'string' && parsed.version.length > 0)
+                return parsed.version;
+        }
+        catch {
+            // Identity falls back; an unjournaled-able version must not block a mutation.
+        }
+    }
+    return 'unknown';
+}
+/**
+ * Open one legacy transaction and append `planned` before the mutation runs.
+ */
+export async function openLegacyMutationJournal(options) {
+    const port = options.journal ?? await loadJournalPort();
+    if (port === null) {
+        return { journaled: false, reason: 'journal_module_unavailable' };
+    }
+    const productVersion = resolveInstalledProductVersion(options.pluginDir);
+    // Unverifiable by construction: the legacy updater never sees signed release
+    // metadata, so the digest is a marker hash labelled `fallback`.
+    const releaseMetadataDigest = createHash('sha256')
+        .update(`legacy-console-updater-unverified:${options.kind}`)
+        .digest('hex');
+    const transactionId = `console-${options.kind}-${Date.now()}-${randomUUID().slice(0, 8)}`;
+    const releaseId = `console-${options.kind}-${productVersion}-${releaseMetadataDigest.slice(0, 12)}`;
+    const journal = {
+        transactionId,
+        journalPath: path.join(options.pdHome, 'transactions', `${transactionId}.jsonl`),
+        releaseId,
+        productVersion,
+        releaseMetadataDigest,
+    };
+    try {
+        port.appendJournalTransition(journal.journalPath, {
+            at: (options.now ?? (() => new Date))().toISOString(),
+            from: null,
+            to: 'planned',
+            transactionId,
+            releaseId,
+            productVersion,
+            releaseMetadataDigest,
+            releaseMetadataDigestSource: 'fallback',
+            generation: 1,
+            detail: `actor=console-updater kind=${options.kind}`,
+        });
+    }
+    catch (error) {
+        return {
+            journaled: false,
+            reason: `journal_write_failed: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    return { journaled: true, journal };
+}
+/**
+ * Maps a mutation's RESULT to its journal terminal state.
+ *
+ * PRI-709 review: the legacy updater reports failure as a VALUE —
+ * `doApplyUpdate` / `doRollbackUpdate` / `doInlineFullUpdate` return
+ * `{ success: false, message }` for ~30 distinct failure modes and only throw
+ * for infrastructure errors. Terminal state decided on "did it throw" alone
+ * would journal confirmed for most real failures. So: `success === true` is
+ * `confirmed`, `success === false` is `failed` (with the reported message as
+ * detail), and a non-object result (no contract) is treated as completed.
+ * The HTTP response contract is untouched either way — this only decides what
+ * the journal records.
+ */
+function toLegacyMutationOutcome(result) {
+    if (typeof result !== 'object' || result === null) {
+        return { to: 'confirmed', detail: 'completed' };
+    }
+    const record = result;
+    if (!Object.hasOwn(record, 'success')) {
+        return { to: 'confirmed', detail: 'completed' };
+    }
+    const detailParts = [record.message, record.reason]
+        .filter((part) => typeof part === 'string' && part.length > 0);
+    const detail = detailParts.length > 0 ? detailParts.join('; ') : 'no detail reported';
+    return { to: record.success === true ? 'confirmed' : 'failed', detail };
+}
+/**
+ * Writes the terminal transition for an opened legacy transaction and reports
+ * loud when it cannot land: the journal would then hold an unfinished
+ * transaction, which is a governance gap (rc-9) even though the mutation's
+ * real outcome must not be masked.
+ */
+async function appendLegacyOutcome(options, status, outcome) {
+    if (!status.journaled)
+        return;
+    const port = options.journal ?? await loadJournalPort();
+    if (port === null)
+        return;
+    try {
+        port.appendJournalTransition(status.journal.journalPath, {
+            at: (options.now ?? (() => new Date))().toISOString(),
+            from: 'planned',
+            to: outcome.to,
+            transactionId: status.journal.transactionId,
+            releaseId: status.journal.releaseId,
+            productVersion: status.journal.productVersion,
+            releaseMetadataDigest: status.journal.releaseMetadataDigest,
+            releaseMetadataDigestSource: 'fallback',
+            generation: 1,
+            detail: `actor=console-updater kind=${options.kind} ${outcome.detail}`,
+        });
+    }
+    catch (error) {
+        console.warn(`[update] Legacy mutation "${options.kind}" finished as "${outcome.to}" but its terminal journal transition `
+            + `could not be written (${error instanceof Error ? error.message : String(error)}). `
+            + `Transaction ${status.journal.transactionId} stays unfinished and must be reconciled.`);
+    }
+}
+/**
+ * Runs a legacy mutation under one journal transaction.
+ *
+ * `planned` is written before `run()`; `confirmed` / `failed` after — decided
+ * by BOTH the thrown/not-thrown boundary and the updater's `success` result
+ * shape (see `toLegacyMutationOutcome`). A journal failure never changes the
+ * mutation's outcome — it is reported alongside it.
+ */
+export async function runLegacyJournaledMutation(options, run) {
+    const opened = await openLegacyMutationJournal(options);
+    try {
+        const result = await run();
+        const outcome = toLegacyMutationOutcome(result);
+        await appendLegacyOutcome(options, opened, { to: outcome.to, detail: `${options.kind}: ${outcome.detail}` });
+        return { result, journal: opened };
+    }
+    catch (error) {
+        await appendLegacyOutcome(options, opened, {
+            to: 'failed',
+            detail: `${options.kind}: ${error instanceof Error ? error.message : String(error)}`,
+        });
+        throw error;
+    }
+}

package/console/dist/server/utils/cli-smoke.d.ts

@@ -0,0 +1,19 @@
+export type CliSmokeResult = {
+    ok: true;
+    version: string;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Spawn the pd CLI entry and require exit 0.
+ *
+ * Resolves `node` from PATH — the same resolution the installed bin/pd.cmd
+ * shim already depends on, so any environment that can run `pd` at all can
+ * run this probe. The entry path is boundary-checked to stay inside the
+ * pd-cli component dir (same guard shape as the legacy-rule preflight's
+ * subprocess target), and the subprocess is invoked with an argv array —
+ * never a shell string (ERR-045). Bounded stderr extract on failure (rc-8);
+ * never throws.
+ */
+export declare function runPostUpdateCliSmoke(pdCliDir: string): CliSmokeResult;

package/console/dist/server/utils/cli-smoke.js

@@ -0,0 +1,60 @@
+/**
+ * PRI-711: post-apply CLI smoke for the full-update pipeline.
+ *
+ * The full update swaps component dists without running npm install, and
+ * resolution gaps of one class have now shipped three times — each discovered
+ * only as a bricked CLI at the next console launch (PRI-561 host-runtime
+ * links, the 2026-08-29 install-layout component gap, PRI-711 codex-adapter).
+ * Spawning the pd CLI once with `--version` loads its entire eager import
+ * graph (health-codex → @principles/codex-adapter →
+ * @principles/host-runtime → @principles/core) and exits without touching
+ * workspace state, so a gap anywhere in that graph surfaces before the update
+ * is recorded as a success.
+ */
+import { execFileSync } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+/**
+ * Spawn the pd CLI entry and require exit 0.
+ *
+ * Resolves `node` from PATH — the same resolution the installed bin/pd.cmd
+ * shim already depends on, so any environment that can run `pd` at all can
+ * run this probe. The entry path is boundary-checked to stay inside the
+ * pd-cli component dir (same guard shape as the legacy-rule preflight's
+ * subprocess target), and the subprocess is invoked with an argv array —
+ * never a shell string (ERR-045). Bounded stderr extract on failure (rc-8);
+ * never throws.
+ */
+export function runPostUpdateCliSmoke(pdCliDir) {
+    const resolvedRoot = path.resolve(pdCliDir);
+    const pdCliEntry = path.join(resolvedRoot, 'dist', 'index.js');
+    if (!pdCliEntry.startsWith(resolvedRoot + path.sep)) {
+        return { ok: false, error: `pd CLI entry ${pdCliEntry} is outside the pd-cli component dir ${resolvedRoot}` };
+    }
+    if (!fs.existsSync(pdCliEntry)) {
+        return { ok: false, error: `pd CLI entry not found at ${pdCliEntry}` };
+    }
+    try {
+        const stdout = execFileSync('node', [pdCliEntry, '--version'], {
+            timeout: 60_000,
+            encoding: 'utf8',
+            windowsHide: true,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        const version = (stdout.trim().split(/\r?\n/, 1)[0] ?? '').trim();
+        return { ok: true, version };
+    }
+    catch (error) {
+        // rc-1/rc-2: the child failure shape is unknown — guard every read.
+        // Node prints the error MESSAGE first and stack frames after, so the
+        // operator-facing extract is the bounded HEAD of stderr (a tail would
+        // carry only stack noise — observed in the PRI-711 test fixture).
+        let reason = error instanceof Error ? error.message : String(error);
+        if (typeof error === 'object' && error !== null && Object.hasOwn(error, 'stderr')) {
+            const { stderr } = error;
+            if (typeof stderr === 'string' && stderr.trim().length > 0)
+                reason = stderr;
+        }
+        return { ok: false, error: reason.trim().slice(0, 400) };
+    }
+}

package/console/dist/server/utils/installed-layout.d.ts

@@ -8,6 +8,14 @@ export interface UpdateLayout {
     pdCliDir: string;
     installLayoutDir: string;
     releaseManagerDir: string;
+    /**
+     * PRI-711: codex-adapter is a runtime-layout component pd-cli resolves
+     * eagerly. Undefined when the DEPLOYED @principles/install-layout is one
+     * generation old (this update runs inside the currently-running console,
+     * which resolves the layout helper installed by the PREVIOUS update) —
+     * consumers must degrade to skipping the adapter, never assume it.
+     */
+    codexAdapterDir: string | undefined;
     hosts: InstallHost[];
 }
 export declare function resolveUpdateLayout(): UpdateLayout | undefined;

package/console/dist/server/utils/installed-layout.js

@@ -46,6 +46,9 @@ export function resolveUpdateLayout() {
             pdCliDir: paths.pdCliDir,
             installLayoutDir: paths.installLayoutDir,
             releaseManagerDir: paths.releaseManagerDir,
+            // rc-1: the deployed install-layout may predate the codexAdapterDir
+            // field — guard instead of trusting the shape.
+            codexAdapterDir: typeof paths.codexAdapterDir === 'string' ? paths.codexAdapterDir : undefined,
             hosts: resolution.manifest?.hosts ?? [],
         };
     }
@@ -57,6 +60,7 @@ export function resolveUpdateLayout() {
         pdCliDir: path.join(legacyPluginDir, 'pd-cli'),
         installLayoutDir: path.join(legacyPluginDir, 'install-layout'),
         releaseManagerDir: path.join(legacyPluginDir, 'release-manager'),
+        codexAdapterDir: path.join(legacyPluginDir, 'codex-adapter'),
         hosts: ['openclaw'],
     };
 }

package/console/dist/ui/i18n/en.json

@@ -1355,8 +1355,8 @@
             "filesUpdated": "Updated {{count}} files",
             "networkErrorHint": "Please check your network connection and try again.",
             "retry": "Retry",
-            "codexWarning": "Codex Host detected. This update only covers the OpenClaw plugin code and does not update the Codex adapter (@principles/codex-adapter). For a full update, run the installer.",
-            "partialUpdateHint": "Plugin code updated. To update the full runtime (including the Codex adapter and dependencies), run: npx create-principles-disciple",
+            "codexWarning": "Codex Host detected. The full update also refreshes the Codex adapter (@principles/codex-adapter) in the runtime layout. To re-register Codex hooks or repair the Codex host install, run the installer.",
+            "partialUpdateHint": "Plugin code updated. If components ever look out of sync, refresh the full runtime with: npx create-principles-disciple",
             "applyFullUpdate": "Full Update",
             "fullUpdating": "Full update in progress…",
             "fullUpdateSuccess": "Full update completed.",

package/console/dist/ui/i18n/zh-CN.json

@@ -1355,8 +1355,8 @@
             "filesUpdated": "更新了 {{count}} 个文件",
             "networkErrorHint": "请检查网络连接后重试。",
             "retry": "重试",
-            "codexWarning": "检测到 Codex Host 已安装。此处的更新仅覆盖 OpenClaw 插件代码，不会更新 Codex 适配器（@principles/codex-adapter）。如需完整更新，请运行安装器。",
-            "partialUpdateHint": "插件代码已更新。如需更新完整运行时（含 Codex 适配器和依赖），请运行：npx create-principles-disciple",
+            "codexWarning": "检测到 Codex Host 已安装。全量更新现在会同步刷新运行时布局中的 Codex 适配器（@principles/codex-adapter）。如需重新注册 Codex hooks 或修复 Codex 宿主安装，请运行安装器。",
+            "partialUpdateHint": "插件代码已更新。如发现组件版本不同步，请运行以下命令刷新完整运行时：npx create-principles-disciple",
             "applyFullUpdate": "全量更新",
             "fullUpdating": "全量更新中…",
             "fullUpdateSuccess": "全量更新完成。",