scene-capability-engine 3.5.1 → 3.5.2

package/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.5.2] - 2026-03-03
+
+### Added
+- Studio task-stream contract in command JSON payloads:
+  - root IDs: `sessionId`, `sceneId`, `specId`, `taskId`, `eventId`
+  - normalized task payload: `task.goal`, `task.status`, `task.summary`, `task.handoff`, `task.next_action`
+  - UI-ready arrays: `task.file_changes[]`, `task.commands[]`, `task.errors[]`, `task.evidence[]`
+  - raw audit passthrough: `event[]` (with `studio events` keeping `events[]` compatibility)
+- OpenHands bridge for task stream:
+  - `sce studio events --openhands-events <path>`
+  - supports `.json`/`.jsonl` raw OpenHands events ingestion and maps to SCE task contract fields
+
+### Changed
+- `studio verify/release` now persist `gate_steps` in stage metadata so command execution details can be surfaced in `task.commands[]` and `task.errors[]`.
+
 ## [3.5.1] - 2026-03-03
 
 ### Added

package/README.md

@@ -128,10 +128,21 @@ SCE is tool-agnostic and works with Codex, Claude Code, Cursor, Windsurf, VS Cod
   - `sce workspace takeover-audit --json`
   - `sce workspace takeover-apply --json`
 
+Studio task-stream output contract (default):
+- IDs: `sessionId`, `sceneId`, `specId`, `taskId`, `eventId`
+- Task: `task.goal`, `task.status`, `task.summary` (3-line), `task.handoff`, `task.next_action`
+- File refs: `task.file_changes[]` with `path`, `line`, `diffRef`
+- Command logs: `task.commands[]` with `cmd`, `exit_code`, `stdout`, `stderr`, `log_path`
+- Errors: `task.errors[]` with `message`, `error_bundle` (copy-ready)
+- Evidence: `task.evidence[]`
+- Raw audit stream: `event[]` (and `studio events` keeps `events[]` compatibility field)
+- OpenHands bridge: `sce studio events --openhands-events <path>` maps OpenHands raw events into the same task contract (`source_stream=openhands`)
+
 ---
 
 ## Important Version Changes
 
+- `3.5.2`: Introduced task-stream output contract for Studio commands (`sessionId/sceneId/specId/taskId/eventId`, structured `task.*` fields, `event[]` audit stream) and added OpenHands raw-event bridge via `sce studio events --openhands-events <path>`.
 - `3.5.1`: Enforced stricter Studio intake defaults (`--manual-spec` and `--no-spec-governance` blocked unless policy override), added historical spec scene backfill command (`sce studio backfill-spec-scenes`) and persisted override mapping (`.sce/spec-governance/spec-scene-overrides.json`) for portfolio/related-spec alignment.
 - `3.5.0`: Added Studio automatic goal intake + scene spec portfolio governance (`sce studio intake`, `sce studio portfolio`), including default intake policy baseline and governance artifacts for bounded scene spec growth.
 - `3.4.6`: Added default `problem-closure-gate` + `problem-contract` baseline and strengthened mandatory problem evaluation dimensions (`problem_contract`/`ontology_alignment`/`convergence`) for verify/release convergence control.
@@ -180,5 +191,5 @@ MIT. See [LICENSE](LICENSE).
 
 ---
 
-**Version**: 3.5.1  
+**Version**: 3.5.2  
 **Last Updated**: 2026-03-03

package/README.zh.md

@@ -128,10 +128,21 @@ SCE 对工具无锁定，可接入 Codex、Claude Code、Cursor、Windsurf、VS
   - `sce workspace takeover-audit --json`
   - `sce workspace takeover-apply --json`
 
+Studio 任务流输出契约（默认）：
+- ID 字段：`sessionId`、`sceneId`、`specId`、`taskId`、`eventId`
+- 任务主体：`task.goal`、`task.status`、`task.summary`（固定三行）、`task.handoff`、`task.next_action`
+- 文件引用：`task.file_changes[]`（`path`、`line`、`diffRef`）
+- 命令执行：`task.commands[]`（`cmd`、`exit_code`、`stdout`、`stderr`、`log_path`）
+- 错误复制：`task.errors[]`（`message`、`error_bundle`，可直接复制给 AI 修复）
+- 证据引用：`task.evidence[]`
+- 原始审计流：`event[]`（`studio events` 同时保留 `events[]` 兼容字段）
+- OpenHands 桥接：`sce studio events --openhands-events <path>` 可将 OpenHands 原始事件映射为同一 task 契约（`source_stream=openhands`）
+
 ---
 
 ## 重要版本变更
 
+- `3.5.2`：新增 Studio 任务流输出契约（`sessionId/sceneId/specId/taskId/eventId`、结构化 `task.*` 字段、`event[]` 审计流），并新增 OpenHands 原始事件桥接能力：`sce studio events --openhands-events <path>`。
 - `3.5.1`：默认强化 Studio intake 治理（`--manual-spec`、`--no-spec-governance` 在未显式放开策略时会被阻断），新增历史 spec 场景回填命令 `sce studio backfill-spec-scenes`，并写入 `.sce/spec-governance/spec-scene-overrides.json` 以统一 portfolio 与 related-spec 的场景映射。
 - `3.5.0`：新增 Studio 目标自动 intake + 场景 spec 组合治理（`sce studio intake`、`sce studio portfolio`），并默认启用 intake 策略基线与治理快照产物，控制场景内 spec 无序增长。
 - `3.4.6`：新增默认 `problem-closure-gate` + `problem-contract` 基线，并强化问题评估强制维度（`problem_contract`/`ontology_alignment`/`convergence`），提升 verify/release 收敛控制。
