@deksden-com/dd-flow-cli 0.9.0-beta.74 → 0.9.0-beta.79

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @deksden-com/dd-flow-cli
 
+## 0.9.0-beta.75
+
+### Patch Changes
+
+- Use adapter-owned native delegation instructions for Codex and the other
+  supported harnesses, preserving independent child Work ownership and clearer
+  native-session diagnostics across fan-out and recovery.
+
 ## 0.9.0-beta.64
 
 ### Patch Changes

package/dist/build-info.json

@@ -1,15 +1,15 @@
 {
   "cli_package": "@deksden-com/dd-flow-cli",
-  "cli_version": "0.9.0-beta.74",
-  "cli_commit": "b9495b1c198fded3294040d1dfdc34d36e6aa809",
-  "built_at": "2026-09-17T00:37:10.744Z",
+  "cli_version": "0.9.0-beta.79",
+  "cli_commit": "f8f5436ce8399616d7da953991c13e9c8b7e1004",
+  "built_at": "2026-09-19T21:50:05.682Z",
   "built_with_canon": {
     "version": "4.1.1",
     "commit": "97f811d33c212ae3497020178b1ed825c7c3ebac",
     "flow_contract": "dd-flow-canonical-2026-08",
-    "repo_root": "/home/runner/work/dd-flow-cli/dd-flow-cli/dd-memorybank",
-    "memorybank_root": "/home/runner/work/dd-flow-cli/dd-flow-cli/dd-memorybank/.memory-bank",
-    "flow_root": "/home/runner/work/dd-flow-cli/dd-flow-cli/dd-memorybank/.memory-bank/dd-flow",
+    "repo_root": "/Users/deksden/Documents/_Projects/dd-memorybank",
+    "memorybank_root": "/Users/deksden/Documents/_Projects/dd-memorybank/.memory-bank",
+    "flow_root": "/Users/deksden/Documents/_Projects/dd-memorybank/.memory-bank/dd-flow",
     "layout": "dot_memory_bank"
   }
 }

package/dist/cli/command-inputs.js

