@bastani/atomic 0.9.40 → 0.9.41-alpha.2

package/CHANGELOG.md

@@ -2,6 +2,81 @@
 
 ## [Unreleased]
 
+## [0.9.41-alpha.2] - 2026-10-22
+
+Workflows that drop a promise stop crashing Atomic, and classifiers can read images.
+
+- **Workflow failures stay inside their run:** an unhandled `ctx` rejection, a stray `ctx.exit()`, or a branch that outlives a kill or quit now fails or ends only its own run instead of the whole process, and `/workflow status` can inspect runs whose child workflows were still starting ([#3846](https://github.com/bastani-inc/atomic/issues/3846), [#3849](https://github.com/bastani-inc/atomic/pull/3849))
+- **Image input for more classifiers:** `models.classify()` accepts `images` for Jev and Clef on Cloudflare Workers AI and OpenRouter, with corrected Workers AI pricing and `compat` settings for proxies ([#3847](https://github.com/bastani-inc/atomic/pull/3847))
+- **Terminal and rendering fixes:** Rex terminal support, terminal modes restored on unexpected exit, Markdown tables after unclosed `$$` blocks, CJK emphasis, `@` autocomplete with regex characters, and a `grep` tool that ignores your ripgrep config ([#3847](https://github.com/bastani-inc/atomic/pull/3847))
+
+### Added
+
+- Codemode `models.classify()` now also accepts `images` for TypeSafe's Jev and Cloudflare's Clef models on `cloudflare-workers-ai` and OpenRouter, next to Jev on `typesafe`, and lists Clef Omni and Jev 1.14 on Workers AI. See [Use classifier models](docs/models.md#use-classifier-models). Provider-level `compat` in `models.json` now also applies to classifier models, with the System One fields `imageInput` and `sendImageOptInHeader` for proxies that serve another service's classifiers. Extension classifier models accept `compat` too. See [Models Configuration](docs/models-configuration.md#typesafe-system-one).
+- Added support for the Rex terminal (`TERM_PROGRAM=rex`): OSC 8 hyperlinks, truecolor, and inline images. Links previously fell back to the `text (url)` format ([#11131](https://github.com/earendil-works/pi/issues/11131), [#11150](https://github.com/earendil-works/pi/pull/11150) by [@petrroll](https://github.com/petrroll), [#11183](https://github.com/earendil-works/pi/pull/11183) by [@nihaals](https://github.com/nihaals))
+
+### Fixed
+
+- Fixed Cloudflare Workers AI classifier pricing: Clef Flash costs $0.038 and Jev $0.042 per million input tokens instead of Jev being listed as free.
+- Fixed the `grep` tool following ripgrep's `RIPGREP_CONFIG_PATH` whenever it searches with `rg`, such as with `literal: true`, where config options like `--ignore-case` silently changed what the tool returned. The tool now runs `rg --no-config` ([#11203](https://github.com/earendil-works/pi/issues/11203))
+- Fixed `@` file autocomplete returning no results for queries containing regex metacharacters such as `[` or `(` ([#10972](https://github.com/earendil-works/pi/issues/10972))
+- Fixed an unclosed `$$` display-math block swallowing or corrupting every Markdown table after it ([#11159](https://github.com/earendil-works/pi/issues/11159))
+- Fixed terminal modes (mouse tracking, focus reporting, Kitty keyboard protocol, bracketed paste, alternate screen) staying enabled when the process exits without calling `stop()`. A process `exit` handler now restores them synchronously ([#11170](https://github.com/earendil-works/pi/issues/11170))
+- Fixed Markdown bold and italic not rendering next to CJK punctuation ([#10730](https://github.com/earendil-works/pi/pull/10730) by [@theBucky](https://github.com/theBucky))
+- A rejection that workflow code leaves unhandled no longer ends the whole Atomic process. This covers a rejected `ctx.tool`, `ctx.task`, `ctx.chain`, `ctx.parallel`, `ctx.workflow`, `ctx.ui` prompt (`input`, `confirm`, `select`, `editor` or `custom`) or stage method call (`prompt`, `complete`, `steer`, `sendUserMessage`, `setModel`, `compact` and the other promise-returning stage methods), including one that is started and never awaited (`void ctx.task(...)` used to leave the run `completed` with no sign of the failure), a `ctx.tool` call made after its run has stopped (`ctx.tool admission is closed for this run`), a string, number or `undefined` thrown from a `ctx.tool` callback, and an error the workflow file throws or receives from `fs` itself, for example in a rolling pool that keeps `branch.finally(...)` as a separate promise. It also covers `ctx.exit()` called inside such a branch, which ends the run as exited with the status and outputs it asked for (on Bun the process used to end right after the run reported `completed`), and a child workflow's own branch that uses `ctx` after its parent exited. Stopping a run no longer ends the process either: a branch that keeps running after `/workflow quit`, a kill, or an abort signal from the code that started the run, and then calls `ctx.stage`, `ctx.task`, `ctx.workflow` or `ctx.exit()`, or that was waiting on a `ctx.ui` prompt when the run was killed, could end it with `workflow killed` (a kill), the quit error (`/workflow quit`), an `AbortError` or `atomic-workflows: HIL aborted` right after the run reported `killed` or `paused`, and the run keeps that status. `ctx.exit()` called in such a branch while the run is paused ends the run as exited once the run resumes, and a kill of the paused run still ends it as `killed` (on Node it used to end as `failed` with `Workflow exit is waiting for explicit resume`, and on Bun the process ended). The rejection fails its own run when it surfaces before that run decides its final status, so other runs, stages, and the interactive engine keep going; a `ctx.task`, `ctx.chain`, `ctx.parallel`, `ctx.workflow`, `ctx.ui` or stage method rejection that the workflow awaits or catches reaches that code unchanged and does not fail the run. Once the run has ended, an error that a `ctx` call rejected with, what `ctx.exit()` threw and the reason the run was stopped with are ignored (the reason of a kill is the string `workflow killed`, which is ignored by value for the rest of the process, so a branch that wakes up long after the run ended is covered too), and so is an error thrown by the workflow file for the next 30 seconds, so the remaining branches of a failing pool cannot end the process; a later one ends it as before. On Node the owning run is identified exactly; on Bun a `ctx` call's rejection, what `ctx.exit()` threw and the reason the run was stopped with are matched by identity (a `ctx` call's string, number or `undefined` only within the event-loop turn in which the call rejected, and the string a kill uses by value), and an error thrown by the workflow file itself is matched through its stack to the run of the file that calls `workflow()`, but only when no other run of that file is running or has run at the same time (a child workflow defined in the same file does not count), so a primitive thrown outside a `ctx` call on Bun is still fatal, and an error that either of two overlapping runs of one file could have thrown ends the process as before instead of failing a run that may be healthy. This works the same in the bundled install as in a source checkout. A rejection that belongs to no workflow run, including one raised by Atomic's own code, ends the process as before, with its original error and stack, and `--unhandled-rejections=warn|none|warn-with-error-code` are honored ([#3846](https://github.com/bastani-inc/atomic/issues/3846))
+- A workflow that omits `name` is now named after the file that defines it when Atomic runs from the bundled install, as it already was in a source checkout, instead of after the bundled extension file (`index.bundle`) ([#3846](https://github.com/bastani-inc/atomic/issues/3846))
+- `/workflow status <runId>` no longer reports `durable checkpoint topology is malformed or incomplete` for a running or crashed run whose child `ctx.workflow` calls have started but not yet recorded a stage or tool of their own, such as a pool of concurrent children when the process was killed. The children now show as running, and a crashed run can be inspected and resumed. A run that fails while such children are still starting now cancels them first, so its status can be inspected as well ([#3846](https://github.com/bastani-inc/atomic/issues/3846))
+
+## [0.9.41-alpha.1] - 2026-10-21
+
+### Breaking Changes
+
+- SDK `steer()` and `followUp()`, and the RPC `steer` and `follow_up` commands, now start a turn when the agent is idle and the session already has messages. On a session with no messages yet, or after a run was aborted, the message still waits for the next prompt. If you queue a message on an idle session that has messages and then call `prompt()` (or send an RPC `prompt`) right away, that prompt now fails with "Agent is already processing" unless you pass `streamingBehavior` (`"steer"` or `"followUp"`) to queue it behind the running turn.
+
+### Added
+
+- `routeExecutionModel()` accepts an optional `inference` option (exported type `RoutingInferenceBounds`) for callers that must not wait indefinitely on routing inference: `deadline` is an `AbortSignal` whose abort ends routing as a complete inference failure, so the caller can degrade to `AutoRoutingInferenceError.currentModelRoute`, and `limit` runs each routing inference under the caller's concurrency limit. Without it, routing keeps having no built-in deadline.
+- RPC `get_available_models` and `refresh_models` responses now list extension providers that accept an API key in `customAuthProviders`, and report extension providers' environment or configured-key authentication in `providerAuthStatuses`.
+- Extension OAuth providers can throw `OAuthRefreshRejectedError` (exported from `@bastani/atomic`, with `isOAuthRefreshRejectedError`) from `refreshToken` when the provider rejected the stored login. The user then sees the same `run /login <provider>` guidance as for a built-in provider. See [Provider OAuth](docs/custom-provider/oauth.md#rejected-logins).
+- Exported `noOpUIContext`, the default no-op extension UI context, from the SDK entry point ([#3801](https://github.com/bastani-inc/atomic/issues/3801))
+- `session.workflows.waitForSettled(runId)` resolves once a workflow run's ending is recorded in the workflow journal and its lease is released, so an SDK host can wait for the journal to be final after a run reports `completed`, `failed` or `killed`. It resolves at once for a run the session is not executing, and rejects with `WorkflowRunStorageError` when the journal could not record the ending. Extensions that call `registerWorkflowRunControl` must implement `waitForSettled` ([#3811](https://github.com/bastani-inc/atomic/issues/3811))
+- `createStructuredOutputTool()` and `generateStructuredOutput()` accept a `timeoutMs` option: the wall-clock limit in milliseconds for one whole structured decision, covering every repair attempt, transport retry, and model fallback together. Without it, the `structured_output` tool uses the session's `httpIdleTimeoutMs` setting and other calls use that setting's 10-minute default. The calling model cannot set it. Extensions can read the setting with `ctx.getHttpIdleTimeoutMs()` ([#3806](https://github.com/bastani-inc/atomic/issues/3806))
+- The task-host `CancelCause` contract adds `pause` and `quit`, typed resumable stops for an agent that is paused and awaiting resume rather than ended. A workflow stage pausing now stops its agents with `pause` instead of `parent-handoff`; `parent-handoff` stays valid for fresh-start handoffs and for entries recorded by earlier versions.
+
+### Changed
+
+- Reopening `/resume` is faster: the session list is kept between opens and reloads only the sessions that were created, renamed, deleted, or changed since the last open, including changes made by other Atomic processes sharing the store.
+- A subagent stopped with `pause` or `quit`, or by its workflow stage pausing, now reaches the parent as `Subagent <agent> quit · paused, awaiting resume` (or `paused · awaiting resume`) with `Stop reason: quit` or `pause` and the exact `subagent({ action: "resume", id: "<child-id>" })` call, as a quit workflow run is reported, instead of a `parent-handoff` stop notice saying the execution has ended and must not be restarted. Its `/tasks` row shows **Paused · awaiting resume**. Children cancelled for good keep the ended notice.
+- The What's New banner shown after an update now leads with the release's highlights summary and points to `/changelog` for the full list of changes. Releases without a summary still show their full notes ([#3804](https://github.com/bastani-inc/atomic/issues/3804))
+- Provider attribution headers now come from pi-ai's client identity, still sent only while `enableInstallTelemetry` is on. Chat requests to providers send Atomic's `User-Agent` (`atomic/<version> (<platform>; <runtime>; <arch>)`), including Cloudflare requests, which sent `atomic` before, and OpenCode requests send `x-opencode-client` whenever attribution is enabled, not only with a session. Extensions' `before_provider_headers` handlers no longer see the OpenRouter, NVIDIA NIM, and OpenCode attribution headers or the default `User-Agent`.
+- The release lookup that runs before Atomic downloads `fd` or `ripgrep` now sends Atomic's `User-Agent` (`atomic/<version> (<platform>; <runtime>; <arch>)`) instead of `atomic`.
+
+### Fixed
+
+- Fixed `structured_output` and `generateStructuredOutput` failing the whole request with `Structured output model is unavailable or not a chat or classifier model` when one explicit `model` or `fallbackModels` ID could not be resolved, for example a display name instead of a `provider/model` ID. The unresolvable ID is now skipped and recorded in `modelAttempts`, and the remaining candidates, including the current chat model, are still tried. The request fails with the original error only when no candidate resolves ([#3814](https://github.com/bastani-inc/atomic/issues/3814))
+- Fixed concurrent extension `select`/`confirm`/`input`/`editor` dialogs in interactive mode: a second dialog replaced the first and the first promise never settled, and a dialog opened from an inline `custom()` component hid that component for good. Closing the visible dialog now shows the previous one again ([#11166](https://github.com/earendil-works/pi/issues/11166))
+- Fixed pasting in the shell hanging after copying text in Atomic and suspending it with Ctrl+Z on Linux: the background `wl-copy`/`xclip`/`xsel` process that keeps serving the clipboard was suspended along with Atomic ([#11179](https://github.com/earendil-works/pi/issues/11179))
+- Fixed codemode scripts failing immediately when both codemode workers are busy, for example with parallel codemode calls or in-process subagents. Scripts now wait up to 60 seconds for a free worker, and `ATOMIC_CODEMODE_MAX_WORKERS` (or `PI_CODEMODE_MAX_WORKERS`) raises the limit of two workers ([#11184](https://github.com/earendil-works/pi/issues/11184))
+- Fixed `mcp.json` files that start with a UTF-8 BOM failing to parse, which skipped all their MCP servers and made `atomic mcp add`/`atomic mcp remove` fail ([#11191](https://github.com/earendil-works/pi/issues/11191))
+- The default GitHub Copilot model is now GPT-6.1 Sol. The previous default, GPT-5.4, was deprecated by GitHub on 2026-10-19 and dropped from the model catalog, so a Copilot login had no usable default model. GPT-6.1 Sol is GitHub's suggested replacement.
+- When extensions fail to start a session, the error now names each failing extension and its own error (`Extension startup failed: <extension path>: <error>`) instead of only `Extension startup failed`. The SDK exports the thrown `ExtensionStartupError`, whose `failures` lists the extension path, event, and message of each failure, together with `isExtensionStartupFailure()` and `isTransientExtensionStartupFailure()` ([#3807](https://github.com/bastani-inc/atomic/issues/3807)).
+- Stored OAuth logins, such as `openai-1` or `anthropic-2`, no longer stop working with `OAuth refresh failed ... invalid_grant` under heavy load from many sessions, workflow stages, or subagents until you run `/login`. A session that is slow or briefly unresponsive while it refreshes a token keeps its claim on that refresh, so another session no longer reuses the replaced refresh token. A slow token refresh is no longer cut off at its timeout. Its result is saved when the response arrives, and other sessions wait for it instead of reusing the replaced token. A token refresh the provider completed is also saved when another session took over meanwhile. A session whose refresh is rejected uses a login that another session has just saved. A login the provider has revoked or expired still fails. The error now tells you to run `/login <provider>` for that provider and shows only the provider's error code and description, never tokens.
+- Sessions waiting for another session's OAuth token refresh no longer fail with `Lock file is already being held` before that refresh finishes under heavy load. They now wait as long as a refresh can keep its claim, then use the rotated token. Cancelling the request still stops the wait.
+- Kimi Code logins no longer break with `invalid_grant` when a token refresh takes longer than 30 seconds or loses its connection mid-request. A revoked or expired OpenAI, Kimi Code, xAI, Meta or GitHub Copilot login now also tells you to run `/login <provider>`, for example on OpenAI's `refresh_token_expired` or `refresh_token_reused` errors.
+- A stored OAuth login no longer breaks with `invalid_grant` after Atomic exits while a token refresh is still running, for example a subagent or `atomic -p` run ending after its request timed out, quitting an interactive session, `SIGTERM`, or `atomic auth`. Atomic now waits up to three seconds on exit for the provider's response and saves the rotated token. An `atomic -p` run no longer stays alive waiting for a token refresh that never answers. If Atomic is killed or crashes during a token refresh, run `/login <provider>`.
+- An extension or `models.json` provider whose `$VAR` API key is unset now reports the missing key the way a built-in provider does wherever its models are used, for example `No API key found for <provider>` with the `/login` hint during compaction and branch summaries. Previously compaction, branch summaries, workflow stages, and subagents failed with `Failed to resolve API key ... from environment variable`.
+- Extension OAuth providers whose refresh is rejected now get the built-in `run /login <provider>` guidance, and a newer login another session saved is still used first, when `refreshToken` throws an error carrying a code the built-in providers treat as a rejected login (`invalid_grant`, `refresh_token_expired`, `refresh_token_reused`, or `refresh_token_invalidated`) in its `error` or `code` property or in an OAuth error response (flat or nested under `error.code`) in `body`, `data`, `response.data`, or `response.body`, or HTTP status 401 in `status`, `statusCode`, `response.status`, or `response.statusCode`. Previously these showed the raw error message, which could include the request's tokens.
+- In interactive sessions, `/login` lists extension providers that take an API key and logs in to them, `/logout` offers their stored keys, and `/login` shows an extension provider configured through an environment variable as configured instead of `not configured`.
+- `/resume` search no longer keeps a session's old text after the session is rewritten with the same message count, first message, header and last-modified time, for example when an earlier message's text is replaced. Search now finds the new text and not the removed text, including when another Atomic process made the change.
+- `structured_output` and `generateStructuredOutput` rejections now say what was wrong instead of the fixed `Invalid structured output: response does not match the decision schema.`. A schema mismatch lists up to five failing paths with the expected shape, such as `/files: expected array, got string` and `/summary: required`, followed by `and N more` when there are others, and never echoes the rejected values. When the provider's tool arguments were not valid JSON, the error is `Invalid structured output: tool call arguments were not valid JSON.` with the kind of syntax error and, when known, its position, without quoting the arguments, instead of a schema mismatch on `{}`. The same detail is sent to the model in the repair request and is kept in `modelAttempts` when a candidate model is exhausted ([#3802](https://github.com/bastani-inc/atomic/issues/3802))
+- Shell `wait` and `kill` results now read as one status line above the task's output instead of a raw JSON envelope with internal ids: `✓ completed · exit 0`, `✗ exited 1`, `● still running · showing output so far`, or `○ cancelled`. A truncated result keeps the full-output path as a dim line, and `(no output)` is dimmed. Waiting on or killing an unknown or foreign task id now says `No background task "<id>" in this session` and points to `/tasks`, instead of `UnknownTask: UnknownTask`. The agent receives the same facts as one compact sentence (state, exit code, truncation, full-output path), the structured observation or cancellation receipt stays in the result `details`, and the failures thrown by `wait` and `kill` keep their code in a `code` property ([#3828](https://github.com/bastani-inc/atomic/issues/3828))
+- Fixed a structured decision having no total time limit: a `structured_output` call, a `generateStructuredOutput()` call, or one routing inference for `model: "auto"` could run four slow generations back to back, plus retries, past every configured timeout, and held a workflow stage for over an hour. The whole decision is now stopped after the `httpIdleTimeoutMs` setting (10 minutes by default; disabled means effectively unbounded) and fails with `Structured output decision exceeded its <n>ms deadline; no decision was accepted.`, without trying another repair or fallback model ([#3806](https://github.com/bastani-inc/atomic/issues/3806))
+- The error for exhausted `structured_output` and `generateStructuredOutput` repairs, and the new deadline error, now end with how each attempt finished and how long it took, such as `Attempts: 1) stopReason=stop 25m02s; 2) stopReason=length 1m30s.`, so one slow generation reads differently from several failed ones. Each provider request, including a transport retry, is listed on its own ([#3806](https://github.com/bastani-inc/atomic/issues/3806))
+- Messages typed while the agent was busy are no longer dropped or left waiting for the end of the run. A message typed while a prompt was still being prepared, while Atomic waited to retry a failed request, just after you sent a prompt (before the screen showed that the turn had started), or while extensions were still finishing the previous run used to appear nowhere and be sent only after the run ended, or be refused with "Agent is already processing" and lost. It now shows as queued straight away and joins the run at its next turn boundary, in the order you typed it. If the agent refuses a message, the text comes back to the editor, or stays in the queue, together with the error.
+- Queued messages are no longer left undelivered when the agent finishes before they are queued. The rest of a queued batch, such as the messages held during compaction, and a `steer` or `follow_up` sent to an idle agent whose session already has messages now start a turn instead of waiting for your next prompt.
+- Near-neutral backgrounds such as message and selection backgrounds no longer turn too bright or blue in 256-color terminals: they now use the nearest color-cube or grayscale entry. Tool status backgrounds keep their blue, green, or red tint, so pending, successful, and failed tool blocks stay distinguishable ([#2550](https://github.com/bastani-inc/atomic/issues/2550))
+- Fixed resumed sessions and `/tree` navigation leaving extension tools inactive when the branch recorded its tools before they were registered, such as tools from extensions installed after the session started. Extension tools the branch never added or removed are now active unless they are registered with `defaultActive: false` ([#11062](https://github.com/earendil-works/pi/issues/11062), [#11075](https://github.com/earendil-works/pi/issues/11075))
+
 ## [0.9.40] - 2026-10-20
 
 ### Breaking Changes

package/README.md

@@ -194,7 +194,7 @@ Type `/` in the editor to trigger commands. [Extensions](#extensions) can regist
 | `/share` | Upload as private GitHub gist with shareable HTML link |
 | `/reload` | Reload keybindings, extensions, skills, prompts, and context files (themes hot-reload automatically) |
 | `/hotkeys` | Show all keyboard shortcuts |
-| `/changelog` | Display version history |
+| `/changelog` | Display the full version history |
 | `/exit` | Exit Atomic |
 | `/quit` | Quit Atomic |
 

package/dist/builtin/intercom/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to the `pi-intercom` extension will be documented in this fi
 
 ## [Unreleased]
 
+## [0.9.41-alpha.1] - 2026-10-21
+
+### Changed
+
+- Workflow route updates cost the Intercom broker far less when many runs are active. The broker now acknowledges each route registration itself instead of the session listing the previous version requested after every update, and each run's route connection retries on its own backoff, with limited concurrency, instead of all of them reconnecting at once. A workflow stage that starts while its run's route connection is waiting to retry waits for that retry rather than failing, and a retry that fails is retried by the stage like any other connection timeout. Mixed versions keep working: with an older broker the session listing is still used, and older sessions work with the new broker.
+
+### Fixed
+
+- `intercom list` with a `group` that names a workflow invocation group you are not a member of no longer reports `No sessions or workflow stages in this group.` The group is visible only to its members, so the peek now says that and tells you to `intercom join` it to see its stages, instead of looking like a run whose stages had all disappeared.
+- Fixed `Intercom event relay failed (atomic:workflow-pending-stage-route): Connection timeout` repeating for every route update when 50 or more workflows ran at once. A broker that is slow to answer a connection is now a recoverable condition that background relays retry quietly. A broker that stays unresponsive for a minute is reported once, and Intercom tool calls you make still report the failure.
+- Fixed a single workflow run's route connection failing to connect and dropping the session's healthy Intercom connection, which re-created every run's connection at the same time.
+
 ## [0.9.40] - 2026-10-20
 
 ### Added

package/dist/builtin/intercom/README.md

@@ -373,7 +373,7 @@ Only registered in sessions where `pi-subagents` supplied the required child bri
 
 **`groups`** — Lists every group represented by a connected session, with session counts and membership markers, so callers can discover names instead of guessing.
 
-**`list`** — Keeps session-listing semantics: returns the current session and every active session sharing at least one membership. Pass `group` for a read-only view of one group.
+**`list`** — Keeps session-listing semantics: returns the current session and every active session sharing at least one membership. Pass `group` for a read-only view of one group. A workflow invocation group (`workflow:<rootRunId>`) is visible only to its members, so peeking at one you have not joined says so and tells you to `join` it instead of listing it as empty.
 
 Live target lookup accepts an exact full Intercom session ID, a unique 8-hex prefix of a UUID-backed session, or an exact case-insensitive session name. Prefix matching stays inside the sender's existing authorized visibility; collisions list the matching full UUIDs and require one of them. Join `workflow:<rootRunId>` and use `intercom list` to see materialized `PENDING`/`RUNNING` workflow stages with canonical `workflow:<rootRunId>/<segment>[/<segment>...]` paths, plus possible future literals, globs, nested paths, and their queued counts. `*` matches one segment and `**` any depth. `workflow:<rootRunId>/**` reaches live stages now and remains sticky for every future stage until root termination; narrower patterns behave the same for their matches. A valid path outside the known set queues with `notInKnownSet` and settles undeliverable at terminal only if never delivered. Use `ask` only on live targets. An eligible invocation member has directional list/send/live-ask control over stages in owned `workflow:<rootRunId>/...` subgroups. A subgroup stage or another workflow root cannot turn a mutable join into parent control; sibling subgroups stay isolated, and explicit `group: "default"` remains non-owned.
 

package/dist/builtin/intercom/broker/broker.ts

@@ -71,10 +71,9 @@ import { handleBrokerPresence } from "./presence-handler.js";
 import {
 	knownGroupSummaries,
 	sessionGroups,
-	sessionsInGroup,
-	sessionsVisibleTo,
 	setSessionGroups,
 } from "./group-membership.js";
+import { replyToList } from "./list-reply.js";
 import { PendingQuestionIndex } from "./pending-question-index.js";
 import { type ReceiptSender, RecipientReceipts, UNCERTAIN_RECEIPT_REASON } from "./recipient-receipts.js";
 import { matchStagePathSegments } from "../workflow-stage-path-matching.js";
@@ -1567,6 +1566,7 @@ class IntercomBroker {
             sessionId: id,
             ...(supervisorId ? { supervisorSessionId: supervisorId } : {}),
             ...(clientMessage.acknowledgesReceipt === true ? { acknowledgesReceipt: true as const } : {}),
+            acknowledgesPendingStageRoutes: true as const,
           });
           if (isAgentRecipient(info)) this.broadcastToMemberships({ type: "session_joined", session: info }, sessionGroups(info), id);
           // #3761: messages written to this recipient's previous connection that it never confirmed saving go out again.
@@ -1636,25 +1636,18 @@ class IntercomBroker {
 		if (requester === undefined) throw new Error("Session not found");
 		const requestId = clientMessage.requestId;
 		const selectedGroup = clientMessage.group;
-		const visible = (sessions: ReadonlyMap<string, Pick<ConnectedSession, "info">>): SessionInfo[] =>
-			typeof selectedGroup === "string"
-				? this.canInspectSelectedGroup(requester, selectedGroup)
-					? sessionsInGroup(sessions, selectedGroup)
-					: []
-				: sessionsVisibleTo(sessions, requester.info);
-		const respond = (sessions: SessionInfo[]): void => {
-			writeMessageIfOpen(socket, {
-				type: "sessions",
-				requestId,
-				sessions,
-				workflowStages: this.workflowStagesVisibleTo(requester, selectedGroup),
-				workflowFutureStages: this.workflowFutureStagesVisibleTo(requester, selectedGroup),
-			});
-		};
 		const multiNode = this.multiNode;
-		if (multiNode === undefined) respond(visible(this.sessions));
-		// Multi-node S5: a session connected through another node is a live peer too, under the same visibility.
-		else void multiNode.remoteSessions().then((remote) => respond([...visible(this.sessions), ...visible(remote)]));
+		replyToList({
+			requestId,
+			requesterInfo: requester.info,
+			selectedGroup,
+			localSessions: () => this.sessions,
+			remoteSessions: multiNode === undefined ? undefined : () => multiNode.remoteSessions(),
+			canInspectSelectedGroup: (group) => this.canInspectSelectedGroup(requester, group),
+			workflowStages: () => this.workflowStagesVisibleTo(requester, selectedGroup),
+			workflowFutureStages: () => this.workflowFutureStagesVisibleTo(requester, selectedGroup),
+			write: (reply) => writeMessageIfOpen(socket, reply),
+		});
         break;
       }
 
@@ -1772,10 +1765,18 @@ class IntercomBroker {
           !clientMessage.runId ||
           typeof clientMessage.group !== "string" ||
           typeof clientMessage.capability !== "string" ||
-          !clientMessage.capability
+          !clientMessage.capability ||
+          (clientMessage.requestId !== undefined && typeof clientMessage.requestId !== "string")
         ) {
           throw new Error("Invalid pending-stage route registration");
         }
+        const routeRequestId = clientMessage.requestId;
+        // The route is applied synchronously, so this answer proves the update is visible to every later request.
+        const acknowledgeRoute = (): void => {
+          if (routeRequestId !== undefined) {
+            writeMessageIfOpen(socket, { type: "pending_stage_route_registered", requestId: routeRequestId });
+          }
+        };
         const owner = this.sessions.get(currentId);
         const existing = this.pendingStageRoutes.get(clientMessage.runId);
         const ownerGroup = normalizeGroup(owner?.registrationGroup);
@@ -1854,6 +1855,7 @@ class IntercomBroker {
             });
             this.retireAmbiguousNameAliases(clientMessage.runId);
           }
+          acknowledgeRoute();
           break;
         }
         this.pendingStageRoutes.set(clientMessage.runId, {
@@ -1877,6 +1879,7 @@ class IntercomBroker {
           });
           this.retireAmbiguousNameAliases(clientMessage.runId);
         }
+        acknowledgeRoute();
         break;
       }
 

package/dist/builtin/intercom/broker/client.ts

@@ -20,11 +20,15 @@ import { buildSendSignature, PendingSendRegistry } from "./pending-send-registry
 import { readSubagentMessageSource } from "../source-ownership.js";
 import { isMessage, isSessionInfo } from "./client-message-validation.js";
 import { normalizeGroups } from "../group.js";
-import { IntercomClientDisconnectedError } from "../recoverable-disconnect.js";
+import { IntercomBrokerTimeoutError, IntercomClientDisconnectedError } from "../recoverable-disconnect.js";
 import { IntercomLiveRouteRefusedError, isLiveWorkflowStageRouteRefusalCode } from "../live-route-refusal.js";
 import { SEND_RESPONSE_TIMEOUT_MS } from "../retry-policy.js";
 
 const BROKER_SOCKET = getBrokerSocketPath();
+/** How long `connect()` waits for the broker to answer `register`. */
+export const BROKER_CONNECT_TIMEOUT_MS = 10_000;
+/** How long an acknowledged pending-stage route registration waits for the broker's answer. */
+export const PENDING_STAGE_ROUTE_ACK_TIMEOUT_MS = 10_000;
 const GROUP_REQUEST_TIMEOUT_MS = 5000;
 const PRESENCE_ACK_TIMEOUT_MS = 5000;
 const RESTORING_RECIPIENT_REQUEST_TIMEOUT_MS = 5000;
@@ -53,6 +57,8 @@ export interface IntercomClientOptions {
 	readonly preferredSessionId?: string;
 	/** #3761: this client confirms each received message with `acknowledgeReceived` once it has saved it. */
 	readonly acknowledgesReceipt?: true;
+	/** Registration answer bound for `connect()`; defaults to `BROKER_CONNECT_TIMEOUT_MS`. */
+	readonly connectTimeoutMs?: number;
 }
 
 export interface SendResult {
@@ -164,8 +170,11 @@ export class IntercomClient extends EventEmitter {
 	private readonly returnAddress: string;
 	private readonly preferredSessionId: string | undefined;
 	private readonly acknowledgesReceipt: boolean;
+	private readonly connectTimeoutMs: number;
 	/** #3761: the broker of the current registration echoed `acknowledgesReceipt`, so it understands `received`. */
 	private brokerAcknowledgesReceipt = false;
+	/** The broker of the current registration answers a pending-stage route registration that carries a `requestId`. */
+	private brokerAcknowledgesPendingStageRoutes = false;
   private socket: net.Socket | null = null;
   private _sessionId: string | null = null;
   private _supervisorSessionId: string | null = null;
@@ -183,6 +192,7 @@ export class IntercomClient extends EventEmitter {
   private pendingMemberships = new Map<string, { resolve: (groups: string[]) => void; reject: (error: Error) => void }>();
   private _groups = normalizeGroups();
   private pendingLiveWorkflowStageRoutes = new Map<string, { resolve(): void; reject(error: Error): void }>();
+  private pendingStageRouteRegistrations = new Map<string, { resolve(): void; reject(error: Error): void }>();
 
   private pendingSupervisorAuthorizations = new Map<string, {
     resolve: (authorization: SupervisorAuthorization) => void;
@@ -198,6 +208,7 @@ export class IntercomClient extends EventEmitter {
 		this.returnAddress = returnAddress;
 		this.preferredSessionId = options.preferredSessionId;
 		this.acknowledgesReceipt = options.acknowledgesReceipt === true;
+		this.connectTimeoutMs = options.connectTimeoutMs ?? BROKER_CONNECT_TIMEOUT_MS;
 	}
 
   private failPending(error: Error): void {
@@ -209,6 +220,7 @@ export class IntercomClient extends EventEmitter {
     for (const pending of this.pendingPresence.values()) pending.reject(error);
     for (const pending of this.pendingMemberships.values()) pending.reject(error);
     for (const pending of this.pendingLiveWorkflowStageRoutes.values()) pending.reject(error);
+    for (const pending of this.pendingStageRouteRegistrations.values()) pending.reject(error);
     this.pendingLists.clear();
     this.pendingGroupLists.clear();
     this.pendingSupervisorAuthorizations.clear();
@@ -216,6 +228,7 @@ export class IntercomClient extends EventEmitter {
     this.pendingPresence.clear();
     this.pendingMemberships.clear();
     this.pendingLiveWorkflowStageRoutes.clear();
+    this.pendingStageRouteRegistrations.clear();
   }
 
 
@@ -279,9 +292,9 @@ export class IntercomClient extends EventEmitter {
             this.socket = null;
           }
           socket.destroy();
-          reject(new Error("Connection timeout"));
+          reject(new IntercomBrokerTimeoutError("Connection timeout"));
         }
-      }, 10000);
+      }, this.connectTimeoutMs);
       
       let connectionEstablished = false;
       
@@ -318,6 +331,7 @@ export class IntercomClient extends EventEmitter {
         this._sessionId = null;
         this._supervisorSessionId = null;
         this.brokerAcknowledgesReceipt = false;
+        this.brokerAcknowledgesPendingStageRoutes = false;
         this._messageSource = undefined;
         this.disconnectError = null;
         if (connectionEstablished && !wasDisconnecting) {
@@ -425,7 +439,8 @@ export class IntercomClient extends EventEmitter {
       case "registered": {
         if (typeof brokerMessage.sessionId !== "string"
           || (brokerMessage.supervisorSessionId !== undefined && typeof brokerMessage.supervisorSessionId !== "string")
-          || (brokerMessage.acknowledgesReceipt !== undefined && brokerMessage.acknowledgesReceipt !== true)) {
+          || (brokerMessage.acknowledgesReceipt !== undefined && brokerMessage.acknowledgesReceipt !== true)
+          || (brokerMessage.acknowledgesPendingStageRoutes !== undefined && brokerMessage.acknowledgesPendingStageRoutes !== true)) {
           throw new Error("Invalid registered message");
         }
 
@@ -438,6 +453,7 @@ export class IntercomClient extends EventEmitter {
           : null;
         // #3761: a broker from before receipts never echoes the capability and drops a client that sends `received`.
         this.brokerAcknowledgesReceipt = this.acknowledgesReceipt && brokerMessage.acknowledgesReceipt === true;
+        this.brokerAcknowledgesPendingStageRoutes = brokerMessage.acknowledgesPendingStageRoutes === true;
         this.emit("_registered", { type: "registered", sessionId: brokerMessage.sessionId });
         break;
       }
@@ -480,13 +496,14 @@ export class IntercomClient extends EventEmitter {
         break;
       }
       case "sessions": {
-		const { requestId, sessions, workflowStages, workflowFutureStages } = brokerMessage;
+		const { requestId, sessions, workflowStages, workflowFutureStages, restricted } = brokerMessage;
 		if (
 			typeof requestId !== "string" ||
 			!Array.isArray(sessions) ||
 			!sessions.every(isSessionInfo) ||
 			(workflowStages !== undefined && !isWorkflowStageRosterEntries(workflowStages)) ||
-			(workflowFutureStages !== undefined && !isWorkflowFutureStageRosterEntries(workflowFutureStages))
+			(workflowFutureStages !== undefined && !isWorkflowFutureStageRosterEntries(workflowFutureStages)) ||
+			(restricted !== undefined && restricted !== true)
 		) {
 			throw new Error("Invalid sessions message");
 		}
@@ -497,6 +514,7 @@ export class IntercomClient extends EventEmitter {
 			sessions,
 			workflowStages: workflowStages ?? [],
 			workflowFutureStages: workflowFutureStages ?? [],
+			...(restricted === true ? { restricted: true as const } : {}),
 		});
 		break;
 	  }
@@ -604,6 +622,15 @@ export class IntercomClient extends EventEmitter {
 			this.emit("pending_stage_route_revoked", { runId });
 			break;
 		}
+      case "pending_stage_route_registered": {
+        const { requestId } = brokerMessage;
+        if (typeof requestId !== "string") throw new Error("Invalid pending-stage route registration acknowledgement");
+        const pending = this.pendingStageRouteRegistrations.get(requestId);
+        if (!pending) return;
+        this.pendingStageRouteRegistrations.delete(requestId);
+        pending.resolve();
+        break;
+      }
       case "live_workflow_stage_route_registered": {
         const { requestId } = brokerMessage;
         if (typeof requestId !== "string") throw new Error("Invalid live workflow-stage route registration");
@@ -1029,6 +1056,70 @@ export class IntercomClient extends EventEmitter {
 	});
   }
 
+	/**
+	 * Register a pending-stage route and settle once the broker has applied it, so a request on any other
+	 * socket observes the update. A broker that does not advertise the answer is covered by a session listing
+	 * on this socket, which that broker only answers after the registration ahead of it.
+	 */
+	registerPendingStageRouteAcknowledged(
+		runId: string,
+		group: string,
+		capability: string,
+		stages?: WorkflowStageRosterAnnouncement[],
+		possibleStages?: WorkflowPossibleStageAnnouncement[],
+		parent?: WorkflowRunParentAnnouncement,
+		dormant?: boolean,
+	): Promise<void> {
+		let socket: net.Socket;
+		try {
+			socket = this.requireActiveSocket();
+		} catch (error) {
+			return Promise.reject(toError(error));
+		}
+		if (!this.brokerAcknowledgesPendingStageRoutes) {
+			try {
+				this.registerPendingStageRoute(runId, group, capability, stages, possibleStages, parent, dormant);
+			} catch (error) {
+				return Promise.reject(toError(error));
+			}
+			return this.listSessions().then(() => undefined);
+		}
+		return new Promise((resolve, reject) => {
+			const requestId = randomUUID();
+			const timeout = setTimeout(() => {
+				if (!this.pendingStageRouteRegistrations.delete(requestId)) return;
+				reject(new IntercomBrokerTimeoutError("Pending-stage route registration timeout"));
+			}, PENDING_STAGE_ROUTE_ACK_TIMEOUT_MS);
+			this.pendingStageRouteRegistrations.set(requestId, {
+				resolve: () => {
+					clearTimeout(timeout);
+					resolve();
+				},
+				reject: (error) => {
+					clearTimeout(timeout);
+					reject(error);
+				},
+			});
+			try {
+				writeMessage(socket, {
+					type: "register_pending_stage_route",
+					requestId,
+					runId,
+					group,
+					capability,
+					stages,
+					possibleStages,
+					...(parent === undefined ? {} : { parent }),
+					...(dormant === true ? { dormant: true as const } : {}),
+				});
+			} catch (error) {
+				clearTimeout(timeout);
+				this.pendingStageRouteRegistrations.delete(requestId);
+				reject(toError(error));
+			}
+		});
+	}
+
   registerLiveWorkflowStageRoute(runId: string, stageKeys: readonly string[], capability: string): Promise<void> {
     let socket: net.Socket;
     try {

package/dist/builtin/intercom/broker/list-reply.ts

@@ -0,0 +1,53 @@
+import type { SessionInfo, WorkflowFutureStageRosterEntry, WorkflowStageRosterEntry } from "../types.js";
+import { sessionsInGroup, sessionsVisibleTo } from "./group-membership.js";
+
+type SessionDirectoryView = ReadonlyMap<string, { readonly info: SessionInfo }>;
+
+export interface SessionsReply {
+	readonly type: "sessions";
+	readonly requestId: string;
+	readonly sessions: SessionInfo[];
+	readonly workflowStages: WorkflowStageRosterEntry[];
+	readonly workflowFutureStages: WorkflowFutureStageRosterEntry[];
+	readonly restricted?: true;
+}
+
+export interface ListReplyRequest {
+	readonly requestId: string;
+	readonly requesterInfo: SessionInfo;
+	readonly selectedGroup: string | undefined;
+	readonly localSessions: () => SessionDirectoryView;
+	/** Present only in multi-node mode; sessions connected through other nodes are live peers too. */
+	readonly remoteSessions: (() => Promise<SessionDirectoryView>) | undefined;
+	readonly canInspectSelectedGroup: (selectedGroup: string) => boolean;
+	readonly workflowStages: () => WorkflowStageRosterEntry[];
+	readonly workflowFutureStages: () => WorkflowFutureStageRosterEntry[];
+	readonly write: (reply: SessionsReply) => void;
+}
+
+/**
+ * The restriction is decided when the reply is built, after any remote read, so a group joined while that read was
+ * pending is honoured and the message, rows and `restricted` flag always describe the same decision.
+ */
+export function replyToList(request: ListReplyRequest): void {
+	const respond = (remote: SessionDirectoryView | undefined): void => {
+		const { selectedGroup } = request;
+		const restricted = selectedGroup !== undefined && !request.canInspectSelectedGroup(selectedGroup);
+		const visible = (sessions: SessionDirectoryView): SessionInfo[] =>
+			restricted
+				? []
+				: selectedGroup !== undefined
+					? sessionsInGroup(sessions, selectedGroup)
+					: sessionsVisibleTo(sessions, request.requesterInfo);
+		request.write({
+			type: "sessions",
+			requestId: request.requestId,
+			sessions: [...visible(request.localSessions()), ...(remote === undefined ? [] : visible(remote))],
+			workflowStages: restricted ? [] : request.workflowStages(),
+			workflowFutureStages: restricted ? [] : request.workflowFutureStages(),
+			...(restricted ? { restricted: true as const } : {}),
+		});
+	};
+	if (request.remoteSessions === undefined) respond(undefined);
+	else void request.remoteSessions().then(respond);
+}