@hheei/pi-subagents 0.7.0 → 0.8.0

package/dist/controller.js

@@ -0,0 +1,217 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, SessionManager, } from "@earendil-works/pi-coding-agent";
+import { isRecord } from "@hheei/pi-ext-core";
+import { CONTROLLER_PROTOCOL, closeControllerIpc, serveControllerIpc } from "./controller-ipc.js";
+import { beginControllerRole, endControllerRole } from "./controller-role.js";
+import piSubagentsExtension, { skillCatalogFromLoaded } from "./extension.js";
+import { holdProcessLock } from "./process-lock.js";
+export class StandaloneControllerError extends Error {
+    code;
+    parentSessionId;
+    constructor(code, message, parentSessionId) {
+        super(message);
+        this.name = "StandaloneControllerError";
+        this.code = code;
+        this.parentSessionId = parentSessionId;
+    }
+}
+export function controllerSocketPath(agentDir, workspace) {
+    return join(controllerDirectory(resolve(agentDir)), `${workspaceKey(resolve(workspace))}.sock`);
+}
+export async function startStandaloneController(options) {
+    const workspace = resolve(options.workspace);
+    const agentDir = resolve(options.agentDir);
+    const directory = controllerDirectory(agentDir);
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const id = workspaceKey(workspace);
+    const lock = lockController(join(directory, `${id}.lock`));
+    let role;
+    let runtime;
+    try {
+        const bindingPath = join(directory, `${id}.json`);
+        const existing = readBinding(bindingPath);
+        if (existing !== undefined && existing.workspace !== workspace) {
+            throw new Error("Standalone controller binding does not match this workspace");
+        }
+        const sessionDir = join(agentDir, "subagents", "sessions");
+        const sessionManager = existing === undefined
+            ? SessionManager.create(workspace, sessionDir)
+            : existsSync(existing.sessionFile)
+                ? SessionManager.open(existing.sessionFile)
+                : // Pi writes the session file only after a user or assistant message.
+                    SessionManager.create(workspace, sessionDir, { id: existing.parentSessionId });
+        const sessionFile = sessionManager.getSessionFile();
+        const parentSessionId = sessionManager.getSessionId();
+        if (sessionFile === undefined)
+            throw new Error("Standalone controller session has no file");
+        if (existing !== undefined && existing.parentSessionId !== parentSessionId) {
+            throw new Error("Standalone controller restored a different parent session");
+        }
+        writeBinding(bindingPath, {
+            workspace,
+            parentSessionId,
+            sessionFile,
+            pid: process.pid,
+            protocol: CONTROLLER_PROTOCOL,
+        });
+        runtime = await createAgentSessionRuntime(async ({ cwd, sessionManager: bound }) => {
+            const services = await createAgentSessionServices({
+                cwd,
+                agentDir,
+                resourceLoaderOptions: {
+                    noExtensions: true,
+                    extensionFactories: [piSubagentsExtension],
+                },
+            });
+            return {
+                ...(await createAgentSessionFromServices({ services, sessionManager: bound })),
+                services,
+                diagnostics: services.diagnostics,
+            };
+        }, { cwd: workspace, agentDir, sessionManager });
+        role = beginControllerRole(skillCatalogFromLoaded(runtime.services.resourceLoader.getSkills().skills));
+        await runtime.session.bindExtensions({ mode: "print" });
+        if (!role.applied)
+            throw new Error("Standalone controller extension did not take ownership");
+        if (role.modelId === undefined || role.credential !== "present") {
+            throw new StandaloneControllerError("model_unavailable", "Standalone controller has no usable Pi model or credential", parentSessionId);
+        }
+        const socketPath = join(directory, `${id}.sock`);
+        const manager = await role.manager;
+        const ipc = await serveControllerIpc({ socketPath, parentSessionId, manager });
+        const started = { runtime, role, lock, ipc };
+        role = undefined;
+        runtime = undefined;
+        // Both signals and a second shutdown call reach this: dispose once, and release the role
+        // and lock even when closing the socket or the runtime throws.
+        let disposal;
+        return {
+            workspace,
+            parentSessionId,
+            sessionFile,
+            socketPath,
+            dispose() {
+                disposal ??= (async () => {
+                    try {
+                        await closeControllerIpc(started.ipc);
+                        await started.runtime.dispose();
+                    }
+                    finally {
+                        endControllerRole(started.role);
+                        started.lock.release();
+                    }
+                })();
+                return disposal;
+            },
+        };
+    }
+    catch (error) {
+        if (runtime !== undefined)
+            await runtime.dispose();
+        if (role !== undefined)
+            endControllerRole(role);
+        lock.release();
+        throw error;
+    }
+}
+function controllerDirectory(agentDir) {
+    return join(agentDir, "subagents", "controllers");
+}
+function workspaceKey(workspace) {
+    return createHash("sha256").update(workspace).digest("hex").slice(0, 32);
+}
+function lockController(lockPath) {
+    try {
+        return holdProcessLock(lockPath, 0);
+    }
+    catch (error) {
+        if (isLockBusy(error)) {
+            throw new StandaloneControllerError("busy", "Standalone controller is already running for this workspace");
+        }
+        throw error;
+    }
+}
+function isLockBusy(error) {
+    return typeof error === "object" && error !== null && "errcode" in error && error.errcode === 5;
+}
+function readBinding(path) {
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        if (isRecord(error) && error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch (error) {
+        throw new Error(`Invalid standalone controller binding: ${path}`, { cause: error });
+    }
+    if (!isRecord(value) ||
+        typeof value.workspace !== "string" ||
+        typeof value.parentSessionId !== "string" ||
+        typeof value.sessionFile !== "string") {
+        throw new Error(`Invalid standalone controller binding: ${path}`);
+    }
+    return {
+        workspace: value.workspace,
+        parentSessionId: value.parentSessionId,
+        sessionFile: value.sessionFile,
+        ...(typeof value.pid === "number" ? { pid: value.pid } : {}),
+        ...(typeof value.protocol === "number" ? { protocol: value.protocol } : {}),
+    };
+}
+/**
+ * A controller left behind by an earlier build keeps this workspace's socket and lock. Its calls are
+ * not this build's to make, so it is stopped here and the caller starts its own.
+ */
+export async function stopPreviousController(agentDir, workspace, expectedPid) {
+    const resolved = resolve(workspace);
+    const id = workspaceKey(resolved);
+    const path = join(controllerDirectory(resolve(agentDir)), `${id}.json`);
+    const binding = readBinding(path);
+    const pid = binding?.pid;
+    // The process that failed the probe may already have been replaced. Killing whatever pid is here
+    // now would stop the replacement.
+    if (expectedPid !== undefined && pid !== expectedPid)
+        return;
+    if (pid === undefined) {
+        throw new Error(`A previous pi-subagents controller owns ${resolved} and does not record its process; quit and reopen the client that started it`);
+    }
+    if (readBinding(path)?.pid !== pid)
+        return;
+    process.kill(pid, "SIGTERM");
+    const deadline = Date.now() + 10_000;
+    while (Date.now() < deadline) {
+        if (!isRunning(pid))
+            return;
+        await new Promise((done) => setTimeout(done, 50));
+    }
+    throw new Error(`A previous pi-subagents controller for ${resolved} did not stop`);
+}
+/** Pid recorded for this workspace, when the binding names one. */
+export function recordedControllerPid(agentDir, workspace) {
+    const resolved = resolve(workspace);
+    const id = workspaceKey(resolved);
+    return readBinding(join(controllerDirectory(resolve(agentDir)), `${id}.json`))?.pid;
+}
+function isRunning(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return !(isRecord(error) && error.code === "ESRCH");
+    }
+}
+function writeBinding(path, binding) {
+    const temporary = `${path}.${process.pid}.tmp`;
+    writeFileSync(temporary, `${JSON.stringify(binding)}\n`, { mode: 0o600 });
+    renameSync(temporary, path);
+}

