@namzu/sdk 15.1.0 → 17.0.0

package/src/provider/fallback.ts

@@ -0,0 +1,300 @@
+/**
+ * Advance through a declared provider chain when a member cannot serve.
+ *
+ * The sibling of `withProviderRetry`, one level out: retry asks "will the SAME
+ * member succeed if I ask again?", this asks "will ANOTHER member succeed if I
+ * ask it instead?". They compose in exactly one order —
+ * `fallback(retry(m0), retry(m1), …)` — and that order is the policy, not an
+ * implementation detail:
+ *
+ *  - the primary is the operator's choice and gets its retries first, so a
+ *    throttle or a 5xx only reaches this decorator once the inner budget is
+ *    spent;
+ *  - a failure the inner loop refuses to retry (`auth`, `not_found`) arrives
+ *    here immediately, which is what "fall over at once on a bad credential"
+ *    means — retrying a wrong key just spends the turn;
+ *  - a server-directed `Retry-After` is honoured by the inner loop before any
+ *    error escapes, so a transient wait is a wait and not a swap.
+ *
+ * None of those three behaviours is implemented here. They fall out of the
+ * nesting, which is why `query()` builds the composition rather than letting a
+ * host assemble it in whichever order it happens to pick.
+ */
+
+import { classifyProviderError, isAbortError } from '../types/provider/errors.js'
+import type { ChatCompletionParams, LLMProvider, StreamChunk } from '../types/provider/index.js'
+import type { Logger } from '../utils/logger.js'
+
+/**
+ * One member of the chain: a constructed provider, and the model to ask it for.
+ *
+ * `model` overrides {@link ChatCompletionParams.model} for this member's
+ * requests and nothing else. Every shipped driver reads that field
+ * (`params.model`, or `params.model || <its configured default>`), so a member
+ * needs no reconstruction to be asked for a different model — which is what
+ * keeps this decorator ignorant of credentials, base URLs and registries. A
+ * chain is an ordered list of (provider, model); building one is the host's
+ * job, walking it is this file's.
+ *
+ * Absent means "whatever the request already asked for", which is the right
+ * default for a member declared without a model: the registry default was
+ * resolved into the request before it got here.
+ */
+export interface ProviderChainMember {
+	readonly provider: LLMProvider
+	readonly model?: string
+}
+
+export interface WithProviderFallbackOptions {
+	readonly log?: Logger
+}
+
+/**
+ * Failures that are a property of the REQUEST rather than of the member serving
+ * it.
+ *
+ * This is the whole decision, stated once. A request fault reproduces
+ * identically on the next member, so falling over would spend a second
+ * provider's money to buy the same error. Everything else — a throttle, an
+ * outage, a rejected credential, a model this provider does not have, a stream
+ * that came back malformed — is a fact about the member, and the next member is
+ * worth asking.
+ *
+ * The three entries, and what each of them being here means:
+ *
+ * - `context_length_exceeded` — the run's own remedy is compaction, which sheds
+ *   history and asks again. Falling over instead would carry the same oversized
+ *   prompt to a provider that has not been given the chance to fit it. Note the
+ *   limit of that reasoning: a chain MAY pair a small window with a larger one,
+ *   and then a fallback genuinely could have succeeded. Compaction is still
+ *   preferred because it is cheaper and it keeps the operator on the provider
+ *   they chose.
+ * - `invalid_request` — namzu built a request the provider rejected. The
+ *   counter-case is real and is recorded here rather than hidden: drivers
+ *   translate the same tool schema differently onto the wire, so a 400 about a
+ *   JSON Schema dialect (see `provider/errors.ts`) is provider-specific and
+ *   another member might accept it. Abort still wins, because the common case
+ *   is a request that is wrong everywhere, and spending the entire chain to
+ *   rediscover one defect is the worse failure.
+ * - `content_filter` — a refusal. No shipped driver reaches this through a
+ *   THROW today: the drivers that surface a filtered completion do so as
+ *   `finishReason: 'content_filter'`, which is a finished stream, not an error.
+ *   The input that makes this entry fire is a driver that throws instead — the
+ *   classifier maps a `content_policy_violation` structural code onto it, and
+ *   `ProviderError` is a public type a third-party driver constructs directly.
+ *   Named rather than omitted for that reason; see
+ *   `docs/conventions/a-check-that-cannot-fail.md` for why an unnameable one
+ *   would have been left out.
+ */
+const REQUEST_FAULT_CODES: ReadonlySet<string> = new Set([
+	'context_length_exceeded',
+	'invalid_request',
+	'content_filter',
+])
+
+/**
+ * Does this failure justify asking the next member?
+ *
+ * The classification is taken from `classifyProviderError` and not re-derived.
+ * A second classifier that disagreed with the first would be two answers to one
+ * question, and the retry decorator already stands on that same answer.
+ *
+ * `status === 404` is read ALONGSIDE the code, and it is not a second opinion —
+ * it is a second field of the one classification. A 404 reaches `not_found`
+ * only on the unclassified path (`codeFromStatus`). A driver that classified
+ * its own 404 into a `ProviderRequestError` gets `kind: 'bad_request'` from
+ * `classifyProviderHttpStatus`, which `KIND_TO_CODE` maps to
+ * `invalid_request` — a request fault, so the run would ABORT on a model the
+ * next member may well have. The status survives on both paths; the code does
+ * not, so the status is what this reads.
+ */
+function shouldFallOver(err: unknown, providerId: string): boolean {
+	const classified = classifyProviderError(err, providerId)
+	if (classified.status === 404) return true
+	return !REQUEST_FAULT_CODES.has(classified.code)
+}
+
+/**
+ * Has the consumer already been handed something a restart would duplicate?
+ *
+ * Deliberately NOT the retry decorator's rule, and the difference is the bug
+ * this function exists to prevent. Retry treats every chunk that is not
+ * error-only as output, which is correct INSIDE retry because each attempt
+ * starts with the flag cleared. Reused one level out it is wrong in the worst
+ * possible place: the inner decorator emits a backoff notice through this
+ * stream on its way to sleeping, that notice is not error-only, and a fallback
+ * reading it as output would refuse to advance for the rest of the turn — for
+ * the 429/5xx path, which is the main reason a chain is declared at all.
+ *
+ * So this asks the narrow question instead: did a chunk carry something the
+ * orchestrator turned into a visible event? `text_delta`, tool-input fragments
+ * and their per-tool boundary, reasoning blocks and citations all did.
+ * `usage`, `finishReason` and the two control notices did not.
+ */
+function isOutputChunk(chunk: StreamChunk): boolean {
+	if (chunk.retry !== undefined || chunk.fallback !== undefined) return false
+	const { content, toolCalls, toolCallEnd, reasoning, citation } = chunk.delta
+	return Boolean(
+		content ||
+			toolCalls?.length ||
+			toolCallEnd ||
+			reasoning !== undefined ||
+			citation !== undefined,
+	)
+}
+
+/**
+ * Wrap an ordered chain so a member that cannot serve is replaced in place.
+ *
+ * ## The cursor's lifetime IS the scope
+ *
+ * Once this decorator advances, every later request in its life goes to the new
+ * member; the chain never rewinds. That is deliberate and it is how "the
+ * primary is restored at each new user message" is implemented — by NOT
+ * implementing it. `query()` builds one of these per call and a host's call is
+ * its turn, so the cursor cannot outlive the turn because the object cannot.
+ * There is no reset to forget to call, and no way for a rate limit at 14:00 to
+ * leave an operator on a cheaper model at 17:00.
+ *
+ * Rewinding within the turn would be the alternative, and it is worse: the
+ * member that just failed would be re-asked on the next iteration of the same
+ * turn, which is a retry wearing a chain's clothes and which the inner
+ * decorator already declined to do.
+ *
+ * ## Each member is tried at most once per turn, and the whole chain is walked
+ *
+ * A chain of N members yields up to N attempts, not one. An operator who
+ * declares four members and is served only by the second on a bad day has been
+ * given three decorative entries — that is the declared-but-undriven defect
+ * this file exists to remove, and stopping after one step would reintroduce it
+ * at position 2 instead of position 1. When the last member fails, its error is
+ * thrown untouched and ordinary error handling takes over.
+ *
+ * ## Once output is out, there is no fallback
+ *
+ * Inherited from retry, for the same reason and not a weaker one: a stream that
+ * has emitted bytes cannot be restarted without duplicating them, and the
+ * consumer has already appended them to a message it is rendering. A mid-stream
+ * failure after output is surfaced, never swapped. See {@link isOutputChunk} —
+ * the definition of "output" is where this property is actually won or lost.
+ *
+ * ## Capabilities are the head's
+ *
+ * The getters below are transparent, so a run negotiates tools, vision and
+ * documents ONCE against `members[0]` and keeps that answer after a swap. This
+ * is a real limitation and it is why the host is expected to refuse a chain
+ * whose members disagree before ever building one (`@namzu/cli` does, and only
+ * runs a mismatched chain when the operator has said so explicitly). Taking the
+ * intersection here instead would cost the primary a capability on every run to
+ * guard against a failure that happens rarely.
+ */
+export function withProviderFallback(
+	members: readonly ProviderChainMember[],
+	options: WithProviderFallbackOptions = {},
+): LLMProvider {
+	const first = members[0]
+	if (!first) {
+		throw new Error('withProviderFallback needs at least one member')
+	}
+	// A one-member chain is the identity. Returning the provider itself rather
+	// than a wrapper that can never advance keeps the no-chain path byte-identical
+	// to what it was before this file existed.
+	if (members.length === 1) return first.provider
+
+	const log = options.log
+	let cursor = 0
+
+	async function* chatStream(params: ChatCompletionParams): AsyncIterable<StreamChunk> {
+		for (;;) {
+			const member = members[cursor]
+			// Unreachable while `cursor` only ever moves to an index this loop has
+			// bounds-checked below; kept because the alternative on a future edit is
+			// calling `chatStream` on undefined, which names neither the field nor
+			// the fix.
+			if (!member) throw new Error(`provider chain has no member at position ${cursor}`)
+
+			const request = member.model !== undefined ? { ...params, model: member.model } : params
+			let produced = false
+			try {
+				for await (const chunk of member.provider.chatStream(request)) {
+					if (isOutputChunk(chunk)) produced = true
+					yield chunk
+				}
+				return
+			} catch (err) {
+				// A Stop is control flow, not a provider failure. Without this the
+				// classifier — which has no concept of cancellation — would file an
+				// abort as some ordinary failure and the run would walk the entire
+				// chain re-issuing an already-cancelled request, one member at a
+				// time, instead of settling as `cancelled`. The retry decorator
+				// guards the same way and for the same reason.
+				if (isAbortError(err) || params.signal?.aborted) throw err
+
+				const next = cursor + 1
+				const to = members[next]
+				if (produced || !to || !shouldFallOver(err, member.provider.id)) {
+					log?.warn('Provider chain: not falling over', {
+						provider: member.provider.id,
+						position: cursor,
+						reason: produced
+							? 'stream already produced output — cannot restart without duplicating it'
+							: !to
+								? 'chain exhausted'
+								: 'the failure is a property of the request, not of the provider',
+					})
+					throw err
+				}
+
+				const classified = classifyProviderError(err, member.provider.id)
+				cursor = next
+				log?.warn('Provider chain: falling over', {
+					from: member.provider.id,
+					fromPosition: cursor - 1,
+					to: to.provider.id,
+					toPosition: cursor,
+					code: classified.code,
+					status: classified.status,
+				})
+
+				// In-band, exactly like the retry notice and for the same reason: the
+				// consumer is blocked inside this iterator, so the stream is the only
+				// channel that reaches it at the moment the swap happens rather than
+				// after the replacement request has already run.
+				yield {
+					id: '',
+					delta: {},
+					fallback: {
+						fromIndex: cursor - 1,
+						fromProviderId: member.provider.id,
+						...(member.model !== undefined ? { fromModel: member.model } : {}),
+						toIndex: cursor,
+						toProviderId: to.provider.id,
+						...(to.model !== undefined ? { toModel: to.model } : {}),
+						code: classified.code,
+						...(classified.status !== undefined ? { status: classified.status } : {}),
+						reason: classified.message,
+					},
+				}
+			}
+		}
+	}
+
+	// Transparent to capability negotiation and identity, like the retry
+	// decorator. The head's declarations are what a run is configured from; see
+	// the note on capabilities above for the limitation that carries.
+	return {
+		get id() {
+			return first.provider.id
+		},
+		get name() {
+			return first.provider.name
+		},
+		get capabilities() {
+			return first.provider.capabilities
+		},
+		chatStream,
+		...(first.provider.listModels ? { listModels: () => first.provider.listModels?.() } : {}),
+		...(first.provider.healthCheck ? { healthCheck: () => first.provider.healthCheck?.() } : {}),
+		...(first.provider.doctorCheck ? { doctorCheck: () => first.provider.doctorCheck?.() } : {}),
+	} as LLMProvider
+}

