scene-capability-engine 3.6.2 → 3.6.4

package/CHANGELOG.md

@@ -7,6 +7,60 @@ 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
+- SQLite-backed write authorization lease flow:
+  - new policy baseline: `.sce/config/authorization-policy.json`
+  - new state tables: `auth_lease_registry`, `auth_event_stream`
+  - new commands:
+    - `sce auth grant`
+    - `sce auth status`
+    - `sce auth revoke`
+- New write-authorization module: `lib/security/write-authorization.js`.
+- New unit coverage:
+  - `tests/unit/security/write-authorization.test.js`
+  - `tests/unit/commands/auth.test.js`
+  - extended state-store auth lifecycle tests.
+
+### Changed
+- `studio apply/release/rollback` now support `--auth-lease <lease-id>` and can enforce lease-based write authorization.
+- `task rerun` now supports `--auth-lease <lease-id>` and can enforce lease-based write authorization on non-dry-run operations.
+- Authorization checks and lease audit events are persisted to `.sce/state/sce-state.sqlite`.
+
 ## [3.6.2] - 2026-03-04
 
 ### Changed

package/README.md

@@ -145,6 +145,19 @@ 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`
+  - inspect/revoke: `sce auth status --json` / `sce auth revoke --lease <lease-id> --json`
+  - protected writes accept `--auth-lease <lease-id>` on `studio apply/release/rollback` and `task rerun`
 
 ---
 
@@ -201,5 +214,5 @@ MIT. See [LICENSE](LICENSE).
 
 ---
 
-**Version**: 3.6.2  
-**Last Updated**: 2026-03-04
+**Version**: 3.6.3  
+**Last Updated**: 2026-03-05

package/README.zh.md

@@ -145,6 +145,19 @@ 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`
+  - 查看/撤销：`sce auth status --json` / `sce auth revoke --lease <lease-id> --json`
+  - 受保护写操作支持 `--auth-lease <lease-id>`：`studio apply/release/rollback`、`task rerun`
 
 ---
 
@@ -201,5 +214,5 @@ MIT，见 [LICENSE](LICENSE)。
 
 ---
 
-**版本**：3.6.2  
-**最后更新**：2026-03-04
+**版本**：3.6.3  
+**最后更新**：2026-03-05

package/bin/scene-capability-engine.js

@@ -24,6 +24,8 @@ const { registerSpecRelatedCommand } = require('../lib/commands/spec-related');
 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,
@@ -160,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];
@@ -194,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'))
@@ -945,6 +974,8 @@ registerOrchestrateCommands(program);
 // Value realization and observability commands
 registerValueCommands(program);
 registerTaskCommands(program);
+registerAuthCommands(program);
+registerStateCommands(program);
 
 // Template management commands
 const templatesCommand = require('../lib/commands/templates');
@@ -1072,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
 
@@ -552,6 +556,8 @@ sce studio generate --scene scene.customer-order-inventory --target 331 --json
 
 # Apply generated patch metadata
 sce studio apply --patch-bundle patch-scene.customer-order-inventory-<timestamp> --json
+# Apply with explicit write lease
+sce studio apply --job <job-id> --auth-lease <lease-id> --json
 
 # Record verification result
 sce studio verify --profile standard --json
@@ -560,6 +566,8 @@ sce studio verify --profile strict --json
 # Record release event
 sce studio release --channel dev --profile standard --json
 sce studio release --channel dev --profile strict --json
+# Release with explicit write lease
+sce studio release --job <job-id> --channel dev --auth-lease <lease-id> --json
 
 # Resume from latest or explicit job
 sce studio resume --job <job-id> --json
@@ -571,6 +579,8 @@ sce studio events --job <job-id> --openhands-events ./openhands-events.json --js
 
 # Rollback a job after apply/release
 sce studio rollback --job <job-id> --reason "manual-check-failed" --json
+# Rollback with explicit write lease
+sce studio rollback --job <job-id> --reason "manual-check-failed" --auth-lease <lease-id> --json
 
 # Build scene-organized spec governance portfolio
 sce studio portfolio --json
@@ -583,6 +593,11 @@ sce studio backfill-spec-scenes --scene scene.unassigned --limit 20 --apply --js
 
 # Enforce authorization for a protected action
 SCE_STUDIO_REQUIRE_AUTH=1 SCE_STUDIO_AUTH_PASSWORD=top-secret sce studio apply --job <job-id> --auth-password top-secret --json