@@ -180,5 +191,5 @@ MIT，见 [LICENSE](LICENSE)。
 
 ---
 
-**版本**：3.5.1  
+**版本**：3.5.2  
 **最后更新**：2026-03-03

package/docs/command-reference.md

@@ -2,8 +2,8 @@
 
 > Quick reference for all `sce` commands
 
-**Version**: 3.5.0
-**Last Updated**: 2026-03-02
+**Version**: 3.5.2
+**Last Updated**: 2026-03-03
 
 ---
 
@@ -550,6 +550,8 @@ sce studio resume --job <job-id> --json
 
 # Inspect recent stage events
 sce studio events --job <job-id> --limit 50 --json
+# Map OpenHands raw events into the same task-stream contract
+sce studio events --job <job-id> --openhands-events ./openhands-events.json --json
 
 # Rollback a job after apply/release
 sce studio rollback --job <job-id> --reason "manual-check-failed" --json
@@ -567,6 +569,16 @@ sce studio backfill-spec-scenes --scene scene.unassigned --limit 20 --apply --js
 SCE_STUDIO_REQUIRE_AUTH=1 SCE_STUDIO_AUTH_PASSWORD=top-secret sce studio apply --job <job-id> --auth-password top-secret --json
 ```
 
+Studio JSON output now includes a stable UI-oriented task stream contract (in addition to existing `job_*` fields):
+- root IDs: `sessionId`, `sceneId`, `specId`, `taskId`, `eventId`
+- `task.goal`, `task.status`, `task.summary` (fixed 3-line summary), `task.handoff`, `task.next_action`
+- `task.file_changes[]`: `path`, `line`, `diffRef`
+- `task.commands[]`: `cmd`, `exit_code`, `stdout`, `stderr`, `log_path`
+- `task.errors[]`: `message`, `error_bundle` (copy-ready diagnostic bundle)
+- `task.evidence[]`: structured evidence references
+- `event[]`: raw audit event stream (`studio events` also keeps legacy `events[]` for compatibility)
+- `studio events --openhands-events <path>` switches `source_stream=openhands` and maps OpenHands raw events to the same task contract fields.
+
 Stage guardrails are enforced by default:
 - `plan` requires `--scene`; SCE binds one active primary session per scene
 - `plan` runs auto intake by default (`.sce/config/studio-intake-policy.json`):

package/lib/commands/studio.js

@@ -643,6 +643,7 @@ async function appendStudioEvent(paths, job, eventType, metadata = {}, fileSyste
   const eventLine = `${JSON.stringify(event)}\n`;
   const eventFile = getEventLogFilePath(paths, job.job_id);
   await fileSystem.appendFile(eventFile, eventLine, 'utf8');
+  return event;
 }
 
 async function readStudioEvents(paths, jobId, options = {}, fileSystem = fs) {
@@ -730,6 +731,697 @@ function resolveNextAction(job) {
   return 'complete';
 }
 
+function resolveTaskStage(mode, job, explicitStage = '') {
+  const normalizedExplicit = normalizeString(explicitStage);
+  if (normalizedExplicit) {
+    return normalizedExplicit;
+  }
+
+  const modeSuffix = normalizeString(mode).replace(/^studio-/, '');
+  if (modeSuffix && (STAGE_ORDER.includes(modeSuffix) || modeSuffix === 'rollback')) {
+    return modeSuffix;
+  }
+
+  if (normalizeString(job && job.status) === 'rolled_back') {
+    return 'rollback';
+  }
+
+  for (let i = STAGE_ORDER.length - 1; i >= 0; i -= 1) {
+    const stageName = STAGE_ORDER[i];
+    const stage = job && job.stages ? job.stages[stageName] : null;
+    const status = normalizeString(stage && stage.status);
+    if (status && status !== 'pending') {
+      return stageName;
+    }
+  }
+
+  return 'plan';
+}
+
+function normalizeTaskFileChanges(fileChanges = []) {
+  const entries = Array.isArray(fileChanges) ? fileChanges : [];
+  const seen = new Set();
+  const normalized = [];
+  for (const entry of entries) {
+    const pathRef = normalizeString(entry && entry.path);
+    if (!pathRef) {
+      continue;
+    }
+    const line = Number.parseInt(`${entry && entry.line != null ? entry.line : 1}`, 10);
+    const normalizedLine = Number.isFinite(line) && line > 0 ? line : 1;
+    const diffRef = normalizeString(entry && entry.diffRef) || `${pathRef}:${normalizedLine}`;
+    if (seen.has(diffRef)) {
+      continue;
+    }
+    seen.add(diffRef);
+    normalized.push({
+      path: pathRef,
+      line: normalizedLine,
+      diffRef
+    });
+  }
+  return normalized;
+}
+
+function normalizeTaskCommands(commands = []) {
+  const entries = Array.isArray(commands) ? commands : [];
+  const normalized = [];
+  for (const entry of entries) {
+    const cmd = normalizeString(entry && entry.cmd);
+    const stdout = typeof (entry && entry.stdout) === 'string' ? entry.stdout : '';
+    const stderr = typeof (entry && entry.stderr) === 'string' ? entry.stderr : '';
+    const exitCodeRaw = entry && entry.exit_code;
+    const exitCode = Number.isFinite(Number(exitCodeRaw))
+      ? Number(exitCodeRaw)
+      : null;
+    const logPath = normalizeString(entry && entry.log_path) || null;
+    if (!cmd && !stdout && !stderr && exitCode == null && !logPath) {
+      continue;
+    }
+    normalized.push({
+      cmd: cmd || 'n/a',
+      exit_code: exitCode,
+      stdout,
+      stderr,
+      log_path: logPath
+    });
+  }
+  return normalized;
+}
+
+function buildErrorBundle(entry = {}) {
+  const lines = [];
+  const pushLine = (key, value) => {
+    const normalized = typeof value === 'string' ? value.trim() : `${value || ''}`.trim();
+    if (!normalized) {
+      return;
+    }
+    lines.push(`${key}: ${normalized}`);
+  };
+  pushLine('message', entry.message);
+  pushLine('step', entry.step_id || entry.step);
+  pushLine('cmd', entry.cmd);
+  if (entry.exit_code != null && `${entry.exit_code}`.trim()) {
+    lines.push(`exit_code: ${entry.exit_code}`);
+  }
+  pushLine('skip_reason', entry.skip_reason);
+  pushLine('stderr', entry.stderr);
+  pushLine('stdout', entry.stdout);
+  return lines.join('\n');
+}
+
+function normalizeTaskErrors(errors = []) {
+  const entries = Array.isArray(errors) ? errors : [];
+  const normalized = [];
+  for (const entry of entries) {
+    const message = normalizeString(entry && entry.message);
+    if (!message) {
+      continue;
+    }
+    const errorBundle = normalizeString(entry && entry.error_bundle) || buildErrorBundle(entry);
+    normalized.push({
+      message,
+      error_bundle: errorBundle
+    });
+  }
+  return normalized;
+}
+
+function normalizeTaskEvidence(evidence = []) {
+  const entries = Array.isArray(evidence) ? evidence : [];
+  const normalized = [];
+  const seen = new Set();
+  for (const entry of entries) {
+    if (typeof entry === 'string') {
+      const ref = normalizeString(entry);
+      if (!ref || seen.has(ref)) {
+        continue;
+      }
+      seen.add(ref);
+      normalized.push({
+        type: 'reference',
+        ref,
+        detail: null
+      });
+      continue;
+    }
+
+    const type = normalizeString(entry && entry.type) || 'reference';
+    const ref = normalizeString(entry && entry.ref);
+    const detail = normalizeString(entry && entry.detail) || null;
+    const key = `${type}:${ref}:${detail || ''}`;
+    if ((!ref && !detail) || seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    normalized.push({
+      type,
+      ref: ref || null,
+      detail
+    });
+  }
+  return normalized;
+}
+
+function pickFirstString(values = []) {
+  for (const value of values) {
+    if (typeof value === 'string' && value.trim()) {
+      return value.trim();
+    }
+  }
+  return '';
+}
+
+function pickFirstNumber(values = []) {
+  for (const value of values) {
+    if (value == null || value === '') {
+      continue;
+    }
+    const numberValue = Number(value);
+    if (Number.isFinite(numberValue)) {
+      return numberValue;
+    }
+  }
+  return null;
+}
+
+function extractEventArrayFromPayload(payload) {
+  if (Array.isArray(payload)) {
+    return payload;
+  }
+  if (!payload || typeof payload !== 'object') {
+    return [];
+  }
+  const candidateKeys = ['events', 'items', 'data', 'records', 'entries'];
+  for (const key of candidateKeys) {
+    if (Array.isArray(payload[key])) {
+      return payload[key];
+    }
+  }
+  return [payload];
+}
+
+async function readOpenHandsEventsFile(openhandsEventsPath, fileSystem = fs) {
+  const normalizedPath = normalizeString(openhandsEventsPath);
+  if (!normalizedPath) {
+    return [];
+  }
+  const exists = await fileSystem.pathExists(normalizedPath);
+  if (!exists) {
+    throw new Error(`OpenHands events file not found: ${normalizedPath}`);
+  }
+
+  const content = await fileSystem.readFile(normalizedPath, 'utf8');
+  const trimmed = `${content || ''}`.trim();
+  if (!trimmed) {
+    return [];
+  }
+
+  try {
+    const parsed = JSON.parse(trimmed);
+    return extractEventArrayFromPayload(parsed);
+  } catch (_error) {
+    const lines = trimmed
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter(Boolean);
+    const parsedLines = [];
+    for (const line of lines) {
+      try {
+        parsedLines.push(JSON.parse(line));
+      } catch (_innerError) {
+        // Skip malformed JSONL lines to keep ingestion robust.
+      }
+    }
+    return parsedLines;
+  }
+}
+
+function normalizeOpenHandsEventRecord(rawEvent, index, jobId) {
+  const raw = rawEvent && typeof rawEvent === 'object'
+    ? rawEvent
+    : { value: rawEvent };
+  const eventId = pickFirstString([
+    raw.event_id,
+    raw.eventId,
+    raw.id,
+    raw.uuid
+  ]) || `oh-evt-${index + 1}`;
+  const eventType = pickFirstString([
+    raw.event_type,
+    raw.eventType,
+    raw.type,
+    raw.kind,
+    raw.action
+  ]) || 'unknown';
+  const timestamp = pickFirstString([
+    raw.timestamp,
+    raw.time,
+    raw.created_at,
+    raw.createdAt,
+    raw.ts
+  ]) || nowIso();
+  return {
+    api_version: STUDIO_EVENT_API_VERSION,
+    event_id: eventId,
+    job_id: jobId,
+    event_type: `openhands.${eventType}`,
+    timestamp,
+    metadata: {
+      source: 'openhands',
+      raw
+    }
+  };
+}
+
+function tryParseJsonText(value) {
+  if (typeof value !== 'string') {
+    return null;
+  }
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return null;
+  }
+  if (!(trimmed.startsWith('{') || trimmed.startsWith('['))) {
+    return null;
+  }
+  try {
+    return JSON.parse(trimmed);
+  } catch (_error) {
+    return null;
+  }
+}
+
+function stringifyCompact(value) {
+  if (value == null) {
+    return '';
+  }
+  if (typeof value === 'string') {
+    return value;
+  }
+  try {
+    return JSON.stringify(value);
+  } catch (_error) {
+    return `${value}`;
+  }
+}
+
+function extractOpenHandsCommandCandidates(raw = {}) {
+  const command = pickFirstString([
+    raw.command,
+    raw.cmd,
+    raw.input && raw.input.command,
+    raw.action && raw.action.command,
+    raw.observation && raw.observation.command,
+    raw.tool_input && raw.tool_input.command
+  ]);
+
+  const toolName = pickFirstString([
+    raw.tool_name,
+    raw.toolName,
+    raw.tool && raw.tool.name,
+    raw.name
+  ]);
+  const toolArgs = raw.arguments || raw.tool_input || raw.input || null;
+
+  const cmd = command || (toolName
+    ? `tool:${toolName}${toolArgs ? ` ${stringifyCompact(toolArgs)}` : ''}`
+    : '');
+
+  return {
+    cmd,
+    exit_code: pickFirstNumber([
+      raw.exit_code,
+      raw.exitCode,
+      raw.result && (raw.result.exit_code ?? raw.result.exitCode)
+    ]),
+    stdout: pickFirstString([
+      raw.stdout,
+      raw.output,
+      raw.result && raw.result.stdout,
+      raw.observation && raw.observation.stdout
+    ]),
+    stderr: pickFirstString([
+      raw.stderr,
+      raw.result && raw.result.stderr,
+      raw.error && raw.error.message,
+      typeof raw.error === 'string' ? raw.error : ''
+    ]),
+    log_path: pickFirstString([
+      raw.log_path,
+      raw.logPath,
+      raw.log && raw.log.path
+    ])
+  };
+}
+
+function collectOpenHandsFileChangesFromRaw(raw = {}) {
+  const changes = [];
+  const addPath = (pathValue, lineValue, diffRefValue = '') => {
+    const pathRef = normalizeString(pathValue);
+    if (!pathRef) {
+      return;
+    }
+    const line = Number.parseInt(`${lineValue != null ? lineValue : 1}`, 10);
+    const normalizedLine = Number.isFinite(line) && line > 0 ? line : 1;
+    const diffRef = normalizeString(diffRefValue) || `${pathRef}:${normalizedLine}`;
+    changes.push({
+      path: pathRef,
+      line: normalizedLine,
+      diffRef
+    });
+  };
+
+  if (typeof raw.path === 'string') {
+    addPath(raw.path, raw.line || raw.line_number, raw.diff_ref);
+  }
+  if (raw.file && typeof raw.file === 'object') {
+    addPath(raw.file.path || raw.file.name, raw.file.line || raw.file.line_number, raw.file.diffRef || raw.file.diff_ref);
+  }
+
+  const arrayKeys = ['files', 'changed_files', 'modified_files', 'created_files', 'deleted_files'];
+  for (const key of arrayKeys) {
+    const values = Array.isArray(raw[key]) ? raw[key] : [];
+    for (const value of values) {
+      if (typeof value === 'string') {
+        addPath(value, 1);
+      } else if (value && typeof value === 'object') {
+        addPath(value.path || value.file || value.name, value.line || value.line_number, value.diffRef || value.diff_ref);
+      }
+    }
+  }
+
+  const patchText = pickFirstString([raw.patch, raw.diff]);
+  if (patchText) {
+    const parsedJson = tryParseJsonText(patchText);
+    if (parsedJson && typeof parsedJson === 'object') {
+      const nested = collectOpenHandsFileChangesFromRaw(parsedJson);
+      changes.push(...nested);
+    } else {
+      const lines = patchText.split(/\r?\n/);
+      for (const line of lines) {
+        const match = line.match(/^\+\+\+\s+b\/(.+)$/);
+        if (match && match[1]) {
+          addPath(match[1], 1);
+        }
+      }
+    }
+  }
+
+  return changes;
+}
+
+function mapOpenHandsEventsToTaskSignals(openhandsEvents = [], context = {}) {
+  const normalizedEvents = openhandsEvents.map((item, index) =>
+    normalizeOpenHandsEventRecord(item, index, context.jobId)
+  );
+
+  const commands = [];
+  const fileChanges = [];
+  const errors = [];
+  const evidence = [];
+
+  for (const event of normalizedEvents) {
+    const raw = event && event.metadata ? event.metadata.raw || {} : {};
+    const commandCandidate = extractOpenHandsCommandCandidates(raw);
+    if (commandCandidate.cmd || commandCandidate.stdout || commandCandidate.stderr || commandCandidate.exit_code != null) {
+      commands.push(commandCandidate);
+    }
+
+    fileChanges.push(...collectOpenHandsFileChangesFromRaw(raw));
+
+    const eventType = normalizeString(event.event_type).toLowerCase();
+    const failedByType = eventType.includes('error') || eventType.includes('fail');
+    const failedByExit = commandCandidate.exit_code != null && Number(commandCandidate.exit_code) !== 0;
+    const failedByStderr = commandCandidate.stderr.length > 0 && !commandCandidate.stdout;
+    if (failedByType || failedByExit || failedByStderr) {
+      const message = pickFirstString([
+        raw.message,
+        raw.error && raw.error.message,
+        typeof raw.error === 'string' ? raw.error : '',
+        failedByExit ? `OpenHands command failed (exit ${commandCandidate.exit_code})` : '',
+        'OpenHands event indicates failure'
+      ]);
+      errors.push({
+        message,
+        step_id: event.event_type,
+        cmd: commandCandidate.cmd,
+        exit_code: commandCandidate.exit_code,
+        stderr: commandCandidate.stderr,
+        stdout: commandCandidate.stdout
+      });
+    }
+
+    evidence.push({
+      type: 'openhands-event',
+      ref: event.event_id,
+      detail: event.event_type
+    });
+  }
+
+  return {
+    event: normalizedEvents,
+    commands: normalizeTaskCommands(commands),
+    file_changes: normalizeTaskFileChanges(fileChanges),
+    errors: normalizeTaskErrors(errors),
+    evidence: normalizeTaskEvidence(evidence)
+  };
+}
+
+function extractCommandsFromStageMetadata(stageMetadata = {}) {
+  const gateSteps = Array.isArray(stageMetadata && stageMetadata.gate_steps)
+    ? stageMetadata.gate_steps
+    : [];
+  return gateSteps.map((step) => ({
+    cmd: normalizeString(step && step.command) || normalizeString(step && step.id) || 'n/a',
+    exit_code: Number.isFinite(Number(step && step.exit_code))
+      ? Number(step.exit_code)
+      : null,
+    stdout: normalizeString(step?.output?.stdout),
+    stderr: normalizeString(step?.output?.stderr),
+    log_path: normalizeString(stageMetadata.report) || null
+  }));
+}
+
+function extractErrorsFromStageMetadata(stageState = {}, stageMetadata = {}) {
+  const directErrors = Array.isArray(stageMetadata && stageMetadata.errors)
+    ? stageMetadata.errors
+    : [];
+  const gateStepErrors = [];
+  const gateSteps = Array.isArray(stageMetadata && stageMetadata.gate_steps)
+    ? stageMetadata.gate_steps
+    : [];
+
+  for (const step of gateSteps) {
+    const status = normalizeString(step && step.status);
+    if (status !== 'failed') {
+      continue;
+    }
+    const stepId = normalizeString(step && step.id) || normalizeString(step && step.name) || 'unknown-step';
+    const stepMessage = `Gate step failed: ${stepId}${step && step.exit_code != null ? ` (exit ${step.exit_code})` : ''}`;
+    gateStepErrors.push({
+      message: stepMessage,
+      step_id: stepId,
+      cmd: normalizeString(step && step.command),
+      exit_code: step && step.exit_code != null ? step.exit_code : null,
+      skip_reason: normalizeString(step && step.skip_reason),
+      stdout: normalizeString(step?.output?.stdout),
+      stderr: normalizeString(step?.output?.stderr)
+    });
+  }
+
+  if (normalizeString(stageState && stageState.status) === 'blocked') {
+    const blockers = Array.isArray(stageMetadata?.problem_evaluation?.blockers)
+      ? stageMetadata.problem_evaluation.blockers
+      : [];
+    if (blockers.length > 0) {
+      gateStepErrors.push({
+        message: `Problem evaluation blocked stage: ${blockers.join(', ')}`,
+        cmd: 'problem-evaluation-policy'
+      });
+    }
+  }
+
+  return [...directErrors, ...gateStepErrors];
+}
+
+function collectTaskFileChanges(job = {}, stageName = '', stageMetadata = {}) {
+  const fileChanges = [];
+  if (Array.isArray(stageMetadata && stageMetadata.file_changes)) {
+    fileChanges.push(...stageMetadata.file_changes);
+  }
+
+  const createdSpec = job?.source?.intake?.created_spec;
+  const createdSpecId = createdSpec && createdSpec.created
+    ? normalizeString(createdSpec.spec_id)
+    : '';
+  if (stageName === 'plan' && createdSpecId) {
+    fileChanges.push(
+      { path: `.sce/specs/${createdSpecId}/requirements.md`, line: 1 },
+      { path: `.sce/specs/${createdSpecId}/design.md`, line: 1 },
+      { path: `.sce/specs/${createdSpecId}/tasks.md`, line: 1 },
+      { path: `.sce/specs/${createdSpecId}/custom/problem-domain-chain.json`, line: 1 },
+      { path: `.sce/specs/${createdSpecId}/custom/problem-contract.json`, line: 1 }
+    );
+  }
+
+  const artifacts = job && job.artifacts ? job.artifacts : {};
+  if (stageName === 'plan') {
+    if (normalizeString(artifacts.spec_portfolio_report)) {
+      fileChanges.push({ path: artifacts.spec_portfolio_report, line: 1 });
+    }
+    if (normalizeString(artifacts.spec_scene_index)) {
+      fileChanges.push({ path: artifacts.spec_scene_index, line: 1 });
+    }
+  }
+  if (stageName === 'generate' && normalizeString(artifacts.generate_report)) {
+    fileChanges.push({ path: artifacts.generate_report, line: 1 });
+  }
+  if (stageName === 'verify' && normalizeString(artifacts.verify_report)) {
+    fileChanges.push({ path: artifacts.verify_report, line: 1 });
+  }
+  if (stageName === 'release' && normalizeString(artifacts.release_report)) {
+    fileChanges.push({ path: artifacts.release_report, line: 1 });
+  }
+  return normalizeTaskFileChanges(fileChanges);
+}
+
+function collectTaskEvidence(job = {}, stageName = '', stageMetadata = {}) {
+  const evidence = [];
+  const stageReport = normalizeString(stageMetadata && stageMetadata.report);
+  if (stageReport) {
+    evidence.push({ type: 'stage-report', ref: stageReport, detail: stageName });
+  }
+
+  const artifacts = job && job.artifacts ? job.artifacts : {};
+  if (stageName && artifacts.problem_eval_reports && artifacts.problem_eval_reports[stageName]) {
+    evidence.push({
+      type: 'problem-evaluation-report',
+      ref: artifacts.problem_eval_reports[stageName],
+      detail: stageName
+    });
+  }
+
+  if (normalizeString(job?.source?.domain_chain?.chain_path)) {
+    evidence.push({
+      type: 'domain-chain',
+      ref: job.source.domain_chain.chain_path,
+      detail: stageName
+    });
+  }
+  if (normalizeString(job?.source?.problem_contract_path)) {
+    evidence.push({
+      type: 'problem-contract',
+      ref: job.source.problem_contract_path,
+      detail: stageName
+    });
+  }
+  if (Array.isArray(stageMetadata && stageMetadata.auto_errorbook_records)) {
+    for (const item of stageMetadata.auto_errorbook_records) {
+      const entryId = normalizeString(item && item.entry_id);
+      if (!entryId) {
+        continue;
+      }
+      evidence.push({
+        type: 'errorbook-entry',
+        ref: entryId,
+        detail: normalizeString(item && item.step_id) || null
+      });
+    }
+  }
+
+  if (normalizeString(job && job.job_id)) {
+    evidence.push({
+      type: 'event-log',
+      ref: `.sce/studio/events/${job.job_id}.jsonl`,
+      detail: 'raw-audit-stream'
+    });
+  }
+
+  return normalizeTaskEvidence(evidence);
+}
+
+function buildTaskSummaryLines(job = {}, stageName = '', taskStatus = '', nextAction = '') {
+  const sceneId = normalizeString(job?.scene?.id) || 'scene.n/a';
+  const specId = normalizeString(job?.scene?.spec_id) || normalizeString(job?.source?.spec_id) || 'spec.n/a';
+  const progress = buildProgress(job);
+  return [
+    `Stage: ${stageName || 'plan'} | Status: ${taskStatus || 'unknown'}`,
+    `Scene: ${sceneId} | Spec: ${specId} | Progress: ${progress.completed}/${progress.total}`,
+    `Next: ${nextAction || 'n/a'}`
+  ];
+}
+
+function buildTaskEnvelope(mode, job, options = {}) {
+  const stageName = resolveTaskStage(mode, job, options.stageName);
+  const stageState = stageName && job && job.stages && job.stages[stageName]
+    ? job.stages[stageName]
+    : {};
+  const stageMetadata = stageState && typeof stageState.metadata === 'object' && stageState.metadata
+    ? stageState.metadata
+    : {};
+  const nextAction = resolveNextAction(job);
+
+  const events = Array.isArray(options.events)
+    ? options.events
+    : (options.event ? [options.event] : []);
+  const latestEvent = events.length > 0 ? events[events.length - 1] : null;
+
+  const taskStatus = normalizeString(stageState && stageState.status)
+    || (stageName === 'rollback' && normalizeString(job && job.status) === 'rolled_back'
+      ? 'completed'
+      : normalizeString(job && job.status) || 'unknown');
+  const taskId = normalizeString(options.taskId)
+    || (normalizeString(job && job.job_id)
+      ? `${job.job_id}:${stageName || 'task'}`
+      : null);
+  const goal = normalizeString(job?.source?.goal)
+    || `Studio ${stageName || 'task'} execution`;
+  const sessionId = normalizeString(job?.session?.scene_session_id) || null;
+  const sceneId = normalizeString(job?.scene?.id) || null;
+  const specId = normalizeString(job?.scene?.spec_id) || normalizeString(job?.source?.spec_id) || null;
+
+  const commands = normalizeTaskCommands([
+    ...(Array.isArray(stageMetadata.commands) ? stageMetadata.commands : []),
+    ...extractCommandsFromStageMetadata(stageMetadata)
+  ]);
+  const errors = normalizeTaskErrors(
+    extractErrorsFromStageMetadata(stageState, stageMetadata)
+  );
+  const fileChanges = collectTaskFileChanges(job, stageName, stageMetadata);
+  const evidence = collectTaskEvidence(job, stageName, stageMetadata);
+
+  const handoff = stageMetadata.handoff && typeof stageMetadata.handoff === 'object'
+    ? stageMetadata.handoff
+    : {
+      stage: stageName,
+      status: taskStatus,
+      completed_at: normalizeString(stageState && stageState.completed_at) || null,
+      report: normalizeString(stageMetadata.report) || null,
+      release_ref: normalizeString(stageMetadata.release_ref) || normalizeString(job?.artifacts?.release_ref) || null
+    };
+
+  return {
+    sessionId,
+    sceneId,
+    specId,
+    taskId,
+    eventId: normalizeString(latestEvent && latestEvent.event_id) || null,
+    task: {
+      goal,
+      status: taskStatus,
+      summary: buildTaskSummaryLines(job, stageName, taskStatus, nextAction),
+      handoff,
+      next_action: nextAction,
+      file_changes: fileChanges,
+      commands,
+      errors,
+      evidence
+    },
+    event: events
+  };
+}
+
 function toRelativePosix(projectPath, absolutePath) {
   return path.relative(projectPath, absolutePath).replace(/\\/g, '/');
 }
@@ -1170,8 +1862,8 @@ function ensureNotRolledBack(job, stageName) {
   }
 }
 
-function buildCommandPayload(mode, job) {
-  return {
+function buildCommandPayload(mode, job, options = {}) {
+  const base = {
     mode,
     success: true,
     job_id: job.job_id,
@@ -1180,6 +1872,10 @@ function buildCommandPayload(mode, job) {
     next_action: resolveNextAction(job),
     artifacts: { ...job.artifacts }
   };
+  return {
+    ...base,
+    ...buildTaskEnvelope(mode, job, options)
+  };
 }
 
 function buildJobDomainChainMetadata(job = {}) {
@@ -1645,7 +2341,7 @@ async function runStudioPlanCommand(options = {}, dependencies = {}) {
   };
 
   await saveJob(paths, job, fileSystem);
-  await appendStudioEvent(paths, job, 'stage.plan.completed', {
+  const planEvent = await appendStudioEvent(paths, job, 'stage.plan.completed', {
     from_chat: fromChat,
     scene_id: sceneId,
     spec_id: effectiveSpecId,
@@ -1671,7 +2367,10 @@ async function runStudioPlanCommand(options = {}, dependencies = {}) {
   }, fileSystem);
   await writeLatestJob(paths, jobId, fileSystem);
 
-  const payload = buildCommandPayload('studio-plan', job);
+  const payload = buildCommandPayload('studio-plan', job, {
+    stageName: 'plan',
+    event: planEvent
+  });
   payload.scene = {
     id: sceneId,
     spec_id: effectiveSpecId
@@ -1756,7 +2455,7 @@ async function runStudioGenerateCommand(options = {}, dependencies = {}) {
   });
 
   await saveJob(paths, job, fileSystem);
-  await appendStudioEvent(paths, job, 'stage.generate.completed', {
+  const generateEvent = await appendStudioEvent(paths, job, 'stage.generate.completed', {
     scene_id: sceneId,
     target: job.target,
     patch_bundle_id: patchBundleId,
@@ -1766,7 +2465,10 @@ async function runStudioGenerateCommand(options = {}, dependencies = {}) {
   }, fileSystem);
   await writeLatestJob(paths, jobId, fileSystem);
 
-  const payload = buildCommandPayload('studio-generate', job);
+  const payload = buildCommandPayload('studio-generate', job, {
+    stageName: 'generate',
+    event: generateEvent
+  });
   printStudioPayload(payload, options);
   return payload;
 }
@@ -1826,14 +2528,17 @@ async function runStudioApplyCommand(options = {}, dependencies = {}) {
   });
 
   await saveJob(paths, job, fileSystem);
-  await appendStudioEvent(paths, job, 'stage.apply.completed', {
+  const applyEvent = await appendStudioEvent(paths, job, 'stage.apply.completed', {
     patch_bundle_id: patchBundleId,
     auth_required: authResult.required,
     problem_evaluation: summarizeProblemEvaluation(applyProblemEvaluation)
   }, fileSystem);
   await writeLatestJob(paths, jobId, fileSystem);
 
-  const payload = buildCommandPayload('studio-apply', job);
+  const payload = buildCommandPayload('studio-apply', job, {
+    stageName: 'apply',
+    event: applyEvent
+  });
   printStudioPayload(payload, options);
   return payload;
 }
@@ -1940,6 +2645,7 @@ async function runStudioVerifyCommand(options = {}, dependencies = {}) {
         profile,
         passed: false,
         report: verifyReportPath,
+        gate_steps: gateResult.steps,
         problem_evaluation: summarizeProblemEvaluation(verifyProblemEvaluation),
         domain_chain: domainChainMetadata,
         auto_errorbook_records: autoErrorbookRecords
@@ -1962,13 +2668,14 @@ async function runStudioVerifyCommand(options = {}, dependencies = {}) {
     profile,
     passed: true,
     report: verifyReportPath,
+    gate_steps: gateResult.steps,
     problem_evaluation: summarizeProblemEvaluation(verifyProblemEvaluation),
     domain_chain: domainChainMetadata,
     auto_errorbook_records: autoErrorbookRecords
   });
 
   await saveJob(paths, job, fileSystem);
-  await appendStudioEvent(paths, job, 'stage.verify.completed', {
+  const verifyEvent = await appendStudioEvent(paths, job, 'stage.verify.completed', {
     profile,
     passed: true,
     report: verifyReportPath,
@@ -1978,7 +2685,10 @@ async function runStudioVerifyCommand(options = {}, dependencies = {}) {
   }, fileSystem);
   await writeLatestJob(paths, jobId, fileSystem);
 
-  const payload = buildCommandPayload('studio-verify', job);
+  const payload = buildCommandPayload('studio-verify', job, {
+    stageName: 'verify',
+    event: verifyEvent
+  });
   printStudioPayload(payload, options);
   return payload;
 }
@@ -2118,6 +2828,7 @@ async function runStudioReleaseCommand(options = {}, dependencies = {}) {
         release_ref: releaseRef,
         passed: false,
         report: releaseReportPath,
+        gate_steps: gateResult.steps,
         auth_required: authResult.required,
         problem_evaluation: summarizeProblemEvaluation(releaseProblemEvaluation),
         domain_chain: domainChainMetadata,
@@ -2143,6 +2854,7 @@ async function runStudioReleaseCommand(options = {}, dependencies = {}) {
     channel,
     release_ref: releaseRef,
     report: releaseReportPath,
+    gate_steps: gateResult.steps,
     auth_required: authResult.required,
     problem_evaluation: summarizeProblemEvaluation(releaseProblemEvaluation),
     domain_chain: domainChainMetadata,
@@ -2171,7 +2883,7 @@ async function runStudioReleaseCommand(options = {}, dependencies = {}) {
   }
 
   await saveJob(paths, job, fileSystem);
-  await appendStudioEvent(paths, job, 'stage.release.completed', {
+  const releaseEvent = await appendStudioEvent(paths, job, 'stage.release.completed', {
     channel,
     release_ref: releaseRef,
     report: releaseReportPath,
@@ -2182,7 +2894,10 @@ async function runStudioReleaseCommand(options = {}, dependencies = {}) {
   }, fileSystem);
   await writeLatestJob(paths, jobId, fileSystem);
 
-  const payload = buildCommandPayload('studio-release', job);
+  const payload = buildCommandPayload('studio-release', job, {
+    stageName: 'release',
+    event: releaseEvent
+  });
   printStudioPayload(payload, options);
   return payload;
 }
@@ -2200,7 +2915,10 @@ async function runStudioResumeCommand(options = {}, dependencies = {}) {
   }
 
   const job = await loadJob(paths, jobId, fileSystem);
-  const payload = buildCommandPayload('studio-resume', job);
+  const events = await readStudioEvents(paths, jobId, { limit: 20 }, fileSystem);
+  const payload = buildCommandPayload('studio-resume', job, {
+    events
+  });
   payload.success = true;
   printStudioPayload(payload, options);
   return payload;
@@ -2252,12 +2970,15 @@ async function runStudioRollbackCommand(options = {}, dependencies = {}) {
   }
 
   await saveJob(paths, job, fileSystem);
-  await appendStudioEvent(paths, job, 'job.rolled_back', {
+  const rollbackEvent = await appendStudioEvent(paths, job, 'job.rolled_back', {
     reason
   }, fileSystem);
   await writeLatestJob(paths, jobId, fileSystem);
 
-  const payload = buildCommandPayload('studio-rollback', job);
+  const payload = buildCommandPayload('studio-rollback', job, {
+    stageName: 'rollback',
+    event: rollbackEvent
+  });
   payload.rollback = { ...job.rollback };
   printStudioPayload(payload, options);
   return payload;
@@ -2297,15 +3018,62 @@ async function runStudioEventsCommand(options = {}, dependencies = {}) {
   }
 
   const limit = normalizePositiveInteger(options.limit, 50);
-  const events = await readStudioEvents(paths, jobId, { limit }, fileSystem);
-
-  const payload = {
-    mode: 'studio-events',
-    success: true,
-    job_id: jobId,
-    limit,
-    events
-  };
+  const job = await loadJob(paths, jobId, fileSystem);
+  const openhandsEventsPath = normalizeString(options.openhandsEvents);
+  let sourceStream = 'studio';
+  let events = await readStudioEvents(paths, jobId, { limit }, fileSystem);
+  let openhandsSignals = null;
+  if (openhandsEventsPath) {
+    const absoluteOpenhandsPath = path.isAbsolute(openhandsEventsPath)
+      ? openhandsEventsPath
+      : path.join(projectPath, openhandsEventsPath);
+    const rawOpenhandsEvents = await readOpenHandsEventsFile(absoluteOpenhandsPath, fileSystem);
+    openhandsSignals = mapOpenHandsEventsToTaskSignals(rawOpenhandsEvents, {
+      jobId: job.job_id
+    });
+    events = openhandsSignals.event;
+    sourceStream = 'openhands';
+  }
+
+  const payload = buildCommandPayload('studio-events', job, { events });
+  payload.limit = limit;
+  payload.source_stream = sourceStream;
+  if (sourceStream === 'openhands') {
+    payload.openhands_events_file = path.relative(projectPath, path.isAbsolute(openhandsEventsPath)
+      ? openhandsEventsPath
+      : path.join(projectPath, openhandsEventsPath)).replace(/\\/g, '/');
+    payload.task = {
+      ...payload.task,
+      summary: [
+        `OpenHands events: ${events.length} | commands: ${openhandsSignals.commands.length} | errors: ${openhandsSignals.errors.length}`,
+        `File changes: ${openhandsSignals.file_changes.length} | source: ${payload.openhands_events_file}`,
+        `Next: ${payload.task.next_action}`
+      ],
+      handoff: {
+        ...(payload.task.handoff || {}),
+        source_stream: 'openhands',
+        openhands_event_count: events.length,
+        openhands_command_count: openhandsSignals.commands.length,
+        openhands_error_count: openhandsSignals.errors.length
+      },
+      commands: openhandsSignals.commands,
+      file_changes: openhandsSignals.file_changes,
+      errors: openhandsSignals.errors,
+      evidence: normalizeTaskEvidence([
+        ...(Array.isArray(payload.task.evidence) ? payload.task.evidence : []),
+        ...openhandsSignals.evidence,
+        {
+          type: 'openhands-event-file',
+          ref: payload.openhands_events_file,
+          detail: 'mapped'
+        }
+      ])
+    };
+    payload.eventId = events.length > 0
+      ? events[events.length - 1].event_id
+      : null;
+  }
+  payload.events = events;
   printStudioEventsPayload(payload, options);
   return payload;
 }
@@ -2591,6 +3359,7 @@ function registerStudioCommands(program) {
     .description('Show studio job event stream')
     .option('--job <job-id>', 'Studio job id (defaults to latest)')
     .option('--limit <number>', 'Maximum number of recent events to return', '50')
+    .option('--openhands-events <path>', 'Optional OpenHands raw events file (.json/.jsonl) mapped to task stream')
     .option('--json', 'Print machine-readable JSON output')
     .action(async (options) => runStudioCommand(runStudioEventsCommand, options, 'events'));
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scene-capability-engine",
-  "version": "3.5.1",
+  "version": "3.5.2",
   "description": "SCE (Scene Capability Engine) - A CLI tool and npm package for spec-driven development with AI coding assistants.",
   "main": "index.js",
   "bin": {