Skip to content

fix(worktrees): retire a created pool name whatever the client claims (STA-4471) - #14919

Open
brennanb2025 wants to merge 1 commit into
mainfrom
brennanb2025/fix-4471
Open

brennanb2025 wants to merge 1 commit into
mainfrom
brennanb2025/fix-4471

Conversation

@brennanb2025

@brennanb2025 brennanb2025 commented Aug 16, 2026 •

Copy link
Copy Markdown
Contributor
Files Added Deleted Net
Test 4 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​320 $\color{#cf222e}{\Huge{\mathbf{−}}}$​9 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​311
Prod 3 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​124 $\color{#cf222e}{\Huge{\mathbf{−}}}$​74 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​50

Fixes STA-4471 (P2). Incomplete-fix follow-up to #14350.

Retargeted onto main and rebased. The original base, brennanb2025/fix-4449-4491 (#14917),
merged; its commit is dropped from this branch. Nothing is stacked above this PR any more.

The defect

Orca auto-names new workspaces from a pool of creature words (nautilus, orca, runner,
emperor…). #14350 introduced retirement: once a generated workspace's cwd is spent, a later
generated create steps over it so the new workspace does not inherit the previous occupant's
Claude/Codex conversation history.

#14350 gated all of that on one new optional client field:

const shouldRetireGeneratedName =
  args.nameWasGenerated === true && isGeneratedWorktreeCreateName(sanitizedName)

That single flag was made to answer two questions that pull in opposite directions, and the second
one is not the client's to answer:

who should decide #14350
walk the creature tier ladder, step over retired cwds the client — it knows if the user chose the name nameWasGenerated
record the created name as spent the host — it knows what it issued nameWasGenerated

The second row is the bug. A client that omits the field creates nautilus, and the registry never
learns about it. The very next generated create on that repo is free to pick nautilus again and
land on the same cwd — which is exactly the collision retirement exists to prevent.

The fix

planWorktreeCreateNames splits the two decisions:

  • Which cwd a create may land on stays gated on nameWasGenerated. A generated name is one of
    ours — nothing was chosen — so folding it onto the canonical tier ladder and stepping over spent
    cwds costs the user nothing. A name the user typed is a request: nautilus stays nautilus
    even where that cwd is retired, prior agent history and all. Silently handing back nautilus-2
    is the worse surprise, and the pool is ordinary English that people type on purpose.
  • Whether the created name is recorded as spent is now decided by the host from the name's
    shape alone (retiresCreatedName: isPoolShaped). Recording is only ever a write. It never
    redirects anybody, and addRetiredWorktreeName independently re-checks pool shape, so a coined
    name like fix-login is still never recorded.

Note on the "absent" case: every producer strips the field when false
(...(nameWasGenerated ? { nameWasGenerated: true } : {})), so the host only ever sees true or
absent — absent covers both older clients and every current client creating a typed name. Reading
absent as typed is therefore not a concession to old peers; it is the common path, and it matches
pre-#14350 behaviour exactly.

The cost this accepts, stated plainly

Two consequences follow, and both are deliberate:

  1. A user who types a pool word can now land on a cwd this host marked spent, and inherit the previous
    occupant's Claude/Codex history — the exact harm the registry exists to prevent. That is the accepted
    price of "an explicitly typed name wins." It fires only against a name the user chose, and only where
    they chose the same word twice; a generated name is still redirected every time.
  2. A typed pool-shaped name now spends that pool slot, where before only client-flagged generated names
    did. Not an exhaustion risk — the pool is 552 names across unbounded tiers, and completed tiers
    compact into a watermark — but it is a behaviour change beyond the reported bug.

What this replaces

An earlier revision of this PR enforced the skip on both paths regardless of provenance, so
typing nautilus on a retired cwd returned nautilus-2. That is reverted. Per the product call,
auto-generated names may be redirected; a name the user typed may not.

Shape

The three create paths — OrcaRuntimeService.createManagedWorktree (runtime/mobile/CLI),
createRemoteWorktree (SSH) and createLocalWorktree (desktop IPC) — each carried their own copy
of the gate plus candidate selection, which is how one rule ended up applied inconsistently. They
now share src/main/worktree-create-name-plan.ts, which is unit-tested directly.

Performance

The typed path no longer loads the retirement registry at all. getRetiredNameRegistryForRepo
calls ensureRetiredWorktreeNamesBackfilled, whose readdir scan is unbounded and whose Promise is
cached forever (STA-4473). Gating the load on the generated ladder rather than on pool shape means a
user typing a pool word on a stalled NFS/SMB/WSL-UNC workspace root pays nothing — so this PR no
longer widens STA-4473's exposure at all, and no longer needs to land with #14924.

Wire compatibility

No wire change: no new field, no new opcode, nothing removed from what the host publishes. Per
docs/reference/remote-wire-compatibility.md Rule 1, the failure #14350 introduced is precisely the
one that rule warns about — a host that requires a new optional field is broken against every
peer that predates it. Enforcement of the write half moved to the host, which is what makes it hold
for those peers; the read half stays advisory, which is what keeps typed names intact.

@brennanb2025

Copy link
Copy Markdown
Contributor Author

Review: CLEAN — merge only as part of the stack

Independent re-verification against head 6ee943de. No blocking defects. One release rule below that a reader landing mid-stack must not miss.


⚠️ Merge order: never ship a build between #14919 and #14924

This PR widens who reaches getRetiredNameRegistryForRepo — the gate moves from "the client said nameWasGenerated" to "the name is pool-shaped" (worktree-create-name-plan.ts:51-53). That loader awaits ensureRetiredWorktreeNamesBackfilled, whose namespace scan has no deadline and no backoff at this head (verified: zero deadline/backoff/timeout hits in worktree-name-retirement.ts on this branch — they arrive in #14924, STA-4473). The scan is readdir over the workspace root and the agent-state root, and it is awaited before the suffix loop, so a stalled mount blocks workspace create.

Scoping the window honestly: the scan is memoized per store + cwd namespace, and the composer's worktrees:listRetiredNames warms it. So the exposure is a pool-shaped create that lands before anything has warmed that namespace this app session — not every create. But it bites hardest exactly where this PR aims: an older paired/mobile client that omits the provenance bit is also the client least likely to have warmed the scan first.

#14924 currently stacks on top of #14919 (base: brennanb2025/fix-4471). Restacking so #14924 lands first deletes this rule entirely and is the better outcome — recommended.

Why this is stacked, not folded into #14917

Deliberate, and worth stating so it survives a mid-stack read: this reverses a product decision from #14350 ("never reissue a generated workspace name", merged 2026-08-15), which chose to leave a user-typed name reusable. It must stay independently revertable. Folding it into #14917 would make that revert also drop the tombstone-persistence fix.

Prior-art conformance — (a) CONFORMS

The established Orca rule: a client-declared bit may enable optional behaviour but must never disable a host-side invariant. That is precisely the split made here — usesGeneratedLadder (walk the creature tier ladder) stays gated on nameWasGenerated; refusing a spent cwd is decided by the host alone. Textbook application. No (c) divergence found anywhere in this PR.

Honesty note: the conformance judgement is carried from an earlier prior-art round and is reasoned, not re-derived in this pass. The code-level split it describes I did verify directly.

Non-vacuity: mutation-tested, all three create paths

Not "the tests are green" — I proved they bind. Reverting the gate to its pre-fix form (registry/retiresCreatedName back to usesGeneratedLadder) kills 5 tests across all 3 create paths, then a clean revert restores green:

Path Test killed by the mutation
unit refuses a retired cwd even when the client sends no provenance bit
unit records a pool-shaped name as spent however the client labelled it
local IPC skips a retired cwd on the local create path when the client omits provenance
SSH IPC skips a retired cwd on the SSH create path when the client omits provenance
runtime skips a retired cwd when an older client omits nameWasGenerated

Strongest signal in the diff: the three integration tests were green while asserting the bug (leaves a user-typed name reusable…, neither skips nor retires a name the user typed). This PR inverts all three rather than adding alongside them — the old behaviour cannot silently survive.

CI at this head: 44 pass, 1 skipping (static analysis and both Node 24/26 shards included).

Two findings NEW to this pass (neither blocking)

  1. retiresCreatedName also drops the provenance gate (:57), which is wider than the PR title suggests — a typed pool-shaped name is now recorded as spent too. This is required for coherence, not incidental scope: refusing retired cwds regardless of provenance while only recording generated ones would burn a directory without a tombstone, and the generator would later reissue that name onto spent state. Correctly pinned by the records a pool-shaped name as spent however the client labelled it test.
  2. Compaction watermark — checked, no gap. The typed ladder uses plain -2/-3 suffixes and does not skip ahead past exhaustedTiers, which looked like a hole for compacted tiers. It isn't: createRetiredNameLookup tests the watermark independently of the explicit name set, so those rungs are still refused. They cost pure string math and no attempt budget (the continue skips attempts += 1), and clampExhaustedTiers bounds the walk — no spin.

Also confirmed unchanged: the display-name (requestedName) suffixing logic is preserved exactly across all three call sites; the old shouldRetireGeneratedName and the new usesGeneratedLadder are the same predicate.

Explicitly NOT covered

  • No independent same-model review round. This PR had 0 reviews and 0 comments before this one. This pass is a single reviewer; treat it accordingly.
  • Test-proven vs reasoned. Test-proven: the provenance-independent refusal and recording on all three create paths, and registry-skip for non-pool names. Reasoned only: the merge-order hazard (argued from the call graph and the absent deadline — no stalled-mount repro was run) and the prior-art verdict.
  • No rendered surface. The diff is main-process only (src/main/**, no renderer files), so there is no UI to screenshot — the user-visible effect is a workspace silently named nautilus-2 instead of nautilus, with no UI change. Not a screenshot gap.
  • SSH execution hosts. ensureRetiredWorktreeNamesBackfilled returns early for repo.connectionId, so a re-added SSH repo still does not recover retirements from its execution host. Pre-existing and documented in-module, not introduced here.

@brennanb2025
brennanb2025 force-pushed the brennanb2025/fix-4471 branch from 6ee943d to d1097eb Compare August 23, 2026 20:34
@greptile-apps

greptile-apps Bot commented Aug 23, 2026

Copy link
Copy Markdown

Too many files changed for review (400 files, 100 file limit).

Bypass the limit by tagging @greptile-apps to review.

@brennanb2025
brennanb2025 changed the base branch from brennanb2025/fix-4449-4491 to main August 23, 2026 20:34
@brennanb2025
brennanb2025 force-pushed the brennanb2025/fix-4471 branch from d1097eb to 43b76d3 Compare August 23, 2026 20:39
@coderabbitai

coderabbitai Bot commented Aug 23, 2026 •

Copy link
Copy Markdown
Contributor

Review Change Stack

📝 Walkthrough

Walkthrough

Adds planWorktreeCreateNames as the shared asynchronous planner for worktree names. Generated names skip retired candidates, while typed names preserve literal naming. Pool-shaped names remain eligible for retirement tracking. Orca runtime and local or SSH IPC creation now use the planner for candidate selection and retirement decisions. Tests cover retired names, suffix handling, typed names, legacy provenance, and non-pool names.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Description check ⚠️ Warning The description explains the defect and implementation, but it omits most required template sections and checklist details. Add the required headings and details for ELI5, Visual Proof with N/A justification, Testing, AI Disclosure, Review, Notes, and checklist status.
✅ Passed checks (4 passed)
Check name Status Explanation
Docstring Coverage ✅ Passed Docstring check was indeterminate for this PR — some files could not be analyzed in time. Not blocking.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Title check ✅ Passed The title accurately identifies the worktree retirement fix and its independence from client-provided provenance.
✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1


ℹ️ Review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 40c3df5d-4031-40b7-b0be-3b57e6c44d54

📥 Commits

Reviewing files that changed from the base of the PR and between d1127b9 and d1097eb7eadfb9f10cbc8d0109a3e3a122c33173.

📒 Files selected for processing (7)
  • src/main/ipc/worktree-remote.ts
  • src/main/ipc/worktrees-ssh-pr-head-fetch.test.ts
  • src/main/ipc/worktrees-windows.test.ts
  • src/main/runtime/orca-runtime.test.ts
  • src/main/runtime/orca-runtime.ts
  • src/main/worktree-create-name-plan.test.ts
  • src/main/worktree-create-name-plan.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 1 remains after this review.

Comment thread src/main/worktree-create-name-plan.ts Resolved
@brennanb2025
brennanb2025 force-pushed the brennanb2025/fix-4471 branch from 43b76d3 to 9572730 Compare August 23, 2026 20:52
@brennanb2025 brennanb2025 changed the title fix(worktrees): refuse a retired cwd regardless of client provenance (STA-4471) fix(worktrees): retire a created pool name whatever the client claims (STA-4471) Aug 23, 2026
@brennanb2025

brennanb2025 commented Aug 23, 2026 •

Copy link
Copy Markdown
Contributor Author

Review loop — final status

Rebased onto main (the old base brennanb2025/fix-4449-4491 merged as #14917; that commit is dropped
from this branch), retargeted the PR base to main, and reversed the product decision this PR had
wrong. Head is 9572730c0c.

What changed in this loop

The product call. The previous revision refused a retired cwd regardless of provenance, so typing
nautilus on a retired cwd returned nautilus-2. That is reverted. Generated names may be redirected;
a name the user typed may not. retiresCreatedName: isPoolShaped is unchanged — the host still records
a created pool-shaped name as spent whatever the client claimed, which is the half worth having, and it
never redirects anybody.

A correction to this PR's own premise. The old body framed the ambiguous population as "older
clients that omit the field." That is understated. Every producer strips the field when false —
...(nameWasGenerated ? { nameWasGenerated: true } : {}) in worktree-creation-flow.ts:137,
create-worktree.ts:83, web-preload-api.ts:1833, worktree-create-args.ts:24,
mobile/src/tasks/blank-workspace-create.ts:34 — so the host only ever sees true or absent, and
absent is what every current client sends for a typed name. The previous revision was therefore
redirecting typed names for the entire live population, not just pre-field peers. Reading absent as
typed is the common path, not a concession.

Registry load tightened. With the provenance gate restored, nothing on the typed path consults the
registry, so the load moved from isPoolShaped to usesGeneratedLadder. That drops
getRetiredNameRegistryForRepo — and with it ensureRetiredWorktreeNamesBackfilled's unbounded
readdir (STA-4473) plus its O(repos) collision-key loop — off typed creates entirely. Consequence:
this PR no longer widens STA-4473's exposure at all, and the old body's "do not ship a build between
this PR and #14924" caveat no longer applies.

Three tests were flipped back to #14350's expectations and strengthened to also assert the
now-unconditional write, and the doc comment that argued for the old behaviour was rewritten.

Rounds run — and an honest account

I ran one substantive round, and it is my own, not a subagent's. Five dispatched reviewers
(review-r1, review-r1b, ref-oss, review-r2, plus a grok worker for visual proof) were spawned;
only the visual-proof worker returned an artifact. The four review workers ran for hours past
explicit time boxes without producing a report, including after two direct wrap-up messages. Per the
rule that a silent worker is never a clean round, I am not claiming a subagent-verified clean round.
The grok worker could not start at all — ~/.grok/auth.json is absent on this host and the CLI blocks
on interactive browser OAuth; it was replaced with a Claude worker, and the $electron skill had to be
symlinked into the worktree first because it was invisible to non-Claude agents.

What I verified directly, with evidence, is below.

Non-vacuity

Reverting production only (worktree-create-name-plan.ts deleted, orca-runtime.ts and
worktree-remote.ts back to origin/main), tests kept:

× keeps a typed name on its retired cwd yet still records it as spent                       (runtime)
× keeps a typed name on its retired cwd yet still records it as spent                       (local IPC)
× keeps a typed name on its retired cwd yet still records it as spent on the SSH create path (SSH)
Tests  3 failed | 1202 passed | 1 skipped (1206)

3 behavioural RED across all three create paths. Reported separately, and not counted as
behavioural evidence: worktree-create-name-plan.test.ts (8 tests) cannot load at all, because the
module is new here — that is a compile failure, not an assertion diff.

Mutation testing

mutation tests killed
registry load gate usesGeneratedLadder → isPoolShaped (typed names redirected again) 5 behavioural — both unit tests plus all three create paths
retiresCreatedName: isPoolShaped → usesGeneratedLadder 4 — the three create-path tests plus records a pool-shaped name as spent however the client labelled it
args.nameWasGenerated === true → !== false (absent read as generated) 6

No coverage hole on any of the three decisions. Mutation 1 additionally flipped one unrelated test
(fences provider resume and reveals one exact live legacy worker…) — that is pre-existing shared-store
leakage in orca-runtime.test.ts, surfaced only under mutation. On the committed code the suite is
stable: the three edited tests pass in isolation, and the full 1187-test file passed 3 consecutive runs.
Not fixed here — reworking the fixtures of a 1187-test file is not this PR's scope.

Checked, found nothing

  • All six retiresCreatedName call sites converted, including both failure/rollback paths on SSH
    (worktree-remote.ts:1804) and local (:2432) and the runtime error path (orca-runtime.ts:24897).
    No shouldRetireGeneratedName remains anywhere.
  • effectiveSanitizedName / effectiveRequestedName are still initialised to sanitizedName /
    requestedName before the loop, so a run of skipped candidates leaves the same values as on main.
  • Loop termination: for (…; attempts < MAX; suffix += 1) advances suffix without spending attempts
    on a skip. creatureNameAtTier(pool, tier + attempt) is strictly increasing and the retired set is
    finite, so it terminates; skipping is pure string math, no I/O, no attempt budget. This diff makes it
    less reachable than the previous revision (generated names only) — same reachability as main.
  • Every creature-name generator sets the bit: the desktop composer (useComposerState.ts:3674, :4212)
    and mobile NewWorktreeModal.tsx:685 are the only two callers of getSuggestedCreatureName; the CLI
    requires --name. So no generator silently falls into the typed path.
  • addRetiredWorktreeName self-gates via normalizeRetirableGeneratedName
    (persistence/loading-store/store.ts:3476), so a coined name is never recorded even though
    retiresCreatedName is now shape-only.
  • Registry growth stays bounded — compactRetiredNames collapses complete tiers into exhaustedTiers,
    clamped at 999,999.
  • SSH boundary: ensureRetiredWorktreeNamesBackfilled already returns early for any repo whose
    execution host is not local, so no scan crosses the boundary.
  • Wire compatibility: no new field, no new opcode, nothing removed from what the host publishes.
  • oxfmt clean; oxlint clean — and the gate was proved live by injecting a violation, which reported
    eslint(no-eval) and unicorn(empty-brace-spaces) before being reverted. typecheck:node clean.

Design audit

CONFORMS WITH CAVEATS. Derived fresh against the problem rather than by re-reading the earlier
verdict on this PR.

  • The candidate-iterator shape is the conventional one: an unbounded for (let suffix = 0; ; suffix += 1)
    that continues on a taken candidate and relies on the taken-set being finite. Orca's
    candidateAt(suffix) → null means skip is that same allocator with the predicate lifted out, which is
    if anything cleaner.
  • Separating "candidates considered" from "attempts spent" is also the right split: bound only the
    I/O-bearing counter, which is what Orca does by incrementing attempts after a candidate survives.
  • Two-stage naming — a ladder of qualified candidates, then a plain numeric suffix — is an established
    structure, and is what the creature ladder degrading to -2 does.
  • Auto-naming workspaces from a word bag is standard.
  • No established answer for the specific thing this PR turns on: a client-declared provenance hint
    that enables optional behaviour while a server-side fact independently governs a write. I am reporting
    that as unproven, not as endorsement. The asymmetry is unusual; I judge it unusual-and-right, because
    the two decisions have genuinely different owners — but that is reasoning, not evidence.
  • One observation worth recording, out of scope here: the tension this PR arbitrates exists because the
    pool is single ordinary English words that users plausibly type. Multi-word compounds sidestep it
    structurally. Changing Orca's pool is not this PR's job, but it is the root cause.

Visual proof

There is a rendered surface, and it was exercised in the running dev build (CDP 9333, throwaway
Electron profile and scratch repo, both deleted afterwards).

baseline
Baseline — only main.

generated redirected
nameWasGenerated: true on the retired nautilus → sidebar shows nautilus-2. Redirected.

typed literal
nameWasGenerated: false on the same retired nautilus → sidebar shows the literal nautilus, next to
the redirected nautilus-2. This is the behaviour the PR restores.

recording ungated
The write half, ungated: a typed cuttlefish was still recorded as spent, while the coined fix-login
was not.
On-disk registry after each step:

after typed nautilus      names: ["nautilus","nautilus-2"]
after typed cuttlefish    names: ["nautilus","nautilus-2","cuttlefish"]
after typed fix-login     names: ["nautilus","nautilus-2","cuttlefish"]   <-- fix-login absent

What I could not prove

  • No subagent-verified clean round. Four dispatched reviewers stalled without artifacts; the round
    above is mine. A second independent pair of eyes has not signed off.
  • CI is not green yet — it is queued on runner capacity, not failing. Worth noting: while the base
    branch pointed at the deleted brennanb2025/fix-4449-4491, CI silently did not run at all and
    gh pr checks reported "no checks reported" rather than a failure. Retargeting to main plus a fresh
    SHA restarted it.
  • Only the local desktop IPC path was driven end-to-end in the app. SSH and runtime/mobile are
    covered by unit tests only — no SSH host or mobile client in this environment.
  • The absent-bit case was not exercised end-to-end in the app, only true and false explicitly,
    and unit-tested for undefined.
  • exhaustedTiers stayed 0 throughout the live run, so the compaction-watermark branch of the ladder is
    unproven on screen (it is unit-tested).
  • The create was invoked through the store action, not by typing into the New Workspace modal — the
    rendered result is real UI, the invocation is programmatic. There is no way to force
    nameWasGenerated either way from the modal on demand.
  • That redirecting a deliberately typed pool name would have been the worse trade remains a product
    judgement
    , now encoded in tests rather than proven by them.

@brennanb2025

Copy link
Copy Markdown
Contributor Author

Correction to the review-loop comment above

I mischaracterised why the dispatched reviewers produced nothing, and the accurate version matters for
how much weight to give the missing second opinion.

I wrote that the four review workers "ran for hours past explicit time boxes without producing a report."
That is wrong. Idle notifications later showed all of them going idle within 7–20 minutes of being
spawned
— roughly when their time boxes said they should. Their reports were simply never delivered to
my session. When I resumed each of them and asked only for a resend of what they had already concluded,
they had 167, 125, 73 and 62 prior messages of real work in their transcripts, and still nothing came
back.

So the correct diagnosis is report delivery in this session was broken, not that the agents hung.
The practical consequence is worse than what I originally described: four reviews were very likely
completed and their findings are sitting unread in agent transcripts. I could not retrieve them.

What does not change: there is still no second pair of eyes on this PR. The round documented above
is mine, evidenced by mutation testing and non-vacuity rather than by an independent reviewer. Anyone
merging this should treat it as single-reviewed. If those transcripts can be recovered out of band, they
are worth reading before merge.

Also updating one status line: PR Checks has moved from queued to in-progress on 9572730c0c;
PR test LoC passes. Still not green at the time of writing.

Everything else in the comment above — the code change, the mutation table, the non-vacuity counts, the
prior-art verdict, and the screenshots — stands as written and was verified directly.

… (STA-4471)

#14350 gated the whole of generated-name retirement on the new optional
`nameWasGenerated` bit, conflating two decisions that pull in opposite
directions:

  - *Which cwd a create may land on* genuinely belongs to the client. A
    generated name is one of ours — nothing was chosen — so folding it onto the
    canonical tier ladder and stepping over cwds this host already spent costs
    the user nothing. A name the user typed is a request; `nautilus` stays
    `nautilus` even where that cwd is retired, because silently handing back
    `nautilus-2` is the worse surprise. This half stays gated, and clients that
    predate the bit are read as typing users, exactly as before #14350.

  - *Whether the created name is recorded as spent* never belonged to the
    client. An older paired or mobile client omits the bit but still hands back
    pool-shaped names, and a registry that never learns about them lets the very
    next generated create collide with one. Recording is only ever a write —
    `addRetiredWorktreeName` self-gates on pool shape, so a coined name like
    `fix-login` is never recorded, and no recorded name ever redirects a typed
    one.

The three create paths — `OrcaRuntimeService.createManagedWorktree` (runtime,
mobile, CLI), `createRemoteWorktree` (SSH) and `createLocalWorktree` (desktop
IPC) — each carried their own copy of the gate plus candidate selection, which
is how one rule ended up applied inconsistently. They now share
`planWorktreeCreateNames`, which is unit-tested directly.

No wire change: no new field, no new opcode, nothing removed from what the host
publishes. A name outside the creature pool never loads the registry, and
neither does a typed name, so neither pays for the deadline-less backfill scan.
@brennanb2025
brennanb2025 force-pushed the brennanb2025/fix-4471 branch from 9572730 to f11a4f2 Compare August 23, 2026 21:06
@brennanb2025

brennanb2025 commented Aug 23, 2026 •

Copy link
Copy Markdown
Contributor Author

Round 2 — the missing reviews arrived, and they found something

The two reports I said were undeliverable came through after all. Both were substantive, and one found a
real defect. Head is now f11a4f2c38.

P2 coverage hole — FOUND, CONFIRMED, FIXED

retiresCreatedName: isPoolShaped was asserted only on the three success paths. Narrowing just the
three failure/rollback call sites back to the old nameWasGenerated === true condition —
orca-runtime.ts:24898, worktree-remote.ts:1805, worktree-remote.ts:2433 — killed zero tests. I
reproduced that before fixing: 1213 passed, identical to baseline.

Why it matters: the failure paths are where a blind registry bites hardest. A client that never sent the
bit creates nautilus, sparse setup fails, the rollback also fails, the directory survives — and nothing
is recorded. The next generated create lands on that spent cwd and inherits the previous occupant's agent
history, which is the original STA-4471 symptom.

Fixed with two tests on the rollback path: one asserting a pool-shaped name is recorded with no
provenance bit, one asserting a coined fix-login is not. Re-running the same failure-path-only
narrowing now kills the first:

× retires a pool-shaped name a failed create left behind even with no provenance bit
Tests  1 failed | 1187 passed | 1 skipped (1189)

Suite is green at 1215 passed / 1 skipped.

Two review suggestions I checked and declined — with reasons

A generator instead of candidateAt(suffix) → null. The argument was that
for (const c of plan.candidates()) would drop the rung index from the call sites and make "a skipped
rung costs no attempt" structural rather than a convention three files honour by hand. That reasoning is
good, but the premise does not hold here: the callers genuinely need suffix —
getBranchNameOverrideCandidate(args.branchNameOverride, suffix) at worktree-remote.ts:1608 and
:2177, and the suffix > 1 guard at :2239 that avoids a ~1–3s gh pr list on the common
no-collision path. A generator would have to yield the index anyway, so it would remove the null check
and nothing else. Not worth touching three create paths for at P2.

const retirementStore = this.store is redundant. It is not. this.store is nullable, and the
narrowing does not survive into the loadRetiredNames closure — removing the alias fails typecheck with
TS2531: Object is possibly 'null'. Since it reads as noise convincingly enough that a reviewer flagged
it, I added a comment saying why it exists, so the next person does not delete it.

Corroboration worth recording

The independent review confirmed several things I had asserted, by different routes: the requestedName
display-suffixing branch correctly stayed keyed on usesGeneratedLadder rather than retiresCreatedName
(the obvious trap when decoupling the two decisions); the effectiveSanitizedName initialisation change
is unobservable; loop termination is bounded by the finite explicit-names set because generated
candidates always start above the compaction watermark; and no code path generates a creature name
without setting the bit — including both retry paths
(create-worktree.ts:65, worktree-create-retry.ts:80), which was the specific defect shape I was most
worried about.

One thing it caught that I had not: isGeneratedWorktreeCreateName is a wider predicate than what
actually persists, so retiresCreatedName is true for a repeat-suffixed spelling like nautilus-2-2
that the typed ladder can now produce. Harmless — normalizeRetirableGeneratedName gates on
creatureNameTier, which rejects it, so the store drops it silently, and the generated ladder can never
emit that spelling anyway. Verified, not changed.

Design audit — full verdict now available

CONFORMS WITH CAVEATS, consistent with what I derived independently, with more detail. The
two-decisions split is the sound one: never accept a caller's provenance claim for a durable write —
derive it host-side from request shape, or store it host-side instead. The safe shape for a provenance
enum is to default to the safe value, let an "auto" claim only remove privileges, and normalise absent
to the restrictive reading for pre-provenance snapshots — the same move this PR makes for the same reason.

Silently suffixing a typed name is the common answer; this PR is more conservative than that.
The caveat: a typed name landing on a directory the app has flagged unsafe has no established answer,
and refusing is the defensible alternative. I have added an explicit "the cost this accepts" section to
the PR body rather than leaving that to be discovered.

Also unproven, so absence of objection should not be read as endorsement: a permanent non-evicting
spent-name registry; a client-transmitted provenance boolean travelling beside the value it describes;
tier-ladder canonicalisation; skipping a rung without spending an attempt budget; and gating an expensive
taken-set read on provenance.

Where this leaves the loop

Round 2 found and fixed a defect, so by the stopping rule this is not a clean round — a further round
would be needed. I am out of runway to run one: the dispatch that authorised this work has closed, so I
can neither report to my coordinator nor spawn another reviewer under it. Stating that plainly rather
than implying the loop converged.

Standing risk for whoever picks this up: the fix above touched only tests plus one comment, so the
production behaviour verified in rounds 1 and 2 is unchanged — but the new failure-path tests themselves
have not been reviewed by anyone other than me.

@brennanb2025

Copy link
Copy Markdown
Contributor Author

CI is queued, so I ran its gates locally on f11a4f2c38

GitHub Actions is backed up — PR Checks has been queued on runner capacity for hours, on this head and
the previous one. That is a capacity backlog, not a failure. To avoid anyone blocking on it, I ran the
gates locally:

gate result
typecheck (all projects) clean
audit:code-quality:native (--deny-warnings) clean
audit:code-quality:type-aware (--deny-warnings) clean
check:max-lines-ratchet OK — 188 grandfathered, no new bypasses
check:reliability-gates passed, 88 gates
oxfmt clean
affected suites (4 files) 1215 passed / 1 skipped

The max-lines ratchet is the one worth calling out: this round added ~45 lines to
orca-runtime.test.ts, which is already large, and the ratchet still passes with no new bypass.

This is not a substitute for CI — it does not cover packaging, Windows, the Git-compatibility matrix, or
cross-version wire compatibility. Those still need the real run before merge.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant