@namzu/sdk 30.2.0 → 31.0.0

package/src/agents/RouterAgent.ts

@@ -1,5 +1,6 @@
 import { EMPTY_TOKEN_USAGE } from '../constants/limits.js'
 import { collectChatCompletion } from '../provider/collect-chat-completion.js'
+import { resolveStreamIdleTimeoutMs, withStreamIdleTimeout } from '../provider/idle-timeout.js'
 import { FallbackResolver } from '../runtime/decision/fallback.js'
 import { DecisionParser } from '../runtime/decision/parser.js'
 import type {
@@ -61,13 +62,19 @@ export class RouterAgent extends AbstractAgent<RouterAgentConfig, RouterAgentRes
 		config: RouterAgentConfig,
 		listener?: RunEventListener,
 	): Promise<RouterAgentResult> {
+		// Resolve before a run id/event exists, matching query(): malformed
+		// liveness policy is a caller config error, not a failed model run.
+		const streamIdleTimeoutMs = resolveStreamIdleTimeoutMs(config.streamIdleTimeoutMs)
+		const signal = input.signal
+			? AbortSignal.any([input.signal, this.abortController.signal])
+			: this.abortController.signal
 		const startTime = Date.now()
 		const runId = this.createRunId()
 		this.bindRun(runId, config.logger)
 
 		await this.emitEvent({ type: 'run_started', runId }, listener)
 
-		const decision = await this.route(input, config)
+		const decision = await this.route(input, config, streamIdleTimeoutMs, signal)
 
 		let targetRoute = config.routes.find((r) => r.agentId === decision.agentId)
 
@@ -149,7 +156,12 @@ export class RouterAgent extends AbstractAgent<RouterAgentConfig, RouterAgentRes
 		}
 	}
 
