@gajae-code/coding-agent 0.12.4 → 0.12.6

package/src/internal-urls/local-protocol.ts

@@ -80,10 +80,32 @@ async function listFilesRecursively(rootPath: string): Promise<string[]> {
 
 	return files.sort((a, b) => a.localeCompare(b));
 }
+function localListingLabel(file: string): string {
+	return file.replace(/[\\[\]\r\n]/g, character => {
+		switch (character) {
+			case "\r":
+				return "\\r";
+			case "\n":
+				return "\\n";
+			default:
+				return `\\${character}`;
+		}
+	});
+}
+
+function localListingHref(file: string): string {
+	return file
+		.split("/")
+		.map(component => encodeURIComponent(component).replaceAll("(", "%28").replaceAll(")", "%29"))
+		.join("/");
+}
 
 async function buildListing(url: InternalUrl, localRoot: string): Promise<InternalResource> {
 	const files = await listFilesRecursively(localRoot);
-	const listing = files.length === 0 ? "(empty)" : files.map(file => `- [${file}](local://${file})`).join("\n");
+	const listing =
+		files.length === 0
+			? "(empty)"
+			: files.map(file => `- [${localListingLabel(file)}](local://${localListingHref(file)})`).join("\n");
 	const content =
 		`# Local\n\n` +
 		`Session-scoped scratch space for large intermediate data, subagent handoffs, and reusable planning artifacts.\n\n` +
@@ -103,31 +125,30 @@ async function buildListing(url: InternalUrl, localRoot: string): Promise<Intern
 function extractRelativePath(url: InternalUrl): string {
 	const host = url.rawHost || url.hostname;
 	const pathname = url.rawPathname ?? url.pathname;
-
-	const combined = host
-		? pathname && pathname !== "/"
-			? `${host}${pathname}`
-			: host
-		: pathname && pathname !== "/"
-			? pathname.slice(1)
-			: "";
-
-	if (!combined) {
-		return "";
-	}
-
-	let decoded: string;
+	const encodedAuthority = /^local:\/\/([^/?#]*)/i.exec(url.href)?.[1] ?? "";
+	const validatedHost = host;
+	let decodedPathname = pathname;
 	try {
-		decoded = decodeURIComponent(combined.replaceAll("\\", "/"));
+		const decodedAuthority = decodeURIComponent(encodedAuthority);
+		if (host && decodedAuthority !== host) throw new Error("authority_mismatch");
+		decodedPathname = decodeURIComponent(pathname.replaceAll("\\", "/"));
 	} catch {
 		throw new Error(`Invalid URL encoding in local:// path: ${url.href}`);
 	}
+	const combined = validatedHost
+		? decodedPathname && decodedPathname !== "/"
+			? `${validatedHost}${decodedPathname}`
+			: validatedHost
+		: decodedPathname && decodedPathname !== "/"
+			? decodedPathname.slice(1)
+			: "";
+	if (!combined) return "";
 	try {
-		validateRelativePath(decoded);
+		validateRelativePath(combined);
 	} catch (error) {
 		throw toLocalValidationError(error);
 	}
-	return decoded;
+	return combined;
 }
 
 function safeSessionId(options: LocalProtocolOptions): string {

package/src/internal-urls/registry-helpers.ts

@@ -2,7 +2,10 @@
  * Shared helpers for internal-url protocol handlers that resolve session-scoped
  * artifact IDs.
  */
+
+import * as fs from "node:fs";
 import * as path from "node:path";
+import { openRecoveryFsRoot, type RecoveryFsRoot } from "@gajae-code/natives";
 import type { ResolveContext } from "./types";
 
 function addDir(dirs: string[], dir: string | null | undefined): void {
@@ -26,3 +29,62 @@ export function authorizedArtifactsDirsFromContext(context?: ResolveContext): st
 	for (const dir of context?.getAuthorizedArtifactsDirs?.() ?? []) addDir(dirs, dir);
 	return dirs;
 }
+
+export interface AuthorizedArtifactsRoot {
+	readonly directory: string;
+	readonly dev: bigint;
+	readonly ino: bigint;
+	readonly authority: RecoveryFsRoot;
+}
+
+export interface AuthorizedArtifactSnapshot {
+	bytes: Buffer;
+	size: number;
+}
+
+export function openAuthorizedArtifactsRoot(directory: string): AuthorizedArtifactsRoot {
+	if (process.platform !== "linux") throw new Error("artifact_authority_unavailable");
+	const named = fs.lstatSync(directory, { bigint: true });
+	if (!named.isDirectory() || named.isSymbolicLink()) throw new Error("unsafe_artifacts_root");
+	const authority = openRecoveryFsRoot(directory);
+	const retained = authority.identity();
+	if (
+		!retained.ok ||
+		!retained.identity ||
+		retained.identity.dev !== named.dev.toString() ||
+		retained.identity.ino !== named.ino.toString()
+	) {
+		authority.close();
+		throw new Error("unsafe_artifacts_root");
+	}
+	return { directory, dev: named.dev, ino: named.ino, authority };
+}
+
+export function closeAuthorizedArtifactsRoot(root: AuthorizedArtifactsRoot): void {
+	root.authority.close();
+}
+
+export function readAuthorizedArtifactFile(
+	root: AuthorizedArtifactsRoot,
+	filename: string,
+	maxBytes: number,
+): AuthorizedArtifactSnapshot | null {
+	if (
+		path.basename(filename) !== filename ||
+		!Number.isSafeInteger(maxBytes) ||
+		maxBytes < 0 ||
+		maxBytes > 16 * 1024 * 1024
+	) {
+		throw new Error("unsafe_artifact_leaf");
+	}
+	if (!root.authority) throw new Error("artifact_authority_unavailable");
+	const captured = root.authority.read(filename, maxBytes);
+	if (!captured.ok) {
+		if (captured.code === "not_found") return null;
+		throw new Error(`unsafe_artifact_leaf:${captured.code ?? "capture_failed"}`);
+	}
+	if (!captured.data || !captured.identity) throw new Error("unsafe_artifact_leaf:missing_evidence");
+	const size = Number(captured.identity.size);
+	if (!Number.isSafeInteger(size) || size < 0) throw new Error("unsafe_artifact_leaf:invalid_size");
+	return { bytes: Buffer.from(captured.data), size };
+}

package/src/modes/acp/acp-agent.ts

@@ -660,6 +660,10 @@ export function createAcpReverseConnection(connection: AgentSideConnection, sess
 		"fs.readTextFile": "fs/read_text_file",
 		"fs.writeTextFile": "fs/write_text_file",
 		"terminal.create": "terminal/create",
+		"terminal.output": "terminal/output",
+		"terminal.waitForExit": "terminal/wait_for_exit",
+		"terminal.kill": "terminal/kill",
+		"terminal.release": "terminal/release",
 		"ui.elicit": "elicitation/create",
 	};
 	return {
@@ -668,6 +672,26 @@ export function createAcpReverseConnection(connection: AgentSideConnection, sess
 			params: JsonObject,
 			options?: { cancellationSignal?: AbortSignal },
 		): Promise<unknown> => {
+			if (method === "terminal.publish") {
+				const toolCallId = typeof params.toolCallId === "string" ? params.toolCallId : undefined;
+				const terminalId = typeof params.terminalId === "string" ? params.terminalId : undefined;
+				if (!toolCallId || !terminalId) {
+					throw new AcpSdkAdapterError(
+						"invalid_params",
+						"ACP terminal publication requires toolCallId and terminalId.",
+					);
+				}
+				await connection.sessionUpdate({
+					sessionId,
+					update: {
+						sessionUpdate: "tool_call_update",
+						toolCallId,
+						status: "in_progress",
+						content: [{ type: "terminal", terminalId }],
+					},
+				});
+				return {};
+			}
 			const name = methods[method];
 			if (!name)
 				throw new AcpSdkAdapterError("acp_reverse_unavailable", `ACP reverse method is unavailable: ${method}`);
@@ -718,6 +742,7 @@ export class AcpAgent implements Agent {
 	readonly #resolvingExisting = new Map<string, PendingAttachment>();
 	readonly #knownSessionCwds = new Map<string, string>();
 	readonly #knownSessionMetadata = new Map<string, { title?: string; updatedAt?: string }>();
+	readonly #pendingDeleteLocators = new Map<string, { cwd: string; path: string }>();
 	readonly #pendingCloseIdempotencyKeys = new Map<string, string>();
 	readonly #sessionEpochs = new Map<string, number>();
 	readonly #tearingDown = new Map<string, number>();
@@ -918,24 +943,35 @@ export class AcpAgent implements Agent {
 
 	async deleteSession(params: DeleteSessionRequest): Promise<DeleteSessionResponse> {
 		const record = this.#sessions.get(params.sessionId);
-		const cwd = record?.cwd ?? this.#knownSessionCwds.get(params.sessionId);
-		// ACP's delete request has no cwd. Only delete sessions this connection has
-		// already scoped through the broker; unknown ids remain the protocol no-op.
-		if (!cwd) return {};
+		const pendingLocator = this.#pendingDeleteLocators.get(params.sessionId);
+		const cwd = record?.cwd ?? this.#knownSessionCwds.get(params.sessionId) ?? pendingLocator?.cwd;
+		// ACP's delete request has no cwd. Unknown ids remain the protocol no-op,
+		// while the broker can reconstruct an authenticated pending locator from its durable ledger.
+		if (!cwd) {
+			await (await this.#brokerAdapter()).global(
+				"session.delete",
+				{ sessionId: params.sessionId },
+				this.#lifecycleIdempotencyKey(params.sessionId, "session.delete"),
+			);
+			return {};
+		}
 		this.#beginTeardown(params.sessionId);
 		try {
 			await this.#teardownSession(params.sessionId, "deleted", true);
-			let saved: string;
-			try {
-				saved = await this.#resolveSavedSession(params.sessionId, cwd);
-			} catch (error) {
-				if (error instanceof AcpSdkAdapterError && error.code === "not_found") {
-					this.#knownSessionCwds.delete(params.sessionId);
-					this.#knownSessionMetadata.delete(params.sessionId);
-					return {};
+			let saved = pendingLocator?.cwd === cwd ? pendingLocator.path : undefined;
+			if (!saved) {
+				try {
+					saved = await this.#resolveSavedSession(params.sessionId, cwd);
+				} catch (error) {
+					if (error instanceof AcpSdkAdapterError && error.code === "not_found") {
+						this.#knownSessionCwds.delete(params.sessionId);
+						this.#knownSessionMetadata.delete(params.sessionId);
+						return {};
+					}
+					throw error;
 				}
-				throw error;
 			}
+			this.#pendingDeleteLocators.set(params.sessionId, { cwd, path: saved });
 			await (await this.#brokerAdapter()).global(
 				"session.delete",
 				{ sessionId: params.sessionId, sessionPath: saved, cwd, target: { path: cwd } },
@@ -943,6 +979,7 @@ export class AcpAgent implements Agent {
 			);
 			this.#knownSessionCwds.delete(params.sessionId);
 			this.#knownSessionMetadata.delete(params.sessionId);
+			this.#pendingDeleteLocators.delete(params.sessionId);
 			return {};
 		} finally {
 			this.#finishTeardown(params.sessionId);
@@ -2168,6 +2205,7 @@ export class AcpAgent implements Agent {
 		this.#resolvingExisting.clear();
 		this.#knownSessionCwds.clear();
 		this.#knownSessionMetadata.clear();
+		this.#pendingDeleteLocators.clear();
 		this.#pendingCloseIdempotencyKeys.clear();
 		if (this.#closing.size === 0) this.#closing.clear();
 		this.#tearingDown.clear();

package/src/modes/acp/acp-client-bridge.ts

@@ -4,6 +4,8 @@
  * `AgentSession`) can route through the client when it advertises the
  * relevant capabilities at `initialize` time.
  */
+
+import { randomUUID } from "node:crypto";
 import type {
 	PermissionOption as AcpPermissionOption,
 	TerminalHandle as AcpTerminalHandle,
@@ -19,10 +21,25 @@ import type {
 	ClientBridgePermissionOption,
 	ClientBridgePermissionOutcome,
 	ClientBridgePermissionToolCall,
+	ClientBridgeProviderLeaseIdentity,
 	ClientBridgeTerminalHandle,
 } from "../../session/client-bridge";
 import { resolveAcpPermissionMode } from "./permission-mode";
 
+const ACP_TERMINAL_PUBLICATION_WAIT_MS = 500;
+
+async function settleTerminalCleanup(operation: () => Promise<unknown>): Promise<boolean> {
+	return await Promise.race([
+		Promise.resolve()
+			.then(operation)
+			.then(
+				() => true,
+				() => false,
+			),
+		Bun.sleep(ACP_TERMINAL_PUBLICATION_WAIT_MS).then(() => false),
+	]);
+}
+
 export { type AcpPermissionMode, resolveAcpPermissionMode } from "./permission-mode";
 
 export function createAcpClientBridge(
@@ -39,6 +56,15 @@ export function createAcpClientBridge(
 	};
 
 	const bridge: ClientBridge = { capabilities, deferAgentInitiatedTurns: true };
+	const connectionId = `acp:${sessionId}`;
+	const connectionGeneration = 1;
+	const terminalProviderLeaseId = `${connectionId}:${randomUUID()}`;
+	const terminalProviderIdentity: ClientBridgeProviderLeaseIdentity = {
+		leaseId: terminalProviderLeaseId,
+		connectionId,
+		connectionGeneration,
+		fence: randomUUID(),
+	};
 
 	if (capabilities.readTextFile) {
 		bridge.readTextFile = async params => {
@@ -63,8 +89,49 @@ export function createAcpClientBridge(
 	}
 
 	if (capabilities.terminal) {
+		let terminalPublicationFailed = false;
+		bridge.quarantineProviderLease = async (providerLease, _reason) => {
+			if (
+				typeof providerLease === "string" ||
+				providerLease.leaseId !== terminalProviderIdentity.leaseId ||
+				providerLease.connectionId !== terminalProviderIdentity.connectionId ||
+				providerLease.connectionGeneration !== terminalProviderIdentity.connectionGeneration ||
+				providerLease.fence !== terminalProviderIdentity.fence
+			)
+				throw new Error("terminal provider lease mismatch");
+			terminalPublicationFailed = true;
+		};
+		let terminalCreationTail = Promise.resolve();
+		const withTerminalCreationAdmission = async <T>(operation: () => Promise<T>): Promise<T> => {
+			const previous = terminalCreationTail;
+			const release = Promise.withResolvers<void>();
+			terminalCreationTail = previous.then(() => release.promise);
+			await previous;
+			try {
+				return await operation();
+			} finally {
+				release.resolve();
+			}
+		};
 		bridge.createTerminal = (params: ClientBridgeCreateTerminalParams) =>
-			createTerminalHandle(connection, sessionId, params);
+			withTerminalCreationAdmission(async () => {
+				if (terminalPublicationFailed) throw new Error("terminal provider quarantined after publication failure");
+				const creationTimeout = AbortSignal.timeout(ACP_TERMINAL_PUBLICATION_WAIT_MS);
+				const creationSignal = params.signal ? AbortSignal.any([params.signal, creationTimeout]) : creationTimeout;
+				return await createTerminalHandle(
+					connection,
+					sessionId,
+					params,
+					creationSignal,
+					terminalProviderIdentity,
+					() => {
+						terminalPublicationFailed = true;
+					},
+					() => {
+						terminalPublicationFailed = true;
+					},
+				);
+			});
 	}
 
 	if (promptPermission) {
@@ -79,21 +146,97 @@ async function createTerminalHandle(
 	connection: AgentSideConnection,
 	sessionId: string,
 	params: ClientBridgeCreateTerminalParams,
+	creationSignal: AbortSignal,
+	providerIdentity: ClientBridgeProviderLeaseIdentity,
+	onCreationUncertain: () => void,
+	onPublicationFailure: () => void,
 ): Promise<ClientBridgeTerminalHandle> {
-	const handle = await connection.createTerminal({
-		sessionId,
-		command: params.command,
-		...(params.args ? { args: params.args } : {}),
-		...(params.env ? { env: params.env } : {}),
-		...(params.cwd ? { cwd: params.cwd } : {}),
-		...(typeof params.outputByteLimit === "number" ? { outputByteLimit: params.outputByteLimit } : {}),
-	});
-	return wrapTerminalHandle(handle);
+	if (creationSignal.aborted) throw new Error("terminal creation aborted");
+	const creation = Promise.resolve().then(() =>
+		connection.createTerminal({
+			sessionId,
+			command: params.command,
+			...(params.args ? { args: params.args } : {}),
+			...(params.env ? { env: params.env } : {}),
+			...(params.cwd ? { cwd: params.cwd } : {}),
+			...(typeof params.outputByteLimit === "number" ? { outputByteLimit: params.outputByteLimit } : {}),
+		}),
+	);
+	const creationAborted = Promise.withResolvers<"aborted">();
+	const onCreationAbort = () => creationAborted.resolve("aborted");
+	creationSignal.addEventListener("abort", onCreationAbort, { once: true });
+	if (creationSignal.aborted) creationAborted.resolve("aborted");
+	const creationOutcome = await Promise.race([
+		creation.then(
+			handle => ({ status: "created" as const, handle }),
+			error => ({ status: "failed" as const, error }),
+		),
+		creationAborted.promise.then(() => ({ status: "aborted" as const })),
+	]);
+	creationSignal.removeEventListener("abort", onCreationAbort);
+	if (creationOutcome.status === "aborted") {
+		onCreationUncertain();
+		void creation.then(
+			async handle => {
+				await settleTerminalCleanup(() => handle.kill());
+				await settleTerminalCleanup(() => handle.release());
+			},
+			() => undefined,
+		);
+		throw new Error("terminal creation aborted");
+	}
+	if (creationOutcome.status === "failed") {
+		onCreationUncertain();
+		throw creationOutcome.error;
+	}
+	const handle = creationOutcome.handle;
+	const publication = Promise.resolve().then(() =>
+		connection.sessionUpdate({
+			sessionId,
+			update: {
+				sessionUpdate: "tool_call_update",
+				toolCallId: params.toolCallId,
+				status: "in_progress",
+				content: [{ type: "terminal", terminalId: handle.id }],
+			},
+		}),
+	);
+	const aborted = Promise.withResolvers<"aborted">();
+	const onAbort = () => aborted.resolve("aborted");
+	params.signal?.addEventListener("abort", onAbort, { once: true });
+	if (params.signal?.aborted) aborted.resolve("aborted");
+	const outcome = await Promise.race([
+		publication.then(
+			() => ({ status: "published" as const }),
+			error => ({ status: "failed" as const, error }),
+		),
+		Bun.sleep(ACP_TERMINAL_PUBLICATION_WAIT_MS).then(() => ({ status: "timeout" as const })),
+		aborted.promise.then(() => ({ status: "aborted" as const })),
+	]);
+	params.signal?.removeEventListener("abort", onAbort);
+	if (outcome.status !== "published") {
+		const killed = await settleTerminalCleanup(() => handle.kill());
+		const released = await settleTerminalCleanup(() => handle.release());
+		if (!params.signal?.aborted || !killed || !released) onPublicationFailure();
+		if (outcome.status === "failed") throw outcome.error;
+		throw new Error(
+			outcome.status === "aborted"
+				? "terminal publication aborted"
+				: `terminal publication did not settle within ${ACP_TERMINAL_PUBLICATION_WAIT_MS}ms`,
+		);
+	}
+	return wrapTerminalHandle(handle, providerIdentity.leaseId, providerIdentity);
 }
 
-function wrapTerminalHandle(handle: AcpTerminalHandle): ClientBridgeTerminalHandle {
+function wrapTerminalHandle(
+	handle: AcpTerminalHandle,
+	providerLeaseId: string,
+	providerLeaseIdentity: ClientBridgeProviderLeaseIdentity,
+): ClientBridgeTerminalHandle {
 	return {
 		terminalId: handle.id,
+		providerLeaseId,
+		providerLeaseIdentity,
 		async currentOutput() {
 			const out = await handle.currentOutput();
 			return {

package/src/modes/components/gjc-bundle-settings.ts

@@ -56,6 +56,7 @@ export interface GjcBundleSettingsDependencies {
 export interface GjcBundleSettingsCallbacks {
 	onClose: () => void;
 	onBundlesChanged?: () => void;
+	onRenderRequested?: () => void;
 }
 
 export type GjcBundleSettingsState =
@@ -187,6 +188,7 @@ export class GjcBundleSettingsComponent extends Container {
 			),
 		);
 		this.addChild(new DynamicBorder());
+		this.callbacks.onRenderRequested?.();
 	}
 
 	#renderList(): void {

package/src/modes/components/plugin-settings.ts

@@ -127,6 +127,7 @@ export interface PluginDetailCallbacks {
 	onFeatureChange: (feature: string, enabled: boolean) => void;
 	onConfigChange: (key: string, value: unknown) => void;
 	onBack: () => void;
+	onRenderRequested?: () => void;
 }
 
 /**
@@ -288,6 +289,7 @@ export class PluginDetailComponent extends Container {
 		this.addChild(new Spacer(1));
 		this.addChild(new Text(theme.fg("dim", "  Enter to edit · Esc to go back"), 0, 0));
 		this.addChild(new DynamicBorder());
+		this.callbacks.onRenderRequested?.();
 	}
 
 	handleInput(data: string): void {
@@ -409,6 +411,7 @@ class ConfigInputSubmenu extends Container {
 export interface PluginSettingsCallbacks {
 	onClose: () => void;
 	onPluginChanged: () => void;
+	onRenderRequested?: () => void;
 }
 
 /** Component with handleInput method */
@@ -450,6 +453,7 @@ export class PluginSettingsComponent extends Container {
 		});
 
 		this.addChild(this.#viewComponent);
+		this.callbacks.onRenderRequested?.();
 	}
 
 	#showPluginDetail(plugin: InstalledPlugin): void {
@@ -477,6 +481,7 @@ export class PluginSettingsComponent extends Container {
 				this.callbacks.onPluginChanged();
 			},
 			onBack: () => this.#showPluginList(),
+			onRenderRequested: () => this.callbacks.onRenderRequested?.(),
 		});
 
 		this.addChild(this.#viewComponent);

package/src/modes/components/settings-selector.ts

@@ -719,6 +719,8 @@ export interface SettingsCallbacks {
 	getStatusLinePreview?: (width?: number) => string;
 	/** Called when plugins change */
 	onPluginsChanged?: () => void;
+	/** Called when asynchronously rebuilt settings content needs a repaint. */
+	onRenderRequested?: () => void;
 	/** Called when an interactive setting cannot be committed. */
 	onError?: (message: string) => void;
 	/** Called when settings panel is closed */
@@ -1287,6 +1289,7 @@ export class SettingsSelectorComponent extends Container {
 		this.#pluginComponent = new PluginSettingsComponent(this.context.cwd, {
 			onClose: () => this.callbacks.onCancel(),
 			onPluginChanged: () => this.callbacks.onPluginsChanged?.(),
+			onRenderRequested: () => this.callbacks.onRenderRequested?.(),
 		});
 		this.addChild(this.#pluginComponent);
 	}
@@ -1296,6 +1299,7 @@ export class SettingsSelectorComponent extends Container {
 			{
 				onClose: () => this.callbacks.onCancel(),
 				onBundlesChanged: () => this.callbacks.onPluginsChanged?.(),
+				onRenderRequested: () => this.callbacks.onRenderRequested?.(),
 			},
 			{
 				runtimeSnapshotProvider: this.context.gjcRuntimeSnapshot,

package/src/modes/controllers/selector-controller.ts

@@ -1334,6 +1334,7 @@ export class SelectorController {
 						onPluginsChanged: () => {
 							this.ctx.ui.requestRender();
 						},
+						onRenderRequested: () => this.ctx.ui.requestRender(),
 						onCancel: () => {
 							done();
 							// Restore status line to saved settings

package/src/prompts/tools/bash.md

@@ -65,5 +65,5 @@ Use it only for sanctioned GJC workflow CLI persistence or state read/write/cont
 # Output minimizer
 
 - Bash stdout/stderr may be rewritten before you see it: long output keeps only the last 1 KiB by default to reduce noise and input-token use. Explicit `tools.artifactTailBytes` / `tools.artifactHeadBytes` settings can set the tail budget or retain both ends. Prefer focused commands and dedicated `search`/`find` tools over producing broad output. Test/lint runners (e.g. `bun test`, `cargo test`, ESLint) are also passed through heuristic filters that drop noise and keep failures.
-- When the local minimizer changes visible text, successful artifact storage appends a footer containing an `artifact://<id>` reference. Complete artifacts are labeled as full output; hard-capped artifacts report omitted bytes instead. If artifact allocation/storage is unavailable before a writer/save operation is attempted, truncation may have no reference or diagnostic. If an artifact writer/save operation is attempted and fails, a bounded diagnostic is emitted without inventing an artifact URI.
-- ACP/client-terminal output can arrive already truncated from the beginning. Treat any truncation notice or metadata as evidence that the visible tail is incomplete. Recover omitted output only when an `artifact://` footer or metadata reference is present; truncation evidence without a reference means the visible output is incomplete and no artifact is recoverable. Output with neither truncation evidence nor an artifact reference is the complete emitted output.
+- When the local minimizer changes visible text, successful artifact storage appends a footer containing an `artifact://<id>` reference. Artifact allocation is best-effort on direct, async, and monitor paths, and only decimal session artifact ids are accepted. Native callback delivery bounds both the core-to-native relay and N-API queue with backpressure and preserves a 64 KiB terminal tail after its core stream budget, emitting at most one typed aggregate loss marker. Complete artifacts are labeled as full output; hard-capped artifacts, streams that lost bytes before Bash capture, reader/client captures that cannot prove completeness, and loss counters beyond JavaScript's exact integer range report incompleteness instead. If artifact allocation/storage is unavailable before a writer/save operation is attempted, truncation may have no reference or diagnostic. If an artifact writer/save operation is attempted and fails, a bounded diagnostic is emitted without inventing an artifact URI.
+- ACP/client-terminal output can arrive already truncated from the beginning. Terminal creation, kill, output-recovery, and release RPCs are settlement-bounded; stalled or failed exit/kill/output operations report source-capture uncertainty instead of hanging or claiming completeness. Treat any truncation notice or metadata as evidence that the visible tail is incomplete. Recover omitted output only when an `artifact://` footer or metadata reference is present; truncation evidence without a reference means the visible output is incomplete and no artifact is recoverable. Output with neither truncation evidence nor an artifact reference is the complete emitted output.

package/src/prompts/tools/monitor.md

@@ -1,8 +1,8 @@
-Start a background monitor that streams events from a long-running script. Each stdout line is an event — you keep working and notifications arrive in the chat. Events arrive on their own schedule and are not replies from the user, even if one lands while you're waiting for the user to answer a question.
+Start a background monitor that streams events from a long-running script. Each stdout line is captured; persistent notifications are latest-biased and coalesced over a short debounce window, while terminal completion flushes the newest pending line. Events arrive on their own schedule and are not replies from the user, even if one lands while you're waiting for the user to answer a question.
 
 Pick by how many notifications you need:
 - **One** ("tell me when the server is ready / the build finishes") → use `bash` with `async: true`. That returns a single completion notification when the command exits.
-- **Many ongoing events** (logs, polling, file watching) → use `monitor`. The script keeps running and every new line of stdout becomes one event delivered into the conversation between turns.
+- **Many ongoing events** (logs, polling, file watching) → use `monitor`. The script keeps running and new stdout is captured; persistent notifications are coalesced so ordinary log traffic does not create one model turn per line.
 
 `monitor` uses the same permission rules as `bash`. To stop a monitor, cancel its background task via `job` with the returned `task_id`, or end the session.
 
@@ -15,7 +15,7 @@ Pick by how many notifications you need:
 
 ## Inputs
 
-- `command` (required): shell command to run as a background monitor. Each stdout line is delivered as a separate task-notification event.
+- `command` (required): shell command to run as a background monitor. Stdout is captured line-by-line; persistent notifications are coalesced before delivery.
 - `kind` (required): one of `"log"`, `"poll"`, `"watch"`, `"other"`. Describes the monitoring strategy so listings can surface useful categories.
 - `description` (required): short human-readable description of what is being monitored. Appears in task listings.
 - `timeout` (optional): maximum wall-clock seconds the monitor may run before automatic shutdown. Omit for the session lifetime.
@@ -23,7 +23,7 @@ Pick by how many notifications you need:
 
 ## Output
 
-Returns `Monitor started · task <task_id>` plus a task entry visible via `job({list: true})`. Each stdout line of the monitored command becomes a `<task-notification>` event delivered between turns.
+Returns `Monitor started · task <task_id>` plus a task entry visible via `job({list: true})`. Persistent notifications contain the latest line and the count of earlier coalesced lines; terminal completion flushes the newest pending line.
 
 ## Cancellation