package/dist/delegation.d.ts

@@ -0,0 +1,73 @@
+import type { PublicSubagent, SubagentState } from "./domain.js";
+import { type Receipt, type ReceiptStatus } from "./receipts.js";
+/** What the agent's runtime is doing now, kept apart from the selected delegation's status. */
+export interface DelegationProgress {
+    readonly runtimeState: SubagentState;
+    readonly summary?: string;
+    readonly activeTool?: string;
+}
+/** Why a delegation did not produce a result, with what it may already have done. */
+export interface DelegationError {
+    readonly reason: string;
+    readonly safeToRetry: boolean;
+    readonly sideEffects: readonly string[];
+}
+/**
+ * Public identity of one delegation: the agent session id plus its monotonic revision. Internal
+ * database keys never appear here, so both consumers speak the same vocabulary.
+ */
+export interface DelegationView {
+    readonly id: string;
+    readonly revision: number;
+    readonly status: ReceiptStatus;
+    readonly task: string;
+    readonly hasOutput: boolean;
+    readonly agent?: string;
+    readonly cwd?: string;
+    readonly resultText?: string;
+    readonly progress?: DelegationProgress;
+    readonly error?: DelegationError;
+}
+/**
+ * Projects one stored delegation. A result only exists for a completed or blocked delegation: the
+ * text of a failed or uncertain one is the reason it failed, not child output.
+ */
+export declare function delegationView(receipt: Receipt, child?: PublicSubagent, options?: {
+    readonly includeOutput?: boolean;
+}): DelegationView;
+/**
+ * The same projection with the result body when the caller asks for it. An explicit read still
+ * obeys the shared output budget: the model gets the head, the tail, and the path to everything it
+ * did not see, never an unbounded body.
+ */
+export declare function agentView(receipt: Receipt, child?: PublicSubagent, options?: {
+    readonly includeOutput?: boolean;
+}): Promise<DelegationView>;
+/** One agent's row in a dashboard: its runtime now, and the status of its latest delegation. */
+export interface AgentSummary {
+    readonly id: string;
+    readonly agent?: string;
+    readonly runtimeState: SubagentState;
+    readonly revision: number;
+    readonly status: ReceiptStatus;
+    readonly hasOutput: boolean;
+    readonly summary?: string;
+}
+export interface DashboardView {
+    readonly total: number;
+    readonly running: number;
+    readonly blocked: number;
+    readonly completed: number;
+    readonly failed: number;
+    readonly children: readonly AgentSummary[];
+}
+/** One stored delegation as history shows it: identity, status and task, never the body. */
+export interface DelegationHistoryEntry {
+    readonly id: string;
+    readonly revision: number;
+    readonly status: ReceiptStatus;
+    readonly task: string;
+    readonly hasOutput: boolean;
+    readonly createdAt: number;
+}
+export declare function historyEntry(receipt: Receipt): DelegationHistoryEntry | undefined;

