@joshuafolkken/kit 1.1471.0 → 1.1514.0

package/scripts/josh/josh-usage-session.ts

@@ -0,0 +1,238 @@
+import type { CommandUsage } from './josh-command-types'
+
+// The usage of the commands `docs/josh-commands-run.md` documents from `run:progress` on — the run's
+// watchers, the lanes, and the session-budget and document-reading commands — keyed by command name.
+// The page's usage blocks are generated from this table and `josh help <command>` prints it, so an
+// example or a flag is written once, here (#3937). The run lifecycle before it is `josh-usage-run.ts`.
+const BARE = { arguments: '' }
+const PATH_DIR = '--path <dir>'
+
+/* eslint-disable @typescript-eslint/naming-convention */
+const SESSION_USAGE: Readonly<Record<string, CommandUsage>> = {
+	'run:progress': {
+		examples: [
+			{ arguments: '--output <path>' },
+			{ arguments: '--once', note: 'five labelled lines now, whatever the clock says' },
+			{ arguments: '--interval 20 --repo joshuafolkken/app-kit --hours 4' },
+		],
+		flags: [
+			{
+				names: ['--mark'],
+				description:
+					'record that a real report happened without printing a line (keeps the last line for `run:wake --list`).',
+			},
+			{
+				names: ['--path'],
+				description:
+					'print the ambient heartbeat log\'s path and exit. Every heartbeat line is mirrored there, so `tail -F "$(pnpm josh run:progress --path)"` follows the run across a `backlogrun` session cut. Reads no run state, so it answers in a lane child too.',
+			},
+			{
+				names: ['--interval <min>'],
+				description:
+					'silence interval (default 20; also `JOSH_PROGRESS_INTERVAL_MINUTES`, then `josh.progress_interval_minutes`).',
+			},
+			{
+				names: ['--wait'],
+				description:
+					'start once in the background: each report goes to the event stream and ambient log, never stdout; exits only on an arrival, `josh followup` ending the run, or `--hours`.',
+			},
+			{
+				names: ['--hours <n>'],
+				description: 'how long the watcher lives (default 8 with `--wait`, 1 otherwise).',
+			},
+			{ names: ['--repo <owner/name>'], description: 'scopes the read.' },
+		],
+	},
+	'run:board': {
+		examples: [
+			{ arguments: '', note: 'redraw until interrupted' },
+			{ arguments: '--once', note: 'one frame, then exit' },
+			{ arguments: '--chat', note: 'one frame for a chat, recorded as a progress report' },
+			{
+				arguments: '--every 5',
+				note: 'the --chat frame as a 📊 Progress Telegram every 5 minutes, until the run ends',
+			},
+		],
+		flags: [
+			{
+				names: ['--chat'],
+				description:
+					'answers a `backlogrun` progress question: the frame `--once` draws, with only `🧠` on the machine line and no escapes; it records the report as `run:progress --mark` does.',
+			},
+			{
+				names: ['--every <minutes>'],
+				description:
+					'sends the `--chat` frame as a `📊 Progress` Telegram now and every `<minutes>` until the run ends — only when a person asks for it.',
+			},
+		],
+	},
+	'run:watcher:guard': { examples: [BARE] },
+	'run:stranded': { examples: [BARE] },
+	'lane:open': { examples: [{ arguments: '1490', note: 'prints the lane directory on stdout' }] },
+	'lane:close': {
+		examples: [{ arguments: '1490' }, { arguments: '--all' }],
+		flags: [{ names: ['--all'], description: 'closes every lane.' }],
+	},
+	'lane:list': { examples: [BARE] },
+	'lane:prune': { examples: [BARE] },
+	'lane:output': {
+		examples: [
+			{ arguments: '1713 /abs/path/to/agent-7.jsonl', note: 'record it; prints the path back' },
+			{ arguments: '1713', note: 'read it; prints the path, or `none`' },
+		],
+	},
+	'lane:dispatch': {
+		examples: [
+			{
+				arguments: '1749',
+				note: "prints the child's pid; a refusal is an empty capture and exit 1",
+			},
+		],
+		flags: [
+			{
+				names: ['JOSH_{SCHEDULER,WORKER,REVIEWER}_MODEL'],
+				description:
+					'Claude Code role overrides; Anthropic defaults are respectively `claude-opus-5-5`, `claude-opus-5-5`, and `claude-opus-5-5`. Codex keeps its provider-specific model.',
+			},
+			{
+				names: ['JOSH_{SCHEDULER,WORKER,REVIEWER}_EFFORT'],
+				description:
+					'role effort overrides for either provider; defaults are `medium`, `medium`, and `high`.',
+			},
+			{
+				names: ['JOSH_REVIEWER_VERIFICATION_{MODEL,EFFORT}'],
+				description:
+					'review round 2 and later (the verification pass); Anthropic defaults are `claude-sonnet-5-5` / `high`, falling back to `JOSH_REVIEWER_*`.',
+			},
+		],
+	},
+	'lane:await': {
+		examples: [
+			{ arguments: '1749 1750', note: 'block until either lane completes' },
+			{
+				arguments: '1749 1750 --owner "$PPID"',
+				note: 'reclaim the carry record for a resumed conversation first',
+			},
+		],
+	},
+	'lane:launch': {
+		examples: [
+			{ arguments: '1749', note: 'every lane after the first' },
+			{
+				arguments: '1749 --stash "backlogrun: josh latest before lanes"',
+				note: 'the first lane only',
+			},
+		],
+	},
+	'lane:sample': { examples: [{ arguments: '', note: 'one machine-load reading' }] },
+	'lane:stats': {
+		examples: [{ arguments: '--period 7', note: "a 7-day period's stage medians and maxima" }],
+	},
+	cost: {
+		examples: [
+			{
+				arguments: '--cut',
+				note: 'compare billed input per request with the shared 135,000 context-cut threshold',
+			},
+			{ arguments: '--over <tokens>', note: 'compare with an explicit limit' },
+			{ arguments: `--cut ${PATH_DIR}`, note: 'Anthropic project or current OpenAI worktree' },
+		],
+		flags: [
+			{
+				names: [PATH_DIR],
+				description:
+					'selects another Anthropic project; OpenAI accepts only linked checkouts of the current project.',
+			},
+		],
+	},
+	'doc:section': {
+		examples: [
+			{ arguments: '<file.md> "<heading>"' },
+			{ arguments: 'backlogrun.md "The hand-off"' },
+		],
+	},
+	'read:set': {
+		examples: [
+			{ arguments: '', note: 'every entry point' },
+			{ arguments: 'backlogrun', note: 'one of them' },
+			{ arguments: 'backlogrun --json' },
+		],
+	},
+	'doc:read': {
+		examples: [
+			{ arguments: 'CLAUDE.md', note: 'under the cap: prints the document' },
+			{ arguments: 'backlogrun.md', note: 'over the cap: prints a directive, no content' },
+		],
+	},
+	'read:files': {
+		examples: [
+			{ arguments: 'a.ts b.ts c.ts', note: 'under the cap: prints each file under its own header' },
+			{
+				arguments: 'a.ts big.ts',
+				note: 'over the cap: prints a directive to Read them in one turn, no content',
+			},
+		],
+	},
+	'edit:files': {
+		examples: [
+			{
+				arguments: 'plan.txt',
+				note: 'applies every block in the plan, one line per edit reporting the outcome',
+			},
+			{ arguments: "- <<'EDITS'", note: 'plan from stdin, then EDITS' },
+		],
+	},
+	time: {
+		examples: [
+			{ arguments: '', note: 'the last run tree, wall clock and cost by role' },
+			{ arguments: '--run', note: 'the same run-tree scope, named explicitly' },
+			{ arguments: '--json', note: 'the same figures, machine-readable' },
+			{ arguments: PATH_DIR, note: "read another project's transcripts from this checkout" },
+		],
+		flags: [
+			{
+				names: ['--run'],
+				description:
+					'(default) the whole run tree, wall clock led beside dollars. It is the only scope; any other flag is a usage error (exit 1). History: `docs/maintainers/josh-commands-run-rationale.md` → "`josh cost` and `josh time` lost their report scopes".',
+			},
+			{
+				names: [PATH_DIR],
+				description:
+					'aim the read at another project (absolute path); keeps the `cwd` behavior when absent.',
+			},
+			{ names: ['--json'], description: 'the run tree, machine-readable.' },
+		],
+	},
+	'cost:audit': {
+		examples: [
+			{ arguments: '', note: 'the last 7 days against the 7 before' },
+			{ arguments: '--period 30', note: 'the last 30 days against the 30 before' },
+		],
+		flags: [
+			{
+				names: ['--period <days>'],
+				description: 'the length of each period, a positive whole number of days (default 7).',
+			},
+		],
+	},
+	retrospective: {
+		examples: [{ arguments: '', note: 'the digest for the run this checkout carries' }],
+	},
+	eval: {
+		examples: [
+			{ arguments: '', note: 'every scenario' },
+			{ arguments: 'consult-not-execute', note: 'one scenario by name' },
+		],
+		flags: [
+			{ names: ['JOSH_EVAL_MODEL'], description: 'the model to run against (default `sonnet`).' },
+			{
+				names: ['JOSH_EVAL_CONCURRENCY'],
+				description:
+					'how many sessions run at once (default `5`); a non-positive-integer value is refused.',
+			},
+		],
+	},
+}
+/* eslint-enable @typescript-eslint/naming-convention */
+
+export { SESSION_USAGE }

