@joshuafolkken/kit 1.957.0 → 1.978.0

package/scripts/issue/issue-closing-pr.ts

@@ -0,0 +1,93 @@
+import { git_closes_keyword } from '#scripts/git/git-closes-keyword'
+import { git_gh_api_path } from '#scripts/git/git-gh-api-path'
+import { git_gh_exec } from '#scripts/git/git-gh-exec'
+import { git_gh_repo } from '#scripts/git/git-gh-repo'
+import { parse_json_object_safe } from '#scripts/git/parse-json-array'
+import { z } from 'zod'
+
+// **The merged pull request that closes an issue GitHub left open** (joshuafolkken/kit#2769). A
+// `backlogrun` child whose pull request merged while GitHub did not apply its `closes #N`
+// (joshuafolkken/kit#2770) came back OPEN, and `run:merge` counted it a failure and parked it — the
+// work had landed, only the issue's close had not.
+//
+// **A merged reference is not enough; the body must close this issue.** A merged pull request that
+// merely mentions the issue — a follow-up, a sibling in the same epic — cross-references it too, and
+// closing on that would close unfinished work. So the pull request counts only when its body's
+// `closes #N` names this issue, read through the one parser every `closes #N` reader shares.
+//
+// **Only references after the last reopen count.** A reopened issue whose earlier attempt merged
+// still carries that pull request's reference, and reading it would close the reopened work — the
+// same reason `issue-merged.ts` reads the last closed/reopened event.
+//
+// **Only a pull request in this repository counts.** A bare `closes #N` names an issue in the pull
+// request's own repository, so a merged pull request elsewhere whose `closes #N` carries the same
+// number closes a different issue — its cross-reference here is a mention, not a close.
+
+const LINE_SEPARATOR = '\n'
+// One compact JSON object per merged pull request that cross-references the issue, and a
+// `{"reopened":true}` marker per reopen, in timeline order.
+const TIMELINE_FILTER = [
+	'.[]',
+	'| if .event == "cross-referenced" and .source.issue.pull_request.merged_at != null',
+	'then {url: .source.issue.html_url, repo: .source.issue.repository.full_name, body: (.source.issue.body // "")}',
+	'elif .event == "reopened" then {reopened: true}',
+	'else empty end',
+].join(' ')
+
+const reference_schema = z.object({ url: z.string(), repo: z.string(), body: z.string() })
+const reopen_schema = z.object({ reopened: z.literal(true) })
+const row_schema = z.union([reference_schema, reopen_schema])
+
+type MergedReference = z.infer<typeof reference_schema>
+type TimelineRow = z.infer<typeof row_schema>
+
+function is_reference(row: TimelineRow): row is MergedReference {
+	return 'url' in row
+}
+
+function parse_references(raw: string): Array<MergedReference> {
+	const rows = raw
+		.split(LINE_SEPARATOR)
+		.map((line) => parse_json_object_safe(line, row_schema))
+		.filter((row) => row !== undefined)
+	const last_reopen = rows.findLastIndex((row) => !is_reference(row))
+
+	return rows.slice(last_reopen + 1).filter((row) => is_reference(row))
+}
+
+function pick_closing_pr(
+	references: ReadonlyArray<MergedReference>,
+	issue: string,
+	repo: string,
+): string | undefined {
+	return references.find(
+		(reference) =>
+			reference.repo === repo &&
+			git_closes_keyword.parse_closes_issue_number(reference.body) === issue,
+	)?.url
+}
+
+// Every doubt falls to `undefined` — an unreadable timeline or repository name leaves the child
+// judged as it was, never closed on a guess.
+async function read_closing_pr(issue: string): Promise<string | undefined> {
+	try {
+		const [raw, repo] = await Promise.all([
+			git_gh_exec.exec_gh_api({
+				path: `${git_gh_api_path.issue_api_path(issue)}/timeline?per_page=100`,
+				should_paginate: true,
+				jq_filter: TIMELINE_FILTER,
+			}),
+			git_gh_repo.repo_get_name_with_owner(),
+		])
+
+		if (repo === undefined) return undefined
+
+		return pick_closing_pr(parse_references(raw), issue, repo)
+	} catch {
+		return undefined
+	}
+}
+
+const issue_closing_pr = { parse_references, pick_closing_pr, read_closing_pr }
+
+export { issue_closing_pr }

