@bastani/atomic 0.9.5-alpha.9 → 0.9.5

package/dist/builtin/subagents/src/extension/prompt-guidance.ts

@@ -1,13 +1,10 @@
 export const DEFAULT_PROMPT_GUIDANCE: string[] = [
-	`**Subagent Orchestration**:
-  - To avoid draining your context window, prefer to use subagents for complex tasks all non-trivial operations should be delegated to subagents.
-  - You should delegate running bash commands (particularly ones that are likely to produce lots of output) such as investigating with the \`aws\` CLI, using the \`gh\` CLI, digging through logs to \`bash\` subagents.
-  - You should use separate subagents for separate tasks, and you may launch them in parallel, but do not delegate multiple tasks that are likely to have significant overlap to separate subagents.
-  - Sometimes subagents will take a long time. DO NOT attempt to do the job yourself while waiting for the subagent to respond Instead, use the time to plan out your next steps.
-  - **Debugging**: When a user asks about debugging, spawn a debugger subagent first.
-    - Do not attempt to debug or analyze code yourself without first consulting the debugger subagent.
-    - Explain the debugger's insights to the user clearly and concisely.
-    - Once the user confirms, implement the necessary code changes based on those insights.
-    - If the user has follow-up questions, spawn additional debugger and research subagents as needed.`,
+	`**Subagent orchestration**: Use subagents selectively for bounded specialist delegation while the parent remains in control.
+  - Keep interactive, exploratory, conceptual, and conversation-led work inline when direct discussion and user steering are more useful than delegation.
+  - Use a single subagent for a focused specialty, a chain for a bounded sequential handoff, or parallel tasks for independent work. Multiple steps, files, tests, validation, or parallelism alone do not require a workflow.
+  - Delegate noisy or context-heavy command investigation when isolation helps, but run concise commands inline when that is simpler. Do not split work with substantial overlap across independent subagents.
+  - Use async/background execution selectively for genuinely long-running or independently useful delegated work. Foreground execution is appropriate when the parent needs the result before proceeding; do not duplicate a delegated job while waiting.
+  - For clearly delegated, well-defined autonomous jobs that are likely long-running/background-oriented or materially need durable stages, checkpoints, resumability, human input, gates, retries, or bounded loops, prefer an appropriate workflow rather than stretching subagent orchestration into an ad hoc workflow.
+  - Debug conceptual questions or exploratory analysis inline when appropriate. Use the debugger subagent for actual failures that need reproduction, root-cause diagnosis, and a validated fix; additional debugger or research delegates are optional when they add a distinct useful angle.`,
 ];
 

package/dist/builtin/subagents/src/extension/schemas.ts

@@ -3,7 +3,7 @@
  */
 
 import { Type } from "typebox";
