@joshuafolkken/kit 1.872.0

package/scripts/time-runtime/time-hook-transcript.ts

@@ -0,0 +1,82 @@
+import path from 'node:path'
+import { cost_transcript } from '#scripts/cost-runtime/cost-transcript'
+
+// Which transcript a Claude Code hook payload is actually about (joshuafolkken/kit#1424).
+//
+// **A hook fired for a forked agent's tool call is handed the *parent* session's transcript.** Both
+// events this package wires carry the same session fields, and neither of them names the fork's own
+// file: `transcript_path` is `<projects>/<slug>/<session-id>.jsonl` whatever agent issued the call,
+// and the fork is identified by a separate `agent_id`. Its transcript sits one level down, at
+// `<projects>/<slug>/<session-id>/subagents/agent-<agent-id>.jsonl`.
+//
+// **So every reader built on `transcript_path` alone has been reading the wrong run inside a fork**,
+// and two of them are: the batching guard (joshuafolkken/kit#1390) and the live density line
+// (joshuafolkken/kit#1329). Measured on 551 forked review agents in this checkout, the guard refused
+// **zero** calls — while a replay of the same transcripts through the fork's own file refuses 1–4 per
+// review round. The parent's timeline is frozen for as long as a fork runs, because the fork's lines
+// go to the fork's file: its open sequence never advances, so it either never reaches the limit or
+// reaches it once and can never qualify again. The density line has the matching symptom — inside a
+// fork it reports the *parent's* calls per round trip, which is a number about a run the reader is
+// not in.
+//
+// **The keys were already meant to be per-fork.** Both hooks key their throttle and refusal records
+// on the transcript the payload names, each documenting that this is what gives "a delegated child …
+// a run of its own". That claim only becomes true here.
+//
+// **A named agent's answer is its own path whether or not that file exists yet, and never the
+// parent's.** The fork's first call has nothing written under it, and "no history" is the honest
+// verdict there — both callers already turn an unreadable transcript into silence, which is the
+// failure direction each of them states. Falling back to the parent instead would judge the fork on a
+// timeline it never ran and, worse, spend the *parent's* refusal record: the parent is often mid-streak
+// exactly when it delegates, so its next genuine third single-call turn would be admitted in silence.
+
+// **The directory and the extension come from `cost-transcript.ts`, which walks this same layout to
+// discover the units a session delegated** — a path rebuilt by hand here would be free to disagree
+// with the one that discovery reads.
+const { TRANSCRIPT_EXTENSION } = cost_transcript
+// **The file-name prefix is stated here, because that module never spells it**: it lists `*.jsonl` and
+// takes the id from whatever it finds. So this one constant can drift from Claude Code, and the
+// direction it drifts in is the safe one — a renamed prefix makes the derived path absent, which both
+// callers already read as "nothing to say" rather than as a verdict about some other file.
+const AGENT_PREFIX = 'agent-'
+// **Letters, digits, `_` and `-` only, because this value is joined into a path.** An id carrying a
+// separator or a `..` segment would resolve outside the session's own directory, and a hook payload is
+// input rather than something this package produced. A spelling the pattern rejects reads as "no fork
+// named", which falls back to the payload's own path.
+const AGENT_ID_PATTERN = /^[\w-]+$/u
+
+// **`null` is accepted alongside `undefined` rather than rejected**, because a payload spelling the
+// absent agent as `null` must read as "no fork" and not as a payload the caller's schema throws out —
+// which would take both hooks off the main line entirely, in silence.
+function is_agent_id(value: string | null | undefined): value is string {
+	return typeof value === 'string' && AGENT_ID_PATTERN.test(value)
+}
+
+// Where the fork's transcript sits, given the session file the payload named. **Exported so a test —
+// and any later caller — can name the file without spelling the layout again**, which is the same
+// reason `cost-transcript.ts` exports `unit_directory`.
+function fork_path(transcript_path: string, agent_id: string): string {
+	const directory = path.dirname(transcript_path)
+	const session_id = path.basename(transcript_path, TRANSCRIPT_EXTENSION)
+	const file_name = `${AGENT_PREFIX}${agent_id}${TRANSCRIPT_EXTENSION}`
+
+	return path.join(cost_transcript.unit_directory(directory, session_id), file_name)
+}
+
+// The transcript a hook should read and key its record on, given the two fields the payload carries.
+//
+// **A path that is not a transcript is answered with itself**, since nothing can be derived from it and
+// guessing would name a file in some other layout entirely.
+function transcript_of(transcript_path: string, agent_id: string | null | undefined): string {
+	if (!is_agent_id(agent_id)) return transcript_path
+	if (!transcript_path.endsWith(TRANSCRIPT_EXTENSION)) return transcript_path
+
+	return fork_path(transcript_path, agent_id)
+}
+
+const time_hook_transcript = {
+	fork_path,
+	transcript_of,
+}
+
+export { time_hook_transcript }

