chainlesschain 0.166.88 → 0.166.90

package/src/commands/agent-controlled-host.js

@@ -0,0 +1,220 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import {
+  normalizeAgentSandbox,
+  assertSandboxCapabilities,
+  assertSandboxAvailable,
+} from "../lib/agent-sandbox.js";
+import { isFormalQualityHermeticRuntime } from "../lib/formal-quality-eval-runtime.js";
+import { resolveCredentialEnvironmentValue } from "../lib/process-execution-broker/credential-transport.js";
+
+const MAX_JSON_BYTES = 1024 * 1024;
+
+function invalid(message, code = "CC_CONTROLLED_HOST_INVALID") {
+  return Object.assign(new Error(message), { code });
+}
+
+/** Read one bounded regular file through its opened identity, never create it. */
+function readJson(file) {
+  if (typeof file !== "string" || !path.isAbsolute(file))
+    throw invalid("Controlled-host JSON paths must be absolute");
+  const before = fs.lstatSync(file, { bigint: true });
+  if (!before.isFile() || before.isSymbolicLink())
+    throw invalid("Controlled-host JSON must be a regular non-symlink file");
+  const fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+  try {
+    const opened = fs.fstatSync(fd, { bigint: true });
+    if (
+      !opened.isFile() ||
+      opened.dev !== before.dev ||
+      opened.ino !== before.ino ||
+      opened.size < 1n ||
+      opened.size > BigInt(MAX_JSON_BYTES)
+    )
+      throw invalid("Controlled-host JSON identity or size is invalid");
+    const bytes = Buffer.alloc(Number(opened.size) + 1);
+    let size = 0;
+    while (size < bytes.length) {
+      const read = fs.readSync(fd, bytes, size, bytes.length - size, null);
+      if (!read) break;
+      size += read;
+    }
+    const after = fs.fstatSync(fd, { bigint: true });
+    if (
+      BigInt(size) !== opened.size ||
+      after.size !== opened.size ||
+      after.mtimeNs !== opened.mtimeNs ||
+      after.ctimeNs !== opened.ctimeNs
+    )
+      throw invalid("Controlled-host JSON changed while reading");
+    const value = JSON.parse(
+      new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(0, size)),
+    );
+    if (!value || typeof value !== "object" || Array.isArray(value))
+      throw invalid("Controlled-host JSON must contain an object");
+    return value;
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+/** Explicit one-shot entry. Provisioning is deliberately not available here. */
+export async function runControlledHost(options, dependencies = {}) {
+  const platform = dependencies.platform ?? process.platform;
+  if (platform !== "linux")
+    throw invalid(
+      "Controlled-host permission authority requires Linux",
+      "CC_SETTINGS_AUTHORITY_PLATFORM_UNSUPPORTED",
+    );
+  const env = dependencies.env ?? process.env;
+  if (isFormalQualityHermeticRuntime(env))
+    throw invalid(
+      "Controlled-host authority cannot run in a hermetic evaluator that suppresses permission providers",
+    );
+  if (!/^[a-zA-Z0-9._:-]{1,128}$/.test(options.context || ""))
+    throw invalid("An explicit controlled-host context is required");
+  if (
+    (options.check === true) ===
+    (typeof options.prompt === "string" && options.prompt.trim().length > 0)
+  )
+    throw invalid("Choose exactly one of --check or a non-empty --prompt");
+  if (
+    !options.check &&
+    ["provider", "model", "baseUrl"].some(
+      (key) => typeof options[key] !== "string" || !options[key].trim(),
+    )
+  )
+    throw invalid("A run requires explicit --provider, --model and --base-url");
+  const maxTurns =
+    options.maxTurns === undefined ? 10 : Number(options.maxTurns);
+  if (!Number.isSafeInteger(maxTurns) || maxTurns < 1 || maxTurns > 100)
+    throw invalid("--max-turns must be an integer from 1 to 100");
+  if (!["text", "json", "stream-json"].includes(options.outputFormat || "text"))
+    throw invalid("--output-format must be text, json or stream-json");
+  const cwd = dependencies.cwd ?? process.cwd();
+  const launch = readJson(options.launch);
+  const settings = readJson(options.sandboxSettings);
+  if (settings.engine !== "docker-egress" || settings.enabled === false)
+    throw invalid(
+      "Controlled-host entry requires enabled docker-egress sandbox settings",
+    );
+  const sandbox = normalizeAgentSandbox(true, { cwd, settings, network: true });
+  assertSandboxCapabilities(sandbox, {
+    host: { platform, arch: process.arch, release: os.release() },
+  });
+  const open =
+    dependencies.openHost ??
+    (await import("../runtime/permission-authority-host.js"))
+      .openPermissionAuthorityHost;
+  const host = open({ launch, contextId: options.context, env });
+  try {
+    // Reopening never provisions; runtimeOptions checks the actual invocation
+    // workspace and rejects writable roots overlapping the fixed authority.
+    host.runtimeOptions({ cwd, sandbox });
+    if (options.check) {
+      const capabilities = host.capabilities(sandbox);
+      const report = {
+        schema: "chainlesschain.controlled-host-check/v1",
+        authorityIdentityVerified: true,
+        backendExecutionVerified: false,
+        backendAvailabilityProbed: false,
+        capabilities,
+      };
+      (dependencies.writeOut ?? ((text) => process.stdout.write(text)))(
+        JSON.stringify(report) + "\n",
+      );
+      return { exitCode: 0, report };
+    }
+    // Availability is checked before resolving credentials or calling a model.
+    (dependencies.assertAvailable ?? assertSandboxAvailable)(sandbox);
+    let apiKey;
+    if (options.apiKeyEnv) {
+      apiKey = await resolveCredentialEnvironmentValue(options.apiKeyEnv, {
+        env,
+      });
+      if (!apiKey)
+        throw invalid("The selected API key environment source is unavailable");
+    }
+    return await host.runHeadless(
+      {
+        cwd,
+        sandbox,
+        prompt: options.prompt,
+        provider: options.provider,
+        model: options.model,
+        baseUrl: options.baseUrl,
+        apiKey,
+        maxTurns,
+        outputFormat: options.outputFormat || "text",
+        permissionMode: "dontAsk",
+        useRegisteredMcp: false,
+        strictMcpConfig: true,
+        ide: false,
+        pdh: false,
+        jetbrains: false,
+        slashMacros: false,
+        expandFileRefs: false,
+      },
+      dependencies.runtimeDependencies,
+    );
+  } finally {
+    host.close();
+  }
+}
+
+export function registerControlledHostCommand(agent, dependencies = {}) {
+  agent
+    .command("controlled-host")
+    .description(
+      "Run against a pre-provisioned Linux permission authority (one-shot, dontAsk)",
+    )
+    .requiredOption(
+      "--launch <file>",
+      "Absolute pre-provisioned launch descriptor JSON",
+    )
+    .requiredOption("--context <id>", "Exact provisioned workspace context ID")
+    .requiredOption(
+      "--sandbox-settings <file>",
+      "Absolute docker-egress sandbox settings JSON",
+    )
+    .option(
+      "--check",
+      "Verify configuration and authority identity only; no backend or model execution",
+    )
+    .option(
+      "--prompt <text>",
+      "Run one headless task in the bound current workspace",
+    )
+    .option("--provider <name>", "Explicit model provider")
+    .option("--model <name>", "Explicit model name")
+    .option("--base-url <url>", "Explicit provider endpoint")
+    .option(
+      "--api-key-env <name>",
+      "Credential environment variable or broker reference",
+    )
+    .option("--max-turns <n>", "Maximum task turns, 1-100", "10")
+    .option("--output-format <format>", "text | json | stream-json", "text")
+    .action(async (options, command) => {
+      try {
+        // Parent agent flags are a different launch contract. Never silently
+        // ignore a supplied --yolo, --bg, --settings or model override there.
+        if (
+          agent.options.some(
+            (option) =>
+              agent.getOptionValueSource(option.attributeName()) === "cli",
+          )
+        )
+          throw invalid(
+            "Place only controlled-host options after the subcommand; parent agent flags are unsupported",
+          );
+        const outcome = await runControlledHost(command.opts(), dependencies);
+        process.exitCode = outcome.exitCode;
+      } catch (error) {
+        process.stderr.write(
+          `${error.code || "CC_CONTROLLED_HOST_FAILED"}: ${error.message}\n`,
+        );
+        process.exitCode = 1;
+      }
+    });
+}

package/src/commands/agent.js

@@ -46,6 +46,7 @@ import {
   isFormalQualityHermeticRuntime,
 } from "../lib/formal-quality-eval-runtime.js";
 import { withQuietStdout } from "../runtime/quiet-stdout.js";
+import { registerControlledHostCommand } from "./agent-controlled-host.js";
 import { resolveCredentialEnvironmentValue } from "../lib/process-execution-broker/credential-transport.js";
 import {
   captureClaudeStorageLaunchEnvironment,
@@ -290,7 +291,7 @@ export function registerAgentCommand(program, dependencies = {}) {
       : captureSkillRetrievalRevocationReader(
           dependencies.skillRetrievalRevocationReader,
         );
-  program
+  const agent = program
     .command("agent")
     .aliases(["a", "exec"])
     .description(
@@ -2259,6 +2260,7 @@ export function registerAgentCommand(program, dependencies = {}) {
       // Interactive session ended (REPL closed) — settle the worktree.
       await _finishWorktree();
     });
+  registerControlledHostCommand(agent, dependencies.controlledHost);
 }
 
 export function registerSubAgentV2Command(program) {

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,85 @@ 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) {
+      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 hub = await (options._getHub || getHub)();
+    const filters = { adapter: options.adapter, scope: options.scope };
+    let result;
+    if (operation === "consumers") {
+      result = 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,
+      });
+    } else if (operation === "retry") {
+      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 +3650,73 @@ 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");
+    if (operation === "retry")
+      command.option("--limit <n>", "Maximum deliveries (1-1000)", "100");
+    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("--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("--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 +4464,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,
 };