@bastani/atomic 0.9.18-alpha.5 → 0.9.18-alpha.7

package/dist/builtin/intercom/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/intercom",
-  "version": "0.9.18-alpha.5",
+  "version": "0.9.18-alpha.7",
   "private": true,
   "description": "Atomic extension providing a private coordination channel between parent and child agent sessions. Fork of: https://github.com/nicobailon/pi-intercom",
   "contributors": [
@@ -44,7 +44,7 @@
   },
   "peerDependencies": {
     "@bastani/atomic": "*",
-    "@earendil-works/pi-tui": "^0.84.4"
+    "@earendil-works/pi-tui": "^0.85.1"
   },
   "peerDependenciesMeta": {
     "@bastani/atomic": {

package/dist/builtin/intercom/recoverable-disconnect.ts

@@ -0,0 +1,52 @@
+/**
+ * Classification for a *recoverable* Intercom broker disconnect.
+ *
+ * The client socket is gone, but the lightweight extension wrapper owns
+ * recovery: a failed lazy-initialization attempt is discarded, and the next
+ * call re-imports the heavy module and reconnects. Work the user did not ask
+ * for — session lifecycle events and background event relays — must therefore
+ * not render such a disconnect as a failure while that retry is still ahead.
+ * Explicit, user-initiated operations keep rejecting visibly.
+ *
+ * Classification is by construction, never by message text. Only errors this
+ * module creates carry the marker, so an identically worded error raised
+ * anywhere else — and every protocol, authentication, configuration, or
+ * non-recoverable initialization failure — stays actionable.
+ */
+
+/** Model-visible recovery direction for a stale broker socket. */
+export const RECOVERABLE_DISCONNECT_MESSAGE =
+	"Client disconnected. Retry the same Intercom call up to three times to reconnect.";
+
+/**
+ * Bound on the `cause` chain walk. Intercom wraps failures with `cause` on the
+ * relay and reply paths (`subagent-relay.ts` and `index-heavy.ts` both do), so
+ * a recoverable disconnect can arrive nested; the bound keeps a cyclic or
+ * adversarially deep chain from turning classification into a hang.
+ */
+const MAX_CAUSE_DEPTH = 8;
+
+interface RecoverableDisconnectMarker {
+	readonly intercomRecoverableDisconnect?: boolean;
+}
+
+/** Raised when an established broker socket is gone and lazy re-initialization can retry. */
+export class IntercomClientDisconnectedError extends Error implements RecoverableDisconnectMarker {
+	readonly intercomRecoverableDisconnect = true;
+
+	constructor(options?: ErrorOptions) {
+		super(RECOVERABLE_DISCONNECT_MESSAGE, options);
+		this.name = "IntercomClientDisconnectedError";
+	}
+}
+
+/** True only for an `IntercomClientDisconnectedError`, directly or as a bounded `cause` ancestor. */
+export function isRecoverableIntercomDisconnect(error: unknown): boolean {
+	let current: unknown = error;
+	for (let depth = 0; depth <= MAX_CAUSE_DEPTH; depth += 1) {
+		if (!(current instanceof Error)) return false;
+		if (current instanceof IntercomClientDisconnectedError) return true;
+		current = current.cause;
+	}
+	return false;
+}

package/dist/builtin/intercom/retry-policy.ts

@@ -0,0 +1,8 @@
+/** Existing maximum wait for an `ask` reply. */
+export const ASK_REPLY_TIMEOUT_MS = 10 * 60 * 1000;
+/** Bounded opportunity to repeat a typed recoverable-disconnect result after the ask wait. */
+export const RETRY_IDENTITY_RETRY_OPPORTUNITY_MS = 60 * 1000;
+/** An operation identity covers the full ask wait plus one explicit retry opportunity. */
+export const RETRY_IDENTITY_TTL_MS = ASK_REPLY_TIMEOUT_MS + RETRY_IDENTITY_RETRY_OPPORTUNITY_MS;
+/** Broker authority outlives client-held identities so a boundary retry cannot lose acceptance proof in transit. */
+export const DELIVERED_MESSAGE_TTL_MS = RETRY_IDENTITY_TTL_MS + RETRY_IDENTITY_RETRY_OPPORTUNITY_MS;

package/dist/builtin/intercom/skills/intercom/SKILL.md

@@ -75,24 +75,24 @@ intercom({ action: "list" })
 intercom({ action: "ask", to: "6332faab-1111-4222-8333-123456789abc", message: "Which option should I use?" })
 ```
 
-Live sessions accept an exact full Intercom session ID or exact case-insensitive name. For workflow stages, first use `intercom({ action: "list" })`: materialized stages appear as `PENDING` or `RUNNING` with canonical `<runId>:<stageId>` targets and actual groups. The invocation context can control owned isolated subgroups by exact target, while sibling subgroups and other runs remain isolated. Use queued `send` for `PENDING`; `ask` is supported only for `RUNNING`, where an exact correlated reply returns to the invocation asker.
+Live sessions accept an exact full Intercom session ID or exact case-insensitive name. For workflow stages, first join `workflow:<rootRunId>` and use `intercom({ action: "list" })`: materialized stages appear as `PENDING` or `RUNNING` with canonical `workflow:<rootRunId>/<segment>[/<segment>...]` targets and actual groups, followed by possible future targets with queued counts. The invocation context can control owned isolated subgroups by exact target, while sibling subgroups and other runs remain isolated. Use queued `send` for `PENDING` or future targets; `ask` is supported only for `RUNNING`, where an exact correlated reply returns to the invocation asker.
 
 ### Deliver to workflow stages that have not started
 
-Send material updates through Intercom to every affected workflow stage, including stages that have not started. Atomic queues messages for known pending stages and delivers them when their sessions initialize:
-
-Before steering a stage, join its invocation group. Use the Intercom `groups` action to discover it. Workflow invocation groups are named `workflow:<rootRunId>`.
+Send material updates through Intercom to every affected workflow stage, including stages that have not started. Before steering, join the invocation group `workflow:<rootRunId>` (discover it with the Intercom `groups` action), then use `intercom list` there to see live, pending, and possible future targets.
 
 ```typescript
 intercom({
   action: "send",
-  to: "<runId>:reviewer",
+  to: "workflow:<rootRunId>/reviewer",
   message: "Scope changed: preserve raw amendment text in the verification oracle."
 })
 // → queued, distinct from live-session delivered, with the FIFO position
 ```
 
-The stage receives the ordinary inbound Intercom message before its first model turn under **Messages received before you started**, with real sender identity and a `Sent:` timestamp. Only same-workflow-group sessions may queue messages. Each exact run/stage key holds at most 50 queued messages; the next send is refused rather than evicting one. Resume/replay, broker restart, and stage-attempt restart preserve exactly-once delivery. If the stage is skipped, cancelled, or becomes terminal before its session initializes, the message becomes undeliverable and acknowledgment-requesting senders receive a correlated failure. Do not use `ask`: Atomic returns `pending_stage_ask_unsupported` and recommends ordinary `send` instead of holding an unbounded waiter.
+Each path segment may be a stage name, a run id, or a glob: `*` matches one segment and may be embedded (`reviewer-*`), while `**` matches any depth. When shared scope or acceptance criteria change, broadcast one authoritative update to `workflow:<rootRunId>/**` (or a narrower pattern) rather than enumerating stages. The broadcast reaches every live stage immediately and remains sticky for every future matching stage, including nested children, until the root run terminates. Other name or pattern sends have the same every-future-match behavior.
+
+A syntactically valid target outside the persisted possible-stage set is accepted speculatively: the queued acknowledgment includes `notInKnownSet`. At terminal settlement, an entry that never delivered produces the correlated undeliverable notification; an entry delivered at least once does not. A stage receives queued messages through the ordinary inbound path before its first model turn under **Messages received before you started**, with real sender identity and a `Sent:` timestamp. Only same-workflow-group sessions may queue messages. Each target holds at most 50 queued messages; the next send is refused rather than evicting one. Resume/replay, broker restart, and stage-attempt restart preserve exactly-once delivery per message and materialized stage. Use `ask` only for a live target: pending, future, and pattern asks return `pending_stage_ask_unsupported`.
 
 ### Runtime named groups
 
@@ -242,7 +242,7 @@ Use constructive quorum when several fresh-context reviewers judge the same arti
 3. Change a verdict only through evidence, never deference. Each reviewer emits its own final structured verdict and records whether the round changed it and which evidence caused the change.
 4. Let the deterministic reducer count final votes; this pattern does not change quorum counts or the `stop_review_loop` contract.
 
-In Atomic workflows, each invocation has its own Intercom group, and parallel stages and delegated subagents inherit it when Intercom is available. Sibling reviewers can therefore coordinate without custom group wiring. See the [constructive quorum workflow pattern](../../../coding-agent/docs/workflows.md#common-workflow-patterns).
+In Atomic workflows, each invocation has its own Intercom group, and parallel stages and delegated subagents inherit it when Intercom is available. Sibling reviewers can therefore coordinate without custom group wiring. See the [constructive quorum workflow pattern](../../../coding-agent/docs/workflows/reliable-design.md#common-workflow-patterns).
 
 ## Key Differences
 
@@ -251,7 +251,7 @@ In Atomic workflows, each invocation has its own Intercom group, and parallel st
 | `join` | Adds or creates a named membership in place | Sessions need another shared routing group |
 | `leave` | Removes one named membership, or resets to home when omitted | Stop sharing one group or restore startup membership |
 | `groups` | Lists every available group with counts and membership markers | Discover a group instead of guessing its name |
-| `send` | Fire-and-forget to a live session, or durable `queued` delivery to `<runId>:<stageKey>` before a workflow stage starts | You don't need a response |
+| `send` | Fire-and-forget to a live session, or durable sticky delivery to `workflow:<rootRunId>/<segment>[/<segment>...]`; globs and `**` broadcasts cover live and future matches | You don't need a response |
 | `ask` | Blocks until a live recipient replies (10 min timeout); refused for an unstarted stage | You need an answer to continue |
 | `reply` | Responds to the active or pending inbound ask; `to` accepts an exact full session ID or exact session name | You were asked something and need to answer naturally |
 | `pending` | Lists unresolved inbound asks | You need to see who is waiting before replying |
@@ -493,7 +493,15 @@ if (!result.delivered) {
 
 ### Connection lost
 
-Sessions automatically reconnect if the broker restarts. If persistently disconnected:
+Sessions automatically reconnect if the broker restarts. If an explicit `send`, `ask`, or `reply` fails with the typed `Client disconnected` error, copy the opaque `retryToken` from the tool result and repeat the exact action and arguments with it. Make at most three claimed attempts. Never attach that token to a different action, target, message, attachment sequence, attachment presence (`attachments` omitted is not explicit `[]`), or reply thread, and omit it for every fresh operation—even a deliberately byte-identical one. Invalid, expired, foreign-session, mismatched, concurrent, exhausted, and settled claims fail without sending.
+
+The token keeps the original message ID and deadline (11 minutes from the initial attempt: the 10-minute ask window plus one minute). A claimed retry that returns `delivered: false`, `Session not found`, durable-authority uncertainty/capacity refusal, or another typed disconnect returns the same token for the next bounded claim; each claim consumes one attempt and never extends the deadline. Delivered or queued success settles it. Initial tokenless nondelivery and unrelated/non-recoverable failures do not create retry state.
+
+Broker acceptance is retained for 12 minutes, so acknowledgement loss does not duplicate delivery and a deduplicated ask remains replyable. Implicit public reply prefers the recorded exact sender ID while live and falls back to authorized reconnect resolution only after departure. A retained implicit reply keeps its original sender/question snapshot, so later inbound asks cannot redirect its token claim. Durable SQLite stores fixed keyed HMAC digests rather than message/attachment text; its paired key and database artifacts are owner-only on POSIX. Missing, malformed, uncertain, or capacity-bound authority fails closed rather than risking a duplicate.
+
+Retry safety is bounded: fresh client operations reserve one of 1,000 identity slots before confirmation, target resolution, or send, while valid existing claims remain usable at capacity. The broker and local result relay allow 10,000 live delivery records; the broker also bounds digest/routing authority to 64 MiB. At a limit Intercom refuses new work before its delivery side effect rather than evicting a still-valid identity.
+
+If the session remains disconnected after those retries:
 
 ```typescript
 intercom({ action: "status" })

package/dist/builtin/intercom/types.ts

@@ -25,10 +25,26 @@ export interface WorkflowStageRosterEntry {
 	readonly sessionId?: string;
 }
 
+export interface WorkflowPossibleStageAnnouncement {
+	/** Canonical depth-faithful path target, e.g. `workflow:<rootRunId>/orchestrator-*`. */
+	readonly target: string;
+	/** Current number of queued sticky entries matching this target. */
+	readonly queuedCount: number;
+}
+
+export interface WorkflowFutureStageRosterEntry {
+	readonly kind: "workflow-future-stage";
+	readonly runId: string;
+	readonly target: string;
+	readonly queuedCount: number;
+	readonly group: string;
+}
+
 export interface SessionDirectory {
 	readonly sessions: SessionInfo[];
-	readonly workflowStages: WorkflowStageRosterEntry[];
-}
+ 	readonly workflowStages: WorkflowStageRosterEntry[];
+	readonly workflowFutureStages: WorkflowFutureStageRosterEntry[];
+ }
 
 export interface WorkflowStageRosterAnnouncement {
 	readonly stageId: string;
@@ -84,6 +100,8 @@ export type ClientMessage =
 			session: Omit<SessionInfo, "id">;
 			/** Internal host-owned identity retained across broker reconnects. */
 			returnAddress?: string;
+			/** Immutable session origin; separate from mutable group memberships. Legacy clients use session.group. */
+			registrationGroup?: string;
 			supervisor?: SupervisorRegistration;
 			supervisorOwnerToken?: string;
 	  }
