create-principles-disciple 1.134.0 → 1.134.2

package/codex-adapter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@principles/codex-adapter",
-  "version": "0.2.8",
+  "version": "0.2.9",
   "description": "Codex CLI host adapter for Principles Disciple — implements HostAdapter interface for OpenAI Codex CLI's stdin/stdout JSON hook model (ADR-0020).",
   "type": "module",
   "main": "./dist/index.js",
@@ -32,7 +32,8 @@
   },
   "dependencies": {
     "@principles/core": "file:../core",
-    "@principles/host-runtime": "file:../host-runtime"
+    "@principles/host-runtime": "file:../host-runtime",
+    "@principles/install-layout": "file:../install-layout"
   },
   "devDependencies": {
     "@types/node": "^26.4.1",

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

@@ -10,6 +10,7 @@ import { migrateLegacyExtensionBackups, reservePdBackupDestination, resolvePdBac
 import { resolveExtensionsDir, resolveUpdateLayout, resolvePluginDir, resolveCanonicalRuntimeRoot, readCurrentVersion, } from '../utils/installed-layout.js';
 import { ActivationCompatibilityReadModel, isFeatureEnabled } from '@principles/core/runtime-v2';
 import { collectFileDepLinkSpecs } from '../utils/update-links.js';
+import { runPostUpdateCliSmoke } from '../utils/cli-smoke.js';
 import { updateMutationController, LEGACY_MUTATION_AUTHORITY, RELEASE_MANAGER_AUTHORITY, MUTATION_KINDS, } from '../update/mutation-controller.js';
 import { runLegacyJournaledMutation } from '../update/legacy-mutation-journal.js';
 import { loadPdConfig, computeFlagsFromLoadResult } from '../config/pd-config-store.js';
@@ -49,6 +50,10 @@ const WORKSPACE_FILES = ['AGENTS.md', 'SOUL.md', 'USER.md', 'CLAUDE.md'];
 // .node addons locked by the gateway/console processes (EPERM on copyfile),
 // npm symlinks/junctions, and thousands of regenerable files.
 const SKIP_DIRS = new Set(['node_modules']);
+// Full-update backups extend the existing plugin backup with sibling code
+// trees. Dependency directories stay in place (native modules may be loaded).
+const RUNTIME_BACKUP_DIR = '.runtime-components';
+const BACKUP_SKIP_DIRS = new Set(['node_modules', RUNTIME_BACKUP_DIR]);
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -223,6 +228,58 @@ function copyFileTo(src, dest) {
         fs.mkdirSync(dir, { recursive: true });
     fs.copyFileSync(src, dest);
 }
+function runtimeComponents(layout) {
+    return {
+        console: layout.consoleDir,
+        'pd-cli': layout.pdCliDir,
+        'host-runtime': layout.hostRuntimeDir,
+        'install-layout': layout.installLayoutDir,
+        core: layout.coreDir,
+        plugin: layout.pluginDir,
+        'release-manager': layout.releaseManagerDir,
+        ...(layout.codexAdapterDir ? { 'codex-adapter': layout.codexAdapterDir } : {}),
+    };
+}
+/** Resolve a backup entry under the backup root, refusing escapes — the
+ * component names recorded in components.json are untrusted runtime data
+ * (rc-1/rc-2), so every join into the backup tree is boundary-checked. */
+function backupEntryPath(root, name) {
+    const target = path.resolve(root, name);
+    if (target === root || !target.startsWith(root + path.sep)) {
+        throw new Error(`Runtime backup entry "${name}" escapes the backup root`);
+    }
+    return target;
+}
+function backupRuntimeComponents(layout, backupDir) {
+    const root = path.join(backupDir, RUNTIME_BACKUP_DIR);
+    fs.mkdirSync(root, { recursive: true });
+    const present = [];
+    for (const [name, dir] of Object.entries(runtimeComponents(layout))) {
+        if (name === 'plugin' || !fs.existsSync(dir))
+            continue;
+        copyDirRecursive(dir, backupEntryPath(root, name), BACKUP_SKIP_DIRS);
+        present.push(name);
+    }
+    // Written last: a partial backup must never be accepted as recoverable.
+    fs.writeFileSync(path.join(root, 'components.json'), JSON.stringify(present));
+}
+function restoreRuntimeComponents(layout, backupDir) {
+    const root = path.join(backupDir, RUNTIME_BACKUP_DIR);
+    if (!fs.existsSync(root))
+        return false; // Historical plugin-only backup.
+    const present = JSON.parse(fs.readFileSync(path.join(root, 'components.json'), 'utf8'));
+    const components = runtimeComponents(layout);
+    if (!Array.isArray(present) || present.some((name) => typeof name !== 'string' || name === 'plugin' || !Object.hasOwn(components, name)
+        || !fs.existsSync(backupEntryPath(root, name)))) {
+        throw new Error('Runtime backup is incomplete or incompatible with this installation');
+    }
+    for (const [name, dir] of Object.entries(components)) {
+        if (name === 'plugin' || !present.includes(name))
+            continue;
+        copyDirRecursive(backupEntryPath(root, name), dir, BACKUP_SKIP_DIRS);
+    }
+    return true;
+}
 // --- Plugin skill-language preservation (PR #1332 companion) -----------------
 // OpenClaw publishes plugin skills by directory name (first declaration
 // wins, same-name roots only warn — no locale mechanism), so a manifest must
@@ -749,7 +806,11 @@ async function doRollbackUpdate(options, workspaceDir) {
         // dependencies. Instead, overwrite from backup: modified files (dist/,
         // package.json, etc.) get the backup version, while node_modules/console/
         // core/ (not in the backup) are left untouched.
-        copyDirRecursive(backupDir, targetDir);
+        const layout = resolveUpdateLayout();
+        const fullBackup = layout && path.resolve(layout.pluginDir) === path.resolve(targetDir)
+            ? restoreRuntimeComponents(layout, backupDir)
+            : false;
+        copyDirRecursive(backupDir, targetDir, BACKUP_SKIP_DIRS);
         // Keep the OpenClaw extension copy in sync with the restored canonical
         // plugin (CP-5 invariant from the 2026-09-05 investigation): OpenClaw
         // loads ~/.openclaw/extensions/principles-disciple, so a rollback that
@@ -759,9 +820,29 @@ async function doRollbackUpdate(options, workspaceDir) {
         const openClawPluginCopy = path.join(resolveExtensionsDir(), 'principles-disciple');
         let extCopySynced = false;
         if (path.resolve(openClawPluginCopy) !== path.resolve(targetDir) && fs.existsSync(openClawPluginCopy)) {
-            copyDirRecursive(backupDir, openClawPluginCopy);
+            copyDirRecursive(backupDir, openClawPluginCopy, BACKUP_SKIP_DIRS);
             extCopySynced = true;
         }
+        if (fullBackup && layout) {
+            const smoke = runPostUpdateCliSmoke(layout.pdCliDir);
+            if (!smoke.ok) {
+                // rc-9: a failed rollback must be observable in history, like every
+                // other failure path — not just in the HTTP response.
+                appendUpdateHistory(workspaceDir, {
+                    fromVersion: 'rolled-back',
+                    toVersion: readCurrentVersion(targetDir) ?? 'unknown',
+                    success: false,
+                    kind: 'failure',
+                    backupPath: backupDir,
+                });
+                return {
+                    success: false,
+                    message: `Runtime backup restored but pd CLI still fails to start: ${smoke.error}`,
+                    reason: 'rollback_cli_smoke_failed',
+                    nextAction: 'Keep the backup and use the official installer pinned to the previous installer release to repair dependencies before restarting Console.',
+                };
+            }
+        }
         // Record rollback history
         appendUpdateHistory(workspaceDir, {
             fromVersion: 'rolled-back',
@@ -772,9 +853,11 @@ async function doRollbackUpdate(options, workspaceDir) {
         });
         return {
             success: true,
-            message: extCopySynced
-                ? 'Rollback completed successfully (OpenClaw extension copy restored too). Note: only the plugin was rolled back; console/core/host-runtime/pd-cli keep the upgraded version. For a full step-back, re-run the official installer pinned to the older release.'
-                : 'Rollback completed successfully. Note: only the plugin was rolled back; console/core/host-runtime/pd-cli keep the upgraded version. For a full step-back, re-run the official installer pinned to the older release.',
+            message: fullBackup
+                ? 'Runtime components restored and pd CLI startup verified. Restart Console to load the restored code.'
+                : extCopySynced
+                    ? 'Rollback completed successfully (OpenClaw extension copy restored too). Note: only the plugin was rolled back; console/core/host-runtime/pd-cli keep the upgraded version. For a full step-back, re-run the official installer pinned to the older release.'
+                    : 'Rollback completed successfully. Note: only the plugin was rolled back; console/core/host-runtime/pd-cli keep the upgraded version. For a full step-back, re-run the official installer pinned to the older release.',
         };
     }
     catch (error) {
@@ -998,19 +1081,9 @@ function ensureRuntimeResolutionLinks(layout, tempDir) {
     ];
     // Data-driven pass: derive links from the STAGED component manifests (see
     // the comment above — staged, never the deployed pre-update manifests).
-    const stagedComponents = [
-        { manifestDir: path.join(tempDir, 'console'), deployedDir: layout.consoleDir },
-        { manifestDir: path.join(tempDir, 'pd-cli'), deployedDir: layout.pdCliDir },
-        { manifestDir: path.join(tempDir, 'host-runtime'), deployedDir: layout.hostRuntimeDir },
-        { manifestDir: path.join(tempDir, 'install-layout'), deployedDir: layout.installLayoutDir },
-        { manifestDir: path.join(tempDir, 'core'), deployedDir: layout.coreDir },
-        { manifestDir: path.join(tempDir, 'plugin'), deployedDir: layout.pluginDir },
-        // PRI-672: staged release-manager component (npm name
-        // create-principles-disciple). Its staged manifest carries the
-        // file:../install-layout ref, and the staged console's manifest carries
-        // file:../release-manager — both derive their resolution links here.
-        { manifestDir: path.join(tempDir, 'release-manager'), deployedDir: layout.releaseManagerDir },
-    ];
+    const stagedComponents = Object.entries(runtimeComponents(layout)).map(([name, deployedDir]) => ({
+        manifestDir: path.join(tempDir, name), deployedDir,
+    }));
     const readStagedDependencies = (manifestDir) => {
         try {
             const pkgPath = path.join(manifestDir, 'package.json');
@@ -1263,9 +1336,8 @@ async function doInlineFullUpdate(workspaceDir) {
         // 2026-09-05 install/upgrade investigation). The backup excludes
         // node_modules (same SKIP_DIRS contract as /apply), and the backup dir
         // is recorded in update-history (success AND failure) so the rollback
-        // handler can find it. Console self-update owns the console dir backup;
-        // core/host-runtime/pd-cli are plain dist overlays re-fetched on any
-        // next update, so only the version authority (plugin) is backed up.
+        // handler can find it. Include every sibling code tree: a plugin-only
+        // rollback cannot repair a CLI/adapter import failure after an update.
         // R5 (review): reservePdBackupDestination creates the directory BEFORE
         // the copy — a mid-copy failure must not leave backupPath pointing at a
         // partial backup (a later /rollback would happily restore the fragment).
@@ -1276,6 +1348,7 @@ async function doInlineFullUpdate(workspaceDir) {
             const backupDest = reservePdBackupDestination(path.basename(extDir));
             try {
                 copyDirRecursive(extDir, backupDest, SKIP_DIRS);
+                backupRuntimeComponents(layout, backupDest);
             }
             catch (backupError) {
                 try {
@@ -1307,6 +1380,23 @@ async function doInlineFullUpdate(workspaceDir) {
                 fs.existsSync(path.join(releaseManagerSrc, 'dist'))) {
                 copyDirRecursive(releaseManagerSrc, layout.releaseManagerDir, SKIP_DIRS);
             }
+            // PRI-711: same PRI-561 ordering for codex-adapter — pd-cli's eager
+            // import graph statically resolves it, so an updated pd-cli paired with
+            // a stale deployed adapter is exactly the generation drift that bricked
+            // the 1.231.2 update (health-codex imported symbols the deployed
+            // adapter happened to carry; the next API addition would not). The
+            // copy keeps the deployed node_modules (SKIP_DIRS), so its resolution
+            // links survive; the data-driven pass below re-derives them anyway.
+            // Skipped when the running console resolves a one-generation-old
+            // install-layout without codexAdapterDir — that generation also lacks
+            // the derivation entry, mirroring the old no-op behavior (rc-9).
+            const codexAdapterDest = layout.codexAdapterDir;
+            if (codexAdapterDest !== undefined &&
+                fs.existsSync(path.join(tempDir, 'codex-adapter')) &&
+                fs.existsSync(path.join(tempDir, 'codex-adapter', 'package.json')) &&
+                fs.existsSync(path.join(tempDir, 'codex-adapter', 'dist'))) {
+                copyDirRecursive(path.join(tempDir, 'codex-adapter'), codexAdapterDest, SKIP_DIRS);
+            }
             const { error: linkError, quarantined } = ensureRuntimeResolutionLinks(layout, tempDir);
             reconciledQuarantine = quarantined;
             if (linkError) {
@@ -1383,12 +1473,32 @@ 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);
+        // 6.8 PRI-711: post-apply CLI smoke. The swap and link steps above are
+        // data-driven but not self-proving — run the updated CLI once and refuse
+        // to record a success if the eager import graph is broken (see
+        // runPostUpdateCliSmoke for the three precedents this catches). The
+        // backup recorded below keeps the failure recoverable via /rollback.
+        const smoke = runPostUpdateCliSmoke(layout.pdCliDir);
+        if (!smoke.ok) {
+            restoreQuarantined(reconciledQuarantine);
+            reconciledQuarantine = [];
+            const failedVersion = readCurrentVersion(extDir) ?? toVersion ?? 'unknown';
+            appendUpdateHistory(workspaceDir, {
+                fromVersion,
+                toVersion: failedVersion,
+                success: false,
+                kind: 'failure',
+                ...(pluginBackupDir ? { backupPath: pluginBackupDir } : {}),
+            });
+            return {
+                success: false,
+                message: `Update applied but the updated pd CLI fails to start: ${smoke.error}`,
+                reason: 'post_update_cli_smoke_failed',
+                nextAction: pluginBackupDir
+                    ? 'Restore the backup recorded in update history (backupPath), then report the stderr above. The console must be restarted before further use.'
+                    : 'Report the stderr above; no backup was reserved for this update. The console must be restarted before further use.',
+                requiresRestart: false,
+            };
         }
         // 7. Version-advance check (drift guard). The full update installs the
         // plugin bundled inside the installer. If the installer is stale (its
@@ -1400,6 +1510,8 @@ async function doInlineFullUpdate(workspaceDir) {
         const newVersion = readCurrentVersion(extDir) ?? toVersion ?? 'unknown';
         const installedExpectedRelease = newVersion === stagedVersion;
         if (!installedExpectedRelease) {
+            restoreQuarantined(reconciledQuarantine);
+            reconciledQuarantine = [];
             // Files were already rewritten to the same (or lower) version. Record a
             // FAILED history entry so the operator sees why, and return a structured
             // error with nextAction.
@@ -1426,6 +1538,10 @@ async function doInlineFullUpdate(workspaceDir) {
             kind: 'update',
             ...(pluginBackupDir ? { backupPath: pluginBackupDir } : {}),
         });
+        // The quarantined pre-update copies are discarded on success; no reset of
+        // the variable is needed here — the return below cannot re-enter the
+        // catch (CodeQL js/useless-assignment-to-local, PR #1580 review).
+        cleanupQuarantined(reconciledQuarantine);
         return {
             success: true,
             message: depsChanged

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": "全量更新完成。",