@deksden-com/dd-flow-cli 0.9.0-beta.14 → 0.9.0-beta.141

package/dist/services/managed-processes.js

@@ -1,50 +1,310 @@
 import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
 import { spawnSync } from "node:child_process";
 import net from "node:net";
 import { getResourceDatabase } from "../storage/database.js";
+import { AppError, errorRecord } from "../shared/errors.js";
+import { maintenanceRetryable } from "../harness-runtime/lib/lease-renewal.mjs";
+export function managedProcessBinding(record, home) {
+    return { resource_home: home, process_id: record.id, registration_sha256: crypto.createHash("sha256").update(JSON.stringify([home, record.id, record.kind, record.owner_id, record.lease_token, record.pid, record.pid_started_at, record.project_id, record.run_id, record.work_id, record.check_id, record.operation_id, record.metadata_json])).digest("hex") };
+}
+export function assertManagedProcessAdmission(context, record) {
+    const expiry = Date.parse(record.lease_expires_at);
+    if (!Number.isFinite(expiry))
+        throw new AppError("runtime_artifact_invalid", "Managed lease expiry is malformed", 1, { process_id: record.id });
+    if (expiry <= Date.parse(context.now()))
+        throw new AppError("process_ownership_unknown", "Managed owner needs fresh renewal before admission", 1, { process_id: record.id, reason: "renewal_required", lease_expires_at: record.lease_expires_at });
+}
 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) {
+/** Retained owners may name the same registry through a historical alias. */
+export function retainedResourceHomeMatches(context, retained) {
+    if (retained === resourceHome(context))
+        return true;
+    if (typeof retained !== "string" || !path.isAbsolute(retained))
+        return false;
+    try {
+        return fs.realpathSync(retained) === fs.realpathSync(resourceHome(context));
+    }
+    catch {
+        return false;
+    }
+}
+/** Runtime IDs are home-local; a shared host registry needs this extra scope. */
+export function managedProcessRuntimeHome(record, authority) {
+    const metadata = parseMetadata(record.metadata_json);
+    if (metadata.dd_flow_home !== undefined)
+        return typeof metadata.dd_flow_home === "string" && path.isAbsolute(metadata.dd_flow_home) ? metadata.dd_flow_home : null;
+    // Older native registrations can still prove their home from the retained
+    // exact daemon owner; PID or project/RUN labels alone never establish it.
+    if (typeof metadata.state_dir === "string" && path.isAbsolute(metadata.state_dir)) {
+        try {
+            const state = JSON.parse(fs.readFileSync(path.join(metadata.state_dir, "daemon.json"), "utf8"));
+            const owner = state.config?.runtime_owner;
+            if (owner?.owner_id === record.owner_id && owner.project_id === record.project_id && owner.run_id === record.run_id && owner.state_dir === metadata.state_dir && typeof owner.dd_flow_home === "string" && path.isAbsolute(owner.dd_flow_home))
+                return owner.dd_flow_home;
+        }
+        catch { /* No retained native scope proof. */ }
+    }
+    if (record.kind === "run-controller" && authority.db.get("SELECT 1 FROM sqlite_schema WHERE name = 'run_controllers'") && authority.db.get("SELECT 1 FROM run_controllers WHERE controller_id = ? AND process_id = ? AND process_lease_token = ? AND project_id = ? AND run_id = ?", [record.owner_id, record.id, record.lease_token, record.project_id, record.run_id]))
+        return authority.ddFlowHome;
+    if (record.kind === "run-control" && authority.db.get("SELECT 1 FROM sqlite_schema WHERE name = 'run_control_workers'") && authority.db.get("SELECT 1 FROM run_control_workers w JOIN run_controls c ON c.control_id = w.control_id WHERE w.control_id = ? AND w.process_id = ? AND w.process_lease_token = ? AND c.project_id = ? AND c.run_id = ?", [record.owner_id, record.id, record.lease_token, record.project_id, record.run_id]))
+        return authority.ddFlowHome;
+    return null;
+}
+export function prepareManagedProcessRegistration(context, input) {
+    requireProcessText(input.kind, "kind");
+    requireProcessText(input.ownerId, "owner");
+    for (const field of ["id", "projectId", "runId", "workId", "checkId", "operationId", "stdoutPath", "stderrPath"]) {
+        if (input[field] !== undefined && input[field] !== null)
+            requireProcessText(input[field], field);
+    }
+    for (const field of ["pid", "ownerPid", "processGroupId"]) {
+        if (input[field] !== undefined)
+            requireProcessPid(input[field], field);
+    }
+    if (input.uniqueActiveOperation !== undefined && typeof input.uniqueActiveOperation !== "boolean")
+        throw new AppError("validation", "uniqueActiveOperation must be boolean", 2);
+    if (input.metadata !== undefined && (!input.metadata || typeof input.metadata !== "object" || Array.isArray(input.metadata)))
+        throw new AppError("validation", "metadata must be a JSON object", 2);
+    prepareManagedProcessLease(context, input.leaseMs);
+    const observer = input.kind === "eval-observer";
+    const observerBirth = observer && input.pid ? processStartedAt(input.pid) : null;
+    if (observer) {
+        if (!Number.isSafeInteger(input.pid) || !input.pid || input.pid < 1 || input.ownerPid !== undefined && input.ownerPid !== input.pid || input.processGroupId !== undefined && input.processGroupId !== input.pid)
+            throw new AppError("process_ownership_unknown", "EVAL observer registration requires its live self-owned process identity", 1);
+        if (!observerBirth)
+            throw new AppError("process_ownership_unknown", "EVAL observer physical identity observation is unavailable", 1, { process_id: input.id, reason: "physical_identity_unavailable", phase: "observer_registration", effect: "no_effect", native_dispatch_started: false });
+        input = { ...input, ownerPid: input.pid, uniqueActiveOperation: true };
+    }
+    if (input.uniqueActiveOperation && !input.operationId)
+        throw new AppError("validation", "Unique managed operation requires operationId", 2);
+    let metadataJson;
+    try {
+        const metadata = { ...input.metadata, dd_flow_home: context.ddFlowHome, ...(input.ownerPid ? { owner_pid: input.ownerPid, owner_pid_started_at: processStartedAt(input.ownerPid) } : {}) };
+        delete metadata.process_birth;
+        delete metadata.owner_birth;
+        if (input.ownerPid)
+            metadata.owner_birth = stableProcessBirth(input.ownerPid);
+        metadataJson = JSON.stringify(metadata);
+    }
+    catch {
+        throw new AppError("validation", "metadata must be JSON-serializable", 2);
+    }
+    const reader = getResourceDatabase(resourceHome(context), "read_existing", context.databaseDeadlineAt);
+    try {
+        if (input.id && reader.get("SELECT 1 FROM managed_processes WHERE id = ?", [input.id]))
+            throw new AppError("validation", "Managed process ID already exists; use its retained registration", 2, { process_id: input.id });
+        if (input.uniqueActiveOperation) {
+            const existing = reader.get("SELECT * FROM managed_processes WHERE operation_id = ? AND state IN ('starting','running','stopping','orphaned')", [input.operationId]);
+            if (existing)
+                throw new AppError("managed_operation_in_progress", "The operation already owns a managed process; observe it instead of spawning a duplicate", 1, { process_id: existing.id, operation_id: input.operationId });
+        }
+    }
+    finally {
+        reader.close?.();
+    }
+    return { input, observer, observerBirth, metadataJson };
+}
+export function registerManagedProcess(context, rawInput) {
+    const { input, observer, observerBirth, metadataJson } = prepareManagedProcessRegistration(context, rawInput);
+    if (!input.uniqueActiveOperation)
+        return registry(context).writeTransaction(() => insertManagedProcess(context, input, metadataJson));
+    const observerProcessBirth = observer ? stableProcessBirth(input.pid) : null;
+    const observerOwner = observer ? parseMetadata(metadataJson) : null;
+    if (observer && (!observerProcessBirth || !observerOwner?.owner_pid_started_at || !parseBirth(observerOwner.owner_birth)))
+        throw new AppError("process_ownership_unknown", "EVAL observer physical identity observation is unavailable", 1, { process_id: input.id, reason: "physical_identity_unavailable", phase: "observer_registration", effect: "no_effect", native_dispatch_started: false });
+    if (observer && !processIsAlive({ pid: input.pid, pid_started_at: observerBirth, metadata_json: JSON.stringify({ process_birth: observerProcessBirth }) }))
+        throw new AppError("process_ownership_unknown", "EVAL observer changed before registration", 1);
+    const db = registry(context);
+    return db.writeTransaction(() => {
+        const existing = db.get("SELECT * FROM managed_processes WHERE operation_id = ? AND state IN ('starting','running','stopping','orphaned')", [input.operationId]);
+        if (existing)
+            throw new AppError("managed_operation_in_progress", "The operation already owns a managed process; observe it instead of spawning a duplicate", 1, { process_id: existing.id, operation_id: input.operationId });
+        let result = insertManagedProcess(context, input, metadataJson);
+        if (observer) {
+            const metadata = JSON.parse(metadataJson);
+            if (input.processGroupId)
+                metadata.process_group_id = input.processGroupId;
+            metadata.process_birth = observerProcessBirth;
+            const now = context.now();
+            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, observerBirth, leaseExpiry(now, input.leaseMs), now, JSON.stringify(metadata), result.id, result.lease_token]);
+            result = requireProcess(db, result.id);
+        }
+        return result;
+    });
+}
+function insertManagedProcess(context, input, metadataJson) {
     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, ...(input.ownerPid ? { owner_pid: input.ownerPid, owner_pid_started_at: processStartedAt(input.ownerPid) } : {}) })]);
