@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/josh/josh-commands-versioning.ts

@@ -3,16 +3,33 @@ import type { CommandEntry } from './josh-command-types'
 /* eslint-disable @typescript-eslint/naming-convention */
 const VERSIONING_COMMANDS: Record<string, CommandEntry> = {
 	bump: {
-		script: 'scripts/version/bump-version.ts',
+		script: 'scripts/version/bump-version-main.ts',
 		description: 'Bump package version',
 		category: 'Versioning',
 		reference: ['[major|minor|patch]', 'maintainer', ['files']],
+		usage: { examples: [{ arguments: 'major' }, { arguments: 'minor' }, { arguments: 'patch' }] },
 	},
 	version: {
 		script: 'scripts/version/version-check.ts',
 		description: 'Show kit versions; --upgrade updates the global and project install',
 		category: 'Versioning',
 		reference: ['[--upgrade]', 'developer', ['files', 'network', 'processes']],
+		usage: {
+			examples: [
+				{ arguments: '' },
+				{
+					arguments: '--upgrade',
+					note: 'upgrade global + project to latest, then re-run fix-gh-packages',
+				},
+			],
+			flags: [
+				{
+					names: ['--upgrade'],
+					description:
+						'upgrade both the global install (`pnpm add -g`) and the project devDependency (`pnpm add -D` + `fix-gh-packages`); already-current or not-installed targets are skipped.',
+				},
+			],
+		},
 	},
 	// A `script` entry, not a shell one: script paths resolve against the kit package root, so this
 	// keeps working from a consumer repo where the file lives under node_modules. The registry
@@ -24,6 +41,7 @@ const VERSIONING_COMMANDS: Record<string, CommandEntry> = {
 			'Check that every published dependency range still resolves for a consumer and no peer range falls below an installed toolkit',
 		category: 'Versioning',
 		reference: ['', 'developer', ['network']],
+		usage: { examples: [{ arguments: '' }] },
 	},
 	// The one place that decides a version. A `script` entry for the same
 	// reason `ranges` is one: script paths resolve against the kit package root, so it keeps working
@@ -33,15 +51,39 @@ const VERSIONING_COMMANDS: Record<string, CommandEntry> = {
 		description: 'Release the merges main has taken since the version last changed',
 		category: 'Versioning',
 		reference: ['[--dry-run]', 'maintainer', ['git', 'network', 'release']],
+		usage: {
+			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.',
+				},
+			],
+		},
 	},
 	// The read-only half of the one above. `release --dry-run` cannot
 	// answer this question: it refuses off the default branch and on a dirty tree, which is every
 	// position a run asks it from. A `script` entry for the same reason `release` is one.
 	'release:scope': {
-		script: 'scripts/release/release-scope-cli.ts',
+		script: 'scripts/release/release-scope-main.ts',
 		description: 'Say whether a release is owed, from the unreleased merges on main',
 		category: 'Versioning',
 		reference: ['[--json]', 'automation', ['none']],
+		usage: {
+			examples: [
+				{ arguments: '', note: '→ required | skip | unknown' },
+				{ arguments: '--json', note: '{"scope":"…","reason":"…"} on one line' },
+			],
+		},
 	},
 	// Run by the release workflows, kit's and the one sync distributes, after a tag has published.
 	// Settings come from the environment, so the workflow decides them.
@@ -50,6 +92,11 @@ const VERSIONING_COMMANDS: Record<string, CommandEntry> = {
 		description: 'Create the GitHub Release for a published tag, with generated notes',
 		category: 'Versioning',
 		reference: ['', 'automation', ['network', 'release']],
+		usage: {
+			examples: [
+				{ arguments: '', note: 'run by CI with GH_TOKEN, RELEASE_TAG and GITHUB_REPOSITORY set' },
+			],
+		},
 	},
 }
 /* eslint-enable @typescript-eslint/naming-convention */

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

@@ -1,5 +1,15 @@
 import { OPTIONAL_ENV_FILE_FLAGS, type CommandEntry } from './josh-command-types'
 
+const PR_TITLE = '"PR title #N"'
+const BODY_FILE_NOTE =
+	'(`-` reads stdin); use this whenever the body carries a backtick or `$`. Passing both forms is refused.'
+const ISSUE_URL = '--issue-url "https://..."'
+const REVIEW_ISSUE = '--issue 2325'
+const CHECK = '--check'
+const YES = '-y'
+const SKIP_COMMIT = '--skip-commit'
+const SKIP_PUSH = '--skip-push'
+
 const GIT_WORKFLOW_SCRIPT = 'scripts/git/git-workflow.ts'
 const GIT_MESSAGE_ARGUMENTS = '[-y] <message>'
 
