@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/prompts/review.md

@@ -12,9 +12,9 @@ Review policy: the level, the round count, and what happens to a finding after t
 ## When to run
 
 When: `CLAUDE.md` → "Pre-commit Self-Review"; inside a workflow, round 1 runs before the commit and
-round 2 beside CI (`.claude/skills/workflow-commands/chain-rule.md`). Pass the review subagent the
-`reviewer` profile's model and effort that `pnpm josh review:brief` prints; never substitute the review
-level for effort.
+round 2 beside CI (`.claude/skills/workflow-commands/chain-rule.md`). Launch the `reviewer` agent
+type (round 2: `reviewer-verification`), never nested, with the model `pnpm josh review:brief` prints.
+Before the reviewer returns its findings → `pnpm josh review:lint` (`.claude/agents/reviewer.md`).
 
 Re-run after fixes until **no high or medium findings remain or the round cap below is reached** (the
 first review counts), whichever comes first. Round 2 is a verification pass over the fixes
@@ -24,22 +24,45 @@ first review counts), whichever comes first. Round 2 is a verification pass over
 
 ## Before round 1 — the implementer's self-check
 
-Answer these five over your own diff before the scoped pair that precedes round 1, and fix what an
-answer turns up (about two in three of 135 sampled round-1 High/Medium findings fell under one). The
-review, its severity tests and the round cap are unchanged.
+Answer these ten over your own diff before the scoped pair that precedes round 1 — question 1 once
+`pnpm josh run:review --join` prints its lines after the review, or, under `--join --fixing` or a
+check `--join` restarted on a moved tree, the ship's pre-detach — and fix what an
+answer turns up (about four in five of 100 sampled High/Medium findings that stopped lane reviews
+fell under one; `pnpm josh lane:stats` counts the kinds that still stop). The review, its severity
+tests and the round cap are unchanged.
 
-1. **Tests pin the change** — for each condition, branch or call added or changed, name the test that
-   turns red when it is deleted or inverted, and check its fixture reaches that branch (no assert on a
-   string the code never draws, no comparison against a literal copy).
+1. **Tests pin the change** — read the `unpinned` and `unchecked` lines `pnpm josh run:review --join`
+   prints from `pnpm josh test:pinned` (each unchecked place is listed in its `full output:` log) (`docs/josh-commands.md` → "`josh test:pinned`"), and check a pinning test's fixture reaches its branch (no assert on a string the code
+   never draws, no comparison against a literal copy).
 2. **Prose matches the code** — grep docs, prompts and comments for the old wording of every behavior,
-   constant, command and heading you changed, moved or removed, `"the table above"` and rewritten
-   sentences included.
+   constant, command and heading you changed, moved or removed (`pnpm josh prose:stale` finds the
+   removed ones), `"the table above"` and rewritten sentences included.
 3. **Failure is not a negative answer** — every timeout, non-zero exit or `gh` failure on a touched
    path returns something a caller can tell apart from `false`, `undefined` or "nothing found".
 4. **Every caller moved with it** — grep every reference to a changed function, list or command, and
    update each sibling path (the other CLI, the registry, the consumer side) in the same change.
+   The readers outside the diff: `pnpm josh review:brief` → `## Readers outside the diff`.
 5. **The Issue is met on HEAD** — the premises you relied on hold on the current tree, and each
    acceptance criterion is checked against the diff.
+6. **State is read fresh** — for every record, stamp, snapshot, memo or ledger a decision reads, name
+   its writer and check it cannot be older than the decision (a past `success`, a tick's shared
+   snapshot, a sync before the commit) or written by another run in between.
+7. **The rule covers its whole input space** — list every kind of input a scan, pattern, matcher or
+   lookup must accept or reject (the sibling file type, the consumer's config beside the root, quoted
+   text, a subshell, a pipe, a heredoc) and pin one test row per kind.
+8. **Edge inputs and environments** — say what the change does when its input is empty, absent or
+   new, and outside a TTY, a lane or the default agent runtime.
+9. **Claims about other components are checked in their code** — for every claim your code or a
+   comment makes about another component's behavior (what a stage does, who enforces a limit, which
+   repository it runs in), open that component's code and confirm it; then name each context the
+   change runs in — kit and a consumer, and a predecessor that died midway leaving its record behind.
+10. **Commands your prose tells a reader to run are run** — for every command a refusal, hint or
+    document you added or changed tells a reader to run, run it as written from a cwd other than the
+    root, with an absolute path, a relative path and an empty input, and check each result — in a
+    scratch copy (`mktemp -d`) when it writes, deletes, files or pushes, never on the lane's files.
+
+The brief lists `Removed tests` → each needs a `## 消えたテストの処置` row in the PR body, or the
+merge is refused: `prompts/collaboration-workflow/report-format.md` → "PR 本文の消えたテストの処置".
 
 ---
 
