@fitchmultz/pi-subagents 0.44.7 → 0.46.0

package/dist/tui/workflow-labels.js

@@ -0,0 +1,223 @@
+import { nonemptyText } from "./text-values.js";
+import { isDoneResult, parallelStatuses, groupStatus, outcomeLabel, spanCompleted, } from "./workflow-outcomes.js";
+export { isDoneResult } from "./workflow-outcomes.js";
+function parallelLabelCount(label) {
+    if (!label.startsWith("[") || !label.endsWith("]")) {
+        return;
+    }
+    const inner = label.slice(1, -1).trim();
+    return inner.length === 0
+        ? 0
+        : inner
+            .split("+")
+            .map((part) => part.trim())
+            .filter(Boolean).length;
+}
+function graphSpan(node, cursor, stepIndex) {
+    const parallel = node.kind === "parallel-group" || node.kind === "dynamic-parallel-group";
+    if (!parallel) {
+        return {
+            stepIndex,
+            start: node.flatIndex ?? cursor,
+            count: 1,
+            isParallel: false,
+            status: node.status,
+            label: node.label,
+            error: node.error,
+        };
+    }
+    const indexes = (node.children ?? []).flatMap((child) => child.flatIndex === undefined ? [] : [child.flatIndex]);
+    return {
+        stepIndex,
+        start: indexes.length > 0 ? Math.min(...indexes) : cursor,
+        count: node.children?.length ?? 0,
+        isParallel: true,
+        status: node.status,
+        label: node.label,
+        error: node.error,
+    };
+}
+function graphSpans(nodes) {
+    const spans = [];
+    let cursor = 0;
+    for (const node of nodes) {
+        if (node.stepIndex === undefined) {
+            continue;
+        }
+        const span = graphSpan(node, cursor, node.stepIndex);
+        spans.push(span);
+        cursor = Math.max(cursor, span.start + span.count);
+    }
+    return spans.sort((left, right) => left.stepIndex - right.stepIndex);
+}
+export function buildChainStepSpans(details) {
+    const graph = graphSpans(details.workflowGraph?.nodes ?? []);
+    if (graph.length > 0) {
+        return graph;
+    }
+    let start = 0;
+    return (details.chainAgents ?? []).map((label, stepIndex) => {
+        const parallel = parallelLabelCount(label), count = parallel ?? 1;
+        const span = { stepIndex, start, count, isParallel: parallel !== undefined };
+        start += count;
+        return span;
+    });
+}
+function activeChainGroup(details) {
+    if (details.mode !== "chain" || details.currentStepIndex === undefined) {
+        return false;
+    }
+    return buildChainStepSpans(details).some((span) => span.stepIndex === details.currentStepIndex && span.isParallel);
+}
+export function buildAsyncChainStepSpans(total, stepCount, parallelGroups = []) {
+    const spans = [];
+    let flat = 0;
+    for (let stepIndex = 0; stepIndex < total; stepIndex++) {
+        const group = parallelGroups.find((candidate) => candidate.stepIndex === stepIndex);
+        if (group) {
+            spans.push({ stepIndex, start: group.start, count: group.count, isParallel: true });
+            flat = Math.max(flat, group.start + group.count);
+            continue;
+        }
+        spans.push({ stepIndex, start: flat, count: flat < stepCount ? 1 : 0, isParallel: false });
+        flat++;
+    }
+    return spans;
+}
+export function workflowGraphHasStatus(details, statuses) {
+    return details.workflowGraph?.nodes.some((node) => statuses.includes(node.status)) ?? false;
+}
+function hasChainRows(details, label) {
+    return (details.mode === "chain" &&
+        (label.hasParallelInChain || (details.workflowGraph?.nodes.length ?? 0) > 0) &&
+        !label.showActiveGroupOnly);
+}
+function placeholder(span, details) {
+    const single = span.isParallel ? undefined : details.chainAgents?.[span.stepIndex];
+    const agentName = single ?? span.label ?? details.chainAgents?.[span.stepIndex] ?? `step-${span.stepIndex + 1}`;
+    return {
+        kind: "placeholder",
+        rowNumber: span.stepIndex + 1,
+        stepLabel: `Step ${span.stepIndex + 1}`,
+        agentName,
+        status: span.status ?? "pending",
+        error: span.error,
+    };
+}
+export function buildChainRenderEntries(details, label) {
+    if (!hasChainRows(details, label)) {
+        return;
+    }
+    const entries = [];
+    for (const span of buildChainStepSpans(details)) {
+        const missing = span.isParallel
+            ? span.count === 0
+            : details.results.at(span.start) === undefined;
+        if (missing) {
+            entries.push(placeholder(span, details));
+            continue;
+        }
+        for (let index = span.start; index < span.start + span.count; index++) {
+            const agentName = details.results.at(index)?.agent ??
+                details.chainAgents?.[span.stepIndex] ??
+                `step-${span.stepIndex + 1}`;
+            entries.push({ kind: "result", resultIndex: index, rowNumber: index + 1, agentName });
+        }
+    }
+    return entries;
+}
+function labelBase(details, spans) {
+    const active = activeChainGroup(details);
+    return {
+        itemTitle: details.mode === "parallel" || active ? "Agent" : "Step",
+        hasParallelInChain: details.mode === "chain" && spans.some((span) => span.isParallel),
+        activeParallelGroup: active,
+        groupStartIndex: 0,
+        groupEndIndex: details.results.length,
+        showActiveGroupOnly: false,
+    };
+}
+function activeGroupLabel(details, spans, base, running) {
+    const current = details.currentStepIndex ?? 0, span = spans.at(current), count = span?.count ?? 1, start = span?.start ?? 0;
+    const total = details.totalSteps ?? details.chainAgents?.length ?? 1;
+    const statuses = Array.from({ length: count }, (_, offset) => groupStatus(details, start + offset));
+    return {
+        ...base,
+        totalCount: count,
+        groupStartIndex: start,
+        groupEndIndex: start + count,
+        showActiveGroupOnly: true,
+        headerLabel: `step ${current + 1}/${total} · parallel group: ${outcomeLabel(statuses, count, running)}`,
+    };
+}
+function chainLabel(details, spans, base, running) {
+    const total = details.totalSteps ?? details.chainAgents?.length ?? details.results.length;
+    const logical = details.mode === "chain" && (details.chainAgents?.length ?? 0) > 0;
+    const done = logical
+        ? spans.filter((span) => spanCompleted(details, span)).length
+        : details.results.filter(isDoneResult).length;
+    const current = details.currentStepIndex === undefined
+        ? Math.min(total, done + Number(running))
+        : details.currentStepIndex + 1;
+    return { ...base, totalCount: total, headerLabel: `step ${running ? current : done}/${total}` };
+}
+export function buildMultiProgressLabel(details, running) {
+    const spans = buildChainStepSpans(details), base = labelBase(details, spans);
+    if (details.mode === "parallel") {
+        const total = details.totalSteps ?? details.results.length;
+        return {
+            ...base,
+            totalCount: total,
+            groupEndIndex: total,
+            headerLabel: outcomeLabel(parallelStatuses(details, total), total, running, true),
+        };
+    }
+    return base.activeParallelGroup
+        ? activeGroupLabel(details, spans, base, running)
+        : chainLabel(details, spans, base, running);
+}
+function fallbackName(details, index, direct, fallback) {
+    const agent = details.results.at(index)?.agent;
+    if (direct) {
+        return nonemptyText(agent) ?? fallback;
+    }
+    return nonemptyText(details.chainAgents?.at(index)) ?? nonemptyText(agent) ?? fallback;
+}
+export function renderEntries(details, label, fallback = "step") {
+    const chain = buildChainRenderEntries(details, label);
+    if (chain) {
+        return chain;
+    }
+    const chainCount = details.chainAgents?.length ?? 0;
+    const direct = label.hasParallelInChain || chainCount === 0;
+    const start = label.showActiveGroupOnly ? label.groupStartIndex : 0;
+    let end = direct ? details.results.length : chainCount;
+    if (label.showActiveGroupOnly) {
+        end = label.groupEndIndex;
+    }
+    return Array.from({ length: end - start }, (_, offset) => {
+        const index = start + offset, row = label.showActiveGroupOnly ? index - label.groupStartIndex + 1 : index + 1;
+        return {
+            kind: "result",
+            resultIndex: index,
+            rowNumber: row,
+            agentName: fallbackName(details, index, direct, `${fallback}-${row}`),
+        };
+    });
+}
+export function resultRowLabel(details, label, index, step) {
+    if (details.mode === "chain" && label.hasParallelInChain) {
+        const span = buildChainStepSpans(details).find((candidate) => index >= candidate.start && index < candidate.start + candidate.count);
+        if (span?.isParallel === true) {
+            return `Agent ${index - span.start + 1}/${span.count}`;
+        }
+        if (span) {
+            return `Step ${span.stepIndex + 1}`;
+        }
+    }
+    if (label.itemTitle !== "Agent") {
+        return `Step ${step}`;
+    }
+    const local = label.activeParallelGroup ? Math.max(1, step - label.groupStartIndex) : step;
+    return `Agent ${local}/${label.totalCount}`;
+}

