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

package/dist/services/controller-fanout.js

@@ -0,0 +1,120 @@
+import { AppError } from "../shared/errors.js";
+import { getVnextFanoutStatus, observeVnextNativeChildren, reconcileVnextFanout, subagentCapacityKey } from "./vnext-fanout.js";
+import { getFlowRunVariables } from "./runs.js";
+import { dispatchVnextPlanReview } from "./vnext-plan-review.js";
+import { resolveExecutionPolicy } from "./execution-policy.js";
+/** Stage entry acknowledges the packet before the controller issues child commands. */
+export function controllerStageEntryPrompt(stage, command, responseFile) {
+    return [
+        `Start the assigned ${stage} Stage now. Your first tool call must be this exact standalone command:`,
+        command,
+        `Read the complete authoritative packet saved to ${JSON.stringify(responseFile)}, including worker_prompt_markdown. If a read is truncated, continue until the entire packet has been read.`,
+        "If the returned packet has orchestration.kind = work_fanout, this Turn is only Stage entry: acknowledge the packet and end your Turn immediately. The packet describes the whole Stage, but its graph/dispatch/finish instructions belong to later controller continuations. Do not list, start, launch or finish Work, create children, change files, run checks, or finish the Stage in this entry Turn. The controller will inspect the graph and send the next assignment with exact issued commands (or dispatch external workers itself).",
+        "Otherwise perform this Stage's semantic work and stop at its boundary or a declared HITL boundary. Do not start a successor Stage.",
+        "Copy runtime-issued lifecycle commands verbatim as standalone calls. Never generate an invocation ID, substitute a shell variable for it, or borrow one from another command. If a required command is missing or rejected without a returned retry command, report the exact error and end the Turn so the controller can handle it."
+    ].join("\n\n");
+}
+/** The shared controller owns this former eval-only Work-graph decision. */
+export async function nextControllerFanout(context, input) {
+    const children = input.children.filter(child => child.status !== "settled_by_root");
+    const observations = { harness_id: input.harness, parent_session_id: input.sessionId, children };
+    if (children.length) {
+        const observed = observeVnextNativeChildren(context, { ...input, observations });
+        const issues = observed.issues;
+        if (issues.length)
+            throw new AppError("fanout_reconciliation_required", "Native children have unresolved lifecycle ownership", 1, { issues });
+    }
+    let fanout = getVnextFanoutStatus(context, input).orchestration;
+    if (!fanout)
+        return { kind: "none" };
+    if (children.length) {
+        const reconciled = await reconcileVnextFanout(context, { ...input, observations });
+        const issues = reconciled.issues.filter(issue => issue.code !== "child_check_in_progress");
+        if (issues.length)
+            throw new AppError("fanout_reconciliation_required", "Native child outcome requires reconciliation, not replay", 1, { issues });
+        if (children.some(child => child.status === "running" || child.status === "unknown"))
+            return { kind: "wait", reason: "native_children_unsettled" };
+        fanout = getVnextFanoutStatus(context, input).orchestration;
+    }
+    if (fanout.state === "dispatch_required") {
+        dispatchVnextPlanReview(context, input);
+        fanout = getVnextFanoutStatus(context, input).orchestration;
+        if (fanout.state === "dispatch_required" || fanout.state === "capacity_required")
+            return { kind: "wait", reason: "qualified_capacity_required" };
+    }
+    const prompt = (text) => ({ kind: "prompt", prompt: text, fingerprint: JSON.stringify({ stage: input.stage, parent: fanout.parent_work_id, works: fanout.works, text }) });
+    if (fanout.state === "coordinator_required")
+        return prompt(`Continue the current ${input.stage} Stage using its authoritative packet. Materialize only its required Work graph with real dependencies. Do not launch children, finish the Stage, or start a successor. Return after registering the graph; the runtime will dispatch its ready Work.`);
+    if (fanout.works.failed || fanout.works.cancelled)
+        return prompt(`Some ${input.stage} child Work failed or was cancelled. Inspect its recorded receipts. Choose a legal scoped repair/retry or block the Stage with the concrete reason. Do not relaunch settled siblings or infer success from a child that omitted work finish.`);
+    if (fanout.works.ready.length) {
+        const choices = fanout.works.ready.map(work => {
+            const payload = context.db.get("SELECT payload_json FROM works WHERE work_id = ?", [work.work_id])?.payload_json;
+            const override = payload ? JSON.parse(payload).execution_override : undefined;
+            return { work, resolved: resolveExecutionPolicy({ ddFlowHome: context.ddFlowHome, policy: input.policy, profiles: input.profiles, stage: input.stage, ...(override ? { work: override } : {}) }) };
+        });
+        const external = choices.filter(choice => choice.resolved.delegation.mode === "external");
+        if (external.length) {
+            const maximum = Math.min(...external.map(choice => choice.resolved.delegation.max_parallel ?? 1));
+            return { kind: "external", works: external.slice(0, maximum).map(choice => choice.work) };
+        }
+        const variables = getFlowRunVariables(context, input);
+        const capacity = variables.variables[subagentCapacityKey];
+        if (typeof capacity !== "number" || !Number.isInteger(capacity) || capacity < 1)
+            return { kind: "wait", reason: "qualified_capacity_required" };
+        const wave = choices.slice(0, capacity).map(choice => choice.work);
+        return prompt([
+            `Launch exactly ${wave.length} direct native children for the current ${input.stage} Stage; the recorded capacity is ${capacity}.`,
+            "Use this harness's native child mechanism, not external roots or forks. Wait for these children to settle; do not cancel siblings because one failed. Do not finish this Stage or start a successor in this Turn.",
+            ...wave.map(work => {
+                if (!work.work_id || !work.start_command)
+                    throw new AppError("fanout_contract_invalid", "Ready Work omits its trusted start command", 1);
+                return `Assign one leaf child Work ${work.work_id}. ${work.launch_policy === "fresh_agent_required" ? "Use empty, non-inherited context when supported; a new Session id alone does not prove empty context." : "Inherit context only through the harness's declared mechanism."}\nIts first technical action must be this exact standalone command:\n${work.start_command}\nUse only the Work packet returned by it. Complete its declared result and exact work finish command, then stop. Do not create children or start another Work. Missing facts go through the Work's failure/result contract; only the coordinator handles Stage HITL.`;
+            })
+        ].join("\n\n"));
+    }
+    if (fanout.works.running)
+        return { kind: "wait", reason: "work_receipts_pending" };
+    if (fanout.works.created)
+        throw new AppError("fanout_graph_stalled", "Created Work has no ready or running dependency path", 1);
+    return prompt(`All declared ${input.stage} child Work has settled (${fanout.works.completed} completed). Read the accepted result receipts and continue this Stage's semantic decision under its original packet. Execute an exact repair command returned by a rejected stage finish; a rejection alone does not create repair Work. Return after finish or after declaring a repair graph. Do not start a successor Stage.`);
+}
+/** Normalize provider-observed topology only; never parse assistant prose. */
+export function controllerNativeChildren(receipt, rootSessionId) {
+    const candidates = [];
+    const object = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : {};
+    const list = (value) => Array.isArray(value) ? value : [];
+    const text = (value, keys) => { for (const key of keys)
+        if (typeof value[key] === "string" && value[key])
+            return value[key]; return null; };
+    const settledTree = new Set(list(receipt.tree_observations)
+        .filter(value => object(value).settled === true)
+        .map(value => text(object(value), ["provider_session_id", "session_id"]))
+        .filter((id) => id !== null));
+    const add = (raw, source, scopedParent = null, fallback = "unknown") => {
+        const value = object(raw);
+        const id = text(value, ["provider_session_id", "session_id", "sessionId", "childSessionId", "conversation_id", "conversationId", "id", "subagentId"]);
+        const parent = text(value, ["parent_provider_session_id", "parent_session_id", "parentSessionId", "parentID", "parentId"]) ?? scopedParent;
+        if (!id || parent !== rootSessionId)
+            return;
+        const state = String(value.status ?? value.state ?? fallback).toLowerCase();
+        const status = ["completed", "complete", "done", "idle", "success", "succeeded"].includes(state) ? "completed" : state === "settled_by_root" ? "settled_by_root" : ["failed", "error"].includes(state) ? "failed" : ["cancelled", "canceled"].includes(state) ? "cancelled" : ["running", "active", "pending"].includes(state) ? "running" : fallback;
+        candidates.push({ session_id: id, parent_session_id: parent, status: status === "unknown" && settledTree.has(id) ? "settled_by_root" : status, source });
+    };
+    for (const value of list(receipt.descendants))
+        add(value, "adapter.descendants");
+    for (const value of list(receipt.children))
+        add(value, "opencode.session.children");
+    const subagents = object(object(receipt.evidence).subagents ?? receipt.subagents);
+    for (const value of list(subagents.running))
+        add(value, "zcode/session/subagents", rootSessionId, "running");
+    for (const value of [...list(subagents.completed), ...list(object(subagents.ended).items)])
+        add(value, "zcode/session/subagents", rootSessionId, "completed");
+    const unique = new Map();
+    for (const child of candidates) {
+        const previous = unique.get(child.session_id);
+        if (!previous || previous.status === "unknown" || previous.status === "running" && child.status !== "running")
+            unique.set(child.session_id, child);
+    }
+    return [...unique.values()].sort((left, right) => left.session_id.localeCompare(right.session_id));
+}

