@deksden-com/dd-flow-cli 0.9.0-beta.16 → 0.9.0-beta.160

package/dist/services/codex-capacity.js

@@ -0,0 +1,367 @@
+import { setTimeout as delay } from "node:timers/promises";
+import crypto from "node:crypto";
+import { CAPACITY_POLICY, capacityBackoff, nativeItemsSettled, normalizeCodexFailure, overloadBurst, parseCapacityOperation, refusalObservation, terminalCodexOverload } from "../harness-runtime/lib/codex-capacity-policy.mjs";
+import { AppError } from "../shared/errors.js";
+import { isObservationLoss } from "../harness-runtime/lib/operation-errors.mjs";
+export function eligibleCodexChildOverload(child, parentSessionId) {
+    return typeof child.session_id === "string" && child.session_id !== parentSessionId && child.parent_session_id === parentSessionId && child.provenance !== "parent_mismatch" && child.status === "failed" && typeof child.terminal_turn_id === "string" && nativeItemsSettled(child.native_turn_items)
+        && terminalCodexOverload({ code: "turn_interrupted", details: { provider_session_id: child.session_id, turn_id: child.terminal_turn_id, native_turn_id: child.terminal_turn_id, terminal_status: "failed", provider_error: child.provider_error } }, child.session_id, child.terminal_turn_id);
+}
+/** A terminal root is not a settled tree. Only the daemon's exact owned tree
+ * with a settled root and positively live descendants permits waiting. */
+export function capacityReadiness(seen, sessionId, operationId, turnId, items, allowDescendants = false) {
+    if (seen.provider_session_id !== sessionId || seen.terminal_turn_id !== undefined && seen.terminal_turn_id !== turnId || !nativeItemsSettled(items))
+        return "unproven";
+    const ids = Array.isArray(seen.tree_session_ids) ? seen.tree_session_ids : [];
+    if (!ids.length || ids[0] !== sessionId || ids.some(id => typeof id !== "string" || !id) || new Set(ids).size !== ids.length)
+        return "unproven";
+    const observations = Array.isArray(seen.tree_observations) ? seen.tree_observations : [];
+    const exactTree = observations.length === ids.length && ids.every(id => observations.filter(item => item.provider_session_id === id).length === 1);
+    const settlement = seen.settlement;
+    const budgetSettled = !settlement || settlement.state === "not_required" || settlement.state === "settled" && settlement.operation_ids?.includes(operationId) === true;
+    const treeSettled = allowDescendants ? exactTree && observations.every(item => item.settled === true) && Array.isArray(seen.unsettled_sessions) && seen.unsettled_sessions.length === 0 : ids.length === 1;
+    if (seen.settled === true && treeSettled && budgetSettled)
+        return "ready";
+    if (!allowDescendants || seen.settled !== false || !exactTree || ids.length < 2 || observations[0]?.provider_session_id !== sessionId || observations[0].settled !== true
+        || settlement && settlement.state !== "not_required" && !(settlement.state === "pending" && settlement.reason === "tree_unsettled"))
+        return "unproven";
+    const live = observations.filter(item => item.settled === false);
+    const unsettled = seen.unsettled_sessions;
+    const knownLive = live.length > 0 && live.every(item => item.provider_session_id !== sessionId && ["active", "running", "inProgress"].includes(String(typeof item.status === "object" && item.status ? item.status.type : item.status)));
+    return knownLive && observations.every(item => typeof item.settled === "boolean") && Array.isArray(unsettled) && unsettled.length === live.length && live.every(item => unsettled.includes(item.provider_session_id)) ? "owned_children_live" : "unproven";
+}
+/** Permit acquisition must still belong to the original task, not merely an
+ * open RUN. Controls/inspection and ordinary successor prompts are unaffected. */
+export function assertCapacityOwnerAdmission(context, record, operationId, binding) {
+    if (!operationId || !record.project_id || !record.run_id)
+        return;
+    const root = parseCapacityOperation(operationId).root;
+    const childOrdinal = /:child:[a-f0-9]+:followup:(\d+)$/.exec(root)?.[1];
+    if (childOrdinal && (!Number.isSafeInteger(Number(childOrdinal)) || Number(childOrdinal) < 1 || String(Number(childOrdinal)) !== childOrdinal))
+        throw new AppError("capacity_continuation_conflict", "Invalid native child continuation ordinal", 1);
+    if (root === operationId && !childOrdinal)
+        return;
+    const reject = () => { throw new AppError("capacity_owner_boundary_changed", "Queued continuation no longer belongs to an unfinished task; reconcile its durable state", 1, { operation_id: operationId, work_id: record.work_id, run_id: record.run_id }); };
+    const metadata = JSON.parse(record.metadata_json);
+    const hasTable = (name) => Boolean(context.db.get("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?", [name]));
+    const parsed = parseCapacityOperation(operationId);
+    if (parsed.ordinal > 0 && !["judge", "probe"].includes(metadata.role ?? "")) {
+        if (!binding?.nativeSessionId || !binding.promptSha256)
+            reject();
+        let intent;
+        const predecessor = parsed.ordinal === 1 ? root : `${root}:capacity:${parsed.ordinal - 1}:session.prompt`;
+        if (hasTable("run_controller_operations")) {
+            const saved = context.db.get("SELECT receipt_json FROM run_controller_operations WHERE operation_id = ? AND controller_id = ? AND generation = ? AND status = 'failed'", [predecessor, record.owner_id, metadata.run_generation ?? 0]);
+            if (saved)
+                intent = JSON.parse(saved.receipt_json).capacity_intent;
+        }
+        if (!intent && record.work_id)
+            for (const table of ["work_launches", "merge_requests"]) {
+                if (!hasTable(table))
+                    continue;
+                const rows = table === "work_launches"
+                    ? context.db.all("SELECT l.adapter_receipt_json FROM work_launches l JOIN works w ON w.work_id = l.work_id WHERE l.work_id = ? AND w.project_id = ? AND w.run_id = ?", [record.work_id, record.project_id, record.run_id])
+                    : context.db.all("SELECT adapter_receipt_json FROM merge_requests WHERE executor_work_id = ? AND project_id = ? AND run_id = ?", [record.work_id, record.project_id, record.run_id]);
+                for (const saved of rows) {
+                    const retained = JSON.parse(saved.adapter_receipt_json ?? "null");
+                    intent = retained?.capacity_intents?.find((item) => item.operation_id === operationId);
+                    if (intent)
+                        break;
+                }
+                if (intent)
+                    break;
+            }
+        if (!intent || intent.policy !== CAPACITY_POLICY || intent.root_operation_id !== root || intent.ordinal !== parsed.ordinal
+            || intent.predecessor !== predecessor || intent.operation_id !== operationId || intent.refusal?.turn_id !== intent.turn_id
+            || intent.refusal?.ordinal !== parsed.ordinal - 1 || intent.refusal?.session_id !== intent.session_id
+            || !Number.isFinite(Date.parse(intent.not_before)) || Date.parse(intent.not_before) > Date.parse(context.now())
+            || intent.deadline !== null && (typeof intent.deadline !== "number" || intent.deadline <= Date.parse(context.now()))
+            || binding?.nativeSessionId !== undefined && intent.session_id !== binding.nativeSessionId
+            || binding?.promptSha256 !== undefined && intent.prompt_sha256 !== binding.promptSha256)
+            reject();
+    }
+    if (context.db.get("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'run_recovery_bindings'")) {
+        if (context.db.get("SELECT 1 FROM run_recovery_bindings b JOIN run_recovery_guards g ON g.recovery_id = b.recovery_id WHERE g.project_id = ? AND g.run_id = ? AND g.status = 'recovered' AND b.status = 'accepted' AND json_extract(b.runtime_dispatch_json, '$.operation_id') = ?", [record.project_id, record.run_id, root]))
+            reject();
+    }
+    if (record.work_id) {
+        const work = context.db.get("SELECT status FROM works WHERE work_id = ? AND project_id = ? AND run_id = ?", [record.work_id, record.project_id, record.run_id]);
+        const merge = context.db.get("SELECT status FROM merge_requests WHERE executor_work_id = ? AND project_id = ? AND run_id = ?", [record.work_id, record.project_id, record.run_id]);
+        if (merge && !["dispatching", "active"].includes(merge.status))
+            reject();
+        // MERGE owns the Stage/request boundary: finishing its Work does not
+        // necessarily commit stage finish yet. External workers own only Work.
+        const mergeOwner = metadata.role === "merge";
+        if (!work || !(merge && mergeOwner ? ["created", "running", "completed"] : ["created", "running"]).includes(work.status))
+            reject();
+    }
+    if (!context.db.get("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'run_controllers'"))
+        return;
+    const controller = context.db.get("SELECT state_json FROM run_controllers WHERE controller_id = ? AND project_id = ? AND run_id = ?", [record.owner_id, record.project_id, record.run_id]);
+    if (!controller)
+        return;
+    const state = JSON.parse(controller.state_json);
+    const run = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [record.project_id, record.run_id]);
+    const index = JSON.parse(run?.index_json ?? "{}");
+    if (state.stage && (index.current_stage && index.current_stage !== state.stage || index.stage_runs?.some(stage => stage.stage === state.stage && ["done", "skipped"].includes(stage.status))))
+        reject();
+    const child = Object.entries(state.child_capacity ?? {}).find(([, intent]) => intent.operation_id === root)?.[0];
+    if (childOrdinal && !child)
+        reject();
+    if (child && context.db.get("SELECT 1 FROM work_sessions ws JOIN works w ON w.work_id = ws.work_id JOIN sessions s ON s.session_id = ws.session_id WHERE w.project_id = ? AND w.run_id = ? AND s.provider_session_id = ? AND w.status <> 'running'", [record.project_id, record.run_id, child]))
+        reject();
+}
+export function capacityDelay(error, ordinal, now = Date.now()) {
+    return capacityBackoff(error, ordinal, now);
+}
+/** Continue a confirmed terminal Turn, never replay its completed effects. */
+export async function continueCodexCapacity(input) {
+    let { error, operationId } = input;
+    const history = [...(input.retainedIntents?.() ?? [])];
+    const parsed = parseCapacityOperation(input.operationId);
+    const rootId = parsed.root;
+    const text = input.continuationText ?? "Continue the same assigned task in this Session. Check current durable RUN, Work and Stage state first. Never repeat an observed lifecycle command, accepted HITL answer, check or merge apply; use only an exact issued successor. Stop at the assigned boundary.";
+    const promptSha = crypto.createHash("sha256").update(text).digest("hex");
+    let ordinal = parsed.ordinal + 1;
+    const conflict = (message) => { throw new AppError("capacity_continuation_conflict", message, 1, { operation_id: operationId, root_operation_id: rootId, session_id: input.sessionId }); };
+    const blocked = (message) => new AppError("capacity_continuation_blocked", message, 1, { capacity_uncertainty: true, operation_id: operationId, root_operation_id: rootId, provider_session_id: input.sessionId, primary_error: error });
+    const observe = async (action, observedOperationId = operationId) => {
+        try {
+            return await action();
+        }
+        catch (cause) {
+            let primary = cause;
+            for (let depth = 0; depth < 4 && primary?.code === "harness_adapter_failed"; depth++)
+                primary = (primary.cause ?? primary.details?.cause);
+            if (isObservationLoss(primary))
+                throw new AppError("operation_observation_lost", "Capacity native observation was lost; do not cancel or resend", 1, { capacity_uncertainty: true, root_operation_id: rootId, operation_id: observedOperationId, provider_session_id: input.sessionId, predecessor_error: error, cause });
+            throw cause;
+        }
+    };
+    const refusals = [...(input.retainedFailures?.() ?? [])];
+    if (parsed.ordinal > history.length)
+        conflict("Continuation has no complete retained predecessor chain");
+    for (let index = 0; index < history.length; index++) {
+        const intent = history[index];
+        const expected = index + 1;
+        if (intent.ordinal !== expected || intent.operation_id !== `${rootId}:capacity:${expected}:session.prompt`
+            || intent.predecessor !== (expected === 1 ? rootId : `${rootId}:capacity:${expected - 1}:session.prompt`)
+            || intent.prompt_sha256 !== promptSha || intent.policy !== CAPACITY_POLICY || intent.root_operation_id !== rootId || intent.session_id !== input.sessionId
+            || intent.deadline !== (input.deadline ?? null) || !intent.refusal || intent.refusal.ordinal !== expected - 1 || intent.refusal.turn_id !== intent.turn_id
+            || !Number.isFinite(Date.parse(intent.not_before)))
+            conflict("Retained capacity chain is incomplete or belongs to another policy/task");
+        const previous = refusals.find(item => item.ordinal === intent.refusal.ordinal);
+        if (previous && JSON.stringify(previous) !== JSON.stringify(intent.refusal))
+            conflict("Retained failure observation changed");
+        if (!previous)
+            refusals.push(intent.refusal);
+    }
+    refusals.sort((a, b) => a.ordinal - b.ordinal);
+    for (let index = 0; index < refusals.length; index++) {
+        const refusal = refusals[index];
+        if (refusal.ordinal !== index || refusal.policy !== CAPACITY_POLICY || refusal.session_id !== input.sessionId || !refusal.turn_id
+            || refusals.slice(0, index).some(item => item.turn_id === refusal.turn_id) || !Number.isFinite(Date.parse(refusal.first_observed_at)))
+            conflict("Retained refusal chain is invalid");
+    }
+    // Reconcile a retained dispatch before preparing another. Native absence is
+    // the only safe way to reuse a prepared intent; a lost reply is not absence.
+    for (const intent of history) {
+        if (intent.ordinal < ordinal)
+            continue;
+        if (intent.predecessor !== operationId || intent.ordinal !== ordinal || intent.operation_id !== `${rootId}:capacity:${ordinal}:session.prompt`)
+            conflict("Retained successor skips its predecessor");
+        if (intent.prompt_sha256 !== promptSha || !intent.turn_id || !Number.isFinite(Date.parse(intent.not_before)))
+            throw error;
+        let observed;
+        try {
+            observed = await observe(() => input.inspectOperation(intent.operation_id), intent.operation_id);
+        }
+        catch (cause) {
+            let code = cause;
+            for (let depth = 0; depth < 4 && code?.code === "harness_adapter_failed"; depth++)
+                code = code.details?.cause;
+            if (code?.code !== "operation_not_found")
+                throw cause;
+            break;
+        }
+        if (observed.operation_id !== intent.operation_id || observed.session_id !== input.sessionId || observed.operation !== "session.prompt")
+            conflict("Retained native successor identity changed");
+        if (observed.primary_error)
+            throw observed.primary_error;
+        while (["prepared", "dispatching", "running", "awaiting_provider", "outcome_unknown"].includes(String(observed.state))) {
+            input.signal?.throwIfAborted();
+            input.assertCurrent();
+            const boundary = await observe(async () => await input.decision?.() ?? "continue", intent.operation_id);
+            if (boundary === "completed" || boundary === "paused")
+                return { provider_session_id: input.sessionId, capacity_decision: boundary };
+            if (boundary === "reconciliation_blocked")
+                throw new AppError("capacity_continuation_blocked", "Retained native successor has an unresolved owner boundary", 1, { operation_id: intent.operation_id, primary_error: error });
+            if (input.deadline !== undefined && Date.now() >= input.deadline)
+                throw new AppError("capacity_owner_deadline_exceeded", "Retained successor exhausted its original deadline", 1);
+            await delay(250, undefined, { signal: input.signal });
+            observed = await observe(() => input.inspectOperation(intent.operation_id), intent.operation_id);
+            input.signal?.throwIfAborted();
+            input.assertCurrent();
+            if (observed.operation_id !== intent.operation_id || observed.session_id !== input.sessionId || observed.operation !== "session.prompt")
+                conflict("Retained native successor identity changed");
+            if (observed.primary_error)
+                throw observed.primary_error;
+        }
+        if (observed.state === "completed" && observed.result && typeof observed.result === "object") {
+            input.signal?.throwIfAborted();
+            input.assertCurrent();
+            const boundary = await observe(async () => await input.decision?.() ?? "continue", intent.operation_id);
+            input.signal?.throwIfAborted();
+            input.assertCurrent();
+            if (boundary === "reconciliation_blocked")
+                throw new AppError("capacity_continuation_blocked", "Retained completion cannot be reconciled with its owner boundary", 1);
+            return boundary === "paused" || boundary === "completed" ? { provider_session_id: input.sessionId, capacity_decision: boundary } : observed.result;
+        }
+        if (observed.state === "failed" && observed.error && !terminalCodexOverload(observed.error, input.sessionId))
+            throw observed.error;
+        if (observed.state !== "failed" || !terminalCodexOverload(observed.error, input.sessionId))
+            throw new AppError("operation_observation_lost", "Retained successor outcome is not proven; do not resend", 1, { operation_id: intent.operation_id, primary_error: error, observed });
+        operationId = intent.operation_id;
+        error = observed.error;
+        ordinal += 1;
+    }
+    const decide = async (observedOperationId = operationId) => {
+        input.signal?.throwIfAborted();
+        input.assertCurrent();
+        const decision = await observe(async () => await input.decision?.() ?? "continue", observedOperationId);
+        input.signal?.throwIfAborted();
+        input.assertCurrent();
+        if (decision === "reconciliation_blocked")
+            throw new AppError("capacity_continuation_blocked", "Native refusal cannot be reconciled with its durable owner boundary", 1, { primary_error: error, root_operation_id: rootId, provider_session_id: input.sessionId });
+        if (decision === "continue" && input.deadline !== undefined && Date.now() >= input.deadline)
+            throw new AppError("capacity_owner_deadline_exceeded", "Continuation exhausted its original owner deadline", 1, { primary_error: error, deadline: input.deadline, root_operation_id: rootId, provider_session_id: input.sessionId });
+        return decision === "continue" ? null : { provider_session_id: input.sessionId, capacity_decision: decision };
+    };
+    for (;; ordinal += 1) {
+        if (!Number.isSafeInteger(ordinal))
+            conflict("Continuation ordinal overflow");
+        if (!terminalCodexOverload(error, input.sessionId)) {
+            if (ordinal === 1)
+                return null;
+            throw error;
+        }
+        const completed = await decide();
+        if (completed)
+            return completed;
+        const prior = await observe(() => input.inspectOperation(operationId));
+        const failure = prior.error;
+        const confirmed = normalizeCodexFailure(failure, input.sessionId);
+        const turnId = confirmed?.turn_id;
+        input.signal?.throwIfAborted();
+        input.assertCurrent();
+        if (prior.primary_error)
+            throw prior.primary_error;
+        if (prior.operation_id !== operationId || prior.operation !== "session.prompt" || prior.session_id !== input.sessionId
+            || prior.state !== "failed" || prior.primary_error || !turnId || !terminalCodexOverload(failure, input.sessionId, turnId)) {
+            throw blocked("Retained predecessor does not prove the exact terminal overloaded Turn");
+        }
+        const readiness = async () => {
+            input.signal?.throwIfAborted();
+            input.assertCurrent();
+            const seen = await observe(() => input.inspectSession(turnId));
+            input.signal?.throwIfAborted();
+            input.assertCurrent();
+            const items = (seen.terminal_turn_id === turnId && seen.terminal_status === "failed" ? seen.native_turn_items : confirmed?.native_turn_items);
+            return capacityReadiness(seen, input.sessionId, operationId, turnId, items, input.allowSettledDescendants);
+        };
+        const ready = await readiness();
+        if (ready === "unproven")
+            throw blocked("Native predecessor readiness is unproven; do not cancel or replay to manufacture proof");
+        const native = normalizeCodexFailure(failure, input.sessionId, turnId);
+        let refusal = refusals.find(item => item.ordinal === ordinal - 1);
+        if (refusal && (refusal.turn_id !== turnId || refusal.session_id !== input.sessionId || refusal.policy !== CAPACITY_POLICY))
+            conflict("Failure ordinal identifies a different native Turn");
+        if (refusal) {
+            const expected = refusalObservation(failure, ordinal - 1, refusal.first_observed_at);
+            if (refusal.native_terminal_at !== expected.native_terminal_at || refusal.native_terminal_basis !== expected.native_terminal_basis)
+                conflict("Retained refusal time differs from its native receipt");
+        }
+        if (!refusal) {
+            if (refusals.some(item => item.turn_id === turnId))
+                conflict("A cached native Turn cannot be a second refusal");
+            // A cached legacy failure cannot be assigned a new time during reattach.
+            if (ordinal > 1 && parsed.ordinal > 0 && !native.observed_at)
+                conflict("Retained continuation has no original failure time");
+            const observedAt = typeof native.observed_at === "string" && Number.isFinite(Date.parse(native.observed_at)) ? native.observed_at : new Date().toISOString();
+            refusal = refusalObservation(failure, ordinal - 1, observedAt);
+            if (!input.atomicIntent)
+                input.retainFailure?.(operationId, refusal);
+            refusals.push(refusal);
+        }
+        const burst = overloadBurst(refusals);
+        if (burst) {
+            if (input.atomicIntent)
+                input.retainFailure?.(operationId, refusal);
+            throw new AppError("provider_overload_burst", "Two consecutive continuation Turns were overloaded within two minutes", 1, { ...burst, root_operation_id: rootId, provider_session_id: input.sessionId, continuation_count: ordinal - 1, primary_error: failure });
+        }
+        const nextId = `${rootId}:capacity:${ordinal}:session.prompt`;
+        const existing = history.find(item => item.operation_id === nextId);
+        if (existing && (existing.predecessor !== operationId || existing.turn_id !== turnId || existing.prompt_sha256 !== promptSha || existing.ordinal !== ordinal))
+            throw error;
+        const wait = existing ? Math.max(0, Date.parse(existing.not_before) - Date.now()) : capacityDelay(failure, ordinal);
+        if (!Number.isFinite(wait) || Date.now() + wait > 8.64e15 || input.deadline !== undefined && Date.now() + wait >= input.deadline) {
+            if (input.atomicIntent)
+                input.retainFailure?.(operationId, refusal);
+            throw new AppError("capacity_owner_deadline_exceeded", "Continuation wait exceeds its original owner deadline", 1, { primary_error: failure, deadline: input.deadline ?? null });
+        }
+        if (!existing) {
+            const intent = { predecessor: operationId, operation_id: nextId, turn_id: turnId, ordinal, prompt_sha256: promptSha, not_before: new Date(Date.now() + wait).toISOString(), policy: CAPACITY_POLICY, root_operation_id: rootId, session_id: input.sessionId, deadline: input.deadline ?? null, refusal };
+            input.retainIntent(intent);
+            history.push(intent);
+        }
+        // Intent/refusal are durable before the first wait; no permit or writer is
+        // held here, and live siblings are never cancelled as a settlement proof.
+        const waitForOwnedChildren = async (initial) => {
+            let current = initial;
+            while (current === "owned_children_live") {
+                await delay(250, undefined, { signal: input.signal });
+                const boundary = await decide();
+                if (boundary)
+                    return boundary;
+                current = await readiness();
+            }
+            if (current !== "ready")
+                throw blocked("Owned native child readiness became unproven");
+            return null;
+        };
+        const childBoundary = await waitForOwnedChildren(ready);
+        if (childBoundary)
+            return childBoundary;
+        // Node timers truncate large delays. Bounded slices preserve cancellation
+        // and owner checks; monotonic elapsed time does not renew a Retry-After.
+        const until = performance.now() + Math.max(0, Date.parse(history.find(item => item.operation_id === nextId).not_before) - Date.now());
+        while (performance.now() < until) {
+            await delay(Math.min(250, Math.max(0, until - performance.now())), undefined, { signal: input.signal });
+            const boundary = await decide();
+            if (boundary)
+                return boundary;
+        }
+        const afterWait = await decide();
+        if (afterWait)
+            return afterWait;
+        const refreshedBoundary = await waitForOwnedChildren(await readiness());
+        if (refreshedBoundary)
+            return refreshedBoundary;
+        const beforeDispatch = await decide();
+        if (beforeDispatch)
+            return beforeDispatch;
+        try {
+            return await observe(() => input.prompt(nextId, text, ordinal), nextId);
+        }
+        catch (nextError) {
+            // A task can complete/pause while the daemon queues for its permit.
+            // Admission then refuses the stale prompt; accept that owner decision
+            // before treating the transport's rejection as another provider failure.
+            const finished = await decide(nextId);
+            if (finished)
+                return finished;
+            error = nextError;
+            operationId = nextId;
+        }
+    }
+}

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

