@deksden-com/dd-flow-cli 0.9.0-beta.11 → 0.9.0-beta.110

package/dist/services/managed-daemon-binding.js

@@ -0,0 +1,38 @@
+import fs from "node:fs";
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { managedProcessRuntimeHome, managedProcessStatus } from "./managed-processes.js";
+export function readNativeDaemonState(stateDir) {
+    if (!path.isAbsolute(stateDir))
+        throw new AppError("daemon_owner_mismatch", "Native state directory must be absolute", 1);
+    return JSON.parse(fs.readFileSync(path.join(stateDir, "daemon.json"), "utf8"));
+}
+/** A shared directory or logical owner is not a physical provider binding. */
+export function managedProviderBelongsToDaemon(provider, daemon, state) {
+    const child = JSON.parse(provider.metadata_json), parent = JSON.parse(daemon.metadata_json);
+    return provider.kind === daemon.kind.replace(/-daemon$/, "-provider")
+        && state.provider_process?.id === provider.id && state.provider_process.lease_token === provider.lease_token
+        && Boolean(provider.pid && provider.pid_started_at && daemon.pid && daemon.pid_started_at)
+        && state.provider_pid === provider.pid && child.owner_pid === daemon.pid && child.owner_pid_started_at === daemon.pid_started_at
+        && provider.owner_id === daemon.owner_id && provider.project_id === daemon.project_id && provider.run_id === daemon.run_id && provider.work_id === daemon.work_id
+        && child.state_dir === parent.state_dir && child.role === parent.role && child.dd_flow_home === parent.dd_flow_home && child.adapter_executable === parent.adapter_executable
+        && child.dispatch_barrier === "run-generation@1" && child.budget?.scope_id === parent.budget?.scope_id;
+}
+/** Identity proof only. Liveness and clean shutdown are separate caller decisions. */
+export function requireManagedDaemonBinding(context, input) {
+    const state = readNativeDaemonState(input.stateDir);
+    const owner = state.config?.runtime_owner;
+    const record = managedProcessStatus(context).find(record => record.id === state.resource_process?.id);
+    const metadata = record && JSON.parse(record.metadata_json);
+    if (!record || !owner || !record.kind.endsWith("-daemon")
+        || record.lease_token !== state.resource_process?.lease_token
+        || !record.pid || record.pid !== state.pid || !record.pid_started_at
+        || record.owner_id !== owner.owner_id || input.ownerId !== undefined && record.owner_id !== input.ownerId
+        || record.project_id !== input.projectId || owner.project_id !== input.projectId
+        || record.run_id !== input.runId || owner.run_id !== input.runId
+        || metadata?.state_dir !== input.stateDir || owner.state_dir !== input.stateDir
+        || owner.dd_flow_home !== context.ddFlowHome || managedProcessRuntimeHome(record, context) !== context.ddFlowHome) {
+        throw new AppError("daemon_owner_mismatch", "Native daemon has no proven physical ownership in this RUN and runtime home", 1);
+    }
+    return { state, process: record };
+}

package/dist/services/managed-processes.js

@@ -1,28 +1,146 @@
 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 } from "../shared/errors.js";
+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") };
+}
 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) {
+/** 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 || !observerBirth || 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);
+        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 {
+        metadataJson = JSON.stringify({ ...input.metadata, dd_flow_home: context.ddFlowHome, ...(input.ownerPid ? { owner_pid: input.ownerPid, owner_pid_started_at: processStartedAt(input.ownerPid) } : {}) });
+    }
+    catch {
+        throw new AppError("validation", "metadata must be JSON-serializable", 2);
+    }
+    const reader = getResourceDatabase(resourceHome(context), "read_existing");
+    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 insertManagedProcess(context, input, metadataJson);
+    const db = registry(context);
+    if (observer && !processIsAlive({ pid: input.pid, pid_started_at: observerBirth }))
+        throw new AppError("process_ownership_unknown", "EVAL observer changed before registration", 1);
+    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;
+            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 ?? {})]);
+     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")
+        throw new AppError("process_confirmation_rejected", "Only a starting managed process can be confirmed", 1, { process_id: current.id, state: current.state });
+    return current;
+}
 export function confirmManagedProcess(context, input) {
+    const current = prepareManagedProcessConfirmation(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;
+    if (input.ownerPid) {
+        metadata.owner_pid = input.ownerPid;
+        metadata.owner_pid_started_at = processStartedAt(input.ownerPid);
+    }
     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]);
@@ -30,17 +148,64 @@ export function confirmManagedProcess(context, input) {
         throw new Error(`Managed process cannot be confirmed: ${input.id}`);
     return requireProcess(db, input.id);
 }
+export function prepareManagedProcessHeartbeat(context, input) {
+    requireProcessText(input.id, "id");
+    requireProcessText(input.leaseToken, "lease-token");
+    prepareManagedProcessLease(context, input.leaseMs);
+}
 export function heartbeatManagedProcess(context, input) {
+    prepareManagedProcessHeartbeat(context, input);
+    const reader = getResourceDatabase(resourceHome(context), "read_existing");
+    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 false;
+    }
+    finally {
+        reader.close?.();
+    }
     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;
 }
+/** 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) {
+    const reader = getResourceDatabase(resourceHome(context), "read_isolated");
+    try {
+        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)
+            || Date.parse(current.lease_expires_at) <= Date.now()) {
+            throw new AppError("controller_lease_lost", "Managed owner lease changed or expired before productive dispatch", 1, { process_id: input.id });
+        }
+    }
+    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) {
+    const existing = prepareManagedProcessFinish(context, input);
+    if (existing.lease_token === input.leaseToken && existing.state === input.state)
+        return true;
+    if (existing.lease_token !== input.leaseToken || !["starting", "running", "stopping", "orphaned"].includes(existing.state))
+        return false;
     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;
+    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)
@@ -48,51 +213,123 @@ export function processIsAlive(record) {
     try {
         process.kill(record.pid, 0);
     }
-    catch {
-        return false;
+    catch (error) {
+        return error.code !== "ESRCH";
     }
-    return !record.pid_started_at || record.pid_started_at === processStartedAt(record.pid);
+    const started = processStartedAt(record.pid);
+    return !record.pid_started_at || !started || record.pid_started_at === started;
 }
-function processTreeIsAlive(record) {
+export function processTreeIsAlive(record) {
+    if (processIsAlive(record))
+        return true;
     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;
+        catch (error) {
+            return error.code !== "ESRCH";
         }
     }
-    return processIsAlive(record);
+    return false;
+}
+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 });
 }
-/** Claims only expired records.  Callers must still verify `processIsAlive` before stopping a PID. */
+/**
+ * Expiry proves that observation stopped, not that the owner died.  A live PID
+ * remains owned until its result is reconciled; only a dead process can be
+ * atomically claimed for cleanup.
+ */
 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) {
+            // 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");
+    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");
+    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)) {
+        terminateOwnedProcess(record, "SIGTERM");
+        await delay(graceMs);
+        if (input.force !== false && processTreeIsAlive(record)) {
+            terminateOwnedProcess(record, "SIGKILL");
+            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 } });
+    }
+    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) {
@@ -101,22 +338,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 = {};
@@ -144,13 +405,20 @@ export async function reservePorts(context, input) {
 }
 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; }
+    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 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))
+    // 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 || processStartedAt(record.pid) !== record.pid_started_at)
         return;
     const group = parseMetadata(record.metadata_json).process_group_id;
     try {