harnery 0.36.0 → 0.37.0

package/dist/core/hooks/health.d.ts

@@ -0,0 +1,59 @@
+import type { Adapter } from "../adapter.js";
+export declare const HOOK_HEALTH_EVENT: "agent_hook.completed";
+export declare const HOOK_HEALTH_RECEIPT_VERSION: 1;
+export declare const HOOK_HEALTH_ERROR_PHASE_LIMIT = 8;
+export type HookHealthOutcome = "completed" | "skipped" | "degraded" | "faulted";
+export interface HookHealthState {
+    readonly started_at_ms: number;
+    readonly started_rss_bytes: number;
+    readonly event_name: string | null;
+    readonly adapter: Adapter | null;
+    readonly payload_bytes: number;
+    coord_root: string | null;
+    owner_id?: string;
+    skipped_reason?: string;
+    v3_state?: string;
+    error_phases: string[];
+}
+export interface HookHealthReceipt {
+    receipt_version: typeof HOOK_HEALTH_RECEIPT_VERSION;
+    hook_name: string;
+    adapter: Adapter | "unknown";
+    outcome: HookHealthOutcome;
+    exit_contract: "always-zero";
+    exit_code: 0;
+    duration_ms: number;
+    payload_bytes: number;
+    pid: number;
+    rss_start_bytes: number;
+    rss_end_bytes: number;
+    rss_delta_bytes: number;
+    retry_worker: boolean;
+    error_count: number;
+    error_phases: readonly string[];
+    owner_id?: string;
+    skipped_reason?: string;
+    v3_state?: string;
+}
+export declare function beginHookHealth(input: {
+    started_at_ms: number;
+    started_rss_bytes: number;
+    event_name: string | null;
+    adapter: Adapter | null;
+    payload_bytes: number;
+}): HookHealthState;
+export declare function observeHookDebug(state: HookHealthState | undefined, entry: Readonly<Record<string, unknown>>): void;
+export declare function observeHookError(state: HookHealthState | undefined, phase: unknown): void;
+export declare function finalizeHookHealth(state: HookHealthState, input: {
+    finished_at_ms: number;
+    finished_rss_bytes: number;
+    pid: number;
+    faulted?: boolean;
+}): HookHealthReceipt;
+export declare function writeHookHealthCompletion(state: HookHealthState | undefined, input: {
+    finished_at_ms: number;
+    finished_rss_bytes: number;
+    pid: number;
+    faulted?: boolean;
+}): HookHealthReceipt | undefined;
+//# sourceMappingURL=health.d.ts.map

package/dist/core/hooks/health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../../src/core/hooks/health.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAG7C,eAAO,MAAM,iBAAiB,EAAG,sBAA+B,CAAC;AACjE,eAAO,MAAM,2BAA2B,EAAG,CAAU,CAAC;AACtD,eAAO,MAAM,6BAA6B,IAAI,CAAC;AAE/C,MAAM,MAAM,iBAAiB,GAAG,WAAW,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAAC;AAEjF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,eAAe,EAAE,OAAO,2BAA2B,CAAC;IACpD,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7B,OAAO,EAAE,iBAAiB,CAAC;IAC3B,aAAa,EAAE,aAAa,CAAC;IAC7B,SAAS,EAAE,CAAC,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,OAAO,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE;IACrC,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;CACvB,GAAG,eAAe,CAMlB;AAED,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,eAAe,GAAG,SAAS,EAClC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACvC,IAAI,CAMN;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,eAAe,GAAG,SAAS,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAGzF;AAED,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,eAAe,EACtB,KAAK,EAAE;IACL,cAAc,EAAE,MAAM,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,GACA,iBAAiB,CA+BnB;AAED,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,eAAe,GAAG,SAAS,EAClC,KAAK,EAAE;IACL,cAAc,EAAE,MAAM,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,GACA,iBAAiB,GAAG,SAAS,CAS/B"}

package/dist/core/hooks/health.js

