@joshuafolkken/kit 1.1240.0 → 1.1373.0

package/scripts/run/board/run-board-usage-text.ts

@@ -0,0 +1,80 @@
+import { run_board_labels } from './run-board-labels'
+import { run_board_machine } from './run-board-machine'
+import type { LaneUsage } from './run-board-usage'
+
+// A running row's CPU and memory column: `⚡ 20% 🧠1.6G`, each figure green, yellow or red in the
+// header gauges' `GAUGE_SHADES`. **A lane's thresholds are its share of what the running lanes may
+// use together**: the header's yellow threshold (`CPU_YELLOW` / `MEMORY_YELLOW`), never the whole
+// machine — the OS, the IDE and the browser always hold some of it — divided by the running rows the
+// frame draws. A lane turns yellow at three quarters of its share and red past the share itself — on
+// an 18 GB machine at 3.2 and 4.2 GB with three lanes running, 1.2 and 1.6 GB with eight. One lane's
+// share is the header's own threshold, so it takes no color the header gauge would not; a lane that
+// ends widens the others' shares, and their colors may turn back.
+
+const { GAUGE_SHADES, HEADER_ICONS, minute_of, painted } = run_board_labels
+const { CPU_YELLOW, MEMORY_YELLOW, percent_text, threshold_alert } = run_board_machine
+const YELLOW_OF_SHARE = 0.75
+const BYTES_PER_KB = 1024
+const BYTES_PER_GB = BYTES_PER_KB * BYTES_PER_KB * BYTES_PER_KB
+const GB_DECIMALS = 1
+const PART_GAP = ' '
+
+type Shade = (typeof GAUGE_SHADES)[keyof typeof GAUGE_SHADES]
+
+// A running lane's thresholds, in percent of the machine: its share of `pool_percent` among `running`.
+function lane_thresholds(pool_percent: number, running: number): { yellow: number; red: number } {
+	const share = pool_percent / Math.max(1, running)
+
+	return { yellow: share * YELLOW_OF_SHARE, red: share }
+}
+
+function shade_of(percent: number, pool_percent: number, running: number): Shade {
+	return GAUGE_SHADES[threshold_alert(percent, lane_thresholds(pool_percent, running))]
+}
+
+// The first sample has no CPU figure, so a row draws its memory alone until the second.
+function cpu_part(cpu_percent: number | undefined, running: number): string | undefined {
+	if (cpu_percent === undefined) return undefined
+
+	const shade = shade_of(cpu_percent, CPU_YELLOW, running)
+
+	return `${HEADER_ICONS.cpu}${painted(shade, percent_text(cpu_percent))}`
+}
+
+function memory_part(usage: LaneUsage, running: number): string {
+	const figure = `${(usage.memory_bytes / BYTES_PER_GB).toFixed(GB_DECIMALS)}G`
+	const shade = shade_of(usage.memory_percent, MEMORY_YELLOW, running)
+
+	return `${HEADER_ICONS.memory}${painted(shade, figure)}`
+}
+
+// `undefined` for a lane no process was found under; `running` is the frame's running rows.
+function text_of(usage: LaneUsage | undefined, running: number): string | undefined {
+	if (usage === undefined) return undefined
+
+	return [cpu_part(usage.cpu_percent, running), memory_part(usage, running)]
+		.filter((part) => part !== undefined)
+		.join(PART_GAP)
+}
+
+// The day a settled row finished, `10/8 `, where that is not the board's own day.
+function day_of(ended_ms: number, now_ms: number): string {
+	const ended = new Date(ended_ms)
+
+	if (ended.toDateString() === new Date(now_ms).toDateString()) return ''
+
+	return `${String(ended.getMonth() + 1)}/${String(ended.getDate())} `
+}
+
+// A settled row's finish time, drawn in the usage column: `🔚 14:05`, or
+// `🔚 10/8 14:05` on another day; `undefined` for a row settled with no recorded end. 🔚 is the
+// header's own end mark — 🏁 is already a done row's state icon.
+function finish_of(ended_ms: number | undefined, now_ms: number): string | undefined {
+	if (ended_ms === undefined) return undefined
+
+	return `${HEADER_ICONS.ended} ${day_of(ended_ms, now_ms)}${minute_of(ended_ms)}`
+}
+
+const run_board_usage_text = { finish_of, lane_thresholds, text_of }
+
+export { run_board_usage_text }

