@deksden-com/dd-flow-cli 0.9.0-beta.121 → 0.9.0-beta.122

package/dist/harness-runtime/lib/lifecycle-command.mjs

@@ -0,0 +1,218 @@
+import path from "node:path";
+import Parser from "tree-sitter";
+import Bash from "tree-sitter-bash";
+import { parse, quote } from "shell-quote";
+import { lifecycleOperationForArgv } from "./lifecycle-contract.mjs";
+
+// One grammar owns structure. shell-quote decodes identified command words;
+// neither parser grants authority or executes expansions.
+const parser = new Parser();
+parser.setLanguage(Bash);
+const shells = new Set(["bash", "sh", "zsh"]);
+const repeatedContexts = new Set(["for_statement", "while_statement", "function_definition", "c_style_for_statement"]);
+const dynamicTypes = ["command_substitution", "process_substitution", "arithmetic_expansion", "brace_expression", "extglob_pattern"];
+function words(text) {
+  try { const entries = parse(text, name => `$${name}`); return entries.every(entry => typeof entry === "string") ? entries : null; }
+  catch { return null; }
+}
+function ancestors(node) {
+  const result = [];
+  for (let parent = node.parent; parent; parent = parent.parent) result.push(parent.type);
+  return result;
+}
+function backgroundContext(node) {
+  for (let unit = node; unit.parent; unit = unit.parent) {
+    const siblings = unit.parent.children;
+    if (siblings[siblings.findIndex(child => child.id === unit.id) + 1]?.type === "&") return true;
+  }
+  return false;
+}
+function dynamicWord(node) {
+  return node.descendantsOfType(dynamicTypes).length > 0
+    || node.descendantsOfType(["simple_expansion", "expansion"]).some(expansion => !["$DD_FLOW_BIN", "${DD_FLOW_BIN}"].includes(expansion.text))
+    || node.type === "word" && /[*?[]/.test(node.text);
+}
+function launcherIndex(values, env) {
+  let index = 0;
+  while (values[index] && /^[A-Za-z_][A-Za-z0-9_]*=/.test(values[index])) {
+    const value = values[index++], equals = value.indexOf("="); env[value.slice(0, equals)] = value.slice(equals + 1);
+  }
+  if (path.basename(values[index] ?? "") === "env") {
+    index++; if (values[index] === "--") index++;
+    if (values[index]?.startsWith("-")) return null;
+    while (values[index] && /^[A-Za-z_][A-Za-z0-9_]*=/.test(values[index])) {
+      const value = values[index++], equals = value.indexOf("="); env[value.slice(0, equals)] = value.slice(equals + 1);
+    }
+  }
+  if (["command", "exec"].includes(values[index] ?? "")) { index++; if (values[index] === "--") index++; }
+  return index;
+}
+function executionCwd(node, nodes) {
+  const lineage = unit => { const result = []; for (; unit; unit = unit.parent) result.push(unit); return result; };
+  const target = lineage(node), targetIds = new Set(target.map(unit => unit.id));
+  let cwd;
+  for (const previous of nodes) {
+    if (previous.endIndex >= node.startIndex) continue;
+    const values = words(previous.text);
+    if (!values) continue;
+    let index = launcherIndex(values, {});
+    if (values[index - 1] === "command" && values[index] === "-p") { index++; if (values[index] === "--") index++; }
+    if (values[index] === "builtin") { index++; if (values[index] === "--") index++; }
+    if (!["cd", "pushd", "popd"].includes(values[index])) continue;
+    const directoryIndex = index + (values[index + 1] === "--" ? 2 : 1);
+    const source = lineage(previous);
+    // A different subshell/substitution cannot change this leaf's directory.
+    // Pipelines are not treated as isolated: bash lastpipe is configurable.
+    if (source.some(unit => ["subshell", "command_substitution", "process_substitution"].includes(unit.type) && !targetIds.has(unit.id))) continue;
+    const common = source.find(unit => targetIds.has(unit.id));
+    const andList = unit => unit.type === "list" && unit.children.some(child => child.type === "&&");
+    const sourcePath = source.slice(1, source.indexOf(common));
+    const targetPath = target.slice(1, target.findIndex(unit => unit.id === common?.id));
+    // Only a successful, foreground absolute cd dominating the leaf is a
+    // route. This walks the grammar's nested left-associative && lists;
+    // it does not evaluate conditionals, directory stacks or shell programs.
+    // `command cd` is a builtin in bash but an external child in zsh;
+    // without native dialect proof none of these prefixes proves parent cwd.
+    if (values.slice(0, index).some(value => ["env", "exec", "command"].includes(path.basename(value)))
+      || values[index] !== "cd" || values.length !== directoryIndex + 1 || !path.isAbsolute(values[directoryIndex]) || dynamicWord(previous)
+      || backgroundContext(previous) || !common || !andList(common)
+      || sourcePath.some(unit => unit.type !== "redirected_statement" && !andList(unit))
+      || targetPath.some(unit => !["redirected_statement", "subshell", "compound_statement"].includes(unit.type) && !andList(unit))) return { unresolved: true };
+    cwd = path.resolve(values[directoryIndex]);
+  }
+  return { cwd };
+}
+function invocationFromWords(values, node, wrapped, env) {
+  let index = launcherIndex(values, env);
+  if (index === null) return null;
+  let executable = values[index], launcher;
+  if (path.basename(executable ?? "") === "node" && (path.basename(values[index + 1] ?? "") === "cli.js" || values[index + 1] === "$DD_FLOW_BIN")) {
+    launcher = executable; executable = values[++index];
+  }
+  if (!executable || !(path.basename(executable) === "dd-flow" || executable === "$DD_FLOW_BIN" || launcher && path.basename(executable) === "cli.js")) return null;
+  const argv = values.slice(index + 1), operation = lifecycleOperationForArgv(argv);
+  if (!operation) return null;
+  const contexts = ancestors(node);
+  const heredoc = node.parent?.type === "redirected_statement" && node.parent.descendantsOfType("heredoc_redirect").length > 0;
+  return { operation, executable, ...(launcher ? { launcher } : {}), argv, env, args: parseCommandArgs(argv.slice(operation === "recovery_accept" ? 3 : 2)),
+    command: quote(values), rewriteSafe: !wrapped, wrapped, heredoc, contexts, ...(!wrapped ? { sourceRange: { start: node.startIndex, end: node.endIndex } } : {}) };
+}
+export function parseLifecycleCommand(command) { return analyze(command, false, 0); }
+function analyze(command, wrapped, depth) {
+  if (depth > 8 || command.length > 1_000_000) return { kind: "none", unresolved: true, reason: "shell_input_limit" };
+  const tree = parser.parse(command);
+  if (!tree) return { kind: "none", unresolved: true, reason: "shell_parse_error" };
+  try {
+    const root = tree.rootNode;
+    if (root.hasError) return { kind: "none", unresolved: true, reason: "shell_parse_error" };
+    const nodes = root.descendantsOfType("command"), found = [];
+    let unsupported;
+    for (const node of nodes) {
+      const name = node.childForFieldName("name"), values = words(node.text);
+      if (!name || !values) { if (name && dynamicWord(name)) unsupported ??= "dynamic_executable"; continue; }
+      const inherited = {};
+      // Conditional exports cannot become unconditional facts in a sibling.
+      for (const previous of root.namedChildren) {
+        if (previous.endIndex > node.startIndex) break;
+        if (previous.type !== "declaration_command" || !previous.text.startsWith("export ")) continue;
+        for (const assignment of previous.descendantsOfType("variable_assignment")) {
+          if (dynamicWord(assignment)) continue;
+          const decoded = words(assignment.text)?.[0], equals = decoded?.indexOf("=") ?? -1;
+          if (decoded && equals > 0) inherited[decoded.slice(0, equals)] = decoded.slice(equals + 1);
+        }
+      }
+      const direct = invocationFromWords(values, node, wrapped, inherited);
+      if (direct) {
+        if (backgroundContext(node)) unsupported ??= "background_lifecycle_execution";
+        if (node.namedChildren.some(dynamicWord)) unsupported ??= "unresolved_lifecycle_word";
+        if (direct.contexts.some(type => repeatedContexts.has(type))) unsupported ??= "repeated_lifecycle_context";
+        if (direct.contexts.some(type => ["command_substitution", "process_substitution"].includes(type))) unsupported ??= "executable_substitution";
+        const route = executionCwd(node, nodes);
+        if (route.unresolved) unsupported ??= "unresolved_execution_cwd";
+        else if (route.cwd) direct.expectedCwd = route.cwd;
+        found.push(direct); continue;
+      }
+      const outerEnv = { ...inherited }, shellIndex = launcherIndex(values, outerEnv);
+      const wrapper = path.basename(values[shellIndex] ?? "");
+      if (["time", "nohup", "timeout"].includes(wrapper)) {
+        let nestedIndex = shellIndex + 1;
+        if (wrapper === "time" && values[nestedIndex] === "-p") nestedIndex++;
+        if (values[nestedIndex] === "--") nestedIndex++;
+        if (wrapper === "timeout" && /^\d+(?:\.\d+)?[smhd]?$/.test(values[nestedIndex] ?? "")) nestedIndex++;
+        const nested = analyze(quote(values.slice(nestedIndex)), true, depth + 1);
+        if (nested.kind !== "none") { found.push(...(nested.invocations ?? [nested.invocation])); unsupported ??= "opaque_execution_wrapper"; continue; }
+        if (nested.unresolved) unsupported ??= nested.reason;
+      }
+      if (shellIndex !== null && shells.has(path.basename(values[shellIndex] ?? "")) && /^-(?:l?c|cl)$/.test(values[shellIndex + 1] ?? "") && values[shellIndex + 2] !== undefined) {
+        const payloadNode = node.namedChildren[shellIndex + 2];
+        if (!payloadNode || dynamicWord(payloadNode)) { unsupported ??= "dynamic_shell_payload"; continue; }
+        if (node.namedChildren.some(child => child !== payloadNode && dynamicWord(child))) unsupported ??= "unresolved_shell_environment";
+        const nested = analyze(values[shellIndex + 2], true, depth + 1);
+        if (nested.kind !== "none") {
+          const route = executionCwd(node, nodes);
+          if (route.unresolved) unsupported ??= "unresolved_execution_cwd";
+          for (const invocation of nested.invocations ?? [nested.invocation]) {
+            invocation.env = { ...outerEnv, ...invocation.env };
+            if (!invocation.expectedCwd && route.cwd) invocation.expectedCwd = route.cwd;
+          }
+          found.push(...(nested.invocations ?? [nested.invocation]));
+          if (backgroundContext(node)) unsupported ??= "background_lifecycle_execution";
+          if (ancestors(node).some(type => repeatedContexts.has(type))) unsupported ??= "repeated_lifecycle_context";
+          if (ancestors(node).some(type => ["command_substitution", "process_substitution"].includes(type))) unsupported ??= "executable_substitution";
+          if (nested.supported === false) unsupported ??= nested.reason ?? "unsupported_wrapper";
+        }
+        else if (nested.unresolved) unsupported ??= nested.reason;
+      } else if (values[shellIndex] === "eval") unsupported ??= "dynamic_eval";
+      else if (values[shellIndex] === "coproc") unsupported ??= "background_lifecycle_execution";
+      else if (dynamicWord(name)) unsupported ??= "dynamic_executable";
+    }
+    if (!found.length) return unsupported ? { kind: "none", unresolved: true, reason: unsupported } : { kind: "none" };
+    if (found.length > 1) unsupported ??= "multiple_lifecycle_invocations";
+    const invocation = found[0];
+    const composed = nodes.length > 1 || root.namedChildren.length !== 1 || invocation.contexts.some(type => !["program", "redirected_statement", "command"].includes(type));
+    return composed || unsupported ? { kind: "compound", invocation, invocations: found, supported: !unsupported, reason: unsupported ?? "shell_composition" }
+      : { kind: "standalone", invocation, invocations: found, supported: true };
+  } finally { /* Native Tree lifetime is managed by the Node binding. */ }
+}
+export function lifecycleCommandFromPayload(payload) {
+  const input = payload.tool_input && typeof payload.tool_input === "object" ? payload.tool_input : {};
+  const command = [payload.command, input.command, input.cmd].find(value => typeof value === "string" && value.length > 0);
+  return typeof command === "string" ? unwrapShellCommand(command) : undefined;
+}
+export function continuationCommand(command) {
+  const values = words(command); if (!values) return null;
+  const start = values.findIndex(word => ["stage", "work"].includes(word)); if (start < 1) return null;
+  const launcher = values.slice(0, start);
+  while (launcher[0] && /^[A-Za-z_][A-Za-z0-9_]*=/.test(launcher[0])) launcher.shift();
+  const direct = launcher.length === 1 && (path.basename(launcher[0]) === "dd-flow" || launcher[0] === "$DD_FLOW_BIN");
+  const node = launcher.length === 2 && path.basename(launcher[0]) === "node" && (path.basename(launcher[1]) === "cli.js" || launcher[1] === "$DD_FLOW_BIN");
+  if (!direct && !node) return null;
+  const args = parseCommandArgs(values.slice(start)), route = args.positional.slice(0, 3).join(" ");
+  const operation = route === "work repair add" ? "work_repair_add" : args.positional[0] === "stage" && args.positional[1] === "block" ? "stage_block" : null;
+  return operation ? { operation, args } : null;
+}
+export function unwrapShellCommand(command) {
+  const values = words(command); if (!values || values.length !== 3 || !shells.has(path.basename(values[0])) || !/^-(?:l?c|cl)$/.test(values[1])) return command;
+  const tree = parser.parse(command);
+  try { const node = tree?.rootNode.namedChildren[0]?.namedChildren[2]; return node && !dynamicWord(node) ? values[2] : command; }
+  finally { /* Native Tree lifetime is managed by the Node binding. */ }
+}
+export function parseCommandArgs(argv) {
+  const positional = [], options = new Map();
+  for (let index = 0; index < argv.length; index++) {
+    const value = argv[index];
+    if (value?.startsWith("--")) {
+      const equals = value.indexOf("=");
+      if (equals > 2) { const key = value.slice(2, equals); options.set(key, [...(options.get(key) ?? []), value.slice(equals + 1)]); continue; }
+      const key = value.slice(2), next = argv[index + 1], optionValue = !next || next.startsWith("--") ? "__dd_flow_flag__" : next;
+      options.set(key, [...(options.get(key) ?? []), optionValue]); if (optionValue !== "__dd_flow_flag__") index++;
+    } else if (value) positional.push(value);
+  }
+  return { positional, options };
+}
+export function commandOption(invocation, name) { const value = invocation.args.options.get(name)?.at(-1); return value === "__dd_flow_flag__" ? undefined : value; }
+export function commandHasOption(invocation, name) { return invocation.args.options.has(name); }
+export function commandPosition(invocation, index) { return invocation.args.positional[index]; }
+export function shellSuffixOffset(command) {
+  const analysis = parseLifecycleCommand(command); return analysis.kind === "none" ? command.length : analysis.invocation.sourceRange?.end ?? command.length;
+}

package/dist/harness-runtime/lib/lifecycle-contract.d.mts

@@ -0,0 +1,10 @@
+export const lifecycleRoutes: {
+  readonly "session register": "session_register"; readonly "stage start": "stage_start"; readonly "stage finish": "stage_finish";
+  readonly "stage pause": "stage_pause"; readonly "stage resume": "stage_resume"; readonly "work start": "work_start";
+  readonly "work finish": "work_finish"; readonly "work fail": "work_fail"; readonly "merge apply": "merge_apply";
+  readonly "merge repair": "merge_repair"; readonly "run recovery accept": "recovery_accept";
+};
+export type LifecycleOperation = typeof lifecycleRoutes[keyof typeof lifecycleRoutes];
+export const lifecycleInternalOptions: readonly ["invocation-id", "hook-event-id"];
+export function lifecycleOperationForArgv(argv: readonly string[]): LifecycleOperation | null;
+export function lifecycleRouteForOperation(operation: LifecycleOperation): keyof typeof lifecycleRoutes;

package/dist/harness-runtime/lib/lifecycle-contract.mjs

@@ -0,0 +1,19 @@
+export const lifecycleRoutes = {
+  "session register": "session_register", "stage start": "stage_start", "stage finish": "stage_finish",
+  "stage pause": "stage_pause", "stage resume": "stage_resume", "work start": "work_start",
+  "work finish": "work_finish", "work fail": "work_fail", "merge apply": "merge_apply",
+  "merge repair": "merge_repair", "run recovery accept": "recovery_accept"
+};
+export const lifecycleInternalOptions = ["invocation-id", "hook-event-id"];
+export function lifecycleOperationForArgv(argv) {
+  if (argv.some(arg => arg === "--help" || arg === "-h")) return null;
+  for (const [route, operation] of Object.entries(lifecycleRoutes)) {
+    if (route.split(" ").every((part, index) => argv[index] === part)) return operation;
+  }
+  return null;
+}
+export function lifecycleRouteForOperation(operation) {
+  const entry = Object.entries(lifecycleRoutes).find(([, value]) => value === operation);
+  if (!entry) throw new Error(`Unknown lifecycle operation: ${operation}`);
+  return entry[0];
+}

package/dist/harness-runtime/lib/native-hook-command.d.mts

@@ -1,3 +1,3 @@
-export function invokeNativeHook(input: { bin: string; args: string[]; payload: unknown; home?: string | undefined; timeoutMs?: number }): Promise<Record<string, unknown> & { timing?: Record<string, number> }>;
-export function hookBudget(timeoutMs?: number, deadlineAt?: number | null): { remaining(phase: string): number };
+export function invokeNativeHook(input: { bin: string; args: string[]; payload: unknown; home?: string | undefined; cwd?: string; env?: NodeJS.ProcessEnv; timeoutMs?: number }): Promise<Record<string, unknown> & { timing?: Record<string, number> }>;
+export function hookBudget(timeoutMs?: number, deadlineAt?: number | null): { deadlineAt: number; remaining(phase: string, maximum?: number): number; run<T>(action: () => T | Promise<T>, phase: string): Promise<T> };
 export function readNativeHookInput(stream: NodeJS.ReadStream, budget: { remaining(phase: string): number }, maxBytes?: number): Promise<string>;

package/dist/harness-runtime/lib/native-hook-command.mjs

@@ -1,8 +1,9 @@
 import { spawn } from "node:child_process";
 import { reportedFailure } from "./process-json.mjs";
 
-/** Native command hooks have a 30s outer limit; leave room for transport and cleanup. */
-export function hookBudget(timeoutMs = 25_000, deadlineAt = null) {
+/** The caller supplies its qualified native limit; phases share that deadline. */
+export function hookBudget(timeoutMs = 25_000, deadlineAt = process.env.DD_FLOW_HOOK_DEADLINE_AT === undefined ? null : Number(process.env.DD_FLOW_HOOK_DEADLINE_AT)) {
+  if (deadlineAt !== null && (!Number.isSafeInteger(deadlineAt) || deadlineAt < 0)) throw Object.assign(new Error("Invalid native hook deadline"), { code: "hook_deadline_invalid", details: { effect: "unknown" } });
   const started = performance.now();
   const duration = Math.max(0, Math.min(timeoutMs, Number.isFinite(deadlineAt) ? deadlineAt - Date.now() : timeoutMs));
   const remaining = (phase, maximum = duration) => {
@@ -10,7 +11,7 @@ export function hookBudget(timeoutMs = 25_000, deadlineAt = null) {
     if (value <= 0) throw Object.assign(new Error(`Native hook deadline exceeded during ${phase}`), { code: "native_hook_timeout", details: { phase, elapsed_ms: Math.round(performance.now() - started), effect: "unknown" } });
     return Math.max(1, Math.min(maximum, value));
   };
-  return { deadlineAt: Date.now() + duration, remaining, async run(action, phase) {
+  return { deadlineAt: Math.floor(Date.now() + duration), remaining, async run(action, phase) {
     const timeoutMs = remaining(phase);
     let timer;
     try { return await Promise.race([Promise.resolve().then(action), new Promise((_, reject) => { timer = setTimeout(() => reject(Object.assign(new Error(`Native hook deadline exceeded during ${phase}`), { code: "native_hook_timeout", details: { phase, effect: "unknown" } })), timeoutMs); })]); }
@@ -57,14 +58,31 @@ export async function terminateCommandTree(child, { platform = process.platform,
 
 /** Preserve the native hook protocol across the CLI process boundary. */
 export async function runBoundedCommand({ bin, args, input = null, cwd, env = {}, timeoutMs = 15_000, timeoutCode = "native_hook_timeout" }) {
+  const inherited = env.DD_FLOW_HOOK_DEADLINE_AT ?? process.env.DD_FLOW_HOOK_DEADLINE_AT;
+  if (inherited !== undefined) {
+    const deadline = Number(inherited);
+    if (!Number.isSafeInteger(deadline) || deadline < 0) throw Object.assign(new Error("Invalid native hook deadline"), { code: "hook_deadline_invalid", details: { effect: "no_effect" } });
+    timeoutMs = Math.min(timeoutMs, deadline - Date.now());
+  }
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) throw Object.assign(new Error("Native hook budget exhausted before subprocess launch"), { code: timeoutCode, details: { phase: "subprocess", effect: "no_effect" } });
   const started = performance.now();
+  // Transport/physical cleanup has its own small tail inside the outer limit.
+  const deadlineAt = Math.floor(Date.now() + Math.max(0, timeoutMs - Math.min(250, timeoutMs / 10)));
   const script = /\.[cm]?js$/.test(bin);
   const output = await new Promise((resolve, reject) => {
     const child = spawn(script ? process.execPath : bin, [...(script ? [bin] : []), ...args], {
-      cwd, env: { ...process.env, ...env }, detached: process.platform !== "win32", stdio: ["pipe", "pipe", "pipe"]
+      cwd, env: { ...process.env, ...env, DD_FLOW_HOOK_DEADLINE_AT: String(deadlineAt) }, detached: process.platform !== "win32", stdio: ["pipe", "pipe", "pipe"]
     });
     let stdout = "", stderr = "", failure, cleanupTimer, settled = false, termination;
-    const finish = (error, value) => { if (settled) return; settled = true; clearTimeout(timer); clearTimeout(cleanupTimer); error ? reject(error) : resolve(value); };
+    const finish = (error, value) => {
+      if (settled) return;
+      settled = true; clearTimeout(timer); clearTimeout(cleanupTimer);
+      if (error) {
+        const diagnostics = hookDiagnostics(stderr);
+        if (diagnostics.length) error.details = { ...error.details, hook_diagnostics: diagnostics };
+        reject(error);
+      } else resolve(value);
+    };
     const stop = error => {
       if (termination || settled) return;
       failure ??= error;
@@ -98,6 +116,19 @@ export async function runBoundedCommand({ bin, args, input = null, cwd, env = {}
   return output;
 }
 
+/** Only our structured phase allowlist crosses a timeout, never raw stderr/env. */
+function hookDiagnostics(stderr) {
+  return stderr.split("\n").flatMap(line => {
+    try {
+      const value = JSON.parse(line);
+      if (value?.kind !== "native_hook_phase") return [];
+      const phase = typeof value.phase === "string" && /^[a-z_]{1,48}$/.test(value.phase) ? value.phase : null;
+      if (!phase) return [];
+      return [{ phase, ...Object.fromEntries(["elapsed_ms", "remaining_ms", "sqlite_extended_code"].filter(key => Number.isFinite(value[key])).map(key => [key, value[key]])) }];
+    } catch { return []; }
+  }).slice(-16);
+}
+
 export async function invokeNativeHook({ bin, args, payload, home, cwd, env, timeoutMs = 15_000 }) {
   const output = await runBoundedCommand({ bin, args, input: `${JSON.stringify(payload)}\n`, cwd, env: { ...env, DD_FLOW_HOME: home }, timeoutMs });
   let result;

package/dist/runtime/context.js

@@ -12,7 +12,7 @@ export function createContext(env, mode = "initialize", importPermitId) {
     const ddFlowHome = resolveDdFlowHome(env);
     return {
         ddFlowHome,
-        db: getDatabase(ddFlowHome, mode, importPermitId),
+        db: getDatabase(ddFlowHome, mode, importPermitId, mode === "hook" && env.DD_FLOW_HOOK_DEADLINE_AT ? Number(env.DD_FLOW_HOOK_DEADLINE_AT) : undefined),
         env,
         now: () => new Date().toISOString()
     };

package/dist/schemas/flow-run.schema.json

@@ -12,6 +12,7 @@
     "project": {"$ref": "#/definitions/identity"},
     "subject": {"$ref": "#/definitions/identity"},
     "flow_kind": {"type": "string", "minLength": 1},
+    "verification_matrix_contract": {"const": "dd-flow/verification-matrix@1"},
     "status": {"enum": ["created", "running", "paused", "waiting_for_user", "done", "failed", "blocked", "cancelled", "discarded"]},
     "verdict": {"type": ["string", "null"]},
     "started_at": {"type": "string", "format": "date-time"},

package/dist/services/codex-hook-delivery.js

@@ -6,17 +6,21 @@ import { commandOption, lifecycleCommandFromPayload, parseLifecycleCommand, cont
 export async function verifyCodexHookDelivery(env, payload) {
     const command = lifecycleCommandFromPayload(payload);
     const parsed = command ? parseLifecycleCommand(command) : { kind: "none" };
-    if (parsed.kind === "none" && !(command && continuationCommand(command)))
+    if (parsed.kind === "none" && !parsed.unresolved && !(command && continuationCommand(command)))
         return undefined;
     const managed = (parsed.kind !== "none" && commandOption(parsed.invocation, "invocation-id")) || env.DD_FLOW_DAEMON_ID;
     if (!managed)
         return undefined; // Explicit legacy/unmanaged transport.
     if (!env.DD_FLOW_CODEX_STATE_DIR || !env.DD_FLOW_DAEMON_ID)
         throw new AppError("native_hook_unproven", "Managed hook has no owning native daemon", 1, { effect: "no_effect" });
+    const deadline = Number(env.DD_FLOW_HOOK_DEADLINE_AT);
+    const remaining = Number.isFinite(deadline) && deadline > 0 ? deadline - Date.now() : 5000;
+    if (remaining <= 0)
+        throw new AppError("native_hook_timeout", "Native hook deadline expired before delivery verification", 1, { phase: "verification", effect: "no_effect", recoverable: false });
     const proof = await callDaemon(env.DD_FLOW_CODEX_STATE_DIR, "hook.verify", {
         daemonId: env.DD_FLOW_DAEMON_ID, rootSessionId: payload.session_id,
         sessionId: payload.agent_id ?? payload.session_id, toolCallId: payload.tool_use_id, turnId: payload.turn_id
-    }, 5000);
+    }, Math.min(5000, remaining));
     if (typeof proof.projectRoot !== "string"
         || typeof proof.ddFlowHome !== "string" || !env.DD_FLOW_HOME || path.resolve(env.DD_FLOW_HOME) !== path.resolve(proof.ddFlowHome)
         || proof.daemonId !== env.DD_FLOW_DAEMON_ID || typeof proof.rootSessionId !== "string" || typeof proof.sessionId !== "string"

package/dist/services/hooks.js

@@ -481,8 +481,8 @@ function codexNativeParentId(payload, childId) {
         return null;
     }
 }
-/** ACP is asynchronous evidence. Only an explicitly issued invocation may use
- * it as the receipt that its CLI waits for; this is not a PreToolUse hook. */
+/** Qualified ACP admission binds public commands to an exact issued assignment.
+ * Its provenance is an observation, never a synchronous PreToolUse assertion. */
 export function handleZcodeEvent(context, input) {
     const notification = parseJsonObject(input.stdin || "{}", "zcode ACP notification");
     const params = objectRecord(notification.params), update = objectRecord(params.update);
@@ -494,8 +494,10 @@ export function handleZcodeEvent(context, input) {
         return { ok: true, observed: false, reason: "non_bash_tool" };
     const command = stringValue(rawInput.command) ?? stringValue(rawInput.cmd);
     const parsed = command ? parseLifecycleCommand(command) : { kind: "none" };
-    if (parsed.kind === "none")
+    if (parsed.kind === "none" && !parsed.unresolved)
         return { ok: true, observed: false, reason: "acp_evidence_only" };
+    if (parsed.kind === "none")
+        throw new AppError("lifecycle_shell_syntax_invalid", "Shell participation could not be proven", 1, { reason: parsed.reason, effect: "unknown", recoverable: false });
     const controlled = objectRecord(objectRecord(notification._meta).ddZcode);
     const providerSessionId = stringValue(native.childSessionId) ?? stringValue(controlled.rootProviderSessionId);
     return recordZcodeLifecycle(context, { projectRoot: input.projectRoot, stdin: JSON.stringify({
@@ -557,7 +559,7 @@ function recordZcodeLifecycle(context, input, invocationId, nativePreTool = fals
     const observedProfile = objectRecord(ddZcode.observedProfile);
     const observedCwd = stringValue(hook.cwd) && path.isAbsolute(String(hook.cwd)) ? resolveProjectRoot(String(hook.cwd)) : null;
     let matchKey = lifecycle ? lifecycleMatchKey(lifecycle, expectedRoot) : null;
-    const eventNameForReceipt = invocationId ? "ToolCallObserved" : "PreToolUse";
+    const eventNameForReceipt = nativePreTool ? "PreToolUse" : "ToolCallObserved";
     const persist = (scope) => {
         if (scope)
             matchKey = lifecycleMatchKey(lifecycleFacts(scope.command), expectedRoot, scope);
@@ -583,6 +585,24 @@ function recordZcodeLifecycle(context, input, invocationId, nativePreTool = fals
         identity: { daemonId, rootSessionId: rootProviderSessionId, sessionId: providerSessionId, parentSessionId: parentProviderSessionId ?? null, toolCallId: toolUseId },
         recordReceipt: scope => { persistedResult = persist(scope); return eventKey; }
     });
+    if (receipt.duplicate) {
+        // Keep first admission immutable. A second transport is independently
+        // retained corroboration, never another claim or an invented ACP cwd.
+        const retained = context.db.get("SELECT event_name, match_key, harness, provider_session_id, parent_session_id, daemon_id FROM hook_events WHERE project_id = ? AND event_key = ?", [project.id, receipt.eventKey]);
+        if (retained && retained.event_name !== eventNameForReceipt) {
+            if (retained.harness !== "zcode-acp" || retained.provider_session_id !== providerSessionId || retained.parent_session_id !== parentSessionId || retained.daemon_id !== daemonId) {
+                throw new AppError("hook_event_replay_mismatch", "Corroborating transport has different native ownership", 1, { event_key: receipt.eventKey });
+            }
+            context.db.writeTransaction(() => recordHookEvent(context, { projectId: project.id, protocolId: null, harness: "zcode-acp", providerSessionId, parentSessionId,
+                daemonId, sessionId, agentId: stringValue(hook.agent_id) ?? null, turnId: null, eventName: eventNameForReceipt, toolName: toolName ?? "Bash", status: "corroborating",
+                payload: { ...hook, command, corroborates_event_key: receipt.eventKey, admission_transport: nativePreTool ? "native_pre_tool" : "acp_observation" },
+                eventKey: `${receipt.eventKey}:${eventNameForReceipt}`, matchKey: null, transcriptPath: stringValue(hook.transcript_path) ?? null, cwd: observedCwd }));
+        }
+        else if (retained) {
+            assertHookEventReplay(context, { projectId: project.id, eventKey: receipt.eventKey, harness: "zcode-acp", providerSessionId, parentSessionId, daemonId,
+                sessionId, turnId: null, eventName: eventNameForReceipt, toolName: toolName ?? "Bash", matchKey: retained.match_key, cwd: observedCwd });
+        }
+    }
     const admittedInvocationId = receipt.invocationId ?? invocationId;
     if (admittedInvocationId)
         return { ok: true, observed: !receipt.duplicate, duplicate: receipt.duplicate, event_key: receipt.eventKey, invocation_id: admittedInvocationId };
@@ -706,8 +726,9 @@ function controlledLifecycleCwd(context, projectRoot, facts, providerSessionId,
     if (work) {
         // PROTOCOLIZE provisions the feature checkout after its coordinator
         // Session has launched in the stable project root. Its transition Work
-        // must keep that physical route until the Stage is complete.
-        if (context.db.get("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name = 'stage_work_memberships'")
+        // must keep that physical route until the Stage is complete. Child Works
+        // share stage membership, not the root coordinator's execution directory.
+        if (work.parent_work_id === null && context.db.get("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name = 'stage_work_memberships'")
             && context.db.get("SELECT 1 FROM stage_work_memberships WHERE project_id = ? AND run_id = ? AND work_id = ? AND stage IN ('specify','protocolize') LIMIT 1", [project.id, run.id, work.work_id]))
             return projectRoot;
         const merge = context.db.get("SELECT target_workspace FROM merge_requests WHERE executor_work_id = ? AND run_id = ?", [work.work_id, run.id]);
@@ -785,14 +806,24 @@ function handleControlledToolEvent(context, input, event, harness) {
     const auxiliary = continuationCommand(command);
     if (!lifecycle && !auxiliary)
         return { ok: true, observed: false, reason: "event_not_participating" };
+    // Syntax refusal precedes assignment/cwd lookup: an unsupported AST cannot
+    // supply a route or execution authority, including a short public Stage call.
+    const shellRefusal = lifecycle?.analysis.supported === false;
     const issuedRunId = lifecycle && !lifecycle.runId && !lifecycle.workId && !lifecycle.bootstrapStageStart
         ? observedLifecycleInvocation(context, command, daemonId)?.scope.runId : null;
-    const expectedCwd = controlledLifecycleCwd(context, expectedRoot, lifecycle, providerSessionId, auxiliary, issuedRunId);
-    if (observedCwd !== expectedCwd) {
-        throw new AppError(`${errorPrefix}_directory_mismatch`, `${label} ${agy ? "launch route" : "Session directory"} does not match the assigned execution workspace`, 1, { expected: expectedCwd, actual: observedCwd, ...(agy ? { actual_provenance: stringValue(event.cwd_provenance) ?? "unknown" } : {}) });
+    if (!shellRefusal && lifecycle && lifecycle.invocation.operation.startsWith("stage_") && !lifecycle.bootstrapStageStart && !lifecycle.runId && !issuedRunId) {
+        throw new AppError("invocation_assignment_missing", "Short lifecycle call has no unique issued RUN assignment; its workspace cannot be inferred", 1, { effect: "no_effect", recoverable: false });
     }
-    const bootstrapStageStart = lifecycle?.bootstrapStageStart;
-    let matchKey = lifecycle ? lifecycleMatchKey(lifecycle, expectedRoot) : null;
+    const expectedCwd = shellRefusal ? observedCwd : controlledLifecycleCwd(context, expectedRoot, lifecycle, providerSessionId, auxiliary, issuedRunId);
+    const executionRoute = shellRefusal ? undefined : lifecycle?.invocation.expectedCwd;
+    if (executionRoute && resolveProjectRoot(executionRoute) !== expectedCwd) {
+        throw new AppError(`${errorPrefix}_directory_mismatch`, "Literal shell cd route does not match the assigned lifecycle workspace", 1, { expected: expectedCwd, actual: executionRoute, actual_provenance: "shell_literal_route", effect: "no_effect", recoverable: false });
+    }
+    if (!executionRoute && observedCwd !== expectedCwd) {
+        throw new AppError(`${errorPrefix}_directory_mismatch`, `${label} ${agy ? "launch route" : "Session directory"} does not match the assigned execution workspace`, 1, { expected: expectedCwd, actual: observedCwd, effect: "no_effect", recoverable: false, ...(agy ? { actual_provenance: stringValue(event.cwd_provenance) ?? "unknown" } : {}) });
+    }
+    const bootstrapStageStart = !shellRefusal && lifecycle?.bootstrapStageStart;
+    let matchKey = lifecycle && !shellRefusal ? lifecycleMatchKey(lifecycle, expectedRoot) : null;
     if (bootstrapStageStart)
         registerProject(context, { root: expectedRoot });
     const project = requireProjectByRoot(context, expectedRoot);
@@ -810,6 +841,7 @@ function handleControlledToolEvent(context, input, event, harness) {
         const payload = {
             session_id: providerSessionId, agent_id: agentId, cwd: observedCwd, tool_name: toolName, tool_input: rawInput, command,
             ...(agy ? { cwd_provenance: stringValue(event.cwd_provenance) ?? "unknown" } : {}),
+            ...(executionRoute ? { lifecycle_execution_cwd: expectedCwd, lifecycle_execution_cwd_provenance: "literal_cd_intent_requires_cli_confirmation" } : {}),
             provider: stringValue(profile.provider), model: stringValue(profile.model), reasoning: stringValue(droid ? profile.reasoning : profile.variant),
             mode: stringValue(droid ? profile.mode : profile.agent), agent_type: stringValue(droid ? profile.agent_type : profile.agent)
         };
@@ -822,10 +854,10 @@ function handleControlledToolEvent(context, input, event, harness) {
         return inserted;
     };
     const result = (inserted) => ({ ok: true, observed: inserted, duplicate: !inserted, event_key: baseKey, phase, harness, session: nativeSessionIdentity(harness, providerSessionId), ...(nativeParentId ? { parent_session: nativeSessionIdentity(harness, nativeParentId) } : {}), daemon_id: daemonId });
-    if (agy && lifecycle) {
+    if ((agy || shellRefusal) && lifecycle) {
         let inserted = false;
         const receipt = observeLifecycleInvocation(context, {
-            command, harness, projectId: project.id, identity: { daemonId, rootSessionId: nativeParentId ?? providerSessionId, sessionId: providerSessionId, parentSessionId: nativeParentId ?? null, toolCallId: toolCallId },
+            command, harness, projectId: project.id, ...(!shellRefusal && (agy || executionRoute) ? { executionCwd: expectedCwd } : {}), identity: { daemonId, rootSessionId: nativeParentId ?? providerSessionId, sessionId: providerSessionId, parentSessionId: nativeParentId ?? null, toolCallId: toolCallId },
             recordReceipt: scope => { inserted = persist(scope); return baseKey; }
         });
         return { ...result(inserted), ...(receipt.invocationId ? { invocation_id: receipt.invocationId } : {}) };
@@ -908,50 +940,19 @@ export function isolatedDdFlowHomeFromHookStdin(stdin) {
  */
 export function commandWithHookEvent(command, eventKey) {
     const analysis = parseLifecycleCommand(command);
-    if (analysis.kind !== "standalone")
+    if (analysis.kind === "none" || analysis.supported === false)
         return command;
     if (commandHasOption(analysis.invocation, "hook-event-id")) {
         return command;
     }
     const option = `--hook-event-id '${eventKey.replaceAll("'", "'\\''")}'`;
     if (analysis.invocation.rewriteSafe) {
-        const index = shellSuffixOffset(command);
-        return `${command.slice(0, index).trimEnd()} ${option} ${command.slice(index)}`.trimEnd();
-    }
-    if (!analysis.invocation.wrapped && analysis.invocation.heredoc && allowsStdinLifecycleCompound(lifecycleFacts(command))) {
-        const index = firstHeredoc(command);
-        if (index >= 0)
-            return `${command.slice(0, index).trimEnd()} ${option} ${command.slice(index)}`;
+        const index = analysis.invocation.sourceRange?.end ?? shellSuffixOffset(command);
+        const suffix = command.slice(index);
+        return `${command.slice(0, index)} ${option}${suffix ? /^\s/.test(suffix) ? suffix : ` ${suffix}` : ""}`;
     }
     return command;
 }
-function firstHeredoc(command) {
-    let quoteState = null;
-    let escaped = false;
-    for (let index = 0; index < command.length - 1; index += 1) {
-        const char = command[index];
-        if (escaped) {
-            escaped = false;
-            continue;
-        }
-        if (char === "\\" && quoteState !== "'") {
-            escaped = true;
-            continue;
-        }
-        if (quoteState) {
-            if (char === quoteState)
-                quoteState = null;
-            continue;
-        }
-        if (char === "'" || char === '"') {
-            quoteState = char;
-            continue;
-        }
-        if (char === "<" && command[index + 1] === "<" && command[index + 2] !== "<")
-            return index;
-    }
-    return -1;
-}
 /**
  * Recognise the small shell surface used by generated dd-flow lifecycle
  * commands. This intentionally does not evaluate Bash: ambiguous composition
@@ -967,6 +968,8 @@ export function analyzeLifecycleShellCommand(command, includeSessionRegister = f
 }
 function lifecycleFacts(command) {
     const analysis = parseLifecycleCommand(command);
+    if (analysis.kind === "none" && analysis.unresolved)
+        throw new AppError("lifecycle_shell_syntax_invalid", "Shell participation could not be proven; use a literal issued command", 1, { phase: "prepare", effect: "no_effect", recoverable: true, disposition: "pre_cli_shell_refusal", reason: analysis.reason });
     if (analysis.kind === "none")
         return null;
     const invocation = analysis.invocation;
@@ -993,17 +996,6 @@ function lifecycleFacts(command) {
         contextSha256: commandOption(invocation, "context-sha256")
     };
 }
-// Worker completion and the two HITL commands intentionally take their
-// payload from stdin. Their generated pipe/heredoc is one lifecycle command,
-// not a second authority. Everything else remains standalone-only.
-function allowsStdinLifecycleCompound(facts) {
-    const operation = facts.invocation.operation;
-    return facts.analysis.kind === "standalone" && facts.invocation.heredoc && !facts.invocation.wrapped
-        && ((operation === "work_finish" && commandHasOption(facts.invocation, "result-stdin"))
-            || (operation === "stage_start" && commandHasOption(facts.invocation, "intake-stdin"))
-            || (operation === "stage_pause" && commandHasOption(facts.invocation, "question-stdin"))
-            || (operation === "stage_resume" && commandHasOption(facts.invocation, "answer-stdin")));
-}
 function lifecycleMatchKey(facts, projectRoot, scope) {
     // Observe the actual argument without validating it. A mistyped project
     // must not leave a receipt matching a later, corrected non-rewriting call.