@@ -0,0 +1,84 @@
+import { processLogger } from "../storage/logger.js";
+export const HOOK_HEALTH_EVENT = "agent_hook.completed";
+export const HOOK_HEALTH_RECEIPT_VERSION = 1;
+export const HOOK_HEALTH_ERROR_PHASE_LIMIT = 8;
+export function beginHookHealth(input) {
+    return {
+        ...input,
+        coord_root: null,
+        error_phases: [],
+    };
+}
+export function observeHookDebug(state, entry) {
+    if (!state)
+        return;
+    const skipped = safeToken(entry.skipped);
+    if (skipped)
+        state.skipped_reason = skipped;
+    const v3State = safeToken(entry.event_v3_state);
+    if (v3State)
+        state.v3_state = v3State;
+}
+export function observeHookError(state, phase) {
+    if (!state || state.error_phases.length >= HOOK_HEALTH_ERROR_PHASE_LIMIT)
+        return;
+    state.error_phases.push(safeToken(phase) ?? "unknown");
+}
+export function finalizeHookHealth(state, input) {
+    const duration = Math.max(0, Math.floor(input.finished_at_ms - state.started_at_ms));
+    const rssStart = boundedInteger(state.started_rss_bytes);
+    const rssEnd = boundedInteger(input.finished_rss_bytes);
+    const hookName = safeToken(state.event_name) ?? "unknown";
+    return {
+        receipt_version: HOOK_HEALTH_RECEIPT_VERSION,
+        hook_name: hookName,
+        adapter: state.adapter ?? "unknown",
+        outcome: input.faulted
+            ? "faulted"
+            : state.error_phases.length > 0
+                ? "degraded"
+                : state.skipped_reason
+                    ? "skipped"
+                    : "completed",
+        exit_contract: "always-zero",
+        exit_code: 0,
+        duration_ms: duration,
+        payload_bytes: boundedInteger(state.payload_bytes),
+        pid: boundedInteger(input.pid),
+        rss_start_bytes: rssStart,
+        rss_end_bytes: rssEnd,
+        rss_delta_bytes: rssEnd - rssStart,
+        retry_worker: hookName === "runtime-context-retry",
+        error_count: state.error_phases.length,
+        error_phases: [...state.error_phases],
+        ...(state.owner_id ? { owner_id: state.owner_id } : {}),
+        ...(state.skipped_reason ? { skipped_reason: state.skipped_reason } : {}),
+        ...(state.v3_state ? { v3_state: state.v3_state } : {}),
+    };
+}
+export function writeHookHealthCompletion(state, input) {
+    if (!state?.coord_root)
+        return undefined;
+    const receipt = finalizeHookHealth(state, input);
+    try {
+        processLogger(state.coord_root, "agent-hook").info(HOOK_HEALTH_EVENT, { ...receipt });
+    }
+    catch {
+        // Hook health is observer-only. Logging can never change adapter behavior.
+    }
+    return receipt;
+}
+function safeToken(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const normalized = value
+        .trim()
+        .slice(0, 128)
+        .replace(/[^a-zA-Z0-9._:/+-]+/g, "-");
+    return /^[a-zA-Z0-9]/.test(normalized) ? normalized : undefined;
+}
+function boundedInteger(value) {
+    if (!Number.isFinite(value))
+        return 0;
+    return Math.max(0, Math.min(Number.MAX_SAFE_INTEGER, Math.floor(value)));
+}

package/dist/core/resources/contract.d.ts

