@fitchmultz/pi-subagents 0.46.2 → 0.48.0

package/dist/pi-intercom/bridge.js

@@ -7,23 +7,65 @@ import { loadConfig, sameListener } from "./bridge-config.js";
 import { ASK_TIMEOUT, Fault, fingerprint, log } from "./bridge-protocol.js";
 import { Session } from "./bridge-session.js";
 import { operationFor, routeFor } from "./bridge-routes.js";
-import { reply } from "./bridge-http.js";
-import { Launcher, sameIdentity } from "./bridge-launch.js";
+import { reply, replyFault } from "./bridge-http.js";
+import { sameIdentity } from "./bridge-launch.js";
+import { BridgeOperations } from "./bridge-operations.js";
+import { authenticatedCertificateChain } from "./native-control-auth.js";
+import { PersistentPresence } from "./bridge-presence.js";
+import { WakeDeliveries } from "./bridge-wake.js";
+import { spawnBrokerIfNeeded } from "./broker/spawn.js";
 const MAX_CONNECTIONS = 128;
+const LONG_ROUTES = new Set([
+    "POST /v1/start",
+    "POST /v1/spawn",
+    "POST /v1/resume",
+    "GET /v1/transcript",
+    "POST /v1/transcript",
+]);
+function validCertificateDates(starts, expires) {
+    return (Number.isFinite(starts) &&
+        Number.isFinite(expires) &&
+        starts <= Date.now() &&
+        expires > Date.now());
+}
 class Bridge {
     config;
     configPath;
     sessions = new Map();
     losses = new Map();
-    launcher = new Launcher();
+    operations;
     sockets = new Set();
     connections = new Map();
     server;
     stopping = false;
     handlers = new Set();
+    presence;
+    deliveries;
     constructor(config, configPath) {
         this.config = config;
         this.configPath = configPath;
+        this.operations = new BridgeOperations(config.stateDir);
+        this.deliveries = new WakeDeliveries(config.stateDir, (identity) => this.allowed(identity));
+        if (config.stateDir !== undefined) {
+            this.presence = new PersistentPresence({
+                stateDir: config.stateDir,
+                clients: () => this.config.clients,
+                connect: async (identity, expires) => {
+                    await spawnBrokerIfNeeded(process.execPath, []);
+                    if (!this.allowed(identity)) {
+                        return;
+                    }
+                    const session = this.session(identity, expires);
+                    const controller = session.begin();
+                    try {
+                        await session.connectedPeers(controller.signal);
+                    }
+                    finally {
+                        session.end(controller);
+                    }
+                },
+            });
+        }
         this.server = createServer({
             ...config.tls,
             minVersion: "TLSv1.2",
@@ -74,7 +116,9 @@ class Bridge {
     }
     allowed(identity) {
         const current = this.config.clients.get(identity.fingerprint256);
-        return !this.stopping && sameIdentity(identity, current);
+        return (!this.stopping &&
+            sameIdentity(identity, current) &&
+            JSON.stringify(identity.wake) === JSON.stringify(current?.wake));
     }
     lost(fp, count = 1) {
         if (count > 0 && this.config.clients.has(fp)) {
@@ -82,9 +126,12 @@ class Bridge {
         }
     }
     session(identity, expires) {
+        this.deliveries.session(identity, expires);
         let session = this.sessions.get(identity.fingerprint256);
         if (!session) {
             session = new Session({
+                stateDir: this.config.stateDir,
+                notifications: identity.wake !== undefined,
                 allowed: (candidate) => this.allowed(candidate),
                 lost: (fp, count) => this.lost(fp, count),
                 losses: (fp) => this.losses.get(fp) ?? 0,
@@ -114,14 +161,19 @@ class Bridge {
         if (!socket.authorized ||
             !identity ||
             this.stopping ||
-            !Number.isFinite(expires) ||
-            !Number.isFinite(starts) ||
-            starts > Date.now() ||
-            expires <= Date.now()) {
+            !validCertificateDates(starts, expires)) {
             log("connection_rejected", { fingerprint: fp, result: "unauthorized" });
             socket.destroy();
             return;
         }
+        try {
+            this.presence?.authenticated(identity, expires);
+        }
+        catch {
+            log("connection_rejected", { fingerprint: fp, result: "presence_storage_failed" });
+            socket.destroy();
+            return;
+        }
         const expiry = () => {
             if (expires <= Date.now()) {
                 this.drop(fp, new Fault(403, "certificate_expired", "Client certificate expired."));
@@ -143,6 +195,7 @@ class Bridge {
         log("connected", { name: identity.name, fingerprint: fp, result: "authenticated" });
     }
     drop(fp, error) {
+        this.deliveries.drop(fp);
         this.sessions.get(fp)?.close(error);
         for (const [socket, connection] of this.connections) {
             if (connection.fingerprint === fp) {
@@ -160,6 +213,7 @@ class Bridge {
                 port: typeof address === "object" && address ? address.port : this.config.port,
                 brokerSocket: getBrokerSocketPath(),
             });
+            this.presence?.start();
         });
         process.on("SIGHUP", () => this.reload());
         // Retain listeners during dispatch: selected SDK dependencies use signal-exit's listener check.
@@ -177,12 +231,13 @@ class Bridge {
             }
             this.config = next;
             this.revokeRemoved();
-            this.launcher.revoke(next.clients).catch(() => log("launch_cleanup", { result: "failed" }));
+            this.operations.revoke(next.clients).catch(() => log("launch_cleanup", { result: "failed" }));
             log("allowlist_reloaded", { result: "accepted", clients: next.clients.size });
         }
         catch {
             this.config = { ...this.config, clients: new Map() };
-            this.launcher
+            this.deliveries.reload();
+            this.operations
                 .revoke(this.config.clients)
                 .catch(() => log("launch_cleanup", { result: "failed" }));
             for (const session of this.sessions.values()) {
@@ -196,6 +251,7 @@ class Bridge {
         }
     }
     revokeRemoved() {
+        this.deliveries.reload();
         for (const [fp, session] of this.sessions) {
             if (!this.allowed(session.identity)) {
                 this.drop(fp, new Fault(403, "revoked", "Identity revoked or changed by configuration reload."));
@@ -234,7 +290,9 @@ class Bridge {
         await Promise.all([
             ...this.handlers,
             ...sessions.map((session) => session.settled()),
-            this.launcher.shutdown(),
+            this.operations.shutdown(),
+            this.presence?.stop(),
+            this.deliveries.stop(),
         ]);
         log("shutdown", { result: "closed" });
     }
@@ -254,7 +312,11 @@ class Bridge {
             this.drop(connection.fingerprint, fault);
             throw fault;
         }
-        return { identity, expires: connection.expires };
+        return {
+            identity,
+            expires: connection.expires,
+            certificate: authenticatedCertificateChain(socket),
+        };
     }
     async handle(req, res) {
         const requestId = randomUUID();
@@ -274,7 +336,7 @@ class Bridge {
             deadline = setTimeout(() => session?.close(new Fault(504, "request_timeout", "HTTP operation deadline exceeded; delivery may be unknown.")), Math.max(1, ms - (Date.now() - started)));
         };
         try {
-            const { identity, expires } = this.admission(req);
+            const { identity, expires, certificate } = this.admission(req);
             const route = routeFor(req);
             session = this.session(identity, expires);
             controller = session.begin();
@@ -282,15 +344,19 @@ class Bridge {
             req.once("aborted", abort);
             res.once("close", onClose);
             const duration = route === "POST /v1/ask" ? ASK_TIMEOUT + 15000 : 15000;
-            setDeadline(route === "POST /v1/start" ? 75000 : duration);
+            setDeadline(LONG_ROUTES.has(route) ? 75000 : duration);
             const operation = await operationFor(req, route, signal);
             if (operation.route === "POST /v1/ask") {
                 setDeadline(operation.timeoutMs + 15000);
             }
-            const data = await this.execute(operation, session, {
+            else if (operation.route === "GET /v1/transcript") {
+                setDeadline(75000);
+            }
+            const data = await this.operations.execute(operation, session, {
                 signal,
                 requestId,
                 expires,
+                certificate,
                 onPeer: (id) => {
                     peer = id;
                 },
@@ -304,10 +370,7 @@ class Bridge {
                 ? error
                 : new Fault(503, "broker_unavailable", "Local broker operation failed.");
             log("request", { ...session?.fields(), requestId, peer, result: fault.code });
-            reply(res, requestId, fault.status, {
-                ok: false,
-                error: { code: fault.code, message: fault.message, ...fault.details },
-            });
+            replyFault(res, requestId, fault);
         }
         finally {
             clearTimeout(deadline);
@@ -318,34 +381,11 @@ class Bridge {
             }
         }
     }
-    async execute(operation, session, context) {
-        switch (operation.route) {
-            case "POST /v1/start":
-                return this.launcher.start(operation.name, {
-                    identity: session.identity,
-                    expires: context.expires,
-                    signal: context.signal,
-                    peers: (signal) => session.connectedPeers(signal),
-                });
-            case "GET /v1/sessions":
-                return this.launcher.list(session.identity);
-            case "POST /v1/stop":
-                return this.launcher.stop(session.identity, operation.sessionId);
-            case "GET /v1/list":
-            case "GET /v1/inbox":
-            case "POST /v1/register":
-            case "POST /v1/ask":
-            case "POST /v1/send":
-            case "POST /v1/reply":
-            case "POST /v1/ack":
-                return session.execute(operation, context);
-        }
-    }
 }
 function main() {
     const args = process.argv.slice(2);
     if (args.length === 1 && (args[0] === "-h" || args[0] === "--help")) {
-        process.stdout.write("Usage: node dist/pi-intercom/bridge.js --config PATH\n\nOptional loopback HTTPS/mTLS bridge for the local pi-intercom broker.\nConfig and TLS key must be owned by you with mode 0600. Never starts the broker.\nSIGHUP reloads the client allowlist (invalid reload denies all clients).\nRestart this helper for TLS/listener rotation. SIGINT/SIGTERM disconnect peers.\n\nExample: node dist/pi-intercom/bridge.js --config ~/.pi/agent/intercom/bridge.json\n");
+        process.stdout.write("Usage: node dist/pi-intercom/bridge.js --config PATH\n\nOptional loopback HTTPS/mTLS bridge for the local pi-intercom broker.\nConfig and TLS key must be owned by you with mode 0600.\nWithout stateDir, messaging never starts the broker. Durable presence safely starts\none only when none is running; it never restarts or replaces a live broker.\nSIGHUP reloads the client allowlist (invalid reload denies all clients).\nRestart this helper for TLS/listener rotation. SIGINT/SIGTERM disconnect peers.\n\nExample: node dist/pi-intercom/bridge.js --config ~/.pi/agent/intercom/bridge.json\n");
         return;
     }
     if (args.length !== 2 || args[0] !== "--config" || args[1] === "") {
@@ -358,7 +398,7 @@ function main() {
         new Bridge(loadConfig(path), path).start();
     }
     catch {
-        process.stderr.write("Bridge startup failed: check config schema, file ownership/mode 0600, absolute TLS/cwd paths, TLS credentials, and launch policy (0700 sessionDir, Pi packageRoot, extension paths).\n");
+        process.stderr.write("Bridge startup failed: check config schema, file ownership/mode 0600, absolute TLS/cwd paths, TLS credentials, stateDir (owned 0700 directory), and launch policy (0700 sessionDir, Pi packageRoot, extension paths).\n");
         process.exitCode = 1;
     }
 }

package/dist/pi-intercom/broker/client.js

@@ -320,6 +320,7 @@ export class IntercomClient extends EventEmitter {
             expectsReply: options.expectsReply,
             ...(options.human ? { human: options.human } : {}),
             ...(options.topic ? { topic: options.topic } : {}),
+            ...(options.control ? { control: options.control } : {}),
             delivery: messageDelivery(options),
             queueMode: options.queueMode,
             threadId: options.threadId,

package/dist/pi-intercom/connection.js

@@ -1,8 +1,7 @@
-import { createHash } from "node:crypto";
 import { IntercomClient } from "./broker/client.js";
 import { spawnBrokerIfNeeded } from "./broker/spawn.js";
 import { asError, errorMessage } from "./validation.js";
-import { formatTargetOptions, resolveSessionTarget } from "./session-targets.js";
+import { formatTargetOptions, resolveSessionTarget, nativePeerId } from "./session-targets.js";
 /** Owns socket registration, coalesced connects and the reconnect/startup timers. */
 export class IntercomConnection {
     client = null;
@@ -195,7 +194,7 @@ export class IntercomConnection {
             if (reason !== "peer-awareness") {
                 await spawnBrokerIfNeeded(this.config.brokerCommand, this.config.brokerArgs);
             }
-            await next.connect(await this.lifecycle.registration(this.hooks.pendingAsks()), `pi-${createHash("sha256").update(sessionId).digest("hex").slice(0, 32)}`);
+            await next.connect(await this.lifecycle.registration(this.hooks.pendingAsks()), nativePeerId(sessionId));
             if (!this.lifecycle.live(ctx, generation)) {
                 await next.disconnect();
                 throw new Error("Intercom runtime no longer active");

package/dist/pi-intercom/inbound.js

@@ -1,7 +1,7 @@
-import { createHash } from "node:crypto";
 import { requestedDelivery, isBlockingSupervisorMessage } from "./inbound-record.js";
 import { formatAttachments } from "./message-format.js";
 import { readQuestionOwner } from "../runs/shared/supervisor-questions.js";
+import { nativePeerId } from "./session-targets.js";
 /** Validates origin and chooses admission; state/resources remain in their owners. */
 export class IntercomInbound {
     lifecycle;
@@ -19,9 +19,7 @@ export class IntercomInbound {
             return false;
         }
         const owner = readQuestionOwner(origin.runId);
-        return (owner?.sessionId === origin.ownerSessionId &&
-            from.id ===
-                `pi-${createHash("sha256").update(origin.ownerSessionId).digest("hex").slice(0, 32)}`);
+        return (owner?.sessionId === origin.ownerSessionId && from.id === nativePeerId(origin.ownerSessionId));
     }
     normalize(from, input) {
         const message = input.topic

package/dist/pi-intercom/index.js

@@ -8,6 +8,7 @@ import { InboundDeliveryOwner } from "./inbound-delivery.js";
 import { ReplyWait } from "./reply-wait.js";
 import { IntercomConnection } from "./connection.js";
 import { IntercomInbound } from "./inbound.js";
+import { NativeControls } from "./native-control.js";
 import { IntercomOutbound } from "./outbound.js";
 import { IntercomInspection } from "./inspection.js";
 import { IntercomTopicActions } from "./topic-actions.js";
@@ -31,7 +32,11 @@ export default function piIntercomExtension(pi) {
     const connection = new IntercomConnection(lifecycle, config, topics, {
         restoring: () => delivery.restoring,
         pendingAsks: () => replies.listPending().length,
-        incoming: (ctx, from, message) => inbound.receive(ctx, from, message),
+        incoming: async (ctx, from, message) => {
+            if (!(await controls.receive(ctx, from, message))) {
+                await inbound.receive(ctx, from, message);
+            }
+        },
         peerLeft: (id) => {
             wait.peerDisconnected(id);
             journal.peerLeft(id);
@@ -42,6 +47,7 @@ export default function piIntercomExtension(pi) {
             }
         },
     });
+    const controls = new NativeControls(lifecycle, connection);
     const delivery = new InboundDeliveryOwner(pi, lifecycle, journal, {
         replies,
         syncStatus: () => connection.syncStatus(),

package/dist/pi-intercom/native-control-auth.js

@@ -0,0 +1,80 @@
+import { X509Certificate } from "node:crypto";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { existsSync } from "node:fs";
+import { loadControlPolicy } from "./bridge-config.js";
+import { getPiAgentDir } from "./agent-dir.js";
+import { fingerprint } from "./bridge-protocol.js";
+export function authenticatedCertificateChain(socket) {
+    const blocks = [];
+    const seen = new Set();
+    let cert = socket.getPeerCertificate(true);
+    for (let depth = 0; depth < 8; depth += 1) {
+        const parsed = new X509Certificate(cert.raw);
+        if (seen.has(parsed.fingerprint256)) {
+            break;
+        }
+        seen.add(parsed.fingerprint256);
+        blocks.push(parsed.toString());
+        cert = cert.issuerCertificate;
+    }
+    return blocks.join("\n");
+}
+function certificates(pem) {
+    const blocks = pem.match(/-----BEGIN CERTIFICATE-----[\s\S]*?-----END CERTIFICATE-----/g);
+    if (!blocks || blocks.length > 8) {
+        throw new Error("Invalid bounded certificate chain.");
+    }
+    return blocks.map((block) => new X509Certificate(block));
+}
+function validNow(cert) {
+    return Date.parse(cert.validFrom) <= Date.now() && Date.parse(cert.validTo) > Date.now();
+}
+function trustedChain(chain, roots) {
+    let current = chain.at(0);
+    if (current === undefined || current.ca || !validNow(current)) {
+        return false;
+    }
+    for (let depth = 0; depth < 8; depth += 1) {
+        const subject = current;
+        const issuer = [...roots, ...chain.slice(1)].find((candidate) => candidate.ca &&
+            validNow(candidate) &&
+            subject.checkIssued(candidate) &&
+            subject.verify(candidate.publicKey));
+        if (!issuer) {
+            return false;
+        }
+        if (roots.some((root) => root.fingerprint256 === issuer.fingerprint256)) {
+            return true;
+        }
+        current = issuer;
+    }
+    return false;
+}
+function controlPolicyPath() {
+    const configured = process.env.PI_INTERCOM_BRIDGE_CONFIG;
+    if (configured !== undefined) {
+        return configured;
+    }
+    const standard = join(getPiAgentDir(), "intercom", "bridge.json");
+    return existsSync(standard) ? standard : join(homedir(), ".pi", "intercom-bridge", "config.json");
+}
+/** Unix broker peers are same-user trusted. Names/payload claims grant no authority. */
+export function authorizedControlPeer(peerId, certificate) {
+    try {
+        const configPath = controlPolicyPath();
+        const config = loadControlPolicy(configPath);
+        const chain = certificates(certificate);
+        const client = chain.at(0);
+        if (client === undefined) {
+            return false;
+        }
+        const fp = fingerprint(client.fingerprint256);
+        return (peerId === `remote-${fp.toLowerCase()}` &&
+            config.clients.has(fp) &&
+            trustedChain(chain, certificates(config.ca.toString("utf8"))));
+    }
+    catch {
+        return false;
+    }
+}

package/dist/pi-intercom/native-control-protocol.js

@@ -0,0 +1,111 @@
+import { isRecord, isUnknownArray } from "../shared/unknown.js";
+export const CONTROL_SCHEMA = "pi-intercom/control-v1";
+export const CONTROL_FALLBACK = "Native Intercom metadata exchange (no conversation response needed).";
+export function isControlVerb(value) {
+    return (value === "capabilities" || value === "cancel" || value === "stop" || value === "transcript");
+}
+export function isControlRequest(value) {
+    return (isRecord(value) &&
+        value.schema === CONTROL_SCHEMA &&
+        value.kind === "request" &&
+        isControlVerb(value.verb) &&
+        typeof value.certificate === "string" &&
+        value.certificate.length <= 16384 &&
+        Object.keys(value).every((key) => ["schema", "kind", "verb", "certificate", "options"].includes(key)));
+}
+export function isControlResult(value) {
+    if (!isRecord(value) ||
+        value.schema !== CONTROL_SCHEMA ||
+        value.kind !== "result" ||
+        !isControlVerb(value.verb)) {
+        return false;
+    }
+    return (validResultFields(value) &&
+        validResultPayload(value) &&
+        Buffer.byteLength(JSON.stringify(value)) <= 1024 * 1024);
+}
+function optionalText(value, max) {
+    return value === undefined || (typeof value === "string" && value.length <= max);
+}
+function validResultFields(value) {
+    const fields = new Set([
+        "schema",
+        "kind",
+        "verb",
+        "status",
+        "mode",
+        "idle",
+        "pendingInput",
+        "queueCleared",
+        "processExited",
+        "stopSupport",
+        "reason",
+        "transcript",
+        "verbs",
+    ]);
+    return (Object.keys(value).every((key) => fields.has(key)) &&
+        typeof value.status === "string" &&
+        ["ok", "denied", "cancel_requested", "shutdown_requested", "unsupported", "failed"].includes(value.status) &&
+        optionalText(value.reason, 2048) &&
+        optionalText(value.mode, 64) &&
+        [value.idle, value.pendingInput].every((flag) => flag === undefined || typeof flag === "boolean") &&
+        [value.queueCleared, value.processExited].every((flag) => flag === undefined || flag === false));
+}
+function validResultPayload(value) {
+    if (value.stopSupport !== undefined &&
+        (typeof value.stopSupport !== "string" ||
+            !["native_shutdown", "requires_activity", "host_dependent"].includes(value.stopSupport))) {
+        return false;
+    }
+    if (value.verbs !== undefined &&
+        (!isUnknownArray(value.verbs) || !value.verbs.every(isControlVerb))) {
+        return false;
+    }
+    return value.transcript === undefined || validTranscript(value.transcript);
+}
+function validTranscript(value) {
+    if (!isRecord(value) || !isUnknownArray(value.records) || value.records.length > 100) {
+        return false;
+    }
+    const fields = new Set([
+        "sessionId",
+        "leafId",
+        "records",
+        "bytes",
+        "truncated",
+        "cursor",
+        "scanLimitReached",
+        "finalizedOnly",
+        "streaming",
+    ]);
+    return (Object.keys(value).every((key) => fields.has(key)) &&
+        typeof value.sessionId === "string" &&
+        value.sessionId.length <= 512 &&
+        (value.leafId === null || typeof value.leafId === "string") &&
+        value.records.every(validTranscriptRecord) &&
+        validTranscriptMetadata(value));
+}
+function validTranscriptMetadata(value) {
+    return (typeof value.bytes === "number" &&
+        Number.isInteger(value.bytes) &&
+        value.bytes >= 0 &&
+        value.bytes <= 131072 &&
+        typeof value.truncated === "boolean" &&
+        optionalText(value.cursor, 512) &&
+        typeof value.scanLimitReached === "boolean" &&
+        value.finalizedOnly === true &&
+        value.streaming === "unavailable");
+}
+function validTranscriptRecord(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    const fields = new Set(["id", "timestamp", "role", "text", "truncated"]);
+    return (Object.keys(value).every((key) => fields.has(key)) &&
+        [value.id, value.timestamp].every((field) => typeof field === "string" && field.length <= 512) &&
+        typeof value.role === "string" &&
+        ["user", "assistant", "toolResult", "custom"].includes(value.role) &&
+        typeof value.text === "string" &&
+        Buffer.byteLength(value.text) <= 131072 &&
+        typeof value.truncated === "boolean");
+}

package/dist/pi-intercom/native-control.js

@@ -0,0 +1,130 @@
+import { authorizedControlPeer } from "./native-control-auth.js";
+import { CONTROL_FALLBACK, CONTROL_SCHEMA, isControlRequest, } from "./native-control-protocol.js";
+import { readLiveTranscript, transcriptOptions } from "./transcript.js";
+export class NativeControls {
+    lifecycle;
+    connection;
+    constructor(lifecycle, connection) {
+        this.lifecycle = lifecycle;
+        this.connection = connection;
+    }
+    result(ctx, request) {
+        const base = {
+            schema: CONTROL_SCHEMA,
+            kind: "result",
+            verb: request.verb,
+            mode: ctx.mode,
+            idle: ctx.isIdle(),
+            pendingInput: ctx.hasPendingMessages(),
+            queueCleared: false,
+            processExited: false,
+        };
+        if (request.verb !== "transcript" && request.options !== undefined) {
+            throw new Error("Only transcript accepts options.");
+        }
+        const stopSupport = stopCapability(ctx);
+        switch (request.verb) {
+            case "capabilities":
+                return {
+                    ...base,
+                    status: "ok",
+                    stopSupport,
+                    verbs: ["capabilities", "cancel", "stop", "transcript"],
+                };
+            case "transcript":
+                return {
+                    ...base,
+                    status: "ok",
+                    transcript: readLiveTranscript(ctx.sessionManager, transcriptOptions(request.options)),
+                };
+            case "cancel":
+                return {
+                    ...base,
+                    status: "cancel_requested",
+                    reason: "Native current-operation abort; accepted queued input is not cleared.",
+                };
+            case "stop":
+                return {
+                    ...base,
+                    status: ctx.mode === "print" || ctx.mode === "json" ? "unsupported" : "shutdown_requested",
+                    stopSupport,
+                    reason: "Native shutdown/current-operation abort requested, not process exit. Idle RPC is deferred until a native command/settlement; print/JSON/SDK have no guaranteed shutdown binding.",
+                };
+        }
+    }
+    async receive(ctx, from, message) {
+        if (!Object.hasOwn(message, "control")) {
+            return false;
+        }
+        // Even malformed/response envelopes never enter conversation journaling or inference.
+        const request = message.control;
+        if (!isControlRequest(request) ||
+            message.replyTo !== undefined ||
+            message.delivery !== "passive" ||
+            message.expectsReply === true) {
+            return true;
+        }
+        const generation = this.lifecycle.generation;
+        const active = this.connection.active;
+        if (!active || !this.lifecycle.live(ctx, generation)) {
+            return true;
+        }
+        const result = this.admit(ctx, from.id, request);
+        // Receipt is acknowledged before shutdown can retire this socket/context.
+        await active.send(from.id, {
+            text: CONTROL_FALLBACK,
+            delivery: "passive",
+            replyTo: message.id,
+            control: result,
+        });
+        this.apply(ctx, generation, { active, peer: from.id, request, result });
+        return true;
+    }
+    apply(ctx, generation, state) {
+        const { active, peer, request, result } = state;
+        if (!this.lifecycle.live(ctx, generation) ||
+            this.connection.active !== active ||
+            !authorizedControlPeer(peer, request.certificate)) {
+            return;
+        }
+        if (result.status === "shutdown_requested" ||
+            (result.status === "unsupported" && request.verb === "stop")) {
+            ctx.shutdown();
+            if (this.lifecycle.live(ctx, generation)) {
+                ctx.abort();
+            }
+        }
+        else if (result.status === "cancel_requested") {
+            ctx.abort();
+        }
+    }
+    admit(ctx, peer, request) {
+        if (!authorizedControlPeer(peer, request.certificate)) {
+            return {
+                schema: CONTROL_SCHEMA,
+                kind: "result",
+                verb: request.verb,
+                status: "denied",
+                reason: "Sender certificate is not currently authorized by private bridge configuration.",
+            };
+        }
+        try {
+            return this.result(ctx, request);
+        }
+        catch {
+            return {
+                schema: CONTROL_SCHEMA,
+                kind: "result",
+                verb: request.verb,
+                status: "failed",
+                reason: "Native control input/state is unavailable.",
+            };
+        }
+    }
+}
+function stopCapability(ctx) {
+    if (ctx.mode === "tui") {
+        return "native_shutdown";
+    }
+    return ctx.mode === "rpc" ? "requires_activity" : "host_dependent";
+}