harnery 0.36.0 → 0.38.0

package/dist/core/supervisor/service.js

@@ -0,0 +1,450 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, rmSync, unlinkSync, writeFileSync, } from "node:fs";
+import { hostname } from "node:os";
+import { resolve } from "node:path";
+import { performance } from "node:perf_hooks";
+import { collectCoordinationHealthSnapshot } from "../agents/health.js";
+import { checkPidToken, processStartToken } from "../agents/state/proc-start.js";
+import { sampleResources } from "../resources/sampler.js";
+import { requestResourceServiceStop } from "../resources/service.js";
+import { readResourceServiceStatus } from "../resources/service-status.js";
+import { resourcePaths } from "../resources/storage.js";
+import { writePrivateJsonAtomic } from "../storage/atomic-json.js";
+import { closeProcessLoggers, legacyLogFields, processLogger } from "../storage/logger.js";
+import { collectSupervisorActivitySnapshot } from "./activity.js";
+import { SUPERVISOR_SNAPSHOT_SCHEMA_VERSION, SUPERVISOR_STATUS_SCHEMA_VERSION, } from "./contract.js";
+import { explainSupervisorFinding } from "./explanations.js";
+import { updateSupervisorFindings } from "./findings.js";
+import { updateSupervisorHistory } from "./history.js";
+import { projectHookHealth } from "./hook-health.js";
+import { writeSupervisorHookHealth } from "./hook-health-storage.js";
+import { collectHookHealth } from "./hooks.js";
+import { SupervisorLogCollector } from "./log-feed.js";
+import { collectServiceHealth } from "./services.js";
+import { readSupervisorStatus } from "./status.js";
+import { readSupervisorFindings, readSupervisorHistory, supervisorPaths } from "./storage.js";
+import { buildSupervisorTimeline } from "./timeline.js";
+export const SUPERVISOR_DEFAULT_INTERVAL_MS = 2_000;
+export const SUPERVISOR_DEFAULT_IDLE_EXIT_MS = 2 * 60_000;
+const SUPERVISOR_MIN_INTERVAL_MS = 500;
+const SUPERVISOR_MAX_INTERVAL_MS = 60_000;
+const SUPERVISOR_MIN_IDLE_EXIT_MS = 5_000;
+const SUPERVISOR_MAX_IDLE_EXIT_MS = 24 * 60 * 60_000;
+export async function spawnSupervisor(coordRootRaw, options = {}) {
+    const coordRoot = resolve(coordRootRaw);
+    const current = readSupervisorStatus(coordRoot);
+    if (current.running) {
+        throw new Error(`local supervisor is already running under pid ${current.record?.pid}`);
+    }
+    await stopLegacyResourceObserver(coordRoot);
+    const intervalMs = normalizeInterval(options.intervalMs);
+    const idleExitMs = normalizeIdleExit(options.idleExitMs);
+    const paths = supervisorPaths(coordRoot);
+    mkdirSync(paths.root, { recursive: true, mode: 0o700 });
+    rmSync(paths.stop, { force: true });
+    const harnBin = new URL("../../../bin/harn", import.meta.url).pathname;
+    if (!existsSync(harnBin))
+        throw new Error(`cannot find harn executable at ${harnBin}`);
+    let spawnError;
+    const child = spawn(harnBin, [
+        "supervisor",
+        "daemon",
+        "--root",
+        coordRoot,
+        "--interval-ms",
+        String(intervalMs),
+        "--idle-exit-ms",
+        String(idleExitMs),
+        ...(options.keepAlive ? ["--keep-alive"] : []),
+    ], {
+        cwd: coordRoot,
+        detached: true,
+        stdio: ["ignore", "ignore", "ignore"],
+        env: {
+            ...process.env,
+            HARNERY_COORD_ROOT_OVERRIDE: coordRoot,
+            HARNERY_OUTPUT_SESSION_TEE: "0",
+        },
+    });
+    child.once("error", (error) => {
+        spawnError = error;
+    });
+    child.unref();
+    const deadline = Date.now() + 5_000;
+    while (Date.now() < deadline) {
+        await delay(50);
+        if (spawnError)
+            throw spawnError;
+        const status = readSupervisorStatus(coordRoot);
+        if (status.running && status.record?.pid === child.pid)
+            return status;
+        if (child.exitCode !== null)
+            break;
+    }
+    throw new Error(`local supervisor failed to start; inspect ${paths.service}`);
+}
+export async function ensureSupervisorRunning(coordRoot) {
+    const status = readSupervisorStatus(coordRoot);
+    if (status.running)
+        return { state: "running", status };
+    try {
+        const started = await spawnSupervisor(coordRoot);
+        return { state: "started", status: started };
+    }
+    catch (error) {
+        return {
+            state: "unavailable",
+            status: readSupervisorStatus(coordRoot),
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+export function requestSupervisorStop(coordRootRaw) {
+    const coordRoot = resolve(coordRootRaw);
+    const paths = supervisorPaths(coordRoot);
+    const status = readSupervisorStatus(coordRoot);
+    mkdirSync(paths.root, { recursive: true, mode: 0o700 });
+    writePrivateJsonAtomic(paths.stop, {
+        requested_at: new Date().toISOString(),
+        requested_by_pid: process.pid,
+    });
+    if (status.running && status.record?.host === hostname()) {
+        try {
+            process.kill(status.record.pid, "SIGTERM");
+        }
+        catch {
+            // The durable stop file handles a racing exit.
+        }
+    }
+    return readSupervisorStatus(coordRoot);
+}
+export async function runSupervisor(input) {
+    const coordRoot = resolve(input.coordRoot);
+    const paths = supervisorPaths(coordRoot);
+    const intervalMs = normalizeInterval(input.intervalMs);
+    const idleExitMs = normalizeIdleExit(input.idleExitMs);
+    const keepAlive = input.keepAlive ?? false;
+    const now = input.now ?? (() => new Date());
+    const wait = input.wait ?? delay;
+    const lease = acquireLease(coordRoot, now());
+    rmSync(paths.stop, { force: true });
+    const startedAt = now().toISOString();
+    const startToken = processStartToken(process.pid);
+    const status = {
+        schema_version: SUPERVISOR_STATUS_SCHEMA_VERSION,
+        pid: process.pid,
+        ...(startToken ? { start_token: startToken } : {}),
+        host: hostname(),
+        nonce: lease.nonce,
+        state: "starting",
+        started_at: startedAt,
+        heartbeat_at: startedAt,
+        interval_ms: intervalMs,
+        keep_alive: keepAlive,
+        idle_exit_ms: idleExitMs,
+        cycle_count: 0,
+    };
+    let stopping = false;
+    let previousResource;
+    let history = readSupervisorHistory(coordRoot);
+    let findings = readSupervisorFindings(coordRoot);
+    let coordination = collectCoordinationHealthSnapshot(coordRoot, now());
+    const logs = new SupervisorLogCollector(coordRoot);
+    const writeStatus = () => {
+        status.heartbeat_at = now().toISOString();
+        writePrivateJsonAtomic(paths.service, status);
+    };
+    const requestStop = () => {
+        stopping = true;
+        status.state = "stopping";
+        writeStatus();
+    };
+    process.on("SIGINT", requestStop);
+    process.on("SIGTERM", requestStop);
+    status.state = "running";
+    writeStatus();
+    log(coordRoot, "supervisor.started", {
+        pid: process.pid,
+        interval_ms: intervalMs,
+        idle_exit_ms: idleExitMs,
+        keep_alive: keepAlive,
+    });
+    try {
+        while (!stopping && !existsSync(paths.stop)) {
+            const cycleStarted = performance.now();
+            try {
+                const cycleNow = now();
+                const serviceHealth = collectServiceHealth(coordRoot, status);
+                const resource = sampleResources(coordRoot, previousResource, {
+                    services: [
+                        { pid: process.pid, id: "supervisor" },
+                        ...serviceHealth.consumers.map((consumer) => ({
+                            pid: consumer.pid,
+                            id: consumer.id,
+                        })),
+                    ],
+                });
+                previousResource = resource.state;
+                writePrivateJsonAtomic(resourcePaths(coordRoot).snapshot, resource.snapshot);
+                const logFeed = await logs.collect(cycleNow);
+                writePrivateJsonAtomic(paths.log_feed, logFeed);
+                const hookHealth = projectHookHealth(logFeed, cycleNow);
+                writeSupervisorHookHealth(coordRoot, hookHealth);
+                const activity = collectSupervisorActivitySnapshot(coordRoot, cycleNow);
+                writePrivateJsonAtomic(paths.activity, activity);
+                const hooks = collectHookHealth(resource.snapshot);
+                const historyResult = updateSupervisorHistory(history, resource.snapshot);
+                history = historyResult.history;
+                if (historyResult.changed)
+                    writePrivateJsonAtomic(paths.history, history);
+                if (historyResult.changed)
+                    coordination = collectCoordinationHealthSnapshot(coordRoot, cycleNow);
+                writePrivateJsonAtomic(paths.coordination_health, coordination);
+                const priorActiveFindingIds = new Set(findings?.active.map((finding) => finding.id) ?? []);
+                const priorTransitionKeys = new Set(findings?.transitions.map((finding) => `${finding.id}:${finding.state}`) ?? []);
+                findings = updateSupervisorFindings({
+                    previous: findings,
+                    resource: resource.snapshot,
+                    services: serviceHealth.services,
+                    hooks,
+                    history,
+                    logFeed,
+                    hookHealth,
+                    coordination,
+                    activity,
+                    now: cycleNow,
+                });
+                writePrivateJsonAtomic(paths.findings, findings);
+                mkdirSync(paths.timelines, { recursive: true, mode: 0o700 });
+                mkdirSync(paths.explanations, { recursive: true, mode: 0o700 });
+                const projectionUpdates = [
+                    ...findings.active.filter((finding) => !priorActiveFindingIds.has(finding.id)),
+                    ...findings.transitions.filter((finding) => !priorTransitionKeys.has(`${finding.id}:${finding.state}`)),
+                ];
+                for (const finding of projectionUpdates) {
+                    const relatedSources = coordination.recent_events.filter((source) => {
+                        const delta = Math.abs(Date.parse(source.observed_at) - Date.parse(finding.observed_at));
+                        return Number.isFinite(delta) && delta <= 5 * 60_000;
+                    });
+                    writePrivateJsonAtomic(resolve(paths.timelines, `${finding.id}.json`), buildSupervisorTimeline(finding, relatedSources));
+                    writePrivateJsonAtomic(resolve(paths.explanations, `${finding.id}.json`), explainSupervisorFinding(finding));
+                }
+                const retainedFindingIds = new Set([
+                    ...findings.active.map((finding) => finding.id),
+                    ...findings.transitions.map((finding) => finding.id),
+                ]);
+                pruneProjectionDirectory(paths.timelines, retainedFindingIds);
+                pruneProjectionDirectory(paths.explanations, retainedFindingIds);
+                const attributedAgentCount = resource.snapshot.groups.filter((group) => group.kind === "agent").length;
+                const idle = serviceHealth.consumers.length === 0 && attributedAgentCount === 0;
+                if (!keepAlive && idle)
+                    status.idle_since ??= now().toISOString();
+                else
+                    status.idle_since = undefined;
+                const snapshot = {
+                    schema_version: SUPERVISOR_SNAPSHOT_SCHEMA_VERSION,
+                    sampled_at: resource.snapshot.sampled_at,
+                    sequence: status.cycle_count + 1,
+                    collector_duration_ms: round1(performance.now() - cycleStarted),
+                    resource_sample_duration_ms: resource.snapshot.sample_duration_ms,
+                    services: serviceHealth.services,
+                    hooks,
+                    active_finding_count: findings.active.length,
+                    history_point_count: history.points.length,
+                    log_record_count: logFeed.total_records,
+                    live_consumer_count: serviceHealth.consumers.length,
+                    attributed_agent_count: attributedAgentCount,
+                };
+                writePrivateJsonAtomic(paths.snapshot, snapshot);
+                status.cycle_count += 1;
+                status.last_cycle_at = snapshot.sampled_at;
+                status.last_cycle_duration_ms = snapshot.collector_duration_ms;
+                status.last_error_code = undefined;
+                log(coordRoot, "supervisor.sample", {
+                    cycle_count: status.cycle_count,
+                    duration_ms: snapshot.collector_duration_ms,
+                    resource_cpu_ms: resource.snapshot.collector_cpu_ms,
+                    visible_processes: resource.snapshot.visible_process_count,
+                    services: serviceHealth.services.length,
+                    hooks: hooks.length,
+                    findings: findings.active.length,
+                    log_records: logFeed.total_records,
+                    hook_health_records: hookHealth.source_record_count,
+                });
+                if (!keepAlive &&
+                    status.idle_since &&
+                    now().getTime() - Date.parse(status.idle_since) >= idleExitMs) {
+                    log(coordRoot, "supervisor.idle_exit", { idle_exit_ms: idleExitMs });
+                    break;
+                }
+            }
+            catch (error) {
+                status.last_error_code = supervisorErrorCode(error);
+                status.state = "error";
+                log(coordRoot, "supervisor.sample_error", { reason_code: status.last_error_code }, error);
+            }
+            if (status.state === "error")
+                status.state = "running";
+            writeStatus();
+            if (input.maxCycles !== undefined && status.cycle_count >= input.maxCycles)
+                break;
+            const remaining = Math.max(0, intervalMs - (performance.now() - cycleStarted));
+            if (!stopping && !existsSync(paths.stop))
+                await wait(remaining);
+        }
+    }
+    finally {
+        process.off("SIGINT", requestStop);
+        process.off("SIGTERM", requestStop);
+        status.state = "stopped";
+        status.stopped_at = now().toISOString();
+        status.idle_since = undefined;
+        writeStatus();
+        log(coordRoot, "supervisor.stopped", { cycle_count: status.cycle_count });
+        try {
+            await closeProcessLoggers();
+        }
+        finally {
+            releaseLease(paths.lease, lease.nonce);
+        }
+    }
+    return status;
+}
+function acquireLease(coordRoot, now) {
+    const paths = supervisorPaths(coordRoot);
+    mkdirSync(paths.root, { recursive: true, mode: 0o700 });
+    for (let attempt = 0; attempt < 2; attempt++) {
+        const startToken = processStartToken(process.pid);
+        const lease = {
+            pid: process.pid,
+            ...(startToken ? { start_token: startToken } : {}),
+            host: hostname(),
+            nonce: randomUUID(),
+            created_at: now.toISOString(),
+        };
+        try {
+            const fd = openSync(paths.lease, "wx", 0o600);
+            try {
+                writeFileSync(fd, `${JSON.stringify(lease)}\n`, "utf8");
+            }
+            finally {
+                closeSync(fd);
+            }
+            return lease;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            const existing = readLease(paths.lease);
+            if (existing && leaseIsLive(existing)) {
+                throw new Error(`local supervisor lease is held by pid ${existing.pid}`);
+            }
+            try {
+                unlinkSync(paths.lease);
+            }
+            catch {
+                // A concurrent starter may have replaced or removed the stale lease.
+            }
+        }
+    }
+    throw new Error("local supervisor could not acquire its singleton lease");
+}
+function pruneProjectionDirectory(directory, retainedFindingIds) {
+    for (const file of readdirSync(directory)) {
+        if (!file.endsWith(".json"))
+            continue;
+        const findingId = file.slice(0, -5);
+        if (!retainedFindingIds.has(findingId))
+            rmSync(resolve(directory, file), { force: true });
+    }
+}
+function releaseLease(path, nonce) {
+    const current = readLease(path);
+    if (current?.nonce !== nonce)
+        return;
+    try {
+        unlinkSync(path);
+    }
+    catch {
+        // A missing lease is already released.
+    }
+}
+function readLease(path) {
+    try {
+        const value = JSON.parse(readFileSync(path, "utf8"));
+        return value && Number.isSafeInteger(value.pid) && typeof value.nonce === "string"
+            ? value
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function leaseIsLive(lease) {
+    if (lease.host !== hostname())
+        return true;
+    try {
+        process.kill(lease.pid, 0);
+    }
+    catch (error) {
+        if (error.code !== "EPERM")
+            return false;
+    }
+    return checkPidToken(lease.pid, lease.start_token) !== "mismatch";
+}
+async function stopLegacyResourceObserver(coordRoot) {
+    const legacy = readResourceServiceStatus(coordRoot);
+    if (!legacy.running)
+        return;
+    requestResourceServiceStop(coordRoot);
+    const deadline = Date.now() + 2_000;
+    while (readResourceServiceStatus(coordRoot).running && Date.now() < deadline)
+        await delay(50);
+}
+function log(coordRoot, event, fields, error) {
+    try {
+        const logger = processLogger(coordRoot, "supervisor");
+        if (error)
+            logger.error(event, legacyLogFields(fields), error);
+        else
+            logger.info(event, legacyLogFields(fields));
+    }
+    catch {
+        // Observability must never break the supervisor loop.
+    }
+}
+function supervisorErrorCode(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (/procfs|\/proc\//i.test(message))
+        return "procfs_read_failed";
+    if (/permission|EACCES|EPERM/i.test(message))
+        return "permission_denied";
+    if (/log/i.test(message))
+        return "log_collection_failed";
+    return "collection_failed";
+}
+function normalizeInterval(value) {
+    const interval = value ?? SUPERVISOR_DEFAULT_INTERVAL_MS;
+    if (!Number.isFinite(interval) ||
+        interval < SUPERVISOR_MIN_INTERVAL_MS ||
+        interval > SUPERVISOR_MAX_INTERVAL_MS) {
+        throw new Error(`supervisor interval must be ${SUPERVISOR_MIN_INTERVAL_MS}-${SUPERVISOR_MAX_INTERVAL_MS} ms`);
+    }
+    return Math.round(interval);
+}
+function normalizeIdleExit(value) {
+    const idle = value ?? SUPERVISOR_DEFAULT_IDLE_EXIT_MS;
+    if (!Number.isFinite(idle) ||
+        idle < SUPERVISOR_MIN_IDLE_EXIT_MS ||
+        idle > SUPERVISOR_MAX_IDLE_EXIT_MS) {
+        throw new Error(`supervisor idle exit must be ${SUPERVISOR_MIN_IDLE_EXIT_MS}-${SUPERVISOR_MAX_IDLE_EXIT_MS} ms`);
+    }
+    return Math.round(idle);
+}
+function delay(milliseconds) {
+    return new Promise((resolveDelay) => setTimeout(resolveDelay, milliseconds));
+}
+function round1(value) {
+    return Math.round(value * 10) / 10;
+}

package/dist/core/supervisor/services.d.ts

@@ -0,0 +1,11 @@
+import { type ObservedServiceHealth, type SupervisorConsumerRecord, type SupervisorServiceStatusRecord } from "./contract.js";
+export declare function registerSupervisorConsumer(coordRoot: string, input: {
+    id: string;
+    pid?: number;
+}): SupervisorConsumerRecord;
+export declare function unregisterSupervisorConsumer(coordRoot: string, id: string): void;
+export declare function collectServiceHealth(coordRoot: string, supervisor: SupervisorServiceStatusRecord): {
+    services: ObservedServiceHealth[];
+    consumers: SupervisorConsumerRecord[];
+};
+//# sourceMappingURL=services.d.ts.map

package/dist/core/supervisor/services.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"services.d.ts","sourceRoot":"","sources":["../../../src/core/supervisor/services.ts"],"names":[],"mappings":"AAKA,OAAO,EACL,KAAK,qBAAqB,EAE1B,KAAK,wBAAwB,EAC7B,KAAK,6BAA6B,EACnC,MAAM,eAAe,CAAC;AAGvB,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAClC,wBAAwB,CAY1B;AAED,wBAAgB,4BAA4B,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAEhF;AAED,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,6BAA6B,GACxC;IAAE,QAAQ,EAAE,qBAAqB,EAAE,CAAC;IAAC,SAAS,EAAE,wBAAwB,EAAE,CAAA;CAAE,CAuC9E"}

package/dist/core/supervisor/services.js

@@ -0,0 +1,155 @@
+import { existsSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs";
+import { hostname } from "node:os";
+import { join } from "node:path";
+import { checkPidToken, processStartToken } from "../agents/state/proc-start.js";
+import { writePrivateJsonAtomic } from "../storage/atomic-json.js";
+import { SUPERVISOR_CONSUMER_SCHEMA_VERSION, } from "./contract.js";
+import { readSupervisorConsumer, supervisorConsumerPath, supervisorPaths } from "./storage.js";
+export function registerSupervisorConsumer(coordRoot, input) {
+    const pid = input.pid ?? process.pid;
+    const startToken = processStartToken(pid);
+    const record = {
+        schema_version: SUPERVISOR_CONSUMER_SCHEMA_VERSION,
+        id: input.id,
+        pid,
+        ...(startToken ? { start_token: startToken } : {}),
+        registered_at: new Date().toISOString(),
+    };
+    writePrivateJsonAtomic(supervisorConsumerPath(coordRoot, input.id), record);
+    return record;
+}
+export function unregisterSupervisorConsumer(coordRoot, id) {
+    rmSync(supervisorConsumerPath(coordRoot, id), { force: true });
+}
+export function collectServiceHealth(coordRoot, supervisor) {
+    const consumers = readLiveConsumers(coordRoot);
+    const semantic = readDetachedService(join(coordRoot, ".harnery", "semantic", "v2", "service.json"), "semantic-reader");
+    const governor = readDetachedService(join(coordRoot, ".harnery", "governor-service", "service.json"), "governor");
+    const relay = readPresenceRelay(join(coordRoot, ".harnery", "presence", "relay-daemon.json"));
+    const dashboard = consumers.find((consumer) => consumer.id === "dashboard");
+    const services = [
+        {
+            id: "supervisor",
+            state: supervisor.state === "running"
+                ? "running"
+                : supervisor.state === "error"
+                    ? "stale"
+                    : "stopped",
+            pid: supervisor.pid,
+            started_at: supervisor.started_at,
+            heartbeat_at: supervisor.heartbeat_at,
+            ...(supervisor.state === "error" ? { reason: "supervisor-reported-error" } : {}),
+        },
+        semantic,
+        governor,
+        relay,
+        dashboard
+            ? {
+                id: "dashboard",
+                state: "running",
+                pid: dashboard.pid,
+                started_at: dashboard.registered_at,
+            }
+            : { id: "dashboard", state: "stopped" },
+    ];
+    return { services, consumers };
+}
+function readLiveConsumers(coordRoot) {
+    const directory = supervisorPaths(coordRoot).consumers;
+    if (!existsSync(directory))
+        return [];
+    const live = [];
+    for (const entry of readdirSync(directory)) {
+        if (!entry.endsWith(".json"))
+            continue;
+        const path = `${directory}/${entry}`;
+        const record = readSupervisorConsumer(path);
+        if (!record || !consumerAlive(record)) {
+            rmSync(path, { force: true });
+            continue;
+        }
+        live.push(record);
+    }
+    return live.sort((left, right) => left.id.localeCompare(right.id));
+}
+function consumerAlive(record) {
+    if (record.schema_version !== SUPERVISOR_CONSUMER_SCHEMA_VERSION ||
+        !Number.isSafeInteger(record.pid) ||
+        record.pid < 1 ||
+        typeof record.id !== "string") {
+        return false;
+    }
+    try {
+        process.kill(record.pid, 0);
+    }
+    catch (error) {
+        if (error.code !== "EPERM")
+            return false;
+    }
+    return checkPidToken(record.pid, record.start_token) !== "mismatch";
+}
+function readDetachedService(path, id) {
+    const record = readBoundedJson(path);
+    if (!record || !Number.isSafeInteger(record.pid) || record.pid < 1) {
+        return { id, state: "stopped" };
+    }
+    if (record.state === "stopping" || record.state === "stopped") {
+        return projection(id, "stopped", record);
+    }
+    if (record.host && record.host !== hostname()) {
+        const age = record.heartbeat_at
+            ? Date.now() - Date.parse(record.heartbeat_at)
+            : Number.POSITIVE_INFINITY;
+        const state = Number.isFinite(age) && age < 120_000 ? "running" : "stale";
+        return projection(id, state, record, state === "stale" ? "remote-heartbeat-expired" : undefined);
+    }
+    const state = pidAlive(record.pid) ? "running" : "stale";
+    return projection(id, state, record, state === "stale" ? "recorded-running-process-missing" : undefined);
+}
+function readPresenceRelay(path) {
+    const record = readBoundedJson(path);
+    if (!record || !Number.isSafeInteger(record.pid) || record.pid < 1) {
+        return { id: "presence-relay", state: "stopped" };
+    }
+    const running = pidAlive(record.pid);
+    return {
+        id: "presence-relay",
+        state: running ? "running" : "stale",
+        pid: record.pid,
+        ...(record.started_at ? { started_at: record.started_at } : {}),
+        ...(!running ? { reason: "recorded-running-process-missing" } : {}),
+    };
+}
+function projection(id, state, record, reason) {
+    return {
+        id,
+        state,
+        pid: record.pid,
+        ...(record.started_at ? { started_at: record.started_at } : {}),
+        ...(record.heartbeat_at ? { heartbeat_at: record.heartbeat_at } : {}),
+        ...(reason ? { reason } : {}),
+    };
+}
+function readBoundedJson(path) {
+    if (!existsSync(path))
+        return undefined;
+    try {
+        const size = statSync(path).size;
+        if (size < 2 || size > 512 * 1_024)
+            return undefined;
+        const value = JSON.parse(readFileSync(path, "utf8"));
+        return value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}

package/dist/core/supervisor/status.d.ts

@@ -0,0 +1,3 @@
+import { type SupervisorStatus } from "./contract.js";
+export declare function readSupervisorStatus(coordRoot: string, nowMs?: number): SupervisorStatus;
+//# sourceMappingURL=status.d.ts.map

package/dist/core/supervisor/status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../../src/core/supervisor/status.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,eAAe,CAAC;AAKvB,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,SAAa,GAAG,gBAAgB,CAyB5F"}

package/dist/core/supervisor/status.js

@@ -0,0 +1,48 @@
+import { hostname } from "node:os";
+import { checkPidToken } from "../agents/state/proc-start.js";
+import { SUPERVISOR_STATUS_SCHEMA_VERSION, } from "./contract.js";
+import { readSupervisorServiceRecord, supervisorPaths } from "./storage.js";
+const STALE_HEARTBEAT_MS = 15_000;
+export function readSupervisorStatus(coordRoot, nowMs = Date.now()) {
+    const paths = supervisorPaths(coordRoot);
+    const record = readSupervisorServiceRecord(coordRoot);
+    if (!validRecord(record)) {
+        return {
+            running: false,
+            stale: false,
+            status_path: paths.service,
+            snapshot_path: paths.snapshot,
+        };
+    }
+    const heartbeatAt = Date.parse(record.heartbeat_at);
+    const stale = !Number.isFinite(heartbeatAt) || nowMs - heartbeatAt > STALE_HEARTBEAT_MS;
+    const running = record.host === hostname() &&
+        !stale &&
+        (record.state === "starting" || record.state === "running" || record.state === "stopping") &&
+        pidStillMatches(record.pid, record.start_token);
+    return {
+        running,
+        stale,
+        record,
+        status_path: paths.service,
+        snapshot_path: paths.snapshot,
+    };
+}
+function validRecord(value) {
+    return (value?.schema_version === SUPERVISOR_STATUS_SCHEMA_VERSION &&
+        Number.isSafeInteger(value.pid) &&
+        value.pid > 0 &&
+        typeof value.host === "string" &&
+        typeof value.heartbeat_at === "string" &&
+        typeof value.keep_alive === "boolean");
+}
+function pidStillMatches(pid, startToken) {
+    try {
+        process.kill(pid, 0);
+    }
+    catch (error) {
+        if (error.code !== "EPERM")
+            return false;
+    }
+    return checkPidToken(pid, startToken) !== "mismatch";
+}