@@ -0,0 +1,90 @@
+export declare const RESOURCE_SNAPSHOT_SCHEMA_VERSION = 1;
+export declare const RESOURCE_SERVICE_STATUS_SCHEMA_VERSION = 1;
+export type ResourceSupportState = "supported" | "partial" | "unsupported" | "error";
+export interface ResourceProcessSample {
+    pid: number;
+    ppid: number;
+    start_id: string;
+    state: string;
+    name: string;
+    command: string;
+    cpu_percent: number | null;
+    rss_bytes: number;
+    age_seconds: number;
+    owner_kind: "agent" | "service" | "unattributed";
+    owner_id: string | null;
+    owner_root_pid: number | null;
+}
+export interface ResourceProcessGroup {
+    kind: ResourceProcessSample["owner_kind"];
+    id: string;
+    process_count: number;
+    cpu_percent: number | null;
+    rss_bytes: number;
+    root_pids: number[];
+}
+export interface ResourceMachineSample {
+    cpu_percent: number | null;
+    cpu_logical_count: number;
+    load_average: [number, number, number] | null;
+    memory_total_bytes: number | null;
+    memory_available_bytes: number | null;
+    memory_used_bytes: number | null;
+    memory_percent: number | null;
+    swap_total_bytes: number | null;
+    swap_used_bytes: number | null;
+    process_count: number;
+}
+export interface ResourceSnapshot {
+    schema_version: typeof RESOURCE_SNAPSHOT_SCHEMA_VERSION;
+    sampled_at: string;
+    interval_ms: number | null;
+    sample_duration_ms: number;
+    collector_cpu_ms: number;
+    platform: NodeJS.Platform;
+    namespace: "host" | "wsl" | "unknown";
+    support: {
+        state: ResourceSupportState;
+        sampler: "procfs" | "unsupported";
+        reason?: string;
+    };
+    machine: ResourceMachineSample;
+    groups: ResourceProcessGroup[];
+    processes: ResourceProcessSample[];
+    visible_process_count: number;
+    omitted_process_count: number;
+    unattributed_process_count: number;
+}
+export interface ResourceServiceStatusRecord {
+    schema_version: typeof RESOURCE_SERVICE_STATUS_SCHEMA_VERSION;
+    pid: number;
+    start_token?: string;
+    host: string;
+    nonce: string;
+    state: "starting" | "running" | "stopping" | "stopped" | "error";
+    started_at: string;
+    heartbeat_at: string;
+    stopped_at?: string;
+    interval_ms: number;
+    sample_count: number;
+    last_sample_at?: string;
+    last_error_code?: string;
+}
+export interface ResourceServiceStatus {
+    running: boolean;
+    stale: boolean;
+    record?: ResourceServiceStatusRecord;
+    status_path: string;
+    snapshot_path: string;
+}
+export interface ResourceSamplerState {
+    sampled_at_ms: number;
+    cpu_total_ticks: number;
+    cpu_idle_ticks: number;
+    process_ticks: Map<string, number>;
+}
+export interface ResourceSampleResult {
+    snapshot: ResourceSnapshot;
+    state?: ResourceSamplerState;
+}
+//# sourceMappingURL=contract.d.ts.map

package/dist/core/resources/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../../src/core/resources/contract.ts"],"names":[],"mappings":"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"}

package/dist/core/resources/contract.js

@@ -0,0 +1,2 @@
+export const RESOURCE_SNAPSHOT_SCHEMA_VERSION = 1;
+export const RESOURCE_SERVICE_STATUS_SCHEMA_VERSION = 1;

package/dist/core/resources/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./contract.js";
+export * from "./sampler.js";
+export * from "./service.js";
+export * from "./service-status.js";
+export * from "./storage.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/core/resources/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/resources/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,qBAAqB,CAAC;AACpC,cAAc,cAAc,CAAC"}

package/dist/core/resources/index.js

@@ -0,0 +1,5 @@
+export * from "./contract.js";
+export * from "./sampler.js";
+export * from "./service.js";
+export * from "./service-status.js";
+export * from "./storage.js";

package/dist/core/resources/sampler.d.ts

@@ -0,0 +1,27 @@
+import { type ResourceSampleResult, type ResourceSamplerState } from "./contract.js";
+interface ResourceSamplerOptions {
+    procRoot?: string;
+    nowMs?: number;
+    clockTicks?: number;
+    pageSize?: number;
+    services?: readonly {
+        pid: number;
+        id: string;
+    }[];
+    unattributedCpuFloor?: number;
+    unattributedRssFloor?: number;
+    maxProcesses?: number;
+}
+export declare function sampleResources(coordRoot: string, previous?: ResourceSamplerState, options?: ResourceSamplerOptions): ResourceSampleResult;
+export declare function parseLinuxProcessStat(line: string): {
+    pid: number;
+    name: string;
+    state: string;
+    ppid: number;
+    ticks: number;
+    startTicks: number;
+    rssPages: number;
+} | null;
+export declare function redactCommand(args: readonly string[]): string;
+export {};
+//# sourceMappingURL=sampler.d.ts.map