@@ -0,0 +1,41 @@
+import path from "node:path";
+import { callDaemon } from "../harness-runtime/lib/dd-codex-daemon.mjs";
+import { AppError } from "../shared/errors.js";
+import { commandOption, lifecycleCommandFromPayload, parseLifecycleCommand, continuationCommand } from "./lifecycle-command.js";
+/** The hook asks the existing daemon about native evidence; it cannot mint it. */
+export async function verifyCodexHookDelivery(env, payload) {
+    const command = lifecycleCommandFromPayload(payload);
+    const parsed = command ? parseLifecycleCommand(command) : { kind: "none", participation: "none" };
+    if (parsed.kind === "none" && !["lifecycle", "auxiliary"].includes(parsed.participation) && !(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,
+        // The daemon verifies the native delivery before retaining it; the source
+        // command cannot itself grant admission to the CLI.
+        nativePayload: payload, nativeCommand: command
+    }, 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"
+        || typeof proof.toolCallId !== "string" || !(proof.parentSessionId === null || typeof proof.parentSessionId === "string")) {
+        throw new AppError("native_hook_unproven", "Native hook proof differs from the requested project/runtime", 1, { effect: "no_effect" });
+    }
+    const binding = proof.nativeHookBinding;
+    const retained = binding && typeof binding === "object" && !Array.isArray(binding) ? binding : null;
+    return { daemonId: proof.daemonId, rootSessionId: proof.rootSessionId, sessionId: proof.sessionId,
+        parentSessionId: proof.parentSessionId, toolCallId: proof.toolCallId, projectRoot: proof.projectRoot, command: command,
+        ...(retained?.schema_id === "dd-flow/hook-request@1" && retained.source_harness === "codex-desktop"
+            && retained.daemon_id === proof.daemonId && retained.root_provider_session_id === proof.rootSessionId
+            && retained.provider_session_id === proof.sessionId && retained.tool_call_id === proof.toolCallId
+            && retained.native_command === command && typeof retained.request_id === "string" ? { nativeHookBinding: retained } : {}) };
+}

