@joshuafolkken/kit 1.1455.0 → 1.1514.0

package/prompts/testing-guide.md

@@ -2,12 +2,10 @@
 
 ## 0. Per-Requirement Test Coverage (MANDATORY)
 
-Before writing any implementation code, **list every requirement from the user's request and assign a test to each one**. This step is non-negotiable.
+Before any implementation code, **list every requirement from the user's request and assign a test to each one**.
 
 ### Planning template
 
-For a user request with N requirements, enumerate each one before touching any source files:
-
 ```text
 Req 1: "Label chip shown immediately"
   → E2E: open editor, type new label, press Enter → chip visible without blurring
@@ -21,19 +19,17 @@ Req N: ...
 
 ### Rules
 
-- **Every user-facing behavior change** (UI interaction, keyboard shortcut, visible state change) must have a corresponding E2E test.
-- **Every logic/utility change** (pure functions, filters, transforms) must have a unit test. A bug fix takes a regression test; a refactor takes tests pinning the existing behavior BEFORE the change (`prompts/refactoring.md`).
+- User-facing behavior change (UI interaction, keyboard shortcut, visible state) → an E2E test.
+- Logic/utility change (pure functions, filters, transforms) → a unit test. Bug fix → a regression test; refactor → tests pinning the existing behavior BEFORE the change (`prompts/refactoring.md`).
 - **Non-runtime updates (pre-approved manual-only exception):** a change touching no executable runtime code path — docs, non-executable config, editor/IDE files, cosmetic asset swaps with no selector/path change — may be verified by hand; declare it in Step 0 with the reason. The mechanically exempt (`*.md`, `.editorconfig`, `.idea/**`, `.vscode/**`, `prompts/**`) need no declaration. A runtime change whose test is infeasible needs the reason and user approval.
-- **basic で kit がテストできない言語だけの変更:** `package.json` に `josh.profile: basic`（改名前の `static` も同じ）が記録され、変更が HTML/CSS や Lua などのソースだけなら自動テストは不要。HTML/CSS はブラウザーで対象ページを開き、想定する画面幅でレイアウト・リンク・HTML 内の操作を確認する。そのほかのソースは変更した処理を実際に動かす。どちらも結果を記録する。同じ変更に JavaScript または TypeScript のファイルが含まれれば自動テストを行う。
-- If a test is genuinely infeasible (e.g., native OS date-picker popup cannot be driven by Playwright), write a comment in the test file explaining why and test the closest observable behavior instead (e.g., that the editor remains open after the `change` event fires).
-- Do **not** report a requirement as done if its test is missing.
+- **basic で kit がテストできない言語だけの変更:** `package.json` に `josh.profile: basic`（改名前の `static` も同じ）があり、変更が HTML/CSS や Lua などのソースだけなら自動テストは不要。HTML/CSS はブラウザーで対象ページを開き、想定する画面幅でレイアウト・リンク・HTML 内の操作を確認する。そのほかのソースは変更した処理を実際に動かす。どちらも結果を記録する。JavaScript または TypeScript のファイルを含む変更は自動テストを行う。
+- Test infeasible (e.g., a native OS date-picker Playwright cannot drive) → comment why in the test file and test the closest observable behavior (e.g., the editor stays open after `change`).
+- A requirement without its test is not done.
 
 ### Verification checklist (add to the completion gate)
 
-- [ ] Count requirements in the user's request.
-- [ ] Count tests added/updated for those requirements.
-- [ ] The two counts match (or each gap is documented as infeasible with a comment).
-- [ ] **UI changes only:** a screenshot of the affected screen was captured and visually confirmed before reporting completion (passing tests are not proof the UI looks correct — see the **UI verification (screenshot)** rule in the completion gate). If a screenshot is impossible in this environment, that is stated and the user is asked to verify visually.
+- [ ] Requirement count equals the count of tests added/updated (each gap documented as infeasible).
+- [ ] UI changes: a screenshot of the affected screen was checked (`CLAUDE.md` → UI verification); if impossible here, say so and ask the user to check.
 
 ---
 
@@ -44,21 +40,19 @@ Req N: ...
 | `src/routes/` pages, UI components with user interaction          | E2E (Playwright)          |
 | `.ts`/`.js` utilities, `src/lib/server/`, display-only components | Unit/Integration (Vitest) |
 
-**The type is decided from the path, not by asking.** A change under `src/routes/` takes E2E; every other runtime path takes Unit — a component with interaction is reached through the route that renders it, and that route is under `src/routes/`. `pnpm josh test:declared` prints the type each untested runtime file calls for on its `required` detail line, so the choice never becomes a stop.
+**The type is decided from the path, not by asking**: under `src/routes/` → E2E; every other runtime path → Unit (an interactive component is reached through its route). `pnpm josh test:declared` prints the type per untested runtime file on its `required` line.
 
 ### Test file naming & placement (one unambiguous rule)
 
-There is exactly **one** convention for every test file — never choose between two. The rules below are mandatory; some are config-enforced (a violating file runs under the wrong vitest project or not at all), others are enforced by convention/review — each rule states which.
-
 | Test kind           | Required filename        | Routed to                        |
 | ------------------- | ------------------------ | -------------------------------- |
 | Unit / integration  | `*.test.ts`              | node/unit vitest project         |
 | Component / browser | `*.svelte.test.ts`       | browser/component vitest project |
 | E2E                 | `src/routes/**/*.e2e.ts` | Playwright                       |
 
-- **Use `*.test.ts` — never `*.spec.ts`.** **Lint-enforced** by `eslint/rules/test-filename.js` (wired into `eslint/base.js`) for every JS/TS extension; how the ban is wired and why: `docs/maintainers/testing-guide-history.md` → "Why the `*.spec.*` ban is a lint rule".
-- **The `.svelte.` infix is required for component/browser tests and must be preserved.** `*.svelte.test.ts` routes the file to the **browser/component** vitest project (`include: src/**/*.svelte.{test,spec}.{js,ts}`); plain `*.test.ts` routes to the **node/unit** project (`include: src/**/*.{test,spec}.{js,ts}`). Renaming `Foo.svelte.test.ts` → `Foo.test.ts` silently moves it to the wrong project — do not drop the `.svelte.` infix.
-- **Colocate every test next to the code it exercises.** A top-level `tests/` directory is **not used** — place `foo.test.ts` beside `foo.ts`, and E2E specs under the relevant `src/routes/**` path. The top-level `tests/` ban is **lint-enforced** by the same rule (`eslint/rules/test-filename.js`). Note: `playwright.config.ts` discovers E2E via `testMatch: '**/*.e2e.{ts,js}'`, so an `*.e2e.ts` placed outside `src/routes/**` would still run — that specific `src/routes/**` placement is enforced by **convention/review, not config**, and must be upheld manually.
+- **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.
 
 ---
 
