@sentropic/h2a-runtime 0.98.7-rc.4 → 0.98.7-rc.8

package/dist/agy-claude.d.ts

@@ -1,2 +1,42 @@
-export * from "@sentropic/h2a/agy-claude";
+export declare const AGY_CLAUDE_QUOTA_CODE = "agy-claude-quota-exhausted";
+export type AgyEffort = "low" | "medium" | "high";
+export declare class AgyEffortError extends Error {
+    readonly code = "agy-effort-unsupported";
+}
+export declare function normalizeAgyEffort(effort: string | undefined): AgyEffort | undefined;
+export declare function isAgyClaudeModel(model: string | undefined): boolean;
+export declare function resolveAgyModel(model: string | undefined, effort?: string): string | undefined;
+export declare class AgyClaudeBuildOptInError extends Error {
+    readonly code = "agy-claude-build-requires-opt-in";
+}
+export declare function assertAgyClaudeBuildAllowed(options: {
+    profile: string;
+    model?: string | undefined;
+    role?: string | undefined;
+    allowClaudeBuild?: boolean | undefined;
+}): void;
+export type AgyClaudeQuotaStatus = {
+    status: "unknown" | "exhausted";
+    observedAt?: string;
+    resetsAt?: string;
+    signature?: string;
+};
+export declare function detectAgyClaudeQuotaExhaustion(output: string, now?: number): {
+    exhausted: boolean;
+    signature?: string;
+    resetsAt?: string;
+};
+export declare class AgyClaudeQuotaExhaustedError extends Error {
+    readonly signature: string;
+    readonly code = "agy-claude-quota-exhausted";
+    readonly retrySafe = false;
+    readonly retryable = false;
+    readonly quota: AgyClaudeQuotaStatus;
+    constructor(signature: string, output: string, now?: number);
+    get resetsAt(): string | undefined;
+}
+export declare function agyClaudeQuotaError(signature: string, output: string, now?: number): AgyClaudeQuotaExhaustedError;
+export declare function agyQuotaStatusPath(): string;
+export declare function readAgyClaudeQuotaStatus(path?: string): AgyClaudeQuotaStatus;
+export declare function writeAgyClaudeQuotaStatus(status: AgyClaudeQuotaStatus, path?: string): void;
 //# sourceMappingURL=agy-claude.d.ts.map

package/dist/agy-claude.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agy-claude.d.ts","sourceRoot":"","sources":["../src/agy-claude.ts"],"names":[],"mappings":"AACA,cAAc,2BAA2B,CAAC"}
+{"version":3,"file":"agy-claude.d.ts","sourceRoot":"","sources":["../src/agy-claude.ts"],"names":[],"mappings":"AAYA,eAAO,MAAM,qBAAqB,+BAA+B,CAAC;AAClE,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;AAClD,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,4BAA4B;CAC1C;AACD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAKpF;AACD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAEnE;AACD,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAU9F;AACD,qBAAa,wBAAyB,SAAQ,KAAK;IACjD,QAAQ,CAAC,IAAI,sCAAsC;CACpD;AACD,wBAAgB,2BAA2B,CAAC,OAAO,EAAE;IACnD,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,gBAAgB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAChH,GAAG,IAAI,CAOP;AACD,MAAM,MAAM,oBAAoB,GAAG;IACjC,MAAM,EAAE,SAAS,GAAG,WAAW,CAAC;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AACF,wBAAgB,8BAA8B,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,SAAa,GAAG;IAChF,SAAS,EAAE,OAAO,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC3D,CAyCA;AACD,qBAAa,4BAA6B,SAAQ,KAAK;IAKzC,QAAQ,CAAC,SAAS,EAAE,MAAM;IAJtC,QAAQ,CAAC,IAAI,gCAAyB;IACtC,QAAQ,CAAC,SAAS,SAAS;IAC3B,QAAQ,CAAC,SAAS,SAAS;IAC3B,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAC;gBAChB,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,SAAa;IAMxE,IAAI,QAAQ,IAAI,MAAM,GAAG,SAAS,CAAgC;CACnE;AACD,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,SAAa,GAAG,4BAA4B,CAErH;AACD,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AACD,wBAAgB,wBAAwB,CAAC,IAAI,SAAuB,GAAG,oBAAoB,CAU1F;AACD,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,oBAAoB,EAAE,IAAI,SAAuB,GAAG,IAAI,CAKzG"}