@@ -93,7 +111,7 @@ export type ClientMessage =
 	| { type: "join_group"; requestId: string; group: string }
 	| { type: "leave_group"; requestId: string; group?: string }
   | { type: "authorize_supervisor"; requestId: string; childName: string; capability?: string }
-  | { type: "send" | "supervisor_send"; to: string; message: Message; attemptId?: string }
+  | { type: "send" | "supervisor_send"; to: string; logicalTarget?: string; requirePendingReply?: true; message: Message; attemptId?: string }
 	| {
 			type: "send_pending_stage_notification";
 			runId: string;
@@ -105,7 +123,7 @@ export type ClientMessage =
 			attemptId?: string;
 	  }
 	| { type: "pending_stage_notification_result"; requestId: string; delivered: boolean }
-  | { type: "register_pending_stage_route"; runId: string; group: string; capability: string; stages?: WorkflowStageRosterAnnouncement[] }
+ | { type: "register_pending_stage_route"; runId: string; group: string; capability: string; stages?: WorkflowStageRosterAnnouncement[]; possibleStages?: WorkflowPossibleStageAnnouncement[] }
   | {
       type: "register_live_workflow_stage_route";
       requestId: string;
@@ -118,6 +136,7 @@ export type ClientMessage =
 		requestId: string;
 		outcome: "queued" | "delivered" | "forward" | "refused";
 		position?: number;
+		target?: string;
 		reason?: string;
 		reasonCode?: "message_id_conflict";
 	  }
