@bastani/atomic 0.9.9-alpha.4 → 0.9.10-alpha.1

package/CHANGELOG.md

@@ -2,6 +2,105 @@
 
 ## [Unreleased]
 
+## [0.9.10-alpha.1] - 2026-07-19
+
+### Breaking Changes
+
+- The bundled `workflow` tool no longer accepts direct one-off `task`, `tasks`, or `chain` shapes (or their direct-only top-level options), and the bundled workflow SDK no longer exports `runTask`, `runParallel`, or `runChain`. Launch named workflows with `workflow` + `inputs`, and author custom definitions with the unchanged `ctx.task`, `ctx.chain`, and `ctx.parallel` primitives.
+- Bundled workflow durability now requires DBOS/Postgres and no longer provides local JSON/SQLite persistence, runtime opt-out/backend selection, session-transcript discovery, or conversion of prior durable data.
+- Added a host-native session picker capability, `ctx.ui.hostSessionPicker(request)`, implemented first-class by every interactive host with one identical API: non-isolated interactive mode mounts the real built-in session selector directly in the terminal process (no IPC), and the isolated interactive engine routes the same capability over a new engine session-picker protocol channel (`engine_session_picker_open/update/error/close` messages and `engine_session_picker_select/cancel/delete` commands). The extension ships JSON-safe rows (`HostSessionPickerRow` — `SessionInfo` with `createdAt`/`modifiedAt` epoch millis) and only semantic events ever cross a process boundary; arrow-key navigation and search are zero-IPC and stay responsive even while the extension's event loop is busy, unlike remote-rendered `ctx.ui.custom()` components, which pay one round trip per keypress. Deletion is extension-owned: the host keeps the row until the extension replies with an update (row removed) or an error. Pickers are disposed cleanly on extension-initiated close and on engine crash/restart. The bundled `/workflow resume` picker now REQUIRES this capability — its remote-rendered `ctx.ui.custom()` selector path was removed with no fallback, and hosts without the capability fail the resume command with one actionable error. The member is absent only on non-interactive surfaces (headless RPC, print). See `docs/tui.md` and `docs/extensions.md`.
+
+### Added
+
+- Added private compaction-planner diagnostic sidecars for failed persisted-session planner calls. Malformed output, unusable ranges, provider errors, and stream failures now save the full response text plus stop reason, usage, request output budget, and non-secret model metadata beside the session JSONL with `0600` permissions where supported; the compaction error reports that path. Credentials, headers, and request prompts are excluded, while in-memory sessions and sidecar write failures preserve the original `RangePlanError` unchanged.
+- Replaced the compaction planner output format from JSON `{"d":[[start,end],...]}` with bare `start,end` records (one per line, no brackets/fences/prose). The new format is ~1% more token-efficient at equivalent range counts and enables trivial newline-based length-truncation recovery.
+- Added silent recovery of complete deletion records from length-truncated compaction planner responses. When the model output is cut by `max_tokens` (`stopReason: "length"`), a deterministic line parser recovers newline-terminated `start,end` records, discards the final unterminated fragment (never guesses multi-digit integers), and passes results through normal validation. Recovery is silent: no warning, banner, or special status—UI shows the normal `✻ Context compacted` message. A private `0600` recovery-diagnostic sidecar is written beside persisted sessions for operational observability (never surfaced in UI). The planner prompt now instructs the model to emit ranges in descending deletion confidence so the highest-priority deletions survive truncation.
+- Added six bundled, composable pattern workflow definitions — `classify-and-act`, `fan-out-and-synthesize`, `adversarial-verification`, `generate-and-filter`, `tournament`, and `loop-until-done` — with typed/defaulted inputs, dedicated artifact-aware stage prompts, declared outputs, named discovery, and `@bastani/workflows/builtin` exports for nested `ctx.workflow(...)` composition.
+- Added `ctx.ui.hostInputForm(request)`, a JSON-safe host-native structured-form capability implemented identically by isolated and non-isolated interactive hosts. The terminal host owns inline rendering, focus, validation, configured keybindings, and editing state; under engine isolation only open and submit/cancel semantic events cross the protocol boundary. Headless RPC and print surfaces omit the optional member.
+- Added `/workflows [run-id]` as a retained workflow-run alias for `/workflow resume`, with confirmed backend-aware deletion for inactive durable/completed rows that protects in-flight runs and preserves independent session transcripts.
+- Added supervised interactive-engine isolation: extension tools, hooks, commands, workflow code, and custom UI rendering now run in a child process so a synchronous busy loop cannot freeze terminal input, spinners, or rendering. A 50 ms heartbeat watchdog identifies blocked callbacks after 250 ms, exposes interrupt/termination guidance after one second, and reports terminated results as unknown without automatic retry. JSON-safe `ctx.ui.custom()` components are remotely rendered with asynchronous input forwarding; unsupported synchronous host callback APIs warn instead of falling back in-process.
+- Added a typed, allowlisted host-terminal control channel for isolated `ctx.ui.custom()` components. An overlay factory's `tui.terminal` now exposes `setMouseScrollTracking(enabled)` and `setAutowrap(enabled)` setters that the terminal host applies to the real host TTY over the engine protocol — the engine child (whose stdout is the JSONL transport, not a TTY) can enable SGR mouse-scroll reporting and Windows autowrap without ever forwarding raw child bytes to the terminal. Controls are component/generation scoped and every enabled mode is reset when the overlay hides, closes, is disposed, or the engine child crashes/restarts. See `docs/tui.md`.
+- Added live-updating, semantically colored rows to the bundled `/workflow resume` picker: completed rows render green, paused yellow, and failed/blocked/crashed red (`SessionInfo.messageColor` now also accepts `"error"`). Rows re-list on run-store changes and a bounded cross-session poll while the picker is open, and running workflows are never offered as resume targets — a fresh-heartbeat running row is hidden from every session, and only stale (crashed) ones surface, labeled `crashed`.
+- Added `atomic update --models` to force-refresh authenticated dynamic provider catalogs with bounded, provider-scoped persistence and actionable failures ([#1875](https://github.com/bastani-inc/atomic/issues/1875)).
+
+### Changed
+
+- Promoted the DBOS SDK and `embedded-postgres` to mandatory dependencies. Atomic configures and launches DBOS lazily on the first workflow action, awaits readiness before every workflow lifecycle path, and surfaces initialization or persistence failures for that action instead of continuing on another backend. Without `DBOS_SYSTEM_DATABASE_URL`, workflow durability runs on an embedded Postgres from npm-distributed binaries (detached daemon under `~/.atomic/postgres`, shared across sessions; Docker `dbos-db` container only as a platform fallback). Concurrent Atomic sessions sharing one database use per-process executor identities, owner/heartbeat metadata, and first-writer-wins resume claims so one session's live workflow cannot be double-dispatched from another.
+- Documented and enforced `/resume`-equivalent workflow-history retention: eligible runs are not filtered or garbage-collected by age/count, and the selector viewport does not limit search/navigation.
+- Kept the interactive-engine watchdog's early 250 ms blocking signal internal instead of rendering repetitive "has not yielded" warnings during ordinary slow extension/tool loading. One-second unresponsive heartbeat-watchdog diagnostics are likewise always kept internal, whether or not they attribute a callback (for example, `extension.hook tool_execution_end`); the isolated host remains responsive and still provides Escape/Ctrl+C recovery controls. Concrete engine failures such as termination and RPC errors continue to surface as chat errors.
+- Changed verbatim compaction to classify the complete active transcript except for exactly the newest `preserve_recent` context-visible messages (default `2`). The protected tail is no longer widened to a user-turn boundary, `preserve_recent: 0` now retains no ordinary message, and repeated compaction includes the prior durable verbatim summary while preserving resumable session boundaries.
+- Redesigned the `/workflow <name>` input form (shown when a named workflow is launched with required inputs missing). The form now renders inside a rounded, theme-aware panel titled `WORKFLOW INPUTS` with the workflow name and field count, matching the workflow catalogue's visual language: each field shows a focus chevron, an accent field name when active, and a right-aligned `required`/`optional` badge (required in the warning color); descriptions use the readable muted tone, validation errors render as a `✗ reason` row, the submit control is a `[ Run workflow ]` button pill (filled accent when focused), and the footer uses accent key chips. Multi-line text inputs blend their inset rules into the panel border, the panel scales to the full terminal width like the other chat surfaces, and the embedded editor cursor stays correctly positioned.
+- Migrated model authentication and refresh to Pi's provider-owned APIs while preserving Atomic's public `AuthStorage`, `ModelRegistry`, SDK options, legacy extension OAuth registration, complete request headers, and credential-specific enterprise endpoints. The model picker now shows cached models immediately and reports concise success, partial-error, and timeout status ([#1875](https://github.com/bastani-inc/atomic/issues/1875)).
+
+### Fixed
+
+- Fixed the repository `publish-release` workflow to reconcile an exact release PR merged externally while required checks are pending. It preserves identity/refs/SHA; correlates workflow-qualified Actions reruns by name plus workflow; and supports empty-workflow `StatusContext` and GitHub App `CheckRun` evidence. Linked reruns group by inferred kind/name across URL changes; linkless rows inspect both external kinds, accept all-passing candidates, block any pending/failure, and exclude nonempty-workflow Actions. Duplicate aliases reuse exact passing evidence. It rechecks after merge and validates merge/branch evidence. Tag recovery proves `verified merge → tag parent → current base`; exhaustive history avoids GitHub's 1,000-result ceiling; protected coordination retains its lock through ambiguous dispatch visibility; and recovered success requires exact-SHA integrity evidence.
+- Fixed shared extension chat compaction rendering so manual, threshold, and overflow compaction use the animated working spinner with reason-aware copy instead of a duplicate plain status row plus generic `Working...`; successful compaction now falls back to the existing typed `✻ Context compacted` message when a refreshed live session snapshot is unavailable, while preserving durable session reconstruction and avoiding duplicate boundaries.
+- Fixed workflow stage-chat `/compact` cancellation and planner/provider failures from escaping their fire-and-forget editor submission promise and terminating the CLI. The authoritative `compaction_end` event now owns the visible status, animation cleanup, and diagnostic path while the same stage remains usable for retry or follow-up.
+- Fixed OpenAI Responses, Codex Responses, and OpenAI Completions context accounting to sum their normalized uncached and cached input partitions even when the values are nearly equal. Anthropic Messages retains its mirrored-cache guard, preventing missed auto-compaction thresholds, understated footer usage, and negative persisted reduction percentages on Codex sessions.
+- Fixed workflow-stage message admission races by adding a linearizable AgentSession generation boundary. Intercom traffic and async bash/subagent completions received before close now use native queued steering/follow-up delivery and drain before terminal stage publication; close-winning detached results route once to the main chat without reopening or mutating the completed stage. Detached producers remain non-blocking, stable producer identities prevent duplicate delivery, and explicit `StageContext.sendUserMessage` plus post-mortem stage chat remain available.
+- Fixed asynchronous extension custom-message admission to return its delivery promise through `pi.sendMessage()` and `pi.sendMessages()`, allowing workflow late-message routers to propagate main-chat failures and release stable producer keys for retry instead of treating rejected routes as successful.
+- Fixed bundled workflow stages freezing when an active foreground subagent used Intercom or blocking `contact_supervisor`. Busy stages give the exact child owner's acknowledged detach handshake first refusal before model-visible stage-session queue insertion; owner loss between probe/commit falls back instead of dropping the broker message. In parallel foreground groups, one accepted commit releases aggregate supervision for all active siblings while their child processes and eventual result/status recovery remain owned; run-owned worktrees are retained until every detached child closes and their diffs are captured.
+- Fixed bundled workflow-stage `intercom.ask` delivery when the target sibling is mid-turn in an in-flight tool call. The open generation now owns the ask before asynchronous foreground-owner coordination begins, waits for its native queue insertion, and drains it before terminal publication; genuinely failed destination admission returns a correlated actionable error rather than consuming the full reply timeout.
+- Fixed `/workflow <name>` input forms becoming non-responsive under interactive-engine isolation. The RPC extension surface advertised `setEditorComponent` as a callable compatibility stub even though it could not install a host editor, so the workflow command waited on an editor that was never mounted while Tab and Escape stayed routed to the ordinary prompt. Named workflow forms now prefer the host-native input-form channel, keeping Tab/Shift+Tab, arrows, editing, configured keybindings, Enter, Escape, and Ctrl+C local and responsive in both interactive modes; cancellation does not dispatch the workflow, inline bottom-editor geometry is preserved, and legacy custom-editor/`ctx.ui.custom()` fallbacks remain available for older hosts.
+- Fixed Ctrl+O (`app.tools.expand`) being consumed without expanding tool and workflow-node detail in attached workflow stage chats under interactive-engine isolation. The child RPC UI facade retains one expansion state shared by its getter and chat render settings, and the remote custom-UI bridge now filters Kitty key-release events unless the child component explicitly opts into them, preventing one physical Ctrl+O press from immediately toggling expansion back off. Repeated expand/collapse toggles match main chat across active and completed runs, single/parallel/chain views, and narrow terminals without changing prompt, custom-UI, or unrelated key ownership.
+- Fixed bundled workflow-stage `intercom.ask` calls hanging when the addressed sibling stage had already completed. Atomic now schedules a post-mortem turn in the completed target's retained conversation, preserves the exact child-to-child reply thread, prevents parent or unrelated sessions from satisfying it, and returns bounded actionable errors for unavailable or non-resumable retained targets. Production workflow and Intercom late-message listeners preserve the first owner's completion promise regardless of registration order, so later or duplicate listeners cannot turn revival failures into silent no-ops ([#1854](https://github.com/bastani-inc/atomic/issues/1854)).
+- Fixed tool results being able to push the active Pi loop past Atomic's buffered compaction threshold before its next provider request. Atomic now performs one ordinary verbatim compaction preflight after tool results enter the prospective next-turn context, returns the rebuilt protocol-valid context to the same loop without scheduling `agent.continue()`, leaves below-threshold turns unchanged, surfaces compaction cancellation/failure, and blocks a follow-up request that remains known to exceed the provider hard input limit.
+- Fixed the interactive TUI dropping its working spinner after successful post-tool autocompaction while the same agent stream continued. The normal working indicator is now restored immediately at the mid-turn compaction boundary, without waiting for the user's next interaction.
+- Fixed bundled workflow stage messaging to distinguish idle sessions from active streams: idle `followUp`/eligible `auto` sends now start a real prompt and report `prompt`, streaming follow-ups queue and steering stays in-turn, paused idle-chat `resume(message)` starts exactly one recorded turn, and interrupted-turn resume, abort/exit guards, and at-most-once continuation behavior remain intact ([#1850](https://github.com/bastani-inc/atomic/issues/1850)).
+- Fixed Escape during isolated-engine compaction timing out with `Timeout waiting for response to abort_compaction`. RPC input now keeps ordinary commands FIFO while validated cancellation and host-response control frames use an independent lane, so `abort_compaction` reaches the active engine session before the pending `compact` request settles; duplicate and late aborts remain harmless, and ordinary command ordering is preserved.
+- Fixed interactive non-schema workflow stages treating typed/freeform `ask_user_question` chat answers as an invisible implicit “stay”. The conversational acknowledgement now completes first, then a real brokered readiness gate exposes `awaiting_input`/`inputRequest.kind: "readiness_gate"`; in that chat flow, Not ready permits another stage-chat turn and re-prompts, while Ready releases dependents. Structured-option behavior remains unchanged, and successful schema finalization stays terminal. ([#1849](https://github.com/bastani-inc/atomic/issues/1849))
+- Fixed the bundled workflow `BACKGROUND` panel's elapsed timer remaining at `0s` until the user switched to the orchestrator. Visible running cards now repaint their existing mounted component on exact one-second boundaries from workflow start, without panel navigation or widget remounting; paused timers remain frozen and ended cards retain their one-shot expiry lifecycle.
+- Fixed the interactive TUI crashing with `Rendered line N exceeds terminal width` (uncaught exception in pi-tui `doRender`) when the terminal was resized — most visibly when shrinking an active session with chat history (e.g. 112 → 83 columns) or fuzz-resizing mid-turn. Under the isolated interactive engine, tool cards and custom messages render out-of-process and asynchronously: after a resize they kept replaying the previous frame wrapped for the old width until the engine child delivered a re-wrapped one, so pi-tui's differential renderer could see lines wider than the terminal and abort the whole session. Remote frames are now defensively clamped to the current render width while the engine catches up, so grow/shrink resizing (including rapid adversarial flapping) never emits an overflowing line; properly re-wrapped frames still replace the clamped ones as soon as they arrive.
+- Fixed the startup banner logo wrapping and shredding into misaligned art on narrow terminals: the identity header is now width-aware, keeping the side-by-side logo/meta layout only when every combined row fits, stacking the identity text (version, provider/model, cwd) under the logo when the meta column would wrap, and dropping the logo art entirely when the terminal is narrower than the logo itself. The layout re-adapts on every terminal resize.
+- Fixed adjacent assistant thinking blocks rendering as separate sections, Windows package checks leaving npm's terminal title behind, standalone Bun binaries omitting interactive OAuth adapters, and clone/fork attempts before the first assistant response returning an unhelpful failure ([#1875](https://github.com/bastani-inc/atomic/issues/1875)).
+- Stopped the isolated interactive engine's extension-level `requestRender()` from invalidating hidden remote overlay components ([#1856](https://github.com/bastani-inc/atomic/issues/1856)). The broadcast now skips components whose remote OverlayHandle is hidden (`setHidden(true)`/`hide()`), so widget-local updates do not trigger host render work for hidden graph/stage frames; shown-again components rejoin the broadcast immediately.
+- Reduced keypress latency for all remotely rendered extension custom UI (workflow inputs forms, graph overlays, and other `ctx.ui.custom()` components) under the isolated interactive engine. The host now pipelines a fresh frame request directly behind every forwarded keypress — engine commands are delivered in order, so the returned frame always reflects the applied input. This cuts the previous input → child-invalidate → render-request → frame path to a single round trip and repaints components that change state on input without self-invalidating.
+- Fixed the mouse wheel scrolling native/main-chat scrollback instead of the workflow graph when a durable workflow overlay was resumed under the isolated interactive engine. The overlay adapter runs inside the engine child, whose stdout is the JSONL transport rather than a TTY, so its `process.stdout` mouse-tracking escape sequences never put the real host terminal into mouse-reporting mode. The overlay now enables host mouse-scroll reporting (and Windows autowrap) through the new typed host-terminal control channel, so wheel gestures reach the remote `GraphView` and change graph scroll offsets while a visible overlay captures the mouse; keyboard navigation, stage-chat wheel capture, and Ctrl+T copy mode are unchanged. Resume selection deterministically disposes the inline picker before the fullscreen overlay mounts and takes focus, so a late picker cleanup can no longer steal focus or leave the graph as an inline/bottom component. Non-isolated hosts keep their local `process.stdout` behavior.
+- Fixed `/resume` and `/workflow resume` intermittently failing with `Timeout waiting for response to prompt` when the picker (or any long-lived interactive prompt) stayed open past 30 seconds. The isolated-engine RPC client now exempts long-lived interactive commands — prompts and custom-UI pickers, queued `steer`/`follow-up` sends, long shell and compaction work, `fork`/`clone`, session `switch`/`new`/`import`, tree navigation, and shortcut invocation — from the generic 30-second request deadline. Process exit, transport violations, abort, and generation replacement still reject pending requests immediately, and bounded metadata/control requests keep a (now injectable) deadline, so real failure detection is unchanged.
+- Made the `/resume` session selector mount and paint its header, search, and loading state on the very first frame, then discover and parse sessions off the host UI loop. Directory scans run in bounded cooperative batches and a single very large transcript is parsed in yielding chunks, so input, search, and cancel stay responsive and one large session can no longer visibly freeze the picker. Closing the selector now cancels in-flight loads and ignores stale results, preventing late list updates after close, scope switch, or a newer load.
+- Fixed a startup input race where typing a command-like draft such as a bare `/` before the header finished loading was reclassified as a submitted cooked-mode command and sent automatically. Raw startup capture now remains authoritative: only Enter-terminated submissions replay, while unfinished slash/bash drafts stay in the editor.
+- Fixed startup changelog and first-run onboarding notices being gated behind the deferred extension reload — and, when a prompt was typed immediately at launch, behind the entire first agent turn. They now render right after the input handler is ready (milliseconds after first paint), matching pi's behavior; the RESOURCES disclosure still waits for the actual extension load it reports on.
+- Reduced deferred extension-load stalls by yielding to the event loop between extension loads only when the current turn has actually run long (≥16 ms) instead of unconditionally — the previous unconditional yields cost a full macrotask turn (~100 ms each while the TUI is live) per bundled extension (~0.5 s of the deferred load).
+- Hardened the isolated interactive engine's runtime and transport. Best-effort RPC rejections are now centrally contained so a fire-and-forget path can no longer crash the host; Escape/cancel recovery is generation-fenced so a cancelled turn survives, the host stays alive, and the engine child is cleanly restarted. The child is the sole authoritative writer of transcript/settings state (host snapshots are side-effect-free, and model/thinking/name operations persist exactly once), and a guardian tracks the full process tree so forced host death leaves no orphaned engine or detached grandchild.
+- Hardened the interactive-engine JSONL transport against unbounded growth and frame loss. Framing is UTF-8 byte-bounded (not UTF-16 char counts), writers in both directions are byte-accounted with backpressure, update coalescing happens before serialization, and terminal/correlated frames are either delivered or fail immediately with an explicit protocol error and same-id rejection instead of a 30-second timeout.
+- Fixed the isolated interactive engine omitting extension slash commands (`/workflow`, its `/workflows` alias, `/run`, `/mcp`, and others) from autocomplete. Because the host session loads no extensions in the interactive-engine child model, those commands live only in the engine child; the host now fetches the child's command catalog asynchronously after engine bind (never delaying first paint or input), merges it into autocomplete with built-in names reserved and locally-present prompts/skills deduped, and re-fetches after engine restart, reload, and new/resume/fork. Command execution continues to route through the child with no duplicate host handling.
+- Fixed expandable skill, resource, built-in tool, MCP, and subagent headers losing their effective keybinding in the isolated interactive engine (for example, `[skill] tmux ( Expand)`). Child rendering and injected custom UI now share one reloadable Atomic keybinding manager, so the default displays `ctrl+o`, remaps display the configured key, and intentionally unbound expansion omits the unavailable shortcut affordance without malformed punctuation.
+- Fixed the TUI flickering with rapid full repaints (~58 Hz, plus idle CPU burn on both processes) whenever a tool card rendered under the isolated interactive engine during a streaming turn — most visibly when the `workflow` tool's `quit`/`pause` action ran while a workflow stage was streaming, though any tool call (e.g. a plain `bash` echo) reproduced it. The engine child's remote tool-card renderer disposed and recreated the `ToolExecutionComponent` on every `engine_tool_render` request, and re-seeding the fresh component unconditionally scheduled a render on its off-screen TUI whose terminal write emitted `engine_custom_invalidate` back to the host, which marked the card dirty and re-sent the render request — forever. The engine render service now reuses the cached component per remote component id (applying args/result/expansion/image-option updates in place) and the seeding setters (`markExecutionStarted`/`setArgsComplete`) are idempotent, so the loop converges after at most one invalidate round trip while legitimate async invalidations (such as image format conversion) still repaint.
+
+## [0.9.9] - 2026-07-15
+
+### Breaking Changes
+
+- Replaced deletion-target context compaction with durable verbatim line compaction. Legacy `context_compaction` entries are now inert archival records, so content they previously hid may re-enter context when old sessions resume; start a new conversation or compact again to establish a new boundary.
+- Removed the deprecated `contextCompact()` SDK method, `context_compact` RPC command, and `context_compaction_start`/`context_compaction_end` events. Use `compact()` and `compaction_start`/`compaction_end`.
+- Changed extension compaction hooks: `session_before_compact` now accepts `cancel` or a complete non-empty `compactedText` override instead of `deletionRequest`; `session_compact` exposes `VerbatimCompactionResult` and the saved `compactionEntry`.
+
+### Added
+
+- Added one-pass contextual line-ranking compaction: Atomic asks the active session model at its active reasoning level, through the normal session stream/provider wrapper, for one whole-region compact `{"d":[[start,end],...]}` deletion plan, then safety-normalizes ranges and mechanically reconstructs verbatim text with cumulative `(filtered N lines)` markers.
+- Added strict pi-style compaction failure semantics: oversized prompts, provider/API errors or overflow, aborts, malformed JSON, and empty/unusable ranges fail without persistence or continuation and without semantic retries, chunking, critical replans, deterministic fallback, or deterministic target correction.
+- Added durable pi-style `CompactionEntry` boundaries discriminated by `details.strategy: "verbatim-lines"`, plus resumable custom-role boundary messages and a collapsible TUI card showing retained-line and token-reduction statistics.
+- Added `pi.sendMessages()` for atomic, array-ordered custom-message admission without waiting for the resulting model turn, allowing companion extensions to keep related preludes and terminal notices contiguous without globally serializing unrelated work.
+
+### Changed
+
+- Changed `compression_ratio` to explicitly represent the fraction of compactable lines to keep. `preserve_recent` is enforced client-side, widens the tail to a user-turn start, and always protects the final logical turn. Role headers are now ordinary ranked lines; only explicit protected spans are split out of model-selected deletion ranges.
+- Simplified resume reconstruction to load the persisted compacted string followed by original messages from `firstKeptEntryId`; no deletion filters, signed-thinking repair pass, or tool dependency repair is re-derived.
+- Retuned the one-pass compaction classifier's retention guidance to surgically thin long tool results, preserve compact diagnostic/code/state anchors, prune repeated retry and superseded bodies, and treat formatting, stack position, markers, and query matches as contextual rather than hard categories.
+- Updated the Pi runtime dependency set (`@earendil-works/pi-agent-core`, `pi-ai`, and `pi-tui`) from `^0.80.6` to `^0.80.7` across Atomic and its bundled packages, with matching Bun and npm lock metadata. This inherits the upstream provider authentication, session-affinity, reasoning replay, tool-choice, model-catalog, terminal input, and prompt-cache fixes from [Pi v0.80.7](https://github.com/earendil-works/pi/releases/tag/v0.80.7) while preserving versionless `0.0.0` workspace manifests.
+- Consolidated ten closed Dependabot updates into the Pi v0.80.7 branch: `linkedom` 0.18.13, npm `ignore` 7.0.6, `@typescript/native-preview` 7.0.0-dev.20260707.2, `typebox` 1.3.6, TypeScript 7.0.2, and the native dependency refreshes documented in `@bastani/atomic-natives`; regenerated the Bun, npm, and publish shrinkwrap dependency graphs without changing workspace package versions.
+- Added an Atomic `StringEnum` export that preserves Pi's Google-compatible enum schema while bridging Pi 0.80.7's TypeBox identity to the direct TypeBox 1.3.6 types; updated bundled extension examples and documentation to use the portable export, and updated TypeScript fixture configs for TypeScript 7's removal of `baseUrl`.
+
+### Fixed
+
+- Fixed resumed sessions resurrecting records hidden by earlier Verbatim Compaction entries after later compactions changed signed-thinking turn or tool-call/result dependencies. Persisted logical deletions are now an authoritative lower bound during every context rebuild: Atomic closes unsafe replay structures by adding transient omissions instead of restoring compacted calls/results, pairs each result with its concrete call occurrence so independent exchanges may reuse an opaque call ID, leaves unrelated retained history unchanged, and keeps the append-only session file intact.
+- Fixed successful manual and automatic compaction UI refreshes to render the compacted transcript with exactly one visible `✻ Context compacted` boundary, while aborted and failed compactions remain unchanged.
+- Fixed the bundled workflows `/workflow resume` experience to mix successful completed workflows into the existing globally newest-first, deduplicated picker with green completed styling, resolve full IDs and prefixes across live, durable, and completed targets, and reopen retained stage chats for follow-up without re-running workflow code or replaying side effects. Completed durable state is retained for authoritative inspection; rows need checkpoints and at least one strictly valid retained conversation, invalid per-stage transcript paths cannot open chat, repeated inspection refreshes changed authoritative chat handles, and selector mount failures close safely. ([#1532](https://github.com/bastani-inc/atomic/issues/1532))
+- Fixed workflow-owned transcripts leaking into normal `/resume`, `-r`, `-c`, and `--continue` history by requiring complete workflow ownership markers, persisting classification in initial fork headers, inheriting it across branches, and keeping malformed legacy markers and ordinary user forks visible.
+- Preserved accepted async-child Intercom chronology across lazily activated companion extensions by atomically admitting same-child ordinary messages before pause, completion, and failure notices; unrelated children remain independent and ask/reply behavior is unchanged ([#1802](https://github.com/bastani-inc/atomic/issues/1802)).
+- Fixed in-process workflow reload to atomically publish freshly rescanned project, user, legacy, configured, and package workflow resources across list/get/inputs/help/completion/invocation surfaces. Overlapping requests are serialized and coalesced, stale session generations cannot overwrite current state, fatal refresh failures retain the prior registry, and reload no longer blocks or changes workflows already in flight. `/workflow reload` and the workflow tool now include actionable per-resource diagnostics instead of reporting bare success when malformed or missing resources were skipped.
+
 ## [0.9.9-alpha.4] - 2026-07-15
 
 ### Fixed

package/README.md

@@ -388,6 +388,7 @@ atomic list
 atomic update                               # update Atomic only
 atomic update --all                         # update Atomic and packages
 atomic update --extensions                  # update packages only
+atomic update --models                      # force-refresh authenticated provider model catalogs
 atomic update --self                        # update Atomic only
 atomic update --self --force                # reinstall Atomic even if current
 atomic update npm:@foo/atomic-tools         # update one package
@@ -487,6 +488,7 @@ atomic uninstall <source> [-l]       # Alias for remove
 atomic update [source|self|atomic]   # Update Atomic only, or one package source
 atomic update --all                  # Update Atomic and packages
 atomic update --extensions           # Update packages only
+atomic update --models               # Force-refresh authenticated provider model catalogs
 atomic update --self                 # Update Atomic only
 atomic update --self --force         # Reinstall Atomic even if current
 atomic update --extension <src>      # Update one package

package/dist/builtin/cursor/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [Unreleased]
 
+## [0.9.10-alpha.1] - 2026-07-19
+
+### Changed
+
+- Published a synchronized Atomic 0.9.10-alpha.1 prerelease for the Cursor provider package; no functional Cursor provider changes were made after 0.9.9.
+
+## [0.9.9] - 2026-07-15
+
+### Changed
+
+- Published the stable Atomic 0.9.9 release for the Cursor provider package with its `@earendil-works/pi-ai` dependency aligned to `^0.80.7`; no functional Cursor provider source changes were made after 0.9.8.
+
 ## [0.9.9-alpha.4] - 2026-07-15
 
 ### Changed

package/dist/builtin/cursor/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/cursor",
-  "version": "0.9.9-alpha.4",
+  "version": "0.9.10-alpha.1",
   "private": true,
   "description": "Experimental first-party Atomic extension for Cursor OAuth, model discovery, and streaming provider registration.",
   "contributors": [
@@ -40,8 +40,8 @@
     }
   },
   "dependencies": {
-    "@bastani/atomic-natives": "0.9.9-alpha.4",
+    "@bastani/atomic-natives": "0.9.10-alpha.1",
     "@bufbuild/protobuf": "^2.12.1",
-    "@earendil-works/pi-ai": "^0.80.7"
+    "@earendil-works/pi-ai": "^0.80.10"
   }
 }

package/dist/builtin/intercom/CHANGELOG.md

@@ -4,6 +4,33 @@ All notable changes to the `pi-intercom` extension will be documented in this fi
 
 ## [Unreleased]
 
+## [0.9.10-alpha.1] - 2026-07-19
+
+### Added
+
+- Added intercom **groups** for broker-enforced session isolation. Every session belongs to exactly one group (implicitly `"default"` when unset), resolved with precedence `orchestrationContext.intercomGroup` (per-session workflow-stage injection) > env `ATOMIC_INTERCOM_GROUP` (legacy `PI_INTERCOM_GROUP`) > intercom `config.json` `"group"` > `"default"`. A session in group G can only message peers in G: cross-group sends are rejected at the broker (unresolvable by name via group-scoped candidate resolution, and rejected by an exact-id defense-in-depth check with reason "Target session is in a different intercom group"), not merely hidden from discovery. `session_joined`/`session_left`/`presence_update` broadcasts and `intercom list` are group-scoped, so a session never sees peers outside its group. The `intercom` tool gains an optional `group` parameter: read-only for `list`/`status` (peek who is in a named group and see your own group), while `send`/`ask` stay locked to your own group and error clearly on a differing group. The subagent-only `contact_supervisor` path uses a dedicated broker protocol plus a supervisor-issued child capability, and only an exact broker-recorded reverse reply may cross back, so isolated children retain their supervisor link without granting peer traffic a general bypass.
+
+### Fixed
+
+- Fixed busy workflow-stage messages being retained solely in Intercom's private wait-until-idle queue. Stage-targeted traffic is now admitted synchronously through the AgentSession generation boundary with stable message IDs, preserving native follow-up ordering and exactly-once delivery; close-winning late traffic is surfaced through the parent/main chat without mutating the terminal stage. Existing non-stage idle batching, terminal barriers, reply correlation, and shutdown generation cleanup are unchanged.
+- Fixed closed workflow-stage Intercom routing to avoid source-side pre-admission, reserve destination dedupe entries until main-chat delivery succeeds, roll back reply context on failure, propagate asynchronous route rejection, and permit a failed stable-key delivery to retry without duplicate parent-chat messages. A final retry survives source-stage retirement, and hosts without batch admission now commit successful fallback members individually so a partial failure retries only the undelivered suffix.
+- Fixed a cross-group isolation bypass where any registered raw client could forge `channel: "supervisor"` on an ordinary `send` frame. Ordinary sends now reject client-authored channel markers; the broker issues child-scoped supervisor capabilities, binds validated registrations to the issuing supervisor, derives the only authorized cross-group destination, and adds the trusted relay marker itself. Wrong targets/tokens, fabricated `replyTo` values, and ordinary peer sends remain isolated, while legitimate child requests and exact supervisor replies continue to cross groups. Parent-held capability state is restored after broker reconnects, the child uses the broker-confirmed current supervisor ID, and the lightweight wrapper lazy-loads the authorization provider before spawn. Claimed provider failures propagate; hosts without a provider omit supervisor metadata rather than launching a silently broken `contact_supervisor` channel.
+- Fixed workflow stages freezing when their active foreground subagent sent Intercom traffic or blocking `contact_supervisor`. Busy open stages give the exact foreground owner probe/commit detach handshake first refusal before model-visible queue insertion; unclaimed traffic and owner loss between probe/commit fall back to normal insertion instead of dropping a broker-delivered message. A commit from one parallel child releases aggregate foreground supervision for all active siblings while their processes and eventual results remain owned.
+- Fixed `intercom.ask` hanging when one workflow stage targeted a sibling stage that had already completed. Blocking late asks now retain their exact sender/thread correlation while the workflow runtime schedules the target's retained conversation for a post-mortem turn; only that target's correlated `intercom.reply` resolves the caller. The production workflow and Intercom listeners now preserve the first owner's completion promise regardless of registration order, preventing the lightweight Intercom relay or duplicate listeners from replacing or double-delivering a claimed revival. Missing, deleted, non-resumable, or failed-to-reopen targets return a bounded actionable tool error instead of waiting for the normal ask timeout, while ordinary late notifications retain their existing parent-chat route ([#1854](https://github.com/bastani-inc/atomic/issues/1854)).
+- Fixed blocking `intercom.ask` delivery to a sibling workflow stage that is mid-turn. Busy targets now reserve the message synchronously in the open AgentSession generation before awaiting foreground-owner detach, then drain the eventual native queue insertion before terminal snapshot publication. Destination-side admission failures return an exact-thread actionable tool error instead of leaving the asker blocked for the 10-minute reply timeout.
+
+## [0.9.9] - 2026-07-15
+
+### Changed
+
+- Aligned the intercom extension peer dependency with `@earendil-works/pi-tui` `^0.80.7` as part of the consolidated Pi v0.80.7 dependency update; no intercom source changes were needed.
+- Updated the runtime `typebox` range to `^1.3.6`.
+
+### Fixed
+
+- Preserved per-child chronology between busy-parent Intercom messages and terminal async subagent notifications: paused, completed, and failed paths now claim pre-terminal ordinary messages from the exact child session/run in FIFO order and atomically admit the prelude plus terminal notice through the custom-message batch API. A process-local bridge complements extension-bus delivery for lazily activated companions; terminal identity deduplicates both paths even when the successful terminal dispatch has an empty prelude, while failed dispatches remain retryable and distinct resumed-run lifecycle terminals remain independent. Idle flushes use the same ordered batch admission, unrelated children remain independent, and ask/reply correlation is unchanged ([#1802](https://github.com/bastani-inc/atomic/issues/1802)).
+- Made every short session ID printed by `intercom list` directly actionable in `send`, blocking `ask`, and targeted `reply`. Target resolution now preserves exact full IDs and exact case-insensitive names before accepting unique ID prefixes, reports colliding prefixes with the matching sessions instead of guessing, resolves blocking asks to the full sender ID so threaded replies correlate correctly, and rejects short-form self-targets at both tool and broker routing boundaries.
+
 ## [0.9.9-alpha.4] - 2026-07-15
 
 ### Changed

package/dist/builtin/intercom/README.md

@@ -20,11 +20,11 @@ Sometimes you're running multiple Atomic/pi sessions — one researching, one ex
 
 Unlike pi-messenger (a shared chat room for multi-agent swarms), intercom is for targeted 1:1 communication where you pick the recipient.
 
-Intercom also integrates with delegated subagents: child agents get a child-only `contact_supervisor` tool when subagent bridge metadata is present. Atomic-prefixed bridge environment variables are supported, and legacy `PI_*` bridge metadata remains compatible. Use `reason: "need_decision"` for blocking clarification, `reason: "interview_request"` for multiple structured supervisor answers, and `reason: "progress_update"` for meaningful plan-changing updates. Normal sessions only see the regular `intercom` tool.
+Intercom also integrates with delegated subagents: child agents get a child-only `contact_supervisor` tool when subagent bridge metadata is present. Atomic-prefixed bridge environment variables are supported, and legacy `PI_*` bridge metadata remains compatible. Atomic's subagent bridge also obtains a broker capability that binds the child session to the exact supervisor; client-authored channel flags are never trusted as cross-group authority. Use `reason: "need_decision"` for blocking clarification, `reason: "interview_request"` for multiple structured supervisor answers, and `reason: "progress_update"` for meaningful plan-changing updates. Normal sessions only see the regular `intercom` tool.
 
 ## In One Minute
 
-Intercom connections are tool-driven. Parent and delegated child sessions keep the lightweight wrapper unloaded until the model or user invokes an Intercom tool, `/intercom`, or the `ALT+M` overlay. A bridged child receives its deterministic Intercom identity and `contact_supervisor` tool at startup, but invoking that tool establishes its broker connection; merely launching a foreground or background child does not connect either session. Concurrent first-use callers share one import and connection attempt, and lazy broker state is leased to the active session generation and cleaned up on shutdown or replacement.
+Intercom connections are normally tool-driven. A bridged child still keeps its own broker connection lazy until it invokes `contact_supervisor`, but Atomic connects the parent Intercom runtime while launching the child to issue a child-bound supervisor capability. The parent retains and restores that capability across broker reconnects, and the broker confirms the supervisor's current session ID when the child registers. Concurrent first-use callers share one import and connection attempt, and broker state is leased to the active session generation and cleaned up on shutdown or replacement.
 
 ## Install
 
@@ -122,6 +122,10 @@ See auth.ts:142-156.
 
 The reply hint (enabled by default) points to `intercom({ action: "reply", ... })`, so recipients do not need raw sender or `replyTo` IDs. Idle recipients get a new turn immediately; busy interactive recipients receive the message once they go idle. Attachment content is included in the agent-visible body, and messages are rendered inline and stored in Pi session history.
 
+When a blocking `intercom.ask` targets a workflow stage that has already completed, Atomic uses the stage's retained conversation as a post-mortem chat. It automatically schedules a new turn in that exact conversation, preserving the original ask text and sender/thread correlation, so the target can answer with ordinary `intercom.reply` and the waiting sibling continues without a manual workflow follow-up. The completed stage and workflow DAG remain terminal. The workflow router has single-owner completion semantics: once it claims the ask, later late-message listeners preserve its completion promise regardless of bundled extension registration order. Parent and unrelated sessions cannot satisfy the child-to-child waiter. Deleted, unavailable, non-resumable, or failed-to-reopen targets return a bounded actionable ask error.
+
+When a blocking ask reaches a sibling workflow stage during an active model/tool turn, the target reserves it synchronously in the open stage generation before any asynchronous foreground-owner detach handshake. Queue insertion waits inside that reservation, and stage finalization drains it before publishing the terminal snapshot. This prevents a structured-output or other terminal tool call from overtaking a mid-turn ask. If destination-side admission genuinely cannot complete, the asker receives an exact-thread actionable error instead of consuming the full 10-minute timeout.
+
 For delegated background children, queued messages and terminal lifecycle notices are ordered per child. Intercom claims the terminal child’s pre-terminal ordinary entries in FIFO order and atomically admits that prelude together with the paused, completed, or failed notice. A process-local companion bridge covers lazily loaded extensions whose event buses are distinct, while exact terminal-identity deduplication prevents double admission even when the successful terminal dispatch has no queued prelude. Failed dispatches remain retryable, and pause/resume/completion identities remain distinct. Other children’s entries remain independently queued, messages are not discarded, terminal admission does not wait for a separate model turn, and correlated ask replies still bypass unrelated queued sends.
 
 ## Workflow: Planner-Worker Coordination
@@ -215,7 +219,7 @@ This matters because the agent receiving the message doesn't need to reconstruct
 
 `send` is fire-and-forget — the tool returns immediately after delivery. By default, it sends immediately even in interactive sessions. If you want an approval dialog before non-reply sends, set `confirmSend: true` in config. Replies that include `replyTo` still skip confirmation so reply-hint flows can continue without an extra approval step.
 
-`ask` sends the message and blocks until the recipient responds (10-minute timeout). The reply comes back as the tool result, so the agent continues in the same turn with full context. No confirmation dialog — if you're asking and waiting, the intent is clear.
+`ask` sends the message and blocks until the recipient responds (10-minute timeout). The reply comes back as the tool result, so the agent continues in the same turn with full context. No confirmation dialog — if you're asking and waiting, the intent is clear. A completed workflow-stage target with a retained conversation is automatically reopened for one post-mortem turn; unavailable or non-resumable completed targets fail actionably without consuming the full reply timeout.
 
 `reply` is receiver-side sugar for replying to an inbound ask. In the turn triggered by an incoming intercom ask, `intercom({ action: "reply", message: "..." })` targets that exact sender and message automatically. If you reply later, it falls back to the single unresolved inbound ask. If multiple asks are pending, use `intercom({ action: "pending" })` to inspect them and then call `reply` with `to` to disambiguate.
 
@@ -234,6 +238,8 @@ This workflow requires [`pi-subagents`](https://github.com/nicobailon/pi-subagen
 - `PI_SUBAGENT_CHILD_AGENT` — the agent type
 - `PI_SUBAGENT_CHILD_INDEX` — the child index within the run
 
+Atomic's bundled subagent bridge additionally supplies internal `ATOMIC_SUBAGENT_SUPERVISOR_CAPABILITY` and `ATOMIC_SUBAGENT_SUPERVISOR_SESSION_ID` values issued by the broker. They are not user-configurable authentication flags: the broker accepts the capability only for the child scope and supervisor session that requested it, and the parent restores the same secret if the broker reconnects. Legacy `PI_*` aliases remain readable where applicable.
+
 If any are missing, the session falls back to the regular `intercom` tool.
 
 ### Three Reasons
@@ -246,7 +252,9 @@ If any are missing, the session falls back to the regular `intercom` tool.
 
 Do not use `contact_supervisor` for routine completion handoffs. Return the final subagent result normally through `pi-subagents`.
 
-During a foreground subagent run, Atomic probes for an exact live foreground owner before delivery. The matching child reserves the request, accepts a generation-scoped detach commit, and acknowledges the commit before asks, sends, decisions, interviews, and progress updates enter the parent's model-visible steering queue. Blocking calls remain alive until the parent sends the exact threaded reply; fire-and-forget calls create no reply waiter. Background and unmatched messages keep their queued-until-idle behavior, and cancellation/replacement invalidates stale handshakes.
+Cross-group delivery uses a dedicated broker protocol. Ordinary raw `send` frames always remain group-isolated and are rejected if they include a forged `channel: "supervisor"` marker. A child can cross groups only after its broker-issued capability has bound its registered socket to the exact supervisor. The broker adds the `supervisor` channel marker to validated inbound traffic so parent relays can distinguish it. Replies cross back only when `replyTo` matches a recorded supervisor message in the exact reverse direction; fabricated thread IDs do not bypass isolation.
+
+During a foreground subagent run, Atomic probes for an exact live foreground owner before delivery. The matching child reserves the request, accepts a generation-scoped detach commit, and acknowledges it before asks, sends, decisions, interviews, and progress updates enter the parent's model-visible steering queue. A busy workflow stage first reserves the message in its AgentSession generation boundary, then waits inside that admission for the same detach handshake before model-visible queue insertion. This prevents terminal stage close from overtaking the handshake while still preventing the active subagent tool from blocking the child request that would release it; unclaimed traffic and a still-current receiver whose owner disappears before commit fall back to ordinary queue insertion. One accepted commit releases foreground supervision for every active member of a parallel group while retaining each child process and eventual result. Blocking calls remain alive until the parent sends the exact threaded reply; fire-and-forget calls create no reply waiter. Background and unmatched traffic for ordinary sessions keeps queued-until-idle behavior, and generation cancellation/replacement invalidates stale handshakes.
 
 ### Example: Blocked Subagent Asks for Guidance
 

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

@@ -3,9 +3,11 @@ import { writeFileSync, unlinkSync, mkdirSync } from "fs";
 import { randomUUID } from "crypto";
 import { writeMessage, createMessageReader } from "./framing.js";
 import { getBrokerPidPath, getBrokerSocketPath, getIntercomDirPath } from "./paths.js";
-import type { SessionInfo, BrokerMessage } from "../types.js";
+import type { SessionInfo, BrokerMessage, SupervisorRegistration } from "../types.js";
 import { DeliveredMessageCache } from "./delivered-message-cache.js";
 import { handleBrokerSend, type BrokerConnectedSession } from "./send-handler.js";
+import { SupervisorChannelCache } from "./supervisor-channel.js";
+import { normalizeGroup } from "../group.js";
 
 const INTERCOM_DIR = getIntercomDirPath();
 const SOCKET_PATH = getBrokerSocketPath();
@@ -34,14 +36,26 @@ function isSessionRegistration(value: unknown): value is Omit<SessionInfo, "id">
     return false;
   }
 
+  if (session.group !== undefined && typeof session.group !== "string") {
+    return false;
+  }
+
   return session.status === undefined || typeof session.status === "string";
 }
+function isSupervisorRegistration(value: unknown): value is SupervisorRegistration {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const registration = value as Record<string, unknown>;
+  return typeof registration.capability === "string"
+    && typeof registration.supervisorSessionId === "string";
+}
+
 
 class IntercomBroker {
   private sessions = new Map<string, ConnectedSession>();
   private server: net.Server;
   private shutdownTimer: NodeJS.Timeout | null = null;
   private deliveredMessages = new DeliveredMessageCache();
+  private supervisorChannel = new SupervisorChannelCache();
 
   constructor() {
     mkdirSync(INTERCOM_DIR, { recursive: true });
@@ -79,8 +93,9 @@ class IntercomBroker {
 
     socket.on("close", () => {
       if (sessionId) {
+        const leavingGroup = this.sessions.get(sessionId)?.info.group;
         this.sessions.delete(sessionId);
-        this.broadcast({ type: "session_left", sessionId }, sessionId);
+        this.broadcastToGroup({ type: "session_left", sessionId }, leavingGroup, sessionId);
 
         this.scheduleShutdownCheck();
       }
@@ -124,29 +139,61 @@ class IntercomBroker {
         if (!isSessionRegistration(clientMessage.session)) {
           throw new Error("Invalid register message");
         }
+        if (clientMessage.supervisorOwnerToken !== undefined
+          && (typeof clientMessage.supervisorOwnerToken !== "string" || !clientMessage.supervisorOwnerToken)) {
+          throw new Error("Invalid supervisor owner token");
+        }
 
         if (currentId) {
           throw new Error("Received duplicate register message");
         }
 
+        let supervisorId: string | undefined;
+        if (clientMessage.supervisor !== undefined) {
+          const childName = clientMessage.session.name?.trim();
+          const claimedSupervisorId = isSupervisorRegistration(clientMessage.supervisor) && childName
+            ? this.supervisorChannel.claim(clientMessage.supervisor.capability, childName)
+            : undefined;
+          if (!claimedSupervisorId || !this.sessions.has(claimedSupervisorId)) {
+            writeMessage(socket, { type: "registration_failed", reason: "Invalid supervisor authorization" });
+            socket.end();
+            return;
+          }
+          supervisorId = claimedSupervisorId;
+        }
+
         const id = randomUUID();
         setId(id);
-        const info: SessionInfo = { ...clientMessage.session, id };
-        this.sessions.set(id, { socket, info });
+        const info: SessionInfo = {
+          ...clientMessage.session,
+          id,
+          group: normalizeGroup(clientMessage.session.group),
+        };
+        this.sessions.set(id, {
+          socket,
+          info,
+          ...(supervisorId ? { supervisorId } : {}),
+          ...(typeof clientMessage.supervisorOwnerToken === "string"
+            ? { supervisorOwnerToken: clientMessage.supervisorOwnerToken }
+            : {}),
+        });
 
         if (this.shutdownTimer) {
           clearTimeout(this.shutdownTimer);
           this.shutdownTimer = null;
         }
 
-        writeMessage(socket, { type: "registered", sessionId: id });
-        this.broadcast({ type: "session_joined", session: info }, id);
+        writeMessage(socket, supervisorId
+          ? { type: "registered", sessionId: id, supervisorSessionId: supervisorId }
+          : { type: "registered", sessionId: id });
+        this.broadcastToGroup({ type: "session_joined", session: info }, info.group, id);
         break;
       }
 
       case "unregister": {
+        const leavingGroup = this.sessions.get(currentId)?.info.group;
         this.sessions.delete(currentId);
-        this.broadcast({ type: "session_left", sessionId: currentId }, currentId);
+        this.broadcastToGroup({ type: "session_left", sessionId: currentId }, leavingGroup, currentId);
         setId(null);
         this.scheduleShutdownCheck();
         break;
@@ -156,14 +203,48 @@ class IntercomBroker {
         if (typeof clientMessage.requestId !== "string") {
           throw new Error("Invalid list message");
         }
+        if (clientMessage.group !== undefined && typeof clientMessage.group !== "string") {
+          throw new Error("Invalid list group");
+        }
 
-        const sessions = Array.from(this.sessions.values()).map(s => s.info);
+        const requester = currentId ? this.sessions.get(currentId) : undefined;
+        const effectiveGroup = normalizeGroup(
+          typeof clientMessage.group === "string" ? clientMessage.group : requester?.info.group,
+        );
+        const sessions = Array.from(this.sessions.values())
+          .map((s) => s.info)
+          .filter((info) => normalizeGroup(info.group) === effectiveGroup);
         writeMessage(socket, { type: "sessions", requestId: clientMessage.requestId, sessions });
         break;
       }
 
-      case "send": {
-        handleBrokerSend(socket, clientMessage, currentId, this.sessions, this.deliveredMessages, writeMessage);
+      case "authorize_supervisor": {
+        const supervisor = this.sessions.get(currentId);
+        if (!supervisor?.supervisorOwnerToken || typeof clientMessage.requestId !== "string"
+          || typeof clientMessage.childName !== "string" || !clientMessage.childName.trim()
+          || (clientMessage.capability !== undefined && typeof clientMessage.capability !== "string")) {
+          throw new Error("Invalid authorize_supervisor message");
+        }
+        const childName = clientMessage.childName.trim();
+        const capability = this.supervisorChannel.authorize(
+          supervisor.info.id,
+          supervisor.supervisorOwnerToken,
+          childName,
+          typeof clientMessage.capability === "string" ? clientMessage.capability : undefined,
+        );
+        writeMessage(socket, {
+          type: "supervisor_authorized",
+          requestId: clientMessage.requestId,
+          capability,
+          supervisorSessionId: supervisor.info.id,
+          childName,
+        });
+        break;
+      }
+
+      case "send":
+      case "supervisor_send": {
+        handleBrokerSend(socket, clientMessage, currentId, this.sessions, this.deliveredMessages, writeMessage, this.supervisorChannel);
         break;
       }
 
@@ -189,7 +270,7 @@ class IntercomBroker {
             session.info.model = clientMessage.model;
           }
           session.info.lastActivity = Date.now();
-          this.broadcast({ type: "presence_update", session: session.info }, currentId);
+          this.broadcastToGroup({ type: "presence_update", session: session.info }, session.info.group, currentId);
         }
         break;
       }
@@ -199,10 +280,11 @@ class IntercomBroker {
     }
   }
 
-
-  private broadcast(msg: BrokerMessage, exclude?: string): void {
+  /** Deliver a broadcast only to sessions in the given (normalized) group. */
+  private broadcastToGroup(msg: BrokerMessage, group: string | undefined, exclude?: string): void {
+    const target = normalizeGroup(group);
     for (const [id, session] of this.sessions) {
-      if (id !== exclude) {
+      if (id !== exclude && normalizeGroup(session.info.group) === target) {
         writeMessage(session.socket, msg);
       }
     }

package/dist/builtin/intercom/broker/client-message-validation.ts

@@ -0,0 +1,39 @@
+import type { Attachment, Message, SessionInfo } from "../types.js";
+
+function isAttachment(value: unknown): value is Attachment {
+  if (typeof value !== "object" || value === null) return false;
+  const attachment = value as Record<string, unknown>;
+  if (attachment.type !== "file" && attachment.type !== "snippet" && attachment.type !== "context") return false;
+  if (typeof attachment.name !== "string" || typeof attachment.content !== "string") return false;
+  return attachment.language === undefined || typeof attachment.language === "string";
+}
+
+export function isMessage(value: unknown): value is Message {
+  if (typeof value !== "object" || value === null) return false;
+  const message = value as Record<string, unknown>;
+  if (typeof message.id !== "string" || typeof message.timestamp !== "number") return false;
+  if (message.replyTo !== undefined && typeof message.replyTo !== "string") return false;
+  if (message.expectsReply !== undefined && typeof message.expectsReply !== "boolean") return false;
+  if (message.replyError !== undefined && typeof message.replyError !== "string") return false;
+  if (typeof message.content !== "object" || message.content === null) return false;
+  const content = message.content as Record<string, unknown>;
+  if (typeof content.text !== "string") return false;
+  return content.attachments === undefined
+    || (Array.isArray(content.attachments) && content.attachments.every(isAttachment));
+}
+
+export function isSessionInfo(value: unknown): value is SessionInfo {
+  if (typeof value !== "object" || value === null) return false;
+  const session = value as Record<string, unknown>;
+  if (
+    typeof session.id !== "string"
+    || typeof session.cwd !== "string"
+    || typeof session.model !== "string"
+    || typeof session.pid !== "number"
+    || typeof session.startedAt !== "number"
+    || typeof session.lastActivity !== "number"
+  ) return false;
+  if (session.name !== undefined && typeof session.name !== "string") return false;
+  if (session.group !== undefined && typeof session.group !== "string") return false;
+  return session.status === undefined || typeof session.status === "string";
+}