@code-yeongyu/senpi 2026.9.18 → 2026.9.19

package/dist/modes/rpc/host-runner.d.ts

@@ -0,0 +1,38 @@
+import { type HostDecisionPolicy } from "./host-decision.ts";
+import type { ResolvedHostLaunchSpec } from "./host-launch-spec.ts";
+export declare const HOST_EXIT_OK = 0;
+export declare const HOST_EXIT_ERROR = 1;
+export declare const HOST_EXIT_USAGE = 2;
+export declare const HOST_EXIT_REFUSED = 3;
+export declare const HOST_EXIT_FALLBACK = 4;
+/** Which daemon a request is about: the endpoint, and the agent directory holding its state. */
+export interface HostTarget {
+    readonly socket: string;
+    readonly agentDir: string;
+}
+export type HostRequest = {
+    readonly action: "ensure";
+    readonly target: HostTarget;
+    readonly spec: ResolvedHostLaunchSpec;
+    readonly policy: HostDecisionPolicy;
+} | {
+    readonly action: "status";
+    readonly target: HostTarget;
+    readonly includeWorkers: boolean;
+} | {
+    readonly action: "stop";
+    readonly target: HostTarget;
+    readonly drain: boolean;
+    readonly force: boolean;
+} | {
+    readonly action: "handoff";
+    readonly target: HostTarget;
+    readonly spec: ResolvedHostLaunchSpec;
+};
+/** One JSON line and the exit code it means. */
+export interface HostOutcome {
+    readonly exitCode: number;
+    readonly payload: Record<string, unknown>;
+}
+export declare function runHostRequest(request: HostRequest): Promise<HostOutcome>;
+//# sourceMappingURL=host-runner.d.ts.map

package/dist/modes/rpc/host-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-runner.d.ts","sourceRoot":"","sources":["../../../src/modes/rpc/host-runner.ts"],"names":[],"mappings":"AAoBA,OAAO,EAIN,KAAK,kBAAkB,EAIvB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAKpE,eAAO,MAAM,YAAY,IAAI,CAAC;AAC9B,eAAO,MAAM,eAAe,IAAI,CAAC;AACjC,eAAO,MAAM,eAAe,IAAI,CAAC;AACjC,eAAO,MAAM,iBAAiB,IAAI,CAAC;AACnC,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAIpC,gGAAgG;AAChG,MAAM,WAAW,UAAU;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,MAAM,WAAW,GACpB;IACA,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;CACnC,GACD;IAAE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAA;CAAE,GAC5F;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAC1G;IAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAA;CAAE,CAAC;AAEtG,gDAAgD;AAChD,MAAM,WAAW,WAAW;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC1C;AAED,wBAAsB,cAAc,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAa/E"}

package/dist/modes/rpc/host-runner.js

