@namzu/sdk 39.0.0 → 41.0.0

package/src/runtime/query/plugin-hooks.ts

@@ -59,3 +59,23 @@ export function applyLifecycleHookResults(
 	}
 	return annotations
 }
+
+/**
+ * What a `pre_tool_use` hook's SKIP goes back to the model as.
+ *
+ * A function rather than a template at the one call site, because the text is
+ * a SIGNAL as well as prose. A skipped call gets a non-error receipt — the
+ * hook refused it, nothing failed — so the transcript's only record that the
+ * tool never ran is this sentence. `file-evidence-replay.ts` reads it back to
+ * keep a skipped `write` from being replayed as a body the file now holds,
+ * and it can only do that while one function owns both the writing and the
+ * recognising.
+ */
+export function skippedToolResultText(toolName: string, reason: string): string {
+	return `Tool ${toolName} skipped by plugin: ${reason}`
+}
+
+/** Whether `content` is the receipt {@link skippedToolResultText} writes for `toolName`. */
+export function isSkippedToolResult(toolName: string, content: string): boolean {
+	return content.startsWith(skippedToolResultText(toolName, ''))
+}

package/src/runtime/query/repeat-call.ts

@@ -1,3 +1,4 @@
+import { createRuntimeContextMessage } from '../../types/message/index.js'
 import type { Message } from '../../types/message/index.js'
 import { stableStringify } from './tool-grants.js'
 
