@bastani/atomic 0.9.13-alpha.1 → 0.9.13-alpha.3

package/dist/builtin/i-have-adhd/index.ts

@@ -0,0 +1,238 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+	buildContextEntries,
+	getAgentDir,
+	type ExtensionAPI,
+	type ExtensionContext,
+	type InputEvent,
+	type InputEventResult,
+	type SessionCompactEvent,
+	type SessionStartEvent,
+	type SessionTreeEvent,
+} from "@bastani/atomic";
+
+export type IHaveAdhdExtensionContext = Pick<ExtensionContext, "hasUI" | "sessionManager"> & {
+	ui: Pick<ExtensionContext["ui"], "notify" | "setStatus"> & {
+		theme: Pick<ExtensionContext["ui"]["theme"], "fg">;
+	};
+};
+
+type IHaveAdhdHandler<E, R = undefined> = (event: E, ctx: IHaveAdhdExtensionContext) => Promise<R | void> | R | void;
+
+export type IHaveAdhdExtensionAPI = Pick<
+	ExtensionAPI,
+	"appendEntry" | "getFlag" | "registerCommand" | "registerFlag" | "sendMessage"
+> & {
+	on(event: "input", handler: IHaveAdhdHandler<InputEvent, InputEventResult>): void;
+	on(event: "session_compact", handler: IHaveAdhdHandler<SessionCompactEvent>): void;
+	on(event: "session_start", handler: IHaveAdhdHandler<SessionStartEvent>): void;
+	on(event: "session_tree", handler: IHaveAdhdHandler<SessionTreeEvent>): void;
+};
+
+const EXTENSION_DIR = dirname(fileURLToPath(import.meta.url));
+const SKILL_PATH = join(EXTENSION_DIR, "skills", "i-have-adhd", "SKILL.md");
+const STATE_ENTRY_TYPE = "i-have-adhd-state";
+const RULES_MESSAGE_TYPE = "i-have-adhd-rules";
+const DISABLED_MESSAGE_TYPE = "i-have-adhd-disabled";
+const STATUS_KEY = "i-have-adhd";
+const DISABLE_CONFIRMATION = "ADHD mode disabled.";
+const STOP_PHRASES = new Set(["stop adhd mode", "normal mode"]);
+const RULES_HEADER =
+	'ADHD MODE ACTIVE. The ruleset below applies to every response until turned off. "stop adhd mode" or "normal mode" turns it off for this session.';
+const DISABLED_NOTICE =
+	"ADHD MODE OFF. Ignore the i-have-adhd ruleset injected earlier in this conversation and return to your default response style.";
+
+type AdhdModeState = {
+	enabled: boolean;
+};
+
+function stripFrontmatter(content: string): string {
+	return content
+		.replace(/^---[^\S\r\n]*\r?\n[\s\S]*?\r?\n---[^\S\r\n]*(?:\r?\n|$)/, "")
+		.trim();
+}
+
+function loadRules(): string {
+	let content: string;
+
+	try {
+		content = readFileSync(SKILL_PATH, "utf8");
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : String(error);
+		throw new Error(`Unable to load i-have-adhd rules from ${SKILL_PATH}: ${reason}`);
+	}
+
+	const rules = stripFrontmatter(content);
+	if (!rules) {
+		throw new Error(`The i-have-adhd rules file is empty: ${SKILL_PATH}`);
+	}
+
+	return rules;
+}
+
+function getSavedState(ctx: IHaveAdhdExtensionContext): boolean | undefined {
+	let savedState: boolean | undefined;
+
+	for (const entry of ctx.sessionManager.getBranch()) {
+		if (entry.type !== "custom" || entry.customType !== STATE_ENTRY_TYPE) {
+			continue;
+		}
+
+		const data = entry.data as Partial<AdhdModeState> | undefined;
+		if (typeof data?.enabled === "boolean") {
+			savedState = data.enabled;
+		}
+	}
+
+	return savedState;
+}
+
+/**
+ * Whether the rules are still live in the context the model actually receives.
+ *
+ * Only the newest marker counts: a later "disabled" notice cancels an earlier
+ * ruleset, and compaction drops summarized entries so the ruleset has to be
+ * injected again.
+ */
+function rulesAreInContext(ctx: IHaveAdhdExtensionContext): boolean {
+	let active = false;
+
+	for (const entry of buildContextEntries(ctx.sessionManager.getEntries(), ctx.sessionManager.getLeafId())) {
+		if (entry.type !== "custom_message") continue;
+
+		if (entry.customType === RULES_MESSAGE_TYPE) {
+			active = true;
+		} else if (entry.customType === DISABLED_MESSAGE_TYPE) {
+			active = false;
+		}
+	}
+
+	return active;
+}
+
+export default function iHaveAdhdExtension(pi: IHaveAdhdExtensionAPI) {
+	const rules = loadRules();
+	const disabledFlag = join(getAgentDir(), ".i-have-adhd-off");
+	let enabled = false;
+
+	const updateStatus = (ctx: IHaveAdhdExtensionContext): void => {
+		if (!enabled) {
+			ctx.ui.setStatus(STATUS_KEY, undefined);
+			return;
+		}
+
+		const dot = ctx.ui.theme.fg("success", "●");
+		const label = ctx.ui.theme.fg("accent", "ADHD Mode");
+		ctx.ui.setStatus(STATUS_KEY, `${dot} ${label}`);
+	};
+
+	/**
+	 * Keep the conversation in sync with the current mode, the way the Claude Code
+	 * SessionStart hook does: inject the ruleset once, never per request.
+	 */
+	const syncContext = (ctx: IHaveAdhdExtensionContext): void => {
+		const injected = rulesAreInContext(ctx);
+
+		if (enabled && !injected) {
+			pi.sendMessage(
+				{
+					customType: RULES_MESSAGE_TYPE,
+					content: `${RULES_HEADER}\n\n${rules}`,
+					display: false,
+				},
+				{ triggerTurn: false },
+			);
+			return;
+		}
+
+		if (!enabled && injected) {
+			pi.sendMessage(
+				{
+					customType: DISABLED_MESSAGE_TYPE,
+					content: DISABLED_NOTICE,
+					display: false,
+				},
+				{ triggerTurn: false },
+			);
+		}
+	};
+
+	const restoreState = (ctx: IHaveAdhdExtensionContext): void => {
+		const savedState = getSavedState(ctx);
+		const explicitlyDisabled = pi.getFlag("no-adhd") === true || existsSync(disabledFlag);
+
+		enabled = savedState ?? !explicitlyDisabled;
+		updateStatus(ctx);
+		syncContext(ctx);
+	};
+
+	const setEnabled = (nextEnabled: boolean, ctx: IHaveAdhdExtensionContext): void => {
+		enabled = nextEnabled;
+		pi.appendEntry(STATE_ENTRY_TYPE, { enabled } satisfies AdhdModeState);
+		updateStatus(ctx);
+		syncContext(ctx);
+		ctx.ui.notify(`ADHD mode ${enabled ? "enabled" : "disabled"}`, "info");
+	};
+
+	pi.registerFlag("no-adhd", {
+		description: "Start with ADHD-friendly output disabled",
+		type: "boolean",
+		default: false,
+	});
+
+	pi.registerCommand("i-have-adhd", {
+		description: "Toggle ADHD-friendly output for this session",
+		handler: async (args, ctx) => {
+			const argument = args.trim().toLowerCase();
+
+			if (argument === "") {
+				setEnabled(!enabled, ctx);
+				return;
+			}
+
+			if (argument === "on") {
+				setEnabled(true, ctx);
+				return;
+			}
+
+			if (argument === "off" || argument === "stop") {
+				setEnabled(false, ctx);
+				return;
+			}
+
+			ctx.ui.notify("Usage: /i-have-adhd [on|off]", "warning");
+		},
+	});
+
+	pi.on("input", async (event, ctx) => {
+		const input = event.text.trim().toLowerCase();
+
+		// Keep the built-in skill command working as an alias without letting Pi
+		// expand a second copy of the same rules into the conversation.
+		if (input === "/skill:i-have-adhd") {
+			setEnabled(true, ctx);
+			return { action: "handled" };
+		}
+
+		if (enabled && STOP_PHRASES.has(input)) {
+			setEnabled(false, ctx);
+
+			if (ctx.hasUI) {
+				return { action: "handled" };
+			}
+
+			return {
+				action: "transform",
+				text: `Reply with exactly: ${DISABLE_CONFIRMATION}`,
+			};
+		}
+
+		return { action: "continue" };
+	});
+
+	pi.on("session_start", async (_event, ctx) => restoreState(ctx));
+	pi.on("session_tree", async (_event, ctx) => restoreState(ctx));
+	pi.on("session_compact", async (_event, ctx) => syncContext(ctx));
+}

