harnery 0.45.1 → 0.46.0

package/dist/core/agents/state/parent-reference.js

@@ -0,0 +1,119 @@
+import { readCoordinationViewV3 } from "../../events/v3/coordination-view.js";
+import { liveInstanceIdV3, nativeInstanceIdV3 } from "../../events/v3/live-route-observer.js";
+import { readNativeParentReference, } from "../../hooks/adapter/native-parent.js";
+import { resolveName } from "./names.js";
+/** Display/recipient evidence only. Never use native evidence as a claim or lifecycle waiver. */
+export function resolveAgentParentReference(coordRoot, child, options = {}) {
+    try {
+        const view = options.view ?? readCoordinationViewV3(coordRoot);
+        if (!view.source_complete || !view.authority_safe)
+            return unknown("parent_authority_unsafe");
+        if (child.generation_id &&
+            child.v3_generation_id &&
+            child.generation_id !== child.v3_generation_id) {
+            return unknown("child_generation_mismatch");
+        }
+        const instance = liveInstanceIdV3(child.instance_id);
+        const generationId = child.generation_id ?? child.v3_generation_id;
+        const generations = [
+            ...Object.values(view.instances),
+            ...Object.values(view.terminal_generations),
+        ];
+        const generation = generationId
+            ? generations.find((row) => row.generation_id === generationId && row.instance_id === instance)
+            : view.instances[instance];
+        if (!generation)
+            return unknown("child_generation_unavailable");
+        if (!safe(view, generation))
+            return unknown("child_authority_unsafe");
+        const canonical = generation.parent_generation_id
+            ? generations.find((row) => row.generation_id === generation.parent_generation_id)
+            : undefined;
+        if (generation.parent_generation_id && !canonical)
+            return unknown("parent_generation_unavailable");
+        if (canonical && cyclic(generations, generation)) {
+            return { state: "conflict", reason: "parent_lineage_cycle" };
+        }
+        const adapter = generation.runtime_attestation.adapter;
+        const platform = adapter.state === "observed" ? adapter.value.id : child.platform;
+        const nativeId = child.native_session_id ?? nativeInstanceIdV3(instance);
+        const native = platform === "codex" && liveInstanceIdV3(nativeId) === instance
+            ? (options.readNativeParent ?? readNativeParentReference)({
+                adapter: platform,
+                native_session_id: nativeId,
+            })
+            : { state: "unknown", reason: "native_child_identity_unavailable" };
+        if (canonical) {
+            if (native.state === "none" ||
+                (native.state === "observed" &&
+                    liveInstanceIdV3(native.parent_session_id) !== canonical.instance_id)) {
+                return { state: "conflict", reason: "parent_sources_disagree" };
+            }
+            return reference(coordRoot, view, canonical.instance_id, canonical, "v3-session-link");
+        }
+        if (native.state === "observed") {
+            const parentInstance = liveInstanceIdV3(native.parent_session_id);
+            if (parentInstance === instance)
+                return { state: "conflict", reason: "parent_self_reference" };
+            const parent = recipientGeneration(view, parentInstance);
+            if (parent && cyclic(generations, generation, parent)) {
+                return { state: "conflict", reason: "parent_lineage_cycle" };
+            }
+            return reference(coordRoot, view, parentInstance, parent, "native-session-metadata", native.source_witness);
+        }
+        return { state: native.state, reason: native.reason };
+    }
+    catch {
+        return unknown("parent_reference_unavailable");
+    }
+}
+function reference(root, view, instance, parent, source, witness) {
+    const native = nativeInstanceIdV3(instance);
+    const name = resolveName(root, native)?.name ?? null;
+    const recipient = recipientGeneration(view, instance);
+    return {
+        state: "verified",
+        relationship: source === "v3-session-link" ? "delegated-child" : "native-child",
+        parent_instance_id: native,
+        parent_v3_instance_id: instance,
+        parent_generation_id: parent?.generation_id ?? null,
+        parent_session_id: parent?.session_id ?? null,
+        parent_name: name,
+        source,
+        ...(witness ? { source_witness: witness } : {}),
+        addressable: Boolean(parent && recipient?.generation_id === parent.generation_id && safe(view, parent) && name),
+    };
+}
+function recipientGeneration(view, instance) {
+    return (view.instances[instance] ??
+        Object.values(view.terminal_generations)
+            .filter((row) => row.instance_id === instance)
+            .sort((a, b) => b.source_position.segment_ordinal - a.source_position.segment_ordinal ||
+            b.source_position.byte_offset - a.source_position.byte_offset)[0]);
+}
+function safe(view, generation) {
+    return !(view.diagnostics_by_generation[generation.generation_id] ?? []).some((d) => d.authority_blocking);
+}
+function cyclic(generations, child, first) {
+    const seen = new Set([child.generation_id]);
+    let cursor = first ?? child;
+    for (let depth = 0; depth <= generations.length; depth++) {
+        if (cursor !== child) {
+            if (seen.has(cursor.generation_id) || cursor.instance_id === child.instance_id)
+                return true;
+            seen.add(cursor.generation_id);
+        }
+        if (!cursor.parent_generation_id)
+            return false;
+        const next = generations.find((g) => g.generation_id === cursor.parent_generation_id);
+        if (!next)
+            return false;
+        if (seen.has(next.generation_id))
+            return true;
+        cursor = next;
+    }
+    return true;
+}
+function unknown(reason) {
+    return { state: "unknown", reason };
+}