@@ -128,11 +129,24 @@ export class RepeatCallTracker {
 }
 
 /**
- * Rides the notice out on the last `tool_result` of the batch.
+ * Rides the notice out on the last `tool_result` of the batch, same slot
+ * steering uses: a `tool_use` block must be answered by a `tool_result` with
+ * the same id, so a user message wedged between them is rejected by the
+ * provider outright.
  *
- * The same and only legal slot steering uses: a `tool_use` block must be
- * answered by a `tool_result` with the same id, so a user message wedged
- * between them is rejected by the provider outright.
+ * That slot only exists when the trailing result's content is plain text. A
+ * result answered with structured content (an image, a document, an MCP
+ * block) has a shape the model reads positionally, and appending a string to
+ * it is either dropped or corrupts the block — this used to mean the notice
+ * was simply dropped, on the theory that an advisory costs nothing to lose.
+ * It costs more than a refusal would: `RepeatCallTracker.record` already
+ * marked the threshold as announced the moment it fired, so a notice lost
+ * here never comes back, unlike steering, which can requeue and wait for a
+ * later plain-text result. The fallback instead rides out as its own
+ * `runtime-context` message placed AFTER the complete tool-result batch —
+ * never between a `tool_use` and its `tool_result`, so provider-required
+ * adjacency still holds — carrying that provenance so it is never mistaken
+ * for operator input (see `isOperatorUserMessage` in `steering.ts`).
  */
 export function attachRepeatNotice(
 	messages: readonly Message[],
@@ -140,6 +154,8 @@ export function attachRepeatNotice(
 ): readonly Message[] {
 	if (notices.length === 0) return messages
 
+	const noticeText = notices.map((n) => n.text).join('\n')
+
 	let lastToolIndex = -1
 	for (let index = messages.length - 1; index >= 0; index--) {
 		if (messages[index]?.role === 'tool') {
@@ -147,19 +163,13 @@ export function attachRepeatNotice(
 			break
 		}
 	}
-	if (lastToolIndex === -1) return messages
-
-	const target = messages[lastToolIndex] as Message
-	// Text only, for the reason `attachSteering` gives: a result answered
-	// with structured content has a shape the model reads positionally, and
-	// appending a string to it is either dropped or corrupts the block. The
-	// notice is advisory, so dropping it costs nothing a refusal would.
-	if (typeof target.content !== 'string') return messages
-
-	const next = [...messages]
-	next[lastToolIndex] = {
-		...target,
-		content: `${target.content}\n\n${notices.map((n) => n.text).join('\n')}`,
+	const target = lastToolIndex === -1 ? undefined : (messages[lastToolIndex] as Message)
+
+	if (target && typeof target.content === 'string') {
+		const next = [...messages]
+		next[lastToolIndex] = { ...target, content: `${target.content}\n\n${noticeText}` }
+		return next
 	}
-	return next
+
+	return [...messages, createRuntimeContextMessage(noticeText, 'repeat-call')]
 }

package/src/runtime/query/steering.ts

@@ -100,6 +100,16 @@ export function attachNotice(
 	messages: readonly Message[],
 	channel: SteeringChannel | undefined,
 	format: (text: string) => string,
+	/**
+	 * Told only when the text actually landed on a result the model will read.
+	 *
+	 * Not on the two paths above it: a batch with no tool result leaves the
+	 * notice queued, and a result whose content is not a string puts it back.
+	 * Draining is therefore not delivery, which matters to the caller that
+	 * keeps its own record of what the text accounts for — `AwaitedJobs`
+	 * drops an exit's entry here, and a premature drop would strand the exit.
+	 */
+	onDelivered?: () => void,
 ): readonly Message[] {
 	if (!channel?.pending) return messages
 	let lastToolIndex = -1
@@ -119,6 +129,7 @@ export function attachNotice(
 	}
 	const next = [...messages]
 	next[lastToolIndex] = { ...target, content: target.content + format(text) }
+	onDelivered?.()
 	return next
 }
 

package/src/runtime/query/tooling.ts

@@ -38,6 +38,8 @@ export interface ToolingBootstrapConfig {
 	backgroundJobs?: BackgroundJobRegistry
 	/** See `QueryParams.backgroundJobOwner`. */
 	backgroundJobOwner?: string
+	/** Where `wait_for_job` records wait-intent; see the executor's own field. */
+	onJobAwaited?: (id: string) => void
 	/** Where the `skill` tool reads from. */
 	skills?: SkillRegistryRef
 	/** How this run reaches the web. */
@@ -85,6 +87,7 @@ export class ToolingBootstrap {
 				pluginManager: config.pluginManager,
 				...(config.backgroundJobs ? { backgroundJobs: config.backgroundJobs } : {}),
 				...(config.backgroundJobOwner ? { backgroundJobOwner: config.backgroundJobOwner } : {}),
+				...(config.onJobAwaited ? { onJobAwaited: config.onJobAwaited } : {}),
 				...(config.skills ? { skills: config.skills } : {}),
 				...(config.web ? { web: config.web } : {}),
 				...(config.toolTimeoutMs !== undefined ? { toolTimeoutMs: config.toolTimeoutMs } : {}),

package/src/sandbox/provider/local.ts

@@ -4,6 +4,7 @@ import {
 	readFile as fsReadFile,
 	writeFile as fsWriteFile,
 	mkdir,
+	open,
 	readdir,
 	rename,
 	rm,
@@ -38,6 +39,7 @@ import type {
 	SandboxFileEntry,
 	SandboxIsolationControl,
 	SandboxProvider,
+	SandboxReadFileOptions,
 	SandboxSpawnOptions,
 	SandboxStatus,
 	SandboxWalkFilesOptions,
@@ -742,13 +744,54 @@ class LocalSandbox implements Sandbox {
 		this.log.debug('File written', { 'namzu.sandbox.path': resolved })
 	}
 
-	async readFile(path: string): Promise<Buffer> {
+	/**
+	 * `options.offset`/`options.length` are HONOURED, not ignored.
+	 *
+	 * {@link Sandbox.readFile} is explicit that a backend which takes the
+	 * parameter and answers with the whole file has given a WRONG answer
+	 * rather than a degraded one, and must reject instead. On a local
+	 * filesystem there is nothing to reject: a slice is one positional read,
+	 * so this serves it.
+	 *
+	 * A range that runs past the end returns the bytes that exist, because a
+	 * caller resuming from a remembered offset cannot know the answer before
+	 * it asks.
+	 *
+	 * `options.signal` cannot be handed to a positional read — `FileHandle`
+	 * takes none — so it is checked on both sides of one bounded slice
+	 * instead. That honours the contract's "aborts the read" as far as a
+	 * local disk allows: an abort is never answered with data.
+	 */
+	async readFile(path: string, options?: SandboxReadFileOptions): Promise<Buffer> {
 		if (this._status === 'destroyed') {
 			throw new Error(`Sandbox ${this.id} is destroyed`)
 		}
 
 		const resolved = await resolveWithinAnyReal(this.roots, path)
-		return fsReadFile(resolved)
+		const { offset, length, signal } = options ?? {}
+		signal?.throwIfAborted()
+		if (offset === undefined && length === undefined) {
+			return await fsReadFile(resolved, signal ? { signal } : undefined)
+		}
+		if (offset !== undefined && (!Number.isSafeInteger(offset) || offset < 0)) {
+			throw new Error('readFile: offset must be a non-negative safe integer')
+		}
+		if (length !== undefined && (!Number.isSafeInteger(length) || length < 0)) {
+			throw new Error('readFile: length must be a non-negative safe integer')
+		}
+		const handle = await open(resolved, 'r')
+		try {
+			const from = offset ?? 0
+			const remaining = Math.max(0, (await handle.stat()).size - from)
+			const want = Math.min(length ?? remaining, remaining)
+			if (want === 0) return Buffer.alloc(0)
+			const buf = Buffer.allocUnsafe(want)
+			const { bytesRead } = await handle.read(buf, 0, want, from)
+			signal?.throwIfAborted()
+			return buf.subarray(0, bytesRead)
+		} finally {
+			await handle.close().catch(() => undefined)
+		}
 	}
 
 	async listFiles(rootPath: string): Promise<readonly SandboxFileEntry[]> {

package/src/scheduler/completion-inbox.ts

@@ -26,6 +26,23 @@ import { type Logger, resolveLogger } from '../utils/logger.js'
  */
 const UNOWNED_BUFFER_LIMIT = 32
 
+/**
+ * How many owned tasks {@link CompletionInbox.describeOwnedWork} can name at
+ * once.
+ *
+ * Unrelated to {@link UNOWNED_BUFFER_LIMIT} — that one bounds a memory leak;
+ * this one bounds a request payload. `describeOwnedWork`'s output is admitted
+ * into the request through `appendWorkContext`'s 8,000-character / ~2,000-token
+ * gate (`runtime/query/iteration/index.ts`), and 16 tasks' worth of scheduler
+ * state fits that with room to spare, including the overflow note below.
+ *
+ * Running tasks fill these slots first — see {@link CompletionInbox.runningOwned}
+ * — so a task still going is never bumped out by launch count alone the way a
+ * single FIFO over every owned task used to bump it. Only once every running
+ * task has a slot do the most recently SETTLED tasks take what is left.
+ */
+const OWNED_WORK_DISPLAY_LIMIT = 16
+
 /**
  * Completions that finished with nobody left to hear them.
  *
@@ -77,7 +94,30 @@ export class CompletionInbox {
 	 * takes one, and a host that owns a gateway naturally reuses it.
 	 */
 	private readonly ours = new Set<TaskId>()
-	private readonly recentOwned: TaskId[] = []
+	/**
+	 * Owned tasks not yet observed to have settled, in launch order.
+	 *
+	 * A `Set`'s iteration order is insertion order, so the most recently
+	 * launched entry is always last — {@link describeOwnedWork} reads that
+	 * order back to front. An id leaves this set the moment its completion is
+	 * observed, by whichever of the three paths sees it first: the gateway's
+	 * broadcast, an announcement recovered from {@link unowned}, or a launch
+	 * that finds the task already terminal. It is never evicted for any other
+	 * reason, so a long-running task stays in here — and therefore visible —
+	 * for exactly as long as it is actually running, regardless of how many
+	 * other tasks this run launches meanwhile.
+	 */
+	private readonly runningOwned = new Set<TaskId>()
+	/**
+	 * Owned tasks observed to have settled, oldest first, bounded to
+	 * {@link OWNED_WORK_DISPLAY_LIMIT}.
+	 *
+	 * This bound is display-driven, not a memory concern the way
+	 * {@link UNOWNED_BUFFER_LIMIT} is: a settled task's own result already
+	 * reached the model once (inline or as a notification), so dropping it
+	 * from here loses a convenience, not the only record of it.
+	 */
+	private readonly settledOwned: TaskId[] = []
 	/**
 	 * Announcements that arrived before anyone said whose task it was.
 	 *
@@ -130,6 +170,7 @@ export class CompletionInbox {
 			// finished its wait faster than the listener ran — is already
 			// delivered. Nothing to queue.
 			this.outstanding.delete(handle.taskId)
+			this.markSettled(handle.taskId)
 			if (this.claimed.has(handle.taskId)) return
 			this.unheard.set(handle.taskId, handle)
 			for (const wake of this.arrivals) wake()
@@ -193,25 +234,49 @@ export class CompletionInbox {
 	launched(taskId: TaskId): void {
 		if (this.ours.has(taskId)) return
 		this.ours.add(taskId)
-		this.recentOwned.push(taskId)
-		if (this.recentOwned.length > 16) this.recentOwned.shift()
 
-		if (this.claimed.has(taskId) || this.unheard.has(taskId)) return
+		if (this.claimed.has(taskId) || this.unheard.has(taskId)) {
+			this.markSettled(taskId)
+			return
+		}
 
 		const parked = this.unowned.get(taskId)
 		if (parked) {
 			this.unowned.delete(taskId)
 			this.unheard.set(taskId, parked)
+			this.markSettled(taskId)
 			for (const wake of [...this.arrivals]) wake()
 			return
 		}
 
 		const settled = this.gateway?.getTask(taskId)
-		if (!settled || !isTerminalAgentTaskState(settled.state)) return
+		if (!settled || !isTerminalAgentTaskState(settled.state)) {
+			// Not observed terminal by any of the checks above: still running,
+			// as far as this inbox knows.
+			this.runningOwned.add(taskId)
+			return
+		}
 		this.unheard.set(taskId, settled)
+		this.markSettled(taskId)
 		for (const wake of [...this.arrivals]) wake()
 	}
 
+	/**
+	 * Move an owned task from {@link runningOwned} to {@link settledOwned}.
+	 *
+	 * Idempotent: `claim` and the completion listener can both observe the
+	 * same settlement (the race either can win), and re-marking a task that
+	 * is already in {@link settledOwned} moves it to the most-recently-settled
+	 * end rather than duplicating it there.
+	 */
+	private markSettled(taskId: TaskId): void {
+		this.runningOwned.delete(taskId)
+		const at = this.settledOwned.indexOf(taskId)
+		if (at !== -1) this.settledOwned.splice(at, 1)
+		this.settledOwned.push(taskId)
+		if (this.settledOwned.length > OWNED_WORK_DISPLAY_LIMIT) this.settledOwned.shift()
+	}
+
 	/**
 	 * Say that a task was launched with nothing waiting on it.
 	 *
@@ -274,6 +339,13 @@ export class CompletionInbox {
 		this.claimed.add(taskId)
 		this.unheard.delete(taskId)
 		this.outstanding.delete(taskId)
+		// A tool only claims a result it is already holding, so a claim is
+		// itself proof of settlement — independent of whether the gateway's
+		// own broadcast has reached this inbox yet. Without this, a task
+		// claimed ahead of its announcement (see the race above) stayed in
+		// {@link runningOwned} until that announcement arrived, understating
+		// its own "still running" count in the meantime.
+		this.markSettled(taskId)
 	}
 
 	/** Whether anything is waiting to be told. */
@@ -281,10 +353,29 @@ export class CompletionInbox {
 		return this.unheard.size > 0
 	}
 
-	/** Bounded, non-consuming scheduler observations. Delivery never establishes user-facing completion. */
+	/**
+	 * Bounded, non-consuming scheduler observations. Delivery never
+	 * establishes user-facing completion.
+	 *
+	 * Running tasks — most recently launched first, matching the order the
+	 * rest of this projection has always used — fill the {@link
+	 * OWNED_WORK_DISPLAY_LIMIT} slots first, so a task still going is named
+	 * here for as long as it keeps running, no matter how many other tasks
+	 * this run has since launched. The most recently SETTLED tasks fill
+	 * whatever slots running tasks leave over. A settled task bumped out
+	 * entirely is not reported missing — its own result already reached the
+	 * model once — but a RUNNING task that does not fit is: the preamble
+	 * says exactly how many, so the model never mistakes the cap for the
+	 * task having ended.
+	 */
 	describeOwnedWork(): string | undefined {
 		if (this.ours.size === 0) return
-		const ids = this.recentOwned
+		const running = [...this.runningOwned].reverse()
+		const shownRunning = running.slice(0, OWNED_WORK_DISPLAY_LIMIT)
+		const stillRunningNotShown = running.length - shownRunning.length
+		const settled = [...this.settledOwned].reverse()
+		const shownSettled = settled.slice(0, OWNED_WORK_DISPLAY_LIMIT - shownRunning.length)
+		const ids = [...shownRunning, ...shownSettled]
 		const tasks = ids.map((taskId) => {
 			let handle = this.unheard.get(taskId)
 			try {
@@ -300,7 +391,11 @@ export class CompletionInbox {
 				resultDelivery: this.claimed.has(taskId) ? 'delivered-to-history' : 'not-delivered',
 			}
 		})
-		return `Owned delegated work (current scheduler observations). Result delivery is not proof that you answered the original request. Answer the latest operator message and complete the requested synthesis of available results unless the operator cancelled or changed that request. Reuse delivered results when sufficient; do not relaunch completed work. If a delivered result is no longer visible, retrieve it by task ID. A terminal state with a non-end_turn stop reason is not successful task completion. Do not repeat a synthesis already given.\n${JSON.stringify({ tasks, omitted: this.ours.size - ids.length })}`
+		const overflow =
+			stillRunningNotShown > 0
+				? ` ${shownRunning.length} running tasks are shown below, and ${stillRunningNotShown} more still running.`
+				: ''
+		return `Owned delegated work (current scheduler observations).${overflow} Result delivery is not proof that you answered the original request. Answer the latest operator message and complete the requested synthesis of available results unless the operator cancelled or changed that request. Reuse delivered results when sufficient; do not relaunch completed work. If a delivered result is no longer visible, retrieve it by task ID. A terminal state with a non-end_turn stop reason is not successful task completion. Do not repeat a synthesis already given.\n${JSON.stringify({ tasks, omitted: this.ours.size - ids.length })}`
 	}
 
 	/**
@@ -391,7 +486,8 @@ export class CompletionInbox {
 		this.unheard.clear()
 		this.outstanding.clear()
 		this.ours.clear()
-		this.recentOwned.length = 0
+		this.runningOwned.clear()
+		this.settledOwned.length = 0
 		this.claimed.clear()
 		this.unowned.clear()
 		// Release anyone still waiting. A closed inbox would otherwise hold

package/src/scheduler/local.ts

@@ -114,6 +114,14 @@ export class LocalTaskScheduler implements TaskScheduler {
 				beforeStart: options.beforeStart,
 				...(options.planId ? { planId: options.planId } : {}),
 				...(options.planStepId ? { planStepId: options.planStepId } : {}),
+				// Display grouping travels with the spawn so the manager can put it
+				// on `agent_pending`. Spread conditionally, like the plan edge
+				// above: a host that groups nothing must not be made to look like
+				// one that grouped everything under an empty label.
+				...(options.workflow ? { workflow: options.workflow } : {}),
+				...(options.phase ? { phase: options.phase } : {}),
+				...(options.phaseDetail ? { phaseDetail: options.phaseDetail } : {}),
+				...(options.phaseOrder !== undefined ? { phaseOrder: options.phaseOrder } : {}),
 				input: {
 					messages: [createUserMessage(options.prompt)],
 					workingDirectory: options.workingDirectory,

package/src/store/run/disk.ts

@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto'
 import { appendFile, mkdir, readFile, readdir, stat, unlink } from 'node:fs/promises'
 import { join } from 'node:path'
+import type { RunExecutionStatus } from '../../types/common/index.js'
 import type { CheckpointId, IterationCheckpoint } from '../../types/hitl/index.js'
 import type { Message } from '../../types/message/index.js'
 import type {
@@ -12,6 +13,7 @@ import type {
 } from '../../types/run/index.js'
 import type {
 	CompletedToolRecord,
+	DelegatedChildRun,
 	ReadRunEventsOptions,
 	RunMessageSnapshot,
 	RunStore,
@@ -432,6 +434,86 @@ export class RunDiskStore implements RunStore {
 		}
 	}
 
+	/**
+	 * Every delegated child run saved under one parent, oldest first.
+	 *
+	 * The sibling of {@link RunDiskStore.listRuns}, and deliberately not a fix
+	 * to it. `addToIndex` returns early for any run with a `parentRunId`, which
+	 * is what keeps delegated children out of `index.json` and therefore out of
+	 * a host's conversation listing — a child is not a conversation anyone
+	 * resumes, and putting one there would offer to continue work whose parent
+	 * turn is long over. That guard stays. This walks the `children/` directory
+	 * instead, so the evidence a child already wrote is reachable by something
+	 * that came looking for it, without any of it becoming resumable.
+	 *
+	 * READ-ONLY, and that matters more here than for most reads: binding a
+	 * {@link RunDiskStore} to a run CREATES its directory, so discovery had to
+	 * be a free walk or it would mint the very directories it claims to find.
+	 * Nothing here writes, moves or prunes.
+	 *
+	 * Tolerant of half-written evidence, the same way the transcript reader
+	 * next door is. A child directory with no `run.json` — a run killed before
+	 * its terminal write — is SKIPPED rather than reported with invented
+	 * fields, and so is one whose `run.json` is not readable JSON. What is
+	 * skipped is the listing row, not the directory: a caller that knows the
+	 * run id can still read the transcript beside it.
+	 *
+	 * Oldest first, by `startedAt`, so the order matches the order the parent
+	 * launched them. A child whose `run.json` never recorded a start sorts
+	 * first; there is no later moment to claim for it.
+	 *
+	 * `baseDir` is the runs directory the parent was written under — the same
+	 * {@link RunStoreConfig.baseDir} the child's store had, which is why one
+	 * parent's children can be spread across several of them when a host gives
+	 * each child its own session directory.
+	 */
+	static async listChildren(
+		baseDir: string,
+		parentRunId: string,
+	): Promise<readonly DelegatedChildRun[]> {
+		asRunId(parentRunId)
+		const childrenDir = join(baseDir, parentRunId, 'children')
+		let names: string[]
+		try {
+			names = await readdir(childrenDir)
+		} catch (err) {
+			if (isFileNotFound(err) || isNotADirectory(err)) return []
+			throw err
+		}
+
+		const children: DelegatedChildRun[] = []
+		for (const name of names) {
+			const dir = join(childrenDir, name)
+			let meta: unknown
+			try {
+				meta = JSON.parse(await readFile(join(dir, 'run.json'), 'utf-8'))
+			} catch (err) {
+				// ENOTDIR covers a stray file sitting beside the child directories.
+				if (isFileNotFound(err) || isNotADirectory(err) || err instanceof SyntaxError) continue
+				throw err
+			}
+			if (meta === null || typeof meta !== 'object') continue
+			const record = meta as Record<string, unknown>
+			const metadata = asRecord(record.metadata)
+			const config = asRecord(metadata?.config)
+			const usage = asRecord(record.tokenUsage)
+			children.push({
+				id: name,
+				parentRunId,
+				dir,
+				...(typeof metadata?.agentId === 'string' ? { agentId: metadata.agentId } : {}),
+				...(typeof metadata?.agentName === 'string' ? { agentName: metadata.agentName } : {}),
+				...(typeof config?.model === 'string' ? { model: config.model } : {}),
+				...(isRunExecutionStatus(record.status) ? { status: record.status } : {}),
+				...(typeof record.startedAt === 'number' ? { startedAt: record.startedAt } : {}),
+				...(typeof record.endedAt === 'number' ? { endedAt: record.endedAt } : {}),
+				...(typeof usage?.totalTokens === 'number' ? { totalTokens: usage.totalTokens } : {}),
+				...(typeof record.depth === 'number' ? { depth: record.depth } : {}),
+			})
+		}
+		return children.sort((left, right) => (left.startedAt ?? 0) - (right.startedAt ?? 0))
+	}
+
 	async addToIndex(run: Run): Promise<void> {
 		if (run.parentRunId) return
 
@@ -798,6 +880,32 @@ function parseCheckpoint(content: string, file: string): IterationCheckpoint {
 	return record as IterationCheckpoint
 }
 
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+	return typeof value === 'object' && value !== null
+		? (value as Record<string, unknown>)
+		: undefined
+}
+
+const RUN_EXECUTION_STATUSES: readonly RunExecutionStatus[] = [
+	'idle',
+	'pending',
+	'running',
+	'completed',
+	'failed',
+	'cancelled',
+]
+
+function isRunExecutionStatus(value: unknown): value is RunExecutionStatus {
+	return typeof value === 'string' && RUN_EXECUTION_STATUSES.includes(value as RunExecutionStatus)
+}
+
+/** A path component that is a file where a directory was expected. */
+function isNotADirectory(err: unknown): boolean {
+	return (
+		typeof err === 'object' && err !== null && (err as NodeJS.ErrnoException).code === 'ENOTDIR'
+	)
+}
+
 function isFileNotFound(err: unknown): boolean {
 	return typeof err === 'object' && err !== null && (err as NodeJS.ErrnoException).code === 'ENOENT'
 }

package/src/tools/builtins/bash.ts

@@ -5,6 +5,7 @@ import { SANDBOX_KILL_GRACE_MS } from '../../constants/sandbox/index.js'
 import { DANGEROUS_PATTERNS } from '../../constants/tools/index.js'
 import { killTree } from '../../process/kill-tree.js'
 import { subscribeToAbort } from '../../utils/abort.js'
+import { readPositiveIntEnv } from '../../utils/env.js'
 import { defineTool } from '../defineTool.js'
 import { scrubInheritedEnv } from '../env-scrub.js'
 
@@ -57,13 +58,13 @@ const inputSchema = z.object({
 			z.number().positive().max(MAX_BASH_TIMEOUT_MS).default(DEFAULT_BASH_TIMEOUT_MS),
 		)
 		.describe(
-			`Command timeout in milliseconds. Default: ${DEFAULT_BASH_TIMEOUT_MS}, maximum: ${MAX_BASH_TIMEOUT_MS}. For work that legitimately runs longer than the maximum, set run_in_background and poll with the \`job\` tool, rather than holding the turn open.`,
+			`Command timeout in milliseconds. Default: ${DEFAULT_BASH_TIMEOUT_MS}, maximum: ${MAX_BASH_TIMEOUT_MS}. For work that legitimately runs longer than the maximum, set run_in_background and await it with \`wait_for_job\`, rather than holding the turn open.`,
 		),
 	run_in_background: z
 		.boolean()
 		.optional()
 		.describe(
-			'Start the command as a background job and return its id immediately, instead of waiting. The turn is not held open; read its output with the `job` tool. Use for watchers, dev servers and long builds. Do NOT write `cmd &` yourself — under the sandbox the shell that backgrounds it exits immediately and takes the job with it.',
+			'Start the command as a background job and return its id immediately, instead of waiting. The turn is not held open; await its completion with `wait_for_job` — one call, no waiting turns. Use `job` with action "read" only for incremental output while it keeps running, or to pick up after a `wait_for_job` call times out. Use for watchers, dev servers and long builds. Do NOT write `cmd &` yourself — under the sandbox the shell that backgrounds it exits immediately and takes the job with it.',
 		),
 })
 
@@ -343,7 +344,7 @@ export const BashTool = defineTool({
 				})
 				return {
 					success: true,
-					output: `Started background job ${job.id}. Read its output with the \`job\` tool: {"action":"read","id":"${job.id}"}.`,
+					output: `Started background job ${job.id}. Await its completion with wait_for_job: {"id":"${job.id}"}. Use job with action "read" only for output while it keeps running.`,
 					data: { jobId: job.id, background: true },
 				}
 			} catch (err) {
@@ -539,10 +540,3 @@ function describeWithheldEnv(dropped: readonly string[]): string {
 	const names = rest > 0 ? `${shown}, and ${rest} more` : shown
 	return `NOTE: ${dropped.length} credential-shaped environment variable(s) were withheld from this command and are unset rather than empty: ${names}. A host that means this command to have one passes it explicitly.`
 }
-
-function readPositiveIntEnv(key: string, fallback: number): number {
-	const value = process.env[key]?.trim()
-	if (!value) return fallback
-	const parsed = Number(value)
-	return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : fallback
-}