package/dist/tui/workflow-outcomes.js

@@ -0,0 +1,124 @@
+import { formatAgentRunningLabel } from "../shared/status-format.js";
+function pausedResult(result) {
+    return result?.interrupted === true || result?.detached === true;
+}
+function blockedResult(result) {
+    return result?.acceptance?.status === "blocked";
+}
+export function isDoneResult(result) {
+    if (pausedResult(result) || result.timedOut === true || blockedResult(result)) {
+        return false;
+    }
+    const status = result.progress?.status;
+    if (status === "completed") {
+        return true;
+    }
+    return status !== "running" && status !== "pending" && result.exitCode === 0;
+}
+function resultStatus(result) {
+    if (result.progress) {
+        return result.progress.status;
+    }
+    if (result.timedOut === true) {
+        return "timed-out";
+    }
+    if (pausedResult(result)) {
+        return "detached";
+    }
+    if (result.exitCode !== 0) {
+        return "failed";
+    }
+    return blockedResult(result) ? "blocked" : "completed";
+}
+function resultIndex(details, result, position) {
+    const progress = details.progress?.find((entry) => entry.index === position) ??
+        details.progress?.find((entry) => entry.agent === result.agent && entry.status === "running");
+    return result.progress?.index ?? progress?.index ?? position;
+}
+export function parallelStatuses(details, total) {
+    const statuses = Array.from({ length: total }, () => "pending");
+    for (const progress of details.progress ?? []) {
+        if (progress.index >= 0 && progress.index < total) {
+            statuses[progress.index] = progress.status;
+        }
+    }
+    for (const [position, result] of details.results.entries()) {
+        const index = resultIndex(details, result, position);
+        if (index >= 0 && index < total) {
+            statuses[index] = resultStatus(result);
+        }
+    }
+    return statuses;
+}
+function stoppedGroupStatus(status, result) {
+    if (status === "failed" || status === "timed-out" || result?.timedOut === true) {
+        return "failed";
+    }
+    if (status === "paused" || status === "detached" || pausedResult(result)) {
+        return "paused";
+    }
+    return;
+}
+function completedGroupStatus(status, result) {
+    if (result !== undefined && result.exitCode !== 0) {
+        return "failed";
+    }
+    if (status === "blocked" || blockedResult(result)) {
+        return "blocked";
+    }
+    return status === "completed" || (result !== undefined && isDoneResult(result))
+        ? "completed"
+        : "pending";
+}
+export function groupStatus(details, index) {
+    const progress = details.progress?.find((entry) => entry.index === index);
+    const result = details.results.find((entry, position) => (entry.progress?.index ?? position) === index);
+    const status = progress?.status ?? result?.progress?.status;
+    if (status === "running") {
+        return "running";
+    }
+    return stoppedGroupStatus(status, result) ?? completedGroupStatus(status, result);
+}
+export function outcomeLabel(statuses, total, running, blockedFirst = false) {
+    const count = (states) => statuses.filter((status) => states.includes(status)).length;
+    const parts = [`${count(["completed"])}/${total} succeeded`];
+    const blocked = count(["blocked"]), failed = count(["failed", "timed-out"]), paused = count(["paused", "detached"]);
+    if (blockedFirst && blocked > 0) {
+        parts.push(`${blocked} need human action`);
+    }
+    if (running) {
+        parts.unshift(formatAgentRunningLabel(count(["running"])));
+    }
+    if (failed > 0) {
+        parts.push(`${failed} failed`);
+    }
+    if (paused > 0) {
+        parts.push(`${paused} paused`);
+    }
+    if (!blockedFirst && blocked > 0) {
+        parts.push(`${blocked} need human action`);
+    }
+    return parts.join(" · ");
+}
+function completedAt(details, index) {
+    const progress = details.progress?.find((entry) => entry.index === index);
+    const result = details.results.find((entry) => entry.progress?.index === index) ?? details.results.at(index);
+    if (["running", "pending", "failed"].includes(progress?.status ?? "")) {
+        return false;
+    }
+    return result !== undefined && isDoneResult(result);
+}
+export function spanCompleted(details, span) {
+    if (span.status !== undefined && span.status !== "completed") {
+        return false;
+    }
+    if (span.count === 0) {
+        return span.status === "completed";
+    }
+    for (let index = span.start; index < span.start + span.count; index++) {
+        if (!completedAt(details, index)) {
+            return false;
+        }
+    }
+    return true;
+}