@@ -0,0 +1,195 @@
+/**
+ * One host request, performed: ensure a daemon, report one, stop one, or hand one off.
+ *
+ * This is the whole behaviour behind `senpi host` - and behind the launchers that call the same
+ * entry point in-process - separated from the command line that expresses it. Every request answers
+ * with a JSON payload plus the exit code that payload means, so a CLI, a desktop and a task runner
+ * report the same outcome with the same vocabulary:
+ *
+ *     0  the request happened            3  refused: a running host this client may not act on,
+ *     4  no host is better than this one     an unreachable socket, or a stop that would end
+ *        one (fallback policy)               somebody else's work
+ *
+ * The refusals are the point. One machine-wide daemon holds every client's sessions, so a client
+ * that cannot get what it wants must SAY so and leave the running host alone (I1) - never stop it,
+ * never bind a second host over its socket. `decideHostAction`, `ensureHost`, `stopHost` and
+ * `handoffHost` already enforce that; this module only gives their outcomes a machine-readable shape.
+ */
+import { engineBuildIdentity } from "../../core/engine-build-identity.js";
+import { daemonEnvKeys, daemonEnvOverrides, writeDaemonEnvKeys } from "./host-daemon-env.js";
+import { createHostDaemonPaths } from "./host-daemon-paths.js";
+import { decideHostAction, HOST_PROTOCOL_VERSION, HostEnsureRefusedError, REQUIRED_HOST_CAPABILITIES, } from "./host-decision.js";
+import { ensureHost } from "./host-ensure.js";
+import { handoffHost } from "./host-handoff.js";
+import { probeProtocolInfo } from "./host-probe.js";
+import { hostSummary, readHostStatus, readSessionCounts } from "./host-status.js";
+import { stopHost } from "./host-stop.js";
+export const HOST_EXIT_OK = 0;
+export const HOST_EXIT_ERROR = 1;
+export const HOST_EXIT_USAGE = 2;
+export const HOST_EXIT_REFUSED = 3;
+export const HOST_EXIT_FALLBACK = 4;
+const PROBE_TIMEOUT_MS = 10_000;
+export async function runHostRequest(request) {
+    switch (request.action) {
+        case "ensure":
+            return ensureOutcome(request.target, request.spec, request.policy);
+        case "status":
+            return statusOutcome(request.target, request.includeWorkers);
+        case "stop":
+            return stopOutcome(request.target, request.drain, request.force);
+        case "handoff":
+            return handoffOutcome(request.target, request.spec);
+        default:
+            return assertNever(request);
+    }
+}
+async function ensureOutcome(target, spec, policy) {
+    const before = await probeProtocolInfo(target.socket, PROBE_TIMEOUT_MS);
+    if (policy === "fallback") {
+        // `fallback` is the caller saying it can live without a host. The decision is made HERE
+        // because an ensure always produces a host or fails: it has no fallback answer of its own.
+        const decision = decideHostAction(decisionClient(), before, "fallback");
+        if (decision.action === "fallback") {
+            return refusal("fallback", before, { reason: decision.reason, socket: target.socket });
+        }
+    }
+    let ensured;
+    try {
+        ensured = await ensureHost({
+            socket: target.socket,
+            agentDir: target.agentDir,
+            hostArgs: spec.hostArgs,
+            env: daemonEnvOverrides(process.env, spec.env),
+            policy: spec.policy,
+            upgrade: policy === "upgrade" ? "if-engine-differs" : "never",
+        });
+    }
+    catch (error) {
+        if (!(error instanceof HostEnsureRefusedError))
+            throw error;
+        return refusal("refuse", before, { reason: error.reason, socket: target.socket });
+    }
+    const host = await probeProtocolInfo(target.socket, PROBE_TIMEOUT_MS);
+    // Only a spawn grants an environment; a reuse inherited whatever the client that started it did.
+    if (!ensured.reused)
+        await recordEnvScope(target, spec);
+    return {
+        exitCode: HOST_EXIT_OK,
+        payload: {
+            action: ensureAction(ensured.reused, before, host),
+            ...identityPayload(target.socket, ensured.pid, host),
+            reused: ensured.reused,
+        },
+    };
+}
+/**
+ * What an ensure DID. A handoff and a fresh start both report `reused: false`, so the instance id is
+ * what tells them apart: a handoff replaced the process behind a socket somebody was already serving.
+ */
+function ensureAction(reused, before, after) {
+    if (reused)
+        return "reuse";
+    return before !== undefined && before.instanceId !== after?.instanceId ? "handoff" : "start";
+}
+async function statusOutcome(target, includeWorkers) {
+    const status = await readHostStatus({ socket: target.socket, agentDir: target.agentDir, includeWorkers });
+    return { exitCode: status.reachable ? HOST_EXIT_OK : HOST_EXIT_REFUSED, payload: { ...status } };
+}
+/**
+ * A hard stop ends every session the daemon holds, including the ones other clients are attached to,
+ * so it is gated on the host's own count and refuses with those counts rather than a bare "busy".
+ * A DRAIN ends no work - the host stops accepting and leaves when it is empty - so it is never gated.
+ */
+async function stopOutcome(target, drain, force) {
+    const host = await probeProtocolInfo(target.socket, PROBE_TIMEOUT_MS);
+    const sessions = await readSessionCounts(target.socket, true);
+    const occupied = sessions.foreign_attached + sessions.foreign_retained > 0;
+    if (!drain && !force && occupied) {
+        return refusal("refuse", host, { reason: "sessions_live", socket: target.socket, sessions });
+    }
+    const result = await stopHost({ socket: target.socket, agentDir: target.agentDir, drain, force });
+    if (result.action === "refuse") {
+        return refusal("refuse", host, { reason: result.reason, socket: target.socket, sessions });
+    }
+    return {
+        exitCode: HOST_EXIT_OK,
+        payload: { action: result.action, socket: target.socket, pid: result.pid, sessions },
+    };
+}
+async function handoffOutcome(target, spec) {
+    const before = await probeProtocolInfo(target.socket, PROBE_TIMEOUT_MS);
+    const result = await handoffHost({
+        socket: target.socket,
+        agentDir: target.agentDir,
+        hostArgs: spec.hostArgs,
+        env: daemonEnvOverrides(process.env, spec.env),
+        policy: spec.policy,
+    });
+    if (result.action === "refuse") {
+        return refusal("refuse", before, {
+            reason: upgradeRefusal(result.reason),
+            socket: target.socket,
+            detail: result.reason,
+            upgradeable: result.upgradeable,
+        });
+    }
+    await recordEnvScope(target, spec);
+    const host = await probeProtocolInfo(target.socket, PROBE_TIMEOUT_MS);
+    return {
+        exitCode: HOST_EXIT_OK,
+        payload: { action: "handoff", ...identityPayload(target.socket, result.pid, host), reused: false },
+    };
+}
+/**
+ * A host that cannot drain and a platform that cannot hand off are one answer to the caller: this
+ * build may not replace the running generation. The refusal that produced it stays in `detail`.
+ */
+function upgradeRefusal(reason) {
+    return reason === "handoff_unsupported" ? "upgrade_unsupported" : reason;
+}
+function identityPayload(socket, pid, host) {
+    return {
+        socket,
+        pid,
+        instanceId: host?.instanceId ?? null,
+        generation: host?.generation ?? null,
+        engineVersion: host?.engineVersion ?? null,
+        engineOrdinal: host?.engineOrdinal ?? null,
+        capabilities: host?.capabilities ?? [],
+        launchProfileId: host?.launch_profile?.profile_id ?? null,
+        upgradeable: decideHostAction(decisionClient(), host, "upgrade").upgradeable,
+    };
+}
+/**
+ * The two ways a request ends without acting, and the exit codes they mean: a `refuse` leaves a
+ * running host alone (3), a `fallback` says no host is better than this one (4).
+ */
+function refusal(kind, host, body) {
+    return {
+        exitCode: kind === "refuse" ? HOST_EXIT_REFUSED : HOST_EXIT_FALLBACK,
+        payload: { action: kind, ...body, host: hostSummary(host) },
+    };
+}
+async function recordEnvScope(target, spec) {
+    const paths = createHostDaemonPaths({ socket: target.socket, agentDir: target.agentDir });
+    await writeDaemonEnvKeys(paths, daemonEnvKeys(process.env, spec.env));
+}
+/**
+ * This build as a client, WITHOUT a launch profile: the request's own `ensureHost` decides whether a
+ * handoff may happen, from the profile it would launch. What is asked here is only what any client
+ * can answer without one - is the running host usable, and could it be handed off from at all.
+ */
+function decisionClient() {
+    return {
+        protocolVersion: HOST_PROTOCOL_VERSION,
+        requiredCapabilities: REQUIRED_HOST_CAPABILITIES,
+        identity: engineBuildIdentity(),
+        startedByUs: false,
+        platform: process.platform,
+    };
+}
+function assertNever(value) {
+    throw new Error(`unreachable host request: ${JSON.stringify(value)}`);
+}
+//# sourceMappingURL=host-runner.js.map