@@ -10,6 +20,28 @@ const WORKFLOW_COMMANDS: Record<string, CommandEntry> = {
 		description: 'Git workflow helper',
 		category: 'Workflow',
 		reference: [GIT_MESSAGE_ARGUMENTS, 'developer', ['git', 'network']],
+		usage: {
+			examples: [
+				{ arguments: '', note: 'interactive' },
+				{ arguments: YES, note: 'unattended (no TTY required)' },
+				{ arguments: '-y "title"', note: 'set commit message prefix' },
+				{ arguments: '-y "<title> #<N>"', note: 'follow-up commit on the same branch' },
+				{
+					arguments: '-y --skip-commit --skip-push',
+					note: 'open the PR without committing/pushing',
+				},
+			],
+			flags: [
+				{
+					names: [YES, '--yes'],
+					description: 'run non-interactively; works without a TTY (agent or CI shell).',
+				},
+				{
+					names: [SKIP_COMMIT, SKIP_PUSH],
+					description: 'recover/open a PR without a new commit or push.',
+				},
+			],
+		},
 	},
 	pr: {
 		script: GIT_WORKFLOW_SCRIPT,
@@ -18,7 +50,8 @@ const WORKFLOW_COMMANDS: Record<string, CommandEntry> = {
 		// Not `GIT_MESSAGE_ARGUMENTS`: `-y` is already in the default arguments below, so advertising
 		// it would document a flag that cannot change what this command does.
 		reference: ['<message>', 'developer', ['network']],
-		default_script_arguments: ['-y', '--skip-commit', '--skip-push'],
+		default_script_arguments: [YES, SKIP_COMMIT, SKIP_PUSH],
+		usage: { examples: [{ arguments: '', note: 'open the PR for the current <N>-<slug> branch' }] },
 	},
 	// **The optional form, on both**. The mandatory `--env-file=.env` is resolved by node before the
 	// script's first line: on a machine with no `.env` it dies as `.env: not found` with exit code 9,
@@ -41,9 +74,37 @@ const WORKFLOW_COMMANDS: Record<string, CommandEntry> = {
 			['git', 'network', 'notifications'],
 		],
 		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+		usage: {
+			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: {
-		script: 'scripts/notify/telegram-test.ts',
+		script: 'scripts/notify/telegram-test-main.ts',
 		description: 'Send Telegram notification',
 		category: 'Workflow',
 		reference: [
@@ -52,6 +113,38 @@ const WORKFLOW_COMMANDS: Record<string, CommandEntry> = {
 			['notifications'],
 		],
 		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+		usage: {
+			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.',
+				},
+			],
+		},
 	},
 	// One observation-ledger sighting: the key's count, the append and the second-sighting verdict,
 	// which a run used to type as a `cat | grep -c` and judge by hand.
@@ -60,6 +153,21 @@ const WORKFLOW_COMMANDS: Record<string, CommandEntry> = {
 		description: 'Record an observation sighting and answer whether it is now filed',
 		category: 'Workflow',
 		reference: ['<key> <depth> <where> <what> [--checkout <path>]', 'automation', ['files']],
+		usage: {
+			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.",
+				},
+			],
+		},
 	},
 	// The observation ledger's commit path for the lines no run's own commit carried:
 	// a lane's lines sit in the primary checkout, which