package/scripts/josh/__snapshots__/josh-command-map.test.ts.snap

@@ -449,10 +449,11 @@ exports[`COMMAND_MAP — reference metadata > keeps every canonical command and
       ],
     ],
     "init": [
-      "[--profile static|node]",
+      "[--profile static|node] [--no-install]",
       "developer",
       [
         "files",
+        "network",
         "processes",
       ],
     ],

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

@@ -26,7 +26,11 @@ const PROJECT_COMMANDS: Record<string, CommandEntry> = {
 		script: 'scripts/init/init.ts',
 		description: 'Initialize config in a new project',
 		category: 'Project',
-		reference: [PROFILE_ARGUMENTS, 'developer', ['files', 'processes']],
+		reference: [
+			`${PROFILE_ARGUMENTS} [--no-install]`,
+			'developer',
+			['files', 'network', 'processes'],
+		],
 	},
 	sync: {
 		script: 'scripts/sync/sync.ts',

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

@@ -52,9 +52,9 @@ const WORKFLOW_COMMANDS: Record<string, CommandEntry> = {
 		reference: ['--task-type <type> --body <text>', 'automation', ['notifications']],
 		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
 	},
-	// The observation ledger's only commit path (joshuafolkken/kit#1756). `pnpm josh git` excludes the
-	// ledger from what it stages, so without this command a parent's appended line has no route to the
-	// default branch at all — and the recurrence count the promotion rule reads is a count of main.
+	// The observation ledger's commit path for the lines no run's own commit carried
+	// (joshuafolkken/kit#1756, joshuafolkken/kit#2763): a lane's lines sit in the primary checkout, which
+	// its commit cannot see, and the recurrence count the promotion rule reads is a count of main.
 	'observations:flush': {
 		script: 'scripts/observations/observations-flush-cli.ts',
 		description: 'Commit the observation ledger as a pull request of its own, and merge it',

package/scripts/observations/observation-ledger-prepare.ts

@@ -0,0 +1,31 @@
+import { readFile } from 'node:fs/promises'
+import path from 'node:path'
+import { OBSERVATION_LEDGER_PATH } from './observation-ledger'
+import { observation_ledger_line, type BrokenLine } from './observation-ledger-line'
+import { observation_ledger_migrate } from './observation-ledger-migrate'
+
+// **What has to hold before a ledger line is committed, asked by both of the paths that commit one**
+// (joshuafolkken/kit#2763): `pnpm josh observations:flush` and the run's own commit in
+// `scripts/git/git-staging.ts`. Lines still on the old path are moved first (joshuafolkken/kit#2724),
+// so the commit carries the move and the lines together, and every entry line is then parsed against
+// the grammar (joshuafolkken/kit#2123) — each caller decides what a broken line costs it.
+//
+// **A ledger that is not there has no line to break** — the change a status saw is then its deletion,
+// and a commit carries that like any other change to it.
+async function read_ledger(root: string): Promise<string> {
+	try {
+		return await readFile(path.join(root, OBSERVATION_LEDGER_PATH), 'utf8')
+	} catch {
+		return ''
+	}
+}
+
+async function prepare(root: string): Promise<ReadonlyArray<BrokenLine>> {
+	observation_ledger_migrate.migrate(root)
+
+	return observation_ledger_line.broken_ledger_lines(await read_ledger(root))
+}
+
+const observation_ledger_prepare = { prepare }
+
+export { observation_ledger_prepare }

package/scripts/observations/observation-ledger.ts

@@ -1,9 +1,8 @@
 // The observation ledger's one path, named here rather than inside any of the places that act on it
-// (joshuafolkken/kit#1756). `git-staging.ts` excludes it from every ordinary commit,
-// `hook-gate-reuse.ts` excludes it from what a hook calls a carried tree, and
-// `observations-flush.ts` is the only thing that stages it — so a literal in each would be three
-// answers to one question, and a rename reaching only some of them would silently restore the
-// contamination the exclusion exists to prevent.
+// (joshuafolkken/kit#1756). `git-staging.ts` stages it with the run's own commit when its grammar
+// holds (joshuafolkken/kit#2763), `hook-gate-reuse.ts` excludes it from what a hook calls a carried
+// tree, and `observations-flush.ts` commits what no run carried — so a literal in each would be three
+// answers to one question, and a rename reaching only some of them would silently split them.
 //
 // **It sits under `docs/maintainers/`, apart from the reader-facing documents** (joshuafolkken/kit#2724).
 const OBSERVATION_LEDGER_PATH = 'docs/maintainers/observations.md'
@@ -70,6 +69,7 @@ const observation_ledger = {
 	has_pending_append,
 	is_ledger_line,
 	is_ledger_path,
+	is_migration_claim,
 	ledger_paths,
 	status_path,
 }

package/scripts/observations/observations-flush.ts

@@ -1,17 +1,15 @@
-import { readFile } from 'node:fs/promises'
 import { git_command } from '#scripts/git/git-command'
 import { git_gh_command } from '#scripts/git/git-gh-command'
 import { main_sync } from '#scripts/git/main-sync'
 import { observation_ledger, OBSERVATION_LEDGER_PATH } from './observation-ledger'
-import { observation_ledger_line, type BrokenLine } from './observation-ledger-line'
-import { observation_ledger_migrate } from './observation-ledger-migrate'
+import type { BrokenLine } from './observation-ledger-line'
+import { observation_ledger_prepare } from './observation-ledger-prepare'
 import { observations_flush_landing } from './observations-flush-landing'
 
-// The commit path the observation ledger did not have (joshuafolkken/kit#1756). The parent session
-// that appends a line never runs `pnpm josh git`; a child runs it inside a lane work tree, which
-// cannot see the parent's checkout at all; and in the primary checkout `git add -u` swept the line
-// into whatever unrelated pull request that run was opening. So the ledger is excluded from ordinary
-// staging (`scripts/git/git-staging.ts`) and this is the one thing that stages it.
+// The commit path for the ledger lines no run's own commit carried (joshuafolkken/kit#1756). A run in
+// the primary checkout commits its appended lines with its own pull request (`scripts/git/
+// git-staging.ts`, joshuafolkken/kit#2763), so what is left here is a lane's lines — they sit in the
+// primary checkout, which a lane's commit cannot see — and whatever was appended after a commit.
 //
 // **The shape is `scripts/release/release-publish.ts`'s, deliberately.** Both open a pull request of
 // their own over one path, wait on the same required checks every other pull request waits on, and
@@ -57,7 +55,7 @@ function branch_name_for(stamp: string): string {
 // single issue, and the ledger's own lines say where each one was seen.
 function pull_request_body(): string {
 	return [
-		`Appended observations from \`${OBSERVATION_LEDGER_PATH}\`, which \`pnpm josh git\` never stages.`,
+		`Appended observations from \`${OBSERVATION_LEDGER_PATH}\` that no run's own commit carried.`,
 		'',
 		'The ledger is append-only, and a second line under one key is what promotes an observation to an issue — so this pull request adds lines and changes none.',
 		'',
@@ -373,31 +371,14 @@ function broken_lines_message(broken: ReadonlyArray<BrokenLine>): string {
 
 // **A malformed line is refused before a branch is cut, not after.** The ledger path was collected
 // without a line ever being parsed (joshuafolkken/kit#2123), so a broken append could ride a flush
-// through; validating here keeps the committed ledger to its grammar.
-//
-// **A ledger that is not there has no line to break** — the change the status saw is then its
-// deletion, and a flush commits that like any other change to it.
-async function read_ledger(): Promise<string> {
-	try {
-		return await readFile(OBSERVATION_LEDGER_PATH, 'utf8')
-	} catch {
-		return ''
-	}
-}
-
-async function refuse_broken_ledger(): Promise<void> {
-	const broken = observation_ledger_line.broken_ledger_lines(await read_ledger())
+// through; validating here keeps the committed ledger to its grammar. The migration and the parse are
+// `observation-ledger-prepare.ts`'s, shared with the run's own commit (joshuafolkken/kit#2763).
+async function prepare_ledger(): Promise<void> {
+	const broken = await observation_ledger_prepare.prepare(process.cwd())
 
 	if (broken.length > 0) throw new Error(broken_lines_message(broken))
 }
 
-// Lines still on the ledger's old path are moved before anything is validated or staged
-// (joshuafolkken/kit#2724), so the flush commits the move and the lines together.
-async function prepare_ledger(): Promise<void> {
-	observation_ledger_migrate.migrate(process.cwd())
-	await refuse_broken_ledger()
-}
-
 // **Nothing pulls in front of the branch, and that is deliberate.** The ledger is dirty by
 // definition at this point, so `git pull --ff-only` aborts on it in exactly the case a pull would
 // have been for — an upstream flush that already advanced the ledger — and reports a failure about

package/scripts/repo/repository-labels.ts

@@ -0,0 +1,91 @@
+import { git_gh_exec } from '#scripts/git/git-gh-exec'
+import { REPOSITORY_LABELS, type LabelDefinition } from '#scripts/git/issue-labels'
+
+// Creates the labels kit's workflow and the distributed `pr-classification.yml` rely on, and only
+// those the repository is missing (joshuafolkken/kit#2797). The one place labels are created: `josh
+// start` provisions a new repository through it and `josh sync` brings every existing one up to date.
+//
+// Labels already present are left as they are, so a repository that recolored one keeps its choice
+// and a second run changes nothing. GitHub compares label names case-insensitively.
+//
+// **Never throws.** A token without the scope or no network must not stop a sync halfway; the names
+// still missing are printed instead, so the person can create them by hand.
+
+function labels_endpoint(repo: string): string {
+	return `repos/${repo}/labels`
+}
+
+// A failed request is an answer to report, never an exception to propagate (see above).
+function request(api: Parameters<typeof git_gh_exec.exec_gh_api_sync>[0]): string | undefined {
+	try {
+		return git_gh_exec.exec_gh_api_sync(api)
+	} catch {
+		return undefined
+	}
+}
+
+function read_existing(repo: string): ReadonlyArray<string> | undefined {
+	const path = labels_endpoint(repo)
+	const listing = request({ path, should_paginate: true, jq_filter: '.[].name' })
+
+	return listing?.split('\n').filter((name) => name.length > 0)
+}
+
+function missing_labels(existing: ReadonlyArray<string>): ReadonlyArray<LabelDefinition> {
+	const names = new Set(existing.map((name) => name.toLowerCase()))
+
+	return REPOSITORY_LABELS.filter((label) => !names.has(label.name.toLowerCase()))
+}
+
+function create_label(label: LabelDefinition, repo: string): boolean {
+	const body = JSON.stringify(label)
+	const is_created = request({ path: labels_endpoint(repo), method: 'POST', body }) !== undefined
+
+	if (is_created) console.info(`  ✔ label ${label.name}`)
+
+	return is_created
+}
+
+function label_names(labels: ReadonlyArray<LabelDefinition>): ReadonlyArray<string> {
+	return labels.map((label) => label.name)
+}
+
+// An unreadable listing is not an empty one: nothing is created, and every label is reported as
+// unconfirmed rather than as missing. An unresolved repository (no GitHub remote) is the same case.
+function unreadable(repo: string | undefined): ReadonlyArray<string> {
+	const names = label_names(REPOSITORY_LABELS)
+	const target = repo ?? 'this repository'
+
+	console.warn(
+		`  ⚠ could not read the labels of ${target}; make sure these exist: ${names.join(', ')}`,
+	)
+
+	return names
+}
+
+function create_missing(
+	missing: ReadonlyArray<LabelDefinition>,
+	repo: string,
+): ReadonlyArray<string> {
+	const names = label_names(missing.filter((label) => !create_label(label, repo)))
+
+	if (names.length > 0) {
+		console.warn(`  ⚠ could not create these labels; create them by hand: ${names.join(', ')}`)
+	}
+
+	return names
+}
+
+// The label names not confirmed present afterwards — empty when the repository has every one.
+function ensure_labels(repo: string | undefined): ReadonlyArray<string> {
+	if (repo === undefined) return unreadable(repo)
+
+	const existing = read_existing(repo)
+	if (existing === undefined) return unreadable(repo)
+
+	return create_missing(missing_labels(existing), repo)
+}
+
+const repository_labels = { missing_labels, ensure_labels }
+
+export { repository_labels }

package/scripts/rules/implementation-cut.ts

@@ -63,6 +63,9 @@ interface LaneCostState {
 	directory: string
 	source: MarkerSource
 	carried: (now?: Date) => RunCut | undefined
+	// The issue whose run hold stands over this checkout (joshuafolkken/kit#2760) — how a `fullrun`
+	// held outside a lane is told apart from a person's tree.
+	held_issue: () => string | undefined
 	verdict: () => CostVerdict
 }
 
@@ -71,6 +74,7 @@ function current_state(): LaneCostState {
 		directory: process.cwd(),
 		source: process.env,
 		carried: run_cut.carried_cut_sync,
+		held_issue: run_cut.held_issue_sync,
 		// **Read through the short reuse window** (joshuafolkken/kit#2385). The row now fires per
 		// threshold crossing rather than once per run, so this predicate is a candidate on every edit;
 		// the window collapses one turn's burst of edits to a single whole-transcript price.
@@ -79,22 +83,49 @@ function current_state(): LaneCostState {
 	}
 }
 
-// A dispatched lane child for this checkout with no cut already carried. The dispatch mark is what
-// tells a child apart from a person (joshuafolkken/kit#1904), read from the environment against this
-// lane's own issue so a leaked mark for another issue reads as a person. **The carried-cut half keeps
-// the guard silent between a cut and its resume**, exactly as `pre-gate-cut.ts`'s does: a record naming
-// this issue means a cut is already in flight, and `begin_cut`'s exclusive create would refuse a second
-// one anyway.
-function uncut_lane_child_issue(state: LaneCostState): string | undefined {
+// A dispatched lane child's issue for this checkout. The dispatch mark is what tells a child apart from
+// a person (joshuafolkken/kit#1904), read from the environment against this lane's own issue so a
+// leaked mark for another issue reads as a person.
+function lane_child_issue(state: LaneCostState): string | undefined {
 	if (!lane_child_marker.is_child_of(state.directory, state.source)) return undefined
 
-	const issue = lane_paths.lane_issue_of(state.directory, { ...state.source })
+	return lane_paths.lane_issue_of(state.directory, { ...state.source })
+}
+
+// The issue a run holds this checkout for, read only outside a lane: a lane's hold is its dispatched
+// child's, so a person finishing that lane's work carries no mark and still sees no refusal.
+function held_run_issue(state: LaneCostState): string | undefined {
+	if (lane_paths.lane_issue_of(state.directory, { ...state.source }) !== undefined) return undefined
+
+	return state.held_issue()
+}
+
+// The run this checkout's edits belong to, with no cut already carried — a dispatched lane child, or
+// **a `fullrun` held in its own checkout** (joshuafolkken/kit#2760): the cut was lane-only, so a run a
+// person started grew without a bound mid-implementation. The run hold naming an issue is what marks
+// such a run, and a person's tree holds nothing, so it still sees no refusal. **The carried-cut half
+// keeps the guard silent between a cut and its resume**, exactly as `pre-gate-cut.ts`'s does: a record
+// naming this issue means a cut is already in flight, and `begin_cut`'s exclusive create would refuse
+// a second one anyway.
+function uncut_run_issue(state: LaneCostState): string | undefined {
+	const issue = lane_child_issue(state) ?? held_run_issue(state)
 
 	if (issue === undefined) return undefined
 
 	return state.carried()?.issue === issue ? undefined : issue
 }
 
+// **An unmeasurable session is cut in a lane and left alone outside one.** A lane child's safety net is
+// the pre-gate direction below; a held run outside a lane is a person's own session, so only a measured
+// `over` interrupts it — a provider with no transcript would otherwise refuse every edit it makes.
+function warrants_the_cut(state: LaneCostState): boolean {
+	const verdict = state.verdict()
+
+	if (lane_child_issue(state) === undefined) return verdict === cost_verdict.OVER_VERDICT
+
+	return verdict !== cost_verdict.UNDER_VERDICT
+}
+
 // **The tool-name test comes first and the world is consulted second, the cost measurement last.** This
 // predicate is asked of every call in the run, so the `Edit` / `Write` string match keeps the lane read
 // off all but the edits, and the lane read keeps the transcript-priced verdict off every edit but those
@@ -109,9 +140,9 @@ function is_over_threshold_edit(
 	call: GuardedCall,
 	state: LaneCostState = current_state(),
 ): boolean {
-	if (!is_edit_tool(call.name) || uncut_lane_child_issue(state) === undefined) return false
+	if (!is_edit_tool(call.name) || uncut_run_issue(state) === undefined) return false
 
-	return state.verdict() !== cost_verdict.UNDER_VERDICT
+	return warrants_the_cut(state)
 }
 
 // **The threshold in the refusal text is assembled from the constant, never spelled** (joshuafolkken/kit#2385).
@@ -125,7 +156,8 @@ const THRESHOLD_TEXT = `${cost_format.format_tokens(CONTEXT_CUT_THRESHOLD)}-toke
 // because `cut` is the only one that ends the turn and a run told merely to "take the cut" would have to
 // read which of the others leave it implementing — the same reason `pre-gate-cut.ts` spells them out.
 const IMPLEMENTATION_CUT_REASON =
-	'⛔ implementation-phase cut: this checkout is a lane dispatched for this issue and its recent-context ' +
+	'⛔ implementation-phase cut: this checkout is a lane dispatched for this issue, or a run holds it for ' +
+	'this issue (joshuafolkken/kit#2760), and its recent-context ' +
 	`cost has crossed the shared ${THRESHOLD_TEXT} threshold mid-implementation, so the thinking accumulated ` +
 	'so far is now re-read on every later request. Take the cut before this edit. ' +
 	'First write a handoff file with the Write tool — the user’s instruction verbatim, what you have ' +
@@ -139,11 +171,12 @@ const IMPLEMENTATION_CUT_REASON =
 	'because the verdict was only ever read at session entry, where the context has not yet grown. The ' +
 	"verdict is `pnpm josh cost --cut`'s exactly — the same per-request billed-input statistic against the " +
 	'same threshold, never a second measurement. Issue `pnpm josh run:cut --impl <N> --handoff <path>` now and read the ' +
-	'verdict: on `cut`, **end the turn immediately** — the fresh process owns the run and continues ' +
-	'implementing, so it must not be waited for; on `not-a-lane`, `unready`, `busy`, `failed` or ' +
+	'verdict: on `cut`, **end the turn immediately** — in a lane the fresh process owns the run and ' +
+	'continues implementing, so it must not be waited for; outside a lane nothing is relaunched, so first ' +
+	'send the `confirmation` Telegram naming the resume command `fullrun #<N>` and keep the hold; on `not-a-lane`, `unready`, `busy`, `failed` or ' +
 	'`unknown`, this process carries the run on and the edit is simply the next call. Never relaunch a ' +
-	'second process after `busy`. This fired because the dispatch mark names this lane; a person working ' +
-	'here carries no mark and sees no refusal, so there is no human-or-child judgement left to make. The ' +
+	'second process after `busy`. This fired because the dispatch mark names this lane or the run hold ' +
+	'names this issue; a person working here carries no mark and holds no run, so sees no refusal, so there is no human-or-child judgement left to make. The ' +
 	'procedure is `.claude/skills/workflow-commands/pre-gate-cut.md`. Reissue this edit once the cut has ' +
 	'answered — an edit reissued right after this refusal passes, so `busy` / `failed` cannot wedge the ' +
 	'run edit after edit; this fires again on the next threshold crossing rather than once per run.'
@@ -195,7 +228,7 @@ const implementation_cut = {
 	is_over_threshold_edit,
 	is_reissued_refusal,
 	takes_the_impl_cut,
-	uncut_lane_child_issue,
+	uncut_run_issue,
 }
 
 export type { LaneCostState }

package/scripts/rules/lane-background.ts

@@ -3,7 +3,10 @@ import { lane_child_marker } from '#scripts/lane/lane-child-marker'
 import { json_value } from '#scripts/lib/json-value'
 import type { GuardedCall } from '#scripts/time-runtime/time-batch-guard'
 import { time_shell } from '#scripts/time-runtime/time-shell'
-import { time_transcript_line } from '#scripts/time-runtime/time-transcript-line'
+import {
+	time_transcript_line,
+	type Block as TranscriptBlock,
+} from '#scripts/time-runtime/time-transcript-line'
 import { run_tail } from './run-tail'
 
 // A dispatched lane child is stopped from backgrounding a long-running josh command (joshuafolkken/kit#2704).
@@ -60,16 +63,32 @@ function is_background_long_run(
 	return is_candidate(call) && is_lane_child()
 }
 
-// The background tasks the transcript tail launched and never saw finish. A launch is read off its own
-// tool result and a finish off the harness notice, both by `time_transcript_line`.
-function pending_background_ids(tail: string): ReadonlyArray<string> {
+// The launches `launched_ids` reads off the transcript tail that never saw their finish. A launch is
+// read off its own tool result and a finish off the harness notice, both by `time_transcript_line`.
+function unfinished_ids(
+	tail: string,
+	launched_ids: (block: TranscriptBlock) => ReadonlyArray<string>,
+): ReadonlyArray<string> {
 	const lines = tail.split('\n').map((line) => time_transcript_line.parse_line(line))
 	const finished = new Set(lines.map((line) => line?.finished_background ?? ''))
-	const launched = lines.flatMap((line) => line?.blocks.map((block) => block.background_id) ?? [])
+	const blocks = lines.flatMap((line) => line?.blocks ?? [])
+	const launched = blocks.flatMap((block) => launched_ids(block))
 
 	return launched.filter((id) => id !== '' && !finished.has(id))
 }
 
+// The background tasks the tail launched and never saw finish — commands and subagents alike
+// (joshuafolkken/kit#2774), since a lane child's turn-end kills either.
+function pending_background_ids(tail: string): ReadonlyArray<string> {
+	return unfinished_ids(tail, (block) => [block.background_id, block.agent_id])
+}
+
+// The backgrounded subagents alone. A subagent always ends and its notice re-invokes the session; a
+// command may be a server that never exits, so only this set says the run is certain to resume.
+function pending_agent_ids(tail: string): ReadonlyArray<string> {
+	return unfinished_ids(tail, (block) => [block.agent_id])
+}
+
 const LANE_BACKGROUND_REASON =
 	'⛔ lane background: this session is a dispatched lane child (`JOSH_LANE_CHILD`), a headless ' +
 	'`claude -p` process whose background Bash tasks are killed when the turn ends — so a backgrounded ' +
@@ -105,6 +124,7 @@ const lane_background = {
 	LANE_BACKGROUND_STOP_REASON,
 	ROW,
 	is_background_long_run,
+	pending_agent_ids,
 	pending_background_ids,
 }
 

package/scripts/rules/stop-rules.ts

@@ -67,9 +67,12 @@ interface StopContext {
 	headless_refusals: number
 	// This session is a dispatched lane child for this checkout — `lane_child_marker.is_child_of`.
 	lane_child: boolean
-	// A background task this run launched has not finished — `lane_background.pending_background_ids`
-	// over the transcript tail (joshuafolkken/kit#2704).
+	// A background task this run launched — a command or a subagent — has not finished —
+	// `lane_background.pending_background_ids` over the transcript tail (joshuafolkken/kit#2704).
 	background_pending: boolean
+	// A backgrounded subagent this run launched has not finished — `lane_background.pending_agent_ids`
+	// (joshuafolkken/kit#2774). Apart from `background_pending`, since only a subagent is sure to end.
+	agent_pending: boolean
 	// The resolved `JOSH_SESSION_LANG` — `session_language.resolve_session_lang` (joshuafolkken/kit#2470).
 	session_lang: string
 }
@@ -221,12 +224,21 @@ function needs_filing(context: StopContext): boolean {
 	return filing_offer.is_first_party_target(context.message, context.session_owner)
 }
 
+// **A running background subagent stands both hold rules down** (joshuafolkken/kit#2774). Its completion
+// notice re-invokes the session, so the turn-end is a wait on the run's own work, not on a person — a
+// notify there says "nothing needed" and dilutes the ones that do. A backgrounded command does not
+// count: a dev server never ends, and a stop behind it would leave a person silently waiting. A lane
+// child never reaches this with a task running: `needs_background_wait` answers it first.
+function is_held_idle(context: StopContext): boolean {
+	return context.hold_present && !context.agent_pending
+}
+
 function needs_notify(context: StopContext): boolean {
-	return context.hold_present && !context.notified
+	return is_held_idle(context) && !context.notified
 }
 
 function needs_release(context: StopContext): boolean {
-	return context.hold_present && context.tree_clean
+	return is_held_idle(context) && context.tree_clean
 }
 
 function citation_reason(message: string): string | undefined {

package/scripts/run/run-carry-cli.ts

@@ -1,5 +1,7 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
+import { cost_cli } from '#scripts/cost-runtime/cost-cli'
+import { cost_verdict } from '#scripts/cost-runtime/cost-verdict'
 import {
 	run_carry,
 	type CarryClaim,
@@ -44,6 +46,9 @@ const UNKNOWN_VERDICT = 'unknown'
 // the run carries on uncut rather than paying a cold preamble the accumulation it would shed no longer
 // covers, exactly as an under-threshold pre-gate cut carries on to the gate.
 const CAPPED_VERDICT = 'capped'
+// The asking session is over the shared context-cut threshold, so nothing was claimed
+// (joshuafolkken/kit#2760).
+const OVER_VERDICT = 'over'
 const NO_CUTS = 0
 
 const CLAIM_VERDICTS: Record<CarryClaim, string> = {
@@ -235,7 +240,22 @@ function adopt(target: string, request: CarryClaimRequest, is_json: boolean): nu
 	return report_claim(target, read.carry, request, is_json)
 }
 
+// **A session already over the shared cut threshold claims nothing** (joshuafolkken/kit#2760). A claim
+// assumed the asking session was fresh, so a `backlogrun` parent that had taken its cut at 233k could
+// retype the keyword in the same conversation and be answered `resumed` by its own hand-off — measured
+// twice, at 232k and 258k. The verdict is `pnpm josh cost --cut`'s, so no second threshold exists; only a
+// measured `over` refuses, because a provider with no transcript cannot be priced at all.
+function report_over(is_json: boolean): number {
+	console.error(
+		'This session is over the shared context-cut threshold (`pnpm josh cost --cut` answers `over`), so no run was begun or resumed here. End this conversation and type the invocation again in a fresh session.',
+	)
+
+	return report(OVER_VERDICT, undefined, is_json, FAILURE_EXIT_CODE)
+}
+
 function claim_record(target: string, request: CarryClaimRequest, is_json: boolean): number {
+	if (cost_cli.session_verdict() === cost_verdict.OVER_VERDICT) return report_over(is_json)
+
 	return request.is_adoption ? adopt(target, request, is_json) : begin(target, request, is_json)
 }
 
@@ -425,6 +445,7 @@ const run_carry_cli = {
 	EXPIRED_VERDICT,
 	MISMATCH_VERDICT,
 	NONE_VERDICT,
+	OVER_VERDICT,
 	RESUMED_VERDICT,
 	STANDING_VERDICT,
 	UNKNOWN_VERDICT,