package/docs/code-quality.md

@@ -0,0 +1,38 @@
+# Code quality
+
+Oxlint checks maintained TypeScript and JavaScript. Oxfmt owns formatting.
+Both tools use the committed npm versions and repository configuration.
+
+```sh
+npm ci --ignore-scripts
+npm run lint
+npm run lint:fix
+npm run format
+npm run format:check
+npm run typecheck
+npm run ci
+```
+
+Lint rejects unsafe types, unchecked assertions, floating promises, accidental
+mutation, import cycles and ambiguous control flow. Application readonly types
+remain checked by TypeScript. `typescript/prefer-readonly-parameter-types` is
+disabled: the published backend cannot express the existing native SDK aliases
+with package-scoped allowances. The project does not patch the checker or add
+production wrappers to satisfy that rule.
+
+Production limits are complexity 10, depth 3, parameters 4, statements 40,
+function lines 80 and file lines 500, excluding blank lines and comments.
+Tests retain complexity 15, depth 4 and parameters 6. Cohesive test suites have
+no size or statement limits.
+
+Formatting uses width 100, two spaces, LF and double quotes. npm owns lockfile
+formatting. Generated runtime schemas and build outputs keep their own bytes.
+The VS Code Oxc extension uses these same lint and formatting configurations.
+
+`npm run ci` runs lint, formatting, TypeScript, package/install smokes and all
+tests. CI separately qualifies the latest official Pi on GitHub-hosted Linux and
+the maintained fork on Linux and macOS. There is no custom checker build, probe
+suite or self-hosted runner requirement.
+
+CI's lint job also checks schema/validator drift against the committed dev dependencies,
+before qualification substitutes the selected host graph.