package/dist/services/dashboard.js

@@ -19,6 +19,8 @@ export function getCmuxStatus(context, input) {
 }
 export function renderDashboard(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    if (projectRecoveryGuarded(context, project.id))
+        throw new AppError("run_recovery_guarded", "Project dashboard is frozen while its RUN is retained for recovery", 1);
     const format = parseDashboardFormat(input.format);
     if (format === "html") {
         if (input.protocol) {
@@ -170,6 +172,10 @@ export function refreshAllDashboards(context, input = {}) {
 }
 export function autoRefreshDashboards(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    // Hooks and usage ingestion continue to record receipts after capture.
+    // Their derived timestamp must not mutate the captured workspace.
+    if (projectRecoveryGuarded(context, project.id))
+        return { ok: true, skipped: true, reason: "run_recovery_guarded" };
     const config = readProjectConfig(context, project.id);
     if (!config.dashboard.auto_refresh) {
         return { ok: true, skipped: true, reason: "dashboard_auto_refresh_disabled" };
@@ -196,6 +202,9 @@ export function autoRefreshDashboards(context, input) {
     }
     return result;
 }
+function projectRecoveryGuarded(context, projectId) {
+    return Boolean(context.db.get("SELECT 1 FROM run_recovery_guards WHERE project_id = ? AND status IN ('draining', 'sealed', 'resuming') LIMIT 1", [projectId]));
+}
 export function dashboardSummary(context, projectId, projectRoot) {
     const config = readProjectConfig(context, projectId);
     return {

package/dist/services/engines.js

@@ -12,7 +12,7 @@ import { requireProtocol } from "./protocols.js";
 import { resolveCanonRootBeforeContext } from "./canon.js";
 import { appendAudit } from "./audit.js";
 import { findProjectByRoot } from "./projects.js";
-import { allRunEngineBindings, findRunHome, readRunEngineBinding, runEngineBindingSchemaId, writeRunEngineBinding } from "./run-engine-bindings.js";
+import { allRunEngineBindings, locateRunRoot, readRunEngineBinding, runEngineBindingSchemaId, writeRunEngineBinding } from "./run-engine-bindings.js";
 export const engineManifestSchemaId = "dd-flow/engine-manifest@1";
 const routerNativeFamilies = new Set(["engine", "version", "schema"]);
 const sourceFile = fileURLToPath(import.meta.url);
@@ -117,7 +117,7 @@ export function installCurrentEngine(context, input = {}) {
 }
 export function listEngines(context) {
     const root = engineStoreRoot(context.ddFlowHome);
-    const engines = readInstalledManifests(root).map(manifestSummary);
+    const engines = readInstalledManifests(root).map(manifest => manifestSummary(manifest));
     return { ok: true, schema_id: "dd-flow/engine-list@1", engine_store: root, engines };
 }
 export function engineInfo(context, input) {
@@ -138,11 +138,10 @@ export function resolveEngine(context, input = {}) {
 export function doctorEngines(context, input = {}) {
     const root = engineStoreRoot(context.ddFlowHome);
     const installed = readInstalledManifests(root);
-    const checks = installed.map((manifest) => ({
-        engine: manifestSummary(manifest),
-        status: manifestHealthy(manifest) ? "ok" : "corrupt",
-        diagnostics: manifestDiagnostics(manifest)
-    }));
+    const checks = installed.map(manifest => {
+        const diagnostics = manifestDiagnostics(manifest);
+        return { engine: manifestSummary(manifest, diagnostics), status: diagnostics.length ? "corrupt" : "ok", diagnostics };
+    });
     const classification = input.classification ?? classifyCliOperation(["engine", "doctor"], input.env ?? context.env);
     const selection = selectEngine(context, input, {}, classification);
     return {
@@ -174,7 +173,9 @@ export function routeArgsThroughEngine(context, args, io, stdin, env, resolvedPr
     if (!selection.selected)
         return Promise.resolve(null);
     const current = getCliBuildInfo();
-    if (selection.selected.package_name === current.package_name && selection.selected.package_version === current.version) {
+    const currentRoot = findPackageRoot(path.dirname(sourceFile));
+    if (selection.selected.package_name === current.package_name && selection.selected.package_version === current.version
+        && currentRoot !== null && fs.realpathSync(selection.selected.snapshot_root) === fs.realpathSync(currentRoot)) {
         return Promise.resolve({ routed: true, exitCode: 0, inProcess: true });
     }
     const entrypoint = resolveManifestEntrypoint(selection.selected);
@@ -182,7 +183,7 @@ export function routeArgsThroughEngine(context, args, io, stdin, env, resolvedPr
 }
 export function bindRunEngine(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
-    const located = findRunHome(context.ddFlowHome, projectRoot, input.runId);
+    const located = locateRunRoot(context.db, projectRoot, input.runId);
     if (!located)
         throw new AppError("not_found", `RUN is not registered in router storage: ${input.runId}`, 1, { run_id: input.runId, project_root: projectRoot });
     const existing = readRunEngineBinding(located.binding_path, { allowMissing: true });
@@ -250,13 +251,45 @@ export function bindCurrentEngineToRun(context, input) {
         engine: engineIdentity(manifest),
         probe: { status: "not_required", command: null }
     };
-    return writeRunEngineBinding(path.join(input.runHome, "engine-binding.json"), binding).binding;
+    return writeRunEngineBinding(path.join(input.runRoot, "engine-binding.json"), binding).binding;
+}
+/** Forks are a new execution authority.  The source binding stays immutable;
+ * this replaces only the copied binding after proving the selected engine can
+ * read the copied RUN. */
+export function upgradeForkedRunEngine(context, input) {
+    const projectRoot = resolveProjectRoot(input.projectRoot);
+    const located = locateRunRoot(context.db, projectRoot, input.runId);
+    if (!located)
+        throw new AppError("not_found", `Forked RUN is not registered: ${input.runId}`, 1);
+    const manifest = requireBoundManifest(context.ddFlowHome, {
+        packageName: getCliBuildInfo().package_name,
+        packageVersion: input.engineVersion,
+        ...(input.integrityChecksum ? { integrityChecksum: input.integrityChecksum } : {})
+    });
+    const requested = engineIdentity(manifest);
+    readRunEngineBinding(located.binding_path);
+    const lineage = path.join(located.run_root, "fork-lineage.json");
+    if (!fs.existsSync(lineage))
+        throw new AppError("fork_lineage_missing", "Engine upgrade is permitted only for a derived RUN", 1, { run_id: located.run_id });
+    const probeArgs = ["run", "status", located.run_id, "--project-root", projectRoot, "--json"];
+    const probe = spawnSync(process.execPath, [resolveManifestEntrypoint(manifest), ...probeArgs], {
+        cwd: manifest.snapshot_root,
+        env: { ...process.env, ...context.env, DD_FLOW_HOME: context.ddFlowHome, DD_FLOW_ENGINE_MODE: "1", DD_FLOW_ENGINE_HOME: manifest.snapshot_root },
+        encoding: "utf8", timeout: 30_000
+    });
+    if (probe.status !== 0)
+        throw new AppError("fork_engine_probe_failed", "Selected engine cannot read the forked RUN", 1, { run_id: located.run_id, engine: manifestSummary(manifest), stderr: probe.stderr.slice(0, 2000) });
+    const binding = { schema_id: runEngineBindingSchemaId, run_id: located.run_id, project_root: projectRoot, bound_at: context.now(), source: "fork_upgrade", reason: requiredText(input.reason, "reason"), engine: requested, probe: { status: "passed", command: `dd-flow ${probeArgs.join(" ")}` } };
+    const temporary = `${located.binding_path}.fork-${process.pid}-${Date.now()}.tmp`;
+    fs.writeFileSync(temporary, `${JSON.stringify(binding, null, 2)}\n`);
+    fs.renameSync(temporary, located.binding_path);
+    return binding;
 }
 function boundRunEngineForArgs(context, args, projectRoot) {
     const runId = runIdForArgs(args);
     if (!runId || !projectRoot)
         return null;
-    const located = findRunHome(context.ddFlowHome, projectRoot, runId);
+    const located = locateRunRoot(context.db, projectRoot, runId);
     if (!located)
         return null;
     const binding = readRunEngineBinding(located.binding_path, { allowMissing: true });
@@ -274,6 +307,8 @@ function runIdForArgs(args) {
     const [family, command, ...rest] = args;
     const parsed = parseLightArgs(rest);
     if (family === "run" && command !== "start" && command !== "list") {
+        if (["drive", "control", "recovery", "capacity"].includes(command ?? ""))
+            return option(parsed, "run");
         if (command === "flags")
             return positional(parsed, 1);
         return positional(parsed, 0);
@@ -383,11 +418,7 @@ export function selectEngine(context, input, options = {}, classification = inpu
     const manifests = readInstalledManifests(engineStoreRoot(context.ddFlowHome))
         .filter((manifest) => manifest.package_name === packageName)
         .filter((manifest) => requiredRange !== null && satisfiesRange(manifest.package_version, requiredRange))
-        .filter((manifest) => options.allowCurrentInProcess
-        && manifest.package_name === build.package_name
-        && manifest.package_version === build.version
-        ? true
-        : manifestHealthy(manifest))
+        .filter((manifest) => manifestHealthy(manifest))
         .sort((a, b) => {
         const versionOrder = compareSemverStrings(b.package_version, a.package_version);
         if (versionOrder !== 0)
@@ -847,7 +878,7 @@ function manifestDiagnostics(manifest, options = {}) {
     }
     return diagnostics;
 }
-function manifestSummary(manifest) {
+function manifestSummary(manifest, diagnostics = manifestDiagnostics(manifest, { checkEntrypoint: false })) {
     return {
         schema_id: manifest.schema_id,
         package_name: manifest.package_name,
@@ -859,8 +890,8 @@ function manifestSummary(manifest) {
         snapshot_root: manifest.snapshot_root,
         resolved_entrypoint: safeResolveManifestEntrypoint(manifest),
         installed_at: manifest.installed_at,
-        healthy: manifestHealthy(manifest),
-        diagnostics: manifestDiagnostics(manifest)
+        healthy: diagnostics.length === 0,
+        diagnostics
     };
 }
 function resolveManifestEntrypoint(manifest) {