package/scripts/time-runtime/time-instant.ts

@@ -0,0 +1,20 @@
+// One decision about an unparseable timestamp, made once (joshuafolkken/kit#1268).
+//
+// Both halves of a run carry dates from somewhere else — the transcript's `timestamp` and GitHub's
+// `created_at` / `merged_at` / check-run times — and both have to answer the same question about a
+// value they cannot read. `undefined` is the answer, never `NaN` and never `0`: a `NaN` propagates
+// silently through every arithmetic that touches it, and a `0` reads as the epoch, which puts a span
+// in 1970 and makes a merge appear before its own pull request.
+//
+// It lives in its own module rather than in either reader because a copy in each is exactly the
+// clone `CLAUDE.md` prohibits, and the two copies would disagree the first time one of them learned
+// to accept another format.
+function parse_instant(raw: string | null | undefined): number | undefined {
+	const parsed = Date.parse(raw ?? '')
+
+	return Number.isNaN(parsed) ? undefined : parsed
+}
+
+const time_instant = { parse_instant }
+
+export { time_instant }

package/scripts/time-runtime/time-markers.ts

@@ -0,0 +1,228 @@
+import { cost_attribute } from '#scripts/cost-runtime/cost-attribute'
+import { json_value } from '#scripts/lib/json-value'
+
+// Which workflow boundary a tool call marks (joshuafolkken/kit#1269).
+//
+// The per-tool totals answer "which command is slow" and say nothing about "which *stage* is long".
+// A stage is bounded by things a transcript can be read for, so this module is the one rule for what
+// counts as a boundary — and it is deliberately about **recognizable commands, never durations**: a
+// boundary guessed from "this interval looks like a review" would move whenever a run got faster,
+// which is the one thing a measurement used to compare two runs must not do.
+//
+// **Only the boundaries `josh_command` cannot already express live here.** `gate`, `pr` and `merge`
+// are `pnpm josh <cmd>` invocations that `time-spans.ts` already names, and re-detecting them here
+// would be a second rule for the same thing. What is left is four: the plan comment, the first
+// edit, the code-review invocation, and the instant the workflow itself opened.
+//
+// **The workflow boundary has two spellings, and both are the same marker** (joshuafolkken/kit#1299).
+// A run is not a session: the transcript attributed to an issue reaches back into whatever the
+// session was doing before the keyword was typed, so without a marker for "the run starts here"
+// that earlier conversation is measured as part of it. Loading the `workflow-commands` skill is the
+// first act of every entry point, and writing the `in-progress` label is the first act every one of
+// them performs on GitHub — so the earliest of the two is taken and neither is required, which is
+// what keeps a delegated unit (whose parent loaded the skill) and a resumed run measurable.
+//
+// **The review boundary sits on whatever call the main line spends the review inside**, and since
+// joshuafolkken/kit#1855 that is an `Agent` call rather than a `Skill` one. Before it, the main line
+// loaded `/code-review` through the `Skill` tool and that call returned three to four minutes later
+// with the finding list — so the `Skill(code-review)` call carried the review's whole duration and
+// was the marker. #1855 moved the review into a forked subagent launched with the `Agent` tool, and
+// the main line no longer loads the skill at all: the `Skill(code-review)` call now lives inside the
+// fork's own transcript, where it returns instantly (it only loads the skill text), and the review's
+// real wall clock is the fork's own `Read`/`grep` spans. Those spans carry no marker of their own, so
+// they inherit the marker of the parent span they run inside — the `Agent` call (`time-overlap.ts`,
+// joshuafolkken/kit#1439). Left unmarked that parent deletes the phase rather than moving it, which is
+// the ~0 ms `review` joshuafolkken/kit#1846 measured. So the `Agent` launch is marked here, exactly
+// as the `Skill` call was, and the old `Skill(code-review)` marker stays for pre-#1855 transcripts.
+//
+// **The launch is recognized by its prompt carrying both `/code-review` and `review:attest`.** The
+// first is the instruction to invoke the review skill; the second is the attestation line
+// `pnpm josh review:brief` emits into the brief the launch passes verbatim (joshuafolkken/kit#1522).
+// Neither alone is enough: an investigation subagent about the review tooling quotes `/code-review`
+// in prose and is handed no brief, so `review:attest` is what tells a genuine review launch from a
+// discussion of one — measured against five real launches, it admits the review and rejects every
+// investigation.
+
+type PhaseMarker = 'none' | 'plan' | 'edit' | 'review' | 'workflow'
+
+const NO_MARKER: PhaseMarker = 'none'
+const PLAN_MARKER: PhaseMarker = 'plan'
+const EDIT_MARKER: PhaseMarker = 'edit'
+const REVIEW_MARKER: PhaseMarker = 'review'
+const WORKFLOW_MARKER: PhaseMarker = 'workflow'
+
+// Writing a new file opens implementation exactly as changing an existing one does, so both count.
+const EDIT_TOOLS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit'])
+
+const SKILL_TOOL = 'Skill'
+const SKILL_KEY = 'skill'
+const REVIEW_SKILL = 'code-review'
+const WORKFLOW_SKILL = 'workflow-commands'
+
+// The forked review launch (joshuafolkken/kit#1846). `Agent` is the tool the main line spawns the
+// review subagent with, and `prompt` is where the instruction to it lives.
+const AGENT_TOOL = 'Agent'
+const PROMPT_KEY = 'prompt'
+// Both must be present. `/code-review` is the invocation the launch tells the subagent to run;
+// `review:attest` is the attestation line the passed-through `review:brief` carries and a discussion
+// of the review never does — so the pair admits a genuine review launch and rejects an investigation
+// subagent that merely mentions the review tooling.
+const REVIEW_INVOCATION = '/code-review'
+const REVIEW_ATTEST = 'review:attest'
+
+// The two skill calls that are boundaries, keyed by name. A map rather than a second `if`, so a
+// third boundary skill is a row and not another branch through the same function.
+const SKILL_MARKERS = new Map<string, PhaseMarker>([
+	[REVIEW_SKILL, REVIEW_MARKER],
+	[WORKFLOW_SKILL, WORKFLOW_MARKER],
+])
+
+// **The `repos/` prefix is what makes this the API path and not any mention of an issue.** Matching a
+// bare `issues/<N>` alongside a `body=` charged the plan boundary to
+// `pnpm josh notify --issue-url "https://github.com/<owner>/<repo>/issues/<N>" --body=…`, which every
+// mid-run stop sends — so planning would have ended at whichever notification went out first.
+const ISSUE_API_PATTERN = /repos\/\S+\/issues\/\d+/u
+
+// The field that separates posting a plan from the other calls made against the same path. The title
+// normalization is `-X PATCH … issues/<N> -f title=…` and the label call is `issues/<N>/labels`;
+// neither writes a body, and both run before the plan in every `fullrun`.
+const BODY_FIELD_PATTERN = /\bbody=/u
+
+// `gh issue comment <N> --body …` posts the same comment without an API path, and `--body-file`
+// carries no `body=` at all — so a plan posted either way went undetected under the API form alone.
+const ISSUE_COMMENT_PATTERN = /\bgh\s+issue\s+comment\b/u
+const BODY_FLAG_PATTERN = /--body(?:-file)?\b/u
+
+// **The add form, not the label's name anywhere in the command.** The prerequisite branch removes the
+// same label with `-X DELETE …/labels/in-progress`, which is a run ending its hold on an issue rather
+// than opening one — matched loosely, that call would move the run's start to somewhere near its end.
+// The API path is required alongside it for the reason the plan boundary requires one: a command that
+// merely quotes the flag, which this repository's own issue bodies do, is not the call.
+// The number is captured because the same call is the only place a run states, in its own transcript,
+// which issue it is running (joshuafolkken/kit#1617). Capturing changes nothing for the `test` above
+// it — the boundary is still the whole match.
+// **The trailing `(?!\/)` is what keeps the capture on the issue being labelled.** `labels[]=in-progress`
+// only has to appear somewhere in the command, and the capture takes the leftmost match — so one call
+// that removed another issue's label before adding this one would declare the run as that other issue,
+// with nothing to correct it because under lanes this declaration is the only evidence there is. The
+// removal form is `…/labels/in-progress`, so refusing a path continued by a slash leaves exactly the
+// add form. The `test` above is unaffected: it already required the `labels[]=` field, which the
+// removal form does not carry.
+const ISSUE_LABELS_PATTERN = /repos\/\S+\/issues\/(\d+)\/labels\b(?!\/)/u
+const IN_PROGRESS_FIELD = 'labels[]=in-progress'
+
+// "This call declares no issue", which is the attribution's own sentinel rather than a second one:
+// what `bash_issue` returns is read by `cost_attribute` and by nothing else, so two spellings of "no
+// issue" could only drift apart.
+const NO_ISSUE = cost_attribute.UNATTRIBUTED_KEY
+
+// One string field of a call's input, or `''` where the input is not a record or the field is not a
+// string. Shared by the two calls that read one — the skill name and the agent prompt — so the
+// record guard exists once.
+function string_field(input: unknown, key: string): string {
+	if (!json_value.is_record(input)) return ''
+
+	const value = input[key]
+
+	return typeof value === 'string' ? value : ''
+}
+
+function skill_name(input: unknown): string {
+	return string_field(input, SKILL_KEY)
+}
+
+// An `Agent` launch's boundary: the review marker when its prompt is a genuine code-review run, and
+// no marker otherwise.
+function agent_marker(input: unknown): PhaseMarker {
+	const prompt = string_field(input, PROMPT_KEY)
+	const is_review = prompt.includes(REVIEW_INVOCATION) && prompt.includes(REVIEW_ATTEST)
+
+	return is_review ? REVIEW_MARKER : NO_MARKER
+}
+
+// A non-Bash call's boundary, read from the tool name and its input.
+function tool_marker(name: string, input: unknown): PhaseMarker {
+	if (EDIT_TOOLS.has(name)) return EDIT_MARKER
+	if (name === AGENT_TOOL) return agent_marker(input)
+	if (name !== SKILL_TOOL) return NO_MARKER
+
+	return SKILL_MARKERS.get(skill_name(input)) ?? NO_MARKER
+}
+
+function is_api_body_write(command: string): boolean {
+	return ISSUE_API_PATTERN.test(command) && BODY_FIELD_PATTERN.test(command)
+}
+
+function is_issue_comment(command: string): boolean {
+	return ISSUE_COMMENT_PATTERN.test(command) && BODY_FLAG_PATTERN.test(command)
+}
+
+function is_in_progress_label(command: string): boolean {
+	return ISSUE_LABELS_PATTERN.test(command) && command.includes(IN_PROGRESS_FIELD)
+}
+
+// Which issue a Bash call declares its run to be running, or `undefined` where it declares nothing.
+//
+// **Attribution's other evidence is the branch, and a lane run has none to give**
+// (joshuafolkken/kit#1617): the session writing the transcript stays on the default branch while the
+// child's commands run in a linked work tree, so `gitBranch` says `main` on every line and
+// `cost_attribute` has nothing to fill forward. This call is what is left, and it is the right thing
+// to be left with — it is the run naming its own issue, once, and `time-sessions.ts` already treats
+// the same call as the statement of *whose* run a session is.
+//
+// **Only the `in-progress` add form counts**, exactly as the marker above: the `-X DELETE` form ends a
+// run's hold rather than opening one, and every other `issues/<N>/…` call a session makes — an epic
+// insertion, a plan comment, a completion comment — names an issue it is not running.
+// **The declaration is read from the one chained command that makes it, not from the call as a
+// whole.** `&&`, `||` and `;` join independent commands into a single Bash call, and only one of them
+// is the add — so a call that touched another issue's labels first (parking one child and starting
+// another, or removing the label before adding it) would have its *leftmost* issue path captured. The
+// lookahead on the pattern above rules out the removal form; splitting rules out every other one, and
+// it has to be ruled out here rather than corrected later, because under lanes this declaration is
+// the only evidence there is.
+// The surrounding whitespace is deliberately not matched: neither test below is anchored, so the
+// spaces a split leaves on a part change nothing, and `\s*` on both sides of an alternation is the
+// shape `sonarjs/super-linear-regex` refuses.
+const COMMAND_SEPARATOR = /&&|\|\||;/u
+
+function label_issue(part: string): number {
+	const matched = ISSUE_LABELS_PATTERN.exec(part)
+
+	return matched?.[1] === undefined ? NO_ISSUE : Number(matched[1])
+}
+
+function bash_issue(command: string): number {
+	for (const part of command.split(COMMAND_SEPARATOR)) {
+		if (is_in_progress_label(part)) return label_issue(part)
+	}
+
+	return NO_ISSUE
+}
+
+// A Bash call's boundary, read from the command it runs. Two are detected here — writing a body to
+// an issue, and labelling one `in-progress` — because the rest of what Bash marks is already a
+// `pnpm josh <cmd>` name.
+//
+// **Which of those writes is the plan is not decided here**: the completion comment and an
+// auto-decision log take the same shape, so `time-phases.ts` accepts only a marker that closes
+// before the first edit. The label carries no body, so the two tests cannot both match one command.
+function bash_marker(command: string): PhaseMarker {
+	if (is_in_progress_label(command)) return WORKFLOW_MARKER
+
+	return is_api_body_write(command) || is_issue_comment(command) ? PLAN_MARKER : NO_MARKER
+}
+
+const time_markers = {
+	NO_MARKER,
+	PLAN_MARKER,
+	EDIT_MARKER,
+	REVIEW_MARKER,
+	WORKFLOW_MARKER,
+	NO_ISSUE,
+	tool_marker,
+	bash_marker,
+	bash_issue,
+}
+
+export type { PhaseMarker }
+export { time_markers }

