@sentropic/h2a 0.97.9 → 0.97.11

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "h2a",
   "description": "H2A coordination with one MCP endpoint (including Track read tools) and the H2A, Track, and Harness operating skills.",
-  "version": "0.97.9",
+  "version": "0.97.11",
   "author": {
     "name": "Fabien Antoine"
   },

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "h2a",
-  "version": "0.97.9",
+  "version": "0.97.11",
   "description": "Coordinate Claude, Codex and other CLI agents through the local h2a bus, objective loops and track system of record.",
   "author": {
     "name": "Fabien Antoine"

package/dist/runtime/local-files/succession-lock.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Succession lock (v4) — single-machine succession protocol.
+ *
+ * Extracted from `runtime/upgrade/index.ts` (Lot 4, step 1: neutral
+ * intra-package move — zero behaviour change). This is the shared lock primitive
+ * used by the auto-upgrade prefix lock today, and (later lots) by the identity
+ * binding lock. It is a LEAF: it imports only `node:fs/os/crypto/child_process`
+ * and nothing from the store, so `upgrade/index.ts` and `local-files/locks.ts`
+ * import it directly by file, never via `local-files/index.js`.
+ *
+ * The full protocol proof-sketch (I1–I7, Lemmas A–C) lives with the code below,
+ * moved unchanged from its original location.
+ */
+/**
+ * R2 staleness-alert threshold. An upgrade held under the lock completes in seconds to
+ * a few minutes (bounded tarball fetch + stage + atomic swap), so a lock far older than
+ * that whose holder reads "live" ONLY for want of a comparable start time is worth
+ * surfacing (a reused PID may be masking a dead holder). Set well above any legitimate
+ * hold. It NEVER triggers a reclaim — purely diagnostic (I7: `at` informs, never decides).
+ */
+export declare const STALE_LOCK_ALERT_MS: number;
+/** Acquire rounds before giving up (a retry means a rival won meanwhile). */
+export declare const PREFIX_LOCK_MAX_ROUNDS = 3;
+/** Succession chain depth before failing closed with a diagnostic. */
+export declare const PREFIX_LOCK_MAX_CHAIN = 8;
+/** Holder-only GC age for abandoned TMP files (debris, never a decision). */
+export declare const PREFIX_LOCK_TMP_DEBRIS_MAX_AGE_MS: number;
+/** Fallback age for the residue sweep when no owner can be identified. */
+export declare const UPGRADE_RESIDUE_MAX_AGE_MS: number;
+/** Why acquisition failed: live holder, undecidable owner, or an OS error. */
+export type PrefixLockReason = "busy" | "dead-undecidable" | `error:${string}`;
+/** Lease on the global prefix. `token` is present only when acquired. */
+export interface PrefixLockLease {
+    readonly acquired: boolean;
+    release(): void;
+    readonly reason?: PrefixLockReason;
+    /** Winning token; present only when acquired. Never republished (I2). */
+    readonly token?: string;
+}
+/** Observation window for one deterministic-test hook invocation. */
+export interface PrefixLockHookContext {
+    readonly prefix: string;
+    readonly lockPath: string;
+    /** File the window is about: LOCK for publish/unlink, SUCC(t) after election. */
+    readonly path: string;
+    /** Our fresh token being published (or held). */
+    readonly token?: string;
+    /** Succession target g (afterPublishSucc / retire windows). */
+    readonly target?: string;
+    readonly round: number;
+    readonly depth: number;
+}
+/**
+ * Critical-section hooks for deterministic tests ONLY. Passed as the 2nd
+ * argument of `acquirePrefixLock(prefix, hooks)` by the test; never enabled
+ * via environment or configuration (there is no env/config reader for them),
+ * and production calls without hooks so every hook is a no-op at zero cost.
+ */
+export interface PrefixLockHooks {
+    /** Just BEFORE the initial publish(LOCK) (round 0) — initial race window. */
+    readonly beforePublishLock?: (ctx: PrefixLockHookContext) => void;
+    /** Just AFTER a publish(SUCC(t)) success, BEFORE retire — unique successor elected. */
+    readonly afterPublishSucc?: (ctx: PrefixLockHookContext) => void;
+    /** In retire(), around the targeted unlink(LOCK) (removal-to-republish window). */
+    readonly beforeRetireUnlink?: (ctx: PrefixLockHookContext) => void;
+    readonly afterRetireUnlink?: (ctx: PrefixLockHookContext) => void;
+}
+interface LockIdent {
+    readonly host: string;
+    readonly boot: string | null;
+    readonly ns: string | null;
+    /** Reader's time namespace; gates proc-sourced start comparisons (B2). */
+    readonly timeNs: string | null;
+    readonly pid: number;
+    readonly start: string | null;
+}
+interface LockRec extends LockIdent {
+    readonly token: string;
+    readonly target?: string;
+    /** Diagnostic only, never decides (I7). */
+    readonly at: number;
+}
+export declare function lockPathFor(prefix: string): string;
+export declare function errnoOf(e: unknown): string;
+export declare function safeAtIso(at: number): string;
+export declare function readPidNs(platform?: NodeJS.Platform, readLink?: (p: string) => string): string | null;
+export declare function readTimeNs(platform?: NodeJS.Platform, readLink?: (p: string) => string): string | null;
+/**
+ * Process start identity, prefixed by its source ("proc:" from Linux /proc
+ * field 22, "ps:" from `ps lstart`). The prefix is part of the stored value
+ * so a reader using a different source never concludes "dead" from a
+ * format/TZ-fragile comparison (C1).
+ */
+export declare function procStartInfo(pid: number, platform?: NodeJS.Platform, mapsToSelf?: () => boolean): {
+    state?: string;
+    start?: string;
+} | undefined;
+interface SelfIdent extends LockIdent {
+    readonly pid: number;
+}
+/** This process's identity, computed once and memoized. */
+export declare function me(): SelfIdent;
+export declare function makeLockRec(token: string, target?: string): LockRec;
+export declare function parseLockRec(raw: unknown): LockRec;
+/** opus `read`: ENOENT -> absent, anything else unreadable -> corrupt (I1). */
+export declare function readLockRecord(path: string): LockRec | "absent" | "corrupt";
+type PublishStatus = {
+    status: "ok";
+} | {
+    status: "exists";
+} | {
+    status: "retry";
+} | {
+    status: "error";
+    code: string;
+};
+/**
+ * opus `publish` (I1): a name appears only with complete, durable content.
+ * Write tmp (wx + byte-count-checked write + fsync + close), then `link(2)`;
+ * EEXIST -> "exists", ENOENT at link -> "retry" (tmp reaped before link),
+ * any other failure -> "error" with the errno (no hard links -> fail closed).
+ * The tmp never contains `.succ.` (C2).
+ */
+export declare function publishLockRecord(path: string, rec: LockRec): PublishStatus;
+type Liveness = "dead" | "live" | "undecidable";
+/** Injected only by tests (platform / start-probe sims); production passes none. */
+interface LivenessDeps {
+    readonly platform?: NodeJS.Platform;
+    readonly probe?: (pid: number) => {
+        state?: string;
+        start?: string;
+    } | undefined;
+}
+/**
+ * A "live" verdict is `datable` when it came from a CONFIRMED, comparable start
+ * (same source, known equal time namespace) — the holder is provably the recorded
+ * process. It is NOT datable when "live" was reached only because the start was
+ * undatable (source mismatch, unknown/differing time namespace, or no start) — there
+ * a reused PID could be masking a dead holder. This bit is used solely to target the
+ * staleness alert (R2); it must never influence a reclaim decision.
+ */
+interface LivenessInfo {
+    readonly verdict: Liveness;
+    readonly datable: boolean;
+}
+/**
+ * Single liveness classifier. `livenessOf` and `isCertainlyDead` are exactly its
+ * "verdict"/"dead" arm, and the R2 staleness alert reads its `datable` bit, so none
+ * of them can drift from this one decision. Never derives "dead" from a fragile
+ * comparison: a source mismatch or an unknown/differing time namespace both yield a
+ * safe "live" (undatable), and a corrupt "legacy" start yields "undecidable" (C1).
+ */
+export declare function classifyLiveness(r: LockRec, self: SelfIdent, deps?: LivenessDeps): LivenessInfo;
+export declare function livenessOf(r: LockRec, self: SelfIdent, deps?: LivenessDeps): Liveness;
+/** No false positive: true implies certainly dead; any doubt is alive (I3). */
+export declare function isCertainlyDead(r: LockRec): boolean;
+/** opus `acquirePrefixLock`, plus M5 reasons and test-only critical hooks. */
+export declare function acquirePrefixLock(prefix: string, hooks?: PrefixLockHooks): PrefixLockLease;
+/** True when the path is older than the threshold; false when unstated. */
+export declare function isOlderThan(path: string, now: number, maxAgeMs: number): boolean;
+export {};
+//# sourceMappingURL=succession-lock.d.ts.map

package/dist/runtime/local-files/succession-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"succession-lock.d.ts","sourceRoot":"","sources":["../../../src/runtime/local-files/succession-lock.ts"],"names":[],"mappings":"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"}