package/scripts/run/board/run-board-usage.ts

@@ -0,0 +1,165 @@
+// Each lane's CPU and memory on its `run:board` row: which lane is loading the machine the header's ⚡
+// and 🧠 show. How the processes are read is `run-board-usage-read.ts`'s; this file turns two readings
+// into each lane's figures.
+//
+// A lane's CPU is its processes' CPU time between two samples as a share of the whole machine — the
+// header's ⚡ scale, so the two read side by side, never Activity Monitor's one-core-is-100% — and its
+// memory the sum of their resident sets. Shared pages are counted once per process, so the figure is
+// larger than what the kernel holds; it compares lanes, which is all the column is for.
+
+const PERCENT = 100
+
+interface ProcessReading {
+	cpu_ms: number
+	rss_bytes: number
+}
+
+interface UsageMark {
+	at_ms: number
+	processes: ReadonlyMap<number, ProcessReading>
+	// Every listed process's lane, `undefined` for one under none — kept so each is looked up once.
+	lanes: ReadonlyMap<number, string | undefined>
+	// Each process's parent, kept only where the counts fold in the children each reaped — empty on the
+	// `ps` path, so nothing is deducted there.
+	parents: ReadonlyMap<number, number>
+	// The processes whose count was read with its reaped children folded in — one whose own read failed
+	// keeps the larger of `ps`'s own time and its last reading, so nothing reaped is taken off it.
+	folded: ReadonlySet<number>
+	cores: number
+	total_bytes: number
+}
+
+// The CPU share is `undefined` on the first sample, which has nothing to take a difference from.
+interface LaneUsage {
+	cpu_percent: number | undefined
+	memory_bytes: number
+	memory_percent: number
+}
+
+// Each lane's usage by its issue number.
+type LaneUsages = ReadonlyMap<number, LaneUsage>
+
+interface LaneProcess {
+	lane: string
+	pid: number
+	reading: ProcessReading
+}
+
+interface LaneTotal {
+	cpu_ms: number
+	rss_bytes: number
+}
+
+const NO_TOTAL: LaneTotal = { cpu_ms: 0, rss_bytes: 0 }
+
+function lane_processes(mark: UsageMark): Array<LaneProcess> {
+	const processes = [...mark.processes].map(([pid, reading]) => {
+		const lane = mark.lanes.get(pid)
+
+		return lane === undefined ? undefined : { lane, pid, reading }
+	})
+
+	return processes.filter((lane_process) => lane_process !== undefined)
+}
+
+// The nearest of a gone process's ancestors still running — the one whose reaped-children time it has
+// landed in. Walked through the last sample's parents, at most once round them. Where a parent between
+// them exited without waiting, launchd reaped the gone process instead and its counted time comes off an
+// ancestor that never received it; which happened cannot be read once both are gone, and taking it off
+// keeps the lane a lower bound where leaving it would count the usual waited-for child twice.
+function live_ancestor(pid: number, before: UsageMark, after: UsageMark): number | undefined {
+	let ancestor = before.parents.get(pid)
+
+	for (let step = 0; step < before.parents.size; step += 1) {
+		if (ancestor === undefined || after.processes.has(ancestor)) return ancestor
+		ancestor = before.parents.get(ancestor)
+	}
+
+	return undefined
+}
+
+// What each running process's count already holds from earlier samples: a counted process that ended
+// and was reaped brings all its time into its ancestor's, so what was counted for it is taken off there
+// — only where that ancestor's count was read with its reaped children folded in.
+function reaped_counted(before: UsageMark, after: UsageMark): Map<number, number> {
+	const counted = new Map<number, number>()
+	const gone = [...before.processes].filter(([pid]) => !after.processes.has(pid))
+
+	for (const [pid, reading] of gone) {
+		const ancestor = live_ancestor(pid, before, after)
+
+		if (ancestor !== undefined && after.folded.has(ancestor)) {
+			counted.set(ancestor, (counted.get(ancestor) ?? 0) + reading.cpu_ms)
+		}
+	}
+
+	return counted
+}
+
+// A process that started since the last sample spent all its CPU time inside the interval; a count
+// that went back — a reused process number — is read as none.
+function cpu_spent(
+	before: UsageMark,
+	counted: ReadonlyMap<number, number>,
+	{ pid, reading }: LaneProcess,
+): number {
+	const earlier = (before.processes.get(pid)?.cpu_ms ?? 0) + (counted.get(pid) ?? 0)
+
+	return Math.max(0, reading.cpu_ms - earlier)
+}
+
+function spent_of(
+	before: UsageMark | undefined,
+	after: UsageMark,
+): (process: LaneProcess) => number {
+	if (before === undefined) return () => 0
+
+	const counted = reaped_counted(before, after)
+
+	return (lane_process) => cpu_spent(before, counted, lane_process)
+}
+
+function totals_of(before: UsageMark | undefined, after: UsageMark): Map<string, LaneTotal> {
+	const totals = new Map<string, LaneTotal>()
+	const spent = spent_of(before, after)
+
+	for (const lane_process of lane_processes(after)) {
+		const total = totals.get(lane_process.lane) ?? NO_TOTAL
+
+		totals.set(lane_process.lane, {
+			cpu_ms: total.cpu_ms + spent(lane_process),
+			rss_bytes: total.rss_bytes + lane_process.reading.rss_bytes,
+		})
+	}
+
+	return totals
+}
+
+function cpu_percent(
+	before: UsageMark | undefined,
+	after: UsageMark,
+	cpu_ms: number,
+): number | undefined {
+	const elapsed = before === undefined ? 0 : after.at_ms - before.at_ms
+
+	return elapsed <= 0 ? undefined : (cpu_ms / (elapsed * after.cores)) * PERCENT
+}
+
+function lane_usage(before: UsageMark | undefined, after: UsageMark, total: LaneTotal): LaneUsage {
+	return {
+		cpu_percent: cpu_percent(before, after, total.cpu_ms),
+		memory_bytes: total.rss_bytes,
+		memory_percent: (total.rss_bytes / after.total_bytes) * PERCENT,
+	}
+}
+
+function usage_of(before: UsageMark | undefined, after: UsageMark): LaneUsages {
+	const totals = [...totals_of(before, after)]
+
+	return new Map(totals.map(([lane, total]) => [Number(lane), lane_usage(before, after, total)]))
+}
+
+const run_board_usage = { usage_of }
+
+export { run_board_usage }
+export type { LaneUsage, LaneUsages, ProcessReading, UsageMark }

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

