@deksden-com/dd-flow-cli 0.1.0

package/dist/cli/run-cli.js

@@ -0,0 +1,945 @@
+import { createContext } from "../runtime/context.js";
+import { helpForArgs } from "./help.js";
+import { AppError, isAppError } from "../shared/errors.js";
+import { writeJson } from "../shared/json.js";
+import { archiveProject, getProjectStatus, migrateProjectIds, registerProject, resolveProject } from "../services/projects.js";
+import { cancelProtocol, getProtocolStatus, readyForMerge, registerProtocol, requireProtocol, transitionProtocol } from "../services/protocols.js";
+import { blockPlanItem, completePlanItem, getPlanStatus, setProtocolPlan, skipPlanItem, startPlanItem } from "../services/plans.js";
+import { cancelMergeQueueJob, claimNextMergeJob, completeMergeJob, failMergeJob, getMergeQueueStatus, noteMergeJob, waitNextMergeJob } from "../services/merge-queue.js";
+import { cleanupApply, cleanupScan } from "../services/cleanup.js";
+import { getCodexHomeStatus, getCodexHooksStatus, handleCodexHook, initCodexHome, installCodexHooks, planCodexHome, printCodexHomeEnv, printCodexHooks, removeCodexHome, removeCodexHooks } from "../services/hooks.js";
+import { bootstrapWorktree, closeWorktree, createWorktreeRecord, getWorktreeStatus, planWorktree } from "../services/worktrees.js";
+import { acquireLaneLock, checkLaneWorkspace, getLaneStatus, heartbeatLaneLock, releaseLaneLock, setLaneWorkspace, waitForLaneLock } from "../services/lanes.js";
+import { getProjectConfigStatus, setProjectConfigValue } from "../services/config.js";
+import { autoRefreshDashboards, getCmuxStatus, openDashboard, refreshDashboard, refreshGlobalDashboard, renderDashboard, renderGlobalDashboard } from "../services/dashboard.js";
+import { getFlowSessionStatus, registerFlowSession, stopFlowSession, stopMergeWorker } from "../services/sessions.js";
+import { attachFlowRunStage, completeFlowRun, completeFlowRunStage, getFlowRunStatus, listFlowRuns, startFlowRun } from "../services/runs.js";
+import { validateSchema } from "../services/schema-validation.js";
+import { preflightMemoryPermissions } from "../services/memory-permissions.js";
+import { requireProjectByRoot } from "../services/projects.js";
+import { resolveProjectRoot } from "../storage/paths.js";
+const defaultIo = {
+    stdout: process.stdout,
+    stderr: process.stderr,
+    stdin: process.stdin
+};
+const flagValue = "__dd_flow_flag__";
+export async function runCli(args, io = defaultIo, env = process.env) {
+    const output = parseOutputOptions(args);
+    const progress = progressForCommand(output.args);
+    try {
+        if (args.includes("--progress-jsonl")) {
+            throw new AppError("usage", "--progress-jsonl is not implemented yet; use --json for final structured progress", 2);
+        }
+        const help = helpForArgs(output.args);
+        if (help) {
+            io.stdout.write(`${help}\n`);
+            return 0;
+        }
+        const context = createContext(env);
+        emitHumanProgress(io, output, progress, "start");
+        const result = await dispatch(output.args, context, io);
+        refreshDashboardsAfterMutation(context, output.args, result);
+        emitHumanProgress(io, output, progress, "done");
+        const payload = attachProgress(result, progress, output);
+        if (output.json)
+            writeJson(io.stdout, payload);
+        else
+            io.stdout.write(renderHumanResult(output.args, payload));
+        return completedCommandExitCode(payload);
+    }
+    catch (error) {
+        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");
+        const errorPayload = attachProgress(payload, progress, output);
+        if (output.json)
+            writeJson(io.stderr, errorPayload);
+        else
+            io.stderr.write(`dd-flow: ${payload.error.message}\n`);
+        return isAppError(error) ? error.exitCode : 1;
+    }
+}
+function parseOutputOptions(args) {
+    const stripped = [];
+    let json = false;
+    for (const arg of args) {
+        if (arg === "--json") {
+            json = true;
+            continue;
+        }
+        stripped.push(arg);
+    }
+    const hookJsonOnly = stripped[0] === "codex" && stripped[1] === "hook" && stripped[2] === "handle";
+    return { json: json || hookJsonOnly, args: stripped, hookJsonOnly };
+}
+function progressForCommand(args) {
+    const [family, command, subcommand] = args;
+    if (family === "merge-queue" && command === "wait-next") {
+        return [
+            { phase: "start", message: "Starting merge queue wait", at: "" },
+            { phase: "running", message: "Waiting for a ready merge job", at: "" },
+            { phase: "done", message: "Merge queue wait finished", at: "" }
+        ];
+    }
+    if (family === "lane" && command === "lock" && subcommand === "wait") {
+        return [
+            { phase: "start", message: "Starting lane lock wait", at: "" },
+            { phase: "running", message: "Waiting for lane lock", at: "" },
+            { phase: "done", message: "Lane lock wait finished", at: "" }
+        ];
+    }
+    if ((family === "cleanup" && command === "apply") ||
+        (family === "protocol" && command === "cancel") ||
+        (family === "project" && command === "archive") ||
+        family === "run") {
+        return [
+            { phase: "start", message: `Starting ${family} ${command}`, at: "" },
+            { phase: "done", message: `${family} ${command} finished`, at: "" }
+        ];
+    }
+    return [];
+}
+function emitHumanProgress(io, output, progress, phase) {
+    if (output.json || output.hookJsonOnly)
+        return;
+    for (const event of progress.filter((item) => item.phase === phase)) {
+        event.at = new Date().toISOString();
+        io.stderr.write(`[${event.phase}] ${event.message}\n`);
+    }
+    if (phase === "start") {
+        for (const event of progress.filter((item) => item.phase === "running")) {
+            event.at = new Date().toISOString();
+            io.stderr.write(`[${event.phase}] ${event.message}\n`);
+        }
+    }
+}
+function attachProgress(result, progress, output) {
+    if (progress.length === 0 || output.hookJsonOnly)
+        return result;
+    for (const event of progress) {
+        if (!event.at)
+            event.at = new Date().toISOString();
+    }
+    if (result && typeof result === "object" && !Array.isArray(result)) {
+        return { ...result, progress };
+    }
+    return { ok: true, result, progress };
+}
+function renderHumanResult(args, result) {
+    const [family, command] = args;
+    const record = result && typeof result === "object" && !Array.isArray(result) ? result : {};
+    const ok = record.ok === false ? "failed" : "ok";
+    if (family === "schema" && command === "validate") {
+        const schema = record.schema && typeof record.schema === "object" ? record.schema : {};
+        const errors = Array.isArray(record.errors) ? record.errors : [];
+        const lines = [`dd-flow schema validate: ${errors.length === 0 ? "valid" : "invalid"}`];
+        if (schema.name)
+            lines.push(`schema: ${String(schema.name)} (${String(schema.id ?? "unknown")})`);
+        if (schema.path)
+            lines.push(`schema_path: ${String(schema.path)}`);
+        if (record.file)
+            lines.push(`file: ${String(record.file)}`);
+        lines.push(`errors: ${errors.length}`);
+        return `${lines.join("\n")}\n`;
+    }
+    const lines = [`dd-flow ${family ?? ""}${command ? ` ${command}` : ""}: ${ok}`.trim()];
+    const project = record.project && typeof record.project === "object" ? record.project : null;
+    const protocol = record.protocol && typeof record.protocol === "object" ? record.protocol : null;
+    if (project?.id)
+        lines.push(`project: ${String(project.id)}`);
+    if (protocol?.id)
+        lines.push(`protocol: ${String(protocol.id)}`);
+    if (record.job && typeof record.job === "object") {
+        const job = record.job;
+        lines.push(`job: ${String(job.protocol_id ?? "none")} ${String(job.status ?? "")}`.trim());
+    }
+    if (record.stopped)
+        lines.push(`stopped: ${String(record.reason ?? "true")}`);
+    if (record.timed_out)
+        lines.push("timed_out: true");
+    if (record.dashboard && typeof record.dashboard === "object")
+        lines.push(`dashboard: ${String(record.dashboard.path ?? "updated")}`);
+    if (record.run && typeof record.run === "object") {
+        const run = record.run;
+        if (run.id)
+            lines.push(`run: ${String(run.id)}`);
+        if (run.run_index_path)
+            lines.push(`run_index: ${String(run.run_index_path)}`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+async function dispatch(args, context, io) {
+    const [family, command, ...rest] = args;
+    const parsed = parseArgs(rest);
+    if (family === "project" && command === "register") {
+        return registerProject(context, { root: requiredOption(parsed, "root") });
+    }
+    if (family === "project" && command === "status") {
+        return getProjectStatus(context, { root: requiredOption(parsed, "root") });
+    }
+    if (family === "project" && command === "resolve") {
+        return resolveProject(context, { idOrAlias: requiredPosition(parsed, 0, "id-or-alias") });
+    }
+    if (family === "project" && command === "archive") {
+        return archiveProject(context, {
+            idOrAlias: parsed.positional[0],
+            root: optionalOption(parsed, "root"),
+            reason: requiredOption(parsed, "reason")
+        });
+    }
+    if (family === "project" && command === "migrate-ids") {
+        return migrateProjectIds(context, {
+            root: requiredOption(parsed, "root"),
+            apply: hasOption(parsed, "apply")
+        });
+    }
+    if (family === "project" && command === "config") {
+        return dispatchProjectConfig(context, parsed);
+    }
+    if (family === "protocol" && command === "register") {
+        const handshakeId = requiredPosition(parsed, 0, "handshake-id");
+        return registerProtocol(context, {
+            handshakeId,
+            projectRoot: requiredOption(parsed, "project-root"),
+            workspacePath: optionalOption(parsed, "workspace-path")
+        });
+    }
+    if (family === "protocol" && command === "status") {
+        return getProtocolStatus(context, { protocolId: requiredPosition(parsed, 0, "protocol-id") });
+    }
+    if (family === "protocol" && command === "ready-for-merge") {
+        return readyForMerge(context, { protocolId: requiredPosition(parsed, 0, "protocol-id") });
+    }
+    if (family === "protocol" && command === "cancel") {
+        return cancelProtocol(context, {
+            protocolId: requiredPosition(parsed, 0, "protocol-id"),
+            reason: requiredOption(parsed, "reason"),
+            closeSessions: parseOptionalBoolean(optionalOption(parsed, "close-sessions"), "close-sessions") ?? false,
+            cancelQueue: parseOptionalBoolean(optionalOption(parsed, "cancel-queue"), "cancel-queue") ?? false,
+            releaseLocks: parseOptionalBoolean(optionalOption(parsed, "release-locks"), "release-locks") ?? false,
+            worktree: parseWorktreePolicy(optionalOption(parsed, "worktree")),
+            force: hasOption(parsed, "force")
+        });
+    }
+    if (family === "transition") {
+        const transitionParsed = parseArgs([command ?? "", ...rest]);
+        const reason = optionalOption(transitionParsed, "reason");
+        return transitionProtocol(context, {
+            protocolId: requiredPosition(transitionParsed, 0, "protocol-id"),
+            to: requiredOption(transitionParsed, "to"),
+            jsonFile: requiredOption(transitionParsed, "json-file"),
+            force: hasOption(transitionParsed, "force"),
+            ...(reason ? { reason } : {})
+        });
+    }
+    if (family === "plan" && command === "set") {
+        return setProtocolPlan(context, {
+            protocolId: requiredPosition(parsed, 0, "protocol-id"),
+            file: requiredOption(parsed, "file")
+        });
+    }
+    if (family === "plan" && command === "status") {
+        return getPlanStatus(context, { protocolId: requiredPosition(parsed, 0, "protocol-id") });
+    }
+    if (family === "plan" && command === "item") {
+        return dispatchPlanItem(context, parsed);
+    }
+    if (family === "lane") {
+        return dispatchLane(context, command, parsed);
+    }
+    if (family === "merge-queue") {
+        return dispatchMergeQueue(context, command, parsed);
+    }
+    if (family === "cleanup") {
+        return dispatchCleanup(context, command, parsed);
+    }
+    if (family === "session") {
+        return dispatchSession(context, command, parsed);
+    }
+    if (family === "run") {
+        return dispatchRun(context, command, parsed);
+    }
+    if (family === "integration" && command === "cmux") {
+        return dispatchCmux(context, parsed);
+    }
+    if (family === "dashboard") {
+        return dispatchDashboard(context, command, parsed);
+    }
+    if (family === "schema") {
+        return dispatchSchema(command, parsed);
+    }
+    if (family === "memory") {
+        return dispatchMemory(command, parsed);
+    }
+    if (family === "codex" && command === "hooks") {
+        return dispatchCodexHooks(context, parsed);
+    }
+    if (family === "codex" && command === "home") {
+        return dispatchCodexHome(context, parsed);
+    }
+    if (family === "codex" && command === "hook") {
+        return dispatchCodexHook(context, parsed, await readStdin(io.stdin));
+    }
+    if (family === "worktree") {
+        return dispatchWorktree(context, command, parsed);
+    }
+    throw new AppError("usage", `Unknown command: ${args.join(" ") || "<empty>"}`, 2);
+}
+function dispatchMergeQueue(context, command, parsed) {
+    if (hasOption(parsed, "session-id")) {
+        throw new AppError("usage", "--session-id is no longer accepted on merge-queue commands; use --worker-id", 2);
+    }
+    if (command === "status") {
+        return getMergeQueueStatus(context, { projectRoot: requiredOption(parsed, "project-root") });
+    }
+    if (command === "next") {
+        return claimNextMergeJob(context, {
+            projectRoot: requiredOption(parsed, "project-root"),
+            workerId: requiredWorkerId(parsed),
+            workspacePath: workspacePathOption(parsed)
+        });
+    }
+    if (command === "wait-next") {
+        return waitNextMergeJob(context, {
+            projectRoot: requiredOption(parsed, "project-root"),
+            workerId: requiredWorkerId(parsed),
+            timeoutSeconds: optionalNumber(parsed, "timeout"),
+            pollIntervalSeconds: optionalNumber(parsed, "poll-interval"),
+            workspacePath: workspacePathOption(parsed),
+            acquireLock: parseOptionalBoolean(optionalOption(parsed, "acquire-lock"), "acquire-lock") ?? false
+        });
+    }
+    if (command === "complete") {
+        return completeMergeJob(context, {
+            protocolId: requiredPosition(parsed, 0, "protocol-id"),
+            workerId: requiredWorkerId(parsed),
+            workspacePath: workspacePathOption(parsed),
+            summary: requiredOption(parsed, "summary")
+        });
+    }
+    if (command === "fail") {
+        return failMergeJob(context, {
+            protocolId: requiredPosition(parsed, 0, "protocol-id"),
+            workerId: requiredWorkerId(parsed),
+            workspacePath: workspacePathOption(parsed),
+            reason: requiredOption(parsed, "reason"),
+            requeue: parseBoolean(requiredOption(parsed, "requeue"), "requeue")
+        });
+    }
+    if (command === "note") {
+        return noteMergeJob(context, {
+            protocolId: requiredPosition(parsed, 0, "protocol-id"),
+            workerId: requiredWorkerId(parsed),
+            summary: requiredOption(parsed, "summary")
+        });
+    }
+    if (command === "cancel") {
+        return cancelMergeQueueJob(context, {
+            protocolId: requiredPosition(parsed, 0, "protocol-id"),
+            reason: requiredOption(parsed, "reason"),
+            workerId: optionalOption(parsed, "worker-id"),
+            workspacePath: optionalOption(parsed, "path"),
+            force: hasOption(parsed, "force")
+        });
+    }
+    throw new AppError("usage", `Unknown merge-queue command: ${command ?? "<empty>"}`, 2);
+}
+function dispatchMemory(command, parsed) {
+    const subcommand = requiredPosition(parsed, 0, "memory subcommand");
+    if (command === "permissions" && subcommand === "preflight") {
+        return preflightMemoryPermissions({
+            root: requiredOption(parsed, "root"),
+            memoryBank: requiredOption(parsed, "memory-bank"),
+            tasks: optionalOption(parsed, "tasks"),
+            flow: requiredOption(parsed, "flow"),
+            mode: requiredOption(parsed, "mode")
+        });
+    }
+    throw new AppError("usage", `Unknown memory command: ${["memory", command, subcommand].filter(Boolean).join(" ")}`, 2);
+}
+function completedCommandExitCode(payload) {
+    if (!payload || typeof payload !== "object" || Array.isArray(payload))
+        return 0;
+    const exitCode = payload.exit_code;
+    return typeof exitCode === "number" && Number.isInteger(exitCode) ? exitCode : 0;
+}
+function dispatchCleanup(context, command, parsed) {
+    if (command === "scan") {
+        return cleanupScan(context, { projectRoot: requiredOption(parsed, "project-root") });
+    }
+    if (command === "apply") {
+        return cleanupApply(context, {
+            projectRoot: requiredOption(parsed, "project-root"),
+            planFile: requiredOption(parsed, "plan-file"),
+            reason: requiredOption(parsed, "reason"),
+            force: hasOption(parsed, "force")
+        });
+    }
+    throw new AppError("usage", `Unknown cleanup command: ${command ?? "<empty>"}`, 2);
+}
+function dispatchProjectConfig(context, parsed) {
+    const action = requiredPosition(parsed, 0, "project config action");
+    const project = requireProjectByRoot(context, resolveProjectRoot(requiredOption(parsed, "project-root")));
+    if (action === "status") {
+        return getProjectConfigStatus(context, project);
+    }
+    if (action === "set") {
+        return setProjectConfigValue(context, project, {
+            key: requiredOption(parsed, "key"),
+            value: requiredOption(parsed, "value")
+        });
+    }
+    throw new AppError("usage", `Unknown project config action: ${action}`, 2);
+}
+function dispatchSession(context, command, parsed) {
+    if (command === "register") {
+        return registerFlowSession(context, {
+            payloadBase64: optionalOption(parsed, "payload-base64"),
+            payloadJson: optionalOption(parsed, "payload-json"),
+            payloadFile: optionalOption(parsed, "payload-file"),
+            sessionId: optionalOption(parsed, "session-id")
+        });
+    }
+    if (command === "status") {
+        return getFlowSessionStatus(context, {
+            projectRoot: requiredOption(parsed, "project-root"),
+            sessionId: optionalOption(parsed, "session-id"),
+            workerId: optionalOption(parsed, "worker-id")
+        });
+    }
+    if (command === "stop") {
+        return stopFlowSession(context, {
+            projectRoot: requiredOption(parsed, "project-root"),
+            sessionId: requiredOption(parsed, "session-id"),
+            reason: requiredOption(parsed, "reason")
+        });
+    }
+    if (command === "stop-worker") {
+        return stopMergeWorker(context, {
+            projectRoot: requiredOption(parsed, "project-root"),
+            workerId: requiredOption(parsed, "worker-id"),
+            reason: requiredOption(parsed, "reason")
+        });
+    }
+    throw new AppError("usage", `Unknown session command: ${command ?? "<empty>"}`, 2);
+}
+function dispatchRun(context, command, parsed) {
+    if (command === "start") {
+        return startFlowRun(context, {
+            projectRoot: requiredOption(parsed, "project-root"),
+            workspaceRoot: optionalOption(parsed, "workspace-root"),
+            flowKind: requiredOption(parsed, "flow-kind"),
+            subjectType: requiredOption(parsed, "subject-type"),
+            subjectId: requiredOption(parsed, "subject-id"),
+            slug: requiredOption(parsed, "slug"),
+            nextAction: optionalOption(parsed, "next-action")
+        });
+    }
+    if (command === "status") {
+        return getFlowRunStatus(context, {
+            projectRoot: requiredOption(parsed, "project-root"),
+            runId: requiredPosition(parsed, 0, "run-id")
+        });
+    }
+    if (command === "list") {
+        return listFlowRuns(context, { projectRoot: requiredOption(parsed, "project-root") });
+    }
+    if (command === "attach-stage") {
+        return attachFlowRunStage(context, {
+            projectRoot: requiredOption(parsed, "project-root"),
+            runId: requiredPosition(parsed, 0, "run-id"),
+            stage: requiredOption(parsed, "stage"),
+            dir: requiredOption(parsed, "dir"),
+            status: requiredOption(parsed, "status"),
+            dataSchemaId: optionalOption(parsed, "data-schema-id")
+        });
+    }
+    if (command === "complete-stage") {
+        const stageReport = optionalOption(parsed, "stage-report") ?? optionalOption(parsed, "dashboard");
+        return completeFlowRunStage(context, {
+            projectRoot: requiredOption(parsed, "project-root"),
+            runId: requiredPosition(parsed, 0, "run-id"),
+            stage: requiredOption(parsed, "stage"),
+            status: requiredOption(parsed, "status"),
+            stageReport,
+            data: optionalOption(parsed, "data"),
+            dataSchemaId: optionalOption(parsed, "data-schema-id"),
+            report: optionalOption(parsed, "report"),
+            aliases: allOptions(parsed, "alias")
+        });
+    }
+    if (command === "complete") {
+        return completeFlowRun(context, {
+            projectRoot: requiredOption(parsed, "project-root"),
+            runId: requiredPosition(parsed, 0, "run-id"),
+            status: requiredOption(parsed, "status"),
+            verdict: optionalOption(parsed, "verdict"),
+            nextAction: optionalOption(parsed, "next-action")
+        });
+    }
+    throw new AppError("usage", `Unknown run command: ${command ?? "<empty>"}`, 2);
+}
+function dispatchCmux(context, parsed) {
+    const action = requiredPosition(parsed, 0, "integration cmux action");
+    if (action === "status") {
+        return getCmuxStatus(context, { projectRoot: requiredOption(parsed, "project-root") });
+    }
+    throw new AppError("usage", `Unknown integration cmux action: ${action}`, 2);
+}
+function dispatchDashboard(context, command, parsed) {
+    if (command === "render") {
+        return renderDashboard(context, { projectRoot: requiredOption(parsed, "project-root"), output: optionalOption(parsed, "output") });
+    }
+    if (command === "render-global") {
+        return renderGlobalDashboard(context, { output: optionalOption(parsed, "output") });
+    }
+    if (command === "open") {
+        return openDashboard(context, { projectRoot: requiredOption(parsed, "project-root"), viewer: optionalOption(parsed, "viewer") });
+    }
+    if (command === "refresh") {
+        const open = optionalOption(parsed, "open");
+        if (typeof open !== "undefined" && !["auto", "true", "false"].includes(open)) {
+            throw new AppError("validation", "--open must be auto, true, or false", 2);
+        }
+        return refreshDashboard(context, {
+            projectRoot: requiredOption(parsed, "project-root"),
+            open: open
+        });
+    }
+    if (command === "refresh-global") {
+        return refreshGlobalDashboard(context, { output: optionalOption(parsed, "output") });
+    }
+    throw new AppError("usage", `Unknown dashboard command: ${command ?? "<empty>"}`, 2);
+}
+function dispatchSchema(command, parsed) {
+    if (command === "validate") {
+        const schemaDir = optionalOption(parsed, "schema-dir");
+        const projectRoot = optionalOption(parsed, "project-root");
+        return validateSchema({
+            schemaName: requiredOption(parsed, "schema"),
+            file: requiredOption(parsed, "file"),
+            ...(schemaDir ? { schemaDir } : {}),
+            ...(projectRoot ? { projectRoot } : {})
+        });
+    }
+    throw new AppError("usage", `Unknown schema command: ${command ?? "<empty>"}`, 2);
+}
+async function dispatchLane(context, command, parsed) {
+    if (command === "status") {
+        return getLaneStatus(context, { projectRoot: requiredOption(parsed, "project-root"), lane: optionalOption(parsed, "lane") });
+    }
+    if (command === "workspace") {
+        const action = requiredPosition(parsed, 0, "lane workspace action");
+        if (action === "set") {
+            return setLaneWorkspace(context, {
+                projectRoot: requiredOption(parsed, "project-root"),
+                lane: requiredOption(parsed, "lane"),
+                workspacePath: requiredOption(parsed, "path"),
+                branch: optionalOption(parsed, "branch")
+            });
+        }
+        if (action === "check") {
+            return checkLaneWorkspace(context, {
+                projectRoot: requiredOption(parsed, "project-root"),
+                lane: requiredOption(parsed, "lane"),
+                workspacePath: requiredOption(parsed, "path")
+            });
+        }
+        throw new AppError("usage", `Unknown lane workspace action: ${action}`, 2);
+    }
+    if (command === "lock") {
+        const action = requiredPosition(parsed, 0, "lane lock action");
+        if (action === "acquire") {
+            return acquireLaneLock(context, {
+                projectRoot: requiredOption(parsed, "project-root"),
+                lane: requiredOption(parsed, "lane"),
+                workerId: requiredOption(parsed, "worker-id"),
+                workspacePath: workspacePathOption(parsed),
+                ttlSeconds: optionalNumber(parsed, "ttl"),
+                reason: requiredOption(parsed, "reason")
+            });
+        }
+        if (action === "heartbeat") {
+            return heartbeatLaneLock(context, {
+                projectRoot: requiredOption(parsed, "project-root"),
+                lane: requiredOption(parsed, "lane"),
+                workerId: requiredOption(parsed, "worker-id"),
+                workspacePath: workspacePathOption(parsed),
+                leaseToken: optionalOption(parsed, "lease-token"),
+                ttlSeconds: optionalNumber(parsed, "ttl")
+            });
+        }
+        if (action === "release") {
+            return releaseLaneLock(context, {
+                projectRoot: requiredOption(parsed, "project-root"),
+                lane: requiredOption(parsed, "lane"),
+                workerId: requiredOption(parsed, "worker-id"),
+                workspacePath: workspacePathOption(parsed),
+                leaseToken: optionalOption(parsed, "lease-token"),
+                reason: requiredOption(parsed, "reason")
+            });
+        }
+        if (action === "status") {
+            return getLaneStatus(context, { projectRoot: requiredOption(parsed, "project-root"), lane: requiredOption(parsed, "lane") });
+        }
+        if (action === "wait") {
+            return waitForLaneLock(context, {
+                projectRoot: requiredOption(parsed, "project-root"),
+                lane: requiredOption(parsed, "lane"),
+                workerId: requiredOption(parsed, "worker-id"),
+                workspacePath: workspacePathOption(parsed),
+                timeoutSeconds: optionalNumber(parsed, "timeout"),
+                pollIntervalSeconds: optionalNumber(parsed, "poll-interval")
+            });
+        }
+        throw new AppError("usage", `Unknown lane lock action: ${action}`, 2);
+    }
+    throw new AppError("usage", `Unknown lane command: ${command ?? "<empty>"}`, 2);
+}
+function dispatchCodexHooks(context, parsed) {
+    const action = requiredPosition(parsed, 0, "codex hooks action");
+    if (action === "print") {
+        return printCodexHooks(context, {
+            projectRoot: requiredOption(parsed, "project-root"),
+            target: optionalOption(parsed, "target"),
+            profile: optionalOption(parsed, "profile")
+        });
+    }
+    if (action === "status") {
+        return getCodexHooksStatus(context, {
+            projectRoot: requiredOption(parsed, "project-root"),
+            target: optionalOption(parsed, "target"),
+            profile: optionalOption(parsed, "profile")
+        });
+    }
+    if (action === "install") {
+        return installCodexHooks(context, {
+            projectRoot: requiredOption(parsed, "project-root"),
+            target: optionalOption(parsed, "target"),
+            profile: optionalOption(parsed, "profile"),
+            yes: hasOption(parsed, "yes")
+        });
+    }
+    if (action === "remove") {
+        return removeCodexHooks(context, {
+            projectRoot: requiredOption(parsed, "project-root"),
+            target: optionalOption(parsed, "target"),
+            profile: optionalOption(parsed, "profile"),
+            yes: hasOption(parsed, "yes")
+        });
+    }
+    throw new AppError("usage", `Unknown codex hooks action: ${action}`, 2);
+}
+function dispatchCodexHome(context, parsed) {
+    const action = requiredPosition(parsed, 0, "codex home action");
+    if (action === "plan") {
+        return planCodexHome(context, {
+            projectRoot: requiredOption(parsed, "project-root"),
+            profile: optionalOption(parsed, "profile"),
+            sourceHome: optionalOption(parsed, "source-home"),
+            targetHome: optionalOption(parsed, "target-home")
+        });
+    }
+    if (action === "init") {
+        return initCodexHome(context, {
+            projectRoot: requiredOption(parsed, "project-root"),
+            profile: optionalOption(parsed, "profile"),
+            sourceHome: optionalOption(parsed, "source-home"),
+            targetHome: optionalOption(parsed, "target-home")
+        });
+    }
+    if (action === "status") {
+        return getCodexHomeStatus(context, {
+            projectRoot: requiredOption(parsed, "project-root"),
+            profile: optionalOption(parsed, "profile")
+        });
+    }
+    if (action === "print-env") {
+        return printCodexHomeEnv(context, {
+            projectRoot: requiredOption(parsed, "project-root"),
+            profile: optionalOption(parsed, "profile")
+        });
+    }
+    if (action === "remove") {
+        return removeCodexHome(context, {
+            projectRoot: requiredOption(parsed, "project-root"),
+            profile: optionalOption(parsed, "profile"),
+            mode: requiredOption(parsed, "mode")
+        });
+    }
+    throw new AppError("usage", `Unknown codex home action: ${action}`, 2);
+}
+function dispatchCodexHook(context, parsed, stdin) {
+    const action = requiredPosition(parsed, 0, "codex hook action");
+    if (action === "handle") {
+        return handleCodexHook(context, {
+            event: requiredOption(parsed, "event"),
+            projectRoot: requiredOption(parsed, "project-root"),
+            stdin
+        });
+    }
+    throw new AppError("usage", `Unknown codex hook action: ${action}`, 2);
+}
+function dispatchWorktree(context, command, parsed) {
+    if (command === "plan") {
+        return planWorktree(context, { protocolId: requiredOption(parsed, "protocol-id") });
+    }
+    if (command === "create") {
+        return createWorktreeRecord(context, {
+            protocolId: requiredOption(parsed, "protocol-id"),
+            branch: requiredOption(parsed, "branch"),
+            base: requiredOption(parsed, "base"),
+            path: requiredOption(parsed, "path")
+        });
+    }
+    if (command === "status") {
+        return getWorktreeStatus(context, { protocolId: requiredOption(parsed, "protocol-id") });
+    }
+    if (command === "bootstrap") {
+        return bootstrapWorktree(context, { protocolId: requiredOption(parsed, "protocol-id") });
+    }
+    if (command === "close") {
+        return closeWorktree(context, {
+            protocolId: requiredOption(parsed, "protocol-id"),
+            mode: requiredOption(parsed, "mode")
+        });
+    }
+    throw new AppError("usage", `Unknown worktree command: ${command ?? "<empty>"}`, 2);
+}
+function dispatchPlanItem(context, parsed) {
+    const action = requiredPosition(parsed, 0, "plan item action");
+    const protocolId = requiredPosition(parsed, 1, "protocol-id");
+    const itemId = requiredPosition(parsed, 2, "item-id");
+    if (action === "start") {
+        return startPlanItem(context, { protocolId, itemId });
+    }
+    if (action === "done") {
+        return completePlanItem(context, {
+            protocolId,
+            itemId,
+            summary: requiredOption(parsed, "summary"),
+            evidence: parsed.options.get("evidence") ?? []
+        });
+    }
+    if (action === "block") {
+        return blockPlanItem(context, {
+            protocolId,
+            itemId,
+            reason: requiredOption(parsed, "reason"),
+            userRequired: parseBoolean(requiredOption(parsed, "user-required"), "user-required")
+        });
+    }
+    if (action === "skip") {
+        return skipPlanItem(context, {
+            protocolId,
+            itemId,
+            reason: requiredOption(parsed, "reason")
+        });
+    }
+    throw new AppError("usage", `Unknown plan item action: ${action}`, 2);
+}
+function parseArgs(args) {
+    const positional = [];
+    const options = new Map();
+    for (let index = 0; index < args.length; index += 1) {
+        const value = args[index];
+        if (value?.startsWith("--")) {
+            const key = value.slice(2);
+            const next = args[index + 1];
+            if (!next || next.startsWith("--")) {
+                options.set(key, [...(options.get(key) ?? []), flagValue]);
+            }
+            else {
+                options.set(key, [...(options.get(key) ?? []), next]);
+                index += 1;
+            }
+        }
+        else if (value) {
+            positional.push(value);
+        }
+    }
+    return { positional, options };
+}
+function requiredPosition(parsed, index, label) {
+    const value = parsed.positional[index];
+    if (!value) {
+        throw new AppError("usage", `Missing required argument: ${label}`, 2);
+    }
+    return value;
+}
+function optionalOption(parsed, key) {
+    const values = parsed.options.get(key);
+    const value = values?.[values.length - 1];
+    return value === flagValue ? undefined : value;
+}
+function allOptions(parsed, key) {
+    return (parsed.options.get(key) ?? []).filter((value) => value !== flagValue);
+}
+function requiredOption(parsed, key) {
+    const value = optionalOption(parsed, key);
+    if (!value) {
+        throw new AppError("usage", `Missing required option: --${key}`, 2);
+    }
+    return value;
+}
+function hasOption(parsed, key) {
+    return parsed.options.has(key);
+}
+function parseBoolean(value, key) {
+    if (value === "true") {
+        return true;
+    }
+    if (value === "false") {
+        return false;
+    }
+    throw new AppError("validation", `--${key} must be true or false`, 2);
+}
+function parseOptionalBoolean(value, key) {
+    return typeof value === "string" ? parseBoolean(value, key) : undefined;
+}
+function optionalNumber(parsed, key) {
+    const value = optionalOption(parsed, key);
+    if (typeof value === "undefined") {
+        return undefined;
+    }
+    const parsedNumber = Number(value);
+    if (!Number.isFinite(parsedNumber)) {
+        throw new AppError("validation", `--${key} must be a number`, 2);
+    }
+    return parsedNumber;
+}
+function requiredWorkerId(parsed) {
+    return requiredOption(parsed, "worker-id");
+}
+function workspacePathOption(parsed) {
+    return optionalOption(parsed, "path") ?? process.cwd();
+}
+function parseWorktreePolicy(value) {
+    const policy = value ?? "keep";
+    if (policy === "keep" || policy === "remove") {
+        return policy;
+    }
+    throw new AppError("validation", "--worktree must be keep or remove", 2);
+}
+async function readStdin(stream) {
+    if (!stream) {
+        return "";
+    }
+    let data = "";
+    stream.setEncoding("utf8");
+    for await (const chunk of stream) {
+        data += chunk;
+    }
+    return data;
+}
+function refreshDashboardsAfterMutation(context, args, result) {
+    if (args[0] === "project" && args[1] === "archive") {
+        refreshGlobalDashboard(context, {});
+        return;
+    }
+    const projectRoot = projectRootForMutation(context, args, result);
+    if (!projectRoot) {
+        return;
+    }
+    autoRefreshDashboards(context, { projectRoot });
+}
+function projectRootForMutation(context, args, result) {
+    const [family, command, ...rest] = args;
+    const parsed = parseArgs(rest);
+    if (family === "dashboard" || family === "integration") {
+        return undefined;
+    }
+    if (family === "project" && command === "register") {
+        return requiredOption(parsed, "root");
+    }
+    if (family === "project" && command === "config" && requiredPosition(parsed, 0, "project config action") === "set") {
+        return requiredOption(parsed, "project-root");
+    }
+    if (family === "protocol" && command === "register") {
+        return requiredOption(parsed, "project-root");
+    }
+    if (family === "protocol" && command === "ready-for-merge") {
+        return protocolProjectRoot(context, requiredPosition(parsed, 0, "protocol-id"));
+    }
+    if (family === "protocol" && command === "cancel") {
+        return protocolProjectRoot(context, requiredPosition(parsed, 0, "protocol-id"));
+    }
+    if (family === "transition") {
+        const transitionParsed = parseArgs([command ?? "", ...rest]);
+        return protocolProjectRoot(context, requiredPosition(transitionParsed, 0, "protocol-id"));
+    }
+    if (family === "plan" && command === "set") {
+        return protocolProjectRoot(context, requiredPosition(parsed, 0, "protocol-id"));
+    }
+    if (family === "plan" && command === "item") {
+        return protocolProjectRoot(context, requiredPosition(parsed, 1, "protocol-id"));
+    }
+    if (family === "lane") {
+        return projectRootForLaneMutation(command, parsed);
+    }
+    if (family === "merge-queue") {
+        return projectRootForMergeQueueMutation(context, command, parsed);
+    }
+    if (family === "cleanup" && command === "apply") {
+        return requiredOption(parsed, "project-root");
+    }
+    if (family === "session") {
+        if (command === "register") {
+            return projectRootFromResult(result);
+        }
+        return ["stop", "stop-worker"].includes(command ?? "") ? requiredOption(parsed, "project-root") : undefined;
+    }
+    if (family === "run" && ["start", "attach-stage", "complete-stage", "complete"].includes(command ?? "")) {
+        return requiredOption(parsed, "project-root");
+    }
+    if (family === "worktree" && ["create", "bootstrap", "close"].includes(command ?? "")) {
+        return protocolProjectRoot(context, requiredOption(parsed, "protocol-id"));
+    }
+    if (family === "codex" && command === "hook" && requiredPosition(parsed, 0, "codex hook action") === "handle") {
+        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;
+    }
+    if (family === "codex" && command === "home") {
+        const action = requiredPosition(parsed, 0, "codex home action");
+        return ["init", "remove"].includes(action) ? requiredOption(parsed, "project-root") : undefined;
+    }
+    return undefined;
+}
+function projectRootForLaneMutation(command, parsed) {
+    if (command === "workspace" && requiredPosition(parsed, 0, "lane workspace action") === "set") {
+        return requiredOption(parsed, "project-root");
+    }
+    if (command !== "lock") {
+        return undefined;
+    }
+    const action = requiredPosition(parsed, 0, "lane lock action");
+    return ["acquire", "heartbeat", "release"].includes(action) ? requiredOption(parsed, "project-root") : undefined;
+}
+function projectRootForMergeQueueMutation(context, command, parsed) {
+    if (["next", "wait-next"].includes(command ?? "")) {
+        return requiredOption(parsed, "project-root");
+    }
+    if (["complete", "fail", "cancel"].includes(command ?? "")) {
+        return protocolProjectRoot(context, requiredPosition(parsed, 0, "protocol-id"));
+    }
+    return undefined;
+}
+function protocolProjectRoot(context, protocolId) {
+    return requireProtocol(context, protocolId).project_root;
+}
+function projectRootFromResult(result) {
+    if (!result || typeof result !== "object") {
+        return undefined;
+    }
+    const session = result.session;
+    if (session && typeof session === "object") {
+        const projectRoot = session.project_root;
+        return typeof projectRoot === "string" ? projectRoot : undefined;
+    }
+    return undefined;
+}