scene-capability-engine 3.3.18 → 3.3.21

package/lib/commands/studio.js

@@ -3,6 +3,7 @@ const crypto = require('crypto');
 const { spawnSync } = require('child_process');
 const fs = require('fs-extra');
 const chalk = require('chalk');
+const { SessionStore } = require('../runtime/session-store');
 
 const STUDIO_JOB_API_VERSION = 'sce.studio.job/v0.1';
 const STAGE_ORDER = ['plan', 'generate', 'apply', 'verify', 'release'];
@@ -101,11 +102,90 @@ function normalizeGateStep(step) {
   };
 }
 
+function createGateFailureFingerprint(failure = {}, context = {}) {
+  const basis = JSON.stringify({
+    stage: normalizeString(context.stage),
+    profile: normalizeString(context.profile),
+    job_id: normalizeString(context.job_id),
+    step_id: normalizeString(failure.id),
+    command: normalizeString(failure.command),
+    exit_code: Number.isFinite(Number(failure.exit_code)) ? Number(failure.exit_code) : null,
+    skip_reason: normalizeString(failure.skip_reason),
+    stderr: normalizeString(failure?.output?.stderr || '').slice(0, 400)
+  });
+  const digest = crypto.createHash('sha1').update(basis).digest('hex').slice(0, 16);
+  return `studio-gate-${digest}`;
+}
+
+async function autoRecordGateFailure(failure = {}, context = {}, dependencies = {}) {
+  if (dependencies.autoRecordFailures === false) {
+    return null;
+  }
+
+  try {
+    const { runErrorbookRecordCommand } = require('./errorbook');
+    const stage = normalizeString(context.stage) || 'verify';
+    const profile = normalizeString(context.profile) || 'standard';
+    const jobId = normalizeString(context.job_id);
+    const stepId = normalizeString(failure.id) || normalizeString(failure.name) || 'unknown-step';
+    const commandText = normalizeString(failure.command) || 'n/a';
+    const skipReason = normalizeString(failure.skip_reason);
+    const stderr = normalizeString(failure?.output?.stderr || '');
+    const errorText = normalizeString(failure?.output?.error || '');
+    const symptom = skipReason
+      ? `Required studio ${stage} gate step "${stepId}" is unavailable: ${skipReason}.`
+      : `Required studio ${stage} gate step "${stepId}" failed (exit=${failure.exit_code ?? 'n/a'}).`;
+    const rootCause = skipReason
+      ? `Gate dependency missing or disabled for studio ${stage} profile ${profile}; remediation required before release.`
+      : `Gate command execution failure in studio ${stage} profile ${profile}; root cause analysis pending.`;
+    const fixActions = [
+      `Inspect failed gate step ${stepId} in studio ${stage} stage.`,
+      `Rerun gate command: ${commandText}`
+    ];
+    if (stderr) {
+      fixActions.push(`Analyze stderr signal: ${stderr.slice(0, 200)}`);
+    } else if (errorText) {
+      fixActions.push(`Analyze runtime error signal: ${errorText.slice(0, 200)}`);
+    }
+
+    const title = `[studio:${stage}] gate failure: ${stepId}`;
+    const tags = ['studio', 'gate-failure', 'release-blocker', `stage-${stage}`];
+    const fingerprint = createGateFailureFingerprint(failure, context);
+    const specRef = normalizeString(context.scene_id) || jobId;
+
+    const result = await runErrorbookRecordCommand({
+      title,
+      symptom,
+      rootCause,
+      fixAction: fixActions,
+      tags: tags.join(','),
+      ontology: 'execution_flow,decision_policy',
+      status: 'candidate',
+      fingerprint,
+      spec: specRef,
+      notes: `auto-captured from studio ${stage} gate`
+    }, {
+      projectPath: dependencies.projectPath || process.cwd(),
+      fileSystem: dependencies.fileSystem || fs
+    });
+
+    return {
+      errorbook_entry_id: result && result.entry ? result.entry.id : null,
+      fingerprint
+    };
+  } catch (_error) {
+    return null;
+  }
+}
+
 async function executeGateSteps(steps, dependencies = {}) {
   const runner = dependencies.commandRunner || defaultCommandRunner;
   const projectPath = dependencies.projectPath || process.cwd();
   const env = dependencies.env || process.env;
   const failOnRequiredSkip = dependencies.failOnRequiredSkip === true;
+  const onFailure = typeof dependencies.onFailure === 'function'
+    ? dependencies.onFailure
+    : null;
 
   const normalizedSteps = Array.isArray(steps) ? steps.map((step) => normalizeGateStep(step)) : [];
   const results = [];
@@ -128,6 +208,14 @@ async function executeGateSteps(steps, dependencies = {}) {
           ? { stdout: '', stderr: '', error: 'required gate step disabled under strict profile' }
           : undefined
       });
