@joshuafolkken/kit 1.1136.0 → 1.1178.0

package/scripts/issue/issue-file.ts

@@ -4,7 +4,12 @@ import { github_issue_url } from '#scripts/gh/github-issue-url'
 import { cli_flags } from '#scripts/lib/cli-flags'
 import { issue_backlinks } from './issue-backlinks'
 import { issue_classification } from './issue-classification'
-import { DEPTH_LABEL_ORDER, FILING_ROUTE_LABELS, has_label_name } from './issue-labels'
+import {
+	AUTO_OK_LABEL,
+	DEPTH_LABEL_ORDER,
+	FILING_ROUTE_LABELS,
+	has_label_name,
+} from './issue-labels'
 import { markdown_section } from './markdown-section'
 
 // The decisions behind `josh issue:file` (joshuafolkken/kit#2808), kept apart from the command that
@@ -31,6 +36,10 @@ interface FileArguments {
 	labels: ReadonlyArray<string>
 	repo: string | undefined
 	distinct: ReadonlyArray<number>
+	// `--over-cap`: the run is blocked by this filing, so the WIP cap does not hold it (`issue-wip.ts`).
+	is_over_cap: boolean
+	// `--no-auto-ok`: the Issue needs a person's judgement, so `auto-ok` is not applied (`issue-auto-ok.ts`).
+	is_auto_ok_opted_out: boolean
 }
 
 const OPTIONS = {
@@ -40,6 +49,8 @@ const OPTIONS = {
 	label: { type: 'string', multiple: true },
 	repo: { type: 'string' },
 	distinct: { type: 'string', multiple: true },
+	'over-cap': { type: 'boolean' },
+	'no-auto-ok': { type: 'boolean' },
 } as const
 
 // The label a `--depth` / `--route` value names, or `undefined` when it names none — read against the
@@ -101,7 +112,15 @@ function arguments_of(values: ParsedValues, title: string | undefined): FileArgu
 
 	if (labelled === undefined || !has_text(title) || !has_text(body_file)) return undefined
 
-	return { title, body_file, ...labelled, labels: values.label ?? [], repo: values.repo }
+	return {
+		title,
+		body_file,
+		...labelled,
+		labels: values.label ?? [],
+		repo: values.repo,
+		is_over_cap: values['over-cap'] === true,
+		is_auto_ok_opted_out: values['no-auto-ok'] === true,
+	}
 }
 
 // An unknown flag is `undefined` rather than a throw, so the answer is the usage line, not a stack trace.
