@bastani/atomic 0.9.12 → 0.9.13-alpha.2

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.2",
+  "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,31 @@ All notable changes to the `pi-intercom` extension will be documented in this fi
 
 ## [Unreleased]
 
+## [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
+
+- In-process child identities and supervisor capabilities now arrive through typed admission policy and are captured on each `IntercomClient` at connect time instead of being read from environment for every message. Descendants cannot inherit a parent's supervisor grant through process environment; legacy Atomic/Pi bridge metadata remains available for older hosts ([#2188](https://github.com/bastani-inc/atomic/issues/2188)).
+
 ## [0.9.12] - 2026-08-04
 
 ### Fixed

package/dist/builtin/intercom/README.md

@@ -20,7 +20,7 @@ Sometimes you're running multiple Atomic/pi sessions — one researching, one ex
 
 Unlike pi-messenger (a shared chat room for multi-agent swarms), intercom is for targeted 1:1 communication where you pick the recipient.
 
-Intercom also integrates with delegated subagents: child agents get a child-only `contact_supervisor` tool when subagent bridge metadata is present. Atomic-prefixed bridge environment variables are supported, and legacy `PI_*` bridge metadata remains compatible. Atomic's subagent bridge also obtains a broker capability that binds the child session to the exact supervisor; client-authored channel flags are never trusted as cross-group authority. Use `reason: "need_decision"` for blocking clarification, `reason: "interview_request"` for multiple structured supervisor answers, and `reason: "progress_update"` for meaningful plan-changing updates. Normal sessions only see the regular `intercom` tool.
+Intercom also integrates with delegated subagents: in-process children receive a typed admission-issued identity for `contact_supervisor`, including their canonical run/agent/index metadata and any supervisor capability. The child identity is bound to its `IntercomClient` when it connects, so each message uses the same client-owned source and a descendant cannot inherit a parent's capability through process environment. Atomic-prefixed bridge environment variables and legacy `PI_*` metadata remain compatible for older integrations only. Use `reason: "need_decision"` for blocking clarification, `reason: "interview_request"` for multiple structured supervisor answers, and `reason: "progress_update"` for meaningful plan-changing updates. Normal sessions only see the regular `intercom` tool.
 
 ## In One Minute
 
@@ -82,6 +82,14 @@ intercom({ action: "list" })
 // → **Other sessions:**
 // → • research (6332faab) — ~/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
@@ -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({
@@ -227,20 +238,13 @@ The planner typically uses `send`. If you prefer manual approval for outgoing no
 
 ## Workflow: Subagent-to-Supervisor Escalation
 
-This workflow requires [`pi-subagents`](https://github.com/nicobailon/pi-subagents) to be installed and to supply child bridge metadata. When `pi-subagents` spawns a delegated child with that metadata, the child session gets a subagent-only `contact_supervisor` tool in addition to the regular `intercom` tool. Normal sessions never see `contact_supervisor`.
+This workflow uses Atomic's in-process subagent admission. When the runtime admits a delegated child with supervisor coordination, the child session gets a subagent-only `contact_supervisor` tool in addition to the regular `intercom` tool. Normal sessions never see `contact_supervisor`.
 
 ### When the Tool Appears
 
-`contact_supervisor` only registers when `pi-subagents` sets all of these environment variables:
-
-- `PI_SUBAGENT_ORCHESTRATOR_TARGET` — the supervisor session name or ID
-- `PI_SUBAGENT_RUN_ID` — the run identifier
-- `PI_SUBAGENT_CHILD_AGENT` — the agent type
-- `PI_SUBAGENT_CHILD_INDEX` — the child index within the run
+`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.
 
-Atomic's bundled subagent bridge additionally supplies internal `ATOMIC_SUBAGENT_SUPERVISOR_CAPABILITY` and `ATOMIC_SUBAGENT_SUPERVISOR_SESSION_ID` values issued by the broker. They are not user-configurable authentication flags: the broker accepts the capability only for the child scope and supervisor session that requested it, and the parent restores the same secret if the broker reconnects. Legacy `PI_*` aliases remain readable where applicable.
-
-If any are missing, the session falls back to the regular `intercom` tool.
+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.
 
 ### Three Reasons
 
@@ -254,7 +258,7 @@ Do not use `contact_supervisor` for routine completion handoffs. Return the fina
 
 Cross-group delivery uses a dedicated broker protocol. Ordinary raw `send` frames always remain group-isolated and are rejected if they include a forged `channel: "supervisor"` marker. A child can cross groups only after its broker-issued capability has bound its registered socket to the exact supervisor. The broker adds the `supervisor` channel marker to validated inbound traffic so parent relays can distinguish it. Replies cross back only when `replyTo` matches a recorded supervisor message in the exact reverse direction; fabricated thread IDs do not bypass isolation.
 
-During a foreground subagent run, Atomic probes for an exact live foreground owner before delivery. The matching child reserves the request, accepts a generation-scoped detach commit, and acknowledges it before asks, sends, decisions, interviews, and progress updates enter the parent's model-visible steering queue. A busy workflow stage first reserves the message in its AgentSession generation boundary, then waits inside that admission for the same detach handshake before model-visible queue insertion. This prevents terminal stage close from overtaking the handshake while still preventing the active subagent tool from blocking the child request that would release it; unclaimed traffic and a still-current receiver whose owner disappears before commit fall back to ordinary queue insertion. One accepted commit releases foreground supervision for every active member of a parallel group while retaining each child process and eventual result. Blocking calls remain alive until the parent sends the exact threaded reply; fire-and-forget calls create no reply waiter. Background and unmatched traffic for ordinary sessions keeps queued-until-idle behavior, and generation cancellation/replacement invalidates stale handshakes.
+During a foreground subagent run, Atomic probes for an exact live foreground owner before delivery. The matching child reserves the request, accepts a generation-scoped detach commit, and acknowledges it before asks, sends, decisions, interviews, and progress updates enter the parent's model-visible steering queue. A busy workflow stage first reserves the message in its AgentSession generation boundary, then waits inside that admission for the same detach handshake before model-visible queue insertion. This prevents terminal stage close from overtaking the handshake while still preventing the active subagent tool from blocking the child request that would release it; unclaimed traffic and a still-current receiver whose owner disappears before commit fall back to ordinary queue insertion. One accepted commit releases foreground supervision for every active member of a parallel group while retaining each in-process session and eventual result. Blocking calls remain alive until the parent sends the exact threaded reply; fire-and-forget calls create no reply waiter. Background and unmatched traffic for ordinary sessions keeps queued-until-idle behavior, and generation cancellation/replacement invalidates stale handshakes.
 
 ### Example: Blocked Subagent Asks for Guidance
 
@@ -329,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"` |
+| `action` | string | `"list"`, `"join"`, `"leave"`, `"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) |
 | `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
 
@@ -353,7 +358,11 @@ 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.
+
+**`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, short ID, working directory, model, and live status. Every displayed short ID can be passed directly to `send`, `ask`, or targeted `reply`.
 
 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.
 
@@ -365,7 +374,7 @@ Target lookup preserves exact full IDs and exact case-insensitive names, then ac
 
 **`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
 
@@ -391,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 |
 |---------|---------|-------------|
@@ -451,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();