-	private async route(input: AgentInput, config: RouterAgentConfig): Promise<RoutingDecision> {
+	private async route(
+		input: AgentInput,
+		config: RouterAgentConfig,
+		streamIdleTimeoutMs: number,
+		signal: AbortSignal,
+	): Promise<RoutingDecision> {
 		// `this.log`, not a fresh `getRootLogger()` child — bound by `bindRun` in
 		// `runExclusive` before this is called, so a routing warning below
 		// carries the SAME `namzu.run.id` as the run it is routing. The old
@@ -209,15 +221,20 @@ export class RouterAgent extends AbstractAgent<RouterAgentConfig, RouterAgentRes
 		// Every routing attempt is a billed model call; a fallback after
 		// three failed parses still cost three calls.
 		let routingUsage: TokenUsage = { ...EMPTY_TOKEN_USAGE }
+		const routingProvider = withStreamIdleTimeout(config.provider, {
+			idleTimeoutMs: streamIdleTimeoutMs,
+			log,
+		})
 
 		for (let attempt = 0; attempt < maxRetries; attempt++) {
 			try {
 				const response = await collectChatCompletion(
-					config.provider.chatStream({
+					routingProvider.chatStream({
 						model: config.model,
 						messages: [createSystemMessage(prompt), createUserMessage(userContent)],
 						temperature: 0,
 						maxTokens: 200,
+						signal,
 					}),
 				)
 
@@ -265,6 +282,11 @@ export class RouterAgent extends AbstractAgent<RouterAgentConfig, RouterAgentRes
 					}
 				}
 			} catch (err) {
+				// Provider-idle expiry aborts only the wrapper's private transport
+				// and is eligible for the router's declared fallback. A caller or
+				// agent cancellation owns this fused signal and must not be
+				// reinterpreted as permission to start a delegate.
+				if (signal.aborted) throw signal.reason
 				log.warn('Routing LLM call failed', {
 					'namzu.router.attempt': attempt + 1,
 					'exception.message': String(err),

package/src/agents/SupervisorAgent.ts

@@ -4,7 +4,7 @@ import { drainQuery } from '../runtime/query/index.js'
 import { PendingAnswers, QuestionParkBinding } from '../runtime/query/question-park.js'
 import { CompletionInbox } from '../scheduler/completion-inbox.js'
 import { LocalTaskScheduler } from '../scheduler/local.js'
-import { buildCoordinatorTools } from '../tools/coordinator/index.js'
+import { ASK_USER_QUESTION_TOOL_NAME, buildCoordinatorTools } from '../tools/coordinator/index.js'
 import type {
 	AgentInput,
 	AgentMetadata,
@@ -151,17 +151,19 @@ export class SupervisorAgent extends AbstractAgent<SupervisorAgentConfig, Superv
 				parentRunId: runId,
 				parentAgentId: this.metadata.id,
 				parentAbortController: this.abortController,
-				depth: 0,
+				// This context describes the CURRENT supervisor. AgentManager owns
+				// the increment when it constructs the child. Resetting a delegated
+				// supervisor to zero here made every grandchild depth one again.
+				depth: config.depth ?? 0,
 				budgetTracker: {
 					total: config.tokenBudget,
 					remaining: config.tokenBudget,
 				},
 				factoryOptions: mergedFactoryOptions,
-				// The supervisor already hands this to its OWN run and its own
-				// coordinator tools; handing it to the spawn context is what
-				// makes a worker ask the same person the supervisor asks.
-				// Without it the two disagreed: the supervisor paused for a
-				// human and the workers it launched approved themselves.
+				// The supervisor already hands this to its OWN run. Handing it to
+				// the spawn context makes a worker's REVIEW-tier calls reach the
+				// same person. It does not grant the root-only question tool.
+				// Without the handler, workers silently auto-approved themselves.
 				...(config.resumeHandler ? { resumeHandler: config.resumeHandler } : {}),
 				tenantId,
 				topicId,
@@ -210,6 +212,7 @@ export class SupervisorAgent extends AbstractAgent<SupervisorAgentConfig, Superv
 		// runs again — which is how a leak of one listener per run becomes a leak
 		// of one per ATTEMPT.
 		try {
+			const isRootAgent = (config.depth ?? 0) === 0
 			const coordinatorToolDefs = buildCoordinatorTools({
 				gateway,
 				completionInbox,
@@ -224,10 +227,11 @@ export class SupervisorAgent extends AbstractAgent<SupervisorAgentConfig, Superv
 				taskStore: input.taskStore,
 				runId,
 				getPlanManager: () => planManagerRef,
-				// With a resume handler present the coordinator surface gains
-				// ask_user_question — the model can park the run on a question
-				// routed through the same HITL channel as plan approvals.
-				...(config.resumeHandler ? { resumeHandler: config.resumeHandler } : {}),
+				// A human-question tool belongs only to the root agent. The handler
+				// itself still reaches `drainQuery` below: delegated REVIEW-tier
+				// tool calls must keep asking the operator instead of falling back
+				// to unattended auto-approval.
+				...(isRootAgent && config.resumeHandler ? { resumeHandler: config.resumeHandler } : {}),
 				questionParks,
 				pendingAnswers,
 				...(config.onPlanApproved ? { onPlanApproved: config.onPlanApproved } : {}),
@@ -236,6 +240,10 @@ export class SupervisorAgent extends AbstractAgent<SupervisorAgentConfig, Superv
 			const tools = new ToolRegistry()
 			if (config.tools) {
 				for (const tool of config.tools.getAll()) {
+					// The boundary is semantic, not an implementation detail of the
+					// built-in builder. A host registry containing the same capability
+					// must not reopen it for a delegated agent.
+					if (!isRootAgent && tool.name === ASK_USER_QUESTION_TOOL_NAME) continue
 					tools.register(tool, config.tools.getAvailability(tool.name))
 				}
 			}
@@ -307,6 +315,14 @@ export class SupervisorAgent extends AbstractAgent<SupervisorAgentConfig, Superv
 						model: config.model,
 						tokenBudget: config.tokenBudget,
 						timeoutMs: config.timeoutMs,
+						...(config.streamIdleTimeoutMs !== undefined
+							? { streamIdleTimeoutMs: config.streamIdleTimeoutMs }
+							: {}),
+						...(config.maxRequestRichContentBytes !== undefined
+							? {
+									maxRequestRichContentBytes: config.maxRequestRichContentBytes,
+								}
+							: {}),
 						maxIterations: config.maxIterations,
 						temperature: config.temperature,
 						env: config.env,
@@ -359,6 +375,9 @@ export class SupervisorAgent extends AbstractAgent<SupervisorAgentConfig, Superv
 					// corrected for twice.
 					...(config.steering ? { steering: config.steering } : {}),
 					...(config.inboundMessages ? { inboundMessages: config.inboundMessages } : {}),
+					...(config.projectInstructionContext
+						? { projectInstructionContext: config.projectInstructionContext }
+						: {}),
 					...(config.authorizationGate ? { authorizationGate: config.authorizationGate } : {}),
 					// The one hop between the config and the tool. `drainQuery`
 					// registers `structured_output` from this and the loop
@@ -366,6 +385,9 @@ export class SupervisorAgent extends AbstractAgent<SupervisorAgentConfig, Superv
 					// came from — only `ReactiveAgent` was passing it.
 					...(config.structuredOutput ? { structuredOutput: config.structuredOutput } : {}),
 					...(config.sandboxProvider ? { sandboxProvider: config.sandboxProvider } : {}),
+					...(config.sandboxTeardownTimeoutMs !== undefined
+						? { sandboxTeardownTimeoutMs: config.sandboxTeardownTimeoutMs }
+						: {}),
 					// Working-memory / compaction seam (optional; absent => unchanged
 					// run path, byte-identical for every existing consumer).
 					...(config.compactionConfig ? { compactionConfig: config.compactionConfig } : {}),

package/src/agents/runAgent.ts

@@ -1,10 +1,12 @@
 import { ToolRegistry } from '../registry/tool/execute.js'
 import { drainQuery } from '../runtime/query/index.js'
+import type { ProjectInstructionContext } from '../runtime/query/project-instructions.js'
 import type { AuthorizationGateConfig } from '../types/authorization/index.js'
 import type { ProjectId, SessionId, TenantId, TopicId } from '../types/ids/index.js'
 import type { Message } from '../types/message/index.js'
 import type { LLMProvider, ReasoningEffort, ThinkingConfig } from '../types/provider/index.js'
 import type { Run, RunEventListener } from '../types/run/index.js'
+import type { SandboxProvider } from '../types/sandbox/index.js'
 import type { Skill } from '../types/skills/index.js'
 import type { StructuredOutputConfig } from '../types/structured-output/index.js'
 import type { ToolRegistryContract } from '../types/tool/index.js'
@@ -62,6 +64,10 @@ export interface RunAgentOptions extends AgentIdentity {
 	model: string
 
 	tools?: ToolRegistryContract
+	/** Execute sandbox-aware tools inside this provider's boundary. */
+	sandboxProvider?: SandboxProvider
+	/** Sandbox teardown wait; defaults to 30 seconds and `0` is unbounded. */
+	sandboxTeardownTimeoutMs?: number
 
 	/**
 	 * Skills to put in front of the model.
@@ -97,6 +103,10 @@ export interface RunAgentOptions extends AgentIdentity {
 	maxIterations?: number
 	tokenBudget?: number
 	timeoutMs?: number
+	/** Maximum provider-stream silence; defaults to five minutes. `0` disables. */
+	streamIdleTimeoutMs?: number
+	/** Accumulated inline image/document bytes per provider request. `0` disables. */
+	maxRequestRichContentBytes?: number
 	temperature?: number
 
 	/**
@@ -134,6 +144,8 @@ export interface RunAgentOptions extends AgentIdentity {
 
 	signal?: AbortSignal
 	listener?: RunEventListener
+	/** Live project policy for hosts that discover nested instruction scopes. */
+	projectInstructionContext?: ProjectInstructionContext
 }
 
 export interface RunAgentResult {
@@ -225,13 +237,23 @@ export async function runAgent(options: RunAgentOptions): Promise<RunAgentResult
 
 	const messages: Message[] =
 		typeof options.prompt === 'string'
-			? [{ role: 'user', content: options.prompt, timestamp: Date.now() } as Message]
+			? [
+					{
+						role: 'user',
+						content: options.prompt,
+						timestamp: Date.now(),
+					} as Message,
+				]
 			: options.prompt
 
 	const run = await drainQuery(
 		{
 			provider: options.provider,
 			tools: options.tools ?? new ToolRegistry(),
+			...(options.sandboxProvider ? { sandboxProvider: options.sandboxProvider } : {}),
+			...(options.sandboxTeardownTimeoutMs !== undefined
+				? { sandboxTeardownTimeoutMs: options.sandboxTeardownTimeoutMs }
+				: {}),
 			messages,
 			workingDirectory: options.workingDirectory ?? process.cwd(),
 			runConfig: {
@@ -239,6 +261,12 @@ export async function runAgent(options: RunAgentOptions): Promise<RunAgentResult
 				maxIterations: options.maxIterations ?? DEFAULT_MAX_ITERATIONS,
 				tokenBudget: options.tokenBudget ?? DEFAULT_TOKEN_BUDGET,
 				timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+				...(options.streamIdleTimeoutMs !== undefined
+					? { streamIdleTimeoutMs: options.streamIdleTimeoutMs }
+					: {}),
+				...(options.maxRequestRichContentBytes !== undefined
+					? { maxRequestRichContentBytes: options.maxRequestRichContentBytes }
+					: {}),
 				...(options.temperature !== undefined ? { temperature: options.temperature } : {}),
 				...(options.thinking ? { thinking: options.thinking } : {}),
 				...(options.effort ? { effort: options.effort } : {}),
@@ -256,10 +284,18 @@ export async function runAgent(options: RunAgentOptions): Promise<RunAgentResult
 			...(options.verificationGate ? { verificationGate: options.verificationGate } : {}),
 			...(options.authorizationGate ? { authorizationGate: options.authorizationGate } : {}),
 			...(options.structuredOutput ? { structuredOutput: options.structuredOutput } : {}),
+			...(options.projectInstructionContext
+				? { projectInstructionContext: options.projectInstructionContext }
+				: {}),
 			...identity,
 		},
 		options.listener,
 	)
 
-	return { output: run.result, structuredOutput: run.structuredOutput, run, identity }
+	return {
+		output: run.result,
+		structuredOutput: run.structuredOutput,
+		run,
+		identity,
+	}
 }

package/src/authorization/command-line.ts

@@ -0,0 +1,390 @@
+/**
+ * Break a command line into the commands it actually runs.
+ *
+ * ## The hole this closes
+ *
+ * A pattern rule tests a regular expression against an argument's value. When
+ * that value is a command line, the value and the command are not the same
+ * thing: `git push origin main` is one command, and
+ * `true; git push origin main` is two, of which the second is the one the rule
+ * was written about. An anchored pattern sees only the first.
+ *
+ * Measured against the gate, with the rule from this repository's own
+ * documentation (`^git push`, deny):
+ *
+ *     git push origin main               -> deny
+ *     echo hi && git push origin main    -> did not match
+ *     true; git push origin main         -> did not match
+ *     bash -c "git push origin main"     -> did not match
+ *
+ * A rule that fails to match reaches the permission mode, and a run with no
+ * terminal resolves that to `auto`. So an operator's prohibition was bypassed
+ * by typing four characters in front of it, in exactly the unattended case the
+ * prohibition exists for. The `bash` tool's own description tells the model to
+ * "use `&&` / `;` chaining for compound commands", so the evading form is not
+ * an exotic input — it is the documented one.
+ *
+ * ## Why splitting alone would make things worse
+ *
+ * Applied naively this widens `allow` in the same motion it fixes `deny`. An
+ * allow rule matching `^git status` would go on matching the first segment of
+ * `git status && rm -rf ~` and hand back `allow` for the whole line. So the
+ * caller must read the two decisions differently, and {@link evaluateRule}
+ * does:
+ *
+ * - **deny** matches when ANY segment matches. One prohibited command poisons
+ *   the line it rides on.
+ * - **allow** matches only when EVERY segment matches, and never when the line
+ *   is {@link CommandLineDecomposition.opaque}. Permission is a claim about the
+ *   whole line, and a claim that cannot be checked is not granted.
+ *
+ * That asymmetry is the same one `refuse-do-not-degrade` describes: when the
+ * analysis is uncertain, the uncertainty spends against the permissive answer.
+ *
+ * ## What `opaque` means
+ *
+ * Some lines contain text that is not the command that runs. Command
+ * substitution (`$(…)`, backticks, `<(…)`) executes something whose text is
+ * not in the line at all, and `eval` runs a string assembled at runtime. No
+ * decomposition of the source can be a decomposition of what ran, so the line
+ * is marked opaque and `allow` declines it. `deny` still tests what is visible,
+ * because a deny that matches too much costs a prompt and a deny that matches
+ * too little costs the thing it was written to prevent.
+ *
+ * ## What it deliberately does not do
+ *
+ * A value with no chain operator, no nested shell and nothing opaque comes back
+ * as itself, byte for byte. That keeps every rule about a non-command argument
+ * — a path, a number, a URL — behaving exactly as it did, and confines this
+ * machinery to the case that motivated it.
+ *
+ * It is a decomposition, not a shell. `xargs sh -c`, a command read from a
+ * file, and a shell invoked through an interpreter it does not recognise all
+ * pass through as ordinary text. Each of those either denies as before or, for
+ * an allow rule, fails to match every segment and so declines. The failure mode
+ * is a prompt, never a silent grant.
+ */
+
+/** The commands a line runs, and whether that list can be trusted as complete. */
+export interface CommandLineDecomposition {
+	/**
+	 * The individual commands, in source order. Never empty: a line that
+	 * decomposes to nothing yields the original.
+	 */
+	readonly segments: readonly string[]
+	/**
+	 * True when the line runs something this decomposition cannot see, so
+	 * `segments` is a lower bound rather than the whole story.
+	 */
+	readonly opaque: boolean
+}
+
+/**
+ * Shells whose `-c` argument is another command line.
+ *
+ * Matched on the basename, so `/bin/bash` and `bash` are the same entry. An
+ * interpreter absent from this list is not a hole that grants anything: its
+ * payload stays inside one segment, where an allow rule fails to match it.
+ */
+const NESTED_SHELLS = new Set(['sh', 'bash', 'zsh', 'dash', 'ksh', 'ash', 'busybox'])
+
+/** Commands whose argument is code assembled at runtime. */
+const RUNTIME_EVALUATORS = new Set(['eval', 'source', '.'])
+
+/**
+ * Depth and width limits.
+ *
+ * A line that exceeds either is reported opaque rather than truncated: a
+ * shortened list of segments would read as complete to `allow`, which is the
+ * one reading that must never be wrong.
+ */
+const MAX_DEPTH = 4
+const MAX_SEGMENTS = 64
+
+export function decomposeCommandLine(command: string): CommandLineDecomposition {
+	const state: WalkState = { opaque: false, structured: false }
+	const segments = split(command, state, 0)
+
+	// The untouched-value case, kept exact. Nothing was cut and nothing was
+	// unpacked, so there is no decomposition to report and the value goes back
+	// as it arrived — which is what keeps a rule about a path or a URL seeing
+	// the string it always saw, punctuation and surrounding space included.
+	if (!state.structured) return { segments: [command], opaque: state.opaque }
+
+	if (segments.length === 0) return { segments: [command], opaque: state.opaque }
+	if (segments.length > MAX_SEGMENTS) {
+		return { segments: segments.slice(0, MAX_SEGMENTS), opaque: true }
+	}
+	return { segments, opaque: state.opaque }
+}
+
+interface WalkState {
+	opaque: boolean
+	/**
+	 * Whether anything was cut or unpacked. False means the value is not a
+	 * command line as far as this module can tell, and it goes back untouched.
+	 */
+	structured: boolean
+}
+
+/**
+ * Walk the line once, quote-aware, cutting at every top-level separator.
+ *
+ * Quote tracking is the whole reason this is not a `String.split`: `echo "a &&
+ * b"` is one command that prints a literal, and a splitter that cannot tell
+ * would report a second command named `b"` — inventing a segment is as wrong as
+ * missing one, because `allow` requires every segment to match.
+ */
+function split(command: string, state: WalkState, depth: number): string[] {
+	const segments: string[] = []
+	let current = ''
+	let quote: "'" | '"' | null = null
+
+	const cut = (): void => {
+		const trimmed = trimSegment(current)
+		current = ''
+		if (trimmed === '') return
+		for (const piece of expand(trimmed, state, depth)) segments.push(piece)
+	}
+
+	for (let i = 0; i < command.length; i += 1) {
+		const char = command[i] as string
+
+		if (quote === "'") {
+			// Single quotes suspend everything, including the backslash. This is
+			// the branch that keeps `echo 'a && b'` one command.
+			if (char === "'") quote = null
+			current += char
+			continue
+		}
+
+		if (char === '\\') {
+			// An escaped separator is a literal, so both characters go through
+			// untouched and the next loop never sees the separator as one.
+			current += char + (command[i + 1] ?? '')
+			i += 1
+			continue
+		}
+
+		if (quote === '"') {
+			if (char === '"') quote = null
+			// Substitution is live inside double quotes, which is exactly where
+			// it hides best.
+			else if (isSubstitutionStart(command, i)) state.opaque = true
+			current += char
+			continue
+		}
+
+		if (char === "'" || char === '"') {
+			quote = char
+			current += char
+			continue
+		}
+
+		if (isSubstitutionStart(command, i)) {
+			state.opaque = true
+			current += char
+			continue
+		}
+
+		const separator = separatorAt(command, i)
+		if (separator > 0) {
+			state.structured = true
+			cut()
+			i += separator - 1
+			continue
+		}
+
+		current += char
+	}
+
+	// An unterminated quote means the line does not parse. Whatever it runs is
+	// not what this walk saw, so the caller must not treat the result as a
+	// complete account.
+	if (quote !== null) state.opaque = true
+
+	cut()
+	return segments
+}
+
+/**
+ * Length of the separator starting at `index`, or 0.
+ *
+ * The redirection cases are why this is a function. `2>&1` and `&>log` contain
+ * `&` and are not separators; splitting there would manufacture a segment named
+ * `1`, which no allow rule matches, and a command that redirects its output
+ * would stop being approvable for a reason nobody could see.
+ */
+function separatorAt(command: string, index: number): number {
+	const char = command[index]
+	const next = command[index + 1]
+
+	if (char === '\n') return 1
+	if (char === ';') return next === ';' ? 2 : 1
+	if (char === '&') {
+		if (next === '&') return 2
+		if (next === '>') return 0
+		if (command[index - 1] === '>') return 0
+		return 1
+	}
+	if (char === '|') {
+		if (next === '|') return 2
+		// `|&` pipes stderr as well; still a pipe, and both sides still run.
+		if (next === '&') return 2
+		return 1
+	}
+	return 0
+}
+
+/** Whether a command substitution opens here. */
+function isSubstitutionStart(command: string, index: number): boolean {
+	const char = command[index]
+	if (char === '`') return true
+	if (char === '$' && command[index + 1] === '(') return true
+	// Process substitution: `diff <(a) <(b)` runs `a` and `b`.
+	if ((char === '<' || char === '>') && command[index + 1] === '(') return true
+	return false
+}
+
+/**
+ * Strip the grouping punctuation a split leaves behind.
+ *
+ * `(cd build && make)` cuts into `(cd build` and `make)`. Leaving the bracket on
+ * would stop an allow rule matching a command it names, and — worse — stop a
+ * deny rule matching one, since `^make` does not match `make)`.
+ */
+function trimSegment(segment: string): string {
+	return segment
+		.trim()
+		.replace(/^[({\s]+/, '')
+		.replace(/[)}\s]+$/, '')
+}
+
+/**
+ * Turn one segment into the commands it stands for.
+ *
+ * A shell invoked with `-c` carries a whole second command line in an argument,
+ * and that argument is where the smuggling this module exists for is easiest:
+ * `bash -c "git push"` contains no separator at all, so nothing above this
+ * function would have looked inside it.
+ *
+ * The outer segment is kept alongside the inner ones. A rule that denies the
+ * interpreter itself must still fire, and for `allow` the extra segment only
+ * makes the requirement stricter — which is the safe direction.
+ */
+function expand(segment: string, state: WalkState, depth: number): string[] {
+	const words = tokenize(segment)
+	const head = words[0]
+	if (head === undefined) return [segment]
+
+	if (RUNTIME_EVALUATORS.has(basename(head.text))) {
+		// The argument is source text assembled elsewhere. Even when it is a
+		// visible literal, what runs is decided at runtime.
+		state.opaque = true
+		return [segment]
+	}
+
+	if (!NESTED_SHELLS.has(basename(head.text))) return [segment]
+
+	const flag = words.findIndex(
+		(word, index) => index > 0 && word.quoted === null && word.text === '-c',
+	)
+	if (flag < 0) return [segment]
+
+	const payload = words[flag + 1]
+	if (payload === undefined) {
+		// `bash -c` with nothing after it is either a syntax error or an
+		// argument this tokenizer failed to read. Neither may be reported as
+		// "there is no nested command".
+		state.opaque = true
+		return [segment]
+	}
+
+	if (depth + 1 >= MAX_DEPTH) {
+		state.opaque = true
+		return [segment]
+	}
+
+	const nested = split(payload.text, state, depth + 1)
+	if (nested.length === 0) return [segment]
+	state.structured = true
+	return [segment, ...nested]
+}
+
+interface Word {
+	readonly text: string
+	/** The quote that wrapped it, or null when it was bare. */
+	readonly quoted: "'" | '"' | null
+}
+
+/**
+ * Split a segment into words, removing one layer of quoting.
+ *
+ * The quote is reported rather than discarded because `-c` must be the flag and
+ * not a literal: `echo "-c"` names no nested shell, and treating its next word
+ * as a command line would decompose a string that never runs.
+ */
+function tokenize(segment: string): Word[] {
+	const words: Word[] = []
+	let current = ''
+	let quote: "'" | '"' | null = null
+	let sawQuote: "'" | '"' | null = null
+	let open = false
+
+	const push = (): void => {
+		if (open) words.push({ text: current, quoted: sawQuote })
+		current = ''
+		sawQuote = null
+		open = false
+	}
+
+	for (let i = 0; i < segment.length; i += 1) {
+		const char = segment[i] as string
+
+		if (quote === "'") {
+			// Single quotes suspend the backslash too, so this branch precedes
+			// the escape below rather than sharing it.
+			if (char === "'") quote = null
+			else current += char
+			open = true
+			continue
+		}
+
+		if (char === '\\' && i + 1 < segment.length) {
+			current += segment[i + 1]
+			i += 1
+			open = true
+			continue
+		}
+
+		if (quote === '"') {
+			if (char === '"') quote = null
+			else current += char
+			open = true
+			continue
+		}
+
+		if (char === "'" || char === '"') {
+			quote = char
+			sawQuote = char
+			open = true
+			continue
+		}
+
+		if (char === ' ' || char === '\t') {
+			push()
+			continue
+		}
+
+		current += char
+		open = true
+	}
+
+	push()
+	return words
+}
+
+function basename(word: string): string {
+	const cut = word.lastIndexOf('/')
+	return cut < 0 ? word : word.slice(cut + 1)
+}