@@ -0,0 +1,62 @@
+import { stamp_file } from '#scripts/josh/stamp-file'
+import type { RunCarry } from './run-carry'
+
+// A named `backlogrun #N` run, with or without `--only`, derives its named list from the `invocation`
+// string. **The invocation is not rewritten** to add an issue mid-run — `classify_claim` compares it
+// character for character to decide who owns the record, so an edited invocation would answer
+// `mismatch` at the next resume. The additions are kept beside it,
+// each marked with whether it jumps the queue (`pnpm josh run:add`) or joins its end
+// (`--no-priority`), and `remaining_of` folds them into the one ordered list the run reads.
+interface CarryAddition {
+	issue: number
+	is_priority: boolean
+}
+
+function issues_of(
+	added: ReadonlyArray<CarryAddition>,
+	is_priority: boolean,
+): ReadonlyArray<number> {
+	return added.filter((entry) => entry.is_priority === is_priority).map((entry) => entry.issue)
+}
+
+// The prioritized additions first, in the order they were added, then the declared list, then the
+// appended additions — each issue once, at its first position.
+function ordered(
+	declared: ReadonlyArray<number>,
+	added: ReadonlyArray<CarryAddition> = [],
+): ReadonlyArray<number> {
+	const sequence = [...issues_of(added, true), ...declared, ...issues_of(added, false)]
+
+	return sequence.filter((issue, index) => sequence.indexOf(issue) === index)
+}
+
+// An issue already added keeps its first entry, so a repeated `run:add` cannot reorder the queue.
+function next_added(
+	carry: RunCarry,
+	additions: ReadonlyArray<CarryAddition>,
+): Array<CarryAddition> {
+	const next = [...(carry.added ?? [])]
+
+	for (const addition of additions) {
+		if (next.every((entry) => entry.issue !== addition.issue)) next.push(addition)
+	}
+
+	return next
+}
+
+function add_issues(
+	target: string,
+	carry: RunCarry,
+	additions: ReadonlyArray<CarryAddition>,
+): RunCarry {
+	const next: RunCarry = { ...carry, added: next_added(carry, additions) }
+
+	stamp_file.write_stamp(target, next)
+
+	return next
+}
+
+const run_carry_added = { add_issues, ordered }
+
+export type { CarryAddition }
+export { run_carry_added }

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