package/dist/modes/rpc/host-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-runner.js","sourceRoot":"","sources":["../../../src/modes/rpc/host-runner.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * One host request, performed: ensure a daemon, report one, stop one, or hand one off.\n *\n * This is the whole behaviour behind `senpi host` - and behind the launchers that call the same\n * entry point in-process - separated from the command line that expresses it. Every request answers\n * with a JSON payload plus the exit code that payload means, so a CLI, a desktop and a task runner\n * report the same outcome with the same vocabulary:\n *\n *     0  the request happened            3  refused: a running host this client may not act on,\n *     4  no host is better than this one     an unreachable socket, or a stop that would end\n *        one (fallback policy)               somebody else's work\n *\n * The refusals are the point. One machine-wide daemon holds every client's sessions, so a client\n * that cannot get what it wants must SAY so and leave the running host alone (I1) - never stop it,\n * never bind a second host over its socket. `decideHostAction`, `ensureHost`, `stopHost` and\n * `handoffHost` already enforce that; this module only gives their outcomes a machine-readable shape.\n */\nimport { engineBuildIdentity } from \"../../core/engine-build-identity.ts\";\nimport { daemonEnvKeys, daemonEnvOverrides, writeDaemonEnvKeys } from \"./host-daemon-env.ts\";\nimport { createHostDaemonPaths } from \"./host-daemon-paths.ts\";\nimport {\n\tdecideHostAction,\n\tHOST_PROTOCOL_VERSION,\n\ttype HostDecisionClient,\n\ttype HostDecisionPolicy,\n\tHostEnsureRefusedError,\n\ttype HostProtocolInfo,\n\tREQUIRED_HOST_CAPABILITIES,\n} from \"./host-decision.ts\";\nimport { type EnsuredHost, ensureHost } from \"./host-ensure.ts\";\nimport { type HandoffRefusal, handoffHost } from \"./host-handoff.ts\";\nimport type { ResolvedHostLaunchSpec } from \"./host-launch-spec.ts\";\nimport { probeProtocolInfo } from \"./host-probe.ts\";\nimport { hostSummary, readHostStatus, readSessionCounts } from \"./host-status.ts\";\nimport { stopHost } from \"./host-stop.ts\";\n\nexport const HOST_EXIT_OK = 0;\nexport const HOST_EXIT_ERROR = 1;\nexport const HOST_EXIT_USAGE = 2;\nexport const HOST_EXIT_REFUSED = 3;\nexport const HOST_EXIT_FALLBACK = 4;\n\nconst PROBE_TIMEOUT_MS = 10_000;\n\n/** Which daemon a request is about: the endpoint, and the agent directory holding its state. */\nexport interface HostTarget {\n\treadonly socket: string;\n\treadonly agentDir: string;\n}\n\nexport type HostRequest =\n\t| {\n\t\t\treadonly action: \"ensure\";\n\t\t\treadonly target: HostTarget;\n\t\t\treadonly spec: ResolvedHostLaunchSpec;\n\t\t\treadonly policy: HostDecisionPolicy;\n\t  }\n\t| { readonly action: \"status\"; readonly target: HostTarget; readonly includeWorkers: boolean }\n\t| { readonly action: \"stop\"; readonly target: HostTarget; readonly drain: boolean; readonly force: boolean }\n\t| { readonly action: \"handoff\"; readonly target: HostTarget; readonly spec: ResolvedHostLaunchSpec };\n\n/** One JSON line and the exit code it means. */\nexport interface HostOutcome {\n\treadonly exitCode: number;\n\treadonly payload: Record<string, unknown>;\n}\n\nexport async function runHostRequest(request: HostRequest): Promise<HostOutcome> {\n\tswitch (request.action) {\n\t\tcase \"ensure\":\n\t\t\treturn ensureOutcome(request.target, request.spec, request.policy);\n\t\tcase \"status\":\n\t\t\treturn statusOutcome(request.target, request.includeWorkers);\n\t\tcase \"stop\":\n\t\t\treturn stopOutcome(request.target, request.drain, request.force);\n\t\tcase \"handoff\":\n\t\t\treturn handoffOutcome(request.target, request.spec);\n\t\tdefault:\n\t\t\treturn assertNever(request);\n\t}\n}\n\nasync function ensureOutcome(\n\ttarget: HostTarget,\n\tspec: ResolvedHostLaunchSpec,\n\tpolicy: HostDecisionPolicy,\n): Promise<HostOutcome> {\n\tconst before = await probeProtocolInfo(target.socket, PROBE_TIMEOUT_MS);\n\tif (policy === \"fallback\") {\n\t\t// `fallback` is the caller saying it can live without a host. The decision is made HERE\n\t\t// because an ensure always produces a host or fails: it has no fallback answer of its own.\n\t\tconst decision = decideHostAction(decisionClient(), before, \"fallback\");\n\t\tif (decision.action === \"fallback\") {\n\t\t\treturn refusal(\"fallback\", before, { reason: decision.reason, socket: target.socket });\n\t\t}\n\t}\n\tlet ensured: EnsuredHost;\n\ttry {\n\t\tensured = await ensureHost({\n\t\t\tsocket: target.socket,\n\t\t\tagentDir: target.agentDir,\n\t\t\thostArgs: spec.hostArgs,\n\t\t\tenv: daemonEnvOverrides(process.env, spec.env),\n\t\t\tpolicy: spec.policy,\n\t\t\tupgrade: policy === \"upgrade\" ? \"if-engine-differs\" : \"never\",\n\t\t});\n\t} catch (error: unknown) {\n\t\tif (!(error instanceof HostEnsureRefusedError)) throw error;\n\t\treturn refusal(\"refuse\", before, { reason: error.reason, socket: target.socket });\n\t}\n\tconst host = await probeProtocolInfo(target.socket, PROBE_TIMEOUT_MS);\n\t// Only a spawn grants an environment; a reuse inherited whatever the client that started it did.\n\tif (!ensured.reused) await recordEnvScope(target, spec);\n\treturn {\n\t\texitCode: HOST_EXIT_OK,\n\t\tpayload: {\n\t\t\taction: ensureAction(ensured.reused, before, host),\n\t\t\t...identityPayload(target.socket, ensured.pid, host),\n\t\t\treused: ensured.reused,\n\t\t},\n\t};\n}\n\n/**\n * What an ensure DID. A handoff and a fresh start both report `reused: false`, so the instance id is\n * what tells them apart: a handoff replaced the process behind a socket somebody was already serving.\n */\nfunction ensureAction(\n\treused: boolean,\n\tbefore: HostProtocolInfo | undefined,\n\tafter: HostProtocolInfo | undefined,\n): string {\n\tif (reused) return \"reuse\";\n\treturn before !== undefined && before.instanceId !== after?.instanceId ? \"handoff\" : \"start\";\n}\n\nasync function statusOutcome(target: HostTarget, includeWorkers: boolean): Promise<HostOutcome> {\n\tconst status = await readHostStatus({ socket: target.socket, agentDir: target.agentDir, includeWorkers });\n\treturn { exitCode: status.reachable ? HOST_EXIT_OK : HOST_EXIT_REFUSED, payload: { ...status } };\n}\n\n/**\n * A hard stop ends every session the daemon holds, including the ones other clients are attached to,\n * so it is gated on the host's own count and refuses with those counts rather than a bare \"busy\".\n * A DRAIN ends no work - the host stops accepting and leaves when it is empty - so it is never gated.\n */\nasync function stopOutcome(target: HostTarget, drain: boolean, force: boolean): Promise<HostOutcome> {\n\tconst host = await probeProtocolInfo(target.socket, PROBE_TIMEOUT_MS);\n\tconst sessions = await readSessionCounts(target.socket, true);\n\tconst occupied = sessions.foreign_attached + sessions.foreign_retained > 0;\n\tif (!drain && !force && occupied) {\n\t\treturn refusal(\"refuse\", host, { reason: \"sessions_live\", socket: target.socket, sessions });\n\t}\n\tconst result = await stopHost({ socket: target.socket, agentDir: target.agentDir, drain, force });\n\tif (result.action === \"refuse\") {\n\t\treturn refusal(\"refuse\", host, { reason: result.reason, socket: target.socket, sessions });\n\t}\n\treturn {\n\t\texitCode: HOST_EXIT_OK,\n\t\tpayload: { action: result.action, socket: target.socket, pid: result.pid, sessions },\n\t};\n}\n\nasync function handoffOutcome(target: HostTarget, spec: ResolvedHostLaunchSpec): Promise<HostOutcome> {\n\tconst before = await probeProtocolInfo(target.socket, PROBE_TIMEOUT_MS);\n\tconst result = await handoffHost({\n\t\tsocket: target.socket,\n\t\tagentDir: target.agentDir,\n\t\thostArgs: spec.hostArgs,\n\t\tenv: daemonEnvOverrides(process.env, spec.env),\n\t\tpolicy: spec.policy,\n\t});\n\tif (result.action === \"refuse\") {\n\t\treturn refusal(\"refuse\", before, {\n\t\t\treason: upgradeRefusal(result.reason),\n\t\t\tsocket: target.socket,\n\t\t\tdetail: result.reason,\n\t\t\tupgradeable: result.upgradeable,\n\t\t});\n\t}\n\tawait recordEnvScope(target, spec);\n\tconst host = await probeProtocolInfo(target.socket, PROBE_TIMEOUT_MS);\n\treturn {\n\t\texitCode: HOST_EXIT_OK,\n\t\tpayload: { action: \"handoff\", ...identityPayload(target.socket, result.pid, host), reused: false },\n\t};\n}\n\n/**\n * A host that cannot drain and a platform that cannot hand off are one answer to the caller: this\n * build may not replace the running generation. The refusal that produced it stays in `detail`.\n */\nfunction upgradeRefusal(reason: HandoffRefusal): string {\n\treturn reason === \"handoff_unsupported\" ? \"upgrade_unsupported\" : reason;\n}\n\nfunction identityPayload(socket: string, pid: number, host: HostProtocolInfo | undefined): Record<string, unknown> {\n\treturn {\n\t\tsocket,\n\t\tpid,\n\t\tinstanceId: host?.instanceId ?? null,\n\t\tgeneration: host?.generation ?? null,\n\t\tengineVersion: host?.engineVersion ?? null,\n\t\tengineOrdinal: host?.engineOrdinal ?? null,\n\t\tcapabilities: host?.capabilities ?? [],\n\t\tlaunchProfileId: host?.launch_profile?.profile_id ?? null,\n\t\tupgradeable: decideHostAction(decisionClient(), host, \"upgrade\").upgradeable,\n\t};\n}\n\n/**\n * The two ways a request ends without acting, and the exit codes they mean: a `refuse` leaves a\n * running host alone (3), a `fallback` says no host is better than this one (4).\n */\nfunction refusal(\n\tkind: \"refuse\" | \"fallback\",\n\thost: HostProtocolInfo | undefined,\n\tbody: { readonly reason: string } & Record<string, unknown>,\n): HostOutcome {\n\treturn {\n\t\texitCode: kind === \"refuse\" ? HOST_EXIT_REFUSED : HOST_EXIT_FALLBACK,\n\t\tpayload: { action: kind, ...body, host: hostSummary(host) },\n\t};\n}\n\nasync function recordEnvScope(target: HostTarget, spec: ResolvedHostLaunchSpec): Promise<void> {\n\tconst paths = createHostDaemonPaths({ socket: target.socket, agentDir: target.agentDir });\n\tawait writeDaemonEnvKeys(paths, daemonEnvKeys(process.env, spec.env));\n}\n\n/**\n * This build as a client, WITHOUT a launch profile: the request's own `ensureHost` decides whether a\n * handoff may happen, from the profile it would launch. What is asked here is only what any client\n * can answer without one - is the running host usable, and could it be handed off from at all.\n */\nfunction decisionClient(): HostDecisionClient {\n\treturn {\n\t\tprotocolVersion: HOST_PROTOCOL_VERSION,\n\t\trequiredCapabilities: REQUIRED_HOST_CAPABILITIES,\n\t\tidentity: engineBuildIdentity(),\n\t\tstartedByUs: false,\n\t\tplatform: process.platform,\n\t};\n}\n\nfunction assertNever(value: never): never {\n\tthrow new Error(`unreachable host request: ${JSON.stringify(value)}`);\n}\n"]}

