@gajae-code/coding-agent 0.2.4 → 0.3.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/coding-agent",
-	"version": "0.2.4",
+	"version": "0.3.0",
 	"description": "Gajae Code CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://gaebal-gajae.dev",
 	"author": "Yeachan-Heo",
@@ -48,12 +48,12 @@
 		"@agentclientprotocol/sdk": "0.21.0",
 		"@babel/parser": "^7.29.3",
 		"@mozilla/readability": "^0.6.0",
-		"@gajae-code/stats": "0.2.4",
-		"@gajae-code/agent-core": "0.2.4",
-		"@gajae-code/ai": "0.2.4",
-		"@gajae-code/natives": "0.2.4",
-		"@gajae-code/tui": "0.2.4",
-		"@gajae-code/utils": "0.2.4",
+		"@gajae-code/stats": "0.3.0",
+		"@gajae-code/agent-core": "0.3.0",
+		"@gajae-code/ai": "0.3.0",
+		"@gajae-code/natives": "0.3.0",
+		"@gajae-code/tui": "0.3.0",
+		"@gajae-code/utils": "0.3.0",
 		"@puppeteer/browsers": "^2.13.0",
 		"@types/turndown": "5.0.6",
 		"@xterm/headless": "^6.0.0",

package/src/async/job-manager.ts

@@ -10,7 +10,7 @@ const DEFAULT_MAX_RUNNING_JOBS = 15;
 export interface AsyncJob {
 	id: string;
 	type: "bash" | "task";
-	status: "running" | "completed" | "failed" | "cancelled";
+	status: "running" | "completed" | "failed" | "cancelled" | "paused";
 	startTime: number;
 	label: string;
 	abortController: AbortController;
@@ -37,6 +37,64 @@ export interface AsyncJobMetadata {
 	};
 }
 
