scene-capability-engine 3.6.3 → 3.6.4

package/CHANGELOG.md

@@ -7,6 +7,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.6.4] - 2026-03-05
+
+### Added
+- Gradual state migration command group:
+  - `sce state plan`
+  - `sce state doctor`
+  - `sce state migrate` (dry-run default, `--apply` to write)
+  - `sce state export`
+- New migration manager module: `lib/state/state-migration-manager.js`.
+- SQLite index tables for staged migration of file-based registries:
+  - `agent_runtime_registry`
+  - `timeline_snapshot_registry`
+  - `scene_session_cycle_registry`
+  - `state_migration_registry`
+- Unit tests for state migration planning/execution/export:
+  - `tests/unit/state/state-migration-manager.test.js`
+  - `tests/unit/commands/state.test.js`
+- New reconciliation gate script for migration parity checks:
+  - `scripts/state-migration-reconciliation-gate.js`
+  - npm script: `gate:state-migration-reconciliation`
+- Session runtime diagnostics expansion:
+  - new command: `sce session list`
+  - `sce session show/list` JSON includes `session_source` and `scene_index` consistency metadata
+
+### Changed
+- Timeline runtime reads now prefer SQLite index entries (`timeline_snapshot_registry`) when available.
+- Scene session listing views now prefer SQLite cycle index entries (`scene_session_cycle_registry`) when available.
+- Agent registry writes now mirror to SQLite agent runtime index (`agent_runtime_registry`) as a best-effort sync.
+- `sce state doctor` now emits aggregate `summary` metrics and runtime read diagnostics (`runtime.timeline`, `runtime.scene_session`) to expose sqlite/file drift status for IDE and CI gates.
+- Startup compliance behavior hardened to avoid runtime side effects on read-only commands:
+  - `sce --version/-v`, `sce --help/-h`, `sce help`, and `sce version-info` now skip steering cleanup checks.
+  - steering compliance allowlist now includes `.sce/steering/manifest.yaml`, `compiled/`, and runtime lock/pending files.
+
 ## [3.6.3] - 2026-03-05
 
 ### Added

package/README.md

@@ -145,6 +145,14 @@ Studio task-stream output contract (default):
   - SQLite-only backend (`.sce/state/sce-state.sqlite`)
   - In-memory fallback only in `NODE_ENV=test` or when `SCE_STATE_ALLOW_MEMORY_FALLBACK=1`
   - Outside those conditions, unavailable SQLite support fails fast for task-ref/event persistence
+- Gradual file-to-sqlite migration tooling:
+  - `sce state plan --json`
+  - `sce state doctor --json`
+  - `sce state migrate --all --apply --json`
+  - `sce state export --out .sce/reports/state-migration/state-export.latest.json --json`
+  - reconciliation gate: `npm run gate:state-migration-reconciliation`
+  - runtime reads now prefer sqlite indexes for timeline/scene-session views when indexed data exists
+  - `state doctor` now emits `summary` and runtime diagnostics (`runtime.timeline`, `runtime.scene_session`) with read-source and consistency status
 - Write authorization lease model (SQLite-backed):
   - policy file: `.sce/config/authorization-policy.json`
   - grant lease: `sce auth grant --scope studio:* --reason "<reason>" --auth-password <password> --json`

package/README.zh.md

@@ -145,6 +145,14 @@ Studio 任务流输出契约（默认）：
   - 仅支持 SQLite 后端（`.sce/state/sce-state.sqlite`）
   - 仅在 `NODE_ENV=test` 或 `SCE_STATE_ALLOW_MEMORY_FALLBACK=1` 时允许内存回退
   - 在上述条件之外若 SQLite 不可用，任务引用/事件持久化会快速失败
+- 渐进式文件到 SQLite 迁移工具：
+  - `sce state plan --json`
+  - `sce state doctor --json`
+  - `sce state migrate --all --apply --json`
+  - `sce state export --out .sce/reports/state-migration/state-export.latest.json --json`
+  - 对账门禁：`npm run gate:state-migration-reconciliation`
+  - 运行时读取在存在索引数据时优先使用 SQLite（timeline/scene-session 视图）
+  - `state doctor` 新增 `summary` 与运行时诊断（`runtime.timeline`、`runtime.scene_session`），可直接读取读源与一致性状态
 - 写入授权租约模型（SQLite 持久化）：
   - 策略文件：`.sce/config/authorization-policy.json`
   - 申请租约：`sce auth grant --scope studio:* --reason "<原因>" --auth-password <密码> --json`

package/bin/scene-capability-engine.js