package/dist/modes/rpc/host-status.d.ts

@@ -0,0 +1,58 @@
+import type { HostProtocolInfo } from "./host-decision.ts";
+import type { RpcLaunchProfile } from "./rpc-types.ts";
+/**
+ * Sessions the host reports. `foreign_*` is the same count from the point of view of a client that
+ * holds none of them itself: for the CLI every session belongs to somebody else, which is exactly
+ * why a hard stop is gated on it.
+ */
+export interface HostSessionCounts {
+    readonly total: number;
+    readonly interactive: number;
+    readonly worker: number;
+    /** Open at zero attachments: retained across a disconnect, still holding its transcript. */
+    readonly retained: number;
+    readonly foreign_attached: number;
+    readonly foreign_retained: number;
+}
+/** One generation's record in the daemon directory - the current one, and any that outlived it. */
+export interface HostGenerationRow {
+    readonly instanceId: string;
+    readonly generation: number;
+    readonly pid: number;
+    readonly engineVersion: string | null;
+    /** True for the generation the pointer names: the one serving the socket. */
+    readonly current: boolean;
+    readonly alive: boolean;
+}
+export interface HostStatusReport {
+    readonly reachable: boolean;
+    readonly socket: string;
+    readonly pid: number | null;
+    readonly instanceId: string | null;
+    readonly generation: number | null;
+    readonly engineVersion: string | null;
+    readonly capabilities: readonly string[];
+    readonly launchProfile: RpcLaunchProfile | null;
+    readonly sessions: HostSessionCounts;
+    readonly zombies: number | null;
+    readonly rss_mb: number | null;
+    readonly open_fds: number | null;
+    /** Environment NAMES the daemon was granted, never values. */
+    readonly env_keys: readonly string[];
+    readonly generations: readonly HostGenerationRow[];
+}
+export interface HostStatusOptions {
+    readonly socket: string;
+    readonly agentDir?: string;
+    /** Ask the host to include `kind: "worker"` rows, exactly as `list_sessions` defines the flag. */
+    readonly includeWorkers?: boolean;
+}
+export declare function readHostStatus(options: HostStatusOptions): Promise<HostStatusReport>;
+/**
+ * The occupancy a stop decision is made on. A host that does not answer holds nothing a client can
+ * see, and an empty count is what lets a stop proceed against a socket nobody serves.
+ */
+export declare function readSessionCounts(socket: string, includeWorkers: boolean): Promise<HostSessionCounts>;
+/** Identity fields of a probed host, for the `host` field of a refusal. */
+export declare function hostSummary(host: HostProtocolInfo | undefined): Record<string, unknown> | null;
+//# sourceMappingURL=host-status.d.ts.map