package/dist/builtin/i-have-adhd/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@bastani/i-have-adhd",
+  "version": "0.9.13-alpha.3",
+  "private": true,
+  "description": "Atomic extension that shapes responses for readers with ADHD. Fork of: https://github.com/ayghri/i-have-adhd",
+  "contributors": [
+    "Ayoub Ghriss",
+    "Norin Lavaee",
+    "Alex Lavaee"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "main": "./index.ts",
+  "types": "./index.ts",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "files": [
+    "*.ts",
+    "skills/**/*",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "atomic-package",
+    "pi-package"
+  ],
+  "atomic": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "peerDependencies": {
+    "@bastani/atomic": "*"
+  },
+  "peerDependenciesMeta": {
+    "@bastani/atomic": {
+      "optional": true
+    }
+  }
+}

package/dist/builtin/i-have-adhd/skills/i-have-adhd/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: i-have-adhd
+description: 'Shape output for a reader with ADHD: lead with the next action, number multi-step work, restate state across turns, suppress tangents, give specific time estimates, make wins visible. Invoke with /i-have-adhd; stays on until "stop adhd mode".'
+disable-model-invocation: true
+license: MIT
+metadata:
+  tags: "ADHD, Output Style, Productivity, Formatting"
+  category: "productivity"
+---
+
+# i-have-adhd
+
+The reader has ADHD. Output is not just brief. It is shaped so an ADHD brain can act on it.
+
+## Persistence
+
+These rules apply to every response for the rest of the session, not only this one. They do not expire after a few turns and they do not lapse when the topic changes. If you are unsure whether they still apply, they do.
+
+Turn them off only when the reader says "stop adhd mode" or "normal mode". Confirm in one line, then return to your default style.
+
+## What ADHD changes about reading
+
+Five facts drive every rule below:
+
+1. Working memory is small. Anything not on screen is forgotten. Do not ask the reader to "keep in mind X."
+2. Knowing the answer is not doing the answer. The friction between "got it" and "done it" is where work dies.
+3. Starting is the hardest step. The first action must be obvious, small, and doable now.
+4. Time estimates feel uniform. "A bit of work" and "a few hours" register the same. Vague estimates fail.
+5. Dopamine is scarce. Visible progress matters. Buried wins do not register.
+
+## Rules
+
+### 1. Lead with the next action
+
+The first line is something the reader can do. Not context. Not a plan. The action.
+
+Bad: "Let's think about this. Your auth flow has a few moving pieces..."
+Good: "Run `npm install jsonwebtoken`, then edit `src/auth.ts:42`."
+
+If the answer is a command, path, or snippet, it goes first. Prose comes after, if at all.
+
+### 2. Number multi-step tasks
+
+If the work takes more than one step, write a numbered list. Each step is one bounded action. No step contains "and then" twice.
+
+Use the fewest steps that still work. Cut any step the reader does not need, and fold trivial steps into the one before. A short path finished beats a complete path abandoned.
+
+Bad: "First open the file, find the function, swap it out, then run the tests."
+
+Good:
+```
+1. Open `src/auth.ts`
+2. Replace `verifyToken` (lines 42 to 58) with the snippet below
+3. Run `npm test -- auth.spec.ts`
+```
+
+### 3. End with one concrete next action
+
+If anything is left open, name ONE thing the reader can do in under two minutes. Even "open the file" counts.
+
+Bad: "Hope that helps. Let me know if you want to dig deeper."
+Good: "Next: run `npm test` and paste the first failing line."
+
+### 4. Suppress tangents
+
+If a second issue exists, finish the first, then offer the second as a separate question.
+
+Bad: "Here's the fix. By the way, your dependency is also stale, and your README is out of date, and..."
+Good: "Here's the fix. Separately: there is also a stale dependency. Want me to handle that next?"
+
+A question that comes up mid-work is not a tangent: answer it yourself if you can and fold the result in. If it still needs the reader, surface it once, at the end.
+
+### 5. Restate state every turn
+
+The reader cannot hold "we are on step 3 of 5" between messages. Restate it.
+
+Bad: "Done. Ready for the next part?"
+Good: "Step 3 of 5 done: schema updated. Next: backfill the new column. Run the script?"
+
+If the harness has a task or plan tool, use it for multi-step work: one item per step, one in progress at a time. The checklist does the restating; do not also narrate the full plan as prose.
+
+### 6. Give specific time estimates
+
+Vague estimates fail. Ballpark in concrete units.
+
+Bad: "This will take some work."
+Good: "About 15 minutes if tests already cover this. An afternoon if not."
+
+### 7. Make completed work visible
+
+Show what now works, in concrete terms. Do not bury wins in a recap.
+
+Bad: "I've made some changes to the auth flow. Among other things..."
+Good: "Login now works with magic links. Try: `npm run dev`, open `/login`."
+
+### 8. Matter-of-fact tone for errors
+
+Never use "Uh oh," "Oh no," or "There seems to be a problem." State cause and fix.
+
+Bad: "Uh oh, the test is failing. There seems to be an issue..."
+Good: "Test fails at `auth.spec.ts:42`: expected 200, got 401. Cause: missing auth header. Fix: add `Authorization: Bearer ${token}` to the request."
+
+### 9. Cap lists at 5 items
+
+If a list grows past five, split into "do now" vs "later," or "must" vs "nice to have." Five items ranked beats ten unranked.
+
+### 10. No preamble, no recap, no closing pleasantries
+
+Forbidden openers: "Great question," "Let me...", "I'll...", "Sure!", "Looking at your...", "To answer your question..."
+
+Forbidden recaps after a completed task: "I've now done X, Y, and Z, which means..."
+
+Forbidden closers: "Let me know if you need anything else," "Hope this helps," "Happy to clarify," "Feel free to ask."
+
+Start with the answer. End when the answer is done.
+
+## When to break the rules
+
+Override the defaults when:
+
+1. User asks to "explain" or "walk me through." Explain fully. Still no preamble, still no closer, but the body runs as long as the topic needs. Add headers so the reader can skim back.
+2. Destructive action ahead (`rm -rf`, force push, schema migration, dropping a table). Confirm before acting. Safety wins over brevity.
+3. Debug spiral. If the last three turns have been "still broken," stop iterating on code. Name the assumption that might be wrong. Ask one diagnostic question.
+4. Real ambiguity in the request. One short clarifying question beats guessing and rewriting.
+5. A rule fights the task. When a rule would delete the answer itself, the task wins; the shape stays. Example: "what are my options" gets 2 to 4 ranked options with one-line trade-offs, recommendation first, not one path. The options are the answer.
+6. A rule fights the harness. Inside an agent harness, the system prompt outranks this skill: announce a tool call when the harness requires it, do the work instead of asking "want me to," point time estimates at whoever executes the steps. Same principle as 5: the constraint wins, the shape stays.
+
+## Pre-send check
+
+Before sending, delete:
+
+1. The first sentence if it announces what you are about to do.
+2. The last sentence if it asks "anything else?" or recaps what just happened.
+3. Any "by the way" sidebar.
+4. Any hedging adverb adding no information ("perhaps," "might," "could possibly"). Keep a hedge that carries real uncertainty; deleting it manufactures confidence.
+5. Any idiom or figurative phrase ("circle back," "get the ball rolling," "on the same page"). Replace with the literal action.
+
+Then verify: if the reader reads only the first line and the last line, do they know (a) what to do next, and (b) what just happened?
+
+If yes, send.

