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

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

@@ -63,6 +63,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");
@@ -95,6 +97,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/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,

package/dist/services/runs.js

@@ -15,6 +15,8 @@ import { refreshRunSessionProjection } from "./run-projection.js";
 import { resolveCanonRoot } from "./canon.js";
 import { bindCurrentEngineToRun } from "./engines.js";
 import { executionProfilePath, loadVnextExecutionProfile } from "./vnext-execution-profile.js";
+import { isLegalVnextTransition, vnextStages } from "../domain/stage-catalog.js";
+import { publicSessionIdentity } from "./session-identity.js";
 const runSchemaId = "dd-flow/flow-run@3";
 const runtimeSchemaId = "dd-flow/flow-run@3";
 const runIdType = "RUN";
@@ -450,6 +452,7 @@ export function attachFlowRunStage(context, input) {
     const dir = requiredStageDir(input.dir);
     const status = parseStageStatus(input.status);
     const existing = index.stage_runs.find((item) => item.stage === stage);
+    assertVnextStageStart(run, index, stage, status, existing);
     if (status === "running" && existing) {
         archiveExistingStageAttempt(runArtifactRoot(run), dir);
     }
@@ -674,8 +677,13 @@ export function completeFlowRun(context, input) {
     const index = authoritativeIndex(run);
     const now = context.now();
     const status = parseRunStatus(input.status);
-    if (!['done', 'blocked', 'cancelled', 'failed'].includes(status)) {
-        throw new AppError('validation', 'completeFlowRun accepts terminal statuses only; use advanceFlowRun for a live RUN', 2, { status });
+    if (!['done', 'cancelled', 'failed'].includes(status)) {
+        throw new AppError('validation', 'completeFlowRun accepts only done, cancelled, or failed; use stage block/unblock for a recoverable blocker', 2, { status });
+    }
+    if (!input.manualOverrideReason) {
+        const activeWork = context.db.get("SELECT work_id, status FROM works WHERE project_id = ? AND run_id = ? AND status IN ('created', 'running', 'paused') LIMIT 1", [project.id, run.id]);
+        if (activeWork)
+            throw new AppError("active_work", "RUN cannot complete while Work remains active", 2, { run_id: run.id, work_id: activeWork.work_id, status: activeWork.status });
     }
     if (input.manualOverrideReason && (status === "cancelled" || status === "failed")) {
         closeOpenStagesForOverride(index, status, now);
@@ -685,7 +693,7 @@ export function completeFlowRun(context, input) {
     index.verdict = input.verdict ?? (status === "done" ? "accepted" : status);
     index.next_action = input.nextAction ?? null;
     index.updated_at = now;
-    if (["done", "blocked", "cancelled", "failed"].includes(status)) {
+    if (["done", "cancelled", "failed"].includes(status)) {
         index.completed_at = now;
         index.finished_at = now;
         index.duration_ms = durationMs(index.started_at ?? run.created_at, now);
@@ -733,7 +741,7 @@ export function advanceFlowRun(context, input) {
 function closeOpenStagesForOverride(index, status, now) {
     const stageStatus = status === "cancelled" ? "skipped" : "failed";
     for (const stage of index.stage_runs) {
-        if (stage.status !== "running" && stage.status !== "pending")
+        if (stage.status !== "running" && stage.status !== "pending" && stage.status !== "paused" && stage.status !== "blocked")
             continue;
         stage.status = stageStatus;
         stage.updated_at = now;
@@ -755,7 +763,7 @@ function closeOpenWorksForOverride(context, projectId, runId, status, now) {
     context.db.run(`UPDATE works
        SET status = ?, updated_at = ?, completed_at = ?
      WHERE project_id = ? AND run_id = ?
-       AND status IN ('created', 'running')`, [workStatus, now, now, projectId, runId]);
+       AND status IN ('created', 'running', 'paused')`, [workStatus, now, now, projectId, runId]);
     context.db.run(`UPDATE work_sessions
        SET status = ?, updated_at = ?, completed_at = ?
      WHERE work_id IN (SELECT work_id FROM works WHERE project_id = ? AND run_id = ?)
@@ -881,7 +889,21 @@ export function getFlowRunSessions(context, input) {
                s.agent_id, s.worker_id, s.provider, s.model, s.reasoning, s.mode,
                s.agent_type, s.transcript_path
       ORDER BY s.created_at, s.session_id`, [project.id, run.id]);
-    return { ok: true, schema_id: "dd-flow/run-sessions@3", run_id: run.id, sessions };
+    const identities = new Map(sessions.map((row) => [String(row.session_id), publicSessionIdentity({
+            harness: String(row.harness),
+            provider_session_id: typeof row.provider_session_id === "string" ? row.provider_session_id : null,
+            session_id: String(row.session_id)
+        })]));
+    return {
+        ok: true,
+        schema_id: "dd-flow/run-sessions@4",
+        run_id: run.id,
+        sessions: sessions.map(({ session_id, harness: _harness, provider_session_id: _providerSessionId, parent_session_id, ...row }) => ({
+            ...row,
+            session: identities.get(String(session_id)) ?? null,
+            ...(typeof parent_session_id === "string" ? { parent_session: identities.get(parent_session_id) ?? null } : {})
+        }))
+    };
 }
 export function appendFlowRunTimelineEvent(context, projectId, runId, event) {
     const run = requireRunById(context, projectId, runId);
@@ -1133,6 +1155,28 @@ function nextAttempt(existing) {
     const number = Number(existing.attempt.replace("try-", ""));
     return `try-${String(Number.isFinite(number) ? number + 1 : 1).padStart(3, "0")}`;
 }
+function assertVnextStageStart(run, index, stage, status, existing) {
+    if (status !== "running" || (run.flow_kind !== "vnext_specify" && run.flow_kind !== "vnext_protocolize"))
+        return;
+    if (!vnextStages.some((candidate) => candidate.id === stage))
+        return;
+    if (existing) {
+        if (existing.status === "running")
+            throw new AppError("stage_already_running", "The same stage attempt is already running; continue it instead of starting another attempt", 2, { run_id: run.id, stage, attempt: existing.attempt ?? null });
+        throw new AppError("illegal_stage_transition", "A completed or paused vNext stage cannot be started as a new implicit attempt", 2, { run_id: run.id, stage, status: existing.status });
+    }
+    const completed = index.stage_runs.filter((candidate) => candidate.status === "done" || candidate.status === "skipped").sort((left, right) => right.order - left.order)[0];
+    if (!completed) {
+        if (stage === "specify")
+            return;
+        throw new AppError("illegal_stage_transition", "The vNext flow must start with SPECIFY", 2, { run_id: run.id, stage });
+    }
+    if (!isLegalVnextTransition(completed.stage, stage))
+        throw new AppError("illegal_stage_transition", "The requested stage is not a legal successor of the last accepted stage", 2, { run_id: run.id, from: completed.stage, to: stage });
+    const unfinished = index.stage_runs.find((candidate) => !["done", "skipped"].includes(candidate.status));
+    if (unfinished)
+        throw new AppError("illegal_stage_transition", "Another stage is still active", 2, { run_id: run.id, active_stage: unfinished.stage, active_status: unfinished.status, to: stage });
+}
 function upsertStage(index, stageRun) {
     const position = index.stage_runs.findIndex((item) => item.stage === stageRun.stage);
     if (position === -1) {

package/dist/services/session-identity.js

@@ -0,0 +1,19 @@
+import crypto from "node:crypto";
+import { AppError } from "../shared/errors.js";
+/** Internal SQLite key. Never expose this as a native harness Session ID. */
+export function storageSessionId(identity) {
+    const harness = requirePart(identity.harness_id, "harness_id");
+    const session = requirePart(identity.session_id, "session_id");
+    return `SES-${crypto.createHash("sha256").update(harness).update("\0").update(session).digest("hex").slice(0, 24)}`;
+}
+export function nativeSessionIdentity(harnessId, sessionId) {
+    return { harness_id: requirePart(harnessId, "harness_id"), session_id: requirePart(sessionId, "session_id") };
+}
+export function publicSessionIdentity(input) {
+    return nativeSessionIdentity(input.harness, input.provider_session_id ?? input.session_id);
+}
+function requirePart(value, field) {
+    if (!value || !value.trim())
+        throw new AppError("session_identity_invalid", `${field} must be a non-empty opaque value`, 1, { field });
+    return value;
+}

package/dist/services/sessions.js

@@ -11,6 +11,18 @@ import { checkpointSessionUsage } from "./usage.js";
 import { refreshRunSessionProjection } from "./run-projection.js";
 import { reconcileSessionCoverageRows } from "../domain/session-coverage.js";
 import { appendFlowRunTimelineEvent } from "./runs.js";
+import { publicSessionIdentity, storageSessionId } from "./session-identity.js";
+export function publicFlowSession(context, session) {
+    const identity = publicSessionIdentity(session);
+    const parent = session.parent_session_id
+        ? context.db.get("SELECT harness, provider_session_id, session_id FROM sessions WHERE project_id = ? AND session_id = ?", [session.project_id, session.parent_session_id])
+        : null;
+    const publicFields = { ...session };
+    delete publicFields.session_id;
+    delete publicFields.provider_session_id;
+    delete publicFields.parent_session_id;
+    return { ...publicFields, harness_id: identity.harness_id, session_id: identity.session_id, parent_session: parent ? publicSessionIdentity(parent) : null };
+}
 export function recordFlowSessionObservation(context, input) {
     const duplicate = context.db.get("SELECT id FROM flow_session_segments WHERE project_id = ? AND event_key = ?", [input.projectId, input.eventKey]);
     if (duplicate)
@@ -86,7 +98,7 @@ export function registerFlowSession(context, input) {
         },
         ...(session.protocol_id ? { protocolId: session.protocol_id } : {})
     });
-    return { ok: true, session };
+    return { ok: true, session: publicFlowSession(context, session) };
 }
 export function getFlowSessionStatus(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
@@ -96,7 +108,7 @@ export function getFlowSessionStatus(context, input) {
     });
     return {
         ok: true,
-        sessions,
+        sessions: sessions.map((session) => publicFlowSession(context, session)),
         coverage: reconcileSessionCoverage(sessions)
     };
 }
@@ -111,13 +123,14 @@ export function stopFlowSession(context, input) {
     markSessionStopped(context, project, session, input.reason);
     if (session.run_id)
         refreshRunSessionProjection(context, project.id, session.run_id);
-    return { ok: true, session: flowSessionById(context, project.id, input.sessionId) };
+    const updated = flowSessionById(context, project.id, input.sessionId);
+    return { ok: true, session: updated ? publicFlowSession(context, updated) : null };
 }
 export function syncFlowSessionUsage(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const session = requireFlowSession(context, project.id, input.sessionId);
     if (!session.run_id) {
-        return { ok: true, session_id: session.session_id, extraction_status: "not_observable", diagnostic: "session_not_bound_to_run" };
+        return { ok: true, session: publicSessionIdentity(session), extraction_status: "not_observable", diagnostic: "session_not_bound_to_run" };
     }
     return { ok: true, snapshot: checkpointSessionUsage(context, session, { checkpoint: "manual_sync", stage: session.current_stage }) };
 }
@@ -158,7 +171,7 @@ export function activeFlowSessionsForProject(context, projectId) {
 }
 export function flowSessionsForProject(context, projectId, filter = {}) {
     if (filter.sessionId) {
-        return context.db.all("SELECT * FROM sessions WHERE project_id = ? AND session_id = ? ORDER BY updated_at DESC", [projectId, filter.sessionId]);
+        return context.db.all("SELECT * FROM sessions WHERE project_id = ? AND (session_id = ? OR provider_session_id = ?) ORDER BY updated_at DESC", [projectId, filter.sessionId, filter.sessionId]);
     }
     if (filter.workerId) {
         return context.db.all("SELECT * FROM sessions WHERE project_id = ? AND worker_id = ? ORDER BY updated_at DESC", [projectId, filter.workerId]);
@@ -166,10 +179,7 @@ export function flowSessionsForProject(context, projectId, filter = {}) {
     return context.db.all("SELECT * FROM sessions WHERE project_id = ? ORDER BY updated_at DESC", [projectId]);
 }
 export function flowSessionById(context, projectId, sessionId) {
-    return context.db.get("SELECT * FROM sessions WHERE project_id = ? AND session_id = ?", [
-        projectId,
-        sessionId
-    ]);
+    return context.db.get("SELECT * FROM sessions WHERE project_id = ? AND (session_id = ? OR provider_session_id = ?)", [projectId, sessionId, sessionId]);
 }
 export function updateFlowSessionContinuation(context, projectId, sessionId, actionKey) {
     const session = flowSessionById(context, projectId, sessionId);
@@ -286,7 +296,12 @@ function normalizeFlowSessionPayload(payload) {
 }
 function upsertFlowSession(context, project, payload, forcedSessionId) {
     const now = context.now();
-    const sessionId = forcedSessionId ?? payload.session_id ?? payload.worker_id ?? payload.protocol_id ?? crypto.randomUUID();
+    // `sessions.session_id` is a private storage key.  The native ID is kept
+    // unchanged in provider_session_id and is always paired with its harness in
+    // public contracts.  A caller may pass a forced key only after a trusted
+    // hook has already derived it from that pair.
+    const nativeSessionId = payload.provider_session_id ?? payload.session_id ?? payload.worker_id ?? payload.protocol_id ?? crypto.randomUUID();
+    const sessionId = forcedSessionId ?? storageSessionId({ harness_id: payload.harness ?? "codex-desktop", session_id: nativeSessionId });
     const workspacePath = payload.workspace_path ?? payload.cwd ?? project.root;
     context.db.run(`INSERT INTO sessions
       (session_id, project_id, harness, provider_session_id, agent_id, provider, model, reasoning, mode, agent_type, project_root, flow_kind, status, run_id, parent_session_id, role, aspect_id, plan_item_id, session_kind, protocol_id, worker_id, workspace_path,
@@ -334,7 +349,7 @@ function upsertFlowSession(context, project, payload, forcedSessionId) {
         sessionId,
         project.id,
         payload.harness ?? "codex-desktop",
-        payload.provider_session_id ?? null,
+        nativeSessionId,
         payload.agent_id ?? null,
         payload.provider ?? null,
         payload.model ?? null,

package/dist/services/stage-pause.js

@@ -7,7 +7,7 @@ import { resolveProjectRoot } from "../storage/paths.js";
 import { findRecentMatchingHookEvent, claimStageResumeHookEvent, stageResumeMatchKey } from "./hooks.js";
 import { requireProjectByRoot } from "./projects.js";
 import { appendFlowRunTimelineEvent, pauseFlowRunStage, resumeFlowRunStage } from "./runs.js";
-import { refreshRunWorkProjection } from "./work-registry.js";
+import { bindSessionForResume, refreshRunWorkProjection } from "./work-registry.js";
 export function pauseStageForUser(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
     const project = requireProjectByRoot(context, projectRoot);
@@ -25,8 +25,18 @@ export function pauseStageForUser(context, input) {
     fs.mkdirSync(pauseRoot, { recursive: true });
     fs.writeFileSync(questionPath, question);
     const now = context.now();
-    context.db.run("UPDATE works SET status = 'paused', updated_at = ? WHERE work_id = ? AND status = 'running'", [now, work.work_id]);
-    pauseFlowRunStage(context, { projectRoot, runId: run.id, stage: stage.stage, workId: work.work_id, pauseId, questionPath });
+    context.db.exec("BEGIN IMMEDIATE");
+    try {
+        const paused = context.db.run("UPDATE works SET status = 'paused', updated_at = ? WHERE work_id = ? AND status = 'running'", [now, work.work_id]);
+        if (paused.changes !== 1)
+            throw new AppError("invalid_work_state", "Work changed before pause could be accepted", 1, { work_id: work.work_id });
+        pauseFlowRunStage(context, { projectRoot, runId: run.id, stage: stage.stage, workId: work.work_id, pauseId, questionPath });
+        context.db.exec("COMMIT");
+    }
+    catch (error) {
+        context.db.exec("ROLLBACK");
+        throw error;
+    }
     refreshRunWorkProjection(context, project.id, run.id);
     const resume = stageResumeCommand(context, { runId: run.id, stage: stage.stage, workId: work.work_id, projectRoot });
     const resumeTemplate = `${resume} <<'USER_ANSWER'\n<paste the complete user answer exactly>\nUSER_ANSWER`;
@@ -61,26 +71,31 @@ export function resumeStageAfterUser(context, input) {
         errorCode: "trusted_stage_resume_required",
         operation: "stage resume"
     }).eventKey;
-    const identity = claimStageResumeHookEvent(context, {
-        projectId: project.id,
-        runId: run.id,
-        stage: stage.stage,
-        workId: work.work_id,
-        projectRoot,
-        eventKey: hookEventId
-    });
     const answerPath = path.join(path.dirname(stage.pause.question_path), "answer.md");
     fs.writeFileSync(answerPath, input.answer);
     const now = context.now();
     const workSession = context.db.get("SELECT id, session_id, prompt_path, result_path, status FROM work_sessions WHERE work_id = ? AND status = 'running' ORDER BY created_at DESC LIMIT 1", [work.work_id]);
     if (!workSession)
         throw new AppError("runtime_missing", "Paused Work has no open Session link", 1, { work_id: work.work_id });
-    if (workSession.session_id !== identity.sessionId) {
-        context.db.run("UPDATE work_sessions SET status = 'completed', updated_at = ?, completed_at = ? WHERE id = ?", [now, now, workSession.id]);
-        context.db.run("INSERT INTO work_sessions (id, work_id, session_id, hook_event_id, status, prompt_path, result_path, created_at, updated_at, completed_at) VALUES (?, ?, ?, ?, 'running', ?, ?, ?, ?, NULL)", [`WSES-${crypto.randomUUID()}`, work.work_id, identity.sessionId, identity.hookEventId, workSession.prompt_path, workSession.result_path, now, now]);
+    context.db.exec("BEGIN IMMEDIATE");
+    let identity;
+    try {
+        identity = claimStageResumeHookEvent(context, { projectId: project.id, runId: run.id, stage: stage.stage, workId: work.work_id, projectRoot, eventKey: hookEventId });
+        if (workSession.session_id !== identity.sessionId) {
+            bindSessionForResume(context, work.work_id, identity, now);
+            context.db.run("UPDATE work_sessions SET status = 'completed', updated_at = ?, completed_at = ? WHERE id = ?", [now, now, workSession.id]);
+            context.db.run("INSERT INTO work_sessions (id, work_id, session_id, hook_event_id, status, prompt_path, result_path, created_at, updated_at, completed_at) VALUES (?, ?, ?, ?, 'running', ?, ?, ?, ?, NULL)", [`WSES-${crypto.randomUUID()}`, work.work_id, identity.sessionId, identity.hookEventId, workSession.prompt_path, workSession.result_path, now, now]);
+        }
+        const resumed = context.db.run("UPDATE works SET status = 'running', updated_at = ? WHERE work_id = ? AND status = 'paused'", [now, work.work_id]);
+        if (resumed.changes !== 1)
+            throw new AppError("invalid_work_state", "Work changed before resume could be accepted", 1, { work_id: work.work_id });
+        resumeFlowRunStage(context, { projectRoot, runId: run.id, stage: stage.stage, workId: work.work_id, answerPath });
+        context.db.exec("COMMIT");
+    }
+    catch (error) {
+        context.db.exec("ROLLBACK");
+        throw error;
     }
-    context.db.run("UPDATE works SET status = 'running', updated_at = ? WHERE work_id = ? AND status = 'paused'", [now, work.work_id]);
-    resumeFlowRunStage(context, { projectRoot, runId: run.id, stage: stage.stage, workId: work.work_id, answerPath });
     refreshRunWorkProjection(context, project.id, run.id);
     appendFlowRunTimelineEvent(context, project.id, run.id, { type: "stage_resume_session_bound", stage: stage.stage, work_id: work.work_id, session_id: identity.sessionId });
     const prompt = fs.readFileSync(workSession.prompt_path, "utf8");