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

package/dist/services/projects.js

@@ -140,7 +140,7 @@ export function migrateProjectIds(context, input) {
         throw new AppError("conflict", `Target project id already exists: ${target.id}`, 1, plan);
     }
     context.db.exec("PRAGMA foreign_keys = OFF");
-    context.db.exec("BEGIN IMMEDIATE");
+    context.db.beginWriteTransaction();
     try {
         context.db.run("UPDATE projects SET id = ?, short_id = ?, slug = ?, state_root = ?, updated_at = ? WHERE id = ?", [target.id, target.short_id, target.slug, target.state_root, now, oldId]);
         for (const table of projectReferenceTables()) {
@@ -232,9 +232,13 @@ export function findProjectByRoot(context, root) {
     return context.db.get("SELECT * FROM projects WHERE root = ?", [root]);
 }
 export function requireProjectByRoot(context, root) {
-    const project = findProjectByRoot(context, root);
+    // Callers may receive a path through a native adapter or shell.  Resolve
+    // aliases such as macOS `/var` -> `/private/var` before comparing with the
+    // canonical root persisted in the project registry.
+    const canonical = normalizeStoredRoot(root);
+    const project = findProjectByRoot(context, canonical);
     if (!project) {
-        throw new AppError("not_found", `Project is not registered: ${root}`, 1);
+        throw new AppError("not_found", `Project is not registered: ${canonical}`, 1);
     }
     return project;
 }

package/dist/services/prompts.js

@@ -136,7 +136,9 @@ export function renderWorkerPrompt(context, input) {
     };
 }
 function runHomePath(run) {
-    return run.run_home_path ?? path.dirname(run.run_index_path);
+    if (!run.run_root)
+        throw new AppError("runtime_missing", "RUN has no artifact root", 1, { run_id: run.id });
+    return run.run_root;
 }
 function readWorkerTask(taskFile, runHome) {
     const resolved = path.resolve(taskFile);
@@ -204,7 +206,7 @@ function protocolIdForRun(context, projectId, runId) {
     return run.subject_id;
 }
 function requireRun(context, projectId, runId) {
-    const row = context.db.get("SELECT id, project_id, subject_type, subject_id, workspace_root, run_index_path, run_home_path, index_json FROM runs WHERE project_id = ? AND (id = ? OR short_id = ?)", [projectId, runId, runId]);
+    const row = context.db.get("SELECT id, project_id, subject_type, subject_id, workspace_root, run_root, index_json FROM runs WHERE project_id = ? AND (id = ? OR short_id = ?)", [projectId, runId, runId]);
     if (!row)
         throw new AppError("not_found", `Run is not found: ${runId}`, 1);
     return row;

package/dist/services/protocols.js

@@ -416,7 +416,7 @@ export function syncProtocolFromRun(context, input) {
         next_action: nextActionForSyncedTarget(targetStage),
         updated_at: now
     };
-    context.db.exec("BEGIN IMMEDIATE");
+    context.db.beginWriteTransaction();
     try {
         persistProtocolState(context, protocol, nextState);
         if (targetStage === "ready_for_merge") {
@@ -486,7 +486,7 @@ export function cancelProtocol(context, input) {
     const now = context.now();
     const worktree = context.db.get("SELECT worktree_path, status FROM worktree_records WHERE project_id = ? AND protocol_id = ?", [protocol.project_id, protocol.id]);
     const worktreeRemoval = input.worktree === "remove" ? removeProtocolWorktreeBeforeCancel(protocol, state, worktree, input.force) : undefined;
-    context.db.exec("BEGIN IMMEDIATE");
+    context.db.beginWriteTransaction();
     try {
         const nextState = {
             ...state,
@@ -733,9 +733,18 @@ function releaseRelatedMergeLocks(context, protocol, reason) {
     return { ok: true, released: released.length, locks: released };
 }
 export function readProtocolRuntimeState(context, protocol) {
+    const expected = runtimeStateJsonPath(context.ddFlowHome, protocol.project_id, protocol.id);
+    if (protocol.state_path !== expected)
+        throw new AppError("protocol_state_migration_required", "Protocol runtime path requires explicit cleanup scan/apply before use", 1, { protocol_id: protocol.id, path: protocol.state_path, expected_path: expected });
+    return repairProtocolRuntimeState(context, protocol);
+}
+/** Explicit cleanup migration; productive readers accept only the current path. */
+export function repairProtocolRuntimeState(context, protocol) {
     const diagnostics = [];
     normalizeProtocolPlanPath(context, protocol, diagnostics);
     try {
+        if (protocol.state_path !== runtimeStateJsonPath(context.ddFlowHome, protocol.project_id, protocol.id))
+            throw new AppError("protocol_state_migration_required", "Retired state files are not runtime authority", 1);
         return { state: readStateFile(protocol.state_path, protocol.id), diagnostics };
     }
     catch {

package/dist/services/recovery-observation-budget.js

@@ -0,0 +1,61 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { AppError } from "../shared/errors.js";
+export const recoveryObservationBudgetMs = 120_000;
+const activeObservation = new AsyncLocalStorage();
+export const withRecoveryObservation = (budget, action) => activeObservation.run(budget, action);
+export const recoveryRpcTimeout = (maximum) => {
+    const observation = activeObservation.getStore();
+    // An unbounded productive transport wait is still bounded while recovery is
+    // actively reconciling. Outside recovery, its owner policy decides when to
+    // stop rather than a hidden adapter timer.
+    if (maximum === null)
+        return observation ? observation.timeout() : null;
+    return observation?.timeout(maximum ?? 30_000) ?? maximum ?? 30_000;
+};
+/** Call only while holding the existing owner-claim transaction. A replay of
+ * an explicit request never replenishes time, even after another request. */
+export function renewRecoveryObservation(snapshot, requestId) {
+    if (!requestId.trim() || requestId.length > 200)
+        throw new AppError("usage", "Reconciliation requires a nonempty request ID of at most 200 characters", 2);
+    const previous = snapshot.recovery_observation;
+    const ids = previous?.reconciliation_ids ?? [];
+    if (!Array.isArray(ids) || ids.some(id => typeof id !== "string"))
+        throw new AppError("recovery_observation_invalid", "Retained reconciliation identities are malformed", 1);
+    if (ids.includes(requestId))
+        return snapshot;
+    return { ...snapshot, recovery_observation: { budget_ms: recoveryObservationBudgetMs, remaining_ms: recoveryObservationBudgetMs, reconciliation_ids: [...ids, requestId], poll_index: 0 } };
+}
+/**
+ * Measures only time this owner can actually observe. Large scheduler gaps
+ * reset the sample instead of turning host sleep into evidence about a remote
+ * process. Persisting the remaining budget makes a recovered owner continue
+ * reconciliation rather than silently receiving a new unlimited wait.
+ */
+export function recoveryObservationBudget(saved, monotonic = () => performance.now()) {
+    const prior = saved && typeof saved === "object" ? saved.recovery_observation : null;
+    let remaining = typeof prior?.remaining_ms === "number" && Number.isFinite(prior.remaining_ms)
+        ? Math.max(0, Math.min(recoveryObservationBudgetMs, prior.remaining_ms))
+        : prior == null ? recoveryObservationBudgetMs : 0;
+    let last = monotonic();
+    let pollIndex = Number.isSafeInteger(prior?.poll_index) && prior.poll_index >= 0 ? prior.poll_index : 0;
+    const observation = {
+        exhausted: () => {
+            const current = monotonic();
+            const elapsed = current - last;
+            last = current;
+            // A gap means this process was not observing; it never proves progress
+            // or death and therefore does not consume the reconciliation budget.
+            if (elapsed >= 0 && elapsed <= 60_000)
+                remaining = Math.max(0, remaining - elapsed);
+            return remaining === 0;
+        },
+        state: () => ({ budget_ms: recoveryObservationBudgetMs, remaining_ms: Math.ceil(remaining), reconciliation_ids: prior?.reconciliation_ids ?? [], poll_index: pollIndex }),
+        timeout: (maximum = 30_000) => {
+            if (observation.exhausted())
+                throw new AppError("recovery_observation_budget_exhausted", "Recovery observation budget exhausted; explicit reconciliation is required", 1);
+            return Math.max(1, Math.min(maximum, Math.ceil(remaining)));
+        },
+        nextDelay: () => Math.min([1000, 2000, 5000, 10000][Math.min(pollIndex++, 3)], Math.ceil(remaining)),
+    };
+    return observation;
+}

package/dist/services/recovery-snapshot-database.js

@@ -0,0 +1,107 @@
+import { DatabaseSync } from "node:sqlite";
+import fs from "node:fs";
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { registerStoreWriter } from "../storage/writer-contract.js";
+import { managedProcessRuntimeHome } from "./managed-processes.js";
+/** Export one RUN's relational evidence, never mutate the live authority. */
+export function captureRecoveryDatabase(source, output, projectId, runId, protocolIds = []) {
+    source.exec(`VACUUM INTO '${output.replace(/'/g, "''")}'`);
+    const db = new DatabaseSync(output);
+    let complete = false;
+    try {
+        registerStoreWriter(db);
+        db.exec("PRAGMA foreign_keys = OFF; PRAGMA secure_delete = ON; BEGIN IMMEDIATE");
+        db.exec("CREATE TEMP TABLE capture_scope (project_id TEXT, run_id TEXT)");
+        db.prepare("INSERT INTO capture_scope VALUES (?, ?)").run(projectId, runId);
+        db.exec("CREATE TEMP TABLE capture_protocols (id TEXT)");
+        for (const id of protocolIds)
+            db.prepare("INSERT INTO capture_protocols VALUES (?)").run(id);
+        if (!db.prepare("SELECT 1 FROM runs WHERE (project_id, id) IN (SELECT * FROM capture_scope)").get())
+            throw new AppError("snapshot_run_missing", "Recovery export requires the selected RUN", 1);
+        const ownRun = "(project_id, run_id) IN (SELECT * FROM capture_scope)";
+        const ownProject = "project_id IN (SELECT project_id FROM capture_scope)";
+        const works = `SELECT work_id FROM works WHERE ${ownRun}`;
+        if (db.prepare(`SELECT 1 FROM sessions WHERE ${ownProject} AND run_id IS NOT NULL AND run_id NOT IN (SELECT run_id FROM capture_scope) AND session_id IN (SELECT session_id FROM work_sessions WHERE work_id IN (${works})) LIMIT 1`).get())
+            throw new AppError("snapshot_scope_conflict", "Selected Work refers to a Session currently bound to another RUN", 1);
+        const sessions = `SELECT session_id FROM sessions WHERE ${ownProject} AND (run_id IN (SELECT run_id FROM capture_scope) OR session_id IN (SELECT session_id FROM work_sessions WHERE work_id IN (${works})))`;
+        const nativeSessions = `SELECT harness, provider_session_id FROM sessions WHERE ${ownProject} AND session_id IN (${sessions})`;
+        const invocations = "json_extract(scope_json, '$.runId') IN (SELECT run_id FROM capture_scope) AND json_extract(scope_json, '$.projectRoot') IN (SELECT root FROM projects WHERE id IN (SELECT project_id FROM capture_scope))";
+        const invocationReceipts = db.prepare("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name = 'lifecycle_invocations'").get()
+            ? ` OR event_key IN (SELECT event_key FROM lifecycle_invocations WHERE ${invocations})` : "";
+        const protocols = `SELECT id FROM capture_protocols UNION SELECT subject_id FROM runs WHERE (project_id, id) IN (SELECT * FROM capture_scope) UNION SELECT value FROM merge_requests, json_each(merge_requests.protocol_ids_json) WHERE ${ownRun} UNION SELECT protocol_id FROM flow_jobs WHERE ${ownRun}`;
+        const rules = {
+            dd_flow_writer_contract: "1",
+            dd_flow_writer_migrations: "0",
+            projects: "id IN (SELECT project_id FROM capture_scope)",
+            runs: "(project_id, id) IN (SELECT * FROM capture_scope)",
+            sessions: `${ownProject} AND session_id IN (${sessions})`,
+            work_sessions: `work_id IN (${works})`, work_launches: `work_id IN (${works})`,
+            work_recovery_segments: `work_id IN (${works})`,
+            run_recovery_bindings: `recovery_id IN (SELECT recovery_id FROM run_recovery_guards WHERE ${ownRun})`,
+            lifecycle_invocations: invocations,
+            hook_events: `${ownProject} AND (session_id IN (${sessions}) OR (harness, provider_session_id) IN (${nativeSessions})${invocationReceipts})`,
+            harness_usage_snapshots: `${ownProject} AND (harness, provider_session_id) IN (${nativeSessions})`,
+            protocols: `${ownProject} AND id IN (${protocols})`,
+            project_config: ownProject,
+            // Host installations, caches, queue owners and leases are not portable RUN authority.
+            runtime_config: "0", hook_installations: "0", codex_home_profiles: "0", codex_session_bindings: "0",
+            merge_servers: "0", merge_sessions: "0", merge_queue: "0", lanes: "0", lane_locks: "0", lane_waiters: "0",
+            sqlite_sequence: "0"
+        };
+        for (const table of ["works", "check_receipts", "merge_requests", "flow_run_flag_mutations", "usage", "flow_session_segments", "flow_jobs", "run_recovery_guards", "run_controllers", "run_controls"])
+            rules[table] = ownRun;
+        for (const table of ["plan_bindings", "plan_progress", "worktree_records", "audit_events"])
+            rules[table] = `${ownProject} AND protocol_id IN (${protocols})`;
+        for (const table of ["run_controller_events", "run_controller_operations"])
+            rules[table] = `controller_id IN (SELECT controller_id FROM run_controllers WHERE ${ownRun})`;
+        for (const table of ["run_control_admissions", "run_control_stage_admissions", "run_control_operations", "run_control_workers"])
+            rules[table] = `control_id IN (SELECT control_id FROM run_controls WHERE ${ownRun})`;
+        const tables = db.prepare("SELECT name FROM sqlite_schema WHERE type = 'table'").all();
+        const quote = (name) => `"${name.replaceAll('"', '""')}"`;
+        // Evaluate every relationship before deleting parents, including historical bindings.
+        for (const { name } of tables) {
+            const predicate = rules[name];
+            if (predicate === undefined && db.prepare(`SELECT 1 FROM ${quote(name)} LIMIT 1`).get())
+                throw new AppError("snapshot_scope_unknown", "Recovery export has no scope rule for a populated table", 1, { table: name });
+            db.exec(`CREATE TEMP TABLE ${quote(`keep_${name}`)} AS SELECT rowid AS retained_id FROM ${quote(name)} WHERE ${predicate ?? "0"}`);
+        }
+        for (const { name } of tables)
+            db.exec(`DELETE FROM ${quote(name)} WHERE rowid NOT IN (SELECT retained_id FROM ${quote(`keep_${name}`)})`);
+        const issues = db.prepare("PRAGMA foreign_key_check").all();
+        if (issues.length)
+            throw new AppError("snapshot_scope_inconsistent", "Scoped recovery export has unresolved relational references", 1, { issues });
+        db.exec("COMMIT; VACUUM");
+        complete = true;
+    }
+    finally {
+        db.close();
+        if (!complete)
+            fs.rmSync(output, { force: true });
+    }
+}
+/** Physical leases are evidence, not authority to resurrect on another host. */
+export function readRecoveryResourceEvidence(resourceHome, projectId, runId, authority) {
+    const file = path.join(resourceHome, "runtime.sqlite");
+    const scope = { schema_id: "dd-flow/recovery-resource-evidence@1", source_home: resourceHome, dd_flow_home: authority.ddFlowHome, project_id: projectId, run_id: runId };
+    if (!fs.existsSync(file))
+        return { ...scope, database_present: false, processes: [], resources: [] };
+    const db = new DatabaseSync(file, { readOnly: true });
+    try {
+        db.exec("PRAGMA busy_timeout = 4000; BEGIN");
+        const candidates = db.prepare("SELECT * FROM managed_processes WHERE project_id = ? AND run_id = ? ORDER BY id").all(projectId, runId).map(record => ({ record, home: managedProcessRuntimeHome(record, authority) }));
+        if (candidates.some(item => item.home === null))
+            throw new AppError("snapshot_resource_scope_unproven", "A retained process has no proven runtime-home identity", 1, { resource_home: resourceHome });
+        const processes = candidates.filter(item => item.home === authority.ddFlowHome).map(item => item.record);
+        const ids = new Set(processes.map(record => record.id)), owners = new Set(processes.map(record => record.owner_id));
+        const resources = db.prepare("SELECT r.* FROM managed_resources r JOIN managed_processes p ON p.id = r.process_id WHERE p.project_id = ? AND p.run_id = ? ORDER BY r.resource_kind, r.resource_key").all(projectId, runId).filter(row => typeof row.process_id === "string" && ids.has(row.process_id));
+        const unbound = db.prepare("SELECT owner_id FROM managed_resources WHERE process_id IS NULL AND owner_id IN (SELECT owner_id FROM managed_processes WHERE project_id = ? AND run_id = ?)").all(projectId, runId).some(row => typeof row.owner_id === "string" && owners.has(row.owner_id));
+        if (unbound)
+            throw new AppError("snapshot_resource_scope_unproven", "A retained resource has no process binding proving its RUN scope", 1, { resource_home: resourceHome });
+        db.exec("COMMIT");
+        return { ...scope, database_present: true, processes, resources };
+    }
+    finally {
+        db.close();
+    }
+}

package/dist/services/run-control-receipt.js

@@ -0,0 +1,56 @@
+import crypto from "node:crypto";
+const object = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : {};
+const records = (value) => Array.isArray(value) ? value.map(object) : [];
+const text = (value) => typeof value === "string" && value.length ? value : null;
+/** Pure projection of durable evidence. Never infer quiescence from an ACK,
+ * a terminal RUN label, or a settlement captured before a subsequent resume. */
+export function controlStatusReceipt(observation, request = {}) {
+    const control = object(observation.control), worker = object(observation.worker), resume = object(observation.resume_operation);
+    const present = Boolean(control.control_id), current = control.current === true;
+    const activeResume = Boolean(resume.operation_id);
+    const historical = !current || activeResume || ["resuming", "resumed"].includes(String(control.status));
+    const settlement = object(control.settlement);
+    const snapshot = historical ? {} : control.admission === "sealed" ? settlement : object(worker.snapshot);
+    const nodes = records(snapshot.nodes).map((node, index) => {
+        const identity = Object.fromEntries(["operation_id", "controller_id", "process_id", "check_id", "merge_request_id", "work_id", "work_session_id", "session_id", "harness", "state_dir", "resource_home"].filter(key => node[key] !== undefined).map(key => [key, node[key]]));
+        const settled = node.status === "completed";
+        const role = ["subject", "worker", "merge", "judge", "probe", "check", "process"].includes(String(node.role)) ? node.role : node.check_id ? "check" : node.merge_request_id ? "merge" : node.process_id ? "process" : "unknown";
+        return { id: `node:${crypto.createHash("sha256").update(JSON.stringify(Object.keys(identity).length ? identity : { index, reason: node.reason })).digest("hex")}`, role, status: settled ? "completed" : node.status === "outcome_unknown" ? "unknown" : "pending", acknowledged: settled || object(node.receipt).cancelled === true, settled, reason: settled ? null : text(node.reason) ?? "node_settlement_required", details: node };
+    });
+    const settled = present && current && !historical && control.status === "settled" && control.admission === "sealed" && Boolean(control.capture_path) && settlement.settled === true && Array.isArray(settlement.nodes) && nodes.every(node => node.settled);
+    let state;
+    if (!present)
+        state = request.action && ["done", "failed", "cancelled"].includes(String(observation.run_status)) ? "terminal_noop" : "not_requested";
+    else if (!current)
+        state = "superseded";
+    else if (resume.status === "failed" || worker.status === "failed")
+        state = "recovery_required";
+    else if (control.status === "resumed" && control.admission === "recovered" && resume.status === "completed")
+        state = "running";
+    else if (activeResume || control.status === "resuming")
+        state = "resuming";
+    else if (settled)
+        state = control.requested_mode === "pause" ? "paused" : "stopped";
+    else
+        state = control.requested_mode === "pause" ? "pause_requested" : "stop_requested";
+    const reasons = settled ? [] : [...new Set([
+            ...nodes.filter(node => !node.settled).map(node => node.reason),
+            ...(Array.isArray(snapshot.pending_reasons) ? snapshot.pending_reasons.filter((reason) => typeof reason === "string" && Boolean(reason)) : []),
+            ...(!present ? [state === "terminal_noop" ? "terminal_settlement_not_observed" : "control_not_requested"]
+                : !current ? ["control_superseded"]
+                    : state === "running" ? ["run_active"]
+                        : state === "resuming" ? ["recovery_acceptance_pending"]
+                            : state === "recovery_required" ? [text(object(resume.error).code) ?? text(object(worker.error).code) ?? "control_recovery_required"]
+                                : control.admission === "sealed" ? ["recovery_capture_required"] : ["settlement_observation_required"])
+        ])];
+    return {
+        ...observation, schema_id: "dd-flow/run-control-receipt@1", ok: true,
+        request_id: request.requestId ?? text(resume.request_id) ?? text(control.request_id), control_id: text(control.control_id),
+        generation: Number.isSafeInteger(control.generation) ? control.generation : 0,
+        requested_mode: request.action ?? (activeResume ? "resume" : text(control.requested_mode)),
+        applied_mode: settled ? control.requested_mode : state === "running" ? "resume" : null,
+        state, settled, nodes, unsettled_reasons: reasons,
+        resumability: settled || state === "recovery_required" ? "recovery_required" : ["running", "not_requested", "terminal_noop", "superseded"].includes(state) ? "not_applicable" : "pending",
+        recovery_id: text(control.recovery_id)
+    };
+}