@@ -135,7 +154,7 @@ export type ClientMessage =
 export type BrokerMessage =
   | { type: "registered"; sessionId: string; supervisorSessionId?: string }
   | { type: "registration_failed"; reason: string }
-  | { type: "sessions"; requestId: string; sessions: SessionInfo[]; workflowStages?: WorkflowStageRosterEntry[] }
+ | { type: "sessions"; requestId: string; sessions: SessionInfo[]; workflowStages?: WorkflowStageRosterEntry[]; workflowFutureStages?: WorkflowFutureStageRosterEntry[] }
 	| { type: "groups"; requestId: string; groups: GroupSummary[] }
 	| { type: "membership_ack"; requestId: string; groups: string[] }
   | { type: "supervisor_authorized"; requestId: string; capability: string; supervisorSessionId: string; childName: string }
@@ -148,7 +167,7 @@ export type BrokerMessage =
 			senderRegistrationName?: string;
 			senderReturnAddress?: string;
 			runId: string;
-			stageKey: string;
+			target: string;
 			message: Message;
 			live?: boolean;
 	  }
@@ -161,5 +180,5 @@ export type BrokerMessage =
   | { type: "presence_failed"; requestId: string; reason: string }
   | { type: "error"; error: string }
   | { type: "delivered"; messageId: string; attemptId?: string }
