@joshuafolkken/kit 1.1471.0 → 1.1514.0

package/prompts/review.md

@@ -48,8 +48,7 @@ review, its severity tests and the round cap are unchanged.
 Run `pnpm josh review:brief --level-only` and use what it prints — `low` or `medium`, from the changed
 paths only, never "this one is small". `--staged` classifies the staged diff, `--json` adds the reason;
 inside a workflow `pnpm josh review:brief` prints the level on its first line. `low` gets 1 round,
-`medium` up to 2. Derivation (inert paths, documentation at `medium`):
-`docs/maintainers/review-history.md` → "The level is decided from the changed paths".
+`medium` up to 2. A diff that touches documentation is not inert: it stays at `medium`.
 
 ```bash
 pnpm josh review:brief --level-only            # the branch diff
@@ -94,8 +93,7 @@ deferred. Without the flag, and on any uncertainty (a missing round-1 snapshot i
   as code).
 
 One path outside that set makes it `required` — `.claude/**`, `CLAUDE.md`, a test, configuration, a
-code line, or a source file whose comment-free text cannot be read. Why: `docs/maintainers/review-history.md`
-→ "The two skip arms".
+code line, or a source file whose comment-free text cannot be read.
 
 Record a skipped round on the Issue:
 
@@ -129,7 +127,8 @@ Findings that reduce to one root judgement are filed as one Issue with a section
 
 Branch 2 only:
 
-- File a follow-up Issue referencing the current one; the current Issue completes.
+- File a follow-up Issue whose `parent: #N` line names the current one — a mention in its background
+  is not read by `epic:bundle`; the current Issue completes.
 - An Issue in no epic is never offered by `epic:next`, so filing continues to the epic. Run these steps
   inside the CI wait: in `fullrun` / `backlogrun` after `pnpm josh git -y` and before
   `pnpm josh followup`; in `halfrun` or a standalone pre-commit self-review as soon as the disposition

package/prompts/testing-guide.md

@@ -50,7 +50,7 @@ Req N: ...
 | Component / browser | `*.svelte.test.ts`       | browser/component vitest project |
 | E2E                 | `src/routes/**/*.e2e.ts` | Playwright                       |
 
-- **Never `*.spec.ts`** — lint-enforced by `eslint/rules/test-filename.js` (wired into `eslint/base.js`) for every JS/TS extension; rationale: `docs/maintainers/testing-guide-history.md` → "Why the `*.spec.*` ban is a lint rule".
+- **Never `*.spec.ts`** — lint-enforced by `eslint/rules/test-filename.js` (wired into `eslint/base.js`) for every JS/TS extension.
 - **Keep the `.svelte.` infix** on component/browser tests: `*.svelte.test.ts` matches the browser project (`include: src/**/*.svelte.{test,spec}.{js,ts}`), plain `*.test.ts` the node project (`include: src/**/*.{test,spec}.{js,ts}`); dropping it silently moves the file to the wrong project.
 - **Colocate** each test beside its code (`foo.test.ts` next to `foo.ts`); no top-level `tests/` (lint-enforced by the same rule). E2E specs go under `src/routes/**` — enforced by review only, since `playwright.config.ts` `testMatch: '**/*.e2e.{ts,js}'` runs them anywhere.
 