package/scripts/time-runtime/time-phase-names.ts

@@ -0,0 +1,123 @@
+// The phase vocabulary — the names a run's wall clock is cut into, the order they print in, and the
+// two tables keyed by them.
+//
+// **It sits apart from `time-phases.ts` for the reason `time-phase-fixture.ts` does**: that file
+// grew past its length limit as phases were added to it, and this is the half with nothing to decide
+// — it says what a phase *is*, while the file it left decides which one a span belongs to. Nothing
+// here imports the classifier, so the dependency runs one way and the next phase added costs one
+// line rather than a fresh argument about where to put it (joshuafolkken/kit#1331).
+
+type PhaseName =
+	| 'plan'
+	| 'setup'
+	| 'implement'
+	| 'gate'
+	| 'rework'
+	| 'review'
+	| 'pr'
+	| 'wrapup'
+	| 'ci'
+	| 'merge'
+	| 'wait'
+	| 'wait-outside'
+	| 'pre-run'
+	| 'post-run'
+	| 'other'
+
+const PLAN_PHASE: PhaseName = 'plan'
+const SETUP_PHASE: PhaseName = 'setup'
+const IMPLEMENT_PHASE: PhaseName = 'implement'
+const GATE_PHASE: PhaseName = 'gate'
+const REWORK_PHASE: PhaseName = 'rework'
+const REVIEW_PHASE: PhaseName = 'review'
+const PR_PHASE: PhaseName = 'pr'
+const WRAPUP_PHASE: PhaseName = 'wrapup'
+const CI_PHASE: PhaseName = 'ci'
+const MERGE_PHASE: PhaseName = 'merge'
+const WAIT_PHASE: PhaseName = 'wait'
+const WAIT_OUTSIDE_PHASE: PhaseName = 'wait-outside'
+const PRE_RUN_PHASE: PhaseName = 'pre-run'
+const POST_RUN_PHASE: PhaseName = 'post-run'
+const OTHER_PHASE: PhaseName = 'other'
+
+// Run order, which is the order they are printed in — by where a phase *opens*, so `wrapup` sits
+// beside the pull request it starts at rather than after the merge it runs beside. The two wait
+// rows, the two outside-the-run rows and `other` come last because none is a stage anything passes
+// through: two are time spent between the stages, two are time that was not the run's at all, and
+// the last is the remainder. **`wait-outside` sits immediately after `wait`** so the two halves of
+// one quantity are read side by side — that comparison is the whole point of the split, and a row
+// placed further down would have to be looked for.
+const PHASE_ORDER: ReadonlyArray<PhaseName> = [
+	PLAN_PHASE,
+	SETUP_PHASE,
+	IMPLEMENT_PHASE,
+	GATE_PHASE,
+	REWORK_PHASE,
+	REVIEW_PHASE,
+	PR_PHASE,
+	WRAPUP_PHASE,
+	CI_PHASE,
+	MERGE_PHASE,
+	WAIT_PHASE,
+	WAIT_OUTSIDE_PHASE,
+	PRE_RUN_PHASE,
+	POST_RUN_PHASE,
+	OTHER_PHASE,
+]
+
+// None is a boundary marker, so none can fail to be found: `other` is the remainder, and the two wait
+// rows are read off the span's own category. A run nobody waited on genuinely waited zero minutes,
+// which is the one answer `not detected` must not be given for — so these are detected whenever a
+// transcript was read at all, rather than on a marker.
+//
+// **They are withheld on exactly the terms the three transcript category rows are**
+// (joshuafolkken/kit#1295) — no span read at all. `wait` printing `0.0 min` where nothing was read
+// asserts that nobody waited, and the run that produces it is the one a reader is least able to check.
+// Keying every one of them off the same criterion is also what keeps `wait` + `wait-outside` equal to
+// the `human wait` category row: they are withheld together or printed together, never some of each.
+//
+// **`wait-outside` is in this set rather than detected on the run's edges** (joshuafolkken/kit#1331),
+// which is where it differs from `pre-run` and `post-run`. Its zero is not a claim about an unchecked
+// half, because those two rows report the same two boundaries in their own right — a reader seeing
+// `pre-run  not detected` beside `wait-outside  0.0 min` already knows that edge was never found, and
+// a third row saying so would restate it at the price of the invariant above.
+const SPAN_BACKED_PHASES: ReadonlySet<PhaseName> = new Set([
+	WAIT_PHASE,
+	WAIT_OUTSIDE_PHASE,
+	OTHER_PHASE,
+])
+
+const GATE_COMMAND = 'josh gate'
+
+// The `pnpm josh <cmd>` names `time-spans.ts` already reads off a Bash call, mapped to the phase
+// each one *is*. Read from that field rather than re-detected here, so what counts as a gate run is
+// one rule and not two.
+const COMMAND_PHASES = new Map<string, PhaseName>([
+	[GATE_COMMAND, GATE_PHASE],
+	['josh git', PR_PHASE],
+	['josh pr', PR_PHASE],
+	['josh followup', MERGE_PHASE],
+])
+
+export type { PhaseName }
+export {
+	CI_PHASE,
+	COMMAND_PHASES,
+	GATE_COMMAND,
+	GATE_PHASE,
+	IMPLEMENT_PHASE,
+	MERGE_PHASE,
+	OTHER_PHASE,
+	PHASE_ORDER,
+	PLAN_PHASE,
+	POST_RUN_PHASE,
+	PRE_RUN_PHASE,
+	PR_PHASE,
+	REVIEW_PHASE,
+	REWORK_PHASE,
+	SETUP_PHASE,
+	SPAN_BACKED_PHASES,
+	WAIT_OUTSIDE_PHASE,
+	WAIT_PHASE,
+	WRAPUP_PHASE,
+}