package/dist/services/command-context.js

@@ -0,0 +1,80 @@
+import path from "node:path";
+import { commandInputs, physicalPathOptions } from "../cli/command-inputs.js";
+import { parseCommandArgs } from "./lifecycle-command.js";
+import { assertPathWithin, canonicalPath } from "../storage/paths.js";
+import { AppError } from "../shared/errors.js";
+import { resolveWorkReference } from "../storage/work-references.js";
+export function normalizedPathAlias(value) {
+    return value.replace(/^\\+(?=@(?:project|workspace|run)(?:\/|$))/, "");
+}
+export function resolveContextualPaths(args, options, roots) {
+    const resolve = (option, original) => {
+        if (!options.has(option))
+            return original;
+        const value = normalizedPathAlias(original);
+        if (!value.startsWith("@"))
+            return value;
+        const match = /^@(project|workspace|run)(?:\/(.*))?$/.exec(value);
+        if (!match || !roots[match[1]])
+            throw new AppError("usage", `Unknown or unavailable path alias: ${value}`, 2, { phase: "prepare", effect: "no_effect", recoverable: true, parameter: option });
+        const root = roots[match[1]];
+        return assertPathWithin(root, path.join(root, match[2] ?? ""), `${match[1]}_alias`);
+    };
+    return args.map((value, index) => {
+        const equal = /^--([^=]+)=(.*)$/s.exec(value);
+        if (equal)
+            return `--${equal[1]}=${resolve(equal[1], equal[2])}`;
+        const option = args[index - 1]?.match(/^--([^=]+)$/)?.[1];
+        return option ? resolve(option, value) : value;
+    });
+}
+/** Contextual paths are route semantics, not lifecycle invocation authority. */
+export function resolveCommandProjectRoot(context, args, explicit) {
+    if (explicit && !normalizedPathAlias(explicit).startsWith("@"))
+        return canonicalPath(explicit, false);
+    if (!context.db.get("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'runs'"))
+        return null;
+    const parsed = parseCommandArgs(args);
+    const key = Object.keys(commandInputs).filter(key => key.split(" ").every((part, i) => parsed.positional[i] === part)).sort((a, b) => b.length - a.length)[0];
+    const reference = parsed.options.get("run")?.[0] ?? (key?.startsWith("stage ") ? parsed.positional[key.split(" ").length] : undefined);
+    if (reference) {
+        const rows = context.db.all("SELECT project_root FROM runs WHERE id = ? OR short_id = ?", [reference, reference]);
+        if (rows.length === 1)
+            return rows[0].project_root;
+        if (rows.length > 1)
+            throw new AppError("usage", "RUN reference requires an explicit project scope", 2, { phase: "prepare", effect: "no_effect" });
+    }
+    const work = parsed.options.get("parent")?.[0] ?? (key?.startsWith("work ") && !key.startsWith("work repair") ? parsed.positional[key.split(" ").length] : undefined);
+    if (work) {
+        const resolved = resolveWorkReference(context, work);
+        return context.db.get("SELECT root FROM projects WHERE id = ?", [resolved.project_id])?.root ?? null;
+    }
+    return null;
+}
+export function resolveCommandPaths(context, args, projectRoot) {
+    const parsed = parseCommandArgs(args);
+    const key = Object.keys(commandInputs).filter(key => key.split(" ").every((part, i) => parsed.positional[i] === part)).sort((a, b) => b.length - a.length)[0];
+    const options = new Set(key ? commandInputs[key]?.contextualPaths ?? [] : []);
+    if (!args.some(value => /(?:^|=)\\*@/.test(value)))
+        return args;
+    for (const [option, values] of parsed.options) {
+        if (physicalPathOptions.has(option) && !options.has(option) && values.some(value => normalizedPathAlias(value).startsWith("@")))
+            throw new AppError("usage", `--${option} requires a physical path on this route`, 2, { phase: "prepare", effect: "no_effect", recoverable: true, parameter: option });
+    }
+    const project = projectRoot ? context.db.get("SELECT id FROM projects WHERE root = ?", [projectRoot]) : undefined;
+    const reference = parsed.options.get("run")?.[0] ?? (key?.startsWith("stage ") ? parsed.positional[key.split(" ").length] : undefined);
+    let run;
+    if (reference && project) {
+        const rows = context.db.all("SELECT id, workspace_root, run_root FROM runs WHERE project_id = ? AND (id = ? OR short_id = ?)", [project.id, reference, reference]);
+        if (rows.length !== 1)
+            throw new AppError("usage", "Path aliases require one RUN in the selected project", 2, { phase: "prepare", effect: "no_effect" });
+        run = rows[0];
+    }
+    const work = parsed.options.get("parent")?.[0] ?? (key?.startsWith("work ") && !key.startsWith("work repair") ? parsed.positional[key.split(" ").length] : undefined);
+    if (work && project) {
+        const resolved = resolveWorkReference(context, work, { projectId: project.id, ...(run ? { runId: run.id } : {}) });
+        if (!run)
+            run = context.db.get("SELECT id, workspace_root, run_root FROM runs WHERE project_id = ? AND id = ?", [project.id, resolved.run_id]);
+    }
+    return resolveContextualPaths(args, options, { project: projectRoot, workspace: run?.workspace_root, run: run?.run_root });
+}