-import { MAX_SUBAGENT_NESTING_DEPTH, SUBAGENT_ACTIONS } from "../shared/types.ts";
+import { MAX_PARALLEL_TASKS, MAX_SUBAGENT_NESTING_DEPTH, SUBAGENT_ACTIONS } from "../shared/types.ts";
 
 const SkillOverride = Type.Unsafe({
 	anyOf: [
@@ -35,12 +35,25 @@ const ReadsOverride = Type.Unsafe({
 	description: "Files to read before running (array of filenames), or false to disable",
 });
 
+const RootReadsOverride = Type.Unsafe({
+	anyOf: [
+		{ type: "array", items: { type: "string" } },
+		{ type: "boolean", enum: [false] },
+	],
+	description: "Files for a single agent to read before running, or false to disable. Relative paths resolve against the effective child cwd.",
+});
+
 const JsonSchemaObject = Type.Unsafe({
 	type: "object",
 	additionalProperties: true,
 	description: "Plain JSON Schema object for structured output.",
 });
 
+const MaxOutputSchema = Type.Object({
+	bytes: Type.Optional(Type.Number()),
+	lines: Type.Optional(Type.Number()),
+}, { additionalProperties: false });
+
 const TaskItem = Type.Object({
 	agent: Type.String(), 
 	task: Type.String(), 
@@ -185,7 +198,10 @@ export const SubagentParams = Type.Object({
 		],
 		description: `Agent or chain config for create/update. Agent: name, package (optional namespace; runtime name becomes package.name), description, scope ('user'|'project', default 'user'), systemPrompt, systemPromptMode, inheritProjectContext, inheritSkills, defaultContext ('fresh'|'fork'), model, tools (comma-separated), extensions (comma-separated), skills (comma-separated), thinking, output, reads, progress, maxSubagentDepth (integer >= 0, clamped to ${MAX_SUBAGENT_NESTING_DEPTH}). Chain: name, package, description, scope, steps (array of {agent, task?, output?, outputMode?, reads?, model?, skill?, progress?}). Presence of 'steps' creates a chain instead of an agent. String values must be valid JSON.`
 	})),
-	tasks: Type.Optional(Type.Array(TaskItem, { description: "PARALLEL mode: [{agent, task, count?, output?, outputMode?, reads?, progress?}, ...]" })),
+	tasks: Type.Optional(Type.Array(TaskItem, {
+		maxItems: MAX_PARALLEL_TASKS,
+		description: `PARALLEL mode: [{agent, task, count?, output?, outputMode?, reads?, progress?}, ...]. Maximum ${MAX_PARALLEL_TASKS} tasks after count expansion.`,
+	})),
 	concurrency: Type.Optional(Type.Integer({ minimum: 1, description: "Top-level PARALLEL mode only: max concurrent tasks. Defaults to config.parallel.concurrency or 4." })),
 	worktree: Type.Optional(Type.Boolean({
 		description: "Create isolated git worktrees for each parallel task. " +
@@ -201,14 +217,13 @@ export const SubagentParams = Type.Object({
 	async: Type.Optional(Type.Boolean({ description: "Run in background (default: false, or per config)" })),
 	agentScope: Type.Optional(Type.String({ description: "Agent discovery scope: 'user', 'project', or 'both' (default: 'both'; project wins on name collisions)" })),
 	cwd: Type.Optional(Type.String()),
+	maxOutput: Type.Optional(MaxOutputSchema),
 	artifacts: Type.Optional(Type.Boolean({ description: "Write debug artifacts (default: true)" })),
 	includeProgress: Type.Optional(Type.Boolean({ description: "Include full progress in result (default: false)" })),
 	share: Type.Optional(Type.Boolean({ description: "Upload session to GitHub Gist for sharing (default: false)" })),
 	sessionDir: Type.Optional(
 		Type.String({ description: "Directory to store session logs (default: temp; enables sessions even if share=false)" }),
 	),
-	// Clarification TUI
-	clarify: Type.Optional(Type.Boolean({ description: "Show TUI to preview/edit before execution. Explicit clarify: true keeps the run foreground for the clarify UI; omitted clarify can still run in the background when async: true is set." })),
 	control: Type.Optional(ControlOverrides),
 	// Solo agent overrides
 	output: Type.Optional(Type.Unsafe({
@@ -219,6 +234,8 @@ export const SubagentParams = Type.Object({
 		description: "Output file for single agent (string), or false to disable. Relative paths resolve against cwd.",
 	})),
 	outputMode: Type.Optional(OutputModeOverride),
+	reads: Type.Optional(RootReadsOverride),
+	progress: Type.Optional(Type.Boolean({ description: "Enable run-scoped progress.md tracking for a single agent under isolated artifact storage, without writing progress.md into the child cwd. This controls the child-maintained file; includeProgress separately controls whether detailed runtime telemetry is returned." })),
 	skill: Type.Optional(SkillOverride),
 	model: Type.Optional(Type.String({ description: "Override model for single agent (e.g. 'anthropic/claude-sonnet-4')" })),
-});
+}, { additionalProperties: false });

package/dist/builtin/subagents/src/extension/tool-description.ts

@@ -0,0 +1,29 @@
+import { APP_NAME } from "@bastani/atomic";
+
+export const SUBAGENT_TOOL_DESCRIPTION = `Delegate bounded specialist work to subagents or manage agent definitions while the parent remains in control.
+EXECUTION (use exactly ONE mode):
+• Execution calls always start non-interactively.
+• Before executing, use { action: "list" } to inspect configured agents/chains. Only execute agents listed as executable/non-disabled.
+• SINGLE: { agent, task?, progress? } - one focused task; progress:true maintains a run-scoped progress.md under isolated artifact storage without writing it into the child cwd (separate from includeProgress, which only returns runtime telemetry); omit task for self-contained agents
+• CHAIN: { chain: [{agent:"agent-a"}, {parallel:[{agent:"agent-b",count:3}]}] } - bounded sequential pipeline with optional parallel fan-out
+• PARALLEL: { tasks: [{agent,task,count?,output?,reads?,progress?}, ...], concurrency?: number, worktree?: true } - independent concurrent tasks (worktree: isolate each task in a git worktree)
+• Optional context: { context: "fresh" | "fork" } (default: if any requested agent has defaultContext: "fork", the whole invocation uses fork; otherwise "fresh"; inspect agent defaults via { action: "list" })
+• async:true is selective for genuinely long-running/background work; foreground is appropriate when the parent needs the result before proceeding
+CHAIN TEMPLATE VARIABLES (use in task strings):
+• {task} - The original task/request from the user
+• {previous} - Text response from the previous step (empty for first step)
+• {chain_dir} - Shared directory for chain files (e.g., <tmpdir>/${APP_NAME}-subagents-<scope>/chain-runs/abc123/)
+Example: { chain: [{agent:"agent-a", task:"Analyze {task}"}, {agent:"agent-b", task:"Plan based on {previous}"}] }
+MANAGEMENT (use action field, omit agent/task/chain/tasks):
+• { action: "list" } - discover executable agents/chains
+• { action: "get", agent: "name" } - full detail; packaged agents use dotted runtime names like "package.agent"
+• { action: "create", config: { name: "custom-agent", package: "code-analysis", systemPrompt, systemPromptMode, inheritProjectContext, inheritSkills, defaultContext, ... } }
+• { action: "update", agent: "code-analysis.custom-agent", config: { package: "analysis", ... } } - merge
+• { action: "delete", agent: "code-analysis.custom-agent" }
+• Use chainName for chain operations; packaged chains also use dotted runtime names
+CONTROL:
+• { action: "status", id: "..." } - inspect an async/background run by id or prefix
+• { action: "interrupt", id?: "..." } - soft-interrupt the current child turn and leave the run paused
+• { action: "resume", id: "...", message: "...", index?: 0 } - follow up with a live async child or revive a completed async/foreground child from its session
+DIAGNOSTICS:
+• { action: "doctor" } - read-only report for runtime paths, discovery, sessions, and intercom`;

package/dist/builtin/subagents/src/intercom/intercom-bridge.ts

@@ -2,7 +2,8 @@ import { execSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { getProjectConfigDirs } from "@bastani/atomic";
+import { fileURLToPath } from "node:url";
+import { APP_NAME, getProjectConfigDirs, getEnvValue } from "@bastani/atomic";
 import type { AgentConfig } from "../agents/agents.ts";
 import type { ExtensionConfig, IntercomBridgeConfig, IntercomBridgeMode } from "../shared/types.ts";
 import { getAgentDir } from "../shared/utils.ts";
@@ -12,11 +13,16 @@ const PI_INTERCOM_PACKAGE_NAME = "pi-intercom";
 function defaultAgentDir(): string {
 	return getAgentDir();
 }
+const INTERCOM_SESSION_ID_ENV = `${APP_NAME.toUpperCase()}_INTERCOM_SESSION_ID`;
 
 function defaultIntercomExtensionDir(agentDir = defaultAgentDir()): string {
 	return path.join(agentDir, "extensions", PI_INTERCOM_PACKAGE_NAME);
 }
 
+function bundledIntercomExtensionDir(): string {
+	return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "intercom");
+}
+
 function defaultIntercomConfigPath(agentDir = defaultAgentDir()): string {
 	return path.join(agentDir, "intercom", "config.json");
 }
@@ -72,6 +78,8 @@ interface ResolveIntercomBridgeInput {
 }
 
 export function resolveIntercomSessionTarget(sessionName: string | undefined, sessionId: string): string {
+	const connectedIntercomSessionId = getEnvValue(INTERCOM_SESSION_ID_ENV)?.trim();
+	if (connectedIntercomSessionId) return connectedIntercomSessionId;
 	const trimmedName = sessionName?.trim();
 	if (trimmedName) return trimmedName;
 	const normalizedSessionId = sessionId.startsWith("session-") ? sessionId.slice("session-".length) : sessionId;
@@ -231,7 +239,10 @@ function configuredPiIntercomPackageDir(input: ResolveIntercomBridgeInput, agent
 }
 
 function resolveIntercomExtensionDir(input: ResolveIntercomBridgeInput, agentDir: string): string {
-	const legacyDir = path.resolve(input.extensionDir ?? defaultIntercomExtensionDir(agentDir));
+	if (input.extensionDir) return path.resolve(input.extensionDir);
+	const bundledDir = bundledIntercomExtensionDir();
+	if (packageHasPiExtension(bundledDir)) return bundledDir;
+	const legacyDir = path.resolve(defaultIntercomExtensionDir(agentDir));
 	if (fs.existsSync(legacyDir)) return legacyDir;
 	return configuredPiIntercomPackageDir(input, agentDir) ?? legacyDir;
 }

package/dist/builtin/subagents/src/intercom/result-intercom.ts

@@ -167,7 +167,7 @@ function formatNestedResultLines(children: PublicNestedRunSummary[] | undefined)
 	return lines;
 }
 
-interface GroupedResultIntercomMessageInput {
+export interface GroupedResultIntercomMessageInput {
 	to: string;
 	runId: string;
 	mode: SubagentRunMode;
@@ -276,7 +276,7 @@ export function buildSubagentResultIntercomPayload(input: GroupedResultIntercomM
 export async function deliverSubagentResultIntercomEvent(
 	events: IntercomEventBus,
 	payload: SubagentResultIntercomPayload,
-	timeoutMs = 500,
+	timeoutMs: number | false = 500,
 ): Promise<boolean> {
 	return deliverSubagentIntercomMessageEvent(events, payload.to, payload.message, timeoutMs, payload as unknown as Record<string, unknown>);
 }
@@ -285,7 +285,7 @@ export async function deliverSubagentIntercomMessageEvent(
 	events: IntercomEventBus,
 	to: string,
 	message: string,
-	timeoutMs = 500,
+	timeoutMs: number | false = 500,
 	extra: Record<string, unknown> = {},
 ): Promise<boolean> {
 	if (typeof events.on !== "function" || typeof events.emit !== "function") return false;
@@ -307,7 +307,7 @@ export async function deliverSubagentIntercomMessageEvent(
 			if (delivery.requestId !== requestId) return;
 			finish(delivery.delivered === true);
 		});
-		timer = setTimeout(() => finish(false), timeoutMs);
+		if (timeoutMs !== false) timer = setTimeout(() => finish(false), timeoutMs);
 		try {
 			events.emit(SUBAGENT_RESULT_INTERCOM_EVENT, { ...extra, to, message, requestId });
 		} catch {

package/dist/builtin/subagents/src/runs/background/async-event-journal.ts

@@ -0,0 +1,106 @@
+import * as fs from "node:fs";
+import type { DrainableSource, JsonlWriteStream } from "../../shared/jsonl-writer.ts";
+import { acquireEventWriter } from "../../shared/event-jsonl-writer.ts";
+
+const DEFAULT_TELEMETRY_BYTES = 512 * 1024;
+const CAPPED_CHILD_EVENT_TYPES = new Set([
+	"message_update", "tool_execution_update", "subagent.child.stdout", "subagent.child.stderr",
+]);
+
+interface ChildEventJournalContext {
+	runId: string;
+	stepIndex?: number;
+	agent: string;
+}
+
+interface ChildEventJournalDeps {
+	maxTelemetryBytes?: number;
+	createWriteStream?: (filePath: string) => JsonlWriteStream;
+	now?: () => number;
+}
+
+export interface ChildEventJournal {
+	append(event: Record<string, unknown>): void;
+	close(): Promise<void>;
+}
+
+function withoutKey(record: Record<string, unknown>, key: string): Record<string, unknown> {
+	const { [key]: _removed, ...rest } = record;
+	return rest;
+}
+
+/** Remove cumulative streaming snapshots while retaining compact delta metadata. */
+export function sanitizeChildEvent(event: Record<string, unknown>): Record<string, unknown> {
+	let sanitized = event;
+	if (event.type === "message_update") {
+		sanitized = withoutKey(event, "message");
+		const assistantEvent = sanitized.assistantMessageEvent;
+		if (assistantEvent && typeof assistantEvent === "object" && !Array.isArray(assistantEvent)) {
+			let compactEvent = withoutKey(withoutKey(assistantEvent as Record<string, unknown>, "partial"), "message");
+			if (!("delta" in compactEvent)) {
+				compactEvent = withoutKey(withoutKey(compactEvent, "content"), "toolCall");
+			}
+			sanitized = { ...sanitized, assistantMessageEvent: compactEvent };
+		}
+	}
+	if (event.type === "message_start") sanitized = withoutKey(sanitized, "message");
+	if (event.type === "tool_execution_update") sanitized = withoutKey(sanitized, "partialResult");
+	if (event.type === "turn_end") sanitized = withoutKey(sanitized, "message");
+	if (event.type === "agent_end") sanitized = withoutKey(sanitized, "messages");
+	return sanitized;
+}
+
+export function createChildEventJournal(
+	filePath: string | undefined,
+	source: DrainableSource,
+	context: ChildEventJournalContext,
+	deps: ChildEventJournalDeps = {},
+): ChildEventJournal {
+	if (!filePath) return { append() {}, async close() {} };
+	const createStream = deps.createWriteStream ?? ((target: string) => fs.createWriteStream(target, { flags: "a" }));
+	const writer = acquireEventWriter(filePath, source, createStream);
+	if (!writer) return { append() {}, async close() {} };
+	const maxTelemetryBytes = deps.maxTelemetryBytes ?? DEFAULT_TELEMETRY_BYTES;
+	const now = deps.now ?? Date.now;
+	let closed = false;
+	let closePromise: Promise<void> | undefined;
+	const write = (record: Record<string, unknown>): void => writer.writeLine(JSON.stringify(record));
+
+	const enrich = (event: Record<string, unknown>): Record<string, unknown> => ({
+		...event,
+		subagentSource: "child",
+		subagentRunId: context.runId,
+		subagentStepIndex: context.stepIndex,
+		subagentAgent: context.agent,
+		observedAt: now(),
+	});
+
+	return {
+		append(event) {
+			if (closed) return;
+			const sanitized = sanitizeChildEvent(event);
+			const record = enrich(sanitized);
+			const lineBytes = Buffer.byteLength(`${JSON.stringify(record)}\n`, "utf-8");
+			const assistantEvent = event.type === "message_update" && event.assistantMessageEvent
+				&& typeof event.assistantMessageEvent === "object" && !Array.isArray(event.assistantMessageEvent)
+				? event.assistantMessageEvent as Record<string, unknown>
+				: undefined;
+			const nestedTerminal = assistantEvent?.type === "done" || assistantEvent?.type === "error";
+			const capped = !nestedTerminal && typeof event.type === "string" && CAPPED_CHILD_EVENT_TYPES.has(event.type);
+			if (capped && !writer.reserveTelemetry(lineBytes, maxTelemetryBytes)) {
+				if (writer.claimTruncationMarker()) {
+					write(enrich({ type: "subagent.child.telemetry_truncated", maxTelemetryBytes }));
+				}
+				return;
+			}
+			write(record);
+		},
+		close() {
+			if (!closePromise) {
+				closed = true;
+				closePromise = writer.close();
+			}
+			return closePromise;
+		},
+	};
+}

package/dist/builtin/subagents/src/runs/background/async-execution-common.ts

@@ -59,10 +59,11 @@ const jitiCliPath = resolveJitiCliPath();
 
 export function formatAsyncStartedMessage(headline: string): string {
 	return [
-		headline,
+		`Launched: ${headline}`,
+		"Completion pending; Pi will deliver the result when the detached run finishes.",
 		"",
 		"The async run is detached. Do not run sleep timers or polling loops just to wait for it.",
-		"If you have independent work, continue that work. If you have nothing else to do until the async result arrives, end your turn now; Pi will deliver the completion when the run finishes.",
+		"If you have independent work, continue that work. If you have nothing else to do until the async result arrives, end your turn now.",
 		"Use subagent({ action: \"status\", id: \"...\" }) when you need the current status/result, or to inspect a blocked/stale run. Do not poll just to wait.",
 	].join("\n");
 }

package/dist/builtin/subagents/src/runs/background/async-execution-single.ts

@@ -4,6 +4,7 @@ import { getEnvValue } from "@bastani/atomic";
 import { buildSkillInjection, resolveSkillsWithFallback } from "../../agents/skills.ts";
 import { getSubagentCodexFastModeSettings, resolveSubagentCodexFastModeScope, resolveSubagentModelFastModeMetadata } from "../../shared/fast-mode.ts";
 import { resolveEffectiveThinking } from "../../shared/model-info.ts";
+import { injectSingleProgressInstruction, writeInitialProgressFile } from "../../shared/settings.ts";
 import { ASYNC_DIR, RESULTS_DIR, SUBAGENT_ASYNC_STARTED_EVENT, resolveChildMaxSubagentDepth } from "../../shared/types.ts";
 import { resolveChildCwd } from "../../shared/utils.ts";
 import { applyThinkingSuffix, SUBAGENT_INTERCOM_SESSION_NAME_ENV } from "../shared/pi-args.ts";
@@ -16,7 +17,7 @@ import {
 	formatAsyncStartedMessage,
 	formatAsyncStartError,
 	piPackageRoot,
-	spawnRunner,
+	spawnRunner as defaultSpawnRunner,
 } from "./async-execution-common.ts";
 import type { AsyncExecutionResult, AsyncSingleParams, AsyncSpawnResult } from "./async-execution-types.ts";
 
@@ -46,6 +47,7 @@ export function executeAsyncSingle(
 		controlIntercomTarget,
 		childIntercomTarget,
 		nestedRoute,
+		spawnRunner = defaultSpawnRunner,
 	} = params;
 	const task = params.task ?? "";
 	const runnerCwd = resolveChildCwd(ctx.cwd, cwd);
@@ -81,7 +83,16 @@ export function executeAsyncSingle(
 	const outputMode = params.outputMode ?? "inline";
 	const validationError = validateFileOnlyOutputMode(outputMode, outputPath, `Async single run (${agent})`);
 	if (validationError) return formatAsyncStartError("single", validationError);
-	const taskWithOutputInstruction = injectSingleOutputInstruction(task, outputPath);
+	let taskWithOutputInstruction = injectSingleOutputInstruction(task, outputPath);
+	// Keep each child's progress contract outside its cwd and isolated by run;
+	// artifacts-disabled async runs use their already run-owned async directory.
+	if (params.progress) {
+		const progressDir = artifactConfig.enabled && artifactsDir
+			? path.join(artifactsDir, "progress", id)
+			: path.join(asyncDir, "progress");
+		writeInitialProgressFile(progressDir);
+		taskWithOutputInstruction = injectSingleProgressInstruction(taskWithOutputInstruction, progressDir);
+	}
 	const model = applyThinkingSuffix(
 		resolveModelCandidate(params.modelOverride ?? agentConfig.model, availableModels, ctx.currentModelProvider),
 		agentConfig.thinking,

package/dist/builtin/subagents/src/runs/background/async-execution-types.ts

@@ -61,6 +61,7 @@ export interface AsyncSingleParams {
 	skills?: string[];
 	output?: string | boolean;
 	outputMode?: "inline" | "file-only";
+	progress?: boolean;
 	modelOverride?: string;
 	availableModels?: AvailableModelInfo[];
 	knownModelProviders?: string[];
@@ -72,6 +73,8 @@ export interface AsyncSingleParams {
 	controlIntercomTarget?: string;
 	childIntercomTarget?: (agent: string, index: number) => string | undefined;
 	nestedRoute?: NestedRouteInfo;
+	/** Internal launch seam used by focused runtime tests. */
+	spawnRunner?: (config: object, suffix: string, cwd: string) => AsyncSpawnResult;
 }
 
 export interface AsyncExecutionResult {

package/dist/builtin/subagents/src/runs/background/async-job-tracker.ts

@@ -97,7 +97,7 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 	const pollIntervalMs = options.pollIntervalMs ?? POLL_INTERVAL_MS;
 	const resultsDir = options.resultsDir ?? RESULTS_DIR;
 	const rerenderWidget = (ctx: ExtensionContext, jobs = Array.from(state.asyncJobs.values())) => {
-		renderWidget(ctx, jobs);
+		renderWidget(ctx, jobs, pi);
 	};
 	const cancelCleanup = (asyncId: string) => {
 		const existingTimer = state.cleanupTimers.get(asyncId);

package/dist/builtin/subagents/src/runs/background/completion-claims.ts

@@ -0,0 +1,189 @@
+import type { FrozenCompletionEnvelope } from "./result-file-claims.js";
+
+type CompletionClaimStatus = "delivered" | "retry" | "exhausted" | "conflict" | "released";
+type TerminalStatus = Extract<CompletionClaimStatus, "delivered" | "exhausted">;
+
+interface CompletionAttempt {
+	status: CompletionClaimStatus;
+	noProgressFailures: number;
+}
+
+interface CompletionFlight {
+	promise: Promise<CompletionAttempt>;
+}
+
+export interface CompletionClaimSnapshot {
+	intercomDelivered: boolean;
+	localDelivered: boolean;
+	noProgressFailures: number;
+	terminalStatus?: TerminalStatus;
+	envelope: FrozenCompletionEnvelope;
+}
+
+interface CompletionClaim extends CompletionClaimSnapshot {
+	signature: string;
+	inFlight?: CompletionFlight;
+	completedAt?: number;
+	lastTouchedAt: number;
+}
+
+export interface CompletionClaimResult extends CompletionAttempt {
+	owner: boolean;
+}
+
+export interface CompletionDeliveryPhases {
+	intercom?: (envelope: FrozenCompletionEnvelope) => Promise<boolean> | boolean;
+	local?: (envelope: FrozenCompletionEnvelope) => Promise<boolean> | boolean;
+	isOwned?: () => boolean;
+	onState?: (snapshot: CompletionClaimSnapshot) => void;
+}
+
+export interface CompletionClaimInitial {
+	intercomDelivered?: boolean;
+	localDelivered?: boolean;
+	noProgressFailures?: number;
+	terminalStatus?: TerminalStatus;
+	envelope?: FrozenCompletionEnvelope;
+}
+
+const STORE_KEY = "__atomicSubagentCompletionClaims";
+const DEFAULT_MAX_NO_PROGRESS_FAILURES = 8;
+const MAX_CLAIMS = 2048;
+
+function cloneEnvelope(envelope: FrozenCompletionEnvelope): FrozenCompletionEnvelope {
+	return JSON.parse(JSON.stringify(envelope)) as FrozenCompletionEnvelope;
+}
+
+function claims(): Map<string, CompletionClaim> {
+	const globalStore = globalThis as Record<string, unknown>;
+	const existing = globalStore[STORE_KEY];
+	if (existing instanceof Map) return existing as Map<string, CompletionClaim>;
+	const created = new Map<string, CompletionClaim>();
+	globalStore[STORE_KEY] = created;
+	return created;
+}
+
+function prune(store: Map<string, CompletionClaim>, now: number, ttlMs: number): void {
+	for (const [key, claim] of store) {
+		if (claim.completedAt !== undefined && now - claim.completedAt > ttlMs) store.delete(key);
+	}
+	if (store.size <= MAX_CLAIMS) return;
+	const disposable = [...store.entries()]
+		.filter(([, claim]) => !claim.inFlight && !claim.intercomDelivered && !claim.localDelivered)
+		.sort((a, b) => a[1].lastTouchedAt - b[1].lastTouchedAt);
+	for (const [key] of disposable) {
+		if (store.size <= MAX_CLAIMS) break;
+		store.delete(key);
+	}
+}
+
+function snapshot(claim: CompletionClaim): CompletionClaimSnapshot {
+	return {
+		intercomDelivered: claim.intercomDelivered,
+		localDelivered: claim.localDelivered,
+		noProgressFailures: claim.noProgressFailures,
+		terminalStatus: claim.terminalStatus,
+		envelope: cloneEnvelope(claim.envelope),
+	};
+}
+
+function persist(claim: CompletionClaim, callback: CompletionDeliveryPhases["onState"]): void {
+	claim.lastTouchedAt = Date.now();
+	callback?.(snapshot(claim));
+}
+
+/** Atomically owns and advances one completion across aliases and watcher replacements. */
+export async function deliverClaimedCompletion(
+	key: string,
+	signature: string,
+	ttlMs: number,
+	phases: CompletionDeliveryPhases,
+	maxNoProgressFailures = DEFAULT_MAX_NO_PROGRESS_FAILURES,
+	initial: CompletionClaimInitial = {},
+	envelope: FrozenCompletionEnvelope = { local: {} },
+): Promise<CompletionClaimResult> {
+	const store = claims();
+	const now = Date.now();
+	prune(store, now, ttlMs);
+	let claim = store.get(key);
+	if (!claim) {
+		claim = {
+			signature,
+			envelope: cloneEnvelope(initial.envelope ?? envelope),
+			intercomDelivered: initial.intercomDelivered === true,
+			localDelivered: initial.localDelivered === true,
+			noProgressFailures: initial.noProgressFailures ?? 0,
+			terminalStatus: initial.terminalStatus,
+			completedAt: initial.terminalStatus ? now : undefined,
+			lastTouchedAt: now,
+		};
+		store.set(key, claim);
+		persist(claim, phases.onState);
+	} else if (claim.signature !== signature) {
+		return { owner: false, status: "conflict", noProgressFailures: claim.noProgressFailures };
+	}
+	claim.lastTouchedAt = now;
+	if (claim.terminalStatus) return { owner: false, status: claim.terminalStatus, noProgressFailures: claim.noProgressFailures };
+	if (claim.inFlight) return { owner: false, ...await claim.inFlight.promise };
+
+	const ownedClaim = claim;
+	const hasVisibleProgress = () => ownedClaim.intercomDelivered || ownedClaim.localDelivered;
+	const retireForOwnershipLoss = (): CompletionAttempt => {
+		if (!hasVisibleProgress()) {
+			store.delete(key);
+			return { status: "released", noProgressFailures: ownedClaim.noProgressFailures };
+		}
+		persist(ownedClaim, phases.onState);
+		return { status: "released", noProgressFailures: ownedClaim.noProgressFailures };
+	};
+	const attempt = (async (): Promise<CompletionAttempt> => {
+		let progressed = false;
+		const failed = (): CompletionAttempt => {
+			if (phases.isOwned && !phases.isOwned()) return retireForOwnershipLoss();
+			ownedClaim.noProgressFailures = progressed ? 0 : ownedClaim.noProgressFailures + 1;
+			if (ownedClaim.noProgressFailures >= Math.max(1, maxNoProgressFailures)) {
+				ownedClaim.terminalStatus = "exhausted";
+				ownedClaim.completedAt = Date.now();
+				persist(ownedClaim, phases.onState);
+				return { status: "exhausted", noProgressFailures: ownedClaim.noProgressFailures };
+			}
+			persist(ownedClaim, phases.onState);
+			return { status: "retry", noProgressFailures: ownedClaim.noProgressFailures };
+		};
+		const runPhase = async (phase: ((value: FrozenCompletionEnvelope) => Promise<boolean> | boolean) | undefined): Promise<boolean | undefined> => {
+			if (!phase) return undefined;
+			if (phases.isOwned && !phases.isOwned()) return false;
+			try { return await phase(cloneEnvelope(ownedClaim.envelope)); } catch { return false; }
+		};
+		if (!ownedClaim.intercomDelivered && phases.intercom) {
+			const delivered = await runPhase(phases.intercom);
+			if (!delivered) return failed();
+			ownedClaim.intercomDelivered = true;
+			progressed = true;
+			persist(ownedClaim, phases.onState);
+			if (phases.isOwned && !phases.isOwned()) return retireForOwnershipLoss();
+		}
+		if (!ownedClaim.localDelivered && phases.local) {
+			const delivered = await runPhase(phases.local);
+			if (!delivered) return failed();
+			ownedClaim.localDelivered = true;
+			progressed = true;
+			persist(ownedClaim, phases.onState);
+			if (phases.isOwned && !phases.isOwned()) return retireForOwnershipLoss();
+		}
+		ownedClaim.noProgressFailures = 0;
+		ownedClaim.terminalStatus = "delivered";
+		ownedClaim.completedAt = Date.now();
+		persist(ownedClaim, phases.onState);
+		return { status: "delivered", noProgressFailures: 0 };
+	})();
+	const flight: CompletionFlight = { promise: attempt };
+	ownedClaim.inFlight = flight;
+	try {
+		return { owner: true, ...await flight.promise };
+	} finally {
+		// The explicit flight handle is the ownership token; comparing resolved
+		// values would let an older attempt clear a newer in-flight claim.
+		if (ownedClaim.inFlight === flight) ownedClaim.inFlight = undefined;
+	}
+}