@fitchmultz/pi-subagents 0.45.0 → 0.46.0

package/dist/pi-intercom/bridge.js

@@ -8,12 +8,14 @@ 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";
 const MAX_CONNECTIONS = 128;
 class Bridge {
     config;
     configPath;
     sessions = new Map();
     losses = new Map();
+    launcher = new Launcher();
     sockets = new Set();
     connections = new Map();
     server;
@@ -72,7 +74,7 @@ class Bridge {
     }
     allowed(identity) {
         const current = this.config.clients.get(identity.fingerprint256);
-        return !this.stopping && current?.name === identity.name && current.cwd === identity.cwd;
+        return !this.stopping && sameIdentity(identity, current);
     }
     lost(fp, count = 1) {
         if (count > 0 && this.config.clients.has(fp)) {
@@ -160,8 +162,9 @@ class Bridge {
             });
         });
         process.on("SIGHUP", () => this.reload());
-        process.once("SIGINT", () => this.stop());
-        process.once("SIGTERM", () => this.stop());
+        // Retain listeners during dispatch: selected SDK dependencies use signal-exit's listener check.
+        process.on("SIGINT", () => this.stop());
+        process.on("SIGTERM", () => this.stop());
     }
     reload() {
         if (this.stopping) {
@@ -174,10 +177,14 @@ class Bridge {
             }
             this.config = next;
             this.revokeRemoved();
+            this.launcher.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
+                .revoke(this.config.clients)
+                .catch(() => log("launch_cleanup", { result: "failed" }));
             for (const session of this.sessions.values()) {
                 session.close(new Fault(503, "configuration_invalid", "Configuration reload failed; all identities denied."));
             }
@@ -224,7 +231,11 @@ class Bridge {
         for (const socket of this.sockets) {
             socket.destroy();
         }
-        await Promise.all([...this.handlers, ...sessions.map((session) => session.settled())]);
+        await Promise.all([
+            ...this.handlers,
+            ...sessions.map((session) => session.settled()),
+            this.launcher.shutdown(),
+        ]);
         log("shutdown", { result: "closed" });
     }
     admission(req) {
@@ -270,14 +281,16 @@ class Bridge {
             const signal = controller.signal;
             req.once("aborted", abort);
             res.once("close", onClose);
-            setDeadline(route === "POST /v1/ask" ? ASK_TIMEOUT + 15000 : 15000);
+            const duration = route === "POST /v1/ask" ? ASK_TIMEOUT + 15000 : 15000;
+            setDeadline(route === "POST /v1/start" ? 75000 : duration);
             const operation = await operationFor(req, route, signal);
             if (operation.route === "POST /v1/ask") {
                 setDeadline(operation.timeoutMs + 15000);
             }
-            const data = await session.execute(operation, {
+            const data = await this.execute(operation, session, {
                 signal,
                 requestId,
+                expires,
                 onPeer: (id) => {
                     peer = id;
                 },
@@ -305,6 +318,29 @@ 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);
@@ -322,7 +358,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, and TLS credentials.\n");
+        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.exitCode = 1;
     }
 }

package/dist/shared/native-session-loader.js

@@ -0,0 +1,17 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import * as path from "node:path";
+import { pathToFileURL } from "node:url";
+export async function loadNativeSession(packageRoot) {
+    // The trusted selected Pi package supplies this exact SDK declaration contract.
+    // A computed URL is required: Jiti rewrites literal SDK imports to its own host graph.
+    // oxlint-disable-next-line typescript/no-unsafe-assignment
+    const sessionModule = await import(__rewriteRelativeImportExtension(pathToFileURL(path.join(packageRoot, "dist/index.js")).href));
+    return sessionModule;
+}

package/dist/shared/native-session.js

@@ -1,18 +1,4 @@
-var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
-    if (typeof path === "string" && /^\.\.?\//.test(path)) {
-        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
-            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
-        });
-    }
-    return path;
-};
-import * as path from "node:path";
-import { pathToFileURL } from "node:url";
 import { requirePiPackageRoot } from "../runs/shared/pi-spawn.js";
+import { loadNativeSession } from "./native-session-loader.js";
 // Detached Node runners do not get Pi's extension-loader package aliases.
-const selectedSessionURL = pathToFileURL(path.join(requirePiPackageRoot(), "dist/index.js")).href;
-// The trusted selected Pi package supplies this exact SDK declaration contract.
-// A computed URL is required: Jiti rewrites literal SDK imports to its own host graph.
-// oxlint-disable-next-line typescript/no-unsafe-assignment
-const sessionModule = await import(__rewriteRelativeImportExtension(selectedSessionURL));
-export const { buildSessionContext, parseSessionEntries, migrateSessionEntries, SessionManager } = sessionModule;
+export const { buildSessionContext, parseSessionEntries, migrateSessionEntries, SessionManager } = await loadNativeSession(requirePiPackageRoot());

package/docs/intercom-bridge.md

@@ -1,14 +1,14 @@
 # Secure remote Intercom bridge
 
-Optional HTTPS messaging proxy for a remote agent such as **Grok Bot**. Pi-intercom's broker remains same-machine Unix IPC. Nothing is added to the Pi extension loader, and starting Pi alone never starts this proxy.
+Optional HTTPS messaging proxy and locally controlled Pi-session launcher for a remote agent such as **Grok Bot**. Pi-intercom's broker remains same-machine Unix IPC. Nothing is added to the Pi extension loader, and starting Pi alone never starts this proxy.
 
 ## Design note
 
-**Transport:** a Mac-local Node HTTPS server bound to **127.0.0.1**, carried by a Mac-initiated **SSH reverse TCP forward** to the Linux box's loopback interface. Grok calls HTTPS on its own loopback. Unlike a Unix-socket tunnel, only the proxy opens `broker.sock`; neither the remote nor SSH can issue raw broker frames. This choice needs no cloud account, public DNS, inbound Mac SSH, or per-call laptop approval. An existing SSH account on Linux is the only tunnel prerequisite. SSH authenticates the tunnel host; end-to-end mTLS authenticates both application endpoints even to other processes on Linux.
+**Transport:** a Mac-local Node HTTPS server bound to **127.0.0.1**, carried by a Mac-initiated **SSH reverse TCP forward** to the Linux box's loopback interface. Grok calls HTTPS on its own loopback. Unlike a Unix-socket tunnel, only the local helper and normal local Pi peers use `broker.sock`; neither the remote nor SSH can issue raw broker frames. This choice needs no cloud account, public DNS, inbound Mac SSH, or per-call laptop approval. An existing SSH account on Linux is the only tunnel prerequisite. SSH authenticates the tunnel host; end-to-end mTLS authenticates both application endpoints even to other processes on Linux.
 
 **Threat model:** deny unauthenticated local/network callers, stolen credentials after revocation/expiry, identity spoofing, arbitrary broker commands, forged replies, accidental LAN exposure, and unbounded waits/resource use. The Mac user, local broker, OS, private CA, and approved remote host are trusted. A compromised authorized Grok credential can read peer metadata and send agent-visible text to local peers (including instructions); mTLS does not sandbox those agents or make the content trustworthy. Listed peers can be in other projects. Approve only a host allowed to see that metadata and message those peers. Root/compromised endpoints and denial of service beyond fixed connection/request limits are outside this boundary.
 
-**Auth/authority:** TLS 1.2+ with client certificates issued by a private CA **and** an explicit SHA-256 certificate fingerprint allowlist. Each allowlisted certificate fixes the peer name and Mac project directory; remote payloads cannot change identity, cwd, socket, shell commands, or presence. Certificates last seven days. TLS verifies the server CA and loopback SAN; never use `curl -k` or disable certificate checks. The proxy exposes only register/list/send/ask/reply, plus inbox/ack receipt plumbing needed to receive messages and answer local asks. No broker admin, topic operations, file reads, or shell endpoint.
+**Auth/authority:** TLS 1.2+ with client certificates issued by a private CA **and** an explicit SHA-256 certificate fingerprint allowlist. Each allowlisted certificate fixes the peer name and Mac project directory; remote payloads cannot change identity, cwd, socket, shell commands, or presence. Certificates last seven days. TLS verifies the server CA and loopback SAN; never use `curl -k` or disable certificate checks. The proxy exposes register/list/send/ask/reply, inbox/ack receipt plumbing, and optional name-only start plus own-launched sessions/stop operations. No broker admin, topic operations, file reads, or shell endpoint.
 
 **Socket discovery:** reuse the actual `IntercomClient`, `getBrokerSocketPath()` and framing code. With the same Mac uid, `PI_CODING_AGENT_DIR` (default `~/.pi/agent`) and `TMPDIR` as Pi, the preferred path is `$TMPDIR/pi-intercom-<sha256(uid:agentDir)[0:16]>/broker.sock`; long paths fall back to `/tmp`. The client's existing owned-socket legacy fallback is retained. No hardcoded `/var/folders` path, chmod, broker spawn, PID-file operation, or broker restart. An unavailable broker returns an error; start a normal Pi session to bring it up.
 
@@ -105,6 +105,53 @@ ssh "$GROK_SSH" 'chmod 600 ~/.config/pi-intercom/*'
 
 For a least-privileged dedicated Linux SSH tunnel account, the administrator can restrict its key to remote forwarding with `restrict,port-forwarding,permitlisten="127.0.0.1:9443",command="/bin/false"` and `AllowTcpForwarding remote`, `GatewayPorts no`. `-N` requests no shell. Provision files separately; do not reuse Grok's client key as an SSH key. No SSH login credential for the Mac is given to Grok.
 
+## Enable controlled destination-session launches
+
+Launching is **disabled by default**, independently for each certificate identity. Messaging-only installs and helper `--help` do not require a Pi SDK. To enable launches, add `launch` to the selected client in the private Mac configuration and create an owned **0700** session directory first:
+
+```bash
+mkdir -m 700 "$BRIDGE/sessions"
+```
+
+```json
+{
+  "packageRoot": "/absolute/immutable/node_modules/@earendil-works/pi-coding-agent",
+  "sessionDir": "/Users/mitch/.pi/intercom-bridge/sessions",
+  "provider": "openai-codex",
+  "model": "EXACT_MODEL_ID",
+  "context": "This is a locally authorized remote Intercom session. Stay idle until an Intercom task arrives and reply through Intercom.",
+  "extensions": [
+    "/absolute/pi-subagents/dist/pi-intercom/index.js",
+    "/absolute/pi-subagents/dist/extension/index.js"
+  ],
+  "discoverResources": false,
+  "trustProject": false,
+  "offline": false,
+  "maxSessions": 4,
+  "startupTimeoutMs": 15000
+}
+```
+
+The helper runs its **physical Node executable**, resolves only the pinned package's manifest `bin.pi`, and uses the identity's fixed, canonical Mac `cwd`. Use the intended installed fork, not a development SDK with the same version. `provider` and `model` must be exact IDs, without fuzzy matching or a thinking suffix. Local settings still choose model reasoning. Native launch context is a genuine user instruction written using that package's exported `SessionManager`; it creates a **0600 native JSONL journal without submitting a prompt or running inference**. The session then starts idle in RPC mode. Success requires exact saved ID/name/file/model, idle RPC state, and actual publication of its named Intercom broker peer. This proves startup, **not provider credential usability**; verify the first real task/reply separately.
+
+Resources are locally controlled. `extensions` requires 1–32 existing absolute paths including Intercom; include subagents and any other useful locally approved extensions there. By default (`discoverResources:false`), discovered/configured/built-in extensions, skills, templates, themes and context-file discovery are disabled; explicit extensions still load. This is an explicit resource selection, not full normal discovery. Set `discoverResources:true` to retain normal native discovery; use the **same physical Intercom extension path already selected by native settings**, avoiding duplicate owners loaded from separate installed copies. `trustProject` (default false) chooses native `--approve` versus `--no-approve` for the fixed local project; it is not a remote approval. `offline` (default false) disables automatic catalog/network activity, not requested model inference. The child retains local credentials and normal environment, but strips enclosing `PI_SUBAGENT_*` identity/control metadata so it is an independent session.
+
+Send SIGHUP after editing policy. Removing/changing an identity or its launch policy stops its existing children; invalid reload denies everyone and stops all owned children. Credential `issue` preserves launch policy but replaces the fingerprint, so rotation also stops the old credential's children. Only this helper's own children may be stopped, never arbitrary Pi sessions or the broker.
+
+```bash
+node "$REMOTE" start --name planner
+node "$REMOTE" sessions
+# Use peerId from start/sessions as the ordinary messaging target:
+node "$REMOTE" ask --to PI_PEER_ID --message 'Review the current project and reply with your findings.'
+node "$REMOTE" stop --session-id NATIVE_SESSION_ID
+```
+
+Names are prefixed `remote:IDENTITY:NAME` to avoid impersonating local peers. An already-live name for the same identity is reused; a concurrent start/stop returns a conflict, not a duplicate launch. After a lost start response, inspect `sessions` or repeat the **same name**, not a fresh name. Name is the **only** remote launch input: no task, cwd, shell, environment, flags, model, resource paths or raw RPC commands. Submit tasks afterward through ordinary Intercom. Fixed cwd and launch settings are **not a sandbox**: the authorized agent can use its locally enabled tools and credentials. Grant launch permission only to a remote identity trusted with that authority and potential model costs.
+
+Caps are 4 sessions per identity by default (local range 1–16), and 32 active launches helper-wide. Readiness deadline defaults to 15 seconds (local range 1–60000 ms). HTTP start has a 75-second outer deadline; CLI start has 90 seconds including cleanup. Startup failure, abort, deadline, explicit stop, identity revocation, certificate expiry and helper SIGINT/SIGTERM stop owned children. Each launch has a private, helper-owned process group. Cleanup closes stdin, escalates that group to TERM/KILL after 1/3 seconds if needed (including unresponsive native workers), and observes actual process closure within 8 seconds; it does not report a signal request as a completed exit. A cleanup deadline returns `stop_timeout`; inspect `sessions` and retry stop, even if the process has since exited. Unsupported RPC dialogs are cancelled and the session is stopped with `interaction_required`; they are never automatically approved. RPC events/diagnostics are continuously drained. Control records are bounded to 4 MiB; oversized unused native transcript/tool events are discarded through their LF boundary with metadata-only overflow reporting, without truncating the native session/tool result or killing a healthy peer. Raw stderr/model/tool content is never sent to the audit log.
+
+Long-lived peers are **not tied to the remote presence peer's five-minute idle lease** or an HTTP connection. They remain available while the helper and certificate authorization remain valid. Journals survive stop/failure/restart and can be resumed locally with the pinned Pi's `--session PATH`; the helper does not silently restart or adopt old/native processes. `sessions` reports current helper ownership, state, PID, native journal path and metadata-only error codes; at most 64 recent records are retained. The PID identifies the owned manifest-CLI process; a supervised fork can run Pi in its native worker. It is not an all-machine session admin API. Planned helper shutdown stops its children; do not SIGKILL the helper to perform routine cleanup.
+
 ## Grok Bot: exact remote commands
 
 On Linux, configure Grok's shell environment:
@@ -141,15 +188,18 @@ curl --fail-with-body --max-time 135 \
 
 All routes require mTLS and the certificate allowlist. Unknown routes/fields, wrong methods, non-JSON bodies, unsafe control characters, and requests larger than 64 KiB are rejected. No CORS; browser-origin requests are rejected. Success is `{ "ok": true, ... }`; application failures are `{ "ok": false, "error": { "code": "...", "message": "..." } }` with a non-2xx status. Certificate/allowlist admission can terminate TLS before HTTP; the CLI reports that as a TLS/transport error. No remote-controlled broker frame or command is passed through.
 
-| Route               | Request                   | Success fields                                           |
-| ------------------- | ------------------------- | -------------------------------------------------------- |
-| `POST /v1/register` | `{}`                      | `sessionId`, `name` (also automatic on other operations) |
-| `GET /v1/list`      | none                      | `sessionId`, `sessions` (metadata + unambiguous targets) |
-| `POST /v1/send`     | `{to,message}`            | `id`, `accepted`, `delivered`                            |
-| `POST /v1/ask`      | `{to,message,timeoutMs?}` | send receipt and `reply:{from,message}`                  |
-| `GET /v1/inbox`     | none                      | `messages:[{from,message}]`, `overflow`, `lostMessages`  |
-| `POST /v1/reply`    | `{replyTo,message}`       | send receipt; target derived from the received ask       |
-| `POST /v1/ack`      | `{ids:[...]}`             | `acked`, `retained`                                      |
+| Route               | Request                   | Success fields                                                            |
+| ------------------- | ------------------------- | ------------------------------------------------------------------------- |
+| `POST /v1/register` | `{}`                      | `sessionId`, `name` (also automatic on other operations)                  |
+| `GET /v1/list`      | none                      | `sessionId`, `sessions` (metadata + unambiguous targets)                  |
+| `POST /v1/send`     | `{to,message}`            | `id`, `accepted`, `delivered`                                             |
+| `POST /v1/ask`      | `{to,message,timeoutMs?}` | send receipt and `reply:{from,message}`                                   |
+| `GET /v1/inbox`     | none                      | `messages:[{from,message}]`, `overflow`, `lostMessages`                   |
+| `POST /v1/reply`    | `{replyTo,message}`       | send receipt; target derived from the received ask                        |
+| `POST /v1/ack`      | `{ids:[...]}`             | `acked`, `retained`                                                       |
+| `POST /v1/start`    | `{name}`                  | `session:{sessionId,peerId,name,status,pid,sessionFile,error?}`, `reused` |
+| `GET /v1/sessions`  | none                      | `sessions` (only current helper/identity-owned launch records)            |
+| `POST /v1/stop`     | `{sessionId}`             | `session` with observed `exited` status; journal retained                 |
 
 Timeout does **not** retract a delivered ask; a late answer can arrive in inbox. Offline/missing peers, broker outages, ambiguous/self targets, a second concurrent ask, invalid/revoked credentials, timeout, and resource limits have explicit errors. HTTP send/list deadlines are bounded by the real client (8/5 seconds); broker registration by 10 seconds. A lost HTTP response or acknowledgement timeout means **delivery unknown**—inspect inbox/local peer before retrying to avoid duplicate instructions.
 
@@ -180,10 +230,10 @@ Confirm the reload/revocation audit record, that Grok disappears from the local
 
 ## Verification / smoke transcript
 
-The process-boundary integration test uses a private real broker, real TLS certificates, actual HTTPS requests and the remote CLI; it requires no model/provider credentials:
+The process-boundary tests use a private real broker, real TLS certificates, actual HTTPS requests and the remote CLI. Launch tests use the actually installed Pi dependency graph with a selected-host native faux provider (no paid inference or external credentials); they prove native persistence, zero pre-startup inference, real Intercom wake/tool reply, ownership/caps, startup failure/abort/deadline, safe dialog cancellation, presence-lease independence, short-lived certificate expiry, rotation/revocation and child exit before helper shutdown completes:
 
 ```bash
-node --test test/integration/intercom-bridge.test.ts
+node --test test/integration/intercom-bridge.test.ts test/integration/intercom-bridge-launch.test.ts
 # Do not inject host startup diagnostics into native fixture stderr:
 env -u PI_TIMING -u PI_EXTENSION_PERFORMANCE npm run ci
 ```

package/docs/reference.md

@@ -375,7 +375,7 @@ The files in `prompts/` document common workflows without registering additional
 
 ## Bundled intercom
 
-For a remote agent on Linux, the optional [secure remote bridge](intercom-bridge.md) provides a loopback-only mTLS HTTPS API over an SSH reverse forward. It registers a certificate-bound peer such as `grok-bot` and permits only messaging operations; the private Unix broker socket remains local. The guide includes setup, remote commands, credential rotation and revocation.
+For a remote agent on Linux, the optional [secure remote bridge](intercom-bridge.md) provides a loopback-only mTLS HTTPS API over an SSH reverse forward. It registers a certificate-bound peer such as `grok-bot` and supports messaging and optional locally pinned, name-only starts of persistent Pi sessions on the destination machine; the private Unix broker socket remains local. The guide includes setup, remote start/sessions/stop commands, lifecycle limits, credential rotation and revocation.
 
 The same `pi-subagents` install registers the intercom extension and skill. `load_intercom({})` exposes the full peer tool explicitly; actionable peer inbound and recovered reply needs also expose it before use. Presence, passive breadcrumbs, routine subagent notices, and human messages answered in chat do not. Broker presence and delivery continue even with the schema hidden. Managed children get a private coordination channel back to the parent Pi session unless an explicit agent extension allowlist excludes it. See [the intercom guide](intercom.md) for direct peer messaging, keyboard UI, tool actions, configuration, and broker details.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitchmultz/pi-subagents",
-  "version": "0.45.0",
+  "version": "0.46.0",
   "description": "Pi extension for subagent orchestration and local session coordination",
   "license": "MIT",
   "type": "module",

package/scripts/intercom-bridge-credentials.mjs

@@ -25,7 +25,7 @@ function help() {
   console.log(`Usage: node scripts/intercom-bridge-credentials.mjs <init|issue|revoke> DIR [NAME] [--cwd PATH]
 
 init    Create a new private CA, loopback server certificate and grok-bot credential.
-issue   Issue a fresh 7-day client certificate; replace that name's old authorization.
+issue   Issue a fresh 7-day client certificate; preserve local launch policy.
 revoke  Remove the named client from the allowlist. Does not delete saved credentials.
 
 Options: --cwd PATH  Local project identity for init/issue (default: current directory)
@@ -38,6 +38,7 @@ Examples:
   node scripts/intercom-bridge-credentials.mjs revoke ~/.pi/intercom-bridge grok-bot
 
 After issue/revoke, send SIGHUP to the helper PID to activate the allowlist.
+Rotation/revocation stops that identity's helper-launched Pi children; journals remain.
 Concurrent credential commands fail rather than overwrite each other's authorization.
 After a crashed command, inspect DIR/.credentials.lock/owner and remove that lock
 only after confirming its process has stopped.
@@ -247,6 +248,7 @@ try {
       fingerprint256: credential.fingerprint256,
       name,
       cwd: resolve(args.values.cwd || previous?.cwd || process.cwd()),
+      ...(previous?.launch === undefined ? {} : { launch: previous.launch }),
     });
     atomicConfig(configPath, config);
     console.log(

package/scripts/intercom-remote.mjs

@@ -4,7 +4,7 @@ import { lstatSync, readFileSync } from "node:fs";
 import { parseArgs } from "node:util";
 
 function help() {
-  console.log(`Usage: node intercom-remote.mjs <register|list|inbox|send|ask|reply|ack> [options] [IDs...]
+  console.log(`Usage: node intercom-remote.mjs <register|list|inbox|send|ask|reply|ack|start|sessions|stop> [options] [IDs...]
 
 Environment (required):
   INTERCOM_BRIDGE_CA    Path to trusted bridge CA certificate
@@ -17,6 +17,8 @@ Options:
   --message TEXT       Message for send/ask/reply
   --reply-to ID        Inbound ask ID from inbox, for reply
   --timeout-ms MS      Ask timeout (100..120000, default: 120000)
+  --name NAME          Start/reuse a named idle Pi session under local policy
+  --session-id ID      Stop only a Pi session launched by this identity/helper
   -h, --help           Show help
 
 Examples:
@@ -25,12 +27,21 @@ Examples:
   node intercom-remote.mjs inbox
   node intercom-remote.mjs reply --reply-to QUESTION_ID --message 'Proceed.'
   node intercom-remote.mjs ack MESSAGE_ID
+  node intercom-remote.mjs start --name planner
+  node intercom-remote.mjs sessions
+  node intercom-remote.mjs stop --session-id NATIVE_SESSION_ID
 
 Outputs JSON. Exit: 0 success, 1 API/TLS/transport failure, 2 invalid arguments.
 No automatic retries: a lost response does not prove a message was unsent.`);
 }
 
 function allowedOptions(action) {
+  if (action === "start") {
+    return ["name"];
+  }
+  if (action === "stop") {
+    return ["session-id"];
+  }
   if (action === "send") {
     return ["to", "message"];
   }
@@ -54,7 +65,17 @@ function requireMessage(recipient, message) {
   }
 }
 
+function launchBody(action, options) {
+  const value = action === "start" ? options.name : options["session-id"];
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(action === "start" ? "--name is required." : "--session-id is required.");
+  }
+  return action === "start" ? { name: value } : { sessionId: value };
+}
 function requestBody(action, options, ids, timeout) {
+  if (action === "start" || action === "stop") {
+    return launchBody(action, options);
+  }
   if (["send", "ask", "reply"].includes(action)) {
     const recipient = action === "reply" ? options["reply-to"] : options.to;
     requireMessage(recipient, options.message);
@@ -108,6 +129,8 @@ try {
       message: { type: "string" },
       "reply-to": { type: "string" },
       "timeout-ms": { type: "string" },
+      name: { type: "string" },
+      "session-id": { type: "string" },
     },
   });
   if (parsed.values.help) {
@@ -116,7 +139,20 @@ try {
   }
   const options = parsed.values;
   [action] = parsed.positionals;
-  if (!["register", "list", "inbox", "send", "ask", "reply", "ack"].includes(action)) {
+  if (
+    ![
+      "register",
+      "list",
+      "inbox",
+      "send",
+      "ask",
+      "reply",
+      "ack",
+      "start",
+      "sessions",
+      "stop",
+    ].includes(action)
+  ) {
     throw new Error("Choose an action; use --help.");
   }
   const allowed = allowedOptions(action);
@@ -159,7 +195,7 @@ try {
   const files = tlsFiles();
   origin.pathname = `/v1/${action}`;
   const payload = JSON.stringify(body);
-  const get = ["list", "inbox"].includes(action);
+  const get = ["list", "inbox", "sessions"].includes(action);
   const result = await new Promise((resolve, reject) => {
     const req = https.request(
       origin,
@@ -203,7 +239,7 @@ try {
       () => {
         req.destroy(new Error("Bridge request deadline exceeded; delivery may be unknown."));
       },
-      (action === "ask" ? timeout : 0) + 15000,
+      action === "start" ? 90000 : (action === "ask" ? timeout : 0) + 15000,
     );
     req.once("close", () => clearTimeout(timer));
     req.once("error", reject);

package/src/pi-intercom/bridge-config.ts

@@ -1,8 +1,17 @@
-import { constants, closeSync, fstatSync, openSync, readFileSync, statSync } from "node:fs";
+import {
+  constants,
+  closeSync,
+  fstatSync,
+  openSync,
+  readFileSync,
+  realpathSync,
+  statSync,
+} from "node:fs";
 import { isAbsolute } from "node:path";
 import { createSecureContext } from "node:tls";
 import { isUnknownArray } from "../shared/unknown.ts";
 import { BODY_LIMIT, object, label, fingerprint } from "./bridge-protocol.ts";
+import { launchPolicy, type LaunchPolicy } from "./bridge-launch-policy.ts";
 
 const MAX_CLIENTS = 64;
 
@@ -10,6 +19,7 @@ export interface Identity {
   readonly fingerprint256: string;
   readonly name: string;
   readonly cwd: string;
+  readonly launch?: LaunchPolicy;
 }
 export interface Config {
   readonly port: number;
@@ -47,17 +57,26 @@ function identities(value: unknown): Map<string, Identity> {
   const clients = new Map<string, Identity>();
   const names = new Set<string>();
   for (const raw of value) {
-    const entry = object(raw, ["fingerprint256", "name", "cwd"]);
+    const entry = object(raw, ["fingerprint256", "name", "cwd", "launch"]);
     const fingerprint256 = fingerprint(entry.fingerprint256);
     const name = label(entry.name, "name", 128).trim();
     const cwd = label(entry.cwd, "cwd", 4096);
-    if (!isAbsolute(cwd) || !statSync(cwd).isDirectory()) {
-      throw new Error("Client cwd must be an existing absolute directory.");
+    if (!isAbsolute(cwd)) {
+      throw new Error("Client cwd must be absolute.");
+    }
+    const launch = launchPolicy(entry.launch);
+    if (launch && !statSync(cwd).isDirectory()) {
+      throw new Error("Launch cwd must be an existing directory.");
     }
     if (clients.has(fingerprint256) || names.has(name.toLowerCase())) {
       throw new Error("Client fingerprints and names must be unique.");
     }
-    clients.set(fingerprint256, { fingerprint256, name, cwd });
+    clients.set(fingerprint256, {
+      fingerprint256,
+      name,
+      cwd: launch ? realpathSync(cwd) : cwd,
+      launch,
+    });
     names.add(name.toLowerCase());
   }
   return clients;

package/src/pi-intercom/bridge-launch-policy.ts

@@ -0,0 +1,109 @@
+import { lstatSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { isAbsolute, join, relative } from "node:path";
+import { isRecord, isUnknownArray } from "../shared/unknown.ts";
+import { label, object, text } from "./bridge-protocol.ts";
+
+export interface LaunchPolicy {
+  readonly packageRoot: string;
+  readonly cli: string;
+  readonly sessionDir: string;
+  readonly provider: string;
+  readonly model: string;
+  readonly context: string;
+  readonly extensions: readonly string[];
+  readonly discoverResources: boolean;
+  readonly trustProject: boolean;
+  readonly offline: boolean;
+  readonly maxSessions: number;
+  readonly startupTimeoutMs: number;
+}
+
+function absolute(value: unknown, field: string): string {
+  const path = label(value, field, 4096);
+  if (!isAbsolute(path)) {
+    throw new Error(`${field} must be absolute.`);
+  }
+  return realpathSync(path);
+}
+function bounded(value: unknown, fallback: number, max: number): number {
+  const number = value ?? fallback;
+  if (typeof number !== "number" || !Number.isInteger(number) || number < 1 || number > max) {
+    throw new Error("Invalid launch limit.");
+  }
+  return number;
+}
+function boolean(value: unknown, fallback: boolean): boolean {
+  if (value === undefined) {
+    return fallback;
+  }
+  if (typeof value !== "boolean") {
+    throw new Error("Launch switches must be boolean.");
+  }
+  return value;
+}
+function executable(packageRoot: string): string {
+  const manifest: unknown = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+  if (
+    !isRecord(manifest) ||
+    manifest.name !== "@earendil-works/pi-coding-agent" ||
+    !isRecord(manifest.bin)
+  ) {
+    throw new Error("Launch package must be an installed Pi package.");
+  }
+  const bin = label(manifest.bin.pi, "Pi manifest bin", 4096);
+  const cli = realpathSync(join(packageRoot, bin));
+  const within = relative(packageRoot, cli);
+  if (within.startsWith("..") || isAbsolute(within) || !statSync(cli).isFile()) {
+    throw new Error("Pi bin must be a file inside the pinned package.");
+  }
+  return cli;
+}
+function extensions(value: unknown): readonly string[] {
+  if (!isUnknownArray(value) || value.length < 1 || value.length > 32) {
+    throw new Error("Launch extensions must contain 1..32 local paths.");
+  }
+  return value.map((entry) => absolute(entry, "extension path"));
+}
+
+export function launchPolicy(value: unknown): LaunchPolicy | undefined {
+  if (value === undefined) {
+    return;
+  }
+  const raw = object(value, [
+    "packageRoot",
+    "sessionDir",
+    "provider",
+    "model",
+    "context",
+    "extensions",
+    "discoverResources",
+    "trustProject",
+    "offline",
+    "maxSessions",
+    "startupTimeoutMs",
+  ]);
+  const packageRoot = absolute(raw.packageRoot, "Pi package root");
+  const sessionDir = absolute(raw.sessionDir, "session directory");
+  const storage = lstatSync(sessionDir);
+  if (
+    !storage.isDirectory() ||
+    storage.uid !== process.getuid?.() ||
+    (storage.mode & 0o777) !== 0o700
+  ) {
+    throw new Error("Launch storage must be an owned directory with mode 0700.");
+  }
+  return {
+    packageRoot,
+    cli: executable(packageRoot),
+    sessionDir,
+    provider: label(raw.provider, "provider", 128),
+    model: label(raw.model, "model", 256),
+    context: text(raw.context),
+    extensions: extensions(raw.extensions),
+    discoverResources: boolean(raw.discoverResources, false),
+    trustProject: boolean(raw.trustProject, false),
+    offline: boolean(raw.offline, false),
+    maxSessions: bounded(raw.maxSessions, 4, 16),
+    startupTimeoutMs: bounded(raw.startupTimeoutMs, 15000, 60000),
+  };
+}