@@ -59,10 +82,20 @@ pnpm josh review:brief --level-only --staged   # the staged diff
 
 ---
 
+## Interaction review
+
+`pnpm josh run:review` writes its brief to a file beside round 1's where it is due, printing both paths; one still owed after round 1
+takes `pnpm josh review:brief --interaction`. Hand it to a reviewer subagent, dispose of the findings
+by the three-way disposition below, and record the pass with
+`pnpm josh review:record --interaction --issue <N> [<category>:<severity>:<file> ...]`.
+
+`pnpm josh followup` refuses a due change with none recorded; `pnpm josh ship --review` runs it itself, beside round 1, and stops once on the findings of both.
+
 ## Review round cap (2 rounds)
 
 Two rounds is the ceiling, not the schedule: every fix creates new surface a further round would find
-something in. Whether round 2 is due is `pnpm josh review:round2`'s answer (below).
+something in. Whether round 2 is due is `pnpm josh review:round2`'s answer (below). The interaction
+review is not one of the two.
 
 ### A merge-conflict resolution review is not one of the two
 
@@ -76,32 +109,28 @@ the child rather than buying a further round.
 ### When round 2 is skipped entirely, and when it is not
 
 ```bash
-pnpm josh review:round2 --round-1-closed   # → required | skip ; the reason on stderr
+pnpm josh review:round2 --record <N>   # → required | skip ; the reason on stderr
 ```
 