@@ -69,20 +177,46 @@ const WORKFLOW_COMMANDS: Record<string, CommandEntry> = {
 		description: 'Commit the observation ledger as a pull request of its own, and merge it',
 		category: 'Workflow',
 		reference: ['', 'automation', ['git', 'network']],
+		usage: { examples: [{ arguments: '' }] },
 	},
 	// The one write path for a `/code-review` round's findings, plus the
 	// `--check` gate `followup` runs before it merges. It appends a `- rf:`
 	// line per finding — or one zero-finding line for a clean round — to the observation ledger, so
 	// `observations:flush` commits them and the recurrence count survives the run.
 	'review:record': {
-		script: 'scripts/review/review-record-cli.ts',
+		script: 'scripts/review/review-record-main.ts',
 		description: 'Record a review round’s findings, or check a round was recorded',
 		category: 'Workflow',
 		reference: [
-			'--issue <N> [--comment] [<category>:<severity>:<file> ...] | --check --issue <N>',
+			'--issue <N> [--comment | --interaction] [<category>:<severity>:<file>[ — <reason>] ...] | --check [--interaction] --issue <N>',
 			'automation',
 			['files', 'network'],
 		],
+		usage: {
+			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?' },
+				{
+					arguments: `${REVIEW_ISSUE} --interaction`,
+					note: 'the interaction review’s pass — a `- ri:` line',
+				},
+			],
+		},
+	},
+	// The reader over the durable review stop log: each finding that stopped a ship, with its file:line
+	// and first sentence, so a period's stops are classified without reading ship logs.
+	'review:stops': {
+		script: 'scripts/review/review-stops-cli.ts',
+		description:
+			'List the review findings that stopped a josh ship over a period, by kind, file:line and first sentence',
+		category: 'Workflow',
+		reference: ['[--period <days>]', 'developer', ['none']],
+		usage: { examples: [{ arguments: '--period 30', note: 'the last 30 days (default 7)' }] },
 	},
 	// The reader over what `review:record` wrote: each recurring category’s
 	// count, and the number of zero-finding rounds that distinguishes a quiet category from an unwatched one.
@@ -91,6 +225,7 @@ const WORKFLOW_COMMANDS: Record<string, CommandEntry> = {
 		description: 'Count review findings by category from the observation ledger',
 		category: 'Workflow',
 		reference: ['', 'developer', ['files']],
+		usage: { examples: [{ arguments: '' }] },
 	},
 	// After a behavior-change Issue merges, re-run its declared baseline and print before/after; a value
 	// that did not move appends a refuted-premise line to the observation ledger.
@@ -99,15 +234,17 @@ const WORKFLOW_COMMANDS: Record<string, CommandEntry> = {
 		description: 'Re-run a merged issue’s baseline command and print the before/after pair',
 		category: 'Workflow',
 		reference: ['<issue-number>', 'automation', ['network', 'processes', 'files']],
+		usage: { examples: [{ arguments: '2212' }] },
 	},
 	// A script rather than an `sh -c` chain, because it has a precondition to enforce: run inside a
 	// linked work tree it would hijack the default branch from every other one.
 	'main:sync': {
-		script: 'scripts/git/main-sync.ts',
+		script: 'scripts/git/main-sync-main.ts',
 		description:
 			'Checkout default branch, pull latest, and prune merged remote-gone branches (refuses inside a lane)',
 		category: 'Workflow',
 		reference: ['', 'developer', ['git', 'network']],
+		usage: { examples: [{ arguments: '' }] },
 	},
 	// A script rather than an `sh -c` chain, because the strategy has to be named rather than left to
 	// the caller's git configuration: a bare `git pull` aborts with `Need to specify how to reconcile
@@ -118,10 +255,11 @@ const WORKFLOW_COMMANDS: Record<string, CommandEntry> = {
 	// hooks — its regenerated catalog's commit runs them — which reserve themselves, and a weight here
 	// would set the held mark they inherit, folding the parallel hook tools into this one place.
 	'main:merge': {
-		script: 'scripts/git/main-merge.ts',
+		script: 'scripts/git/main-merge-main.ts',
 		description: 'Merge origin default branch into the current branch',
 		category: 'Workflow',
 		reference: ['', 'developer', ['git', 'network']],
+		usage: { examples: [{ arguments: '' }] },
 	},
 }
 /* eslint-enable @typescript-eslint/naming-convention */

package/scripts/josh/josh-environment-file.ts

@@ -1,4 +1,7 @@
+import { readFileSync } from 'node:fs'
+import { parseEnv } from 'node:util'
 import { ENV_FILE_NAME } from '#ports'
+import { OPTIONAL_ENV_FILE_FLAGS } from './josh-command-types'
 
 // Loading `.env` from inside a command, for the commands that must stay in-process.
 //
@@ -8,23 +11,60 @@ import { ENV_FILE_NAME } from '#ports'
 // command a hook fires on every `Bash` call, or one an unattended `epicrun` polls every sixty
 // seconds, cannot pay that, so it reads the file itself instead.
 //
-// `process.loadEnvFile` is node's own `--env-file` parser and keeps node's precedence: a value
+// `parseEnv` is node's own `--env-file` parser, and the loader keeps node's precedence: a value
 // already in the environment wins over the file's. A missing or unreadable file is swallowed,
 // exactly as `--env-file-if-exists` does.
 //