package/docs/development.md

@@ -0,0 +1,99 @@
+# Development and validation
+
+[Getting started](../README.md) · [Subagents reference](reference.md)
+
+## Local validation
+
+See [Code quality](code-quality.md) for the strict Oxlint/Oxfmt rules and commands. `npm run ci` runs lint and formatting before TypeScript, package checks and tests.
+
+`npm run check:compat` uses the selected host installed in this checkout, never a hidden Pi from PATH. It runs full CI with actual native editor receipts: a supplied clean `PI_EDITOR_RECEIPT_TEST_ROOT` stays read-only, otherwise the owning runner snapshots public `pi-apply-edits` main once in a temporary checkout, records its exact Git SHA, installs only its third-party runtime dependencies, and cleans its owned copy. Repository CI resolves that editor SHA once for all host/platform lanes. It checks host SDK/manifest-bin identity, typechecks, builds, and qualifies both compiled entries with a private Intercom broker through the native SDK and bundled RPC CLI. Official hosts exercise same/different-cwd resume, acceptance, structured output, native result routing/ownership and tool activation. No provider credentials or inference services are used.
+
+Repository CI resolves latest stable official Pi and maintained fork main once, then freezes that version/SHA across the Linux/macOS lanes and release qualification. Full `npm run ci`, selected-host native contracts, Git production builds and packed-install smokes remain required.
+
+Fork jobs supply `PI_COMPAT_HOST=fork`, `PI_COMPAT_EXPECTED_VERSION`, `PI_COMPAT_EXPECTED_PACKAGE_DIR`, `PI_HOST_INDEX`, and `PI_HOST_CLI` to verify the selected SDK and CLI. The official job uses the resolved latest stable cohort with `PI_COMPAT_HOST=official`. Both targets use ordinary 1.0 lifecycle and finalized tool-result accounting, without checkpoint, immediate-usage or pending-call APIs. Unsupported hosts fail qualification rather than skip native checks. See [host capabilities](reference.md#host-capabilities-and-result-delivery) and [limitations](intercom.md#limitations).
+
+For a fresh development worktree, run `npm ci` before launching Pi there: project-local `.pi/extensions` can autoload before dependencies exist. Alternatively launch from a neutral directory and use `change_dir` to enter the owned worktree after startup. Do not disable all extensions or remove project extensions to hide missing dependencies.
+
+Use an empty HOME outside your real home ancestry and a short temporary directory whose ancestors have no project/package or agent markers. Set HOME, TMPDIR, TMP, TEMP, cache and fixture cwd consistently; never create mutable fixtures beneath the real home or retained evidence directory. Child tests use local fixtures and their own broker/profile. CI runs the latest Node 24 release on Linux and macOS without claiming a full platform-by-host matrix.
+
+The completion guard recognizes verified `modifiedFiles` receipts from pi-apply-edits v1's `apply_patch`, `replace_text`, and `write_files`, including partial publication errors. Previews and unchanged results do not count as mutations. To exercise the real editor through native SDK events, use an installed v1 editor checkout:
+
+```bash
+PI_EDITOR_RECEIPT_TEST_ROOT=/absolute/path/to/pi-apply-edits \
+  node --test test/integration/native-editor-receipts.test.ts
+```
+
+`PI_EDITOR_RECEIPT_TEST_SDK` selects another installed host package root; `PI_EDITOR_RECEIPT_EVIDENCE_DIR` retains receipts and fixture files. Without an editor checkout, this optional integration test skips.
+
+### SDK embeddings of runtime-only installations
+
+Before loading a pruned package with `DefaultResourceLoader`, set `process.env.PI_PACKAGE_DIR = getPackageDir()` from the **selected SDK**. This is the existing host-location contract for native session APIs and detached runners. Alternatively the host must be discoverable through the extension's dependency graph or an actual Pi executable on PATH. CLI consumers resolve their own host normally.
+
+Detached history workers need one of those host-location sources to resolve the selected host's terminal-stripping implementation. The parent uses Pi's normal extension-loader imports without loading another runtime. Qualification covers both the explicit-host SDK path and the real bundled CLI with a production-only package.
+
+To diagnose the full suite against the locked published Pi dependencies:
+
+```bash
+npm ci
+npm run ci
+```
+
+The [host limitations](intercom.md#limitations) include historical official 0.87.1 results. Retain distinct queue and prompt-preparation checks and report their actual results for the selected host; portable qualification does not establish a full-suite pass.
+
+That command runs TypeScript no-emit checking, package shape smoke checks, an isolated single-package install smoke, and the full unit/integration suite. The bundled agent tests cover the Fitch profile set directly, so validation does not require pi-fitch-kit. `npm test` is intentionally the fast unit-test shortcut (`npm run test:unit`), not the full completion gate.
+
+For a credential-free Linux gate against committed `HEAD`, Docker and `PI_LINUX_PI_ARCHIVE` are required. Supply an absolute path to a `.tar.gz` containing one top-level `pi/`: a Pi 1.0 source checkout, its Linux `node_modules` (including workspace dependencies), and all built `dist/` output. It must include `pi/packages/coding-agent/dist/index.js` and `pi/packages/coding-agent/dist/bundle/cli.js`.
+
+Prepare that checkout in a clean Linux build environment matching the image's CPU architecture and Node version. Install locked dependencies and complete Pi's workspace build, including its generated model data, before archiving. Do not copy host `node_modules`, Pi user state, `auth.json`, secret `.env` files, or credential-bearing npm/Git configuration. From the Linux build environment:
+
+```bash
+tar -czf /absolute/path/native-pi-linux-node24.tar.gz -C /clean/linux-build pi
+```
+
+Run with an archive matching the image:
+
+```bash
+PI_LINUX_PI_ARCHIVE=/absolute/path/native-pi-linux-node24.tar.gz \
+  bash scripts/linux-smoke.sh
+```
+
+The archive is mounted read-only and extracted to `/native-pi`. The unprivileged `node` user installs locked package dependencies in `/workspace`, points the private CLI link and all SDK overrides at the supplied build, and runs the full, unchanged `npm run ci` gate. No host home, source mount, credentials, or model calls are passed into it. The gate does not patch Pi/Jiti or skip native cases.
+
+## Real Pi smoke
+
+The default local gate includes real SDK reload/reopen and native child-session ownership checks with a controlled CLI and no model calls. Other execution tests stay mock-heavy and deterministic. When you need to verify the actual local file-path Pi package boundary, run the opt-in real smoke:
+
+```bash
+export PATH="$PWD/node_modules/.bin:$PATH"
+node scripts/real-pi-smoke.mjs
+```
+
+Use direct `node` invocation with the intended `pi` first on `PATH`. npm scripts prepend `node_modules/.bin`.
+
+It installs this checkout into an isolated temporary Pi home, runs `pi list`, and loads the bundled subagent and intercom extensions. It does not install pi-fitch-kit, publish to npm, or use GitHub Actions.
+
+Live model-backed subagent paths are intentionally opt-in because they can use provider credentials and tokens:
+
+```bash
+PI_REAL_SMOKE_MODEL=openai/gpt-6-astra node scripts/real-pi-smoke.mjs --llm
+```
+
+That mode copies local `auth.json` and `models.json` into the isolated Pi agent dir, then asks a real Pi session to exercise intercom status plus subagent list, waiting execution, background launch, and background completion. Set `PI_REAL_SMOKE_AUTH_AGENT_DIR` if your auth files are not in `~/.pi/agent`.
+
+For a broader live gate, add `--llm-full`:
+
+```bash
+PI_REAL_SMOKE_MODEL=openai/gpt-6-astra node scripts/real-pi-smoke.mjs --llm-full
+```
+
+That also verifies real parallel, chain, file output, and acceptance flows. It checks actual tool calls and native settlement, and audits saved parent/child model identities. The smoke stops its own processes before removing copied credentials or artifacts, including on timeout or handled cancellation. Use `--keep-temp` to preserve noncredential evidence.
+
+## Local test watchdog
+
+`npm test`, `npm run test:unit`, `npm run test:integration`, and `npm run test:all` run through `scripts/run-tests.mjs`, which applies a per-suite local watchdog so hung child-process or worktree tests fail with the command context instead of hanging forever. The default is 300000ms for units and 1200000ms for integration. Override it when debugging slow local runs:
+
+```bash
+PI_TEST_TIMEOUT_MS=1800000 npm run test:integration
+# or
+node scripts/run-tests.mjs integration --timeout-ms 1800000
+```

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.
 
@@ -18,7 +18,7 @@ Optional HTTPS messaging proxy for a remote agent such as **Grok Bot**. Pi-inter
 
 ## 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.
+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](reference.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.
@@ -35,11 +35,13 @@ The last JSON line contains paths to the issued client `cert`/`key`, trusted `ca
   "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"
-  }]
+  "clients": [
+    {
+      "fingerprint256": "SHA256_FINGERPRINT_FROM_ISSUE",
+      "name": "grok-bot",
+      "cwd": "/Users/mitch/project"
+    }
+  ]
 }
 ```
 
@@ -103,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:
@@ -139,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.
 
@@ -178,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
 ```
@@ -201,9 +253,12 @@ Observed **2026-10-06**, from a separate process on the Mac through the installe
 {
   "platform": "darwin",
   "transport": "loopback HTTPS mTLS",
-  "list": {"ok": true, "peers": ["secure-intercom-bridge", "grok-bot"]},
+  "list": { "ok": true, "peers": ["secure-intercom-bridge", "grok-bot"] },
   "ask": {
-    "ok": true, "accepted": true, "delivered": true, "replied": true,
+    "ok": true,
+    "accepted": true,
+    "delivered": true,
+    "replied": true,
     "reply": "bridge-smoke-ok"
   }
 }