@bastani/atomic 0.9.18-alpha.2 → 0.9.18-alpha.3

package/dist/builtin/workflows/src/index.js

@@ -1392,7 +1392,6 @@ function compactStage(stage) {
     inputRequest,
     notices,
     mcpScope: _mcpScope,
-    pendingStageDeliveryAvailable: _pendingStageDeliveryAvailable,
     attemptedModels: _attemptedModels,
     modelAttempts: _modelAttempts,
     result: _result,
@@ -4459,6 +4458,7 @@ function durableStageCheckpointMetadata(stage, run, sourceOrder) {
       version: DURABLE_STAGE_TOPOLOGY_VERSION,
       stageId: stage.id,
       parentIds: [...stage.parentIds],
+      ...stage.intercomGroup !== undefined ? { intercomGroup: stage.intercomGroup } : {},
       ...stage.executionOrder !== undefined ? { order: stage.executionOrder } : {},
       ...sourceOrder !== undefined && sourceOrder >= 0 ? { sourceOrder } : {},
       ...stage.promptFootprint !== undefined ? { occurrenceKey: stage.id } : {},
@@ -5191,11 +5191,13 @@ function createDurableStagePrimitive(input) {
     const isMidSessionResume = session?.sessionFile !== undefined;
     const topology = activeStageTopology(input.backend, input.workflowId, replayKey);
     const durableStageId = topology?.stageId ?? pendingStageIdForReplay(input.backend, input.workflowId, replayKey, name);
+    const durableIntercomGroup = topology?.intercomGroup ?? input.durableIntercomGroup?.(replayKey, durableStageId);
     const liveOptions = {
       ...options ?? {},
       durableReplayKey: replayKey,
       ...durableStageId !== undefined ? { durableStageId } : {},
       ...topology !== undefined ? { durableParentIds: [...topology.parentIds] } : {},
+      ...durableIntercomGroup !== undefined ? { durableIntercomGroup } : {},
       ...isMidSessionResume ? {
         resumeFromSessionFile: session.sessionFile,
         durableAccumulatedDurationMs: session.durationMs ?? 0
@@ -5224,6 +5226,7 @@ function createDurableTaskPrimitive(input) {
     }
     const session = input.backend.getStageSession(input.workflowId, replayKey);
     const topology = activeStageTopology(input.backend, input.workflowId, replayKey);
+    const durableIntercomGroup = topology?.intercomGroup ?? input.durableIntercomGroup?.(replayKey, topology?.stageId);
     const taskOptions = {
       ...options,
       durableReplayKey: replayKey,
@@ -5231,6 +5234,7 @@ function createDurableTaskPrimitive(input) {
         durableStageId: topology.stageId,
         durableParentIds: [...topology.parentIds]
       } : {},
+      ...durableIntercomGroup !== undefined ? { durableIntercomGroup } : {},
       ...session?.sessionFile !== undefined ? {
         resumeFromSessionFile: session.sessionFile,
         durableAccumulatedDurationMs: session.durationMs ?? 0
@@ -8608,6 +8612,7 @@ function appendStageStart(api, payload) {
     name: payload.name,
     parentIds: [...payload.parentIds],
     ...payload.model !== undefined ? { model: payload.model } : {},
+    ...payload.intercomGroup !== undefined ? { intercomGroup: payload.intercomGroup } : {},
     ...payload.pendingStageDeliveryAvailable !== undefined ? { pendingStageDeliveryAvailable: payload.pendingStageDeliveryAvailable } : {},
     ...payload.replayKey !== undefined ? { replayKey: payload.replayKey } : {},
     ...payload.replayedFromStageId !== undefined ? { replayedFromStageId: payload.replayedFromStageId } : {},
@@ -10357,18 +10362,28 @@ function resolveStageGroup(stageOptions, workflowGroup) {
   const group = stageOptions.group;
   if (group === undefined)
     return workflowGroup;
-  if (group === true)
-    return randomUUID2();
-  const trimmed = group.trim();
-  return trimmed.length > 0 ? trimmed : undefined;
+  const authored = group === true ? randomUUID2() : group.trim();
+  if (authored.length === 0)
+    return;
+  if (workflowGroup === undefined || authored === DEFAULT_INTERCOM_GROUP)
+    return authored;
+  const owner2 = normalizeGroup(workflowGroup);
+  if (authored === owner2 || authored.startsWith(`${owner2}/`))
+    return authored;
+  return `${owner2}/${authored}`;
+}
+function workflowInvocationOwnsGroup(workflowGroup, candidate) {
+  if (workflowGroup === undefined || candidate === undefined)
+    return false;
+  const owner2 = normalizeGroup(workflowGroup);
+  const group = normalizeGroup(candidate);
+  return group === owner2 || group.startsWith(`${owner2}/`);
 }
 function stageHasIntercomAccess(_stageOptions) {
   return true;
 }
 function stageCanUseWorkflowPendingStageRoute(stageOptions, workflowGroup) {
-  if (!stageHasIntercomAccess(stageOptions) || stageOptions?.group === true)
-    return false;
-  return normalizeGroup(resolveStageGroup(stageOptions, workflowGroup)) === normalizeGroup(workflowGroup);
+  return stageHasIntercomAccess(stageOptions) && workflowInvocationOwnsGroup(workflowGroup, resolveStageGroup(stageOptions, workflowGroup));
 }
 
 // dist/builtin/workflows/builtin/verification-usage.ts
@@ -14496,6 +14511,7 @@ function stripWorkflowOnlyOptions(options, defaultSessionDir, meta2, pendingStag
     durableReplayKey: _durableReplayKey,
     durableAccumulatedDurationMs: _durableAccumulatedDurationMs,
     durableStageId: _durableStageId,
+    durableIntercomGroup: _durableIntercomGroup,
     durableParentIds: _durableParentIds,
     sessionDir,
     gitWorktreeDir: _gitWorktreeDir,
@@ -16618,15 +16634,18 @@ function createWorkflowStageFactory(input) {
     const replaySource = replayDecision.kind === "replay" ? replayDecision.source : undefined;
     const executeReplaySource = replayDecision.kind === "execute" ? replayDecision.source : undefined;
     const shouldReplay = replaySource !== undefined;
-    const stageOptionsForContext = executeReplaySource?.sessionFile === undefined ? options : {
+    const replayStageOptions = executeReplaySource?.sessionFile === undefined ? options : {
       ...options ?? {},
       context: options?.context ?? "fork",
       forkFromSessionFile: options?.forkFromSessionFile ?? executeReplaySource.sessionFile
     };
+    const intercomGroup = options?.durableIntercomGroup ?? resolveStageGroup(replayStageOptions, input.workflowIntercomGroup);
+    const stageOptionsForContext = replayStageOptions?.group === undefined || intercomGroup === undefined ? replayStageOptions : { ...replayStageOptions, group: intercomGroup };
     const pendingStageDeliveryAvailable = stageCanUseWorkflowPendingStageRoute(stageOptionsForContext, input.workflowIntercomGroup);
     const stageSnapshot = {
       id: stageId,
       name,
+      ...intercomGroup === undefined ? {} : { intercomGroup },
       replayKey,
       status: shouldReplay ? "completed" : "pending",
       parentIds: Object.freeze(parentIds),
@@ -16825,6 +16844,7 @@ function createWorkflowStageFactory(input) {
         name,
         parentIds: stageSnapshot.parentIds,
         ...stageReplayFields(stageSnapshot),
+        ...intercomGroup === undefined ? {} : { intercomGroup },
         pendingStageDeliveryAvailable,
         ts: stageSnapshot.startedAt ?? Date.now()
       });
@@ -17506,11 +17526,16 @@ async function run(def, inputs, opts = {}) {
     completedStageReplayKeys,
     sourceToReplayedNodeIds: sourceToContinuationNodeIds
   });
+  const durableIntercomGroup = (replayKey, stageId) => {
+    const stages = activeStore.runs().find((candidate) => candidate.id === runId)?.stages ?? [];
+    return stages.find((stage) => stageId !== undefined && stage.id === stageId || stage.replayKey === replayKey)?.intercomGroup;
+  };
   let observedTaskTailQuit;
   const durableTask = createDurableTaskPrimitive({
     workflowId: runId,
     backend: durableBackend,
     nextReplayKey: (stageName) => stageReplayKeyGenerator(stageName),
+    durableIntercomGroup,
     task: taskRunners.task,
     recordCachedTask: cachedStage.record,
     signal: ownController.signal,
@@ -17559,6 +17584,7 @@ async function run(def, inputs, opts = {}) {
       workflowId: runId,
       backend: durableBackend,
       nextReplayKey: (stageName) => stageReplayKeyGenerator(stageName),
+      durableIntercomGroup,
       recordCachedStage: cachedStage.record,
       stage: (name, options, replayKey) => {
         const stage = runtime.stage(name, options);

package/docs/intercom.md

@@ -153,7 +153,7 @@ Name sessions with `/name` so they can target each other (for example `/name pla
 | `join` | Adds a trimmed named group membership and creates the group if needed. The action waits for broker acknowledgement and reports the complete resulting membership set. `default` is shared; `true` and `auto` are reserved for subagent auto-groups. |
 | `leave` | With `group`, removes only that membership and keeps all others. Without `group`, resets the session to its resolved startup home group. Both forms report the resulting membership set. |
 | `groups` | Lists every group represented by a connected session, with its session count and a marker for each group this session belongs to. Use it to discover names rather than guessing. |
-| `list` | Keeps session-listing semantics: returns the current session plus every active session sharing at least one membership, with name, full session ID, working directory, model, and live status. Pass `group` for a read-only view of one group. |
+| `list` | Returns the current session, every active session sharing at least one membership, and discoverable workflow stages. Workflow rows are explicitly labeled `PENDING` or `RUNNING` and include the canonical `<runId>:<stageId>` target. Pass `group` for a read-only view of one group. |
 | `send` | Fire-and-forget delivery through ordinary Intercom. A live workflow-stage session receives the message immediately and returns `delivered`. A known workflow stage whose session has not initialized is addressed as `<runId>:<stageKey>`; Atomic persists the message and returns the distinct `queued` result with its FIFO position. Unknown stage identities retain the ordinary unknown-target failure. Requires `to` and `message`; cannot message the current session. |
 | `ask` | Sends a message and blocks until a live recipient replies (10-minute timeout). An ask to a known workflow stage whose session has not initialized is refused with `pending_stage_ask_unsupported` and recommends ordinary `send`; holding a waiter until a stage eventually starts would be unbounded. A live recipient disconnect fails promptly. From a foreground child to its launching parent, the existing fresh-subagent handoff path remains unchanged. |
 | `reply` | Replies to the intercom-triggered message of the current turn; otherwise falls back to the single unresolved inbound ask. With multiple pending asks, pass `to` or inspect with `pending` first. |
@@ -172,9 +172,9 @@ Sent and received messages are recorded in session history as `intercom_sent` /
 
 ### Targeting Sessions and Pending Workflow Stages
 
-Live-session lookup accepts only an exact full session ID or an exact case-insensitive session name. Ordinary `send` also accepts the exact `<runId>:<stageKey>` identity of a known workflow stage whose session has not initialized. The run ID is the full UUID, and the authored stage key is case-sensitive. Unknown runs and stages retain the ordinary unknown-target failure. Targeting is **group-scoped** — see [Groups](#groups) below.
+Live-session lookup accepts only an exact full Intercom session ID or an exact case-insensitive session name. Workflow stages use the canonical exact `<runId>:<stageId>` target printed by `intercom list` and workflow status surfaces; this target works while the row is `PENDING` and after it becomes `RUNNING`. Status surfaces label pending stages whose pre-start delivery capability is unavailable without presenting a usable target, and never advertise a retained pending stage after its run terminates. The `sessionId` shown by `workflow status` belongs to the workflow SDK and is **not** an Intercom target.
 
-Before steering a stage, join its invocation group. Use the Intercom `groups` action to discover it. Workflow invocation groups are named `workflow:<rootRunId>`.
+Before steering a stage from the main chat, enter the workflow invocation context by joining `workflow:<rootRunId>` with `intercom({ action: "join", group: "workflow:<rootRunId>" })`; workflow-owned invocation sessions already start there. A member of that invocation group can list, `send` to, and live-`ask` exact stages in any invocation-owned subgroup (`workflow:<rootRunId>/<name>`), including intentionally isolated reviewer batches. This control is directional: a session registered as a subgroup stage cannot gain parent control by joining the invocation group, subgroup members cannot discover or reach sibling subgroups, and another workflow invocation remains refused. `PENDING` accepts queued `send` only; `RUNNING` accepts immediate `send` and correlated `ask`/`reply`.
 
 ### Deferred delivery to pending stages
 
@@ -182,7 +182,9 @@ Send material updates through Intercom to every affected workflow stage, includi
 
 The workflows extension persists up to **50 queued messages per exact run/stage key** with workflow state. Messages survive resume/replay and broker restart, and logical message IDs prevent redelivery across stage-attempt restarts. When the stage session initializes, it receives the FIFO entries through the ordinary Intercom inbound path before its first model turn, under the heading **Messages received before you started**, with sender identity and `Sent:` timestamps visible separately from the task prompt.
 
-Only a session in the workflow run's Intercom group can queue a message; a cross-group attempt is refused with `Target workflow run is in a different intercom group`. The 51st queued message is refused with `Pending stage message queue is full (limit 50)` rather than evicting an earlier entry. If the destination is skipped, the run is cancelled, or the stage becomes terminal before its session initializes, Atomic marks the message undeliverable and sends the correlated failure notification when acknowledgment was requested. Blocking `ask` is deliberately unsupported before initialization: use ordinary `send`, because a stage may start much later or never start.
+Only a workflow invocation member with eligible invocation-control authority can queue to its invocation-owned stages; this includes a main-chat session that explicitly joined `workflow:<rootRunId>`. Subgroup peers and another root run remain refused even if they add that membership. An explicit stage `group: "default"` is a shared-group escape, is not workflow-owned, and does not receive pending invocation delivery. An ineligible attempt is refused with `Target workflow run is in a different intercom group`. The 51st queued message is refused with `Pending stage message queue is full (limit 50)` rather than evicting an earlier entry.
+
+If the destination stage is skipped, the run terminates, or the stage becomes terminal before its session initializes, Atomic marks the queued message undeliverable and sends the correlated failure notification when acknowledgment was requested. Blocking `ask` is deliberately unsupported before initialization: use ordinary `send`, because a stage may start much later or never start.
 
 ### Groups
 
@@ -193,7 +195,7 @@ Every session belongs to a non-empty set of intercom **groups**. Sessions with n
 - `join` adds one membership. `leave` removes the named membership, while bare `leave` resets the complete set to the startup home group.
 - `status` reports the complete membership set. `session_joined`/`session_left`/`presence_update` events are delivered whenever a membership change affects visibility.
 
-A session's home group is resolved with this precedence: explicit stage/task/subagent group > runtime-owned workflow invocation group or inherited launching-session group > env `ATOMIC_INTERCOM_GROUP` (legacy `PI_INTERCOM_GROUP`) > Intercom `config.json` `"group"` > `"default"`. Each top-level workflow invocation gets a stable non-default group from its persistent run identity; Intercom-capable stages, nested workflows, and their delegated subagents inherit it without authors threading IDs. Explicit `group: "default"` opts into the shared group. Boolean `true` and the trimmed, case-insensitive strings `"true"`/`"auto"` request an automatically generated subgroup; those string names are reserved. Stages and children without Intercom access receive no group. See [workflows.md](/workflows) for workflow-stage rules. The subagent-only `contact_supervisor` path remains capability-based and can cross group boundaries; ordinary `send`, `ask`, and replies cannot use it as a bypass.
+A session's home group is resolved with this precedence: explicit stage/task/subagent group > runtime-owned workflow invocation group or inherited launching-session group > env `ATOMIC_INTERCOM_GROUP` (legacy `PI_INTERCOM_GROUP`) > Intercom `config.json` `"group"` > `"default"`. Workflow stage named groups and `group: true` are namespaced under `workflow:<rootRunId>/...`, preventing cross-run collisions while preserving sibling isolation. `group: "default"` remains the explicit non-owned escape. The invocation group has asymmetric exact-target control over its owned subgroups; ownership does not grant reverse or lateral access.
 
 The broker, not the client, marks validated supervisor traffic. Ordinary `send` frames remain membership-isolated even if a raw client forges a supervisor marker, and replies cross back only through an exact broker-recorded `replyTo` match. Parent-held authorization state is restored after reconnects. Before an Intercom-enabled foreground child first runs, the parent wrapper may lazy-load and connect the broker provider to mint that exact child's capability; queued children request no capability. The child still connects only when it uses an Intercom delivery path, and claimed decisions or interviews terminally hand off before child send or waiter admission. A claimed provider failure aborts launch, while runtimes with no provider omit supervisor metadata and do not expose a broken channel.
 

package/docs/workflows.md

@@ -116,7 +116,7 @@ Named workflow runs execute in the background. By default, after launch expect a
 
 For a request with several implementation items, do not turn list order into one serial workflow by default. Triage dependencies first, then launch independent items as a bounded wave of separate top-level runs; see [Task queues and software factories](#task-queues-and-software-factories).
 
-While a workflow is running, the visible below-editor `BACKGROUND` panel advances its elapsed label every second from the moment the run starts; it does not require opening or switching to the orchestrator. Updates repaint the existing mounted panel in place, paused timers stay frozen, the panel renders every qualifying top-level run, and terminal or quit cards retain their brief recent-run expiry. A zero-stage workflow whose work consists only of `ctx.tool(...)` calls mounts the same panel without a synthetic stage: at normal widths its run metadata reports the live-tool total when more than one is active, followed by pending and running durable tool-node names and statuses as space permits; the collapsed narrow form reports only the number of live tools. Quit cards remain resumable and discoverable with `/workflow status` after they leave the panel. A run waiting for human input uses the blue `？` indicator in the BACKGROUND panel, the `/workflow connect` picker, and the `/workflow status` listing; answering or cancelling the prompt restores the run's current indicator.
+While a workflow is running, the visible below-editor `BACKGROUND` panel advances its elapsed label every second from the moment the run starts; it does not require opening or switching to the orchestrator. Updates repaint the existing mounted panel in place, paused timers stay frozen, the panel renders every qualifying top-level run, and terminal or quit cards retain their brief recent-run expiry. At normal widths the panel names materialized pending stages with canonical stage IDs and exact Intercom targets when pre-start delivery is available; unavailable delivery is labeled instead of implying steerability. An exact target is never partially truncated: the panel uses only pending-stage forms that fit the metadata-row budget, and omits the pending label entirely when none fit so existing live-tool and elapsed/status metadata is not displaced. The narrow form remains aggregate-only. A zero-stage workflow whose work consists only of `ctx.tool(...)` calls mounts the same panel without a synthetic stage: at normal widths its run metadata reports the live-tool total when more than one is active, followed by pending and running durable tool-node names and statuses as space permits; the collapsed narrow form reports only the number of live tools. Quit cards remain resumable and discoverable with `/workflow status` after they leave the panel. A run waiting for human input uses the blue `？` indicator in the BACKGROUND panel, the `/workflow connect` picker, and the `/workflow status` listing; answering or cancelling the prompt restores the run's current indicator.
 
 ### Workflow run identifiers and the BACKGROUND panel
 
@@ -126,7 +126,7 @@ Stage targeting is exact but not UUID-bound, because stage identifiers are not a
 
 #### Intercom delivery to pending workflow stages
 
-A known workflow stage whose session has not initialized is still addressable by the workflow run's full UUID and its exact authored stage key. From a sibling session in the same workflow Intercom group, use ordinary Intercom delivery:
+A known workflow stage whose session has not initialized is still addressable by the workflow run's full UUID and its exact authored stage key while that run can still reach the stage. Model-facing `workflow status` and interactive status list/detail surfaces proactively enumerate materialized pending stages by display name and canonical stage ID. They print the exact `<runId>:<stageId>` target only when `pendingStageDeliveryAvailable` is true and the stage's owning run is nonterminal, and label delivery unavailable otherwise; an ended root or nested child run never advertises a retained pending stage as steerable through a projected parent. Duplicate display names therefore remain independently identifiable without overstating capability. Run `intercom({ action: "list" })` from the invocation context to discover materialized stages: each live route appears as `PENDING` or `RUNNING` with its canonical target. Note that the `sessionId` reported by `workflow status` is an SDK session id and is **not** an Intercom target. From a session in the workflow invocation group — including a main chat that explicitly joined `workflow:<rootRunId>` — use ordinary Intercom delivery:
 
 ```ts
 intercom({
@@ -141,12 +141,12 @@ Send material updates through Intercom to every affected workflow stage, includi
 
 The workflows extension persists pending messages with run state across resume/replay and broker restart. Each exact run/stage key accepts 50 queued messages; the next send is refused without eviction. Only sessions in the run's Intercom group may queue them. When the stage session initializes, Atomic delivers its messages FIFO through the ordinary inbound Intercom path **before the first model turn**. The transcript labels them **Messages received before you started**, preserves sender identity and `Sent:` timestamps, and keeps them separate from the stage task prompt. Duplicate logical message IDs and stage-attempt restarts do not redeliver a message.
 
-If the destination is skipped, the run is cancelled, or the stage becomes terminal before its session initializes, Atomic marks queued messages undeliverable rather than dropping them. Senders whose messages requested acknowledgment receive a correlated failure notification. Running and completed stages continue through their existing live, late, and post-mortem routes.
+If the destination is skipped, the run terminates, or the stage becomes terminal before its session initializes, Atomic marks queued messages undeliverable rather than dropping them. Senders whose messages requested acknowledgment receive a correlated failure notification. Running and completed stages continue through their existing live, late, and post-mortem routes.
 
 
-At 80 columns and wider, each `BACKGROUND` card uses two rows so the id is not squeezed beside the workflow name: the first row contains the status glyph and full UUID, and the second contains the workflow name followed by its mode, progress, live-tool total when more than one is active, pending/running `ctx.tool` node names and statuses as space permits, and elapsed/status metadata. Tool nodes are read-only durable graph nodes, not attachable stage chats. The panel renders every qualifying top-level run, so each card is two rows high (plus the existing spacing between cards). Below 80 columns, the panel keeps its collapsed form, omits ids and tool names, and includes a live-tool count when one or more tool nodes are pending or running.
+At 80 columns and wider, each `BACKGROUND` card keeps the full run identity and preserves its mode, progress, live-tool details, and elapsed/status metadata. When the remaining single-row budget permits, it adds bounded pending-stage details: a target is either shown exactly or replaced by a `stage`-labeled canonical ID, and `… N more` reports omitted pending stages. If no bounded pending-stage form fits, the pending label is omitted entirely rather than displacing the existing metadata. Tool nodes are read-only durable graph nodes, not attachable stage chats. Below 80 columns, the panel keeps its aggregate collapsed form and omits run IDs, stage identities, targets, and tool names.
 
-For chat surfaces such as workflow status, run detail, dispatch confirmation, and the run picker, a full id wraps onto continuation rows when the card is narrower than the id. The renderer never ellipsizes the id and keeps the card border closed at its minimum layout width, while terminals below that floor — including sub-30-column terminals — can hard-clip the box. An awaiting-input attribution banner is titled `AWAITING INPUT` and contains the same two identity rows — `？` plus the full run id, then the workflow name and optional metadata — while the existing prompt question and options remain below it in the normal prompt UI.
+For chat surfaces such as workflow status, run detail, dispatch confirmation, and the run picker, a full id wraps onto continuation rows when the card is narrower than the id. Pending-stage targets in run detail use the same rule: the exact address wraps instead of being ellipsized, and narrow status cards wrap the canonical stage ID or drop its display-name decoration rather than rendering a partial ID. The renderer keeps the card border closed at its minimum layout width, while terminals below that floor — including sub-30-column terminals — can hard-clip the box. An awaiting-input attribution banner is titled `AWAITING INPUT` and contains the same two identity rows — `？` plus the full run id, then the workflow name and optional metadata — while the existing prompt question and options remain below it in the normal prompt UI.
 
 The `/workflow connect` run picker shows five runs at a time; use the arrow keys or mouse wheel to scroll through additional retained runs.
 
@@ -984,7 +984,7 @@ Author workflows to create at least one tracked execution node by calling `ctx.t
 
 ### Source layout for authored workflows
 
-Keep a small, readable workflow in one entry file. Do not split short one-use prompts, create one file per stage, add wrapper-only modules, hide the graph across files, or use line counts alone as a module boundary.
+Keep a small, readable workflow in one entry file and write it for human maintainers. Keep the graph and control flow visible in the top-level workflow entry file, use stage names that state each stage's responsibility, and make its inputs, outputs, evidence, and success contract explicit. A developer reading the entry file from top to bottom should be able to identify the graph, branches, gates, artifacts, and stop conditions. Avoid both monolithic prompt blobs and gratuitous fragmentation: do not split short one-use prompts, create one file per stage, add wrapper-only modules, hide the graph across files, or use line counts alone as a module boundary.
 
 When a meaningful source boundary improves clarity, reuse, ownership, or testability, keep the graph and control flow in the top-level workflow entry file and extract cohesive concerns:
 
@@ -1007,6 +1007,12 @@ The repository uses this shape in `.atomic/workflows/release-docs.ts`: the entry
 
 The subdirectory is for cohesive, reusable support code, not a requirement to give every prompt or stage its own file.
 
+### Workflow and extension responsibilities
+
+Evaluate Atomic extension hooks when a workflow needs fine-grained, cross-cutting tool or session event control. Workflow TypeScript owns the inspectable DAG, stages, handoffs, durable `ctx.tool` side effects, and gates. Extension hooks own cross-cutting session and model-tool policy such as `tool_call` interception, input mutation, or blocking; `tool_result` transformation; context and provider hooks; lifecycle observation; or reusable custom tools. Use hooks only when cross-stage or cross-workflow event control is materially clearer than embedding the policy in each stage. Do not require a companion extension for ordinary workflow logic. See the authoritative [extension event documentation](/extensions#events) for hook contracts and ordering.
+
+When a workflow depends on a companion extension, make that dependency explicit and package and document the extension with the workflow. If stages use `tools` allowlists, include any custom tools provided by the extension. Document the hook-driven behavior and keep the graph, stage contracts, artifacts, gates, and stop conditions visible in the workflow entry file so readers can distinguish inspectable workflow orchestration from event policy.
+
 ### Dynamic topology must remain acyclic
 
 Atomic `workflow({ run })` definitions are imperative, dynamic TypeScript. The final graph is materialized only while `run(ctx)` executes and may depend on runtime inputs, branches, loops, files or network data, model or human output, helpers, and nested workflows. Discovery can report module import and definition-shape diagnostics: it loads the module, checks its exports, schemas, and `run` function, and rejects failures observable at that point. It does not execute every control-flow path or compile `run` into a complete graph. TypeScript and discovery cannot prove arbitrary dynamic acyclicity.
@@ -1579,7 +1585,7 @@ Ordinary `intercom` is mandatory in every workflow model stage. `noTools: "all"`
 - Never make a guard watch itself, recursively start another guard, reopen a terminal task, or add a dependency from the current frontier to an ancestor. Complete all turns on a retained guard before starting downstream dependency work.
 - Messages admitted before a worker generation closes drain through that stage boundary. Late messages do not reopen or mutate its terminal workflow state. Give each live branch a bounded stop rule; `ctx.parallel(...)` releases downstream work only after all started branches settle, even when one finishes first.
 - Persist decisions under stable keys. Pause/resume, model fallback, durable replay, and nested workflows then reread the artifact instead of sending duplicate interventions.
-- Omit `group` for ordinary use. The worker, guard, nested workflows, and delegated subagents inherit the top-level workflow invocation's stable Intercom group. Set an explicit group only for intentional isolation; an override separates that stage from ordinary same-group peers.
+- Omit `group` for ordinary use. The worker, guard, nested workflows, and delegated subagents inherit the top-level workflow invocation's stable Intercom group. Set an explicit group only for intentional isolation; an override isolates that stage from ordinary same-group peers while leaving it steerable from the invocation context, which retains directional list/send/live-ask control over the subgroups it owns.
 - Use `context: "fresh"` for guards, reviewers, and judges. They should see only the contract, candidate, decision artifacts, and current files.
 - Use `context: "fork"` plus `forkFromSessionFile` for implementation, debugging, and repair roles that need continuity with an owned earlier session. `context: "fork"` alone does not name a fork source; an initial worker with no prior lineage may start fresh. A later continuation should use the earlier worker's `sessionFile` when available. Do not fork an independent guard from the worker it judges.
 - Send a forked continuation only the delta after the fork point: new evidence, the decision artifact, any human answer, and the next action. Keep the full shared contract in its canonical file.
@@ -2423,9 +2429,9 @@ readonly group?: string | true;
 
 Sets the stage session's [Intercom](/intercom) home group. Every top-level workflow invocation receives a stable, non-`"default"` runtime group derived from its persistent run identity. Intercom-capable stages inherit that group when `group` is omitted, including stages in nested workflows. The group stays stable across model fallback, pause/resume, and durable replay, while separate top-level invocations receive different groups.
 
-`group` is accepted on `stage`/`task` options, on `ctx.parallel(...)` options, and per parallel step. Explicit values override the workflow invocation group; a step-level value also overrides its parallel-set value. A named string joins that group, including `group: "default"` to opt into the shared default group. Boolean `true` auto-generates one shared UUID group **per `ctx.parallel(...)` set** (minted once for every item in that set), while `true` on a non-parallel stage creates a fresh stage-only group. The trimmed, case-insensitive string sentinels `"true"` and `"auto"` have the same automatic behavior and are reserved.
+`group` is accepted on `stage`/`task` options, on `ctx.parallel(...)` options, and per parallel step. Explicit values override the workflow invocation group; a step-level value also overrides its parallel-set value. A named string becomes an **invocation-owned subgroup** resolved to `workflow:<rootRunId>/<name>`, so the same authored name in two concurrent runs never collides. Boolean `true` auto-generates one shared UUID group **per `ctx.parallel(...)` set** (minted once for every item in that set) and is namespaced the same way, while `true` on a non-parallel stage creates a fresh stage-only subgroup. The trimmed, case-insensitive string sentinels `"true"` and `"auto"` have the same automatic behavior and are reserved. `group: "default"` is the one exception: it opts into the shared default group, is **not** invocation-owned, and does not receive pending invocation delivery.
 
-The full precedence is: explicit stage/task/parallel group > workflow invocation group > `ATOMIC_INTERCOM_GROUP` (or legacy `PI_INTERCOM_GROUP`) > Intercom config > `"default"`. Every workflow model stage receives its workflow invocation group because ordinary Intercom is mandatory. Tool restrictions do not suppress that group; explicit `group` values retain their existing precedence. Subagents inherit their launching stage's resolved group by default (see [subagents.md](/subagents)). The subagent-only `contact_supervisor` channel keeps its broker-authorized cross-group route; ordinary client sends remain group-bound.
+The full precedence is: explicit stage/task/parallel group > workflow invocation group > `ATOMIC_INTERCOM_GROUP` (or legacy `PI_INTERCOM_GROUP`) > Intercom config > `"default"`. Every workflow model stage receives its workflow invocation group because ordinary Intercom is mandatory. Tool restrictions do not suppress that group; explicit `group` values retain their existing precedence. Subagents inherit their launching stage's resolved group by default (see [subagents.md](/subagents)). The subagent-only `contact_supervisor` channel keeps its broker-authorized cross-group route. Ordinary client sends remain group-bound, with one deliberate exception: the workflow invocation group has directional list/send/live-ask control over the subgroups it owns, so an isolated stage stays steerable from the invocation context. That authority does not run in reverse or sideways — a subgroup stage cannot use it to reach a sibling subgroup, and another run cannot use it at all.
 
 Authors do not need to generate or pass a group through ordinary stages, tasks, parallel steps, nested workflows, or delegated subagents. Use an explicit named group or `group: true` only to create an intentional subgroup, such as isolating one reviewer level from another.
 
@@ -3049,6 +3055,9 @@ Expiry aborts the request operation signal so work that supports cancellation ca
 
 From interactive chat, named workflow launches run in the background so the parent chat stays available. Run `/workflow connect <run>` to see agents working and chat with and steer each stage. Inspection, prompt-response, and control calls (`status`, `stages`, `stage`, `transcript`, `answer`, `pause`, `resume`, `interrupt`, `quit`) remain available while work runs.
 
+The no-`runId` status listing includes bounded pending-stage rows after each run summary. Each row gives the display name, canonical stage ID, literal `pending` lifecycle, `pendingStageDeliveryAvailable`, and either the exact usable Intercom target or `unavailable`. Interactive status cards and run detail show the same identity/availability distinction within their width budgets. Status cards wrap exact targets onto continuation rows instead of rendering a partially truncated address; bounded omissions retain an explicit remaining-stage count.
+
+
 `workflow({ action: "models" })` returns the registry's configured-auth catalog snapshot in registry order. Each entry includes `provider`, `id`, `fullId`, an `isCurrent` marker, and `availableThinkingLevels` derived from the real model's `reasoning` and `thinkingLevelMap` metadata. This is not proof of credentials, entitlements, OAuth freshness, or live provider access, and it exposes no authentication details.
 
 Named launches wait only for **startup admission**, not for workflow completion. Atomic returns `status: "running"` after durable registration, reusable-worktree setup, and other pre-body setup succeed, while the workflow body and stages continue in the background. If setup fails before the workflow body is admitted — for example, `git_worktree_dir` points inside the invoking checkout — the original `workflow` tool call instead returns a structured `status: "failed"` result with the allocated full run id and concrete setup error. No background-start claim or orphan run is retained, so the caller can correct the inputs and retry immediately. Failures after admission remain ordinary background lifecycle outcomes reported through status and lifecycle notices.

package/npm-shrinkwrap.json

@@ -1,16 +1,16 @@
 {
 	"name": "@bastani/atomic",
-	"version": "0.9.18-alpha.2",
+	"version": "0.9.18-alpha.3",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "@bastani/atomic",
-			"version": "0.9.18-alpha.2",
+			"version": "0.9.18-alpha.3",
 			"license": "MIT",
 			"dependencies": {
-				"@bastani/atomic-natives": "0.9.18-alpha.2",
-				"@bastani/pi-ai": "0.9.18-alpha.2",
+				"@bastani/atomic-natives": "0.9.18-alpha.3",
+				"@bastani/pi-ai": "0.9.18-alpha.3",
 				"@dbos-inc/dbos-sdk": "4.25.14",
 				"@earendil-works/pi-agent-core": "^0.84.4",
 				"@earendil-works/pi-client": "^0.84.4",
@@ -517,18 +517,18 @@
 			}
 		},
 		"node_modules/@bastani/atomic-natives": {
-			"version": "0.9.18-alpha.2",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives/-/atomic-natives-0.9.18-alpha.2.tgz",
+			"version": "0.9.18-alpha.3",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives/-/atomic-natives-0.9.18-alpha.3.tgz",
 			"license": "MIT",
 			"optionalDependencies": {
-				"@bastani/atomic-natives-darwin-arm64": "0.9.18-alpha.2",
-				"@bastani/atomic-natives-darwin-x64": "0.9.18-alpha.2",
-				"@bastani/atomic-natives-linux-arm64-gnu": "0.9.18-alpha.2",
-				"@bastani/atomic-natives-linux-arm64-musl": "0.9.18-alpha.2",
-				"@bastani/atomic-natives-linux-x64-gnu": "0.9.18-alpha.2",
-				"@bastani/atomic-natives-linux-x64-musl": "0.9.18-alpha.2",
-				"@bastani/atomic-natives-win32-arm64-msvc": "0.9.18-alpha.2",
-				"@bastani/atomic-natives-win32-x64-msvc": "0.9.18-alpha.2"
+				"@bastani/atomic-natives-darwin-arm64": "0.9.18-alpha.3",
+				"@bastani/atomic-natives-darwin-x64": "0.9.18-alpha.3",
+				"@bastani/atomic-natives-linux-arm64-gnu": "0.9.18-alpha.3",
+				"@bastani/atomic-natives-linux-arm64-musl": "0.9.18-alpha.3",
+				"@bastani/atomic-natives-linux-x64-gnu": "0.9.18-alpha.3",
+				"@bastani/atomic-natives-linux-x64-musl": "0.9.18-alpha.3",
+				"@bastani/atomic-natives-win32-arm64-msvc": "0.9.18-alpha.3",
+				"@bastani/atomic-natives-win32-x64-msvc": "0.9.18-alpha.3"
 			},
 			"engines": {
 				"bun": ">=1.4.0",
@@ -536,8 +536,8 @@
 			}
 		},
 		"node_modules/@bastani/atomic-natives-darwin-arm64": {
-			"version": "0.9.18-alpha.2",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-darwin-arm64/-/atomic-natives-darwin-arm64-0.9.18-alpha.2.tgz",
+			"version": "0.9.18-alpha.3",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-darwin-arm64/-/atomic-natives-darwin-arm64-0.9.18-alpha.3.tgz",
 			"license": "MIT",
 			"os": [
 				"darwin"
@@ -548,8 +548,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-darwin-x64": {
-			"version": "0.9.18-alpha.2",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-darwin-x64/-/atomic-natives-darwin-x64-0.9.18-alpha.2.tgz",
+			"version": "0.9.18-alpha.3",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-darwin-x64/-/atomic-natives-darwin-x64-0.9.18-alpha.3.tgz",
 			"license": "MIT",
 			"os": [
 				"darwin"
@@ -560,8 +560,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-linux-arm64-gnu": {
-			"version": "0.9.18-alpha.2",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-arm64-gnu/-/atomic-natives-linux-arm64-gnu-0.9.18-alpha.2.tgz",
+			"version": "0.9.18-alpha.3",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-arm64-gnu/-/atomic-natives-linux-arm64-gnu-0.9.18-alpha.3.tgz",
 			"license": "MIT",
 			"os": [
 				"linux"
@@ -575,8 +575,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-linux-arm64-musl": {
-			"version": "0.9.18-alpha.2",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-arm64-musl/-/atomic-natives-linux-arm64-musl-0.9.18-alpha.2.tgz",
+			"version": "0.9.18-alpha.3",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-arm64-musl/-/atomic-natives-linux-arm64-musl-0.9.18-alpha.3.tgz",
 			"license": "MIT",
 			"os": [
 				"linux"
@@ -590,8 +590,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-linux-x64-gnu": {
-			"version": "0.9.18-alpha.2",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-x64-gnu/-/atomic-natives-linux-x64-gnu-0.9.18-alpha.2.tgz",
+			"version": "0.9.18-alpha.3",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-x64-gnu/-/atomic-natives-linux-x64-gnu-0.9.18-alpha.3.tgz",
 			"license": "MIT",
 			"os": [
 				"linux"
@@ -605,8 +605,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-linux-x64-musl": {
-			"version": "0.9.18-alpha.2",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-x64-musl/-/atomic-natives-linux-x64-musl-0.9.18-alpha.2.tgz",
+			"version": "0.9.18-alpha.3",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-x64-musl/-/atomic-natives-linux-x64-musl-0.9.18-alpha.3.tgz",
 			"license": "MIT",
 			"os": [
 				"linux"
@@ -620,8 +620,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-win32-arm64-msvc": {
-			"version": "0.9.18-alpha.2",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-win32-arm64-msvc/-/atomic-natives-win32-arm64-msvc-0.9.18-alpha.2.tgz",
+			"version": "0.9.18-alpha.3",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-win32-arm64-msvc/-/atomic-natives-win32-arm64-msvc-0.9.18-alpha.3.tgz",
 			"license": "MIT",
 			"os": [
 				"win32"
@@ -632,8 +632,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-win32-x64-msvc": {
-			"version": "0.9.18-alpha.2",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-win32-x64-msvc/-/atomic-natives-win32-x64-msvc-0.9.18-alpha.2.tgz",
+			"version": "0.9.18-alpha.3",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-win32-x64-msvc/-/atomic-natives-win32-x64-msvc-0.9.18-alpha.3.tgz",
 			"license": "MIT",
 			"os": [
 				"win32"
@@ -644,8 +644,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/pi-ai": {
-			"version": "0.9.18-alpha.2",
-			"resolved": "https://registry.npmjs.org/@bastani/pi-ai/-/pi-ai-0.9.18-alpha.2.tgz",
+			"version": "0.9.18-alpha.3",
+			"resolved": "https://registry.npmjs.org/@bastani/pi-ai/-/pi-ai-0.9.18-alpha.3.tgz",
 			"license": "MIT",
 			"dependencies": {
 				"@anthropic-ai/sdk": "0.91.1",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/atomic",
-  "version": "0.9.18-alpha.2",
+  "version": "0.9.18-alpha.3",
   "description": "Atomic coding agent CLI with read, bash, edit, write tools and session management",
   "type": "module",
   "atomicConfig": {
@@ -79,8 +79,8 @@
     "prepublishOnly": "bun run clean && bun run build && bun run shrinkwrap"
   },
   "dependencies": {
-    "@bastani/atomic-natives": "0.9.18-alpha.2",
-    "@bastani/pi-ai": "0.9.18-alpha.2",
+    "@bastani/atomic-natives": "0.9.18-alpha.3",
+    "@bastani/pi-ai": "0.9.18-alpha.3",
     "@dbos-inc/dbos-sdk": "4.25.14",
     "@earendil-works/pi-agent-core": "^0.84.4",
     "@earendil-works/pi-client": "^0.84.4",