@namzu/sdk 50.1.0 → 51.1.0

package/src/provider/token-budget.ts

@@ -1,8 +1,10 @@
+import { estimateMessagesTokens } from '../compaction/token-estimate.js'
 import { EMPTY_TOKEN_USAGE } from '../constants/limits.js'
 import type { SessionTokenBudget } from '../store/budget/ledger.js'
 import { type TokenUsage, mergeTokenUsage } from '../types/common/index.js'
 import { ProviderError, classifyProviderError } from '../types/provider/errors.js'
 import type { LLMProvider, StreamChunk } from '../types/provider/index.js'
+import { cancelCauseOf } from '../types/session/cancel-cause.js'
 import { isProviderRequestError } from './errors.js'
 
 export class TokenBudgetAdmissionError extends ProviderError {
@@ -49,6 +51,7 @@ export function withTokenBudget(provider: LLMProvider, budget: SessionTokenBudge
 		let completed = false
 		let outputObserved = false
 		let uncertainRetry = false
+		let streamedChars = 0
 		let contacted = false
 		let abandoned = false
 		let iterator: AsyncIterator<StreamChunk> | undefined
@@ -107,6 +110,7 @@ export function withTokenBudget(provider: LLMProvider, budget: SessionTokenBudge
 					})
 				}
 				if (Object.keys(chunk.delta).length > 0) outputObserved = true
+				if (typeof chunk.delta.content === 'string') streamedChars += chunk.delta.content.length
 				if (chunk.error) throw new Error(chunk.error)
 				yield chunk
 			}
@@ -142,7 +146,33 @@ export function withTokenBudget(provider: LLMProvider, budget: SessionTokenBudge
 			} catch {
 				// Cleanup cannot replace the provider outcome.
 			}
-			if (!completed) await budget.failRequest(requestId, usage)
+			if (!completed) {
+				// A request the operator deliberately cancelled (a `user` cancel cause,
+				// not a parent or a runtime tearing the tree down) before any usage frame
+				// arrived is closed on an estimate (the prompt and what streamed), not
+				// left as unknown spend. Left open it poisons the whole tree: every
+				// sibling and every later child is refused for the rest of the turn,
+				// because of work somebody chose to stop. The estimate can under-count
+				// what the provider billed for the part it never reported; a failure
+				// that was not a cancellation keeps its marker as before.
+				if (
+					usage === undefined &&
+					signal?.aborted === true &&
+					cancelCauseOf(signal.reason) === 'user' &&
+					!uncertainRetry
+				) {
+					const prompt = estimateMessagesTokens(params.messages)
+					const completion = Math.ceil(streamedChars / 4)
+					await budget.finishRequest(requestId, {
+						...EMPTY_TOKEN_USAGE,
+						promptTokens: prompt,
+						completionTokens: completion,
+						totalTokens: prompt + completion,
+					})
+				} else {
+					await budget.failRequest(requestId, usage)
+				}
+			}
 		}
 	}
 

package/src/public-runtime.ts

@@ -20,6 +20,17 @@ export { BackgroundJobOutputWaitLimitError } from './runtime/jobs/registry.js'
 export { HostCallDeniedError } from './execution/code-runtime/types.js'
 export { WorkerCodeRuntime } from './execution/code-runtime/worker.js'
 