@@ -121,12 +140,16 @@ function is_undeclared_classification(label: string, body: string): boolean {
 
 // Every label the filing carries: the depth, the route when there is one, the classification labels
 // the body declares (`issue_classification.labels_for`, which merges case-insensitively), then any
-// extra `--label`. One request applies them all, so no label is a separate step to forget.
-function labels_of(args: FileArguments, body: string): ReadonlyArray<string> {
+// extra `--label`, then `auto-ok` when the filing opted in (`issue-auto-ok.ts`) and no `--label`
+// already named it. One request applies them all, so no label is a separate step to forget.
+function labels_of(args: FileArguments, body: string, is_auto_ok = false): ReadonlyArray<string> {
 	const extra = args.labels.filter((label) => !is_undeclared_classification(label, body))
 	const declared = [args.depth, ...(args.route === undefined ? [] : [args.route]), ...extra]
+	const labels = issue_classification.labels_for(body, declared)
 
-	return issue_classification.labels_for(body, declared)
+	if (!is_auto_ok || has_label_name(labels, AUTO_OK_LABEL)) return labels
+
+	return [...labels, AUTO_OK_LABEL]
 }
 
 function is_same_repository(target: string, current: string): boolean {

package/scripts/issue/issue-labels.ts

@@ -16,7 +16,7 @@ const PLANNED_LABEL = 'run:planned'
 // forever (joshuafolkken/kit#860).
 const NEEDS_DECISION_LABEL = 'needs-decision'
 // Marks an issue whose defect reaches the verification path, so it runs with nothing beside it
-// (joshuafolkken/kit#2776). A run applies it from the verification-path enumeration in `wip-cap.md`;
+// (joshuafolkken/kit#2776). A run applies it from the verification-path enumeration in `backlogrun-lanes.md`;
 // `backlog:next` enforces it (`backlog-solo.ts`), so the rule no longer rests on a judgement at
 // dispatch time.
 const RUN_SOLO_LABEL = 'run:solo'
@@ -36,11 +36,12 @@ const PRIORITY_HIGH_LABEL = 'priority:high'
 const AUTO_OK_LABEL = 'auto-ok'
 // Degrades one issue's run to a `halfrun`-shaped stop: it is implemented and taken through the
 // verification gate, and then nothing is committed, pushed, opened as a pull request or merged
-// (joshuafolkken/kit#1125). **Only a person applies it**, exactly as strongly as `auto-ok` — a mark a
-// run could clear for itself is not a mark.
+// (joshuafolkken/kit#1125). **Only a person applies it** — a mark a run could clear for itself is not
+// a mark.
 //
-// It is the opposite of `auto-ok` in what it does and its twin in who may apply it: one widens
-// unattended execution past an epic's edge, the other withholds the last step of it. `auto-ok`
+// It is the opposite of `auto-ok` in what it does: one widens unattended execution past an epic's
+// edge, the other withholds the last step of it. Unlike `auto-ok`, which `issue:file` applies by
+// default to work found by opted-in work (joshuafolkken/kit#3213), no run ever applies it. `auto-ok`
 // answers "may this run at all", this one answers "may its result ship without a person looking".
 //
 // **Not `needs-decision`, and the difference is what the two sets below encode.** A parked issue is
@@ -154,7 +155,7 @@ const FILING_ROUTE_LABELS: ReadonlyArray<{
 //
 // **The depth is read off the subject, so a run applies it.** Unlike `auto-ok` and
 // `needs-human-review` this is not a person's judgement about authorization; it is the same reading
-// §2i already asks a run to make before it files, and none of the three withholds or widens anything
+// `observation-filing.md` already asks a run to make before it files, and none of the three withholds or widens anything
 // a run may do.
 const DEPTH_0_LABEL = 'depth:0'
 const DEPTH_1_LABEL = 'depth:1'
@@ -171,9 +172,8 @@ const DEPTH_LABEL_ORDER: ReadonlyArray<string> = [DEPTH_0_LABEL, DEPTH_1_LABEL,
 // description, so provisioning from here is what gives each one a stable color a reader can scan by.
 // Green, amber and pale blue, so the consumer-facing depth is the one that stands out in a listing.
 //
-// **The provisioning command lives in `observation-filing.md`**, because prose cannot import this module —
-// the same split `FILING_ROUTE_LABELS` above lives with. `scripts/rules/issue-depth-label.test.ts` keys
-// those three command lines to this array, so a color changed here without the document fails.
+// **`josh issue:file` provisions them** through `repository_labels.ensure_labels` before its create
+// call (joshuafolkken/kit#3176), so no document carries a creation command to keep in step.
 const DEPTH_LABELS: ReadonlyArray<{
 	name: string
 	color: string
@@ -182,17 +182,17 @@ const DEPTH_LABELS: ReadonlyArray<{
 	{
 		name: DEPTH_0_LABEL,
 		color: '0e8a16',
-		description: 'Depth 0 — what a consumer of this package touches (SKILL.md §2i)',
+		description: 'Depth 0 — what a consumer of this package touches (observation-filing.md)',
 	},
 	{
 		name: DEPTH_1_LABEL,
 		color: 'fbc02d',
-		description: 'Depth 1 — the run orchestration that executes an Issue (SKILL.md §2i)',
+		description: 'Depth 1 — the run orchestration that executes an Issue (observation-filing.md)',
 	},
 	{
 		name: DEPTH_2_LABEL,
 		color: 'c5def5',
-		description: 'Depth 2 — what measures a run (SKILL.md §2i)',
+		description: 'Depth 2 — what measures a run (observation-filing.md)',
 	},
 ]
 

package/scripts/issue/issue-rank.ts

@@ -15,7 +15,7 @@ import {
 //
 // **`run:solo` alone is not a key.** It means "runs alone", not "runs first": tidying that only touches
 // the verification path carries it too, and a low-priority one is not owed a place ahead of the queue.
-// Only a defect on that path is, because `wip-cap.md` holds a batch until it has merged.
+// Only a defect on that path is, because `backlogrun-lanes.md` holds a batch until it has merged.
 
 interface RankRow {
 	labels: ReadonlyArray<string>

package/scripts/issue/issue-read-cli.ts

@@ -8,7 +8,7 @@ import { issue_report_failures, type ReadFailureKind } from './issue-report-fail
 // `josh issue:read <N> [<N> ...]` — the body *and* the comments of every issue named, in one call
 // (joshuafolkken/kit#1715).
 //
-// It replaces the two `gh api` reads `.claude/skills/workflow-commands/SKILL.md` §2g tells an agent
+// It replaces the two `gh api` reads `.claude/skills/workflow-commands/issue-comments.md` tells an agent
 // to type per issue. Measured over four recorded `backlogrun` parents, `issue bookkeeping` was the
 // largest single contributor to the parent's turn count — 110 of 414 turns, 26.6% — and one issue
 // read at a time was its dominant shape: 19 `…/issues/<N>` calls and 5 `…/comments` calls, each its
@@ -23,7 +23,7 @@ import { issue_report_failures, type ReadFailureKind } from './issue-report-fail
 // prevent.
 //
 // **A failed read is never printed as an issue**, and neither is a failed comment listing printed as
-// "no comments" — the block says which of the two it holds, because §2g's rule is that the later text
+// "no comments" — the block says which of the two it holds, because `issue-comments.md`'s rule is that the later text
 // wins, and a comment nobody read cannot win anything.
 
 const FAILURE_EXIT_CODE = 1
@@ -88,7 +88,7 @@ async function read_issue(issue_number: string): Promise<NumberResult> {
 
 // One issue's block for a caller that wants the text rather than the printing — `run:prep` composes it
 // with the state block and the dependency-update line. A failed read is returned as its kind, never as
-// an empty block, so §2g's "a comment nobody read cannot win anything" holds through the bundle too.
+// an empty block, so `issue-comments.md`'s "a comment nobody read cannot win anything" holds through the bundle too.
 async function read_block(issue_number: string): Promise<BlockRead> {
 	const result = await read_issue(issue_number)
 

package/scripts/issue/issue-read.ts

@@ -6,7 +6,7 @@ import { z } from 'zod'
 // (joshuafolkken/kit#1715).
 //
 // **It exists because reading one issue costs a parent two turns.** `.claude/skills/workflow-commands/SKILL.md`
-// §2g requires the body *and* the comments, since a decision recorded after the body was written
+// `issue-comments.md` requires the body *and* the comments, since a decision recorded after the body was written
 // lives only in a comment; typed by hand that is `gh api repos/{owner}/{repo}/issues/<N>` followed by
 // `gh api repos/{owner}/{repo}/issues/<N>/comments`. Measured over four recorded `backlogrun`
 // parents, `issue bookkeeping` was the single largest contributor to the parent's turn count — 110 of
@@ -15,7 +15,7 @@ import { z } from 'zod'
 // distribution this collapses.
 //
 // **The comments are never silently absent.** A listing that could not be read prints a line saying
-// so, because a block showing no comment where the read failed is exactly the misread §2g exists to
+// so, because a block showing no comment where the read failed is exactly the misread `issue-comments.md` exists to
 // prevent: the agreement in force would be taken from a body a comment had already overturned.
 
 const ISSUE_LABEL = 'issue: '

package/scripts/issue/issue-scout-cli.ts

@@ -107,7 +107,7 @@ function format_duplicate(candidate: DuplicateCandidate): string {
 	const epic = candidate.epic === undefined ? '' : ` (epic #${String(candidate.epic)})`
 	// The reader does two different things with the two states, so the row has to say which it is: an
 	// open candidate means somebody is already tracking this, a closed one means it may already be
-	// done — and the second is the exit `SKILL.md` → §2g names, not a second filing.
+	// done — and the second is the exit `issue-comments.md` names, not a second filing.
 	const closed = candidate.is_closed === true ? ' (closed)' : ''
 
 	return `  #${String(candidate.number)}  ${score}  ${candidate.title}${closed}${epic}`
@@ -211,7 +211,7 @@ function named_epics(draft: BacklogIssue, issues: ReadonlyArray<BacklogIssue>):
 		.map((issue) => issue.number)
 }
 
-// A person naming the epic is the strongest signal there is — it is what §2a's `into <target>` suffix
+// A person naming the epic is the strongest signal there is — it is what `into-target.md`'s `into <target>` suffix
 // means — so it is reported ahead of whatever the candidate search concluded, with the candidates
 // still named beside it.
 function format_named_epics(epics: ReadonlyArray<number>, decision: BundleDecision): Array<string> {

package/scripts/issue/issue-state-cli.ts

@@ -170,7 +170,7 @@ async function read_all(request: StateRequest): Promise<ReadonlyArray<IssueRepor
 }
 
 // `[]` for a number that produced no state, so one unresolvable number costs the others nothing.
-// The heading is withheld for a single number: `.claude/skills/workflow-commands/SKILL.md` §2z and
+// The heading is withheld for a single number: `.claude/skills/workflow-commands/needs-human-review.md` and
 // `.claude/skills/diag/SKILL.md` read that report's three lines verbatim.
 function state_blocks(report: IssueReport, should_attribute: boolean): ReadonlyArray<string> {
 	if (report.result.kind !== 'state') return []

package/scripts/issue/issue-state.ts

@@ -88,8 +88,8 @@ function format_issue_state(state: IssueState): string {
 
 // The same three lines, under the number they belong to. Kept as a separate function rather than a
 // flag on the one above, so the single-number report has no branch that could ever prepend a fourth
-// line to it: `.claude/skills/workflow-commands/SKILL.md` §2z and `.claude/skills/diag/SKILL.md`
-// read those three verbatim, and §2z's `needs-human-review` stop is decided from them.
+// line to it: `.claude/skills/workflow-commands/needs-human-review.md` and `.claude/skills/diag/SKILL.md`
+// read those three verbatim, and `needs-human-review.md`'s `needs-human-review` stop is decided from them.
 function format_attributed_issue_state(issue_number: string, state: IssueState): string {
 	return `${ISSUE_LABEL}${issue_number}\n${format_issue_state(state)}`
 }

package/scripts/issue/issue-wip.ts

@@ -0,0 +1,70 @@
+import { delivered_rules } from '#scripts/rules/delivered-rules'
+import { INTERRUPT_ROUTE_LABEL, SPLIT_ROUTE_LABEL, TIER_A_ROUTE_LABEL } from './issue-labels'
+
+// The WIP cap at the call that files (joshuafolkken/kit#3181). The count used to be a hand-run
+// `gh api … | wc -l` the agent compared with the cap itself; `josh issue:file` now reads it and asks
+// the exemption question before anything is sent, the same hold `--distinct` places on a duplicate.
+// What stays judgement — whether a filing is exempt — is declared by the route or by `--over-cap`.
+
+const WITHIN = 'within'
+const EXEMPT = 'exempt'
+const HELD = 'held' as const
+
+type WipVerdict = typeof WITHIN | typeof EXEMPT | typeof HELD
+
+// Each route is an exempt category by definition: a prerequisite or upstream defect (`tier-a`) and a
+// split child block the run, and an interrupt is one of the three tests. `review-cap` is the review
+// round cap's branch 2, which `wip-cap.md` counts as discretionary, so it is held like no route at all.
+const EXEMPT_ROUTES: ReadonlySet<string> = new Set([
+	TIER_A_ROUTE_LABEL,
+	SPLIT_ROUTE_LABEL,
+	INTERRUPT_ROUTE_LABEL,
+])
+
+const HELD_MESSAGE =
+	'✖ over the WIP cap: close one first; nothing honestly closable means do not file — a discretionary ' +
+	'filing waits. An interrupt meeting one of three tests (a verification answers wrongly, a documented ' +
+	'workflow cannot complete, or data is lost or written outside the repository) files with ' +
+	'`--route interrupt`; a filing the run is blocked by reissues with `--over-cap`. Either way, state ' +
+	'the overage (`prompts/collaboration-workflow/wip-cap.md`).'
+
+const UNREAD_MESSAGE =
+	'⚠ wip: could not count the open Issues — the filing goes on unchecked against the cap ' +
+	'(`prompts/collaboration-workflow/wip-cap.md`).'
+
+interface WipFiling {
+	route: string | undefined
+	is_over_cap: boolean
+}
+
+function is_exempt(filing: WipFiling): boolean {
+	return filing.is_over_cap || (filing.route !== undefined && EXEMPT_ROUTES.has(filing.route))
+}
+
+// The cap is "more than `WIP_CAP` open", so exactly the cap is still within it.
+function verdict_of(count: number, filing: WipFiling): WipVerdict {
+	if (count <= delivered_rules.WIP_CAP) return WITHIN
+
+	return is_exempt(filing) ? EXEMPT : HELD
+}
+
+function count_line(count: number, repo: string, verdict: WipVerdict): string {
+	return `wip: ${String(count)} open in ${repo} · cap ${String(delivered_rules.WIP_CAP)} · ${verdict}`
+}
+
+// The listing's JSON is an array of rows; anything else is unreadable rather than zero, because zero
+// would pass every filing as within the cap.
+function count_of(json: string): number | undefined {
+	try {
+		const parsed: unknown = JSON.parse(json)
+
+		return Array.isArray(parsed) ? parsed.length : undefined
+	} catch {
+		return undefined
+	}
+}
+
+const issue_wip = { HELD, HELD_MESSAGE, UNREAD_MESSAGE, verdict_of, count_line, count_of }
+
+export type { WipVerdict }
+export { issue_wip }

package/scripts/josh/hook-decision.ts

@@ -38,6 +38,7 @@ type HookPayload = z.infer<typeof payload_schema>
 
 const HOOK_EVENT_NAME = 'PreToolUse'
 const DENY_DECISION = 'deny'
+const ALLOW_DECISION = 'allow'
 // No record means nothing has been refused yet, and every span began after instant zero — which is
 // the answer wanted: the first qualifying accumulation of a run is refused.
 const NEVER_MS = 0
@@ -84,6 +85,21 @@ function deny_envelope(reason: string): string {
 	})
 }
 
+// **A rewrite, not a refusal** (joshuafolkken/kit#3154): the call proceeds with `updated_input` merged
+// over its own. `allow` is the decision the harness applies an `updatedInput` under; a settings `deny`
+// rule still wins over it, so this never widens what the call may do.
+function rewrite_envelope(updated_input: Record<string, unknown>, context: string): string {
+	return JSON.stringify({
+		systemMessage: context,
+		hookSpecificOutput: {
+			hookEventName: HOOK_EVENT_NAME,
+			permissionDecision: ALLOW_DECISION,
+			updatedInput: updated_input,
+			additionalContext: context,
+		},
+	})
+}
+
 // **A notice, not a decision.** It carries no `permissionDecision`, so the call proceeds exactly as it
 // would have; `additionalContext` is what reaches the model, and `systemMessage` is what the person
 // watching sees. Both are filled because either channel alone leaves one of the two blind — and the
@@ -470,6 +486,7 @@ const hook_decision = {
 	notice_envelope,
 	parse_hook_payload,
 	report_no_payload,
+	rewrite_envelope,
 	stamp_fault,
 	write_decision,
 	write_outcome,

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

@@ -115,6 +115,16 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		// `UserPromptSubmit`, so it must stay eligible for in-process dispatch rather than pay a second
 		// tsx start each turn. It calls `process.loadEnvFile` itself through the shared loader.
 	},
+	'codex:hook-adapter': {
+		script: 'scripts/hooks/codex-hook-adapter.ts',
+		description:
+			'Codex hook: run the pretool or posttool guard on a Codex payload (reads the tool call on stdin)',
+		category: 'Development',
+		reference: ['<pretool|posttool>', 'automation', ['none']],
+		// The live-source fallback `scripts/hooks/run-hook.sh` derives from the `codex-hook-adapter`
+		// bundle name (joshuafolkken/kit#3184). **No `tsx_arguments`**, the same as `pretool:guard`
+		// above: it runs before every guarded Codex call.
+	},
 	'cspell:dot': {
 		script: 'scripts/lint/cspell-cached.ts',
 		description: 'Run spell check including dotfiles',
@@ -158,7 +168,7 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 	'test:red': {
 		script: 'scripts/test/test-red.ts',
 		description:
-			'Run the changed unit tests against the pre-fix tree (merge-base worktree) and report red/green/no-test',
+			'Run the changed unit tests against the pre-fix tree (merge-base worktree) and report red/green/no-test/test-only',
 		category: 'Development',
 		reference: ['', 'developer', ['git', 'processes']],
 	},

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

@@ -66,10 +66,10 @@ const ISSUE_COMMANDS: Record<string, CommandEntry> = {
 	'issue:file': {
 		script: 'scripts/issue/issue-file-cli.ts',
 		description:
-			'File an Issue with every filing step: lint, Origin, duplicate scout, labels, then epic:bundle',
+			'File an Issue with every filing step: lint, Origin, 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,…>]',
+			'<title> --body-file <path> --depth <0|1|2> [--route <route>] [--label <name>] [--repo <owner/repo>] [--distinct <N,…>] [--over-cap] [--no-auto-ok]',
 			'automation',
 			['network'],
 		],

package/scripts/lane/lane-launch-cli.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { josh_command } from '#scripts/josh/josh-run'
+import { lane_registry } from '#scripts/lane/lane-registry'
 import { cli_flags } from '#scripts/lib/cli-flags'
 import { INSTALL_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { execa } from 'execa'
@@ -15,6 +16,7 @@ import { execa } from 'execa'
 // and messages are reused rather than cloned — `lane:open`'s cut-session guard and its `full` /
 // `already-open` refusals, `stash:pop`'s message-matched pop, `lane:dispatch`'s in-progress claim and
 // warning. Their explanations stream through to stderr; the child's pid is the one thing on stdout.
+// A lane a park kept is the one `already-open` it steps past — `lane_directory` below.
 
 const ARGV_OFFSET = 2
 const SUCCESS_EXIT_CODE = 0
@@ -86,14 +88,30 @@ type LaunchOutcome = { kind: 'launched'; pid: string } | { kind: 'unopened' } |
 const UNOPENED: LaunchOutcome = { kind: 'unopened' }
 const FAILED: LaunchOutcome = { kind: 'failed' }
 
+// **A lane a park kept open is resumed, not reopened** (joshuafolkken/kit#3228). A child parked before
+// its commit leaves its uncommitted work in its lane, and `lane:open` refuses that lane as
+// `already-open` — so the released child is dispatched into the kept tree instead. **Only a lane a
+// child was already dispatched into counts as kept**: `lane:dispatch` records the child's output in the
+// lane's `.env`, and a lane whose install failed never got that far, so it still goes through
+// `lane:open` and its refusal. So does a stranded lane, whose `.env` is gone with its tree.
+async function lane_directory(issue: string): Promise<string | undefined> {
+	const kept = await lane_registry.find_open_lane(issue)
+
+	if (kept?.output !== undefined) return kept.directory
+
+	const opened = await josh_command.josh_run(['lane:open', issue], should_forward_stderr)
+
+	return opened.code === SUCCESS_EXIT_CODE ? opened.out : undefined
+}
+
 // The launch chain in-process. The CLI prints the pid; `backlog:drive` launches through this same
 // chain (joshuafolkken/kit#2508).
 async function launch_lane(context: LaunchContext): Promise<LaunchOutcome> {
-	const opened = await josh_command.josh_run(['lane:open', context.issue], should_forward_stderr)
+	const directory = await lane_directory(context.issue)
 
-	if (opened.code !== SUCCESS_EXIT_CODE) return UNOPENED
+	if (directory === undefined) return UNOPENED
 
-	if (!(await prepare(context.stash, opened.out))) return FAILED
+	if (!(await prepare(context.stash, directory))) return FAILED
 
 	const dispatched = await josh_command.josh_run(
 		['lane:dispatch', context.issue],

package/scripts/lines/bytes-command.ts

@@ -4,6 +4,7 @@ import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { document_byte_budget } from '#scripts/document/document-byte-budget'
 import { entry_read_budget } from '#scripts/document/entry-read-budget'
+import { resident_budget } from '#scripts/document/resident-budget'
 
 // The package root, resolved from this file rather than the caller's working directory.
 const REPO_ROOT = fileURLToPath(new URL('../../', import.meta.url))
@@ -75,14 +76,40 @@ function normalized_path(argument: string): string {
 	return argument.startsWith('./') ? argument.slice('./'.length) : argument
 }
 
+function remaining_phrase(remaining: number): string {
+	return remaining < 0 ? `over by ${(-remaining).toString()}` : `${remaining.toString()} left`
+}
+
+// The resident document is held by a fixed limit rather than a block ratchet, and loosening it is
+// Tier C, so its row names the headroom or the overage but never a value to raise it to
+// (joshuafolkken/kit#3171).
+function resident_row(status: DocumentStatus): string {
+	const counts = `${status.current.toString()}/${status.recorded.toString()} bytes`
+
+	return `${status.path}${ROW_GAP}${counts} · ${remaining_phrase(status.remaining)}`
+}
+
+function is_resident(relative_path: string): boolean {
+	return resident_budget.limit_bytes_for(relative_path) !== undefined
+}
+
+function recorded_for(relative_path: string): number | undefined {
+	return (
+		resident_budget.limit_bytes_for(relative_path) ??
+		document_byte_budget.recorded_bytes_for(relative_path)
+	)
+}
+
 function argument_row(argument: string, root: string = REPO_ROOT): string {
 	const relative_path = normalized_path(argument)
-	const recorded = document_byte_budget.recorded_bytes_for(relative_path)
+	const recorded = recorded_for(relative_path)
 
 	if (recorded === undefined) return `${relative_path}${ROW_GAP}${NOT_BUDGETED}`
 	if (!existsSync(path.join(root, relative_path))) return `${relative_path}${ROW_GAP}${NOT_A_FILE}`
 
-	return status_row(status_of(relative_path, recorded, root))
+	const status = status_of(relative_path, recorded, root)
+
+	return is_resident(relative_path) ? resident_row(status) : status_row(status)
 }
 
 // A document is "near its ceiling" once less than this is left before its recorded block ceiling —
@@ -118,10 +145,6 @@ function entry_status_of(entry: string, recorded: number): EntryStatus {
 	return { entry, current, recorded, remaining }
 }
 
-function remaining_phrase(remaining: number): string {
-	return remaining < 0 ? `over by ${(-remaining).toString()}` : `${remaining.toString()} left`
-}
-
 // The primary budget, one row per entry: the total each workflow entry reads against its recorded
 // ceiling and the headroom left — printed on every scan, so the main budget is no longer a number the
 // gate reveals only when it fails (joshuafolkken/kit#2271).

package/scripts/notify/telegram-notify.ts

@@ -3,6 +3,10 @@ import { timed_fetch } from '#scripts/lib/timed-fetch'
 import { z } from 'zod'
 
 const TELEGRAM_API_BASE = 'https://api.telegram.org'
+// `sendMessage` refuses a text longer than this.
+const TELEGRAM_TEXT_LIMIT = 4096
+const BODY_TRUNCATION_MARK = '\n...'
+const TRAILING_HIGH_SURROGATE = /[\uD800-\uDBFF]$/u
 
 const telegram_environment_schema = z.object({
 	telegram_bot_token: z.string().min(1, { message: 'TELEGRAM_BOT_TOKEN is required' }),
@@ -188,10 +192,31 @@ function build_blocks(input: TelegramSendInput): Array<string> {
 	return blocks
 }
 
-function build_text(input: TelegramSendInput): string {
+function join_blocks(input: TelegramSendInput): string {
 	return build_blocks(input).join('\n\n')
 }
 
+// A cut between the two halves of a surrogate pair leaves a lone surrogate, which is not valid
+// UTF-8 once encoded, so the half is dropped with the rest of the tail.
+function head_of(body: string, kept: number): string {
+	const head = body.slice(0, kept)
+
+	return TRAILING_HIGH_SURROGATE.test(head) ? head.slice(0, -1) : head
+}
+
+// **The body is cut to fit Telegram's length limit, keeping its head** (joshuafolkken/kit#3242). A
+// warning carrying a whole driver stderr ran past 4096 characters and was refused with `400 Bad
+// Request`, so it reached nobody. A caller puts the cause first, so the tail is what is dropped, and the
+// header and the URLs around the body survive.
+function build_text(input: TelegramSendInput): string {
+	const text = join_blocks(input)
+	const overflow = text.length - TELEGRAM_TEXT_LIMIT
+	if (overflow <= 0 || input.body === undefined) return text
+	const kept = Math.max(0, input.body.length - overflow - BODY_TRUNCATION_MARK.length)
+
+	return join_blocks({ ...input, body: `${head_of(input.body, kept)}${BODY_TRUNCATION_MARK}` })
+}
+
 async function post_message(config: TelegramConfig, text: string): Promise<void> {
 	const url = `${TELEGRAM_API_BASE}/bot${config.bot_token}/sendMessage`
 	const response = await timed_fetch(url, {

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

@@ -1,4 +1,4 @@
-// The observation ledger's line grammar (`.claude/skills/workflow-commands/observation-filing.md`)
+// The observation ledger's line grammar (`.claude/skills/workflow-commands/observation-ledger.md`)
 // is fixed — `- k:<slug> | d<n> | <YYYY-MM-DD> | <where> | <what>` — but the path was collected in
 // `observation-ledger.ts` without a line ever being parsed, so a malformed append rode a flush
 // through unremarked. This validates a ledger entry line and reports why a broken one is broken