scene-capability-engine 3.5.0 → 3.5.2

package/lib/commands/studio.js

@@ -12,8 +12,10 @@ const { findRelatedSpecs } = require('../spec/related-specs');
 const { captureTimelineCheckpoint } = require('../runtime/project-timeline');
 const { runProblemEvaluation } = require('../problem/problem-evaluator');
 const {
+  loadStudioIntakePolicy,
   runStudioAutoIntake,
-  runStudioSpecGovernance
+  runStudioSpecGovernance,
+  runStudioSceneBackfill
 } = require('../studio/spec-intake-governor');
 
 const STUDIO_JOB_API_VERSION = 'sce.studio.job/v0.1';
@@ -641,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) {
@@ -728,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, '/');
 }
@@ -1168,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,
@@ -1178,6 +1872,10 @@ function buildCommandPayload(mode, job) {
     next_action: resolveNextAction(job),
     artifacts: { ...job.artifacts }
   };
+  return {
+    ...base,
+    ...buildTaskEnvelope(mode, job, options)
+  };
 }
 
 function buildJobDomainChainMetadata(job = {}) {
@@ -1358,6 +2056,20 @@ async function runStudioPlanCommand(options = {}, dependencies = {}) {
     throw new Error('--scene is required');
   }
 
+  const intakePolicyBundle = await loadStudioIntakePolicy(projectPath, fileSystem);
+  const intakePolicy = intakePolicyBundle.policy || {};
+  const governancePolicy = intakePolicy.governance || {};
+  if (manualSpecMode && intakePolicy.allow_manual_spec_override !== true) {
+    throw new Error(
+      '--manual-spec is disabled by studio intake policy (allow_manual_spec_override=false)'
+    );
+  }
+  if (skipSpecGovernance && governancePolicy.require_auto_on_plan !== false) {
+    throw new Error(
+      '--no-spec-governance is disabled by studio intake policy (governance.require_auto_on_plan=true)'
+    );
+  }
+
   let domainChainBinding = await resolveDomainChainBinding({
     sceneId,
     specId,
@@ -1629,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,
@@ -1655,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
@@ -1740,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,
@@ -1750,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;
 }
@@ -1810,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;
 }
@@ -1924,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
@@ -1946,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,
@@ -1962,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;
 }
@@ -2102,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,
@@ -2127,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,
@@ -2155,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,
@@ -2166,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;
 }
@@ -2184,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;
@@ -2236,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;
@@ -2281,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;
 }
@@ -2383,6 +3167,19 @@ function printStudioPortfolioPayload(payload, options = {}) {
   console.log(`  Overflow scenes: ${summary.overflow_scenes || 0}`);
 }
 
+function printStudioBackfillPayload(payload, options = {}) {
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+  console.log(chalk.blue('Studio scene backfill'));
+  console.log(`  Source scene: ${payload.source_scene || 'scene.unassigned'}`);
+  console.log(`  Candidates: ${payload.summary ? payload.summary.candidate_count : 0}`);
+  console.log(`  Changed: ${payload.summary ? payload.summary.changed_count : 0}`);
+  console.log(`  Apply: ${payload.apply ? 'yes' : 'no'}`);
+  console.log(`  Override file: ${payload.override_file || 'n/a'}`);
+}
+
 async function runStudioPortfolioCommand(options = {}, dependencies = {}) {
   const projectPath = dependencies.projectPath || process.cwd();
   const fileSystem = dependencies.fileSystem || fs;
@@ -2404,6 +3201,29 @@ async function runStudioPortfolioCommand(options = {}, dependencies = {}) {
   return payload;
 }
 
+async function runStudioBackfillSpecScenesCommand(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+  const backfillOptions = {
+    scene: normalizeString(options.scene),
+    all: options.all === true,
+    limit: options.limit,
+    apply: options.apply === true,
+    refresh_governance: options.refreshGovernance !== false
+  };
+  if (options.activeOnly === true) {
+    backfillOptions.active_only = true;
+  }
+
+  const payload = await runStudioSceneBackfill(backfillOptions, {
+    projectPath,
+    fileSystem
+  });
+
+  printStudioBackfillPayload(payload, options);
+  return payload;
+}
+
 async function runStudioCommand(handler, options, stageName = '') {
   try {
     const stage = normalizeString(stageName) || 'unknown';
@@ -2447,9 +3267,9 @@ function registerStudioCommands(program) {
     .requiredOption('--from-chat <session>', 'Chat session identifier or transcript reference')
     .option('--spec <spec-id>', 'Optional spec binding for domain-chain context ingestion')
     .option('--goal <goal>', 'Optional goal summary')
-    .option('--manual-spec', 'Disable auto intake and only use explicit --spec or existing scene binding')
+    .option('--manual-spec', 'Legacy bypass flag (disabled by default policy)')
     .option('--target <target>', 'Target integration profile', 'default')
-    .option('--no-spec-governance', 'Skip auto portfolio governance snapshot on plan stage')
+    .option('--no-spec-governance', 'Legacy bypass flag (disabled by default policy)')
     .option('--job <job-id>', 'Reuse an explicit studio job id')
     .option('--json', 'Print machine-readable JSON output')
     .action(async (options) => runStudioCommand(runStudioPlanCommand, options, 'plan'));
@@ -2462,7 +3282,7 @@ function registerStudioCommands(program) {
     .option('--spec <spec-id>', 'Optional explicit spec id')
     .option('--goal <goal>', 'Goal text used for intent classification')
     .option('--apply', 'Create spec when decision is create_spec')
-    .option('--manual-spec', 'Disable auto intake and keep explicit/manual binding only')
+    .option('--manual-spec', 'Legacy bypass flag (disabled by default policy)')
     .option('--json', 'Print machine-readable JSON output')
     .action(async (options) => runStudioCommand(runStudioIntakeCommand, options, 'intake'));
 
@@ -2475,6 +3295,18 @@ function registerStudioCommands(program) {
     .option('--json', 'Print machine-readable JSON output')
     .action(async (options) => runStudioCommand(runStudioPortfolioCommand, options, 'portfolio'));
 
+  studio
+    .command('backfill-spec-scenes')
+    .description('Backfill scene bindings for historical specs (writes override mapping when --apply)')
+    .option('--scene <scene-id>', 'Source scene filter (default: scene.unassigned)')
+    .option('--all', 'Include completed/stale specs (default uses active-only policy)')
+    .option('--active-only', 'Force active-only filtering')
+    .option('--limit <n>', 'Maximum number of specs to process')
+    .option('--apply', 'Write mapping to .sce/spec-governance/spec-scene-overrides.json')
+    .option('--no-refresh-governance', 'Skip portfolio refresh after apply')
+    .option('--json', 'Print machine-readable JSON output')
+    .action(async (options) => runStudioCommand(runStudioBackfillSpecScenesCommand, options, 'backfill-spec-scenes'));
+
   studio
     .command('generate')
     .description('Generate patch bundle metadata for a planned studio job (scene inherited from plan)')
@@ -2527,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'));
 
@@ -2567,6 +3400,7 @@ module.exports = {
   runStudioRollbackCommand,
   runStudioEventsCommand,
   runStudioPortfolioCommand,
+  runStudioBackfillSpecScenesCommand,
   runStudioResumeCommand,
   registerStudioCommands
 };