@fffattiger/pix-cli 0.1.0

package/dist/log.js

@@ -0,0 +1,12 @@
+/**
+ * Single brand namespace for all user-visible CLI output. Every line is
+ * prefixed `[pix]` so logs/errors are unambiguous regardless of which process
+ * emitted them.
+ */
+export function pixLog(message) {
+    console.log(`[pix] ${message}`);
+}
+export function pixErr(message) {
+    console.error(`[pix] ${message}`);
+}
+//# sourceMappingURL=log.js.map

package/dist/log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.js","sourceRoot":"","sources":["../src/log.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,UAAU,MAAM,CAAC,OAAe;IACpC,OAAO,CAAC,GAAG,CAAC,SAAS,OAAO,EAAE,CAAC,CAAC;AAClC,CAAC;AAED,MAAM,UAAU,MAAM,CAAC,OAAe;IACpC,OAAO,CAAC,KAAK,CAAC,SAAS,OAAO,EAAE,CAAC,CAAC;AACpC,CAAC"}

package/dist/paths.d.ts

@@ -0,0 +1,29 @@
+/** Environment variable overriding the Vite client dist location. */
+export declare const CLIENT_DIST_ENV = "PIX_CLIENT_DIST";
+/**
+ * Locate the pix workspace root by walking up from `fromUrl` until a manifest
+ * declares the `packages/*` workspace. Robust to the CLI being reached from
+ * `dist/`, `dist-test/`, or a bin shim, so client-dist resolution never depends
+ * on the process cwd.
+ */
+export declare function resolveWorkspaceRoot(fromUrl?: string): string;
+/**
+ * Locate the pix-cli package root (the directory holding `bin/` and this
+ * package's manifest). Used to spawn the sibling `pix-sessiond` bin reliably.
+ */
+export declare function resolveCliPackageRoot(fromUrl?: string): string;
+/**
+ * Resolve the absolute path to the built Vite client dist. Precedence:
+ *   1. `PIX_CLIENT_DIST`
+ *   2. `<workspace-root>/packages/client/dist` (workspace source layout)
+ *   3. `<cli-package-root>/client` (REL1 self-contained bundle: the built
+ *      Vite dist is shipped inside the release tarball so `pix start` serves
+ *      the UI from a standalone `npm i -g` install with no workspace root)
+ *
+ * Fails closed when `index.html` is absent so the host never silently serves an
+ * empty document root. Returns an absolute path.
+ */
+export declare function resolveClientDist(): string;
+/** Path to the foreground `pix-sessiond` bin, resolved from this package. */
+export declare function resolveSessiondBin(): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAIA,qEAAqE;AACrE,eAAO,MAAM,eAAe,oBAAoB,CAAC;AAwBjD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,MAAwB,GAAG,MAAM,CAU9E;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,GAAE,MAAwB,GAAG,MAAM,CAa/E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CA+B1C;AAED,6EAA6E;AAC7E,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C"}

package/dist/paths.js