@@ -72,156 +66,111 @@ There is exactly **one** convention for every test file — never choose between
 ### Test Functions
 
 - Outside `describe`: `test`; inside `describe`: `it`
-- Use `describe` only when grouping multiple tests is necessary
+- `describe` only when grouping multiple tests
 
 ### Parameterized Tests
 
 - Playwright: `for` loop; Vitest: `test.each` / `it.each`
-- Test cases: define as `cases` or `*_cases` array at file top (outside test functions)
+- Cases: a `cases` or `*_cases` array at file top, outside test functions
 
 ### Constants
 
-- All magic numbers/strings except `0`, `1`, `-1` must be `UPPER_SNAKE_CASE` constants
-- Place after imports at file top
+- Magic numbers/strings except `0`, `1`, `-1` → `UPPER_SNAKE_CASE` constants after the imports
 
 ### Imports
 
-- Always include `.js` extension: `import { foo } from './bar.js'`
+- Always the `.js` extension: `import { foo } from './bar.js'`
 - Type imports: `import { type Foo } from '...'`
 
 ### Playwright
 
-- Element selection: `page.getByTestId('id')` — add `data-testid` to implementation files
+- Select with `page.getByTestId('id')`; add `data-testid` to the implementation
 - Test functions always `async`
-- **Project split:** `playwright.config.ts` defines **`e2e-guest`** (no auth: `src/routes/**/dash-guest.e2e.ts`, `src/routes/**/demo.e2e.ts`), then **`e2e-main`** (depends on `e2e-guest`), then **`e2e-leak-check`** (depends on `e2e-main`). Authenticated projects set `storageState` to `src/routes/.auth/user.json` when that file exists — **there is no UI login on every test**; cookies/session are restored from disk.
-- **Workers:** Playwright uses `workers: 1` because authenticated E2E shares one storage state; higher parallelism races on the same DB user.
-- **Timeouts:** Guest/main/leak projects use **per-project test timeouts** in `playwright.config.ts` so switching tabs and dash actions are not cut off by the global default.
+- `playwright.config.ts` projects, each depending on the previous: `e2e-guest` (no auth: `src/routes/**/dash-guest.e2e.ts`, `src/routes/**/demo.e2e.ts`) → `e2e-main` → `e2e-leak-check`. Authenticated ones restore `storageState` from `src/routes/.auth/user.json` when it exists — no UI login per test.
+- `workers: 1` — authenticated E2E shares one storage state and DB user.
+- Guest/main/leak projects set per-project test timeouts so tab switches and dash actions are not cut off.
 
 ### Regression fix workflow (E2E data / cleanup bugs)
 