package/dist/modes/rpc/host-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-status.d.ts","sourceRoot":"","sources":["../../../src/modes/rpc/host-status.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAG3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAIvD;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,4FAA4F;IAC5F,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CAClC;AAED,mGAAmG;AACnG,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,6EAA6E;IAC7E,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,aAAa,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAChD,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,8DAA8D;IAC9D,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,WAAW,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACnD;AAED,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,kGAAkG;IAClG,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;CAClC;AAED,wBAAsB,cAAc,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAyB1F;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,OAAO,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAiB3G;AAED,2EAA2E;AAC3E,wBAAgB,WAAW,CAAC,IAAI,EAAE,gBAAgB,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAW9F"}

package/dist/modes/rpc/host-status.js

@@ -0,0 +1,117 @@
+/**
+ * What a client can observe about the daemon on one socket, in one record.
+ *
+ * Everything that describes the RUNNING host comes from the host's own answers - `get_protocol_info`
+ * for identity, `list_sessions` for occupancy - because files describe the past and the socket
+ * describes the present. Everything that describes the DAEMON DIRECTORY (which generations exist,
+ * which environment scope the last ensure granted) comes from disk, because a generation that no
+ * longer answers is exactly what an operator is looking for when they ask.
+ *
+ * A socket nobody serves is not an error here: `reachable: false` with the same field set is the
+ * answer, so a caller parses one shape either way and branches on one boolean.
+ */
+import { readdir } from "node:fs/promises";
+import { processIsLive } from "../app-server/daemon/process.js";
+import { readDaemonEnvKeys } from "./host-daemon-env.js";
+import { createHostDaemonPaths, generationPaths } from "./host-daemon-paths.js";
+import { parseJson, readFileOrUndefined } from "./host-daemon-state.js";
+import { probeProtocolInfo, requestOnSocket } from "./host-probe.js";
+import { readHostProcessMetrics } from "./host-process-metrics.js";
+const STATUS_PROBE_TIMEOUT_MS = 10_000;
+export async function readHostStatus(options) {
+    const paths = createHostDaemonPaths({
+        socket: options.socket,
+        ...(options.agentDir ? { agentDir: options.agentDir } : {}),
+    });
+    const host = await probeProtocolInfo(options.socket, STATUS_PROBE_TIMEOUT_MS);
+    const generations = await readGenerations(paths);
+    const current = generations.find((row) => row.current);
+    const metrics = current ? await readHostProcessMetrics(current.pid) : UNOBSERVED_METRICS;
+    return {
+        reachable: host !== undefined,
+        socket: options.socket,
+        pid: current?.pid ?? null,
+        instanceId: host?.instanceId ?? current?.instanceId ?? null,
+        generation: host?.generation ?? current?.generation ?? null,
+        engineVersion: host?.engineVersion ?? current?.engineVersion ?? null,
+        capabilities: host?.capabilities ?? [],
+        launchProfile: host?.launch_profile ?? null,
+        sessions: await readSessionCounts(options.socket, options.includeWorkers === true),
+        zombies: metrics.zombies,
+        rss_mb: metrics.rss_mb,
+        open_fds: metrics.open_fds,
+        env_keys: await readDaemonEnvKeys(paths),
+        generations,
+    };
+}
+/**
+ * The occupancy a stop decision is made on. A host that does not answer holds nothing a client can
+ * see, and an empty count is what lets a stop proceed against a socket nobody serves.
+ */
+export async function readSessionCounts(socket, includeWorkers) {
+    const reply = await requestOnSocket(socket, { type: "list_sessions", ...(includeWorkers ? { include_workers: true } : {}) }, STATUS_PROBE_TIMEOUT_MS);
+    const rows = sessionRows(reply);
+    const attached = rows.filter((row) => row.attachments > 0).length;
+    const retained = rows.length - attached;
+    return {
+        total: rows.length,
+        interactive: rows.filter((row) => row.kind !== "worker").length,
+        worker: rows.filter((row) => row.kind === "worker").length,
+        retained,
+        foreign_attached: attached,
+        foreign_retained: retained,
+    };
+}
+/** Identity fields of a probed host, for the `host` field of a refusal. */
+export function hostSummary(host) {
+    if (host === undefined)
+        return null;
+    return {
+        protocolVersion: host.protocolVersion,
+        serverVersion: host.serverVersion,
+        capabilities: host.capabilities,
+        instanceId: host.instanceId ?? null,
+        generation: host.generation ?? null,
+        engineVersion: host.engineVersion ?? null,
+        launchProfileId: host.launch_profile?.profile_id ?? null,
+    };
+}
+const UNOBSERVED_METRICS = { rss_mb: null, open_fds: null, zombies: null };
+function sessionRows(reply) {
+    if (!isRecord(reply) || !Array.isArray(reply.sessions))
+        return [];
+    return reply.sessions.flatMap((entry) => {
+        if (!isRecord(entry))
+            return [];
+        return [
+            {
+                kind: typeof entry.kind === "string" ? entry.kind : "interactive",
+                attachments: typeof entry.attachments === "number" ? entry.attachments : 0,
+            },
+        ];
+    });
+}
+async function readGenerations(paths) {
+    const pointer = parseJson(await readFileOrUndefined(paths.pointerFile));
+    const currentId = typeof pointer?.instance_id === "string" ? pointer.instance_id : undefined;
+    const entries = await readdir(paths.generationsDir).catch(() => []);
+    const rows = [];
+    for (const instanceId of entries) {
+        const record = parseJson(await readFileOrUndefined(generationPaths(paths, instanceId).pidFile));
+        if (typeof record?.pid !== "number")
+            continue;
+        rows.push({
+            instanceId,
+            generation: typeof record.generation === "number" ? record.generation : 0,
+            pid: record.pid,
+            engineVersion: typeof record.engineVersion === "string" ? record.engineVersion : null,
+            current: instanceId === currentId,
+            alive: processIsLive(record.pid),
+        });
+    }
+    return rows.sort((left, right) => left.generation - right.generation);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=host-status.js.map

package/dist/modes/rpc/host-status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-status.js","sourceRoot":"","sources":["../../../src/modes/rpc/host-status.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAChE,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAE,qBAAqB,EAAE,eAAe,EAAwB,MAAM,wBAAwB,CAAC;AACtG,OAAO,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAExE,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACrE,OAAO,EAA2B,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAG5F,MAAM,uBAAuB,GAAG,MAAM,CAAC;AAqDvC,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,OAA0B;IAC9D,MAAM,KAAK,GAAG,qBAAqB,CAAC;QACnC,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC3D,CAAC,CAAC;IACH,MAAM,IAAI,GAAG,MAAM,iBAAiB,CAAC,OAAO,CAAC,MAAM,EAAE,uBAAuB,CAAC,CAAC;IAC9E,MAAM,WAAW,GAAG,MAAM,eAAe,CAAC,KAAK,CAAC,CAAC;IACjD,MAAM,OAAO,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACvD,MAAM,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,MAAM,sBAAsB,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,kBAAkB,CAAC;IACzF,OAAO;QACN,SAAS,EAAE,IAAI,KAAK,SAAS;QAC7B,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,GAAG,EAAE,OAAO,EAAE,GAAG,IAAI,IAAI;QACzB,UAAU,EAAE,IAAI,EAAE,UAAU,IAAI,OAAO,EAAE,UAAU,IAAI,IAAI;QAC3D,UAAU,EAAE,IAAI,EAAE,UAAU,IAAI,OAAO,EAAE,UAAU,IAAI,IAAI;QAC3D,aAAa,EAAE,IAAI,EAAE,aAAa,IAAI,OAAO,EAAE,aAAa,IAAI,IAAI;QACpE,YAAY,EAAE,IAAI,EAAE,YAAY,IAAI,EAAE;QACtC,aAAa,EAAE,IAAI,EAAE,cAAc,IAAI,IAAI;QAC3C,QAAQ,EAAE,MAAM,iBAAiB,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,cAAc,KAAK,IAAI,CAAC;QAClF,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,QAAQ,EAAE,MAAM,iBAAiB,CAAC,KAAK,CAAC;QACxC,WAAW;KACX,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,MAAc,EAAE,cAAuB;IAC9E,MAAM,KAAK,GAAG,MAAM,eAAe,CAClC,MAAM,EACN,EAAE,IAAI,EAAE,eAAe,EAAE,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAC/E,uBAAuB,CACvB,CAAC;IACF,MAAM,IAAI,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;IAChC,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,WAAW,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC;IAClE,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC;IACxC,OAAO;QACN,KAAK,EAAE,IAAI,CAAC,MAAM;QAClB,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,MAAM;QAC/D,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,MAAM;QAC1D,QAAQ;QACR,gBAAgB,EAAE,QAAQ;QAC1B,gBAAgB,EAAE,QAAQ;KAC1B,CAAC;AACH,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,WAAW,CAAC,IAAkC;IAC7D,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACpC,OAAO;QACN,eAAe,EAAE,IAAI,CAAC,eAAe;QACrC,aAAa,EAAE,IAAI,CAAC,aAAa;QACjC,YAAY,EAAE,IAAI,CAAC,YAAY;QAC/B,UAAU,EAAE,IAAI,CAAC,UAAU,IAAI,IAAI;QACnC,UAAU,EAAE,IAAI,CAAC,UAAU,IAAI,IAAI;QACnC,aAAa,EAAE,IAAI,CAAC,aAAa,IAAI,IAAI;QACzC,eAAe,EAAE,IAAI,CAAC,cAAc,EAAE,UAAU,IAAI,IAAI;KACxD,CAAC;AACH,CAAC;AAED,MAAM,kBAAkB,GAAuB,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AAO/F,SAAS,WAAW,CAAC,KAAc;IAClC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC;QAAE,OAAO,EAAE,CAAC;IAClE,OAAO,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,KAAc,EAAE,EAAE;QAChD,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;YAAE,OAAO,EAAE,CAAC;QAChC,OAAO;YACN;gBACC,IAAI,EAAE,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,aAAa;gBACjE,WAAW,EAAE,OAAO,KAAK,CAAC,WAAW,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;aAC1E;SACD,CAAC;IACH,CAAC,CAAC,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,eAAe,CAAC,KAAsB;IACpD,MAAM,OAAO,GAAG,SAAS,CAAC,MAAM,mBAAmB,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC;IACxE,MAAM,SAAS,GAAG,OAAO,OAAO,EAAE,WAAW,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC;IAC7F,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;IACpE,MAAM,IAAI,GAAwB,EAAE,CAAC;IACrC,KAAK,MAAM,UAAU,IAAI,OAAO,EAAE,CAAC;QAClC,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,mBAAmB,CAAC,eAAe,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;QAChG,IAAI,OAAO,MAAM,EAAE,GAAG,KAAK,QAAQ;YAAE,SAAS;QAC9C,IAAI,CAAC,IAAI,CAAC;YACT,UAAU;YACV,UAAU,EAAE,OAAO,MAAM,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;YACzE,GAAG,EAAE,MAAM,CAAC,GAAG;YACf,aAAa,EAAE,OAAO,MAAM,CAAC,aAAa,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI;YACrF,OAAO,EAAE,UAAU,KAAK,SAAS;YACjC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,CAAC;SAChC,CAAC,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC,UAAU,CAAC,CAAC;AACvE,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC/B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC7E,CAAC","sourcesContent":["/**\n * What a client can observe about the daemon on one socket, in one record.\n *\n * Everything that describes the RUNNING host comes from the host's own answers - `get_protocol_info`\n * for identity, `list_sessions` for occupancy - because files describe the past and the socket\n * describes the present. Everything that describes the DAEMON DIRECTORY (which generations exist,\n * which environment scope the last ensure granted) comes from disk, because a generation that no\n * longer answers is exactly what an operator is looking for when they ask.\n *\n * A socket nobody serves is not an error here: `reachable: false` with the same field set is the\n * answer, so a caller parses one shape either way and branches on one boolean.\n */\nimport { readdir } from \"node:fs/promises\";\nimport { processIsLive } from \"../app-server/daemon/process.ts\";\nimport { readDaemonEnvKeys } from \"./host-daemon-env.ts\";\nimport { createHostDaemonPaths, generationPaths, type HostDaemonPaths } from \"./host-daemon-paths.ts\";\nimport { parseJson, readFileOrUndefined } from \"./host-daemon-state.ts\";\nimport type { HostProtocolInfo } from \"./host-decision.ts\";\nimport { probeProtocolInfo, requestOnSocket } from \"./host-probe.ts\";\nimport { type HostProcessMetrics, readHostProcessMetrics } from \"./host-process-metrics.ts\";\nimport type { RpcLaunchProfile } from \"./rpc-types.ts\";\n\nconst STATUS_PROBE_TIMEOUT_MS = 10_000;\n\n/**\n * Sessions the host reports. `foreign_*` is the same count from the point of view of a client that\n * holds none of them itself: for the CLI every session belongs to somebody else, which is exactly\n * why a hard stop is gated on it.\n */\nexport interface HostSessionCounts {\n\treadonly total: number;\n\treadonly interactive: number;\n\treadonly worker: number;\n\t/** Open at zero attachments: retained across a disconnect, still holding its transcript. */\n\treadonly retained: number;\n\treadonly foreign_attached: number;\n\treadonly foreign_retained: number;\n}\n\n/** One generation's record in the daemon directory - the current one, and any that outlived it. */\nexport interface HostGenerationRow {\n\treadonly instanceId: string;\n\treadonly generation: number;\n\treadonly pid: number;\n\treadonly engineVersion: string | null;\n\t/** True for the generation the pointer names: the one serving the socket. */\n\treadonly current: boolean;\n\treadonly alive: boolean;\n}\n\nexport interface HostStatusReport {\n\treadonly reachable: boolean;\n\treadonly socket: string;\n\treadonly pid: number | null;\n\treadonly instanceId: string | null;\n\treadonly generation: number | null;\n\treadonly engineVersion: string | null;\n\treadonly capabilities: readonly string[];\n\treadonly launchProfile: RpcLaunchProfile | null;\n\treadonly sessions: HostSessionCounts;\n\treadonly zombies: number | null;\n\treadonly rss_mb: number | null;\n\treadonly open_fds: number | null;\n\t/** Environment NAMES the daemon was granted, never values. */\n\treadonly env_keys: readonly string[];\n\treadonly generations: readonly HostGenerationRow[];\n}\n\nexport interface HostStatusOptions {\n\treadonly socket: string;\n\treadonly agentDir?: string;\n\t/** Ask the host to include `kind: \"worker\"` rows, exactly as `list_sessions` defines the flag. */\n\treadonly includeWorkers?: boolean;\n}\n\nexport async function readHostStatus(options: HostStatusOptions): Promise<HostStatusReport> {\n\tconst paths = createHostDaemonPaths({\n\t\tsocket: options.socket,\n\t\t...(options.agentDir ? { agentDir: options.agentDir } : {}),\n\t});\n\tconst host = await probeProtocolInfo(options.socket, STATUS_PROBE_TIMEOUT_MS);\n\tconst generations = await readGenerations(paths);\n\tconst current = generations.find((row) => row.current);\n\tconst metrics = current ? await readHostProcessMetrics(current.pid) : UNOBSERVED_METRICS;\n\treturn {\n\t\treachable: host !== undefined,\n\t\tsocket: options.socket,\n\t\tpid: current?.pid ?? null,\n\t\tinstanceId: host?.instanceId ?? current?.instanceId ?? null,\n\t\tgeneration: host?.generation ?? current?.generation ?? null,\n\t\tengineVersion: host?.engineVersion ?? current?.engineVersion ?? null,\n\t\tcapabilities: host?.capabilities ?? [],\n\t\tlaunchProfile: host?.launch_profile ?? null,\n\t\tsessions: await readSessionCounts(options.socket, options.includeWorkers === true),\n\t\tzombies: metrics.zombies,\n\t\trss_mb: metrics.rss_mb,\n\t\topen_fds: metrics.open_fds,\n\t\tenv_keys: await readDaemonEnvKeys(paths),\n\t\tgenerations,\n\t};\n}\n\n/**\n * The occupancy a stop decision is made on. A host that does not answer holds nothing a client can\n * see, and an empty count is what lets a stop proceed against a socket nobody serves.\n */\nexport async function readSessionCounts(socket: string, includeWorkers: boolean): Promise<HostSessionCounts> {\n\tconst reply = await requestOnSocket(\n\t\tsocket,\n\t\t{ type: \"list_sessions\", ...(includeWorkers ? { include_workers: true } : {}) },\n\t\tSTATUS_PROBE_TIMEOUT_MS,\n\t);\n\tconst rows = sessionRows(reply);\n\tconst attached = rows.filter((row) => row.attachments > 0).length;\n\tconst retained = rows.length - attached;\n\treturn {\n\t\ttotal: rows.length,\n\t\tinteractive: rows.filter((row) => row.kind !== \"worker\").length,\n\t\tworker: rows.filter((row) => row.kind === \"worker\").length,\n\t\tretained,\n\t\tforeign_attached: attached,\n\t\tforeign_retained: retained,\n\t};\n}\n\n/** Identity fields of a probed host, for the `host` field of a refusal. */\nexport function hostSummary(host: HostProtocolInfo | undefined): Record<string, unknown> | null {\n\tif (host === undefined) return null;\n\treturn {\n\t\tprotocolVersion: host.protocolVersion,\n\t\tserverVersion: host.serverVersion,\n\t\tcapabilities: host.capabilities,\n\t\tinstanceId: host.instanceId ?? null,\n\t\tgeneration: host.generation ?? null,\n\t\tengineVersion: host.engineVersion ?? null,\n\t\tlaunchProfileId: host.launch_profile?.profile_id ?? null,\n\t};\n}\n\nconst UNOBSERVED_METRICS: HostProcessMetrics = { rss_mb: null, open_fds: null, zombies: null };\n\ninterface SessionRow {\n\treadonly kind: string;\n\treadonly attachments: number;\n}\n\nfunction sessionRows(reply: unknown): readonly SessionRow[] {\n\tif (!isRecord(reply) || !Array.isArray(reply.sessions)) return [];\n\treturn reply.sessions.flatMap((entry: unknown) => {\n\t\tif (!isRecord(entry)) return [];\n\t\treturn [\n\t\t\t{\n\t\t\t\tkind: typeof entry.kind === \"string\" ? entry.kind : \"interactive\",\n\t\t\t\tattachments: typeof entry.attachments === \"number\" ? entry.attachments : 0,\n\t\t\t},\n\t\t];\n\t});\n}\n\nasync function readGenerations(paths: HostDaemonPaths): Promise<readonly HostGenerationRow[]> {\n\tconst pointer = parseJson(await readFileOrUndefined(paths.pointerFile));\n\tconst currentId = typeof pointer?.instance_id === \"string\" ? pointer.instance_id : undefined;\n\tconst entries = await readdir(paths.generationsDir).catch(() => []);\n\tconst rows: HostGenerationRow[] = [];\n\tfor (const instanceId of entries) {\n\t\tconst record = parseJson(await readFileOrUndefined(generationPaths(paths, instanceId).pidFile));\n\t\tif (typeof record?.pid !== \"number\") continue;\n\t\trows.push({\n\t\t\tinstanceId,\n\t\t\tgeneration: typeof record.generation === \"number\" ? record.generation : 0,\n\t\t\tpid: record.pid,\n\t\t\tengineVersion: typeof record.engineVersion === \"string\" ? record.engineVersion : null,\n\t\t\tcurrent: instanceId === currentId,\n\t\t\talive: processIsLive(record.pid),\n\t\t});\n\t}\n\treturn rows.sort((left, right) => left.generation - right.generation);\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n"]}