+      if (skippedAsFailure && onFailure) {
+        const failure = results[results.length - 1];
+        await Promise.resolve(onFailure({
+          reason: 'required_skip',
+          step,
+          failure
+        })).catch(() => {});
+      }
       continue;
     }
 
@@ -163,6 +251,14 @@ async function executeGateSteps(steps, dependencies = {}) {
 
     if (!passed && step.required) {
       hasFailure = true;
+      if (onFailure) {
+        const failure = results[results.length - 1];
+        await Promise.resolve(onFailure({
+          reason: 'command_failed',
+          step,
+          failure
+        })).catch(() => {});
+      }
     }
   }
 
@@ -345,6 +441,30 @@ async function buildReleaseGateSteps(options = {}, dependencies = {}) {
     required: true
   });
 
+  const gitManagedGateScript = path.join(projectPath, 'scripts', 'git-managed-gate.js');
+  const hasGitManagedGateScript = await fileSystem.pathExists(gitManagedGateScript);
+  steps.push({
+    id: 'git-managed-gate',
+    name: 'git managed release gate',
+    command: 'node',
+    args: ['scripts/git-managed-gate.js', '--fail-on-violation', '--json'],
+    required: true,
+    enabled: hasGitManagedGateScript,
+    skip_reason: hasGitManagedGateScript ? '' : 'scripts/git-managed-gate.js not found'
+  });
+
+  const errorbookReleaseGateScript = path.join(projectPath, 'scripts', 'errorbook-release-gate.js');
+  const hasErrorbookReleaseGateScript = await fileSystem.pathExists(errorbookReleaseGateScript);
+  steps.push({
+    id: 'errorbook-release-gate',
+    name: 'errorbook release gate',
+    command: 'node',
+    args: ['scripts/errorbook-release-gate.js', '--fail-on-block', '--json'],
+    required: true,
+    enabled: hasErrorbookReleaseGateScript,
+    skip_reason: hasErrorbookReleaseGateScript ? '' : 'scripts/errorbook-release-gate.js not found'
+  });
+
   const weeklySummaryPath = path.join(projectPath, '.sce', 'reports', 'release-evidence', 'release-ops-weekly-summary.json');
   const hasWeeklySummary = await fileSystem.pathExists(weeklySummaryPath);
   steps.push({
@@ -534,14 +654,16 @@ function buildProgress(job) {
 }
 
 function resolveNextAction(job) {
+  const sceneRef = normalizeString(job && job.scene && job.scene.id);
+  const planSceneArg = sceneRef || '<scene-id>';
   if (job.status === 'rolled_back') {
-    return 'sce studio plan --from-chat <session>';
+    return `sce studio plan --scene ${planSceneArg} --from-chat <session>`;
   }
   if (!job.stages.plan || job.stages.plan.status !== 'completed') {
-    return `sce studio plan --from-chat <session> --job ${job.job_id}`;
+    return `sce studio plan --scene ${planSceneArg} --from-chat <session> --job ${job.job_id}`;
   }
   if (!job.stages.generate || job.stages.generate.status !== 'completed') {
-    return `sce studio generate --scene <scene-id> --job ${job.job_id}`;
+    return `sce studio generate --job ${job.job_id}`;
   }
   if (!job.stages.apply || job.stages.apply.status !== 'completed') {
     const patchBundleId = job.artifacts.patch_bundle_id || '<patch-bundle-id>';
@@ -613,10 +735,14 @@ async function runStudioPlanCommand(options = {}, dependencies = {}) {
   const projectPath = dependencies.projectPath || process.cwd();
   const fileSystem = dependencies.fileSystem || fs;
   const fromChat = normalizeString(options.fromChat);
+  const sceneId = normalizeString(options.scene);
 
   if (!fromChat) {
     throw new Error('--from-chat is required');
   }
+  if (!sceneId) {
+    throw new Error('--scene is required');
+  }
 
   const paths = resolveStudioPaths(projectPath);
   await ensureStudioDirectories(paths, fileSystem);
@@ -624,11 +750,20 @@ async function runStudioPlanCommand(options = {}, dependencies = {}) {
   const jobId = normalizeString(options.job) || createJobId();
   const now = nowIso();
   const stages = createStageState();
+  const sessionStore = dependencies.sessionStore || new SessionStore(projectPath);
+  const sceneSessionBinding = await sessionStore.beginSceneSession({
+    sceneId,
+    objective: normalizeString(options.goal) || `Studio scene cycle for ${sceneId}`,
+    tool: normalizeString(options.tool) || 'generic'
+  });
   stages.plan = {
     status: 'completed',
     completed_at: now,
     metadata: {
-      from_chat: fromChat
+      from_chat: fromChat,
+      scene_id: sceneId,
+      scene_session_id: sceneSessionBinding.session.session_id,
+      scene_cycle: sceneSessionBinding.scene_cycle
     }
   };
 
@@ -643,7 +778,14 @@ async function runStudioPlanCommand(options = {}, dependencies = {}) {
       goal: normalizeString(options.goal) || null
     },
     scene: {
-      id: null
+      id: sceneId
+    },
+    session: {
+      policy: 'mandatory.scene-primary',
+      scene_id: sceneId,
+      scene_session_id: sceneSessionBinding.session.session_id,
+      scene_cycle: sceneSessionBinding.scene_cycle,
+      created_new_scene_session: sceneSessionBinding.created_new === true
     },
     target: normalizeString(options.target) || 'default',
     stages,
@@ -657,6 +799,9 @@ async function runStudioPlanCommand(options = {}, dependencies = {}) {
   await saveJob(paths, job, fileSystem);
   await appendStudioEvent(paths, job, 'stage.plan.completed', {
     from_chat: fromChat,
+    scene_id: sceneId,
+    scene_session_id: sceneSessionBinding.session.session_id,
+    scene_cycle: sceneSessionBinding.scene_cycle,
     target: job.target
   }, fileSystem);
   await writeLatestJob(paths, jobId, fileSystem);
@@ -669,22 +814,27 @@ async function runStudioPlanCommand(options = {}, dependencies = {}) {
 async function runStudioGenerateCommand(options = {}, dependencies = {}) {
   const projectPath = dependencies.projectPath || process.cwd();
   const fileSystem = dependencies.fileSystem || fs;
-  const sceneId = normalizeString(options.scene);
-  if (!sceneId) {
-    throw new Error('--scene is required');
-  }
+  const sceneArg = normalizeString(options.scene);
 
   const paths = resolveStudioPaths(projectPath);
   await ensureStudioDirectories(paths, fileSystem);
   const latestJobId = await readLatestJob(paths, fileSystem);
   const jobId = resolveRequestedJobId(options, latestJobId);
   if (!jobId) {
-    throw new Error('No studio job found. Run: sce studio plan --from-chat <session>');
+    throw new Error('No studio job found. Run: sce studio plan --scene <scene-id> --from-chat <session>');
   }
 
   const job = await loadJob(paths, jobId, fileSystem);
   ensureNotRolledBack(job, 'generate');
   ensureStagePrerequisite(job, 'generate', 'plan');
+  const jobSceneId = normalizeString(job && job.scene && job.scene.id);
+  if (!jobSceneId) {
+    throw new Error('Cannot run studio generate: scene is not defined in plan stage');
+  }
+  if (sceneArg && sceneArg !== jobSceneId) {
+    throw new Error(`Scene mismatch: planned scene is "${jobSceneId}" but --scene provided "${sceneArg}"`);
+  }
+  const sceneId = sceneArg || jobSceneId;
   const patchBundleId = normalizeString(options.patchBundle) || `patch-${sceneId}-${Date.now()}`;
 
   job.scene = job.scene || {};
@@ -723,7 +873,7 @@ async function runStudioApplyCommand(options = {}, dependencies = {}) {
   const latestJobId = await readLatestJob(paths, fileSystem);
   const jobId = resolveRequestedJobId(options, latestJobId);
   if (!jobId) {
-    throw new Error('No studio job found. Run: sce studio plan --from-chat <session>');
+    throw new Error('No studio job found. Run: sce studio plan --scene <scene-id> --from-chat <session>');
   }
 
   const job = await loadJob(paths, jobId, fileSystem);
@@ -771,7 +921,7 @@ async function runStudioVerifyCommand(options = {}, dependencies = {}) {
   const latestJobId = await readLatestJob(paths, fileSystem);
   const jobId = resolveRequestedJobId(options, latestJobId);
   if (!jobId) {
-    throw new Error('No studio job found. Run: sce studio plan --from-chat <session>');
+    throw new Error('No studio job found. Run: sce studio plan --scene <scene-id> --from-chat <session>');
   }
 
   const profile = normalizeString(options.profile) || 'standard';
@@ -781,6 +931,7 @@ async function runStudioVerifyCommand(options = {}, dependencies = {}) {
 
   const verifyReportPath = `${STUDIO_REPORTS_DIR}/verify-${job.job_id}.json`;
   const verifyStartedAt = nowIso();
+  const autoErrorbookRecords = [];
   const gateSteps = await buildVerifyGateSteps({ profile }, {
     projectPath,
     fileSystem
@@ -789,7 +940,26 @@ async function runStudioVerifyCommand(options = {}, dependencies = {}) {
     projectPath,
     commandRunner: dependencies.commandRunner,
     env: dependencies.env,
-    failOnRequiredSkip: profile === 'strict'
+    failOnRequiredSkip: profile === 'strict',
+    onFailure: async ({ failure }) => {
+      const captured = await autoRecordGateFailure(failure, {
+        stage: 'verify',
+        profile,
+        job_id: job.job_id,
+        scene_id: job?.scene?.id
+      }, {
+        projectPath,
+        fileSystem,
+        autoRecordFailures: dependencies.autoRecordFailures
+      });
+      if (captured && captured.errorbook_entry_id) {
+        autoErrorbookRecords.push({
+          step_id: failure.id,
+          entry_id: captured.errorbook_entry_id,
+          fingerprint: captured.fingerprint
+        });
+      }
+    }
   });
   const verifyCompletedAt = nowIso();
   const verifyReport = {
@@ -800,7 +970,8 @@ async function runStudioVerifyCommand(options = {}, dependencies = {}) {
     started_at: verifyStartedAt,
     completed_at: verifyCompletedAt,
     passed: gateResult.passed,
-    steps: gateResult.steps
+    steps: gateResult.steps,
+    auto_errorbook_records: autoErrorbookRecords
   };
 
   await writeStudioReport(projectPath, verifyReportPath, verifyReport, fileSystem);
@@ -817,13 +988,15 @@ async function runStudioVerifyCommand(options = {}, dependencies = {}) {
       metadata: {
         profile,
         passed: false,
-        report: verifyReportPath
+        report: verifyReportPath,
+        auto_errorbook_records: autoErrorbookRecords
       }
     };
     await saveJob(paths, job, fileSystem);
     await appendStudioEvent(paths, job, 'stage.verify.failed', {
       profile,
-      report: verifyReportPath
+      report: verifyReportPath,
+      auto_errorbook_records: autoErrorbookRecords
     }, fileSystem);
     await writeLatestJob(paths, jobId, fileSystem);
     throw new Error(`studio verify failed: ${gateResult.steps.filter((step) => step.status === 'failed').map((step) => step.id).join(', ')}`);
@@ -833,14 +1006,16 @@ async function runStudioVerifyCommand(options = {}, dependencies = {}) {
   ensureStageCompleted(job, 'verify', {
     profile,
     passed: true,
-    report: verifyReportPath
+    report: verifyReportPath,
+    auto_errorbook_records: autoErrorbookRecords
   });
 
   await saveJob(paths, job, fileSystem);
   await appendStudioEvent(paths, job, 'stage.verify.completed', {
     profile,
     passed: true,
-    report: verifyReportPath
+    report: verifyReportPath,
+    auto_errorbook_records: autoErrorbookRecords
   }, fileSystem);
   await writeLatestJob(paths, jobId, fileSystem);
 
@@ -858,7 +1033,7 @@ async function runStudioReleaseCommand(options = {}, dependencies = {}) {
   const latestJobId = await readLatestJob(paths, fileSystem);
   const jobId = resolveRequestedJobId(options, latestJobId);
   if (!jobId) {
-    throw new Error('No studio job found. Run: sce studio plan --from-chat <session>');
+    throw new Error('No studio job found. Run: sce studio plan --scene <scene-id> --from-chat <session>');
   }
 
   const channel = normalizeString(options.channel) || 'dev';
@@ -880,6 +1055,7 @@ async function runStudioReleaseCommand(options = {}, dependencies = {}) {
   const profile = normalizeString(options.profile) || 'standard';
   const releaseReportPath = `${STUDIO_REPORTS_DIR}/release-${job.job_id}.json`;
   const releaseStartedAt = nowIso();
+  const autoErrorbookRecords = [];
   const gateSteps = await buildReleaseGateSteps({ profile }, {
     projectPath,
     fileSystem
@@ -888,7 +1064,26 @@ async function runStudioReleaseCommand(options = {}, dependencies = {}) {
     projectPath,
     commandRunner: dependencies.commandRunner,
     env: dependencies.env,
-    failOnRequiredSkip: profile === 'strict'
+    failOnRequiredSkip: profile === 'strict',
+    onFailure: async ({ failure }) => {
+      const captured = await autoRecordGateFailure(failure, {
+        stage: 'release',
+        profile,
+        job_id: job.job_id,
+        scene_id: job?.scene?.id
+      }, {
+        projectPath,
+        fileSystem,
+        autoRecordFailures: dependencies.autoRecordFailures
+      });
+      if (captured && captured.errorbook_entry_id) {
+        autoErrorbookRecords.push({
+          step_id: failure.id,
+          entry_id: captured.errorbook_entry_id,
+          fingerprint: captured.fingerprint
+        });
+      }
+    }
   });
   const releaseCompletedAt = nowIso();
   const releaseReport = {
@@ -901,7 +1096,8 @@ async function runStudioReleaseCommand(options = {}, dependencies = {}) {
     started_at: releaseStartedAt,
     completed_at: releaseCompletedAt,
     passed: gateResult.passed,
-    steps: gateResult.steps
+    steps: gateResult.steps,
+    auto_errorbook_records: autoErrorbookRecords
   };
 
   await writeStudioReport(projectPath, releaseReportPath, releaseReport, fileSystem);
@@ -921,7 +1117,8 @@ async function runStudioReleaseCommand(options = {}, dependencies = {}) {
         release_ref: releaseRef,
         passed: false,
         report: releaseReportPath,
-        auth_required: authResult.required
+        auth_required: authResult.required,
+        auto_errorbook_records: autoErrorbookRecords
       }
     };
     await saveJob(paths, job, fileSystem);
@@ -929,7 +1126,8 @@ async function runStudioReleaseCommand(options = {}, dependencies = {}) {
       channel,
       release_ref: releaseRef,
       report: releaseReportPath,
-      auth_required: authResult.required
+      auth_required: authResult.required,
+      auto_errorbook_records: autoErrorbookRecords
     }, fileSystem);
     await writeLatestJob(paths, jobId, fileSystem);
     throw new Error(`studio release failed: ${gateResult.steps.filter((step) => step.status === 'failed').map((step) => step.id).join(', ')}`);
@@ -940,15 +1138,38 @@ async function runStudioReleaseCommand(options = {}, dependencies = {}) {
     channel,
     release_ref: releaseRef,
     report: releaseReportPath,
-    auth_required: authResult.required
+    auth_required: authResult.required,
+    auto_errorbook_records: autoErrorbookRecords
   });
 
+  const sceneId = normalizeString(job && job.scene && job.scene.id);
+  const sceneSessionId = normalizeString(job && job.session && job.session.scene_session_id);
+  if (sceneId && sceneSessionId) {
+    const sessionStore = dependencies.sessionStore || new SessionStore(projectPath);
+    const rollover = await sessionStore.completeSceneSession(sceneId, sceneSessionId, {
+      summary: `Scene ${sceneId} completed by studio release ${releaseRef}`,
+      status: 'completed',
+      jobId: job.job_id,
+      releaseRef,
+      channel,
+      nextObjective: `Next cycle for scene ${sceneId} after release ${releaseRef}`
+    });
+    job.session = {
+      ...(job.session || {}),
+      completed_scene_session_id: rollover.completed_session.session_id,
+      scene_session_id: rollover.next_session ? rollover.next_session.session_id : null,
+      scene_cycle: rollover.next_scene_cycle || null,
+      rolled_over_at: nowIso()
+    };
+  }
+
   await saveJob(paths, job, fileSystem);
   await appendStudioEvent(paths, job, 'stage.release.completed', {
     channel,
     release_ref: releaseRef,
     report: releaseReportPath,
-    auth_required: authResult.required
+    auth_required: authResult.required,
+    auto_errorbook_records: autoErrorbookRecords
   }, fileSystem);
   await writeLatestJob(paths, jobId, fileSystem);
 
@@ -966,7 +1187,7 @@ async function runStudioResumeCommand(options = {}, dependencies = {}) {
   const latestJobId = await readLatestJob(paths, fileSystem);
   const jobId = resolveRequestedJobId(options, latestJobId);
   if (!jobId) {
-    throw new Error('No studio job found. Run: sce studio plan --from-chat <session>');
+    throw new Error('No studio job found. Run: sce studio plan --scene <scene-id> --from-chat <session>');
   }
 
   const job = await loadJob(paths, jobId, fileSystem);
@@ -985,7 +1206,7 @@ async function runStudioRollbackCommand(options = {}, dependencies = {}) {
   const latestJobId = await readLatestJob(paths, fileSystem);
   const jobId = resolveRequestedJobId(options, latestJobId);
   if (!jobId) {
-    throw new Error('No studio job found. Run: sce studio plan --from-chat <session>');
+    throw new Error('No studio job found. Run: sce studio plan --scene <scene-id> --from-chat <session>');
   }
 
   const reason = normalizeString(options.reason) || 'manual-rollback';
@@ -1008,6 +1229,19 @@ async function runStudioRollbackCommand(options = {}, dependencies = {}) {
     auth_required: authResult.required
   };
 
+  const sceneSessionId = normalizeString(job && job.session && job.session.scene_session_id);
+  if (sceneSessionId) {
+    const sessionStore = dependencies.sessionStore || new SessionStore(projectPath);
+    await sessionStore.snapshotSession(sceneSessionId, {
+      summary: `Studio rollback: ${reason}`,
+      status: 'rolled_back',
+      payload: {
+        job_id: job.job_id,
+        reason
+      }
+    });
+  }
+
   await saveJob(paths, job, fileSystem);
   await appendStudioEvent(paths, job, 'job.rolled_back', {
     reason
@@ -1050,7 +1284,7 @@ async function runStudioEventsCommand(options = {}, dependencies = {}) {
   const latestJobId = await readLatestJob(paths, fileSystem);
   const jobId = resolveRequestedJobId(options, latestJobId);
   if (!jobId) {
-    throw new Error('No studio job found. Run: sce studio plan --from-chat <session>');
+    throw new Error('No studio job found. Run: sce studio plan --scene <scene-id> --from-chat <session>');
   }
 
   const limit = normalizePositiveInteger(options.limit, 50);
@@ -1084,6 +1318,7 @@ function registerStudioCommands(program) {
   studio
     .command('plan')
     .description('Create/refresh a studio plan job from chat context')
+    .requiredOption('--scene <scene-id>', 'Scene identifier (mandatory primary session anchor)')
     .requiredOption('--from-chat <session>', 'Chat session identifier or transcript reference')
     .option('--goal <goal>', 'Optional goal summary')
     .option('--target <target>', 'Target integration profile', 'default')
@@ -1093,8 +1328,8 @@ function registerStudioCommands(program) {
 
   studio
     .command('generate')
-    .description('Generate patch bundle metadata for a planned studio job')
-    .requiredOption('--scene <scene-id>', 'Scene identifier to generate')
+    .description('Generate patch bundle metadata for a planned studio job (scene inherited from plan)')
+    .option('--scene <scene-id>', 'Optional scene identifier; must match planned scene when provided')
     .option('--target <target>', 'Target integration profile override')
     .option('--patch-bundle <id>', 'Explicit patch bundle id')
     .option('--job <job-id>', 'Studio job id (defaults to latest)')

package/lib/runtime/multi-spec-scene-session.js

@@ -0,0 +1,147 @@
+const { resolveSpecSceneBinding } = require('./scene-session-binding');
+
+function normalizeString(value) {
+  if (typeof value !== 'string') {
+    return '';
+  }
+  return value.trim();
+}
+
+function toSpecStatus(specId, orchestratePayload = {}, topLevelStatus = '') {
+  const completed = new Set(Array.isArray(orchestratePayload.completed) ? orchestratePayload.completed : []);
+  const failed = new Set([
+    ...(Array.isArray(orchestratePayload.failed) ? orchestratePayload.failed : []),
+    ...(Array.isArray(orchestratePayload.skipped) ? orchestratePayload.skipped : [])
+  ]);
+
+  if (completed.has(specId)) {
+    return 'completed';
+  }
+  if (failed.has(specId)) {
+    return 'failed';
+  }
+
+  const orchestrationStatus = normalizeString(orchestratePayload.status).toLowerCase();
+  if (orchestrationStatus === 'completed') {
+    return 'completed';
+  }
+  if (orchestrationStatus === 'failed' || orchestrationStatus === 'stopped') {
+    return 'failed';
+  }
+
+  const topStatus = normalizeString(topLevelStatus).toLowerCase();
+  if (topStatus === 'completed') {
+    return 'completed';
+  }
+  return 'failed';
+}
+
+async function bindMultiSpecSceneSession(options = {}, dependencies = {}) {
+  const {
+    specTargets = [],
+    sceneId = null,
+    commandName = 'spec-command',
+    commandLabel = 'spec-command',
+    commandOptions = {},
+    runViaOrchestrate
+  } = options;
+  const {
+    projectPath = process.cwd(),
+    fileSystem,
+    sessionStore
+  } = dependencies;
+
+  if (!Array.isArray(specTargets) || specTargets.length === 0) {
+    throw new Error('specTargets is required for bindMultiSpecSceneSession');
+  }
+  if (typeof runViaOrchestrate !== 'function') {
+    throw new Error('runViaOrchestrate callback is required for bindMultiSpecSceneSession');
+  }
+
+  const sceneBinding = await resolveSpecSceneBinding({
+    sceneId,
+    allowNoScene: false
+  }, {
+    projectPath,
+    fileSystem,
+    sessionStore
+  });
+
+  const shouldTrackSessions = commandOptions.dryRun !== true;
+  const specSessions = [];
+  if (shouldTrackSessions) {
+    for (const specId of specTargets) {
+      const linked = await sessionStore.startSpecSession({
+        sceneId: sceneBinding.scene_id,
+        specId,
+        objective: `${commandLabel} (orchestrate): ${specId}`
+      });
+      specSessions.push({
+        spec_id: specId,
+        spec_session_id: linked.spec_session.session_id
+      });
+    }
+  }
+
+  try {
+    const result = await runViaOrchestrate();
+    const orchestratePayload = result && result.orchestrate_result
+      ? result.orchestrate_result
+      : {};
+
+    if (shouldTrackSessions) {
+      for (const item of specSessions) {
+        const specStatus = toSpecStatus(item.spec_id, orchestratePayload, result && result.status);
+        await sessionStore.completeSpecSession({
+          specSessionRef: item.spec_session_id,
+          status: specStatus,
+          summary: `${commandLabel} orchestrate ${specStatus}: ${item.spec_id}`,
+          payload: {
+            command: commandName,
+            mode: 'multi-spec-orchestrate',
+            spec: item.spec_id,
+            orchestration_status: normalizeString(orchestratePayload.status) || null
+          }
+        });
+      }
+    }
+
+    return {
+      ...result,
+      scene_session: {
+        bound: true,
+        scene_id: sceneBinding.scene_id,
+        scene_cycle: sceneBinding.scene_cycle,
+        scene_session_id: sceneBinding.scene_session_id,
+        binding_source: sceneBinding.source,
+        multi_spec_child_sessions: specSessions
+      }
+    };
+  } catch (error) {
+    if (shouldTrackSessions) {
+      for (const item of specSessions) {
+        try {
+          await sessionStore.completeSpecSession({
+            specSessionRef: item.spec_session_id,
+            status: 'failed',
+            summary: `${commandLabel} orchestrate failed: ${item.spec_id}`,
+            payload: {
+              command: commandName,
+              mode: 'multi-spec-orchestrate',
+              spec: item.spec_id,
+              error: error.message
+            }
+          });
+        } catch (_innerError) {
+          // best-effort close
+        }
+      }
+    }
+    throw error;
+  }
+}
+
+module.exports = {
+  bindMultiSpecSceneSession,
+  toSpecStatus
+};