package/dist/core/agents/state/pidmap.js

@@ -15,7 +15,7 @@
  */
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
 import { dirname, join } from "node:path";
-import { checkPidToken, processStartToken } from "./proc-start.js";
+import { processStartToken, verifyProcessGeneration } from "./proc-start.js";
 /**
  * Row count that triggers a dead-row sweep on the next write.
  *
@@ -44,7 +44,7 @@ export function parsePidmapRow(row) {
 function rowStillNamesItsProcess(pid, startToken) {
     if (!pidIsAlive(pid))
         return false;
-    return checkPidToken(pid, startToken) !== "mismatch";
+    return verifyProcessGeneration(pid, startToken) !== "different";
 }
 function atomicWrite(path, content) {
     mkdirSync(dirname(path), { recursive: true });

package/dist/core/agents/state/proc-start.d.ts

@@ -30,9 +30,8 @@
  *    through the caller's locale and timezone, so both are pinned; without that,
  *    two callers reading the same live process disagree.
  */
-import { signalProcessWithHandle } from "./process-handle.js";
 /** Which probe answers "when did this process start?" on this machine. */
-export type StartTokenProbe = "procfs" | "ps" | "windows";
+export type StartTokenProbe = "procfs" | "ps";
 /**
  * Which probe this machine uses, decided once.
  *
@@ -50,7 +49,7 @@ export declare function resetStartTokenCaches(): void;
  * than by splitting the whole line, because comm is the executable name in
  * parentheses and may itself contain spaces and parens. The boot segment is
  * dropped rather than faked when the kernel will not name its boot, which
- * yields the pre-boot-id shape that `tokensAgree` still accepts.
+ * yields the pre-boot-id shape that `verifyProcessGeneration` compares by ticks.
  */
 export declare function procfsStartToken(pid: number): string | null;
 /**
@@ -71,43 +70,33 @@ export declare function psStartToken(pid: number, run?: (pid: number) => {
 export declare function processStartToken(pid: number): string | null;
 export type ProcessGenerationVerdict = "same" | "different" | "unknown";
 type ReadProcessStartToken = (pid: number) => string | null;
-/** A missing or unreadable token never establishes process identity. */
+/**
+ * Does `pid` still name the run that wrote `recordedToken`?
+ *
+ * - `"same"`: both tokens present and equal.
+ * - `"different"`: the pid was recycled. A liveness check cannot see this,
+ *   because a recycled pid is alive.
+ * - `"unknown"`: a token is missing, malformed, or unreadable. Never treat
+ *   this as proof of identity.
+ *
+ * A Linux token written without a boot segment cannot identify a run across
+ * reboots, so it is compared on its tick count: a different count proves a
+ * different run, and an equal count stays unknown.
+ */
 export declare function verifyProcessGeneration(pid: number, recordedToken: string | null | undefined, readToken?: ReadProcessStartToken): ProcessGenerationVerdict;
 export interface ProcessGenerationSignalDependencies {
     readToken?: ReadProcessStartToken;
-    signalProcess?: typeof signalProcessWithHandle;
+    kill?: (pid: number, signal: NodeJS.Signals | number) => unknown;
 }
 /**
- * Observations may refuse a signal, but only the retained native process handle
- * can authorize it. No numeric-PID effect follows the preliminary token read.
+ * Recheck the process generation immediately before sending the signal.
+ *
+ * The process can still exit and its PID can be reused between the token read
+ * and the signal. Eliminating that race requires a generation-bound OS handle.
  */
 export declare function signalIfSameGeneration(pid: number, recordedToken: string | null | undefined, signal: NodeJS.Signals | number, dependencies?: ProcessGenerationSignalDependencies): {
     sent: boolean;
     verdict: ProcessGenerationVerdict;
 };
