@fitchmultz/pi-subagents 0.44.4 → 0.44.5

package/dist/runs/foreground/question-control.js

@@ -1,22 +1,27 @@
 import * as path from "node:path";
-import { cancelSupervisorQuestion, claimQuestionRevival, formatSupervisorQuestions, listSupervisorQuestions, questionProcessAlive, questionRecoveryHint, readQuestionState, recordQuestionDelivery, releaseQuestionRevival, saveQuestionAnswer } from "../shared/supervisor-questions.js";
+import { formatRunAction } from "../../shared/status-format.js";
+import { cancelSupervisorQuestion, claimQuestionRevival, formatSupervisorQuestions, listSupervisorQuestions, questionProcessAlive, questionRecoveryHint, readQuestionState, recordQuestionDelivery, releaseQuestionRevival, saveQuestionAnswer, supervisorQuestionPage } from "../shared/supervisor-questions.js";
 import { liveLaunchOverrideNotice, nestedResolutionScopeForExecutor, reviveSavedSubagent } from "./foreground-control.js";
-function questionResult(questions, text = formatSupervisorQuestions(questions)) {
-    return { content: [{ type: "text", text }], details: { mode: "management", results: [], questions } };
+function questionResult(questions, text) {
+    return { content: [{ type: "text", text }], details: { mode: "management", results: [], ...supervisorQuestionPage(questions) } };
 }
 export function projectSupervisorQuestions(result, params, ownerSessionId, childSafe = false) {
     if (result.isError && !result.content.some((item) => item.type === "text" && /Async run not found|Status file not found/.test(item.text)))
         return result;
-    const questions = listSupervisorQuestions(ownerSessionId, params.id ?? params.runId ?? (params.dir ? path.basename(params.dir) : undefined))
+    const id = params.id ?? params.runId ?? (params.dir ? path.basename(params.dir) : undefined);
+    const questions = listSupervisorQuestions(ownerSessionId, id)
         .filter((question) => question.state === "awaiting_input" || question.state === "answer_pending");
     if (!questions.length)
         return result;
+    const page = supervisorQuestionPage(questions);
     const questionOnly = result.isError && result.content.some((item) => item.type === "text" && /Async run not found|Status file not found/.test(item.text));
     return {
         ...result,
         ...(questionOnly ? { isError: false } : {}),
-        content: [{ type: "text", text: [`Supervisor input (not execution completion):\n${formatSupervisorQuestions(questions, childSafe)}`, ...(questionOnly ? [] : result.content.map((item) => item.type === "text" ? item.text : ""))].join("\n\n") }],
-        details: { ...result.details, questions },
+        content: [{ type: "text", text: [`Supervisor input (not execution completion):\n${formatSupervisorQuestions(page.questions, childSafe)}`,
+                    ...(page.questionList.nextOffset !== undefined ? [`More questions: ${formatRunAction("questions", id, { offset: page.questionList.nextOffset, limit: page.questionList.limit }, childSafe)}`] : []),
+                    ...(questionOnly ? [] : result.content.map((item) => item.type === "text" ? item.text : ""))].join("\n\n") }],
+        details: { ...result.details, ...page },
     };
 }
 export function cancelSupervisorInput(result, params, ownerSessionId, events) {
@@ -34,7 +39,7 @@ export function cancelSupervisorInput(result, params, ownerSessionId, events) {
     }
     const cancelled = questions.map((question) => readQuestionState(question));
     return result.isError ? questionResult(cancelled, `Cancelled ${questions.length} pending supervisor question(s). Any live waiter will abort its agent; cancellation is requested, not proof of process exit.`)
-        : { ...result, details: { ...result.details, questions: cancelled } };
+        : { ...result, details: { ...result.details, ...supervisorQuestionPage(cancelled) } };
 }
 export function controlSupervisorQuestion(input) {
     try {
@@ -45,9 +50,15 @@ export function controlSupervisorQuestion(input) {
         if (params.index !== undefined && (!Number.isSafeInteger(params.index) || params.index < 0))
             throw new Error("index must be a non-negative integer.");
         const questions = listSupervisorQuestions(input.ctx.sessionManager.getSessionId(), id)
-            .filter((question) => params.index === undefined || question.index === params.index);
-        if (params.action === "questions")
-            return questionResult(questions, formatSupervisorQuestions(questions, Boolean(nestedResolutionScopeForExecutor(input.deps))));
+            .filter((question) => (params.index === undefined || question.index === params.index) && (params.action !== "questions" || params.questionId === undefined || question.questionId === params.questionId));
+        if (params.action === "questions") {
+            const page = supervisorQuestionPage(questions, params), childSafe = Boolean(nestedResolutionScopeForExecutor(input.deps));
+            const text = [formatSupervisorQuestions(page.questions, childSafe),
+                `Questions: ${page.questions.length} shown, ${page.questionList.total} total (offset ${page.questionList.offset}).`,
+                ...(page.questionList.nextOffset !== undefined ? [`More questions: ${formatRunAction("questions", id, { offset: page.questionList.nextOffset, limit: page.questionList.limit,
+                        ...(params.index !== undefined ? { index: params.index } : {}), ...(params.questionId ? { questionId: params.questionId } : {}) }, childSafe)}`] : [])].join("\n\n");
+            return { content: [{ type: "text", text }], details: { mode: "management", results: [], ...page } };
+        }
         if (!id || !params.questionId)
             throw new Error("action='answer' requires id and questionId.");
         const question = questions.find((entry) => entry.questionId === params.questionId);
@@ -66,10 +77,10 @@ export function controlSupervisorQuestion(input) {
         const result = reviveSavedSubagent({ ...input, params: { ...params, message: `${answer.origin === "human" ? "Direct user answer (human origin)" : "Supervisor answer"} to question ${question.questionId}:\n\n${answer.message}\n\nOriginal question:\n${question.message}` } }, { ...question, source: "question" }, claim.runId);
         if (result.isError) {
             releaseQuestionRevival(question);
-            return { ...result, details: { ...result.details, questions: [readQuestionState(question)] } };
+            return { ...result, details: { ...result.details, ...supervisorQuestionPage([readQuestionState(question)]) } };
         }
         recordQuestionDelivery(question, { kind: "revive", runId: claim.runId, deliveredAt: Date.now() });
-        return { ...result, details: { ...result.details, questions: [readQuestionState(question)] } };
+        return { ...result, details: { ...result.details, ...supervisorQuestionPage([readQuestionState(question)]) } };
     }
     catch (error) {
         return { content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }], isError: true, details: { mode: "management", results: [] } };

package/dist/runs/foreground/wait-run.js

@@ -1,7 +1,8 @@
 import * as path from "node:path";
 import { writeAsyncControlRequest } from "../background/async-control.js";
 import { ownedRunExecutionResult, ownedRunProgressResult, ownedRunStatusResult, ownedRunView, resolveOwnedRun } from "../shared/run-records.js";
-import { getRunMetadataDir, listOwnedRunQuestions, questionProcessAlive, readRunJson } from "../shared/supervisor-questions.js";
+import { formatSupervisorQuestions, getRunMetadataDir, listOwnedRunQuestions, questionProcessAlive, readRunJson, supervisorQuestionPage } from "../shared/supervisor-questions.js";
+import { formatRunAction } from "../../shared/status-format.js";
 import { getSingleResultOutput, readStatus } from "../../shared/utils.js";
 import { INTERCOM_DETACH_REQUEST_EVENT, INTERCOM_DETACH_RESPONSE_EVENT, POLL_INTERVAL_MS } from "../../shared/types.js";
 import { resolveSubagentRunId } from "../background/run-id-resolver.js";
@@ -87,8 +88,9 @@ export async function waitForOwnedRun(input) {
                 const questions = runQuestions.filter((question) => question.ownerSessionId === owner && (index === undefined || question.index === index) && question.state === "awaiting_input");
                 if (questions.length) {
                     const result = ownedRunStatusResult(target, deps.state);
-                    result.details.questions = questions;
-                    finish("awaiting_input", `Run ${target.runId} needs input; waiting ended without stopping it.\n\n${questions.map((question) => `Question ${question.questionId}: ${question.message}`).join("\n\n")}`, result);
+                    const page = supervisorQuestionPage(questions), childSafe = Boolean(nestedResolutionScopeForExecutor(deps));
+                    Object.assign(result.details, page);
+                    finish("awaiting_input", `Run ${target.runId} needs input; waiting ended without stopping it.\n\n${formatSupervisorQuestions(page.questions, childSafe)}\n\nAll questions: ${formatRunAction("questions", target.runId, index === undefined ? {} : { index }, childSafe)}`, result);
                     return;
                 }
                 if ((index !== undefined || view.resultPath) && children.every((child) => child.result && child.state !== "live" && child.state !== "unknown") && (index !== undefined || view.state !== "live")) {

package/dist/runs/shared/run-history.js

@@ -64,6 +64,12 @@ export function recordRun(agent, task, exitCode, durationMs) {
         fs.mkdirSync(agentDir, { recursive: true });
         db = openHistoryDatabase(path.join(historyDirectory(agentDir), TIMING_DATABASE));
         const connection = db;
+        const imported = connection.prepare("SELECT 1 FROM sqlite_schema WHERE type='table' AND name='timing_meta'").get()
+            && connection.prepare("SELECT key FROM timing_meta WHERE key='legacy-imported'").get();
+        // Filesystem reads and JSON parsing must not consume another writer's admission budget.
+        const legacy = imported ? [] : legacySamples(agentDir).reverse();
+        // Allow brief native writer overlap; three attempts still bound best-effort admission.
+        connection.exec("PRAGMA busy_timeout=1000");
         historyTransaction(connection, () => {
             connection.exec(`CREATE TABLE IF NOT EXISTS timing_meta(key TEXT PRIMARY KEY);
 				CREATE TABLE IF NOT EXISTS samples(sequence INTEGER PRIMARY KEY,agent TEXT NOT NULL,task TEXT NOT NULL,ts INTEGER NOT NULL,status TEXT NOT NULL,duration REAL NOT NULL,exit INTEGER);
@@ -71,7 +77,8 @@ export function recordRun(agent, task, exitCode, durationMs) {
             const insert = connection.prepare("INSERT INTO samples(agent,task,ts,status,duration,exit) VALUES (?,?,?,?,?,?)");
             const save = (sample) => insert.run(sample.agent, sample.task, sample.ts, sample.status, sample.duration, sample.exit ?? null);
             if (!connection.prepare("SELECT key FROM timing_meta WHERE key='legacy-imported'").get()) {
-                for (const sample of legacySamples(agentDir).reverse())
+                // Another writer may have imported while this snapshot was being read.
+                for (const sample of legacy)
                     save(sample);
                 connection.exec("INSERT INTO timing_meta VALUES ('legacy-imported')");
             }

package/dist/runs/shared/supervisor-questions.js

@@ -9,6 +9,33 @@ import { runCooperatively, runSynchronously } from "../../shared/cooperative.js"
 import { ASYNC_DIR, TEMP_ROOT_DIR } from "../../shared/types.js";
 export const LEGACY_QUESTIONS_DIR = path.join(TEMP_ROOT_DIR, "supervisor-questions");
 export const QUESTIONS_DIR = path.join(getAgentDir(), "sessions", "subagent-runs");
+export function summarizeSupervisorQuestion(question) {
+    const directory = questionDir(question);
+    return {
+        questionId: question.questionId, runId: question.runId, ownerSessionId: question.ownerSessionId, ownerTarget: question.ownerTarget,
+        agent: question.agent, index: question.index, childSessionId: question.childSessionId, childTarget: question.childTarget,
+        sessionFile: question.sessionFile, cwd: question.cwd, pid: question.pid, processIdentity: question.processIdentity,
+        createdAt: question.createdAt, reason: question.reason, state: question.state, message: question.message.slice(0, 2048),
+        questionPath: path.join(directory, "question.json"),
+        ...(question.message.length > 2048 ? { messageTruncated: true } : {}),
+        ...(question.interview ? { hasInterview: true } : {}),
+        ...(question.answer ? { answer: { message: question.answer.message.slice(0, 2048), answeredAt: question.answer.answeredAt, origin: question.answer.origin },
+            answerPath: path.join(directory, "answer.json"), ...(question.answer.message.length > 2048 ? { answerTruncated: true } : {}) } : {}),
+        ...(question.delivery ? { delivery: { kind: question.delivery.kind, runId: question.delivery.runId, deliveredAt: question.delivery.deliveredAt } } : {}),
+        ...(question.revival ? { revival: { runId: question.revival.runId, pid: question.revival.pid, startedAt: question.revival.startedAt } } : {}),
+    };
+}
+export function supervisorQuestionPage(questions, options = {}) {
+    const offset = options.offset ?? 0, limit = options.limit ?? 20;
+    if (!Number.isSafeInteger(offset) || offset < 0)
+        throw new Error("Question offset must be a non-negative integer.");
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100)
+        throw new Error("Question limit must be from 1 to 100.");
+    const pending = (question) => question.state === "awaiting_input" || question.state === "answer_pending" ? 0 : 1;
+    const sorted = questions.toSorted((a, b) => pending(a) - pending(b) || a.createdAt - b.createdAt || a.questionId.localeCompare(b.questionId));
+    return { questions: sorted.slice(offset, offset + limit).map((question) => summarizeSupervisorQuestion(question)),
+        questionList: { total: questions.length, offset, limit, ...(offset + limit < questions.length ? { nextOffset: offset + limit } : {}) } };
+}
 function safeId(value) {
     if (typeof value !== "string" || !/^[a-zA-Z0-9_-]+$/.test(value))
         throw new Error("Invalid run or question ID.");
@@ -311,10 +338,13 @@ export function formatSupervisorQuestions(questions, childSafe = false) {
         `Run: ${question.runId} | Child: ${question.index} (${question.agent}) | Owner: ${question.ownerSessionId}`,
         `Session: ${question.sessionFile} | Child target: ${question.childTarget}`,
         question.message,
-        ...(question.answer ? [`Saved answer: ${question.answer.message}`] : []),
+        ...(question.messageTruncated ? [`[Question preview truncated. Full question: ${question.questionPath}]`] : []),
+        ...(question.hasInterview ? [`Structured interview: ${question.questionPath}`] : []),
+        ...(question.answer ? [`Saved answer: ${question.answer.message}`, ...(question.answerTruncated ? [`[Answer preview truncated. Exact saved answer: ${question.answerPath}]`] : [])] : []),
         ...(question.revival && !question.delivery ? [`Continuation requested: ${question.revival.runId}; delivery unconfirmed. Answer retained.`, questionRecoveryHint(question, childSafe)] : []),
         question.delivery ? `Answer delivered via ${question.delivery.kind}; run: ${question.delivery.runId}`
             : question.state === "cancelled" ? "Question cancelled; use continue for a new follow-up."
-                : `Answer: ${formatRunAction("answer", question.runId, { questionId: question.questionId, message: question.answer?.message ?? "..." }, childSafe)}`,
+                : question.answerTruncated ? `Retry answer with the exact saved message from ${question.answerPath}; a preview is not a valid replacement.`
+                    : `Answer: ${formatRunAction("answer", question.runId, { questionId: question.questionId, message: question.answer?.message ?? "..." }, childSafe)}`,
     ].join("\n")).join("\n\n");
 }

package/dist/shared/status-format.js

@@ -7,7 +7,7 @@ export function formatRunAction(action, id, fields = {}, childSafe = false) {
     const legacyChild = childSafe && loadConfig().compactChildTools === false;
     const parentAction = { status: "inspect", resume: "continue", interrupt: "stop" };
     const name = legacyChild ? action : parentAction[action] ?? action;
-    const args = Object.entries({ action: name, id, ...fields }).map(([key, value]) => `${key}: ${JSON.stringify(value)}`).join(", ");
+    const args = Object.entries({ action: name, ...(id !== undefined ? { id } : {}), ...fields }).map(([key, value]) => `${key}: ${JSON.stringify(value)}`).join(", ");
     const call = `${legacyChild || action === "extend" ? "subagent" : "agent_runs"}({ ${args} })`;
     return action === "extend" && !legacyChild ? `load_subagent({}), then ${call}` : call;
 }

package/docs/intercom-bridge.md

@@ -0,0 +1,212 @@
+# 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.
+
+## 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.
+
+**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.
+
+**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.
+
+**Delivery/lifecycle:** one broker peer per authorized certificate, registered lazily on the first API call, with a five-minute inactivity lease. Poll inbox to maintain presence. Send returns broker acceptance, not proof a model consumed it. Ask steers the recipient and waits at most two minutes for both the exact recipient ID and exact `replyTo`. One outgoing ask per identity. Revocation/expiry/shutdown/client disconnect terminate waits. Inbox is bounded and volatile; overflow is reported, not silently described as successful receipt. Restarting the helper loses inbox contents and pending replies. Upgrade to a durable inbox journal if restart recovery is required; existing Pi recipients still save their own messages normally.
+
+**Audit:** JSONL metadata on stdout: request/connection identity, certificate fingerprint, operation, peer/message IDs and outcome. Message/attachment bodies and keys are not logged. Protect logs (0700 directory, 0600 files); rotate them with your normal log tooling. Never publish private config/keys or raw inbox/list output as smoke evidence.
+
+## Mac setup
+
+Requires Node **24.21.0+**, OpenSSL with `req -addext` (Homebrew OpenSSL works), and a connected Pi session with Intercom. Run commands from this checkout/package directory. A runtime-only installed checkout already has `dist/`; for development use `npm ci` first. See the [installation guide](../README.md#installation) before rebuilding an in-use extension. This standalone helper can run from its own installed copy without touching the live Pi runtime.
+
+```bash
+# Use a NEW directory; init refuses to overwrite any existing CA.
+umask 077
+BRIDGE="$HOME/.pi/intercom-bridge"
+node scripts/intercom-bridge-credentials.mjs init "$BRIDGE" --cwd "$PWD"
+```
+
+The last JSON line contains paths to the issued client `cert`/`key`, trusted `ca`, and `config`; it does not print secret contents. Keep those paths for the copy step. Configuration is local-only, owned by the Mac user and private:
+
+```json
+{
+  "port": 9443,
+  "ca": "/Users/mitch/.pi/intercom-bridge/ca.crt",
+  "cert": "/Users/mitch/.pi/intercom-bridge/server.crt",
+  "key": "/Users/mitch/.pi/intercom-bridge/server.key",
+  "clients": [{
+    "fingerprint256": "SHA256_FINGERPRINT_FROM_ISSUE",
+    "name": "grok-bot",
+    "cwd": "/Users/mitch/project"
+  }]
+}
+```
+
+`cwd` controls presence/project association, **not** an authorization restriction. `list` intentionally returns all connected peer identities, omitting topics/subscriptions. Target full IDs or the returned `target` when names collide. Port `0` requests an ephemeral port, reported in the listening log; a fixed port is easier for SSH.
+
+Start the helper in a dedicated terminal (or supervise this exact command with launchd):
+
+```bash
+# Match Pi's agent directory and temp environment, especially for launchd.
+export PI_CODING_AGENT_DIR="${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}"
+export TMPDIR="$(getconf DARWIN_USER_TEMP_DIR)"
+node dist/pi-intercom/bridge.js --config "$BRIDGE/config.json" >> "$BRIDGE/audit.jsonl"
+```
+
+The listening record includes the helper PID and port. Record the PID as `HELPER_PID` in your administration terminal; **do not use the broker PID**. Wait for that readiness record before making a request: a running process is not proof its listener is ready. Verify `lsof -nP -iTCP:9443 -sTCP:LISTEN` shows only `127.0.0.1:9443`. Keep the helper running; no per-message approvals are needed.
+
+For the installed Mac LaunchAgent (`com.fitchmultz.pi-intercom-bridge`), inspect and administer it with:
+
+```bash
+launchctl print "gui/$(id -u)/com.fitchmultz.pi-intercom-bridge"
+# Reload allowlist without restarting:
+launchctl kill SIGHUP "gui/$(id -u)/com.fitchmultz.pi-intercom-bridge"
+# Stop immediately; remove the plist too to disable future login starts:
+launchctl bootout "gui/$(id -u)" "$HOME/Library/LaunchAgents/com.fitchmultz.pi-intercom-bridge.plist"
+# Start again explicitly:
+launchctl bootstrap "gui/$(id -u)" "$HOME/Library/LaunchAgents/com.fitchmultz.pi-intercom-bridge.plist"
+```
+
+The installed agent has no `KeepAlive` auto-restart; stopping its helper really stops access. Remove its plist to disable future login starts permanently. Inspect/drain inbox before a planned helper restart because it is volatile.
+
+### Tunnel and provision Grok
+
+Use the **known, approved** Linux SSH host/account, not an invented example host. Preserve SSH host-key verification and do not forward your SSH agent:
+
+```bash
+GROK_SSH='grok@YOUR_LINUX_HOST'
+# On Linux, first inspect effective SSH config with the administrator:
+# sudo sshd -T | grep gatewayports
+# Require GatewayPorts=no (default) or clientspecified, NEVER yes.
+
+# On the Mac, dedicated terminal/supervised process:
+ssh -NT -a -o BatchMode=yes -o StrictHostKeyChecking=yes \
+  -o ExitOnForwardFailure=yes -o ServerAliveInterval=30 -o ServerAliveCountMax=3 \
+  -R 127.0.0.1:9443:127.0.0.1:9443 "$GROK_SSH"
+```
+
+**On Linux, verify `ss -ltn '( sport = :9443 )'` shows only `127.0.0.1:9443` before use.** `GatewayPorts=yes` forces wildcard binding even when `-R` requests loopback. If it shows `0.0.0.0`, `*`, or `[::]`, stop the tunnel and correct that SSH policy. Do not open a firewall port. OpenSSH references: [ssh `-R`](https://man.openbsd.org/ssh.1) and [sshd `GatewayPorts`](https://man.openbsd.org/sshd_config.5#GatewayPorts).
+
+Transfer **only** the client certificate/key, public `ca.crt`, and the dependency-free remote script through the existing approved SSH/SFTP channel:
+
+```bash
+# Use cert/key paths printed by init/issue, not the CA or server keys.
+CLIENT_CERT='/absolute/path/from/issue/grok-bot-ISSUED.crt'
+CLIENT_KEY='/absolute/path/from/issue/grok-bot-ISSUED.key'
+ssh "$GROK_SSH" 'umask 077; mkdir -p ~/.config/pi-intercom; chmod 700 ~/.config/pi-intercom'
+scp "$CLIENT_CERT" "$GROK_SSH:.config/pi-intercom/client.crt"
+scp "$CLIENT_KEY" "$GROK_SSH:.config/pi-intercom/client.key"
+scp "$BRIDGE/ca.crt" scripts/intercom-remote.mjs "$GROK_SSH:.config/pi-intercom/"
+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.
+
+## Grok Bot: exact remote commands
+
+On Linux, configure Grok's shell environment:
+
+```bash
+export INTERCOM_BRIDGE_URL='https://127.0.0.1:9443'
+export INTERCOM_BRIDGE_CA="$HOME/.config/pi-intercom/ca.crt"
+export INTERCOM_BRIDGE_CERT="$HOME/.config/pi-intercom/client.crt"
+export INTERCOM_BRIDGE_KEY="$HOME/.config/pi-intercom/client.key"
+REMOTE="$HOME/.config/pi-intercom/intercom-remote.mjs"
+
+node "$REMOTE" register
+node "$REMOTE" list
+node "$REMOTE" send --to planner --message 'Grok checking in. Please send your current status.'
+node "$REMOTE" ask --to planner --message 'What is the current status?' --timeout-ms 120000
+node "$REMOTE" inbox
+node "$REMOTE" reply --reply-to QUESTION_ID_FROM_INBOX --message 'Proceed with the stable API.'
+node "$REMOTE" ack ORDINARY_MESSAGE_ID_FROM_INBOX
+```
+
+Poll inbox at a reasonable cadence (for example every 5–15 seconds) while Grok is available. Fetch is non-destructive, so retrying a fetch cannot lose messages; persist/consume then ack ordinary messages. Inbound asks remain in the inbox until `reply` succeeds; ack does not discard a reply obligation. Use `send` for most coordination and `ask` only when Grok really needs a blocking answer. The CLI has a hard request deadline (ask timeout + 15 seconds), validates TLS, emits JSON, and exits 1 on errors / 2 on invalid arguments. It never retries mutations automatically.
+
+Curl works too, with bounded waiting and the same TLS files:
+
+```bash
+curl --fail-with-body --max-time 135 \
+  --cacert "$INTERCOM_BRIDGE_CA" --cert "$INTERCOM_BRIDGE_CERT" --key "$INTERCOM_BRIDGE_KEY" \
+  -H 'Content-Type: application/json' \
+  -d '{"to":"planner","message":"Please reply with your status.","timeoutMs":120000}' \
+  "$INTERCOM_BRIDGE_URL/v1/ask"
+```
+
+### JSON API contract
+
+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` |
+
+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.
+
+## Rotate credentials
+
+Client renewal replaces its old fingerprint rather than authorizing both indefinitely. Credential commands hold a private directory lock across the complete config read/modify/write and certificate issuance, so concurrent operations fail instead of restoring a revoked fingerprint. After a crashed command, inspect `DIR/.credentials.lock/owner`, confirm that process is gone, then remove that lock and retry; never clear a live command's lock.
+
+Renew with:
+
+```bash
+node scripts/intercom-bridge-credentials.mjs issue "$BRIDGE" grok-bot
+# Transfer the NEW cert/key using the same private copy commands above.
+kill -HUP "$HELPER_PID"
+```
+
+SIGHUP rereads the private config, drops removed/changed peers and their TLS connections, and cancels pending waits. Confirm the reload audit record and verify the old certificate is denied. Invalid reload fails closed. Client expiry also applies to existing connections/peer leases, not just new TLS handshakes. Restart Grok's client process if it caches its files.
+
+Server certificate expires after one year; CA after ten. To rotate server/CA, create a **new** credential directory with `init`, transfer its new public CA and new client credential, stop/restart **only this helper** with the new config, and retain the old directory briefly as a private rollback. Never restart the shared broker or change its socket permissions for rotation. If the CA key is compromised, replace the entire CA immediately. Old private key files retained by `issue` should be removed only when no rollback is needed.
+
+## How to revoke Grok
+
+```bash
+node scripts/intercom-bridge-credentials.mjs revoke "$BRIDGE" grok-bot
+kill -HUP "$HELPER_PID"
+```
+
+Confirm the reload/revocation audit record, that Grok disappears from the local peer list, and that its old cert cannot call `/v1/list`. Stop the SSH forward too if no other client needs it. Remove Grok's saved client key on Linux and obsolete local client keys when no longer needed. Emergency immediate cut-off: stop **the helper process**, not Pi or the broker. Certificate renewal cannot bypass the removed fingerprint; reauthorization requires a new local `issue` + reload.
+
+## 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:
+
+```bash
+node --test test/integration/intercom-bridge.test.ts
+# Do not inject host startup diagnostics into native fixture stderr:
+env -u PI_TIMING -u PI_EXTENSION_PERFORMANCE npm run ci
+```
+
+For a live smoke, from a separate Mac process and then Linux use the remote CLI to list peers and ask an intentionally selected connected session:
+
+```bash
+node "$REMOTE" list
+node "$REMOTE" ask --to KNOWN_FULL_SESSION_ID --message 'Bridge smoke only: reply with bridge-smoke-ok.' --timeout-ms 120000
+```
+
+Save only a redacted transcript: platform, operation, returned peer names relevant to the test, accepted/delivered, and reply text. Do not publish unrelated cwd/model/topic/message content.
+
+Observed **2026-10-06**, from a separate process on the Mac through the installed runtime-only helper to the live broker and a real connected Pi session (not a mocked recipient):
+
+```json
+{
+  "platform": "darwin",
+  "transport": "loopback HTTPS mTLS",
+  "list": {"ok": true, "peers": ["secure-intercom-bridge", "grok-bot"]},
+  "ask": {
+    "ok": true, "accepted": true, "delivered": true, "replied": true,
+    "reply": "bridge-smoke-ok"
+  }
+}
+```
+
+**Off-box deployment/smoke is not yet verified:** the actual Grok Linux SSH destination/access was unavailable. No credentials were transferred to an unverified host. Once that access is supplied, verify Linux's listener and repeat these exact list/ask commands there.

package/docs/intercom.md

@@ -305,6 +305,8 @@ agent_runs({ action: "stop", id: "<run-id>" })
 
 The full `subagent` tool also accepts `questions` and `answer`; its stop action is `interrupt`. Questions expose `awaiting_input`, `answer_pending`, `answered`, or `cancelled` independently of run completion. Ownership follows the saved supervisor session, not its cwd or display name. The live intercom reply path saves the same answer. Saving an answer or cancelling through run controls also clears the matching live intercom pending ask; a nudge does not resolve a question.
 
+Question lists page 20 summaries by default, unresolved first. Use `limit: 1–100`, then pass `details.questionList.nextOffset` as `offset`; `id`, `index` and `questionId` narrow the lookup. Summaries retain identity, state, delivery and revival evidence without copying the saved launch or attempt baseline. Previews stop at 2,048 characters. Read `questionPath` for the complete question/interview/contract and `answerPath` for the exact saved answer; never retry an answer using a truncated preview. Browsing does not modify these durable files.
+
 Needs-attention notices for a matching unresolved question say **Waiting for supervisor input** and include the question ID and answer call. `answer_pending` still means delivery is unconfirmed, not that the child resumed. A live waiter consumes the durable answer. If it exited, answering revives its saved Pi session with the original acceptance contract and a new run ID. Identical repeated answers do not launch duplicate work; conflicting answers leave the original intact. `stop` cancels the question and aborts any live waiter. An interrupted pre-launch revival can be recovered with the exact `continue` call shown in the answer receipt; ambiguous launch evidence is not silently retried.
 
 Questions, saved launch contracts, and canonical version-2 run status/results live under `${PI_CODING_AGENT_DIR:-~/.pi/agent}/sessions/subagent-runs`, separate from disposable temporary files. Pending records are not age-cleaned. Active legacy owners keep their original runtime and files until they finish; recovery preserves available evidence for the same saved owner without replaying work or deleting history. Ordinary peer asks still use `askTimeoutMs` and are not durable supervisor questions.
@@ -572,7 +574,7 @@ Assistant-error replies wait for broker acknowledgement during `message_end`, bo
 
 Historical official Pi 0.87.1 checks exposed queue visibility and prompt-preparation races. Current tests preserve exact-once receipts and input rejection/recovery on the selected host, including the genuine Pi 1.0 pre-admission window described above; they do not promise one combined provider turn. Historical results are not a current 1.0 pass. Use an explicit `async: false` wait when dependent work needs a finalized result. Native pending-call, idle-checkpoint and immediate-usage APIs are no longer supported. See [result delivery](../README.md#host-capabilities-and-result-delivery) and [local qualification](../README.md#local-validation).
 
-- **Same machine only** — Uses local Unix sockets, no network support
+- **Same machine only** — The core broker uses local Unix sockets, no network support. The optional [secure remote bridge](intercom-bridge.md) authenticates remote messaging through a separate loopback mTLS proxy; it does not expose the broker socket.
 - **No dedicated intercom log** — Messages are kept in Pi session history, but there is no separate intercom transcript or inbox
 - **No attachments UI** — `file`, `snippet`, and `context` attachments are supported in the protocol, but not in the compose overlay
 - **Only connected sessions appear** — The list shows Pi sessions that have loaded `pi-intercom` and successfully registered with the broker, not every open Pi process on the machine

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitchmultz/pi-subagents",
-  "version": "0.44.4",
+  "version": "0.44.5",
   "description": "Pi extension for subagent orchestration and local session coordination",
   "license": "MIT",
   "type": "module",
@@ -33,6 +33,7 @@
     "skills/**/*",
     "prompts/**/*",
     "docs/intercom.md",
+    "docs/intercom-bridge.md",
     "docs/performance.md",
     "README.md",
     "CHANGELOG.md"

package/scripts/intercom-bridge-credentials.mjs

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+import { execFileSync } from "node:child_process";
+import { randomBytes, X509Certificate } from "node:crypto";
+import { lstatSync, mkdirSync, readFileSync, renameSync, rmSync, rmdirSync, writeFileSync } from "node:fs";
+import { resolve, join } from "node:path";
+import { parseArgs } from "node:util";
+
+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.
+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)
+         -h, --help  Show help
+Environment: OPENSSL  OpenSSL executable (default: openssl; requires -addext support)
+
+Examples:
+  node scripts/intercom-bridge-credentials.mjs init ~/.pi/intercom-bridge --cwd "$PWD"
+  node scripts/intercom-bridge-credentials.mjs issue ~/.pi/intercom-bridge grok-bot
+  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.
+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.
+Exit: 0 success, 1 filesystem/OpenSSL failure, 2 invalid arguments.
+Never transfer ca.key or server.key to the remote host.`);
+}
+
+function privatePath(path, directory = false) {
+  const st = lstatSync(path);
+  if (st.isSymbolicLink() || !(directory ? st.isDirectory() : st.isFile()) ||
+      st.uid !== process.getuid() || (st.mode & 0o077)) {
+    throw new Error(`Expected an owned, private ${directory ? "directory" : "file"}: ${path}`);
+  }
+}
+
+function atomicConfig(path, config) {
+  const temp = `${path}.${randomBytes(8).toString("hex")}.tmp`;
+  try {
+    writeFileSync(temp, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+    renameSync(temp, path);
+  } finally {
+    rmSync(temp, { force: true });
+  }
+}
+
+function openssl(...args) {
+  execFileSync(process.env.OPENSSL || "openssl", args, { stdio: ["ignore", "pipe", "pipe"], timeout: 30000 });
+}
+
+function key(path) {
+  openssl("ecparam", "-name", "prime256v1", "-genkey", "-noout", "-out", path);
+  privatePath(path);
+}
+
+function issueCertificate(dir, stem, name, server = false) {
+  const keyPath = join(dir, `${stem}.key`);
+  const certPath = join(dir, `${stem}.crt`);
+  const csrPath = join(dir, `${stem}.csr`);
+  const extPath = join(dir, `${stem}.ext`);
+  key(keyPath);
+  try {
+    openssl("req", "-new", "-key", keyPath, "-subj", `/CN=${name}`, "-out", csrPath);
+    writeFileSync(extPath, `basicConstraints=critical,CA:FALSE\nkeyUsage=critical,digitalSignature\nextendedKeyUsage=${server ? "serverAuth" : "clientAuth"}\n${server ? "subjectAltName=DNS:localhost,IP:127.0.0.1\n" : ""}`, { mode: 0o600, flag: "wx" });
+    openssl("x509", "-req", "-in", csrPath, "-CA", join(dir, "ca.crt"), "-CAkey", join(dir, "ca.key"),
+      "-set_serial", `0x${randomBytes(16).toString("hex")}`, "-days", server ? "365" : "7", "-sha256", "-extfile", extPath, "-out", certPath);
+  } finally {
+    rmSync(csrPath, { force: true });
+    rmSync(extPath, { force: true });
+  }
+  const cert = new X509Certificate(readFileSync(certPath));
+  return { cert: certPath, key: keyPath, fingerprint256: cert.fingerprint256, expires: cert.validTo };
+}
+
+let args;
+try {
+  args = parseArgs({ allowPositionals: true, options: { help: { type: "boolean", short: "h" }, cwd: { type: "string" } } });
+  if (args.values.help) { help(); process.exit(0); }
+  const [action, dir, name] = args.positionals;
+  if (!["init", "issue", "revoke"].includes(action) || !dir || args.positionals.length > 3 ||
+      (action !== "init" && !name) || (name && !/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(name)) ||
+      (action === "revoke" && args.values.cwd)) throw new Error("Invalid arguments; use --help.");
+} catch (error) {
+  console.error(error.message);
+  process.exit(2);
+}
+
+let lock;
+try {
+  process.umask(0o077);
+  const [action, rawDir, suppliedName] = args.positionals;
+  const dir = resolve(rawDir);
+  const name = suppliedName || "grok-bot";
+  const configPath = join(dir, "config.json");
+  let config;
+  if (action === "init") mkdirSync(dir, { mode: 0o700 }); // Never overwrite a CA.
+  privatePath(dir, true);
+  const lockPath = join(dir, ".credentials.lock");
+  try { mkdirSync(lockPath, { mode: 0o700 }); }
+  catch (error) {
+    if (error.code === "EEXIST") throw new Error(`Another credential command holds ${lockPath}; inspect its owner before retrying.`);
+    throw error;
+  }
+  lock = lockPath;
+  writeFileSync(join(lock, "owner"), `${process.pid}\n`, { mode: 0o600, flag: "wx" });
+  if (action === "init") {
+    key(join(dir, "ca.key"));
+    openssl("req", "-new", "-x509", "-key", join(dir, "ca.key"), "-days", "3650", "-sha256", "-subj", "/CN=Pi Intercom Bridge CA",
+      "-addext", "basicConstraints=critical,CA:TRUE,pathlen:0", "-addext", "keyUsage=critical,keyCertSign,cRLSign", "-out", join(dir, "ca.crt"));
+    const server = issueCertificate(dir, "server", "localhost", true);
+    config = { port: 9443, ca: join(dir, "ca.crt"), cert: server.cert, key: server.key, clients: [] };
+  } else {
+    privatePath(dir, true);
+    privatePath(configPath);
+    config = JSON.parse(readFileSync(configPath, "utf8"));
+    if (!Array.isArray(config.clients)) throw new Error("Invalid clients allowlist.");
+  }
+  if (action === "revoke") {
+    if (!config.clients.some((client) => client.name === name)) throw new Error(`No authorized client named ${name}.`);
+    config.clients = config.clients.filter((client) => client.name !== name);
+    atomicConfig(configPath, config);
+    console.log(JSON.stringify({ revoked: name, config: configPath, next: "Send SIGHUP to the helper PID." }));
+  } else {
+    privatePath(join(dir, "ca.key"));
+    const credential = issueCertificate(dir, `${name}-${randomBytes(8).toString("hex")}`, name);
+    const previous = config.clients.find((client) => client.name === name);
+    config.clients = config.clients.filter((client) => client.name !== name);
+    config.clients.push({ fingerprint256: credential.fingerprint256, name, cwd: resolve(args.values.cwd || previous?.cwd || process.cwd()) });
+    atomicConfig(configPath, config);
+    console.log(JSON.stringify({ name, ...credential, ca: config.ca, config: configPath, next: "Transfer only client cert/key and ca.crt; reload helper allowlist with SIGHUP." }));
+  }
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 1;
+} finally {
+  if (lock) {
+    rmSync(join(lock, "owner"), { force: true });
+    rmdirSync(lock);
+  }
+}