+/**
+ * Typed outcome a subagent task run may produce. A `paused` outcome is
+ * non-terminal and non-delivering: the run suspended at a safe boundary and the
+ * subagent can be resumed from its persisted sessionFile. `completed` always
+ * wins a race with a late pause because the run returns it once it has actually
+ * finished.
+ */
+export type SubagentRunOutcome = { kind: "completed"; text: string } | { kind: "paused"; note?: string };
+
+/** Canonical lifecycle of a subagent across pause/resume cycles. */
+export type SubagentLifecycle = "running" | "paused" | "queued" | "completed" | "failed" | "cancelled";
+
+/**
+ * Live, executor-owned control handle for a RUNNING subagent. Registered when a
+ * subagent run starts and removed on pause/terminal so a paused subagent retains
+ * no live `AgentSession` reference (leak-free).
+ */
+export interface SubagentLiveHandle {
+	/** Request a cooperative safe-boundary pause (never aborts the in-flight tool). */
+	requestPause(): void;
+	/** Inject a steering message into the live session. */
+	injectMessage(content: string, deliverAs: "steer" | "followUp" | "nextTurn"): Promise<void>;
+}
+
+/**
+ * Canonical, stable-id-keyed record for a subagent. Survives `AsyncJob`
+ * eviction so resume stays addressable by subagent id, and is the single source
+ * of truth for control-plane status and identity.
+ */
+export interface SubagentRecord {
+	subagentId: string;
+	ownerId?: string;
+	/** Current live/last AsyncJob id; null while queued with no active job. */
+	currentJobId: string | null;
+	historicalJobIds: string[];
+	status: SubagentLifecycle;
+	sessionFile: string | null;
+	/** False for ephemeral sessions (no persistent artifacts dir). */
+	resumable: boolean;
+	queued?: { ownerId?: string; seq: number; message?: string; createdAt: number };
+}
+
+/** Lightweight, manager-owned resume payload. The async layer treats `data` as opaque. */
+export interface ResumeDescriptor {
+	subagentId: string;
+	ownerId?: string;
+	data: unknown;
+}
+
+/** A pending resume awaiting a free concurrency slot. */
+interface ResumeQueueEntry {
+	subagentId: string;
+	ownerId?: string;
+	seq: number;
+	message?: string;
+	createdAt: number;
+}
+
 export interface AsyncJobManagerOptions {
 	onJobComplete: (jobId: string, text: string, job?: AsyncJob) => void | Promise<void>;
 	maxRunningJobs?: number;
@@ -78,6 +136,56 @@ export interface AsyncJobFilter {
 	ownerId?: string;
 }
 
+function sliceTextFromUtf8ByteOffset(text: string, offsetBytes: number): string {
+	if (offsetBytes <= 0) return text;
+	let consumedBytes = 0;
+	let codeUnitIndex = 0;
+	for (const char of text) {
+		const charBytes = Buffer.byteLength(char, "utf8");
+		if (consumedBytes + charBytes > offsetBytes) break;
+		consumedBytes += charBytes;
+		codeUnitIndex += char.length;
+	}
+	return text.slice(codeUnitIndex);
+}
+
+/**
+ * A slice of process-stream output for a background job, as recorded by
+ * `appendOutput` / read by `readOutputSince`.
+ *
+ * The cursor model is monotonic UTF-8 byte offsets. `nextOffset` is the offset
+ * to pass to the next read to receive only fresh bytes; `startOffset` is the
+ * first byte the manager still retains for this job. When the requested offset
+ * is older than `startOffset`, the manager returns the retained tail and sets
+ * `truncated: true`.
+ */
+export interface AsyncJobOutputSlice {
+	jobId: string;
+	status: AsyncJob["status"];
+	text: string;
+	startOffset: number;
+	nextOffset: number;
+	truncated: boolean;
+}
+
+/** Internal: a single chunk of captured stdout/stderr keyed by its byte range. */
+interface AsyncJobOutputChunk {
+	startByte: number;
+	endByte: number;
+	text: string;
+}
+
+interface AsyncJobOutputState {
+	chunks: AsyncJobOutputChunk[];
+	startOffset: number;
+	nextOffset: number;
+	retainedBytes: number;
+}
+
+/** Default retention cap for per-job captured output. ~512 KiB matches the
+ *  bash tail-buffer order of magnitude without dominating session memory. */
+export const DEFAULT_JOB_OUTPUT_RETENTION_BYTES = 512 * 1024;
+
 export class AsyncJobManager {
 	static #instance: AsyncJobManager | undefined;
 
@@ -102,11 +210,20 @@ export class AsyncJobManager {
 	readonly #suppressedDeliveries = new Set<string>();
 	readonly #watchedJobs = new Set<string>();
 	readonly #evictionTimers = new Map<string, NodeJS.Timeout>();
+	readonly #outputState = new Map<string, AsyncJobOutputState>();
+	readonly #ownerCleanups = new Map<string, Set<() => void>>();
+	readonly #outputRetentionBytes = DEFAULT_JOB_OUTPUT_RETENTION_BYTES;
 	readonly #onJobComplete: AsyncJobManagerOptions["onJobComplete"];
 	readonly #maxRunningJobs: number;
 	readonly #retentionMs: number;
 	#deliveryLoop: Promise<void> | undefined;
 	#disposed = false;
+	readonly #subagentRecords = new Map<string, SubagentRecord>();
+	readonly #liveHandles = new Map<string, SubagentLiveHandle>();
+	readonly #resumeQueue: ResumeQueueEntry[] = [];
+	#resumeSeq = 0;
+	#resumeRunner?: (subagentId: string, message?: string, descriptor?: ResumeDescriptor) => string | undefined;
+	readonly #resumeDescriptors = new Map<string, ResumeDescriptor>();
 
 	#filterJobs(jobs: Iterable<AsyncJob>, filter?: AsyncJobFilter): AsyncJob[] {
 		const ownerId = filter?.ownerId;
@@ -131,7 +248,7 @@ export class AsyncJobManager {
 			jobId: string;
 			signal: AbortSignal;
 			reportProgress: (text: string, details?: Record<string, unknown>) => Promise<void>;
-		}) => Promise<string>,
+		}) => Promise<string | SubagentRunOutcome>,
 		options?: AsyncJobRegisterOptions,
 	): string {
 		if (this.#disposed) {
@@ -174,20 +291,38 @@ export class AsyncJobManager {
 		};
 		job.promise = (async () => {
 			try {
-				const text = await run({ jobId: id, signal: abortController.signal, reportProgress });
+				const result = await run({ jobId: id, signal: abortController.signal, reportProgress });
+				const outcome: SubagentRunOutcome =
+					typeof result === "string" ? { kind: "completed", text: result } : result;
 				if (job.status === "cancelled") {
-					job.resultText = text;
+					job.resultText = outcome.kind === "completed" ? outcome.text : outcome.note;
 					this.#scheduleEviction(id);
+					this.#markRecordTerminal(id, "cancelled");
+					this.#drainResumeQueue();
+					return;
+				}
+				if (outcome.kind === "paused") {
+					// Sole canonical writer of the running -> paused transition. No
+					// delivery and no eviction scheduling: a paused subagent stays
+					// listed and resumable from its sessionFile.
+					job.status = "paused";
+					if (outcome.note) job.resultText = outcome.note;
+					this.#markRecordPaused(id);
+					this.#drainResumeQueue();
 					return;
 				}
 				job.status = "completed";
-				job.resultText = text;
-				this.#enqueueDelivery(id, text);
+				job.resultText = outcome.text;
+				this.#enqueueDelivery(id, outcome.text);
 				this.#scheduleEviction(id);
+				this.#markRecordTerminal(id, "completed");
+				this.#drainResumeQueue();
 			} catch (error) {
 				if (job.status === "cancelled") {
 					job.errorText = error instanceof Error ? error.message : String(error);
 					this.#scheduleEviction(id);
+					this.#markRecordTerminal(id, "cancelled");
+					this.#drainResumeQueue();
 					return;
 				}
 				const errorText = error instanceof Error ? error.message : String(error);
@@ -195,6 +330,8 @@ export class AsyncJobManager {
 				job.errorText = errorText;
 				this.#enqueueDelivery(id, errorText);
 				this.#scheduleEviction(id);
+				this.#markRecordTerminal(id, "failed");
+				this.#drainResumeQueue();
 			}
 		})();
 
@@ -211,6 +348,15 @@ export class AsyncJobManager {
 		const job = this.#jobs.get(id);
 		if (!job) return false;
 		if (filter?.ownerId && job.ownerId !== filter.ownerId) return false;
+		if (job.status === "paused") {
+			// Paused jobs have no running promise to abort; transition directly.
+			// The session file is kept, so the record stays resumable by id.
+			job.status = "cancelled";
+			this.#markRecordTerminal(id, "cancelled");
+			this.#scheduleEviction(id);
+			this.#drainResumeQueue();
+			return true;
+		}
 		if (job.status !== "running") return false;
 		job.status = "cancelled";
 		job.abortController.abort();
@@ -218,6 +364,200 @@ export class AsyncJobManager {
 		return true;
 	}
 
+	// ── Subagent control plane (pause / resume / steer support) ──────────
+
+	/** Register or replace the canonical record for a subagent. */
+	registerSubagentRecord(record: SubagentRecord): void {
+		this.#subagentRecords.set(record.subagentId, record);
+	}
+
+	getSubagentRecord(subagentId: string, filter?: AsyncJobFilter): SubagentRecord | undefined {
+		const rec = this.#subagentRecords.get(subagentId.trim());
+		if (!rec) return undefined;
+		if (filter?.ownerId && rec.ownerId !== filter.ownerId) return undefined;
+		return rec;
+	}
+
+	getSubagentRecords(filter?: AsyncJobFilter): SubagentRecord[] {
+		const ownerId = filter?.ownerId;
+		const out: SubagentRecord[] = [];
+		for (const rec of this.#subagentRecords.values()) {
+			if (ownerId && rec.ownerId !== ownerId) continue;
+			out.push(rec);
+		}
+		return out;
+	}
+
+	registerLiveHandle(subagentId: string, handle: SubagentLiveHandle): void {
+		this.#liveHandles.set(subagentId, handle);
+	}
+
+	getLiveHandle(subagentId: string): SubagentLiveHandle | undefined {
+		return this.#liveHandles.get(subagentId);
+	}
+
+	removeLiveHandle(subagentId: string): void {
+		this.#liveHandles.delete(subagentId);
+	}
+
+	/** Install the TaskTool-owned resume runner. Returns the new job id, or undefined on failure. */
+	setResumeRunner(
+		runner: (subagentId: string, message?: string, descriptor?: ResumeDescriptor) => string | undefined,
+	): void {
+		this.#resumeRunner = runner;
+	}
+
+	registerResumeDescriptor(descriptor: ResumeDescriptor): void {
+		this.#resumeDescriptors.set(descriptor.subagentId, descriptor);
+	}
+
+	getResumeDescriptor(subagentId: string, filter?: AsyncJobFilter): ResumeDescriptor | undefined {
+		const descriptor = this.#resumeDescriptors.get(subagentId.trim());
+		if (!descriptor) return undefined;
+		if (filter?.ownerId && descriptor.ownerId !== filter.ownerId) return undefined;
+		return descriptor;
+	}
+
+	#recordByJobId(jobId: string): SubagentRecord | undefined {
+		for (const rec of this.#subagentRecords.values()) {
+			if (rec.currentJobId === jobId) return rec;
+		}
+		return undefined;
+	}
+
+	#markRecordPaused(jobId: string): void {
+		const rec = this.#recordByJobId(jobId);
+		if (rec) {
+			rec.status = "paused";
+			this.#liveHandles.delete(rec.subagentId);
+		}
+	}
+
+	#markRecordTerminal(jobId: string, status: "completed" | "failed" | "cancelled"): void {
+		const rec = this.#recordByJobId(jobId);
+		if (!rec) return;
+		rec.status = status;
+		this.#liveHandles.delete(rec.subagentId);
+	}
+
+	/** Request a graceful safe-boundary pause of a running subagent. */
+	pauseSubagent(
+		subagentId: string,
+		filter?: AsyncJobFilter,
+	): { ok: boolean; status?: SubagentLifecycle; reason?: string } {
+		const rec = this.getSubagentRecord(subagentId, filter);
+		if (!rec) return { ok: false, reason: "not_found" };
+		if (rec.status !== "running") return { ok: false, status: rec.status, reason: "not_running" };
+		const handle = this.#liveHandles.get(rec.subagentId);
+		if (!handle) return { ok: false, status: rec.status, reason: "no_live_handle" };
+		handle.requestPause();
+		return { ok: true, status: rec.status };
+	}
+
+	/** Resume a non-running subagent from its sessionFile, optionally injecting a message first. */
+	resumeSubagent(
+		subagentId: string,
+		filter?: AsyncJobFilter,
+		message?: string,
+	): { ok: boolean; status?: SubagentLifecycle; jobId?: string; queued?: boolean; reason?: string } {
+		const rec = this.getSubagentRecord(subagentId, filter);
+		if (!rec) return { ok: false, reason: "not_found" };
+		if (rec.status === "running") return { ok: false, status: "running", reason: "already_running" };
+		if (rec.status === "queued") {
+			if (message !== undefined && rec.queued) {
+				rec.queued.message = message;
+				const queued = this.#resumeQueue.find(entry => entry.subagentId === rec.subagentId);
+				if (queued) queued.message = message;
+				return { ok: true, queued: true, status: "queued" };
+			}
+			return { ok: false, status: "queued", reason: "already_queued" };
+		}
+		if (!rec.resumable || !rec.sessionFile) return { ok: false, reason: "context_unavailable" };
+		if (!this.#resumeRunner) return { ok: false, reason: "no_runner" };
+		if (this.getRunningJobs().length >= this.#maxRunningJobs) {
+			const seq = ++this.#resumeSeq;
+			rec.status = "queued";
+			rec.queued = { ownerId: rec.ownerId, seq, message, createdAt: Date.now() };
+			this.#resumeQueue.push({
+				subagentId: rec.subagentId,
+				ownerId: rec.ownerId,
+				seq,
+				message,
+				createdAt: rec.queued.createdAt,
+			});
+			return { ok: true, queued: true, status: "queued" };
+		}
+		return this.#startResume(rec, message);
+	}
+
+	#startResume(
+		rec: SubagentRecord,
+		message?: string,
+	): { ok: boolean; status?: SubagentLifecycle; jobId?: string; reason?: string } {
+		const prevJobId = rec.currentJobId;
+		const newJobId = this.#resumeRunner?.(rec.subagentId, message, this.#resumeDescriptors.get(rec.subagentId));
+		if (!newJobId) return { ok: false, reason: "resume_failed" };
+		if (prevJobId && prevJobId !== newJobId) rec.historicalJobIds.push(prevJobId);
+		rec.currentJobId = newJobId;
+		rec.status = this.#jobs.get(newJobId)?.status ?? "running";
+		rec.queued = undefined;
+		return { ok: true, status: rec.status, jobId: newJobId };
+	}
+
+	/** Drain queued resumes (FIFO by seq) while concurrency slots are available. */
+	#drainResumeQueue(): void {
+		if (this.#resumeQueue.length === 0) return;
+		this.#resumeQueue.sort((a, b) => a.seq - b.seq);
+		while (this.#resumeQueue.length > 0 && this.getRunningJobs().length < this.#maxRunningJobs) {
+			const entry = this.#resumeQueue.shift();
+			if (!entry) return;
+			const rec = this.#subagentRecords.get(entry.subagentId);
+			if (rec?.status !== "queued") continue;
+			this.#startResume(rec, entry.message);
+		}
+	}
+
+	/** Cancel a subagent by stable id across running/paused/queued states (keeps the session file). */
+	cancelSubagent(subagentId: string, filter?: AsyncJobFilter): boolean {
+		const rec = this.getSubagentRecord(subagentId, filter);
+		if (!rec) return false;
+		if (rec.status === "running" && rec.currentJobId) return this.cancel(rec.currentJobId, filter);
+		if (rec.status === "paused") {
+			if (rec.currentJobId) {
+				const job = this.#jobs.get(rec.currentJobId);
+				if (job && job.status === "paused") {
+					job.status = "cancelled";
+					this.#scheduleEviction(rec.currentJobId);
+				}
+			}
+			rec.status = "cancelled";
+			this.#liveHandles.delete(rec.subagentId);
+			this.#drainResumeQueue();
+			return true;
+		}
+		if (rec.status === "queued") {
+			const idx = this.#resumeQueue.findIndex(e => e.subagentId === rec.subagentId);
+			if (idx !== -1) this.#resumeQueue.splice(idx, 1);
+			rec.status = "cancelled";
+			rec.queued = undefined;
+			return true;
+		}
+		return false;
+	}
+
+	#purgeOwnerSubagentState(ownerId?: string): void {
+		for (let i = this.#resumeQueue.length - 1; i >= 0; i--) {
+			if (!ownerId || this.#resumeQueue[i].ownerId === ownerId) this.#resumeQueue.splice(i, 1);
+		}
+		for (const [sid, rec] of this.#subagentRecords) {
+			if (!ownerId || rec.ownerId === ownerId) {
+				this.#liveHandles.delete(sid);
+				this.#resumeDescriptors.delete(sid);
+				this.#subagentRecords.delete(sid);
+			}
+		}
+	}
+
 	getJob(id: string): AsyncJob | undefined {
 		return this.#jobs.get(id);
 	}