-/**
- * Do two tokens describe the same run?
- *
- * Equality, plus one concession: a row written before tokens carried a boot
- * segment recorded the tick count alone, so it is compared on the part it
- * actually recorded. Refusing that would call every pre-upgrade row a recycled
- * pid and prune a working machine's live rows the first time the new code ran.
- * Such a row loses its reboot protection until the next write rewrites it,
- * which is a strictly better position than the one it came from.
- */
-export declare function tokensAgree(recorded: string, current: string): boolean;
-/**
- * Does `pid` still name the process a row recorded?
- *
- * Three answers, and the difference between the last two matters:
- *
- * - `"match"` — recorded token, current token, same run. The row is trustworthy.
- * - `"mismatch"` — both present and different. The pid was recycled. This is
- *   the case a liveness check cannot see, because a recycled pid is alive.
- * - `"unverified"` — no recorded token (a row written before tokens existed) or
- *   no current one (an unsupported platform). Callers treat this the way they
- *   treated every row previously: trust it if the pid is alive.
- */
-export declare function checkPidToken(pid: number, recorded: string | undefined): "match" | "mismatch" | "unverified";
 export {};
 //# sourceMappingURL=proc-start.d.ts.map

package/dist/core/agents/state/proc-start.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"proc-start.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/state/proc-start.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAKH,OAAO,EAAE,uBAAuB,EAA4B,MAAM,qBAAqB,CAAC;AAExF,0EAA0E;AAC1E,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,IAAI,GAAG,SAAS,CAAC;AAc1D;;;;;;GAMG;AACH,wBAAgB,eAAe,IAAI,eAAe,CAQjD;AAyBD,uDAAuD;AACvD,wBAAgB,qBAAqB,IAAI,IAAI,CAG5C;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAc3D;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,MAAM,EACX,GAAG,GAAE,CAAC,GAAG,EAAE,MAAM,KAAK;IAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAiB,GAC7E,MAAM,GAAG,IAAI,CAUf;AAWD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQ5D;AAED,MAAM,MAAM,wBAAwB,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,CAAC;AAExE,KAAK,qBAAqB,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;AAE5D,wEAAwE;AACxE,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,MAAM,EACX,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACxC,SAAS,GAAE,qBAAyC,GACnD,wBAAwB,CAkB1B;AAED,MAAM,WAAW,mCAAmC;IAClD,SAAS,CAAC,EAAE,qBAAqB,CAAC;IAClC,aAAa,CAAC,EAAE,OAAO,uBAAuB,CAAC;CAChD;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,MAAM,EACX,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACxC,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,MAAM,EAC/B,YAAY,GAAE,mCAAwC,GACrD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,wBAAwB,CAAA;CAAE,CAQtD;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAQtE;AAOD;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC3B,OAAO,GAAG,UAAU,GAAG,YAAY,CAKrC"}
+{"version":3,"file":"proc-start.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/state/proc-start.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAMH,0EAA0E;AAC1E,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,IAAI,CAAC;AAc9C;;;;;;GAMG;AACH,wBAAgB,eAAe,IAAI,eAAe,CAOjD;AAyBD,uDAAuD;AACvD,wBAAgB,qBAAqB,IAAI,IAAI,CAG5C;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAc3D;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,MAAM,EACX,GAAG,GAAE,CAAC,GAAG,EAAE,MAAM,KAAK;IAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAiB,GAC7E,MAAM,GAAG,IAAI,CAUf;AAWD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAG5D;AAED,MAAM,MAAM,wBAAwB,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,CAAC;AAExE,KAAK,qBAAqB,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;AAE5D;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,MAAM,EACX,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACxC,SAAS,GAAE,qBAAyC,GACnD,wBAAwB,CAuB1B;AAOD,MAAM,WAAW,mCAAmC;IAClD,SAAS,CAAC,EAAE,qBAAqB,CAAC;IAClC,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,MAAM,KAAK,OAAO,CAAC;CAClE;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,MAAM,EACX,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACxC,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,MAAM,EAC/B,YAAY,GAAE,mCAAwC,GACrD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,wBAAwB,CAAA;CAAE,CAUtD"}