+
+# Grant/review/revoke write lease (stored in .sce/state/sce-state.sqlite)
+SCE_AUTH_PASSWORD=top-secret sce auth grant --scope studio:* --reason "maintenance window" --auth-password top-secret --json
+sce auth status --json
+sce auth revoke --lease <lease-id> --reason "window closed" --json
 ```
 
 Studio JSON output now includes a stable UI-oriented task stream contract (in addition to existing `job_*` fields):
@@ -689,6 +704,78 @@ 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`)
+- Default protected actions: `studio:apply`, `studio:release`, `studio:rollback`, `task:rerun`
+- Default lease TTL: 15 minutes (`default_ttl_minutes`)
+- Write commands accept `--auth-lease <lease-id>`
+- Policy env overrides:
+  - `SCE_AUTH_REQUIRE_LEASE=1`
+  - `SCE_AUTH_PASSWORD_ENV=<ENV_NAME>`
+  - `SCE_AUTH_ENFORCE_ACTIONS=studio:apply,task:rerun`
+
+Default write authorization policy (recommended to commit): `.sce/config/authorization-policy.json`
+
+```json
+{
+  "enabled": false,
+  "enforce_actions": ["studio:apply", "studio:release", "studio:rollback", "task:rerun"],
+  "default_ttl_minutes": 15,
+  "max_ttl_minutes": 120,
+  "require_password_for_grant": true,
+  "require_password_for_revoke": false,
+  "password_env": "SCE_AUTH_PASSWORD",
+  "default_scope": ["project:*"],
+  "allow_test_bypass": true,
+  "allow_password_as_inline_lease": false
+}
+```
+
 Studio intake policy file (default, recommended to commit): `.sce/config/studio-intake-policy.json`
 
 ```json

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/auth.js

@@ -0,0 +1,269 @@
+const chalk = require('chalk');
+const fs = require('fs-extra');
+const {
+  grantWriteAuthorizationLease,
+  revokeWriteAuthorizationLease,
+  collectWriteAuthorizationStatus,
+  getWriteAuthorizationLease
+} = require('../security/write-authorization');
+
+function normalizeString(value) {
+  if (typeof value !== 'string') {
+    return '';
+  }
+  return value.trim();
+}
+
+function normalizeInteger(value, fallback = 0) {
+  const parsed = Number.parseInt(`${value}`, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return fallback;
+  }
+  return parsed;
+}
+
+function normalizeScopeInput(value) {
+  if (Array.isArray(value)) {
+    return value;
+  }
+  const text = normalizeString(value);
+  if (!text) {
+    return [];
+  }
+  return text.split(/[,\s]+/g).map((item) => normalizeString(item)).filter(Boolean);
+}
+
+function printAuthPayload(payload, options = {}) {
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+
+  const mode = normalizeString(payload.mode);
+  if (mode === 'auth-grant') {
+    console.log(chalk.blue(`Auth lease granted: ${payload.lease.lease_id}`));
+    console.log(`  Subject: ${payload.lease.subject}`);
+    console.log(`  Role: ${payload.lease.role}`);
+    console.log(`  Scope: ${(payload.lease.scope || []).join(', ') || 'n/a'}`);
+    console.log(`  Expires: ${payload.lease.expires_at || 'n/a'}`);
+    console.log(`  Store: ${payload.store_path || 'n/a'}`);
+    return;
+  }
+
+  if (mode === 'auth-revoke') {
+    console.log(chalk.blue(`Auth lease revoked: ${payload.lease.lease_id}`));
+    console.log(`  Subject: ${payload.lease.subject}`);
+    console.log(`  Revoked at: ${payload.lease.revoked_at || 'n/a'}`);
+    console.log(`  Store: ${payload.store_path || 'n/a'}`);
+    return;
+  }
+
+  if (mode === 'auth-status') {
+    if (payload.lease) {
+      console.log(chalk.blue(`Auth lease: ${payload.lease.lease_id}`));
+      console.log(`  Subject: ${payload.lease.subject}`);
+      console.log(`  Role: ${payload.lease.role}`);
+      console.log(`  Scope: ${(payload.lease.scope || []).join(', ') || 'n/a'}`);
+      console.log(`  Expires: ${payload.lease.expires_at || 'n/a'}`);
+      console.log(`  Revoked: ${payload.lease.revoked_at || 'no'}`);
+    } else {
+      console.log(chalk.blue('Auth lease status'));
+      console.log(`  Active leases: ${payload.summary.active_lease_count}`);
+      console.log(`  Events: ${payload.summary.event_count}`);
+    }
+    console.log(`  Store: ${payload.store_path || 'n/a'}`);
+  }
+}
+
+async function runAuthGrantCommand(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+  const env = dependencies.env || process.env;
+
+  const granted = await grantWriteAuthorizationLease({
+    subject: options.subject,
+    role: options.role,
+    scope: normalizeScopeInput(options.scope),
+    ttlMinutes: normalizeInteger(options.ttlMinutes, 15),
+    reason: options.reason,
+    authPassword: options.authPassword,
+    actor: options.actor,
+    metadata: {
+      source: 'sce auth grant'
+    }
+  }, {
+    projectPath,
+    fileSystem,
+    env,
+    authSecret: dependencies.authSecret
+  });
+
+  const payload = {
+    mode: 'auth-grant',
+    success: true,
+    policy: granted.policy,
+    policy_path: granted.policy_path,
+    lease: granted.lease,
+    store_path: granted.store_path
+  };
+
+  printAuthPayload(payload, options);
+  return payload;
+}
+
+async function runAuthStatusCommand(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+  const env = dependencies.env || process.env;
+  const leaseId = normalizeString(options.lease);
+
+  if (leaseId) {
+    const [status, lease] = await Promise.all([
+      collectWriteAuthorizationStatus({
+        activeOnly: options.all !== true,
+        limit: normalizeInteger(options.limit, 20),
+        eventsLimit: normalizeInteger(options.eventsLimit, 20)
+      }, {
+        projectPath,
+        fileSystem,
+        env
+      }),
+      getWriteAuthorizationLease(leaseId, {
+        projectPath,
+        fileSystem,
+        env
+      })
+    ]);
+
+    const payload = {
+      mode: 'auth-status',
+      success: true,
+      policy: status.policy,
+      policy_path: status.policy_path,
+      lease: lease || null,
+      summary: {
+        active_lease_count: Array.isArray(status.leases) ? status.leases.length : 0,
+        event_count: Array.isArray(status.events) ? status.events.length : 0
+      },
+      events: Array.isArray(status.events) ? status.events : [],
+      store_path: status.store_path
+    };
+    printAuthPayload(payload, options);
+    return payload;
+  }
+
+  const status = await collectWriteAuthorizationStatus({
+    activeOnly: options.all !== true,
+    limit: normalizeInteger(options.limit, 20),
+    eventsLimit: normalizeInteger(options.eventsLimit, 20)
+  }, {
+    projectPath,
+    fileSystem,
+    env
+  });
+
+  const payload = {
+    mode: 'auth-status',
+    success: true,
+    policy: status.policy,
+    policy_path: status.policy_path,
+    leases: Array.isArray(status.leases) ? status.leases : [],
+    events: Array.isArray(status.events) ? status.events : [],
+    summary: {
+      active_lease_count: Array.isArray(status.leases) ? status.leases.length : 0,
+      event_count: Array.isArray(status.events) ? status.events.length : 0
+    },
+    store_path: status.store_path
+  };
+
+  printAuthPayload(payload, options);
+  return payload;
+}
+
+async function runAuthRevokeCommand(options = {}, dependencies = {}) {
+  const leaseId = normalizeString(options.lease);
+  if (!leaseId) {
+    throw new Error('--lease is required');
+  }
+
+  const projectPath = dependencies.projectPath || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+  const env = dependencies.env || process.env;
+
+  const revoked = await revokeWriteAuthorizationLease(leaseId, {
+    authPassword: options.authPassword,
+    reason: options.reason,
+    actor: options.actor
+  }, {
+    projectPath,
+    fileSystem,
+    env,
+    authSecret: dependencies.authSecret
+  });
+
+  const payload = {
+    mode: 'auth-revoke',
+    success: true,
+    policy: revoked.policy,
+    policy_path: revoked.policy_path,
+    lease: revoked.lease,
+    store_path: revoked.store_path
+  };
+
+  printAuthPayload(payload, options);
+  return payload;
+}
+
+function runAuthCommand(handler, options = {}, context = 'auth') {
+  Promise.resolve(handler(options))
+    .catch((error) => {
+      console.error(chalk.red(`${context} failed: ${error.message}`));
+      process.exitCode = 1;
+    });
+}
+
+function registerAuthCommands(program) {
+  const auth = program
+    .command('auth')
+    .description('Manage temporary write authorization leases');
+
+  auth
+    .command('grant')
+    .description('Grant a write authorization lease (persisted in sqlite)')
+    .option('--subject <subject>', 'Lease subject (default: current user)')
+    .option('--role <role>', 'Subject role', 'maintainer')
+    .option('--scope <scope>', 'Scope list, comma-separated (example: studio:*,task:rerun)')
+    .option('--ttl-minutes <minutes>', 'Lease TTL in minutes', '15')
+    .option('--reason <reason>', 'Grant reason')
+    .option('--actor <actor>', 'Audit actor override')
+    .option('--auth-password <password>', 'Authorization password for grant policy')
+    .option('--json', 'Print machine-readable JSON output')
+    .action((options) => runAuthCommand(runAuthGrantCommand, options, 'auth grant'));
+
+  auth
+    .command('status')
+    .description('Show current authorization lease and event status from sqlite')
+    .option('--lease <lease-id>', 'Inspect one lease id')
+    .option('--all', 'Include inactive/revoked leases')
+    .option('--limit <n>', 'Lease result limit', '20')
+    .option('--events-limit <n>', 'Auth event result limit', '20')
+    .option('--json', 'Print machine-readable JSON output')
+    .action((options) => runAuthCommand(runAuthStatusCommand, options, 'auth status'));
+
+  auth
+    .command('revoke')
+    .description('Revoke a write authorization lease')
+    .requiredOption('--lease <lease-id>', 'Lease id')
+    .option('--reason <reason>', 'Revoke reason')
+    .option('--actor <actor>', 'Audit actor override')
+    .option('--auth-password <password>', 'Authorization password for revoke policy')
+    .option('--json', 'Print machine-readable JSON output')
+    .action((options) => runAuthCommand(runAuthRevokeCommand, options, 'auth revoke'));
+}
+
+module.exports = {
+  runAuthGrantCommand,
+  runAuthStatusCommand,
+  runAuthRevokeCommand,
+  registerAuthCommands
+};