@hoplogic/hopjit 0.1.0

package/dist/cli.js

@@ -0,0 +1,623 @@
+#!/usr/bin/env node
+// @module: hop-cli ^anc-struct-hop-cli
+import { Command } from 'commander';
+import { readFileSync, readdirSync, statSync, existsSync, mkdirSync, copyFileSync, cpSync } from 'node:fs';
+import { resolve, join, isAbsolute, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ExecutionEngine } from './engine.js';
+import { parseSpec } from './parser.js';
+import { validateSpec } from './validator.js';
+import { readVars, readState, stateExists, flattenVars } from './persistence.js';
+import { hasChildren, getChildren } from './ast-helpers.js';
+// 在 spec 树中按 step_id 查找节点（join_parallel 用于定位 parallel 容器及其 children）
+function findStepInSpec(stepId, steps) {
+    for (const step of steps) {
+        if (step.step_id === stepId)
+            return step;
+        if (hasChildren(step)) {
+            const found = findStepInSpec(stepId, getChildren(step));
+            if (found)
+                return found;
+        }
+    }
+    return null;
+}
+const program = new Command();
+program.name('hopjit').version('0.1.0').description('HopStep execution engine CLI'); // @a: anc-struct-hop-cli, anc-cli-dispatch
+/** 把结果序列化为单行 JSON 写 stdout——CLI 对 Agent 消费方的结构化输出约定。见 [[hop-cli#^anc-cli-json-io]] */
+export function output(data) {
+    process.stdout.write(JSON.stringify(data) + '\n');
+}
+/** 运行时错误（参数非法、IO 失败）写 stderr 并以非零 exit code 退出，与业务错误的 stdout JSON 分流。见 [[hop-cli#^anc-cli-json-io]] */
+export function errorExit(message, code = 1) {
+    process.stderr.write(`Error: ${message}\n`);
+    process.exit(code);
+}
+// @file 解析根目录：并行 worker 的裸文件名（无 / 、非绝对）重定向到该 child 的 work_zone，
+// 消除多 worker 共享 cwd 的固定名竞态。见 design/hop-cli.md ^anc-cli-parallel-file-isolation。
+// @a: anc-cli-parallel-file-isolation
+export function resolveFileArgBase(filePath, workZoneBase) {
+    // 仅对 worker 子实例的「裸文件名」重定向；绝对路径/含 / 的相对路径尊重 driver 显式意图
+    if (workZoneBase && !isAbsolute(filePath) && !filePath.includes('/')) {
+        return join(workZoneBase, filePath);
+    }
+    return resolve(filePath);
+}
+/** 解析 JSON 参数：`@file` 前缀从文件读取（走 worker work_zone 重定向），否则原样 JSON.parse。见 [[hop-cli#^anc-cli-file-arg-safety]] */
+export function resolveParam(value, workZoneBase) {
+    if (!value)
+        return undefined;
+    if (value.startsWith('@')) {
+        const filePath = resolveFileArgBase(value.slice(1), workZoneBase);
+        return JSON.parse(readFileSync(filePath, 'utf-8'));
+    }
+    return JSON.parse(value);
+}
+/** 提交越界校验：`--output @<path>` 的解析路径必须落在本执行单元 work_zone 内，越界（/tmp、
+ * 项目根、兄弟 child）→ 抛错拒绝提交。引擎唯一能真拦的点（复用模式 act 由 CC 执行、写入不过引擎，
+ * 只能提交时校验）。回归 ppt-html v4 串台：worker 写共享 /tmp 互相覆盖。见 [[hop-cli#^anc-cli-file-arg-safety]]。
+ * @a: anc-cli-file-arg-safety */
+export function assertOutputInWorkZone(value, instanceDir, workZoneBase) {
+    if (!value || !value.startsWith('@'))
+        return; // 内联 JSON 不涉文件，免校验
+    const resolved = resolveFileArgBase(value.slice(1), workZoneBase);
+    const workZone = resolve(join(instanceDir, 'work_zone'));
+    // 允许 work_zone 目录本身及其子路径（含 worker 子实例的 <childDir>/work_zone，因 instanceDir 已是 childDir）
+    if (resolved !== workZone && !resolved.startsWith(workZone + '/')) {
+        errorExit(`WORK_ZONE_VIOLATION: --output 路径越界 '${resolved}' 不在本执行单元 work_zone '${workZone}' 内。`
+            + `请把 output 写到 work_zone（响应给出的 output_path），不要写 /tmp 或自选绝对路径——否则与兄弟 worker 串台。`);
+    }
+}
+/** 解析文本参数（如 --steps/--reason）：`@file` 前缀读文件原文，否则返回原值——LLM 生成内容经 @file 防注入。见 [[hop-cli#^anc-cli-file-arg-safety]] */
+export function resolveTextParam(value, workZoneBase) {
+    if (!value)
+        return undefined;
+    if (value.startsWith('@')) {
+        const filePath = resolveFileArgBase(value.slice(1), workZoneBase);
+        return readFileSync(filePath, 'utf-8');
+    }
+    return value;
+}
+// 判定 --instance 是否指向 parallel worker 子实例（路径含 /parallel/），
+// 是则返回其 work_zone 工作区用于裸文件名重定向。// @a: anc-cli-parallel-file-isolation
+export function workerWorkZone(instanceDir, instanceOpt) {
+    if (!instanceOpt || !instanceOpt.includes('/parallel/'))
+        return undefined;
+    return join(instanceDir, 'work_zone');
+}
+/** 解析目标实例目录：显式 --instance 直接定位，省略时取 state_dir 下最新（按 mtime）实例。见 [[hop-cli#^anc-cli-instance-resolve]] */
+export function resolveInstance(stateDir, instanceId) {
+    if (instanceId) {
+        return join(stateDir, instanceId);
+    }
+    // 先按目录类型过滤（跳过文件），再取 mtime 排最新；单项 statSync 容错——
+    // 目录混入不可 stat 的项（权限/竞态删除）不应中断整个解析。
+    const entries = readdirSync(stateDir, { withFileTypes: true })
+        .filter(d => d.isDirectory())
+        .map(d => {
+        try {
+            return { name: d.name, mtimeMs: statSync(join(stateDir, d.name)).mtimeMs };
+        }
+        catch {
+            return null;
+        }
+    })
+        .filter((e) => e !== null)
+        .sort((a, b) => b.mtimeMs - a.mtimeMs);
+    if (entries.length === 0) {
+        throw new Error('No instances found in state directory');
+    }
+    return join(stateDir, entries[0].name);
+}
+/** 构造 CLI 默认 HostConfig（workspace=cwd + 默认沙箱），供独立模式命令实例化 Engine/Dispatcher。见 [[hop-cli#^anc-struct-hop-cli]] */
+export function buildHostConfig() {
+    return {
+        workspace_dir: process.cwd(),
+        sandbox: {
+            filesystem: { workspace_dir: '.', read_access: { allowed: ['.'], denied: [], confirm_required: [] } },
+            network: { trusted_hosts: [] },
+            runtime: { available: [] },
+        },
+        api_key: process.env['HOPSTEP_ANTHROPIC_API_KEY'] ?? '',
+    };
+}
+/** context 精简档 resolve：env HOPJIT_CONTEXT_MODE > --context-mode flag > 默认 full。见 [[prompt-assembler#^anc-exec-context-mode]] */
+export function resolveContextMode(flag) {
+    const v = (process.env['HOPJIT_CONTEXT_MODE'] ?? flag ?? '').toLowerCase();
+    return v === 'minimal' ? 'minimal' : 'full';
+}
+// === Commands ===
+// 执行前合法性校验——只读，不创建实例。返回 error+warn 全集。
+// 见 [[HopSpec V3配套HopJIT运行时能力#^anc-exec-validation]]
+program.command('validate <spec>')
+    .description('Validate spec legality without creating an instance')
+    .action((specPath) => {
+    try {
+        const content = readFileSync(resolve(specPath), 'utf-8');
+        const { ast, errors: parseErrors } = parseSpec(content);
+        // 解析错误即 error 级，无法继续验证规则
+        if (parseErrors.length > 0) {
+            output({ status: 'error', errors: parseErrors, warnings: [] });
+            return;
+        }
+        const all = validateSpec(ast);
+        const errors = all.filter((e) => e.severity === 'error');
+        const warnings = all.filter((e) => e.severity === 'warn');
+        output({
+            status: errors.length > 0 ? 'error' : 'ok',
+            errors: errors,
+            warnings: warnings,
+        });
+    }
+    catch (err) {
+        errorExit(err instanceof Error ? err.message : String(err));
+    }
+});
+// list <dir>：扫目录列可执行 spec（无状态纯函数）。判定规则见 design/hop-cli.md ^anc-cli-list // @a: anc-cli-list
+program.command('list <dir>')
+    .description('List executable HopSpec files in a directory (no state, no instance)')
+    .action((dir) => {
+    try {
+        const dirAbs = resolve(dir);
+        const entries = readdirSync(dirAbs).filter(f => f.endsWith('.md')).sort();
+        const specs = [];
+        for (const file of entries) {
+            const full = join(dirAbs, file);
+            let content;
+            try {
+                content = readFileSync(full, 'utf-8');
+            }
+            catch {
+                continue;
+            }
+            // 排除设计文档：@trace 头 / design/ 路径 / impl 段
+            if (content.includes('%% @trace') || full.includes('/design/') || content.includes('## impl '))
+                continue;
+            const { ast, errors: parseErrors } = parseSpec(content);
+            if (parseErrors.length > 0)
+                continue; // 解析失败跳过
+            const goal = (ast.header.goal ?? '').trim();
+            const hasSteps = (ast.steps?.length ?? 0) > 0;
+            if (!goal || !hasSteps)
+                continue; // 非可执行 spec
+            const goalFirst = goal.split(/[\n。.]/)[0].trim(); // Goal 首句
+            specs.push({ file, id: (ast.header.id ?? ast.header.title ?? '').trim(), goal: goalFirst });
+        }
+        output({ status: 'ok', dir, specs });
+    }
+    catch (err) {
+        errorExit(err instanceof Error ? err.message : String(err));
+    }
+});
+program.command('init <spec>')
+    .description('Parse spec and initialize execution instance')
+    .option('--params <json>', 'Spec inputs as JSON or @file')
+    .option('--parent <id>', 'Parent instance ID')
+    .option('--step <id>', 'Call step ID')
+    .option('--parallel-parent <id>', 'Parent instance ID (for parallel child subinstance)')
+    .option('--parallel-child <id>', 'Parallel child step ID (subinstance落 <parent>/parallel/<id>/)')
+    .option('--trace <id>', 'Trace ID')
+    .option('--state-dir <dir>', 'State directory', '.hopstate')
+    .option('--log-dir <dir>', 'Log directory for .hoplog output')
+    .option('--log-level <level>', 'Log level: debug | info | warn', 'info')
+    .action((specPath, opts) => {
+    try {
+        const content = readFileSync(resolve(specPath), 'utf-8');
+        const hostConfig = buildHostConfig();
+        const params = resolveParam(opts.params);
+        // 子实例（复用模式）两类：call → <stateDir>/<parent>/calls/<step>/；parallel → <parent>/parallel/<child>/
+        const callMode = opts.parent && opts.step; // @a: anc-step-call
+        const isParallelChild = !!(opts.parallelParent && opts.parallelChild); // @a: anc-exec-parallel-subinstance
+        const childParent = callMode ? opts.parent : isParallelChild ? opts.parallelParent : undefined;
+        const childStep = callMode ? opts.step : isParallelChild ? opts.parallelChild : undefined;
+        const subdir = callMode ? 'calls' : 'parallel';
+        const effectiveStateDir = (callMode || isParallelChild)
+            ? join(opts.stateDir, childParent, subdir)
+            : opts.stateDir;
+        const engineOpts = {
+            stateDir: effectiveStateDir,
+            ...(params ? { params } : {}),
+            ...(opts.logDir ? { logDir: opts.logDir } : {}),
+            ...(opts.logLevel ? { logLevel: opts.logLevel } : {}),
+            ...((callMode || isParallelChild) ? { parentInstanceId: childParent, callStepId: childStep } : {}),
+            ...(isParallelChild ? { canFanout: false, subtreeRoot: opts.parallelChild } : {}),
+            ...(opts.trace ? { traceId: opts.trace } : {}),
+        };
+        const engine = new ExecutionEngine();
+        const result = engine.initExecution(content, hostConfig, engineOpts);
+        output(result);
+    }
+    catch (err) {
+        errorExit(err instanceof Error ? err.message : String(err));
+    }
+});
+// run = init + 推进到首个 caller 介入点（引擎 completeAndAdvance 节奏）。// @a: anc-cli-dispatch, anc-exec-parallel-subinstance
+// 支持 --parallel-parent/--parallel-child 创建 worker 子实例并推进（worker 一条命令完成 init+advance）。
+program.command('run <spec>')
+    .description('Init and advance to first caller-action point or terminal (combines init + advance)')
+    .option('--params <json>', 'Spec inputs as JSON or @file')
+    .option('--parallel-parent <id>', 'Parent instance ID (for parallel worker subinstance)')
+    .option('--parallel-child <id>', 'Parallel child step ID (worker scope)')
+    .option('--state-dir <dir>', 'State directory', '.hopstate')
+    .option('--log-dir <dir>', 'Log directory for .hoplog output')
+    .option('--log-level <level>', 'Log level: debug | info | warn', 'info')
+    .option('--context-mode <mode>', 'Context verbosity: full (default) | minimal (see ^anc-exec-context-mode)')
+    .action(async (specPath, opts) => {
+    try {
+        const content = readFileSync(resolve(specPath), 'utf-8');
+        const hostConfig = buildHostConfig();
+        const isWorker = !!(opts.parallelParent && opts.parallelChild);
+        const effectiveStateDir = isWorker
+            ? join(opts.stateDir, opts.parallelParent, 'parallel')
+            : opts.stateDir;
+        // worker 启动入口也走裸 @file 隔离：--params @裸名 重定向到本 child work_zone，
+        // 与 submit_and_fetch_next 同规则，消除共享 cwd 竞态。// @a: anc-cli-parallel-file-isolation
+        const runWorkZoneBase = isWorker
+            ? join(opts.stateDir, opts.parallelParent, 'parallel', opts.parallelChild, 'work_zone')
+            : undefined;
+        const params = resolveParam(opts.params, runWorkZoneBase);
+        // for-each worker 的 itemVar 经引擎单一权威、driver 透传的 --params 注入——
+        // worker 不翻父实例自播种（破隔离+权威倒置，已撤；缺 itemVar 由 engine init 硬校验报错）。
+        // 见 design/parallel-execution.md §9e ^anc-exec-parallel-foreach-worker。// @a: anc-exec-parallel-foreach-worker
+        const engineOpts = {
+            stateDir: resolve(effectiveStateDir),
+            canFanout: !isWorker,
+            specPath: resolve(specPath),
+            cliAbsPath: resolve(fileURLToPath(import.meta.url)),
+            ...(isWorker ? { subtreeRoot: opts.parallelChild, parentInstanceId: opts.parallelParent, callStepId: opts.parallelChild, traceId: opts.parallelParent } : {}), // @a: anc-obs-trace-inherit
+            ...(params ? { params } : {}),
+            ...(opts.logDir ? { logDir: resolve(opts.logDir) } : {}),
+            ...(opts.logLevel ? { logLevel: opts.logLevel } : {}),
+            contextMode: resolveContextMode(opts.contextMode), // env > flag > full。@a: anc-exec-context-mode
+        };
+        const engine = new ExecutionEngine();
+        const initResult = engine.initExecution(content, hostConfig, engineOpts);
+        if (initResult.status !== 'ok') {
+            output(initResult);
+            return;
+        }
+        const result = await engine.advanceToCaller();
+        output(result);
+    }
+    catch (err) {
+        errorExit(err instanceof Error ? err.message : String(err));
+    }
+});
+// submit_and_fetch_next：driver 主循环唯一应答命令——交活 + 领取下一指令（一次原子往返）。
+// 提交内容由互斥参数区分；回写成功则 completeAndAdvance 推进返回 NextResponse，出错原样返回不推进。
+// 节奏归引擎，见 design/exec-engine.md ^anc-exec-advance-to-caller。// @a: anc-cli-dispatch
+program.command('submit_and_fetch_next <step-id>')
+    .description('Submit step result and fetch next caller-action point (driver main loop)')
+    .option('--output <json>', 'Step result (reason/check/act) as JSON or @file')
+    .option('--answer <json>', 'Confirm decision (HITL) as JSON or @file')
+    .option('--child-instance <id>', 'Call child instance ID (maps callee outputs back)')
+    .option('--failure <text>', 'Step failure reason')
+    .option('--branch <case-id>', 'Branch case selection')
+    .option('--replan <md>', 'Replanned children markdown or @file (for adaptive_needed)')
+    .option('--reason <text>', 'Optional reason (for branch selection audit)')
+    .option('--instance <id>', 'Instance ID')
+    .option('--state-dir <dir>', 'State directory', '.hopstate')
+    .action(async (stepId, opts) => {
+    try {
+        // 互斥校验：一次只提交一种
+        const modes = ['output', 'answer', 'childInstance', 'failure', 'branch', 'replan']
+            .filter(k => opts[k] !== undefined);
+        if (modes.length > 1) {
+            throw new Error(`INVALID_STATE: 互斥参数只能给一个，收到 [${modes.join(', ')}]`);
+        }
+        const instanceDir = resolveInstance(opts.stateDir, opts.instance);
+        const engine = ExecutionEngine.load(instanceDir);
+        // can_fanout 已从 StateFile 恢复（顶层 true / worker false），无需显式设
+        // parallel worker 裸 @file 重定向到本 child work_zone，消除共享 cwd 竞态。
+        // @a: anc-cli-parallel-file-isolation
+        const workZoneBase = workerWorkZone(instanceDir, opts.instance);
+        // 按参数路由到回写方法 → 成功则 completeAndAdvance 推进；出错原样返回不推进。
+        let writeResult;
+        if (opts.childInstance) { // call 回填
+            const childDir = join(instanceDir, 'calls', opts.childInstance);
+            const childVars = flattenVars(readVars(childDir));
+            writeResult = engine.completeCallStep(stepId, childVars);
+        }
+        else if (opts.failure !== undefined) { // 步骤失败
+            const reason = resolveTextParam(opts.failure, workZoneBase) ?? opts.failure;
+            writeResult = engine.failStep(stepId, reason);
+        }
+        else if (opts.branch !== undefined) { // 分支选择
+            writeResult = engine.selectBranch(stepId, opts.branch, opts.reason);
+        }
+        else if (opts.replan !== undefined) { // 重规划 children
+            const stepsMd = resolveTextParam(opts.replan, workZoneBase) ?? opts.replan;
+            writeResult = engine.submitReplan(stepId, stepsMd);
+        }
+        else { // 普通输出 / confirm answer
+            // output / answer 互斥（前面 modes 校验保证），取非空的那个解析
+            // 提交越界校验：--output @file 的路径必须在本执行单元 work_zone 内，越界拒绝（防串台）。
+            // @a: anc-cli-file-arg-safety
+            if (opts.output !== undefined)
+                assertOutputInWorkZone(opts.output, instanceDir, workZoneBase);
+            const raw = opts.output ?? opts.answer;
+            const outputs = raw ? resolveParam(raw, workZoneBase) : undefined;
+            writeResult = engine.completeStep(stepId, outputs);
+        }
+        if (writeResult.status !== 'ok') {
+            output(writeResult);
+            return;
+        } // 出错不推进
+        const next = await engine.advanceToCaller();
+        output(next);
+    }
+    catch (err) {
+        errorExit(err instanceof Error ? err.message : String(err));
+    }
+});
+// join_parallel：N 个 worker 子实例全部完成后，单进程收集各子目录输出 merge 回父 scope，推进到下一步。
+// 规避 N 进程并发写父 state.json/vars.json 的丢更新（决策9）。// @a: anc-exec-parallel-join-merge
+program.command('join_parallel <parallel-step-id>')
+    .description('Collect parallel child subinstance outputs, merge into parent scope, advance (single-process join)')
+    .option('--instance <id>', 'Instance ID')
+    .option('--state-dir <dir>', 'State directory', '.hopstate')
+    .action(async (parallelStepId, opts) => {
+    try {
+        const instanceDir = resolveInstance(opts.stateDir, opts.instance);
+        const engine = ExecutionEngine.load(instanceDir);
+        // can_fanout 已从 StateFile 恢复（join 在顶层实例调，can_fanout=true）
+        const spec = engine.getSpec();
+        const parallel = spec ? findStepInSpec(parallelStepId, spec.steps ?? []) : null;
+        if (!parallel || parallel.step_type !== 'parallel') {
+            errorExit(`INVALID_STEP_ID: '${parallelStepId}' is not a parallel step`);
+            return;
+        }
+        // 收集各 child 子实例结果：读 parallel/<child_id>/ 的 vars + state（判定 failed）。
+        // for-each parallel 的 spec 只有模板 child（{P}.1），fan-out 落 N 个合成子实例目录——
+        // 必须扫 parallel/ 目录枚举实际子实例，不能用 getChildren（只有模板，漏 N-1 个）。
+        // 见 design/parallel-execution.md §9c' ^anc-exec-parallel-foreach-join-collect。// @a: anc-exec-parallel-foreach-join-collect
+        const parallelDir = join(instanceDir, 'parallel');
+        const scanForeachChildren = () => {
+            try {
+                return readdirSync(parallelDir, { withFileTypes: true }) // forEach：枚举实际合成子实例目录
+                    .filter(e => e.isDirectory() && e.name.startsWith(`${parallelStepId}.`))
+                    .map(e => e.name);
+            }
+            catch {
+                return [];
+            } // parallel/ 目录不存在（未 fan-out 即 join）→ 空集
+        };
+        const childIds = parallel.forEach
+            ? scanForeachChildren()
+            : getChildren(parallel).map(c => c.step_id); // 静态：spec children 即真实 ID
+        // join 前置不变量（见 design/exec-engine.md ^anc-exec-parallel-join-preconditions）：
+        // ① 完整性+终态校验：所有期望的 fan-out child 必须有终态子实例（漏建/仍 running → 拒绝 join），
+        //    防 driver 提前 join 漏 worker 产生残缺 merge；
+        // ② 格式校验：readState/readVars 内置 format_version + 关键字段校验（CORRUPT_STATE_FILE）；
+        // ③ 单 child 读失败隔离：try/catch 包每个 child，损坏的标 failed 不连累其余。
+        // @a: anc-exec-parallel-join-preconditions
+        // for-each 期望 child 数 = listVar 长度；每个合成 ID {P}.k 都必须有终态子实例。
+        // 未启动的 worker 根本没有子目录，单靠"扫已存在目录"会漏掉它们——故按期望集逐一核验。
+        const expectedIds = (() => {
+            if (!parallel.forEach)
+                return childIds; // 静态：spec children 即期望集
+            const listVar = parallel.forEach.listVar;
+            const listVal = flattenVars(readVars(instanceDir))[listVar];
+            // listVar 非数组必须响亮报错，不静默算 0——否则"listVar 坏了"（deflate @file/$file 指针、
+            // 上游谎报）会伪装成"0 个 child"、产出空 join，故障漂离源头。见 design ^anc-exec-parallel-join-preconditions。
+            if (!Array.isArray(listVal)) {
+                errorExit(`INVALID_STATE: for-each listVar '${listVar}' 不是数组（实际 ${typeof listVal}${typeof listVal === 'string' ? `: ${JSON.stringify(String(listVal).slice(0, 60))}` : ''}），无法算期望 child 数——上游该输出真数组，勿传 @file 指针字符串`);
+                return [];
+            }
+            return Array.from({ length: listVal.length }, (_, i) => `${parallelStepId}.${i + 1}`);
+        })();
+        const childResults = {};
+        let blockedChild = null; // ① 漏建/未终态违例（收集后统一 errorExit）
+        for (const childId of expectedIds) {
+            const childDir = join(parallelDir, childId);
+            if (!stateExists(childDir)) {
+                // 子实例不存在：for-each 必须全部 worker 跑完——漏建即未完成，拒绝；
+                // 静态 parallel 的 child 可能因含 confirm 退串行而无子实例目录，跳过（其状态在父 state 中串行推进）。
+                if (parallel.forEach) {
+                    blockedChild = childId;
+                    break;
+                }
+                continue;
+            }
+            try {
+                const childState = readState(childDir);
+                // ① 终态校验：worker 仍在跑（含 running 步骤）→ 拒绝整个 join（响亮失败，非脏 merge）
+                if (Object.values(childState.step_states).some(s => s === 'running')) {
+                    blockedChild = childId;
+                    break;
+                }
+                const childVars = flattenVars(readVars(childDir));
+                // 子实例含 failed 顶层步骤即视为失败（沿用底层 parallel child fail 语义）
+                const failed = Object.values(childState.step_states).some(s => s === 'failed');
+                // log = 该 child 子 hoplog run 目录（join 块记录子日志定位线索，见 ^anc-obs-parallel-dispatch）
+                childResults[childId] = { vars: childVars, failed, log: childState.hoplog_run_dir };
+            }
+            catch {
+                // ③ 单 child 文件损坏/读失败（CORRUPT_STATE_FILE 等）→ 标 failed（聚合写 None），不连累其余
+                childResults[childId] = { vars: {}, failed: true };
+            }
+        }
+        if (blockedChild) {
+            errorExit(`INVALID_STATE: parallel child '${blockedChild}' 未终态或子实例缺失，不能 join——请等所有 worker 返回后再 join`);
+            return;
+        }
+        const writeResult = engine.joinParallel(parallelStepId, childResults);
+        if (writeResult.status !== 'ok') {
+            output(writeResult);
+            return;
+        }
+        const next = await engine.advanceToCaller();
+        output(next);
+    }
+    catch (err) {
+        errorExit(err instanceof Error ? err.message : String(err));
+    }
+});
+// fanout-plan：parallel_ready 后主 agent 调一次，拿初始批 worker 启动命令。CLI 无状态算调度、原子标 dispatched。
+// 见 design/parallel-execution.md ^anc-exec-parallel-fanout-advisor。// @a: anc-exec-parallel-fanout-advisor
+program.command('fanout-plan <parallel-step-id>')
+    .description('fan-out 调度顾问：返回初始批 worker 的完整启动命令（主 agent 起 subagent 执行，不自己拼命令）')
+    .option('--instance <id>', 'Instance ID')
+    .option('--state-dir <dir>', 'State directory', '.hopstate')
+    .action((parallelStepId, opts) => {
+    try {
+        const instanceDir = resolveInstance(opts.stateDir, opts.instance);
+        const engine = ExecutionEngine.load(instanceDir);
+        output(engine.fanoutSchedule(parallelStepId));
+    }
+    catch (err) {
+        errorExit(err instanceof Error ? err.message : String(err));
+    }
+});
+// fanout-next：主 agent 每收一个 worker 完成通知即调，拿下一动作（补位 launch / join / wait）。
+// --done/--status 标识哪个 child 完成及成败；计算本身 level-triggered 读全量子实例状态复原窗口。
+// 见 design/parallel-execution.md ^anc-exec-parallel-fanout-advisor / ^anc-exec-parallel-fanout-concurrency。// @a: anc-exec-parallel-fanout-advisor
+program.command('fanout-next <parallel-step-id>')
+    .description('fan-out 调度顾问：worker 完成后返回下一动作（launch 补位 / join 收敛 / wait 等待）')
+    .option('--done <child-step-id>', 'Completed child step ID (from notification label)')
+    .option('--status <status>', 'Completed child status: completed | failed', 'completed')
+    .option('--instance <id>', 'Instance ID')
+    .option('--state-dir <dir>', 'State directory', '.hopstate')
+    .action((parallelStepId, opts) => {
+    try {
+        const instanceDir = resolveInstance(opts.stateDir, opts.instance);
+        const engine = ExecutionEngine.load(instanceDir);
+        output(engine.fanoutSchedule(parallelStepId));
+    }
+    catch (err) {
+        errorExit(err instanceof Error ? err.message : String(err));
+    }
+});
+// debug_step：调试用——纯推进一步、不消化纯计算 body、不自动 advance。正常驱动用 run + submit_and_fetch_next。
+program.command('debug_step')
+    .description('[DEBUG] Advance exactly one step (no body consumption, no auto-advance). Normal driving uses run + submit_and_fetch_next')
+    .option('--instance <id>', 'Instance ID')
+    .option('--state-dir <dir>', 'State directory', '.hopstate')
+    .action((opts) => {
+    try {
+        const instanceDir = resolveInstance(opts.stateDir, opts.instance);
+        const engine = ExecutionEngine.load(instanceDir);
+        const result = engine.nextStep();
+        output(result);
+    }
+    catch (err) {
+        errorExit(err instanceof Error ? err.message : String(err));
+    }
+});
+program.command('status')
+    .description('Get execution status')
+    .option('--instance <id>', 'Instance ID')
+    .option('--state-dir <dir>', 'State directory', '.hopstate')
+    .action((opts) => {
+    try {
+        const instanceDir = resolveInstance(opts.stateDir, opts.instance);
+        const engine = ExecutionEngine.load(instanceDir);
+        const result = engine.getStatus();
+        output(result);
+    }
+    catch (err) {
+        errorExit(err instanceof Error ? err.message : String(err));
+    }
+});
+program.command('vars')
+    .description('Get all variable values')
+    .option('--instance <id>', 'Instance ID')
+    .option('--state-dir <dir>', 'State directory', '.hopstate')
+    .action((opts) => {
+    try {
+        const instanceDir = resolveInstance(opts.stateDir, opts.instance);
+        const engine = ExecutionEngine.load(instanceDir);
+        const result = engine.getVars();
+        output(result);
+    }
+    catch (err) {
+        errorExit(err instanceof Error ? err.message : String(err));
+    }
+});
+program.command('resume')
+    .description('Resume execution from crash or pause (recover + advance to next caller-action point)')
+    .option('--instance <id>', 'Instance ID')
+    .option('--state-dir <dir>', 'State directory', '.hopstate')
+    .action(async (opts) => {
+    try {
+        const instanceDir = resolveInstance(opts.stateDir, opts.instance);
+        const engine = ExecutionEngine.recover(instanceDir); // 崩溃恢复：重置悬空 running，落盘
+        const result = await engine.advanceToCaller(); // 推进到下一个 caller 介入点
+        output(result);
+    }
+    catch (err) {
+        errorExit(err instanceof Error ? err.message : String(err));
+    }
+});
+// install-skill：把包内 driver/ 的 skill 源展开到 .claude/skills/（CC）或指定目录。
+// 纯文件拷贝、不涉引擎状态。包根用 import.meta.url 定位（不依赖 cwd）。见 design/hop-cli.md ^anc-cli-install-skill。
+// @a: anc-cli-install-skill
+program.command('install-skill')
+    .description('Install hopspec driver skills into .claude/skills/ (or --dir) from the package driver/ sources')
+    .option('--dir <target>', 'Target skills directory', '.claude/skills')
+    .option('--carrier <carrier>', 'Driver carrier: cc | codex', 'cc')
+    .option('--force', 'Overwrite existing files')
+    .action((opts) => {
+    try {
+        // 包根 = cli.js（dist/cli.js）的 dist 的上一级
+        const pkgRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+        const driverDir = join(pkgRoot, 'driver');
+        if (!existsSync(driverDir)) {
+            errorExit(`INSTALL_SKILL_ERROR: 包内未找到 driver/（${driverDir}）——确认包完整安装`);
+            return;
+        }
+        const target = isAbsolute(opts.dir) ? opts.dir : resolve(process.cwd(), opts.dir);
+        const installed = [];
+        const force = opts.force === true;
+        // 拷贝 helper：目标存在且非 force → 跳过并记录
+        const copyFile = (src, dst) => {
+            if (existsSync(dst) && !force)
+                return false;
+            mkdirSync(dirname(dst), { recursive: true });
+            copyFileSync(src, dst);
+            return true;
+        };
+        const copyDir = (src, dst) => {
+            if (existsSync(dst) && !force)
+                return false;
+            mkdirSync(dirname(dst), { recursive: true });
+            cpSync(src, dst, { recursive: true });
+            return true;
+        };
+        if (opts.carrier === 'codex') {
+            // Codex 载体：AGENTS.md + references
+            const agents = join(driverDir, 'codex', 'AGENTS.md');
+            if (copyFile(agents, join(target, 'AGENTS.md')))
+                installed.push(join(target, 'AGENTS.md'));
+            if (copyDir(join(driverDir, 'references'), join(target, 'references')))
+                installed.push(join(target, 'references/'));
+        }
+        else {
+            // CC 载体（默认）：hopspec-skill.md → hopspec/SKILL.md + references + hopskill-build/
+            if (copyFile(join(driverDir, 'hopspec-skill.md'), join(target, 'hopspec', 'SKILL.md')))
+                installed.push(join(target, 'hopspec/SKILL.md'));
+            if (copyDir(join(driverDir, 'references'), join(target, 'hopspec', 'references')))
+                installed.push(join(target, 'hopspec/references/'));
+            if (copyDir(join(driverDir, 'hopskill-build'), join(target, 'hopskill-build')))
+                installed.push(join(target, 'hopskill-build/'));
+        }
+        const skipped = installed.length === 0;
+        output({
+            status: 'ok',
+            carrier: opts.carrier,
+            target,
+            installed,
+            ...(skipped ? { note: '无文件写入（目标已存在，用 --force 覆盖）' } : {}),
+        });
+    }
+    catch (err) {
+        errorExit(err instanceof Error ? err.message : String(err));
+    }
+});
+export { program };
+const isMain = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+    program.parseAsync(process.argv).catch(err => {
+        errorExit(err instanceof Error ? err.message : String(err));
+    });
+}