@sentropic/h2a 0.97.2 → 0.97.4

package/dist/runtime/identity/worker.js

@@ -0,0 +1,189 @@
+/**
+ * L2 identity worker — the dedicated, non-detached child that resolves the
+ * shared identity OFF the parent's MCP event loop.
+ *
+ * It receives ONE typed request over IPC, runs the canonical async resolution
+ * (the same writer path as the CLI — `resolveLiveIdentityAsync`, whose only
+ * append of a binding row is `reclaimOrMint*`), and returns ONE response. It
+ * publishes NO presence, NO tool signature, NO wake, NO readiness ACK; those are
+ * the parent's job after it validates the result. No PEM ever crosses IPC — only
+ * paths, which the parent re-validates against the canonical key layout.
+ *
+ * It is argv-only (the request arrives over IPC), stdout is ignored (it must
+ * never emit protocol traffic), and diagnostics go to stderr. A cancel makes it
+ * stop starting any NEW transaction (cooperative); a transaction already entered
+ * under a lock finishes so no half-written binding is left, and the lock is
+ * released in the resolver's `finally`.
+ */
+import { resolveLiveIdentityAsync } from "./live.js";
+import { LockCancelledError, LockTimeoutError } from "../local-files/locks.js";
+import { createMcpTrace, setActiveMcpTrace } from "../mcp/phase-trace.js";
+function classify(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (err instanceof LockCancelledError) {
+        return { cause: "identity_timeout", message };
+    }
+    const code = err?.code;
+    if (code === "EROFS")
+        return { cause: "storage_readonly", message };
+    if (code === "EACCES" || code === "EPERM")
+        return { cause: "storage_permission_denied", message };
+    if (err instanceof Error && err.name === "LockTimeoutError") {
+        return { cause: "identity_timeout", message };
+    }
+    // A generic durable-store write failure vs. an unexpected worker fault.
+    if (code === "ENOSPC" || code === "EIO")
+        return { cause: "identity_storage_failed", message };
+    return { cause: "identity_worker_failed", message };
+}
+function send(message) {
+    try {
+        process.send?.(message);
+    }
+    catch {
+        /* the parent may have closed the channel; nothing more we can do */
+    }
+}
+const abort = new AbortController();
+let handled = false;
+process.on("message", (raw) => {
+    const msg = raw;
+    if (!msg || typeof msg !== "object")
+        return;
+    if (msg.kind === "cancel") {
+        // Cooperative: stop before any NEW transaction. A transaction already under a
+        // lock finishes; its `finally` releases the lock.
+        abort.abort(msg.reason ?? "cancel");
+        send({ kind: "cancel_ack", v: 1 });
+        return;
+    }
+    if (msg.kind !== "resolve_identity" || handled)
+        return;
+    handled = true;
+    const req = msg;
+    // L0 (#249): relocate the identity/lock/registry instrumentation that used to
+    // run on the parent. Installing a correlated `identity-child` trace (same
+    // attemptId as the parent) makes resolveLiveIdentityAsync's provider/keys/
+    // register/alias spans, the registry_read span, and the binding-lock spans
+    // fire HERE (on the worker's stderr, which the parent forwards line by line),
+    // instead of being silently lost when resolution moved off the parent loop.
+    setActiveMcpTrace(createMcpTrace({
+        role: "identity-child",
+        ...(req.traceAttemptId !== undefined ? { attemptId: req.traceAttemptId } : {}),
+        pid: process.pid
+    }));
+    const input = {
+        root: req.request.root,
+        host: req.request.host,
+        cwd: req.request.cwd,
+        ...(req.request.explicitInstance !== undefined
+            ? { explicitInstance: req.request.explicitInstance }
+            : {}),
+        ...(req.request.name !== undefined ? { name: req.request.name } : {}),
+        ...(req.request.scopes !== undefined ? { scopes: req.request.scopes } : {}),
+        ...(req.request.declaredCapabilities !== undefined
+            ? { declaredCapabilities: req.request.declaredCapabilities }
+            : {})
+    };
+    const budgetMs = Number.isFinite(req.budgetMs) && req.budgetMs > 0 ? req.budgetMs : 20_000;
+    const startNs = process.hrtime.bigint();
+    const remainingMs = () => budgetMs - Number((process.hrtime.bigint() - startNs) / 1000000n);
+    const cancellableDelay = (ms) => new Promise((resolve) => {
+        if (abort.signal.aborted)
+            return resolve();
+        const timer = setTimeout(resolve, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            resolve();
+        };
+        abort.signal.addEventListener("abort", onAbort, { once: true });
+    });
+    // Retry on CONTENTION (a live lock holder) until the budget, ceding the event
+    // loop between attempts so an IPC cancel is honored; the parent's 20 s deadline
+    // is authoritative. A PERMANENT error (EROFS / EACCES / …) is NOT retried — it
+    // is the failure. `reclaimOrMint*` stays the unique binding writer across
+    // attempts; a contended attempt writes no binding (it releases the lock first).
+    // Shared across attempts: the mint candidate is generated once (no keypair
+    // leak) and the expensive OUTSIDE-lock reads are parsed once (no re-parse of
+    // the ~17 MB registry per retry under contention).
+    const mintMemo = {};
+    const prepCache = {};
+    let attempt = 0;
+    const resolveWithRetry = async () => {
+        while (!abort.signal.aborted) {
+            const budget = remainingMs();
+            if (budget <= 0)
+                throw new LockTimeoutError("identity", undefined, budgetMs);
+            try {
+                return await resolveLiveIdentityAsync(input, {
+                    signal: abort.signal,
+                    deadlineMs: budget,
+                    // Fail a contended registration fast so the identity lock is not held
+                    // through a long registry wait; the loop retries outside the section.
+                    registryLockTimeoutMs: 250,
+                    mintMemo,
+                    prepCache,
+                    attempt
+                });
+            }
+            catch (err) {
+                attempt += 1;
+                if (abort.signal.aborted)
+                    throw err;
+                if (err instanceof LockTimeoutError && remainingMs() > 0) {
+                    await cancellableDelay(200);
+                    continue;
+                }
+                throw err;
+            }
+        }
+        throw new LockCancelledError("identity", "cancelled");
+    };
+    void resolveWithRetry()
+        .then((identity) => {
+        send({
+            kind: "identity_resolved",
+            v: 1,
+            identity: {
+                instance: identity.instance,
+                host: identity.host,
+                ...(identity.workspace !== undefined ? { workspace: identity.workspace } : {}),
+                ...(identity.name !== undefined ? { name: identity.name } : {}),
+                action: identity.action,
+                ...(identity.providerSessionId !== undefined
+                    ? { providerSessionId: identity.providerSessionId }
+                    : {}),
+                ...(identity.providerSessionSource !== undefined
+                    ? { providerSessionSource: identity.providerSessionSource }
+                    : {}),
+                // Paths only — the parent re-validates them against identityKeyPaths.
+                privateKeyPath: identity.privateKeyPath ?? "",
+                publicKeyPath: identity.publicKeyPath ?? "",
+                ...(identity.migrationNotice !== undefined
+                    ? { migrationNotice: identity.migrationNotice }
+                    : {}),
+                ...(identity.legacyInstance !== undefined
+                    ? { legacyInstance: identity.legacyInstance }
+                    : {}),
+                // Only a locally-derived identity (no explicit --instance) may attest a
+                // delegation; an explicit label never becomes an ownership attestation.
+                delegationEligible: req.request.explicitInstance === undefined
+            }
+        });
+    })
+        .catch((err) => {
+        const { cause, message } = classify(err);
+        send({ kind: "identity_error", v: 1, cause, message });
+    })
+        .finally(() => {
+        // The worker's whole job is one resolution; exit so no orphan lingers to
+        // start another transaction. Give the IPC a tick to flush.
+        setTimeout(() => process.exit(0), 10).unref?.();
+    });
+});
+// If the parent's channel closes before a result, exit rather than linger.
+process.on("disconnect", () => {
+    abort.abort("disconnect");
+    setTimeout(() => process.exit(0), 50).unref?.();
+});
+//# sourceMappingURL=worker.js.map