package/scripts/josh/josh-usage-workflow.ts

@@ -0,0 +1,212 @@
+import type { CommandUsage } from './josh-command-types'
+
+// The usage of the commands `docs/josh-commands-automation.md` documents under "Workflow",
+// "Versioning", "Maintenance" and "Git hooks", keyed by command name. The page's usage blocks are
+// generated from this table and `josh help <command>` prints it, so an example or a flag is written
+// once, here (#3939).
+const PR_TITLE = '"PR title #N"'
+const ISSUE_URL = '--issue-url "https://..."'
+const REVIEW_ISSUE = '--issue 2325'
+const CHECK = '--check'
+const JSON_FLAG = '--json'
+const BODY_FILE_NOTE =
+	'(`-` reads stdin); use this whenever the body carries a backtick or `$`. Passing both forms is refused.'
+
+/* eslint-disable @typescript-eslint/naming-convention */
+const WORKFLOW_USAGE: Readonly<Record<string, CommandUsage>> = {
+	followup: {
+		examples: [
+			{ arguments: PR_TITLE, note: 'merges (default)' },
+			{ arguments: String.raw`${PR_TITLE} --notify-message "Implemented X:\n- change 1"` },
+			{ arguments: `${PR_TITLE} --notify-message-file completion.md` },
+			{ arguments: `${PR_TITLE} --ai-review-ignore-reason "false positive"` },
+			{ arguments: `${PR_TITLE} --no-merge`, note: 'do the work, leave the PR open' },
+		],
+		flags: [
+			{
+				names: ['--no-merge'],
+				description:
+					'do the follow-up work but do not merge; leaves the PR open (the only flag that stops the merge). `--merge` is a deprecated no-op. A PR already merged by hand skips the CI wait, the AI-review scan and the merge and runs only the post-merge tail; a completion report already on the Issue is not posted again.',
+			},
+			{
+				names: ['--notify-message'],
+				description: 'inline completion body; `\\n` expands to newlines.',
+			},
+			{
+				names: ['--notify-message-file'],
+				description: `read the completion body from a file ${BODY_FILE_NOTE}`,
+			},
+			{
+				names: ['--ai-review-ignore-reason'],
+				description: 'reason to dismiss an AI-review finding.',
+			},
+		],
+	},
+	notify: {
+		examples: [
+			{ arguments: String.raw`--task-type planning ${ISSUE_URL} --body="- bullet 1\n- bullet 2"` },
+			{
+				arguments: `--task-type confirmation ${ISSUE_URL} --body-file r.md --recommended "Go" --alternative "Wait"`,
+			},
+		],
+		flags: [
+			{
+				names: ['--task-type'],
+				description:
+					'one of `planning` 📋, `completion` ✅, `failure` ❌, `warning` ⚠️, `kickoff_retry` 🔄, `confirmation` ⏸️. Do not send `completion` or `warning` by hand — `josh followup` sends them.',
+			},
+			{
+				names: ['--body', "--body=$'…'"],
+				description: "inline body; use `--body=$'…'` when it starts with `-`.",
+			},
+			{ names: ['--body-file'], description: `read the body from a file ${BODY_FILE_NOTE}` },
+			{
+				names: ['--repo-name', '--issue-url', '--pr-url'],
+				description:
+					'header repository, resolved in that order, then the working directory. The issue title is read from `--issue-url`.',
+			},
+			{
+				names: ['--recommended', '--alternative'],
+				description:
+					'the choices appended under `JOSH_SESSION_LANG` headings; `--recommended` is required for `confirmation`, `--alternative` is repeatable.',
+			},
+		],
+	},
+	'observations:flush': { examples: [{ arguments: '' }] },
+	'measure:rerun': { examples: [{ arguments: '2212' }] },
+	'review:record': {
+		examples: [
+			{ arguments: `${REVIEW_ISSUE} bug-risks:medium:src/foo.ts:42 tests:low:a.test.ts` },
+			{ arguments: REVIEW_ISSUE, note: 'a zero-finding round — records one `none` line' },
+			{
+				arguments: `${REVIEW_ISSUE} --comment`,
+				note: 'a round that passed after the PR opened — an Issue comment, no append',
+			},
+			{ arguments: `${CHECK} ${REVIEW_ISSUE}`, note: 'the merge gate: was it recorded?' },
+		],
+	},
+	bump: { examples: [{ arguments: 'major' }, { arguments: 'minor' }, { arguments: 'patch' }] },
+	release: {
+		examples: [
+			{ arguments: '' },
+			{ arguments: '--dry-run', note: 'count and report, write nothing' },
+		],
+		flags: [
+			{
+				names: ['--dry-run'],
+				description:
+					'count and report only; writes nothing, fetches nothing, and creates no work tree.',
+			},
+			{
+				names: ['--help', '-h'],
+				description:
+					'print the usage line and exit 0 without fetching or releasing. Any other argument is refused with the usage line and a non-zero exit, before anything is fetched.',
+			},
+		],
+	},
+	'release:scope': {
+		examples: [
+			{ arguments: '', note: '→ required | skip | unknown' },
+			{ arguments: '--json', note: '{"scope":"…","reason":"…"} on one line' },
+		],
+	},
+	'ruleset:check': {
+		examples: [
+			{ arguments: '', note: 'report only' },
+			{ arguments: '--apply', note: 'add the missing checks to the existing rule' },
+		],
+		flags: [
+			{
+				names: ['--apply'],
+				description:
+					"append the missing checks to the ruleset's required-checks rule (or to the branch protection's contexts). It never creates a ruleset: with none, create one under Settings → Rules → Rulesets, then rerun. Writing a repository setting needs admin access, so only this flag writes — `josh sync` and `josh doctor` never do.",
+			},
+		],
+	},
+	'audit:provision': {
+		examples: [
+			{ arguments: '', note: 'no-op if a scanner is already present' },
+			{ arguments: '--force', note: 'ignore backoff, allow a longer download' },
+		],
+		flags: [
+			{
+				names: ['--force'],
+				description:
+					'ignore the 6-hour failure backoff and allow a longer download window; the command to run after fixing a network problem.',
+			},
+		],
+	},
+	'reconcile-templates': {
+		examples: [
+			{ arguments: '', note: 'regenerate copy templates + record tripwire hashes' },
+			{ arguments: CHECK, note: 'verify templates are in sync; non-zero on drift' },
+		],
+		flags: [
+			{
+				names: [CHECK],
+				description:
+					'verify only; exits non-zero on drift. A pre-commit hook runs this when a tracked source or copy template is staged.',
+			},
+		],
+	},
+	'pre-push-unit': { examples: [{ arguments: '' }] },
+	'reserved-run': {
+		examples: [
+			{ arguments: '2 -- pnpm install', note: 'hold 2 cores while installing' },
+			{ arguments: '1 -- pnpm josh audit', note: 'hold 1 core while scanning' },
+		],
+	},
+	'pre-commit-type-check': { examples: [{ arguments: '' }] },
+	'pr:classification': {
+		examples: [{ arguments: '', note: 'run by CI on a pull request; fails without one label' }],
+	},
+	'observation:record': {
+		examples: [
+			{ arguments: "flaky-e2e d1 'tests/e2e/login.test.ts' 'times out on CI only'" },
+			{
+				arguments: "flaky-e2e d1 'src/app.ts' 'fails there too' --checkout ~/Development/app",
+				note: "another repository's ledger",
+			},
+		],
+		flags: [
+			{
+				names: ['--checkout <path>'],
+				description: "count and append in that repository's `.josh/observations/` instead.",
+			},
+		],
+	},
+	'release:github': {
+		examples: [
+			{ arguments: '', note: 'run by CI with GH_TOKEN, RELEASE_TAG and GITHUB_REPOSITORY set' },
+		],
+	},
+	'latest:scope': {
+		examples: [
+			{ arguments: '', note: 'required or skip, the reason on stderr' },
+			{ arguments: '--record', note: 'note a finished josh latest run' },
+			{ arguments: JSON_FLAG, note: 'the verdict and the reason as JSON' },
+		],
+		flags: [
+			{ names: ['--record'], description: 'write the completion record `josh latest` ends with.' },
+			{ names: [JSON_FLAG], description: 'emit the verdict and its reason as JSON.' },
+		],
+	},
+	'latest:guard': { examples: [{ arguments: '', note: 'refuses inside a lane' }] },
+	'prevent-main-commit': { examples: [{ arguments: '', note: 'run by the pre-commit hook' }] },
+	'check-commit-message': {
+		examples: [{ arguments: '.git/COMMIT_EDITMSG', note: 'run by the commit-msg hook' }],
+	},
+	'secretlint-scan': {
+		examples: [{ arguments: 'src/app.ts .env.example', note: 'the staged paths' }],
+	},
+	'pre-commit-lint': {
+		examples: [
+			{ arguments: 'cspell src/app.ts' },
+			{ arguments: 'prettier src/app.ts' },
+			{ arguments: 'eslint src/app.ts' },
+		],
+	},
+}
+/* eslint-enable @typescript-eslint/naming-convention */
+
+export { WORKFLOW_USAGE }