@@ -0,0 +1,100 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+/** Environment variable overriding the Vite client dist location. */
+export const CLIENT_DIST_ENV = "PIX_CLIENT_DIST";
+function readManifest(path) {
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+function isWorkspaceRoot(dir) {
+    const manifest = readManifest(join(dir, "package.json"));
+    return (manifest !== undefined &&
+        Array.isArray(manifest.workspaces) &&
+        manifest.workspaces.some((p) => p === "packages/*"));
+}
+/**
+ * Locate the pix workspace root by walking up from `fromUrl` until a manifest
+ * declares the `packages/*` workspace. Robust to the CLI being reached from
+ * `dist/`, `dist-test/`, or a bin shim, so client-dist resolution never depends
+ * on the process cwd.
+ */
+export function resolveWorkspaceRoot(fromUrl = import.meta.url) {
+    let dir = dirname(fileURLToPath(fromUrl));
+    while (true) {
+        if (isWorkspaceRoot(dir))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir) {
+            throw new Error("[pix] could not locate pix workspace root");
+        }
+        dir = parent;
+    }
+}
+/**
+ * Locate the pix-cli package root (the directory holding `bin/` and this
+ * package's manifest). Used to spawn the sibling `pix-sessiond` bin reliably.
+ */
+export function resolveCliPackageRoot(fromUrl = import.meta.url) {
+    let dir = dirname(fileURLToPath(fromUrl));
+    while (true) {
+        const manifest = readManifest(join(dir, "package.json"));
+        if (manifest?.name === "@fffattiger/pix-cli" && existsSync(join(dir, "bin"))) {
+            return dir;
+        }
+        const parent = dirname(dir);
+        if (parent === dir) {
+            throw new Error("[pix] could not locate pix-cli package root");
+        }
+        dir = parent;
+    }
+}
+/**
+ * Resolve the absolute path to the built Vite client dist. Precedence:
+ *   1. `PIX_CLIENT_DIST`
+ *   2. `<workspace-root>/packages/client/dist` (workspace source layout)
+ *   3. `<cli-package-root>/client` (REL1 self-contained bundle: the built
+ *      Vite dist is shipped inside the release tarball so `pix start` serves
+ *      the UI from a standalone `npm i -g` install with no workspace root)
+ *
+ * Fails closed when `index.html` is absent so the host never silently serves an
+ * empty document root. Returns an absolute path.
+ */
+export function resolveClientDist() {
+    const override = process.env[CLIENT_DIST_ENV];
+    if (override !== undefined && override.length > 0) {
+        if (!existsSync(join(override, "index.html"))) {
+            throw new Error(`[pix] client dist not found (index.html missing): ${override}\n` +
+                "[pix] build the client first: npm run build");
+        }
+        return resolve(override);
+    }
+    // Workspace source layout: <workspace-root>/packages/client/dist. Missing or
+    // absent workspace root falls through to the bundle layout below.
+    try {
+        const workspaceCandidate = join(resolveWorkspaceRoot(), "packages", "client", "dist");
+        if (existsSync(join(workspaceCandidate, "index.html"))) {
+            return resolve(workspaceCandidate);
+        }
+    }
+    catch {
+        // no workspace root (standalone REL1 bundle install) — fall through
+    }
+    // REL1 bundle layout: <cli-package-root>/client (built Vite dist shipped in
+    // the self-contained release tarball).
+    const bundleCandidate = join(resolveCliPackageRoot(), "client");
+    if (!existsSync(join(bundleCandidate, "index.html"))) {
+        throw new Error(`[pix] client dist not found (index.html missing): ${bundleCandidate}\n` +
+            "[pix] build the client first: npm run build (or set PIX_CLIENT_DIST)");
+    }
+    return resolve(bundleCandidate);
+}
+/** Path to the foreground `pix-sessiond` bin, resolved from this package. */
+export function resolveSessiondBin() {
+    return join(resolveCliPackageRoot(), "bin", "pix-sessiond.mjs");
+}
+//# sourceMappingURL=paths.js.map

package/dist/paths.js.map

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

package/dist/probe.d.ts

