@joshuafolkken/kit 1.1387.0 → 1.1453.0

package/scripts/issue/issue-watch.ts

@@ -0,0 +1,240 @@
+import { git_gh_api_path } from '#scripts/gh/git-gh-api-path'
+import { git_gh_conditional } from '#scripts/gh/git-gh-conditional'
+import { git_gh_issue_read } from '#scripts/gh/git-gh-issue-read'
+import { git_command } from '#scripts/git/git-command'
+import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { json_value } from '#scripts/lib/json-value'
+import { z } from 'zod'
+import { issue_watch_diff, type WatchSnapshot } from './issue-watch-diff'
+
+// The record of what a run last read of its issue, and the poll that compares the issue against it.
+//
+// **The baseline is written where the run reads the issue** — `josh run:entry`, which prints the body
+// and every comment — so it is the same for a dispatched lane child and a `fullrun` in a person's own
+// checkout, and a resume that prints nothing keeps the baseline it had. One record per checkout,
+// keyed on its root like the review attestation, carries the issue number, so the hook needs no other
+// way to learn which issue the session works on.
+//
+// **A poll is a conditional request.** The issue object's ETag changes with its body and with its
+// comment count, so a 304 there means neither moved and the comments are not read at all.
+
+const RECORD_PREFIX = 'josh-issue-watch-'
+const CLOSED_STATE = 'closed'
+
+const record_schema = z.object({
+	issue: z.string(),
+	body: z.string(),
+	last_comment_id: z.number(),
+	acknowledged_at: z.string(),
+	checked_at: z.string(),
+	etag: z.string().optional(),
+	pending: z.string().optional(),
+	shown: z.string().optional(),
+})
+
+const issue_schema = z.looseObject({ body: z.string().nullish(), state: z.string() })
+
+type WatchRecord = z.infer<typeof record_schema>
+
+type Fetched =
+	| { kind: 'unchanged' }
+	| { kind: 'unreadable' }
+	| { kind: 'closed' }
+	| { kind: 'read'; snapshot: WatchSnapshot; etag: string | undefined }
+
+const UNREADABLE: Fetched = { kind: 'unreadable' }
+
+function record_path(root: string = PROJECT_ROOT): string {
+	return stamp_file.stamp_path(RECORD_PREFIX, root)
+}
+
+function read_record(root?: string): WatchRecord | undefined {
+	const raw = stamp_file.read_stamp_text(record_path(root))
+
+	return raw === undefined ? undefined : json_value.parse_with(raw, record_schema)
+}
+
+function write_record(record: WatchRecord, root?: string): WatchRecord {
+	stamp_file.replace_stamp(record_path(root), record)
+
+	return record
+}
+
+function clear(root?: string): void {
+	stamp_file.remove_stamp(record_path(root))
+}
+
+interface FetchRequest {
+	issue: string
+	etag?: string | undefined
+	timeout_ms?: number | undefined
+}
+
+async function read_snapshot(
+	request: FetchRequest,
+	body: string,
+	etag: string | undefined,
+): Promise<Fetched> {
+	const comments = issue_watch_diff.parse_comments(
+		await git_gh_issue_read.issue_list_comments(request.issue, request.timeout_ms),
+	)
+
+	return comments === undefined ? UNREADABLE : { kind: 'read', snapshot: { body, comments }, etag }
+}
+
+async function fetch_issue(request: FetchRequest): Promise<Fetched> {
+	const read = await git_gh_conditional.read_conditional(
+		git_gh_api_path.issue_api_path(request.issue),
+		request.etag,
+		request.timeout_ms,
+	)
+
+	if (read.kind !== 'changed') return read
+
+	const fields = json_value.parse_with(read.body, issue_schema)
+
+	if (fields === undefined) return UNREADABLE
+	if (fields.state === CLOSED_STATE) return { kind: 'closed' }
+
+	return await read_snapshot(request, fields.body ?? '', read.etag)
+}
+
+// `acknowledged_at` is when a person's update was last taken in — the baseline's own read, or an
+// acknowledgement that had something to take in. The review attestation compares it with the brief.
+function fresh_record(
+	issue: string,
+	fetched: Extract<Fetched, { kind: 'read' }>,
+	now: Date,
+	acknowledged_at: string = now.toISOString(),
+): WatchRecord {
+	const baseline = issue_watch_diff.baseline_of(fetched.snapshot)
+	const checked_at = now.toISOString()
+
+	return { issue, ...baseline, acknowledged_at, checked_at, etag: fetched.etag }
+}
+
+// Called by `josh run:entry` once it has printed the issue. `false` when the issue could not be read,
+// which leaves no record — a watch with no baseline would call the whole issue unread.
+async function record_baseline(
+	issue: string,
+	root?: string,
+	now: Date = new Date(),
+): Promise<boolean> {
+	const fetched = await fetch_issue({ issue })
+
+	if (fetched.kind !== 'read') return false
+
+	write_record(fresh_record(issue, fetched, now), root)
+
+	return true
+}
+
+// The `_here` forms key the record on the repository root rather than `process.cwd()`, the same reason
+// `review_attest.check_here` does: a run started from a subdirectory must find the record it wrote.
+async function record_baseline_here(issue: string): Promise<boolean> {
+	return await record_baseline(issue, await git_command.repository_root())
+}
+
+async function clear_here(): Promise<void> {
+	clear(await git_command.repository_root())
+}
+
+function with_fetched(record: WatchRecord, fetched: Fetched, checked_at: string): WatchRecord {
+	if (fetched.kind !== 'read') return { ...record, checked_at }
+
+	const pending = issue_watch_diff.unread_diff(record, fetched.snapshot)
+
+	return { ...record, checked_at, etag: fetched.etag, pending }
+}
+
+interface PollOptions {
+	interval_ms: number
+	timeout_ms?: number
+	now?: Date
+}
+
+function is_due(record: WatchRecord, options: PollOptions, now: Date): boolean {
+	return now.getTime() - Date.parse(record.checked_at) >= options.interval_ms
+}
+
+async function refresh(
+	record: WatchRecord,
+	options: PollOptions,
+	now: Date,
+	root?: string,
+): Promise<WatchRecord | undefined> {
+	const fetched = await fetch_issue({
+		issue: record.issue,
+		etag: record.etag,
+		timeout_ms: options.timeout_ms,
+	})
+
+	if (fetched.kind === 'closed') {
+		clear(root)
+
+		return undefined
+	}
+
+	return write_record(with_fetched(record, fetched, now.toISOString()), root)
+}
+
+// The checkout's record, polled when the last poll is at least `interval_ms` old. `undefined` when no
+// run recorded a baseline here, or the issue has closed — a closed issue ends its watch.
+async function poll(options: PollOptions, root?: string): Promise<WatchRecord | undefined> {
+	const record = read_record(root)
+	const now = options.now ?? new Date()
+
+	if (record === undefined || !is_due(record, options, now)) return record
+
+	return await refresh(record, options, now, root)
+}
+
+// Marks a pending update shown, so the hook stops once per update rather than on every call.
+function mark_shown(record: WatchRecord, root?: string): WatchRecord {
+	return write_record({ ...record, shown: record.pending }, root)
+}
+
+interface Acknowledged {
+	issue: string
+	diff: string | undefined
+}
+
+// `josh issue:ack`: read the issue as it is now, return what changed since the baseline, and make
+// that the new baseline. **What is returned is exactly what is acknowledged** — the read and the new
+// baseline are the same snapshot, so an update landing between the two cannot be acknowledged unseen.
+async function acknowledge(
+	root?: string,
+	now: Date = new Date(),
+): Promise<Acknowledged | undefined> {
+	const record = read_record(root)
+
+	if (record === undefined) return undefined
+
+	const fetched = await fetch_issue({ issue: record.issue })
+
+	if (fetched.kind !== 'read') return undefined
+
+	const diff = issue_watch_diff.unread_diff(record, fetched.snapshot)
+
+	const acknowledged_at = diff === undefined ? record.acknowledged_at : now.toISOString()
+
+	write_record(fresh_record(record.issue, fetched, now, acknowledged_at), root)
+
+	return { issue: record.issue, diff }
+}
+
+const issue_watch = {
+	acknowledge,
+	clear,
+	clear_here,
+	mark_shown,
+	poll,
+	read_record,
+	record_baseline,
+	record_baseline_here,
+	record_path,
+}
+
+export type { Acknowledged, PollOptions, WatchRecord }
+export { issue_watch }

