@joshuafolkken/kit 1.1229.0 → 1.1370.0

package/scripts/rules/run-tail-rule.ts

@@ -4,27 +4,23 @@ import type { GuardedCall } from '#scripts/time-runtime/time-batch-guard'
 import { time_shell } from '#scripts/time-runtime/time-shell'
 import { shell_segments } from './shell-segments'
 
-// The trigger and the decision behind the `run-tail` row of `delivered-rules.ts`
-// (joshuafolkken/kit#1510).
+// The trigger and the decision behind the `run-tail` row of `delivered-rules.ts`.
 //
-// **Two stops, one cause.** `fullrun #1501` ran 45m03s on about 17 minutes of work. Of the 25 idle
-// minutes, 6m28s was a `pnpm josh git -y` issued in the **foreground** with a 900-second tool
-// timeout — above the harness's 600-second cap, so the harness detached it at the cap and nothing
-// read the output file afterwards — and 6m06s was bare CI: the push landed, the turn ended, and the
-// merge started only when the person asked whether it was merging. Both halves handed the deciding
-// of when to look back to something that was never going to decide it.
+// **Two stops, one cause.** A `pnpm josh git -y` issued in the **foreground** with a tool timeout
+// above the harness's 600-second cap is detached at the cap with nothing reading the output file
+// afterwards; and a push that ends the turn leaves the merge waiting until a person asks. Both hand
+// the deciding of when to look back to something that is never going to decide it.
 //
 // **So the refusal is put in front of the foreground call, which is the last call before the seam.**
 // A turn ending between the push and `pnpm josh followup` is an *absence* of a call, and no
 // `PreToolUse` hook can see one; the foreground push is a call, and refusing it delivers both halves
-// at the one moment they still bind. That is the same reading joshuafolkken/kit#1570 took for a wait
-// timer and joshuafolkken/kit#1556 for a verification behind a pipe.
+// at the one moment they still bind. That is the same reading `early-heartbeat.ts` takes for a wait
+// timer and `piped-verification.ts` for a verification behind a pipe.
 //
 // **Backgrounding is what closes the seam, rather than a second rule about turns.** A command issued
 // with `run_in_background` re-invokes the run when it exits, so the completion notification is what
-// resumes the tail — not a person noticing the silence. joshuafolkken/kit#1333 had already
-// established the same end state as a procedure, and symptom 2 is its regression; prose that had to
-// be remembered was what regressed, so this time the moment is named as a call.
+// resumes the tail — not a person noticing the silence. Prose that has to be remembered is what
+// regresses, so the moment is named as a call.
 //
 // **A call already made properly is not a trigger.** Reissued with `run_in_background`, the same
 // command falls through and the run pays nothing — the shape `is_body_only_issue_read` takes for a
