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

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

@@ -0,0 +1,425 @@
+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";
+}
+/** 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);
+    db.beginWriteTransaction();
+    try {
+        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) {
+            result = confirmManagedProcess(context, { id: result.id, leaseToken: result.lease_token, pid: input.pid, ...(input.processGroupId ? { processGroupId: input.processGroupId } : {}) });
+            if (result.pid_started_at !== observerBirth || !processIsAlive(result))
+                throw new AppError("process_ownership_unknown", "EVAL observer changed before registration committed", 1);
+        }
+        db.exec("COMMIT");
+        return result;
+    }
+    catch (error) {
+        db.exec("ROLLBACK");
+        throw error;
+    }
+}
+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, 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 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]);
+    if (result.changes !== 1)
+        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;
+}
+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]);
+    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)
+        return false;
+    try {
+        process.kill(record.pid, 0);
+    }
+    catch (error) {
+        return error.code !== "ESRCH";
+    }
+    const started = processStartedAt(record.pid);
+    return !record.pid_started_at || !started || record.pid_started_at === started;
+}
+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 (error) {
+            return error.code !== "ESRCH";
+        }
+    }
+    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 });
+}
+/**
+ * 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.beginWriteTransaction();
+    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 ownerAlive = managedOwnerIsAlive(candidate);
+            if (ownerAlive === true || (ownerAlive === null && processTreeIsAlive(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;
+    }
+    catch (error) {
+        db.exec("ROLLBACK");
+        throw error;
+    }
+}
+/** 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");
+    }
+    finally {
+        db.close?.();
+    }
+}
+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) {
+        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;
+        }
+        try {
+            await stopManagedProcess(context, { id: processRecord.id, leaseToken: processRecord.lease_token, graceMs, reason: "orphan_reconciled" });
+            outcomes.push({ id: processRecord.id, outcome: "stopped" });
+        }
+        catch (error) {
+            if (error.code !== "process_tree_not_settled")
+                throw error;
+            outcomes.push({ id: processRecord.id, outcome: "kill_failed" });
+        }
+    }
+    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 = {};
+    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 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" }); 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) {
+    // 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 {
+        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)); }