+// The workflow runtime: runs a model-authored orchestration script on the
+// interpreter above, with `agent()` as its only host call.
+export {
+	FileWorkflowJournal,
+	parseWorkflowMeta,
+	resolveWorkflowLimits,
+	summarizeWorkflowPhases,
+	WorkflowRuntime,
+	WorkflowScriptError,
+} from './execution/workflow/index.js'
+
 export {
 	CompactionConfigSchema,
 	PluginRuntimeConfigSchema,

package/src/public-tools.ts

@@ -54,9 +54,15 @@ export { builtinCommandArguments, commandArgumentOf } from './tools/command-argu
 export {
 	type CommandShell,
 	type CommandShellProbe,
+	WINDOWS_BASH_GUIDANCE,
+	WINDOWS_CMD_FALLBACK_NOTICE,
 	findCommandShell,
 	findCommandShellForDialect,
+	findGitBash,
 	hostCommandShell,
+	isWindowsBash,
+	rewriteWindowsNullRedirect,
+	windowsShellNotice,
 	describeSpawnFailure,
 	hostShellSpawn,
 	installedCommandShellForDialect,

package/src/public-types.ts

@@ -32,6 +32,9 @@ export type { CoalesceOptions } from './streaming/coalesce.js'
 export type * from './types/bidi/index.js'
 export type * from './types/tool/index.js'
 export type * from './types/job/index.js'
+export type * from './execution/workflow/types.js'
+export type { PhaseAgentView, PhaseRecord } from './execution/workflow/phases.js'
+export type { WorkflowRuntimeOptions } from './execution/workflow/runtime.js'
 export type { WorkerCodeRuntimeOptions } from './execution/code-runtime/worker.js'
 export type {
 	CodeRunOutcome,

package/src/runtime/jobs/job-id.ts

@@ -0,0 +1,66 @@
+import { randomBytes } from 'node:crypto'
+
+/**
+ * Background job ids: `b` and eight characters of `0-9a-z`.
+ *
+ * Random rather than counted. A counter restarts with every registry, so a
+ * resumed conversation that still says `job_1` about a dead job would be
+ * answered by whatever job happens to be `job_1` in the new session. A random
+ * id from a space of 36^8 does not collide across sessions in practice, and
+ * the registry additionally never hands out one it already holds.
+ *
+ * Ids are opaque to callers: nothing may parse them or rely on the shape.
+ */
+const ALPHABET = '0123456789abcdefghijklmnopqrstuvwxyz'
+const ID_BODY_LENGTH = 8
+const ID_PATTERN = /^b[0-9a-z]{8}$/
+
+/**
+ * Whether `id` looks like one this SDK minted (`b` + 8 base36 characters).
+ * A helper only: the tools do not gate on it, because a host's own registry
+ * may use other ids. Ids are opaque; a host must not parse them.
+ */
+export function isBackgroundJobId(id: unknown): id is string {
+	return typeof id === 'string' && ID_PATTERN.test(id)
+}
+
+/**
+ * A fresh id. Bytes are mapped onto the alphabet by rejection so every
+ * character is uniform (256 is not a multiple of 36).
+ */
+export function createBackgroundJobId(isTaken: (id: string) => boolean = () => false): string {
+	for (;;) {
+		let body = ''
+		while (body.length < ID_BODY_LENGTH) {
+			for (const byte of randomBytes(ID_BODY_LENGTH * 2)) {
+				if (byte >= 252) continue // 252 = 36 * 7
+				body += ALPHABET[byte % 36]
+				if (body.length === ID_BODY_LENGTH) break
+			}
+		}
+		const id = `b${body}`
+		if (!isTaken(id)) return id
+	}
+}
+
+const MAX_JOB_ID_INPUT_LENGTH = 128
+
+/**
+ * The tools' only gate on an id a caller passes in. A host may supply its own
+ * registry with its own id format, so shape is NOT checked here: anything that
+ * is a sane single token goes on to the registry, whose "No background job
+ * <id>." answers for an unknown one. Returns a plain refusal for input that
+ * cannot be an id at all (not a string, empty, over 128 characters, or
+ * containing whitespace or control characters), otherwise undefined.
+ */
+export function invalidBackgroundJobIdInput(id: unknown): string | undefined {
+	if (typeof id !== 'string' || id.length === 0) return 'A background job id is required.'
+	if (id.length > MAX_JOB_ID_INPUT_LENGTH) {
+		return `That is not a background job id: it is longer than ${MAX_JOB_ID_INPUT_LENGTH} characters.`
+	}
+	// biome-ignore lint/suspicious/noControlCharactersInRegex: rejecting control characters is the point.
+	if (/[\s\u0000-\u001f\u007f-\u009f]/u.test(id)) {
+		return 'That is not a background job id: ids contain no spaces or control characters.'
+	}
+	return undefined
+}

package/src/runtime/jobs/registry.ts

@@ -10,6 +10,7 @@ import type {
 	BackgroundJobOutputWaitResult,
 } from '../../types/job/index.js'
 import { subscribeToAbort } from '../../utils/abort.js'
+import { createBackgroundJobId } from './job-id.js'
 
 /**
  * Work that outlives a tool call, owned by whoever started it.
@@ -213,7 +214,6 @@ const GROUP_POLL_MS = 250
 
 export class BackgroundJobRegistry {
 	private readonly jobs = new Map<string, JobEntry>()
-	private counter = 0
 	private readonly exitListeners = new Set<(job: BackgroundJob) => void>()
 	private outputWaiters = 0
 	private readonly outputWaitersByOwner = new Map<string, number>()
@@ -303,8 +303,7 @@ export class BackgroundJobRegistry {
 			throw new BackgroundJobLimitError({ owner: params.owner, limit: this.maxJobs })
 		}
 
-		this.counter += 1
-		const id = `job_${this.counter}`
+		const id = createBackgroundJobId((candidate) => this.jobs.has(candidate))
 		// Same scrub as the foreground path: inheritance is implicit, so the
 		// operator's provider credentials do not travel into a command nobody
 		// decided should see them. A background job outlives the call that

package/src/runtime/query/iteration/stream-turn.ts

@@ -268,7 +268,7 @@ export async function* streamProviderTurn(
 
 	let id = ''
 	const model = ''
-	const text = new StreamTextAccumulator()
+	let text = new StreamTextAccumulator()
 	let finishReason: ChatCompletionResponse['finishReason'] = 'stop'
 	// What the stream itself reported, if anything. `finishReason` above
 	// defaults to 'stop' for the response; classifying unreadable tool input
@@ -413,8 +413,31 @@ export async function* streamProviderTurn(
 					code: chunk.retry.code,
 					...(chunk.retry.status !== undefined ? { status: chunk.retry.status } : {}),
 					serverDirected: chunk.retry.serverDirected,
+					...(chunk.retry.restart ? { restart: true } : {}),
 				})
 				yield* drainPending()
+				if (chunk.retry.restart) {
+					// The failed attempt's text and reasoning are void: the request
+					// starts over under the same message. The decorator never
+					// restarts once a tool call began, so no bucket is left behind.
+					text = new StreamTextAccumulator()
+					reasoningBuckets.clear()
+					citations.length = 0
+					replayState = undefined
+					id = ''
+					finishReason = 'stop'
+					reportedFinishReason = undefined
+					finishDetail = undefined
+					streamedLength = 0
+					lastOutputCall = undefined
+					usage = {
+						promptTokens: 0,
+						completionTokens: 0,
+						totalTokens: 0,
+						cachedTokens: 0,
+						cacheWriteTokens: 0,
+					}
+				}
 				continue
 			}
 

package/src/runtime/query/prompt.ts

@@ -5,6 +5,7 @@ import {
 	type PromptContributionRegistry,
 	SKILLS_CONTRIBUTION_ID,
 } from '../../prompt/contributions.js'
+import { isWindowsBash } from '../../tools/command-shell.js'
 import type { ToolManager } from '../../toolsets/manager.js'
 import type { AgentRuntimeContext } from '../../types/agent/base.js'
 import type { AgentContextLevel } from '../../types/agent/factory.js'
@@ -135,8 +136,11 @@ function buildShellContext(config: PromptBuilderConfig): string | undefined {
 		)
 			continue
 		const dialect = tool.commandDialect({ sandboxed: config.sandboxed === true })
+		// Git Bash on a Windows host is named, so the line does not read as the
+		// Linux shell it is not. The syntax rules are in the tool's description.
+		const gitBash = !config.sandboxed && dialect === 'bash' && isWindowsBash()
 		lines.push(
-			`Execution shell for ${name}: ${dialect}${config.sandboxed ? ' (sandbox guest)' : ' (host)'}.`,
+			`Execution shell for ${name}: ${dialect}${config.sandboxed ? ' (sandbox guest)' : gitBash ? ' (Git Bash on Windows, host)' : ' (host)'}.`,
 		)
 		if (dialect === 'cmd')
 			lines.push(

package/src/tools/builtins/bash.ts

@@ -8,8 +8,12 @@ import { subscribeToAbort } from '../../utils/abort.js'
 import { readPositiveIntEnv } from '../../utils/env.js'
 import {
 	type CommandShell,
+	WINDOWS_BASH_GUIDANCE,
 	bashToolDialect,
 	describeSpawnFailure,
+	hostCommandShell,
+	isWindowsBash,
+	rewriteWindowsNullRedirect,
 	sandboxShellSpawn,
 	spawnHostShell,
 	withoutBashStartup,
@@ -57,6 +61,12 @@ const inputSchema = z.object({
 	command: z
 		.string()
 		.min(1)
+		// Git Bash on Windows: a model that writes `>nul` meant the null device.
+		// Rewritten here, before the permission rules read the line and before
+		// it runs, so the two see the same text.
+		.transform((command) =>
+			isWindowsBash(hostCommandShell()) ? rewriteWindowsNullRedirect(command) : command,
+		)
 		.describe(
 			'The bash command to execute. Required, non-empty. Single command per call (use `&&` / `;` chaining for compound commands). Avoid heredocs that span more than a few hundred bytes — large content should be created with `write`, then extended with `edit` insertLine: "end", not piped into bash.',
 		),
@@ -336,10 +346,12 @@ export const SANDBOX_CANNOT_DETACH =
 export const SANDBOX_ESCAPE_NOT_APPROVED =
 	'dangerously_disable_sandbox was not approved for this call, so the command did not run. Leaving the sandbox needs the user to confirm it each time, and this turn either cannot ask or does not allow it. Run the command inside the sandbox, or tell the user what it needs and let them run it.'
 
-export const BashTool = defineTool({
+const BASH_DESCRIPTION =
+	'Executes a command line using the execution shell disclosed in the system context and returns stdout/stderr output. Command timeout is configurable. The `command` parameter is required — never call this tool with empty arguments. For very long content (e.g. building a large file), prefer `write` for the opening and `edit` with insertLine: "end" for follow-up chunks over a heredoc to avoid hitting the output token limit mid-stream.'
+
+const BashToolBase = defineTool({
 	name: 'bash',
-	description:
-		'Executes a command line using the execution shell disclosed in the system context and returns stdout/stderr output. Command timeout is configurable. The `command` parameter is required — never call this tool with empty arguments. For very long content (e.g. building a large file), prefer `write` for the opening and `edit` with insertLine: "end" for follow-up chunks over a heredoc to avoid hitting the output token limit mid-stream.',
+	description: BASH_DESCRIPTION,
 	inputSchema,
 	// A command carries quotes and backslashes of its own, and a heredoc
 	// carries newlines: copied into the JSON string raw, they end it.
@@ -721,3 +733,21 @@ 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.`
 }
+
+/**
+ * The same tool, whose description gains the Windows guidance when the host
+ * shell is Git Bash. Resolved on first read, not at import: finding Git Bash
+ * runs `where.exe`, which a program that only imports the SDK must not pay.
+ */
+export const BashTool: typeof BashToolBase = Object.defineProperty(
+	{ ...BashToolBase },
+	'description',
+	{
+		enumerable: true,
+		configurable: true,
+		get: () =>
+			isWindowsBash(hostCommandShell())
+				? `${BASH_DESCRIPTION} ${WINDOWS_BASH_GUIDANCE}`
+				: BASH_DESCRIPTION,
+	},
+)

package/src/tools/builtins/job.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod'
 
+import { invalidBackgroundJobIdInput } from '../../runtime/jobs/job-id.js'
 import { defineTool } from '../defineTool.js'
 
 /**
@@ -90,6 +91,9 @@ export const JobTool = defineTool({
 			}
 		}
 
+		const badId = invalidBackgroundJobIdInput(input.id)
+		if (badId) return { success: false, output: '', error: badId }
+
 		try {
 			if (input.action === 'kill') {
 				const killed = await jobs.kill(input.id)

package/src/tools/builtins/wait-for-job.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod'
 
+import { invalidBackgroundJobIdInput } from '../../runtime/jobs/job-id.js'
 import { readPositiveIntEnv } from '../../utils/env.js'
 import { defineTool } from '../defineTool.js'
 import { describeJobWaitTimeout, waitForJobWithBounds } from './wait-for-job-bounds.js'
@@ -131,6 +132,9 @@ export const WaitForJobTool = defineTool({
 		}
 		const jobs = context.backgroundJobs
 
+		const badId = invalidBackgroundJobIdInput(input.id)
+		if (badId) return { success: false, output: '', error: badId }
+
 		try {
 			jobs.get(input.id)
 		} catch (err) {

package/src/tools/command-shell.ts

@@ -32,12 +32,30 @@
  * those would change what a command line means after the rules read it, so
  * they are removed from the environment of the spawned bash.
  * `NAMZU_BASH_SHELL=/bin/sh` restores the old shell exactly.
+ *
+ * ## Windows
+ *
+ * `cmd.exe` is a dialect the permission lexer cannot read: every command
+ * line comes back opaque, so every call needs a person in every mode, and a
+ * model writes POSIX syntax that cmd cannot run. So on Windows the same rule
+ * applies as everywhere else: run bash where it exists, and read the line as
+ * bash. The bash that exists on a Windows machine is Git for Windows'
+ * (`findGitBash`). Without it the tool falls back to cmd, as before, and
+ * {@link windowsShellNotice} says so once. `NAMZU_BASH_SHELL=cmd` keeps cmd
+ * on a machine that has Git Bash.
  */
 
-import { type ChildProcess, type SpawnOptions, spawn as nodeSpawn } from 'node:child_process'
+import {
+	type ChildProcess,
+	type SpawnOptions,
+	execFileSync,
+	spawn as nodeSpawn,
+} from 'node:child_process'
+import { randomUUID } from 'node:crypto'
 import { constants, accessSync, existsSync } from 'node:fs'
-import { delimiter, isAbsolute, join } from 'node:path'
+import { delimiter, isAbsolute, join, win32 } from 'node:path'
 
+import { MSYS_TAG_VARIABLE, registerMsysShell } from '../process/kill-tree.js'
 import type { ShellDialect } from '../types/tool/index.js'
 
 /** The shell a host-side command runs in. */
@@ -48,6 +66,8 @@ export interface CommandShell {
 	readonly dialect: ShellDialect
 	/** Where the choice came from, for diagnostics. */
 	readonly source: 'override' | 'bash' | 'sh' | 'platform'
+	/** True when this is a Windows executable (Git Bash), which needs Windows-only spawn details. */
+	readonly windows?: true
 }
 
 /** What resolution looks at. Injected by tests to simulate a host without bash. */
@@ -55,6 +75,13 @@ export interface CommandShellProbe {
 	readonly env: NodeJS.ProcessEnv
 	readonly platform: NodeJS.Platform
 	readonly isExecutable: (path: string) => boolean
+	/**
+	 * Windows only: the paths `where.exe git` prints, one per entry, in order.
+	 * Absent or throwing means git was not found on PATH.
+	 */
+	readonly whereGit?: () => readonly string[]
+	/** Windows only: the working directory, whose own programs are never trusted. Default: `process.cwd()`. */
+	readonly cwd?: string
 }
 
 const WELL_KNOWN_BASH = ['/bin/bash', '/usr/bin/bash']
@@ -63,6 +90,66 @@ const WELL_KNOWN_SH = ['/bin/sh', '/usr/bin/sh']
 /** Environment variables that change what a bash command line means. */
 const BASH_STARTUP_VARIABLES = new Set(['BASH_ENV', 'ENV', 'SHELLOPTS', 'BASHOPTS'])
 
+/** A variable of a Windows environment, whose names are not case-sensitive. */
+function windowsEnv(env: NodeJS.ProcessEnv, name: string): string | undefined {
+	const key = Object.keys(env).find((k) => k.toLowerCase() === name.toLowerCase())
+	return key === undefined ? undefined : env[key]
+}
+
+/** Is `path` the working directory or inside it? Windows paths compare without case. */
+function insideDirectory(path: string, directory: string): boolean {
+	const relative = win32.relative(directory, path)
+	return relative === '' || (!relative.startsWith('..') && !win32.isAbsolute(relative))
+}
+
+/**
+ * Git for Windows' bash.exe, found in this order:
+ *
+ * 1. `%ProgramFiles%\Git\bin\bash.exe`, then `%ProgramFiles(x86)%\Git\bin\bash.exe`;
+ * 2. `%LOCALAPPDATA%\\Programs\\Git\\bin\\bash.exe`, a per-user install;
+ * 3. the install that holds the first `git` that `where.exe git` lists: its
+ *    `bin\bash.exe`, one or two directories up from the `git.exe` it printed.
+ *    A hit inside the working directory is skipped, because a repository can
+ *    carry a `git.exe` of its own and the search must not run it.
+ *
+ * There is no registry lookup, and `where bash` is never asked: on a machine
+ * with WSL, `System32\bash.exe` is the launcher of another system.
+ */
+export function findGitBash(probe: CommandShellProbe): string | undefined {
+	const programFiles = windowsEnv(probe.env, 'ProgramFiles') ?? 'C:\\Program Files'
+	const programFilesX86 = windowsEnv(probe.env, 'ProgramFiles(x86)') ?? 'C:\\Program Files (x86)'
+	for (const root of [programFiles, programFilesX86]) {
+		const candidate = win32.join(root, 'Git', 'bin', 'bash.exe')
+		if (probe.isExecutable(candidate)) return candidate
+	}
+	// A per-user install (the installer's "just me" choice) lives under LOCALAPPDATA.
+	const localAppData = windowsEnv(probe.env, 'LOCALAPPDATA')
+	if (localAppData !== undefined && localAppData !== '') {
+		const candidate = win32.join(localAppData, 'Programs', 'Git', 'bin', 'bash.exe')
+		if (probe.isExecutable(candidate)) return candidate
+	}
+	let listed: readonly string[] = []
+	try {
+		listed = probe.whereGit?.() ?? []
+	} catch {
+		return undefined
+	}
+	const cwd = probe.cwd ?? process.cwd()
+	for (const line of listed) {
+		const git = line.trim()
+		if (!win32.isAbsolute(git) || insideDirectory(git, cwd)) continue
+		const directory = win32.dirname(git)
+		// <Git>\cmd\git.exe and <Git>\bin\git.exe, then <Git>\mingw64\bin\git.exe.
+		for (const candidate of [
+			win32.join(directory, '..', 'bin', 'bash.exe'),
+			win32.join(directory, '..', '..', 'bin', 'bash.exe'),
+		]) {
+			if (probe.isExecutable(candidate)) return candidate
+		}
+	}
+	return undefined
+}
+
 export function findCommandShell(probe: CommandShellProbe): CommandShell {
 	const override = probe.env.NAMZU_BASH_SHELL
 	if (override !== undefined && override !== '') {
@@ -76,11 +163,27 @@ export function findCommandShell(probe: CommandShellProbe): CommandShell {
 						?.toLowerCase()
 						.replace(/\.exe$/, '')
 				: override.slice(override.lastIndexOf('/') + 1)
-		return { path: override, dialect: name === 'bash' ? 'bash' : 'sh', source: 'override' }
+		// cmd is not a POSIX shell and takes no `-c`: naming it keeps Node's
+		// own cmd path, which is how a Windows machine with Git Bash runs the
+		// tool as it did before bash was preferred.
+		if (probe.platform === 'win32' && name === 'cmd')
+			return { path: undefined, dialect: 'cmd', source: 'override' }
+		return {
+			path: override,
+			dialect: name === 'bash' ? 'bash' : 'sh',
+			source: 'override',
+			...(probe.platform === 'win32' ? { windows: true as const } : {}),
+		}
+	}
+	// Looking `bash` up on the Windows PATH can find WSL's launcher, which
+	// runs the command in another system, so only Git for Windows' own
+	// install is used. Without it Node's platform shell (cmd) runs the line.
+	if (probe.platform === 'win32') {
+		const gitBash = findGitBash(probe)
+		return gitBash === undefined
+			? { path: undefined, dialect: 'cmd', source: 'platform' }
+			: { path: gitBash, dialect: 'bash', source: 'bash', windows: true }
 	}
-	// Windows keeps Node's platform shell. Looking `bash` up on its PATH can
-	// find WSL's launcher, which runs the command in another system.
-	if (probe.platform === 'win32') return { path: undefined, dialect: 'cmd', source: 'platform' }
 	for (const directory of (probe.env.PATH ?? '').split(delimiter)) {
 		if (directory === '' || !directory.startsWith('/')) continue
 		const candidate = join(directory, 'bash')
@@ -92,6 +195,55 @@ export function findCommandShell(probe: CommandShellProbe): CommandShell {
 	return { path: '/bin/sh', dialect: 'sh', source: 'sh' }
 }
 
+/**
+ * Said once, in the session, when a Windows machine has no Git Bash and the
+ * `bash` tool runs cmd.exe. Undefined everywhere else.
+ */
+export const WINDOWS_CMD_FALLBACK_NOTICE =
+	'Git for Windows not found — shell commands run in cmd.exe and each one asks for approval. Install Git for Windows for full support.'
+
+export function windowsShellNotice(shell: CommandShell = hostCommandShell()): string | undefined {
+	return shell.source === 'platform' && shell.path === undefined && shell.dialect === 'cmd'
+		? WINDOWS_CMD_FALLBACK_NOTICE
+		: undefined
+}
+
+/**
+ * Is the host `bash` tool Git Bash on Windows? The model is then told so, and
+ * the Windows-only spawn details apply.
+ */
+export function isWindowsBash(shell: CommandShell = hostCommandShell()): boolean {
+	return shell.windows === true && shell.dialect === 'bash'
+}
+
+/** What a model needs to know when the `bash` tool is Git Bash on Windows, appended to the tool's description. */
+export const WINDOWS_BASH_GUIDANCE =
+	'This tool runs Git Bash (POSIX sh), not cmd.exe or PowerShell. Use Unix shell syntax: `/dev/null` not `NUL`, forward slashes, `$VAR` not `%VAR%` or `$env:VAR`. To run PowerShell, call `powershell -NoProfile -Command "…"`.'
+
+/**
+ * Rewrite a redirect to Windows' `NUL` device (`>nul`, `2>NUL`, `&>nul`) to
+ * `/dev/null`. In bash `nul` is an ordinary file name, so the line would
+ * create a file called `nul` that Windows then cannot delete. A line with
+ * `<`, `$` or a backtick is left alone: it may be a heredoc or a string that
+ * only mentions the text.
+ */
+export function rewriteWindowsNullRedirect(command: string): string {
+	if (/[<$`]/.test(command)) return command
+	return command.replace(/(\d?&?>+[ \t]*)nul(?=\s|$|[|&;)\n])/gi, '$1/dev/null')
+}
+
+/** `where.exe git`, run from the system directory by its absolute path, so PATH cannot stand in for it. */
+function whereGit(): readonly string[] {
+	const root = process.env.SystemRoot ?? process.env.windir ?? 'C:\\Windows'
+	const output = execFileSync(win32.join(root, 'System32', 'where.exe'), ['git'], {
+		encoding: 'utf8',
+		windowsHide: true,
+		stdio: ['ignore', 'pipe', 'ignore'],
+		timeout: 5000,
+	})
+	return output.split(/\r?\n/)
+}
+
 /**
  * An explicitly requested interpreter for a host script. Unlike the live
  * `bash` tool's automatic choice, this never substitutes bash for sh (or sh
@@ -144,7 +296,12 @@ let resolved: CommandShell | undefined
  */
 export function hostCommandShell(): CommandShell {
 	if (resolved === undefined) {
-		resolved = findCommandShell({ env: process.env, platform: process.platform, isExecutable })
+		resolved = findCommandShell({
+			env: process.env,
+			platform: process.platform,
+			isExecutable,
+			whereGit,
+		})
 	}
 	return resolved
 }
@@ -180,7 +337,17 @@ export function hostShellSpawn(
 } {
 	if (shell.path === undefined) return { file: undefined, args: [command], env }
 	if (shell.dialect !== 'bash') return { file: shell.path, args: ['-c', command], env }
-	return { file: shell.path, args: ['-c', command], env: withoutBashStartup(env) }
+	const clean = withoutBashStartup(env)
+	// Git for Windows: the line is read as bash, so `>nul` must already have
+	// become `/dev/null` (the tool's input does that before the rules read it;
+	// this covers a caller that did not), and git must never open an editor.
+	if (shell.windows === true)
+		return {
+			file: shell.path,
+			args: ['-c', rewriteWindowsNullRedirect(command)],
+			env: { ...clean, GIT_EDITOR: 'true' },
+		}
+	return { file: shell.path, args: ['-c', command], env: clean }
 }
 
 /** Why a command could not be started, in the words a model or operator reads. */
@@ -283,15 +450,31 @@ export function spawnHostShell(
 	},
 ): ChildProcess {
 	const spawnFn = options.spawnImpl ?? nodeSpawn
-	const resolved = hostShellSpawn(command, options.env, options.shell)
+	const shell = options.shell ?? hostCommandShell()
+	const spawned = hostShellSpawn(command, options.env, shell)
+	// Git Bash: tag the shell so a kill can find what a forked command left.
+	const tag = shell.windows === true && shell.path !== undefined ? randomUUID() : undefined
+	const resolved =
+		tag === undefined ? spawned : { ...spawned, env: { ...spawned.env, [MSYS_TAG_VARIABLE]: tag } }
 	const common: SpawnOptions = {
 		cwd: options.cwd,
 		env: resolved.env,
 		detached: options.detached ?? (options.platform ?? process.platform) !== 'win32',
 		windowsHide: true,
-		...(options.stdio === undefined ? {} : { stdio: options.stdio }),
+		// Git Bash reads no terminal: a command that asks for input gets
+		// end-of-file (the null device) instead of waiting for a timeout.
+		...(options.stdio === undefined
+			? resolved.file !== undefined && shell.windows === true
+				? { stdio: ['ignore', 'pipe', 'pipe'] as SpawnOptions['stdio'] }
+				: {}
+			: { stdio: options.stdio }),
+	}
+	if (resolved.file !== undefined) {
+		const child = spawnFn(resolved.file, [...resolved.args], common)
+		if (tag !== undefined && child !== null && typeof child === 'object')
+			registerMsysShell(child, { bash: resolved.file, tag })
+		return child
 	}
-	if (resolved.file !== undefined) return spawnFn(resolved.file, [...resolved.args], common)
 	const windows = windowsCmdSpawn(command, resolved.env)
 	return spawnFn(windows.file, [...windows.args], {
 		...common,

package/src/types/provider/error.ts

@@ -45,4 +45,10 @@ export interface ProviderRequestErrorInit extends ProviderErrorInfo {
 	 * still welcome; what is not welcome is a raw body passed straight in.
 	 */
 	readonly detail?: string
+	/**
+	 * The provider's own `x-should-retry` verdict, when it sent one. Only `false`
+	 * is acted on: a provider that says the same request must not be sent again
+	 * is believed over the status code, so the retry loop leaves it alone.
+	 */
+	readonly shouldRetry?: boolean
 }