-Ask once round 1's fixes are in, before the commit. Pass `--round-1-closed` only when every round-1
-High/Medium closed — fixed in this working tree or verified false positive — and none was filed or
-deferred. Without the flag, and on any uncertainty (a missing round-1 snapshot included), the answer is
-`required`.
+Ask once round 1's fixes are in and the round is recorded with each finding's disposition
+(`pnpm josh review:record`'s usage), before the commit. Round 1 is closed only when the ledger shows
+every round-1 High/Medium as `fixed` or `false-positive`. Anything else, including a missing round-1
+snapshot, answers `required`.
 
 `skip` has exactly two arms, and the reason line names which fired:
 
 - **A** — the fix delta is empty.
 - **B** — every path in the fix delta is inert by the review-level classification above:
-  `docs/**/*.md`, the root `README.md`, under `prompts/`, or a `.ts` / `.js` / `.svelte` file outside
+  `docs/**/*.md`, the root `README.md`, under `prompts/`, a metrics approval under
+  `.josh/metrics-accepted/`, or a `.ts` / `.js` / `.svelte` file outside
   `.claude/` changed only in comments (a lint, type-check, coverage or bundler directive comment counts
   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.
 
-Record a skipped round on the Issue:
-
-1. Label the Issue `review-round2-skipped`, created once per repository:
-   `gh api repos/{owner}/{repo}/labels -f name=review-round2-skipped -f color=c5def5 -f description="Review round 2 was skipped under the condition in prompts/review.md" --silent 2>/dev/null || true`,
-   then `gh api repos/{owner}/{repo}/issues/<N>/labels -f 'labels[]=review-round2-skipped'`.
-2. Comment under `## Round 2 skipped`, naming which arm fired and quoting the command's reason line
-   verbatim.
+`--record <N>` records a skipped round on the Issue itself: a comment under `## Round 2 skipped`
+naming which arm fired and quoting the reason line verbatim, written once however often it is asked.
 
 ### Three-way disposition after the cap
 
@@ -139,19 +168,19 @@ Branch 2 only:
   a `fold`; the first filing asks nothing.
 
   1. Before the current Issue closes, file it tagged `route:review-cap`:
-     `pnpm josh issue:file "<title>" --body-file <body-file> --depth <n> --route review-cap`. It lints
+     `pnpm josh issue:file "<title>" --body-file <body-file> --route review-cap --found-during <N>`
+     (`--found-during` leaves the deferral note on the current Issue the ship reviewer reads). It lints
      the body, applies the declared labels, runs the duplicate scan and `epic:bundle`
-     (`docs/josh-commands-backlog.md` → `josh issue:file`). `epic:bundle` reads open issues only, so
+     (`docs/josh-commands-backlog.md` → `josh issue:file`). A security finding declares its
+     `- セキュリティ:` line (`issue-template.md` → H). `epic:bundle` reads open issues only, so
      after the parent closes it answers `none` permanently.
-  2. Act on the printed `epic:bundle` answer by running the write command yourself — `epic:bundle`
-     writes nothing, and a hand edit of the epic body leaves the task list and `blocked-by` relations
-     disagreeing (`epic:next` returns `error`). Tier A, no confirmation:
-     - `add_to_epic` → `pnpm josh epic --add <E> <new>`, with `--before <M>` / `--after <M>` when the
-       relation carries an order.
-     - `create_epic` → `pnpm josh epic "<title>" <new> <other> [--ordered]`.
-     - `ask` (candidates across two or more epics) → run the recommended epic's write command and record
-       what was taken, what was rejected and why on the new Issue and that epic's `## Decisions`. Stop
-       only where the two epics are genuinely too close to separate.
+  2. Act on the printed `epic:bundle` answer with `pnpm josh epic:bundle <new> --apply` — never a
+     hand edit of the epic body, which leaves the task list and `blocked-by` relations disagreeing
+     (`epic:next` returns `error`). Tier A, no confirmation:
+     - `add_to_epic` / `create_epic` → `--apply` writes it, with any recorded order.
+     - `ask` (candidates across two or more epics) → `--apply` writes nothing; place it in the
+       recommended epic with `pnpm josh epic --add <E> <new> --decision-file <path>`
+       (`.claude/skills/epic-commands/epic-bundle.md`).
      - `none` → nothing.
      - Non-zero exit, or any ⚠ warning above `Nothing to bundle.` → stop and report what it said; a
        `none` after such a warning is not "nothing to bundle".

package/prompts/testing-guide.md

@@ -2,20 +2,7 @@
 
 ## 0. Per-Requirement Test Coverage (MANDATORY)
 
-Before any implementation code, **list every requirement from the user's request and assign a test to each one**.
-
-### Planning template
-
-```text
-Req 1: "Label chip shown immediately"
-  → E2E: open editor, type new label, press Enter → chip visible without blurring
-
-Req 2: "Down arrow moves to next row"
-  → E2E: open editor on row 1, press ↓ → row 2 enters edit mode
-
-Req N: ...
-  → Unit/E2E: ...
-```
+Every requirement gets a test (`CLAUDE.md` → "Code Change Rules" Step 0); the declaration's form is `prompts/collaboration-workflow/report-format.md` → "作業前サマリはいつ・どう出すか". This section decides which test.
 
 ### Rules
 
@@ -23,8 +10,8 @@ Req N: ...
 - 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 のファイルを含む変更は自動テストを行う。
+- **A runtime change with no test is refused at the commit** — `pnpm josh git -y` refuses it while `pnpm josh test:declared` answers `required` (the `test-declared` row of `pnpm josh rule:list`).
 - 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)
 
@@ -58,10 +45,7 @@ Req N: ...
 
 ## 2. Test Guidelines
 
-### Naming
-
-- Variables/functions: `snake_case` | Constants: `UPPER_SNAKE_CASE`
-- Boolean prefix: `is_`, `has_`, `should_`, `can_`, `will_`, `did_`
+Naming, imports, `any`, `@ts-ignore`, magic numbers, template `String()` and the 10-statement limit are lint-enforced (`eslint/base.js`); this section holds only what lint cannot see.
 
 ### Test Functions
 
@@ -73,15 +57,6 @@ Req N: ...
 - Playwright: `for` loop; Vitest: `test.each` / `it.each`
 - Cases: a `cases` or `*_cases` array at file top, outside test functions
 
-### Constants
-
-- Magic numbers/strings except `0`, `1`, `-1` → `UPPER_SNAKE_CASE` constants after the imports
-
-### Imports
-
-- Always the `.js` extension: `import { foo } from './bar.js'`
-- Type imports: `import { type Foo } from '...'`
-
 ### Playwright
 
 - Select with `page.getByTestId('id')`; add `data-testid` to the implementation
@@ -102,17 +77,6 @@ When tests leave persistent state behind:
 ### Error Messages
 
 - State expected and actual values
-- Wrap `number` in template literals with `String()`
-- No `?? ''` unless the value can be `undefined`
-
-### Type Safety
-
-- No `any`; use every loop variable
-- `@ts-expect-error`, not `@ts-ignore`
-
-### Statement Limit
-
-- Max 10 statements per test function; split beyond that
 
 ### No live network
 
@@ -122,15 +86,15 @@ When tests leave persistent state behind:
 
 ### 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 `tools/test/josh-harness.ts` — kit, a consumer without `docs/`, a lane worktree (joshuafolkken/kit#2402). Packed suite: `vitest.harness.config.ts`
 
 ---
 
 ## 3. Checklist
 
-- [ ] `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 `?? ''`
+- [ ] `pnpm josh gate`, then the E2E gate per § 6
+- [ ] `pnpm josh lint:related`: 0 errors on touched files; Playwright: no failures and no flaky runs
+- [ ] § 2 holds: `data-testid` selectors, `async` Playwright tests, expected/actual in error messages
 
 ---
 
@@ -161,6 +125,8 @@ Decided by whether a pull request is open:
 
 **Never ask the user to run it**, in either row, and never report completion on an unread E2E result — unread is not a pass.
 
+Second row: run 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.
+
 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

package/scripts/agent/agent-argv.ts

@@ -95,30 +95,28 @@ function resolve(
 	return resolved.kind === 'rejected' ? resolved : with_profile(invocation, resolved.profile)
 }
 
+function profiled_in(invocation: string, resolved: ProfileResult, cwd: string): AgentArgvResult {
+	return resolved.kind === 'rejected'
+		? resolved
+		: with_profile_in(invocation, resolved.profile, cwd)
+}
+
 // **A cut relaunch's profile, resolved for the phase the resumed child is entering**.
-// A stored lane profile keeps its model and takes only the phase's effort; a
-// lane without one resolves the worker for the phase. An env override wins over the phase in either path.
+// A stored lane profile keeps its model unless the phase's own model key is set, and takes the phase's
+// effort; a lane without one resolves the worker for the phase. An env override wins over the phase in
+// either path.
 function resume_argv(
 	invocation: string,
 	profile: AgentProfile | undefined,
 	phase: string,
 	cwd: string,
 ): AgentArgvResult {
-	if (profile !== undefined) {
-		return with_profile_in(invocation, agent_role_profile.with_phase_effort(profile, phase), cwd)
-	}
-
-	const resolved = agent_role_profile.resolve(agent_role_profile.WORKER, process.env, phase)
-
-	return resolved.kind === 'rejected'
-		? resolved
-		: with_profile_in(invocation, resolved.profile, cwd)
-}
+	const resolved =
+		profile === undefined
+			? agent_role_profile.resolve(agent_role_profile.WORKER, process.env, phase)
+			: agent_role_profile.with_phase(profile, phase)
 
-function profiled_in(invocation: string, resolved: ProfileResult, cwd: string): AgentArgvResult {
-	return resolved.kind === 'rejected'
-		? resolved
-		: with_profile_in(invocation, resolved.profile, cwd)
+	return profiled_in(invocation, resolved, cwd)
 }
 
 function resolve_in(

package/scripts/agent/agent-event.ts

@@ -1,15 +1,11 @@
 import { json_value } from '#scripts/lib/json-value'
+import { transcript_record, type TranscriptRecord } from '#scripts/lib/transcript-record'
 import { z } from 'zod'
 import type { AgentProvider } from './agent-role-profile'
 import { claude_result_event } from './claude-result-event'
 
-const TEXT_BLOCK_SCHEMA = z.looseObject({ type: z.literal('text'), text: z.string() })
-const CLAUDE_MESSAGE_SCHEMA = z.looseObject({ content: z.array(z.unknown()).optional() })
+const ASSISTANT_TYPE = 'assistant'
 const CLAUDE_INIT_SCHEMA = z.looseObject({ type: z.literal('system'), subtype: z.literal('init') })
-const CLAUDE_ASSISTANT_SCHEMA = z.looseObject({
-	type: z.literal('assistant'),
-	message: CLAUDE_MESSAGE_SCHEMA,
-})
 const USAGE_SCHEMA = z.looseObject({
 	input_tokens: z.number().optional(),
 	cached_input_tokens: z.number().optional(),
@@ -58,12 +54,16 @@ function usable_text(value: unknown): string | undefined {
 	return typeof value === 'string' && value.trim() !== '' ? value : undefined
 }
 
-function claude_progress(content: ReadonlyArray<unknown>): string | undefined {
-	return content
-		.map((block) => TEXT_BLOCK_SCHEMA.safeParse(block))
-		.filter((parsed) => parsed.success)
-		.map((parsed) => parsed.data.text)
-		.findLast((text) => text.trim() !== '')
+function claude_progress(record: TranscriptRecord): string | undefined {
+	return transcript_record
+		.blocks_of(record)
+		.filter((block) => block.type === transcript_record.TEXT_TYPE)
+		.map((block) => usable_text(block.text))
+		.findLast((text) => text !== undefined)
+}
+
+function is_claude_assistant(record: TranscriptRecord | undefined): record is TranscriptRecord {
+	return record?.type === ASSISTANT_TYPE && record.message !== undefined && record.message !== null
 }
 
 function claude_result(value: unknown, state: AgentEventState): AgentEventState | undefined {
@@ -80,9 +80,9 @@ function claude_result(value: unknown, state: AgentEventState): AgentEventState
 }
 
 function claude_assistant(value: unknown, state: AgentEventState): AgentEventState | undefined {
-	const assistant = CLAUDE_ASSISTANT_SCHEMA.safeParse(value)
-	if (!assistant.success) return undefined
-	const progress = claude_progress(assistant.data.message.content ?? []) ?? state.progress
+	const record = transcript_record.read(value)
+	if (!is_claude_assistant(record)) return undefined
+	const progress = claude_progress(record) ?? state.progress
 
 	return { ...state, provider: 'anthropic', progress }
 }

package/scripts/agent/agent-exit-record.ts

@@ -42,6 +42,18 @@ function is_mid_turn(transcript: string): boolean {
 	return TURN_TYPES.has(last)
 }
 
-const agent_exit_record = { is_mid_turn, read_exit_record }
+// Whether the transcript's last line is its exit record. A log appended across launches keeps an
+// earlier session's record, so a later session that died before finishing — inside a turn, or on a
+// start-up error that is not JSON — leaves something else last and its own ending unread.
+function ends_on_exit_record(transcript: string): boolean {
+	const last = transcript.split('\n').findLast((line) => line.trim() !== '')
+
+	return (
+		last !== undefined &&
+		claude_result_event.decode(json_value.parse_or_undefined(last)) !== undefined
+	)
+}
+
+const agent_exit_record = { ends_on_exit_record, is_mid_turn, read_exit_record }
 
 export { agent_exit_record }

package/scripts/agent/agent-provider.ts

@@ -0,0 +1,138 @@
+import { agent_session_environment } from '#scripts/josh/agent-session-environment'
+import { z } from 'zod'
+
+// Which provider an agent session runs on, read from the session's own keys or the mark a detached
+// launch hands its child. `agent-role-profile.ts` resolves a role's profile on top of it.
+
+const EMPTY_LENGTH = 0
+
+const PROVIDER_SCHEMA = z.enum(['anthropic', 'openai'])
+
+type AgentProvider = z.infer<typeof PROVIDER_SCHEMA>
+type AgentEnvironment = Readonly<Record<string, string | undefined>>
+
+interface Rejected {
+	kind: 'rejected'
+	note: string
+}
+
+type ProviderResult = Rejected | { kind: 'provider'; provider: AgentProvider; is_default?: true }
+
+const ANTHROPIC_PROVIDER: AgentProvider = 'anthropic'
+const OPENAI_PROVIDER: AgentProvider = 'openai'
+const CODEX_SESSION_KEY = 'CODEX_THREAD_ID'
+
+function trimmed(value: string | undefined): string | undefined {
+	const result = value?.trim()
+
+	return result === undefined || result.length === EMPTY_LENGTH ? undefined : result
+}
+
+function rejection(key: string, value: string, expected: string): Rejected {
+	return { kind: 'rejected', note: `${key}=${value} ${expected}, so the agent was not started` }
+}
+
+function has_session(environment: AgentEnvironment, keys: ReadonlyArray<string>): boolean {
+	return keys.some((key) => trimmed(environment[key]) !== undefined)
+}
+
+const CONFLICTING_SESSIONS: Rejected = {
+	kind: 'rejected',
+	note: 'both Codex and Claude Code sessions were detected',
+}
+
+// The provider a detached launcher hands a process that is not itself an agent session.
+// `detached_launch` strips the parent-session keys — the very keys the
+// detection below reads — so a `josh ship --detach --review` supervisor could never resolve its reviewer.
+// **It is a fallback, read only when no session is detected**: the mark is inherited by everything the
+// supervisor starts, and a real session's own keys must keep deciding for that session.
+const HANDED_PROVIDER_KEY = 'JOSH_AGENT_PROVIDER'
+
+// **Nothing named a provider, so Claude Code is the default** — a person typing `josh lane:launch` in a
+// plain terminal has no session and no mark. Only silence defaults: two detected sessions and a mark
+// naming no allowed provider still refuse. `is_default` lets a launch say so, and lets `josh cost` keep
+// reading "no session of its own" rather than pricing another session's transcript.
+const DEFAULT_PROVIDER: ProviderResult = {
+	kind: 'provider',
+	provider: ANTHROPIC_PROVIDER,
+	is_default: true,
+}
+const DEFAULT_NOTICE = ` No agent session or ${HANDED_PROVIDER_KEY} was found, so the provider defaulted to ${ANTHROPIC_PROVIDER} (Claude Code).`
+
+function handed_provider(environment: AgentEnvironment): ProviderResult {
+	const value = trimmed(environment[HANDED_PROVIDER_KEY])
+	if (value === undefined) return DEFAULT_PROVIDER
+	const parsed = PROVIDER_SCHEMA.safeParse(value)
+
+	return parsed.success
+		? { kind: 'provider', provider: parsed.data }
+		: rejection(HANDED_PROVIDER_KEY, value, 'is not an allowed provider')
+}
+
+// The session this process runs in, read from its own keys: `undefined` when none is detected.
+function detected_provider(environment: AgentEnvironment): ProviderResult | undefined {
+	const has_codex = has_session(environment, [CODEX_SESSION_KEY])
+	const has_claude = has_session(environment, agent_session_environment.PARENT_SESSION_KEYS)
+
+	if (has_codex === has_claude) return has_codex ? CONFLICTING_SESSIONS : undefined
+
+	return { kind: 'provider', provider: has_codex ? OPENAI_PROVIDER : ANTHROPIC_PROVIDER }
+}
+
+function resolve_provider(environment: AgentEnvironment = process.env): ProviderResult {
+	return detected_provider(environment) ?? handed_provider(environment)
+}
+
+// The sentence a launch appends when it ran on the default, so falling back is never silent; empty when
+// a session or a mark decided.
+function default_notice(environment: AgentEnvironment = process.env): string {
+	const selected = resolve_provider(environment)
+
+	return selected.kind === 'provider' && selected.is_default === true ? DEFAULT_NOTICE : ''
+}
+
+// The same sentence on stderr, for a launcher whose own line is a verdict or a brief another process
+// reads: `run:wake --start`, `review:brief` and `ship --detach` default exactly as a dispatch does.
+function warn_of_default(environment: AgentEnvironment = process.env): void {
+	const notice = default_notice(environment).trim()
+
+	if (notice !== '') console.error(notice)
+}
+
+// Whether this session is woken when a background command it started completes.
+// Claude Code re-invokes the session at the completion; a Codex session is not
+// re-invoked, so a parent there can only wait by polling, each poll a model call over its whole context.
+// Only a resolved Codex session answers no — a defaulted or conflicting one keeps the callback.
+function has_completion_callback(environment: AgentEnvironment = process.env): boolean {
+	const selected = resolve_provider(environment)
+
+	return selected.kind !== 'provider' || selected.provider !== OPENAI_PROVIDER
+}
+
+// The mark a detached launch sets on its child: the provider this session resolved, the default
+// included, or nothing when it was refused — the child then fails the same way this session would have.
+function handoff_environment(
+	environment: AgentEnvironment = process.env,
+): Readonly<Record<string, string>> {
+	const selected = resolve_provider(environment)
+
+	return selected.kind === 'provider' ? { [HANDED_PROVIDER_KEY]: selected.provider } : {}
+}
+
+const agent_provider = {
+	ANTHROPIC_PROVIDER,
+	CODEX_SESSION_KEY,
+	HANDED_PROVIDER_KEY,
+	OPENAI_PROVIDER,
+	PROVIDER_SCHEMA,
+	default_notice,
+	handoff_environment,
+	has_completion_callback,
+	rejection,
+	resolve_provider,
+	trimmed,
+	warn_of_default,
+}
+
+export type { AgentEnvironment, AgentProvider, ProviderResult, Rejected }
+export { agent_provider }