@deksden-com/dd-flow-cli 0.7.0 → 0.8.0-beta.135

package/dist/cli/run-cli.js

@@ -1,4 +1,5 @@
 import fs from "node:fs";
+import path from "node:path";
 import { createContext, createRouterContext } from "../runtime/context.js";
 import { helpForArgs } from "./help.js";
 import { AppError, isAppError } from "../shared/errors.js";
@@ -9,7 +10,7 @@ import { blockPlanItem, completePlanItem, getPlanStatus, skipPlanItem, startPlan
 import { cancelMergeQueueJob, claimNextMergeJob, claimMergeJob, claimMergeBundle, completeMergeBundle, completeMergeJob, failMergeBundle, failMergeJob, getMergeBundleStatus, getMergeQueueStatus, noteMergeJob, waitNextMergeJob } from "../services/merge-queue.js";
 import { getMergeWorkerStatus, oneShotMergeClaim, startMergeWorker, stopProjectMergeWorker } from "../services/merge-worker.js";
 import { cleanupApply, cleanupScan } from "../services/cleanup.js";
-import { getCodexHomeStatus, getCodexHooksStatus, handleCodexHook, initCodexHome, installCodexHooks, planCodexHome, printCodexHomeEnv, printCodexHooks, removeCodexHome, removeCodexHooks } from "../services/hooks.js";
+import { getCodexHomeStatus, getCodexHooksStatus, handleCodexHook, handleAgyEvent, handleGrokEvent, handleOpenCodeEvent, handleZcodeEvent, isolatedDdFlowHomeFromHookStdin, claimBootstrapHookEvent, findRecentMatchingHookEvent, stageStartMatchKey, initCodexHome, installCodexHooks, planCodexHome, printCodexHomeEnv, printCodexHooks, removeCodexHome, removeCodexHooks } from "../services/hooks.js";
 import { bootstrapWorktree, closeWorktree, createWorktreeRecord, getWorktreeStatus, planWorktree } from "../services/worktrees.js";
 import { acquireLaneLock, cancelLaneWaiter, checkLaneWorkspace, getLaneWaiters, getLaneStatus, heartbeatLaneLock, releaseLaneLock, setLaneWorkspace, waitAcquireLaneLock, waitForLaneLock } from "../services/lanes.js";
 import { getProjectConfigStatus, setProjectConfigValue } from "../services/config.js";
@@ -20,19 +21,32 @@ import { autoRefreshDashboards, dashboardData, getCmuxStatus, openDashboard, ope
 import { dashboardTargetSummary, preferredDashboardCommand, relatedDashboardCommands, resolveDashboardTarget } from "../services/dashboard-targets.js";
 import { getFlowSessionStatus, registerFlowSession, stopFlowSession, stopMergeWorker, syncFlowSessionUsage } from "../services/sessions.js";
 import { getProtocolBranchContext } from "../services/branch-context.js";
-import { attachFlowRunStage, completeFlowRun, completeFlowRunStage, getFlowRunTimeline, getFlowRunUsage, getFlowRunFlagsStatus, getFlowRunStatus, listFlowRuns, reviseFlowRunFlags, startFlowRun } from "../services/runs.js";
+import { attachFlowRunStage, completeFlowRun, completeFlowRunStage, getFlowRunSessions, getFlowRunTimeline, getStoredFlowRunUsage, getFlowRunFlagsStatus, getFlowRunStatus, getFlowRunConfig, getFlowRunVariables, listFlowRuns, reviseFlowRunFlags, setFlowRunConfig, setFlowRunVariable, startFlowRun } from "../services/runs.js";
 import { previewNextEntityId } from "../services/ids.js";
 import { validateSchema } from "../services/schema-validation.js";
 import { preflightMemoryPermissions } from "../services/memory-permissions.js";
+import { ingestAgyUsage, ingestGrokUsage, ingestOpenCodeUsage, ingestZcodeUsage } from "../services/usage.js";
 import { applyMigration, assessMigrationImpact, assertUpgradeRunStorageReady, planMigration, verifyMigrationReport } from "../services/migrations.js";
 import { publishProjectSummary } from "../services/project-summary.js";
 import { requireProjectByRoot } from "../services/projects.js";
 import { resolveProjectRoot } from "../storage/paths.js";
 import { doctorEngines, bindRunEngine, engineInfo, installCurrentEngine, listEngines, resolveEngine, resolveExplicitProjectRoot, resolveOperationProjectRoot, routeArgsThroughEngine } from "../services/engines.js";
 import { preflightCliCompatibility } from "../services/compatibility-preflight.js";
+import { finishVnextSpecifyStage, getVnextWorkStatus, isVnextSpecifyFlow, isVnextSpecifyRun, launchVnextSpecify } from "../services/vnext-specify.js";
+import { finishVnextProtocolize, isVnextProtocolizeRun, startVnextProtocolize } from "../services/vnext-protocolize.js";
+import { finishVnextPlan, isVnextPlanRun, startVnextPlan } from "../services/vnext-plan.js";
+import { dispatchVnextPlanReview, finishVnextPlanReview, isVnextPlanReviewRun, recordVnextPlanReviewCapacity, startVnextPlanReview } from "../services/vnext-plan-review.js";
+import { addVnextCodeRepair, finishVnextCode, startVnextCode } from "../services/vnext-code.js";
+import { addVnextCodeReviewRepair, finishVnextCodeReview, isVnextCodeReviewRun, startVnextCodeReview } from "../services/vnext-code-review.js";
+import { getVnextFanoutStatus } from "../services/vnext-fanout.js";
+import { pauseStageForUser, resumeStageAfterUser } from "../services/stage-pause.js";
+import { blockStageForRuntime, unblockStageAfterRuntimeRepair } from "../services/stage-blocker.js";
 import { classifyCliOperation, requiresExplicitUpgradeAuthorization } from "../services/cli-operation-classifier.js";
 import { renderWorkerPrompt } from "../services/prompts.js";
 import { finishStage, startStage } from "../services/stage-lifecycle.js";
+import { addWorkBatch, cancelWork, deleteWork, failWork, finishWork, listWorks, mutateWorkDeps, retryWork, showWork, startWork } from "../services/work-registry.js";
+import { createEvalBootstrapSnapshot, createEvalRunSnapshot, prepareVnextSpecifyRun, restoreEvalBootstrapSnapshot, restoreEvalRunSnapshot } from "../services/eval-snapshots.js";
+import { loadExternalStageContext } from "../services/stage-context.js";
 const defaultIo = {
     stdout: process.stdout,
     stderr: process.stderr,
@@ -42,10 +56,8 @@ const flagValue = "__dd_flow_flag__";
 export async function runCli(args, io = defaultIo, env = process.env) {
     const output = parseOutputOptions(args);
     const progress = progressForCommand(output.args);
+    let heartbeat;
     try {
-        if (args.includes("--progress-jsonl")) {
-            throw new AppError("usage", "--progress-jsonl is not implemented yet; use --json for final structured progress", 2);
-        }
         if (output.args.length === 1 && output.args[0] === "--version") {
             const payload = getCliVersionReport();
             if (output.json)
@@ -68,9 +80,15 @@ export async function runCli(args, io = defaultIo, env = process.env) {
         }
         const routerContext = createRouterContext(env);
         emitHumanProgress(io, output, progress, "start");
+        if (output.progressJsonl) {
+            writeProgressJsonl(io, "start", `Starting ${output.args.slice(0, 3).join(" ")}`);
+            heartbeat = setInterval(() => writeProgressJsonl(io, "running", "Command is still running"), 15_000);
+        }
         const scopeProjectRoot = resolveProjectRootBeforeRouting(output.args, env);
-        const routed = await routeArgsThroughEngine(routerContext, output.json ? [...output.args, "--json"] : output.args, io, io.stdin, env, scopeProjectRoot);
+        const routed = await routeArgsThroughEngine(routerContext, output.json ? [...output.args, "--json", ...(output.progressJsonl ? ["--progress-jsonl"] : [])] : output.args, io, io.stdin, env, scopeProjectRoot);
         if (routed?.routed && !routed.inProcess) {
+            if (heartbeat)
+                clearInterval(heartbeat);
             emitHumanProgress(io, output, progress, "done");
             return routed.exitCode;
         }
@@ -78,9 +96,13 @@ export async function runCli(args, io = defaultIo, env = process.env) {
             ? createContext({ ...env, DD_FLOW_ENGINE_MODE: "1", DD_FLOW_ENGINE_HOME: "in-process", DD_FLOW_ROUTED_FROM: getCliVersionReport().cli.version }, databaseModeForCommand(output.args, classification))
             : createContext(env, databaseModeForCommand(output.args, classification));
         preflightCliCompatibility(dispatchContext, output.args, env, scopeProjectRoot);
-        const result = await dispatch(output.args, dispatchContext, io, scopeProjectRoot, classification);
+        const result = await dispatch(output.args, dispatchContext, io, scopeProjectRoot, classification, output);
         const refreshWarnings = refreshDashboardsAfterMutation(dispatchContext, output.args, result, scopeProjectRoot);
         const resultWithWarnings = addWarnings(result, refreshWarnings);
+        if (heartbeat)
+            clearInterval(heartbeat);
+        if (output.progressJsonl)
+            writeProgressJsonl(io, "done", "Command finished");
         emitHumanProgress(io, output, progress, "done");
         const payload = attachProgress(resultWithWarnings, progress, output);
         if (output.json)
@@ -90,12 +112,18 @@ export async function runCli(args, io = defaultIo, env = process.env) {
         return completedCommandExitCode(payload);
     }
     catch (error) {
+        if (heartbeat)
+            clearInterval(heartbeat);
         const payload = isAppError(error)
             ? { ok: false, error: { code: error.code, message: error.message, details: error.details } }
             : { ok: false, error: { code: "unexpected", message: String(error) } };
         emitHumanProgress(io, output, progress, "failed");
+        if (output.progressJsonl)
+            writeProgressJsonl(io, "failed", payload.error.message, { code: payload.error.code });
         const errorPayload = attachProgress(payload, progress, output);
-        if (output.json)
+        if (output.json && output.progressJsonl)
+            writeJson(io.stdout, errorPayload);
+        else if (output.json)
             writeJson(io.stderr, errorPayload);
         else
             io.stderr.write(renderHumanError(payload));
@@ -157,15 +185,20 @@ function renderHumanError(payload) {
 function parseOutputOptions(args) {
     const stripped = [];
     let json = false;
+    let progressJsonl = false;
     for (const arg of args) {
         if (arg === "--json") {
             json = true;
             continue;
         }
+        if (arg === "--progress-jsonl") {
+            progressJsonl = true;
+            continue;
+        }
         stripped.push(arg);
     }
     const hookJsonOnly = stripped[0] === "codex" && stripped[1] === "hook" && stripped[2] === "handle";
-    return { json: json || hookJsonOnly, args: stripped, hookJsonOnly };
+    return { json: json || hookJsonOnly, progressJsonl, args: stripped, hookJsonOnly };
 }
 function progressForCommand(args) {
     const [family, command, subcommand] = args;
@@ -211,6 +244,12 @@ function emitHumanProgress(io, output, progress, phase) {
         }
     }
 }
+function writeProgressJsonl(io, phase, message, detail) {
+    io.stderr.write(`${JSON.stringify({ schema_id: "dd-flow/progress@1", phase, message, at: new Date().toISOString(), ...(detail ? { detail } : {}) })}\n`);
+}
+function commandProgress(io, output) {
+    return (message) => output.progressJsonl ? writeProgressJsonl(io, "running", message) : io.stderr.write(`[running] ${message}\n`);
+}
 function attachProgress(result, progress, output) {
     if (progress.length === 0 || output.hookJsonOnly)
         return result;
@@ -416,7 +455,7 @@ function stringValue(value) {
 function shortSha(value) {
     return value ? value.slice(0, 12) : "unknown";
 }
-async function dispatch(args, context, io, scopeProjectRoot = null, classification = classifyCliOperation(args, context.env)) {
+async function dispatch(args, context, io, scopeProjectRoot = null, classification = classifyCliOperation(args, context.env), output = parseOutputOptions(args)) {
     const [family, command, ...rest] = args;
     const parsed = parseArgs(rest);
     if (family === "engine") {
@@ -560,6 +599,32 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
         const protocolId = requiredPosition(parsed, 0, "protocol-id");
         return getPlanStatus(context, { protocolId, projectRoot: requiredScopeProjectRoot(scopeProjectRoot, "plan status") });
     }
+    if (family === "plan" && command === "reviews") {
+        throw new AppError("usage", "PLAN review dispatch moved to: dd-flow plan-review dispatch <RUN>", 2);
+    }
+    if (family === "plan-review" && command === "dispatch") {
+        return dispatchVnextPlanReview(context, { projectRoot: requiredScopeProjectRoot(scopeProjectRoot, "plan-review dispatch"), runId: requiredPosition(parsed, 0, "run-id") });
+    }
+    if (family === "stage" && command === "fanout") {
+        const action = requiredPosition(parsed, 0, "fanout action");
+        const runId = requiredPosition(parsed, 1, "run-id");
+        const stage = requiredOption(parsed, "stage");
+        const projectRoot = requiredScopeProjectRoot(scopeProjectRoot, "stage fanout");
+        if (action === "status")
+            return getVnextFanoutStatus(context, { projectRoot, runId, stage });
+        if (action === "dispatch") {
+            if (stage === "plan-review")
+                return dispatchVnextPlanReview(context, { projectRoot, runId });
+            return getVnextFanoutStatus(context, { projectRoot, runId, stage });
+        }
+        throw new AppError("usage", "Use: dd-flow stage fanout <status|dispatch> <RUN> --stage <stage> --project-root <path>", 2);
+    }
+    if (family === "run" && command === "capacity") {
+        if (requiredPosition(parsed, 0, "capacity action") !== "record")
+            throw new AppError("usage", "Use: dd-flow run capacity record <RUN> --available-slots <0..15> --project-root <path>", 2);
+        const availableSlots = Number(requiredOption(parsed, "available-slots"));
+        return recordVnextPlanReviewCapacity(context, { projectRoot: requiredScopeProjectRoot(scopeProjectRoot, "run capacity record"), runId: requiredPosition(parsed, 1, "run-id"), availableSlots });
+    }
     if (family === "plan" && command === "item") {
         return dispatchPlanItem(context, parsed, requiredScopeProjectRoot(scopeProjectRoot, "plan item"));
     }
@@ -575,31 +640,279 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
             ...(workspaceRoot ? { workspaceRoot } : {})
         });
     }
+    if (family === "work" && command === "status") {
+        return getVnextWorkStatus(context, {
+            projectRoot: requiredOption(parsed, "project-root"),
+            workId: requiredPosition(parsed, 0, "work-id")
+        });
+    }
+    if (family === "work" && command === "add-batch") {
+        return addWorkBatch(context, { parentWorkId: requiredOption(parsed, "parent"), file: requiredOption(parsed, "file") });
+    }
+    if (family === "work" && command === "ls") {
+        return listWorks(context, { ...(optionalOption(parsed, "run") ? { runId: optionalOption(parsed, "run") } : {}), ...(optionalOption(parsed, "parent") ? { parentWorkId: optionalOption(parsed, "parent") } : {}), ...(optionalOption(parsed, "status") ? { status: optionalOption(parsed, "status") } : {}), ...(hasOption(parsed, "ready") ? { ready: true } : {}), ...(hasOption(parsed, "include-results") ? { includeResults: true } : {}), ...(optionalOption(parsed, "limit") ? { limit: Number(optionalOption(parsed, "limit")) } : {}) });
+    }
+    if (family === "work" && command === "show")
+        return showWork(context, requiredPosition(parsed, 0, "work-id"));
+    if (family === "work" && command === "repair" && requiredPosition(parsed, 0, "action") === "add") {
+        if (!hasOption(parsed, "task-stdin"))
+            throw new AppError("usage", "work repair add requires --task-stdin", 2);
+        const origins = parsed.options.get("origin-work") ?? [];
+        const findings = parsed.options.get("from-finding") ?? [];
+        if (!origins.length && !findings.length)
+            throw new AppError("usage", "work repair add requires --from-check with --origin-work or --from-finding", 2);
+        if (findings.length)
+            return addVnextCodeReviewRepair(context, {
+                projectRoot: requiredScopeProjectRoot(scopeProjectRoot, "work repair add"),
+                runId: requiredOption(parsed, "run"),
+                findingIds: findings,
+                writeScope: parsed.options.get("write-scope") ?? [],
+                objective: await readStdin(io.stdin)
+            });
+        if (!hasOption(parsed, "from-check"))
+            throw new AppError("usage", "check repair requires --from-check", 2);
+        if (!origins.length)
+            throw new AppError("usage", "check repair requires at least one --origin-work", 2);
+        return addVnextCodeRepair(context, {
+            projectRoot: requiredScopeProjectRoot(scopeProjectRoot, "work repair add"),
+            runId: requiredOption(parsed, "run"),
+            checkReceiptId: requiredOption(parsed, "from-check"),
+            originWorkIds: origins,
+            writeScope: parsed.options.get("write-scope") ?? [],
+            objective: await readStdin(io.stdin)
+        });
+    }
+    if (family === "work" && command === "deps") {
+        const on = parsed.options.get("on") ?? [];
+        return mutateWorkDeps(context, { workId: requiredPosition(parsed, 1, "work-id"), action: requiredPosition(parsed, 0, "action"), ...(on.length ? { on } : {}) });
+    }
+    if (family === "work" && command === "delete")
+        return deleteWork(context, requiredPosition(parsed, 0, "work-id"));
+    if (family === "work" && command === "start") {
+        const hookEventId = optionalOption(parsed, "hook-event-id");
+        const projectRoot = requiredScopeProjectRoot(scopeProjectRoot, "work start");
+        return startWork(context, requiredPosition(parsed, 0, "work-id"), { ...(hookEventId ? { hookEventId } : {}), projectRoot });
+    }
+    if (family === "work" && command === "finish") {
+        const resultFile = optionalOption(parsed, "result-file");
+        const resultStdin = hasOption(parsed, "result-stdin");
+        if (Boolean(resultFile) === resultStdin)
+            throw new AppError("usage", "work finish requires exactly one of --result-file or --result-stdin", 2);
+        const result = resultFile ? fs.readFileSync(path.resolve(resultFile), "utf8") : await readStdin(io.stdin);
+        return await finishWork(context, requiredPosition(parsed, 0, "work-id"), result, commandProgress(io, output));
+    }
+    if (family === "work" && command === "fail")
+        return failWork(context, requiredPosition(parsed, 0, "work-id"), requiredOption(parsed, "reason"));
+    if (family === "work" && command === "cancel")
+        return cancelWork(context, requiredPosition(parsed, 0, "work-id"), requiredOption(parsed, "reason"));
+    if (family === "work" && command === "retry")
+        return retryWork(context, requiredPosition(parsed, 0, "work-id"), requiredOption(parsed, "reason"));
     if (family === "stage" && command === "start") {
         const dir = optionalOption(parsed, "dir");
         const bootstrap = hasOption(parsed, "bootstrap");
         const subject = optionalOption(parsed, "subject");
         const intakeFile = optionalOption(parsed, "intake-file");
-        const sessionId = optionalOption(parsed, "session-id");
+        const intakeStdin = hasOption(parsed, "intake-stdin");
+        const contextFile = optionalOption(parsed, "context-file");
+        const contextSha256 = optionalOption(parsed, "context-sha256");
+        if (Boolean(contextFile) !== Boolean(contextSha256))
+            throw new AppError("usage", "stage start requires --context-file together with --context-sha256", 2);
+        if (hasOption(parsed, "session-id")) {
+            throw new AppError("usage", "--session-id is managed by the harness lifecycle adapter and is not accepted", 2);
+        }
+        let hookEventId = optionalOption(parsed, "hook-event-id");
+        const requireSessionBinding = hasOption(parsed, "require-session-binding");
+        const projectRoot = requiredOption(parsed, "project-root");
+        const stage = requiredOption(parsed, "stage");
+        const externalContext = contextFile && contextSha256 ? loadExternalStageContext({ file: contextFile, expectedSha256: contextSha256, stage }) : undefined;
+        const claimVnextStageStart = (runId) => {
+            registerProject(context, { root: projectRoot });
+            return findRecentMatchingHookEvent(context, {
+                projectId: requireProjectByRoot(context, resolveProjectRoot(projectRoot)).id,
+                matchKey: stageStartMatchKey(runId, stage, projectRoot, contextSha256),
+                errorCode: "trusted_session_binding_required",
+                operation: `vNext ${stage.toUpperCase()} start`
+            }).eventKey;
+        };
+        if ((bootstrap || (!bootstrap && stage === "specify" && isVnextSpecifyRun(context, { projectRoot, runId: requiredPosition(parsed, 0, "run-id") }))) && stage === "specify" && isVnextSpecifyFlow(projectRoot)) {
+            if ((intakeFile && intakeStdin) || (externalContext && (intakeFile || intakeStdin))) {
+                throw new AppError("usage", "Use exactly one of --intake-file or --intake-stdin", 2);
+            }
+            if (!intakeFile && !intakeStdin && !externalContext) {
+                throw new AppError("usage", "vNext SPECIFY start requires --intake-file, --intake-stdin or a runner context", 2);
+            }
+            if (!hookEventId) {
+                registerProject(context, { root: projectRoot });
+                hookEventId = bootstrap
+                    ? claimBootstrapHookEvent(context, {
+                        projectId: requireProjectByRoot(context, resolveProjectRoot(projectRoot)).id,
+                        projectRoot,
+                        subject: subject ?? "specify",
+                        intakeMode: externalContext ? "context" : intakeStdin ? "stdin" : "file",
+                        ...(contextSha256 ? { contextSha256 } : {})
+                    })
+                    : claimVnextStageStart(requiredPosition(parsed, 0, "run-id"));
+            }
+            const result = launchVnextSpecify(context, {
+                projectRoot,
+                ...(externalContext ? { intakeMarkdown: runnerIntake(externalContext) } : intakeFile ? { intakeFile } : { intakeMarkdown: await readStdin(io.stdin) }),
+                hookEventId,
+                ...(subject ? { slug: subject } : {}),
+                ...(externalContext ? { externalContext } : {}),
+                ...(!bootstrap ? { runId: requiredPosition(parsed, 0, "run-id") } : {})
+            });
+            return attachExternalStageContext(result, externalContext);
+        }
+        if (!bootstrap && stage === "protocolize" && isVnextProtocolizeRun(context, { projectRoot, runId: requiredPosition(parsed, 0, "run-id") })) {
+            hookEventId ??= claimVnextStageStart(requiredPosition(parsed, 0, "run-id"));
+            return attachExternalStageContext(startVnextProtocolize(context, { projectRoot, runId: requiredPosition(parsed, 0, "run-id"), hookEventId, ...(contextSha256 ? { contextSha256 } : {}), ...(externalContext ? { externalContext } : {}) }), externalContext);
+        }
+        if (!bootstrap && stage === "plan" && isVnextPlanRun(context, { projectRoot, runId: requiredPosition(parsed, 0, "run-id") })) {
+            hookEventId ??= claimVnextStageStart(requiredPosition(parsed, 0, "run-id"));
+            return attachExternalStageContext(startVnextPlan(context, { projectRoot, runId: requiredPosition(parsed, 0, "run-id"), hookEventId, ...(contextSha256 ? { contextSha256 } : {}), ...(externalContext ? { externalContext } : {}) }), externalContext);
+        }
+        if (!bootstrap && stage === "plan-review" && isVnextPlanReviewRun(context, { projectRoot, runId: requiredPosition(parsed, 0, "run-id") })) {
+            hookEventId ??= claimVnextStageStart(requiredPosition(parsed, 0, "run-id"));
+            return attachExternalStageContext(startVnextPlanReview(context, { projectRoot, runId: requiredPosition(parsed, 0, "run-id"), hookEventId, ...(contextSha256 ? { contextSha256 } : {}), ...(externalContext ? { externalContext } : {}) }), externalContext);
+        }
+        if (!bootstrap && stage === "code" && isVnextPlanRun(context, { projectRoot, runId: requiredPosition(parsed, 0, "run-id") })) {
+            hookEventId ??= claimVnextStageStart(requiredPosition(parsed, 0, "run-id"));
+            return attachExternalStageContext(await startVnextCode(context, { projectRoot, runId: requiredPosition(parsed, 0, "run-id"), hookEventId, progress: commandProgress(io, output), ...(contextSha256 ? { contextSha256 } : {}), ...(externalContext ? { externalContext } : {}) }), externalContext);
+        }
+        if (!bootstrap && stage === "code-review" && isVnextCodeReviewRun(context, { projectRoot, runId: requiredPosition(parsed, 0, "run-id") })) {
+            hookEventId ??= claimVnextStageStart(requiredPosition(parsed, 0, "run-id"));
+            return attachExternalStageContext(startVnextCodeReview(context, { projectRoot, runId: requiredPosition(parsed, 0, "run-id"), hookEventId, ...(contextSha256 ? { contextSha256 } : {}), ...(externalContext ? { externalContext } : {}) }), externalContext);
+        }
+        if (intakeStdin) {
+            throw new AppError("usage", "--intake-stdin is only available for vNext SPECIFY", 2);
+        }
+        if (externalContext) {
+            throw new AppError("usage", "--context-file is currently supported only by vNext flow stages", 2);
+        }
         return startStage(context, {
-            projectRoot: requiredOption(parsed, "project-root"),
+            projectRoot,
             ...(bootstrap ? { bootstrap: { subject: subject ?? requiredOption(parsed, "subject"), ...(intakeFile ? { intakeFile } : {}) } } : { runId: requiredPosition(parsed, 0, "run-id") }),
-            stage: requiredOption(parsed, "stage"),
-            ...(sessionId ? { sessionId } : {}),
+            stage,
+            ...(hookEventId ? { hookEventId } : {}),
+            ...(requireSessionBinding ? { requireSessionBinding: true } : {}),
             ...(dir ? { dir } : {})
         });
     }
     if (family === "stage" && command === "finish") {
         const dir = optionalOption(parsed, "dir");
-        const outcome = optionalOption(parsed, "outcome") ?? optionalOption(parsed, "status");
+        if (hasOption(parsed, "status")) {
+            throw new AppError("usage", "Stage status belongs in the semantic input file", 2);
+        }
+        const projectRoot = requiredOption(parsed, "project-root");
+        const runId = requiredPosition(parsed, 0, "run-id");
+        const stage = requiredOption(parsed, "stage");
         const semanticFile = optionalOption(parsed, "semantic-file") ?? optionalOption(parsed, "data");
+        const resultFile = optionalOption(parsed, "result-file") ?? semanticFile;
+        const resultStdin = hasOption(parsed, "result-stdin");
+        if (stage === "specify" && isVnextSpecifyRun(context, { projectRoot, runId })) {
+            const outcome = optionalOption(parsed, "outcome");
+            if (!outcome || !["specified", "failed", "cancelled"].includes(outcome)) {
+                throw new AppError("usage", "vNext SPECIFY requires --outcome specified|failed|cancelled; use stage pause for a user question", 2);
+            }
+            if (resultFile && resultStdin) {
+                throw new AppError("usage", "Use exactly one of --result-file or --result-stdin", 2);
+            }
+            if (!resultFile && !resultStdin) {
+                throw new AppError("usage", "vNext SPECIFY finish requires --result-file or --result-stdin", 2);
+            }
+            return finishVnextSpecifyStage(context, {
+                projectRoot,
+                runId,
+                ...(resultFile ? { resultFile } : { resultJson: await readStdin(io.stdin) }),
+                outcome: outcome
+            });
+        }
+        if (stage === "protocolize" && isVnextProtocolizeRun(context, { projectRoot, runId })) {
+            if (!resultFile || resultStdin || hasOption(parsed, "outcome")) {
+                throw new AppError("usage", "vNext PROTOCOLIZE requires exactly --result-file", 2);
+            }
+            return finishVnextProtocolize(context, { projectRoot, runId, resultFile });
+        }
+        if (stage === "plan" && isVnextPlanRun(context, { projectRoot, runId })) {
+            if (optionalOption(parsed, "code-work-batch-file"))
+                throw new AppError("usage", "vNext PLAN derives its CODE batch from accepted semantic plans; do not supply a batch file", 2);
+            return finishVnextPlan(context, { projectRoot, runId });
+        }
+        if (stage === "plan-review" && isVnextPlanReviewRun(context, { projectRoot, runId })) {
+            if (resultStdin || hasOption(parsed, "outcome"))
+                throw new AppError("usage", "vNext PLAN-REVIEW uses --decision-file", 2);
+            const decisionFile = optionalOption(parsed, "decision-file");
+            return finishVnextPlanReview(context, { projectRoot, runId, ...(decisionFile ? { decisionFile } : {}) });
+        }
+        if (stage === "code" && isVnextPlanRun(context, { projectRoot, runId })) {
+            if (semanticFile || resultFile || resultStdin || hasOption(parsed, "outcome")) {
+                throw new AppError("usage", "vNext CODE finish accepts only --verification-file", 2);
+            }
+            return await finishVnextCode(context, { projectRoot, runId, verificationFile: optionalOption(parsed, "verification-file") ?? path.join("<missing>", "code-verification.json"), progress: commandProgress(io, output) });
+        }
+        if (stage === "code-review" && isVnextCodeReviewRun(context, { projectRoot, runId })) {
+            if (resultStdin || semanticFile || resultFile || hasOption(parsed, "outcome"))
+                throw new AppError("usage", "vNext CODE-REVIEW uses --decision-file", 2);
+            return await finishVnextCodeReview(context, { projectRoot, runId, ...(optionalOption(parsed, "decision-file") ? { decisionFile: optionalOption(parsed, "decision-file") } : {}), progress: commandProgress(io, output) });
+        }
+        if (hasOption(parsed, "outcome") || hasOption(parsed, "result-file") || resultStdin) {
+            throw new AppError("usage", "--outcome, --result-file and --result-stdin are only available for vNext SPECIFY", 2);
+        }
         return finishStage(context, {
+            projectRoot,
+            runId,
+            stage,
+            ...(dir ? { dir } : {}),
+            ...(semanticFile ? { semanticFile } : {})
+        });
+    }
+    if (family === "stage" && command === "pause") {
+        if (!hasOption(parsed, "question-stdin"))
+            throw new AppError("usage", "stage pause requires --question-stdin", 2);
+        return pauseStageForUser(context, {
             projectRoot: requiredOption(parsed, "project-root"),
             runId: requiredPosition(parsed, 0, "run-id"),
             stage: requiredOption(parsed, "stage"),
-            ...(dir ? { dir } : {}),
-            ...(outcome ? { outcome } : {}),
-            ...(semanticFile ? { semanticFile } : {})
+            workId: requiredOption(parsed, "work"),
+            question: await readStdin(io.stdin)
+        });
+    }
+    if (family === "stage" && command === "resume") {
+        if (!hasOption(parsed, "answer-stdin"))
+            throw new AppError("usage", "stage resume requires --answer-stdin", 2);
+        const hookEventId = optionalOption(parsed, "hook-event-id");
+        return resumeStageAfterUser(context, {
+            projectRoot: requiredOption(parsed, "project-root"),
+            runId: requiredPosition(parsed, 0, "run-id"),
+            stage: requiredOption(parsed, "stage"),
+            workId: requiredOption(parsed, "work"),
+            answer: await readStdin(io.stdin),
+            ...(hookEventId ? { hookEventId } : {})
+        });
+    }
+    if (family === "stage" && command === "block") {
+        if (!hasOption(parsed, "summary-stdin"))
+            throw new AppError("usage", "stage block requires --summary-stdin", 2);
+        const kind = requiredOption(parsed, "kind");
+        if (kind !== "engine" && kind !== "harness" && kind !== "environment")
+            throw new AppError("usage", "--kind must be engine, harness or environment", 2);
+        return blockStageForRuntime(context, {
+            projectRoot: requiredOption(parsed, "project-root"),
+            runId: requiredPosition(parsed, 0, "run-id"),
+            stage: requiredOption(parsed, "stage"),
+            workId: requiredOption(parsed, "work"),
+            kind,
+            code: requiredOption(parsed, "code"),
+            summary: await readStdin(io.stdin),
+            retryable: hasOption(parsed, "retryable")
+        });
+    }
+    if (family === "stage" && command === "unblock") {
+        return unblockStageAfterRuntimeRepair(context, {
+            projectRoot: requiredOption(parsed, "project-root"),
+            runId: requiredPosition(parsed, 0, "run-id"),
+            stage: requiredOption(parsed, "stage"),
+            workId: requiredOption(parsed, "work")
         });
     }
     if (family === "lane") {
@@ -623,6 +936,9 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
     if (family === "run") {
         return dispatchRun(context, command, parsed);
     }
+    if (family === "stat") {
+        return dispatchStat(context, command, parsed);
+    }
     if (family === "id") {
         return dispatchId(context, command, parsed);
     }
@@ -650,6 +966,37 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
     if (family === "codex" && command === "hook") {
         return dispatchCodexHook(context, parsed, await readStdin(io.stdin));
     }
+    if (family === "zcode" && command === "event") {
+        return dispatchZcodeEvent(context, parsed, await readStdin(io.stdin));
+    }
+    if (family === "zcode" && command === "usage") {
+        if (requiredPosition(parsed, 0, "zcode usage action") !== "ingest")
+            throw new AppError("usage", "Unknown zcode usage action", 2);
+        return ingestZcodeUsage(context, { projectRoot: requiredOption(parsed, "project-root"), stdin: await readStdin(io.stdin) });
+    }
+    if (family === "grok" && command === "event") {
+        return dispatchGrokEvent(context, parsed, await readStdin(io.stdin));
+    }
+    if (family === "grok" && command === "usage") {
+        if (requiredPosition(parsed, 0, "grok usage action") !== "ingest")
+            throw new AppError("usage", "Unknown grok usage action", 2);
+        return ingestGrokUsage(context, { projectRoot: requiredOption(parsed, "project-root"), stdin: await readStdin(io.stdin) });
+    }
+    if (family === "opencode" && command === "event") {
+        return dispatchOpenCodeEvent(context, parsed, await readStdin(io.stdin));
+    }
+    if (family === "opencode" && command === "usage") {
+        if (requiredPosition(parsed, 0, "opencode usage action") !== "ingest")
+            throw new AppError("usage", "Unknown opencode usage action", 2);
+        return ingestOpenCodeUsage(context, { projectRoot: requiredOption(parsed, "project-root"), stdin: await readStdin(io.stdin) });
+    }
+    if (family === "agy" && command === "event")
+        return dispatchAgyEvent(context, parsed, await readStdin(io.stdin));
+    if (family === "agy" && command === "usage") {
+        if (requiredPosition(parsed, 0, "agy usage action") !== "ingest")
+            throw new AppError("usage", "Unknown agy usage action", 2);
+        return ingestAgyUsage(context, { projectRoot: requiredOption(parsed, "project-root"), stdin: await readStdin(io.stdin) });
+    }
     if (family === "worktree") {
         return dispatchWorktree(context, command, parsed, requiredScopeProjectRoot(scopeProjectRoot, `worktree ${command ?? ""}`));
     }
@@ -962,6 +1309,48 @@ function dispatchSession(context, command, parsed) {
     throw new AppError("usage", `Unknown session command: ${command ?? "<empty>"}`, 2);
 }
 function dispatchRun(context, command, parsed) {
+    if (command === "snapshot") {
+        const action = requiredPosition(parsed, 0, "snapshot action");
+        if (action === "bootstrap") {
+            const bootstrapAction = requiredPosition(parsed, 1, "bootstrap snapshot action");
+            if (bootstrapAction === "create")
+                return createEvalBootstrapSnapshot(context, {
+                    projectRoot: requiredOption(parsed, "project-root"),
+                    output: requiredOption(parsed, "output")
+                });
+            if (bootstrapAction === "restore")
+                return restoreEvalBootstrapSnapshot(context, {
+                    snapshot: requiredOption(parsed, "snapshot"),
+                    projectRoot: requiredOption(parsed, "project-root")
+                });
+            throw new AppError("usage", "Use: dd-flow run snapshot bootstrap create|restore", 2);
+        }
+        if (action === "create") {
+            const candidate = parsed.options.has("candidate");
+            const stageEntry = optionalOption(parsed, "stage-entry");
+            if (candidate && stageEntry !== undefined)
+                throw new AppError("usage", "Use either --candidate or --stage-entry, not both", 2);
+            if (!candidate && stageEntry === undefined)
+                throw new AppError("usage", "Snapshot create requires --candidate or --stage-entry", 2);
+            const input = {
+                projectRoot: requiredOption(parsed, "project-root"),
+                runId: requiredPosition(parsed, 1, "run-id"),
+                output: requiredOption(parsed, "output")
+            };
+            return candidate
+                ? createEvalRunSnapshot(context, { ...input, candidate: true })
+                : createEvalRunSnapshot(context, { ...input, stageEntry: stageEntry });
+        }
+        if (action === "restore")
+            return restoreEvalRunSnapshot(context, {
+                snapshot: requiredOption(parsed, "snapshot"),
+                projectRoot: requiredOption(parsed, "project-root")
+            });
+        throw new AppError("usage", "Use: dd-flow run snapshot bootstrap create|restore | dd-flow run snapshot create <RUN> (--stage-entry <stage>|--candidate) --project-root <path> --output <directory> | dd-flow run snapshot restore --snapshot <directory> --project-root <path>", 2);
+    }
+    if (command === "prepare-vnext-specify") {
+        return prepareVnextSpecifyRun(context, { projectRoot: requiredOption(parsed, "project-root"), slug: requiredOption(parsed, "slug") });
+    }
     if (command === "start") {
         if (optionalOption(parsed, "flow-kind") === "mb-upgrade") {
             assertUpgradeRunStorageReady(context, requiredOption(parsed, "project-root"));
@@ -997,12 +1386,33 @@ function dispatchRun(context, command, parsed) {
             hiddenSections: allOptions(parsed, "hide")
         });
     }
-    if (command === "usage") {
-        return getFlowRunUsage(context, {
-            projectRoot: requiredOption(parsed, "project-root"),
-            runId: requiredPosition(parsed, 0, "run-id"),
-            groupBy: optionalOption(parsed, "group-by")
-        });
+    if (command === "config") {
+        const action = requiredPosition(parsed, 0, "run config action");
+        const runId = requiredPosition(parsed, 1, "run-id");
+        if (action === "status") {
+            return getFlowRunConfig(context, { projectRoot: requiredOption(parsed, "project-root"), runId });
+        }
+        if (action === "set") {
+            return setFlowRunConfig(context, {
+                projectRoot: requiredOption(parsed, "project-root"),
+                runId,
+                key: requiredOption(parsed, "key"),
+                value: requiredOption(parsed, "value"),
+                reason: requiredOption(parsed, "reason")
+            });
+        }
+        throw new AppError("usage", `Unknown run config action: ${action}`, 2);
+    }
+    if (command === "vars") {
+        const action = requiredPosition(parsed, 0, "run vars action");
+        const runId = requiredPosition(parsed, 1, "run-id");
+        if (action === "ls")
+            return getFlowRunVariables(context, { projectRoot: requiredOption(parsed, "project-root"), runId });
+        if (action === "get")
+            return getFlowRunVariables(context, { projectRoot: requiredOption(parsed, "project-root"), runId, key: requiredOption(parsed, "key") });
+        if (action === "set")
+            return setFlowRunVariable(context, { projectRoot: requiredOption(parsed, "project-root"), runId, key: requiredOption(parsed, "key"), value: requiredOption(parsed, "value") });
+        throw new AppError("usage", `Unknown run vars command: ${action}`, 2);
     }
     if (command === "flags") {
         const action = requiredPosition(parsed, 0, "flow flags action");
@@ -1052,16 +1462,39 @@ function dispatchRun(context, command, parsed) {
         });
     }
     if (command === "complete") {
+        throw new AppError("usage", "run complete is retired; only an operator may use run override", 2);
+    }
+    if (command === "override") {
+        const status = requiredOption(parsed, "status");
+        if (!['cancelled', 'failed'].includes(status)) {
+            throw new AppError("usage", "run override status must be cancelled or failed", 2, { status });
+        }
         return completeFlowRun(context, {
             projectRoot: requiredOption(parsed, "project-root"),
             runId: requiredPosition(parsed, 0, "run-id"),
-            status: requiredOption(parsed, "status"),
+            status,
             verdict: optionalOption(parsed, "verdict"),
-            nextAction: optionalOption(parsed, "next-action")
+            nextAction: optionalOption(parsed, "next-action"),
+            manualOverrideReason: requiredOption(parsed, "reason")
         });
     }
     throw new AppError("usage", `Unknown run command: ${command ?? "<empty>"}`, 2);
 }
+function dispatchStat(context, command, parsed) {
+    if (command === "usage") {
+        return getStoredFlowRunUsage(context, {
+            projectRoot: requiredOption(parsed, "project-root"),
+            runId: requiredOption(parsed, "run"),
+            groupBy: optionalOption(parsed, "group-by"),
+            sessionId: optionalOption(parsed, "session"),
+            stage: optionalOption(parsed, "stage")
+        });
+    }
+    if (command === "run" && parsed.positional[0] === "sessions" && parsed.positional[1] === "ls") {
+        return getFlowRunSessions(context, { projectRoot: requiredOption(parsed, "project-root"), runId: requiredOption(parsed, "run") });
+    }
+    throw new AppError("usage", "Usage: dd-flow stat usage --run <RUN-ID> --project-root <root> | dd-flow stat run sessions ls --run <RUN-ID> --project-root <root>", 2);
+}
 function dispatchId(context, command, parsed) {
     if (command === "next") {
         return previewNextEntityId(context, {
@@ -1412,7 +1845,9 @@ function dispatchCodexHome(context, parsed) {
 function dispatchCodexHook(context, parsed, stdin) {
     const action = requiredPosition(parsed, 0, "codex hook action");
     if (action === "handle") {
-        const result = handleCodexHook(context, {
+        const isolatedHome = isolatedDdFlowHomeFromHookStdin(stdin);
+        const hookContext = isolatedHome ? createContext({ ...context.env, DD_FLOW_HOME: isolatedHome }) : context;
+        const result = handleCodexHook(hookContext, {
             event: requiredOption(parsed, "event"),
             projectRoot: optionalOption(parsed, "project-root"),
             stdin
@@ -1424,6 +1859,39 @@ function dispatchCodexHook(context, parsed, stdin) {
     }
     throw new AppError("usage", `Unknown codex hook action: ${action}`, 2);
 }
+function dispatchZcodeEvent(context, parsed, stdin) {
+    const action = requiredPosition(parsed, 0, "zcode event action");
+    if (action === "handle") {
+        return handleZcodeEvent(context, {
+            projectRoot: requiredOption(parsed, "project-root"),
+            stdin
+        });
+    }
+    throw new AppError("usage", `Unknown zcode event action: ${action}`, 2);
+}
+function dispatchGrokEvent(context, parsed, stdin) {
+    const action = requiredPosition(parsed, 0, "grok event action");
+    if (action === "handle") {
+        const result = handleGrokEvent(context, { projectRoot: requiredOption(parsed, "project-root"), stdin });
+        if (result && typeof result === "object" && !Array.isArray(result) && "hookSpecificOutput" in result) {
+            return { hookSpecificOutput: result.hookSpecificOutput };
+        }
+        return {};
+    }
+    throw new AppError("usage", `Unknown grok event action: ${action}`, 2);
+}
+function dispatchOpenCodeEvent(context, parsed, stdin) {
+    const action = requiredPosition(parsed, 0, "opencode event action");
+    if (action === "handle")
+        return handleOpenCodeEvent(context, { projectRoot: requiredOption(parsed, "project-root"), stdin });
+    throw new AppError("usage", `Unknown opencode event action: ${action}`, 2);
+}
+function dispatchAgyEvent(context, parsed, stdin) {
+    const action = requiredPosition(parsed, 0, "agy event action");
+    if (action === "handle")
+        return handleAgyEvent(context, { projectRoot: requiredOption(parsed, "project-root"), stdin });
+    throw new AppError("usage", `Unknown agy event action: ${action}`, 2);
+}
 function dispatchWorktree(context, command, parsed, scopeProjectRoot) {
     if (command === "plan") {
         return planWorktree(context, { protocolId: requiredOption(parsed, "protocol-id"), projectRoot: scopeProjectRoot });
@@ -1726,7 +2194,7 @@ function projectRootForMutation(context, args, result, resolvedScope) {
     if (family === "run" && ["start", "attach-stage", "complete-stage", "complete", "flags"].includes(command ?? "")) {
         return requiredOption(parsed, "project-root");
     }
-    if (family === "stage" && ["start", "finish"].includes(command ?? "")) {
+    if (family === "stage" && ["start", "pause", "resume", "finish"].includes(command ?? "")) {
         return requiredOption(parsed, "project-root");
     }
     if (family === "worktree" && ["create", "bootstrap", "close"].includes(command ?? "")) {
@@ -1735,6 +2203,14 @@ function projectRootForMutation(context, args, result, resolvedScope) {
     if (family === "codex" && command === "hook" && requiredPosition(parsed, 0, "codex hook action") === "handle") {
         return optionalOption(parsed, "project-root");
     }
+    if (family === "zcode" && ((command === "event" && requiredPosition(parsed, 0, "zcode event action") === "handle") || command === "usage")) {
+        return requiredOption(parsed, "project-root");
+    }
+    if (family === "opencode" && ((command === "event" && requiredPosition(parsed, 0, "opencode event action") === "handle") || command === "usage")) {
+        return requiredOption(parsed, "project-root");
+    }
+    if (family === "agy" && ((command === "event" && requiredPosition(parsed, 0, "agy event action") === "handle") || command === "usage"))
+        return requiredOption(parsed, "project-root");
     if (family === "codex" && command === "hooks") {
         const action = requiredPosition(parsed, 0, "codex hooks action");
         return ["install", "remove"].includes(action) ? requiredOption(parsed, "project-root") : undefined;
@@ -1770,6 +2246,27 @@ function projectRootForMergeQueueMutation(context, command, parsed) {
 function protocolProjectRoot(context, protocolId) {
     return requireProtocol(context, protocolId).project_root;
 }
+function runnerIntake(context) {
+    const input = context.value.task_input?.[0];
+    if (!input?.path)
+        throw new AppError("validation", "Runner SPECIFY context requires one ordered task_input file", 2);
+    const file = path.resolve(input.path);
+    if (!fs.existsSync(file) || !fs.statSync(file).isFile())
+        throw new AppError("not_found", "Runner SPECIFY task input is missing", 2, { task_input: file });
+    return fs.readFileSync(file, "utf8");
+}
+/** Stage services install context before their lifecycle transition.  Keeping
+ * this check here makes an incomplete service migration fail closed instead of
+ * silently materialising evidence after a Stage has become running. */
+function attachExternalStageContext(result, loaded) {
+    if (!loaded)
+        return result;
+    const promptPath = typeof result.prompt_path === "string" ? result.prompt_path : null;
+    if (!promptPath || !result.external_context || typeof result.external_context !== "object") {
+        throw new AppError("stage_context_not_installed", "vNext stage service did not atomically install the supplied runner context", 1);
+    }
+    return { ...result, worker_prompt_markdown: fs.readFileSync(promptPath, "utf8") };
+}
 function isScopedProtocolMutation(family, command) {
     if (family === "transition")
         return true;