harnery 0.42.0 → 0.44.0

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

@@ -151,6 +151,47 @@ export function processStartToken(pid) {
         return null;
     return startTokenProbe() === "procfs" ? procfsStartToken(pid) : psStartToken(pid);
 }
+/** A missing or unreadable token never establishes process identity. */
+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";
+    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";
+    }
+    catch {
+        return "unknown";
+    }
+}
+/**
+ * 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 {
+        kill(pid, signal);
+        return { sent: true, verdict };
+    }
+    catch {
+        return { sent: false, verdict };
+    }
+}
 /**
  * Do two tokens describe the same run?
  *

package/dist/core/agents/state/stale-sweep.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stale-sweep.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/state/stale-sweep.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAkEH,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG;IAC7C,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,qBAAqB,EAAE,MAAM,CAAC;CAC/B,CAyJA"}
+{"version":3,"file":"stale-sweep.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/state/stale-sweep.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAyIH,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG;IAC7C,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,qBAAqB,EAAE,MAAM,CAAC;CAC/B,CAuPA"}

package/dist/core/agents/state/stale-sweep.js

@@ -9,12 +9,15 @@
  * HARNERY_AGENT_COORD_FRESHNESS env var or `.harnery/config.jsonc`
  * `coord.freshness_seconds` (see `coordFreshnessSeconds`).
  */