package/dist/core/resources/sampler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampler.d.ts","sourceRoot":"","sources":["../../../src/core/resources/sampler.ts"],"names":[],"mappings":"AAOA,OAAO,EAIL,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EAE1B,MAAM,eAAe,CAAC;AA0BvB,UAAU,sBAAsB;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,SAAS;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAClD,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAKD,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,EACjB,QAAQ,CAAC,EAAE,oBAAoB,EAC/B,OAAO,GAAE,sBAA2B,GACnC,oBAAoB,CAgItB;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG;IACnD,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,IAAI,CA0BP;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAuB7D"}

package/dist/core/resources/sampler.js

@@ -0,0 +1,357 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, readlinkSync } from "node:fs";
+import { cpus, loadavg, platform, release } from "node:os";
+import { basename, join } from "node:path";
+import { performance } from "node:perf_hooks";
+import { parsePidmapRow } from "../agents/state/pidmap.js";
+import { checkPidToken } from "../agents/state/proc-start.js";
+import { RESOURCE_SNAPSHOT_SCHEMA_VERSION, } from "./contract.js";
+const DEFAULT_CLOCK_TICKS = 100;
+const DEFAULT_PAGE_SIZE = 4_096;
+const DEFAULT_UNATTRIBUTED_CPU_FLOOR = 0.5;
+const DEFAULT_UNATTRIBUTED_RSS_FLOOR = 64 * 1_024 * 1_024;
+const DEFAULT_MAX_PROCESSES = 500;
+const MAX_COMMAND_CHARS = 240;
+let cachedClockTicks;
+let cachedPageSize;
+export function sampleResources(coordRoot, previous, options = {}) {
+    const started = performance.now();
+    const cpuBefore = process.cpuUsage();
+    const nowMs = options.nowMs ?? Date.now();
+    const currentPlatform = platform();
+    if (currentPlatform !== "linux") {
+        return {
+            snapshot: unsupportedSnapshot(currentPlatform, nowMs, started, cpuBefore),
+        };
+    }
+    const procRoot = options.procRoot ?? "/proc";
+    if (!existsSync(join(procRoot, "stat"))) {
+        return {
+            snapshot: unsupportedSnapshot(currentPlatform, nowMs, started, cpuBefore, "procfs_unavailable"),
+        };
+    }
+    const clockTicks = options.clockTicks ?? systemClockTicks();
+    const pageSize = options.pageSize ?? systemPageSize();
+    const uptimeSeconds = parseUptime(readFileSync(join(procRoot, "uptime"), "utf8"));
+    const cpu = parseLinuxCpu(readFileSync(join(procRoot, "stat"), "utf8"));
+    const memory = parseMeminfo(readFileSync(join(procRoot, "meminfo"), "utf8"));
+    const readings = readLinuxProcesses(procRoot, clockTicks, pageSize, uptimeSeconds);
+    const anchors = readOwnershipAnchors(coordRoot, readings, options.services ?? []);
+    const byPid = new Map(readings.map((reading) => [reading.pid, reading]));
+    const processTicks = new Map();
+    const intervalMs = previous ? Math.max(0, nowMs - previous.sampled_at_ms) : null;
+    const totalTickDelta = previous ? Math.max(0, cpu.total - previous.cpu_total_ticks) : 0;
+    const logicalCpus = Math.max(1, cpus().length);
+    const processes = readings.map((reading) => {
+        const identity = `${reading.pid}:${reading.startTicks}`;
+        processTicks.set(identity, reading.ticks);
+        const priorTicks = previous?.process_ticks.get(identity);
+        const processDelta = priorTicks === undefined ? undefined : Math.max(0, reading.ticks - priorTicks);
+        const cpuPercent = processDelta === undefined || totalTickDelta <= 0
+            ? null
+            : round1((processDelta / totalTickDelta) * logicalCpus * 100);
+        const ownership = resolveOwnership(reading.pid, byPid, anchors);
+        return {
+            pid: reading.pid,
+            ppid: reading.ppid,
+            start_id: identity,
+            state: reading.state,
+            name: reading.name,
+            command: reading.command,
+            cpu_percent: cpuPercent,
+            rss_bytes: reading.rssBytes,
+            age_seconds: round1(reading.ageSeconds),
+            owner_kind: ownership?.kind ?? "unattributed",
+            owner_id: ownership?.id ?? null,
+            owner_root_pid: ownership?.rootPid ?? null,
+        };
+    });
+    const visible = processes
+        .filter((row) => row.owner_kind !== "unattributed" ||
+        (row.cpu_percent ?? 0) >=
+            (options.unattributedCpuFloor ?? DEFAULT_UNATTRIBUTED_CPU_FLOOR) ||
+        row.rss_bytes >= (options.unattributedRssFloor ?? DEFAULT_UNATTRIBUTED_RSS_FLOOR))
+        .sort(processSort)
+        .slice(0, options.maxProcesses ?? DEFAULT_MAX_PROCESSES);
+    const groups = aggregateGroups(visible);
+    const cpuPercent = previous && totalTickDelta > 0
+        ? round1(((totalTickDelta - Math.max(0, cpu.idle - previous.cpu_idle_ticks)) / totalTickDelta) *
+            100)
+        : null;
+    const memoryTotal = memory.MemTotal ?? null;
+    const memoryAvailable = memory.MemAvailable ?? memory.MemFree ?? null;
+    const memoryUsed = memoryTotal !== null && memoryAvailable !== null
+        ? Math.max(0, memoryTotal - memoryAvailable)
+        : null;
+    const swapTotal = memory.SwapTotal ?? null;
+    const swapFree = memory.SwapFree ?? null;
+    const swapUsed = swapTotal !== null && swapFree !== null ? Math.max(0, swapTotal - swapFree) : null;
+    const collectorCpu = process.cpuUsage(cpuBefore);
+    const snapshot = {
+        schema_version: RESOURCE_SNAPSHOT_SCHEMA_VERSION,
+        sampled_at: new Date(nowMs).toISOString(),
+        interval_ms: intervalMs,
+        sample_duration_ms: round1(performance.now() - started),
+        collector_cpu_ms: round1((collectorCpu.user + collectorCpu.system) / 1_000),
+        platform: currentPlatform,
+        namespace: /microsoft|wsl/i.test(release()) ? "wsl" : "host",
+        support: { state: "supported", sampler: "procfs" },
+        machine: {
+            cpu_percent: cpuPercent,
+            cpu_logical_count: logicalCpus,
+            load_average: loadavg(),
+            memory_total_bytes: memoryTotal,
+            memory_available_bytes: memoryAvailable,
+            memory_used_bytes: memoryUsed,
+            memory_percent: memoryUsed !== null && memoryTotal ? round1((memoryUsed / memoryTotal) * 100) : null,
+            swap_total_bytes: swapTotal,
+            swap_used_bytes: swapUsed,
+            process_count: readings.length,
+        },
+        groups,
+        processes: visible,
+        visible_process_count: visible.length,
+        omitted_process_count: Math.max(0, readings.length - visible.length),
+        unattributed_process_count: visible.filter((row) => row.owner_kind === "unattributed").length,
+    };
+    return {
+        snapshot,
+        state: {
+            sampled_at_ms: nowMs,
+            cpu_total_ticks: cpu.total,
+            cpu_idle_ticks: cpu.idle,
+            process_ticks: processTicks,
+        },
+    };
+}
+export function parseLinuxProcessStat(line) {
+    const open = line.indexOf("(");
+    const close = line.lastIndexOf(")");
+    if (open <= 0 || close <= open)
+        return null;
+    const pid = Number(line.slice(0, open).trim());
+    const fields = line
+        .slice(close + 1)
+        .trim()
+        .split(/\s+/);
+    const state = fields[0] ?? "?";
+    const ppid = Number(fields[1]);
+    const userTicks = Number(fields[11]);
+    const systemTicks = Number(fields[12]);
+    const startTicks = Number(fields[19]);
+    const rssPages = Number(fields[21]);
+    if (![pid, ppid, userTicks, systemTicks, startTicks, rssPages].every(Number.isFinite))
+        return null;
+    return {
+        pid,
+        name: line.slice(open + 1, close),
+        state,
+        ppid,
+        ticks: userTicks + systemTicks,
+        startTicks,
+        rssPages: Math.max(0, rssPages),
+    };
+}
+export function redactCommand(args) {
+    const secretName = /(?:^|[-_])(token|secret|password|passwd|api[-_]?key|authorization)(?:$|[-_])/i;
+    const output = [];
+    let redactNext = false;
+    for (const raw of args) {
+        let value = raw;
+        if (redactNext) {
+            output.push("<redacted>");
+            redactNext = false;
+            continue;
+        }
+        const equals = value.indexOf("=");
+        if (equals > 0 && secretName.test(value.slice(0, equals))) {
+            value = `${value.slice(0, equals + 1)}<redacted>`;
+        }
+        else if (secretName.test(value.replace(/^--?/, ""))) {
+            redactNext = true;
+        }
+        value = value.replace(/(https?:\/\/)[^:@\s/]+:[^@\s/]+@/gi, "$1<redacted>@");
+        output.push(value.replace(/[\r\n\t]+/g, " "));
+    }
+    const joined = output.join(" ").trim();
+    return joined.length <= MAX_COMMAND_CHARS ? joined : `${joined.slice(0, MAX_COMMAND_CHARS - 1)}…`;
+}
+function readLinuxProcesses(procRoot, clockTicks, pageSize, uptimeSeconds) {
+    const rows = [];
+    for (const entry of readdirSync(procRoot, { withFileTypes: true })) {
+        if (!entry.isDirectory() || !/^\d+$/.test(entry.name))
+            continue;
+        const pidRoot = join(procRoot, entry.name);
+        try {
+            const parsed = parseLinuxProcessStat(readFileSync(join(pidRoot, "stat"), "utf8"));
+            if (!parsed)
+                continue;
+            const args = readFileSync(join(pidRoot, "cmdline"), "utf8").split("\0").filter(Boolean);
+            let name = parsed.name;
+            try {
+                name = basename(readlinkSync(join(pidRoot, "exe"))) || name;
+            }
+            catch {
+                // Kernel threads and racing processes may have no readable executable.
+            }
+            rows.push({
+                pid: parsed.pid,
+                ppid: parsed.ppid,
+                state: parsed.state,
+                name,
+                command: redactCommand(args.length > 0 ? args : [parsed.name]),
+                ticks: parsed.ticks,
+                startTicks: parsed.startTicks,
+                rssBytes: parsed.rssPages * pageSize,
+                ageSeconds: Math.max(0, uptimeSeconds - parsed.startTicks / clockTicks),
+            });
+        }
+        catch {
+            // Process exits and permission boundaries are normal during a table scan.
+        }
+    }
+    return rows;
+}
+function readOwnershipAnchors(coordRoot, readings, services) {
+    const byPid = new Set(readings.map((row) => row.pid));
+    const directory = join(coordRoot, ".harnery", "pid-map");
+    const anchors = new Map();
+    if (existsSync(directory)) {
+        for (const entry of readdirSync(directory)) {
+            if (!/^\d+$/.test(entry))
+                continue;
+            const pid = Number(entry);
+            if (!byPid.has(pid))
+                continue;
+            try {
+                const row = parsePidmapRow(readFileSync(join(directory, entry), "utf8"));
+                if (!row.instanceId || checkPidToken(pid, row.startToken) === "mismatch")
+                    continue;
+                anchors.set(pid, { kind: "agent", id: row.instanceId });
+            }
+            catch {
+                // An unreadable or racing row cannot prove ownership.
+            }
+        }
+    }
+    for (const service of services) {
+        if (byPid.has(service.pid) && service.id.trim()) {
+            anchors.set(service.pid, { kind: "service", id: service.id.trim() });
+        }
+    }
+    return anchors;
+}
+function resolveOwnership(pid, byPid, anchors) {
+    const seen = new Set();
+    let cursor = pid;
+    for (let hops = 0; hops < 64 && cursor > 0 && !seen.has(cursor); hops++) {
+        seen.add(cursor);
+        const owner = anchors.get(cursor);
+        if (owner)
+            return { ...owner, rootPid: cursor };
+        cursor = byPid.get(cursor)?.ppid ?? 0;
+    }
+    return undefined;
+}
+function aggregateGroups(processes) {
+    const groups = new Map();
+    for (const row of processes) {
+        const id = row.owner_id ?? "unattributed";
+        const key = `${row.owner_kind}:${id}`;
+        const group = groups.get(key) ?? {
+            kind: row.owner_kind,
+            id,
+            process_count: 0,
+            cpu_percent: null,
+            rss_bytes: 0,
+            root_pids: [],
+        };
+        group.process_count += 1;
+        group.rss_bytes += row.rss_bytes;
+        if (row.cpu_percent !== null)
+            group.cpu_percent = round1((group.cpu_percent ?? 0) + row.cpu_percent);
+        if (row.owner_root_pid !== null && !group.root_pids.includes(row.owner_root_pid)) {
+            group.root_pids.push(row.owner_root_pid);
+        }
+        groups.set(key, group);
+    }
+    return [...groups.values()].sort((left, right) => (right.cpu_percent ?? -1) - (left.cpu_percent ?? -1) ||
+        right.rss_bytes - left.rss_bytes ||
+        left.id.localeCompare(right.id));
+}
+function processSort(left, right) {
+    return ((right.cpu_percent ?? -1) - (left.cpu_percent ?? -1) ||
+        right.rss_bytes - left.rss_bytes ||
+        left.pid - right.pid);
+}
+function parseLinuxCpu(content) {
+    const fields = content.split("\n")[0]?.trim().split(/\s+/).slice(1).map(Number) ?? [];
+    if (fields.length < 4 || fields.some((value) => !Number.isFinite(value))) {
+        throw new Error("procfs_cpu_invalid");
+    }
+    return {
+        total: fields.reduce((sum, value) => sum + value, 0),
+        idle: (fields[3] ?? 0) + (fields[4] ?? 0),
+    };
+}
+function parseMeminfo(content) {
+    const result = {};
+    for (const line of content.split("\n")) {
+        const match = /^([A-Za-z_()]+):\s+(\d+)\s+kB$/.exec(line.trim());
+        if (match)
+            result[match[1]] = Number(match[2]) * 1_024;
+    }
+    return result;
+}
+function parseUptime(content) {
+    const value = Number(content.trim().split(/\s+/, 1)[0]);
+    if (!Number.isFinite(value) || value < 0)
+        throw new Error("procfs_uptime_invalid");
+    return value;
+}
+function systemClockTicks() {
+    cachedClockTicks ??= positiveGetconf("CLK_TCK", DEFAULT_CLOCK_TICKS);
+    return cachedClockTicks;
+}
+function systemPageSize() {
+    cachedPageSize ??= positiveGetconf("PAGESIZE", DEFAULT_PAGE_SIZE);
+    return cachedPageSize;
+}
+function positiveGetconf(key, fallback) {
+    const result = spawnSync("getconf", [key], { encoding: "utf8", timeout: 1_000 });
+    const value = result.status === 0 ? Number(result.stdout.trim()) : Number.NaN;
+    return Number.isFinite(value) && value > 0 ? value : fallback;
+}
+function unsupportedSnapshot(currentPlatform, nowMs, started, cpuBefore, reason = "platform_unsupported") {
+    const collectorCpu = process.cpuUsage(cpuBefore);
+    return {
+        schema_version: RESOURCE_SNAPSHOT_SCHEMA_VERSION,
+        sampled_at: new Date(nowMs).toISOString(),
+        interval_ms: null,
+        sample_duration_ms: round1(performance.now() - started),
+        collector_cpu_ms: round1((collectorCpu.user + collectorCpu.system) / 1_000),
+        platform: currentPlatform,
+        namespace: "unknown",
+        support: { state: "unsupported", sampler: "unsupported", reason },
+        machine: {
+            cpu_percent: null,
+            cpu_logical_count: cpus().length,
+            load_average: null,
+            memory_total_bytes: null,
+            memory_available_bytes: null,
+            memory_used_bytes: null,
+            memory_percent: null,
+            swap_total_bytes: null,
+            swap_used_bytes: null,
+            process_count: 0,
+        },
+        groups: [],
+        processes: [],
+        visible_process_count: 0,
+        omitted_process_count: 0,
+        unattributed_process_count: 0,
+    };
+}
+function round1(value) {
+    return Math.round(value * 10) / 10;
+}

package/dist/core/resources/service-status.d.ts

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

package/dist/core/resources/service-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-status.d.ts","sourceRoot":"","sources":["../../../src/core/resources/service-status.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,qBAAqB,EAE3B,MAAM,eAAe,CAAC;AAKvB,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,MAAM,EACjB,KAAK,SAAa,GACjB,qBAAqB,CA0BvB"}