@@ -1,11 +1,10 @@
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { cli_flags } from '#scripts/lib/cli-flags'
-import { run_issue_number } from '#scripts/run/run-issue-number'
+import { run_invocation } from '#scripts/run/run-invocation'
 import { run_carry, type CarryChange, type CarryClaimRequest, type CarryOwner } from './run-carry'
 
-// The argument half of `josh run:carry`. It sat inside `run-carry-cli.ts` until the ownership answers
-// joshuafolkken/kit#1722 added took that file to 96% of the 300-line limit, and the seam it split on
-// was already there: everything here turns `argv` into one `Request` and reads no record, while
-// everything left there acts on a record and prints. Nothing about the behavior moved with it.
+// The argument half of `josh run:carry`: everything here turns `argv` into one `Request` and reads no
+// record, while `run-carry-cli.ts` acts on a record and prints.
 
 const NO_INCREMENT = 0
 const ONE_CUT = 1
@@ -18,8 +17,8 @@ const EMPTY_INVOCATION = ''
 // A pid below this addresses a process group rather than a process, which `process-identity.ts`
 // rejects on the read side. Refused here too, so a record never records an owner nothing can be.
 const MIN_PID = 1
-// `--owner` is read by the two claiming alternatives and by the counting group (joshuafolkken/kit#1935):
-// a count checks the owner so a session whose record was handed off, or taken over by a successor,
+// `--owner` is read by the two claiming alternatives and by the counting group: a
+// count checks the owner so a session whose record was handed off, or taken over by a successor,
 // cannot advance a budget that is no longer its own. `--end` alone accepts it and ignores it, and a
 // usage line that offered it there would be promising an ownership check nothing performs.
 const USAGE =