@@ -148,7 +148,7 @@ Reset module state at the start of each test (`reset_praise_audio_index()` in `s
 
 ## 6. Closing the E2E gate without a human run
 
-No human E2E run closes the gate, and nothing a red local run stopped is let through (`docs/maintainers/testing-guide-history.md`).
+No human E2E run closes the gate, and nothing a red local run stopped is let through.
 
 ### Which result closes the gate
 

package/scripts/agent/agent-argv.ts

@@ -4,6 +4,7 @@ import {
 	type AgentEnvironment,
 	type AgentProfile,
 	type AgentRole,
+	type ProfileResult,
 } from './agent-role-profile'
 import { claude_agent_argv } from './claude-agent-argv'
 import { codex_agent_argv } from './codex-agent-argv'
@@ -11,6 +12,8 @@ import { codex_agent_argv } from './codex-agent-argv'
 interface AgentArgv {
 	command: string
 	args: ReadonlyArray<string>
+	// The invocation is the last element, so `detached-launch.ts` lets that one break lines.
+	ends_with_prompt: true
 }
 
 type AgentArgvResult =
@@ -112,22 +115,35 @@ function resume_argv(
 		: with_profile_in(invocation, resolved.profile, cwd)
 }
 
+function profiled_in(invocation: string, resolved: ProfileResult, cwd: string): AgentArgvResult {
+	return resolved.kind === 'rejected'
+		? resolved
+		: with_profile_in(invocation, resolved.profile, cwd)
+}
+
 function resolve_in(
 	invocation: string,
 	role: AgentRole,
 	cwd: string,
 	environment: AgentEnvironment = process.env,
 ): AgentArgvResult {
-	const resolved = agent_role_profile.resolve(role, environment)
+	return profiled_in(invocation, agent_role_profile.resolve(role, environment), cwd)
+}
 
-	return resolved.kind === 'rejected'
-		? resolved
-		: with_profile_in(invocation, resolved.profile, cwd)
+// The reviewer for one review round, so a verification pass runs on its own profile.
+function review_in(
+	invocation: string,
+	round: number,
+	cwd: string,
+	environment: AgentEnvironment = process.env,
+): AgentArgvResult {
+	return profiled_in(invocation, agent_role_profile.resolve_review(round, environment), cwd)
 }
 
 const agent_argv = {
 	resolve,
 	resolve_in,
+	review_in,
 	resume_argv,
 	with_profile,
 	with_profile_in,

package/scripts/agent/agent-role-profile.ts

@@ -1,11 +1,8 @@
 import { agent_session_environment } from '#scripts/josh/agent-session-environment'
 import { z } from 'zod'
+import { agent_safe_text } from './agent-safe-text'
 
-const FIRST_PRINTABLE_CODE = 0x20
-const DELETE_CODE = 0x7f
-const FIRST_CODE_POINT = 0
 const EMPTY_LENGTH = 0
-const MAX_VALUE_LENGTH = 4096
 
 const ROLE_SCHEMA = z.enum(['scheduler', 'worker', 'reviewer'])
 const PROVIDER_SCHEMA = z.enum(['anthropic', 'openai'])
@@ -32,6 +29,18 @@ type ProfileResult = { kind: 'profile'; profile: AgentProfile } | { kind: 'rejec
 type Rejected = Extract<ProfileResult, { kind: 'rejected' }>
 type EffortResult = Rejected | { kind: 'effort'; effort: AgentEffort }
 type ProviderResult = Rejected | { kind: 'provider'; provider: AgentProvider; is_default?: true }
+type OverrideField = 'model' | 'effort'
+
+interface Override {
+	key: string
+	value: string | undefined
+}
+
+// What a resolution is keyed on beyond the role: the run phase (effort) and the review round (profile).
+interface AgentStage {
+	phase?: string | undefined
+	round?: number
+}
 
 const SCHEDULER: AgentRole = 'scheduler'
 const WORKER: AgentRole = 'worker'
@@ -72,6 +81,22 @@ const OPENAI_PROFILES: Readonly<Record<AgentRole, AgentProfile>> = {
 
 const PROVIDER_PROFILES = { anthropic: DEFAULT_PROFILES, openai: OPENAI_PROFILES }
 
+// **The verification pass resolves a profile of its own** (joshuafolkken/kit#3926). A round after the
+// first only checks that the first round's findings were fixed, so its model and effort are set apart:
+// its own keys win, then the reviewer's, then its own default.
+const FIRST_REVIEW_ROUND = 1
+// Sonnet holds the verification pass by the eval criterion: on every `verification-fix-*` scenario its
+// pass/fail equals Opus's (100% agreement), and Opus passes all 4.
+const VERIFICATION_MODEL = 'claude-sonnet-5-5'
+const VERIFICATION_PROFILES: Readonly<Record<AgentProvider, AgentProfile>> = {
+	anthropic: { ...DEFAULT_PROFILES.reviewer, model: VERIFICATION_MODEL },
+	openai: OPENAI_PROFILES.reviewer,
+}
+const VERIFICATION_KEYS = {
+	model: 'JOSH_REVIEWER_VERIFICATION_MODEL',
+	effort: 'JOSH_REVIEWER_VERIFICATION_EFFORT',
+}
+
 // **Effort as a function of the run phase, not the role alone**. For the first
 // merge only the mechanical ship/bookkeeping region is lowered: the pre-gate resume drives the gate,
 // commit, PR and merge, applying fixes the gate has already named — work delegation.md calls the opposite
@@ -93,19 +118,7 @@ const ENV_KEYS: Readonly<Record<AgentRole, { model: string; effort: string }>> =
 
 const LEGACY_WORKER_KEYS = { model: 'JOSH_LANE_MODEL', effort: 'JOSH_LANE_EFFORT' }
 
-function is_control_character(character: string): boolean {
-	const code = character.codePointAt(FIRST_CODE_POINT) ?? FIRST_PRINTABLE_CODE
-
-	return code < FIRST_PRINTABLE_CODE || code === DELETE_CODE
-}
-
-function is_safe_value(value: string): boolean {
-	if (value.length === EMPTY_LENGTH || value.length > MAX_VALUE_LENGTH) return false
-
-	for (const character of value) if (is_control_character(character)) return false
-
-	return true
-}
+const { MAX_VALUE_LENGTH, is_safe_prompt, is_safe_value, printable } = agent_safe_text
 
 function trimmed(value: string | undefined): string | undefined {
 	const result = value?.trim()
@@ -113,44 +126,53 @@ function trimmed(value: string | undefined): string | undefined {
 	return result === undefined || result.length === EMPTY_LENGTH ? undefined : result
 }
 
-function override_value(
+function is_verification(role: AgentRole, round: number | undefined): boolean {
+	return role === REVIEWER && round !== undefined && round > FIRST_REVIEW_ROUND
+}
+
+// The keys an override is read from, first match wins: a worker falls back to its legacy lane keys, and
+// a verification round reads its own keys ahead of the reviewer's.
+function override_keys(
 	role: AgentRole,
-	field: 'model' | 'effort',
-	environment: AgentEnvironment,
-): { key: string; value: string | undefined } {
+	field: OverrideField,
+	round: number | undefined,
+): readonly [string, ...Array<string>] {
 	const key = ENV_KEYS[role][field]
-	const value = trimmed(environment[key])
-	if (value !== undefined) return { key, value }
-	if (role !== WORKER) return { key, value: undefined }
+	if (role === WORKER) return [key, LEGACY_WORKER_KEYS[field]]
 
-	const legacy = LEGACY_WORKER_KEYS[field]
-	const legacy_value = trimmed(environment[legacy])
+	return is_verification(role, round) ? [VERIFICATION_KEYS[field], key] : [key]
+}
 
-	return legacy_value === undefined
-		? { key, value: undefined }
-		: { key: legacy, value: legacy_value }
+function override_value(
+	role: AgentRole,
+	field: OverrideField,
+	environment: AgentEnvironment,
+	round?: number,
+): Override {
+	const keys = override_keys(role, field, round)
+	const key = keys.find((candidate) => trimmed(environment[candidate]) !== undefined)
+
+	return key === undefined
+		? { key: keys[0], value: undefined }
+		: { key, value: trimmed(environment[key]) }
 }
 
 function model_override(
 	role: AgentRole,
 	environment: AgentEnvironment,
 	provider: AgentProvider,
-): { key: string; value: string | undefined } {
-	const key = ENV_KEYS[role].model
-
+	round: number | undefined,
+): Override {
 	return provider === OPENAI_PROVIDER
-		? { key, value: undefined }
-		: override_value(role, 'model', environment)
+		? { key: ENV_KEYS[role].model, value: undefined }
+		: override_value(role, 'model', environment, round)
 }
 
 function rejection(key: string, value: string, expected: string): Rejected {
 	return { kind: 'rejected', note: `${key}=${value} ${expected}, so the agent was not started` }
 }
 
-function resolved_effort(
-	override: { key: string; value: string | undefined },
-	fallback: AgentEffort,
-): EffortResult {
+function resolved_effort(override: Override, fallback: AgentEffort): EffortResult {
 	const parsed = EFFORT_SCHEMA.safeParse(override.value ?? fallback)
 
 	return parsed.success
@@ -290,17 +312,27 @@ function with_phase_effort(
 	return { ...profile, effort: overridden_effort(profile, phase, environment) }
 }
 
-function resolve(
+function stage_defaults(
+	provider: AgentProvider,
 	role: AgentRole,
-	environment: AgentEnvironment = process.env,
-	phase?: string,
+	round: number | undefined,
+): AgentProfile {
+	return is_verification(role, round)
+		? VERIFICATION_PROFILES[provider]
+		: PROVIDER_PROFILES[provider][role]
+}
+
+function resolve_stage(
+	role: AgentRole,
+	environment: AgentEnvironment,
+	stage: AgentStage,
 ): ProfileResult {
 	const selected = resolve_provider(environment)
 	if (selected.kind === 'rejected') return selected
-	const defaults = PROVIDER_PROFILES[selected.provider][role]
-	const model = model_override(role, environment, selected.provider)
-	const effort = override_value(role, 'effort', environment)
-	const resolved = resolved_effort(effort, phase_effort(role, phase, defaults.effort))
+	const defaults = stage_defaults(selected.provider, role, stage.round)
+	const model = model_override(role, environment, selected.provider, stage.round)
+	const effort = override_value(role, 'effort', environment, stage.round)
+	const resolved = resolved_effort(effort, phase_effort(role, stage.phase, defaults.effort))
 
 	if (resolved.kind === 'rejected') return resolved
 
@@ -314,10 +346,29 @@ function resolve(
 	return validate(profile, model.key)
 }
 
+function resolve(
+	role: AgentRole,
+	environment: AgentEnvironment = process.env,
+	phase?: string,
+): ProfileResult {
+	return resolve_stage(role, environment, { phase })
+}
+
+// The reviewer for one review round: round 1 as `resolve(REVIEWER)` does, any later round the
+// verification pass's own profile.
+function resolve_review(round: number, environment: AgentEnvironment = process.env): ProfileResult {
+	return resolve_stage(REVIEWER, environment, { round })
+}
+
 function describe(profile: AgentProfile): string {
 	return `provider=${profile.provider} role=${profile.role} model=${profile.model} effort=${profile.effort}`
 }
 
+// The run-log line a review launch writes, so each round's model is on record beside its round.
+function describe_review(round: number, profile: AgentProfile): string {
+	return `review round ${String(round)} · ${describe(profile)}`
+}
+
 function parse(value: unknown): AgentProfile | undefined {
 	const parsed = PROFILE_SCHEMA.safeParse(value)
 
@@ -335,15 +386,20 @@ const agent_role_profile = {
 	PROFILE_SCHEMA,
 	REVIEWER,
 	SCHEDULER,
+	VERIFICATION_PROFILES,
 	WORKER,
 	default_notice,
 	describe,
+	describe_review,
 	handoff_environment,
 	has_completion_callback,
+	is_safe_prompt,
 	is_safe_value,
 	parse,
+	printable,
 	resolve,
 	resolve_provider,
+	resolve_review,
 	warn_of_default,
 	with_phase_effort,
 }

package/scripts/agent/agent-safe-text.ts

@@ -0,0 +1,60 @@
+// The text an agent launch may carry: a model id, an effort and a prompt, refused when empty, over
+// length or carrying a control character, so nothing a value holds can inject a further argument.
+
+const FIRST_PRINTABLE_CODE = 0x20
+const DELETE_CODE = 0x7f
+const FIRST_CODE_POINT = 0
+const EMPTY_LENGTH = 0
+const MAX_VALUE_LENGTH = 4096
+const LINE_FEED = '\n'
+const SPACE = ' '
+
+function is_control_character(character: string): boolean {
+	const code = character.codePointAt(FIRST_CODE_POINT) ?? FIRST_PRINTABLE_CODE
+
+	return code < FIRST_PRINTABLE_CODE || code === DELETE_CODE
+}
+
+function is_line_feed(character: string): boolean {
+	return character === LINE_FEED
+}
+
+function is_never_allowed(): boolean {
+	return false
+}
+
+function is_refused(character: string, is_allowed: (character: string) => boolean): boolean {
+	return is_control_character(character) && !is_allowed(character)
+}
+
+function is_safe_text(value: string, is_allowed: (character: string) => boolean): boolean {
+	if (value.length === EMPTY_LENGTH || value.length > MAX_VALUE_LENGTH) return false
+
+	for (const character of value) if (is_refused(character, is_allowed)) return false
+
+	return true
+}
+
+function is_safe_value(value: string): boolean {
+	return is_safe_text(value, is_never_allowed)
+}
+
+// **An agent's prompt is the one value a line break belongs in.** A ship-stop prompt carries the failed
+// output's lines (joshuafolkken/kit#3964); every other control character is refused as in any value.
+function is_safe_prompt(value: string): boolean {
+	return is_safe_text(value, is_line_feed)
+}
+
+function printable_character(character: string): string {
+	return is_refused(character, is_line_feed) ? SPACE : character
+}
+
+// Command output made fit for a prompt: every control character but a line break becomes a space, so
+// the text passes `is_safe_prompt` whatever the command printed.
+function printable(text: string): string {
+	return Array.from(text, printable_character).join('')
+}
+
+const agent_safe_text = { MAX_VALUE_LENGTH, is_safe_prompt, is_safe_value, printable }
+
+export { agent_safe_text }

package/scripts/agent/claude-agent-argv.ts

@@ -6,6 +6,7 @@ import {
 	type AgentProfile,
 	type AgentRole,
 } from './agent-role-profile'
+import { lane_instructions } from './lane-instructions'
 
 const AGENT_COMMAND = 'claude'
 // **The permission mode is passed, not left to the checkout's `.claude/settings.json`.** Claude Code
@@ -63,6 +64,7 @@ const PROJECT_MCP_FILE = '.mcp.json'
 interface ClaudeArgv {
 	command: string
 	args: ReadonlyArray<string>
+	ends_with_prompt: true
 }
 
 type ClaudeArgvResult =
@@ -87,6 +89,14 @@ function tool_flags(cwd: string = process.cwd()): ReadonlyArray<string> {
 	return [TOOLS_FLAG, LAUNCHED_TOOLS.join(','), ...mcp_flags]
 }
 
+// **A lane child and a review session start from the lane instruction set** (`lane-instructions.ts`);
+// the scheduler keeps `CLAUDE.md`, because it is the one that stops and asks a person.
+function instruction_flags(profile: AgentProfile, cwd?: string): ReadonlyArray<string> {
+	if (profile.role === agent_role_profile.SCHEDULER) return []
+
+	return lane_instructions.flags(cwd)
+}
+
 function build(
 	invocation: string,
 	profile: AgentProfile,
@@ -98,6 +108,7 @@ function build(
 		args: [
 			...AGENT_FLAGS,
 			...tool_flags(cwd),
+			...instruction_flags(profile, cwd),
 			...session_id_flags(session_id),
 			MODEL_FLAG,
 			profile.model,
@@ -105,6 +116,7 @@ function build(
 			profile.effort,
 			invocation,
 		],
+		ends_with_prompt: true,
 	}
 }
 
@@ -121,6 +133,7 @@ function build_resume(
 		args: [
 			...AGENT_FLAGS,
 			...tool_flags(cwd),
+			...instruction_flags(profile, cwd),
 			RESUME_FLAG,
 			session_id,
 			MODEL_FLAG,
@@ -129,6 +142,7 @@ function build_resume(
 			profile.effort,
 			invocation,
 		],
+		ends_with_prompt: true,
 	}
 }
 

package/scripts/agent/codex-agent-argv.ts

@@ -19,6 +19,7 @@ const LEDGER_DIRECTORY = path.dirname(OBSERVATION_LEDGER_DIRECTORY)
 interface CodexArgv {
 	command: string
 	args: ReadonlyArray<string>
+	ends_with_prompt: true
 }
 
 function effort_config(profile: AgentProfile): string {
@@ -91,6 +92,7 @@ function build(invocation: string, profile: AgentProfile, cwd?: string): CodexAr
 			JSON_FLAG,
 			invocation,
 		],
+		ends_with_prompt: true,
 	}
 }
 

package/scripts/agent/lane-instructions.ts

@@ -0,0 +1,144 @@
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { cost_tokens } from '#scripts/cost-runtime/cost-tokens'
+import { document_section } from '#scripts/document/document-section'
+import { distributed_paths } from '#scripts/init/distributed-paths'
+import { find_package_directory } from '#scripts/josh/package-directory'
+import { stamp_file } from '#scripts/josh/stamp-file'
+
+interface LaneSet {
+	text: string
+	rules_path: string
+}
+
+// **A headless lane child or review session starts from the lane instruction set, not `CLAUDE.md`.**
+// `CLAUDE.md` carries rules only an interactive session can act on — consultation versus execution,
+// explicit workflow invocation, stop notifications — and every request re-reads it. The lane document
+// names the rules a lane does need by `CLAUDE.md` heading or bold label, and each `include` line is
+// expanded from the launch checkout's own `CLAUDE.md` here, so the rule text keeps one source (#3929).
+const LANE_DOCUMENT = 'prompts/collaboration-workflow/lane-instructions.md'
+const RULES_FILE = 'CLAUDE.md'
+// `AGENTS.md` only points at `CLAUDE.md`, and Claude Code loads it once `CLAUDE.md` is excluded.
+const POINTER_FILE = 'AGENTS.md'
+const INCLUDE_PATTERN = /^<!-- include: CLAUDE\.md → "(?<wanted>.+)" -->$/u
+const PROMPT_FILE_FLAG = '--append-system-prompt-file'
+const SETTINGS_FLAG = '--settings'
+const PROMPT_FILE_PREFIX = 'josh-lane-instructions-'
+const PROMPT_FILE_SUFFIX = '.md'
+const PACKAGE_DIRECTORY = find_package_directory(path.dirname(fileURLToPath(import.meta.url)))
+
+// An include that resolves to nothing is `undefined`, never an empty string, so a renamed heading
+// fails the whole composition rather than silently dropping a rule.
+function expand_line(line: string, rules: string): string | undefined {
+	const wanted = INCLUDE_PATTERN.exec(line)?.groups?.['wanted']
+
+	if (wanted === undefined) return line
+
+	return document_section.section(rules, wanted)?.text
+}
+
+function compose(lane_markdown: string, rules: string): string | undefined {
+	const expanded = lane_markdown.split('\n').map((line) => expand_line(line, rules))
+
+	if (expanded.includes(undefined)) return undefined
+
+	return expanded.join('\n')
+}
+
+// **Where the rules are: the checkout's `CLAUDE.md`, else the package copy it imports.** kit and a
+// consumer holding a full copy keep them in `CLAUDE.md`; a consumer written by `josh init` imports
+// them from the package, and its own `CLAUDE.md` — the bootstrap note and the project's additions —
+// stays loaded, because only the file the set was composed from is excluded.
+function rules_sources(cwd: string): ReadonlyArray<string> {
+	const imported = distributed_paths.CLAUDE_MD_IMPORT_LINE.replace(/^@/u, '')
+
+	return [path.join(cwd, RULES_FILE), path.join(cwd, imported)]
+}
+
+function composed_from(lane_markdown: string, rules_path: string): string | undefined {
+	const rules = document_section.read_optional(rules_path)
+
+	return rules === undefined ? undefined : compose(lane_markdown, rules)
+}
+
+function composed_set(cwd: string, package_directory: string): LaneSet | undefined {
+	const lane_markdown = document_section.read_optional(path.join(package_directory, LANE_DOCUMENT))
+
+	if (lane_markdown === undefined) return undefined
+
+	for (const rules_path of rules_sources(cwd)) {
+		const text = composed_from(lane_markdown, rules_path)
+
+		if (text !== undefined) return { text, rules_path }
+	}
+
+	return undefined
+}
+
+function composed_in(
+	cwd: string,
+	package_directory: string = PACKAGE_DIRECTORY,
+): string | undefined {
+	return composed_set(cwd, package_directory)?.text
+}
+
+// Named by its content and this account, so concurrent launches of the same text share one file and a
+// changed `CLAUDE.md` never reuses a stale one. The name is predictable in a temp directory other
+// accounts may write to, so an existing file is reused only when it is this account's own regular file
+// holding exactly this text; anything else is replaced through `stamp_file`, which refuses another
+// account's file and renames a new one into place whole. A file rather than the text itself, because
+// the launcher refuses a line break in any argv element but the prompt.
+function written(text: string): string | undefined {
+	const file_path = stamp_file.stamp_path(PROMPT_FILE_PREFIX, text, PROMPT_FILE_SUFFIX)
+
+	if (stamp_file.read_stamp_text(file_path) === text) return file_path
+
+	try {
+		return stamp_file.replace_text_stamp(file_path, text)
+	} catch {
+		return undefined
+	}
+}
+
+function excluded_settings(rules_path: string, cwd: string): string {
+	return JSON.stringify({ claudeMdExcludes: [rules_path, path.join(cwd, POINTER_FILE)] })
+}
+
+// No flags when the set cannot be composed or safely written: the child then loads `CLAUDE.md` as
+// before, which costs tokens but never loses a rule.
+function flags(cwd: string = process.cwd()): ReadonlyArray<string> {
+	const set = composed_set(cwd, PACKAGE_DIRECTORY)
+	const prompt_file = set === undefined ? undefined : written(set.text)
+
+	if (set === undefined || prompt_file === undefined) return []
+
+	return [PROMPT_FILE_FLAG, prompt_file, SETTINGS_FLAG, excluded_settings(set.rules_path, cwd)]
+}
+
+function tokens_of(text: string): string {
+	return cost_tokens.estimate(text).toLocaleString('en-US')
+}
+
+// `read:set lane-child`'s resident line: what each lane request carries in place of the rules file.
+function rules_tokens(rules_path: string): string {
+	return tokens_of(document_section.read_optional(rules_path) ?? '')
+}
+
+function resident_line(cwd: string = process.cwd()): string {
+	const set = composed_set(cwd, PACKAGE_DIRECTORY)
+	const rules = rules_tokens(set?.rules_path ?? path.join(cwd, RULES_FILE))
+	const lane_tokens = set === undefined ? 'not composed' : `${tokens_of(set.text)} tok`
+
+	return `  resident: lane instructions ${lane_tokens} in place of ${RULES_FILE} ${rules} tok`
+}
+
+const lane_instructions = {
+	PROMPT_FILE_FLAG,
+	SETTINGS_FLAG,
+	compose,
+	composed_in,
+	flags,
+	resident_line,
+}
+
+export { lane_instructions }

package/scripts/backlog/backlog-budget.ts

@@ -42,7 +42,7 @@ const WATCH_VERDICT = 'watch'
 const STOP_VERDICT = 'stop'
 const TRIAGE_VERDICT = 'triage'
 
-// `run` — start what `backlog:next` offered. `watch` — sleep the polling interval and ask again,
+// `run` — start what `backlog:next` offered. `watch` — sleep the re-ask floor and ask again,
 // except while something of the run's own is in flight, where the wake is the progress watcher's exit
 // and the interval is only a floor (`docs/maintainers/backlogrun-driver.md` → "Waiting while
 // something is in flight").
@@ -87,7 +87,7 @@ interface BudgetDecision {
 }
 
 const BLOCKED_REASON =
-	'Everything opted in is blocked or already running, so waiting can still change the answer. Poll again at the polling interval.'
+	'Everything opted in is blocked or already running, so waiting can still change the answer. Ask again at the re-ask floor (60 s).'
 
 const TRIAGE_REASON =
 	'An opted-in candidate carries neither `run:solo` nor `run:lane`, so nothing starts until it is judged. Read each issue named above, record its order and one of the two labels with a comment, then ask again.'
@@ -121,7 +121,7 @@ function max_reached_reason(merged: number, max_issues: number): string {
 }
 
 function draining_reason(running: number, reason: string): string {
-	return `Start nothing more and poll until the running children merge (running: ${String(running)}). Then report and finish — ${reason}`
+	return `Start nothing more and wait on \`pnpm josh lane:await\` until the running children merge (running: ${String(running)}). Then report and finish — ${reason}`
 }
 
 function idle_expired_reason(answer: BacklogAnswer, idle_budget_ms: number): string {
@@ -140,7 +140,7 @@ function idle_watch_reason(answer: BacklogAnswer, left_ms: number): string {
 // **The watch runs down while they drain, and restarts at each one collected.** A collected child is
 // work, so it moves `active_at`; an ask that offered nothing never does.
 function running_watch_reason(answer: BacklogAnswer, running: number, left_ms: number): string {
-	return `${waiting_on(answer)} and the idle watch has about ${to_minutes(left_ms)} minutes left, with ${String(running)} still running. Keep the working tree until they merge and poll at the polling interval — the watch is running down meanwhile.`
+	return `${waiting_on(answer)} and the idle watch has about ${to_minutes(left_ms)} minutes left, with ${String(running)} still running. Keep the working tree and wait on \`pnpm josh lane:await\` until they merge — the watch is running down meanwhile.`
 }
 
 function watching_reason(input: BudgetInput, left_ms: number): string {

package/scripts/backlog/backlog-drive-named.ts

@@ -12,7 +12,7 @@ const { MERGE_TOKEN } = run_merge_token
 
 const NO_RETRIES = 0
 const FIRST = 0
-const TERMINAL_OUTCOMES: ReadonlySet<string> = new Set(['merged', 'parked', 'split'])
+const TERMINAL_OUTCOMES: ReadonlySet<string> = new Set(['merged', 'parked', 'split', 'withdrawn'])
 
 // The skip follows the declared order alone: an issue `run:add` put in was
 // asked for on its own, so its failure skips nothing and a declared failure does not skip it.