create-principles-disciple 1.105.0 → 1.107.0

package/console/dist/server/index.js

@@ -24,6 +24,7 @@ import { handleUpdateRoute } from './routes/update.js';
 import { handleUpdateHistoryRoute } from './routes/update-history.js';
 import { handleConfigRoute } from './routes/config.js';
 import { sendJson, sendNotFound, sendUnauthorized } from './utils/response.js';
+import { migrateLegacyExtensionBackups, resolvePdBackupsRoot } from './utils/pd-backups.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 // WEB_ROOT calculation: server is at PKG_ROOT/dist/server/index.js
@@ -400,6 +401,21 @@ export async function main() {
         console.warn('[pd-console] No auth token configured. Running without authentication. Use --token or PD_CONSOLE_TOKEN to enable.');
     }
     const services = await initServices(workspace, authConfig);
+    // One-time hygiene: move legacy PD backups out of ~/.openclaw/extensions so
+    // OpenClaw plugin discovery stops reporting a duplicate principles-disciple
+    // plugin on every gateway startup. Best-effort, never blocks startup.
+    try {
+        const legacy = migrateLegacyExtensionBackups();
+        if (legacy.movedFrom.length > 0) {
+            console.log(`[pd-console] Migrated ${legacy.movedFrom.length} legacy PD backup dir(s) out of the extensions dir to ${resolvePdBackupsRoot()}`);
+        }
+        for (const failure of legacy.failed) {
+            console.warn(`[pd-console] Could not migrate legacy PD backup "${failure.name}" out of the extensions dir: ${failure.reason}. Move it out manually to silence the OpenClaw "duplicate plugin id" warning.`);
+        }
+    }
+    catch (err) {
+        console.warn('[pd-console] Legacy backup migration failed:', err instanceof Error ? err.message : err);
+    }
     const server = http.createServer(handleRequest(services));
     const shutdown = async (signal) => {
         console.log(`[pd-console] Received ${signal}, shutting down...`);

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

@@ -6,6 +6,7 @@ import semver from 'semver';
 import { sendSuccess, sendError, sendMethodNotAllowed, sendBadRequest, sendNotFound, } from '../utils/response.js';
 import { appendUpdateHistory } from './update-history.js';
 import { checkOpenClawGateway, stopOpenClawGateway, restartOpenClawGateway, } from '../utils/gateway.js';
+import { migrateLegacyExtensionBackups, reservePdBackupDestination, resolvePdBackupsRoot, } from '../utils/pd-backups.js';
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -82,12 +83,27 @@ function isValidMergeStrategy(value) {
 function validatePathInWorkspace(target, workspaceDir) {
     const resolved = path.resolve(target);
     const resolvedWorkspace = path.resolve(workspaceDir);
-    // Allow paths within workspace or within the OpenClaw extensions directory.
-    // The extensions dir is under the OpenClaw install home (~/.openclaw/extensions),
-    // which is NOT derived from the workspace dir (the two may be on different drives).
+    // Allow paths within workspace, within the OpenClaw extensions directory,
+    // or within the PD backups root. The extensions dir and backups root are
+    // under the OpenClaw install home (~/.openclaw), which is NOT derived from
+    // the workspace dir (the two may be on different drives).
     const extensionsDir = path.resolve(resolveExtensionsDir());
-    return resolved.startsWith(resolvedWorkspace + path.sep) || resolved === resolvedWorkspace
-        || resolved.startsWith(extensionsDir + path.sep) || resolved === extensionsDir;
+    const backupsRoot = path.resolve(resolvePdBackupsRoot());
+    const insideRoot = (root) => resolved.startsWith(root + path.sep) || resolved === root;
+    return insideRoot(resolvedWorkspace) || insideRoot(extensionsDir) || insideRoot(backupsRoot);
+}
+/**
+ * Log the result of a legacy-backup migration (rc-9: failures are surfaced,
+ * never silent). Returns nothing; migration itself is best-effort.
+ */
+function logLegacyBackupMigration(source) {
+    const legacy = migrateLegacyExtensionBackups();
+    if (legacy.movedFrom.length > 0) {
+        console.log(`[${source}] Migrated ${legacy.movedFrom.length} legacy PD backup dir(s) out of the extensions dir to ${resolvePdBackupsRoot()}`);
+    }
+    for (const failure of legacy.failed) {
+        console.warn(`[${source}] Could not migrate legacy PD backup "${failure.name}" out of the extensions dir: ${failure.reason}. Move it out manually to silence the OpenClaw "duplicate plugin id" warning.`);
+    }
 }
 // ---------------------------------------------------------------------------
 // Core update operations (inline to avoid cross-package import)
@@ -128,6 +144,85 @@ function copyFileTo(src, dest) {
         fs.mkdirSync(dir, { recursive: true });
     fs.copyFileSync(src, dest);
 }
+// --- 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
+// declare exactly ONE language root. The shipped manifest declares zh
+// (product default); installs made with --lang en have their installed
+// manifest rewritten to the en root by the installer. Updates ship a fresh
+// zh-default manifest and would silently revert that choice — so capture the
+// installed language BEFORE any mutation and re-apply it after the new
+// manifest lands. Mirrors create-principles-disciple/src/skill-language.ts
+// (keep the two transforms in sync).
+const SKILL_LANGUAGE_ROOTS = {
+    zh: 'templates/langs/zh/skills',
+    en: 'templates/langs/en/skills',
+};
+function isLanguageSkillRoot(entry) {
+    if (typeof entry !== 'string')
+        return false;
+    const normalized = entry.replaceAll('\\', '/');
+    return normalized === SKILL_LANGUAGE_ROOTS.zh || normalized === SKILL_LANGUAGE_ROOTS.en;
+}
+function detectInstalledSkillLanguage(extDir) {
+    try {
+        const manifestPath = path.join(extDir, 'openclaw.plugin.json');
+        if (!fs.existsSync(manifestPath))
+            return 'zh';
+        const raw = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+        if (!isRecord(raw) || !Array.isArray(raw.skills))
+            return 'zh';
+        const languages = new Set();
+        for (const entry of raw.skills) {
+            if (typeof entry !== 'string')
+                continue;
+            const normalized = entry.replaceAll('\\', '/');
+            if (normalized === SKILL_LANGUAGE_ROOTS.zh)
+                languages.add('zh');
+            else if (normalized === SKILL_LANGUAGE_ROOTS.en)
+                languages.add('en');
+        }
+        // Exactly one language root → that is the user's selection. Zero or both
+        // (pre-ERR-097 legacy install) → product default.
+        if (languages.size !== 1)
+            return 'zh';
+        for (const language of languages)
+            return language;
+        return 'zh';
+    }
+    catch {
+        return 'zh';
+    }
+}
+function reapplySkillLanguage(extDir, language) {
+    try {
+        const manifestPath = path.join(extDir, 'openclaw.plugin.json');
+        if (!fs.existsSync(manifestPath))
+            return;
+        // Defense in depth: only rewrite when the selected language's templates
+        // actually exist — otherwise the host would warn "plugin skill path not
+        // found" and publish nothing.
+        if (!fs.existsSync(path.join(extDir, SKILL_LANGUAGE_ROOTS[language]))) {
+            console.error(`[pd-console:update] skill language "${language}" templates missing — keeping shipped manifest skills`);
+            return;
+        }
+        const raw = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+        if (!isRecord(raw) || !Array.isArray(raw.skills))
+            return;
+        const skills = raw.skills;
+        const kept = skills.filter((entry) => typeof entry === 'string' && !isLanguageSkillRoot(entry));
+        const next = [...kept, SKILL_LANGUAGE_ROOTS[language]];
+        const unchanged = next.length === skills.length && next.every((entry, i) => entry === skills[i]);
+        if (unchanged)
+            return;
+        raw.skills = next;
+        fs.writeFileSync(manifestPath, JSON.stringify(raw, null, 2) + '\n', 'utf-8');
+    }
+    catch (error) {
+        // rc-9: degrade observably, never fail the whole update over skill language.
+        console.error(`[pd-console:update] failed to re-apply skill language "${language}": ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
 function getAllFilesLocal(dir, skipDirs) {
     const skip = skipDirs ?? new Set();
     const result = [];
@@ -293,6 +388,13 @@ async function doApplyUpdate(options, workspaceDir) {
     try {
         // 0. Save current version BEFORE any changes
         const fromVersion = readCurrentVersion(targetDir) ?? 'unknown';
+        // Capture the installed skill language before the tarball's manifest
+        // overwrites it (PR #1332 companion — see reapplySkillLanguage).
+        const skillLanguage = detectInstalledSkillLanguage(targetDir);
+        // 0.5 Heal legacy installs: older versions left backups inside the
+        // extensions dir, where OpenClaw discovery picks them up as duplicate
+        // plugins. Move them out before creating a new backup alongside them.
+        logLegacyBackupMigration('pd-update');
         // 1. Fetch latest package info (with timeout + retry)
         const response = await fetchWithRetry(NPM_REGISTRY_LATEST, 'Registry check');
         const rawData = await response.json();
@@ -307,10 +409,13 @@ async function doApplyUpdate(options, workspaceDir) {
         if (!tarball)
             return { success: false, message: 'Missing tarball URL in registry response' };
         // 2. Create backup if requested (Fix 2: skip node_modules to avoid EPERM
-        //    from locked native modules and npm symlinks/junctions)
+        //    from locked native modules and npm symlinks/junctions).
+        //    The backup lives in <openclawHome>/pd-backups — OUTSIDE the
+        //    extensions dir, because OpenClaw plugin discovery scans every
+        //    extensions/ child and would report the backup as a duplicate
+        //    "principles-disciple" plugin on every gateway startup.
         if (createBackup) {
-            const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
-            backupPath = path.join(path.dirname(targetDir), `.pd-backup-${timestamp}`);
+            backupPath = reservePdBackupDestination(path.basename(targetDir));
             copyDirRecursive(targetDir, backupPath, SKIP_DIRS);
         }
         // 3. Download and extract new version (with timeout + retry)
@@ -355,6 +460,9 @@ async function doApplyUpdate(options, workspaceDir) {
             copyFileTo(path.join(tempDir, file), path.join(targetDir, file));
             updatedFiles.push(file);
         }
+        // 4b. The incoming manifest declares the product-default skill language
+        // (zh); restore the language this install was materialized with.
+        reapplySkillLanguage(targetDir, skillLanguage);
         // Fix 3: deletions intentionally skipped — see comment above.
         // 5. Update package.json version
         const pkgPath = path.join(targetDir, 'package.json');
@@ -487,7 +595,13 @@ async function doInlineFullUpdate(workspaceDir) {
     }
     // Capture version before changes
     const fromVersion = readCurrentVersion(extDir) ?? 'unknown';
+    // Capture the installed skill language before the tarball's manifest
+    // overwrites it (PR #1332 companion — see reapplySkillLanguage).
+    const skillLanguage = detectInstalledSkillLanguage(extDir);
     let tempDir;
+    // Heal legacy installs: move old backups out of the extensions dir so
+    // OpenClaw discovery stops reporting a duplicate plugin (see pd-backups.ts).
+    logLegacyBackupMigration('pd-update-full');
     try {
         // 2. Fetch installer package info from npm
         const response = await fetchWithRetry(NPM_REGISTRY_INSTALLER, 'Installer registry check');
@@ -527,6 +641,9 @@ async function doInlineFullUpdate(workspaceDir) {
         const pluginSrc = path.join(tempDir, 'plugin');
         if (fs.existsSync(pluginSrc)) {
             copyDirRecursive(pluginSrc, extDir, SKIP_DIRS);
+            // The incoming manifest declares the product-default skill language
+            // (zh); restore the language this install was materialized with.
+            reapplySkillLanguage(extDir, skillLanguage);
         }
         //    b. console/ → extDir/console/ (overwrite dist/ files; do NOT rmSync —
         //       console/node_modules/ may contain locked native modules like
@@ -725,7 +842,7 @@ export async function handleUpdateRoute(req, res, workspaceDir, subPath) {
                 return;
             }
             if (!validatePathInWorkspace(backupDir, workspaceDir)) {
-                sendBadRequest(res, 'backupDir must be within workspace or extensions directory');
+                sendBadRequest(res, 'backupDir must be within the workspace, extensions directory, or PD backups directory');
                 return;
             }
             const result = await doRollbackUpdate({ targetDir, backupDir }, workspaceDir);

package/console/dist/server/utils/pd-backups.d.ts

@@ -0,0 +1,24 @@
+export interface LegacyBackupMigrationResult {
+    movedFrom: string[];
+    failed: {
+        name: string;
+        reason: string;
+    }[];
+}
+/** Backups root — outside the extensions dir OpenClaw scans for plugins. */
+export declare function resolvePdBackupsRoot(): string;
+/**
+ * Reserve a unique backup destination under the backups root:
+ * <root>/<targetName>-<ISO timestamp>, with a numeric suffix on collision.
+ * Atomic reservation via plain (non-recursive) mkdirSync — EEXIST means the
+ * name is taken, retry with the next suffix. The retry loop is bounded; never
+ * poll existsSync in a loop (a stale/mocked always-true predicate makes it
+ * unbounded).
+ */
+export declare function reservePdBackupDestination(targetName: string): string;
+/**
+ * Move legacy PD backup directories out of the extensions dir into the
+ * backups root, so OpenClaw stops discovering them as duplicate plugins.
+ * Best-effort per entry (rc-9: failures are reported, never silent).
+ */
+export declare function migrateLegacyExtensionBackups(): LegacyBackupMigrationResult;

package/console/dist/server/utils/pd-backups.js

@@ -0,0 +1,125 @@
+/**
+ * PD plugin backup location utilities.
+ *
+ * Backups must NEVER live inside ~/.openclaw/extensions: OpenClaw's plugin
+ * discovery scans every child directory of the extensions root, so a backup
+ * containing package.json (openclaw.extensions) + dist/bundle.js is discovered
+ * as a SECOND "principles-disciple" plugin, producing
+ * "duplicate plugin id detected; global plugin will be overridden by global
+ * plugin" on every gateway startup.
+ *
+ * Backups therefore live in <openclawHome>/pd-backups, which is outside every
+ * plugin discovery root. Legacy backups that older PD versions left inside
+ * extensions/ (".pd-backup-<ts>" from the console updater,
+ * "principles-disciple.backup.<ms>" from the installer) are migrated out by
+ * migrateLegacyExtensionBackups().
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+/**
+ * Resolve the OpenClaw install home.
+ * Priority: OPENCLAW_HOME env var (explicit override) > ~/.openclaw
+ */
+function resolveOpenClawHome() {
+    const envHome = process.env.OPENCLAW_HOME;
+    if (envHome && envHome.trim().length > 0)
+        return path.resolve(envHome);
+    return path.join(os.homedir(), '.openclaw');
+}
+/** Backups root — outside the extensions dir OpenClaw scans for plugins. */
+export function resolvePdBackupsRoot() {
+    return path.join(resolveOpenClawHome(), 'pd-backups');
+}
+/**
+ * Extract a POSIX errno code from a thrown fs error (rc-2: type guard, no
+ * blind `as` cast on the error object).
+ */
+function getErrorCode(err) {
+    if (err !== null && typeof err === 'object' && Object.hasOwn(err, 'code')) {
+        const { code } = err;
+        return typeof code === 'string' ? code : undefined;
+    }
+    return undefined;
+}
+/**
+ * Reserve a unique backup destination under the backups root:
+ * <root>/<targetName>-<ISO timestamp>, with a numeric suffix on collision.
+ * Atomic reservation via plain (non-recursive) mkdirSync — EEXIST means the
+ * name is taken, retry with the next suffix. The retry loop is bounded; never
+ * poll existsSync in a loop (a stale/mocked always-true predicate makes it
+ * unbounded).
+ */
+export function reservePdBackupDestination(targetName) {
+    const root = resolvePdBackupsRoot();
+    fs.mkdirSync(root, { recursive: true });
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    let lastError;
+    for (let attempt = 0; attempt < 100; attempt++) {
+        const suffix = attempt === 0 ? '' : `-${attempt}`;
+        const candidate = path.join(root, `${targetName}-${timestamp}${suffix}`);
+        try {
+            fs.mkdirSync(candidate);
+            return candidate;
+        }
+        catch (err) {
+            if (getErrorCode(err) === 'EEXIST') {
+                lastError = err;
+                continue;
+            }
+            throw err;
+        }
+    }
+    throw new Error(`Could not reserve a unique backup directory under ${root}: ${lastError instanceof Error ? lastError.message : String(lastError)}`);
+}
+/**
+ * Backup directory names older PD versions created as siblings of the plugin
+ * inside the extensions dir (both are re-discovered as duplicate plugins).
+ */
+function isLegacyPdBackupName(name) {
+    // Console updater (<= 2026-08): ".pd-backup-<ISO ts>" sibling.
+    if (name.startsWith('.pd-backup-'))
+        return true;
+    // Installer (<= 2026-08): "<extDir>.backup.<epoch ms>" sibling.
+    return /^principles-disciple\.backup\.\d+$/.test(name);
+}
+/**
+ * Move legacy PD backup directories out of the extensions dir into the
+ * backups root, so OpenClaw stops discovering them as duplicate plugins.
+ * Best-effort per entry (rc-9: failures are reported, never silent).
+ */
+export function migrateLegacyExtensionBackups() {
+    const result = { movedFrom: [], failed: [] };
+    const extensionsDir = path.join(resolveOpenClawHome(), 'extensions');
+    let entries;
+    try {
+        entries = fs.readdirSync(extensionsDir, { withFileTypes: true });
+    }
+    catch {
+        return result; // no extensions dir — nothing to migrate
+    }
+    const root = resolvePdBackupsRoot();
+    for (const entry of entries) {
+        if (!entry.isDirectory() || !isLegacyPdBackupName(entry.name))
+            continue;
+        const from = path.join(extensionsDir, entry.name);
+        let to = path.join(root, entry.name);
+        let suffix = 1;
+        while (fs.existsSync(to)) {
+            to = path.join(root, `${entry.name}-${suffix}`);
+            suffix += 1;
+        }
+        try {
+            fs.mkdirSync(root, { recursive: true });
+            fs.renameSync(from, to);
+            result.movedFrom.push(from);
+        }
+        catch (err) {
+            result.failed.push({
+                name: entry.name,
+                reason: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    return result;
+}

package/console/dist/web/assets/app.css

@@ -2234,6 +2234,9 @@
     -moz-user-select: none;
          user-select: none;
   }
+  .\[pd-console\:update\] {
+    pd-console: update;
+  }
   @media (hover: hover) {
     .group-hover\:opacity-100:is(:where(.group):hover *) {
       opacity: 100%;

package/core/dist/runtime-v2/__tests__/architecture-regression.test.js

@@ -328,6 +328,12 @@ const KNOWN_PLUGIN_CORE_FILES = new Set([
     // I/O shell: reads .pd/config.yaml, constructs PiAiRuntimeAdapter, writes trajectory.
     // Pure detection logic lives in @principles/core/runtime-v2/signal-collector/.
     'signal-collector-host.ts',
+    // PRI-530: Plugin I/O boundary — sync readonly state.db reads resolving principle
+    // receipt attribution (title fallback chain / approval date / source summary).
+    'principle-receipt-metadata.ts',
+    // PRI-531: Plugin I/O boundary — durable receipt ledger writes (state.db
+    // principle_applications inserts + 90-day retention sweep).
+    'principle-application-ledger.ts',
     'pain-lifecycle.ts',
     'session-tracker.ts',
     // PRI-459: now a thin re-export adapter over @principles/core/principle-tree-ledger.
@@ -429,7 +435,10 @@ describe('PRI-212 plugin core anti-growth guard', () => {
         // collection I/O host (correction + empathy upstream merge). Reads
         // .pd/config.yaml, constructs PiAiRuntimeAdapter, writes trajectory. Pure
         // detection logic lives in @principles/core/runtime-v2/signal-collector/.
-        expect(KNOWN_PLUGIN_CORE_FILES.size).toBe(94);
+        // PRI-530: Added principle-receipt-metadata.ts (94 → 95) — plugin I/O boundary
+        // for principle receipt attribution reads (readonly state.db joins).
+        // PRI-531: Added principle-application-ledger.ts (95 → 96) — receipt ledger writer.
+        expect(KNOWN_PLUGIN_CORE_FILES.size).toBe(96);
     });
 });
 const REQUIRED_TEST_FILES = [