chainlesschain 0.166.89 → 0.166.91

package/src/commands/automation.js

@@ -107,6 +107,20 @@ function _dbFromCtx(cmd) {
   return null;
 }
 
+function reportExecution(execution) {
+  const message = `Execution ${execution.id} → ${execution.status}`;
+  if (execution.status === EXECUTION_STATUS.SUCCESS) {
+    logger.success(message);
+  } else if (execution.status === EXECUTION_STATUS.SIMULATED) {
+    logger.log(`${message} (simulation only; no external actions applied)`);
+  } else {
+    logger.error(
+      `${message}: ${execution.error || "execution did not succeed"}`,
+    );
+    process.exitCode = 1;
+  }
+}
+
 async function readBoundedJsonStdin(options, maximum = 80 * 1024) {
   if (options?.jsonStdin !== true) {
     throw new Error("--json-stdin is required for routine definitions");
@@ -665,8 +679,18 @@ function _wire(root) {
           action,
           expectedRevision: opts.expectedRevision,
         });
-        if (opts.json) console.log(JSON.stringify(result, null, 2));
-        else logger.success(`${flowId} ${action} completed`);
+        if (opts.json) {
+          console.log(JSON.stringify(result, null, 2));
+          if (
+            [EXECUTION_STATUS.FAILED, EXECUTION_STATUS.UNSUPPORTED].includes(
+              result.result?.status,
+            )
+          ) {
+            process.exitCode = 1;
+          }
+        } else if (result.result?.id && result.result?.flowId) {
+          reportExecution(result.result);
+        } else logger.success(`${flowId} ${action} completed`);
       } catch (e) {
         logger.error(e.message);
         process.exitCode = 1;
@@ -1033,14 +1057,17 @@ function _wire(root) {
 
   root
     .command("fire-trigger <triggerId>")
-    .description("Simulate trigger firing (executes flow)")
+    .description("Fire a trigger; use --test for simulation")
     .option("-i, --input <json>", "Input data as JSON")
+    .option("--test", "Simulate only; no external actions are applied")
     .action(async (triggerId, opts, cmd) => {
       const db = _dbFromCtx(cmd);
       try {
         const input = parseJsonOption(opts.input, "--input") || {};
-        const exec = fireTrigger(db, triggerId, input);
-        logger.success(`Fired trigger → exec ${chalk.cyan(exec.id)}`);
+        const exec = fireTrigger(db, triggerId, input, {
+          testMode: Boolean(opts.test),
+        });
+        reportExecution(exec);
         logger.log(`  status:   ${exec.status}`);
         logger.log(`  duration: ${exec.durationMs}ms`);
         logger.log(`  steps:    ${exec.stepsLog.length}`);
@@ -1095,9 +1122,9 @@ function _wire(root) {
 
   root
     .command("execute <flowId>")
-    .description("Manually execute a flow (simulated)")
+    .description("Execute a flow; use --test for simulation")
     .option("-i, --input <json>", "Input data as JSON")
-    .option("--test", "Test mode (marks execution as test)")
+    .option("--test", "Simulate only; no external actions are applied")
     .action(async (flowId, opts, cmd) => {
       const db = _dbFromCtx(cmd);
       try {
@@ -1106,7 +1133,7 @@ function _wire(root) {
           inputData: input,
           testMode: Boolean(opts.test),
         });
-        logger.success(`Execution ${chalk.cyan(exec.id)} → ${exec.status}`);
+        reportExecution(exec);
         logger.log(`  duration: ${exec.durationMs}ms`);
         logger.log(`  steps:    ${exec.stepsLog.length}`);
         if (exec.error) logger.log(chalk.red(`  error: ${exec.error}`));

package/src/commands/hub.js

@@ -3446,6 +3446,139 @@ function _defaultKnownVendors() {
 
 // ─── Commander wire-up ───────────────────────────────────────────────
 
+async function cmdDerivation(operation, reference, options = {}) {
+  try {
+    if (
+      reference &&
+      (!["event", "person", "place", "item", "topic"].includes(
+        reference.entityType,
+      ) ||
+        typeof reference.entityId !== "string" ||
+        !reference.entityId.trim() ||
+        reference.entityId.length > 1024)
+    ) {
+      throw new Error("A valid entity type and ID are required");
+    }
+    if (operation === "delete" && options.confirm !== true) {
+      throw new Error(
+        "Normalized entity deletion requires --confirm; raw archive is retained",
+      );
+    }
+    if (
+      operation === "prune" &&
+      options.confirm !== true &&
+      options.dryRun !== true
+    ) {
+      throw new Error("Retired derivation receipt pruning requires --confirm");
+    }
+    if (
+      operation === "prune" &&
+      (!Array.isArray(options.consumer) ||
+        options.consumer.length < 1 ||
+        options.consumer.length > 100 ||
+        options.consumer.some(
+          (id) => typeof id !== "string" || !id.trim() || id.length > 1024,
+        ))
+    ) {
+      throw new Error("Select between 1 and 100 retired consumer IDs");
+    }
+    const limit = options.limit === undefined ? 100 : Number(options.limit);
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 1000) {
+      throw new Error("Derivation limit must be between 1 and 1000");
+    }
+    const budget = {};
+    for (const name of ["maxVaultBytes", "minFreeBytes", "reserveBytes"]) {
+      if (options[name] === undefined) continue;
+      const value = Number(options[name]);
+      if (!Number.isSafeInteger(value) || value < 0)
+        throw new Error(`${name} must be a non-negative safe integer`);
+      budget[name] = value;
+    }
+    if (options.audit && (options.state || options.kind)) {
+      throw new Error(
+        "Consumer audit includes all kinds and states; omit --kind and --state",
+      );
+    }
+    if (
+      operation === "status" &&
+      Object.keys(budget).length &&
+      !options.storage
+    ) {
+      throw new Error(
+        "Storage budget options require --storage for derivation-status",
+      );
+    }
+    // Check before constructing a registry: full hub startup may rebuild indexes.
+    if (operation === "retry" && Object.keys(budget).length) {
+      const minimal = await (options._getHub || getHubMinimal)();
+      minimal.vault.assertStorageBudget(budget);
+    }
+    if (operation === "status" && options.storage) {
+      if (options.adapter !== undefined || options.scope !== undefined) {
+        throw new Error(
+          "Storage reports cover the whole vault; omit --adapter and --scope",
+        );
+      }
+      const minimal = await (options._getHub || getHubMinimal)();
+      const result = { storage: minimal.vault.assertStorageBudget(budget) };
+      printJson(result);
+      return result;
+    }
+    const hub = await (
+      options._getHub ||
+      (operation === "consumers" || (operation === "prune" && options.dryRun)
+        ? getHubMinimal
+        : getHub)
+    )();
+    const filters = { adapter: options.adapter, scope: options.scope };
+    let result;
+    if (operation === "consumers") {
+      result = options.audit
+        ? hub.vault.getDerivationStore().auditConsumers({
+            afterConsumerId: options.after,
+            limit,
+          })
+        : hub.vault.getDerivationStore().listConsumers({
+            state: options.state,
+            kind: options.kind,
+            afterConsumerId: options.after,
+            limit,
+          });
+    } else if (operation === "prune") {
+      result = hub.vault.getDerivationStore().pruneRetiredConsumers({
+        consumerIds: options.consumer,
+        activeConsumerId: hub.registry?.consumerId,
+        limit,
+        ...(options.dryRun ? { dryRun: true } : {}),
+      });
+    } else if (operation === "retry") {
+      if (Object.keys(budget).length) hub.vault.assertStorageBudget(budget);
+      result = await hub.registry.retryDerivations({ ...filters, limit });
+    } else if (operation === "state") {
+      result = hub.vault
+        .getDerivationStore()
+        .getState(reference.entityType, reference.entityId, {
+          consumerId: hub.registry.consumerId,
+        });
+    } else if (operation === "delete") {
+      const deleted = hub.vault.deleteEntity(
+        reference.entityType,
+        reference.entityId,
+      );
+      result = {
+        deleted,
+        derivations: await hub.registry.retryDerivations({ limit: 1000 }),
+      };
+    } else {
+      result = hub.registry.getDerivationStatus(filters);
+    }
+    printJson(result);
+    return result;
+  } catch (error) {
+    fail(null, error, options.json);
+  }
+}
+
 export function registerHubCommand(program, dependencies = {}) {
   const factory = readEvolutionCompositionFactory(dependencies);
   const invocationOptions = (options) => {
@@ -3571,6 +3704,96 @@ export function registerHubCommand(program, dependencies = {}) {
     .option("--json", "Output JSON")
     .action(cmdListAdapters);
 
+  for (const [name, operation, description] of [
+    [
+      "derivation-status",
+      "status",
+      "Inspect KG/RAG delivery status for this vault",
+    ],
+    [
+      "retry-derivations",
+      "retry",
+      "Retry a bounded page of KG/RAG work from current vault state",
+    ],
+  ]) {
+    const command = hub
+      .command(name)
+      .description(description)
+      .option("--adapter <name>", "Filter by source adapter")
+      .option("--scope <scope>", "Filter by source scope")
+      .option("--json", "Output JSON");
+    command
+      .option("--max-vault-bytes <n>", "Preflight maximum DB + WAL + SHM bytes")
+      .option(
+        "--min-free-bytes <n>",
+        "Preflight minimum free disk bytes after reserve",
+      )
+      .option(
+        "--reserve-bytes <n>",
+        "Caller-estimated extra bytes for preflight (not a reservation)",
+      );
+    if (operation === "retry")
+      command.option("--limit <n>", "Maximum deliveries (1-1000)", "100");
+    else
+      command.option(
+        "--storage",
+        "Inspect storage only and check the supplied byte budget",
+      );
+    command.action((options) => cmdDerivation(operation, null, options));
+  }
+
+  hub
+    .command("derivation-consumers")
+    .description(
+      "List registered derivation consumers without retirement tokens",
+    )
+    .option("--state <state>", "Filter by active or retired")
+    .option(
+      "--audit",
+      "Inventory registered and historical consumers with retention reasons and receipt counts",
+    )
+    .option("--kind <kind>", "Filter by ephemeral or persistent")
+    .option("--after <id>", "Continue after a consumer ID")
+    .option("--limit <n>", "Maximum consumers (1-1000)", "100")
+    .option("--json", "Output JSON")
+    .action((options) => cmdDerivation("consumers", null, options));
+
+  hub
+    .command("prune-derivations")
+    .description(
+      "Prune non-running receipts of explicitly selected retired ephemeral consumers",
+    )
+    .requiredOption("--consumer <ids...>", "Retired consumer IDs (1-100)")
+    .option("--limit <n>", "Maximum receipts removed (1-1000)", "100")
+    .option("--confirm", "Confirm removal of these retired projection receipts")
+    .option(
+      "--dry-run",
+      "Validate IDs and preview bounded receipt cleanup without deletion",
+    )
+    .option("--json", "Output JSON")
+    .action((options) => cmdDerivation("prune", null, options));
+
+  hub
+    .command("derivation-state <entityType> <entityId>")
+    .description(
+      "Inspect an entity's source revision and KG/RAG receipts without its payload",
+    )
+    .option("--json", "Output JSON")
+    .action((entityType, entityId, options) =>
+      cmdDerivation("state", { entityType, entityId }, options),
+    );
+
+  hub
+    .command("delete-entity <entityType> <entityId>")
+    .description(
+      "Delete a normalized entity and queue index removal; raw archive remains and reimport may restore it",
+    )
+    .option("--confirm", "Confirm deletion of this normalized entity")
+    .option("--json", "Output JSON")
+    .action((entityType, entityId, options) =>
+      cmdDerivation("delete", { entityType, entityId }, options),
+    );
+
   hub
     .command("readiness")
     .description(
@@ -4318,6 +4541,7 @@ export function registerHubCommand(program, dependencies = {}) {
 // `_wizard` / `_factoryDeps` / `_knownVendors` injected, bypassing the
 // real `getHub()` call. The commander wiring above is the runtime path.
 export const _internal = {
+  cmdDerivation,
   cmdAsk,
   cmdRepl,
   cmdRetrieveContext,

package/src/commands/project.js

@@ -14,6 +14,8 @@
  *   cc project list [--user <id>] [--status <s>] [--limit <n>] [--json]
  *   cc project show <id> [--json]
  *   cc project delete <id> [--hard] [--json]
+ *   cc project risk-evaluate --snapshot <json-file> [--json]
+ *   cc project task-description-preview --snapshot <json-file> [--json]
  *
  * 设计 (per #21 v1.2 GA 反馈 "目标在手机端做ai项目的交互要像在电脑端那样丝滑"):
  *   CLI 直接读写 desktop chainlesschain.db, 立刻在 desktop UI 出现,
@@ -21,6 +23,8 @@
  */
 
 import chalk from "chalk";
+import fs from "node:fs";
+import path from "node:path";
 import {
   openProjectsDb,
   defaultProjectDbPath,
@@ -30,6 +34,114 @@ import {
 } from "../lib/project-runtime.js";
 
 const DEFAULT_USER = "default";
+const MAX_PROJECT_SNAPSHOT_BYTES = 2 * 1024 * 1024;
+
+function snapshotFailure(code) {
+  const error = new Error(code);
+  error.code = code;
+  throw error;
+}
+
+/** Read a user-selected regular snapshot without following links or devices. */
+function readProjectSnapshot(file, io = fs) {
+  if (
+    typeof file !== "string" ||
+    !file ||
+    /^[\\/]{2}[?.][\\/]/u.test(file) ||
+    (process.platform === "win32" &&
+      /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/iu.test(
+        path.basename(file),
+      ))
+  )
+    snapshotFailure("SNAPSHOT_INVALID_PATH");
+  let fd;
+  try {
+    // Reject FIFO/device paths before opening. O_NONBLOCK also covers a POSIX
+    // file replaced by a FIFO between this check and the descriptor open.
+    if (!io.lstatSync(file).isFile())
+      snapshotFailure("SNAPSHOT_REGULAR_FILE_REQUIRED");
+    fd = io.openSync(
+      file,
+      fs.constants.O_RDONLY |
+        (fs.constants.O_NONBLOCK || 0) |
+        (fs.constants.O_NOFOLLOW || 0),
+    );
+    const before = io.fstatSync(fd);
+    if (!before.isFile()) snapshotFailure("SNAPSHOT_REGULAR_FILE_REQUIRED");
+    if (
+      !Number.isSafeInteger(before.size) ||
+      before.size < 0 ||
+      before.size > MAX_PROJECT_SNAPSHOT_BYTES
+    )
+      snapshotFailure("SNAPSHOT_FILE_TOO_LARGE");
+    const data = Buffer.alloc(before.size + 1);
+    let count = 0;
+    while (count < data.length) {
+      const read = io.readSync(fd, data, count, data.length - count, count);
+      if (read === 0) break;
+      count += read;
+    }
+    const after = io.fstatSync(fd);
+    if (
+      count !== before.size ||
+      after.size !== before.size ||
+      after.mtimeMs !== before.mtimeMs ||
+      after.ctimeMs !== before.ctimeMs
+    )
+      snapshotFailure("SNAPSHOT_CHANGED_DURING_READ");
+    let text;
+    try {
+      text = new TextDecoder("utf-8", { fatal: true }).decode(
+        data.subarray(0, count),
+      );
+    } catch {
+      snapshotFailure("SNAPSHOT_INVALID_UTF8");
+    }
+    try {
+      return JSON.parse(text);
+    } catch {
+      snapshotFailure("SNAPSHOT_INVALID_JSON");
+    }
+  } catch (error) {
+    if (error.code?.startsWith("SNAPSHOT_")) throw error;
+    snapshotFailure("SNAPSHOT_READ_FAILED");
+  } finally {
+    if (fd !== undefined) io.closeSync(fd);
+  }
+}
+
+function printSnapshotError(error, options) {
+  const code =
+    typeof error?.code === "string" &&
+    /^(SNAPSHOT|ACTION)_[A-Z_]+$/u.test(error.code)
+      ? error.code
+      : "SNAPSHOT_EVALUATION_FAILED";
+  if (options.json)
+    console.log(JSON.stringify({ status: "error", error: code }));
+  else console.error(chalk.red(code));
+  process.exitCode = 2;
+}
+
+function printProjectRisk(result) {
+  console.log("Offline project risk evaluation (unverified snapshot)");
+  console.log(`Status: ${result.status}`);
+  console.log(`Rule: ${result.ruleVersion}`);
+  if (result.asOf) console.log(`As of: ${result.asOf}`);
+  if (result.inputDigest) console.log(`Input: ${result.inputDigest}`);
+  if (result.status !== "evaluated") {
+    console.log(`Reasons: ${result.reasonCodes.join(", ")}`);
+    return;
+  }
+  console.log(
+    `Tasks: ${result.summary.taskCount}; matching tasks: ${result.summary.riskTaskCount}; overdue: ${result.summary.overdueTaskCount}; blocked: ${result.summary.blockedTaskCount}`,
+  );
+  for (const task of result.tasks) {
+    const blockers = task.blockingTaskRefs.map((ref) => ref.id).join(", ");
+    console.log(
+      `${task.taskRef.id}: ${task.reasonCodes.join(", ")}${blockers ? ` (dependencies: ${blockers})` : ""}`,
+    );
+  }
+}
 
 function _now() {
   return Date.now();
@@ -74,6 +186,54 @@ export function registerProjectCommand(program) {
       "Manage desktop projects (shared SQLite, syncs to mobile via Phase 3d)",
     );
 
+  cmd
+    .command("risk-evaluate")
+    .description(
+      "Evaluate overdue tasks and direct blockers in an offline snapshot",
+    )
+    .requiredOption(
+      "--snapshot <json-file>",
+      "Complete project risk snapshot (max 2 MiB)",
+    )
+    .option("--json", "Output JSON")
+    .action(async (options) => {
+      try {
+        const snapshot = readProjectSnapshot(options.snapshot);
+        const { evaluateProjectRiskSnapshot } =
+          await import("@chainlesschain/session-core/project-risk-evaluation");
+        const result = evaluateProjectRiskSnapshot(snapshot);
+        if (options.json) console.log(JSON.stringify(result, null, 2));
+        else printProjectRisk(result);
+        if (result.status === "insufficient-data") process.exitCode = 2;
+      } catch (error) {
+        printSnapshotError(error, options);
+      }
+    });
+
+  cmd
+    .command("task-description-preview")
+    .description(
+      "Preview a task description request from an unverified offline snapshot",
+    )
+    .requiredOption(
+      "--snapshot <json-file>",
+      "Task/project/description/idempotencyKey JSON (max 2 MiB)",
+    )
+    .option("--json", "Output JSON")
+    .action(async (options) => {
+      try {
+        const snapshot = readProjectSnapshot(options.snapshot);
+        const { createTaskDescriptionPreview } =
+          await import("@chainlesschain/session-core/task-description-action-service");
+        const result = createTaskDescriptionPreview(snapshot);
+        if (!options.json)
+          console.log("Offline task description preview (unverified snapshot)");
+        console.log(JSON.stringify(result, null, 2));
+      } catch (error) {
+        printSnapshotError(error, options);
+      }
+    });
+
   // ===== init =====
   cmd
     .command("init <name>")
@@ -255,4 +415,6 @@ export function registerProjectCommand(program) {
 // 暴露给单测
 export const _projectInternals = {
   defaultProjectDbPath,
+  readProjectSnapshot,
+  MAX_PROJECT_SNAPSHOT_BYTES,
 };

package/src/data/changelog.json

@@ -1,6 +1,32 @@
 {
   "source": "CHANGELOG.md",
   "releases": [
+    {
+      "productVersion": null,
+      "cliVersion": "0.166.91",
+      "cliVersions": ["0.166.91"],
+      "date": null,
+      "title": "",
+      "sections": [
+        {
+          "heading": "Fixed - cc CLI 0.166.91: cross-platform release validation",
+          "body": "- Accept verified directory identities through the Windows Server 2025 native\n  file-information API, while retaining handle binding and reparse-point checks.\n- Preserve Windows native evaluator failure and cleanup evidence when the helper\n  cannot publish a settlement. Compare journal identities within their pathname\n  and descriptor domains on supported Node versions.\n- Keep literal audit search assertions independent of redacted operation text;\n  verify that unsafe legacy text remains omitted from query results.\n- Give the receipt signer deadline test enough admission time on hosted runners\n  and verify that the signer is actually invoked before its bounded timeout.\n- Regenerate the bundled CLI changelog from its canonical source.\n- Capture JetBrains transcript snapshots on the event dispatch thread during\n  cross-platform host validation, retaining the full transcript assertions.\n- Preserve equivalent protected Windows evaluator ACLs across .NET Framework\n  and PowerShell's .NET runtime through the native security API.\n- Retry cooperative lock release during nested safe owner reads without treating\n  it as corruption; losing a held lock still fails closed.\n- Pin the patched `shell-quote` dependency in both workspace and standalone\n  desktop installs to reject command injection after shell comment tokens.\n- Publish Session Core `0.3.16` and Personal Data Hub `0.4.64` before CLI\n  `0.166.91`, with exact dependency pins and public package verification.\n- Pair VS Code `0.37.136` and JetBrains `0.4.154` with CLI `0.166.91` after\n  the full exact-commit CLI and IDE validation workflows pass."
+        }
+      ]
+    },
+    {
+      "productVersion": null,
+      "cliVersion": "0.166.90",
+      "cliVersions": ["0.166.90"],
+      "date": "2026-10-06",
+      "title": "",
+      "sections": [
+        {
+          "heading": "Added - cc CLI 0.166.90: recoverable projections and project risk evidence",
+          "body": "- Verified on 2026-10-06: exact release commit `28cff6adc8` passed complete\n  CLI CI, Strict Sandbox, IDE host and security gates. Session Core `0.3.15`,\n  Agent SDK `0.2.13`, PDH `0.4.63` and CLI `0.166.90` were published through\n  GitHub Actions OIDC with independent public archive verification. Open VSX\n  `0.37.135` and JetBrains `0.4.153` are public; both publication workflows\n  succeeded, and JetBrains approval/listing was independently read back.\n  Desktop workbench changes are outside the separate v5.0.3.138 installer.\n- Publish Personal Data Hub `0.4.63` and Session Core `0.3.15` before the CLI,\n  with exact dependency pins and public tarball verification. Require the full\n  PDH suite with its declared native SQLCipher driver on Linux, Windows and macOS.\n- Publish Agent SDK `0.2.13` with Vitest `4.1.11` test tooling to remove the\n  vulnerable Tinypool dependency, and upgrade the workspace proxy-addr to\n  `2.0.8`. Require SDK build and tests on the exact Linux, Windows and macOS\n  release commit before OIDC publication.\n- Persist PDH projection receipts, recover incomplete derivations and support\n  bounded receipt retention. Harden RAG updates, audit redaction and capability\n  reporting so unavailable sources do not appear as successful live collection.\n- Add offline project risk evaluation and version-bound task description\n  previews. Session Core also supplies native SQLite action/read services and\n  saved rule/source reviews for the desktop project workbench; CLI previews\n  carry unverified snapshot authority and do not execute those desktop actions.\n- Pair VS Code `0.37.135` and JetBrains `0.4.153` with CLI `0.166.90` after\n  exact-commit release checks and public npm readback."
+        }
+      ]
+    },
     {
       "productVersion": null,
       "cliVersion": "0.166.89",

package/src/gateways/ws/personal-data-hub-protocol.js

@@ -193,7 +193,8 @@ async function withHub(fn, loadHub = getHub) {
 }
 
 function governedHubLoader(factory) {
-  if (typeof factory === "function") return () => getGovernedAnalysisHub(factory);
+  if (typeof factory === "function")
+    return () => getGovernedAnalysisHub(factory);
   const error = new Error(
     "Personal Data Hub model egress requires an authenticated evolution composition factory",
   );
@@ -201,16 +202,24 @@ function governedHubLoader(factory) {
   throw error;
 }
 
+function validateEntityReference(entityType, entityId) {
+  if (
+    !["event", "person", "place", "item", "topic"].includes(entityType) ||
+    typeof entityId !== "string" ||
+    !entityId.trim() ||
+    entityId.length > 1024
+  ) {
+    throw new Error("A valid entityType and entityId are required");
+  }
+}
+
 export const PERSONAL_DATA_HUB_HANDLERS = {
   "personal-data-hub.ask": async (msg, context = {}) => {
     const factory = context.server?.evolutionCompositionFactory;
-    return withHub(
-      async (hub) => {
-        if (!hub.engine) throw new Error("Analysis engine unavailable");
-        return await hub.engine.ask(msg.question, msg.options || {});
-      },
-      governedHubLoader(factory),
-    );
+    return withHub(async (hub) => {
+      if (!hub.engine) throw new Error("Analysis engine unavailable");
+      return await hub.engine.ask(msg.question, msg.options || {});
+    }, governedHubLoader(factory));
   },
 
   // Path Y: prompt context only, no LLM call. Lets web-shell / mobile host
@@ -250,6 +259,43 @@ export const PERSONAL_DATA_HUB_HANDLERS = {
   "personal-data-hub.list-adapters": async () =>
     withHub((hub) => hub.registry.list()),
 
+  "personal-data-hub.derivation-status": async (msg) =>
+    withHub((hub) =>
+      hub.registry.getDerivationStatus({
+        adapter: msg.adapter,
+        scope: msg.scope,
+      }),
+    ),
+
+  "personal-data-hub.derivation-state": async (msg) =>
+    withHub((hub) => {
+      validateEntityReference(msg.entityType, msg.entityId);
+      return hub.vault
+        .getDerivationStore()
+        .getState(msg.entityType, msg.entityId, {
+          consumerId: hub.registry.consumerId,
+        });
+    }),
+
+  "personal-data-hub.retry-derivations": async (msg) =>
+    withHub((hub) =>
+      hub.registry.retryDerivations({
+        adapter: msg.adapter,
+        scope: msg.scope,
+        limit: msg.limit,
+      }),
+    ),
+
+  "personal-data-hub.delete-entity": async (msg) =>
+    withHub(async (hub) => {
+      if (msg.confirm !== true)
+        throw new Error("Entity deletion requires confirm: true");
+      validateEntityReference(msg.entityType, msg.entityId);
+      const deleted = hub.vault.deleteEntity(msg.entityType, msg.entityId);
+      const derivations = await hub.registry.retryDerivations({ limit: 1000 });
+      return { deleted, derivations };
+    }),
+
   // Per-adapter readiness ("能否采集 + 不能的原因"). Probes each adapter's
   // authenticate({ readinessOnly: true }) — see AdapterRegistry.readiness().
   // The web-shell PersonalDataHub view renders this as a 就绪状态 column so