@@ -0,0 +1,300 @@
+import { AppError } from "../shared/errors.js";
+import { parseCommandArgs } from "../services/lifecycle-command.js";
+import { isUpgradeAllowlisted } from "../services/cli-operation-classifier.js";
+const words = (value) => value.split(" ").filter(Boolean);
+const route = (positions, required = "", values = "", switches = "", repeatable = "", enums = {}) => ({
+    positions: typeof positions === "number" ? [positions, positions] : positions,
+    required: words(required), values: words(`${required} ${values}`), switches: words(switches), repeatable: words(repeatable), enums
+});
+const project = "project-root";
+const scoped = "project-root"; // Optional when the router resolves a unique retained scope.
+const lifecycle = "invocation-id hook-event-id";
+const worker = "worker-id";
+const control = "project-root run";
+export const commandInputs = {
+    "version": route(0),
+    "status": route(0, "", "root project-root", "check-registry"),
+    "project register": route(0, "root"),
+    "project status": route(0, "root"),
+    "project summary": route(0, project, "write"),
+    "project resolve": route(1),
+    "project archive": route([0, 1], "reason", "root"),
+    "project migrate-ids": route(0, "root", "", "apply"),
+    "project config status": route(0, project),
+    "project config set": route(0, `${project} key value`),
+    "protocol register": route(1, project, "workspace-path"),
+    "protocol status": route(1, "", scoped),
+    "protocol branch-status": route([0, 1], "", `${scoped} path`),
+    "protocol ready": route(0, project),
+    "protocol blockers": route(1, project),
+    "protocol implement": route(1, "", `${scoped} reason`, "force"),
+    "protocol ready-for-merge": route(1, "", scoped),
+    "protocol transition": route(1, "to", `${scoped} payload-file json-file reason`, "force"),
+    "transition": route(1, "to", `${scoped} payload-file json-file reason`, "force"),
+    "protocol sync-from-run": route(1, "run", `${scoped} target`),
+    "protocol cancel": route(1, "reason", `${scoped} close-sessions cancel-queue release-locks worktree`, "force"),
+    "plan status": route(1, "", scoped),
+    "plan reviews": { ...route(0), retired: "PLAN review dispatch moved to: dd-flow plan-review dispatch <RUN>" },
+    "plan item start": route(2, "", scoped),
+    "plan item done": route(2, "summary", `${scoped} evidence`, "", "evidence"),
+    "plan item block": route(2, "reason user-required", scoped),
+    "plan item skip": route(2, "reason", scoped),
+    "plan-review dispatch": route(1, "", scoped),
+    "prompt render": route(0, `${project} run stage profile`, "workspace-root task-file plan-item"),
+    "stage start": { ...route([0, 1], `${project} stage`, `${lifecycle} dir subject intake-file context-file context-sha256`, "bootstrap intake-stdin require-session-binding"), contextualPaths: words("project-root intake-file context-file") },
+    "stage finish": { ...route(1, `${project} stage`, `${lifecycle} dir semantic-file data result-file outcome decision-file verification-file retry-check reason request work`, "result-stdin"), contextualPaths: words("project-root semantic-file result-file decision-file verification-file") },
+    "stage pause": { ...route(1, `${project} stage work`, lifecycle, "question-stdin"), contextualPaths: ["project-root"] },
+    "stage resume": { ...route(1, `${project} stage work`, lifecycle, "answer-stdin"), contextualPaths: ["project-root"] },
+    "stage block": route(1, `${project} stage work kind code`, "", "summary-stdin retryable", "", { kind: ["engine", "harness", "environment"] }),
+    "stage unblock": route(1, `${project} stage work`),
+    "stage fanout status": route(1, "stage", scoped),
+    "stage fanout dispatch": route(1, "stage", scoped),
+    "stage fanout reconcile": route(1, "stage observations-file", scoped),
+    "stage native observe": route(1, "stage observations-file", scoped),
+    "work status": route(1, project),
+    "work add-batch": route(0, "parent file", scoped),
+    "work ls": route(0, "", `${scoped} run parent status limit`, "ready include-results", "", { status: ["created", "running", "paused", "completed", "failed", "cancelled"] }),
+    "work show": route(1, "", scoped),
+    "work repair add": route(0, "run", `${scoped} origin-work from-check from-finding from-unresolved check-ref verification-file`, "task-stdin", "origin-work from-finding from-unresolved check-ref"),
+    "work deps add": route(1, "on", scoped, "", "on"),
+    "work deps remove": route(1, "on", scoped, "", "on"),
+    "work deps list": route(1, "", scoped),
+    "work deps clear": route(1, "", scoped),
+    "work delete": route(1, "", scoped),
+    "work launch": route(1, "", `${scoped} stage`),
+    "work start": { ...route(1, "", `${scoped} ${lifecycle} recovery-id`), contextualPaths: ["project-root"] },
+    "work finish": { ...route(1, "", `${scoped} ${lifecycle} result-file retry-check reason`, "result-stdin"), contextualPaths: words("project-root result-file") },
+    "work fail": { ...route(1, "reason", `${scoped} ${lifecycle}`), contextualPaths: ["project-root"] },
+    "work cancel": route(1, "reason", scoped),
+    "work retry": route(1, "reason", scoped),
+    "session register": { ...route(0, "", `${scoped} ${lifecycle} payload-base64 payload-json payload-file session-id`), contextualPaths: words("project-root payload-file") },
+    "session status": route(0, project, "session-id worker-id"),
+    "session stop": route(0, `${project} session-id reason`),
+    "session stop-worker": route(0, `${project} worker-id reason`),
+    "session usage sync": route(0, project, "session-id"),
+    "run start": route(0, `${project} flow-kind subject-type subject-id slug`, "workspace-root next-action preset task-profile-file execution-routing-file protocol-override-file flag", "", "flag"),
+    "run prepare-vnext-specify": route(0, `${project} slug`, "execution-routing-file"),
+    "run status": route(1, project),
+    "run list": route(0, project),
+    "run timeline": route(1, project, "hide", "", "hide"),
+    "run config status": route(1, project),
+    "run config set": route(1, `${project} key value reason`),
+    "run vars ls": route(1, project),
+    "run vars get": route(1, `${project} key`),
+    "run vars set": route(1, `${project} key value`),
+    "run flags status": route(1, project),
+    "run flags revise": route(1, `${project} expected-revision idempotency-key`, "flag preset reason", "allow-downgrade", "flag"),
+    "run attach-stage": route(1, `${project} stage dir status`, "data-schema-id"),
+    "run complete-stage": route(1, `${project} stage status`, "stage-report dashboard data data-schema-id report alias", "", "alias"),
+    "run complete": { ...route(0), retired: "run complete is retired; only an operator may use run override" },
+    "run override": route(1, `${project} status reason`, "verdict next-action", "", "", { status: ["cancelled", "failed"] }),
+    "run capacity record": route(1, `${project} available-slots`),
+    "run recovery inspect": route(1, project),
+    "run recovery begin": route(1, `${project} interruption-json`),
+    "run recovery seal": route(1, `${project} recovery-id settlement-json`),
+    "run recovery capture": route(1, `${project} recovery-id capture-path`),
+    "run recovery resume": route(1, `${project} recovery-id daemon-id harness native-session-id`),
+    "run recovery accept": { ...route(1, `${project} recovery-id`, lifecycle), contextualPaths: ["project-root"] },
+    "run snapshot bootstrap create": route(0, `${project} output`),
+    "run snapshot bootstrap restore": route(0, `${project} snapshot`),
+    "run snapshot create": route(1, `${project} output`, "recovery-id stage-entry", "candidate incomplete"),
+    "run snapshot restore": route(0, `${project} snapshot`, "execution-routing-file recovery-id"),
+    "run fork": route(0, "from output engine-version request-id", "integrity-checksum"),
+    "run drive status": route(0, control, "after"),
+    "run drive launch": route(0, `${control} request-id context-file context-sha256`, "stop-after capture-root"),
+    "run drive serve": route(0, `${control} controller-id`),
+    "run drive answer": route(0, `${control} request-id pause-id answer-file`),
+    "run drive context": route(0, `${control} controller-id request-id stage context-file context-sha256`),
+    "run control status": route(0, control),
+    "run control reconcile": route(0, `${control} control-id request-id`),
+    "run control resume": route(0, `${control} request-id from`, "wait-ms"),
+    "run control serve": route(0, `${control} control-id`),
+    "run control pause": route(0, `${control} request-id`, "grace-ms wait-ms escalate", "force"),
+    "run control stop": route(0, `${control} request-id`, "grace-ms wait-ms escalate", "force"),
+    "runtime scope fence": route(0, "scope-id request-id"),
+    "runtime scope status": route(0, "scope-id"),
+    "runtime scope stop": route(0, "scope-id request-id"),
+    "runtime scope control": route(0, "scope-id request-id mode", "manifest-json", "", "", { mode: ["pause", "stop"] }),
+    "runtime scope serve": route(0, "scope-id generation"),
+    "runtime scope resume": route(0, "scope-id request-id generation capture-key"),
+    "runtime scope reconcile": route(0, "scope-id generation request-id"),
+    "runtime process check-admission": route(0, "id lease-token"),
+    "runtime process start": route(0, `${control} command ports ready-port`, "ready-path ready-timeout-ms"),
+    "runtime process stop": route(0, "id lease-token", "grace-ms"),
+    "runtime process register": route(0, "kind owner", "lease-ms budget-json project-id run pid process-group-id owner-pid work check operation stdout stderr harness dispatch-barrier role state-dir adapter-executable"),
+    "runtime process confirm": route(0, "id lease-token pid", "owner-pid lease-ms process-group-id"),
+    "runtime process heartbeat": route(0, "id lease-token", "lease-ms"),
+    "runtime process admission": route(0, "id lease-token owner state-dir", "daemon-id operation-id operation native-session-id prompt-sha256"),
+    "runtime process release-turn": route(0, "id lease-token owner daemon-id", "operation-id observation-file"),
+    "runtime process finish": route(0, "id lease-token state", "reason", "", "", { state: ["stopped", "failed"] }),
+    "runtime process status": route(0),
+    "runtime process reconcile": route(0, "owner", "grace-ms"),
+    "lane status": route(0, project, "lane"),
+    "lane waiters": route(0, project, "lane"),
+    "lane waiter cancel": route(0, `${project} lane ${worker} reason`),
+    "lane workspace set": route(0, `${project} lane path`, "branch"),
+    "lane workspace check": route(0, `${project} lane path`),
+    "lane lock acquire": route(0, `${project} lane ${worker} reason`, "path ttl"),
+    "lane lock heartbeat": route(0, `${project} lane ${worker}`, "path lease-token ttl"),
+    "lane lock release": route(0, `${project} lane ${worker} reason`, "path lease-token"),
+    "lane lock status": route(0, `${project} lane`),
+    "lane lock wait": route(0, `${project} lane ${worker}`, "path timeout poll-interval"),
+    "lane lock wait-acquire": route(0, `${project} lane ${worker} reason`, "path timeout poll-interval ttl"),
+    "merge-queue status": route(0, "", scoped),
+    "merge-queue next": route(0, worker, `${scoped} path`),
+    "merge-queue claim": route(1, worker, `${scoped} path`),
+    "merge-queue wait-next": route(0, worker, `${scoped} path timeout poll-interval acquire-lock`),
+    "merge-queue complete": route(1, `${worker} summary`, `${scoped} path`),
+    "merge-queue fail": route(1, `${worker} reason requeue`, `${scoped} path`),
+    "merge-queue note": route(1, `${worker} summary`, scoped),
+    "merge-queue cancel": route(1, "reason", `${scoped} worker-id path`, "force"),
+    "merge serve": route(0, "agent-profile", "poll-seconds max-parallel-projects", "once"),
+    "merge server status": route(0),
+    "merge server stop": route(1),
+    "merge apply": route(1, `${project} work`),
+    "merge repair": route(1, project),
+    "merge request status": route(1, project),
+    "merge request route": route(1, `${project} mode reason`, "", "", "", { mode: ["same_session", "server"] }),
+    "merge status": route(0, project, "path"),
+    "merge bundle status": route(0, project, "path"),
+    "merge bundle claim": route(0, `${project} ${worker}`, "path"),
+    "merge bundle complete": route(0, `${project} ${worker} summary`, "path"),
+    "merge bundle fail": route(0, `${project} ${worker} reason requeue`, "path"),
+    "merge one-shot": route(0, `${project} ${worker}`, "path"),
+    "merge-worker status": route(0, project),
+    "merge-worker start": route(0, `${project} ${worker}`, "path branch"),
+    "merge-worker stop": route(0, `${project} reason`, worker),
+    "engine install": route(0, "", "", "force"),
+    "engine list": route(0),
+    "engine info": route(0, "", "package version"),
+    "engine resolve": route(0, "", "root project-root"),
+    "engine doctor": route(0, "", "root project-root"),
+    "engine bind-run": route(1, `${project} engine-version reason`, "package integrity-checksum"),
+    "canon register": route(0, "root"),
+    "canon status": route(0, "", "root"),
+    "canon resolve": route(0, "", "root"),
+    "migration impact": route(0, project, "target-version mode"),
+    "migration plan": route(0, project, "source-version target-version run backup-path backup-created-at"),
+    "migration report": route(0, project, "source-version target-version run backup-path backup-created-at"),
+    "migration verify": route(0, "file"),
+    "migration apply": route(0, project, "source-version target-version run backup-path backup-created-at file"),
+    "storage migrate-writer": route(0, "database backup", "", "offline"),
+    "cleanup scan": route(0, project),
+    "cleanup apply": route(0, `${project} plan-file reason`, "", "force"),
+    "worktree plan": route(0, "protocol-id", scoped),
+    "worktree create": route(0, "protocol-id branch base path", scoped),
+    "worktree status": route(0, "protocol-id", scoped),
+    "worktree bootstrap": route(0, "protocol-id", scoped),
+    "worktree close": route(0, "protocol-id mode", scoped, "", "", { mode: ["keep", "remove"] }),
+    "codex home plan": route(0, project, "profile source-home target-home"),
+    "codex home init": route(0, project, "profile source-home target-home"),
+    "codex home status": route(0, project, "profile"),
+    "codex home print-env": route(0, project, "profile"),
+    "codex home remove": route(0, `${project} mode`, "profile"),
+    "codex hooks print": route(0, project, "target profile"),
+    "codex hooks status": route(0, project, "target profile"),
+    "codex hooks install": route(0, project, "target profile", "yes"),
+    "codex hooks remove": route(0, project, "target profile", "yes"),
+    "codex hook handle": route(0, "event", scoped),
+    "zcode hook handle": route(0, project),
+    "zcode invocation prepare": route(0),
+    "zcode event handle": route(0, project),
+    "zcode usage ingest": route(0, project),
+    "grok event handle": route(0, project),
+    "grok usage ingest": route(0, project),
+    "opencode event handle": route(0, project),
+    "opencode usage ingest": route(0, project),
+    "droid event handle": route(0, project),
+    "droid usage ingest": route(0, project),
+    "agy event handle": route(0, project),
+    "agy usage ingest": route(0, project),
+    "stat usage": route(0, `${project} run`, "group-by session stage"),
+    "stat run sessions ls": route(0, `${project} run`),
+    "id next": route(0, `${project} type slug`, "", "", "", { type: ["protocol", "prt", "run", "work", "wrk"] }),
+    "integration cmux status": route(0, project),
+    "dashboard data": route(0, "", "project project-root protocol", "global"),
+    "dashboard render": route(0, "", "project project-root protocol output format"),
+    "dashboard render-global": route(0, "", "output format"),
+    "dashboard open": route(0, "", "project project-root protocol viewer format"),
+    "dashboard refresh": route(0, "", "project project-root protocol open format output", "all"),
+    "dashboard refresh-global": route(0, "", "output format"),
+    "schema validate": route(0, "schema file", "schema-dir project-root run"),
+    "memory permissions preflight": route(0, "root memory-bank flow mode", "tasks")
+};
+export function contextualPathOptionsForLifecycle(operation) {
+    const key = operation === "recovery_accept" ? "run recovery accept" : operation.replaceAll("_", " ");
+    return new Set(commandInputs[key]?.contextualPaths ?? []);
+}
+const flag = "__dd_flow_flag__";
+const positiveInteger = new Set(words("limit lease-ms pid owner-pid process-group-id ready-timeout-ms max-parallel-projects expected-revision"));
+const nonnegativeInteger = new Set(words("after generation wait-ms grace-ms available-slots"));
+const positiveNumber = new Set(words("ttl poll-interval poll-seconds"));
+const booleans = new Set(words("write close-sessions cancel-queue release-locks user-required requeue acquire-lock"));
+export function prepareCommandRoute(args) {
+    const parsed = parseCommandArgs(args);
+    const key = Object.keys(commandInputs).filter(key => key.split(" ").every((part, index) => parsed.positional[index] === part))
+        .sort((a, b) => b.split(" ").length - a.split(" ").length)[0];
+    const reject = (message, parameter) => { throw new AppError("usage", message, 2, { phase: "prepare", effect: "no_effect", recoverable: true, ...(parameter ? { parameter } : {}) }); };
+    if (!key)
+        return reject("Unknown command; use dd-flow --help");
+    const contract = commandInputs[key];
+    if (contract.retired)
+        reject(contract.retired);
+    const prefixLength = key.split(" ").length;
+    const positionCount = parsed.positional.length - prefixLength;
+    if (positionCount < contract.positions[0] || positionCount > contract.positions[1])
+        reject(`${key} expects ${contract.positions[0] === contract.positions[1] ? contract.positions[0] : `${contract.positions[0]}..${contract.positions[1]}`} positional argument(s)`);
+    for (const [name, values] of parsed.options) {
+        if (key.startsWith("merge-queue ") && name === "session-id")
+            reject("--session-id is no longer accepted on merge-queue commands; use --worker-id", name);
+        const upgrade = ["compatibility-mode", "mb-upgrade-mode"].includes(name);
+        if (upgrade && !isUpgradeAllowlisted(args))
+            reject(`${key} does not support explicit upgrade mode`, name);
+        if (!upgrade && !contract.values.includes(name) && !contract.switches.includes(name))
+            reject(`${key} does not accept --${name}`, name);
+        if (values.length > 1 && !contract.repeatable.includes(name))
+            reject(`--${name} must occur once`, name);
+        for (const value of values) {
+            if (contract.switches.includes(name) || name === "mb-upgrade-mode") {
+                if (value !== flag)
+                    reject(`--${name} is a switch and does not take a value`, name);
+                continue;
+            }
+            if (value === flag || !value.trim())
+                reject(`--${name} requires a non-empty value`, name);
+            if (name === "compatibility-mode" && value !== "mb-upgrade")
+                reject("--compatibility-mode must be mb-upgrade", name);
+            const choices = contract.enums[name];
+            if (choices && !choices.includes(key === "id next" && name === "type" ? value.toLowerCase() : value))
+                reject(`--${name} must be ${choices.join(" or ")}`, name);
+            if (booleans.has(name) && !["true", "false"].includes(value))
+                reject(`--${name} must be true or false`, name);
+            const number = Number(value);
+            if (positiveInteger.has(name) && (!/^[0-9]+$/.test(value) || !Number.isSafeInteger(number) || number <= 0)
+                || nonnegativeInteger.has(name) && (!/^[0-9]+$/.test(value) || !Number.isSafeInteger(number) || number < 0)
+                || positiveNumber.has(name) && (!Number.isFinite(number) || number <= 0)
+                || name === "timeout" && (!Number.isFinite(number) || number < 0)
+                || name === "available-slots" && number > 15)
+                reject(`Invalid numeric value for --${name}`, name);
+        }
+    }
+    for (const name of contract.required)
+        if (!parsed.options.has(name))
+            reject(`Missing required option: --${name}`, name);
+    for (const aliases of [
+        ["root", "project-root"], ["payload-file", "json-file"],
+        ["payload-file", "payload-json", "payload-base64"], ["semantic-file", "data", "result-file", "result-stdin"],
+        ["stage-report", "dashboard"], ["task-file", "plan-item"], ["project", "project-root"],
+        ["intake-file", "intake-stdin", "context-file"]
+    ]) {
+        const present = aliases.filter(name => parsed.options.has(name));
+        if (present.length > 1)
+            reject(`Use only one of ${present.map(name => `--${name}`).join(", ")}`);
+    }
+    if (contract.values.includes("retry-check") && parsed.options.has("retry-check") !== parsed.options.has("reason"))
+        reject("--retry-check and --reason must be supplied together");
+    // Retain the dispatcher's historic offsets for nested action positions.
+    const family = parsed.positional[0];
+    const singleWord = ["status", "version", "transition"].includes(family);
+    return { key, family, command: singleWord ? undefined : parsed.positional[1], parsed: { options: parsed.options, positional: parsed.positional.slice(singleWord ? 1 : 2) } };
+}