package/dist/delegation.js

@@ -0,0 +1,71 @@
+import { truncateWithSpill } from "@hheei/pi-ext-core";
+import { receiptCarriesOutput } from "./receipts.js";
+/**
+ * Projects one stored delegation. A result only exists for a completed or blocked delegation: the
+ * text of a failed or uncertain one is the reason it failed, not child output.
+ */
+export function delegationView(receipt, child, options) {
+    if (receipt.childId === undefined || receipt.revision === undefined) {
+        throw new Error(`Delegation ${receipt.delegationId} has no public identity`);
+    }
+    const text = receipt.resultText;
+    const hasOutput = receiptCarriesOutput(receipt.status, text);
+    const failed = text !== undefined && !hasOutput;
+    return {
+        id: receipt.childId,
+        revision: receipt.revision,
+        status: receipt.status,
+        task: receipt.task,
+        hasOutput,
+        ...(options?.includeOutput === true && text !== undefined && hasOutput
+            ? { resultText: text }
+            : {}),
+        ...(failed && text !== undefined
+            ? {
+                error: {
+                    reason: text,
+                    safeToRetry: receipt.safeToRetry ?? false,
+                    sideEffects: receipt.sideEffects ?? [],
+                },
+            }
+            : {}),
+        ...(child === undefined
+            ? {}
+            : {
+                agent: child.agent,
+                cwd: child.cwd,
+                progress: {
+                    runtimeState: child.state,
+                    ...(child.summary === undefined ? {} : { summary: child.summary }),
+                    ...(child.activeTool === undefined ? {} : { activeTool: child.activeTool }),
+                },
+            }),
+    };
+}
+/**
+ * The same projection with the result body when the caller asks for it. An explicit read still
+ * obeys the shared output budget: the model gets the head, the tail, and the path to everything it
+ * did not see, never an unbounded body.
+ */
+export async function agentView(receipt, child, options) {
+    const view = delegationView(receipt, child);
+    const text = receipt.resultText;
+    if (options?.includeOutput !== true || !view.hasOutput || text === undefined)
+        return view;
+    const bounded = await truncateWithSpill(text, "subagent-output");
+    return { ...view, resultText: bounded.text };
+}
+export function historyEntry(receipt) {
+    const id = receipt.childId;
+    const revision = receipt.revision;
+    if (id === undefined || revision === undefined)
+        return undefined;
+    return {
+        id,
+        revision,
+        status: receipt.status,
+        task: receipt.task,
+        hasOutput: receiptCarriesOutput(receipt.status, receipt.resultText),
+        createdAt: receipt.createdAt,
+    };
+}