@@ -0,0 +1,97 @@
+import { type SessiondBuildIncompatibilityReason } from "@fffattiger/pix-protocol";
+import type { SessiondProbe } from "@fffattiger/pix-host";
+import type { SessiondPaths } from "@fffattiger/pix-sessiond/control";
+/**
+ * Ping a sessiond instance over its local RPC socket. Returns a boolean —
+ * never throws — because callers (readiness polling, capability probes, status)
+ * only need to know reachability, not the failure reason.
+ */
+export declare function pingSessiond(endpoint: string, secret: string, timeoutMs?: number): Promise<boolean>;
+/**
+ * Why a daemon's protocol version could not be positively verified. `timeout`
+ * and `unreachable` are transient (retryable); `auth` and `malformed` are fixed
+ * problems an operator must resolve; `unsupported_version` is a positively
+ * authenticated but unsupported protocol version (future major, version 0, or
+ * any other value) that MUST be preserved — it is never replaceable. In EVERY
+ * state the running daemon must be preserved — an unverified daemon is never
+ * shut down or replaced.
+ */
+export type UnverifiableReason = "timeout" | "auth" | "malformed" | "unreachable" | "unsupported_version" | "unknown";
+/**
+ * The ONLY protocol version that may be shut down/replaced via the narrow
+ * legacy (v1) control envelope. `knownLegacy` is EXACTLY this version and no
+ * other: a future protocol version (e.g. 3 when current is 2), version 0, or
+ * any other unsupported numeric is never replaceable via the v1-only control
+ * path and is classified unverifiable (preserved).
+ */
+export declare const LEGACY_PROTOCOL_VERSION: 1;
+/**
+ * Explicit sessiond compatibility state (Protocol v2 stale-daemon safety +
+ * Phase 7A build fence).
+ *
+ * - `current`: a POSITIVELY authenticated `system.hello` returned the current
+ *   protocol version AND a build identity that passes the explicit Phase 7A
+ *   compatibility matrix (product, protocol, sessiond/Worker/adapter contract
+ *   generations, capability fingerprint — see
+ *   `packages/protocol/src/build.ts`) ⇒ the daemon may be reused as-is.
+ * - `staleBuild`: a POSITIVELY authenticated current-protocol daemon whose
+ *   build identity is missing (pre-fence build) or fails the matrix. The SAME
+ *   protocol major does NOT mean implementation compatible, so the daemon is
+ *   never silently reused; it MAY be replaced — but only through the
+ *   authenticated, instance-fenced shutdown path, never via a PID signal.
+ * - `knownLegacy`: a POSITIVELY authenticated `system.hello` (over the narrow
+ *   legacy envelope, since the current client cannot parse a v1 response)
+ *   returned EXACTLY {@link LEGACY_PROTOCOL_VERSION} (v1) ⇒ the daemon is stale
+ *   and MAY be shut down/replaced — but only through the authenticated,
+ *   instance-fenced shutdown path, never via a PID signal.
+ * - `unverifiable`: the daemon is NOT positively authenticated as current,
+ *   staleBuild, or knownLegacy — transient hello timeout, auth failure,
+ *   malformed/unparseable response (including a hello carrying a MALFORMED
+ *   build block, which fails the strict hello schema), unreachable, or a
+ *   positively authenticated but UNSUPPORTED version (future major / 0 /
+ *   other numeric). The daemon MUST be preserved; callers return a retryable
+ *   or fixed operator error instead of touching authority.
+ */
+export type SessiondCompatibility = {
+    state: "current";
+} | {
+    state: "staleBuild";
+    reason: SessiondBuildIncompatibilityReason;
+} | {
+    state: "knownLegacy";
+    version: number;
+} | {
+    state: "unverifiable";
+    reason: UnverifiableReason;
+};
+/**
+ * Resolve the explicit sessiond compatibility state via authenticated
+ * `system.hello`. Protocol v2 stale-daemon safety + the Phase 7A build fence:
+ * this is the ONE place the CLI decides whether a running daemon is current,
+ * stale-build, known-legacy, or unverifiable, so `ensureSessiond` can reuse,
+ * replace, or preserve authority without ever guessing. Never throws.
+ */
+export declare function probeSessiondCompatibility(endpoint: string, secret: string, timeoutMs?: number): Promise<SessiondCompatibility>;
+/**
+ * Resolve the authenticated protocol version of a sessiond via `system.hello`.
+ * Returns the daemon's negotiated protocolVersion, or undefined when it cannot
+ * be positively verified (auth / timeout / unreachable / malformed). Protocol
+ * v2 stale-daemon safety: callers use this to refuse silently reusing a
+ * pingable v1 daemon. The raw version is never echoed into an operator-facing
+ * error.
+ */
+export declare function helloProtocolVersion(endpoint: string, secret: string, timeoutMs?: number): Promise<number | undefined>;
+/** True only when the authenticated daemon is POSITIVELY current. */
+export declare function isProtocolCurrent(endpoint: string, secret: string, timeoutMs?: number): Promise<boolean>;
+/** Authenticated reachability probe for the one supported stale protocol. */
+export declare function pingLegacyV1Sessiond(endpoint: string, secret: string, timeoutMs?: number): Promise<boolean>;
+/** Authenticated, instance-fenced shutdown for the one supported stale protocol. */
+export declare function shutdownLegacyV1Sessiond(endpoint: string, secret: string, instanceId: string, timeoutMs?: number): Promise<boolean>;
+/**
+ * Build a host {@link SessiondProbe} backed by a real RPC ping against the
+ * resolved sessiond socket. The probe reads the secret read-only; when no
+ * secret exists yet it reports unavailable rather than throwing, so /v1/health
+ * stays honest while a daemon is mid-bootstrap.
+ */
+export declare function createSessiondProbe(paths: SessiondPaths): SessiondProbe;
+//# sourceMappingURL=probe.d.ts.map

