@deksden-com/dd-flow-cli 0.9.0-beta.17 → 0.9.0-beta.19

package/dist/services/hooks.js

@@ -285,7 +285,7 @@ export function handleCodexHook(context, input) {
         return { ok: true, observed: false, reason: "event_not_participating", event: eventName };
     // Resume legitimately receives an answer through stdin. It is matched by
     // immutable lifecycle arguments below; never reject or rewrite that pipe.
-    if (lifecycle.analysis.kind === "compound") {
+    if (lifecycle.analysis.kind === "compound" && !allowsStdinLifecycleCompound(lifecycle)) {
         return {
             ok: false,
             observed: false,
@@ -299,14 +299,25 @@ export function handleCodexHook(context, input) {
             }
         };
     }
-    const { flowPayload, stageStart, stageResume, workStart, bootstrapStageStart, commandProjectRoot } = lifecycle;
+    const { flowPayload, stageStart, stageFinish, stagePause, stageResume, workStart, workFinish, workFail, bootstrapStageStart, commandProjectRoot } = lifecycle;
     const matchKey = commandProjectRoot ? lifecycleMatchKey(lifecycle, commandProjectRoot) : null;
     // A bootstrap stage is the first stateful command for a new materialized project.
     // Its PreToolUse event arrives before stage start can register that project.
     if (bootstrapStageStart && commandProjectRoot) {
         registerProject(context, { root: commandProjectRoot });
     }
-    const project = projectForHook(context, input.projectRoot ?? commandProjectRoot, stringValue(payload.cwd));
+    let project;
+    try {
+        project = projectForHook(context, input.projectRoot ?? commandProjectRoot, stringValue(payload.cwd));
+    }
+    catch (error) {
+        // A terminal command outside a registered flow gets no trusted receipt;
+        // the CLI will fail closed if it is actually executed. This keeps hooks
+        // inert for unrelated shell-parser probes and stale project directories.
+        if (stageFinish || stagePause || workFinish || workFail)
+            return { ok: true, observed: false, reason: "project_not_registered" };
+        throw error;
+    }
     if (!project)
         return { ok: true, observed: false, reason: "unrelated_cwd" };
     // Codex retains the root session_id for a thread-spawned child, while the
@@ -364,7 +375,7 @@ export function handleCodexHook(context, input) {
         session: providerSessionId ? nativeSessionIdentity("codex-desktop", providerSessionId) : null,
         ...(parentProviderSessionId ? { parent_session: nativeSessionIdentity("codex-desktop", parentProviderSessionId) } : {}),
         protocol_id: protocolId,
-        ...(providerSessionId && (flowPayload || stageStart || stageResume || workStart)
+        ...(providerSessionId && (flowPayload || stageStart || stageFinish || stagePause || stageResume || workStart || workFinish || workFail)
             ? {
                 hookSpecificOutput: {
                     hookEventName: "PreToolUse",
@@ -414,7 +425,7 @@ export function handleZcodeEvent(context, input) {
     const lifecycle = lifecycleFacts(command);
     if (!lifecycle)
         return { ok: true, observed: false, reason: "event_not_participating" };
-    if (lifecycle.analysis.kind === "compound") {
+    if (lifecycle.analysis.kind === "compound" && !allowsStdinLifecycleCompound(lifecycle)) {
         throw new AppError("compound_lifecycle_command", "dd-flow lifecycle commands must be a standalone ZCode Bash tool call", 1, {
             standalone_command: lifecycle.invocation.command
         });
@@ -521,12 +532,12 @@ export function handleGrokEvent(context, input) {
     const lifecycle = lifecycleFacts(command);
     if (!lifecycle)
         return { ok: true, observed: false, reason: "event_not_participating" };
-    if (lifecycle.analysis.kind === "compound") {
+    if (lifecycle.analysis.kind === "compound" && !allowsStdinLifecycleCompound(lifecycle)) {
         throw new AppError("compound_lifecycle_command", "dd-flow lifecycle commands must be a standalone Grok Build tool call", 1, {
             standalone_command: lifecycle.invocation.command
         });
     }
-    const { flowPayload, stageStart, stageResume, workStart, bootstrapStageStart, commandProjectRoot } = lifecycle;
+    const { flowPayload, stageStart, stageFinish, stagePause, stageResume, workStart, workFinish, workFail, bootstrapStageStart, commandProjectRoot } = lifecycle;
     const expectedRoot = resolveProjectRoot(input.projectRoot);
     if (commandProjectRoot && resolveProjectRoot(commandProjectRoot) !== expectedRoot) {
         throw new AppError("project_mismatch", "Grok Build lifecycle command project root does not match the controlled workspace", 1, {
@@ -570,20 +581,32 @@ export function handleGrokEvent(context, input) {
     });
     const result = { ok: true, observed: inserted, duplicate: !inserted, event_key: eventKey, session: nativeSessionIdentity("grok-acp", providerSessionId),
         ...(isChild ? { parent_session: nativeSessionIdentity("grok-acp", stringValue(ddGrok.parentProviderSessionId) ?? rootProviderSessionId) } : {}), daemon_id: daemonId ?? null };
-    return (flowPayload || stageStart || stageResume || workStart)
+    return (flowPayload || stageStart || stageFinish || stagePause || stageResume || workStart || workFinish || workFail)
         ? { ...result, hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "allow", updatedInput: { ...(rawInput ?? {}), command: commandWithHookEvent(command, eventKey) } } }
         : result;
 }
 /** Convert a controlled OpenCode tool hook into the shared lifecycle receipt. */
 export function handleOpenCodeEvent(context, input) {
     const event = parseJsonObject(input.stdin || "{}", "OpenCode tool event");
-    const agy = event.source_harness === "antigravity-cli";
-    const harness = agy ? "antigravity-cli" : "opencode-server";
     if (event.schema_id !== "dd-flow/opencode-tool-event@1")
         throw new AppError("unsupported_opencode_event_schema", "Unsupported OpenCode event schema", 1);
+    return handleControlledToolEvent(context, input, event, event.source_harness === "antigravity-cli" ? "antigravity-cli" : "opencode-server");
+}
+/** Accept adapter-observed Factory identity, never a model-supplied Session ID. */
+export function handleDroidEvent(context, input) {
+    const event = parseJsonObject(input.stdin || "{}", "Droid tool event");
+    if (event.schema_id !== "dd-flow/droid-tool-event@1")
+        throw new AppError("unsupported_droid_event_schema", "Unsupported Droid event schema", 1);
+    return handleControlledToolEvent(context, input, event, "droid-cli");
+}
+function handleControlledToolEvent(context, input, event, harness) {
+    const agy = harness === "antigravity-cli";
+    const droid = harness === "droid-cli";
+    const label = droid ? "Droid" : agy ? "Antigravity" : "OpenCode";
+    const errorPrefix = droid ? "droid" : agy ? "agy" : "opencode";
     const phase = stringValue(event.phase);
     if (phase !== "before" && phase !== "after")
-        throw new AppError("unsupported_opencode_event_schema", "OpenCode event phase must be before or after", 1);
+        throw new AppError(`unsupported_${errorPrefix}_event_schema`, `${label} event phase must be before or after`, 1);
     const session = objectRecord(event.session);
     const profile = objectRecord(event.profile);
     const rawInput = objectRecord(event.input);
@@ -591,16 +614,18 @@ export function handleOpenCodeEvent(context, input) {
     const nativeParentId = stringValue(session.parent_provider_session_id);
     const daemonId = stringValue(event.daemon_id);
     const toolCallId = stringValue(event.tool_call_id);
-    const eventId = stringValue(event.event_id) ?? toolCallId;
+    const eventId = stringValue(event.event_id) ?? (droid ? undefined : toolCallId);
     const toolName = stringValue(event.tool);
     const directory = stringValue(session.directory);
-    if (!providerSessionId || !daemonId || !toolCallId || !eventId || !toolName || !directory || !path.isAbsolute(directory)) {
-        throw new AppError("opencode_session_identity_invalid", "OpenCode event is missing trusted physical identity", 1);
+    if (!providerSessionId || !daemonId || (!droid && !toolCallId) || !eventId || !toolName || !directory || !path.isAbsolute(directory)) {
+        throw new AppError(`${errorPrefix}_session_identity_invalid`, `${label} event is missing trusted physical identity`, 1);
     }
     const expectedRoot = resolveProjectRoot(input.projectRoot);
     if (resolveProjectRoot(directory) !== expectedRoot) {
-        throw new AppError(agy ? "agy_directory_mismatch" : "opencode_directory_mismatch", `${agy ? "Antigravity" : "OpenCode"} Session directory does not match the controlled workspace`, 1, { expected: expectedRoot, actual: directory });
+        throw new AppError(`${errorPrefix}_directory_mismatch`, `${label} Session directory does not match the controlled workspace`, 1, { expected: expectedRoot, actual: directory });
     }
+    if (droid && nativeParentId === providerSessionId)
+        throw new AppError("droid_session_identity_invalid", "A Droid Session cannot parent itself", 1);
     const sessionId = storageSessionId(nativeSessionIdentity(harness, providerSessionId));
     const parentSessionId = nativeParentId ? storageSessionId(nativeSessionIdentity(harness, nativeParentId)) : null;
     const command = stringValue(rawInput.command) ?? stringValue(rawInput.cmd) ?? stringValue(rawInput.CommandLine);
@@ -611,43 +636,49 @@ export function handleOpenCodeEvent(context, input) {
             projectId: project.id, protocolId: null, harness, providerSessionId, parentSessionId,
             daemonId, sessionId, agentId: stringValue(session.agent_id) ?? null, turnId: stringValue(event.message_id) ?? null,
             eventName: "PostToolUse", toolName, status: "observed", payload: { session_id: providerSessionId, cwd: expectedRoot, tool_name: toolName, status: objectRecord(event.outcome).status },
-            eventKey: baseKey, matchKey: null, transcriptPath: null, cwd: expectedRoot
+            eventKey: baseKey, matchKey: null, transcriptPath: droid ? stringValue(event.transcript_path) ?? null : null, cwd: expectedRoot
         });
         return { ok: true, observed: inserted, duplicate: !inserted, event_key: baseKey, phase, harness, session: nativeSessionIdentity(harness, providerSessionId), ...(nativeParentId ? { parent_session: nativeSessionIdentity(harness, nativeParentId) } : {}) };
     }
-    if (!command || !["bash", "Bash", "run_command", "run_terminal_command", "RunTerminalCommand"].includes(toolName)) {
+    if (!command || !(droid ? ["Execute"] : ["bash", "Bash", "run_command", "run_terminal_command", "RunTerminalCommand"]).includes(toolName)) {
         return { ok: true, observed: false, reason: command ? "non_bash_tool" : "event_not_participating" };
     }
     const lifecycle = lifecycleFacts(command);
     if (!lifecycle)
         return { ok: true, observed: false, reason: "event_not_participating" };
-    if (lifecycle.analysis.kind === "compound") {
-        throw new AppError("compound_lifecycle_command", `dd-flow lifecycle commands must be a standalone ${agy ? "Antigravity" : "OpenCode"} shell tool call`, 1, { standalone_command: lifecycle.invocation.command });
+    if (lifecycle.analysis.kind === "compound" && !allowsStdinLifecycleCompound(lifecycle)) {
+        throw new AppError("compound_lifecycle_command", `dd-flow lifecycle commands must be a standalone ${label} shell tool call`, 1, { standalone_command: lifecycle.invocation.command });
     }
     const { flowPayload, bootstrapStageStart, commandProjectRoot } = lifecycle;
     if (commandProjectRoot && resolveProjectRoot(commandProjectRoot) !== expectedRoot) {
-        throw new AppError("project_mismatch", "OpenCode lifecycle command project root does not match the controlled workspace", 1, { expected: expectedRoot, actual: commandProjectRoot });
+        throw new AppError("project_mismatch", `${label} lifecycle command project root does not match the controlled workspace`, 1, { expected: expectedRoot, actual: commandProjectRoot });
     }
     const matchKey = lifecycleMatchKey(lifecycle, expectedRoot);
     if (bootstrapStageStart)
         registerProject(context, { root: expectedRoot });
     const project = requireProjectByRoot(context, expectedRoot);
+    if (droid) {
+        const existing = context.db.get("SELECT harness, provider_session_id, parent_session_id, daemon_id, match_key, tool_name FROM hook_events WHERE project_id = ? AND event_key = ?", [project.id, baseKey]);
+        if (existing && (existing.harness !== harness || existing.provider_session_id !== providerSessionId || existing.parent_session_id !== parentSessionId || existing.daemon_id !== daemonId || existing.match_key !== matchKey || existing.tool_name !== toolName)) {
+            throw new AppError("droid_event_replay_mismatch", "Droid event ID was already observed with different lifecycle identity", 1);
+        }
+    }
     const agentId = stringValue(session.agent_id);
     const observedSession = flowPayload ? bindObservedFlowSession(context, project, {
         ...flowPayload, harness, provider_session_id: providerSessionId, agent_id: agentId ?? null,
         parent_session_id: parentSessionId, provider: stringValue(profile.provider) ?? null, model: stringValue(profile.model) ?? null,
-        reasoning: stringValue(profile.variant) ?? null, mode: stringValue(profile.agent) ?? null, agent_type: stringValue(profile.agent) ?? null,
-        metadata: { opencode_version: stringValue(event.server_version) ?? null, api_fingerprint: stringValue(event.api_fingerprint) ?? null, plugin_sha256: stringValue(event.plugin_sha256) ?? null, native_project_id: stringValue(session.project_id) ?? null }
+        reasoning: stringValue(droid ? profile.reasoning : profile.variant) ?? null, mode: stringValue(droid ? profile.mode : profile.agent) ?? null, agent_type: stringValue(droid ? profile.agent_type : profile.agent) ?? null,
+        metadata: droid ? { droid_version: stringValue(event.runtime_version) ?? null } : { opencode_version: stringValue(event.server_version) ?? null, api_fingerprint: stringValue(event.api_fingerprint) ?? null, plugin_sha256: stringValue(event.plugin_sha256) ?? null, native_project_id: stringValue(session.project_id) ?? null }
     }, sessionId) : undefined;
     const payload = {
         session_id: providerSessionId, agent_id: agentId, cwd: expectedRoot, tool_name: toolName, tool_input: rawInput, command,
-        provider: stringValue(profile.provider), model: stringValue(profile.model), reasoning: stringValue(profile.variant),
-        mode: stringValue(profile.agent), agent_type: stringValue(profile.agent)
+        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)
     };
     const inserted = recordHookEvent(context, {
         projectId: project.id, protocolId: observedSession?.protocol_id ?? null, harness, providerSessionId, parentSessionId,
         daemonId, sessionId, agentId: agentId ?? null, turnId: stringValue(event.message_id) ?? null, eventName: "PreToolUse", toolName,
-        status: "observed", payload, eventKey: baseKey, matchKey, transcriptPath: null, cwd: expectedRoot
+        status: "observed", payload, eventKey: baseKey, matchKey, transcriptPath: droid ? stringValue(event.transcript_path) ?? null : null, cwd: expectedRoot
     });
     recordFlowSessionObservation(context, { projectId: project.id, sessionId, runId: observedSession?.run_id ?? null, protocolId: observedSession?.protocol_id ?? null, cwd: expectedRoot, toolName, eventKey: baseKey });
     const result = { ok: true, observed: inserted, duplicate: !inserted, event_key: baseKey, phase, harness, session: nativeSessionIdentity(harness, providerSessionId), ...(nativeParentId ? { parent_session: nativeSessionIdentity(harness, nativeParentId) } : {}), daemon_id: daemonId };
@@ -727,25 +758,39 @@ function lifecycleFacts(command) {
         return null;
     const invocation = analysis.invocation;
     const stageStart = invocation.operation === "stage_start";
+    const stageFinish = invocation.operation === "stage_finish";
+    const stagePause = invocation.operation === "stage_pause";
     const stageResume = invocation.operation === "stage_resume";
     const workStart = invocation.operation === "work_start";
+    const workFinish = invocation.operation === "work_finish";
+    const workFail = invocation.operation === "work_fail";
     return {
         analysis,
         invocation,
         flowPayload: flowSessionPayloadFromRegisterCommand(invocation),
         stageStart,
+        stageFinish,
+        stagePause,
         stageResume,
-        workStart,
+        workStart, workFinish, workFail,
         bootstrapStageStart: stageStart && commandHasOption(invocation, "bootstrap"),
         commandProjectRoot: commandOption(invocation, "project-root"),
-        stageName: stageStart || stageResume ? commandOption(invocation, "stage") : undefined,
-        runId: stageStart || stageResume ? commandPosition(invocation, 0) : undefined,
-        workId: stageResume ? commandOption(invocation, "work") : workStart ? commandPosition(invocation, 0) : undefined,
+        stageName: stageStart || stageFinish || stagePause || stageResume ? commandOption(invocation, "stage") : undefined,
+        runId: stageStart || stageFinish || stagePause || stageResume ? commandPosition(invocation, 0) : undefined,
+        workId: stagePause || stageResume ? commandOption(invocation, "work") : workStart || workFinish || workFail ? commandPosition(invocation, 0) : undefined,
         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 (operation === "work_finish" && commandHasOption(facts.invocation, "result-stdin"))
+        || ((operation === "stage_pause" || operation === "stage_resume") && facts.invocation.heredoc);
+}
 function lifecycleMatchKey(facts, projectRoot) {
-    const { invocation, bootstrapStageStart, stageStart, stageResume, workStart, stageName, runId, workId, contextSha256 } = facts;
+    const { invocation, bootstrapStageStart, stageStart, stageFinish, stagePause, stageResume, workStart, workFinish, workFail, stageName, runId, workId, contextSha256 } = facts;
     if (bootstrapStageStart)
         return bootstrapMatchKey({
             projectRoot,
@@ -755,12 +800,58 @@ function lifecycleMatchKey(facts, projectRoot) {
         });
     if (stageStart && runId && stageName)
         return stageStartMatchKey(runId, stageName, projectRoot, contextSha256);
+    if (stageFinish && runId && stageName)
+        return stageLifecycleMatchKey("stage_finish", runId, stageName, projectRoot);
+    if (stagePause && runId && stageName && workId)
+        return stageLifecycleMatchKey("stage_pause", runId, stageName, projectRoot, workId);
     if (stageResume && runId && stageName && workId)
         return stageResumeMatchKey(runId, stageName, workId, projectRoot);
     if (workStart && workId)
         return workStartMatchKey(workId, projectRoot);
+    if (workFinish && workId)
+        return workLifecycleMatchKey("work_finish", workId, projectRoot);
+    if (workFail && workId)
+        return workLifecycleMatchKey("work_fail", workId, projectRoot);
     return null;
 }
+export function stageLifecycleMatchKey(operation, runId, stage, projectRoot, workId) {
+    return crypto.createHash("sha256").update(JSON.stringify({ operation, run_id: runId, stage, project_root: resolveProjectRoot(projectRoot), ...(workId ? { work_id: workId } : {}) })).digest("hex");
+}
+export function workLifecycleMatchKey(operation, workId, projectRoot) {
+    return crypto.createHash("sha256").update(JSON.stringify({ operation, work_id: workId, project_root: resolveProjectRoot(projectRoot) })).digest("hex");
+}
+/** Claims a Work terminal command only after its exact hook receipt has proved
+ * the physical Session that issued it. Work code performs the owner check. */
+export function claimWorkLifecycleHookEvent(context, input) {
+    const matchKey = workLifecycleMatchKey(input.operation, input.workId, input.projectRoot);
+    const eventKey = input.eventKey ?? findRecentMatchingHookEvent(context, {
+        projectId: input.projectId, matchKey, errorCode: "trusted_session_binding_required", operation: input.operation.replace("_", " ")
+    }).eventKey;
+    const event = context.db.get("SELECT id, session_id, match_key, status FROM hook_events WHERE project_id = ? AND event_key = ?", [input.projectId, eventKey]);
+    if (!event?.session_id || event.status !== "observed" || event.match_key !== matchKey) {
+        throw new AppError("trusted_session_binding_required", `${input.operation.replace("_", " ")} requires one fresh matching PreToolUse hook event`, 1, { work_id: input.workId, event_key: eventKey });
+    }
+    const claimed = context.db.run("UPDATE hook_events SET status = 'claimed', claimed_at = ? WHERE id = ? AND status = 'observed'", [context.now(), event.id]);
+    if (claimed.changes !== 1)
+        throw new AppError("trusted_session_binding_required", "matching Work lifecycle hook event was already claimed", 1, { work_id: input.workId });
+    return hookSessionIdentity(context, input.projectId, eventKey);
+}
+/** Claims a lifecycle command only after its exact hook receipt has proved the
+ * physical Session that issued it. Stage code performs the Work-owner check. */
+export function claimStageLifecycleHookEvent(context, input) {
+    const matchKey = stageLifecycleMatchKey(input.operation, input.runId, input.stage, input.projectRoot, input.workId);
+    const eventKey = input.eventKey ?? findRecentMatchingHookEvent(context, {
+        projectId: input.projectId, matchKey, errorCode: "trusted_session_binding_required", operation: input.operation.replace("_", " ")
+    }).eventKey;
+    const event = context.db.get("SELECT id, session_id, match_key, status FROM hook_events WHERE project_id = ? AND event_key = ?", [input.projectId, eventKey]);
+    if (!event?.session_id || event.status !== "observed" || event.match_key !== matchKey) {
+        throw new AppError("trusted_session_binding_required", `${input.operation.replace("_", " ")} requires one fresh matching PreToolUse hook event`, 1, { run_id: input.runId, stage: input.stage, event_key: eventKey });
+    }
+    const claimed = context.db.run("UPDATE hook_events SET status = 'claimed', claimed_at = ? WHERE id = ? AND status = 'observed'", [context.now(), event.id]);
+    if (claimed.changes !== 1)
+        throw new AppError("trusted_session_binding_required", "matching lifecycle hook event was already claimed", 1, { run_id: input.runId, stage: input.stage });
+    return hookSessionIdentity(context, input.projectId, eventKey);
+}
 /** Trusted session identity is created by PreToolUse, never supplied by an agent. */
 export function sessionIdForHookEvent(context, projectId, eventKey) {
     const event = context.db.get("SELECT session_id FROM hook_events WHERE project_id = ? AND event_key = ?", [projectId, eventKey]);

package/dist/services/lifecycle-command.js

@@ -175,10 +175,18 @@ function lifecycleOperation(argv) {
         return "session_register";
     if (key === "stage start")
         return "stage_start";
+    if (key === "stage finish")
+        return "stage_finish";
+    if (key === "stage pause")
+        return "stage_pause";
     if (key === "stage resume")
         return "stage_resume";
     if (key === "work start")
         return "work_start";
+    if (key === "work finish")
+        return "work_finish";
+    if (key === "work fail")
+        return "work_fail";
     return null;
 }
 export function parseCommandArgs(argv) {

package/dist/services/run-recovery.js

@@ -0,0 +1,104 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { resolveProjectRoot } from "../storage/paths.js";
+import { requireProjectByRoot } from "./projects.js";
+import { appendFlowRunTimelineEvent } from "./runs.js";
+function requireRun(context, projectId, runId) {
+    const run = context.db.get("SELECT r.id, r.run_root, r.workspace_root, p.root AS project_root FROM runs r JOIN projects p ON p.id = r.project_id WHERE r.project_id = ? AND r.id = ?", [projectId, runId]);
+    if (!run?.run_root)
+        throw new AppError("runtime_missing", "RUN artifact root is unavailable", 1, { run_id: runId });
+    return run;
+}
+function parseObject(value, label) { try {
+    const parsed = JSON.parse(value);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed))
+        return parsed;
+}
+catch { /* validated below */ } throw new AppError("validation", `${label} must be a JSON object`, 2); }
+export function recoveryGuard(context, projectId, runId) { return context.db.get("SELECT recovery_id, project_id, run_id, generation, status, interruption_json, settlement_json, capture_path, created_at, updated_at, sealed_at, resumed_at FROM run_recovery_guards WHERE project_id = ? AND run_id = ? ORDER BY generation DESC LIMIT 1", [projectId, runId]) ?? null; }
+export function assertRunMutationAllowed(context, projectId, runId) { const guard = recoveryGuard(context, projectId, runId); if (guard && ["draining", "sealed", "resuming"].includes(guard.status))
+    throw new AppError("run_recovery_guarded", "RUN is retained for recovery; reconcile or resume its recovery operation before accepting a new lifecycle mutation", 1, { run_id: runId, recovery_id: guard.recovery_id, generation: guard.generation, status: guard.status }); }
+export function beginRunRecovery(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const run = requireRun(context, project.id, input.runId);
+    const interruption = parseObject(input.interruption, "interruption");
+    const prior = recoveryGuard(context, project.id, run.id);
+    if (prior && ["draining", "sealed", "resuming"].includes(prior.status))
+        return { ok: true, recovery: { ...prior, interruption: JSON.parse(prior.interruption_json) }, reused: true };
+    const recoveryId = `RCV-${crypto.randomUUID()}`, generation = (prior?.generation ?? 0) + 1, now = context.now();
+    context.db.run("INSERT INTO run_recovery_guards (recovery_id, project_id, run_id, generation, status, interruption_json, settlement_json, capture_path, created_at, updated_at, sealed_at, resumed_at) VALUES (?, ?, ?, ?, 'draining', ?, NULL, NULL, ?, ?, NULL, NULL)", [recoveryId, project.id, run.id, generation, JSON.stringify(interruption), now, now]);
+    appendFlowRunTimelineEvent(context, project.id, run.id, { type: "run_recovery_draining", recovery_id: recoveryId, generation, interruption });
+    return { ok: true, recovery: { recovery_id: recoveryId, run_id: run.id, generation, status: "draining", interruption } };
+}
+export function sealRunRecovery(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const run = requireRun(context, project.id, input.runId);
+    const guard = recoveryGuard(context, project.id, run.id);
+    if (!guard || guard.recovery_id !== input.recoveryId)
+        throw new AppError("recovery_not_found", "Recovery operation is not registered for this RUN", 1, { recovery_id: input.recoveryId, run_id: run.id });
+    const settlement = parseObject(input.settlement, "settlement");
+    if (settlement.settled !== true)
+        throw new AppError("recovery_not_settled", "Recovery capture requires an explicit settled tree receipt", 1, { recovery_id: guard.recovery_id });
+    if (guard.status === "sealed")
+        return { ok: true, recovery: { ...guard, settlement: JSON.parse(guard.settlement_json ?? "{}") }, reused: true };
+    if (guard.status !== "draining")
+        throw new AppError("recovery_invalid_state", "Recovery is not draining", 1, { recovery_id: guard.recovery_id, status: guard.status });
+    const now = context.now();
+    context.db.run("UPDATE run_recovery_guards SET status = 'sealed', settlement_json = ?, sealed_at = ?, updated_at = ? WHERE recovery_id = ? AND status = 'draining'", [JSON.stringify(settlement), now, now, guard.recovery_id]);
+    appendFlowRunTimelineEvent(context, project.id, run.id, { type: "run_recovery_sealed", recovery_id: guard.recovery_id, generation: guard.generation, settlement });
+    return { ok: true, recovery: { recovery_id: guard.recovery_id, run_id: run.id, generation: guard.generation, status: "sealed", settlement } };
+}
+export function recordRecoveryCapture(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const run = requireRun(context, project.id, input.runId);
+    const guard = recoveryGuard(context, project.id, run.id);
+    if (!guard || guard.recovery_id !== input.recoveryId || guard.status !== "sealed")
+        throw new AppError("recovery_invalid_state", "Recovery capture requires a sealed recovery operation", 1, { recovery_id: input.recoveryId, run_id: run.id });
+    const capture = path.resolve(input.capturePath);
+    if (!fs.existsSync(capture))
+        throw new AppError("recovery_capture_missing", "Recovery capture path is unavailable", 1, { capture });
+    context.db.run("UPDATE run_recovery_guards SET capture_path = ?, updated_at = ? WHERE recovery_id = ?", [capture, context.now(), guard.recovery_id]);
+    appendFlowRunTimelineEvent(context, project.id, run.id, { type: "run_recovery_capture_ready", recovery_id: guard.recovery_id, capture_path: capture });
+    return { ok: true, recovery_id: guard.recovery_id, capture_path: capture };
+}
+export function resumeRunRecovery(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const run = requireRun(context, project.id, input.runId);
+    const guard = recoveryGuard(context, project.id, run.id);
+    if (!guard || guard.recovery_id !== input.recoveryId)
+        throw new AppError("recovery_not_found", "Recovery operation is not registered for this RUN", 1, { recovery_id: input.recoveryId, run_id: run.id });
+    if (guard.status === "recovered")
+        return { ok: true, recovery_id: guard.recovery_id, generation: guard.generation, resumed: true, reused: true };
+    if (guard.status !== "sealed" || !guard.capture_path)
+        throw new AppError("recovery_capture_required", "Recovery must be sealed and captured before it can resume", 1, { recovery_id: guard.recovery_id, status: guard.status });
+    // The root coordinator keeps its same native Session and receives a recovery
+    // prompt from the eval runner. Only delegated Work is returned to the ready
+    // graph and therefore gets a fresh, addressable recovery packet.
+    const now = context.now(), running = context.db.all("SELECT work_id, started_at, status FROM works WHERE project_id = ? AND run_id = ? AND status = 'running' AND parent_work_id IS NOT NULL ORDER BY work_id", [project.id, run.id]);
+    context.db.exec("BEGIN IMMEDIATE");
+    try {
+        for (const work of running) {
+            const evidence = path.join(run.run_root, "recoveries", guard.recovery_id, "works", work.work_id), source = path.join(run.run_root, "works", work.work_id);
+            fs.mkdirSync(path.dirname(evidence), { recursive: true });
+            if (fs.existsSync(source) && !fs.existsSync(evidence))
+                fs.cpSync(source, evidence, { recursive: true, verbatimSymlinks: true });
+            context.db.run("INSERT INTO work_recovery_segments (recovery_id, work_id, generation, prior_started_at, evidence_path, status, created_at, updated_at) VALUES (?, ?, ?, ?, ?, 'prepared', ?, ?)", [guard.recovery_id, work.work_id, guard.generation, work.started_at, evidence, now, now]);
+            context.db.run("UPDATE work_sessions SET status = 'interrupted', completed_at = ?, updated_at = ? WHERE work_id = ? AND status = 'running'", [now, now, work.work_id]);
+            context.db.run("UPDATE works SET status = 'created', result = NULL, started_at = NULL, completed_at = NULL, updated_at = ? WHERE work_id = ? AND status = 'running'", [now, work.work_id]);
+        }
+        context.db.run("UPDATE run_recovery_guards SET status = 'recovered', resumed_at = ?, updated_at = ? WHERE recovery_id = ? AND status = 'sealed'", [now, now, guard.recovery_id]);
+        context.db.exec("COMMIT");
+    }
+    catch (error) {
+        context.db.exec("ROLLBACK");
+        throw error;
+    }
+    appendFlowRunTimelineEvent(context, project.id, run.id, { type: "run_recovery_resumed", recovery_id: guard.recovery_id, generation: guard.generation, interrupted_works: running.map((work) => work.work_id) });
+    return { ok: true, recovery_id: guard.recovery_id, generation: guard.generation, resumed: true, interrupted_works: running.map((work) => work.work_id) };
+}
+export function recoveryPromptForWork(context, workId) { const row = context.db.get("SELECT recovery_id, generation, evidence_path FROM work_recovery_segments WHERE work_id = ? AND status = 'prepared' ORDER BY generation DESC LIMIT 1", [workId]); return row ? { recoveryId: row.recovery_id, generation: row.generation, evidencePath: row.evidence_path } : null; }
+export function activateRecoveryWork(context, workId) { context.db.run("UPDATE work_recovery_segments SET status = 'running', updated_at = ? WHERE work_id = ? AND status = 'prepared'", [context.now(), workId]); }
+export function settleRecoveryWork(context, workId, status) { context.db.run("UPDATE work_recovery_segments SET status = ?, updated_at = ? WHERE work_id = ? AND status = 'running'", [status, context.now(), workId]); }
+export function inspectRunRecovery(context, input) { const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot)); const run = requireRun(context, project.id, input.runId); const guard = recoveryGuard(context, project.id, run.id); const works = context.db.all("SELECT w.work_id, w.status, s.recovery_id, s.status AS segment_status FROM works w LEFT JOIN work_recovery_segments s ON s.work_id = w.work_id AND s.generation = (SELECT MAX(generation) FROM work_recovery_segments latest WHERE latest.work_id = w.work_id) WHERE w.project_id = ? AND w.run_id = ? ORDER BY w.work_id", [project.id, run.id]); return { ok: true, run_id: run.id, recovery: guard ? { ...guard, interruption: JSON.parse(guard.interruption_json), settlement: guard.settlement_json ? JSON.parse(guard.settlement_json) : null } : null, works }; }

package/dist/services/stage-lifecycle.js

@@ -18,6 +18,7 @@ import { registerProject } from "./projects.js";
 import { registerProtocol } from "./protocols.js";
 import { previewNextEntityId } from "./ids.js";
 import { hookSessionIdentity, sessionIdForHookEvent } from "./hooks.js";
+import { assertRunMutationAllowed } from "./run-recovery.js";
 const stagePromptSections = [
     "stage_identity",
     "authoritative_runtime_facts",
@@ -119,6 +120,7 @@ export function startStage(context, input) {
     if (!runId)
         throw new AppError("usage", "stage start requires a RUN id or --bootstrap", 2);
     const before = runView(getFlowRunStatus(context, { projectRoot, runId }));
+    assertRunMutationAllowed(context, before.run.project_id, before.run.id);
     const dir = input.dir ?? defaultStageDir(input.stage, before.run.flow_kind);
     const attached = runView(attachFlowRunStage(context, {
         projectRoot,
@@ -263,6 +265,7 @@ export function finishStage(context, input) {
         throw new AppError("usage", "stage finish requires a RUN id", 2);
     const runId = input.runId;
     const view = runView(getFlowRunStatus(context, { projectRoot, runId }));
+    assertRunMutationAllowed(context, view.run.project_id, view.run.id);
     const existing = view.index.stage_runs?.find((stage) => stage.stage === input.stage);
     if (!existing) {
         throw new AppError("not_found", `Run stage is not attached: ${input.stage}`, 1, { run_id: view.run.id, stage: input.stage });

package/dist/services/usage.js

@@ -19,6 +19,14 @@ export function ingestOpenCodeUsage(context, input) {
 export function ingestAgyUsage(context, input) {
     return ingestHarnessUsage(context, input, { harness: "antigravity-cli", label: "Antigravity", idPrefix: "AUSG", sourceKind: "antigravity_cli_session_usage_v1" });
 }
+/** Droid counters must describe one physical Session; inclusive roots double-count children. */
+export function ingestDroidUsage(context, input) {
+    const payload = parseJsonObject(input.stdin || "{}", "Droid usage snapshot");
+    if (payload.usage_scope !== "physical_session" || !["complete", "partial"].includes(String(payload.completeness))) {
+        throw new Error("Droid usage requires physical_session scope and complete or partial completeness");
+    }
+    return ingestHarnessUsage(context, input, { harness: "droid-cli", label: "Droid", idPrefix: "DUSG", sourceKind: "droid_session_usage_v1" });
+}
 function ingestHarnessUsage(context, input, harness) {
     const payload = parseJsonObject(input.stdin || "{}", `${harness.label} usage snapshot`);
     const usage = object(payload.usage);
@@ -262,9 +270,9 @@ function toolCallsForLinks(context, links, observedAt) {
     result.status = result.observed_sessions === 0 ? "unavailable" : result.unavailable_sessions.length ? "partial" : "measured";
     return result;
 }
-function isExternalHarness(harness) { return harness === "zcode-acp" || harness === "grok-acp" || harness === "opencode-server" || harness === "antigravity-cli"; }
+function isExternalHarness(harness) { return harness === "droid-cli" || harness === "zcode-acp" || harness === "grok-acp" || harness === "opencode-server" || harness === "antigravity-cli"; }
 function harnessSourceKind(harness) {
-    return harness === "grok-acp" ? "grok_session_usage_v1" : harness === "zcode-acp" ? "zcode_session_usage_v1" : harness === "antigravity-cli" ? "antigravity_cli_session_usage_v1" : "opencode_session_usage_v1";
+    return harness === "droid-cli" ? "droid_session_usage_v1" : harness === "grok-acp" ? "grok_session_usage_v1" : harness === "zcode-acp" ? "zcode_session_usage_v1" : harness === "antigravity-cli" ? "antigravity_cli_session_usage_v1" : "opencode_session_usage_v1";
 }
 function readHarnessToolCallsWindow(context, harness, projectId, providerSessionId, startedAt, endedAt, observedAt) {
     if (!providerSessionId)
@@ -425,7 +433,7 @@ function hasInclusiveUsageSnapshot(context, projectId, harness, providerSessionI
 function readHarnessUsageWindow(context, harness, projectId, providerSessionId, startedAt, endedAt, observedAt) {
     if (!providerSessionId)
         return { status: "not_observable", diagnostic: "provider_session_id_missing" };
-    const snapshots = context.db.all(`SELECT observed_at, total_tokens, input_tokens, cache_read_input_tokens, cache_write_input_tokens, output_tokens, reasoning_output_tokens
+    const snapshots = context.db.all(`SELECT completeness, observed_at, total_tokens, input_tokens, cache_read_input_tokens, cache_write_input_tokens, output_tokens, reasoning_output_tokens
        FROM harness_usage_snapshots
       WHERE project_id = ? AND harness = ? AND provider_session_id = ? AND observed_at <= ?
       ORDER BY observed_at, id`, [projectId, harness, providerSessionId, observedAt]);
@@ -434,6 +442,8 @@ function readHarnessUsageWindow(context, harness, projectId, providerSessionId,
     const before = snapshots.filter((snapshot) => Date.parse(snapshot.observed_at) <= Date.parse(startedAt)).at(-1);
     if (!last || !before || last === before)
         return { status: "not_yet_emitted", diagnostic: `${harness}_usage_window_incomplete` };
+    if (harness === "droid-cli" && (last.completeness !== "complete" || before.completeness !== "complete"))
+        return { status: "not_observable", diagnostic: "droid-cli_usage_window_partial" };
     const delta = (value, baseline) => value === null || baseline === null ? null : Math.max(0, value - baseline);
     const input = delta(last.input_tokens, before.input_tokens);
     const cacheRead = delta(last.cache_read_input_tokens, before.cache_read_input_tokens);

package/dist/services/vnext-fanout.js

@@ -135,3 +135,43 @@ export async function reconcileVnextFanout(context, input) {
     appendFlowRunTimelineEvent(context, project.id, input.runId, { type: "native_child_reconciliation", stage: input.stage, observations: value, issues, reconciled });
     return { ok: true, issues, reconciled };
 }
+/**
+ * Records every terminal native child at the Stage where it is first observed.
+ * This is separate from fan-out settlement: a historical child can be valid
+ * evidence for an earlier Work, while an unbound terminal child is retained
+ * as an inconsistency instead of being rediscovered in a later review wave.
+ */
+export function observeVnextNativeChildren(context, input) {
+    const value = input.observations;
+    if (!value || typeof value.harness_id !== "string" || !value.harness_id || typeof value.parent_session_id !== "string" || !Array.isArray(value.children)
+        || value.children.some(child => !child || typeof child.session_id !== "string" || !["running", "unknown", "completed", "failed", "cancelled"].includes(String(child.status))))
+        throw new AppError("usage", "Expected native observations: harness_id, parent_session_id and children[{session_id,status}]", 2);
+    if (new Set(value.children.map(child => child.session_id)).size !== value.children.length)
+        throw new AppError("usage", "Native observations must contain each child Session exactly once", 2);
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const parent = storageSessionId({ harness_id: value.harness_id, session_id: value.parent_session_id });
+    const issues = [], history = [], pending = [];
+    for (const child of value.children) {
+        const sessionId = storageSessionId({ harness_id: value.harness_id, session_id: String(child.session_id) });
+        const links = context.db.all(`SELECT ws.id, ws.work_id, ws.status, w.status AS work_status, w.parent_work_id, s.current_stage
+         FROM work_sessions ws JOIN works w ON w.work_id = ws.work_id
+         JOIN sessions s ON s.project_id = w.project_id AND s.session_id = ws.session_id
+        WHERE w.project_id = ? AND w.run_id = ? AND ws.session_id = ? AND s.parent_session_id = ? ORDER BY ws.created_at`, [project.id, input.runId, sessionId, parent]);
+        if (child.status === "running" || child.status === "unknown") {
+            pending.push({ session_id: child.session_id, outcome: child.status, links: links.map(link => ({ work_id: link.work_id, work_session_id: link.id })) });
+            continue;
+        }
+        if (!links.length) {
+            issues.push({ code: "unbound_native_delegation_detected", session_id: child.session_id, outcome: child.status, detected_at_stage: input.stage, origin_stage: "unknown" });
+            continue;
+        }
+        if (links.length !== 1) {
+            issues.push({ code: "child_execution_ambiguous", session_id: child.session_id, outcome: child.status, detected_at_stage: input.stage, work_ids: links.map(link => link.work_id) });
+            continue;
+        }
+        const link = links[0];
+        history.push({ session_id: child.session_id, outcome: child.status, work_id: link.work_id, work_session_id: link.id, work_status: link.work_status, origin_stage: link.current_stage ?? "unknown", detected_at_stage: input.stage });
+    }
+    appendFlowRunTimelineEvent(context, project.id, input.runId, { type: "native_child_observation", stage: input.stage, observations: value, issues, history, pending });
+    return { ok: true, issues, history, pending };
+}