package/dist/core/agents/state/proc-start.js

@@ -33,7 +33,6 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { coordEnv } from "../../../lib/env.js";
-import { signalProcessWithHandle, windowsProcessStartToken } from "./process-handle.js";
 /**
  * The `ps` probe is text formatted by `strftime("%c", localtime(...))`, so its
  * output moves with `TZ` and `LC_TIME`. A hook running under `LC_ALL=C` (git
@@ -55,8 +54,6 @@ export function startTokenProbe() {
     const override = coordEnv("PID_PROBE");
     if (override === "procfs" || override === "ps")
         return override;
-    if (process.platform === "win32")
-        return "windows";
     if (cachedProbe === undefined) {
         cachedProbe = existsSync("/proc/self/stat") ? "procfs" : "ps";
     }
@@ -98,7 +95,7 @@ export function resetStartTokenCaches() {
  * than by splitting the whole line, because comm is the executable name in
  * parentheses and may itself contain spaces and parens. The boot segment is
  * dropped rather than faked when the kernel will not name its boot, which
- * yields the pre-boot-id shape that `tokensAgree` still accepts.
+ * yields the pre-boot-id shape that `verifyProcessGeneration` compares by ticks.
  */
 export function procfsStartToken(pid) {
     let stat;
@@ -152,93 +149,63 @@ function defaultPsRun(pid) {
 export function processStartToken(pid) {
     if (!Number.isFinite(pid) || pid <= 0)
         return null;
-    const probe = startTokenProbe();
-    return probe === "windows"
-        ? windowsProcessStartToken(pid)
-        : probe === "procfs"
-            ? procfsStartToken(pid)
-            : psStartToken(pid);
+    return startTokenProbe() === "procfs" ? procfsStartToken(pid) : psStartToken(pid);
 }
-/** A missing or unreadable token never establishes process identity. */
+/**
+ * Does `pid` still name the run that wrote `recordedToken`?
+ *
+ * - `"same"`: both tokens present and equal.
+ * - `"different"`: the pid was recycled. A liveness check cannot see this,
+ *   because a recycled pid is alive.
+ * - `"unknown"`: a token is missing, malformed, or unreadable. Never treat
+ *   this as proof of identity.
+ *
+ * A Linux token written without a boot segment cannot identify a run across
+ * reboots, so it is compared on its tick count: a different count proves a
+ * different run, and an equal count stays unknown.
+ */
 export function verifyProcessGeneration(pid, recordedToken, readToken = processStartToken) {
     if (!Number.isInteger(pid) ||
         pid <= 0 ||
         typeof recordedToken !== "string" ||
         !recordedToken.trim())
         return "unknown";
-    // A bootless Linux token cannot identify a process across machine boots.
-    if (/^l\d+$/.test(recordedToken))
-        return "unknown";
+    let currentToken;
     try {
-        const currentToken = readToken(pid);
-        if (typeof currentToken !== "string" || !currentToken.trim())
-            return "unknown";
-        if (/^l\d+$/.test(currentToken))
-            return "unknown";
-        return currentToken === recordedToken ? "same" : "different";
+        currentToken = readToken(pid);
     }
     catch {
         return "unknown";
     }
+    if (typeof currentToken !== "string" || !currentToken.trim())
+        return "unknown";
+    const bootless = (token) => /^l\d+$/.test(token);
+    if (recordedToken[0] === "l" &&
+        currentToken[0] === "l" &&
+        (bootless(recordedToken) || bootless(currentToken)))
+        return ticksOf(recordedToken) === ticksOf(currentToken) ? "unknown" : "different";
+    return currentToken === recordedToken ? "same" : "different";
+}
+function ticksOf(token) {
+    const dot = token.indexOf(".");
+    return dot === -1 ? token.slice(1) : token.slice(dot + 1);
 }
 /**
- * Observations may refuse a signal, but only the retained native process handle
- * can authorize it. No numeric-PID effect follows the preliminary token read.
+ * Recheck the process generation immediately before sending the signal.
+ *
+ * The process can still exit and its PID can be reused between the token read
+ * and the signal. Eliminating that race requires a generation-bound OS handle.
  */
 export function signalIfSameGeneration(pid, recordedToken, signal, dependencies = {}) {
+    const kill = dependencies.kill ?? process.kill;
     const verdict = verifyProcessGeneration(pid, recordedToken, dependencies.readToken);
     if (verdict !== "same")
         return { sent: false, verdict };
     try {
-        return (dependencies.signalProcess ?? signalProcessWithHandle)(pid, recordedToken, signal);
+        kill(pid, signal);
+        return { sent: true, verdict };
     }
     catch {
-        return { sent: false, verdict: "unknown" };
+        return { sent: false, verdict };
     }
 }
-/**
- * Do two tokens describe the same run?
- *
- * Equality, plus one concession: a row written before tokens carried a boot
- * segment recorded the tick count alone, so it is compared on the part it
- * actually recorded. Refusing that would call every pre-upgrade row a recycled
- * pid and prune a working machine's live rows the first time the new code ran.
- * Such a row loses its reboot protection until the next write rewrites it,
- * which is a strictly better position than the one it came from.
- */
-export function tokensAgree(recorded, current) {
-    if (recorded === current)
-        return true;
-    // Only the Linux form has a boot segment to disagree about, and only when
-    // exactly one side carries one is this a shape difference rather than two
-    // genuinely different start instants.
-    if (recorded[0] !== "l" || current[0] !== "l")
-        return false;
-    if (recorded.includes(".") === current.includes("."))
-        return false;
-    return ticksOf(recorded) === ticksOf(current);
-}
-function ticksOf(token) {
-    const dot = token.indexOf(".");
-    return dot === -1 ? token.slice(1) : token.slice(dot + 1);
-}
-/**
- * Does `pid` still name the process a row recorded?
- *
- * Three answers, and the difference between the last two matters:
- *
- * - `"match"` — recorded token, current token, same run. The row is trustworthy.
- * - `"mismatch"` — both present and different. The pid was recycled. This is
- *   the case a liveness check cannot see, because a recycled pid is alive.
- * - `"unverified"` — no recorded token (a row written before tokens existed) or
- *   no current one (an unsupported platform). Callers treat this the way they
- *   treated every row previously: trust it if the pid is alive.
- */
-export function checkPidToken(pid, recorded) {
-    if (!recorded)
-        return "unverified";
-    const current = processStartToken(pid);
-    if (!current)
-        return "unverified";
-    return tokensAgree(recorded, current) ? "match" : "mismatch";
-}

package/dist/core/agents/state/service-process.d.ts

@@ -0,0 +1,61 @@
+import { type ProcessGenerationSignalDependencies, type ProcessGenerationVerdict } from "./proc-start.js";
+export interface ServiceProcessDependencies extends ProcessGenerationSignalDependencies {
+    /** Throws ESRCH, or returns false, when the process is gone. */
+    probePid?: (pid: number) => unknown;
+}
+export type ServiceLiveness = "running" | "stopped" | "unknown";
+export interface ServiceProcessOwner {
+    pid: number;
+    host: string;
+    start_token?: string;
+    state?: string;
+}
+/**
+ * A stale heartbeat does not prove that a process has exited. Another host, a
+ * probe error other than ESRCH, or an unverifiable token answers unknown. A
+ * recorded `stopped` state counts only while the generation still matches.
+ */
+export declare function observeServiceProcess(owner: ServiceProcessOwner, dependencies?: ServiceProcessDependencies): {
+    generation: ProcessGenerationVerdict;
+    liveness: ServiceLiveness;
+};
+/** Refuse a start while another owner runs or cannot be identified. */
+export declare function serviceStartRefusal(label: string, stopCommand: string, pid: number | undefined, liveness: ServiceLiveness): Error;
+export interface ServiceLease {
+    pid: number;
+    start_token?: string;
+    host: string;
+    nonce: string;
+    created_at?: string;
+}
+export declare function readServiceLease(path: string): ServiceLease | undefined;
+/** An absent lease is stopped; an unreadable one cannot be identified. */
+export declare function serviceLeaseOwner(path: string): {
+    lease?: ServiceLease;
+    liveness: ServiceLiveness;
+};
+/**
+ * Take the singleton lease with an exclusive create. A lease whose owner is
+ * proven stopped is replaced; any other owner refuses the start.
+ */
+export declare function acquireServiceLease(path: string, refuse: (pid: number | undefined, liveness: ServiceLiveness) => Error, fields?: Record<string, unknown>): {
+    nonce: string;
+    release: () => void;
+};
+export interface ServiceStopFields {
+    signal_sent: boolean;
+    signal_verdict: ProcessGenerationVerdict;
+}
+/**
+ * Write the durable stop request, then SIGTERM the owner `status` observed as
+ * running on this host, after a fresh generation check. The request stays for
+ * the daemon either way; `read` reports the state afterward.
+ */
+export declare function requestServiceStop<S extends {
+    liveness: ServiceLiveness;
+    generation: ProcessGenerationVerdict;
+    record?: ServiceProcessOwner;
+}>(status: S, read: () => S, stopPath: string, dependencies?: ServiceProcessDependencies, options?: {
+    signal?: boolean;
+}): S & ServiceStopFields;
+//# sourceMappingURL=service-process.d.ts.map

package/dist/core/agents/state/service-process.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-process.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/state/service-process.ts"],"names":[],"mappings":"AAmBA,OAAO,EACL,KAAK,mCAAmC,EACxC,KAAK,wBAAwB,EAI9B,MAAM,iBAAiB,CAAC;AAEzB,MAAM,WAAW,0BAA2B,SAAQ,mCAAmC;IACrF,gEAAgE;IAChE,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;CACrC;AAED,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAEhE,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,mBAAmB,EAC1B,YAAY,GAAE,0BAA+B,GAC5C;IAAE,UAAU,EAAE,wBAAwB,CAAC;IAAC,QAAQ,EAAE,eAAe,CAAA;CAAE,CAuBrE;AAED,uEAAuE;AACvE,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,QAAQ,EAAE,eAAe,GACxB,KAAK,CAMP;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAmBvE;AAED,0EAA0E;AAC1E,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG;IAC/C,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,QAAQ,EAAE,eAAe,CAAC;CAC3B,CAIA;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,eAAe,KAAK,KAAK,EACrE,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACnC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,IAAI,CAAA;CAAE,CA0CxC;AAED,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,OAAO,CAAC;IACrB,cAAc,EAAE,wBAAwB,CAAC;CAC1C;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,CAAC,SAAS;IACR,QAAQ,EAAE,eAAe,CAAC;IAC1B,UAAU,EAAE,wBAAwB,CAAC;IACrC,MAAM,CAAC,EAAE,mBAAmB,CAAC;CAC9B,EAED,MAAM,EAAE,CAAC,EACT,IAAI,EAAE,MAAM,CAAC,EACb,QAAQ,EAAE,MAAM,EAChB,YAAY,GAAE,0BAA+B,EAC7C,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GACjC,CAAC,GAAG,iBAAiB,CAevB"}

package/dist/core/agents/state/service-process.js

@@ -0,0 +1,143 @@
+/**
+ * One owner check for every singleton background service (governor, local
+ * supervisor, legacy resource observer): is the recorded process still the
+ * run that wrote the record, and how is a stop requested?
+ */
+import { randomUUID } from "node:crypto";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, unlinkSync, writeFileSync, } from "node:fs";
+import { hostname } from "node:os";
+import { dirname } from "node:path";
+import { writePrivateJsonAtomic } from "../../storage/atomic-json.js";
+import { stateDirMode, stateFileMode } from "../../storage/modes.js";
+import { processStartToken, signalIfSameGeneration, verifyProcessGeneration, } from "./proc-start.js";
+/**
+ * A stale heartbeat does not prove that a process has exited. Another host, a
+ * probe error other than ESRCH, or an unverifiable token answers unknown. A
+ * recorded `stopped` state counts only while the generation still matches.
+ */
+export function observeServiceProcess(owner, dependencies = {}) {
+    if (owner.host !== hostname())
+        return { generation: "unknown", liveness: "unknown" };
+    try {
+        if ((dependencies.probePid ?? ((pid) => process.kill(pid, 0)))(owner.pid) === false)
+            return { generation: "unknown", liveness: "stopped" };
+    }
+    catch (error) {
+        return {
+            generation: "unknown",
+            liveness: error.code === "ESRCH" ? "stopped" : "unknown",
+        };
+    }
+    const generation = verifyProcessGeneration(owner.pid, owner.start_token, dependencies.readToken);
+    return {
+        generation,
+        liveness: generation === "same"
+            ? owner.state === "stopped"
+                ? "stopped"
+                : "running"
+            : generation === "different"
+                ? "stopped"
+                : "unknown",
+    };
+}
+/** Refuse a start while another owner runs or cannot be identified. */
+export function serviceStartRefusal(label, stopCommand, pid, liveness) {
+    return new Error(liveness === "running"
+        ? `${label} is already running under pid ${pid}`
+        : `${label} process generation is unknown${pid ? ` for pid ${pid}` : ""}; run \`${stopCommand}\` to write a durable stop request before starting it again`);
+}
+export function readServiceLease(path) {
+    try {
+        const value = JSON.parse(readFileSync(path, "utf8"));
+        if (!Number.isSafeInteger(value.pid) ||
+            (value.pid ?? 0) <= 0 ||
+            typeof value.host !== "string" ||
+            !value.host ||
+            typeof value.nonce !== "string" ||
+            !value.nonce)
+            return undefined;
+        return {
+            ...value,
+            start_token: typeof value.start_token === "string" ? value.start_token : undefined,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** An absent lease is stopped; an unreadable one cannot be identified. */
+export function serviceLeaseOwner(path) {
+    if (!existsSync(path))
+        return { liveness: "stopped" };
+    const lease = readServiceLease(path);
+    return { lease, liveness: lease ? observeServiceProcess(lease).liveness : "unknown" };
+}
+/**
+ * Take the singleton lease with an exclusive create. A lease whose owner is
+ * proven stopped is replaced; any other owner refuses the start.
+ */
+export function acquireServiceLease(path, refuse, fields = {}) {
+    mkdirSync(dirname(path), { recursive: true, mode: stateDirMode() });
+    for (let attempt = 0; attempt < 2; attempt++) {
+        const startToken = processStartToken(process.pid);
+        const lease = {
+            ...fields,
+            pid: process.pid,
+            ...(startToken ? { start_token: startToken } : {}),
+            host: hostname(),
+            nonce: randomUUID(),
+            created_at: new Date().toISOString(),
+        };
+        try {
+            const fd = openSync(path, "wx", stateFileMode());
+            try {
+                writeFileSync(fd, `${JSON.stringify(lease)}\n`, "utf8");
+            }
+            finally {
+                closeSync(fd);
+            }
+            return {
+                nonce: lease.nonce,
+                release: () => {
+                    if (readServiceLease(path)?.nonce !== lease.nonce)
+                        return;
+                    try {
+                        unlinkSync(path);
+                    }
+                    catch {
+                        // A missing lease is already released.
+                    }
+                },
+            };
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            const owner = serviceLeaseOwner(path);
+            if (owner.liveness !== "stopped")
+                throw refuse(owner.lease?.pid, owner.liveness);
+            try {
+                unlinkSync(path);
+            }
+            catch {
+                // A concurrent starter may have replaced or removed the stale lease.
+            }
+        }
+    }
+    throw new Error(`could not acquire the singleton lease at ${path}`);
+}
+/**
+ * Write the durable stop request, then SIGTERM the owner `status` observed as
+ * running on this host, after a fresh generation check. The request stays for
+ * the daemon either way; `read` reports the state afterward.
+ */
+export function requestServiceStop(status, read, stopPath, dependencies = {}, options = {}) {
+    writePrivateJsonAtomic(stopPath, {
+        requested_at: new Date().toISOString(),
+        requested_by_pid: process.pid,
+    });
+    const signal = options.signal !== false && status.liveness === "running" && status.record?.host === hostname()
+        ? signalIfSameGeneration(status.record.pid, status.record.start_token, "SIGTERM", dependencies)
+        : { sent: false, verdict: status.generation };
+    return { ...read(), signal_sent: signal.sent, signal_verdict: signal.verdict };
+}

package/dist/core/config.d.ts

@@ -152,6 +152,45 @@ export declare function endOfTurnStatusCommand(coordRoot?: string | null): strin
  * `coordRoot` is resolved via `findCoordRoot()` when not passed.
  */
 export declare function ripgrepAutoInstall(coordRoot?: string | null): boolean;
+/** Wait before queueing while Linux memory pressure is high (PSI `full avg10`). */
+export interface AdmissionPressureConfig {
+    psi_full_avg10: number;
+    max_wait_seconds: number;
+}
+/** Per-resource defaults for `admission run`; command-line flags win. */
+export interface AdmissionResourceConfig {
+    capacity?: number;
+    timeout_minutes?: number;
+    defer_on_pressure?: AdmissionPressureConfig;
+}
+export interface AdmissionProjectConfig {
+    resources: Record<string, AdmissionResourceConfig>;
+    /** Present when the agent hook should wrap heavy shell commands in a slot. */
+    guard?: {
+        resource: string;
+    };
+}
+/**
+ * Admission settings from `.harnery/config.jsonc`:
+ *
+ * ```jsonc
+ * "admission": {
+ *   "resources": {
+ *     "build": {
+ *       "capacity": 2,
+ *       "timeout_minutes": 30,
+ *       "defer_on_pressure": { "psi_full_avg10": 40, "max_wait_seconds": 300 }
+ *     }
+ *   },
+ *   "guard": { "resource": "build" }
+ * }
+ * ```
+ *
+ * Project config only, like other machine-shaping policy. Malformed values are
+ * dropped one by one rather than rejecting the whole block. Undefined when the
+ * project declares no admission settings.
+ */
+export declare function readAdmissionConfig(coordRoot?: string | null): AdmissionProjectConfig | undefined;
 /**
  * Whether this repo pins workflow runs to subscription billing:
  * `.harnery/config.jsonc` `{ "workflow": { "subscriptionOnly": true } }`.