package/dist/builtin/intercom/CHANGELOG.md

@@ -4,6 +4,39 @@ All notable changes to the `pi-intercom` extension will be documented in this fi
 
 ## [Unreleased]
 
+## [0.9.13-alpha.3] - 2026-08-13
+
+### Breaking Changes
+
+- Removed unique-ID-prefix targeting. `send`, `ask`, and `reply` now accept only an exact full session ID or an exact case-insensitive session name.
+
+### Changed
+
+- Intercom now displays full session and message IDs everywhere: list rows, the session-list overlay, inbound message headers, reply-to lines, message-id result badges, and unnamed-session `subagent-chat-<id>` aliases.
+
+### Fixed
+
+- Fixed the session-list overlay clipping full session IDs at narrow terminal widths by wrapping IDs onto dim rows and marking unavoidable truncation with a visible ellipsis; inline sender and reply-to IDs now also signal overflow.
+
+## [0.9.13-alpha.2] - 2026-08-12
+
+### Changed
+
+- Detached intercom broker processes now receive `AI_AGENT=atomic` for generic child-process attribution.
+- Added runtime `intercom` `join` and `leave` actions for named group membership. Joining updates broker presence without changing the session ID, keeps `send`/`ask` group-isolated, lets later subagents inherit the joined group, and reports success only after broker acknowledgement; `default` remains explicit while `true` and `auto` stay reserved for generated subagent groups ([#2334](https://github.com/bastani-inc/atomic/issues/2334)).
+
+### Fixed
+- Fixed Intercom relay and detach-handshake callbacks that finish after an extension reload. Stale event-bus emissions and subscription cleanup are now best-effort, so runtime replacement does not turn a late delivery into an unhandled rejection.
+- Fixed late Intercom callbacks using a stale extension runtime by using the host's exported stale-context predicate instead of a duplicated error-message marker.
+
+- Fixed the intercom broker failing to start on standalone-binary installs, where every `intercom` call and every `subagent` delegation failed with `Intercom not connected: Intercom broker exited before startup with code 1`. The broker is a detached subprocess, so it never inherits the host extension loader's `@bastani/atomic` alias, and release archives ship no physical copy of that optional peer; `group.ts` now reads `ATOMIC_INTERCOM_GROUP` (and the legacy `PI_INTERCOM_GROUP`) locally instead of importing the host package. A defined-but-empty `ATOMIC_INTERCOM_GROUP` still shadows the legacy name, exactly as before ([#2208](https://github.com/bastani-inc/atomic/issues/2208)).
+- Removing that import also keeps the entire coding-agent module graph out of broker startup on every platform, not only standalone installs: measured spawn-to-socket-connectable startup went from 1104 ms minimum / 1318 ms average to 85 ms / 96 ms on Node with tsx, and from 252 ms / 260 ms to 17 ms / 18 ms on Bun ([#2208](https://github.com/bastani-inc/atomic/issues/2208)).
+- Broker stderr is no longer discarded. It is captured to `broker.log` in the agent's intercom directory through an already-open file descriptor (not a pipe, which cannot outlive the parent that spawned the detached broker), and both the "exited before startup" error and the readiness-timeout error now quote the log path and a bounded tail of that output. The Windows hidden launcher appends the broker's own stderr to the same file ([#2208](https://github.com/bastani-inc/atomic/issues/2208)).
+- The startup log is capped at 8 KiB rather than growing without limit. The parent truncates it on every spawn, but the parent exits while the detached broker keeps running, so the broker applies the cap itself. External truncation would not work — a POSIX append descriptor writes at the new end of file, and the inherited Windows append handle has no truncate right ([#2208](https://github.com/bastani-inc/atomic/issues/2208)).
+- The cap is installed by the broker entrypoint's first import, before any other module of the broker evaluates. ESM runs a module's static dependencies ahead of the importer's own body, so installing from the entrypoint body left every dependency free to write first: an oversized write while a dependency initialized produced a 32,768-byte log, and a throw during initialization produced 34,372 bytes ([#2208](https://github.com/bastani-inc/atomic/issues/2208)).
+- The cap covers all three routes that reach the log, not only the stream: `process.stderr.write`, `console.error` / `console.warn`, and the default fatal printing for an uncaught exception or an unhandled rejection. Measured against an 8 KiB cap with only the stream patched, a Bun `console.error` left 32,769 bytes, a Bun uncaught error 33,228 bytes, a Bun unhandled rejection 33,326 bytes, and a Node unhandled rejection 33,620 bytes; all four now stay at or below the cap ([#2208](https://github.com/bastani-inc/atomic/issues/2208)).
+- Broker readiness now polls at 10 ms with bounded backoff up to the previous 100 ms interval instead of sleeping a flat 100 ms after every attempt, which had become the dominant cost of a startup that finishes in tens of milliseconds. The overall startup timeout is unchanged ([#2208](https://github.com/bastani-inc/atomic/issues/2208)).
+
 ## [0.9.13-alpha.1] - 2026-08-05
 
 ### Changed

package/dist/builtin/intercom/README.md

@@ -58,7 +58,7 @@ A session becomes intercom-connected when all of these are true:
 
 The session list only shows intercom-connected sessions, not every open Pi process on the machine.
 
-If a session is unnamed, intercom exposes a runtime-only fallback alias like `subagent-chat-1a2b3c4d` so other sessions can still target it. That alias is not persisted as the session title, so resume pickers can keep showing the transcript snippet instead of a generic `session-...` name.
+If a session is unnamed, intercom exposes a runtime-only fallback alias like `subagent-chat-1a2b3c4d-1111-4222-8333-123456789abc` so other sessions can still target it. That alias is not persisted as the session title, so resume pickers can keep showing the transcript snippet instead of a generic `session-...` name.
 
 ## Quick Start
 
@@ -78,20 +78,28 @@ The agent can list sessions and send messages using the `intercom` tool. Tool ca
 // List active sessions
 intercom({ action: "list" })
 // → **Current session:**
-// → • executor (20d43841) — ~/projects/api (claude-sonnet-4) [self, idle]
+// → • executor (20d43841-1111-4222-8333-123456789abc) — ~/projects/api (claude-sonnet-4) [self, idle]
 // → **Other sessions:**
-// → • research (6332faab) — ~/projects/api (claude-sonnet-4) [same cwd, thinking]
+// → • research (6332faab-1111-4222-8333-123456789abc) — ~/projects/api (claude-sonnet-4) [same cwd, thinking]
+
+// Join a named group (it is created if no session is there yet)
+intercom({ action: "join", group: "api-review" })
+// → Joined intercom group "api-review".
+
+// Return to the group's home resolved at session start
+intercom({ action: "leave" })
+// → Returned to home intercom group "default".
 
 // Send a message
 intercom({ action: "send", to: "research", message: "Check if UserService.validate() handles null" })
 // → Message sent to research
 
-// The short ID printed by list is also a valid target
-intercom({ action: "ask", to: "6332faab", message: "Which validation path should I use?" })
+// The full session ID printed by list is also a valid target
+intercom({ action: "ask", to: "6332faab-1111-4222-8333-123456789abc", message: "Which validation path should I use?" })
 
 // Check connection status
 intercom({ action: "status" })
-// → Connected: Yes, Session ID: abc123, Active sessions: 3
+// → Connected: Yes, Session ID: abc12345-1111-4222-8333-123456789abc, Active sessions: 3
 
 // Send with attachments (code snippets, files, or context)
 intercom({
@@ -126,7 +134,7 @@ When a blocking `intercom.ask` targets a workflow stage that has already complet
 
 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.
+For delegated 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
 
@@ -168,10 +176,13 @@ intercom({
   to: "planner",
   message: "Should retry apply to all endpoints or just idempotent ones? Also, max retry count and backoff strategy?"
 })
+
 // → Reply from planner: Only GET/PUT/DELETE — never POST. Max 3 retries, exponential backoff starting at 100ms.
 // Worker continues implementing with the answer, same turn, full context.
 ```
 
+To coordinate two plain chat sessions without changing their startup config, have each one call `intercom({ action: "join", group: "NAME" })`. Joining updates broker presence in place, so the broker broadcasts a leave to the old group and a join to `NAME` without changing the session ID; the tool reports success only after the broker acknowledges the new group. Calls to `list`, `status`, `send`, and `ask` then use `NAME`; sessions that stay in `default` cannot discover or message the joined peers. Call `intercom({ action: "leave" })` to return to the original resolved home group. `contact_supervisor` keeps its dedicated capability-based cross-group behavior.
+
 **Worker finds something unexpected — escalates and waits:**
 ```typescript
 intercom({
@@ -233,7 +244,7 @@ This workflow uses Atomic's in-process subagent admission. When the runtime admi
 
 `contact_supervisor` is registered from the typed admission record. The record binds the supervisor target, canonical child identity, child index, session name, and broker-issued capability to the child session; these values are not inherited from environment variables. If the parent does not grant supervisor coordination, the session falls back to the regular `intercom` tool.
 
-The child identity remains stable across foreground continuation, `async: true`, interruption, and cold resume. Intercom detach uses the same in-process continuation as async work, so the jobs widget and terminal envelope retain one canonical path.
+The child identity remains stable across foreground continuation, interruption, and cold resume. Intercom detach uses the same in-process continuation as foreground coordination, so the terminal envelope retains one canonical path.
 
 ### Three Reasons
 
@@ -322,11 +333,12 @@ The supervisor can reply with plain JSON or a fenced `json` block. If the reply
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `action` | string | `"list"`, `"send"`, `"ask"`, `"reply"`, `"pending"`, or `"status"` |
-| `to` | string | Exact session name, exact full ID, or unique ID prefix (for send/ask, or to disambiguate reply) |
+| `action` | string | `"list"`, `"join"`, `"leave"`, `"send"`, `"ask"`, `"reply"`, `"pending"`, or `"status"` |
+| `to` | string | Exact session name or exact full session ID (for send/ask, or targeted reply) |
 | `message` | string | Message text (for send/ask/reply) |
 | `attachments` | array | Optional `file`, `snippet`, or `context` attachments |
 | `replyTo` | string | Optional message ID for threading or replying to an `ask` |
+| `group` | string | Group name for `join`; read-only group filter for `list`/`status`. `send`/`ask` stay locked to the current group. |
 
 ### contact_supervisor
 
@@ -346,19 +358,23 @@ Only registered in sessions where `pi-subagents` supplied the required child bri
 
 ### intercom actions
 
-**`list`** — Returns the current session plus other active intercom-connected sessions with name, short ID, working directory, model, and live status. Every displayed short ID can be passed directly to `send`, `ask`, or targeted `reply`. Status is derived automatically from Pi lifecycle events: `idle`, `thinking`, or `tool:<name>`.
+**`join`** — Moves this session into the trimmed named group and creates that group when no peer is there yet. `default` is the shared default group. The names `true` and `auto` are reserved for subagent auto-groups and are rejected. Subagents launched after the join inherit the joined group.
 
-Target lookup preserves exact full IDs and exact case-insensitive names, then accepts a unique session-ID prefix. If a prefix matches multiple sessions, Intercom reports every match and asks for a longer ID or exact name instead of guessing. Resolving a prefix to the current session still triggers the normal self-target rejection.
+**`leave`** — Moves this session back to the resolved home group from session startup. It takes no `group` parameter.
+
+**`list`** — Returns the current session plus other active intercom-connected sessions with name, full session ID, working directory, model, and live status. Every displayed full session ID can be passed directly to `send`, `ask`, or targeted `reply`.
+
+Target lookup accepts only an exact full session ID or an exact case-insensitive session name. Targeting is also **group-scoped** — see [Groups](#groups) below.
 
 **`send`** — Sends a message to the specified session. By default it sends immediately, including in interactive sessions. Set `confirmSend: true` in config if you want a confirmation dialog for non-reply sends. Replies that include `replyTo` skip confirmation. Returns delivery confirmation.
 
 **`ask`** — Sends a message and waits for the recipient to reply (10-minute timeout). The reply is returned as the tool result. No confirmation dialog. Only one pending `ask` is allowed per session at a time; if several blocking requests race (parallel `ask` calls, or `ask` alongside `contact_supervisor`), one wins the reservation and each other call returns a normal "Already waiting for a reply" tool error without disturbing the pending ask. Use this when the agent needs the answer to continue working.
 
-**`reply`** — Replies to the current intercom-triggered message if there is one. Otherwise it falls back to the single unresolved inbound ask. If multiple asks are pending, pass an exact name, exact full ID, or unique ID prefix in `to`, or inspect them with `pending` first. Under the hood this is still a normal `send` with the exact `replyTo` value.
+**`reply`** — Replies to the current intercom-triggered message if there is one. Otherwise it falls back to the single unresolved inbound ask. If multiple asks are pending, pass an exact name or exact full session ID in `to`, or inspect them with `pending` first. Under the hood this is still a normal `send` with the exact `replyTo` value.
 
 **`pending`** — Lists unresolved inbound asks with sender, message ID, elapsed time, and a short preview. Useful when replying after the original triggered turn.
 
-**`status`** — Shows connection status, session ID, and total count of active sessions (including the current session).
+**`status`** — Shows connection status, session ID, current group, and the total count of active sessions in that group. A `group` filter remains a read-only peek.
 
 ## Keyboard Shortcuts
 
@@ -384,7 +400,7 @@ Create `~/.atomic/agent/intercom/config.json` for Atomic. Legacy pi-compatible i
 }
 ```
 
-The default `npx --no-install tsx` pair is a compatibility sentinel: intercom recognizes it and starts the broker through the current Atomic/Pi runtime (`process.execPath`). Node-based installs use that runtime with a resolved `tsx` CLI, falling back to Atomic's bundled `jiti` loader when `tsx` is unavailable; Bun source-checkout runs use the current Bun executable directly; standalone Atomic Bun binaries re-enter the split launcher through a narrow internal broker handoff. Default startup therefore does not rely on `npx`, `tsx`, or `bun` being on `PATH`.
+The default `npx --no-install tsx` pair is a compatibility sentinel: intercom recognizes it and starts the broker through the current Atomic/Pi runtime (`process.execPath`). It never resolves or executes `tsx` — Node-based installs run the broker with Atomic's bundled `jiti` loader, which is dependency-free pure JavaScript; Bun source-checkout runs use the current Bun executable directly; standalone Atomic Bun binaries re-enter the split launcher through a narrow internal broker handoff. Default startup therefore does not rely on `npx`, `tsx`, or `bun` being on `PATH`.
 
 | Setting | Default | Description |
 |---------|---------|-------------|
@@ -444,8 +460,13 @@ Runtime files live under the active agent directory. Atomic defaults to `~/.atom
 - `broker-launch.vbs` — Windows helper script used to launch the broker without a console window
 - `broker.pid` — Broker process ID
 - `broker.spawn.lock` — Short-lived lock used to avoid duplicate auto-spawns
+- `broker.log` — Broker stderr, truncated on every spawn and capped at 8 KiB by the broker itself
 - `config.json` — User configuration
 
+The broker is a detached subprocess and never inherits the host's extension-loader module aliases, so every module reachable from `broker/broker.ts` resolves to Node built-ins or Intercom's own files. Its stderr is captured to `broker.log` through an already-open file descriptor rather than a pipe, because a pipe to a process that outlives its parent breaks once the parent exits. Startup failures — both an early exit and a readiness timeout — quote the log path and a bounded tail of that output.
+
+The broker caps the file from the inside, since nothing on the parent side can bound a child that outlives it. `broker/bounded-stderr-install.ts` is the entrypoint's first import, so the cap is in place before any other broker module evaluates, and it applies an 8 KiB byte budget to `process.stderr.write`, to `console.error` / `console.warn` (Bun's console writes to the descriptor directly and would otherwise bypass the stream), and to the default fatal printing for an uncaught exception or an unhandled rejection. It cannot cover output emitted before that import evaluates, native writes to file descriptor 2, child processes, or hard termination.
+
 ## Design Decisions
 
 **Local IPC instead of TCP.** Same-machine only by design. `pi-intercom` uses Unix sockets on macOS/Linux and a named pipe on Windows, which keeps setup simple and avoids port management.

package/dist/builtin/intercom/broker/bounded-stderr-install.ts

@@ -0,0 +1,18 @@
+import { installBoundedStderr } from "./bounded-stderr.js";
+
+/**
+ * Side-effect installer for the broker's stderr cap.
+ *
+ * ESM evaluates a module's static dependencies before the importer's own body, so calling
+ * `installBoundedStderr()` from the broker entrypoint left every module it imports free to write
+ * unbounded stderr first. Measured: an oversized write at the top of `group.ts` produced a
+ * 32,778-byte log even though the cap was 8 KiB.
+ *
+ * `broker.ts` therefore imports this module first, and nothing else. Importing it is the
+ * installation.
+ *
+ * The side effect deliberately does not live in `bounded-stderr.ts`: tests and other callers
+ * import that module as a plain utility, and installing at its module scope would patch their
+ * process globals behind their backs.
+ */
+installBoundedStderr();