package/dist/probe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"probe.d.ts","sourceRoot":"","sources":["../src/probe.ts"],"names":[],"mappings":"AAIA,OAAO,EAAoE,KAAK,kCAAkC,EAAE,MAAM,0BAA0B,CAAC;AACrJ,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AAGtE;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,SAAS,SAAQ,GAChB,OAAO,CAAC,OAAO,CAAC,CAQlB;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,kBAAkB,GAC1B,SAAS,GACT,MAAM,GACN,WAAW,GACX,aAAa,GACb,qBAAqB,GACrB,SAAS,CAAC;AAEd;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,EAAG,CAAU,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,MAAM,qBAAqB,GAC7B;IAAE,KAAK,EAAE,SAAS,CAAA;CAAE,GACpB;IAAE,KAAK,EAAE,YAAY,CAAC;IAAC,MAAM,EAAE,kCAAkC,CAAA;CAAE,GACnE;IAAE,KAAK,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACzC;IAAE,KAAK,EAAE,cAAc,CAAC;IAAC,MAAM,EAAE,kBAAkB,CAAA;CAAE,CAAC;AAgB1D;;;;;;GAMG;AACH,wBAAsB,0BAA0B,CAC9C,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,SAAS,SAAQ,GAChB,OAAO,CAAC,qBAAqB,CAAC,CAwDhC;AAED;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,SAAS,SAAQ,GAChB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAK7B;AAED,qEAAqE;AACrE,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,SAAS,SAAQ,GAChB,OAAO,CAAC,OAAO,CAAC,CAGlB;AAyED,6EAA6E;AAC7E,wBAAsB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,SAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,CAGhH;AAED,oFAAoF;AACpF,wBAAsB,wBAAwB,CAC5C,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,SAAS,SAAQ,GAChB,OAAO,CAAC,OAAO,CAAC,CAGlB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,aAAa,GAAG,aAAa,CAQvE"}

package/dist/probe.js