package/dist/domain.d.ts

@@ -8,16 +8,6 @@ export declare function normalizeSubagentState(value: unknown): SubagentState |
  * is created, because it decides who holds the process for the rest of the child's life.
  */
 export type Presentation = "panel" | "background";
-/**
- * How `agent_send` hands its message to a child.
- *
- * `steer` enters the current assistant turn once its tool calls are in, before the next model
- * request, so it redirects work already in flight. `follow_up` waits until the child's run has no
- * tool calls or steering left, then continues as a new turn in the same run. There is no "auto":
- * the two queues already are the two situations, so the caller picks instead of guessing from the
- * child's state.
- */
-export type SendMode = "steer" | "follow_up";
 export type VisualSubagentState = SubagentState;
 export declare function toVisualSubagentState(state: SubagentState, interrupted?: string): VisualSubagentState;
 export declare const VISUAL_SUBAGENT_GLYPH: Record<VisualSubagentState, string>;
@@ -33,12 +23,10 @@ export interface ChildIdentity {
     readonly subagentId: string;
     readonly runtimeIdentity: string;
     readonly endpoint: string;
-    readonly token: string;
 }
 /**
- * The non-secret half of {@link ChildIdentity}: what a launch spec may contain and
- * what may be persisted. The controller token is added by the launcher at spawn
- * time and never written to a registry snapshot.
+ * What a launch spec may contain and what may be persisted: the child's identity minus nothing,
+ * because the mailbox is authenticated by the process lock its writer holds, not by a token.
  */
 export interface ChildBridgeEnvironment {
     readonly parentSessionId: string;
@@ -211,11 +199,20 @@ export interface SpawnSubagentInput {
      * Where to run this child. `auto` (the default) means a panel whenever this parent has a
      * presentation host, and the background otherwise; the Task tool pins `background` because a
      * Task is settled by its parent and never handed to a human. This is not a model-facing
-     * parameter: `agent_spawn` always spawns with `auto`.
+     * parameter: `agents_delegate` always spawns with `auto`.
      */
     readonly presentation?: Presentation | "auto";
-    /** Optional child session title; the child branch prefixes it with the subagent marker. */
-    readonly title?: string;
+}
+/**
+ * Input for a single delegated turn. An existing child ID always takes precedence over the agent
+ * definition: the child already owns its launch configuration, model, and session history.
+ */
+export interface DelegateSubagentInput {
+    readonly task: string;
+    readonly id?: string;
+    readonly agent?: string;
+    /** Only used when creating a child; ignored when id is supplied. */
+    readonly cwd?: string;
 }
 /** True when a manager call returned a structured failure instead of a value. */
 export declare function isOperationError(value: unknown): value is OperationError;
@@ -228,7 +225,6 @@ export declare const BRIDGE_ENVIRONMENT_KEYS: {
     readonly childId: "PI_SUBAGENTS_CHILD_ID";
     readonly runtimeId: "PI_SUBAGENTS_RUNTIME_ID";
     readonly endpoint: "PI_SUBAGENTS_ENDPOINT";
-    readonly token: "PI_SUBAGENTS_TOKEN";
 };
 /** Non-secret agent label for the child TUI identity line. Not part of handshake. */
 export declare const CHILD_AGENT_ENV_KEY: "PI_SUBAGENTS_AGENT";
@@ -236,6 +232,12 @@ export declare const CHILD_AGENT_ENV_KEY: "PI_SUBAGENTS_AGENT";
 export declare const CHILD_TITLE_ENV_KEY: "PI_SUBAGENTS_TITLE";
 /** Bound Pi session id for the child branch. Not part of the runner handshake. */
 export declare const CHILD_SESSION_ENV_KEY: "PI_SUBAGENTS_SESSION_ID";
+/**
+ * Set on the standalone controller process. Its children must not discover Pi settings extensions:
+ * another installed copy of this package registers the same bridge tool as the explicit -e entry,
+ * and Pi aborts the child before it connects.
+ */
+export declare const STANDALONE_CONTROLLER_ENV_KEY: "PI_SUBAGENTS_STANDALONE_CONTROLLER";
 /** Pi session ids reach argv and file names, so they must stay in Pi's accepted alphabet. */
 export declare function isSessionId(value: unknown): value is string;
 export declare function isThinkingLevel(value: unknown): value is ThinkingLevel;

package/dist/domain.js

@@ -60,7 +60,6 @@ export const BRIDGE_ENVIRONMENT_KEYS = {
     childId: "PI_SUBAGENTS_CHILD_ID",
     runtimeId: "PI_SUBAGENTS_RUNTIME_ID",
     endpoint: "PI_SUBAGENTS_ENDPOINT",
-    token: "PI_SUBAGENTS_TOKEN",
 };
 /** Non-secret agent label for the child TUI identity line. Not part of handshake. */
 export const CHILD_AGENT_ENV_KEY = "PI_SUBAGENTS_AGENT";
@@ -68,6 +67,12 @@ export const CHILD_AGENT_ENV_KEY = "PI_SUBAGENTS_AGENT";
 export const CHILD_TITLE_ENV_KEY = "PI_SUBAGENTS_TITLE";
 /** Bound Pi session id for the child branch. Not part of the runner handshake. */
 export const CHILD_SESSION_ENV_KEY = "PI_SUBAGENTS_SESSION_ID";
+/**
+ * Set on the standalone controller process. Its children must not discover Pi settings extensions:
+ * another installed copy of this package registers the same bridge tool as the explicit -e entry,
+ * and Pi aborts the child before it connects.
+ */
+export const STANDALONE_CONTROLLER_ENV_KEY = "PI_SUBAGENTS_STANDALONE_CONTROLLER";
 const SESSION_ID_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$/;
 /** Pi session ids reach argv and file names, so they must stay in Pi's accepted alphabet. */
 export function isSessionId(value) {

package/dist/extension.js

@@ -2,14 +2,16 @@ import { createRenderThrottle, DEFAULT_MAX_BYTES, errorMessage, fitsOutputBudget
 import { discoverAgents } from "./agent-resolver.js";
 import { registerChildBridge } from "./child-bridge.js";
 import { registerParentCommands } from "./commands.js";
+import { activeControllerRole } from "./controller-role.js";
 import { BRIDGE_ENVIRONMENT_KEYS, isThinkingLevel } from "./domain.js";
 import { createCmuxHostAdapter, createHerdrHostAdapter, listCmuxAttachments, listHerdrAttachments, rebindCmuxSurface, rebindHerdrTab, selectHostAdapter, systemHostCommandRunner, } from "./host-adapter.js";
 import { appendSubagentInfo, displaySubagentText, registerSubagentInfo } from "./info.js";
 import { createMailboxTransport } from "./mailbox.js";
 import { SubagentManager } from "./manager.js";
 import { transformSubagentsMarkdown } from "./markdown.js";
+import { sweepUncertainDispatch } from "./receipts.js";
 import { createSubagentRegistry } from "./registry.js";
-import { createRuntimeTokenStore, launchChild, openChildPanel, prepareRuntimeDirectory, } from "./runtime.js";
+import { launchChild, openChildPanel, prepareRuntimeDirectory } from "./runtime.js";
 import { persistSubagentIntent, resolveSubagentLaunch } from "./session-bootstrap.js";
 import { createSubagentStatus } from "./status.js";
 import { registerInteractiveToolActivation } from "./tool-activation.js";
@@ -39,7 +41,6 @@ function childIdentityFromEnv(env) {
         subagentId: requiredBridgeValue(env, BRIDGE_ENVIRONMENT_KEYS.childId),
         runtimeIdentity: requiredBridgeValue(env, BRIDGE_ENVIRONMENT_KEYS.runtimeId),
         endpoint: requiredBridgeValue(env, BRIDGE_ENVIRONMENT_KEYS.endpoint),
-        token: requiredBridgeValue(env, BRIDGE_ENVIRONMENT_KEYS.token),
     };
 }
 /**
@@ -139,26 +140,43 @@ export default function piSubagentsExtension(pi) {
             const context = runtime.extension;
             const parentSessionId = context.sessionManager.getSessionId();
             const registry = createSubagentRegistry({ parentSessionId });
-            const tokens = createRuntimeTokenStore({ parentSessionId, diagnose });
+            sweepUncertainDispatch(registry.path, parentSessionId);
             // Presentation is chosen once per parent session: herdr first, then cmux, and a parent with
             // neither runs every child in the background. Successful selection stays silent; only actual
             // failures and fallback diagnostics are reported by the launch path.
             const ownerId = parentSessionId;
             const ownsAttachment = (identity) => identity.createdBy === ownerId;
-            const hostSelection = await selectHostAdapter({
-                adapters: {
-                    herdr: createHerdrHostAdapter({ ownerId, ownsAttachment }),
-                    cmux: createCmuxHostAdapter({ ownerId, ownsAttachment }),
-                },
-            });
-            const delivery = getBackgroundDelivery(pi);
-            const channel = createParentChannel(pi, {
-                isIdle: () => context.isIdle(),
-                ui: context.ui,
-                delivery,
-                signal: runtime.signal,
-            });
+            const controller = activeControllerRole();
+            const hostSelection = controller
+                ? {
+                    available: false,
+                    selectedHost: null,
+                    reason: "standalone controller keeps children in the background",
+                }
+                : await selectHostAdapter({
+                    adapters: {
+                        herdr: createHerdrHostAdapter({ ownerId, ownsAttachment }),
+                        cmux: createCmuxHostAdapter({ ownerId, ownsAttachment }),
+                    },
+                });
+            const channel = controller ??
+                createParentChannel(pi, {
+                    isIdle: () => context.isIdle(),
+                    ui: context.ui,
+                    delivery: getBackgroundDelivery(pi),
+                    signal: runtime.signal,
+                });
             runtime.resources.add("parent-channel", () => channel.dispose());
+            if (controller !== undefined) {
+                controller.applied = true;
+                const model = context.model;
+                if (model !== undefined && model.id !== "unknown") {
+                    controller.provider = model.provider;
+                    controller.modelId = model.id;
+                    const key = await context.modelRegistry.getApiKeyForProvider(model.provider);
+                    controller.credential = typeof key === "string" && key !== "" ? "present" : "missing";
+                }
+            }
             let manager;
             // One sqlite file is the ledger and the mailbox. Presence is not liveness.
             const mailbox = createMailboxTransport({
@@ -171,17 +189,18 @@ export default function piSubagentsExtension(pi) {
             runtime.resources.add("subagent-bridge", () => mailbox.close());
             // A definition names skills the way Pi lists them, so the parent's loaded skill set is
             // the only name → path catalog; Pi hands it over before every prompt of this session.
-            let skillCatalog = [];
-            const unsubscribeSkillCatalog = pi.on("before_agent_start", (event) => {
-                const skills = event.systemPromptOptions?.skills ?? [];
-                skillCatalog = skillCatalogFromLoaded(skills);
-            });
-            runtime.resources.add("subagent-skill-catalog", unsubscribeSkillCatalog);
+            let skillCatalog = controller?.skills ?? [];
+            if (controller === undefined) {
+                const unsubscribeSkillCatalog = pi.on("before_agent_start", (event) => {
+                    const skills = event.systemPromptOptions?.skills ?? [];
+                    skillCatalog = skillCatalogFromLoaded(skills);
+                });
+                runtime.resources.add("subagent-skill-catalog", unsubscribeSkillCatalog);
+            }
             manager = new SubagentManager({
                 parentSessionId,
                 registry,
                 channel,
-                tokens,
                 async resolve(input) {
                     const model = context.model;
                     if (model === undefined)
@@ -213,7 +232,6 @@ export default function piSubagentsExtension(pi) {
                     return launchChild({
                         registry,
                         record,
-                        tokens,
                         waitForBridge: (childId, signal) => mailbox.waitUntilSeen(childId, {
                             timeoutMs: START_WINDOW_MS,
                             ...(signal === undefined ? {} : { signal }),
@@ -229,7 +247,6 @@ export default function piSubagentsExtension(pi) {
                             openPanel: (record) => openChildPanel({
                                 registry,
                                 record,
-                                tokens,
                                 host: hostSelection.adapter,
                                 waitForBridge: (childId, signal) => mailbox.waitUntilSeen(childId, {
                                     timeoutMs: START_WINDOW_MS,
@@ -260,7 +277,6 @@ export default function piSubagentsExtension(pi) {
                                 const launch = await openChildPanel({
                                     registry,
                                     record,
-                                    tokens,
                                     host: hostSelection.adapter,
                                     waitForBridge: (childId, signal) => mailbox.waitUntilSeen(childId, {
                                         timeoutMs: START_WINDOW_MS,
@@ -288,6 +304,7 @@ export default function piSubagentsExtension(pi) {
                     }
                     : {}),
             });
+            controller?.bindManager(manager);
             // Recovery must never take the extension down with it: a registry this version cannot
             // read (for example records written by an older release) is reported in the session and
             // the user is told how to reset it.

package/dist/host-adapter.js

@@ -184,7 +184,7 @@ export function createCmuxHostAdapter(options) {
                 noun: "surface",
                 // TODO(cmux-focus): cmux does not report which surface a human is looking at, so
                 // observation cannot answer `focused` and idle reclaim fails open here: a cmux child
-                // is only ever closed by agent_stop.
+                // is only ever closed by agents_stop.
                 reportsFocus: false,
                 observe: async () => {
                     const process = await runner.run("cmux", ["--json", "list-panels"], { timeoutMs });

package/dist/launch-spec.d.ts

@@ -12,7 +12,7 @@ export interface LaunchSpec {
     readonly cwd: string;
     readonly presentation: Presentation;
     readonly stdio: "pipe" | "inherit";
-    /** Bridge variables to add to the child environment, excluding the controller token. */
+    /** Bridge variables to add to the child environment. */
     readonly env: Readonly<Record<string, string>>;
     readonly config: EffectiveLaunchConfig;
 }
@@ -25,8 +25,6 @@ export interface BuildLaunchSpecOptions {
     readonly bridge: ChildBridgeEnvironment;
 }
 export declare function assembleChildPrompt(instructions: string): string;
-/** Adds the per-runtime controller token. Tokens stay out of launch spec snapshots and the registry. */
-export declare function withBridgeToken(env: Readonly<Record<string, string>>, token: string): Record<string, string>;
 /**
  * Absolute path to this package's extension entry, which every child loads with
  * `-e` so the child branch exists even when extension discovery is disabled.