-When fixing bugs where tests leave data behind (or similar persistent state):
+When tests leave persistent state behind:
 
-1. **Add or extend a failing guard** — e.g. `src/routes/dash/dash-leak-check.e2e.ts` exports `dash_leak_guard.scrub_then_assert_clean`: it scrubs tasks whose titles contain the `E2E_` automation prefix, then asserts none remain. Confirm it **fails** while scrub or per-test teardown is broken (red).
-2. **Fix production code or test teardown** — cleanup must be reliable (prefer `data-testid` over locale-specific `aria-label` for automation; avoid swallowing cleanup errors unless explicitly intended).
-3. **Confirm the guard passes** (green) with full `pnpm test:e2e` (or targeted Playwright command above).
-4. **Document** any new invariant in this guide or the relevant E2E helper module.
+1. Add or extend a guard and confirm it fails (e.g. `dash_leak_guard.scrub_then_assert_clean` in `src/routes/dash/dash-leak-check.e2e.ts` scrubs `E2E_`-prefixed tasks, then asserts none remain).
+2. Fix production code or teardown — prefer `data-testid` over locale-specific `aria-label`; do not swallow cleanup errors unless intended.
+3. Confirm green with full `pnpm test:e2e` (or a targeted Playwright run).
+4. Document any new invariant here or in the E2E helper module.
 
 ### Error Messages
 
-- Include expected and actual values explicitly
+- State expected and actual values
 - Wrap `number` in template literals with `String()`
-- Don't add `?? ''` unless the value can genuinely be `undefined`
+- No `?? ''` unless the value can be `undefined`
 
 ### Type Safety
 
-- No `any`; always use loop variables (avoids unused-variable lint errors)
-- Use `@ts-expect-error`, not `@ts-ignore`
+- No `any`; use every loop variable
+- `@ts-expect-error`, not `@ts-ignore`
 
 ### Statement Limit
 
-- Max 10 statements per test function; split complex tests if exceeded
+- Max 10 statements per test function; split beyond that
 
 ### No live network
 