package/dist/agy-claude.js

@@ -1,3 +1,148 @@
-// Small shared contract; importing it must not load either CLI entry point.
-export * from "@sentropic/h2a/agy-claude";
+// AGY/Claude shared contract — VENDORED copy of
+// `packages/h2a/src/runtime/agy-claude.ts` (see agy-claude-vendor-sync.test.ts).
+// Why vendored instead of imported: this module is a leaf (node builtins
+// only) that both the runtime and the core need; a cross-package import in
+// either direction creates an undeclared edge that breaks isolated installs
+// of this package (MODULE_NOT_FOUND at host startup) or an unorderable
+// typecheck cycle. Edit the CORE copy first, then sync this file exactly
+// (the sync test fails closed on any drift).
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+export const AGY_CLAUDE_QUOTA_CODE = "agy-claude-quota-exhausted";
+export class AgyEffortError extends Error {
+    code = "agy-effort-unsupported";
+}
+export function normalizeAgyEffort(effort) {
+    if (effort === undefined)
+        return undefined;
+    if (effort === "max")
+        return "high";
+    if (effort === "low" || effort === "medium" || effort === "high")
+        return effort;
+    throw new AgyEffortError(`invalid AGY effort ${effort}; AGY effort must be low|medium|high (max maps to high)`);
+}
+export function isAgyClaudeModel(model) {
+    return model?.startsWith("claude-") ?? false;
+}
+export function resolveAgyModel(model, effort) {
+    const level = normalizeAgyEffort(effort);
+    const claude = model && /^(claude-(?:opus|sonnet)-5-5)(?:-(.*))?$/.exec(model);
+    if (claude) {
+        // Validate a supplied suffix even when a separate effort overrides it.
+        const suffix = normalizeAgyEffort(claude[2]);
+        const resolved = level ?? suffix;
+        return resolved ? `${claude[1]}-${resolved}` : model;
+    }
+    return model;
+}
+export class AgyClaudeBuildOptInError extends Error {
+    code = "agy-claude-build-requires-opt-in";
+}
+export function assertAgyClaudeBuildAllowed(options) {
+    if (options.role !== undefined && !["review", "challenge", "build"].includes(options.role)) {
+        throw new Error("invalid agy run role: expected review|challenge|build");
+    }
+    if (options.profile === "agy" && isAgyClaudeModel(options.model) && options.role === "build" && options.allowClaudeBuild !== true) {
+        throw new AgyClaudeBuildOptInError("AGY Claude credits are reserved for reviews and adversarial challenges; build requires --allow-claude-build");
+    }
+}
+export function detectAgyClaudeQuotaExhaustion(output, now = Date.now()) {
+    let preliminary = { exhausted: false };
+    const lines = output.split(/\r?\n/);
+    for (let index = 0; index < lines.length; index++) {
+        let line = lines[index];
+        // Provider diagnostics only: prose mentioning 429/quota is not evidence.
+        if (!/^\s*(?:AGY_ERROR\s*\{|(?:API )?error\s*:)/i.test(line))
+            continue;
+        let structured = /AGY_ERROR\s*(\{.*)/.exec(line)?.[1];
+        if (structured) {
+            // Native/tmux screen captures insert newlines at visual column wraps,
+            // including inside JSON strings. Reassemble only an anchored diagnostic,
+            // require complete JSON, and never consume the next provider diagnostic.
+            let end = index;
+            for (;;) {
+                try {
+                    JSON.parse(structured);
+                    break;
+                }
+                catch {
+                    const next = lines[end + 1];
+                    if (next === undefined || /^\s*(?:AGY_ERROR\s*\{|(?:API )?error\s*:)/i.test(next))
+                        break;
+                    structured += next;
+                    end++;
+                }
+            }
+            try {
+                JSON.parse(structured);
+            }
+            catch {
+                continue;
+            } // Partial chunks still prove no complete reset.
+            line = `AGY_ERROR ${structured}`;
+            index = end;
+        }
+        let signature;
+        if (/\b429\b/.test(line))
+            signature = "agy-claude:http-429";
+        else if (/RESOURCE_EXHAUSTED/i.test(line))
+            signature = "agy-claude:resource-exhausted";
+        else if (/quota (?:exceeded|reached)|individual quota/i.test(line))
+            signature = "agy-claude:quota-exceeded";
+        if (!signature)
+            continue;
+        const duration = /Resets in\s+((?:\d+(?:\.\d+)?\s*[dhms]\s*)+)/i.exec(line)?.[1];
+        let ms = 0;
+        if (duration)
+            for (const part of duration.matchAll(/(\d+(?:\.\d+)?)\s*([dhms])/gi)) {
+                ms += Number(part[1]) * ({ d: 86_400_000, h: 3_600_000, m: 60_000, s: 1_000 }[part[2].toLowerCase()] ?? 0);
+            }
+        const resetsAt = duration && Number.isFinite(now + ms) && ms < 8.64e15 - now
+            ? new Date(now + ms).toISOString() : undefined;
+        if (resetsAt)
+            return { exhausted: true, signature, resetsAt };
+        preliminary = { exhausted: true, signature };
+    }
+    return preliminary;
+}
+export class AgyClaudeQuotaExhaustedError extends Error {
+    signature;
+    code = AGY_CLAUDE_QUOTA_CODE;
+    retrySafe = false;
+    retryable = false;
+    quota;
+    constructor(signature, output, now = Date.now()) {
+        super("AGY Claude quota exhausted; no fallback or automatic retry. The caller chooses the next action.");
+        this.signature = signature;
+        const detected = detectAgyClaudeQuotaExhaustion(output, now);
+        this.quota = { status: "exhausted", signature, observedAt: new Date(now).toISOString(),
+            ...(detected.resetsAt ? { resetsAt: detected.resetsAt } : {}) };
+    }
+    get resetsAt() { return this.quota.resetsAt; }
+}
+export function agyClaudeQuotaError(signature, output, now = Date.now()) {
+    return new AgyClaudeQuotaExhaustedError(signature, output, now);
+}
+export function agyQuotaStatusPath() {
+    return join(process.env.XDG_STATE_HOME ?? join(homedir(), ".local", "state"), "h2a", "agy-claude-quota.json");
+}
+export function readAgyClaudeQuotaStatus(path = agyQuotaStatusPath()) {
+    try {
+        const value = JSON.parse(readFileSync(path, "utf8"));
+        if (value.status === "exhausted" && typeof value.observedAt === "string" && Number.isFinite(Date.parse(value.observedAt))) {
+            return { status: value.status, observedAt: value.observedAt,
+                ...(typeof value.signature === "string" ? { signature: value.signature } : {}),
+                ...(typeof value.resetsAt === "string" && Number.isFinite(Date.parse(value.resetsAt)) ? { resetsAt: value.resetsAt } : {}) };
+        }
+    }
+    catch { /* No provider observation: never invent availability. */ }
+    return { status: "unknown" };
+}
+export function writeAgyClaudeQuotaStatus(status, path = agyQuotaStatusPath()) {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const temporary = `${path}.${process.pid}.tmp`;
+    writeFileSync(temporary, JSON.stringify(status), { mode: 0o600 });
+    renameSync(temporary, path);
+}
 //# sourceMappingURL=agy-claude.js.map

package/dist/agy-claude.js.map

@@ -1 +1 @@
-{"version":3,"file":"agy-claude.js","sourceRoot":"","sources":["../src/agy-claude.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,cAAc,2BAA2B,CAAC"}
+{"version":3,"file":"agy-claude.js","sourceRoot":"","sources":["../src/agy-claude.ts"],"names":[],"mappings":"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"}

package/dist/central-mcp.d.ts

@@ -1,3 +1,17 @@
+type CentralMarker = Readonly<{
+    endpoint: string;
+    generation: string;
+    pid: number;
+    startedAt: string;
+}>;
+type CentralPing = Readonly<{
+    kind: "generation";
+    generation: string;
+}> | Readonly<{
+    kind: "dead";
+}> | Readonly<{
+    kind: "ambiguous";
+}>;
 export type CentralMcpPreparation = Readonly<{
     status: "central";
     endpoint: string;
@@ -6,6 +20,20 @@ export type CentralMcpPreparation = Readonly<{
     status: "degraded";
     reason: string;
 }>;
+/** Test seam mirroring the core marker-path options. Production always uses
+ *  `/run/user/<uid>`; the path is never env-derived. */
+export interface CentralMcpPaths {
+    readonly runtimeBase?: string;
+}
+export declare const H2A_MCP_CENTRAL_ENV = "H2A_MCP_CENTRAL";
+export declare const H2A_MCP_CENTRAL_ENDPOINT_ENV = "H2A_MCP_CENTRAL_ENDPOINT";
+export declare function centralMcpPing(endpoint: string, timeoutMs?: number): Promise<CentralPing>;
+/**
+ * Read the protected central marker without exposing its token to callers
+ * that only need liveness/generation metadata. A missing marker is the sole
+ * non-error absence case; malformed or insecure state remains a hard failure.
+ */
+export declare function readCentralMcpMarker(paths?: CentralMcpPaths): CentralMarker | undefined;
 /** Raw (unstructured) central MCP server output. Read by `h2a logs`, rotated at spawn. */
 export declare function resolveCentralMcpLogPath(): string;
 /**
@@ -15,6 +43,7 @@ export declare function resolveCentralMcpLogPath(): string;
  */
 export declare function ensureCentralMcp(options?: Readonly<{
     root?: string;
+    paths?: CentralMcpPaths;
 }>): Promise<Readonly<{
     endpoint: string;
     generation: string;
@@ -24,9 +53,12 @@ export declare function prepareCentralMcpForLaunch(options: Readonly<{
     root?: string;
     profile: string;
     cwd: string;
+    paths?: CentralMcpPaths;
 }>): Promise<CentralMcpPreparation | undefined>;
 /** Restore launches inherit these values; each re-entered run rewrites its host config. */
 export declare function prepareCentralMcpForRestore(options?: Readonly<{
     root?: string;
+    paths?: CentralMcpPaths;
 }>): Promise<CentralMcpPreparation | undefined>;
+export {};
 //# sourceMappingURL=central-mcp.d.ts.map

package/dist/central-mcp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"central-mcp.d.ts","sourceRoot":"","sources":["../src/central-mcp.ts"],"names":[],"mappings":"AA4DA,MAAM,MAAM,qBAAqB,GAC7B,QAAQ,CAAC;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,GACrE,QAAQ,CAAC;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAuDrD,0FAA0F;AAC1F,wBAAgB,wBAAwB,IAAI,MAAM,CAEjD;AAuFD;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,GAAE,QAAQ,CAAC;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAM,GACxC,OAAO,CAAC,QAAQ,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,SAAS,CAAC,CA6DzE;AA+ED,mFAAmF;AACnF,wBAAsB,0BAA0B,CAAC,OAAO,EAAE,QAAQ,CAAC;IACjE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;CACb,CAAC,GAAG,OAAO,CAAC,qBAAqB,GAAG,SAAS,CAAC,CAiC9C;AAED,2FAA2F;AAC3F,wBAAsB,2BAA2B,CAC/C,OAAO,GAAE,QAAQ,CAAC;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAM,GACxC,OAAO,CAAC,qBAAqB,GAAG,SAAS,CAAC,CAU5C"}
+{"version":3,"file":"central-mcp.d.ts","sourceRoot":"","sources":["../src/central-mcp.ts"],"names":[],"mappings":"AA0CA,KAAK,aAAa,GAAG,QAAQ,CAAC;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC,CAAC;AAEH,KAAK,WAAW,GACZ,QAAQ,CAAC;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,GACpD,QAAQ,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,GAC1B,QAAQ,CAAC;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,CAAC,CAAC;AAEpC,MAAM,MAAM,qBAAqB,GAC7B,QAAQ,CAAC;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,GACrE,QAAQ,CAAC;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAMrD;wDACwD;AACxD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAID,eAAO,MAAM,mBAAmB,oBAAoB,CAAC;AACrD,eAAO,MAAM,4BAA4B,6BAA6B,CAAC;AA0DvE,wBAAsB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,SAA8B,GAAG,OAAO,CAAC,WAAW,CAAC,CAyBpH;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,GAAE,eAAoB,GAAG,aAAa,GAAG,SAAS,CAuC3F;AA4BD,0FAA0F;AAC1F,wBAAgB,wBAAwB,IAAI,MAAM,CAEjD;AAuFD;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,GAAE,QAAQ,CAAC;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,eAAe,CAAA;CAAE,CAAM,GACjE,OAAO,CAAC,QAAQ,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,SAAS,CAAC,CA6DzE;AAoFD,mFAAmF;AACnF,wBAAsB,0BAA0B,CAAC,OAAO,EAAE,QAAQ,CAAC;IACjE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,eAAe,CAAC;CACzB,CAAC,GAAG,OAAO,CAAC,qBAAqB,GAAG,SAAS,CAAC,CAyB9C;AAED,2FAA2F;AAC3F,wBAAsB,2BAA2B,CAC/C,OAAO,GAAE,QAAQ,CAAC;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,eAAe,CAAA;CAAE,CAAM,GACjE,OAAO,CAAC,qBAAqB,GAAG,SAAS,CAAC,CAU5C"}

package/dist/central-mcp.js

@@ -1,11 +1,20 @@
 /**
- * Runtime-side central MCP lifecycle. The core package remains the sole owner
- * of marker validation, reclaim, and server startup; this module only selects
- * a persisted endpoint, asks core for protected liveness facts, and starts the
- * existing foreground command as a detached child when necessary.
+ * Runtime-side central MCP lifecycle. This module owns its end of the
+ * central contract: endpoint selection, marker read/validation, HTTP
+ * liveness ping, and starting the existing foreground serve command as a
+ * detached child when necessary. It deliberately never names the core
+ * package: host-config rendering stays a core command invoked over the
+ * `h2a` binary (the same spawn pattern used for `mcp-central-serve`
+ * below), so isolated installs of this package keep working and degrade
+ * cleanly where core is absent.
+ *
+ * Cross-package constants below (env names, marker directory/file, ping
+ * path, file mode) mirror the core contract values. They are pinned by the
+ * vitest suite in this directory, which exercises them against real
+ * markers and a real HTTP peer.
  */
-import { spawn } from "node:child_process";
-import { chmodSync, closeSync, constants, existsSync, mkdirSync, openSync, readFileSync, readSync, renameSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { spawn, spawnSync } from "node:child_process";
+import { chmodSync, closeSync, constants, existsSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, renameSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { getH2aConfig, resolveConfigPath, setH2aConfig } from "./config.js";
@@ -14,24 +23,135 @@ const CENTRAL_PORT_BASE = 47_000;
 const CENTRAL_PORT_SPAN = 10_000;
 const CENTRAL_START_TIMEOUT_MS = 10_000;
 const CENTRAL_START_POLL_MS = 100;
-let coreCentralMcp;
-function loadCoreCentralMcp() {
-    // Keep the core/runtime boundary dynamic. Core already reaches runtime via a
-    // string-specifier seam for central marker ownership checks, so a static
-    // runtime dependency here would turn that boundary into a hard cycle.
-    const corePackage = "@sentropic/h2a";
-    coreCentralMcp ??= import(corePackage).then((core) => {
-        const candidate = core;
-        if (typeof candidate.H2A_MCP_CENTRAL_ENV !== "string" ||
-            typeof candidate.H2A_MCP_CENTRAL_ENDPOINT_ENV !== "string" ||
-            typeof candidate.centralMcpPing !== "function" ||
-            typeof candidate.readCentralMcpMarker !== "function" ||
-            typeof candidate.runCli !== "function") {
-            throw new Error("@sentropic/h2a does not expose the central MCP runtime surface");
+// Stable cross-package contract values (mirrored from core; pinned by the
+// vitest suite in this directory against real markers and a real HTTP peer).
+export const H2A_MCP_CENTRAL_ENV = "H2A_MCP_CENTRAL";
+export const H2A_MCP_CENTRAL_ENDPOINT_ENV = "H2A_MCP_CENTRAL_ENDPOINT";
+const CENTRAL_RUNTIME_DIRECTORY = "h2a-mcp-central";
+const CENTRAL_MARKER_FILE = "marker.json";
+const CENTRAL_PING_PATH = "/_h2a-central/ping";
+const CENTRAL_LIVENESS_TIMEOUT_MS = 1_500;
+const CENTRAL_HOST_SETUP_TIMEOUT_MS = 60_000;
+function currentUid() {
+    if (typeof process.getuid !== "function") {
+        throw new Error(`${H2A_MCP_CENTRAL_ENDPOINT_ENV} requires a current uid`);
+    }
+    return process.getuid();
+}
+function centralMcpMarkerPath(paths = {}) {
+    const base = paths.runtimeBase ?? join("/run/user", String(currentUid()));
+    return join(base, CENTRAL_RUNTIME_DIRECTORY, CENTRAL_MARKER_FILE);
+}
+function isLoopbackHostname(hostname) {
+    return hostname === "127.0.0.1" || hostname === "::1" || hostname === "[::1]" || hostname === "localhost";
+}
+function parseCentralMcpEndpoint(value) {
+    if (!value || value.trim().length === 0) {
+        throw new Error(`${H2A_MCP_CENTRAL_ENDPOINT_ENV} must be a non-empty absolute http URL`);
+    }
+    let endpoint;
+    try {
+        endpoint = new URL(value);
+    }
+    catch {
+        throw new Error(`${H2A_MCP_CENTRAL_ENDPOINT_ENV} must be a non-empty absolute http URL`);
+    }
+    if (endpoint.protocol !== "http:" ||
+        !isLoopbackHostname(endpoint.hostname) ||
+        !endpoint.port ||
+        Number(endpoint.port) < 1 ||
+        Number(endpoint.port) > 65_535 ||
+        endpoint.username ||
+        endpoint.password ||
+        endpoint.search ||
+        endpoint.hash) {
+        throw new Error(`${H2A_MCP_CENTRAL_ENDPOINT_ENV} must be an absolute http URL with an explicit port`);
+    }
+    return endpoint.href;
+}
+function errorHasCode(error, expectedCode) {
+    let current = error;
+    for (let depth = 0; depth < 4 && current && typeof current === "object"; depth += 1) {
+        if (current.code === expectedCode)
+            return true;
+        current = current.cause;
+    }
+    return false;
+}
+export async function centralMcpPing(endpoint, timeoutMs = CENTRAL_LIVENESS_TIMEOUT_MS) {
+    const canonicalEndpoint = parseCentralMcpEndpoint(endpoint);
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    const pingUrl = new URL(CENTRAL_PING_PATH, canonicalEndpoint).href;
+    return fetch(pingUrl, { signal: controller.signal }).then(async (response) => {
+        clearTimeout(timeout);
+        if (!response.ok)
+            return { kind: "dead" };
+        try {
+            const body = (await response.json());
+            return typeof body.generation === "string" && body.generation.length > 0
+                ? { kind: "generation", generation: body.generation }
+                : { kind: "dead" };
         }
-        return candidate;
+        catch {
+            return { kind: "dead" };
+        }
+    }, (error) => {
+        clearTimeout(timeout);
+        // ECONNREFUSED is the only transport failure that positively proves no
+        // listener owns this registration. Timeouts and all other errors are not.
+        return (errorHasCode(error, "ECONNREFUSED") ? { kind: "dead" } : { kind: "ambiguous" });
     });
-    return coreCentralMcp;
+}
+/**
+ * Read the protected central marker without exposing its token to callers
+ * that only need liveness/generation metadata. A missing marker is the sole
+ * non-error absence case; malformed or insecure state remains a hard failure.
+ */
+export function readCentralMcpMarker(paths = {}) {
+    const path = centralMcpMarkerPath(paths);
+    let info;
+    try {
+        info = lstatSync(path);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+    if (!info.isFile())
+        throw new Error(`central MCP marker is not a regular file: ${path}`);
+    if (info.uid !== currentUid())
+        throw new Error(`central MCP marker is not owned by the current user: ${path}`);
+    if ((info.mode & 0o777) !== 0o600)
+        throw new Error(`central MCP marker must have mode 0600: ${path}`);
+    let value;
+    try {
+        value = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        throw new Error(`central MCP marker is malformed: ${path}`);
+    }
+    if (typeof value.endpoint !== "string" ||
+        typeof value.generation !== "string" ||
+        value.generation.length === 0 ||
+        typeof value.pid !== "number" ||
+        typeof value.startedAt !== "string" ||
+        typeof value.token !== "string" ||
+        value.token.length === 0) {
+        throw new Error(`central MCP marker is malformed: ${path}`);
+    }
+    try {
+        return {
+            endpoint: parseCentralMcpEndpoint(value.endpoint),
+            generation: value.generation,
+            pid: value.pid,
+            startedAt: value.startedAt,
+        };
+    }
+    catch {
+        throw new Error(`central MCP marker is malformed: ${path}`);
+    }
 }
 function delay(milliseconds) {
     return new Promise((resolve) => setTimeout(resolve, milliseconds));
@@ -127,7 +247,7 @@ function centralLogFile() {
     catch { /* rotation is best-effort; the spawn below still proceeds */ }
     return path;
 }
-async function waitForCentralStart(core, endpoint, spawnFailure) {
+async function waitForCentralStart(paths, endpoint, spawnFailure) {
     const deadline = Date.now() + CENTRAL_START_TIMEOUT_MS;
     while (Date.now() < deadline) {
         const failure = spawnFailure();
@@ -136,9 +256,9 @@ async function waitForCentralStart(core, endpoint, spawnFailure) {
             appendCrashLog("mcp-server", { event: "startupError", reason: "spawn-failed", detail: failure.message });
             throw failure;
         }
-        const ping = await core.centralMcpPing(endpoint, CENTRAL_START_POLL_MS);
+        const ping = await centralMcpPing(endpoint, CENTRAL_START_POLL_MS);
         if (ping.kind === "generation") {
-            const marker = core.readCentralMcpMarker();
+            const marker = readCentralMcpMarker(paths);
             if (marker?.endpoint === endpoint && marker.generation === ping.generation) {
                 return { endpoint, generation: ping.generation };
             }
@@ -159,10 +279,10 @@ export async function ensureCentralMcp(options = {}) {
     const endpoint = configuredCentralEndpoint();
     if (!endpoint)
         return undefined;
-    const core = await loadCoreCentralMcp();
-    const marker = core.readCentralMcpMarker();
+    const paths = options.paths ?? {};
+    const marker = readCentralMcpMarker(paths);
     if (marker) {
-        const ping = await core.centralMcpPing(marker.endpoint);
+        const ping = await centralMcpPing(marker.endpoint);
         if (ping.kind === "ambiguous") {
             appendCrashLog("mcp-server", { event: "refusal", instanceId: marker.generation, reason: "ambiguous-liveness", detail: marker.endpoint });
             throw new Error(`central MCP liveness at ${marker.endpoint} is ambiguous; refusing to start another server`);
@@ -185,8 +305,8 @@ export async function ensureCentralMcp(options = {}) {
             stdio: ["ignore", logFd, logFd],
             env: {
                 ...process.env,
-                [core.H2A_MCP_CENTRAL_ENV]: "1",
-                [core.H2A_MCP_CENTRAL_ENDPOINT_ENV]: endpoint,
+                [H2A_MCP_CENTRAL_ENV]: "1",
+                [H2A_MCP_CENTRAL_ENDPOINT_ENV]: endpoint,
             },
         });
         child.once("error", (error) => {
@@ -211,7 +331,7 @@ export async function ensureCentralMcp(options = {}) {
     finally {
         closeSync(logFd);
     }
-    return waitForCentralStart(core, endpoint, () => spawnError);
+    return waitForCentralStart(paths, endpoint, () => spawnError);
 }
 function profileMcpConfig(profile, cwd) {
     switch (profile) {
@@ -235,33 +355,9 @@ function profileMcpConfig(profile, cwd) {
             return undefined;
     }
 }
-function coherentHostSetupReport(host) {
-    return {
-        ok: true,
-        repair: false,
-        dryRun: false,
-        sessionFreshnessGuarantee: "runtime central MCP writer",
-        nativeCommandFailureLimit: "runtime central MCP writer",
-        version: "runtime-central-mcp",
-        hosts: [{
-                host,
-                ok: true,
-                findings: [],
-                diagnostics: [],
-                changed: [],
-                preserved: [],
-                failures: [],
-                unverifiable: [],
-                unrepaired: [],
-                coherencePaths: [],
-                plannedActions: [],
-                repairMarkerPath: "",
-            }],
-    };
-}
-function activateCentralMcpEnvironment(core, endpoint) {
-    process.env[core.H2A_MCP_CENTRAL_ENV] = "1";
-    process.env[core.H2A_MCP_CENTRAL_ENDPOINT_ENV] = endpoint;
+function activateCentralMcpEnvironment(endpoint) {
+    process.env[H2A_MCP_CENTRAL_ENV] = "1";
+    process.env[H2A_MCP_CENTRAL_ENDPOINT_ENV] = endpoint;
 }
 function deactivateCentralMcpEnvironment() {
     delete process.env.H2A_MCP_CENTRAL;
@@ -284,25 +380,46 @@ function restoreHostConfig(path, snapshot) {
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
+/**
+ * Render the host config through the core CLI over the `h2a` binary (never an
+ * in-process core import). Output stays captured (quiet launch path); a
+ * nonzero exit degrades to the per-session sidecar exactly like before. The
+ * real installation doctor runs here instead of the former always-ok stub, so
+ * a genuinely incoherent host setup now surfaces as degraded-with-reason
+ * rather than a masked central — still fail-closed, never a crash.
+ */
+function writeHostConfig(target, cwd) {
+    let status = null;
+    let spawnError;
+    try {
+        const result = spawnSync("h2a", ["host", "setup", "--host", target.host, "--write", target.path], { cwd, stdio: "pipe", encoding: "utf8", timeout: CENTRAL_HOST_SETUP_TIMEOUT_MS });
+        status = result.status;
+        spawnError = result.error;
+    }
+    catch (error) {
+        spawnError = error instanceof Error ? error : new Error(String(error));
+    }
+    if (status !== 0) {
+        throw new Error(`central MCP could not write the ${target.host} host config at ${target.path}` +
+            (spawnError ? ` (${spawnError.message})` : ""));
+    }
+}
 /** Ensure central MCP and rewrite the launched host's existing MCP config path. */
 export async function prepareCentralMcpForLaunch(options) {
     let hostConfig;
     try {
-        const central = await ensureCentralMcp({ ...(options.root ? { root: options.root } : {}) });
+        const central = await ensureCentralMcp({
+            ...(options.root ? { root: options.root } : {}),
+            ...(options.paths ? { paths: options.paths } : {}),
+        });
         if (!central)
             return undefined;
-        const core = await loadCoreCentralMcp();
         const target = profileMcpConfig(options.profile, options.cwd);
         if (target)
             hostConfig = { path: target.path, snapshot: captureHostConfig(target.path) };
-        activateCentralMcpEnvironment(core, central.endpoint);
-        if (target) {
-            const quiet = { stdout: { write: () => true }, stderr: { write: () => true }, cwd: () => options.cwd };
-            const code = core.runCli(["host", "setup", "--host", target.host, "--write", target.path], quiet, { doctorHostInstallations: () => coherentHostSetupReport(target.host) });
-            if (code !== 0) {
-                throw new Error(`central MCP could not write the ${target.host} host config at ${target.path}`);
-            }
-        }
+        activateCentralMcpEnvironment(central.endpoint);
+        if (target)
+            writeHostConfig(target, options.cwd);
         return { status: "central", ...central };
     }
     catch (error) {
@@ -325,7 +442,7 @@ export async function prepareCentralMcpForRestore(options = {}) {
         const central = await ensureCentralMcp(options);
         if (!central)
             return undefined;
-        activateCentralMcpEnvironment(await loadCoreCentralMcp(), central.endpoint);
+        activateCentralMcpEnvironment(central.endpoint);
         return { status: "central", ...central };
     }
     catch (error) {