harnery 0.29.0 → 0.31.0

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

@@ -0,0 +1,199 @@
+/**
+ * Process start-token probe: the "is this still the same process?" half of pid
+ * identity.
+ *
+ * A pid alone does not identify a process. Operating systems hand numbers back
+ * out, and faster than intuition suggests: one development machine runs a
+ * `pid_max` of 99999 against roughly 100 new processes a second, turning the
+ * whole space over about every quarter hour. Anything that remembers a pid for
+ * longer than that is remembering a number, not a process.
+ *
+ * A start token pins the pair down. Two processes can share a pid but never a
+ * pid *and* a start instant, so a recorded `(pid, token)` either still names the
+ * process that was recorded or plainly does not.
+ *
+ * The token is opaque on purpose. Callers compare it for equality and nothing
+ * else, which is why no clock arithmetic appears here: Linux reports ticks since
+ * boot and BSD reports a formatted date, and neither needs converting to be
+ * compared with itself. A platform that will not answer returns null, meaning
+ * "unverifiable" — callers fall back to a plain liveness check, which is where
+ * they were before this existed.
+ *
+ * Two rules keep comparison honest, and both exist because getting them wrong
+ * reports a *false* mismatch, which prunes a live row and hands the identity
+ * walk the same wrong answer this module was written to stop:
+ *
+ * 1. One machine uses one probe. The probe is chosen by capability and locked
+ *    in, never fallen back from, so a transient read failure cannot answer in
+ *    the other probe's dialect and read as a recycled pid.
+ * 2. A probe's output must not depend on who asked. The `ps` text is formatted
+ *    through the caller's locale and timezone, so both are pinned; without that,
+ *    two callers reading the same live process disagree.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { coordEnv } from "../../../lib/env.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
+ * sets it routinely) and a shell running under the user's locale would render
+ * the same start instant two different ways and call each other liars. Pinning
+ * both makes the rendering a property of the process, not of its reader.
+ */
+const PS_ENV_PINS = { TZ: "UTC", LC_ALL: "C" };
+let cachedProbe;
+let cachedBootId;
+/**
+ * Which probe this machine uses, decided once.
+ *
+ * `HARNERY_PID_PROBE` forces the choice. That exists so the `ps` path can be
+ * exercised on a procfs machine — it is the same code on either OS, and running
+ * it only on hardware we happen to own is how a branch rots.
+ */
+export function startTokenProbe() {
+    const override = coordEnv("PID_PROBE");
+    if (override === "procfs" || override === "ps")
+        return override;
+    if (cachedProbe === undefined) {
+        cachedProbe = existsSync("/proc/self/stat") ? "procfs" : "ps";
+    }
+    return cachedProbe;
+}
+/**
+ * A short, stable identifier for the current boot, or null where there is none.
+ *
+ * Linux counts a process's start in ticks *since boot*, so the number alone
+ * repeats every time the machine restarts. Pid-map rows live in the working
+ * tree and outlive reboots, which is the whole exposure: a stale row for pid
+ * 1234 at 45.23s after boot matches a fresh process that happens to land on the
+ * same pid at the same moment of the next boot, and that false match is exactly
+ * the bug the token exists to prevent. Scoping the count to its boot removes
+ * the coincidence. BSD needs no equivalent, since its token is an absolute
+ * date.
+ */
+function bootId() {
+    if (cachedBootId !== undefined)
+        return cachedBootId;
+    try {
+        const raw = readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim().replace(/-/g, "");
+        cachedBootId = /^[0-9a-f]{8,}$/.test(raw) ? raw.slice(0, 8) : null;
+    }
+    catch {
+        cachedBootId = null;
+    }
+    return cachedBootId;
+}
+/** Forget the cached probe and boot id. Tests only. */
+export function resetStartTokenCaches() {
+    cachedProbe = undefined;
+    cachedBootId = undefined;
+}
+/**
+ * `l[<boot>.]<ticks since boot>` from `/proc/<pid>/stat`, with no subprocess.
+ *
+ * The tick count is field 22, counted from the end of the comm field rather
+ * 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.
+ */
+export function procfsStartToken(pid) {
+    let stat;
+    try {
+        stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+    }
+    catch {
+        return null; // dead pid, or no procfs — either way, nothing to say
+    }
+    const afterComm = stat.slice(stat.lastIndexOf(") ") + 2);
+    // Fields after comm, 0-based: 0 is state (field 3), so starttime (field 22)
+    // sits at 19.
+    const ticks = afterComm.split(" ")[19];
+    if (!ticks || !/^\d+$/.test(ticks))
+        return null;
+    const boot = bootId();
+    return boot ? `l${boot}.${ticks}` : `l${ticks}`;
+}
+/**
+ * `p<start date>` from one `ps -o lstart=`, for machines without procfs.
+ *
+ * Second resolution is ample: telling two runs of one pid apart would need the
+ * entire pid space to recycle inside a second. The runner is injectable so the
+ * parsing and the env pinning can be tested without a process to look at.
+ */
+export function psStartToken(pid, run = defaultPsRun) {
+    let out;
+    try {
+        out = run(pid);
+    }
+    catch {
+        return null; // no ps on this machine
+    }
+    if (out.status !== 0)
+        return null;
+    const lstart = (out.stdout ?? "").split("\n")[0]?.trim().replace(/\s+/g, " ");
+    return lstart ? `p${lstart}` : null;
+}
+function defaultPsRun(pid) {
+    const out = spawnSync("ps", ["-o", "lstart=", "-p", String(pid)], {
+        encoding: "utf8",
+        timeout: 2000,
+        env: { ...process.env, ...PS_ENV_PINS },
+    });
+    return { status: out.status, stdout: out.stdout ?? "" };
+}
+/**
+ * An opaque token identifying *this run* of `pid`, or null when the platform
+ * will not say.
+ */
+export function processStartToken(pid) {
+    if (!Number.isFinite(pid) || pid <= 0)
+        return null;
+    return startTokenProbe() === "procfs" ? procfsStartToken(pid) : psStartToken(pid);
+}
+/**
+ * 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/shell-mutation.d.ts

@@ -1,7 +1,7 @@
 /**
  * A heuristic parser that extracts file paths likely to be mutated by a
  * shell command. Used by
- * the cursor + codex harness adapters to emit SHELL_CLAIM_CANDIDATE log lines
+ * the cursor + codex adapter adapters to emit SHELL_CLAIM_CANDIDATE log lines
  * (warn-only, never blocks).
  *
  * Two cases:

package/dist/core/agents/state/shell-mutation.js

@@ -1,7 +1,7 @@
 /**
  * A heuristic parser that extracts file paths likely to be mutated by a
  * shell command. Used by
- * the cursor + codex harness adapters to emit SHELL_CLAIM_CANDIDATE log lines
+ * the cursor + codex adapter adapters to emit SHELL_CLAIM_CANDIDATE log lines
  * (warn-only, never blocks).
  *
  * Two cases:

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

@@ -13,8 +13,8 @@ import { existsSync, readdirSync, readFileSync, statSync, unlinkSync } from "nod
 import { join } from "node:path";
 import { coordFreshnessSeconds } from "../../config.js";
 import { emit } from "../events/emit.js";
-/** platform → harness, for the swept-event envelope (mirrors heartbeat-writer's harnessOf). */
-function harnessFromPlatform(platform) {
+/** platform → adapter, for the swept-event envelope (mirrors heartbeat-writer's adapterOf). */
+function adapterFromPlatform(platform) {
     if (platform === "cursor")
         return "cursor";
     if (platform === "codex")
@@ -22,13 +22,13 @@ function harnessFromPlatform(platform) {
     return "claude-code";
 }
 /** Emit a best-effort health.heartbeat_swept event. Telemetry only, never throws. */
-function emitSwept(coordRoot, instanceId, harness, sessionId, reason, ageSecs) {
+function emitSwept(coordRoot, instanceId, adapter, sessionId, reason, ageSecs) {
     try {
         emit(coordRoot, {
             event_type: "health.heartbeat_swept",
             instance_id: instanceId,
             session_id: sessionId,
-            harness,
+            adapter,
             source: "agent-coord",
             data: { reason, ...(ageSecs !== undefined ? { age_secs: ageSecs } : {}) },
             // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
@@ -98,7 +98,7 @@ export function staleSweep(coordRoot) {
                 continue;
             }
             const instanceId = parsed.instance_id ?? idFromFile;
-            const harness = harnessFromPlatform(parsed.platform);
+            const adapter = adapterFromPlatform(parsed.platform);
             const sessionId = parsed.session_id ?? instanceId;
             const ts = parsed.last_heartbeat
                 ? Math.floor(Date.parse(parsed.last_heartbeat) / 1000)
@@ -108,7 +108,7 @@ export function staleSweep(coordRoot) {
                 if (mtimeSecs(path) < cutoff) {
                     unlinkSync(path);
                     heartbeatsRemoved.push(f);
-                    emitSwept(coordRoot, instanceId, harness, sessionId, "missing_ts");
+                    emitSwept(coordRoot, instanceId, adapter, sessionId, "missing_ts");
                 }
                 else if (parsed.instance_id) {
                     liveInstanceIds.add(parsed.instance_id);
@@ -119,7 +119,7 @@ export function staleSweep(coordRoot) {
                 // Legitimate stale prune (valid timestamp, past the freshness cutoff).
                 unlinkSync(path);
                 heartbeatsRemoved.push(f);
-                emitSwept(coordRoot, instanceId, harness, sessionId, "stale", nowSec - ts);
+                emitSwept(coordRoot, instanceId, adapter, sessionId, "stale", nowSec - ts);
                 continue;
             }
             if (parsed.instance_id)

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

@@ -0,0 +1,86 @@
+/**
+ * Repository-local working artifacts.
+ *
+ * Artifacts are file trees that should survive an agent session but should not
+ * become project records: screenshots, exports, audit dumps, rollback inputs,
+ * and similar material. Each direct child of `.harnery/artifacts/` is one
+ * managed unit with a small manifest. Cleanup fails closed: only a valid,
+ * expired, inactive, untracked managed unit is deletable.
+ */
+export declare const ARTIFACTS_DIR: string;
+export declare const ARTIFACT_MANIFEST = ".harnery-artifact.json";
+export declare const ARTIFACT_SCHEMA_VERSION: 1;
+export interface ArtifactActor {
+    instance_id: string;
+    session_id?: string;
+    name?: string;
+}
+export interface ArtifactManifestV1 {
+    schema_version: typeof ARTIFACT_SCHEMA_VERSION;
+    artifact_id: string;
+    slug: string;
+    purpose: string;
+    created_at: string;
+    created_by?: ArtifactActor;
+    retention: {
+        expires_at: string;
+        renewed_at?: string;
+        reason?: string;
+    };
+    released_at?: string;
+    released_by?: ArtifactActor;
+}
+export type ArtifactClassification = "managed-active" | "managed-current" | "managed-expired" | "managed-tracked" | "invalid-manifest" | "unmanaged" | "symlink" | "unknown";
+export interface ArtifactInventoryEntry {
+    name: string;
+    path: string;
+    relative_path: string;
+    classification: ArtifactClassification;
+    reason: string;
+    action: "keep" | "would-delete" | "deleted";
+    bytes: number | null;
+    artifact_id: string | null;
+    slug: string | null;
+    created_at: string | null;
+    expires_at: string | null;
+    owner_instance_id: string | null;
+}
+export interface ArtifactCreateInput {
+    slug: string;
+    purpose: string;
+    retentionDays: number;
+    actor?: ArtifactActor;
+    now?: Date;
+    id?: string;
+}
+export interface ArtifactMutationInput {
+    actor?: ArtifactActor;
+    now?: Date;
+}
+export declare function artifactsRoot(repoRoot: string): string;
+/** Public config-aware default for embedding hosts that create artifact units. */
+export declare function configuredArtifactRetentionDays(repoRoot: string): number;
+export declare function createArtifact(repoRoot: string, input: ArtifactCreateInput): {
+    path: string;
+    manifest: ArtifactManifestV1;
+};
+export declare function inventoryArtifacts(repoRoot: string, opts?: {
+    now?: Date;
+    freshnessSeconds?: number;
+}): ArtifactInventoryEntry[];
+export declare function showArtifact(repoRoot: string, ref: string, opts?: {
+    now?: Date;
+    freshnessSeconds?: number;
+}): {
+    entry: ArtifactInventoryEntry;
+    manifest: ArtifactManifestV1;
+};
+export declare function renewArtifact(repoRoot: string, ref: string, days: number, reason: string, input?: ArtifactMutationInput): ArtifactManifestV1;
+export declare function releaseArtifact(repoRoot: string, ref: string, input?: ArtifactMutationInput): ArtifactManifestV1;
+export declare function cleanArtifacts(repoRoot: string, opts?: {
+    yes?: boolean;
+    now?: Date;
+    freshnessSeconds?: number;
+}): ArtifactInventoryEntry[];
+export declare function resolveArtifactRef(repoRoot: string, ref: string): string;
+//# sourceMappingURL=index.d.ts.map

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

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