-  | { type: "queued"; messageId: string; attemptId?: string; runId: string; stageKey: string; position: number }
-	| { type: "delivery_failed"; messageId: string; reason: string; reasonCode?: "message_id_conflict"; attemptId?: string };
+	| { type: "queued"; messageId: string; attemptId?: string; target: string; position: number }
+	| { type: "delivery_failed"; messageId: string; reason: string; reasonCode?: "message_id_conflict" | "session_not_found"; attemptId?: string };

package/dist/builtin/intercom/workflow-stage-path-matching.ts

@@ -0,0 +1,90 @@
+/**
+ * Shared glob semantics for workflow stage path targets (slice 3, D2/D5/D6).
+ *
+ * This module is mirrored verbatim in
+ * `packages/workflows/src/shared/workflow-stage-path-matching.ts` (the broker must stay
+ * loadable with only Node built-ins and Intercom-local modules, and amendment A1 forbids
+ * cross-package imports). A parity test runs both implementations over one fixture table
+ * and asserts identical results; keep the two files byte-identical in behavior.
+ */
+
+/** Glob-match `candidateSegments` against `patternSegments`. */
+export function matchStagePathSegments(
+	patternSegments: readonly string[],
+	candidateSegments: readonly string[],
+): boolean {
+	return matchSegmentsFrom(patternSegments, 0, candidateSegments, 0);
+}
+
+/** Split an unprefixed stage path into its `/` segments. */
+export function splitStagePathSegments(path: string): string[] {
+	return path.split("/");
+}
+
+/** D4 membership (advisory, bidirectional) of a target path inside the persisted possible-stage set. */
+export function targetSegmentsInPossibleStages(
+	targetSegments: readonly string[],
+	possibleStages: readonly string[],
+): boolean {
+	return possibleStages.some((entry) => {
+		const entrySegments = splitStagePathSegments(entry);
+		return (
+			matchStagePathSegments(entrySegments, targetSegments) ||
+			matchStagePathSegments(targetSegments, entrySegments)
+		);
+	});
+}
+
+function matchSegmentsFrom(
+	pattern: readonly string[],
+	patternIndex: number,
+	candidate: readonly string[],
+	candidateIndex: number,
+): boolean {
+	let p = patternIndex;
+	let c = candidateIndex;
+	while (p < pattern.length) {
+		const segment = pattern[p]!;
+		if (segment === "**") {
+			for (let skip = c; skip <= candidate.length; skip += 1) {
+				if (matchSegmentsFrom(pattern, p + 1, candidate, skip)) return true;
+			}
+			return false;
+		}
+		if (c >= candidate.length) return false;
+		if (!matchSegmentGlob(segment, candidate[c]!)) return false;
+		p += 1;
+		c += 1;
+	}
+	return c === candidate.length;
+}
+
+function matchSegmentGlob(pattern: string, value: string): boolean {
+	if (!pattern.includes("*")) return pattern === value;
+	let p = 0;
+	let v = 0;
+	let star = -1;
+	let mark = -1;
+	while (v < value.length) {
+		if (p < pattern.length && pattern[p] === "*") {
+			star = p;
+			mark = v;
+			p += 1;
+			continue;
+		}
+		if (p < pattern.length && pattern[p] === value[v]) {
+			p += 1;
+			v += 1;
+			continue;
+		}
+		if (star >= 0) {
+			p = star + 1;
+			mark += 1;
+			v = mark;
+			continue;
+		}
+		return false;
+	}
+	while (p < pattern.length && pattern[p] === "*") p += 1;
+	return p === pattern.length;
+}