package/dist/cli/help.js

@@ -242,7 +242,7 @@ Usage:
   dd-flow stage finish <RUN-ID|RUN-short-id> --project-root <root> --stage <name> [--semantic-file <RUN-local-json>] --json
   dd-flow stage finish <RUN-ID|RUN-short-id> --project-root <root> --stage specify (--result-file <RUN-local-specify.json>|--result-stdin) --outcome <specified|failed|cancelled> --json
 
-stage start is the worker's first practical flow command. It performs deterministic setup and returns a ready-to-use, stage-specific work packet with trusted runtime facts, compatibility and permission preflight, aliases, write boundary and exact lifecycle commands. A material user question uses stage pause, not stage finish: pause leaves the same stage, Work, Session and attempt open and returns the exact resume command. Engine, harness and environment failures use stage block and never create HITL. On the next Turn, pass a complete user answer to stage resume, or repair an external blocker and call its returned stage unblock command. stage fanout is read-only orchestration state plus the stage's deterministic Work materialization action for an external runner; it never makes product decisions. stage finish is reserved for actual stage completion and generates the final deterministic reports. Generated lifecycle commands include DD_FLOW_HOME when the RUN uses a non-default runtime.`
+stage start is the worker's first practical flow command. It performs deterministic setup and returns a ready-to-use, stage-specific work packet with trusted runtime facts, compatibility and permission preflight, aliases, write boundary and exact lifecycle commands. Managed commands use scoped RUN/Work aliases and @project; their internal invocation UUID is bound by the native hook and is intentionally not model-facing. @ aliases apply only to declared dd-flow path arguments, not to shell tools. A material user question uses stage pause, not stage finish: pause leaves the same stage, Work, Session and attempt open and returns the exact resume command. Engine, harness and environment failures use stage block and never create HITL. On the next Turn, pass a complete user answer to stage resume, or repair an external blocker and call its returned stage unblock command. stage fanout is read-only orchestration state plus the stage's deterministic Work materialization action for an external runner; it never makes product decisions. stage finish is reserved for actual stage completion and generates the final deterministic reports. Unmanaged operator calls retain explicit project and runtime selection.`
     ],
     [
         "work",

package/dist/cli/hook-ingress.js

@@ -0,0 +1,82 @@
+import { fileURLToPath } from "node:url";
+import { performance } from "node:perf_hooks";
+import { parseCommandArgs, parseLifecycleCommand, lifecycleCommandFromPayload } from "../services/lifecycle-command.js";
+import { errorRecord, AppError } from "../shared/errors.js";
+import { parseJsonObject } from "../shared/json.js";
+const workerFile = fileURLToPath(import.meta.url);
+const ingressBudgetMs = 20_000; // Native host timeout is 30s; this includes cold module/DB open.
+/** Lightweight entry: unrelated hooks never load the router or open storage. */
+export async function runHookIngress(args) {
+    try {
+        const parsed = parseCommandArgs(args.slice(3));
+        for (const [key, values] of parsed.options)
+            if (!["event", "project-root", "json"].includes(key) || values.length !== 1)
+                throw new AppError("usage", `Invalid hook option: ${key}`, 2);
+        const event = parsed.options.get("event")?.[0];
+        if (!event?.trim() || event === "__dd_flow_flag__" || parsed.positional.length)
+            throw new AppError("usage", "Hook ingress requires --event with a value", 2);
+        const root = parsed.options.get("project-root")?.[0];
+        if (root !== undefined && (!root.trim() || root === "__dd_flow_flag__"))
+            throw new AppError("usage", "--project-root requires a value", 2);
+        if (parsed.options.has("json") && parsed.options.get("json")?.[0] !== "__dd_flow_flag__")
+            throw new AppError("usage", "--json does not take a value", 2);
+        let stdin = "";
+        for await (const chunk of process.stdin) {
+            stdin += String(chunk);
+            if (Buffer.byteLength(stdin) > 1_048_576)
+                throw new AppError("native_hook_response_invalid", "Hook input exceeds 1 MiB", 1);
+        }
+        const payload = parseJsonObject(stdin || "{}", "native hook stdin");
+        const command = lifecycleCommandFromPayload(payload);
+        if (event !== "PreToolUse" || !command || parseLifecycleCommand(command).kind === "none") {
+            process.stdout.write("{}\n");
+            return 0;
+        }
+        const started = performance.now();
+        const { invokeNativeHook } = await import("../harness-runtime/lib/native-hook-command.mjs");
+        const result = await invokeNativeHook({ bin: workerFile, args, payload, home: process.env.DD_FLOW_HOME, timeoutMs: ingressBudgetMs });
+        const { timing, ...output } = result;
+        process.stderr.write(`${JSON.stringify({ kind: "hook_ingress", total_ms: Math.round(performance.now() - started), ...timing })}\n`);
+        process.stdout.write(`${JSON.stringify(output)}\n`);
+        return 0;
+    }
+    catch (error) {
+        const record = errorRecord(error);
+        process.stderr.write(`${JSON.stringify({ ok: false, error: record })}\n`);
+        return record.exitCode;
+    }
+}
+// A bounded CLI subprocess, not a detached writer: its successful reply follows COMMIT.
+if (process.argv[1] === workerFile) {
+    try {
+        let stdin = "";
+        for await (const chunk of process.stdin)
+            stdin += String(chunk);
+        const payload = parseJsonObject(stdin, "native hook stdin");
+        const started = performance.now();
+        const { verifyCodexHookDelivery } = await import("../services/codex-hook-delivery.js");
+        const proof = await verifyCodexHookDelivery(process.env, payload);
+        const verified = performance.now();
+        const [{ createContext }, { handleCodexHook }] = await Promise.all([import("../runtime/context.js"), import("../services/hooks.js")]);
+        const loaded = performance.now();
+        const context = createContext(process.env, "hook");
+        const opened = performance.now();
+        try {
+            if (proof)
+                context.codexHookProof = proof;
+            const parsed = parseCommandArgs(process.argv.slice(5));
+            const projectRoot = parsed.options.get("project-root")?.[0];
+            const result = handleCodexHook(context, { event: "PreToolUse", ...(projectRoot ? { projectRoot } : {}), stdin });
+            process.stdout.write(`${JSON.stringify({ ...(result.hookSpecificOutput ? { hookSpecificOutput: result.hookSpecificOutput } : {}), timing: {
+                    verify_ms: Math.round(verified - started), load_ms: Math.round(loaded - verified), open_ms: Math.round(opened - loaded), receipt_ms: Math.round(performance.now() - opened)
+                } })}\n`);
+        }
+        finally {
+            context.db.close?.();
+        }
+    }
+    catch (error) {
+        process.stderr.write(`${JSON.stringify({ ok: false, error: errorRecord(error) })}\n`);
+        process.exitCode = 1;
+    }
+}

package/dist/cli/input-preparation.js

@@ -0,0 +1,115 @@
+import fs from "node:fs";
+import path from "node:path";
+import { AppError, isAppError } from "../shared/errors.js";
+import { validateSchema } from "../services/schema-validation.js";
+export function prepareError(error, input = {}) {
+    if (isAppError(error)) {
+        // A malformed user input is safely correctable.  A broken schema registry,
+        // binding, or storage is not; do not disguise infrastructure damage as a
+        // retryable command typo.
+        const inputErrorCodes = new Set([
+            "usage", "validation", "schema_validation", "invalid_json", "not_found",
+            "path_escape", "input_file_missing", "input_file_not_regular", "input_file_unreadable",
+            "response_file_parent_invalid", "response_file_invalid", "context_checksum_mismatch", "invalid_run_config_state", "invalid_work_state", "invalid_stage_state", "runtime_budget_invalid", "runtime_scope_manifest_invalid", "runtime_scope_resume_invalid",
+            "fork_path_conflict", "fork_output_not_empty", "fork_checkpoint_invalid", "fork_engine_unavailable", "snapshot_missing",
+            "repair_check_declaration_missing", "review_repair_check_required", "review_check_reference_unknown", "semantic_status_inconsistent", "migration_report_invalid", "controller_context_missing", "snapshot_output_inside_runtime"
+        ]);
+        if (!inputErrorCodes.has(error.code) && error.details.phase !== "prepare")
+            throw error;
+        throw new AppError(error.code, error.message, 2, {
+            ...error.details,
+            phase: "prepare",
+            effect: "no_effect",
+            recoverable: true,
+            ...input
+        });
+    }
+    const code = error?.code;
+    if (typeof input.file !== "string" || !["ENOENT", "EACCES", "EPERM", "EISDIR", "ENOTDIR", "ELOOP", "ENAMETOOLONG"].includes(code ?? ""))
+        throw error;
+    throw new AppError("input_file_unreadable", `Cannot read input file${typeof input.file === "string" ? `: ${input.file}` : ""}`, 2, {
+        phase: "prepare", effect: "no_effect", recoverable: true, ...input, cause: code ?? String(error)
+    });
+}
+export function prepareTextFile(file, label = "input file") {
+    const prepared = prepareFileBytes(file, label);
+    return { file: prepared.file, text: prepared.bytes.toString("utf8") };
+}
+export function prepareFileBytes(file, label = "input file") {
+    const absolute = path.resolve(file);
+    let descriptor;
+    try {
+        descriptor = fs.openSync(absolute, fs.constants.O_RDONLY | fs.constants.O_NONBLOCK);
+        const stat = fs.fstatSync(descriptor);
+        if (!stat.isFile()) {
+            throw new AppError("input_file_not_regular", `${label} must be a readable regular file: ${absolute}`, 2, { file: absolute, label });
+        }
+        return { file: absolute, bytes: fs.readFileSync(descriptor) };
+    }
+    catch (error) {
+        if (error?.code === "ENOENT") {
+            throw new AppError("input_file_missing", `${label} does not exist: ${absolute}`, 2, {
+                phase: "prepare", effect: "no_effect", recoverable: true, file: absolute, label
+            });
+        }
+        return prepareError(error, { file: absolute, label });
+    }
+    finally {
+        if (descriptor !== undefined)
+            fs.closeSync(descriptor);
+    }
+}
+export function prepareJsonText(text, input) {
+    try {
+        return { file: input.file, text, value: JSON.parse(text) };
+    }
+    catch {
+        // Keep the established public code so agents can recognise this as a
+        // safe correction-and-retry condition.
+        throw new AppError("invalid_json", `Invalid JSON in ${input.label ?? "input"}: ${input.file}`, 2, {
+            phase: "prepare", effect: "no_effect", recoverable: true, file: input.file, label: input.label ?? "input",
+            cause: "Invalid JSON syntax"
+        });
+    }
+}
+export function prepareJsonFile(file, label = "input JSON") {
+    const prepared = prepareTextFile(file, label);
+    return prepareJsonText(prepared.text, { file: prepared.file, label });
+}
+export function prepareJsonSchema(file, label, schema) {
+    const prepared = prepareJsonFile(file, label);
+    try {
+        validateSchema({ ...schema, file: prepared.file, data: prepared.value });
+    }
+    catch (error) {
+        return prepareError(error, { file: prepared.file, label });
+    }
+    return prepared;
+}
+/** Read-only destination check; execution still handles filesystem races. */
+export function prepareOutputFile(value) { return prepareOutput(value, false); }
+export function prepareOutputDirectory(value) { return prepareOutput(value, true); }
+function prepareOutput(value, directory) {
+    const file = path.resolve(value);
+    try {
+        let ancestor = directory ? file : path.dirname(file);
+        while (!fs.existsSync(ancestor) && path.dirname(ancestor) !== ancestor)
+            ancestor = path.dirname(ancestor);
+        if (!fs.statSync(ancestor).isDirectory())
+            throw new AppError("validation", "Output parent must be a directory", 2);
+        fs.accessSync(ancestor, fs.constants.W_OK | fs.constants.X_OK);
+        if (fs.existsSync(file)) {
+            const stat = fs.statSync(file);
+            if (directory ? !stat.isDirectory() : !stat.isFile())
+                throw new AppError("validation", directory ? "Output must name a directory" : "Output must name a regular file", 2);
+            fs.accessSync(file, fs.constants.W_OK | (directory ? fs.constants.X_OK : 0));
+        }
+        return file;
+    }
+    catch (error) {
+        const code = error?.code;
+        if (["ENOENT", "EACCES", "EPERM", "ENOTDIR", "ELOOP", "ENAMETOOLONG"].includes(code ?? ""))
+            return prepareError(new AppError("validation", "Output destination is not writable or has an invalid parent", 2, { cause: code }), { file, parameter: "output" });
+        return prepareError(error, { file, parameter: "output" });
+    }
+}