package/src/provider/index.ts

@@ -35,3 +35,5 @@ export {
 } from '../types/provider/errors.js'
 export { DEFAULT_PROVIDER_RETRY, withProviderRetry } from './retry.js'
 export type { ProviderRetryConfig, WithProviderRetryOptions } from './retry.js'
+export { withProviderFallback } from './fallback.js'
+export type { ProviderChainMember, WithProviderFallbackOptions } from './fallback.js'

package/src/public-runtime.ts

@@ -268,9 +268,15 @@ export {
 	registerMock,
 	resolveProviderCapabilities,
 	UnknownProviderError,
+	withProviderFallback,
 	withProviderRetry,
 } from './provider/index.js'
-export type { ProviderRetryConfig, WithProviderRetryOptions } from './provider/index.js'
+export type {
+	ProviderChainMember,
+	ProviderRetryConfig,
+	WithProviderFallbackOptions,
+	WithProviderRetryOptions,
+} from './provider/index.js'
 
 export {
 	assertIsolation,

package/src/run/reporter.ts

@@ -332,6 +332,26 @@ export function createRunReporter(parentLogger?: Logger): RunReporter {
 				})
 				break
 
+			case 'provider_fallback':
+				// `warn` for the same reason as a retry, and one stronger: the rest
+				// of this run is being served by a provider the caller did not pick.
+				log.warn(
+					`Provider ${event.fromProviderId} could not serve — continuing on ${event.toProviderId}`,
+					{
+						runId: event.runId,
+						iteration: event.iteration,
+						fromIndex: event.fromIndex,
+						fromProviderId: event.fromProviderId,
+						fromModel: event.fromModel,
+						toIndex: event.toIndex,
+						toProviderId: event.toProviderId,
+						toModel: event.toModel,
+						code: event.code,
+						status: event.status,
+					},
+				)
+				break
+
 			default: {
 				const _exhaustive: never = event
 				throw new Error(`Unhandled run event type: ${(_exhaustive as RunEvent).type}`)

package/src/runtime/query/index.ts

@@ -16,6 +16,7 @@ import type { CompactionConfig } from '../../config/runtime.js'
 import { TOOL_OUTPUT_DIR_NAME } from '../../constants/tools/index.js'
 import { EmergencySaveManager } from '../../manager/run/emergency.js'
 import { resolveProviderCapabilities } from '../../provider/capabilities.js'
+import { type ProviderChainMember, withProviderFallback } from '../../provider/fallback.js'
 import { type ProviderRetryConfig, withProviderRetry } from '../../provider/retry.js'
 import type { PathBuilder } from '../../session/workspace/path-builder.js'
 import {
@@ -120,6 +121,23 @@ export interface QueryParams {
 	 */
 	retry?: Partial<ProviderRetryConfig> | false
 
+	/**
+	 * Members to fall over to, in order, when {@link provider} cannot serve.
+	 *
+	 * Absent means what it always meant: one provider, no failover. Each member
+	 * is tried at most once per call and the chain never rewinds, so the scope
+	 * of a swap is this `query()` — for a host whose call is one user turn, that
+	 * is turn scope with no reset to forget. See `withProviderFallback`.
+	 *
+	 * Two things this does NOT do, both deliberate. Capabilities are negotiated
+	 * once against {@link provider}, so a member that declares less will be sent
+	 * a request shaped for the head — refuse a disagreeing chain before you
+	 * build one. And a fallback loses the prompt cache: the replacement provider
+	 * has never seen this conversation, so the turn re-reads its whole context
+	 * at full price.
+	 */
+	fallbackProviders?: readonly ProviderChainMember[]
+
 	/**
 	 * Install process-level crash handlers that dump this run's state to
 	 * `<runDir>/../emergency/<runId>.json` on SIGINT, SIGTERM or an
@@ -472,6 +490,46 @@ export interface QueryParams {
 	strictCapabilities?: boolean
 }
 
+/**
+ * Refuse to price a run whose tokens two differently-priced members may produce.
+ *
+ * `RunPersistence` holds ONE {@link ModelPricing} table and applies it to every
+ * accumulation regardless of which model produced the tokens. Across a swap that
+ * makes `costInfo.totalCost` wrong by an unbounded margin, and silently — the
+ * number keeps the shape of an answer. `CostInfo` cannot express the truth
+ * either: it carries `inputCostPer1M` / `outputCostPer1M`, and there is no
+ * honest value for those once a total spans two rate cards.
+ *
+ * So the total is refused rather than blended. Naming what that costs is part
+ * of the refusal, because the caller loses `costLimitUsd` with it: the guard
+ * enforces that limit from this same accumulated total, and a limit enforced
+ * with the wrong rate card stops a run early or late by the same unbounded
+ * margin. A budget that is quietly wrong is worse than a budget that is
+ * declined.
+ *
+ * Reachable, not decorative: a host that passes `pricing` and declares a chain
+ * hits it on the first call. It costs `@namzu/cli` nothing, which passes no
+ * pricing at all — its `/cost` already reports that the provider gave no price.
+ *
+ * The way out is per-member pricing, which needs a `CostInfo` that can sum over
+ * heterogeneous rates. That is a public-type change and it is not this one.
+ */
+function assertCostIsAttributable(
+	chain: readonly ProviderChainMember[],
+	pricing: ModelPricing | undefined,
+): void {
+	if (pricing === undefined || chain.length < 2) return
+	throw new NamzuError({
+		code: 'invalid_config',
+		message:
+			`A provider chain of ${chain.length} members was declared together with a single pricing table. ` +
+			'One table cannot price two members, so the run would report a total that is wrong by an unbounded ' +
+			'margin — and `runConfig.costLimitUsd` would be enforced against that same wrong total. ' +
+			'Either drop `pricing` (usage is still reported per model in the run) or declare one member.',
+		details: { chainLength: chain.length },
+	})
+}
+
 export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run> {
 	// Boot-time filesystem migration (session-hierarchy.md §13.4.1). First
 	// call per process per root actually runs; subsequent calls short-circuit
@@ -489,10 +547,29 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 	// of its warns behind `options.log`, and this is its only production
 	// call site — so without it the "failed, retrying" and "failed, giving
 	// up" lines were dead code and a backoff left no trace anywhere.
-	const resilientProvider =
+	//
+	// With a chain declared, the same sentence holds one level out: retry is
+	// applied per MEMBER and the fallback decorator wraps the result, so the
+	// composition is `fallback(retry(m0), retry(m1), …)`. That order is not a
+	// preference. Assembled the other way round — which is what a host gets if
+	// it wraps its own chain and hands the result in, because this function
+	// would then wrap THAT in retry — an exhausted chain gets restarted from
+	// the head by the outer loop and a throttle on the last member is counted
+	// by two budgets. Building it here is what makes the order unspellable
+	// wrong.
+	const chain: readonly ProviderChainMember[] = [
+		{ provider: params.provider },
+		...(params.fallbackProviders ?? []),
+	]
+	assertCostIsAttributable(chain, params.pricing)
+	const withRetry = (provider: LLMProvider): LLMProvider =>
 		params.retry === false
-			? params.provider
-			: withProviderRetry(params.provider, { config: params.retry, log: getRootLogger() })
+			? provider
+			: withProviderRetry(provider, { config: params.retry, log: getRootLogger() })
+	const resilientProvider = withProviderFallback(
+		chain.map((member) => ({ ...member, provider: withRetry(member.provider) })),
+		{ log: getRootLogger() },
+	)
 
 	const ctx = RunContextFactory.build({
 		agentId: params.agentId,

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

@@ -258,6 +258,32 @@ export async function* streamProviderTurn(
 				continue
 			}
 
+			// A chain swap, not output, and handled beside the retry notice
+			// because it is the same kind of thing: a fact about HOW the answer
+			// is being produced, arriving on the only channel open while the
+			// consumer is blocked inside the provider's iterator. It carries no
+			// delta, so nothing below applies to it either.
+			if (chunk.fallback) {
+				await emitEvent({
+					type: 'provider_fallback',
+					runId,
+					iteration,
+					fromIndex: chunk.fallback.fromIndex,
+					fromProviderId: chunk.fallback.fromProviderId,
+					...(chunk.fallback.fromModel !== undefined
+						? { fromModel: chunk.fallback.fromModel }
+						: {}),
+					toIndex: chunk.fallback.toIndex,
+					toProviderId: chunk.fallback.toProviderId,
+					...(chunk.fallback.toModel !== undefined ? { toModel: chunk.fallback.toModel } : {}),
+					code: chunk.fallback.code,
+					...(chunk.fallback.status !== undefined ? { status: chunk.fallback.status } : {}),
+					reason: chunk.fallback.reason,
+				})
+				yield* drainPending()
+				continue
+			}
+
 			if (chunk.error) {
 				streamError = chunk.error
 				break

package/src/types/provider/stream.ts

@@ -81,6 +81,18 @@ export interface StreamChunk {
 	 * output.
 	 */
 	retry?: ProviderRetryNotice
+
+	/**
+	 * The call failed and a different member of the provider chain is taking
+	 * over from here.
+	 *
+	 * Emitted by the fallback decorator, never by a driver, and it rides the
+	 * stream for the reason {@link retry} does. Like a retry notice it carries
+	 * no delta and must not be treated as output — and that distinction is
+	 * load-bearing twice over, because the fallback decorator reads these
+	 * chunks too when deciding whether output has already gone out.
+	 */
+	fallback?: ProviderFallbackNotice
 }
 
 /** See {@link StreamChunk.retry}. */
@@ -96,3 +108,28 @@ export interface ProviderRetryNotice {
 	/** The delay came from the server's own `Retry-After`, not backoff. */
 	readonly serverDirected: boolean
 }
+
+/**
+ * See {@link StreamChunk.fallback}.
+ *
+ * Both members are named, not just the new one. Naming only the replacement
+ * does not tell an operator which of their declared members went down, and on a
+ * chain of four that is the only fact they can act on.
+ *
+ * The positions are 0-based indices into the chain as the host declared it, so
+ * a surface can name a member the way its own configuration does rather than
+ * inventing a second numbering.
+ */
+export interface ProviderFallbackNotice {
+	readonly fromIndex: number
+	readonly fromProviderId: string
+	readonly fromModel?: string
+	readonly toIndex: number
+	readonly toProviderId: string
+	readonly toModel?: string
+	/** Classified failure code, as `classifyProviderError` reports it. */
+	readonly code: string
+	readonly status?: number
+	/** The classified failure's own sentence, already redacted at its source. */
+	readonly reason: string
+}

package/src/types/run/events.ts

@@ -186,6 +186,35 @@ type CoreRunEvent =
 			/** The delay came from the server's own `Retry-After`. */
 			serverDirected: boolean
 	  }
+	/**
+	 * A member of the provider chain could not serve, and a later member has
+	 * taken over. The run continues from where it stopped.
+	 *
+	 * This event is the feature's honesty. A chain that swapped silently would
+	 * produce a run that succeeded while quietly not doing what the operator
+	 * asked — served by a provider they did not choose, at a price and a
+	 * quality they did not agree to, with nothing in the transcript saying so.
+	 * A host is expected to SHOW this, not log it.
+	 *
+	 * Emitted at the moment of the swap, before the replacement request runs.
+	 */
+	| {
+			type: 'provider_fallback'
+			runId: RunId
+			iteration: number
+			/** 0-based position in the chain, as the host declared it. */
+			fromIndex: number
+			fromProviderId: string
+			fromModel?: string
+			toIndex: number
+			toProviderId: string
+			toModel?: string
+			/** Classified failure code, as the boundary classifier reports it. */
+			code: string
+			status?: number
+			/** The classified failure's own sentence. */
+			reason: string
+	  }
 	| {
 			type: 'tool_completed'
 			runId: RunId

package/src/utils/frontmatter.ts

@@ -16,19 +16,24 @@
  * half-understands YAML produces a value that passes validation and means
  * nothing.
  *
- * **Known gap, stated rather than implied.** The refusal is not yet total. A
- * *block* sequence
+ * That refusal is now total for lists. A *block* sequence
  *
  * ```yaml
  * allowed-tools:
  *   - Read
  * ```
  *
- * is silently dropped — its lines carry no `:` and are skipped — while the
- * flow form `[Read, Grep]` throws. Both readers this replaced behaved that
- * way, so it is inherited rather than introduced, but it contradicts
- * `docs/conventions/refuse-do-not-degrade.md` and is tracked as a follow-up.
- * Do not read the paragraph above as a guarantee it does not make.
+ * used to be silently dropped — its lines carry no `:` and were skipped, so the
+ * key came back **absent** — while the flow form `[Read, Grep]` threw. One
+ * spelling of a list was a hard error and the other was silence, and the silent
+ * one is the shape an author actually writes, because the block form is the
+ * natural YAML for a list.
+ *
+ * It matters most for a key like `allowed-tools`: a skill that asked for `Bash`
+ * and silently did not get it is indistinguishable from one that never asked,
+ * which is a capability quietly not granted rather than a formatting nicety.
+ * Both readers this replaced behaved that way, so it was inherited rather than
+ * introduced; it is now refused, naming the key.
  *
  * **Vocabulary belongs to the caller.** This returns the parsed map; it does
  * not know what a skill needs or what a command needs, and it validates no
@@ -176,6 +181,26 @@ export function parseFrontmatter(raw: string, source: string): ParsedFrontmatter
 
 		if (/^\s/.test(line)) {
 			if (!currentKey) continue
+
+			// A block sequence item. Refused, not skipped.
+			//
+			// These lines carry no `:`, so the `continue` below used to drop them
+			// and the key — having no scalar value and no mapping entries — came
+			// back ABSENT. The flow form `[Read, Grep]` already threw, so one
+			// spelling of a list was a hard error and the other was silence.
+			//
+			// The block form is the more natural YAML for a list, which is what
+			// made this worth closing: `allowed-tools` is a list, so this is the
+			// shape an author actually writes, and a skill that asked for `Bash`
+			// and silently did not get it is indistinguishable from one that never
+			// asked. A capability quietly not granted is the worst thing this
+			// reader can produce.
+			if (/^\s*-\s/.test(line)) {
+				throw new Error(
+					`${source}: "${currentKey}" uses a block sequence (a "- " list), which this reader does not support. Write it as a single-line value instead. Refusing rather than reading "${currentKey}" as absent, which is what silently dropping the list would mean.`,
+				)
+			}
+
 			const colonIdx = line.indexOf(':')
 			if (colonIdx === -1) continue
 			const key = line.slice(0, colonIdx).trim()