package/dist/builtin/intercom/workflow-stage-target.ts

@@ -0,0 +1,57 @@
+const WORKFLOW_RUN_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const WORKFLOW_TARGET_PREFIX = "workflow:";
+
+export type WorkflowStageTargetKind = "path" | "pattern" | "deep-pattern";
+
+export interface WorkflowStageTarget {
+	readonly rootRunId: string;
+	readonly segments: string[];
+	readonly kind: WorkflowStageTargetKind;
+}
+
+export interface LegacyWorkflowStageTarget {
+	readonly runId: string;
+	readonly stageKey: string;
+}
+
+/** Parse the canonical root-anchored workflow-stage target grammar. */
+export function parseWorkflowStageTarget(target: string): WorkflowStageTarget | undefined {
+	if (!target.startsWith(WORKFLOW_TARGET_PREFIX)) return undefined;
+	const slash = target.indexOf("/", WORKFLOW_TARGET_PREFIX.length);
+	if (slash < 0) return undefined;
+	const rootRunId = target.slice(WORKFLOW_TARGET_PREFIX.length, slash);
+	if (!WORKFLOW_RUN_ID_PATTERN.test(rootRunId)) return undefined;
+	const segments = target.slice(slash + 1).split("/");
+	if (segments.length === 0 || segments.some((segment) => segment.length === 0)) return undefined;
+	const kind = segments.includes("**")
+		? "deep-pattern"
+		: segments.some((segment) => segment.includes("*"))
+			? "pattern"
+			: "path";
+	return { rootRunId, segments, kind };
+}
+
+/** Detect the removed pre-D8 `<runId>:<stageKey>` grammar for migration errors only. */
+export function parseLegacyWorkflowStageTarget(target: string): LegacyWorkflowStageTarget | undefined {
+	const separator = target.indexOf(":");
+	if (separator < 0) return undefined;
+	const runId = target.slice(0, separator);
+	const stageKey = target.slice(separator + 1);
+	return WORKFLOW_RUN_ID_PATTERN.test(runId) && stageKey.length > 0 ? { runId, stageKey } : undefined;
+}
+
+export function formatWorkflowStageTarget(rootRunId: string, ...segments: readonly string[]): string {
+	return `${WORKFLOW_TARGET_PREFIX}${rootRunId}/${segments.join("/")}`;
+}
+
+export function withWorkflowStageTargetFinalSegment(target: string, segment: string): string | undefined {
+	const parsed = parseWorkflowStageTarget(target);
+	if (parsed === undefined || segment.length === 0 || segment.includes("/")) return undefined;
+	return formatWorkflowStageTarget(parsed.rootRunId, ...parsed.segments.slice(0, -1), segment);
+}
+
+export function legacyWorkflowStageTargetMigrationHint(canonicalTarget?: string): string {
+	const base =
+		"Legacy workflow-stage targets in the `<runId>:<stageKey>` form are no longer supported. Use the canonical `workflow:<rootRunId>/<segment>` path form.";
+	return canonicalTarget === undefined ? base : `${base} Use \`${canonicalTarget}\` for this stage.`;
+}