@@ -25,6 +25,7 @@ const { registerTimelineCommands } = require('../lib/commands/timeline');
 const { registerValueCommands } = require('../lib/commands/value');
 const { registerTaskCommands } = require('../lib/commands/task');
 const { registerAuthCommands } = require('../lib/commands/auth');
+const { registerStateCommands } = require('../lib/commands/state');
 const VersionChecker = require('../lib/version/version-checker');
 const {
   findLegacyKiroDirectories,
@@ -161,6 +162,9 @@ function isLegacyMigrationAllowlistedCommand(args) {
   if (command === 'help') {
     return true;
   }
+  if (command === 'version-info') {
+    return true;
+  }
 
   if (command === 'workspace') {
     const subcommand = args[commandIndex + 1];
@@ -195,6 +199,30 @@ function isTakeoverAutoApplySkippedCommand(args) {
   return subcommand === 'takeover-audit';
 }
 
+/**
+ * Commands/options that must be read-only and have no runtime side effects.
+ *
+ * @param {string[]} args
+ * @returns {boolean}
+ */
+function isNoMutationCommand(args) {
+  if (!Array.isArray(args) || args.length === 0) {
+    return false;
+  }
+
+  if (args.includes('-v') || args.includes('--version') || args.includes('-h') || args.includes('--help')) {
+    return true;
+  }
+
+  const commandIndex = findCommandIndex(args);
+  if (commandIndex < 0) {
+    return false;
+  }
+
+  const command = args[commandIndex];
+  return command === 'help' || command === 'version-info';
+}
+
 // 版本和基本信息
 program
   .name(t('cli.name'))
@@ -947,6 +975,7 @@ registerOrchestrateCommands(program);
 registerValueCommands(program);
 registerTaskCommands(program);
 registerAuthCommands(program);
+registerStateCommands(program);
 
 // Template management commands
 const templatesCommand = require('../lib/commands/templates');
@@ -1074,7 +1103,8 @@ async function updateProjectConfig(projectName) {
   const args = process.argv.slice(2);
   const isLegacyAllowlistedCommand = isLegacyMigrationAllowlistedCommand(args);
   const skipAutoTakeover = isTakeoverAutoApplySkippedCommand(args);
-  const skipCheck = args.includes('--skip-steering-check') || 
+  const skipCheck = isNoMutationCommand(args) ||
+                    args.includes('--skip-steering-check') || 
                     process.env.KSE_SKIP_STEERING_CHECK === '1';
   const forceCheck = args.includes('--force-steering-check');
 

package/docs/command-reference.md

@@ -232,12 +232,16 @@ sce session start "ship order workflow hardening" --tool codex --agent-version 1
 sce session resume release-20260224 --status active
 sce session snapshot release-20260224 --summary "post-gate checkpoint" --payload '{"tests_passed":42}' --json
 sce session show release-20260224 --json
+sce session list --limit 20 --json
 ```
 
 Session governance defaults:
 - `1 scene = 1 primary session` (managed by `studio plan --scene ...`)
 - `spec` runs can bind as child sessions (`spec bootstrap|pipeline --scene <scene-id>`)
 - successful `studio release` auto-archives current scene session and opens next cycle session
+- `session show/list` JSON now includes runtime diagnostics:
+  - `session_source`
+  - `scene_index.status` (`aligned`, `pending-sync`, `sqlite-ahead`, etc.)
 
 ### Watch Mode
 
@@ -700,6 +704,50 @@ Default policy file (recommended to commit): `.sce/config/studio-security.json`
 }
 ```
 
+State migration commands (gradual file -> sqlite indexing):
+
+```bash
+# inspect migratable file-based registries
+sce state plan --json
+
+# diagnose sqlite readiness and file/sqlite index sync
+sce state doctor --json
+
+# dry-run migration (default no write)
+sce state migrate --all --json
+
+# apply migration writes into sqlite index tables
+sce state migrate --all --apply --json
+
+# migrate specific components
+sce state migrate --component collab.agent-registry --component runtime.timeline-index --apply --json
+
+# export sqlite migration tables for audit/debug
+sce state export --out .sce/reports/state-migration/state-export.latest.json --json
+
+# reconciliation gate (non-blocking by default; choose strict flags as needed)
+npm run gate:state-migration-reconciliation
+node scripts/state-migration-reconciliation-gate.js --fail-on-alert --fail-on-pending --json
+```
+
+Current migratable components:
+- `collab.agent-registry` (`.sce/config/agent-registry.json`)
+- `runtime.timeline-index` (`.sce/timeline/index.json`)
+- `runtime.scene-session-index` (`.sce/session-governance/scene-index.json`)
+
+SQLite index tables introduced for gradual migration:
+- `agent_runtime_registry`
+- `timeline_snapshot_registry`
+- `scene_session_cycle_registry`
+- `state_migration_registry`
+
+Runtime read preference:
+- timeline/session runtime views now prefer SQLite indexes when indexed rows exist.
+- file artifacts remain source-of-truth for content payload and recovery operations.
+- `sce state doctor --json` now includes:
+  - `summary` aggregate (`pending_components`, `total_record_drift`, `blocking_count`, `alert_count`)
+  - runtime read diagnostics (`runtime.timeline`, `runtime.scene_session`) with read-source/read-preference and consistency status
+
 Write lease model (optional, policy-driven, SQLite-backed):
 - Policy file: `.sce/config/authorization-policy.json`
 - Lease/event persistence: `.sce/state/sce-state.sqlite` (`auth_lease_registry`, `auth_event_stream`)

package/lib/collab/agent-registry.js

@@ -11,6 +11,7 @@
 const path = require('path');
 const fsUtils = require('../utils/fs-utils');
 const { MultiAgentConfig } = require('./multi-agent-config');
+const { getSceStateStore } = require('../state/sce-state-store');
 
 const REGISTRY_FILENAME = 'agent-registry.json';
 const CONFIG_DIR = '.sce/config';
@@ -26,13 +27,16 @@ class AgentRegistry {
    * @param {import('../lock/machine-identifier').MachineIdentifier} machineIdentifier
    * @param {import('../lock/task-lock-manager').TaskLockManager|null} [taskLockManager=null] - Optional, injected to avoid circular deps
    */
-  constructor(workspaceRoot, machineIdentifier, taskLockManager = null) {
+  constructor(workspaceRoot, machineIdentifier, taskLockManager = null, options = {}) {
     this._workspaceRoot = workspaceRoot;
     this._machineIdentifier = machineIdentifier;
     this._taskLockManager = taskLockManager;
     this._registryPath = path.join(workspaceRoot, CONFIG_DIR, REGISTRY_FILENAME);
     this._configDir = path.join(workspaceRoot, CONFIG_DIR);
     this._multiAgentConfig = new MultiAgentConfig(workspaceRoot);
+    this._stateStore = options.stateStore || getSceStateStore(workspaceRoot, {
+      env: options.env || process.env
+    });
   }
 
   /**
@@ -67,6 +71,39 @@ class AgentRegistry {
   async _writeRegistry(registry) {
     await fsUtils.ensureDirectory(this._configDir);
     await fsUtils.writeJSON(this._registryPath, registry);
+    await this._syncRegistryToStateStore(registry);
+  }
+
+  _mapRegistryRows(registry = {}) {
+    if (!registry || typeof registry !== 'object' || !registry.agents || typeof registry.agents !== 'object') {
+      return [];
+    }
+    return Object.values(registry.agents)
+      .map((agent) => ({
+        agent_id: `${agent && agent.agentId ? agent.agentId : ''}`.trim(),
+        machine_id: `${agent && agent.machineId ? agent.machineId : ''}`.trim(),
+        instance_index: Number.parseInt(`${agent && agent.instanceIndex}`, 10) || 0,
+        hostname: `${agent && agent.hostname ? agent.hostname : ''}`.trim() || null,
+        registered_at: `${agent && agent.registeredAt ? agent.registeredAt : ''}`.trim() || null,
+        last_heartbeat: `${agent && agent.lastHeartbeat ? agent.lastHeartbeat : ''}`.trim() || null,
+        status: `${agent && agent.status ? agent.status : ''}`.trim() || null,
+        current_task: agent && typeof agent.currentTask === 'object' ? agent.currentTask : null
+      }))
+      .filter((row) => row.agent_id);
+  }
+
+  async _syncRegistryToStateStore(registry = {}) {
+    if (!this._stateStore) {
+      return;
+    }
+    try {
+      const rows = this._mapRegistryRows(registry);
+      await this._stateStore.upsertAgentRuntimeRecords(rows, {
+        source: 'collab.agent-registry'
+      });
+    } catch (_error) {
+      // best effort only, file registry remains source
+    }
   }
 
   /**

package/lib/commands/session.js

@@ -102,7 +102,32 @@ function registerSessionCommands(program) {
       try {
         const store = new SessionStore(process.cwd());
         const current = await store.getSession(sessionRef || 'latest');
-        _printSessionResult('session_show', current, options.json);
+        const sceneIndex = await store.getSceneIndexDiagnostics();
+        _printSessionResult('session_show', current, options.json, {
+          session_source: 'file',
+          scene_index: sceneIndex
+        });
+      } catch (error) {
+        _exitWithError(error, options.json);
+      }
+    });
+
+  session
+    .command('list')
+    .description('List recent sessions')
+    .option('--limit <n>', 'Maximum sessions to return', '20')
+    .option('--json', 'Output as JSON')
+    .action(async (options) => {
+      try {
+        const store = new SessionStore(process.cwd());
+        const limitRaw = Number.parseInt(`${options.limit || '20'}`, 10);
+        const limit = Number.isFinite(limitRaw) && limitRaw > 0 ? Math.min(limitRaw, 5000) : 20;
+        const sessions = await store.listSessions();
+        const sceneIndex = await store.getSceneIndexDiagnostics();
+        _printSessionListResult('session_list', sessions.slice(0, limit), options.json, {
+          session_source: 'file',
+          scene_index: sceneIndex
+        });
       } catch (error) {
         _exitWithError(error, options.json);
       }
@@ -120,12 +145,13 @@ function _parsePayload(raw) {
   }
 }
 
-function _printSessionResult(action, session, asJson = false) {
+function _printSessionResult(action, session, asJson = false, metadata = {}) {
   if (asJson) {
     console.log(JSON.stringify({
       success: true,
       action,
       session,
+      ...metadata
     }, null, 2));
     return;
   }
@@ -147,6 +173,38 @@ function _printSessionResult(action, session, asJson = false) {
   if (session.objective) {
     console.log(chalk.gray(`Objective: ${session.objective}`));
   }
+  if (metadata.session_source) {
+    console.log(chalk.gray(`Session source: ${metadata.session_source}`));
+  }
+  if (metadata.scene_index && metadata.scene_index.status) {
+    console.log(chalk.gray(`Scene index consistency: ${metadata.scene_index.status}`));
+  }
+}
+
+function _printSessionListResult(action, sessions, asJson = false, metadata = {}) {
+  if (asJson) {
+    console.log(JSON.stringify({
+      success: true,
+      action,
+      total: Array.isArray(sessions) ? sessions.length : 0,
+      sessions: Array.isArray(sessions) ? sessions : [],
+      ...metadata
+    }, null, 2));
+    return;
+  }
+
+  console.log(chalk.green('✓ Sessions listed'));
+  const list = Array.isArray(sessions) ? sessions : [];
+  console.log(chalk.gray(`Total: ${list.length}`));
+  if (metadata.session_source) {
+    console.log(chalk.gray(`Session source: ${metadata.session_source}`));
+  }
+  if (metadata.scene_index && metadata.scene_index.status) {
+    console.log(chalk.gray(`Scene index consistency: ${metadata.scene_index.status}`));
+  }
+  for (const session of list) {
+    console.log(`- ${session.session_id} | ${session.status} | ${session.updated_at || session.started_at || 'n/a'}`);
+  }
 }
 
 function _exitWithError(error, asJson = false) {

package/lib/commands/state.js

@@ -0,0 +1,210 @@
+const path = require('path');
+const chalk = require('chalk');
+const fs = require('fs-extra');
+const {
+  COMPONENT_DEFINITIONS,
+  buildStateMigrationPlan,
+  runStateMigration,
+  runStateDoctor,
+  runStateExport
+} = require('../state/state-migration-manager');
+
+function normalizeString(value) {
+  if (typeof value !== 'string') {
+    return '';
+  }
+  return value.trim();
+}
+
+function collectOptionValue(value, previous = []) {
+  const normalized = normalizeString(value);
+  if (!normalized) {
+    return previous;
+  }
+  return [...previous, normalized];
+}
+
+function normalizeComponentInput(value = []) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  const items = [];
+  for (const entry of value) {
+    const normalized = normalizeString(entry);
+    if (!normalized) {
+      continue;
+    }
+    for (const token of normalized.split(/[,\s]+/g)) {
+      const cleaned = normalizeString(token);
+      if (cleaned) {
+        items.push(cleaned);
+      }
+    }
+  }
+  return Array.from(new Set(items));
+}
+
+function printPayload(payload, options = {}, title = 'State') {
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+
+  console.log(chalk.blue(title));
+  if (payload.mode) {
+    console.log(`  Mode: ${payload.mode}`);
+  }
+  if (payload.store_path) {
+    console.log(`  Store: ${payload.store_path}`);
+  }
+  if (payload.sqlite) {
+    console.log(`  SQLite: configured=${payload.sqlite.configured ? 'yes' : 'no'} available=${payload.sqlite.available ? 'yes' : 'no'}`);
+  }
+  if (payload.summary && typeof payload.summary === 'object') {
+    for (const [key, value] of Object.entries(payload.summary)) {
+      console.log(`  ${key}: ${value}`);
+    }
+  }
+  if (Array.isArray(payload.components)) {
+    for (const item of payload.components) {
+      console.log(`  - ${item.id} | source=${item.source_record_count} | status=${item.status}`);
+    }
+  }
+  if (Array.isArray(payload.operations)) {
+    for (const item of payload.operations) {
+      console.log(`  - ${item.component_id} | ${item.status} | source=${item.source_record_count}`);
+    }
+  }
+  if (payload.out_file) {
+    console.log(`  Export: ${payload.out_file}`);
+  }
+}
+
+async function runStatePlanCommand(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+  const env = dependencies.env || process.env;
+  const components = normalizeComponentInput(options.component);
+
+  const payload = await buildStateMigrationPlan({
+    componentIds: components
+  }, {
+    projectPath,
+    fileSystem,
+    env
+  });
+  printPayload(payload, options, 'State Plan');
+  return payload;
+}
+
+async function runStateDoctorCommand(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+  const env = dependencies.env || process.env;
+
+  const payload = await runStateDoctor({}, {
+    projectPath,
+    fileSystem,
+    env
+  });
+  printPayload(payload, options, 'State Doctor');
+  return payload;
+}
+
+async function runStateMigrateCommand(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+  const env = dependencies.env || process.env;
+  const components = normalizeComponentInput(options.component);
+  const componentIds = options.all === true ? [] : components;
+
+  const payload = await runStateMigration({
+    apply: options.apply === true,
+    all: options.all === true,
+    componentIds
+  }, {
+    projectPath,
+    fileSystem,
+    env
+  });
+  printPayload(payload, options, 'State Migrate');
+  return payload;
+}
+
+async function runStateExportCommand(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+  const env = dependencies.env || process.env;
+
+  const payload = await runStateExport({
+    out: normalizeString(options.out)
+  }, {
+    projectPath,
+    fileSystem,
+    env
+  });
+  printPayload(payload, options, 'State Export');
+  return payload;
+}
+
+async function safeRun(handler, options = {}, dependencies = {}, title = 'state command') {
+  try {
+    await handler(options, dependencies);
+  } catch (error) {
+    if (options && options.json) {
+      console.log(JSON.stringify({
+        success: false,
+        mode: title.replace(/\s+/g, '-'),
+        error: error.message
+      }, null, 2));
+    } else {
+      console.error(chalk.red(`${title} failed:`), error.message);
+    }
+    process.exitCode = 1;
+  }
+}
+
+function registerStateCommands(program) {
+  const state = program
+    .command('state')
+    .description('Manage gradual migration from file registries to sqlite indexes');
+
+  const knownIds = COMPONENT_DEFINITIONS.map((item) => item.id).join(', ');
+
+  state
+    .command('plan')
+    .description('Inspect migratable file-based registries and produce migration plan')
+    .option('--component <id>', `Component id (repeatable): ${knownIds}`, collectOptionValue, [])
+    .option('--json', 'Print machine-readable JSON output')
+    .action(async (options) => safeRun(runStatePlanCommand, options, {}, 'state plan'));
+
+  state
+    .command('doctor')
+    .description('Check sqlite readiness and file/sqlite index consistency')
+    .option('--json', 'Print machine-readable JSON output')
+    .action(async (options) => safeRun(runStateDoctorCommand, options, {}, 'state doctor'));
+
+  state
+    .command('migrate')
+    .description('Migrate selected components to sqlite indexes (dry-run by default)')
+    .option('--component <id>', `Component id (repeatable): ${knownIds}`, collectOptionValue, [])
+    .option('--all', 'Migrate all known components')
+    .option('--apply', 'Apply migration writes (default is dry-run)')
+    .option('--json', 'Print machine-readable JSON output')
+    .action(async (options) => safeRun(runStateMigrateCommand, options, {}, 'state migrate'));
+
+  state
+    .command('export')
+    .description('Export sqlite state migration tables as JSON snapshot')
+    .option('--out <path>', 'Output file path', '.sce/reports/state-migration/state-export.latest.json')
+    .option('--json', 'Print machine-readable JSON output')
+    .action(async (options) => safeRun(runStateExportCommand, options, {}, 'state export'));
+}
+
+module.exports = {
+  runStatePlanCommand,
+  runStateDoctorCommand,
+  runStateMigrateCommand,
+  runStateExportCommand,
+  registerStateCommands
+};