package/docs/extensions.md

@@ -1510,6 +1510,35 @@ export default function (pi: ExtensionAPI) {
 
 ## ExtensionAPI Methods
 
+### pi.sessionKind / pi.sessionContext / pi.sharedHostEnabled
+
+Read-only facts about the session this extension instance was loaded for, available at factory time so an extension
+can decide what to register before it registers anything:
+
+| Property | Type | Value |
+|---|---|---|
+| `pi.cwd` | `string` | Absolute working directory of this session |
+| `pi.sharedHostEnabled` | `boolean` | Whether this session runs on a shared RPC host |
+| `pi.sessionKind` | `"interactive" \| "worker"` | Visibility class the opener chose (`open_session.kind`); `interactive` for classic launches and any open that omits it |
+| `pi.sessionContext` | `Readonly<Record<string, string>>` | Opaque labels the opener attached (`open_session.context`), or `{}` |
+
+```typescript
+export default function ({ pi }) {
+  // One extension set serves every session of a shared daemon; gate per session, not per host.
+  if (pi.sessionKind === "worker" && pi.sessionContext.role === "child") {
+    pi.registerTool(reportToParentTool);
+    return;
+  }
+  pi.registerCommand("review", reviewCommand);
+}
+```
+
+The engine never interprets `sessionContext`: it takes no part in authentication, model selection, resource loading
+or any other host decision, and it is republished only on `list_sessions { include_workers: true }`. Its caps are
+enforced at the RPC boundary (at most 32 keys matching `^[a-z][a-z0-9_]*$`, each value at most 16 KiB, at most 32 KiB
+of JSON in total), so an extension receives an already-validated map. Both values are frozen for the session's life;
+there is no setter. See [Session kind and context](rpc.md#session-kind-and-context-open_session) for the wire side.
+
 ### pi.on(event, handler)
 
 Subscribe to events. See [Events](#events) for event types and return values.
@@ -2066,6 +2095,12 @@ pi.events.emit("my:event", { ... });
 
 Senpi's default-on `config-reload` builtin watches configured global surfaces and trusted project-local `.senpi` surfaces. A real content change requests the normal full session reload when the agent is idle; busy or compacting sessions defer it until a safe idle edge. When an extension vetoes the reload through `session_before_reload` (for example while subagents it owns are still running), the change also defers quietly: one `Hot-reload deferred: <reason>` notice per distinct veto reason, silent retries on later idle edges plus a periodic veto recheck, and the usual `Hot-reloading:`/`Hot-reloaded:` notifications only once the veto clears and the reload actually runs. Parseable built-in files (`settings.json`, `models.json`, and `keybindings.json`) are validated before reload, so a rejected edit keeps the running configuration active.
 
+> **Cost on a shared host:** the watcher runs per session. Each session's `config-reload` instance lazily spawns one
+> `node:worker_threads` Worker for recursive filesystem watching, so a host serving N sessions carries about N extra
+> OS threads and ~5 MB per session ([senpi#1794](https://github.com/code-yeongyu/senpi/issues/1794)). It is the
+> dominant per-session cost of a shared RPC daemon ([RPC: session runtime](rpc.md#session-runtime---session-runtime-in-processworker));
+> a host whose settings disable the builtin adds no thread per session at all.
+
 Configure it in `settings.json` with optional fields; omitted fields use the defaults shown here. Invalid `configReload` fields are ignored individually, so a malformed block falls back to these defaults rather than disabling watching:
 
 ```json

package/docs/providers.md

@@ -215,6 +215,35 @@ The provider streams through Ollama's OpenAI-compatible `/v1/chat/completions` e
 Existing local Ollama configurations remain supported. When an `ollama` provider in `models.json` includes
 an explicit `models` catalog, that catalog takes precedence and Senpi does not run Ollama Cloud discovery.
 
+## B.AI
+
+Use `/login bai` to store an API key, or export `BAI_API_KEY`. B.AI model availability is credential-scoped,
+so refresh the catalog after login:
+
+```bash
+export BAI_API_KEY=...
+senpi update --models
+senpi --provider bai --model gpt-5.6-sol
+```
+
+Senpi discovers available IDs from `https://api.b.ai/v1/models` and enriches classified chat models with
+B.AI's documented context, output, input modality, reasoning-level, and standard pricing metadata. Because that
+list is credential-scoped, a model you are not entitled to never appears.
+
+B.AI serves one API key over three protocols and documents several models on more than one of them, so the
+endpoint is a client choice rather than a per-model property. Senpi pins one protocol per model: GPT and
+DeepSeek use OpenAI Responses (the two families B.AI names for that endpoint), Claude uses Anthropic Messages,
+and the remaining chat families use OpenAI Chat Completions.
+
+B.AI rejects a function tool whose root parameters schema declares no `type`. On the Responses endpoint Senpi
+merges such a union root into a single object schema so the tool keeps its parameters; the Chat Completions and
+Messages paths already do the same normalization for every provider. Image-only IDs such as `gpt-image-2` remain
+on B.AI's image API and are not listed as chat models.
+
+The catalog records B.AI's standard reference prices in USD per 1M tokens. They exclude temporary promotions,
+top-up bonuses, DeepSeek idle-period rates, and account benefits, so B.AI's final billing record remains
+authoritative.
+
 ## API Keys
 
 ### Environment Variables or Auth File
@@ -232,6 +261,7 @@ senpi
 | Ant Ling | `ANT_LING_API_KEY` | `ant-ling` |
 | Azure OpenAI Responses | `AZURE_OPENAI_API_KEY` | `azure-openai-responses` |
 | OpenAI | `OPENAI_API_KEY` | `openai` |
+| B.AI | `BAI_API_KEY` | `bai` |
 | Ollama Cloud | `OLLAMA_API_KEY` | `ollama` |
 | DeepSeek | `DEEPSEEK_API_KEY` | `deepseek` |
 | NVIDIA NIM | `NVIDIA_API_KEY` | `nvidia` |