package/dist/services/compatibility-preflight.js

@@ -1,17 +1,30 @@
 import { AppError } from "../shared/errors.js";
 import { getCliBuildInfo } from "./build-info.js";
 import { classifyCliOperation } from "./cli-operation-classifier.js";
-import { resolveOperationProjectRoot, selectEngine } from "./engines.js";
-export function preflightCliCompatibility(context, args, env = process.env, resolvedProjectRoot) {
+import { parseCommandArgs } from "./lifecycle-command.js";
+export async function preflightCliCompatibility(context, args, env = process.env, resolvedProjectRoot) {
     const classification = classifyCliOperation(args, env);
     if (classification.mode === "router_native") {
         return { ok: true, classification, compatibility: null };
     }
+    // Internal scope-free ownership maintenance has no project compatibility
+    // work. Keep the engine/protocol/canon graph out of that cold path.
+    const parsed = parseCommandArgs(args);
+    if (resolvedProjectRoot === null && parsed.positional[0] === "runtime" && parsed.positional[1] === "process"
+        && !parsed.options.has("project-root") && !parsed.options.has("root"))
+        return { ok: true, classification, compatibility: null };
+    const { resolveOperationProjectRoot, selectEngine, selectBoundExecutingEngine } = await import("./engines.js");
     const projectRoot = resolvedProjectRoot ?? resolveOperationProjectRoot(context, args);
     if (!projectRoot) {
         return { ok: true, classification, compatibility: null };
     }
-    const selection = selectEngine(context, { projectRoot, env }, { allowCurrentInProcess: true }, classification);
+    // Compatibility checks the executing build/manifest identity. Routing and
+    // binding validate snapshot bytes before dispatch; maintenance must not
+    // rehash the dependency closure or spawn health probes on every lease ACK.
+    // Read-only probes may intentionally inspect a copied RUN before its new
+    // executor is bound. Writer authority is neither required nor granted here.
+    const selection = (classification.mode === "read_only_diagnostics" ? null : selectBoundExecutingEngine(context, args, projectRoot, env))
+        ?? selectEngine(context, { projectRoot, env }, { allowCurrentInProcess: true, verifyCurrentContent: false }, classification);
     const compatibility = compatibilityReport(selection, classification);
     if (classification.mode === "read_only_diagnostics" || classification.mode === "mb_upgrade") {
         return { ok: true, classification, compatibility };

package/dist/services/config.js

@@ -28,7 +28,8 @@ export function getProjectConfigStatus(context, project) {
     };
 }
 export function setProjectConfigValue(context, project, input) {
-    const value = parseConfigValue(input.key, input.value);
+    const value = prepareProjectConfigValue(input.key, input.value);
+    migrateLegacyConfig(context, project.id);
     const now = context.now();
     context.db.run(`INSERT INTO project_config (project_id, key, value_json, created_at, updated_at)
      VALUES (?, ?, ?, ?, ?)
@@ -38,13 +39,15 @@ export function setProjectConfigValue(context, project, input) {
     return getProjectConfigStatus(context, project);
 }
 export function readProjectConfig(context, projectId) {
-    // Status and dashboard reads intentionally open SQLite read-only. Legacy
-    // cleanup is a write-side concern and must not make those commands fail.
-    if (context.db.writable)
-        migrateLegacyConfig(context, projectId);
+    // Project legacy values without changing storage. Explicit writes migrate
+    // them; a canonical override always wins over its legacy alias.
+    const rows = configOverrides(context, projectId), keys = new Set(rows.map(row => row.key));
     const config = structuredClone(defaultProjectConfig);
-    for (const row of configOverrides(context, projectId)) {
-        applyConfigValue(config, row.key, JSON.parse(row.value_json));
+    for (const row of rows) {
+        const key = legacyConfigKey(row.key);
+        if (key !== row.key && keys.has(key))
+            continue;
+        applyConfigValue(config, key, JSON.parse(row.value_json));
     }
     return config;
 }
@@ -89,7 +92,7 @@ export function globalDashboardHtmlPath(context) {
 function configOverrides(context, projectId) {
     return context.db.all("SELECT key, value_json, updated_at FROM project_config WHERE project_id = ? ORDER BY key ASC", [projectId]);
 }
-function parseConfigValue(key, value) {
+export function prepareProjectConfigValue(key, value) {
     if (key === "integrations.cmux.mode") {
         if (!cmuxModes.includes(value)) {
             throw new AppError("validation", "--value for integrations.cmux.mode must be off, auto, or required", 2);

package/dist/services/continuation-outcome.js

@@ -0,0 +1,25 @@
+import { AppError } from "../shared/errors.js";
+import { applicableLifecycleRejection } from "./lifecycle-invocations.js";
+import { stageAttempt } from "./stage-work-graph.js";
+/** Only the settled coordinator turn can explain a repeated continuation.
+ * A stale error from another stage/turn or an error followed by success is not
+ * authority. Never inspect the assistant's prose for this decision. */
+export function assertNoCorrelatedRejection(context, scope) {
+    const rows = context.db.all(`SELECT event_key, outcome_json FROM hook_events
+    WHERE project_id = ? AND json_extract(outcome_json, '$.run_id') = ?
+    AND json_extract(outcome_json, '$.generation') = ? AND json_extract(outcome_json, '$.stage') = ?
+    AND json_extract(outcome_json, '$.controller_turn') = ? AND json_extract(outcome_json, '$.attempt') = ? ORDER BY id`, [scope.projectId, scope.runId, scope.generation, scope.stage, scope.turn, stageAttempt(context, scope.projectId, scope.runId, scope.stage)]);
+    const latest = new Map();
+    for (const row of rows) {
+        const value = { ...JSON.parse(row.outcome_json), event_key: row.event_key };
+        const invocationId = context.db.get("SELECT 1 FROM sqlite_master WHERE name='lifecycle_invocations'")
+            ? context.db.get("SELECT id FROM lifecycle_invocations WHERE event_key=?", [row.event_key])?.id : undefined;
+        latest.set(invocationId ?? JSON.stringify([value.operation, value.session_id ?? null, value.correlation_key ?? value.fingerprint ?? value.work_id ?? null, value.attempt ?? null]), value);
+    }
+    for (const value of latest.values())
+        if (value.error) {
+            const failure = applicableLifecycleRejection(context, value.error, scope, { eventKey: value.event_key });
+            if (failure)
+                throw new AppError(failure.code, failure.message, 1, { ...failure.details, operation: value.operation, hook_event_id: value.hook_event_id, continuation_scope: scope });
+        }
+}