package/scripts/josh/josh.ts

@@ -1,4 +1,5 @@
 import { doctor_consumer } from '#scripts/doctor/doctor-consumer'
+import { command_usage } from './command-usage'
 import { find_package_directory, josh_logic, UNKNOWN_COMMAND_EXIT_CODE } from './josh-logic'
 
 const ARGV_OFFSET = 2
@@ -12,10 +13,6 @@ const HELP_COMMANDS: ReadonlySet<string> = new Set(['help', '--help', '-h'])
 // A bare `--all` in the command slot is a help request, not a command.
 const ALL_FLAG = '--all'
 
-function print_help(is_all: boolean, is_consumer: boolean): void {
-	console.info(josh_logic.format_help(is_all, is_consumer))
-}
-
 // Both halves go to stderr. The help listing is a diagnosis here, not the answer, and a shell
 // wiring `--port $(josh port dev)` reads stdout alone, so a command name this kit cannot resolve
 // has to leave that stream empty rather than substitute the whole toolkit index (#825).
@@ -24,6 +21,18 @@ function handle_unknown(cmd: string): never {
 	process.exit(1)
 }
 
+// `josh help <command>` prints that one command's usage — the text its reference page renders
+// (#3932); a flag in the topic slot is still a listing request (`josh --help --all`).
+function print_help(is_all: boolean, is_consumer: boolean, topic: string | undefined): void {
+	if (topic === undefined || topic.startsWith('-')) {
+		console.info(josh_logic.format_help(is_all, is_consumer))
+
+		return
+	}
+
+	console.info(command_usage.format_command_help(topic) ?? handle_unknown(topic))
+}
+
 // `process.exit` truncates a piped stdout at its buffer size, and the output at risk is the script's
 // own — `scripts/gate/verification-gate.ts` writes its per-check blocks
 // and its failure summary through this process, and sets `process.exitCode` rather than exiting for