@@ -237,6 +577,170 @@ export class AsyncJobManager {
 		return this.#filterJobs(this.#jobs.values(), filter);
 	}
 
+	/**
+	 * Append a sanitized process-stream chunk for a background job. Called from
+	 * the unthrottled bash-executor capture hook (`onRawChunk`) so monitor sees
+	 * every chunk even when preview/progress callbacks are throttled.
+	 *
+	 * Offsets are in UTF-8 bytes. Storing chunk metadata avoids unsafe byte
+	 * slicing across multibyte characters at read time. The retention window is
+	 * a per-job rolling cap (`DEFAULT_JOB_OUTPUT_RETENTION_BYTES`); when it
+	 * overflows, oldest whole chunks are evicted and `startOffset` advances —
+	 * subsequent reads from a stale offset get `truncated: true`.
+	 */
+	appendOutput(jobId: string, chunk: string): void {
+		if (this.#disposed) return;
+		if (!chunk) return;
+		if (!this.#jobs.has(jobId)) return;
+
+		const state = this.#outputState.get(jobId) ?? {
+			chunks: [],
+			startOffset: 0,
+			nextOffset: 0,
+			retainedBytes: 0,
+		};
+
+		const byteLength = Buffer.byteLength(chunk, "utf8");
+		if (byteLength === 0) return;
+
+		const startByte = state.nextOffset;
+		const endByte = startByte + byteLength;
+		state.chunks.push({ startByte, endByte, text: chunk });
+		state.retainedBytes += byteLength;
+		state.nextOffset = endByte;
+
+		while (state.retainedBytes > this.#outputRetentionBytes && state.chunks.length > 0) {
+			const dropped = state.chunks.shift();
+			if (!dropped) break;
+			const droppedBytes = dropped.endByte - dropped.startByte;
+			state.retainedBytes -= droppedBytes;
+			state.startOffset = dropped.endByte;
+		}
+
+		this.#outputState.set(jobId, state);
+	}
+
+	/**
+	 * Read fresh process-stream output for a job since `offset` (in UTF-8
+	 * bytes). Returns `undefined` when the job does not exist or when an
+	 * `ownerId` filter is set and the job belongs to a different owner — this
+	 * mirrors the manager-level "not found" pattern used by `cancel`.
+	 *
+	 * - `offset < startOffset` returns the retained tail with `truncated: true`.
+	 * - `offset > nextOffset` clamps to `nextOffset` and returns an empty text
+	 *   slice with `truncated: false`.
+	 * - Assembled text slices the leading retained chunk at a UTF-8 codepoint
+	 *   boundary when needed, so multibyte characters cannot be split.
+	 */
+	readOutputSince(jobId: string, offset: number, filter?: AsyncJobFilter): AsyncJobOutputSlice | undefined {
+		const job = this.#jobs.get(jobId);
+		if (!job) return undefined;
+		if (filter?.ownerId && job.ownerId !== filter.ownerId) return undefined;
+
+		const state = this.#outputState.get(jobId);
+		if (!state) {
+			return {
+				jobId,
+				status: job.status,
+				text: "",
+				startOffset: 0,
+				nextOffset: 0,
+				truncated: false,
+			};
+		}
+
+		const requestedOffset = Math.max(0, Math.floor(offset));
+		if (requestedOffset >= state.nextOffset) {
+			return {
+				jobId,
+				status: job.status,
+				text: "",
+				startOffset: state.startOffset,
+				nextOffset: state.nextOffset,
+				truncated: false,
+			};
+		}
+
+		const truncated = requestedOffset < state.startOffset;
+		const effectiveOffset = truncated ? state.startOffset : requestedOffset;
+		const parts: string[] = [];
+		for (const chunk of state.chunks) {
+			if (chunk.endByte <= effectiveOffset) continue;
+			if (effectiveOffset > chunk.startByte) {
+				parts.push(sliceTextFromUtf8ByteOffset(chunk.text, effectiveOffset - chunk.startByte));
+				continue;
+			}
+			parts.push(chunk.text);
+		}
+
+		return {
+			jobId,
+			status: job.status,
+			text: parts.join(""),
+			startOffset: state.startOffset,
+			nextOffset: state.nextOffset,
+			truncated,
+		};
+	}
+
+	/**
+	 * Register an owner-scoped cleanup callback. Returns an unregister function.
+	 *
+	 * Used by Cron* tools to clear session-scoped timers when the owning agent
+	 * is torn down. Invoked by `runOwnerCleanups({ ownerId })` before
+	 * `cancelAll({ ownerId })` so timers cannot register new jobs during
+	 * teardown.
+	 */
+	registerOwnerCleanup(ownerId: string, cleanup: () => void): () => void {
+		if (!ownerId) {
+			throw new Error("registerOwnerCleanup requires a non-empty ownerId");
+		}
+		let bag = this.#ownerCleanups.get(ownerId);
+		if (!bag) {
+			bag = new Set();
+			this.#ownerCleanups.set(ownerId, bag);
+		}
+		bag.add(cleanup);
+		return () => {
+			const current = this.#ownerCleanups.get(ownerId);
+			if (!current) return;
+			current.delete(cleanup);
+			if (current.size === 0) this.#ownerCleanups.delete(ownerId);
+		};
+	}
+
+	/**
+	 * Run and clear every registered cleanup for the given filter. Idempotent
+	 * and error-isolated: a throwing cleanup does not prevent siblings from
+	 * running and never escalates to the caller.
+	 */
+	runOwnerCleanups(filter?: AsyncJobFilter): void {
+		const ownerId = filter?.ownerId;
+		const targets: Array<[string, Set<() => void>]> = [];
+		if (ownerId) {
+			const bag = this.#ownerCleanups.get(ownerId);
+			if (bag) targets.push([ownerId, bag]);
+		} else {
+			for (const entry of this.#ownerCleanups.entries()) targets.push(entry);
+		}
+		for (const [id, bag] of targets) {
+			const callbacks = Array.from(bag);
+			bag.clear();
+			this.#ownerCleanups.delete(id);
+			for (const cleanup of callbacks) {
+				try {
+					cleanup();
+				} catch (error) {
+					logger.warn("Async job owner cleanup failed", {
+						ownerId: id,
+						error: error instanceof Error ? error.message : String(error),
+					});
+				}
+			}
+		}
+		this.#purgeOwnerSubagentState(ownerId);
+	}
+
 	getDeliveryState(filter?: AsyncJobFilter): AsyncJobDeliveryState {
 		const deliveries = this.#filterDeliveries(filter);
 		const inFlightDeliveries = this.#filterInFlightDeliveries(filter);
@@ -357,6 +861,10 @@ export class AsyncJobManager {
 	async dispose(options?: { timeoutMs?: number }): Promise<boolean> {
 		this.#disposed = true;
 		this.#clearEvictionTimers();
+		// Run-and-clear any remaining owner cleanups before tearing down jobs so
+		// late-arriving timers cannot register fresh work against a disposed
+		// manager. Errors in cleanup callbacks are logged but never escalated.
+		this.runOwnerCleanups();
 		this.cancelAll();
 		await this.waitForAll();
 		const drained = await this.drainDeliveries({ timeoutMs: options?.timeoutMs ?? 3_000 });
@@ -366,6 +874,12 @@ export class AsyncJobManager {
 		this.#inFlightDeliveries.length = 0;
 		this.#suppressedDeliveries.clear();
 		this.#watchedJobs.clear();
+		this.#outputState.clear();
+		this.#ownerCleanups.clear();
+		this.#subagentRecords.clear();
+		this.#liveHandles.clear();
+		this.#resumeDescriptors.clear();
+		this.#resumeQueue.length = 0;
 		return drained;
 	}
 
@@ -399,6 +913,7 @@ export class AsyncJobManager {
 			this.#jobs.delete(jobId);
 			this.#suppressedDeliveries.delete(jobId);
 			this.#watchedJobs.delete(jobId);
+			this.#outputState.delete(jobId);
 			return;
 		}
 		const existing = this.#evictionTimers.get(jobId);
@@ -410,6 +925,7 @@ export class AsyncJobManager {
 			this.#jobs.delete(jobId);
 			this.#suppressedDeliveries.delete(jobId);
 			this.#watchedJobs.delete(jobId);
+			this.#outputState.delete(jobId);
 		}, this.#retentionMs);
 		timer.unref();
 		this.#evictionTimers.set(jobId, timer);

package/src/cli/agents-cli.ts

@@ -64,6 +64,9 @@ function toFrontmatter(agent: AgentDefinition): Record<string, unknown> {
 	if (agent.thinkingLevel) frontmatter.thinkingLevel = agent.thinkingLevel;
 	if (agent.output !== undefined) frontmatter.output = agent.output;
 	if (agent.blocking) frontmatter.blocking = true;
+	if (agent.bashAllowedPrefixes && agent.bashAllowedPrefixes.length > 0) {
+		frontmatter.bashAllowedPrefixes = agent.bashAllowedPrefixes;
+	}
 
 	return frontmatter;
 }

package/src/cli/auth-broker-cli.ts

@@ -69,6 +69,7 @@ const CALLBACK_PORTS: Record<string, number> = {
 	"google-gemini-cli": 8085,
 	"google-antigravity": 51121,
 	"gitlab-duo": 8080,
+	xai: 56121,
 };
 
 function getTokenFilePath(): string {