hive-lite 0.1.9 → 0.2.1

package/src/lib/operator.js

@@ -0,0 +1,1156 @@
+const cp = require('child_process');
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+const { createId } = require('./id');
+const { readIntentTarget, validateIntentTarget } = require('./intent');
+const { ensureDir, exists, readJson, readText, writeJson, writeText } = require('./fsx');
+const { runGitRaw } = require('./git');
+
+const STEP_RESULT_SCHEMA_VERSION = 'hive.operator.step_result.v1';
+const RUN_SCHEMA_VERSION = 'hive.operator.run.v1';
+
+const SKILLS = {
+  start: 'hive-lite-start-prompt',
+  finish: 'hive-lite-finish',
+};
+
+const STATUS_ENUM = new Set([
+  'prompt_ready',
+  'split_required',
+  'map_update_required',
+  'needs_human_action',
+  'accept_ready',
+  'risk_acceptance_required',
+  'blocked',
+  'failed',
+  'accepted',
+  'done',
+]);
+
+const RECOMMENDED_ACTION_ENUM = new Set([
+  'copy_coding_prompt',
+  'start_ready_phase',
+  'manual_review_required',
+  'accept',
+  'accept_risk',
+  'accept_with_risk',
+  'review_reason_required',
+  'revise_required',
+  'map_update_required',
+  'stop',
+  'retry',
+  'none',
+]);
+
+const ARTIFACT_FILENAMES = {
+  coding_agent_prompt_path: 'coding-agent-prompt.md',
+  review_packet_path: 'review-packet.md',
+  handoff_prompt_path: 'handoff-prompt.md',
+  start_intent_path: 'start-intent.md',
+  map_update_required_path: 'map-update-required.md',
+};
+
+const DEFAULT_AGENT_TIMEOUT_MS = 10 * 60 * 1000;
+
+function rel(root, file) {
+  return path.relative(root, file).replace(/\\/g, '/');
+}
+
+function operatorRoot(root) {
+  return path.join(root, '.hive', 'state', 'operator');
+}
+
+function runsRoot(root) {
+  return path.join(operatorRoot(root), 'runs');
+}
+
+function currentRoot(root) {
+  return path.join(operatorRoot(root), 'current');
+}
+
+function resolveRepoPath(root, value) {
+  if (!value || typeof value !== 'string') return null;
+  return path.isAbsolute(value) ? path.resolve(value) : path.resolve(root, value);
+}
+
+function assertOperatorPath(root, value, label) {
+  const resolved = resolveRepoPath(root, value);
+  if (!resolved) throw new Error(`${label} is required`);
+  const relative = path.relative(operatorRoot(root), resolved).replace(/\\/g, '/');
+  if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) {
+    throw new Error(`${label} must be inside .hive/state/operator/: ${value}`);
+  }
+  return resolved;
+}
+
+function sha256(file) {
+  return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+}
+
+function splitCommand(commandText) {
+  const text = String(commandText || '').trim();
+  if (!text) return [];
+  const parts = [];
+  const pattern = /"([^"\\]*(?:\\.[^"\\]*)*)"|'([^'\\]*(?:\\.[^'\\]*)*)'|(\S+)/g;
+  let match;
+  while ((match = pattern.exec(text))) {
+    const value = match[1] !== undefined ? match[1] : match[2] !== undefined ? match[2] : match[3];
+    parts.push(value.replace(/\\(["'\\])/g, '$1'));
+  }
+  return parts;
+}
+
+function parsePositiveInteger(value, label) {
+  if (value === undefined || value === null || value === '') return null;
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 0) {
+    throw new Error(`${label} must be a non-negative integer number of milliseconds.`);
+  }
+  return parsed;
+}
+
+function firstConfigured(values) {
+  return values.find((value) => value !== undefined && value !== null && value !== '');
+}
+
+function resolveAgentConfig(options = {}, env = process.env) {
+  const commandText = options.operatorAgentCommand
+    || options.agentCommand
+    || env.HIVE_LITE_OPERATOR_AGENT_COMMAND
+    || env.HIVE_OPERATOR_AGENT_COMMAND
+    || '';
+  if (!commandText) {
+    throw new Error('No operator agent command configured. Set HIVE_LITE_OPERATOR_AGENT_COMMAND or pass --operator-agent-command "<command>".');
+  }
+  const argv = splitCommand(commandText);
+  if (argv.length === 0) {
+    throw new Error('No operator agent command configured. Set HIVE_LITE_OPERATOR_AGENT_COMMAND or pass --operator-agent-command "<command>".');
+  }
+  const mode = options.operatorAgentMode
+    || options.agentMode
+    || env.HIVE_LITE_OPERATOR_AGENT_MODE
+    || env.HIVE_OPERATOR_AGENT_MODE
+    || 'stdin';
+  if (!['stdin', 'prompt_file'].includes(mode)) {
+    throw new Error(`Unsupported operator agent mode: ${mode}. Use stdin or prompt_file.`);
+  }
+  const commandName = path.basename(argv[0]);
+  if (mode === 'stdin' && commandName === 'codex' && !argv.slice(1).some((arg) => arg === 'exec' || arg === 'e')) {
+    throw new Error('Codex interactive CLI requires a terminal when stdin is piped. Use HIVE_LITE_OPERATOR_AGENT_COMMAND="codex -a never -s workspace-write exec" with HIVE_LITE_OPERATOR_AGENT_MODE="stdin", or pass --operator-agent-command "codex -a never -s workspace-write exec".');
+  }
+  const timeoutMs = parsePositiveInteger(
+    firstConfigured([
+      options.operatorAgentTimeoutMs,
+      options.agentTimeoutMs,
+      env.HIVE_LITE_OPERATOR_AGENT_TIMEOUT_MS,
+      env.HIVE_OPERATOR_AGENT_TIMEOUT_MS,
+    ]),
+    'operator agent timeout',
+  ) ?? DEFAULT_AGENT_TIMEOUT_MS;
+  return {
+    commandText,
+    command: argv[0],
+    args: argv.slice(1),
+    mode,
+    timeoutMs,
+  };
+}
+
+function createRun(root, input) {
+  const runId = createId('oprun');
+  const runDir = path.join(runsRoot(root), runId);
+  const currentDir = currentRoot(root);
+  ensureDir(runDir);
+  ensureDir(path.join(runDir, 'input'));
+  ensureDir(path.join(runDir, 'steps'));
+  ensureDir(currentDir);
+  const run = {
+    schema_version: RUN_SCHEMA_VERSION,
+    id: runId,
+    status: 'running',
+    created_at: new Date().toISOString(),
+    input,
+    paths: {
+      run_dir: rel(root, runDir),
+      current_dir: rel(root, currentDir),
+    },
+    step_counts: {},
+    context: {},
+  };
+  writeJson(path.join(runDir, 'run.json'), run);
+  writeJson(path.join(currentDir, 'run.json'), run);
+  return {
+    ...run,
+    root,
+    runDir,
+    currentDir,
+  };
+}
+
+function saveRun(run) {
+  const data = {
+    schema_version: run.schema_version,
+    id: run.id,
+    status: run.status,
+    created_at: run.created_at,
+    updated_at: new Date().toISOString(),
+    input: run.input,
+    paths: run.paths,
+    step_counts: run.step_counts,
+    context: run.context,
+  };
+  writeJson(path.join(run.runDir, 'run.json'), data);
+  writeJson(path.join(run.currentDir, 'run.json'), data);
+}
+
+function nextStepName(run, base) {
+  const count = (run.step_counts[base] || 0) + 1;
+  run.step_counts[base] = count;
+  saveRun(run);
+  return count === 1 ? base : `${base}-${count}`;
+}
+
+function stepPaths(run, stepName) {
+  const stepDir = path.join(run.runDir, 'steps', stepName);
+  return {
+    stepDir,
+    artifactsDir: path.join(stepDir, 'artifacts'),
+    invocationPath: path.join(stepDir, 'invocation.md'),
+    stdoutPath: path.join(stepDir, 'stdout.log'),
+    stderrPath: path.join(stepDir, 'stderr.log'),
+    resultPath: path.join(stepDir, 'step-result.json'),
+  };
+}
+
+function writeRequirementInput(run, requirement) {
+  const file = path.join(run.runDir, 'input', 'requirement.md');
+  const current = path.join(run.currentDir, 'requirement.md');
+  const value = `${String(requirement).trim()}\n`;
+  writeText(file, value);
+  writeText(current, value);
+  return {
+    requirement_path: rel(run.root, file),
+    current_requirement_path: rel(run.root, current),
+  };
+}
+
+function absoluteFromDisplayPath(root, displayPath) {
+  if (!displayPath) return null;
+  if (path.isAbsolute(displayPath)) return displayPath;
+  return path.resolve(root, displayPath);
+}
+
+function copyIntentInput(run, cwd, target) {
+  const validation = validateIntentTarget(run.root, cwd, target);
+  if (!validation.valid) {
+    const errors = validation.errors.map((item) => `${item.code}: ${item.message}`).join('; ');
+    throw new Error(`Start Intent Handoff is invalid: ${errors || 'validation failed'}`);
+  }
+  const shown = readIntentTarget(run.root, cwd, target);
+  const inputMarkdown = path.join(run.runDir, 'input', 'start-intent.md');
+  const inputJson = path.join(run.runDir, 'input', 'start-intent.json');
+  const currentMarkdown = path.join(run.currentDir, 'start-intent.md');
+  const currentJson = path.join(run.currentDir, 'start-intent.json');
+  writeText(inputMarkdown, shown.markdown.endsWith('\n') ? shown.markdown : `${shown.markdown}\n`);
+  writeText(currentMarkdown, shown.markdown.endsWith('\n') ? shown.markdown : `${shown.markdown}\n`);
+
+  const sourceJson = validation.paths.json ? absoluteFromDisplayPath(run.root, validation.paths.json) : null;
+  const jsonValue = sourceJson && exists(sourceJson)
+    ? readJson(sourceJson)
+    : shown;
+  writeJson(inputJson, jsonValue);
+  writeJson(currentJson, jsonValue);
+
+  return {
+    validation,
+    shown,
+    copied: {
+      input_markdown: rel(run.root, inputMarkdown),
+      input_json: rel(run.root, inputJson),
+      current_markdown: rel(run.root, currentMarkdown),
+      current_json: rel(run.root, currentJson),
+    },
+  };
+}
+
+function printIntentShow(io, validation, shown) {
+  io.stdout.write(`Start Intent Handoff: ${validation.intent_id || '(unknown)'}\n`);
+  io.stdout.write(`Status: ${validation.valid ? 'valid' : 'invalid'}\n`);
+  io.stdout.write(`Path: ${validation.paths.markdown}\n\n`);
+  io.stdout.write('Find Intent:\n');
+  io.stdout.write(`${shown.findIntent || '(none)'}\n\n`);
+}
+
+function baseInvocation(run, paths, skill, body) {
+  return [
+    '# Hive Lite Operator Step Invocation',
+    '',
+    'Role and Objective:',
+    `- Run only the selected Hive Lite operator skill for this step: $${skill}.`,
+    '- Produce the required structured step result so the operator runner can continue.',
+    '- Do not automate the coding agent or treat natural-language transcript text as protocol.',
+    '',
+    'Inputs:',
+    `Target repo root: ${run.root}`,
+    `Operator run: ${run.id}`,
+    `Step: ${path.basename(paths.stepDir)}`,
+    `Selected skill: $${skill}`,
+    '',
+    'Invoke this operator skill in a fresh session:',
+    '',
+    '```text',
+    body.trimEnd(),
+    '```',
+    '',
+    'Runner contract:',
+    '- This is an operator-agent session for Hive Lite skills only.',
+    '- Do not launch, supervise, or automate any coding agent.',
+    '- Do not run the discovery skill inside this operator run.',
+    '- Do not wait for human input inside the agent session.',
+    '- Write the structured step result, then exit cleanly.',
+    '- Do not rely on natural-language stdout/stderr as workflow protocol.',
+    '',
+    'Completion contract:',
+    '- Write every referenced artifact under .hive/state/operator/.',
+    '- Write `step-result.json` to the exact Step result path below.',
+    '- If the step cannot produce a prompt/accept/manual-action result, write a map-update, blocked, or failed result with the concrete next action.',
+    '- Stop after writing the result; the runner handles user interaction.',
+    '',
+    `Step result path: ${rel(run.root, paths.resultPath)}`,
+    `Artifacts directory: ${rel(run.root, paths.artifactsDir)}`,
+    `Current artifacts directory: ${rel(run.root, run.currentDir)}`,
+    `Step-result schema_version: ${STEP_RESULT_SCHEMA_VERSION}`,
+    '',
+    'Allowed result statuses include:',
+    '- prompt_ready',
+    '- split_required',
+    '- map_update_required',
+    '- needs_human_action',
+    '- accept_ready',
+    '- risk_acceptance_required',
+    '- blocked',
+    '- failed',
+    '- accepted',
+    '- done',
+    '',
+    'Required result shapes:',
+    '- For `map_update_required`, write a human-readable artifact first, then write `step-result.json` like:',
+    '```json',
+    JSON.stringify({
+      schema_version: STEP_RESULT_SCHEMA_VERSION,
+      skill,
+      status: 'map_update_required',
+      recommended_action: 'map_update_required',
+      artifacts: {
+        map_update_required_path: rel(run.root, path.join(paths.artifactsDir, 'map-update-required.md')),
+      },
+      map_update: {
+        changed_files: ['.hive/map/areas.yaml'],
+        reason: 'Project Map changed and must be committed or stashed before continuing.',
+      },
+    }, null, 2),
+    '```',
+    '- For `blocked`, write `recommended_action: revise_required` and include `blockers` with concrete next steps.',
+    '- For `failed`, use only unexpected tool/runtime failures that prevent a normal structured result.',
+    '',
+    'Artifact paths in step-result.json must be under .hive/state/operator/.',
+    '',
+  ].join('\n');
+}
+
+function startInvocationBody(input) {
+  if (input.type === 'intent') {
+    return [
+      '$hive-lite-start-prompt',
+      `Use Start Intent Handoff: ${input.intentPath}`,
+      '',
+      `Original intent target: ${input.originalTarget}`,
+    ].join('\n');
+  }
+  if (input.type === 'handoff') {
+    return [
+      '$hive-lite-start-prompt',
+      input.handoffText,
+    ].filter(Boolean).join('\n');
+  }
+  return [
+    '$hive-lite-start-prompt',
+    input.requirement,
+  ].join('\n');
+}
+
+function finishInvocationBody(run, action = {}) {
+  const lines = ['$hive-lite-finish'];
+  if (run.context.ctx_id) lines.push(`Context: ${run.context.ctx_id}`);
+  if (run.context.chg_id) lines.push(`Change: ${run.context.chg_id}`);
+  if (action.kind) {
+    lines.push('');
+    lines.push(`Runner human action: ${action.kind}`);
+    if (action.note) lines.push(`Human note: ${action.note}`);
+    if (action.reason) lines.push(`Human reason: ${action.reason}`);
+    if (action.chg_id) lines.push(`Change: ${action.chg_id}`);
+  } else {
+    lines.push('');
+    lines.push('The human has confirmed the coding agent is done editing.');
+  }
+  return lines.join('\n');
+}
+
+function createInvocation(run, paths, skill, body) {
+  ensureDir(paths.artifactsDir);
+  const value = baseInvocation(run, paths, skill, body);
+  writeText(paths.invocationPath, value);
+  return value;
+}
+
+function gitOutput(root, args) {
+  try {
+    return runGitRaw(args, { cwd: root }).trim();
+  } catch {
+    return '';
+  }
+}
+
+function gitRawOutput(root, args) {
+  try {
+    return runGitRaw(args, { cwd: root });
+  } catch {
+    return '';
+  }
+}
+
+function statusLines(root) {
+  const output = gitRawOutput(root, ['status', '--porcelain', '-uall']);
+  return output ? output.split(/\r?\n/).filter(Boolean).sort() : [];
+}
+
+function isAllowedSkillWrite(skill, file) {
+  const clean = String(file || '').replace(/^"|"$/g, '');
+  if (clean.startsWith('.hive/state/operator/')) return true;
+  if (skill === SKILLS.start) {
+    return clean.startsWith('.hive/context/')
+      || clean.startsWith('.hive/map/');
+  }
+  if (skill === SKILLS.finish) {
+    return clean.startsWith('.hive/changes/')
+      || clean.startsWith('.hive/deltas/')
+      || clean.startsWith('.hive/patches/');
+  }
+  return false;
+}
+
+function normalizeStatusPath(file) {
+  return String(file || '')
+    .replace(/^"|"$/g, '')
+    .replace(/\\"/g, '"')
+    .replace(/\\\\/g, '\\');
+}
+
+function statusLinePaths(line) {
+  let file = String(line || '').slice(3).trim();
+  if (file.includes(' -> ')) {
+    return file.split(' -> ').map((item) => normalizeStatusPath(item.trim())).filter(Boolean);
+  }
+  return [normalizeStatusPath(file)];
+}
+
+function fileState(root, file, status = 'clean') {
+  const absolute = path.join(root, file);
+  try {
+    const stat = fs.lstatSync(absolute);
+    if (stat.isSymbolicLink()) {
+      return {
+        status,
+        exists: true,
+        kind: 'symlink',
+        hash: crypto.createHash('sha256').update(fs.readlinkSync(absolute)).digest('hex'),
+      };
+    }
+    if (stat.isFile()) {
+      return {
+        status,
+        exists: true,
+        kind: 'file',
+        hash: sha256(absolute),
+      };
+    }
+    return {
+      status,
+      exists: true,
+      kind: stat.isDirectory() ? 'directory' : 'other',
+      hash: null,
+    };
+  } catch {
+    return {
+      status,
+      exists: false,
+      kind: 'missing',
+      hash: null,
+    };
+  }
+}
+
+function statusSnapshot(root) {
+  const files = {};
+  for (const line of statusLines(root)) {
+    const status = line.slice(0, 2);
+    for (const file of statusLinePaths(line)) {
+      files[file] = fileState(root, file, status);
+    }
+  }
+  return {
+    head: gitOutput(root, ['rev-parse', 'HEAD']) || null,
+    files,
+  };
+}
+
+function stateSignature(state) {
+  return JSON.stringify([
+    state.status,
+    state.exists,
+    state.kind,
+    state.hash,
+  ]);
+}
+
+function changedHeadPaths(root, beforeHead, afterHead) {
+  if (!beforeHead || !afterHead || beforeHead === afterHead) return [];
+  const output = gitOutput(root, ['diff', '--name-only', beforeHead, afterHead, '--']);
+  return output ? output.split(/\r?\n/).filter(Boolean) : [];
+}
+
+function validateSkillAuthority(root, skill, before, after) {
+  const violations = new Set();
+  const paths = new Set([
+    ...Object.keys(before.files || {}),
+    ...Object.keys(after.files || {}),
+  ]);
+  for (const file of paths) {
+    if (isAllowedSkillWrite(skill, file)) continue;
+    const beforeState = before.files[file] || fileState(root, file, 'clean');
+    const afterState = after.files[file] || fileState(root, file, 'clean');
+    if (stateSignature(beforeState) !== stateSignature(afterState)) violations.add(file);
+  }
+  for (const file of changedHeadPaths(root, before.head, after.head)) {
+    if (!isAllowedSkillWrite(skill, file)) violations.add(file);
+  }
+  if (violations.size > 0) {
+    throw new Error(`Operator skill modified files outside its authority: ${[...violations].sort().join(', ')}`);
+  }
+}
+
+function runSubprocess(command, args, options) {
+  return new Promise((resolve) => {
+    const child = cp.spawn(command, args, {
+      cwd: options.cwd,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: {
+        ...process.env,
+        HIVE_LITE_OPERATOR_RUN_ID: options.runId,
+        HIVE_LITE_OPERATOR_STEP_RESULT: options.resultPath,
+        HIVE_LITE_OPERATOR_ARTIFACTS_DIR: options.artifactsDir,
+      },
+    });
+    const stdout = fs.createWriteStream(options.stdoutPath);
+    const stderr = fs.createWriteStream(options.stderrPath);
+    let spawnError = null;
+    let timedOut = false;
+    let killTimer = null;
+    const timeoutMs = Number.isInteger(options.timeoutMs) ? options.timeoutMs : DEFAULT_AGENT_TIMEOUT_MS;
+    const timeoutTimer = timeoutMs > 0
+      ? setTimeout(() => {
+        timedOut = true;
+        child.kill('SIGTERM');
+        killTimer = setTimeout(() => {
+          child.kill('SIGKILL');
+        }, Math.min(2000, timeoutMs));
+        if (killTimer.unref) killTimer.unref();
+      }, timeoutMs)
+      : null;
+    if (timeoutTimer && timeoutTimer.unref) timeoutTimer.unref();
+    child.on('error', (error) => {
+      spawnError = error;
+    });
+    child.stdout.pipe(stdout);
+    child.stderr.pipe(stderr);
+    if (options.stdin !== null && options.stdin !== undefined) {
+      child.stdin.end(options.stdin);
+    } else {
+      child.stdin.end();
+    }
+    child.on('close', (code, signal) => {
+      if (timeoutTimer) clearTimeout(timeoutTimer);
+      if (killTimer) clearTimeout(killTimer);
+      stdout.end();
+      stderr.end();
+      resolve({ code, signal, error: spawnError, timedOut, timeoutMs });
+    });
+  });
+}
+
+async function runAgentStep(run, baseStep, skill, input, agentConfig, io) {
+  const stepName = nextStepName(run, baseStep);
+  const paths = stepPaths(run, stepName);
+  ensureDir(paths.stepDir);
+  ensureDir(paths.artifactsDir);
+
+  const body = skill === SKILLS.start ? startInvocationBody(input) : finishInvocationBody(run, input);
+  const invocation = createInvocation(run, paths, skill, body);
+  io.stdout.write(`Running ${skill}...\n`);
+
+  const args = [...agentConfig.args];
+  let stdin = null;
+  if (agentConfig.mode === 'stdin') {
+    stdin = invocation;
+  } else {
+    const promptTokenIndex = args.findIndex((arg) => arg.includes('{prompt_file}'));
+    if (promptTokenIndex === -1) args.push(paths.invocationPath);
+    else args[promptTokenIndex] = args[promptTokenIndex].replace(/\{prompt_file\}/g, paths.invocationPath);
+  }
+
+  io.stdout.write('[OK] agent session started\n');
+  io.stdout.write(`[..] waiting for structured result (logs: ${rel(run.root, paths.stdoutPath)}, ${rel(run.root, paths.stderrPath)})\n`);
+  const before = statusSnapshot(run.root);
+  const proc = await runSubprocess(agentConfig.command, args, {
+    cwd: run.root,
+    stdin,
+    stdoutPath: paths.stdoutPath,
+    stderrPath: paths.stderrPath,
+    resultPath: paths.resultPath,
+    artifactsDir: paths.artifactsDir,
+    runId: run.id,
+    timeoutMs: agentConfig.timeoutMs,
+  });
+
+  const after = statusSnapshot(run.root);
+  validateSkillAuthority(run.root, skill, before, after);
+
+  if (proc.error) {
+    throw new Error(`Operator agent failed to start: ${proc.error.message}`);
+  }
+  if (proc.timedOut) {
+    throw new Error(`Operator agent timed out after ${proc.timeoutMs}ms before completing the step. Transcript logs: ${rel(run.root, paths.stdoutPath)}, ${rel(run.root, paths.stderrPath)}. Expected result: ${rel(run.root, paths.resultPath)}`);
+  }
+  if (proc.code !== 0) {
+    throw new Error(`Operator agent exited with code ${proc.code}. Transcript logs: ${rel(run.root, paths.stdoutPath)}, ${rel(run.root, paths.stderrPath)}`);
+  }
+
+  return validateAndLoadStepResult(run, paths, skill);
+}
+
+function collectPathFields(value, fields = []) {
+  if (!value || typeof value !== 'object') return fields;
+  if (Array.isArray(value)) {
+    for (const item of value) collectPathFields(item, fields);
+    return fields;
+  }
+  for (const [key, child] of Object.entries(value)) {
+    if (key === 'artifact_hashes' || key === 'artifactHashes') continue;
+    if (key.endsWith('_path') && typeof child === 'string') fields.push({ key, value: child });
+    else collectPathFields(child, fields);
+  }
+  return fields;
+}
+
+function validateArtifactHashes(root, result, pathFields) {
+  const hashes = result.artifact_hashes || result.artifactHashes || {};
+  for (const field of pathFields) {
+    const expected = hashes[field.key] || hashes[field.value];
+    if (!expected) continue;
+    const file = resolveRepoPath(root, field.value);
+    if (!exists(file)) throw new Error(`artifact for hash check does not exist: ${field.value}`);
+    if (sha256(file) !== expected) throw new Error(`artifact hash mismatch: ${field.value}`);
+  }
+}
+
+function validateAndLoadStepResult(run, paths, expectedSkill) {
+  if (!exists(paths.resultPath)) {
+    throw new Error(`Operator step failed: missing step-result.json at ${rel(run.root, paths.resultPath)}. Transcript logs: ${rel(run.root, paths.stdoutPath)}, ${rel(run.root, paths.stderrPath)}`);
+  }
+  let result;
+  try {
+    result = readJson(paths.resultPath);
+  } catch (error) {
+    throw new Error(`Operator step failed: invalid step-result.json at ${rel(run.root, paths.resultPath)}: ${error.message}`);
+  }
+  if (result.schema_version !== STEP_RESULT_SCHEMA_VERSION) {
+    throw new Error(`Operator step failed: unsupported step-result schema_version ${result.schema_version || '(missing)'}`);
+  }
+  if (result.skill !== expectedSkill) {
+    throw new Error(`Operator step failed: expected skill ${expectedSkill}, got ${result.skill || '(missing)'}`);
+  }
+  if (!STATUS_ENUM.has(result.status)) {
+    throw new Error(`Operator step failed: invalid status ${result.status || '(missing)'}`);
+  }
+  if (!RECOMMENDED_ACTION_ENUM.has(result.recommended_action || 'none')) {
+    throw new Error(`Operator step failed: invalid recommended_action ${result.recommended_action || '(missing)'}`);
+  }
+  validateRecommendedAction(result);
+
+  const pathFields = collectPathFields(result);
+  for (const field of pathFields) {
+    assertOperatorPath(run.root, field.value, field.key);
+    if (!exists(resolveRepoPath(run.root, field.value))) {
+      throw new Error(`Operator step failed: artifact path does not exist: ${field.value}`);
+    }
+  }
+  validateArtifactHashes(run.root, result, pathFields);
+  validateRequiredArtifacts(result);
+  syncCurrentArtifacts(run.root, result, paths.resultPath);
+
+  if (result.ctx_id) run.context.ctx_id = result.ctx_id;
+  if (result.chg_id) run.context.chg_id = result.chg_id;
+  if (result.split && result.split.id) run.context.split_id = result.split.id;
+  saveRun(run);
+  return result;
+}
+
+function validateRecommendedAction(result) {
+  const allowedByStatus = {
+    prompt_ready: new Set(['copy_coding_prompt']),
+    split_required: new Set(['start_ready_phase']),
+    map_update_required: new Set(['map_update_required']),
+    needs_human_action: new Set(['manual_review_required', 'review_reason_required']),
+    accept_ready: new Set(['accept']),
+    risk_acceptance_required: new Set(['accept_risk', 'accept_with_risk']),
+    blocked: new Set(['revise_required']),
+  };
+  const allowed = allowedByStatus[result.status];
+  if (!allowed) return;
+  if (!result.recommended_action) {
+    throw new Error(`Operator step failed: ${result.status} requires recommended_action`);
+  }
+  if (!allowed.has(result.recommended_action)) {
+    throw new Error(`Operator step failed: ${result.status} cannot use recommended_action ${result.recommended_action}`);
+  }
+}
+
+function validateRequiredArtifacts(result) {
+  if (result.status === 'prompt_ready') {
+    const promptPath = result.artifacts && result.artifacts.coding_agent_prompt_path;
+    if (!promptPath) throw new Error('Operator step failed: prompt_ready requires artifacts.coding_agent_prompt_path');
+  }
+  if (result.status === 'split_required' && result.recommended_action === 'start_ready_phase') {
+    const phase = result.split && result.split.ready_phase;
+    if (!phase || !phase.handoff_prompt_path) {
+      throw new Error('Operator step failed: split_required requires split.ready_phase.handoff_prompt_path');
+    }
+  }
+  if (result.status === 'map_update_required') {
+    const mapUpdatePath = result.artifacts && result.artifacts.map_update_required_path;
+    if (!mapUpdatePath) throw new Error('Operator step failed: map_update_required requires artifacts.map_update_required_path');
+  }
+}
+
+function syncCurrentArtifacts(root, result, resultPath) {
+  ensureDir(currentRoot(root));
+  for (const [key, filename] of Object.entries(ARTIFACT_FILENAMES)) {
+    const artifactPath = result.artifacts && result.artifacts[key];
+    if (!artifactPath) continue;
+    const source = resolveRepoPath(root, artifactPath);
+    const target = path.join(currentRoot(root), filename);
+    if (path.resolve(source) !== path.resolve(target)) {
+      fs.copyFileSync(source, target);
+    }
+  }
+  fs.copyFileSync(resultPath, path.join(currentRoot(root), 'step-result.json'));
+}
+
+class ActionInput {
+  constructor(input, output) {
+    this.output = output;
+    this.nonInteractive = !input.isTTY;
+    this.closed = false;
+    if (this.nonInteractive) {
+      let text = '';
+      try {
+        text = fs.readFileSync(0, 'utf8');
+      } catch {
+        text = '';
+      }
+      this.lines = text.length ? text.split(/\r?\n/) : [];
+    } else {
+      this.rl = readline.createInterface({ input, output });
+    }
+  }
+
+  async ask(prompt, fallback = 'q') {
+    if (this.nonInteractive) {
+      const value = this.lines.length > 0 ? this.lines.shift() : fallback;
+      if (prompt) this.output.write(prompt);
+      return value;
+    }
+    return new Promise((resolve) => {
+      this.rl.question(prompt || '', (answer) => resolve(answer));
+    });
+  }
+
+  close() {
+    if (this.rl && !this.closed) this.rl.close();
+    this.closed = true;
+  }
+}
+
+function artifactPath(root, result, key) {
+  const value = result.artifacts && result.artifacts[key];
+  return value ? resolveRepoPath(root, value) : null;
+}
+
+function displayArtifact(root, result, key) {
+  if (ARTIFACT_FILENAMES[key]) {
+    const stable = path.join(currentRoot(root), ARTIFACT_FILENAMES[key]);
+    if (exists(stable)) return rel(root, stable);
+  }
+  const value = result.artifacts && result.artifacts[key];
+  return value || rel(root, path.join(currentRoot(root), ARTIFACT_FILENAMES[key]));
+}
+
+function copyPromptToClipboard(text) {
+  const platform = process.platform;
+  const candidates = platform === 'darwin'
+    ? [['pbcopy', []]]
+    : platform === 'win32'
+      ? [['clip', []]]
+      : [['wl-copy', []], ['xclip', ['-selection', 'clipboard']], ['xsel', ['--clipboard', '--input']]];
+  for (const [command, args] of candidates) {
+    try {
+      const result = cp.spawnSync(command, args, {
+        input: text,
+        encoding: 'utf8',
+        stdio: ['pipe', 'ignore', 'ignore'],
+      });
+      if (result.status === 0) return true;
+    } catch {
+      // Try the next platform clipboard helper.
+    }
+  }
+  return false;
+}
+
+async function renderPromptReady(run, result, agentConfig, input, io) {
+  const promptFile = artifactPath(run.root, result, 'coding_agent_prompt_path');
+  const promptDisplay = displayArtifact(run.root, result, 'coding_agent_prompt_path');
+  io.stdout.write('\nCoding Prompt Ready\n\n');
+  io.stdout.write('Prompt\n');
+  io.stdout.write(`  ${promptDisplay}\n\n`);
+  if (result.summary) {
+    io.stdout.write('Summary\n');
+    for (const line of String(result.summary).split(/\r?\n/)) io.stdout.write(`  ${line}\n`);
+    io.stdout.write('\n');
+  }
+  for (;;) {
+    io.stdout.write('Actions\n');
+    io.stdout.write('  [Enter] Copy prompt\n');
+    io.stdout.write('  [o] Open full prompt\n');
+    io.stdout.write('  [q] Quit\n');
+    const choice = (await input.ask('> ', '')).trim().toLowerCase();
+    if (choice === 'q') return null;
+    if (choice === 'o') {
+      io.stdout.write('\nFull Prompt\n\n');
+      io.stdout.write(readText(promptFile));
+      if (!readText(promptFile).endsWith('\n')) io.stdout.write('\n');
+      io.stdout.write('\n');
+      continue;
+    }
+    const text = readText(promptFile);
+    const copied = copyPromptToClipboard(text);
+    writeText(path.join(run.currentDir, 'copied-coding-agent-prompt.md'), text);
+    io.stdout.write('\nPrompt copied.\n');
+    if (!copied) io.stdout.write(`Clipboard unavailable; prompt copy is saved at ${rel(run.root, path.join(run.currentDir, 'copied-coding-agent-prompt.md'))}.\n`);
+    io.stdout.write('\nSend it to your coding agent.\n');
+    io.stdout.write('Return here when coding is finished.\n\n');
+    io.stdout.write('Actions\n');
+    io.stdout.write('  [Enter] Coding is done\n');
+    io.stdout.write('  [q] Quit\n');
+    const done = (await input.ask('> ', '')).trim().toLowerCase();
+    if (done === 'q') return null;
+    return runAgentStep(run, 'finish', SKILLS.finish, {}, agentConfig, io);
+  }
+}
+
+async function renderSplitRequired(run, result, agentConfig, input, io) {
+  const ready = result.split && result.split.ready_phase;
+  io.stdout.write('\nRequirement Split\n\n');
+  if (ready) {
+    io.stdout.write('Ready\n');
+    io.stdout.write(`  ${ready.id || 'phase'}${ready.title ? `: ${ready.title}` : ''}\n\n`);
+  }
+  const waiting = result.split && Array.isArray(result.split.waiting_phases) ? result.split.waiting_phases : [];
+  if (waiting.length > 0) {
+    io.stdout.write('Waiting\n');
+    for (const phase of waiting) io.stdout.write(`  ${phase.id}${phase.title ? `: ${phase.title}` : ''}\n`);
+    io.stdout.write('\n');
+  }
+  io.stdout.write('Actions\n');
+  io.stdout.write(`  [Enter] Start ${ready && ready.id ? ready.id : 'ready phase'}\n`);
+  io.stdout.write('  [q] Quit\n');
+  const choice = (await input.ask('> ', '')).trim().toLowerCase();
+  if (choice === 'q' || !ready || !ready.handoff_prompt_path) return null;
+  const handoffPath = resolveRepoPath(run.root, ready.handoff_prompt_path);
+  const handoffText = readText(handoffPath);
+  return runAgentStep(run, 'start', SKILLS.start, {
+    type: 'handoff',
+    handoffText,
+  }, agentConfig, io);
+}
+
+async function renderManualReview(run, result, agentConfig, input, io) {
+  io.stdout.write('\nManual Review Required\n\n');
+  io.stdout.write('Please verify the changed behavior manually.\n\n');
+  const checks = result.manual_review && Array.isArray(result.manual_review.checks)
+    ? result.manual_review.checks
+    : [];
+  if (checks.length > 0) {
+    io.stdout.write('Check\n');
+    for (const check of checks) io.stdout.write(`  ${check}\n`);
+    io.stdout.write('\n');
+  }
+  io.stdout.write('Actions\n');
+  io.stdout.write('  [a] 已人工确认，通过\n');
+  io.stdout.write('  [d] 已人工确认，否决\n');
+  io.stdout.write('  [q] Quit\n');
+  const choice = (await input.ask('> ', 'q')).trim().toLowerCase();
+  if (choice === 'a') {
+    return runAgentStep(run, 'finish', SKILLS.finish, {
+      kind: 'manual_review_passed',
+      chg_id: result.chg_id,
+      note: 'Human selected 已人工确认，通过 in the operator runner.',
+    }, agentConfig, io);
+  }
+  if (choice === 'd') {
+    io.stdout.write('\nReview Failed\n\n');
+    io.stdout.write('Current change should not be accepted.\n');
+    io.stdout.write('Ask the coding agent to revise using the same prompt/context.\n\n');
+    io.stdout.write('Actions\n');
+    io.stdout.write('  [Enter] Coding is done\n');
+    io.stdout.write('  [q] Quit\n');
+    const done = (await input.ask('> ', '')).trim().toLowerCase();
+    if (done === 'q') return null;
+    return runAgentStep(run, 'finish', SKILLS.finish, {}, agentConfig, io);
+  }
+  return null;
+}
+
+async function renderAcceptReady(run, result, agentConfig, input, io) {
+  io.stdout.write('\nFinish Passed\n\n');
+  if (result.finish) {
+    if (result.finish.changed_file_count !== undefined) {
+      io.stdout.write('Changed\n');
+      io.stdout.write(`  ${result.finish.changed_file_count} files\n\n`);
+    }
+    if (result.finish.evidence_verdict) {
+      io.stdout.write('Evidence\n');
+      io.stdout.write(`  ${result.finish.evidence_verdict}\n\n`);
+    }
+    if (result.finish.risk_level) {
+      io.stdout.write('Risk\n');
+      io.stdout.write(`  ${result.finish.risk_level}\n\n`);
+    }
+  }
+  io.stdout.write('Actions\n');
+  io.stdout.write('  [a] Accept\n');
+  io.stdout.write('  [q] Quit\n');
+  const choice = (await input.ask('> ', 'q')).trim().toLowerCase();
+  if (choice !== 'a') return null;
+  return runAgentStep(run, 'finish', SKILLS.finish, {
+    kind: 'accept',
+    chg_id: result.chg_id,
+  }, agentConfig, io);
+}
+
+async function renderRiskRequired(run, result, agentConfig, input, io) {
+  io.stdout.write('\nRisk Acceptance Required\n\n');
+  if (result.reason) {
+    io.stdout.write('Reason\n');
+    io.stdout.write(`  ${result.reason}\n\n`);
+  }
+  io.stdout.write('Actions\n');
+  io.stdout.write('  [Enter] Enter risk reason\n');
+  io.stdout.write('  [q] Quit\n');
+  const choice = (await input.ask('> ', '')).trim().toLowerCase();
+  if (choice === 'q') return null;
+  let reason = '';
+  while (!reason) {
+    reason = (await input.ask('Risk reason: ', '')).trim();
+    if (!reason) io.stdout.write('Risk reason is required before accept-risk.\n');
+    if (!reason && input.nonInteractive) return null;
+  }
+  io.stdout.write('\nRisk reason recorded.\n\n');
+  io.stdout.write('Actions\n');
+  io.stdout.write('  [a] Accept with risk\n');
+  io.stdout.write('  [q] Quit\n');
+  const accept = (await input.ask('> ', 'q')).trim().toLowerCase();
+  if (accept !== 'a') return null;
+  return runAgentStep(run, 'finish', SKILLS.finish, {
+    kind: 'accept_risk',
+    chg_id: result.chg_id,
+    reason,
+  }, agentConfig, io);
+}
+
+async function renderReviewReasonRequired(run, result, agentConfig, input, io) {
+  io.stdout.write('\nReview Reason Required\n\n');
+  io.stdout.write('A human review reason is required before this change can be accepted.\n\n');
+  const reason = (await input.ask('Review reason: ', '')).trim();
+  if (!reason) return null;
+  return runAgentStep(run, 'finish', SKILLS.finish, {
+    kind: 'review_reason',
+    chg_id: result.chg_id,
+    reason,
+  }, agentConfig, io);
+}
+
+async function renderBlocked(run, result, agentConfig, input, io) {
+  io.stdout.write('\nBlocked\n\n');
+  const blockers = result.blockers || result.reasons || [];
+  if (blockers.length > 0) {
+    io.stdout.write('Reason\n');
+    for (const blocker of blockers) io.stdout.write(`  ${blocker}\n`);
+    io.stdout.write('\n');
+  }
+  io.stdout.write('Current change cannot be accepted.\n\n');
+  io.stdout.write('Next\n');
+  io.stdout.write('  Ask the coding agent to revise the change, then return here.\n\n');
+  io.stdout.write('Actions\n');
+  io.stdout.write('  [Enter] Coding is done\n');
+  io.stdout.write('  [q] Quit\n');
+  const choice = (await input.ask('> ', 'q')).trim().toLowerCase();
+  if (choice === 'q') return null;
+  return runAgentStep(run, 'finish', SKILLS.finish, {}, agentConfig, io);
+}
+
+async function renderMapUpdateRequired(run, result, input, io) {
+  io.stdout.write('\nMap Update Required\n\n');
+  const details = displayArtifact(run.root, result, 'map_update_required_path');
+  io.stdout.write('Details\n');
+  io.stdout.write(`  ${details}\n\n`);
+  const changed = result.map_update && Array.isArray(result.map_update.changed_files)
+    ? result.map_update.changed_files
+    : [];
+  if (changed.length > 0) {
+    io.stdout.write('Changed\n');
+    for (const file of changed) io.stdout.write(`  ${file}\n`);
+    io.stdout.write('\n');
+  }
+  io.stdout.write('Reason\n');
+  io.stdout.write('  Project Map was updated while preparing this requirement.\n');
+  io.stdout.write('  Commit or stash the map update before generating the coding prompt.\n\n');
+  for (;;) {
+    io.stdout.write('Actions\n');
+    io.stdout.write('  [o] Open details\n');
+    io.stdout.write('  [q] Quit\n');
+    const choice = (await input.ask('> ', 'q')).trim().toLowerCase();
+    if (choice === 'o') {
+      const file = artifactPath(run.root, result, 'map_update_required_path');
+      const text = readText(file);
+      io.stdout.write('\n');
+      io.stdout.write(text);
+      if (!text.endsWith('\n')) io.stdout.write('\n');
+      io.stdout.write('\n');
+      continue;
+    }
+    return null;
+  }
+}
+
+async function handleStepResult(run, result, agentConfig, input, io) {
+  let current = result;
+  while (current) {
+    if (current.status === 'prompt_ready' && current.recommended_action === 'copy_coding_prompt') {
+      current = await renderPromptReady(run, current, agentConfig, input, io);
+    } else if (current.status === 'split_required' && current.recommended_action === 'start_ready_phase') {
+      current = await renderSplitRequired(run, current, agentConfig, input, io);
+    } else if (current.status === 'needs_human_action' && current.recommended_action === 'manual_review_required') {
+      current = await renderManualReview(run, current, agentConfig, input, io);
+    } else if (current.status === 'needs_human_action' && current.recommended_action === 'review_reason_required') {
+      current = await renderReviewReasonRequired(run, current, agentConfig, input, io);
+    } else if (current.status === 'accept_ready' && current.recommended_action === 'accept') {
+      current = await renderAcceptReady(run, current, agentConfig, input, io);
+    } else if (current.status === 'risk_acceptance_required') {
+      current = await renderRiskRequired(run, current, agentConfig, input, io);
+    } else if (current.status === 'blocked' || current.recommended_action === 'revise_required') {
+      current = await renderBlocked(run, current, agentConfig, input, io);
+    } else if (current.status === 'map_update_required') {
+      current = await renderMapUpdateRequired(run, current, input, io);
+    } else if (current.status === 'accepted' || current.status === 'done') {
+      io.stdout.write('\nOperator step complete.\n');
+      current = null;
+    } else if (current.status === 'failed') {
+      throw new Error('Operator skill reported failed status.');
+    } else {
+      io.stdout.write(`\nNo V1 action available for ${current.status}/${current.recommended_action || 'none'}.\n`);
+      current = null;
+    }
+  }
+}
+
+async function runOperator(cwd, options = {}, io = {}) {
+  const root = options.root || cwd;
+  const out = io.stdout || process.stdout;
+  const err = io.stderr || process.stderr;
+  const inputStream = io.stdin || process.stdin;
+  const input = new ActionInput(inputStream, out);
+  try {
+    const hasIntent = !!options.intent;
+    const requirement = String(options.requirement || '').trim();
+    if (hasIntent) {
+      const validation = validateIntentTarget(root, cwd, options.intent);
+      if (!validation.valid) {
+        const errors = validation.errors.map((item) => `${item.code}: ${item.message}`).join('; ');
+        throw new Error(`Start Intent Handoff is invalid: ${errors || 'validation failed'}`);
+      }
+      const shown = readIntentTarget(root, cwd, options.intent);
+      printIntentShow({ stdout: out, stderr: err }, validation, shown);
+    } else if (!requirement) {
+      throw new Error('operator run requires a clear requirement or --intent <intent_id_or_path>');
+    }
+
+    const agentConfig = resolveAgentConfig(options, process.env);
+    const run = createRun(root, hasIntent
+      ? { type: 'start_intent', target: options.intent }
+      : { type: 'clear_requirement' });
+
+    let startInput;
+    if (hasIntent) {
+      const copied = copyIntentInput(run, cwd, options.intent);
+      run.input.intent_id = copied.validation.intent_id;
+      run.input.paths = copied.copied;
+      saveRun(run);
+      startInput = {
+        type: 'intent',
+        intentPath: copied.copied.current_markdown,
+        originalTarget: options.intent,
+      };
+    } else {
+      const paths = writeRequirementInput(run, requirement);
+      run.input.requirement_path = paths.requirement_path;
+      run.input.current_requirement_path = paths.current_requirement_path;
+      saveRun(run);
+      startInput = {
+        type: 'requirement',
+        requirement,
+      };
+    }
+
+    const result = await runAgentStep(run, 'start', SKILLS.start, startInput, agentConfig, { stdout: out, stderr: err });
+    await handleStepResult(run, result, agentConfig, input, { stdout: out, stderr: err });
+    run.status = 'complete';
+    saveRun(run);
+    return run;
+  } finally {
+    input.close();
+  }
+}
+
+module.exports = {
+  STEP_RESULT_SCHEMA_VERSION,
+  copyIntentInput,
+  createRun,
+  resolveAgentConfig,
+  runAgentStep,
+  runOperator,
+  splitCommand,
+  validateAndLoadStepResult,
+};