@deksden-com/dd-flow-cli 0.9.0-beta.13 → 0.9.0-beta.133

package/dist/cli/help.js

@@ -1,4 +1,37 @@
 const helpPages = new Map([
+    ["runtime scope", `Usage:
+  dd-flow runtime scope fence --scope-id EVAL_ID --request-id ID --json
+  dd-flow runtime scope status --scope-id EVAL_ID --json
+  dd-flow runtime scope stop --scope-id EVAL_ID --request-id ID --json
+  dd-flow runtime scope control --scope-id EVAL_ID --request-id ID --mode pause|stop [--manifest-json JSON] --json
+  dd-flow runtime scope resume --scope-id EVAL_ID --request-id ID --generation N --capture-key SHA256 --json
+  dd-flow runtime scope reconcile --scope-id EVAL_ID --generation N --request-id ID --json
+
+Use the EVAL manifest's retained DD_FLOW_RESOURCE_HOME. Commands select exactly
+one scope across its registered runtime homes; neighboring scopes are untouched.
+fence durably blocks new provider turns and owned baseline checks. It does not
+stop existing work. status reports retained ownership, not proof of settlement.
+stop fences first and requests owned daemon-tree and baseline-process cleanup.
+Inspect settled and each node's evidence: ok alone does not prove cleanup.
+Unproven ownership or cleanup remains pending; repeat stop to observe settlement.
+The fence/stop route is terminal cancellation and has no resume command.
+control records recoverable scope intent and starts a detached drain owner.
+The EVAL resolver supplies a runtime-scope-manifest@1 declaration with the source
+manifest path, SHA-256 and execution IDs, including queued executions. Declaration
+changes are rejected. resume accepts the exact captured generation and starts
+detached recovery preparation. It does not yet release scope admission: inspect
+dispatch_blocked and pending reasons; accepted preparation is not resumed work.
+RUN pause/stop/resume uses dd-flow run control.`],
+    ["storage", `Usage:
+  dd-flow storage migrate-writer --database ABSOLUTE_DB --backup NEW_ABSOLUTE_FILE --offline --json
+
+Drain all local and external runtime owners before using --offline. This command
+migrates one existing database, not a whole runtime or retained provider Session.
+It refuses unresolved ownership rows, preserves a verified WAL-safe backup, and
+fences unaware old writers. It does not initialize the default DD_FLOW_HOME.
+The backup path must be new; existing backups are never overwritten. An exact
+retry of a committed migration returns its receipt after verifying the backup.
+If no committed receipt exists, retain the failed backup and choose a new path.`],
     [
         "",
         `dd-flow - mechanical control layer for dd-flow workflows
@@ -33,11 +66,14 @@ Core commands:
   session register/status/stop  Register flow sessions and stop workers.
   dashboard data/render/open/refresh Render, refresh, open, and inspect project/global dashboards.
   schema validate             Validate canonical dd-flow JSON data contracts.
+  storage migrate-writer      Explicitly back up and fence a drained SQLite store.
+  runtime scope fence/status/stop Fence, inspect, or cancel one retained EVAL scope.
   memory permissions preflight Check Memory Bank write/read permissions.
   integration cmux status       Inspect optional cmux integration.
   codex home/hooks/hook         Manage Codex homes, hooks, and hook events.
   zcode event/usage             Ingest trusted zcode-acp lifecycle and usage evidence.
   grok event/usage              Ingest trusted Grok Build lifecycle and usage evidence.
+  droid event/usage             Ingest trusted Factory Droid lifecycle and physical usage evidence.
   opencode event/usage          Ingest trusted OpenCode lifecycle and usage evidence.
   agy event/usage               Ingest trusted Antigravity CLI lifecycle and usage evidence.
   worktree plan/create/status   Record Worktrunk-backed feature worktrees.
@@ -152,12 +188,18 @@ Usage:
   dd-flow run start --project-root <root> [--workspace-root <checkout>] --flow-kind <kind> --subject-type <type> --subject-id <id> --slug <slug> [--preset compact|normal|full] [--task-profile-file <file>] [--protocol-override-file <file>] [--flag key=value] [--next-action <text>] --json
   dd-flow id next --type protocol|run --project-root <root> --slug <slug> --json
   dd-flow run status <RUN-ID|RUN-short-id> --project-root <root> --json
+  dd-flow run control status --run <RUN-ID> --project-root <root> --json
+  dd-flow run control reconcile --run <RUN-ID> --project-root <root> --control-id <ID> --request-id <ID> --json
+  dd-flow run drive launch --run <RUN-ID> --project-root <root> --request-id <id> --context-file <file> --context-sha256 <sha256> [--stop-after <stage>] [--capture-root <directory>] --json
+  dd-flow run drive status --run <RUN-ID> --project-root <root> [--after <sequence>] --json
   dd-flow run list --project-root <root> --json
-  dd-flow run prepare-vnext-specify --project-root <root> --slug <slug> --json
-  dd-flow run snapshot create <RUN-ID|RUN-short-id> (--stage-entry <stage>|--candidate) --project-root <root> --output <directory> --json
-  dd-flow run snapshot restore --snapshot <directory> --project-root <prepared-root> --json
+  dd-flow run prepare-vnext-specify --project-root <root> --slug <slug> [--execution-routing-file <file>] --json
+  dd-flow run recovery inspect|begin|seal|capture|resume <RUN-ID|RUN-short-id> --project-root <root> --json
+  dd-flow run snapshot create <RUN-ID|RUN-short-id> (--stage-entry <stage>|--candidate|--incomplete|--recovery-id <RCV-ID>) --project-root <root> --output <directory> --json
+  dd-flow run snapshot restore --snapshot <directory> --project-root <prepared-root> [--recovery-id <RCV-ID>] --json
   dd-flow run snapshot bootstrap create --project-root <root> --output <directory> --json
   dd-flow run snapshot bootstrap restore --snapshot <directory> --project-root <prepared-root> --json
+  dd-flow run fork --from <sealed-stage-entry-snapshot> --output <empty-directory> --engine-version <exact-version> --request-id <id> [--integrity-checksum <sha256>] --json
   dd-flow run timeline <RUN-ID|RUN-short-id> --project-root <root> --json
   dd-flow stat usage --run <RUN-ID|RUN-short-id> --project-root <root> [--stage <stage[,stage...]>] [--session <session-id>] --json
   dd-flow stat run sessions ls --run <RUN-ID|RUN-short-id> --project-root <root> --json
@@ -169,7 +211,13 @@ Usage:
 
 RUN-* is the execution envelope for one concrete flow launch. Semantic truth remains in protocol, experiment, DEF, scenario, evidence, and Memory Bank documents. New run artifacts are stored under DD_FLOW_HOME/projects/<PRJ-ID-slug>/runs/<RUN-ID-slug>/ with one run.json projection and an append-only timeline.jsonl. Timeline is the compact full run report: summary is always present, while --hide may suppress bulky sections. Use \`dd-flow stat usage --run …\` to reread registered local Codex transcript counters and tool-call facts and refresh the current usage projection; unavailable data is explicit rather than zero.
 
-run prepare-vnext-specify allocates an otherwise unstarted vNext RUN for the canonical SPECIFY entry checkpoint. run snapshot is the eval-only checkpoint boundary: it snapshots one quiescent RUN, its dedicated DD_FLOW_HOME, and the exact project tree including its Git repository, then restores them into a fresh dedicated runtime. It is not a general runtime backup command and fails closed for a shared runtime.
+run start and prepare-vnext-specify accept --execution-routing-file for vNext RUNs: dd-flow/execution-routing@1 with an execution object selects the complete routing policy from existing agent-profiles. RUN creation freezes the input and selected profiles without changing project settings.
+run snapshot restore also accepts --execution-routing-file for a new stage-entry experiment. Its fresh DD_FLOW_HOME may contain only agent-profiles and the empty database; selected profiles are read before import, previous RUN policy is archived, and existing Work overrides must resolve against the selected frozen profiles. Recovery imports reject this option.
+run snapshot restore and run fork accept --operational-decision-file for an explicitly accepted decision bound to the new stage-entry experiment. Store the input outside fork output; its bytes are bound to the idempotent request. A snapshot with a scoped decision cannot grant it to another execution implicitly. Recovery retains the original decision and rejects replacement.
+run fork restores one sealed stage-entry snapshot to an isolated project and DD_FLOW_HOME, archives source authority, then binds an exact engine only in that copy. It is idempotent by request ID and output receipt; it never resumes a provider session or changes its source RUN.
+run prepare-vnext-specify allocates an otherwise unstarted vNext RUN for the canonical SPECIFY entry checkpoint. run recovery makes an interrupted RUN read-only, requires an explicit settled-tree receipt, captures immutable recovery evidence, then explicitly returns delegated Work to the ready graph. run snapshot is the eval-only checkpoint boundary: it snapshots one quiescent RUN, its dedicated DD_FLOW_HOME, and the exact project tree including its Git repository, then restores them into a fresh dedicated runtime. It is not a general runtime backup command and fails closed for a shared runtime.
+
+Managed drive is not yet native-provider qualified. With --capture-root, its detached controller fences RUN writers and captures each completed Stage before dispatching its successor. The capture root must be outside the runtime, project and workspace. Status events expose boundary_captured receipts; capturing means writers are still fenced, and capture_failed retains the fence for operator reconciliation. External snapshot creation is rejected while a managed controller owns a live RUN.
 
 Examples:
   dd-flow run start --project-root "$PWD" --flow-kind mb_sdlc --subject-type protocol --subject-id PRT-001-demo --slug demo --json
@@ -184,16 +232,22 @@ Examples:
 Usage:
   dd-flow stage start <RUN-ID|RUN-short-id> --project-root <root> --stage <name> [--dir <NN-stage-slug>] [--require-session-binding] --json
   dd-flow stage start --bootstrap --project-root <root> --stage specify --subject <safe-subject> (--intake-file <path>|--intake-stdin) [--require-session-binding] --json
-  dd-flow stage pause <RUN-ID|RUN-short-id> --project-root <root> --stage <name> --work <WORK-ID> --question-stdin --json
-  dd-flow stage resume <RUN-ID|RUN-short-id> --project-root <root> --stage <name> --work <WORK-ID> --answer-stdin --json
-  dd-flow stage block <RUN-ID|RUN-short-id> --project-root <root> --stage <name> --work <WORK-ID> --kind engine|harness|environment --code <code> --summary-stdin [--retryable] --json
+  dd-flow stage pause <RUN-ID|RUN-short-id> --project-root <root> --stage <name> --work <WORK-ID> (--question-file <path>|--question-stdin) --json
+  dd-flow stage resume <RUN-ID|RUN-short-id> --project-root <root> --stage <name> --work <WORK-ID> (--answer-file <path>|--answer-stdin) --json
+
+Managed resume commands restore the accepted answer file from runtime state. Execute the returned command without adding an answer path or recreating the answer. The explicit answer flags above are for unmanaged calls.
+Path aliases @project, @workspace and @run are supported only in declared CLI path parameters and require a uniquely bound context. File-writing tools use physical paths. Both --option value and --option=value are accepted; quoted or escaped aliases are normalized identically. Pre-RUN bootstrap paths and external schema directories require physical paths.
+An aggregate CODE/CODE-REVIEW failure may return continuation.kind=repair_required: its repair Work is already registered. End the coordinator turn and let the controller dispatch the fresh child; do not recreate the repair. A recovery retry uses --retry-check <receipt> --reason-file <recovery.json>, containing only {"reason":"actual environment recovery evidence"}. Legacy --reason remains accepted, but cannot be combined with --reason-file. A needs_input continuation is not yet executable: write its requested file first, then use command_after_input.
+  dd-flow stage block <RUN-ID|RUN-short-id> --project-root <root> --stage <name> --work <WORK-ID> --kind engine|harness|environment --code <code> (--summary-file <path>|--summary-stdin) [--retryable] --json
   dd-flow stage unblock <RUN-ID|RUN-short-id> --project-root <root> --stage <name> --work <WORK-ID> --json
   dd-flow stage fanout status <RUN-ID|RUN-short-id> --project-root <root> --stage <name> --json
   dd-flow stage fanout dispatch <RUN-ID|RUN-short-id> --project-root <root> --stage <name> --json
+  dd-flow stage fanout reconcile <RUN-ID> --project-root <root> --stage <name> --observations-file <native-observations.json> --json
+  dd-flow stage native observe <RUN-ID> --project-root <root> --stage <name> --observations-file <native-observations.json> --json
   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",
@@ -203,8 +257,9 @@ Usage:
   dd-flow work ls (--run <RUN-ID>|--parent <WORK-ID>) [--ready] --json
   dd-flow work show <WORK-ID> --json
   dd-flow work start <WORK-ID> --project-root <root> --json
+  dd-flow work launch <WORK-ID> [--stage <name>] --json
   dd-flow work finish <WORK-ID> (--result-file <path>|--result-stdin) --project-root <root> --json
-  dd-flow work repair add --run <RUN-ID> (--from-check <CHECK-ID>|--from-unresolved <gap> --verification-file <file>) --origin-work <WORK-ID>... --task-stdin --project-root <root> --json
+  dd-flow work repair add --run <RUN-ID> (--from-check <CHECK-ID>|--from-unresolved <gap> --verification-file <file>) --origin-work <WORK-ID>... (--task-file <path>|--task-stdin) --project-root <root> --json
 
 CODE workers receive their full accepted packet from work start. work finish validates the result and executes the packet's focused checks before completion. A failed aggregate CODE gate or unresolved semantic verification creates a repair Work from the selected completed origin context and retained evidence. Its planned write areas are coordination hints only; the repair may change any necessary project file inside its RUN workspace.`
     ],
@@ -537,17 +592,38 @@ handler resolves the registered project from cwd. The option is only a manual
 override.
 
 Managed homes isolate dd-flow hooks while sharing selected Codex state from the source home.`
+    ],
+    [
+        "zcode hook",
+        `dd-flow zcode hook - handle a synchronous native ZCode PreToolUse callback
+
+Usage:
+  dd-flow zcode hook handle --project-root <root> --json
+
+The managed ZCode native hook supplies the callback on stdin. It records the
+receipt before returning a rewritten tool input with --hook-event-id.`
     ],
     [
         "zcode event",
-        `dd-flow zcode event - ingest a zcode-acp session/update notification
+        `dd-flow zcode event - ingest a zcode-acp session/update notification as evidence
 
 Usage:
   dd-flow zcode event handle --project-root <root> --json
   dd-flow zcode usage ingest --project-root <root> --json
 
-Both payloads are read from stdin. The event adapter retains lifecycle identity;
-the usage adapter retains cumulative provider counters for RUN accounting.`
+Both payloads are read from stdin. Native hooks own lifecycle admission; ACP
+events and usage retain secondary evidence for RUN accounting.`
+    ],
+    [
+        "droid event",
+        `dd-flow droid event - ingest a controlled Factory Droid Execute hook
+
+Usage:
+  dd-flow droid event handle --project-root <root> --json
+  dd-flow droid usage ingest --project-root <root> --json
+
+Reads trusted adapter JSON from stdin. Usage requires physical_session scope and explicit completeness.
+`
     ],
     [
         "opencode event",

package/dist/cli/hook-ingress.js

@@ -0,0 +1,78 @@
+import { fileURLToPath } from "node:url";
+import { performance } from "node:perf_hooks";
+import { parseCommandArgs, parseLifecycleCommand, lifecycleCommandFromPayload, continuationCommand } 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.
+const { hookBudget, readNativeHookInput } = await import("../harness-runtime/lib/native-hook-command.mjs");
+/** 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);
+        const budget = hookBudget(ingressBudgetMs, process.env.DD_FLOW_HOOK_DEADLINE_AT ? Number(process.env.DD_FLOW_HOOK_DEADLINE_AT) : null);
+        const stdin = await readNativeHookInput(process.stdin, budget);
+        const payload = parseJsonObject(stdin || "{}", "native hook stdin");
+        const command = lifecycleCommandFromPayload(payload);
+        const analysis = command ? parseLifecycleCommand(command) : { kind: "none", unresolved: false };
+        if (event !== "PreToolUse" || !command || (analysis.kind === "none" && (!("participation" in analysis) || !["lifecycle", "auxiliary"].includes(analysis.participation)) && !continuationCommand(command))) {
+            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: budget.remaining("admission") });
+        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 {
+        const stdin = await readNativeHookInput(process.stdin, hookBudget(ingressBudgetMs, process.env.DD_FLOW_HOOK_DEADLINE_AT ? Number(process.env.DD_FLOW_HOOK_DEADLINE_AT) : null));
+        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,116 @@
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+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: error.details.effect ?? "no_effect",
+            recoverable: error.details.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", input_sha256: crypto.createHash("sha256").update(text).digest("hex")
+        });
+    }
+}
+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" });
+    }
+}

package/dist/cli/native-hook-ingress.js

@@ -0,0 +1,80 @@
+import { AppError, errorRecord } from "../shared/errors.js";
+import { parseCommandArgs } from "../services/lifecycle-command.js";
+import { channel } from "node:diagnostics_channel";
+/** These ingress commands consume a prepared store; they never prepare it. */
+export function isNativeHookIngress(args) {
+    return args[2] === "handle" && ((args[1] === "event" && ["agy", "grok", "droid", "opencode", "zcode"].includes(args[0] ?? ""))
+        || args[0] === "zcode" && args[1] === "hook");
+}
+export async function dispatchNativeHook(args, stdin, env) {
+    const started = performance.now();
+    const deadline = env.DD_FLOW_HOOK_DEADLINE_AT === undefined ? undefined : Number(env.DD_FLOW_HOOK_DEADLINE_AT);
+    if (deadline !== undefined && !Number.isSafeInteger(deadline))
+        throw new AppError("hook_deadline_invalid", "Native hook deadline must be an absolute millisecond timestamp", 1, { effect: "unknown" });
+    const phase = (name) => {
+        if (deadline !== undefined && deadline <= Date.now())
+            throw new AppError("native_hook_timeout", "Native hook deadline expired", 1, { phase: name, effect: "unknown" });
+        process.stderr.write(`${JSON.stringify({ kind: "native_hook_phase", phase: name, elapsed_ms: Math.round(performance.now() - started), ...(deadline !== undefined ? { remaining_ms: Math.max(0, deadline - Date.now()) } : {}) })}\n`);
+    };
+    phase("import");
+    const parsed = parseCommandArgs(args.slice(3));
+    const projectRoot = parsed.options.get("project-root")?.[0];
+    if (!isNativeHookIngress(args) || parsed.positional.length || !projectRoot || projectRoot === "__dd_flow_flag__")
+        throw new AppError("usage", "Native hook requires --project-root", 2);
+    for (const [name, values] of parsed.options)
+        if (!["project-root", "json"].includes(name) || values.length !== 1 || name === "json" && values[0] !== "__dd_flow_flag__")
+            throw new AppError("usage", `Invalid native hook option: ${name}`, 2);
+    const [hooks, { createContext }, { resolveDdFlowHome }] = await Promise.all([
+        import("../services/hooks.js"), import("../runtime/context.js"), import("../storage/paths.js")
+    ]);
+    phase("imported");
+    let opened;
+    // Reuse the actual envelope validators and shell parser. They return for
+    // unrelated tools before their first DB access, without duplicating policy.
+    const context = {
+        env, ddFlowHome: resolveDdFlowHome(env), now: () => new Date().toISOString(),
+        get db() {
+            if (!opened) {
+                phase("store_open");
+                opened = createContext(env, "hook");
+                phase("store_opened");
+            }
+            return opened.db;
+        }
+    };
+    const handler = args[0] === "agy" ? hooks.handleAgyEvent : args[0] === "grok" ? hooks.handleGrokEvent
+        : args[0] === "droid" ? hooks.handleDroidEvent : args[0] === "opencode" ? hooks.handleOpenCodeEvent
+            : args[1] === "hook" ? hooks.handleZcodeHook : hooks.handleZcodeEvent;
+    const timing = channel("dd-flow.sqlite.ingress");
+    // This command owns one synchronous store; there is no concurrent handler here.
+    let previousPhase;
+    const log = (value) => {
+        const record = value;
+        if (record.phase === previousPhase)
+            return;
+        previousPhase = record.phase;
+        process.stderr.write(`${JSON.stringify({ kind: "native_hook_phase", phase: record.phase, elapsed_ms: Math.round(performance.now() - started), ...(record.remaining_ms !== undefined ? { remaining_ms: record.remaining_ms } : {}) })}\n`);
+    };
+    timing.subscribe(log);
+    try {
+        phase("receipt");
+        return await handler(context, { projectRoot, stdin });
+    }
+    finally {
+        timing.unsubscribe(log);
+        opened?.db.close?.();
+    }
+}
+export async function runNativeHookIngress(args) {
+    try {
+        const { readNativeHookInput, hookBudget } = await import("../harness-runtime/lib/native-hook-command.mjs");
+        const stdin = await readNativeHookInput(process.stdin, hookBudget(25_000, process.env.DD_FLOW_HOOK_DEADLINE_AT ? Number(process.env.DD_FLOW_HOOK_DEADLINE_AT) : null));
+        process.stdout.write(`${JSON.stringify(await dispatchNativeHook(args, stdin, process.env))}\n`);
+        return 0;
+    }
+    catch (error) {
+        const record = errorRecord(error);
+        process.stderr.write(`${JSON.stringify({ ok: false, error: record })}\n`);
+        return record.exitCode;
+    }
+}