@@ -35,11 +34,11 @@ const OPTIONS = {
 	merged: { type: 'string' },
 	owner: { type: 'string' },
 	// A boolean like `--cut`: it marks the end-of-run retrospective as run rather than counting an
-	// amount (joshuafolkken/kit#2328). It joins the counting group, so it carries `--owner` and is
-	// refused from a session that no longer owns the record, exactly as a merge count is.
+	// amount. It joins the counting group, so it carries `--owner` and is refused from a session that
+	// no longer owns the record, exactly as a merge count is.
 	retrospective: { type: 'boolean' },
 	resume: { type: 'string' },
-	// The retrospective's result carried to the event stream (joshuafolkken/kit#2342). It pairs with
+	// The retrospective's result carried to the event stream. It pairs with
 	// `--retrospective` and only with it: the mark and the result it records are one action, so a mark
 	// with nothing to read and a result no mark records are both usage errors rather than half-done
 	// closes. It is not a record field — `to_change` never carries it — so it rides the count request to
@@ -47,7 +46,7 @@ const OPTIONS = {
 	summary: { type: 'string' },
 	// **`--stopped <reason>` rides on `--end`, so it is a modifier rather than a fifth group.** A run
 	// that halts needing a person ends its record exactly as a clean one does; the reason is what turns
-	// that end into the ⏸️ confirmation the person gets after a session cut (joshuafolkken/kit#2136).
+	// that end into the ⏸️ confirmation the person gets after a session cut.
 	// Named without `--end` it is ignored, the way a read ignores every counting flag.
 	stopped: { type: 'string' },
 } as const
@@ -58,13 +57,13 @@ type ParsedValues = Partial<Record<OptionName, string | boolean>>
 type OptionValue = string | boolean | undefined
 
 // The counting request carries the owner so `count` can refuse a write from a session that is no
-// longer the record's owner (joshuafolkken/kit#1935).
+// longer the record's owner.
 interface CountRequest {
 	kind: 'count'
 	change: CarryChange
 	owner: CarryOwner
 	// The retrospective result to emit, present exactly when `change.retrospective` is set and never
-	// otherwise (joshuafolkken/kit#2342). The CLI reads it to append one event as it applies the mark.
+	// otherwise. The CLI reads it to append one event as it applies the mark.
 	summary?: string
 }
 
@@ -91,7 +90,7 @@ function to_count(value: OptionValue): number | undefined {
 }
 
 // **`--done` and `--merged` name an issue, so each is checked as one and not as a count.** The shape
-// is `run-issue-number.ts`'s, which already refuses `0` and a leading zero — the same rule the `run:*`
+// is `issue-number-shape.ts`'s, which already refuses `0` and a leading zero — the same rule the `run:*`
 // commands interpolate a number under, imported rather than restated. Absent is an empty object rather
 // than a zero: there is no issue to record, which is a different fact from recording issue zero. A
 // present-but-malformed value is `undefined`, which invalidates the whole invocation.
@@ -100,7 +99,7 @@ function to_issue(value: OptionValue): { issue?: number } | undefined {
 
 	if (text === undefined) return {}
 
-	if (!run_issue_number.ISSUE_NUMBER_PATTERN.test(text)) return undefined
+	if (!issue_number_shape.ISSUE_NUMBER_PATTERN.test(text)) return undefined
 
 	const issue = Number(text)
 
@@ -118,9 +117,9 @@ function to_done(value: OptionValue): Pick<CarryChange, 'done'> | undefined {
 	return parsed.issue === undefined ? {} : { done: parsed.issue }
 }
 
-// **`--merged` names the issue that merged, never a count** (joshuafolkken/kit#3296). A bare count
-// could not be matched against `merged_issues`, so a parent that counted a merge by hand and the
-// driver's `run:merge` for the same issue added two for one merge. Naming the issue makes the hand
+// **`--merged` names the issue that merged, never a count.** A bare count cannot be matched against
+// `merged_issues`, so a parent counting a merge by hand and the driver's `run:merge` for the same
+// issue would add two for one merge. Naming the issue makes the hand
 // count the same change `run:merge` applies — one merge plus its number — so `apply_change`'s
 // duplicate check holds whichever of the two arrives first.
 function to_merged(value: OptionValue): Pick<CarryChange, 'merged' | 'merged_issue'> | undefined {
@@ -205,8 +204,8 @@ function summary_text(values: ParsedValues): string | undefined {
 }
 
 // The mark and its result are one close: `--retrospective` needs a `--summary` to record, and a
-// `--summary` names a result no other flag records (joshuafolkken/kit#2342). Either flag without the
-// other is a usage error, so each must be present exactly when the other is.
+// `--summary` names a result no other flag records. Either flag without the other is
+// a usage error, so each must be present exactly when the other is.
 function is_summary_paired(values: ParsedValues): boolean {
 	return (summary_text(values) !== undefined) === (values.retrospective === true)
 }
@@ -229,12 +228,16 @@ function to_count_request(values: ParsedValues, owner: CarryOwner): Request | un
 // `--begin ""` is a loop whose invocation variable was unset. A record named by nothing is one every
 // other empty `--begin` then reads as its own, which is the cross-run inheritance `classify_claim`
 // exists to refuse — so it is a usage error rather than a record.
+// A `backlogrun` invocation is stored in `run_invocation.rebuild`'s canonical spelling, the one the
+// wake supervisor hands back, so no record is one the wake refuses.
 function to_claim_request(
-	invocation: string,
+	typed: string,
 	owner: CarryOwner,
 	is_adoption: boolean,
 ): Request | undefined {
-	if (invocation === EMPTY_INVOCATION) return undefined
+	if (typed === EMPTY_INVOCATION) return undefined
+
+	const invocation = run_invocation.rebuild(typed) ?? typed
 
 	return { kind: 'claim', claim: { invocation, owner, is_adoption } }
 }

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

@@ -38,7 +38,7 @@ function has_other_change(change: CarryChange): boolean {
 	return has_amount || change.done !== undefined || change.retrospective === true
 }
 
-// **A duplicate merge drops only the merge** (joshuafolkken/kit#3296): `--merged <issue>` may ride
+// **A duplicate merge drops only the merge**: `--merged <issue>` may ride
 // beside `--filed` or `--done` in one call, and those are still increments the record has not seen.
 // Only a duplicate carrying nothing else leaves the record untouched, which is `undefined` here.
 function effective_change(carry: RunCarry, change: CarryChange): CarryChange | undefined {