@deksden-com/dd-flow-cli 0.9.0-beta.1 → 0.9.0-beta.10

package/dist/services/hooks.js

@@ -7,6 +7,7 @@ import { AppError } from "../shared/errors.js";
 import { parseJsonObject } from "../shared/json.js";
 import { ensureDir, resolveProjectRoot } from "../storage/paths.js";
 import { appendAudit } from "./audit.js";
+import { nativeSessionIdentity, storageSessionId } from "./session-identity.js";
 import { commandHasOption, commandOption, commandPosition, parseLifecycleCommand, unwrapShellCommand } from "./lifecycle-command.js";
 import { registerProject, requireProjectByRoot } from "./projects.js";
 import { activeFlowSessionsForProject, bindObservedFlowSession, flowSessionPayloadFromRegisterCommand, recordFlowSessionObservation } from "./sessions.js";
@@ -278,7 +279,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" && !lifecycle.stageResume) {
+    if (lifecycle.analysis.kind === "compound") {
         return {
             ok: false,
             observed: false,
@@ -303,10 +304,11 @@ export function handleCodexHook(context, input) {
     if (!project)
         return { ok: true, observed: false, reason: "unrelated_cwd" };
     const binding = sessionId ? upsertSessionBindingFromPayload(context, project, sessionId, payload) : undefined;
+    const storageId = sessionId ? storageSessionId(nativeSessionIdentity("codex-desktop", sessionId)) : null;
     const observedSession = flowPayload
-        ? bindObservedFlowSession(context, project, flowPayload, sessionId ?? flowPayload.session_id ?? undefined)
+        ? bindObservedFlowSession(context, project, { ...flowPayload, harness: "codex-desktop", provider_session_id: sessionId ?? flowPayload.provider_session_id ?? null }, storageId ?? undefined)
         : undefined;
-    const effectiveSessionId = observedSession?.session_id ?? sessionId ?? null;
+    const effectiveSessionId = observedSession?.session_id ?? storageId;
     const protocolId = observedSession?.protocol_id ?? binding?.protocol_id ?? null;
     const eventKey = hookEventKey(payload, eventName, toolName, command);
     const inserted = recordHookEvent(context, {
@@ -343,7 +345,7 @@ export function handleCodexHook(context, input) {
         observed: inserted,
         duplicate: !inserted,
         event_key: eventKey,
-        session_id: effectiveSessionId,
+        session: sessionId ? nativeSessionIdentity("codex-desktop", sessionId) : null,
         protocol_id: protocolId,
         ...(sessionId && (flowPayload || stageStart || stageResume || workStart)
             ? {
@@ -377,7 +379,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" && !lifecycle.stageResume) {
+    if (lifecycle.analysis.kind === "compound") {
         throw new AppError("compound_lifecycle_command", "dd-flow lifecycle commands must be a standalone ZCode Bash tool call", 1, {
             standalone_command: lifecycle.invocation.command
         });
@@ -403,8 +405,8 @@ export function handleZcodeEvent(context, input) {
         throw new AppError("zcode_identity_missing", "ZCode ACP event has no root provider Session ID", 1);
     const childProviderSessionId = stringValue(runtime.childSessionId);
     const providerSessionId = childProviderSessionId ?? rootProviderSessionId;
-    const sessionId = `zcode-acp:${providerSessionId}`;
-    const parentSessionId = childProviderSessionId ? `zcode-acp:${rootProviderSessionId}` : null;
+    const sessionId = storageSessionId(nativeSessionIdentity("zcode-acp", providerSessionId));
+    const parentSessionId = childProviderSessionId ? storageSessionId(nativeSessionIdentity("zcode-acp", rootProviderSessionId)) : null;
     const agentId = stringValue(runtime.agentId);
     const observedSession = flowPayload ? bindObservedFlowSession(context, project, {
         ...flowPayload,
@@ -463,9 +465,8 @@ export function handleZcodeEvent(context, input) {
         duplicate: !inserted,
         event_key: eventKey,
         harness: "zcode-acp",
-        session_id: sessionId,
-        provider_session_id: providerSessionId,
-        parent_session_id: parentSessionId,
+        session: nativeSessionIdentity("zcode-acp", providerSessionId),
+        ...(childProviderSessionId ? { parent_session: nativeSessionIdentity("zcode-acp", rootProviderSessionId) } : {}),
         daemon_id: daemonId ?? null
     };
 }
@@ -485,7 +486,7 @@ 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" && !lifecycle.stageResume) {
+    if (lifecycle.analysis.kind === "compound") {
         throw new AppError("compound_lifecycle_command", "dd-flow lifecycle commands must be a standalone Grok Build tool call", 1, {
             standalone_command: lifecycle.invocation.command
         });
@@ -509,8 +510,8 @@ export function handleGrokEvent(context, input) {
     if (!rootProviderSessionId || !providerSessionId)
         throw new AppError("grok_identity_missing", "Grok Build hook has no trusted Session ID", 1);
     const isChild = providerSessionId !== rootProviderSessionId;
-    const sessionId = `grok-acp:${providerSessionId}`;
-    const parentSessionId = isChild ? `grok-acp:${stringValue(ddGrok.parentProviderSessionId) ?? rootProviderSessionId}` : null;
+    const sessionId = storageSessionId(nativeSessionIdentity("grok-acp", providerSessionId));
+    const parentSessionId = isChild ? storageSessionId(nativeSessionIdentity("grok-acp", stringValue(ddGrok.parentProviderSessionId) ?? rootProviderSessionId)) : null;
     const daemonId = stringValue(ddGrok.daemonId);
     const agentId = stringValue(hook.agent_id) ?? stringValue(hook.agentId);
     const observedSession = flowPayload ? bindObservedFlowSession(context, project, {
@@ -532,8 +533,8 @@ export function handleGrokEvent(context, input) {
         projectId: project.id, sessionId, runId: observedSession?.run_id ?? null, protocolId: observedSession?.protocol_id ?? null,
         cwd: expectedRoot, toolName: toolName ?? "Bash", eventKey
     });
-    const result = { ok: true, observed: inserted, duplicate: !inserted, event_key: eventKey, harness: "grok-acp", session_id: sessionId,
-        provider_session_id: providerSessionId, parent_session_id: parentSessionId, daemon_id: daemonId ?? null };
+    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)
         ? { ...result, hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "allow", updatedInput: { ...(rawInput ?? {}), command: commandWithHookEvent(command, eventKey) } } }
         : result;
@@ -565,8 +566,8 @@ export function handleOpenCodeEvent(context, input) {
     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 });
     }
-    const sessionId = `${harness}:${providerSessionId}`;
-    const parentSessionId = nativeParentId ? `${harness}:${nativeParentId}` : null;
+    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);
     const baseKey = `${eventId}:${phase}`;
     if (phase === "after") {
@@ -577,7 +578,7 @@ export function handleOpenCodeEvent(context, input) {
             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
         });
-        return { ok: true, observed: inserted, duplicate: !inserted, event_key: baseKey, phase, harness, session_id: sessionId };
+        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)) {
         return { ok: true, observed: false, reason: command ? "non_bash_tool" : "event_not_participating" };
@@ -585,7 +586,7 @@ export function handleOpenCodeEvent(context, input) {
     const lifecycle = lifecycleFacts(command);
     if (!lifecycle)
         return { ok: true, observed: false, reason: "event_not_participating" };
-    if (lifecycle.analysis.kind === "compound" && !lifecycle.stageResume) {
+    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 });
     }
     const { flowPayload, bootstrapStageStart, commandProjectRoot } = lifecycle;
@@ -614,7 +615,7 @@ export function handleOpenCodeEvent(context, input) {
         status: "observed", payload, eventKey: baseKey, matchKey, transcriptPath: 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_id: sessionId, provider_session_id: providerSessionId, parent_session_id: parentSessionId, daemon_id: daemonId };
+    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 };
     return agy ? result : { ...result, hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "allow", updatedInput: { ...rawInput, command: commandWithHookEvent(command, baseKey) } } };
 }
 /** Convert an Antigravity CLI tool hook into the shared lifecycle receipt. */
@@ -736,7 +737,7 @@ export function sessionIdForHookEvent(context, projectId, eventKey) {
 /** Reads immutable identity facts already captured by PreToolUse. */
 export function hookSessionIdentity(context, projectId, eventKey) {
     const event = context.db.get(`SELECT he.id, he.harness, he.provider_session_id, he.parent_session_id, he.daemon_id, he.session_id, he.agent_id, he.turn_id, he.transcript_path, he.provider, he.model, he.reasoning, he.mode, he.agent_type, COALESCE(he.cwd, csb.cwd) AS cwd
-     FROM hook_events he LEFT JOIN codex_session_bindings csb ON csb.project_id = he.project_id AND csb.session_id = he.session_id
+     FROM hook_events he LEFT JOIN codex_session_bindings csb ON csb.project_id = he.project_id AND csb.session_id = COALESCE(he.provider_session_id, he.session_id)
      WHERE he.project_id = ? AND he.event_key = ?`, [projectId, eventKey]);
     if (!event?.session_id)
         throw new AppError("hook_event_not_found", "stage start requires a trusted PreToolUse hook event", 1, { event_key: eventKey });
@@ -747,7 +748,9 @@ export function hookSessionIdentity(context, projectId, eventKey) {
         parentSessionId: event.parent_session_id,
         daemonId: event.daemon_id,
         agentId: event.agent_id,
-        sessionId: event.harness === "codex-desktop" ? event.agent_id ?? event.session_id : event.session_id,
+        // agent_id is an auxiliary provider fact, never a replacement Session ID.
+        sessionId: event.session_id,
+        nativeSessionId: event.provider_session_id ?? event.session_id,
         turnId: event.turn_id,
         transcriptPath: event.transcript_path,
         provider: event.provider,

package/dist/services/lanes.js

@@ -288,6 +288,7 @@ export async function waitAcquireLaneLock(context, input) {
                 timeoutSeconds
             });
         }
+        input.progress?.(`lane ${lane} is waiting at queue position ${String(result.payload.position ?? "unknown")}; next update in ${pollIntervalSeconds} seconds`);
         await delay(pollIntervalSeconds * 1000);
     }
 }

package/dist/services/managed-processes.js

@@ -0,0 +1,169 @@
+import crypto from "node:crypto";
+import { spawnSync } from "node:child_process";
+import net from "node:net";
+import { getResourceDatabase } from "../storage/database.js";
+const defaultLeaseMs = 15 * 60_000;
+export function resourceHome(context) {
+    return context.env?.DD_FLOW_RESOURCE_HOME ?? context.ddFlowHome ?? "/tmp/dd-flow-runtime";
+}
+export function registerManagedProcess(context, input) {
+    const db = registry(context);
+    const now = context.now();
+    const id = input.id ?? `PROC-${crypto.randomUUID()}`;
+    const token = crypto.randomUUID();
+    db.run(`INSERT INTO managed_processes
+      (id, kind, pid, pid_started_at, owner_id, lease_token, lease_expires_at, project_id, run_id, work_id, check_id, operation_id, stdout_path, stderr_path, state, started_at, updated_at, finished_at, termination_reason, metadata_json)
+     VALUES (?, ?, NULL, NULL, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'starting', ?, ?, NULL, NULL, ?)`, [id, input.kind, input.ownerId, token, leaseExpiry(now, input.leaseMs), input.projectId ?? null, input.runId ?? null, input.workId ?? null, input.checkId ?? null, input.operationId ?? null, input.stdoutPath ?? null, input.stderrPath ?? null, now, now, JSON.stringify(input.metadata ?? {})]);
+    return requireProcess(db, id);
+}
+export function confirmManagedProcess(context, input) {
+    const db = registry(context);
+    const now = context.now();
+    const current = requireProcess(db, input.id);
+    const metadata = parseMetadata(current.metadata_json);
+    if (input.processGroupId)
+        metadata.process_group_id = input.processGroupId;
+    const result = db.run(`UPDATE managed_processes
+     SET pid = ?, pid_started_at = ?, state = 'running', lease_expires_at = ?, updated_at = ?, metadata_json = ?
+     WHERE id = ? AND lease_token = ? AND state = 'starting'`, [input.pid, processStartedAt(input.pid), leaseExpiry(now, input.leaseMs), now, JSON.stringify(metadata), input.id, input.leaseToken]);
+    if (result.changes !== 1)
+        throw new Error(`Managed process cannot be confirmed: ${input.id}`);
+    return requireProcess(db, input.id);
+}
+export function heartbeatManagedProcess(context, input) {
+    const db = registry(context);
+    return db.run("UPDATE managed_processes SET lease_expires_at = ?, updated_at = ? WHERE id = ? AND lease_token = ? AND state IN ('starting','running','stopping')", [leaseExpiry(context.now(), input.leaseMs), context.now(), input.id, input.leaseToken]).changes === 1;
+}
+export function finishManagedProcess(context, input) {
+    const db = registry(context);
+    const now = context.now();
+    const updated = db.run("UPDATE managed_processes SET state = ?, termination_reason = ?, finished_at = ?, updated_at = ?, lease_expires_at = ? WHERE id = ? AND lease_token = ? AND state IN ('starting','running','stopping','orphaned')", [input.state, input.reason ?? null, now, now, now, input.id, input.leaseToken]).changes === 1;
+    if (updated)
+        db.run("DELETE FROM managed_resources WHERE process_id = ?", [input.id]);
+    return updated;
+}
+export function processIsAlive(record) {
+    if (!record.pid)
+        return false;
+    try {
+        process.kill(record.pid, 0);
+    }
+    catch {
+        return false;
+    }
+    return !record.pid_started_at || record.pid_started_at === processStartedAt(record.pid);
+}
+function processTreeIsAlive(record) {
+    const group = parseMetadata(record.metadata_json).process_group_id;
+    if (process.platform !== "win32" && typeof group === "number") {
+        try {
+            process.kill(-group, 0);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    return processIsAlive(record);
+}
+/** Claims only expired records.  Callers must still verify `processIsAlive` before stopping a PID. */
+export function claimExpiredManagedProcesses(context, ownerId) {
+    const db = registry(context);
+    const now = context.now();
+    db.exec("BEGIN IMMEDIATE");
+    try {
+        const candidates = db.all("SELECT * FROM managed_processes WHERE state IN ('starting','running','stopping','orphaned') AND lease_expires_at < ? ORDER BY lease_expires_at, id", [now]);
+        const claimed = [];
+        for (const candidate of candidates) {
+            const token = crypto.randomUUID();
+            const result = db.run("UPDATE managed_processes SET owner_id = ?, lease_token = ?, state = 'orphaned', lease_expires_at = ?, updated_at = ? WHERE id = ? AND lease_token = ? AND state IN ('starting','running','stopping','orphaned') AND lease_expires_at < ?", [ownerId, token, leaseExpiry(now), now, candidate.id, candidate.lease_token, now]);
+            if (result.changes === 1)
+                claimed.push({ ...candidate, owner_id: ownerId, lease_token: token, state: "orphaned", updated_at: now });
+        }
+        db.exec("COMMIT");
+        return claimed;
+    }
+    catch (error) {
+        db.exec("ROLLBACK");
+        throw error;
+    }
+}
+export function managedProcessStatus(context) {
+    return registry(context).all("SELECT * FROM managed_processes ORDER BY updated_at DESC, id");
+}
+/** Reconcile only records the system owns and has atomically claimed. */
+export async function reconcileExpiredManagedProcesses(context, ownerId, graceMs = 1_000) {
+    const claimed = claimExpiredManagedProcesses(context, ownerId);
+    const outcomes = [];
+    for (const processRecord of claimed) {
+        if (!processTreeIsAlive(processRecord)) {
+            finishManagedProcess(context, { id: processRecord.id, leaseToken: processRecord.lease_token, state: "stopped", reason: "orphan_not_alive" });
+            outcomes.push({ id: processRecord.id, outcome: "already_stopped" });
+            continue;
+        }
+        terminateOwnedProcess(processRecord, "SIGTERM");
+        await delay(graceMs);
+        if (processTreeIsAlive(processRecord)) {
+            terminateOwnedProcess(processRecord, "SIGKILL");
+            await delay(Math.min(graceMs, 250));
+        }
+        if (processTreeIsAlive(processRecord)) {
+            outcomes.push({ id: processRecord.id, outcome: "kill_failed" });
+            continue;
+        }
+        finishManagedProcess(context, { id: processRecord.id, leaseToken: processRecord.lease_token, state: "stopped", reason: "orphan_reconciled" });
+        outcomes.push({ id: processRecord.id, outcome: "stopped" });
+    }
+    return outcomes;
+}
+export async function reservePorts(context, input) {
+    const db = registry(context);
+    const claims = [];
+    const ports = {};
+    try {
+        for (const name of input.names) {
+            for (;;) {
+                const port = await availablePort();
+                const key = String(port);
+                const token = crypto.randomUUID();
+                const now = context.now();
+                const result = db.run("INSERT OR IGNORE INTO managed_resources (resource_kind, resource_key, owner_id, lease_token, lease_expires_at, process_id, metadata_json, created_at, updated_at) VALUES ('port', ?, ?, ?, ?, ?, ?, ?, ?)", [key, input.ownerId, token, leaseExpiry(now, input.leaseMs), input.processId ?? null, JSON.stringify({ name }), now, now]);
+                if (result.changes === 1) {
+                    claims.push({ key, token });
+                    ports[name] = port;
+                    break;
+                }
+            }
+        }
+    }
+    catch (error) {
+        releasePortClaims(db, claims);
+        throw error;
+    }
+    return { ports, release: () => releasePortClaims(db, claims) };
+}
+function registry(context) { return getResourceDatabase(resourceHome(context)); }
+function requireProcess(db, id) { const row = db.get("SELECT * FROM managed_processes WHERE id = ?", [id]); if (!row)
+    throw new Error(`Managed process is missing: ${id}`); return row; }
+function leaseExpiry(now, leaseMs = defaultLeaseMs) { return new Date(Date.parse(now) + leaseMs).toISOString(); }
+function processStartedAt(pid) { const result = spawnSync("ps", ["-o", "lstart=", "-p", String(pid)], { encoding: "utf8" }); const value = result.status === 0 ? result.stdout.trim() : ""; return value || null; }
+function releasePortClaims(db, claims) { for (const claim of claims)
+    db.run("DELETE FROM managed_resources WHERE resource_kind = 'port' AND resource_key = ? AND lease_token = ?", [claim.key, claim.token]); }
+function terminateOwnedProcess(record, signal) {
+    if (!record.pid || !record.pid_started_at || !processTreeIsAlive(record))
+        return;
+    const group = parseMetadata(record.metadata_json).process_group_id;
+    try {
+        process.kill(process.platform === "win32" || typeof group !== "number" ? record.pid : -group, signal);
+    }
+    catch { /* inspect again below */ }
+}
+function parseMetadata(value) { try {
+    const parsed = JSON.parse(value);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? { ...parsed } : {};
+}
+catch {
+    return {};
+} }
+function availablePort() { return new Promise((resolve, reject) => { const server = net.createServer(); server.once("error", reject); server.listen(0, "127.0.0.1", () => { const address = server.address(); const port = typeof address === "object" && address ? address.port : undefined; server.close((error) => error ? reject(error) : port ? resolve(port) : reject(new Error("Could not allocate local port"))); }); }); }
+function delay(milliseconds) { return new Promise((resolve) => setTimeout(resolve, milliseconds)); }

package/dist/services/merge-server.js

@@ -5,6 +5,7 @@ import { AppError } from "../shared/errors.js";
 import { flowCommand } from "./stage-pause.js";
 import { validateSchema } from "./schema-validation.js";
 import { adapterSessionId, runHarnessAdapter } from "./harness-adapter.js";
+import { harnessRuntimeArguments, resolveHarnessCommand } from "./harness-config.js";
 /** A deterministic dispatcher; only the launched harness Session performs agent work. */
 export async function serveMergeRequests(context, input) {
     const running = context.db.get("SELECT server_id, pid FROM merge_servers WHERE status IN ('running','stopping') ORDER BY started_at LIMIT 1");
@@ -63,6 +64,8 @@ async function dispatch(context, input) {
     const claimed = context.db.run("UPDATE merge_requests SET status = 'dispatching', dispatch_owner = ?, dispatch_lease_token = ?, dispatch_lease_expires_at = ?, updated_at = ? WHERE merge_request_id = ? AND status = 'queued' AND execution_route = 'server'", [input.serverId, token, leaseUntil, context.now(), input.request.merge_request_id]);
     if (claimed.changes !== 1)
         return;
+    const leaseHeartbeat = setInterval(() => { const now = context.now(); context.db.run("UPDATE merge_requests SET dispatch_lease_expires_at = ?, updated_at = ? WHERE merge_request_id = ? AND status = 'dispatching' AND dispatch_owner = ? AND dispatch_lease_token = ?", [new Date(Date.now() + 120_000).toISOString(), now, input.request.merge_request_id, input.serverId, token]); }, 30_000);
+    leaseHeartbeat.unref();
     const stateDir = path.join(input.root, input.request.merge_request_id);
     fs.mkdirSync(stateDir, { recursive: true });
     const promptFile = path.join(stateDir, "launch.md");
@@ -71,8 +74,8 @@ async function dispatch(context, input) {
     fs.writeFileSync(promptFile, `Start the assigned MERGE stage now. Your first tool call must be this exact standalone command:\n\n${stageCommand}\n\nTrust and follow the complete stage packet it returns. Continue through merge apply and stage finish. Stop only when the stage reaches a terminal result or explicitly requests user/operator action.\n`);
     event(input.journal, { type: "launch_intent", server_id: input.serverId, request_id: input.request.merge_request_id, token, profile: input.profile, prompt_file: promptFile, at: context.now() });
     input.progress?.(`launching ${input.request.merge_request_id} with ${input.profile.id}`);
-    const executable = context.env[`DD_FLOW_${input.profile.harness.toUpperCase()}_ADAPTER`] ?? `dd-${input.profile.harness}`;
-    const common = ["--state-dir", stateDir, "--journal", adapterJournal, "--cwd", input.request.target_workspace, "--provider", input.profile.provider, "--model", input.profile.model, "--reasoning", input.profile.reasoning, "--mode", input.profile.mode, "--permission", input.profile.permission, "--project-root", input.request.target_workspace, "--dd-flow-home", context.ddFlowHome, "--json"];
+    const executable = resolveHarnessCommand(context.ddFlowHome, input.profile.harness, "adapter");
+    const common = ["--state-dir", stateDir, "--journal", adapterJournal, "--cwd", input.request.target_workspace, "--provider", input.profile.provider, "--model", input.profile.model, "--reasoning", input.profile.reasoning, "--mode", input.profile.mode, "--permission", input.profile.permission, "--project-root", input.request.target_workspace, "--dd-flow-home", context.ddFlowHome, ...harnessRuntimeArguments(context.ddFlowHome, input.profile.harness), "--json"];
     try {
         const adapterCall = (args, timeoutMs, progressMessage) => runHarnessAdapter({ executable, args, env: context.env, ...(timeoutMs ? { timeoutMs } : {}), ...(input.progress ? { progress: input.progress } : {}), ...(progressMessage ? { progressMessage } : {}), onEvidence: (value) => event(input.journal, { type: "adapter_call", ...value }) });
         await adapterCall(["daemon", "start", ...common]);
@@ -95,6 +98,9 @@ async function dispatch(context, input) {
             context.db.run("UPDATE merge_requests SET status = 'recovery_required', last_error_json = ?, updated_at = ? WHERE merge_request_id = ?", [JSON.stringify({ code: "adapter_lost_after_stage_start", error: String(error) }), context.now(), input.request.merge_request_id]);
         throw error;
     }
+    finally {
+        clearInterval(leaseHeartbeat);
+    }
 }
 function nextServerRequests(context, limit) { const selected = new Set(); return context.db.all("SELECT merge_request_id, project_id, run_id, executor_work_id, target_workspace, execution_route, status, created_at FROM merge_requests WHERE status = 'queued' AND execution_route = 'server' ORDER BY created_at, merge_request_id").filter((request) => { if (selected.has(request.project_id) || context.db.get("SELECT 1 FROM merge_requests WHERE project_id = ? AND status NOT IN ('completed','failed','cancelled') AND (created_at < ? OR (created_at = ? AND merge_request_id < ?)) LIMIT 1", [request.project_id, request.created_at, request.created_at, request.merge_request_id]))
     return false; selected.add(request.project_id); return true; }).slice(0, limit); }

package/dist/services/portable-refs.js

@@ -0,0 +1,57 @@
+import fs from "node:fs";
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+export function assertPortableArtifactRef(value, input) {
+    const parsed = parseArtifactRef(value);
+    let file;
+    let root;
+    if (parsed.path.startsWith("run://")) {
+        const prefix = `run://${input.runId}/`;
+        if (!parsed.path.startsWith(prefix) || parsed.path.slice(prefix.length).split("/").includes(".."))
+            throw new AppError("invalid_evidence_ref", "Artifact RUN reference must stay in the current RUN", 2, { ref: value });
+        root = input.runHome;
+        file = path.join(root, parsed.path.slice(prefix.length));
+    }
+    else {
+        root = input.workspaceRoot;
+        if (!parsed.path)
+            throw new AppError("invalid_evidence_ref", "Artifact reference must name a file", 2, { ref: value });
+        file = path.isAbsolute(parsed.path) ? parsed.path : path.join(root, parsed.path);
+    }
+    if (!fs.existsSync(file))
+        throw new AppError("evidence_ref_missing", "Artifact reference does not exist", 2, { ref: value, resolved_path: file });
+    const realRoot = fs.realpathSync(root);
+    const realFile = fs.realpathSync(file);
+    if (!contained(realRoot, realFile))
+        throw new AppError("invalid_evidence_ref", "Artifact reference must stay inside its declared workspace", 2, { ref: value, resolved_path: realFile, root: realRoot });
+    if (parsed.lines)
+        validateLineRanges(realFile, parsed.lines, value);
+    return realFile;
+}
+function parseArtifactRef(value) {
+    if (typeof value !== "string" || !value.trim())
+        throw new AppError("invalid_evidence_ref", "Artifact reference must be a non-empty string", 2, { ref: value });
+    const [rawPath, ...fragments] = value.split("#");
+    if (fragments.length > 1 || (fragments.length === 1 && !fragments[0]))
+        throw new AppError("invalid_evidence_ref", "Artifact reference has an invalid fragment", 2, { ref: value });
+    const match = rawPath.match(/^(.*):(\d+(?:-\d+)?(?:,\d+(?:-\d+)?)*)$/);
+    if (!match)
+        return { path: rawPath, fragment: fragments[0] ?? null, lines: null };
+    const lines = match[2].split(",").map((item) => {
+        const [startText, endText] = item.split("-");
+        const start = Number(startText);
+        const end = Number(endText ?? startText);
+        if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start < 1 || end < start)
+            throw new AppError("invalid_evidence_ref", "Artifact line ranges must be positive and ordered", 2, { ref: value, range: item });
+        return { start, end };
+    });
+    return { path: match[1], fragment: fragments[0] ?? null, lines };
+}
+function contained(root, file) { const relative = path.relative(root, file); return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative)); }
+function validateLineRanges(file, ranges, ref) {
+    const source = fs.readFileSync(file, "utf8");
+    const lines = source === "" ? 0 : source.replace(/\r?\n$/, "").split(/\r?\n/).length;
+    const invalid = ranges.find((range) => range.end > lines);
+    if (invalid)
+        throw new AppError("evidence_line_out_of_range", "Artifact line range exceeds the referenced file", 2, { ref, file, line_count: lines, invalid_range: invalid });
+}

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/run-engine-bindings.js

@@ -2,36 +2,18 @@ import fs from "node:fs";
 import path from "node:path";
 import { AppError } from "../shared/errors.js";
 export const runEngineBindingSchemaId = "dd-flow/run-engine-binding@1";
-export function findRunHome(ddFlowHome, projectRoot, runIdOrAlias) {
-    const projectsRoot = path.join(ddFlowHome, "projects");
-    if (!fs.existsSync(projectsRoot))
+/** Resolve a RUN from SQLite authority; never discover one by scanning storage paths. */
+export function locateRunRoot(db, projectRoot, runIdOrAlias) {
+    const rows = db.all(`SELECT r.project_id, r.id AS run_id, r.run_root
+       FROM runs r JOIN projects p ON p.id = r.project_id
+      WHERE p.root = ? AND (r.id = ? OR r.short_id = ?)`, [realpathOrResolve(projectRoot), runIdOrAlias, runIdOrAlias]).filter((row) => Boolean(row.run_root));
+    if (rows.length > 1)
+        throw new AppError("ambiguous_id", `RUN id is ambiguous for project: ${runIdOrAlias}`, 2, { project_root: realpathOrResolve(projectRoot), candidates: rows.map((row) => row.run_id) });
+    const row = rows[0];
+    if (!row?.run_root)
         return null;
-    const expectedRoot = realpathOrResolve(projectRoot);
-    const matches = [];
-    for (const projectId of fs.readdirSync(projectsRoot)) {
-        const runsRoot = path.join(projectsRoot, projectId, "runs");
-        if (!isDirectory(runsRoot))
-            continue;
-        for (const runId of fs.readdirSync(runsRoot)) {
-            if (!runIdMatches(runId, runIdOrAlias))
-                continue;
-            const runHome = path.join(runsRoot, runId);
-            const authorityPath = path.join(runHome, "run.json");
-            const bindingPath = path.join(runHome, "engine-binding.json");
-            const binding = readRunEngineBinding(bindingPath, { allowMissing: true });
-            const authorityRoot = binding?.project_root ?? projectRootFromAuthority(authorityPath);
-            if (!authorityRoot || realpathOrResolve(authorityRoot) !== expectedRoot)
-                continue;
-            matches.push({ project_id: projectId, run_id: runId, run_home: runHome, authority_path: authorityPath, binding_path: bindingPath });
-        }
-    }
-    if (matches.length > 1) {
-        throw new AppError("ambiguous_id", `RUN id is ambiguous for project: ${runIdOrAlias}`, 2, {
-            project_root: expectedRoot,
-            candidates: matches.map((match) => match.run_id)
-        });
-    }
-    return matches[0] ?? null;
+    const runRoot = path.resolve(row.run_root);
+    return { project_id: row.project_id, run_id: row.run_id, run_root: runRoot, authority_path: path.join(runRoot, "run.json"), binding_path: path.join(runRoot, "engine-binding.json") };
 }
 export function readRunEngineBinding(file, options = {}) {
     if (!fs.existsSync(file)) {
@@ -86,6 +68,14 @@ export function allRunEngineBindings(ddFlowHome) {
     }
     return bindings;
 }
+function isDirectory(value) {
+    try {
+        return fs.statSync(value).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
 function isRunEngineBinding(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         return false;
@@ -115,32 +105,6 @@ function sameEngine(left, right) {
         && left.integrity_checksum === right.integrity_checksum
         && left.snapshot_root === right.snapshot_root;
 }
-function projectRootFromAuthority(file) {
-    try {
-        const value = JSON.parse(fs.readFileSync(file, "utf8"));
-        const execution = recordValue(value.execution);
-        const workspace = recordValue(value.workspace);
-        const project = recordValue(value.project);
-        return stringValue(execution?.project_root)
-            ?? stringValue(workspace?.project_root)
-            ?? stringValue(project?.root)
-            ?? stringValue(value.project_root);
-    }
-    catch {
-        return null;
-    }
-}
-function runIdMatches(fullId, idOrAlias) {
-    return fullId === idOrAlias || /^RUN-[0-9]+$/.test(idOrAlias) && fullId.startsWith(`${idOrAlias}-`);
-}
-function isDirectory(value) {
-    try {
-        return fs.statSync(value).isDirectory();
-    }
-    catch {
-        return false;
-    }
-}
 function realpathOrResolve(value) {
     try {
         return fs.realpathSync(value);
@@ -149,9 +113,3 @@ function realpathOrResolve(value) {
         return path.resolve(value);
     }
 }
-function recordValue(value) {
-    return value && typeof value === "object" && !Array.isArray(value) ? value : null;
-}
-function stringValue(value) {
-    return typeof value === "string" && value.length > 0 ? value : null;
-}

package/dist/services/run-projection.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { reconcileSessionCoverageRows } from "../domain/session-coverage.js";
+import { publicSessionIdentity } from "./session-identity.js";
 export function refreshRunSessionProjection(context, projectId, runId) {
     const run = context.db.get("SELECT id, flow_kind, status, project_root, subject_type, subject_id, runtime_path, run_index_path, index_json FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]);
     if (!run)
@@ -9,7 +10,8 @@ export function refreshRunSessionProjection(context, projectId, runId) {
     const sessionRows = context.db.all(`SELECT session_id, harness, provider_session_id, parent_session_id, role, session_kind, worker_id, current_stage, status,
             created_at, updated_at, stopped_at, coverage_units_json
        FROM sessions WHERE project_id = ? AND run_id = ? ORDER BY created_at, session_id`, [projectId, runId]);
-    const sessions = sessionRows.map(sessionProjection);
+    const sessionIdentities = new Map(sessionRows.map((row) => [row.session_id, publicSessionIdentity(row)]));
+    const sessions = sessionRows.map((row) => sessionProjection(row, sessionIdentities));
     const workRows = context.db.all("SELECT work_id, parent_work_id, status, depends_on_json, launch_policy, started_at, completed_at FROM works WHERE project_id = ? AND run_id = ? ORDER BY created_at, work_id", [projectId, runId]);
     const works = workRows.map((work) => ({ work_id: work.work_id, parent_work_id: work.parent_work_id, status: work.status, depends_on: parseStringArray(work.depends_on_json), launch_policy: work.launch_policy, started_at: work.started_at, completed_at: work.completed_at }));
     const rootWorkId = workRows.find((work) => work.parent_work_id === null)?.work_id ?? null;
@@ -123,10 +125,12 @@ function readPlanId(planPath) {
     return "unknown-plan";
 }
 function workerProjection(context, projectId, runId) {
-    return Object.fromEntries(context.db.all("SELECT job_id, plan_item_id, status, worker_session_id FROM flow_jobs WHERE project_id = ? AND run_id = ? ORDER BY job_id", [projectId, runId]).map((job) => [job.job_id, {
+    return Object.fromEntries(context.db.all(`SELECT j.job_id, j.plan_item_id, j.status, j.worker_session_id, s.harness, s.provider_session_id
+       FROM flow_jobs j LEFT JOIN sessions s ON s.project_id = j.project_id AND s.session_id = j.worker_session_id
+      WHERE j.project_id = ? AND j.run_id = ? ORDER BY j.job_id`, [projectId, runId]).map((job) => [job.job_id, {
             units: [job.plan_item_id],
             status: { pending: "registered", done: "completed" }[job.status] ?? job.status,
-            ...(job.worker_session_id ? { session_id: job.worker_session_id } : {})
+            ...(job.worker_session_id && job.harness ? { session: publicSessionIdentity({ harness: job.harness, provider_session_id: job.provider_session_id, session_id: job.worker_session_id }) } : {})
         }]));
 }
 function parseStringArray(value) {
@@ -138,12 +142,10 @@ function parseStringArray(value) {
         return [];
     }
 }
-function sessionProjection(row) {
+function sessionProjection(row, identities) {
     return {
-        session_id: row.session_id,
-        harness: row.harness,
-        provider_session_id: row.provider_session_id,
-        parent_session_id: row.parent_session_id,
+        session: publicSessionIdentity(row),
+        ...(row.parent_session_id ? { parent_session: identities.get(row.parent_session_id) ?? null } : {}),
         role: row.role,
         session_kind: row.session_kind,
         work_id: row.worker_id,