scene-capability-engine 3.5.1 → 3.6.0

package/lib/commands/studio.js

@@ -11,6 +11,8 @@ const {
 const { findRelatedSpecs } = require('../spec/related-specs');
 const { captureTimelineCheckpoint } = require('../runtime/project-timeline');
 const { runProblemEvaluation } = require('../problem/problem-evaluator');
+const { TaskRefRegistry } = require('../task/task-ref-registry');
+const { getSceStateStore } = require('../state/sce-state-store');
 const {
   loadStudioIntakePolicy,
   runStudioAutoIntake,
@@ -40,8 +42,7 @@ function resolveStudioPaths(projectPath = process.cwd()) {
     projectPath,
     studioDir,
     jobsDir: path.join(studioDir, 'jobs'),
-    latestFile: path.join(studioDir, 'latest-job.json'),
-    eventsDir: path.join(studioDir, 'events')
+    latestFile: path.join(studioDir, 'latest-job.json')
   };
 }
 
@@ -597,7 +598,6 @@ async function writeStudioReport(projectPath, relativePath, payload, fileSystem
 
 async function ensureStudioDirectories(paths, fileSystem = fs) {
   await fileSystem.ensureDir(paths.jobsDir);
-  await fileSystem.ensureDir(paths.eventsDir);
 }
 
 async function writeLatestJob(paths, jobId, fileSystem = fs) {
@@ -622,10 +622,6 @@ function getJobFilePath(paths, jobId) {
   return path.join(paths.jobsDir, `${jobId}.json`);
 }
 
-function getEventLogFilePath(paths, jobId) {
-  return path.join(paths.eventsDir, `${jobId}.jsonl`);
-}
-
 async function saveJob(paths, job, fileSystem = fs) {
   const jobFile = getJobFilePath(paths, job.job_id);
   await fileSystem.writeJson(jobFile, job, { spaces: 2 });
@@ -640,39 +636,28 @@ async function appendStudioEvent(paths, job, eventType, metadata = {}, fileSyste
     timestamp: nowIso(),
     metadata
   };
-  const eventLine = `${JSON.stringify(event)}\n`;
-  const eventFile = getEventLogFilePath(paths, job.job_id);
-  await fileSystem.appendFile(eventFile, eventLine, 'utf8');
+  const sceneId = normalizeString(job?.scene?.id) || null;
+  const specId = normalizeString(job?.scene?.spec_id) || normalizeString(job?.source?.spec_id) || null;
+  const stateStore = getSceStateStore(paths.projectPath, { fileSystem });
+  const persisted = await stateStore.appendStudioEvent({
+    ...event,
+    scene_id: sceneId,
+    spec_id: specId
+  });
+  if (!persisted) {
+    throw new Error('Failed to persist studio event into sqlite state store');
+  }
+  return event;
 }
 
 async function readStudioEvents(paths, jobId, options = {}, fileSystem = fs) {
   const { limit = 50 } = options;
-  const eventFile = getEventLogFilePath(paths, jobId);
-  const exists = await fileSystem.pathExists(eventFile);
-  if (!exists) {
-    return [];
+  const stateStore = getSceStateStore(paths.projectPath, { fileSystem });
+  const events = await stateStore.listStudioEvents(jobId, { limit });
+  if (events === null) {
+    throw new Error('SQLite state backend unavailable while reading studio events');
   }
-
-  const content = await fileSystem.readFile(eventFile, 'utf8');
-  const lines = content
-    .split(/\r?\n/)
-    .map((line) => line.trim())
-    .filter(Boolean);
-
-  const parsed = [];
-  for (const line of lines) {
-    try {
-      const payload = JSON.parse(line);
-      parsed.push(payload);
-    } catch (_error) {
-      // Ignore malformed lines to keep event stream robust.
-    }
-  }
-
-  if (limit <= 0) {
-    return parsed;
-  }
-  return parsed.slice(-limit);
+  return events;
 }
 
 async function loadJob(paths, jobId, fileSystem = fs) {
@@ -730,6 +715,705 @@ 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/state/sce-state.sqlite',
+      detail: `studio_event_stream:job_id=${job.job_id}`
+    });
+  }
+
+  return normalizeTaskEvidence(evidence);
+}
+
+function buildTaskSummaryLines(job = {}, stageName = '', taskStatus = '', nextAction = '', taskRef = '') {
+  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'}${taskRef ? ` | Ref: ${taskRef}` : ''}`,
+    `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 taskRef = normalizeString(options.taskRef) || 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
+    };
+
+  const normalizedHandoff = {
+    ...handoff,
+    task_ref: taskRef
+  };
+
+  return {
+    sessionId,
+    sceneId,
+    specId,
+    taskId,
+    taskRef,
+    eventId: normalizeString(latestEvent && latestEvent.event_id) || null,
+    task: {
+      ref: taskRef,
+      goal,
+      status: taskStatus,
+      summary: buildTaskSummaryLines(job, stageName, taskStatus, nextAction, taskRef),
+      handoff: normalizedHandoff,
+      next_action: nextAction,
+      file_changes: fileChanges,
+      commands,
+      errors,
+      evidence
+    },
+    event: events
+  };
+}
+
 function toRelativePosix(projectPath, absolutePath) {
   return path.relative(projectPath, absolutePath).replace(/\\/g, '/');
 }
@@ -1170,8 +1854,50 @@ function ensureNotRolledBack(job, stageName) {
   }
 }
 
-function buildCommandPayload(mode, job) {
-  return {
+function buildStudioTaskKey(stageName = '') {
+  const normalizedStage = normalizeString(stageName) || 'task';
+  return `studio:${normalizedStage}`;
+}
+
+async function resolveTaskReference(mode, job, options = {}) {
+  const explicitTaskRef = normalizeString(options.taskRef);
+  if (explicitTaskRef) {
+    return explicitTaskRef;
+  }
+
+  const sceneId = normalizeString(job?.scene?.id);
+  const specId = normalizeString(job?.scene?.spec_id) || normalizeString(job?.source?.spec_id);
+  if (!sceneId || !specId) {
+    return null;
+  }
+
+  const stageName = resolveTaskStage(mode, job, options.stageName);
+  const taskKey = normalizeString(options.taskKey) || buildStudioTaskKey(stageName);
+  const projectPath = normalizeString(options.projectPath) || process.cwd();
+  const fileSystem = options.fileSystem || fs;
+  const taskRefRegistry = options.taskRefRegistry || new TaskRefRegistry(projectPath, { fileSystem });
+
+  try {
+    const taskRef = await taskRefRegistry.resolveOrCreateRef({
+      sceneId,
+      specId,
+      taskKey,
+      source: 'studio-stage',
+      metadata: {
+        mode: normalizeString(mode) || null,
+        stage: stageName || null,
+        job_id: normalizeString(job?.job_id) || null
+      }
+    });
+    return taskRef.task_ref;
+  } catch (_error) {
+    return null;
+  }
+}
+
+async function buildCommandPayload(mode, job, options = {}) {
+  const taskRef = await resolveTaskReference(mode, job, options);
+  const base = {
     mode,
     success: true,
     job_id: job.job_id,
@@ -1180,6 +1906,13 @@ function buildCommandPayload(mode, job) {
     next_action: resolveNextAction(job),
     artifacts: { ...job.artifacts }
   };
+  return {
+    ...base,
+    ...buildTaskEnvelope(mode, job, {
+      ...options,
+      taskRef
+    })
+  };
 }
 
 function buildJobDomainChainMetadata(job = {}) {
@@ -1645,7 +2378,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 +2404,12 @@ async function runStudioPlanCommand(options = {}, dependencies = {}) {
   }, fileSystem);
   await writeLatestJob(paths, jobId, fileSystem);
 
-  const payload = buildCommandPayload('studio-plan', job);
+  const payload = await buildCommandPayload('studio-plan', job, {
+    stageName: 'plan',
+    event: planEvent,
+    projectPath,
+    fileSystem
+  });
   payload.scene = {
     id: sceneId,
     spec_id: effectiveSpecId
@@ -1756,7 +2494,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 +2504,12 @@ async function runStudioGenerateCommand(options = {}, dependencies = {}) {
   }, fileSystem);
   await writeLatestJob(paths, jobId, fileSystem);
 
-  const payload = buildCommandPayload('studio-generate', job);
+  const payload = await buildCommandPayload('studio-generate', job, {
+    stageName: 'generate',
+    event: generateEvent,
+    projectPath,
+    fileSystem
+  });
   printStudioPayload(payload, options);
   return payload;
 }
@@ -1826,14 +2569,19 @@ 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 = await buildCommandPayload('studio-apply', job, {
+    stageName: 'apply',
+    event: applyEvent,
+    projectPath,
+    fileSystem
+  });
   printStudioPayload(payload, options);
   return payload;
 }
@@ -1940,6 +2688,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 +2711,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 +2728,12 @@ async function runStudioVerifyCommand(options = {}, dependencies = {}) {
   }, fileSystem);
   await writeLatestJob(paths, jobId, fileSystem);
 
-  const payload = buildCommandPayload('studio-verify', job);
+  const payload = await buildCommandPayload('studio-verify', job, {
+    stageName: 'verify',
+    event: verifyEvent,
+    projectPath,
+    fileSystem
+  });
   printStudioPayload(payload, options);
   return payload;
 }
@@ -2118,6 +2873,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 +2899,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 +2928,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 +2939,12 @@ async function runStudioReleaseCommand(options = {}, dependencies = {}) {
   }, fileSystem);
   await writeLatestJob(paths, jobId, fileSystem);
 
-  const payload = buildCommandPayload('studio-release', job);
+  const payload = await buildCommandPayload('studio-release', job, {
+    stageName: 'release',
+    event: releaseEvent,
+    projectPath,
+    fileSystem
+  });
   printStudioPayload(payload, options);
   return payload;
 }
@@ -2200,7 +2962,12 @@ 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 = await buildCommandPayload('studio-resume', job, {
+    events,
+    projectPath,
+    fileSystem
+  });
   payload.success = true;
   printStudioPayload(payload, options);
   return payload;
@@ -2252,12 +3019,17 @@ 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 = await buildCommandPayload('studio-rollback', job, {
+    stageName: 'rollback',
+    event: rollbackEvent,
+    projectPath,
+    fileSystem
+  });
   payload.rollback = { ...job.rollback };
   printStudioPayload(payload, options);
   return payload;
@@ -2297,15 +3069,66 @@ async function runStudioEventsCommand(options = {}, dependencies = {}) {
   }
 
   const limit = normalizePositiveInteger(options.limit, 50);
-  const events = await readStudioEvents(paths, jobId, { limit }, fileSystem);
+  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 = {
-    mode: 'studio-events',
-    success: true,
-    job_id: jobId,
-    limit,
-    events
-  };
+  const payload = await buildCommandPayload('studio-events', job, {
+    events,
+    projectPath,
+    fileSystem
+  });
+  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 +3414,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'));