-- **A unit test must not reach the network.** Mock every read that leaves the process — a `gh` call, an HTTP request, a CLI subprocess that makes one
-- **Mock the whole read, not the first half of it.** A helper that stubs one call and leaves a second one on its default calls through, and the test still **passes** — slower, and against whatever the remote answers. That is how joshuafolkken/kit#1353 reached a 10-second timeout in CI on a change that had nothing to do with it
-- In kit's own checkout `vitest.config.ts` arms a guard that fails the run and lists the `gh` invocations it recorded — the commands, not the test that made them, which the command text is usually enough to find (`docs/josh-commands.md` → `josh test:unit`). Elsewhere the rule holds without one
+- **A unit test must not reach the network** — mock every read leaving the process (`gh` call, HTTP request, CLI subprocess that makes one).
+- **Mock the whole read**: a stub of one call leaving a second on its default still passes, slowly and against the remote (joshuafolkken/kit#1353: a 10-second CI timeout).
+- kit's `vitest.config.ts` fails such a run, listing the `gh` invocations (`docs/josh-commands.md` → `josh test:unit`); elsewhere the rule holds unguarded.
 
 ### A josh command that writes state runs through the integration harness (kit only)
 
-- **A new or changed state-writing josh command needs a test in all three environments of `scripts/test/josh-harness.ts`** — kit, a consumer without `docs/`, a lane worktree (joshuafolkken/kit#2402). Packed suite: `vitest.harness.config.ts`
+- A new or changed state-writing josh command needs a test in all three environments of `scripts/test/josh-harness.ts` — kit, a consumer without `docs/`, a lane worktree (joshuafolkken/kit#2402). Packed suite: `vitest.harness.config.ts`
 
 ---
 
 ## 3. Checklist
 
-- [ ] **Before “done”:** **Completion gate** in `CLAUDE.md` — `pnpm josh gate` (lint, type check, spell check and unit tests), then E2E per § 6 below: the CI E2E job where a pull request is open, **`pnpm josh test:e2e`** run by you where there is none. **Do not** stop at `pnpm josh test:unit` when E2E applies, and **never** ask the user to run it. Run it with `CI` unset so Playwright uses **DEV** (`pnpm run dev` on the port `playwright.config.ts` resolves from `PORT_SEED`), matching the VS Code Test plugin. ReadLints **0 errors** on touched files; Playwright **no failures and no flaky** runs in what you report. **If Playwright cannot run in your environment:** do **not** use `pnpm build` or `CI=true` unless the user asked — say the E2E result is missing and that the gate is therefore not closed
-- [ ] Magic numbers/strings → constants (except `0`, `1`, `-1`)
-- [ ] `.js` on all import paths
-- [ ] Playwright: `data-testid` selectors only
-- [ ] `async`/`await` used correctly
-- [ ] No `any`; all loop variables used
-- [ ] Max 10 statements per test function
-- [ ] `read_lints` run; 0 errors before reporting done
-- [ ] No unnecessary `?? ''`; `String()` for numbers in template literals
+- [ ] `pnpm josh gate`, then E2E per § 6: the CI E2E job where a pull request is open; where there is none, run `pnpm josh test:e2e` with `CI` unset (DEV: `pnpm run dev` on the port `playwright.config.ts` derives from `PORT_SEED`); no `pnpm build` or `CI=true` unless asked. Playwright cannot run here → report the E2E result missing and the gate not closed
+- [ ] `read_lints`: 0 errors on touched files; Playwright: no failures and no flaky runs
+- [ ] § 2 holds: constants, `.js` imports, `data-testid` selectors, correct `async`/`await`, no `any`, ≤10 statements, `String()` / no needless `?? ''`
 
 ---
 
 ## 4. Reference Files
 
-**E2E:** `src/routes/**/page.e2e.ts`, `src/routes/**/praise.e2e.ts`
-**Unit:** `src/lib/data/phrases/phrases.test.ts`, `src/lib/data/praise-audio.test.ts`
-**ESLint:** `eslint.config.js`
+E2E: `src/routes/**/page.e2e.ts`, `src/routes/**/praise.e2e.ts` · Unit: `src/lib/data/phrases/phrases.test.ts`, `src/lib/data/praise-audio.test.ts` · ESLint: `eslint.config.js`
 
 ---
 
 ## 5. Unit Test Example — Stateful Functions
 
-```typescript
-import { expect, test } from 'vitest'
-import { get_praise_audio_file, reset_praise_audio_index } from './praise-audio.js'
-
-test('returns expected values in sequence', () => {
-	reset_praise_audio_index() // reset state at the start of each test
-
-	const first_result = get_praise_audio_file()
-	expect(first_result).toBe('expected-value-1')
-
-	const second_result = get_praise_audio_file()
-	expect(second_result).toBe('expected-value-2')
-})
-```
+Reset module state at the start of each test (`reset_praise_audio_index()` in `src/lib/data/praise-audio.test.ts`), then assert each call of the sequence in order.
 
 ---
 
 ## 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
 
-Decided by whether a pull request is open, never by judgement:
+Decided by whether a pull request is open:
 
 | Situation                                                                                    | What closes the gate                                                                                             |
 | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
 | A pull request is open — `fullrun`, `prrun`, `backlogrun`                                    | The CI E2E job. `pnpm josh followup` waits for the checks and refuses to merge while any of them is non-passing. |
 | No pull request — `halfrun`'s stop before commit, a completion reported outside any workflow | `pnpm josh test:e2e`, run by **you**, output read by you.                                                        |
 
-**Never ask the user to run it, in either row.** A completion report is not allowed to depend on
-somebody being at the keyboard; that dependency is what made a `fullrun` chain stall at its last
-step. And never report completion on an E2E result nobody read — an unread result is not a pass.
+**Never ask the user to run it**, in either row, and never report completion on an unread E2E result — unread is not a pass.
 
-**Where the application layer ships an integrated gate, prefer it** over a bare `pnpm josh test:e2e`
-for the second row: `@joshuafolkken/app-kit` ships `pnpm josh-app verify`, which builds once and
-boots once to run the E2E suite and the DAST scan against that one server — and which delegates E2E
-to `josh test:e2e`, so the skip below still applies. **Decide by the command list the installed
-toolkit prints, not by which toolkit is installed and not by a version number written here**: the
-same rule the UI gate uses, and the only one that survives a release.
+Second row: prefer an integrated gate when the installed toolkit's printed command list has one (not by toolkit or version) — `@joshuafolkken/app-kit`'s `pnpm josh-app verify` builds and boots once for E2E and the DAST scan, delegating E2E to `josh test:e2e` (so the skip below applies).
 
 ### A project with no E2E suite
 
-`pnpm josh test:e2e` runs through `scripts/test/test-e2e-guard.ts`, which **skips and exits 0**, naming
-the reason, when `@playwright/test` is not installed or no `*.e2e.{ts,js}` file exists. That skip is
-a **defined** outcome, not an accident: a project with no E2E suite has nothing for the gate to
-read, and the run says so out loud. **A skip you did not see printed is not one** — it is an unread
-result, and it falls under the previous paragraph.
+`pnpm josh test:e2e` runs through `scripts/test/test-e2e-guard.ts`, which skips and exits 0, naming the reason, when `@playwright/test` is not installed or no `*.e2e.{ts,js}` file exists. That is a defined outcome; **a skip you did not see printed is an unread result**.
 
-**CI decides the same question by the same rule.** The `e2e-detect` job in
-`templates/workflows/ci.yml` enables the `e2e` job when any `*.e2e.{ts,js}` exists outside
-`node_modules` — the guard's own glob — whatever the config's filename;
-`scripts/ci/ci-yml-e2e-detect.test.ts` pins the agreement. CI enables the job on the spec alone, even
-where the guard skips for a missing `@playwright/test`, so a spec that cannot run ends red rather than
-silently green.
+CI uses the same rule: the `e2e-detect` job in `templates/workflows/ci.yml` enables the `e2e` job when any `*.e2e.{ts,js}` exists outside `node_modules` (the guard's glob), whatever the config's filename — on the spec alone, so a spec that cannot run ends red, not silently green. `scripts/ci/ci-yml-e2e-detect.test.ts` pins the agreement.
 
 ### The gate is not weakened
 
-- **A non-passing check keeps the merge closed.** `evaluate_pr_state` returns `success` only when
-  GitHub reports the pull request `CLEAN` **and** every required check passes; the only exception is a
-  non-passing set made entirely of CodeRabbit checks (the temporary kit#753 policy). A failing check
-  ends the wait on the poll that sees it, by name (`PR checks failed (failed checks: E2E).`).
-- **Filtering, narrowing or reinterpreting E2E output to get past it is a workaround** —
-  `CLAUDE.md` → "Cross-package problems"; reporting the filtered result honestly does not make it
-  compliant.
-- **`E2E` stays off the default required-check list**; a project opts in through
-  `JOSH_REQUIRED_CHECKS`. `scripts/gh/git-pr-checks-e2e-gate.test.ts` pins both properties.
+- **A non-passing check keeps the merge closed.** `evaluate_pr_state` returns `success` only when GitHub reports the pull request `CLEAN` and every required check passes; the only exception is a non-passing set made entirely of CodeRabbit checks (the temporary kit#753 policy). A failing check ends the wait on the poll that sees it, by name (`PR checks failed (failed checks: E2E).`).
+- **Filtering, narrowing or reinterpreting E2E output to get past it is a workaround** (`CLAUDE.md` → "Cross-package problems"), however honestly reported.
+- `E2E` stays off the default required-check list; a project opts in through `JOSH_REQUIRED_CHECKS`. `scripts/gh/git-pr-checks-e2e-gate.test.ts` pins both properties.

package/scripts/adopt/adopt-toolkits.ts

@@ -65,8 +65,7 @@ function declared_toolkits(project_root: string): ReadonlyArray<string> {
 // declares one, so a toolkit shipping several CLIs still resolves to one deterministically.
 function pick_bin_name(package_name: string, bin: string | Record<string, string>): string {
 	const unscoped = path.basename(package_name)
-	if (typeof bin === 'string') return unscoped
-	if (bin[unscoped] !== undefined) return unscoped
+	if (typeof bin === 'string' || bin[unscoped] !== undefined) return unscoped
 
 	return Object.keys(bin)[0] ?? unscoped
 }
@@ -99,8 +98,7 @@ function has_runnable_cli(project_root: string, bin_name: string): boolean {
 // spawning it would fail the sync step rather than say what is wrong.
 function resolve_toolkit(project_root: string, package_name: string): Release | undefined {
 	const bin_name = read_bin_name(project_root, package_name)
-	if (bin_name === undefined) return undefined
-	if (!has_runnable_cli(project_root, bin_name)) return undefined
+	if (bin_name === undefined || !has_runnable_cli(project_root, bin_name)) return undefined
 
 	return { package_name, version: LATEST_VERSION, bin_name }
 }

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-exit-record.ts

@@ -20,6 +20,28 @@ function read_exit_record(transcript: string): ClaudeResultEvent | undefined {
 		.findLast((record) => record !== undefined)
 }
 
-const agent_exit_record = { read_exit_record }
+function event_type(line: string): unknown {
+	const value = json_value.parse_or_undefined(line)
+
+	return typeof value === 'object' && value !== null && 'type' in value ? value.type : undefined
+}
+
+// The Claude stream events a turn is made of — a Codex transcript's own (`turn.completed`, `error`)
+// are none of these, so one never reads as killed.
+const TURN_TYPES: ReadonlySet<unknown> = new Set(['system', 'assistant', 'user', 'stream_event'])
+
+// Whether a Claude session was killed inside a turn: its last event is a turn's, not a `result`. A
+// finished turn ends on a result; a background task can wake the session for another turn, and a
+// process killed before that turn's result leaves other events last.
+function is_mid_turn(transcript: string): boolean {
+	const last = transcript
+		.split('\n')
+		.map((line) => event_type(line))
+		.findLast((type) => type !== undefined)
+
+	return TURN_TYPES.has(last)
+}
+
+const agent_exit_record = { is_mid_turn, read_exit_record }
 
 export { agent_exit_record }

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,
 }