package/dist/runtime/identity/worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.js","sourceRoot":"","sources":["../../../src/runtime/identity/worker.ts"],"names":[],"mappings":"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"}

package/dist/runtime/local-files/locks.d.ts

@@ -24,6 +24,20 @@
  * unlinking and retrying. Otherwise we poll up to `timeoutMs` and throw
  * `LockTimeoutError`.
  */
+/**
+ * A passive observation of a lock critical section, for the L0 phase trace.
+ * `lock` is a LOGICAL id (the lock's parent directory name, e.g. `registry` /
+ * `identity`) — never the lock owner payload or any binding content. Emitting
+ * an observation never changes the lock's timeout, poll or reclaim policy, and
+ * a throwing observer can never break the critical section.
+ */
+export interface LockObservation {
+    readonly lock: string;
+    readonly event: "wait" | "acquired" | "released" | "timeout";
+    readonly waitMs?: number;
+    readonly holdMs?: number;
+    readonly attempts?: number;
+}
 export interface LockOwner {
     readonly pid: number;
     readonly hostname: string;
@@ -47,6 +61,26 @@ export interface WithLockOptions {
      * reason to silently continue.
      */
     readonly reclaimStale?: boolean;
+    /**
+     * Passive instrumentation hook (L0). Called on `wait` (once, before the first
+     * acquire attempt), `acquired` (with `waitMs`/`attempts`), `released` (with
+     * `holdMs`) and `timeout` (with `waitMs`). It cannot change locking behaviour.
+     */
+    readonly observe?: (event: LockObservation) => void;
+    /**
+     * L2 cooperative cancellation (async `withLock` only). When aborted while
+     * WAITING for the lock, the wait stops and `withLock` rejects with a
+     * `LockCancelledError` — the worker then stops before entering a new critical
+     * section. Once the lock is HELD, `fn` runs to completion (a transaction
+     * already entered finishes cleanly); the signal never interrupts a held
+     * section, so no half-written state is left behind.
+     */
+    readonly signal?: AbortSignal;
+}
+/** Thrown by the async `withLock` when its signal aborts DURING the wait. */
+export declare class LockCancelledError extends Error {
+    readonly lockPath: string;
+    constructor(lockPath: string, reason?: string);
 }
 export declare class LockTimeoutError extends Error {
     readonly lockPath: string;

package/dist/runtime/local-files/locks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"locks.d.ts","sourceRoot":"","sources":["../../../src/runtime/local-files/locks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAKH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,8DAA8D;IAC9D,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,UAAU,GAAG,YAAY,CAAC,CAAC,CAAC;IAC9E;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;CACjC;AAED,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,CAAC;gBAEvB,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,SAAS,GAAG,SAAS,EAAE,SAAS,EAAE,MAAM;CAWtF;AAgHD,wBAAsB,QAAQ,CAAC,CAAC,EAC9B,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EACxB,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,CAAC,CAAC,CA0BZ;AAED,wBAAgB,YAAY,CAAC,CAAC,EAC5B,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,CAAC,EACX,OAAO,GAAE,eAAoB,GAC5B,CAAC,CA0BH"}
+{"version":3,"file":"locks.d.ts","sourceRoot":"","sources":["../../../src/runtime/local-files/locks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAMH;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,UAAU,GAAG,SAAS,CAAC;IAC7D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAuBD,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,8DAA8D;IAC9D,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,UAAU,GAAG,YAAY,CAAC,CAAC,CAAC;IAC9E;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC;IACpD;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,6EAA6E;AAC7E,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBACd,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;CAK9C;AAED,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,CAAC;gBAEvB,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,SAAS,GAAG,SAAS,EAAE,SAAS,EAAE,MAAM;CAWtF;AAgHD,wBAAsB,QAAQ,CAAC,CAAC,EAC9B,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EACxB,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,CAAC,CAAC,CAwCZ;AAED,wBAAgB,YAAY,CAAC,CAAC,EAC5B,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,CAAC,EACX,OAAO,GAAE,eAAoB,GAC5B,CAAC,CAoCH"}

package/dist/runtime/local-files/locks.js

@@ -26,6 +26,35 @@
  */
 import { closeSync, openSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { hostname } from "node:os";
+import { basename, dirname } from "node:path";
+function logicalLockId(lockPath) {
+    try {
+        const label = basename(dirname(lockPath)) || basename(lockPath);
+        return label.length > 64 ? label.slice(0, 64) : label;
+    }
+    catch {
+        return "lock";
+    }
+}
+function notifyObserver(observe, event) {
+    if (!observe)
+        return;
+    try {
+        observe(event);
+    }
+    catch {
+        /* a passive observer must never disturb the critical section */
+    }
+}
+/** Thrown by the async `withLock` when its signal aborts DURING the wait. */
+export class LockCancelledError extends Error {
+    lockPath;
+    constructor(lockPath, reason) {
+        super(`LockCancelledError: acquisition of ${lockPath} was cancelled${reason ? ` (${reason})` : ""}`);
+        this.name = "LockCancelledError";
+        this.lockPath = lockPath;
+    }
+}
 export class LockTimeoutError extends Error {
     lockPath;
     lastSeenOwner;
@@ -149,22 +178,36 @@ export async function withLock(lockPath, fn, options = {}) {
     const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     const pollMs = options.pollMs ?? DEFAULT_POLL_MS;
     const selfHostname = hostname();
-    const deadline = Date.now() + timeoutMs;
+    const observe = options.observe;
+    const lock = observe ? logicalLockId(lockPath) : "";
+    const startedAt = Date.now();
+    const deadline = startedAt + timeoutMs;
     let lastSeen;
+    let attempts = 0;
+    notifyObserver(observe, { lock, event: "wait" });
     while (true) {
+        if (options.signal?.aborted) {
+            notifyObserver(observe, { lock, event: "timeout", waitMs: Date.now() - startedAt, attempts });
+            throw new LockCancelledError(lockPath, String(options.signal.reason ?? "aborted"));
+        }
+        attempts++;
         const attempt = acquire(lockPath, selfHostname, options);
         if (attempt.ok)
             break;
         lastSeen = attempt.lastSeen ?? lastSeen;
         if (Date.now() >= deadline) {
+            notifyObserver(observe, { lock, event: "timeout", waitMs: Date.now() - startedAt, attempts });
             throw new LockTimeoutError(lockPath, lastSeen, timeoutMs);
         }
         await delay(pollMs);
     }
+    const acquiredAt = Date.now();
+    notifyObserver(observe, { lock, event: "acquired", waitMs: acquiredAt - startedAt, attempts });
     try {
         return await fn();
     }
     finally {
+        notifyObserver(observe, { lock, event: "released", holdMs: Date.now() - acquiredAt });
         try {
             unlinkSync(lockPath);
         }
@@ -177,22 +220,32 @@ export function withLockSync(lockPath, fn, options = {}) {
     const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     const pollMs = options.pollMs ?? DEFAULT_POLL_MS;
     const selfHostname = hostname();
-    const deadline = Date.now() + timeoutMs;
+    const observe = options.observe;
+    const lock = observe ? logicalLockId(lockPath) : "";
+    const startedAt = Date.now();
+    const deadline = startedAt + timeoutMs;
     let lastSeen;
+    let attempts = 0;
+    notifyObserver(observe, { lock, event: "wait" });
     while (true) {
+        attempts++;
         const attempt = acquire(lockPath, selfHostname, options);
         if (attempt.ok)
             break;
         lastSeen = attempt.lastSeen ?? lastSeen;
         if (Date.now() >= deadline) {
+            notifyObserver(observe, { lock, event: "timeout", waitMs: Date.now() - startedAt, attempts });
             throw new LockTimeoutError(lockPath, lastSeen, timeoutMs);
         }
         busyWaitSync(pollMs);
     }
+    const acquiredAt = Date.now();
+    notifyObserver(observe, { lock, event: "acquired", waitMs: acquiredAt - startedAt, attempts });
     try {
         return fn();
     }
     finally {
+        notifyObserver(observe, { lock, event: "released", holdMs: Date.now() - acquiredAt });
         try {
             unlinkSync(lockPath);
         }

package/dist/runtime/local-files/locks.js.map

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

package/dist/runtime/local-files/store.d.ts

@@ -28,6 +28,27 @@ export interface CreateLocalStoreOptions {
      * critical section plus inter-host clock skew. Default 30000.
      */
     leaseMs?: number;
+    /**
+     * L2: when `false`, DO NOT create the store layout — no directory, no schema
+     * sentinel, no empty `instances.jsonl`. An existing sentinel is still read and
+     * validated; an absent root simply yields empty reads (a genuinely unreadable
+     * file is NOT flattened to an empty list). Used by the MCP transport so
+     * `initialize` / `tools/list` / `h2a_identity_status` and every read-only tool
+     * answer on a read-only or not-yet-created root, before identity is ready.
+     * Default `true` (unchanged behavior for every existing caller).
+     */
+    initialize?: boolean;
+    /**
+     * L2: when `true`, every mutating method refuses with a typed
+     * `StorageReadonlyError` ("storage_readonly") instead of attempting a write.
+     * Read paths are unaffected. Default `false`.
+     */
+    readOnly?: boolean;
+}
+/** L2: a mutator refused because the store was opened read-only. */
+export declare class StorageReadonlyError extends Error {
+    readonly code = "storage_readonly";
+    constructor(operation: string);
 }
 /**
  * An append-only audit event for a subagent (DEC-071). Distinct from the

package/dist/runtime/local-files/store.d.ts.map

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

package/dist/runtime/local-files/store.js

@@ -1,11 +1,20 @@
-import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { H2A_ARTIFACT_KINDS, H2A_AUTHORITY_MATRIX, H2A_DECLARATION_INTERET_BODY_KIND, appendJournalEntry, assertValidNegotiationState, canSignArtifactKind, computeHash, createJournalEntry, deriveDecisionDossier as deriveDecisionDossierCore, derivePostureConflit, derivePostureConfiance as derivePostureConfianceCore, evaluatePresenterBias, isH2AEnvelope, validateH2AEnvelope, isH2ADeclarationInteret, validateSubagentBinding, verifyCanonical, verifyJournalChain } from "@sentropic/h2a";
 import { withLockSync } from "./locks.js";
 import { withLeaseSync } from "./lease.js";
+import { getActiveMcpTrace } from "../mcp/phase-trace.js";
 import { inboxDir, inboxDirRaw, localStorePaths, negotiationDir, negotiationJournalFile, outboxDir, outboxDirRaw, safePathSegment } from "./paths.js";
 import { H2A_STORE_SCHEMA_FILE, H2A_STORE_SCHEMA_VERSION, StoreSchemaMismatchError, readCliPackageVersion } from "./schema.js";
 import { listIdentityAliases, mergeInboxDedup } from "../identity/migration.js";
+/** L2: a mutator refused because the store was opened read-only. */
+export class StorageReadonlyError extends Error {
+    code = "storage_readonly";
+    constructor(operation) {
+        super(`storage_readonly: ${operation} refused on a read-only store`);
+        this.name = "StorageReadonlyError";
+    }
+}
 function ensureDir(path) {
     mkdirSync(path, { recursive: true });
 }
@@ -122,12 +131,32 @@ function envLeaseMs() {
 }
 export function createLocalStore(options) {
     const paths = localStorePaths(options.root);
-    ensureLayout(paths);
-    ensureSchemaSentinel(paths.root, {
-        allowVersionMismatch: options.allowVersionMismatch === true
-    });
-    if (!existsSync(paths.instances)) {
-        writeFileSync(paths.instances, "", { encoding: "utf8" });
+    const initialize = options.initialize !== false;
+    const readOnly = options.readOnly === true;
+    if (initialize) {
+        ensureLayout(paths);
+        ensureSchemaSentinel(paths.root, {
+            allowVersionMismatch: options.allowVersionMismatch === true
+        });
+        if (!existsSync(paths.instances)) {
+            writeFileSync(paths.instances, "", { encoding: "utf8" });
+        }
+    }
+    else {
+        // Non-initializing open (L2): create nothing. Only VALIDATE a sentinel that
+        // already exists — an incompatible one still fails closed (an unsupported
+        // schema is a refusal, never a silent write); an absent one is left absent.
+        if (existsSync(join(paths.root, H2A_STORE_SCHEMA_FILE))) {
+            ensureSchemaSentinel(paths.root, {
+                allowVersionMismatch: options.allowVersionMismatch === true
+            });
+        }
+    }
+    // L2 defense-in-depth: a mutator on a read-only store refuses with a typed
+    // error rather than surfacing a raw EROFS from deep in an append.
+    function assertWritable(operation) {
+        if (readOnly)
+            throw new StorageReadonlyError(operation);
     }
     const lockTimeoutMs = options.lockTimeoutMs ?? 5000;
     const lockMode = resolveLockMode(options.lockMode);
@@ -139,10 +168,28 @@ export function createLocalStore(options) {
     // is the same-machine default (DEC-036); `lease` is the cross-host primitive
     // (DEC-065) for a shared RWX store. Both share the `(path, fn, opts)` shape;
     // the lease handle arg is simply ignored by the store's sync sections.
+    // L0 passive lock instrumentation: forward the primitive's observations to
+    // the ambient MCP trace (logical lock id only — never the owner payload).
+    // Undefined trace → no observe callback is attached and behaviour is byte-for
+    // -byte identical to before. Detailed-gated so a normal CLI run adds nothing.
+    function lockObserver() {
+        const trace = getActiveMcpTrace();
+        if (!trace?.detailed)
+            return undefined;
+        return (event) => {
+            trace.phase(`lock_${event.event}`, {
+                tool: event.lock,
+                ...(event.waitMs !== undefined ? { waitMs: event.waitMs } : {}),
+                ...(event.holdMs !== undefined ? { holdMs: event.holdMs } : {})
+            });
+        };
+    }
     function lock(lockPath, fn, opts) {
-        return lockMode === "lease"
-            ? withLeaseSync(lockPath, fn, opts)
-            : withLockSync(lockPath, fn, opts);
+        if (lockMode === "lease") {
+            return withLeaseSync(lockPath, fn, opts);
+        }
+        const observe = lockObserver();
+        return withLockSync(lockPath, fn, observe ? { ...opts, observe } : opts);
     }
     const registryLock = join(paths.registry, ".lock");
     const negotiationLock = (id) => join(negotiationDir(paths, id), ".lock");
@@ -160,6 +207,25 @@ export function createLocalStore(options) {
         return Array.isArray(value) ? value : [value];
     }
     function listInstances() {
+        // L0 registry-read measurement (detailed-gated so the hot path is untouched
+        // when not tracing): the registry file size in bytes, recorded SEPARATELY
+        // from any lock hold. This is the read the identity-resolution boot performs
+        // against a large `instances.jsonl` — the candidate cause surface for T8.
+        const trace = getActiveMcpTrace();
+        if (trace?.detailed) {
+            let bytes = 0;
+            try {
+                bytes = statSync(paths.instances).size;
+            }
+            catch {
+                /* a missing/rotating registry is not a measurement failure */
+            }
+            return trace.span("registry_read", () => readJsonl(paths.instances).map((reg) => ({
+                ...reg,
+                roles: toArray(reg.roles),
+                scopes: toArray(reg.scopes)
+            })), { bytes });
+        }
         return readJsonl(paths.instances).map((reg) => ({
             ...reg,
             roles: toArray(reg.roles),
@@ -170,6 +236,7 @@ export function createLocalStore(options) {
         return listInstances().find((entry) => entry.id === id);
     }
     function registerInstance(reg) {
+        assertWritable("registerInstance");
         lock(registryLock, () => {
             if (findInstance(reg.id)) {
                 return;
@@ -201,6 +268,7 @@ export function createLocalStore(options) {
         return readJsonl(paths.keys);
     }
     function addInstanceKey(instanceId, publicKeyPem) {
+        assertWritable("addInstanceKey");
         lock(registryLock, () => {
             if (!findInstance(instanceId)) {
                 throw new Error(`Instance not registered: ${instanceId}`);
@@ -857,6 +925,7 @@ export function createLocalStore(options) {
         return out;
     }
     function putInboxMessage(actor, envelope) {
+        assertWritable("putInboxMessage");
         const validation = validateH2AEnvelope(envelope);
         if (!validation.ok) {
             throw new Error("putInboxMessage: invalid H2A envelope — " + validation.errors.join("; "));