package/scripts/issue/measure-rerun-cli.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env tsx
 import { execSync } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
+import { gh_author_association } from '#scripts/gh/gh-author-association'
 import { git_gh_issue_read } from '#scripts/gh/git-gh-issue-read'
 import { parse_json_object_or_undefined } from '#scripts/git/parse-json-array'
 import { issue_number_shape } from '#scripts/issue/issue-number-shape'
@@ -24,8 +25,6 @@ import { session_cite } from './session-cite'
 const FAILURE_EXIT_CODE = 1
 const ARGV_OFFSET = 2
 const ISSUE_FIELDS = 'body,author_association'
-const TRUSTED_ASSOCIATIONS: ReadonlySet<string> = new Set(['OWNER', 'MEMBER', 'COLLABORATOR'])
-const TRUSTED_LIST = [...TRUSTED_ASSOCIATIONS].join(' / ')
 const UNKNOWN_ASSOCIATION = 'unknown'
 const USAGE = 'Usage: josh measure:rerun <issue-number>'
 const NO_BASELINE = 'no `command → value` baseline found in ## ベースライン — nothing to re-run'
@@ -100,10 +99,10 @@ async function read_trusted_body(issue_number: string): Promise<BodyRead> {
 
 	const association = issue.author_association ?? UNKNOWN_ASSOCIATION
 
-	if (!TRUSTED_ASSOCIATIONS.has(association)) {
+	if (!gh_author_association.is_trusted(association)) {
 		return {
 			kind: 'refused',
-			reason: `refusing to run the baseline of ${session_cite.issue(issue_number)}: its author is ${association}, not ${TRUSTED_LIST}`,
+			reason: `refusing to run the baseline of ${session_cite.issue(issue_number)}: its author is ${association}, not ${gh_author_association.TRUSTED_LIST}`,
 		}
 	}
 

package/scripts/josh/josh-command-map.ts

@@ -54,6 +54,7 @@ const ALIASES: Record<string, string> = {
 	pf: 'profile',
 	st: 'start',
 	sy: 'sync',
+	un: 'uninstall',
 	rmi: 'registry:migrate',
 	g: 'git',
 	gp: 'pr',
@@ -79,9 +80,12 @@ const ALIASES: Record<string, string> = {
 	rvf: 'review:findings',
 	ruv: 'rule:value',
 	ev: 'eval',
+	fr: 'fresh:run',
+	as: 'auth:setup',
 	lsm: 'lane:sample',
 	lst: 'lane:stats',
 	lli: 'lane:limit',
+	lrs: 'lane:restart',
 	blr: 'backlogrun',
 }
 

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

@@ -61,6 +61,17 @@ const AI_COMMANDS: Record<string, CommandEntry> = {
 		category: 'AI tools',
 		reference: ['[--exclude <n>[,<n>...]] [--label <name>]', 'automation', ['network']],
 	},
+	'auto-ok:judge': {
+		script: 'scripts/auto-ok/auto-ok-judge-cli.ts',
+		description:
+			'List the open issues backlogrun owes an auto-ok judgement, or record one (--apply / --decline)',
+		category: 'AI tools',
+		reference: [
+			'[--apply <n> (--lane | --solo) | --decline <n> --reason <text>]',
+			'automation',
+			['network'],
+		],
+	},
 	...BACKLOG_COMMANDS,
 	cost: {
 		script: 'scripts/cost-runtime/cost-cli.ts',

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

@@ -11,10 +11,10 @@ const BACKLOG_COMMANDS: Record<string, CommandEntry> = {
 	backlogrun: {
 		script: 'scripts/backlog/backlogrun-cli.ts',
 		description:
-			'Start a backlogrun in the background and show its board; with one already running, only show the board',
+			'Start a backlogrun in the background and show its board; with one already running, only show the board, or replace it when it is idle and the invocation differs; --stop stops it',
 		category: 'AI tools',
 		reference: [
-			'[#<n>...] [--only] [--max <n>] [--idle <minutes>] [--agent claude|codex]',
+			'[<n>...] [--only] [--max <n>] [--idle <minutes>] [--agent claude|codex] | --stop',
 			'developer',
 			['files', 'network', 'processes'],
 		],

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

@@ -181,7 +181,7 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 	'test:unit': {
 		script: 'scripts/test/test-unit-guard.ts',
 		description:
-			'Run unit tests with Vitest (skips when Vitest is absent; fails when it has no tests)',
+			'Run unit tests with Vitest (without Vitest: a basic project runs its own test script, others skip; fails when Vitest has no tests)',
 		category: 'Development',
 		reference: [FILTER_ARGUMENTS, 'developer', ['processes']],
 		core_weight: gate_plan.direct_unit_weight,

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

@@ -11,6 +11,13 @@ const ISSUES_WITH_REPO = '<issue...> [--repo <owner/repo>]'
 
 /* eslint-disable @typescript-eslint/naming-convention */
 const ISSUE_COMMANDS: Record<string, CommandEntry> = {
+	'issue:ack': {
+		script: 'scripts/issue/issue-ack-cli.ts',
+		description:
+			"Record that the run read a person's update to its issue, printing the update it acknowledges",
+		category: 'AI tools',
+		reference: ['<issue>', 'automation', ['network']],
+	},
 	'issue:read': {
 		script: 'scripts/issue/issue-read-cli.ts',
 		description: "Print each issue's title, body and every comment on it, in one call",
@@ -68,7 +75,7 @@ const ISSUE_COMMANDS: Record<string, CommandEntry> = {
 			'File an Issue with every filing step: lint, Origin, fold, WIP cap, duplicate scout, labels, then epic:bundle',
 		category: 'AI tools',
 		reference: [
-			'<title> --body-file <path> --depth <0|1|2> [--route <route>] [--label <name>] [--repo <owner/repo>] [--distinct <N,…>] [--over-cap] [--no-auto-ok] [--requested] [--release]',
+			'<title> --body-file <path> --depth <0|1|2> [--route <route>] [--label <name>] [--repo <owner/repo>] [--distinct <N,…>] [--over-cap] [--no-auto-ok] [--release]',
 			'automation',
 			['network'],
 		],
@@ -76,9 +83,9 @@ const ISSUE_COMMANDS: Record<string, CommandEntry> = {
 	'issue:release': {
 		script: 'scripts/issue/issue-release-cli.ts',
 		description:
-			"Link an Issue to the repository's open release Issue as its blocker, filing one when none is open",
+			"Link an Issue to the repository's open release Issue as its blocker (or, with --wait, as waiting on it), filing one when none is open",
 		category: 'AI tools',
-		reference: ['<issue>', 'automation', ['network']],
+		reference: ['<issue> [--wait]', 'automation', ['network']],
 	},
 }
 /* eslint-enable @typescript-eslint/naming-convention */

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

@@ -40,7 +40,7 @@ const LANE_COMMANDS: Record<string, CommandEntry> = {
 	'lane:prune': {
 		...LANE_ARGUMENTS,
 		description:
-			'Close every lane an interruption left without its work tree, then sweep unregistered leftovers under the lanes root',
+			'Close every lane an interruption left without its work tree and every spent lane, then sweep unregistered leftovers under the lanes root',
 		category: 'AI tools',
 		reference: ['', 'automation', ['files', 'git']],
 		default_script_arguments: ['prune'],
@@ -74,6 +74,15 @@ const LANE_COMMANDS: Record<string, CommandEntry> = {
 		category: 'AI tools',
 		reference: ['<issue> [--stash <message>]', 'automation', ['files', 'git', 'processes']],
 	},
+	// `.env` is read for `JOSH_LANE_ROOT`, as every lane command reads it, so the lane is found.
+	'lane:restart': {
+		script: 'scripts/lane/lane-restart-cli.ts',
+		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+		description:
+			'Stop a running lane child, stash its uncommitted work and re-dispatch its issue in a fresh session — not counted as an outage or a failure',
+		category: 'AI tools',
+		reference: ['<issue>', 'developer', ['files', 'git', 'processes', 'network']],
+	},
 	// A live run's lane limit: `.env` is read so the bare form reports the
 	// `JOSH_LANE_LIMIT` a person set there when no override stands.
 	'lane:limit': {
@@ -97,7 +106,7 @@ const LANE_COMMANDS: Record<string, CommandEntry> = {
 	'lane:stats': {
 		...MEASURE_ARGUMENTS,
 		description:
-			'Print one table row of lane throughput, gate duration and machine load over a period, and the per-stage durations of a lane under it',
+			'Print one table row of lane throughput, gate duration and machine load over a period, the per-stage durations of a lane under it, and the wait after each ship stop reason under those',
 		category: 'AI tools',
 		reference: ['--period <days> [--limit <lane-limit>]', 'maintainer', ['none']],
 		default_script_arguments: ['stats'],

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

@@ -17,7 +17,7 @@ const PROJECT_COMMANDS: Record<string, CommandEntry> = {
 		description: 'Set a project up for the GitHub Issue workflow, from git init to the setup PR',
 		category: 'Project',
 		reference: [
-			`${PROFILE_ARGUMENTS} [--yes] [--github] [--public] [--init-command <command>] [--push-preflight-command <command>]`,
+			`${PROFILE_ARGUMENTS} [--yes] [--github] [--public] [--dry-run] [--init-command <command>] [--push-preflight-command <command>]`,
 			'developer',
 			['files', 'git', 'network', 'processes'],
 		],
@@ -29,12 +29,30 @@ const PROJECT_COMMANDS: Record<string, CommandEntry> = {
 		reference: ['<dir>', 'automation', ['files', 'git']],
 		is_kit_only: true,
 	},
+	'fresh:run': {
+		script: 'scripts/fresh-machine/fresh-machine-cli.ts',
+		description:
+			'Run an install scenario in a Docker container of a machine with nothing installed, and keep the log',
+		category: 'Project',
+		reference: [
+			'<pattern> | --spec <file.json> [--package-version <version>] [--log-dir <dir>] [--rebuild] | --list',
+			'maintainer',
+			['files', 'network', 'processes'],
+		],
+	},
+	'auth:setup': {
+		script: 'scripts/auth/auth-setup-cli.ts',
+		description:
+			'Save the long-lived Claude Code token `claude setup-token` prints in the macOS keychain, for josh fresh:run',
+		category: 'Project',
+		reference: ['[--check]', 'maintainer', ['network', 'processes']],
+	},
 	init: {
 		script: 'scripts/init/init.ts',
 		description: 'Initialize config in a new project',
 		category: 'Project',
 		reference: [
-			`${PROFILE_ARGUMENTS} [--no-install]`,
+			`${PROFILE_ARGUMENTS} [--no-install] [--dry-run]`,
 			'developer',
 			['files', 'network', 'processes'],
 		],
@@ -45,6 +63,12 @@ const PROJECT_COMMANDS: Record<string, CommandEntry> = {
 		category: 'Project',
 		reference: ['', 'developer', ['files']],
 	},
+	uninstall: {
+		script: 'scripts/uninstall/uninstall.ts',
+		description: 'Remove what kit added to a project and list what is left to review by hand',
+		category: 'Project',
+		reference: [`${PROFILE_ARGUMENTS} [--yes]`, 'developer', ['files', 'processes']],
+	},
 	'registry:migrate': {
 		script: 'scripts/registry-migration/migrate.ts',
 		description: 'Migrate a project from GitHub Packages to public npm',

package/scripts/josh/josh-verdict.ts

@@ -35,7 +35,7 @@ import { status_icons } from '#scripts/lib/status-icons'
 // gate's plan line is what says "the gate starts here", and it is single-sourced for the reason the
 // verdict is: the printer builds it and the detector matches it from one place.
 
-const { FAIL_ICON, PASS_ICON } = status_icons
+const { FAIL_ICON, PASS_ICON, WARN_ICON } = status_icons
 const GATE_SUBJECT = 'verification gate'
 
 // The prefixes are what the detector matches **and** what the printer builds its line from, so a
@@ -43,16 +43,41 @@ const GATE_SUBJECT = 'verification gate'
 // this module exists to prevent.
 const GATE_PASSED_PREFIX = `${PASS_ICON} ${GATE_SUBJECT} passed`
 const GATE_FAILED_PREFIX = `${FAIL_ICON} ${GATE_SUBJECT} failed`
+// **A gate that ran no check has not passed, and it has not failed either.** Every check of a `basic`
+// project with nothing to check exits 0 with a skip notice, which is a legitimate state — the exit code
+// stays 0, or such a project could never commit — but a line reading `passed` made it indistinguishable
+// from a gate that ran every check. It opens with neither icon and neither word, so no reader of the
+// other two prefixes can take it for one of them.
+const GATE_UNVERIFIED_PREFIX = `${WARN_ICON} ${GATE_SUBJECT} not verified`
 
-type JoshVerdict = 'passed' | 'failed'
+type JoshVerdict = 'passed' | 'failed' | 'unverified'
 
 // Typed rather than left to inference: the namespace object widens a bare literal to `string`, and a
 // caller comparing `read_verdict(line)` against it would then be comparing two unrelated types.
 const PASSED_VERDICT: JoshVerdict = 'passed'
 const FAILED_VERDICT: JoshVerdict = 'failed'
+const UNVERIFIED_VERDICT: JoshVerdict = 'unverified'
 
-function format_gate_passed(step_count: string, total: string): string {
-	return `${GATE_PASSED_PREFIX} (${step_count} checks) in ${total}.`
+// How many of a gate's checks ran, and how many passed without running.
+interface GateCounts {
+	ran: number
+	skipped: number
+}
+
+// The split is printed only when there is one. A gate that skipped nothing — kit's own, and an ordinary
+// consumer's — keeps the line it always printed.
+function format_counts(counts: GateCounts): string {
+	if (counts.skipped === 0) return `${String(counts.ran)} checks`
+
+	return `${String(counts.ran)} ran, ${String(counts.skipped)} skipped`
+}
+
+function format_gate_passed(counts: GateCounts, total: string): string {
+	return `${GATE_PASSED_PREFIX} (${format_counts(counts)}) in ${total}.`
+}
+
+function format_gate_unverified(skipped: number, total: string): string {
+	return `${GATE_UNVERIFIED_PREFIX} (0 ran, ${String(skipped)} skipped) in ${total}.`
 }
 
 function format_gate_failed(failed_labels: string, total: string): string {
@@ -91,14 +116,18 @@ function read_verdict(line: string): JoshVerdict | undefined {
 
 	if (trimmed.startsWith(GATE_PASSED_PREFIX)) return PASSED_VERDICT
 
+	if (trimmed.startsWith(GATE_UNVERIFIED_PREFIX)) return UNVERIFIED_VERDICT
+
 	return undefined
 }
 
 const josh_verdict = {
 	PASSED_VERDICT,
 	FAILED_VERDICT,
+	UNVERIFIED_VERDICT,
 	format_gate_passed,
 	format_gate_failed,
+	format_gate_unverified,
 	GATE_OPENING_MARK,
 	GATE_OPENING_PREFIX,
 	is_gate_opening,

package/scripts/josh/process-identity.ts

@@ -52,6 +52,7 @@ const PROBE_ENVIRONMENT = { TZ: 'UTC', LC_ALL: 'C' }
 // `process.kill(pid, 0)` runs every permission check and delivers nothing, so it is the standard
 // liveness probe: it throws `ESRCH` where the process is gone.
 const LIVENESS_SIGNAL = 0
+const NO_SUCH_PROCESS = 'ESRCH'
 // Below this a pid is not a process: `0` addresses the caller's own process group and anything
 // negative addresses another group, so a truncated or hand-edited record carrying either would
 // otherwise answer "alive" forever.
@@ -79,18 +80,28 @@ interface StartProbes {
 	read_ps_start: (pid: number) => string | undefined
 }
 
-function is_live_pid(pid: number): boolean {
-	if (pid < LOWEST_REAL_PID) return false
-
+// The code the liveness probe was refused with, or nothing where the caller may signal the process.
+function signal_refusal(pid: number): string | undefined {
 	try {
 		process.kill(pid, LIVENESS_SIGNAL)
 
-		return true
-	} catch {
-		return false
+		return undefined
+	} catch (error) {
+		return (error as NodeJS.ErrnoException).code ?? NO_SUCH_PROCESS
 	}
 }
 
+function is_live_pid(pid: number): boolean {
+	return pid >= LOWEST_REAL_PID && signal_refusal(pid) === undefined
+}
+
+// **Whether a pid names any process at all, for a reader that may not be allowed to signal it.** Only
+// `ESRCH` proves the process gone: `EPERM` is the kernel refusing a signal to a process it has just
+// found — one under another user, or outside a sandbox that may only signal its own — so it is present.
+function is_present_pid(pid: number): boolean {
+	return pid >= LOWEST_REAL_PID && signal_refusal(pid) !== NO_SUCH_PROCESS
+}
+
 // Linux exposes field 22 as the process start time in clock ticks since boot. The command name in
 // field 2 may itself contain spaces or `)`, so parsing starts after its final closing parenthesis;
 // `state` is then index 0 and `starttime` index 19. A direct file read avoids process enumeration and
@@ -315,6 +326,19 @@ function is_same_process(
 	return matches_recorded_start(pid, recorded_start, read)
 }
 
+// `is_same_process` for a reader that may not be allowed to signal the writer (`is_present_pid`): a
+// refused signal still compares the start time, so a reissued pid separates from its writer here too.
+function is_present_process(
+	pid: number,
+	recorded_start: string | undefined,
+	read: (pid: number) => string | undefined = read_start,
+): boolean | undefined {
+	if (!is_present_pid(pid)) return false
+	if (recorded_start === undefined) return undefined
+
+	return matches_recorded_start(pid, recorded_start, read)
+}
+
 // **Whether a record is the caller's own, which is a different question from whether its writer is
 // alive**. `is_same_process` asks about the recorded process; this asks
 // whether that process *is this one*. A supervisor that has been replaced reads its successor's
@@ -339,6 +363,8 @@ const process_identity = {
 	is_live_beacon,
 	is_live_pid,
 	is_own_process,
+	is_present_pid,
+	is_present_process,
 	is_same_process,
 	open_beacon,
 	own_fields,