@@ -90,7 +86,7 @@ function is_backgrounded(input: unknown): boolean {
 }
 
 /**
- * The occasion this rule governs: the push step, in either spelling (joshuafolkken/kit#1643).
+ * The occasion this rule governs: the push step, in either spelling.
  *
  * It is the denominator `scripts/rules/rule-value.ts` reads for this row, because the trigger below
  * fires only on the foreground spelling — a run that detached every push never trips it, so the rate
@@ -129,7 +125,7 @@ function is_foreground_push_step(call: GuardedCall): boolean {
  * changes what the run *knows*. A push does not work that way: a `queue` or an `epicrun` issues one
  * per child, and a round-2 fix commit issues a second inside a single `fullrun`. Refused once and
  * free afterwards, every push but the first is back to the run's own self-restraint, which is the
- * thing joshuafolkken/kit#1333 already measured failing.
+ * thing that fails.
  *
  * **It also removes the stand-aside this row has no use for.** `is_first_delivery` stays silent for
  * ten seconds after the batching guard stamps any refusal; the push step is never a candidate of that

package/scripts/rules/shell-body-trigger.ts

@@ -1,5 +1,5 @@
-// The `shell-body` row's trigger, in a module of its own rather than inside the enumeration
-// (joshuafolkken/kit#1198). Every other row's trigger is already shaped that way — `time_batch_guard`
+// The `shell-body` row's trigger, in a module of its own rather than inside the enumeration.
+// Every other row's trigger is already shaped that way — `time_batch_guard`
 // and `cost_blocks` each hold their own reading of a call — and this one needs a small model of what
 // zsh does inside double quotes, which is more than an enumeration row should carry. The split also
 // gives that model a suite of its own, so a regex change is read beside the cases it has to keep.
@@ -53,8 +53,8 @@ const INLINE_BODY_VALUE = new RegExp(
 	'gu',
 )
 
-// **What zsh evaluates inside double quotes, measured in this harness rather than assumed**
-// (joshuafolkken/kit#1198): a backtick runs as command substitution and a `$` expands. `!` does
+// **What zsh evaluates inside double quotes, measured in this harness rather than assumed**:
+// a backtick runs as command substitution and a `$` expands. `!` does
 // **not** — history expansion is off in a non-interactive zsh, and `"hello!world"` survives intact —
 // so it is deliberately absent: a rule that fired on every exclamation mark would be firing on turns
 // where nothing is wrong, which `prompts/collaboration-workflow/rule-delivery.md` names as worse than
@@ -73,8 +73,8 @@ const WHOLE_VALUE_SUBSTITUTION = new RegExp(`^${SUBSTITUTION}$`, 'u')
 
 // **A backtick inside the substitution voids the exemption.** The exemption's reason is that the
 // *output* is not re-scanned — but the substitution's own command is shell text, and a backtick in it
-// runs exactly as an inline one does. `body="$(echo \`date\`)"` executes `date`, which is the damage
-// joshuafolkken/kit#1198 was filed over, merely written one level in. A nested `$( … )` is the safe
+// runs exactly as an inline one does. `body="$(echo \`date\`)"` executes `date`, which is the inline
+// damage merely written one level in. A nested `$( … )` is the safe
 // spelling of the same composition and stays exempt.
 const BACKTICK = '`'
 
@@ -118,7 +118,7 @@ function is_shell_evaluated_body(command: string): boolean {
 	return false
 }
 
-// **The safe spellings, which is what keeping this rule looks like** (joshuafolkken/kit#1643). They
+// **The safe spellings, which is what keeping this rule looks like**. They
 // are the ones the refusal hands back: the `*-file` flags, a field whose value is a file reference,
 // and `$'…'` quoting. The `*-file` flags cannot reach `INLINE_BODY_VALUE` at all — the note at the top
 // of this file records why — so they are read straight off the command rather than out of a value.

package/scripts/rules/shell-segments.ts

@@ -20,10 +20,8 @@ function segments_of(command: string): Array<string> {
 	return command.split(SEGMENT_SEPARATOR).map((segment) => segment.trim())
 }
 
-// **Both spellings still match, and the expansion is no longer this file's** (joshuafolkken/kit#1643
-// for the reading, joshuafolkken/kit#1789 for where it now happens). A `josh_names` here used to widen
-// each caller's set with every alias standing for one of its names; `josh_command_of` expands the
-// alias in the command it reads, so `pnpm josh ga` arrives as `josh gate` and a caller's canonical set
+// **Both spellings match, and the expansion is not this file's.** `josh_command_of` expands the alias
+// in the command it reads, so `pnpm josh ga` arrives as `josh gate` and a caller's canonical set
 // matches it as it is. Widening as well would be a second copy of one rule, and the caller that
 // forgot it would be the one that stops seeing `pnpm josh ga` at all — which is why each caller's own
 // suite names a call in its alias spelling.

package/scripts/rules/stop-rules.ts

@@ -5,8 +5,7 @@ import { issue_citation } from './issue-citation'
 import { lane_background } from './lane-background'
 import { reply_language } from './reply-language'
 
-// The stop-time rules, delivered on the `Stop` hook (joshuafolkken/kit#2121, joshuafolkken/kit#2422,
-// joshuafolkken/kit#2445).
+// The stop-time rules, delivered on the `Stop` hook.
 //
 // **It exists because `.claude/settings.json` wired no `Stop` event.** The four events it did wire
 // (`SessionStart` / `UserPromptSubmit` / `PreToolUse` / `PostToolUse`) can catch the moment a call is
@@ -20,7 +19,7 @@ import { reply_language } from './reply-language'
 // permission envelope. The stop guard is a second *entry* on the one foundation, exactly as
 // `pretool-guard` is one — not a second copy of the plumbing.
 //
-// **Every rule refuses** (joshuafolkken/kit#2247). Missing the stop notification or leaving a hold
+// **Every rule refuses**. Missing the stop notification or leaving a hold
 // on a clean tree costs a person a silent wait or a trampled tree; a bare `#N` in the reply reaches
 // the person watching but not the model that could fix it, so it too blocks — `{"decision":"block"}`
 // is the one channel a `Stop` hook has to the model, and `stop_hook_active` caps a false positive at a
@@ -45,14 +44,14 @@ interface StopContext {
 	hold_present: boolean
 	// `git status --porcelain` came back empty.
 	tree_clean: boolean
-	// That record carries a `prrun` stop mark (joshuafolkken/kit#3023): the run stopped at a green pull
+	// That record carries a `prrun` stop mark: the run stopped at a green pull
 	// request and keeps the hold over a clean tree on purpose, so a person can look before it merges.
 	prrun_stopped: boolean
 	// A `confirmation` notify is on this run's transcript tail.
 	notified: boolean
 	// The turn's session-facing reply text.
 	message: string
-	// The person's last prompt — a `#N` it already carried is quoted, not cited (joshuafolkken/kit#2819).
+	// The person's last prompt — a `#N` it already carried is quoted, not cited.
 	prompt: string
 	// This stop already forced a continuation earlier in the prompt — the loop-breaker Claude Code
 	// documents, so a run that will not comply is not blocked forever.
@@ -66,26 +65,29 @@ interface StopContext {
 	// The owner of the repository the session runs in, or `undefined` when it cannot be read.
 	session_owner: string | undefined
 	// This session is a headless `backlogrun` parent with lanes still in flight and no cut handed its
-	// record off — `run-headless.ts` → `must_keep_waiting` (joshuafolkken/kit#2437).
+	// record off — `run-headless.ts` → `must_keep_waiting`.
 	headless_waiting: boolean
 	// How many headless-wait refusals sit on this run's transcript tail — the spin bound below.
 	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 — a command or a subagent — has not finished —
-	// `lane_background.pending_background_ids` over the transcript tail (joshuafolkken/kit#2704).
+	// `lane_background.pending_background_ids` over the transcript tail.
 	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.
+	// A backgrounded subagent this run launched has not finished — `lane_background.pending_agent_ids`.
+	// Apart from `background_pending`, since only a subagent is sure to end.
 	agent_pending: boolean
-	// This lane child handed its region to a running detached ship — `lane_handoff.is_handed_off`
-	// (joshuafolkken/kit#2962). The supervisor notifies on its own outcome, so nobody waits on this stop.
+	// This lane child handed its region to a running detached ship — `lane_handoff.is_handed_off`.
+	// The supervisor notifies on its own outcome, so nobody waits on this stop.
 	handed_off: boolean
-	// The resolved `JOSH_SESSION_LANG` — `session_language.resolve_session_lang` (joshuafolkken/kit#2470).
+	// The resolved `JOSH_SESSION_LANG` — `session_language.resolve_session_lang`.
 	session_lang: string
-	// This session is an agent kit launched under `claude -p` — `agent_headless.is_headless`
-	// (joshuafolkken/kit#3245). No person reads its reply, so the rules on how a reply is written stand down.
+	// This session is an agent kit launched under `claude -p` — `agent_headless.is_headless`.
+	// No person reads its reply, so the rules on how a reply is written stand down.
 	headless_agent: boolean
+	// This session drives a live `backlogrun` carry record — `run_headless.is_backlog_parent`.
+	// With `headless_agent` and `lane_child`, what makes a run unattended.
+	backlog_parent: boolean
 }
 
 interface StopOutcome {
@@ -111,18 +113,18 @@ const STOP_NOTIFY_REASON =
 // keep it because their tree is dirty, which is why this row is silent whenever the tree is not clean.
 const HOLD_RELEASE_REASON =
 	'⛔ working-tree hold not released: this working tree is clean but its `run:hold` record is still in ' +
-	'place, so the next run here runs `git switch main && git pull` believing the tree is free while ' +
+	'place, so the next run here runs `pnpm josh ms` believing the tree is free while ' +
 	'you hold it. The workflow-commands skill → `working-tree-hold.md`: a stop that leaves the tree clean ' +
 	'releases the hold with `pnpm josh run:release <N>` (bare for a `new` entry). A `halfrun` ' +
 	'pre-commit stop and a `needs-human-review` stop keep the hold because their tree is dirty, and a ' +
 	'`prrun` stop keeps it by its stop mark — this row is silent there. Release it, then end with a one-line confirmation that it was released — do ' +
 	'not repeat your previous reply.'
 
-// **A refusal that corrects rather than advises** (joshuafolkken/kit#2247). The bare `#N` is already
+// **A refusal that corrects rather than advises**. The bare `#N` is already
 // on screen and the hook cannot unsay it, so the reason does the one thing that helps the *next* reply:
 // it names the numbers it detected and hands over the exact `issue:cite` call that prints the
-// paste-ready lines, then asks for the corrected citation lines alone — not the whole reply reissued
-// (joshuafolkken/kit#2329). Reprinting the whole reply is what made the correction read as a duplicate;
+// paste-ready lines, then asks for the corrected citation lines alone — not the whole reply reissued.
+// Reprinting the whole reply is what made the correction read as a duplicate;
 // the bare copy already scrolled past stays, and the fix follows it as a short correction. The rule
 // itself is not restated — it is resident in `CLAUDE.md` — only pointed at.
 const ISSUE_CITATION_REASON =
@@ -140,19 +142,21 @@ function build_citation_reason(references: ReadonlyArray<string>): string {
 	)
 }
 
-// **An offer to file is a Tier A filing deferred to the user** (joshuafolkken/kit#2422). The judgement
-// is already made, so the reason hands over the filing chain rather than a question; the rule itself
-// is resident in `observation-filing.md` and only pointed at.
+// **An offer to file in an unattended run is a Tier A filing deferred to nobody**.
+// The judgement is already made, so the reason hands over the filing chain rather than a question; the
+// rule itself is resident in `observation-filing.md` and only pointed at. **An interactive session asks
+// first**: there the offer is the correct reply, so `needs_filing` is silent.
 const FILING_OFFER_REASON =
-	'⛔ filing offer: your reply offers to file an Issue instead of filing it. Filing into a ' +
-	'first-party repository is Tier A — the trigger is the judgement that it is worth filing, not the ' +
-	"run's progress (the workflow-commands skill → `observation-filing.md`). Run " +
+	'⛔ filing offer: your reply offers to file an Issue instead of filing it, and this run is ' +
+	'unattended — nobody is there to answer. Filing into a first-party repository there is Tier A — ' +
+	"the trigger is the judgement that it is worth filing, not the run's progress (the " +
+	'workflow-commands skill → `observation-filing.md`). Run ' +
 	'`pnpm josh issue:file "<title>" --body-file <path> --depth <0|1|2>` — it scouts, lints, labels and ' +
 	'runs `epic:bundle` itself — then end with the one-line citation of what was filed; do not repeat ' +
 	'your previous reply. If it is not worth filing ' +
 	'after all, say so in one line instead.'
 
-// **A headless parent's turn-end is its process's end** (joshuafolkken/kit#2437). Under `claude -p` the
+// **A headless parent's turn-end is its process's end**. Under `claude -p` the
 // background waits die with the turn, so the lanes lose their parent and nothing re-invokes it. The
 // reason hands over the foreground wait rather than a question, because there is nobody to answer one.
 // The refusal's opening, which the transcript tail is counted by.
@@ -166,7 +170,7 @@ const HEADLESS_REFUSAL_CAP = 3
 
 // The foreground waits as they appear in a transcript's tool-call input — the JSON `command` field, so
 // the refusal's own prose, which names the same commands, never matches. `run:progress --wait` is not
-// one (joshuafolkken/kit#3102): it streams its reports and runs until work arrives, so it is started in
+// one: it streams its reports and runs until work arrives, so it is started in
 // the background, where it lives as long as the turn the foreground wait keeps open.
 const HEADLESS_WAIT_CALLS = ['"command":"pnpm josh lane:await']
 
@@ -180,7 +184,7 @@ const HEADLESS_WAIT_BODY =
 
 const HEADLESS_WAIT_REASON = `${HEADLESS_WAIT_MARKER}${HEADLESS_WAIT_BODY}`
 
-// **A lane child never asks a person for the index** (joshuafolkken/kit#2445). The index rule protects
+// **A lane child never asks a person for the index**. The index rule protects
 // a person's own staging, and a lane is a per-run work tree with none to protect; the sanctioned commit
 // flow is already authorized, so the reason hands it over instead of letting the run wait on a person.
 // Both halves must appear — an index command and a request for permission — so a report that merely
@@ -204,8 +208,8 @@ function needs_index_route(context: StopContext): boolean {
 	return context.lane_child && asks_index_permission(context.message)
 }
 
-// **A refusal is the turn's only input, so it names the language the answer is written in**
-// (joshuafolkken/kit#2470). The session-language line reaches a turn only through `UserPromptSubmit`;
+// **A refusal is the turn's only input, so it names the language the answer is written in**.
+// The session-language line reaches a turn only through `UserPromptSubmit`;
 // a turn this hook continues has no prompt, and an English refusal read alone was answered in English.
 function language_note(lang: string): string {
 	return (
@@ -214,8 +218,8 @@ function language_note(lang: string): string {
 	)
 }
 
-// **A reply that drifted out of the session language is sent back once to be rewritten**
-// (joshuafolkken/kit#2470). The drift persists — each turn matches the language of the one before — so
+// **A reply that drifted out of the session language is sent back once to be rewritten**.
+// The drift persists — each turn matches the language of the one before — so
 // the rewrite has to happen on the turn it starts; `stop_hook_active` bounds it to one.
 function build_language_reason(lang: string): string {
 	return (
@@ -231,19 +235,28 @@ function language_reason(context: StopContext): string | undefined {
 	return build_language_reason(context.session_lang)
 }
 
+// The sessions no person answers: one kit launched under `claude -p` (a lane child, a woken session), a
+// dispatched lane child, or the `backlogrun` parent the user handed the backlog to.
+function is_unattended(context: StopContext): boolean {
+	return context.headless_agent || context.lane_child || context.backlog_parent
+}
+
 function needs_filing(context: StopContext): boolean {
-	if (context.filed || !filing_offer.offers_filing(context.message)) return false
+	if (!is_unattended(context) || context.filed) return false
 
-	return filing_offer.is_first_party_target(context.message, context.session_owner)
+	return (
+		filing_offer.offers_filing(context.message) &&
+		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
+// **A running background subagent stands both hold rules down**. 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.
 //
-// **A lane handed to the detached ship stands them down too** (joshuafolkken/kit#2962): the hold now
+// **A lane handed to the detached ship stands them down too**: the hold now
 // belongs to the supervisor driving the merge, and the person hears from that supervisor's own notify.
 function is_held_idle(context: StopContext): boolean {
 	return context.hold_present && !context.agent_pending && !context.handed_off
@@ -264,8 +277,8 @@ function citation_reason(context: StopContext): string | undefined {
 	return build_citation_reason(references)
 }
 
-// The two rules on how a reply is written. **A headless agent's reply has no reader**
-// (joshuafolkken/kit#3245): its text lands in a stream-json log, so correcting its citations or its
+// The two rules on how a reply is written. **A headless agent's reply has no reader**:
+// its text lands in a stream-json log, so correcting its citations or its
 // language costs a turn and reaches nobody. The artifacts a person does read — a Telegram, an Issue, a
 // pull request — are held to the same rules by their own guards, not here.
 function wording_reason(context: StopContext): string | undefined {
@@ -298,15 +311,15 @@ function count_headless_refusals(tail: string): number {
 	return tail.slice(Math.max(last_wait, 0)).split(HEADLESS_WAIT_MARKER).length - 1
 }
 
-// **A lane child with a task still running is sent back to wait, not to notify** (joshuafolkken/kit#2704).
+// **A lane child with a task still running is sent back to wait, not to notify**.
 // Its turn-end kills the task, so the notify the hold rules would ask for announces a stop that loses
 // the work; the #2606 child obeyed exactly that and its gate died at `exit code 143`.
 function needs_background_wait(context: StopContext): boolean {
 	return context.lane_child && context.background_pending
 }
 
-// The two hold rules, notify ahead of release — behind the lane index route (joshuafolkken/kit#2445)
-// and the lane background wait (joshuafolkken/kit#2704), since the notify they would ask for announces
+// The two hold rules, notify ahead of release — behind the lane index route
+// and the lane background wait, since the notify they would ask for announces
 // a pause the run has no reason to take.
 function hold_reason(context: StopContext): string | undefined {
 	if (needs_index_route(context)) return LANE_INDEX_REASON
@@ -324,7 +337,7 @@ function hold_reason(context: StopContext): string | undefined {
 // reports the notify first; the filing offer goes ahead of the citation, since the filing it forces
 // produces the citation the reply then needs.
 //
-// **The headless wait comes first and outlasts `stop_hook_active` up to its spin bound** (joshuafolkken/kit#2437).
+// **The headless wait comes first and outlasts `stop_hook_active` up to its spin bound**.
 // The loop-breaker exists so a person is not wedged behind a rule the run will not satisfy; a headless
 // parent has no person, and letting its second stop through is exactly the silent end the rule is for.
 // Each continuation it forces is a foreground wait of minutes, and the rule falls silent by itself once

package/scripts/rules/tail-commands.ts

@@ -3,7 +3,7 @@ import { time_shell } from '#scripts/time-runtime/time-shell'
 import { time_transcript_line, type Block } from '#scripts/time-runtime/time-transcript-line'
 
 // The `Bash` commands a run's transcript tail already issued, parsed once here rather than in each
-// rule that needs them (joshuafolkken/kit#2119). `prior-comment-read.ts` had this reading first; the
+// rule that needs them. `prior-comment-read.ts` had this reading first; the
 // scout gate needs the same "what did the run already run" question, so a second copy would be the
 // clone `CLAUDE.md` prohibits. The delivery path sees only the raw tail — `delivered-rules.ts` names
 // the reason a run's own calls are not handed to it — so the earlier calls are recovered by parsing

package/scripts/rules/test-declared-commit.ts

@@ -2,8 +2,8 @@ import { test_declared_changed } from '#scripts/test/test-declared-changed'
 import type { GuardedCall } from '#scripts/time-runtime/time-batch-guard'
 import { run_tail_rule } from './run-tail-rule'
 
-// The trigger and the delivered text behind the `test-declared` row of `delivered-rules.ts`
-// (joshuafolkken/kit#2118). It lives beside `run-tail-rule.ts` and the other per-rule modules rather than
+// The trigger and the delivered text behind the `test-declared` row of `delivered-rules.ts`.
+// It lives beside `run-tail-rule.ts` and the other per-rule modules rather than
 // inline in the enumeration, so the enumeration stays a list of rows.
 //
 // **A commit whose code change carries no test, refused at the commit stage `run-tail` already

package/scripts/rules/third-party-write.ts

@@ -3,8 +3,8 @@ import { bash_triggers } from './bash-triggers'
 import { gh_api } from './gh-api'
 import { shell_segments } from './shell-segments'
 
-// The trigger and the delivered text behind the `third-party-write` row of `delivered-rules.ts`
-// (joshuafolkken/kit#2122). A `gh api` write to a repository whose owner is not this session's — a
+// The trigger and the delivered text behind the `third-party-write` row of `delivered-rules.ts`.
+// A `gh api` write to a repository whose owner is not this session's — a
 // tracker we do not own — is Tier C: `CLAUDE.md` → "Third-party repositories are Tier C" and
 // `upstream-interrupt.md` forbid it without explicit current-turn user instruction, and a correct
 // diagnosis is not that instruction.
@@ -25,7 +25,7 @@ import { shell_segments } from './shell-segments'
 // A third-party write means all three: a `gh api` call, a write, and a repository target whose owner
 // the classification calls third-party. `unknown` (an unreadable session remote, an unparseable path)
 // is not third-party — the rule stays silent rather than refusing a write it cannot prove is external.
-// The `{owner}` placeholder (joshuafolkken/kit#3188) is judged by every owner `gh` could expand it to:
+// The `{owner}` placeholder is judged by every owner `gh` could expand it to:
 // first-party only when all of them are, so a fork checkout whose `upstream` is another owner's still
 // refuses the write `gh` may send there. A candidate whose owner could not be read counts as
 // third-party here — unlike an unreadable session owner, it is a remote `gh` may really write to.

package/scripts/rules/worktree-guard.ts

@@ -2,8 +2,8 @@ import { bash_triggers } from './bash-triggers'
 import { git_argv } from './git-argv'
 import { shell_segments } from './shell-segments'
 
-// The trigger and the delivered text behind the `worktree-mutation` row of `delivered-rules.ts`
-// (joshuafolkken/kit#2120). Group 2 of the three Bash-string gaps: a working-tree change made outside
+// The trigger and the delivered text behind the `worktree-mutation` row of `delivered-rules.ts`.
+// Group 2 of the three Bash-string gaps: a working-tree change made outside
 // the authorized routes.
 //
 // **The deny list does not cover these at all.** `git checkout -- <path>` and `git restore <path>`
@@ -19,6 +19,10 @@ import { shell_segments } from './shell-segments'
 // (with or without `-u`) and the read-only `git stash list` / `show` pass, and everything else — bare
 // `git stash`, a message-less push, `pop` / `apply` / `drop` / `save` / `clear` — is refused.
 //
+// **The refusal names the way on for a handed-over stash.** joshuafolkken/kit#3630's plan restored a
+// stash with `git stash apply`, and the lane parked on how to apply it instead of popping by message;
+// the reason now says the substitution is the run's own to make (joshuafolkken/kit#3648).
+//
 // **It fires on every occurrence**, for the reason `git-force.ts` does: discarding the working tree is
 // destructive each time it is issued.
 
@@ -83,7 +87,7 @@ function is_unauthorized_stash(args: ReadonlyArray<string>): boolean {
 	return true
 }
 
-// `git clean` deletes untracked files, which no commit can bring back (joshuafolkken/kit#2983). It
+// `git clean` deletes untracked files, which no commit can bring back. It
 // refuses to act without a force (`clean.requireForce`), so a force — `--force`, or a cluster carrying
 // `f` — is what marks the destructive call; `git clean -n` is a dry run and passes.
 const CLEAN_SUBCOMMAND = 'clean'
@@ -127,8 +131,11 @@ const WORKTREE_MUTATION_REASON =
 	'josh stash:pop "<message>"`, never a positional `git stash pop` a shared stack lets another lane ' +
 	'divert. A stash push is authorized only inside a documented flow and only with a findable message ' +
 	'— `git stash push -u -m "<message>"` — which this row allows; a bare `git stash`, a message-less ' +
-	'push, or `pop` / `apply` / `drop` is refused. **This rule fires on every occurrence, not once per ' +
-	'run.**'
+	'push, or `pop` / `apply` / `drop` is refused. A plan that restores a handed-over stash with `git ' +
+	'stash apply` / `git stash pop` is read as `pnpm josh stash:pop "<message>"`: apply it that way, ' +
+	'continue, and record the substitution on the Issue — Tier A, never a `needs-decision` park ' +
+	'unless the plan says why the owner keeps the stash: then stop and confirm (`operating-rules.md` ' +
+	'→ "no-self-staging"). **This rule fires on every occurrence, not once per run.**'
 
 const ROW = {
 	id: 'worktree-mutation',

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

@@ -0,0 +1,165 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { epic_issue } from '#scripts/epic/epic-issue'
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
+import { run_carry, type RunCarry } from '#scripts/run/carry/run-carry'
+import { run_carry_added, type CarryAddition } from '#scripts/run/carry/run-carry-added'
+import { run_event_stream } from '#scripts/run/event/run-event-stream'
+import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
+import { run_invocation } from '#scripts/run/run-invocation'
+import { run_add, type AddOutcome, type AddPorts, type IssueView } from './run-add'
+
+// `josh run:add <issue...> [--no-priority]` — the wiring around `run-add.ts`.
+// It refuses unless a `backlogrun` holds the carry record here: an issue labelled with no run to take
+// it would be picked up by whichever run starts next, which is not what was asked. A run that named
+// issues reads its list off the record — with `--only` or without, since a named run drains the pool
+// only after that list — so the queued issues are written there too; a pool run reads the labels alone. Each queued issue is announced as an `add` event, which wakes a `run:progress --wait` parked
+// on a full house so the parent offers it the next freed lane.
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const USAGE_EXIT_CODE = 2
+const ARGV_OFFSET = 2
+const ISSUE_PREFIX = '#'
+const NO_PRIORITY_FLAG = '--no-priority'
+const USAGE = `Usage: josh run:add <issue...> [${NO_PRIORITY_FLAG}]`
+const NO_RUN_MESSAGE =
+	'No backlogrun is running here, so nothing was added. Start one with `backlogrun #N`.'
+
+interface AddRequest {
+	issues: ReadonlyArray<number>
+	is_priority: boolean
+}
+
+interface LiveRun {
+	target: string
+	carry: RunCarry
+}
+
+function parse_issue(token: string): number | undefined {
+	const digits = token.startsWith(ISSUE_PREFIX) ? token.slice(ISSUE_PREFIX.length) : token
+
+	return issue_number_shape.ISSUE_NUMBER_PATTERN.test(digits) ? Number(digits) : undefined
+}
+
+// Every token but the flag must be an issue number: a typo is refused whole rather than adding the
+// rest, so the queue never holds half of what was typed.
+function parse_request(argv: ReadonlyArray<string>): AddRequest | undefined {
+	const tokens = argv.filter((token) => token !== NO_PRIORITY_FLAG)
+	const issues = tokens.map((token) => parse_issue(token)).filter((issue) => issue !== undefined)
+
+	if (issues.length === 0 || issues.length !== tokens.length) return undefined
+
+	return { issues, is_priority: !argv.includes(NO_PRIORITY_FLAG) }
+}
+
+async function live_run(): Promise<LiveRun | undefined> {
+	const directory = await run_carry.repository_directory()
+
+	if (directory === undefined) return undefined
+
+	const target = run_carry.carry_path(directory)
+	const read = run_carry.read_carry(target)
+
+	return read.kind === 'carried' ? { target, carry: read.carry } : undefined
+}
+
+// Re-read rather than reusing the record found before the labels were written: the parent may have
+// marked an issue done in between, and writing the stale copy back would undo that.
+function record(target: string, additions: ReadonlyArray<CarryAddition>): void {
+	const read = run_carry.read_carry(target)
+
+	if (
+		read.kind !== 'carried' ||
+		run_invocation.issue_numbers(read.carry.invocation) === undefined
+	) {
+		return
+	}
+
+	if (additions.length > 0) run_carry_added.add_issues(target, read.carry, additions)
+}
+
+async function announce(issues: ReadonlyArray<number>): Promise<void> {
+	const [issue, ...rest] = issues
+
+	if (issue === undefined) return
+
+	await run_event_stream_emit.emit(
+		run_event_stream.EVENT_KIND.ADD,
+		`added ${ISSUE_PREFIX}${String(issue)}`,
+	)
+	await announce(rest)
+}
+
+// The blockers still open. A blocker whose state did not come back counts as open, so an issue is
+// never reported free to run on a read that did not say so.
+function view_of(json: string): IssueView | undefined {
+	const issue = epic_issue.parse_epic_issue(json)
+
+	if (issue === undefined) return undefined
+
+	const blockers = (issue.blockedBy?.nodes ?? [])
+		.filter((blocker) => epic_issue.normalize_state(blocker.state ?? '') !== epic_issue.CLOSED)
+		.map((blocker) => blocker.number)
+
+	return { is_open: epic_issue.is_open(issue.state), blockers }
+}
+
+async function read_issue(issue: number): Promise<IssueView | undefined> {
+	const read = await git_gh_command.issue_get_state_and_relations_classified(String(issue))
+
+	return read.kind === 'read' ? view_of(read.json) : undefined
+}
+
+async function apply_label(issue: number, label: string): Promise<boolean> {
+	return await git_gh_command.issue_add_label(String(issue), label)
+}
+
+const GH_PORTS: AddPorts = { read_issue, apply_label }
+
+async function add(request: AddRequest, target: string, ports: AddPorts): Promise<number> {
+	const outcomes: ReadonlyArray<AddOutcome> = await run_add.add_all(
+		request.issues,
+		request.is_priority,
+		ports,
+	)
+	const additions = run_add.additions_of(outcomes, request.is_priority)
+
+	record(target, additions)
+	await announce(additions.map((addition) => addition.issue))
+
+	for (const outcome of outcomes) console.info(run_add.describe(outcome, request.is_priority))
+
+	return run_add.is_all_queued(outcomes) ? SUCCESS_EXIT_CODE : FAILURE_EXIT_CODE
+}
+
+async function run(argv: ReadonlyArray<string>, ports: AddPorts = GH_PORTS): Promise<number> {
+	const request = parse_request(argv)
+
+	if (request === undefined) {
+		console.error(USAGE)
+
+		return USAGE_EXIT_CODE
+	}
+
+	const live = await live_run()
+
+	if (live === undefined) {
+		console.error(NO_RUN_MESSAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	return await add(request, live.target, ports)
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const run_add_cli = { NO_RUN_MESSAGE, USAGE, parse_request, run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { run_add_cli }