-import { existsSync, readdirSync, readFileSync, statSync, unlinkSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, lstatSync, readdirSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
 import { coordFreshnessSeconds } from "../../config.js";
 import { eventAdapterIdV3FromPlatform } from "../../events/v3/adapter-id.js";
+import { withGenerationCustodyV3 } from "../../events/v3/generation-custody.js";
+import { liveInstanceIdV3 } from "../../events/v3/live-routing.js";
 import { writeProducerDiagnosticV3 } from "../../events/v3/producers/intake.js";
 import { recordLiveSweepObservationV3 } from "../live-lifecycle-v3.js";
+import { captureFileRevision, deleteFileIfUnchanged, recoverInterruptedFileDeletions, } from "./unchanged-file.js";
 /** platform → adapter, for the swept-event envelope (mirrors heartbeat-writer's adapterOf). */
 /**
  * Record the sweep before deleting disposable cache state.
@@ -25,13 +28,14 @@ import { recordLiveSweepObservationV3 } from "../live-lifecycle-v3.js";
  * diagnostics spool instead. If neither durable record can be written, fail
  * closed and keep the file.
  */
-function emitSwept(coordRoot, instanceId, adapter, sessionId, reason, ageSecs) {
+function emitSwept(coordRoot, instanceId, adapter, sessionId, expectedGenerationId, reason, ageSecs) {
     try {
         recordLiveSweepObservationV3({
             coordRoot,
             owner: instanceId,
             nativeSessionId: sessionId,
             adapter,
+            expectedGenerationId,
             observation: reason === "stale"
                 ? "stale_heartbeat"
                 : reason === "unparseable"
@@ -53,14 +57,58 @@ function emitSwept(coordRoot, instanceId, adapter, sessionId, reason, ageSecs) {
         }));
     }
 }
-/** File mtime in epoch-seconds, or +Infinity if it can't be read (treat as fresh → don't reap). */
-function mtimeSecs(path) {
+/** Any retained or unreadable owner row prevents dependent cache deletion. */
+function retainsHeartbeat(coordRoot, activeDir, owner, uncertainOwners) {
+    if (uncertainOwners.has("*") || uncertainOwners.has(owner))
+        return true;
+    if (!/^[A-Za-z0-9_-]{1,128}$/.test(owner))
+        return true;
+    const heartbeat = join(activeDir, `${owner}.json`);
     try {
-        return Math.floor(statSync(path).mtimeMs / 1000);
+        lstatSync(heartbeat);
+        return true;
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            return true;
+    }
+    try {
+        if (!lstatSync(activeDir).isDirectory())
+            return true;
+    }
+    catch (error) {
+        return error.code !== "ENOENT";
+    }
+    // Callers hold this owner's custody. A sweeper that died after the initial
+    // directory scan may have left its heartbeat hidden under a private pin.
+    for (const recovery of recoverInterruptedFileDeletions(activeDir, (source) => source === heartbeat)) {
+        if (recovery.sourcePath && recovery.sourcePath !== heartbeat)
+            continue;
+        if (recovery.state !== "restored") {
+            uncertainOwners.add(recovery.sourcePath ? owner : "*");
+            recordCleanupFailure(coordRoot, recovery.sourcePath ?? activeDir, recovery);
+        }
+        return true;
+    }
+    return false;
+}
+function recordCleanupFailure(coordRoot, sourcePath, result) {
+    if (result.state !== "error" &&
+        result.state !== "recovery-required" &&
+        result.state !== "retained") {
+        return;
     }
-    catch {
-        return Number.POSITIVE_INFINITY;
+    writeProducerDiagnosticV3(coordRoot, "heartbeat_sweep_unrecorded", {
+        signal: "cache.cleanup",
+        state: "cache_cleanup_pending",
+        reason: `${result.state}:${result.error ?? "file_cleanup_pending"}; source=${sourcePath}; recovery=${result.recoveryPath ?? "unavailable"}`,
+    });
+}
+function recordHeartbeatCleanupResult(coordRoot, sourcePath, owner, result, uncertainOwners) {
+    if (result.state === "recovery-required" || result.state === "error") {
+        uncertainOwners.add(owner);
     }
+    recordCleanupFailure(coordRoot, sourcePath, result);
 }
 export function staleSweep(coordRoot) {
     const heartbeatsRemoved = [];
@@ -86,81 +134,129 @@ export function staleSweep(coordRoot) {
     // lifecycle.sweep_observed; a terminal or unavailable generation gets a
     // heartbeat_sweep_unrecorded producer diagnostic without being resurrected.
     const liveInstanceIds = new Set();
-    const d = join(coordRoot, ".harnery", "active");
+    const uncertainOwners = new Set();
+    const d = resolve(coordRoot, ".harnery", "active");
+    for (const recovery of existsSync(d)
+        ? recoverInterruptedFileDeletions(d, (source) => dirname(source) === d && /^[A-Za-z0-9_-]{1,128}\.json$/.test(basename(source)))
+        : []) {
+        if (recovery.state !== "restored") {
+            uncertainOwners.add(recovery.sourcePath ? basename(recovery.sourcePath, ".json") : "*");
+            recordCleanupFailure(coordRoot, recovery.sourcePath ?? d, recovery);
+        }
+    }
     if (existsSync(d)) {
         for (const f of readdirSync(d)) {
             if (!f.endsWith(".json"))
                 continue;
             const path = join(d, f);
             const idFromFile = f.replace(/\.json$/, "");
-            let parsed = null;
+            if (!/^[A-Za-z0-9_-]{1,128}$/.test(idFromFile))
+                continue;
             try {
-                parsed = JSON.parse(readFileSync(path, "utf8"));
-            }
-            catch {
-                parsed = null;
-            }
-            if (parsed === null) {
-                // Unparseable: only reap if the file itself is mtime-old.
-                if (mtimeSecs(path) < cutoff) {
+                withGenerationCustodyV3(coordRoot, [liveInstanceIdV3(idFromFile)], () => {
+                    const revision = captureFileRevision(path);
+                    if (!revision)
+                        return;
+                    const mtimeSecs = Number(revision.mtimeNs / 1000000000n);
+                    let parsed = null;
                     try {
-                        const ageSecs = nowSec - mtimeSecs(path);
-                        if (!emitSwept(coordRoot, idFromFile, "claude-code", idFromFile, "unparseable", ageSecs)) {
-                            continue;
-                        }
-                        unlinkSync(path);
-                        heartbeatsRemoved.push(f);
+                        const value = JSON.parse(revision.bytes.toString("utf8"));
+                        if (value && typeof value === "object" && !Array.isArray(value))
+                            parsed = value;
                     }
                     catch {
-                        /* swallow */
+                        parsed = null;
                     }
-                }
-                continue;
-            }
-            const instanceId = parsed.instance_id ?? idFromFile;
-            const adapter = eventAdapterIdV3FromPlatform(parsed.platform, { context: "stale-sweep" });
-            const sessionId = parsed.session_id ?? instanceId;
-            const ts = parsed.last_heartbeat
-                ? Math.floor(Date.parse(parsed.last_heartbeat) / 1000)
-                : Number.NaN;
-            if (!parsed.last_heartbeat || !Number.isFinite(ts)) {
-                // No / NaN last_heartbeat: can't trust content; gate on mtime.
-                if (mtimeSecs(path) < cutoff) {
-                    if (!emitSwept(coordRoot, instanceId, adapter, sessionId, "missing_ts", nowSec - mtimeSecs(path))) {
-                        continue;
+                    if (parsed === null) {
+                        // Unparseable: only reap if the file itself is mtime-old.
+                        if (mtimeSecs < cutoff) {
+                            const result = deleteFileIfUnchanged(path, revision, () => emitSwept(coordRoot, idFromFile, "claude-code", idFromFile, null, "unparseable", nowSec - mtimeSecs));
+                            recordHeartbeatCleanupResult(coordRoot, path, idFromFile, result, uncertainOwners);
+                            if (result.state === "deleted") {
+                                heartbeatsRemoved.push(f);
+                            }
+                        }
+                        return;
                     }
-                    unlinkSync(path);
-                    heartbeatsRemoved.push(f);
-                }
-                else if (parsed.instance_id) {
-                    liveInstanceIds.add(parsed.instance_id);
-                }
-                continue;
+                    // The filename selects the writer's custody scope. A conflicting content
+                    // identity cannot authorize an audit or deletion for a different owner.
+                    if (parsed.instance_id !== undefined && parsed.instance_id !== idFromFile)
+                        return;
+                    const instanceId = parsed.instance_id ?? idFromFile;
+                    const adapter = eventAdapterIdV3FromPlatform(parsed.platform, { context: "stale-sweep" });
+                    const sessionId = parsed.session_id ?? instanceId;
+                    const generationId = typeof parsed.v3_generation_id === "string" &&
+                        /^gen_[A-Za-z0-9._-]+$/.test(parsed.v3_generation_id)
+                        ? parsed.v3_generation_id
+                        : null;
+                    const ts = parsed.last_heartbeat
+                        ? Math.floor(Date.parse(parsed.last_heartbeat) / 1000)
+                        : Number.NaN;
+                    if (!parsed.last_heartbeat || !Number.isFinite(ts)) {
+                        // No / NaN last_heartbeat: can't trust content; gate on mtime.
+                        if (mtimeSecs < cutoff) {
+                            const result = deleteFileIfUnchanged(path, revision, () => emitSwept(coordRoot, instanceId, adapter, sessionId, generationId, "missing_ts", nowSec - mtimeSecs));
+                            recordHeartbeatCleanupResult(coordRoot, path, idFromFile, result, uncertainOwners);
+                            if (result.state === "deleted") {
+                                heartbeatsRemoved.push(f);
+                            }
+                        }
+                        else if (parsed.instance_id) {
+                            liveInstanceIds.add(parsed.instance_id);
+                        }
+                        return;
+                    }
+                    if (ts < cutoff) {
+                        // Legitimate stale prune (valid timestamp, past the freshness cutoff).
+                        const result = deleteFileIfUnchanged(path, revision, () => emitSwept(coordRoot, instanceId, adapter, sessionId, generationId, "stale", nowSec - ts));
+                        recordHeartbeatCleanupResult(coordRoot, path, idFromFile, result, uncertainOwners);
+                        if (result.state === "deleted") {
+                            heartbeatsRemoved.push(f);
+                        }
+                        return;
+                    }
+                    if (parsed.instance_id)
+                        liveInstanceIds.add(parsed.instance_id);
+                });
             }
-            if (ts < cutoff) {
-                // Legitimate stale prune (valid timestamp, past the freshness cutoff).
-                if (!emitSwept(coordRoot, instanceId, adapter, sessionId, "stale", nowSec - ts)) {
-                    continue;
-                }
-                unlinkSync(path);
-                heartbeatsRemoved.push(f);
-                continue;
+            catch {
+                // Busy or unknown custody retains the cache and its dependent files.
+                uncertainOwners.add(idFromFile);
             }
-            if (parsed.instance_id)
-                liveInstanceIds.add(parsed.instance_id);
         }
     }
     // 2. Prune pid-map entries whose instance has no live heartbeat.
-    const pidmapDir = join(coordRoot, ".harnery", "pid-map");
+    const pidmapDir = resolve(coordRoot, ".harnery", "pid-map");
+    for (const recovery of existsSync(pidmapDir)
+        ? recoverInterruptedFileDeletions(pidmapDir, (source) => dirname(source) === pidmapDir && /^\d+$/.test(basename(source)))
+        : [])
+        recordCleanupFailure(coordRoot, recovery.sourcePath ?? pidmapDir, recovery);
     if (existsSync(pidmapDir)) {
         for (const f of readdirSync(pidmapDir)) {
+            if (f.startsWith(".harnery-delete-"))
+                continue;
             const path = join(pidmapDir, f);
             try {
-                const row = readFileSync(path, "utf8").trim();
+                const revision = captureFileRevision(path);
+                if (!revision)
+                    continue;
+                const row = revision.bytes.toString("utf8").trim();
                 const ownerId = row.split("\t")[0]?.trim() ?? "";
-                if (!ownerId || !liveInstanceIds.has(ownerId)) {
-                    unlinkSync(path);
-                    pidmapsRemoved += 1;
+                const prune = () => {
+                    if (!ownerId ||
+                        (!liveInstanceIds.has(ownerId) &&
+                            !retainsHeartbeat(coordRoot, d, ownerId, uncertainOwners))) {
+                        const result = deleteFileIfUnchanged(path, revision, () => !ownerId || !retainsHeartbeat(coordRoot, d, ownerId, uncertainOwners));
+                        recordCleanupFailure(coordRoot, path, result);
+                        if (result.state === "deleted")
+                            pidmapsRemoved += 1;
+                    }
+                };
+                if (/^[A-Za-z0-9_-]{1,128}$/.test(ownerId)) {
+                    withGenerationCustodyV3(coordRoot, [liveInstanceIdV3(ownerId)], prune);
+                }
+                else if (!ownerId) {
+                    prune();
                 }
             }
             catch {
@@ -170,7 +266,12 @@ export function staleSweep(coordRoot) {
     }
     // 3. Prune prompt hashes for dead owners. Resource hashes retain their own
     // count so existing peer-hash telemetry keeps its original meaning.
-    const agentsDir = join(coordRoot, ".harnery");
+    const agentsDir = resolve(coordRoot, ".harnery");
+    for (const recovery of existsSync(agentsDir)
+        ? recoverInterruptedFileDeletions(agentsDir, (source) => dirname(source) === agentsDir &&
+            /^\.last-(?:resource|peer)-hash\.[A-Za-z0-9_-]{1,128}$/.test(basename(source)))
+        : [])
+        recordCleanupFailure(coordRoot, recovery.sourcePath ?? agentsDir, recovery);
     if (existsSync(agentsDir)) {
         for (const f of readdirSync(agentsDir)) {
             const resourceHash = f.startsWith(".last-resource-hash.");
@@ -183,16 +284,25 @@ export function staleSweep(coordRoot) {
                 // retained heartbeat's liveness could not be determined safely.
                 if (!/^[A-Za-z0-9_-]{1,128}$/.test(owner))
                     continue;
-                if (existsSync(join(d, `${owner}.json`)))
-                    continue;
             }
-            if (!liveInstanceIds.has(owner)) {
+            if (!liveInstanceIds.has(owner) && /^[A-Za-z0-9_-]{1,128}$/.test(owner)) {
                 try {
-                    unlinkSync(join(agentsDir, f));
-                    if (resourceHash)
-                        resourceHashesRemoved += 1;
-                    else
-                        peerHashesRemoved += 1;
+                    withGenerationCustodyV3(coordRoot, [liveInstanceIdV3(owner)], () => {
+                        if (retainsHeartbeat(coordRoot, d, owner, uncertainOwners))
+                            return;
+                        const path = join(agentsDir, f);
+                        const revision = captureFileRevision(path);
+                        if (!revision)
+                            return;
+                        const result = deleteFileIfUnchanged(path, revision, () => !retainsHeartbeat(coordRoot, d, owner, uncertainOwners));
+                        recordCleanupFailure(coordRoot, path, result);
+                        if (result.state === "deleted") {
+                            if (resourceHash)
+                                resourceHashesRemoved += 1;
+                            else
+                                peerHashesRemoved += 1;
+                        }
+                    });
                 }
                 catch {
                     /* swallow */

package/dist/core/agents/state/unchanged-file.d.ts

@@ -0,0 +1,44 @@
+export interface FileRevision {
+    readonly bytes: Buffer;
+    readonly dev: bigint;
+    readonly ino: bigint;
+    readonly size: bigint;
+    readonly mtimeNs: bigint;
+    readonly ctimeNs: bigint;
+}
+export type DeleteFileResult = {
+    state: "deleted" | "changed" | "missing" | "rejected";
+} | {
+    state: "recovery-required";
+    recoveryPath: string;
+    error?: string;
+} | {
+    state: "error";
+    recoveryPath?: string;
+    error: string;
+};
+export interface FileRecoveryResult {
+    state: "restored" | "retained" | "error";
+    recoveryPath: string;
+    sourcePath?: string;
+    error?: string;
+}
+/** A stable read of one regular file, including its exact bytes and revision. */
+export declare function captureFileRevision(filePath: string): FileRevision | null;
+export declare function fileRevisionMatches(filePath: string, expected: FileRevision): boolean;
+/**
+ * Writers must publish by atomic rename, never by an open descriptor to the old
+ * inode. The private directory is outside their publication namespace. Moving
+ * the row gives deletion custody over that inode without owning its live name.
+ * The caller owns the state parent and keeps its topology stable. Its platform
+ * permissions define which principals can modify it; this protocol does not
+ * exclude principals already authorized to change that parent.
+ */
+export declare function deleteFileIfUnchanged(filePath: string, expected: FileRevision, validate: (pinned: FileRevision) => boolean): DeleteFileResult;
+/**
+ * Recover same-host/platform/PID-namespace pins after process termination. File fsync
+ * protects manifest contents; directory entries are not fsynced, so this does
+ * not promise recovery after an OS crash or power loss.
+ */
+export declare function recoverInterruptedFileDeletions(directoryPath: string, validate: (sourcePath: string) => boolean): FileRecoveryResult[];
+//# sourceMappingURL=unchanged-file.d.ts.map

package/dist/core/agents/state/unchanged-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unchanged-file.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/state/unchanged-file.ts"],"names":[],"mappings":"AAsBA,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,MAAM,gBAAgB,GACxB;IAAE,KAAK,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,UAAU,CAAA;CAAE,GACzD;IAAE,KAAK,EAAE,mBAAmB,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GACpE;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7D,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,UAAU,GAAG,UAAU,GAAG,OAAO,CAAC;IACzC,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAsED,iFAAiF;AACjF,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAoCzE;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,GAAG,OAAO,CAGrF;AAsGD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,YAAY,EACtB,QAAQ,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,OAAO,GAC1C,gBAAgB,CAmFlB;AAED;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC7C,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,GACxC,kBAAkB,EAAE,CA+FtB"}