@@ -44,7 +53,7 @@ async function main(): Promise<void> {
 	const is_consumer = doctor_consumer.is_kit_consumer(find_package_directory(process.cwd()))
 
 	if (!cmd || cmd === ALL_FLAG || HELP_COMMANDS.has(cmd)) {
-		print_help(is_all, is_consumer)
+		print_help(is_all, is_consumer, process.argv[ARGV_OFFSET + 1])
 
 		return
 	}

package/scripts/josh/package-directory.ts

@@ -0,0 +1,20 @@
+import { existsSync } from 'node:fs'
+import path from 'node:path'
+import { ancestor_directories } from '#scripts/lib/ancestor-directories'
+
+const PACKAGE_JSON = 'package.json'
+
+// Resolve the kit package root by ascending to the nearest package.json. This works both
+// from the bundled dist/josh.js (one level under the root) and from the tsx source at
+// scripts/josh/ (two levels), so this file's depth no longer has to be hard-coded.
+// A leaf apart from `josh-logic`, so a bundled command can import it without pulling the
+// dispatcher's main-guarded closure into its single-file bundle.
+function find_package_directory(start_directory: string): string {
+	return (
+		ancestor_directories.nearest(start_directory, (directory) =>
+			existsSync(path.join(directory, PACKAGE_JSON)),
+		) ?? start_directory
+	)
+}
+
+export { find_package_directory }

package/scripts/lane/lane-capacity.ts

@@ -73,8 +73,14 @@ function seated_limit(limit: number): number {
 // Never negative: a repository holding more `in-progress` issues than the limit allows — the limit
 // was lowered, or a stale label outlived its run — has no free lane, and a negative count read as
 // "how many to offer" would be a slice nobody meant.
-function free_lanes(limit: number, occupied: number): number {
-	return Math.max(NO_LANES, seated_limit(limit) - occupied)
+//
+// **A lane that holds no place under the limit still holds its port seat** (joshuafolkken/kit#3967):
+// `seated` counts every open lane, so the free count never offers more launches than seats are left.
+function free_lanes(limit: number, occupied: number, seated = occupied): number {
+	const by_limit = seated_limit(limit) - occupied
+	const by_seats = lane_seed_policy.LAST_LANE_SEAT - seated
+
+	return Math.max(NO_LANES, Math.min(by_limit, by_seats))
 }
 
 const lane_capacity = {

package/scripts/lane/lane-check-stats.ts

@@ -0,0 +1,56 @@
+import { lane_ledger, type GateCheckRecord, type GateEntry, type LedgerEntry } from './lane-ledger'
+import { lane_stage_stats } from './lane-stage-stats'
+import { lane_stats, type StatsWindow } from './lane-stats'
+
+// Which check a gate waited on: the ledger's per-check rows of one period reduced to one row per check
+// — median, maximum, how many runs and how many were reused — printed last by `josh lane:stats`. The
+// rows are in the order the checks first appear.
+//
+// **A reused check is counted, never timed.** It started no process, so its zero would pull the median
+// toward a check that never ran; a check with only reused rows prints `not measured`.
+
+const MS_PER_SECOND = 1000
+const DECIMALS = 1
+const COLUMNS = ['check', 'median (s)', 'max (s)', 'runs', 'reused'] as const
+
+function is_gate(entry: LedgerEntry): entry is GateEntry {
+	return entry.kind === lane_ledger.KIND.GATE
+}
+
+function cell(milliseconds: number | undefined): string {
+	return milliseconds === undefined
+		? lane_stage_stats.NOT_MEASURED
+		: (milliseconds / MS_PER_SECOND).toFixed(DECIMALS)
+}
+
+function check_row(label: string, checks: ReadonlyArray<GateCheckRecord>): string {
+	const runs = checks.filter((check) => check.label === label)
+	const timed = runs.filter((check) => check.is_reused !== true).map((check) => check.elapsed_ms)
+
+	return lane_stats.to_row([
+		label,
+		cell(lane_stats.median(timed)),
+		cell(lane_stats.peak(timed)),
+		String(runs.length),
+		String(runs.length - timed.length),
+	])
+}
+
+// The period's table: `entries` is the whole ledger, filtered here to `window`.
+function table(entries: ReadonlyArray<LedgerEntry>, window: StatsWindow): string {
+	const checks = lane_stats
+		.in_window(entries, window)
+		.filter(is_gate)
+		.flatMap((gate) => gate.checks ?? [])
+	const labels = [...new Set(checks.map((check) => check.label))]
+
+	return [
+		lane_stats.to_row(COLUMNS),
+		lane_stats.to_row(COLUMNS.map(() => '---')),
+		...labels.map((label) => check_row(label, checks)),
+	].join('\n')
+}
+
+const lane_check_stats = { table }
+
+export { lane_check_stats }

package/scripts/lane/lane-child-invocation.ts

@@ -1,13 +1,17 @@
+import { agent_role_profile } from '#scripts/agent/agent-role-profile'
 import { issue_cite } from '#scripts/issue/issue-cite'
 import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { run_ship_next, type ShipResume } from '#scripts/run/ship/run-ship-next'
 import type { Stage } from '#scripts/run/ship/run-ship-stage'
+import { run_ship_stop_context, type StopContext } from '#scripts/run/ship/run-ship-stop-context'
 
 interface ShipStop extends ShipResume {
 	stage: Stage
+	context?: StopContext
 }
 
 const CHILD_INVOCATION = 'fullrun'
+const LINE_BREAK = '\n'
 // What a brokered reviewer's prompt ends with, so the one pattern below finds it too.
 const REVIEW_INVOCATION = 'the reviewer of lane'
 const RESUME_GUIDE = '.claude/skills/workflow-commands/pre-gate-cut.md'
@@ -79,14 +83,41 @@ function outage_resume_invocation(issue: string): string {
 // **A known stage puts the next command in the prompt**, so the relaunched
 // session runs it rather than re-deriving it from `chain-rule.md`. An OpenAI lane's supervisor sees only
 // that the ship failed, not where, so without a stage the prompt points at `run:step` as before.
+//
+// **A stop that carries its context puts it in the prompt too** — the failed output's
+// tail and the changed files (`run-ship-stop-context.ts`), so the session starts at the fix rather than
+// at `josh ship --log` and `git diff` (joshuafolkken/kit#3923).
+//
+// The context gets what the rest of the prompt leaves of the one argv element's cap, so the whole
+// prompt still launches (joshuafolkken/kit#3964).
+function known_stop_lines(
+	issue: string,
+	stop: ShipStop,
+	frame: ReadonlyArray<string>,
+): ReadonlyArray<string> {
+	const { context } = stop
+	const is_excerpted = run_ship_stop_context.has_excerpt(context)
+	const next = run_ship_next.next_step(issue, stop.stage, stop, is_excerpted)
+
+	if (context === undefined) return [next]
+
+	const fixed = [...frame, next].join(LINE_BREAK).length + LINE_BREAK.length
+	const budget = agent_role_profile.MAX_VALUE_LENGTH - fixed
+
+	return [next, run_ship_stop_context.describe(issue, context, budget)]
+}
+
 function ship_stop_invocation(issue: string, stop?: ShipStop): string {
 	const opening = `Resuming the lane child for issue ${issue_cite.plain(issue)} after its detached ship supervisor stopped at a failed stage — do not re-read the workflow-commands entry documents (SKILL.md, fullrun.md).`
-	const next =
+	const closing = `Do not re-plan or re-implement what is already on the branch. ${child_invocation(issue)}`
+	const middle =
 		stop === undefined
-			? `Run \`pnpm josh run:step ${issue}\` and read the stopped report it names, fix what stopped the ship, then hand the region back per chain-rule.md.`
-			: run_ship_next.next_step(issue, stop.stage, stop)
+			? [
+					`Run \`pnpm josh run:step ${issue}\` and read the stopped report it names, fix what stopped the ship, then hand the region back per chain-rule.md.`,
+				]
+			: known_stop_lines(issue, stop, [opening, closing])
 
-	return `${opening} ${next} Do not re-plan or re-implement what is already on the branch. ${child_invocation(issue)}`
+	return [opening, ...middle, closing].join(LINE_BREAK)
 }
 
 const lane_child_invocation = {

package/scripts/lane/lane-dispatch.ts

@@ -7,7 +7,7 @@ import { IN_PROGRESS_LABEL } from '#scripts/issue/issue-labels'
 import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { session_cite } from '#scripts/issue/session-cite'
 import { telegram_notify } from '#scripts/notify/telegram-notify'
-import { detached_launch } from '#scripts/run/detached-launch'
+import { detached_launch, type LaunchArgv } from '#scripts/run/detached-launch'
 import { run_event_stream } from '#scripts/run/event/run-event-stream'
 import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
 import { run_ending } from '#scripts/run/run-ending'
@@ -197,7 +197,7 @@ function existing_dispatch(request: StartRequest): DispatchOutcome | undefined {
 	return dispatched_of(request, active.pid, [])
 }
 
-function launch_argv(request: StartRequest, nonce: string | undefined): AgentArgv {
+function launch_argv(request: StartRequest, nonce: string | undefined): LaunchArgv {
 	if (request.profile.provider !== 'openai') return request.argv
 	if (nonce === undefined) throw new Error('OpenAI supervisor nonce is missing')
 
@@ -404,7 +404,7 @@ function log_sentence(outcome: Dispatched, issue: string): string {
 		return ` Its output is NOT being kept — ${outcome.notes.join(NOTE_SEPARATOR)} — so ${outcome.log_path} will not grow and the process trace is the only answer: ${poll}.`
 	}
 
-	return ` It writes to ${outcome.log_path}. To poll it, ${poll}.`
+	return ` It writes to ${outcome.log_path}. Wait on it with \`pnpm josh lane:await ${issue} --owner "$PPID"\` in the background and end the turn; once that output falls silent, ${poll}.`
 }
 
 // Whether this dispatch resumed the disconnected child's session or started fresh — the report the