+// **A switch that turns a guard or a gate off is never taken from the file** (kit #4660): the run
+// can write `.env`, so a switch read from it would let the run switch off the guards that bind it. It
+// counts only from the environment the session was launched with — `JOSH_RULE_GUARD=off claude`. The
+// flag form is loaded through the same filter (`apply_node_flags`), so a process kit starts never
+// inherits a switch from the file either.
+//
 // **Call it only on the real command path** — inside the `import.meta.url` guard, or the hook's own
 // entry — never from a function a unit test calls, so a developer's own `.env` cannot decide what
 // the tests see.
-function load_environment_file(): void {
+
+// Every `JOSH_*_GUARD` switch, the hooks' `JOSH_*_FORCE` skips and the gate's `JOSH_SCOPED_GREEN`.
+const LAUNCH_ONLY_KEY = /^JOSH_(?:\w+_GUARD|\w+_FORCE|SCOPED_GREEN)$/u
+
+function is_launch_only_key(key: string): boolean {
+	return LAUNCH_ONLY_KEY.test(key)
+}
+
+function read_environment_file(): string {
 	try {
-		process.loadEnvFile(ENV_FILE_NAME)
+		return readFileSync(ENV_FILE_NAME, 'utf8')
 	} catch {
 		// No `.env` beside this project, or one this process may not read. The caller then reads from
 		// the environment alone, which is what it did before any file existed.
+		return ''
+	}
+}
+
+function load_environment_file(): void {
+	const entries = Object.entries(parseEnv(read_environment_file()))
+
+	for (const [key, value] of entries) {
+		if (!is_launch_only_key(key) && process.env[key] === undefined) process.env[key] = value
 	}
 }
 
+// The node flags a spawned command is started with. The `.env` flag is loaded here, into the
+// environment the child inherits, rather than handed to node, whose own loader cannot leave the
+// launch-only keys out.
+function apply_node_flags(flags: ReadonlyArray<string>): ReadonlyArray<string> {
+	const [environment_flag] = OPTIONAL_ENV_FILE_FLAGS
+
+	if (!flags.includes(environment_flag ?? '')) return flags
+
+	load_environment_file()
+
+	return flags.filter((flag) => flag !== environment_flag)
+}
+
 const josh_environment_file = {
+	apply_node_flags,
 	load_environment_file,
 }
 

package/scripts/josh/josh-in-process.ts

@@ -31,8 +31,8 @@ function bundled_script_path(package_directory: string, script: string): string
 
 // The file this dispatcher imports in its own process, or `undefined` to spawn tsx instead.
 // `tsx_arguments` are node flags the script needs *before* its own code runs — today every one of
-// them a form of `--env-file`, which has no in-process equivalent that reproduces node's own
-// parsing and precedence. Those commands (`doctor`, `latest:scope`, `followup`, `notify`) keep a
+// them a form of `--env-file`, which the dispatcher loads into the child's environment just before
+// it spawns (`josh_environment_file.apply_node_flags`). Those commands (`doctor`, `latest:scope`, `followup`, `notify`) keep a
 // process of their own; each runs at most a few times per run, so none of them is where the cost
 // this saves accumulates. Under plain node, which cannot load a `.ts` script at all, only a
 // pre-built command runs in-process; every other one keeps spawning tsx.

package/scripts/josh/josh-logic.ts

@@ -1,20 +1,22 @@
-import { existsSync, readFileSync } from 'node:fs'
+import { existsSync } from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { resolve_local_bin, resolve_package_bin } from '#scripts/build/local-bin'
 import { core_budget } from '#scripts/gate/core-budget'
+import { package_manifest } from '#scripts/lib/package-manifest'
 import { package_version_schema } from '#scripts/lib/schemas'
 import { resolve_spawn_exit } from '#scripts/lib/spawn-exit'
 import { execaSync } from 'execa'
 import { command_suggest } from './command-suggest'
+import { ALIASES } from './josh-aliases'
 import {
-	ALIASES,
 	CATEGORY_ORDER,
 	COMMAND_MAP,
 	type CommandCategory,
 	type CommandEntry,
 } from './josh-command-map'
 import { composite_arguments, USAGE_ERROR_EXIT_CODE } from './josh-composite-arguments'
+import { josh_environment_file } from './josh-environment-file'
 import { josh_in_process } from './josh-in-process'
 import { kit_only } from './kit-only'
 import { find_package_directory } from './package-directory'
@@ -24,7 +26,6 @@ const COLUMN_WIDTH = 26
 const ALIAS_PAD_WIDTH = 2
 const TSX_BIN = 'tsx'
 const TSX_PACKAGE = 'tsx'
-const PACKAGE_JSON = 'package.json'
 // Not an exit code the shell ever sees: `josh.ts` reads it as "no such command" and answers with
 // the listing on stderr. It is named because `run_command` now reports through a promise, where a
 // bare `-1` is one step further from the check that reads it.
@@ -71,9 +72,7 @@ function resolve_tsx_runner(): TsxRunner {
 }
 
 function read_package_version(): string {
-	const raw = readFileSync(path.join(PACKAGE_DIR, PACKAGE_JSON), 'utf8')
-
-	return package_version_schema.parse(JSON.parse(raw)).version
+	return package_manifest.read_manifest(PACKAGE_DIR, package_version_schema).version
 }
 
 const HEADER = `josh v${read_package_version()} — Joshua Folkken's dev toolkit`
@@ -165,16 +164,11 @@ function format_unknown_command(cmd: string): string {
 	return `Unknown command: ${cmd}.${hint} Run 'josh --help' for common commands or 'josh --all' for the full list.`
 }
 
-// A `.cmd` shim needs the win32 shell to be executable, but the node binary does not — and
-// running it through the shell would break on the spaces in a typical Windows install path.
-function should_use_shell(executable: string): boolean {
-	return process.platform === 'win32' && executable !== process.execPath
-}
-
+// No `shell` option on purpose: execa runs a Windows `.cmd` shim itself and escapes the arguments
+// for cmd.exe, which the shell would receive unescaped.
 function spawn_script(tsx_executable: string, script_arguments: Array<string>): number {
 	const result = execaSync(tsx_executable, script_arguments, {
 		stdio: 'inherit',
-		shell: should_use_shell(tsx_executable),
 		reject: false,
 	})
 
@@ -200,7 +194,7 @@ function spawn_script_entry(
 
 	return spawn_script(runner.executable, [
 		...runner.leading_arguments,
-		...(entry.tsx_arguments ?? []),
+		...josh_environment_file.apply_node_flags(entry.tsx_arguments ?? []),
 		script_path,
 		...script_arguments,
 	])
@@ -287,7 +281,7 @@ async function dispatch_entry(
 	return await core_budget.with_command_reservation(
 		weight,
 		async () => await run_entry(entry, subcommand_arguments),
-		{ memory_mb: declared(entry.memory_mb), command },
+		{ memory_mb: declared(entry.memory_mb), command, is_unit: entry.is_unit_claim },
 	)
 }
 
@@ -316,7 +310,8 @@ const josh_logic = {
 }
 
 export type { CommandEntry } from './josh-command-map'
-export { ALIASES, COMMAND_MAP } from './josh-command-map'
+export { ALIASES } from './josh-aliases'
+export { COMMAND_MAP } from './josh-command-map'
 export { SPAWN_ERROR_EXIT_CODE } from '#scripts/lib/spawn-exit'
 export { composite_arguments, USAGE_ERROR_EXIT_CODE } from './josh-composite-arguments'
 export {

package/scripts/josh/josh-run.ts

@@ -17,6 +17,8 @@ import { execa } from 'execa'
 //
 // **`timeout_ms` bounds a read made from inside a loop**: the step is killed and
 // its exit reads as a failure, so a hung network call ends a pass instead of the loop around it.
+//
+// **`environment` adds to the inherited one** for that one step — a switch the step's hooks read.
 
 const PNPM = 'pnpm'
 const JOSH = 'josh'
@@ -29,15 +31,31 @@ interface JoshResult {
 	err?: string
 }
 
+interface ExtraOptions {
+	timeout?: number
+	env?: Readonly<Record<string, string>>
+}
+
+function extra_options(
+	timeout_ms: number | undefined,
+	environment: Readonly<Record<string, string>> | undefined,
+): ExtraOptions {
+	return {
+		...(timeout_ms !== undefined && { timeout: timeout_ms }),
+		...(environment !== undefined && { env: environment }),
+	}
+}
+
 async function josh_run(
 	args: ReadonlyArray<string>,
 	should_forward_stderr = false,
 	timeout_ms?: number,
+	environment?: Readonly<Record<string, string>>,
 ): Promise<JoshResult> {
 	const result = await execa(PNPM, [JOSH, ...args], {
 		reject: false,
 		stderr: should_forward_stderr ? FORWARDED_STDERR : 'pipe',
-		...(timeout_ms !== undefined && { timeout: timeout_ms }),
+		...extra_options(timeout_ms, environment),
 	})
 
 	return {

package/scripts/josh/package-directory.ts

@@ -1,8 +1,6 @@
 import { existsSync } from 'node:fs'
-import path from 'node:path'
 import { ancestor_directories } from '#scripts/lib/ancestor-directories'
-
-const PACKAGE_JSON = 'package.json'
+import { package_manifest } from '#scripts/lib/package-manifest'
 
 // 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
@@ -12,7 +10,7 @@ const PACKAGE_JSON = 'package.json'
 function find_package_directory(start_directory: string): string {
 	return (
 		ancestor_directories.nearest(start_directory, (directory) =>
-			existsSync(path.join(directory, PACKAGE_JSON)),
+			existsSync(package_manifest.manifest_path(directory)),
 		) ?? start_directory
 	)
 }

package/scripts/josh/process-identity.ts

@@ -3,8 +3,8 @@ import { randomUUID } from 'node:crypto'
 import { readFileSync, rmSync } from 'node:fs'
 import { createServer, type Server } from 'node:net'
 import path from 'node:path'
+import { PLATFORM_TEMP_ROOT } from '#scripts/josh/platform-temporary'
 import { PROBE_TIMEOUT_MS } from '#scripts/lib/timeouts'
-import { PLATFORM_TEMP_ROOT } from './platform-temporary'
 
 // Whether the process a record names is still the one that wrote it.
 //
@@ -30,7 +30,7 @@ import { PLATFORM_TEMP_ROOT } from './platform-temporary'
 // `Tue Sep  8 09:15:33 2026` in one shell and `Tue Sep  8 02:15:33 2026` in another that exported
 // `TZ=UTC` — and a writer and reader disagreeing about `TZ` would read a live process as a stranger.
 // That failure is worse than the one this module fixes, because it fires on a gate that really is
-// running: `unit-worker-share` would sweep the marker of a live run and put every suite back on the
+// running: `unit-run-marker` would sweep the marker of a live run and put every suite back on the
 // whole machine, and `bench-guard` would clear the caches out from under a running gate. The probe
 // therefore pins `TZ` and `LC_ALL` rather than inheriting them.
 
@@ -237,11 +237,16 @@ function beacon_target(token: string): string | undefined {
 }
 
 // No status is a probe killed by its timeout or a signal — unknown, the same as its own timeout.
-function run_socket_probe(target: string): number | undefined {
+// `kill_after_ms` is a parameter so a test can ask what the probe itself reports for a socket
+// without a loaded machine's slow start turning the answer into the timeout's.
+function run_socket_probe(
+	target: string,
+	kill_after_ms: number = PROBE_TIMEOUT_MS,
+): number | undefined {
 	return (
 		spawnSync(process.execPath, ['-e', SOCKET_PROBE_SOURCE, target], {
 			stdio: 'ignore',
-			timeout: PROBE_TIMEOUT_MS,
+			timeout: kill_after_ms,
 		}).status ?? undefined
 	)
 }
@@ -359,6 +364,9 @@ function is_own_process(pid: number | undefined, recorded_start: string | undefi
 }
 
 const process_identity = {
+	PROBE_ENVIRONMENT,
+	START_PROBES,
+	START_TIME_FORMAT,
 	close_beacon,
 	is_live_beacon,
 	is_live_pid,
@@ -371,6 +379,7 @@ const process_identity = {
 	own_start,
 	read_start,
 	resolve_own_start,
+	run_socket_probe,
 }
 
 export { process_identity }

package/scripts/josh/run-record-path.ts

@@ -0,0 +1,15 @@
+// The run's own records — observations, accepted metrics — josh writes under the root `.josh/`
+// directory. `defect-report.ts`, `scoped-green.ts`, `test-read-map.ts`, `test-pinned-cache.ts` and
+// the background `josh test:pinned`'s tree key (`run-review-pinned-tree.ts`) read such a path as
+// bookkeeping, not as a change to the code — no test reads it.
+const RUN_RECORD_ROOT = '.josh/'
+
+function is_run_record(relative: string): boolean {
+	return relative.startsWith(RUN_RECORD_ROOT)
+}
+
+const run_record_path = {
+	is_run_record,
+}
+
+export { run_record_path }