@@ -0,0 +1,214 @@
+import { randomUUID } from "node:crypto";
+import { createConnection } from "node:net";
+import { SessiondRpcClient } from "@fffattiger/pix-sessiond/client";
+import { SessiondError } from "@fffattiger/pix-sessiond";
+import { PROTOCOL_VERSION, SESSIOND_BUILD_IDENTITY, evaluateSessiondBuild } from "@fffattiger/pix-protocol";
+import { readLocalSecret } from "./secret.js";
+/**
+ * Ping a sessiond instance over its local RPC socket. Returns a boolean —
+ * never throws — because callers (readiness polling, capability probes, status)
+ * only need to know reachability, not the failure reason.
+ */
+export async function pingSessiond(endpoint, secret, timeoutMs = 2_000) {
+    const client = new SessiondRpcClient({ endpoint, secret, timeoutMs });
+    try {
+        const result = await client.call("system.ping", {});
+        return result.pong === true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The ONLY protocol version that may be shut down/replaced via the narrow
+ * legacy (v1) control envelope. `knownLegacy` is EXACTLY this version and no
+ * other: a future protocol version (e.g. 3 when current is 2), version 0, or
+ * any other unsupported numeric is never replaceable via the v1-only control
+ * path and is classified unverifiable (preserved).
+ */
+export const LEGACY_PROTOCOL_VERSION = 1;
+/** Map a current-client hello failure onto the operator-facing reason. */
+function classifyUnverifiableReason(error) {
+    if (error instanceof SessiondError) {
+        switch (error.code) {
+            case "timeout": return "timeout";
+            case "unauthorized": return "auth";
+            case "invalid_request": return "malformed";
+            case "unavailable": return "unreachable";
+            default: return "unknown";
+        }
+    }
+    return "unknown";
+}
+/**
+ * Resolve the explicit sessiond compatibility state via authenticated
+ * `system.hello`. Protocol v2 stale-daemon safety + the Phase 7A build fence:
+ * this is the ONE place the CLI decides whether a running daemon is current,
+ * stale-build, known-legacy, or unverifiable, so `ensureSessiond` can reuse,
+ * replace, or preserve authority without ever guessing. Never throws.
+ */
+export async function probeSessiondCompatibility(endpoint, secret, timeoutMs = 2_000) {
+    // 1. Try the current client first. A schema-valid response can only carry the
+    //    current protocol version, so success is a positively authenticated
+    //    current daemon. A v1 daemon (or any transient failure) surfaces here as
+    //    an RPC error — never a bogus "current" answer.
+    //    For a current-protocol daemon the Phase 7A build matrix then decides
+    //    whether that daemon's BUILD is reusable — same protocol major alone is never
+    //    sufficient. A missing build block (pre-fence dist) or a value mismatch
+    //    classifies as staleBuild (positively authenticated, replaceable); a
+    //    MALFORMED block fails the strict hello schema below and surfaces as
+    //    unverifiable (preserved — never destroyed on a guess).
+    let currentError;
+    try {
+        const result = await new SessiondRpcClient({ endpoint, secret, timeoutMs }).call("system.hello", {});
+        if (result.protocolVersion !== PROTOCOL_VERSION) {
+            currentError = new Error("unexpected system.hello protocol version");
+        }
+        else {
+            const build = evaluateSessiondBuild(result.build, SESSIOND_BUILD_IDENTITY);
+            if (build.state === "compatible")
+                return { state: "current" };
+            return { state: "staleBuild", reason: build.reason };
+        }
+    }
+    catch (error) {
+        currentError = error;
+    }
+    // 2. The current client cannot schema-parse a legacy (v1) response envelope.
+    //    Retry the SAME authenticated hello over the narrow legacy envelope.
+    const legacy = await legacyV1ControlCall(endpoint, secret, "system.hello", {}, timeoutMs);
+    if (legacy.ok) {
+        const version = legacy.result.protocolVersion;
+        // A current-version answer over the LEGACY envelope can never be accepted
+        // as "current": this client cannot evaluate that daemon's Phase 7A build
+        // identity over the legacy envelope, and a current-protocol daemon has no
+        // business answering it. Classify unverifiable (preserved), never reused.
+        if (version === PROTOCOL_VERSION) {
+            return { state: "unverifiable", reason: "malformed" };
+        }
+        // knownLegacy is EXACTLY the allowlisted legacy version and nothing else.
+        if (version === LEGACY_PROTOCOL_VERSION) {
+            return { state: "knownLegacy", version: LEGACY_PROTOCOL_VERSION };
+        }
+        if (typeof version === "number") {
+            if (Number.isSafeInteger(version)) {
+                // A positively authenticated but unsupported numeric version (future
+                // major, 0, …): NOT replaceable via the v1-only control path — preserve.
+                return { state: "unverifiable", reason: "unsupported_version" };
+            }
+            // Non-integer / non-finite numeric version is a malformed answer.
+            return { state: "unverifiable", reason: "malformed" };
+        }
+        // A non-numeric protocolVersion in an otherwise-valid response is malformed.
+        return { state: "unverifiable", reason: "malformed" };
+    }
+    // 3. Neither surface could positively verify the daemon. Preserve it; the
+    //    caller turns this into a retryable (timeout/unreachable) or fixed
+    //    (auth/malformed) operator error — never a shutdown.
+    return { state: "unverifiable", reason: classifyUnverifiableReason(currentError) };
+}
+/**
+ * Resolve the authenticated protocol version of a sessiond via `system.hello`.
+ * Returns the daemon's negotiated protocolVersion, or undefined when it cannot
+ * be positively verified (auth / timeout / unreachable / malformed). Protocol
+ * v2 stale-daemon safety: callers use this to refuse silently reusing a
+ * pingable v1 daemon. The raw version is never echoed into an operator-facing
+ * error.
+ */
+export async function helloProtocolVersion(endpoint, secret, timeoutMs = 2_000) {
+    const compat = await probeSessiondCompatibility(endpoint, secret, timeoutMs);
+    if (compat.state === "current")
+        return PROTOCOL_VERSION;
+    if (compat.state === "knownLegacy")
+        return compat.version;
+    return undefined;
+}
+/** True only when the authenticated daemon is POSITIVELY current. */
+export async function isProtocolCurrent(endpoint, secret, timeoutMs = 2_000) {
+    const compat = await probeSessiondCompatibility(endpoint, secret, timeoutMs);
+    return compat.state === "current";
+}
+/**
+ * Narrow Protocol-v1 control call used ONLY to identify and replace an owned
+ * stale daemon during the coordinated v2 rollout. It deliberately does not
+ * import or accept old product DTOs: AUTH plus the exact lock instance id
+ * remains the authority, and responses are checked only for the correlated
+ * fixed control method. A failed call never throws; it reports the reason.
+ */
+async function legacyV1ControlCall(endpoint, secret, method, params, timeoutMs) {
+    const id = randomUUID();
+    return new Promise((resolve) => {
+        const socket = createConnection(endpoint);
+        let buffered = "";
+        let authenticated = false;
+        let settled = false;
+        const finish = (outcome) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            socket.destroy();
+            resolve(outcome);
+        };
+        const timer = setTimeout(() => finish({ ok: false, reason: "timeout" }), timeoutMs);
+        socket.on("connect", () => socket.write(`AUTH ${secret}\n`));
+        socket.on("data", (chunk) => {
+            buffered += chunk.toString("utf8");
+            if (buffered.length > 64 * 1024)
+                return finish({ ok: false, reason: "malformed" });
+            while (true) {
+                const newline = buffered.indexOf("\n");
+                if (newline < 0)
+                    return;
+                const line = buffered.slice(0, newline);
+                buffered = buffered.slice(newline + 1);
+                if (!authenticated) {
+                    if (line !== "OK")
+                        return finish({ ok: false, reason: "auth" });
+                    authenticated = true;
+                    socket.write(`${JSON.stringify({ protocolVersion: 1, id, method, params })}\n`);
+                    continue;
+                }
+                try {
+                    const response = JSON.parse(line);
+                    if (response.id !== id || response.method !== method || response.ok !== true) {
+                        return finish({ ok: false, reason: "malformed" });
+                    }
+                    return finish({ ok: true, result: response.result ?? {} });
+                }
+                catch {
+                    return finish({ ok: false, reason: "malformed" });
+                }
+            }
+        });
+        socket.on("error", () => finish({ ok: false, reason: "unreachable" }));
+        socket.on("close", () => finish({ ok: false, reason: "unreachable" }));
+    });
+}
+/** Authenticated reachability probe for the one supported stale protocol. */
+export async function pingLegacyV1Sessiond(endpoint, secret, timeoutMs = 2_000) {
+    const outcome = await legacyV1ControlCall(endpoint, secret, "system.ping", {}, timeoutMs);
+    return outcome.ok && outcome.result.pong === true;
+}
+/** Authenticated, instance-fenced shutdown for the one supported stale protocol. */
+export async function shutdownLegacyV1Sessiond(endpoint, secret, instanceId, timeoutMs = 2_000) {
+    const outcome = await legacyV1ControlCall(endpoint, secret, "system.shutdown", { instanceId }, timeoutMs);
+    return outcome.ok && outcome.result.accepted === true;
+}
+/**
+ * Build a host {@link SessiondProbe} backed by a real RPC ping against the
+ * resolved sessiond socket. The probe reads the secret read-only; when no
+ * secret exists yet it reports unavailable rather than throwing, so /v1/health
+ * stays honest while a daemon is mid-bootstrap.
+ */
+export function createSessiondProbe(paths) {
+    return {
+        async isAvailable() {
+            const secret = await readLocalSecret(paths.secretFile);
+            if (secret === undefined)
+                return false;
+            return pingSessiond(paths.endpoint, secret);
+        },
+    };
+}
+//# sourceMappingURL=probe.js.map

package/dist/probe.js.map

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

package/dist/secret.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Minimum trimmed length of an accepted sessiond secret. The daemon publishes a
+ * base64url encoding of 32 random bytes (43 chars); requiring >= 32 rejects
+ * debris/partial files while staying compatible with the publisher.
+ */
+export declare const MIN_SECRET_LENGTH = 32;
+export declare class UnsafeSecretError extends Error {
+    constructor(message: string);
+}
+/**
+ * Read the sessiond local secret in a strictly read-only, fail-closed way.
+ *
+ * Guarantees (B4 supervision contract):
+ *   - Never creates, writes, or chmods the file. The daemon owns publication.
+ *   - Rejects symlinks and non-regular files via `lstat` (no follow).
+ *   - Requires the trimmed secret to be at least {@link MIN_SECRET_LENGTH}
+ *     chars, so a 0-byte or partial file cannot be used as a credential.
+ *
+ * Returns `undefined` when the file does not exist yet (the daemon has not
+ * published it); throws {@link UnsafeSecretError} for an unsafe/existing-but-
+ * malformed file. Network callers must treat `undefined` as "not ready".
+ */
+export declare function readLocalSecret(secretFile: string): Promise<string | undefined>;
+//# sourceMappingURL=secret.d.ts.map

package/dist/secret.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret.d.ts","sourceRoot":"","sources":["../src/secret.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAEpC,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAuBrF"}

package/dist/secret.js

@@ -0,0 +1,55 @@
+import { lstat, readFile } from "node:fs/promises";
+/**
+ * Minimum trimmed length of an accepted sessiond secret. The daemon publishes a
+ * base64url encoding of 32 random bytes (43 chars); requiring >= 32 rejects
+ * debris/partial files while staying compatible with the publisher.
+ */
+export const MIN_SECRET_LENGTH = 32;
+export class UnsafeSecretError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "UnsafeSecretError";
+    }
+}
+/**
+ * Read the sessiond local secret in a strictly read-only, fail-closed way.
+ *
+ * Guarantees (B4 supervision contract):
+ *   - Never creates, writes, or chmods the file. The daemon owns publication.
+ *   - Rejects symlinks and non-regular files via `lstat` (no follow).
+ *   - Requires the trimmed secret to be at least {@link MIN_SECRET_LENGTH}
+ *     chars, so a 0-byte or partial file cannot be used as a credential.
+ *
+ * Returns `undefined` when the file does not exist yet (the daemon has not
+ * published it); throws {@link UnsafeSecretError} for an unsafe/existing-but-
+ * malformed file. Network callers must treat `undefined` as "not ready".
+ */
+export async function readLocalSecret(secretFile) {
+    let info;
+    try {
+        info = await lstat(secretFile);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+    if (info.isSymbolicLink() || !info.isFile()) {
+        throw new UnsafeSecretError(`unsafe sessiond secret file (not a regular file): ${secretFile}`);
+    }
+    let raw;
+    try {
+        raw = await readFile(secretFile, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+    const secret = raw.trim();
+    if (secret.length < MIN_SECRET_LENGTH) {
+        throw new UnsafeSecretError(`sessiond secret too short (${secret.length} < ${MIN_SECRET_LENGTH}): ${secretFile}`);
+    }
+    return secret;
+}
+//# sourceMappingURL=secret.js.map

package/dist/secret.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret.js","sourceRoot":"","sources":["../src/secret.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAEnD;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,CAAC;AAEpC,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC1C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,UAAkB;IACtD,IAAI,IAAI,CAAC;IACT,IAAI,CAAC;QACH,IAAI,GAAG,MAAM,KAAK,CAAC,UAAU,CAAC,CAAC;IACjC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC;QACzE,MAAM,KAAK,CAAC;IACd,CAAC;IACD,IAAI,IAAI,CAAC,cAAc,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC;QAC5C,MAAM,IAAI,iBAAiB,CAAC,qDAAqD,UAAU,EAAE,CAAC,CAAC;IACjG,CAAC;IACD,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IAC3C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC;QACzE,MAAM,KAAK,CAAC;IACd,CAAC;IACD,MAAM,MAAM,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAC1B,IAAI,MAAM,CAAC,MAAM,GAAG,iBAAiB,EAAE,CAAC;QACtC,MAAM,IAAI,iBAAiB,CAAC,8BAA8B,MAAM,CAAC,MAAM,MAAM,iBAAiB,MAAM,UAAU,EAAE,CAAC,CAAC;IACpH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}