+     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, metadataJson]);
     return requireProcess(db, id);
 }
+export function prepareManagedProcessConfirmation(context, input) {
+    requireProcessText(input.id, "id");
+    requireProcessText(input.leaseToken, "lease-token");
+    requireProcessPid(input.pid, "pid");
+    if (input.ownerPid !== undefined)
+        requireProcessPid(input.ownerPid, "owner-pid");
+    if (input.processGroupId !== undefined && input.processGroupId !== null)
+        requireProcessPid(input.processGroupId, "process-group-id");
+    prepareManagedProcessLease(context, input.leaseMs);
+    const current = readManagedProcess(context, input.id);
+    if (current.lease_token !== input.leaseToken)
+        throw new AppError("process_lease_lost", "Managed process lease does not match", 1);
+    if (current.state !== "starting" && !(current.state === "running" && current.pid === input.pid && processIsAlive(current) && (!input.processGroupId || parseMetadata(current.metadata_json).process_group_id === input.processGroupId) && (!input.ownerPid || parseMetadata(current.metadata_json).owner_pid === input.ownerPid)))
+        throw new AppError("process_confirmation_rejected", "Only the retained physical process may be confirmed", 1, { process_id: current.id, state: current.state });
+    return current;
+}
 export function confirmManagedProcess(context, input) {
+    const prepared = prepareManagedProcessConfirmation(context, input);
+    const retainedIdentity = parseMetadata(prepared.metadata_json);
+    const retainedOwner = retainedIdentity.owner_pid;
+    const validRetainedOwner = typeof retainedOwner === "number" && Number.isSafeInteger(retainedOwner) && retainedOwner > 0;
+    const ownerUnknown = Object.hasOwn(retainedIdentity, "owner_pid") && (!validRetainedOwner || typeof retainedIdentity.owner_pid_started_at !== "string" || !retainedIdentity.owner_pid_started_at.trim() || Object.hasOwn(retainedIdentity, "owner_birth") && !parseBirth(retainedIdentity.owner_birth));
+    if (prepared.state === "running" && (!prepared.pid_started_at || Object.hasOwn(retainedIdentity, "process_birth") && !parseBirth(retainedIdentity.process_birth) || ownerUnknown) || input.ownerPid === undefined && Object.hasOwn(retainedIdentity, "owner_pid") && !validRetainedOwner)
+        throw new AppError("process_ownership_unknown", "Retained managed physical identity is unconfirmed", 1, { process_id: input.id, reason: "stored_identity_unconfirmed", phase: "process_confirmation", effect: "no_effect", native_dispatch_started: false });
+    // Initial confirmation must observe the registered owner too, even when a
+    // bootstrap caller omits its optional override. Running bindings never repair.
+    const ownerPid = input.ownerPid ?? (validRetainedOwner ? retainedOwner : undefined);
+    const pidStartedAt = processStartedAt(input.pid), processBirth = stableProcessBirth(input.pid);
+    const ownerStartedAt = ownerPid ? processStartedAt(ownerPid) : null, ownerBirth = ownerPid ? stableProcessBirth(ownerPid) : null;
+    if (!pidStartedAt || !processBirth || ownerPid && (!ownerStartedAt || !ownerBirth))
+        throw new AppError("process_ownership_unknown", "Managed physical identity observation is unavailable", 1, { process_id: input.id, reason: "physical_identity_unavailable", phase: "process_confirmation", effect: "no_effect", native_dispatch_started: false });
     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;
-    if (input.ownerPid) {
-        metadata.owner_pid = input.ownerPid;
-        metadata.owner_pid_started_at = processStartedAt(input.ownerPid);
-    }
-    const result = db.run(`UPDATE managed_processes
+    return db.writeTransaction(() => {
+        const current = requireProcess(db, input.id);
+        if (current.lease_token !== input.leaseToken || !["starting", "running"].includes(current.state))
+            throw new AppError("process_confirmation_rejected", "Managed process changed before confirmation", 1);
+        if (current.state === "running") {
+            if (prepared.state !== "running" || managedProcessBinding(current, resourceHome(context)).registration_sha256 !== managedProcessBinding(prepared, resourceHome(context)).registration_sha256 || current.pid !== input.pid || input.processGroupId && parseMetadata(current.metadata_json).process_group_id !== input.processGroupId || input.ownerPid && parseMetadata(current.metadata_json).owner_pid !== input.ownerPid)
+                throw new AppError("process_confirmation_rejected", "Confirmed process binding changed", 1);
+            return { ...current, registration_sha256: managedProcessBinding(current, resourceHome(context)).registration_sha256 };
+        }
+        const now = context.now();
+        const metadata = parseMetadata(current.metadata_json);
+        if (input.processGroupId)
+            metadata.process_group_id = input.processGroupId;
+        metadata.process_birth = processBirth;
+        if (ownerPid) {
+            metadata.owner_pid = ownerPid;
+            metadata.owner_pid_started_at = ownerStartedAt;
+            metadata.owner_birth = ownerBirth;
+        }
+        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);
+     WHERE id = ? AND lease_token = ? AND state = 'starting'`, [input.pid, pidStartedAt, 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}`);
+        const confirmed = requireProcess(db, input.id);
+        return { ...confirmed, registration_sha256: managedProcessBinding(confirmed, resourceHome(context)).registration_sha256 };
+    });
+}
+export function prepareManagedProcessHeartbeat(context, input) {
+    requireProcessText(input.id, "id");
+    requireProcessText(input.leaseToken, "lease-token");
+    prepareManagedProcessLease(context, input.leaseMs);
 }
 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;
+    return renewManagedProcess(context, input).owned;
+}
+export function renewManagedProcess(context, input) {
+    prepareManagedProcessHeartbeat(context, input);
+    let db;
+    try {
+        if (context.resourceDatabaseMode === "prepared_existing")
+            registry(context);
+        const reader = getResourceDatabase(resourceHome(context), "read_existing", context.databaseDeadlineAt);
+        try {
+            if (!reader.get("SELECT 1 FROM managed_processes WHERE id=? AND lease_token=? AND state IN ('starting','running','stopping')", [input.id, input.leaseToken]))
+                return { owned: false, process_id: input.id };
+        }
+        finally {
+            reader.close?.();
+        }
+        db = registry(context);
+    }
+    catch (error) {
+        // No lease mutation has started. The storage helper cannot know that
+        // operation boundary and deliberately defaults to an unknown effect.
+        if (error instanceof AppError && error.code === "process_heartbeat_timeout"
+            && maintenanceRetryable({ ...error, details: { ...error.details, effect: "no_effect" } }))
+            throw new AppError(error.code, error.message, error.exitCode, { ...error.details, effect: "no_effect", maintenance_phase: "renewal_prepare" });
+        throw error;
+    }
+    return db.writeTransaction(() => {
+        const now = context.now();
+        if (!db.get("SELECT 1 FROM managed_processes WHERE id=? AND lease_token=? AND state IN ('starting','running','stopping')", [input.id, input.leaseToken]))
+            return { owned: false, process_id: input.id };
+        const changed = db.run("UPDATE managed_processes SET lease_expires_at = ?, updated_at = ? WHERE id = ? AND lease_token = ? AND state IN ('starting','running','stopping')", [leaseExpiry(now, input.leaseMs), now, input.id, input.leaseToken]).changes === 1;
+        if (!changed)
+            return { owned: false, process_id: input.id };
+        const record = requireProcess(db, input.id);
+        return { owned: true, process_id: record.id, lease_expires_at: record.lease_expires_at, registration_sha256: managedProcessBinding(record, resourceHome(context)).registration_sha256 };
+    });
+}
+/** Read-only lease check for a caller already holding a RUN writer. Renewal
+ * must happen before entering that writer, never from this assertion. */
+export function assertManagedProcessLease(context, input) {
+    let reader;
+    try {
+        reader = getResourceDatabase(resourceHome(context), "read_isolated", context.databaseDeadlineAt);
+        const current = reader.get("SELECT pid, lease_expires_at, state FROM managed_processes WHERE id = ? AND lease_token = ?", [input.id, input.leaseToken]);
+        if (!current || current.pid !== input.pid || !["starting", "running"].includes(current.state)) {
+            throw new AppError("controller_lease_lost", "Managed owner lease changed before productive dispatch", 1, { process_id: input.id });
+        }
+        if (!Number.isFinite(Date.parse(current.lease_expires_at)) || Date.parse(current.lease_expires_at) <= Date.now())
+            throw new AppError("controller_lease_unconfirmed", "Managed owner requires renewal before productive dispatch", 1, { process_id: input.id, reason: "renewal_required" });
+    }
+    catch (error) {
+        const failure = errorRecord(error);
+        // This assertion only reads. Unavailable observation is not evidence of
+        // owner loss; the caller must reconfirm outside its RUN writer.
+        if (maintenanceRetryable({ ...failure, details: { ...failure.details, effect: "no_effect" } }))
+            throw new AppError("controller_lease_unconfirmed", "Managed owner observation requires confirmation before productive dispatch", 1, { process_id: input.id, reason: "observation_unavailable", cause: failure });
+        throw error;
+    }
+    finally {
+        reader?.close?.();
+    }
+}
+export function prepareManagedProcessFinish(context, input) {
+    requireProcessText(input.id, "id");
+    requireProcessText(input.leaseToken, "lease-token");
+    if (input.state !== "stopped" && input.state !== "failed")
+        throw new AppError("validation", "--state must be stopped or failed", 2);
+    if (input.reason !== undefined && input.reason !== null && typeof input.reason !== "string")
+        throw new AppError("validation", "reason must be a string or null", 2);
+    return readManagedProcess(context, input.id);
 }
 export function finishManagedProcess(context, input) {
+    prepareManagedProcessFinish(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;
+    return db.writeTransaction(() => {
+        const existing = requireProcess(db, input.id);
+        if (existing.lease_token !== input.leaseToken || existing.state !== input.state && !["starting", "running", "stopping", "orphaned"].includes(existing.state))
+            return false;
+        if (existing.state === input.state) {
+            db.run("DELETE FROM managed_resources WHERE process_id = ?", [input.id]);
+            return true;
+        }
+        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]);
+        if (updated)
+            return true;
+        // Another client may have completed the same lease after our initial read.
+        const current = requireProcess(db, input.id);
+        return current.lease_token === input.leaseToken && current.state === input.state;
+    });
 }
 export function processIsAlive(record) {
     if (!record.pid)
@@ -53,22 +313,78 @@ export function processIsAlive(record) {
         process.kill(record.pid, 0);
     }
     catch (error) {
-        return error.code !== "ESRCH";
+        const code = error.code;
+        if (code === "ESRCH")
+            return false;
+        // A reused PID may now belong to another user. EPERM proves presence,
+        // not identity; still compare its observed birth before calling it ours.
+        if (code !== "EPERM")
+            return true;
+    }
+    const metadata = record.metadata_json ? parseMetadata(record.metadata_json) : {};
+    if (Object.hasOwn(metadata, "process_birth")) {
+        const birth = parseBirth(metadata.process_birth), observed = stableProcessBirth(record.pid);
+        return !birth || !observed || observed === birth;
     }
     const started = processStartedAt(record.pid);
     return !record.pid_started_at || !started || record.pid_started_at === started;
 }
+/** Unlike an admission guard, observability must distinguish unknown from
+ * alive. Unknown identity still cannot authorize termination or finalization. */
+export function managedProcessObservation(record) {
+    if (!record.pid || !record.pid_started_at)
+        return 'unknown';
+    try {
+        process.kill(record.pid, 0);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ESRCH")
+            return "absent";
+        if (code !== "EPERM")
+            return "unknown";
+    }
+    const reply = spawnSync('ps', ['-o', 'lstart=,stat=', '-p', String(record.pid)], { encoding: 'utf8', timeout: 1000, env: { ...process.env, TZ: 'UTC', LC_ALL: 'C' } });
+    if (reply.status !== 0 || !reply.stdout.trim())
+        return 'unknown';
+    const parts = reply.stdout.trim().split(/\s+/), state = parts.pop();
+    if (state?.startsWith('Z'))
+        return 'absent';
+    const metadata = parseMetadata(record.metadata_json);
+    if (Object.hasOwn(metadata, 'process_birth')) {
+        const expected = parseBirth(metadata.process_birth);
+        if (!expected)
+            return 'unknown';
+        const observed = `ps-lstart-utc-c@1:${parts.join(' ')}`;
+        return expected.replace(/\s+/g, ' ') === observed ? 'alive' : 'absent';
+    }
+    // Legacy lstart lacks a recorded timezone. A mismatch might be timezone
+    // drift, so only equal identity or a missing PID establishes an outcome.
+    const legacy = processStartedAt(record.pid);
+    return legacy && legacy === record.pid_started_at ? 'alive' : 'unknown';
+}
 export function processTreeIsAlive(record) {
     if (processIsAlive(record))
         return true;
     const group = parseMetadata(record.metadata_json).process_group_id;
+    const birth = parseBirth(parseMetadata(record.metadata_json).process_birth);
+    // POSIX cannot reuse a leader PID while its old process group survives.
+    if (process.platform !== "win32" && group === record.pid && record.pid && birth) {
+        try {
+            process.kill(record.pid, 0);
+        }
+        catch { /* A missing leader can still have living children. */ }
+        const observed = stableProcessBirth(record.pid);
+        if (observed && observed !== birth)
+            return false;
+    }
     if (process.platform !== "win32" && typeof group === "number") {
         try {
             process.kill(-group, 0);
             return true;
         }
-        catch {
-            return false;
+        catch (error) {
+            return error.code !== "ESRCH";
         }
     }
     return false;
@@ -77,7 +393,7 @@ export function managedOwnerIsAlive(record) {
     const metadata = parseMetadata(record.metadata_json);
     if (typeof metadata.owner_pid !== "number")
         return null;
-    return processIsAlive({ pid: metadata.owner_pid, pid_started_at: typeof metadata.owner_pid_started_at === "string" ? metadata.owner_pid_started_at : null });
+    return processIsAlive({ pid: metadata.owner_pid, pid_started_at: typeof metadata.owner_pid_started_at === "string" ? metadata.owner_pid_started_at : null, metadata_json: JSON.stringify({ process_birth: metadata.owner_birth }) });
 }
 /**
  * Expiry proves that observation stopped, not that the owner died.  A live PID
@@ -87,32 +403,93 @@ export function managedOwnerIsAlive(record) {
 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 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]).filter(candidate => {
+        const ownerAlive = managedOwnerIsAlive(candidate);
+        return ownerAlive !== true && !(ownerAlive === null && processTreeIsAlive(candidate));
+    });
+    return db.writeTransaction(() => {
         const claimed = [];
         for (const candidate of candidates) {
-            const ownerAlive = managedOwnerIsAlive(candidate);
-            if (ownerAlive === true || (ownerAlive === null && processTreeIsAlive(candidate)))
+            // A heartbeat or replacement registration invalidates the pre-writer
+            // death proof; expiry alone never authorizes claiming that new owner.
+            if (JSON.stringify(db.get("SELECT * FROM managed_processes WHERE id = ?", [candidate.id])) !== JSON.stringify(candidate))
                 continue;
             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;
+    });
+}
+/** Workspace gates are leases, not spawned processes. Children retain their own registrations. */
+export function managedLeaseReleased(record) {
+    const metadata = parseMetadata(record.metadata_json);
+    return record.kind === "workspace-gate" && record.pid === null && record.pid_started_at === null
+        && metadata.process_group_id == null && metadata.role === "check_gate"
+        && ["stopped", "failed"].includes(record.state) && Boolean(record.finished_at);
+}
+export function managedProcessStatus(context) {
+    const db = getResourceDatabase(resourceHome(context), "read_existing", context.databaseDeadlineAt);
+    try {
+        return db.all("SELECT * FROM managed_processes ORDER BY updated_at DESC, id");
     }
-    catch (error) {
-        db.exec("ROLLBACK");
-        throw error;
+    finally {
+        db.close?.();
     }
 }
-export function managedProcessStatus(context) {
-    return registry(context).all("SELECT * FROM managed_processes ORDER BY updated_at DESC, id");
+export function prepareManagedProcessStopOperation(context, input) {
+    const graceMs = prepareManagedProcessStop(input);
+    const record = readManagedProcess(context, input.id);
+    assertStopOwnership(record, input.leaseToken);
+    return { record, graceMs };
+}
+function readManagedProcess(context, id) {
+    const db = getResourceDatabase(resourceHome(context), "read_existing", context.databaseDeadlineAt);
+    try {
+        return requireProcess(db, id);
+    }
+    finally {
+        db.close?.();
+    }
+}
+function assertStopOwnership(record, leaseToken) {
+    if (record.lease_token !== leaseToken)
+        throw new AppError("process_lease_lost", "Managed process lease does not match", 1);
+    if (["stopped", "failed"].includes(record.state) && !processTreeIsAlive(record))
+        return;
+    if (!record.pid || !record.pid_started_at)
+        throw new AppError("process_identity_unknown", "Managed process has no confirmed physical identity; retain its pending launch", 1);
+}
+export async function stopManagedProcess(context, input) {
+    const { graceMs } = prepareManagedProcessStopOperation(context, input);
+    const db = registry(context), record = requireProcess(db, input.id);
+    assertStopOwnership(record, input.leaseToken);
+    if (["stopped", "failed"].includes(record.state) && !processTreeIsAlive(record))
+        return record;
+    db.run("UPDATE managed_processes SET state = 'stopping', updated_at = ? WHERE id = ? AND lease_token = ? AND state IN ('starting','running','orphaned')", [context.now(), record.id, record.lease_token]);
+    if (processTreeIsAlive(record)) {
+        const signalErrors = [];
+        const termError = terminateOwnedProcess(record, "SIGTERM");
+        if (termError)
+            signalErrors.push(errorRecord(termError));
+        await delay(graceMs);
+        if (!termError && input.force !== false && processTreeIsAlive(record)) {
+            const killError = terminateOwnedProcess(record, "SIGKILL");
+            if (killError)
+                signalErrors.push(errorRecord(killError));
+            await delay(250);
+        }
+        if (processTreeIsAlive(record))
+            throw Object.assign(new Error("Owned process tree could not be safely stopped; resources retained"), { code: "process_tree_not_settled", details: { process_id: record.id, signal_errors: signalErrors } });
+    }
+    if (!finishManagedProcess(context, { id: record.id, leaseToken: record.lease_token, state: "stopped", reason: input.reason ?? "requested_stop" }))
+        throw Object.assign(new Error("Managed process ownership changed before settlement"), { code: "process_lease_lost" });
+    return requireProcess(db, record.id);
 }
 /** Reconcile only records the system owns and has atomically claimed. */
 export async function reconcileExpiredManagedProcesses(context, ownerId, graceMs = 1_000) {
+    prepareManagedProcessReconcile(ownerId, graceMs);
     const claimed = claimExpiredManagedProcesses(context, ownerId);
     const outcomes = [];
     for (const processRecord of claimed) {
@@ -121,22 +498,46 @@ export async function reconcileExpiredManagedProcesses(context, ownerId, graceMs
             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));
+        try {
+            await stopManagedProcess(context, { id: processRecord.id, leaseToken: processRecord.lease_token, graceMs, reason: "orphan_reconciled" });
+            outcomes.push({ id: processRecord.id, outcome: "stopped" });
         }
-        if (processTreeIsAlive(processRecord)) {
+        catch (error) {
+            if (error.code !== "process_tree_not_settled")
+                throw error;
             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 function prepareManagedProcessStop(input) {
+    requireProcessText(input.id, "id");
+    requireProcessText(input.leaseToken, "lease-token");
+    if (input.reason !== undefined)
+        requireProcessText(input.reason, "reason");
+    if (input.force !== undefined && typeof input.force !== "boolean")
+        throw new AppError("validation", "force must be boolean", 2);
+    return prepareProcessGrace(input.graceMs);
+}
+export function prepareManagedProcessReconcile(ownerId, graceMs) {
+    requireProcessText(ownerId, "owner");
+    return prepareProcessGrace(graceMs);
+}
+function requireProcessText(value, parameter) {
+    if (typeof value !== "string" || !value.trim())
+        throw new AppError("validation", `--${parameter} must be nonempty text`, 2);
+}
+function requireProcessPid(value, parameter) {
+    if (!Number.isSafeInteger(value) || Number(value) <= 0)
+        throw new AppError("validation", `--${parameter} must be a positive integer`, 2);
+}
+function prepareProcessGrace(value = 1_000) {
+    if (!Number.isSafeInteger(value) || value < 0 || value > 2 ** 31 - 1)
+        throw new AppError("validation", "--grace-ms must be a nonnegative integer within the supported timer range", 2);
+    return value;
+}
 export async function reservePorts(context, input) {
+    prepareManagedProcessLease(context, input.leaseMs);
     const db = registry(context);
     const claims = [];
     const ports = {};
@@ -162,23 +563,42 @@ export async function reservePorts(context, input) {
     }
     return { ports, release: () => releasePortClaims(db, claims) };
 }
-function registry(context) { return getResourceDatabase(resourceHome(context)); }
+function registry(context) { return getResourceDatabase(resourceHome(context), context.resourceDatabaseMode, context.databaseDeadlineAt); }
 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; }
+    throw new AppError("not_found", `Managed process is missing: ${id}`, 1); return row; }
+export function prepareManagedProcessLease(context, leaseMs) { return leaseExpiry(context.now(), leaseMs); }
+function leaseExpiry(now, leaseMs = defaultLeaseMs) {
+    if (!Number.isSafeInteger(leaseMs) || leaseMs <= 0 || !Number.isFinite(new Date(Date.parse(now) + leaseMs).getTime()))
+        throw new AppError("validation", "--lease-ms must be a positive integer within the supported date range", 2);
+    return new Date(Date.parse(now) + leaseMs).toISOString();
+}
+export function processStartedAt(pid) { const result = spawnSync("ps", ["-o", "lstart=", "-p", String(pid)], { encoding: "utf8", timeout: 1_000 }); const value = result.status === 0 ? result.stdout.trim() : ""; return value || null; }
+function stableProcessBirth(pid) {
+    const result = spawnSync("ps", ["-o", "lstart=", "-p", String(pid)], { encoding: "utf8", timeout: 1_000, env: { ...process.env, TZ: "UTC", LC_ALL: "C" } });
+    const value = result.status === 0 ? result.stdout.trim() : "";
+    return value ? `ps-lstart-utc-c@1:${value}` : null;
+}
+function parseBirth(value) { return typeof value === "string" && value.startsWith("ps-lstart-utc-c@1:") && value.length > "ps-lstart-utc-c@1:".length ? 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) {
     // Never signal a group merely because its former leader PID was once ours.
     // PID reuse or a departed leader makes group ownership unprovable.
-    if (!record.pid || !record.pid_started_at || !processIsAlive(record))
+    if (!record.pid || !record.pid_started_at)
         return;
-    const group = parseMetadata(record.metadata_json).process_group_id;
+    const metadata = parseMetadata(record.metadata_json);
+    const birth = parseBirth(metadata.process_birth);
+    if (Object.hasOwn(metadata, "process_birth") ? !birth || stableProcessBirth(record.pid) !== birth : processStartedAt(record.pid) !== record.pid_started_at)
+        return;
+    const group = metadata.process_group_id;
+    // A non-leader PID does not establish ownership of its whole process group.
     try {
-        process.kill(process.platform === "win32" || typeof group !== "number" ? record.pid : -group, signal);
+        process.kill(process.platform === "win32" || group !== record.pid ? record.pid : -group, signal);
+    }
+    catch (error) {
+        if (error.code !== "ESRCH")
+            return Object.assign(error, { details: { process_id: record.id, pid: record.pid, pgid: group ?? null, signal, phase: "owned_process_stop" } });
     }
-    catch { /* inspect again below */ }
 }
 function parseMetadata(value) { try {
     const parsed = JSON.parse(value);