Skip to content

fix(dev-fleet): re-resolve the main checkout without a gateway restart - #12463

Merged
chenmingwei23 merged 2 commits into
mainfrom
fix/dev-fleet-reresolve-main-checkout-3470
Sep 21, 2026
Merged

chenmingwei23 merged 2 commits into
mainfrom
fix/dev-fleet-reresolve-main-checkout-3470

Conversation

@chenmingwei23

@chenmingwei23 chenmingwei23 commented Sep 21, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

A user who answers Dev Fleet's setup card keeps seeing the setup card. ensure_main_repo_discovered() set _DISCOVERY_DONE = True at the end of every run, including a run that found nothing, so a process that started before the operator pointed Dev Fleet at a checkout answered "no checkout found" for the rest of its life.

repo_path was the odd knob out. auto_prune is re-read each reaper cycle and ticket_url_template is read per resolution, so both take effect while the gateway runs.

Why it matters

This lands in the lowest-context moment the product has: a first run, on the one screen whose only job is to get the user to a working fleet. The old copy did name the restart, so it was not a trap, but "do this, then restart the gateway" is a worse loop than "do this" when nothing about the state actually requires a restart.

What changed

Symptom: the setup card never goes away. Root cause: the latch recorded a negative result as final. Change: _DISCOVERY_DONE = bool(discovered), so only a resolved checkout latches, and /fleet calls the new worktree_ops._ensure_repo_resolved() per poll. That returns at a truthiness guard before any await, so a resolved install pays nothing and only the state with no fleet re-runs discovery.

Only one of the two documented remedies can self-heal, and the copy now says which. This corrects a premise in the issue, which lists setting KIROCREW_DEVFLEET_REPO and adding dev_fleet.repo_path as equivalent. _load_dev_fleet_cfg re-reads config.json on every call, so a running process sees a newly written repo_path. KIROCREW_DEVFLEET_REPO is read with os.environ.get off this process's own environment, which no outside shell can change, so that route needs a restart and always will. no_checkout_found_action previously ended "then restart the gateway" for both; it now leads with the config route and says plainly that the variable needs a restart.

The refresher restart is not bookkeeping. _status_refresher returns when nothing is resolved rather than idling, on the previously correct reasoning that a startup-resolved global never becomes resolved later. A late resolution that left it stopped would serve a fleet whose rows never refresh again: the setup card disappears, the page looks alive, and nothing fetches. That is worse than the honest "restart the gateway" this replaces, so _ensure_repo_resolved starts it on the attempt that resolves. It lives in worktree_ops because the task handle is owned at that level and repository sits below it in the component DAG.

No verdict outlives the attempt that produced it. _REPO_INVALID_MSG is now assigned on both branches, so an attempt that finds nothing clears it instead of inheriting it. This is the hazard the triage proposal identified and the issue's own inventory missed: MAIN_REPO from a later attempt sitting beside an earlier attempt's validation verdict would hand _repo() a path whose markers were never checked, and worktree remove, update-ref -d, pull --ff-only and pip install -e run inside whatever that is.

The retry spawns no subprocess. _load_fallback_repos and _upstream_remote both return before reaching git while _repo() raises, and _resolve_primary_checkout runs only on an attempt that found a path. The credential-helper warm keeps its own None sentinel because it reads --system and --global scope only and is repo-independent, so its two git config calls stay once-per-process rather than once-per-poll. What an unresolved poll costs is tiers 2 and 5 on the subprocess executor, every 12 seconds, only while the page is open.

A resolved path that fails the marker test still latches, and that state renders the RepoUnreadable banner naming the path and the remedy. That latch is reopenable, and only tier 1 is fixed for the process: it is read off this process's own environment, which no outside shell can change, whereas tier 2 re-reads config.json on every call. So _invalid_resolution_is_stale reopens the latch once the configured string changes, which is what makes the card's "picks it up on its next refresh" promise true for the typo case as well as the not-found one. It compares against the string the latching attempt read rather than against MAIN_REPO, which is the _resolve_primary_checkout form of it, so a configured path pointing into a linked worktree does not read as changed on every poll. Both reads that decide where the fleet points go through _configured_main_repo_checked, and the attempt hands its one snapshot to _discover_main_repo rather than letting it read tier 2 again, because two reads of one file can disagree and the inferred latch that disagreement produces would be valid, and therefore final.

Two of the four blockers the issue lists needed no work, which the triage proposal established and I confirmed against the code. The AST ratchet checks MAIN_REPO loads, not writers, so a second writer needs no exemption; both new guards are bare truthiness tests, which it permits. _UPSTREAM_REMOTE and _FALLBACK_REPOS decline to cache when _repo() raises, so neither was ever poisoned. Main also already carried ensure_main_repo_discovered() as a single-flight seam, so no new lock or entry point was needed.

The decision to make this lifecycle change is recorded in #3470, raised by Design Review on #3406 and routed by triage. No user-facing default of a command, loop or agent changes: an unconfigured install that previously required a restart now resolves on its own, and a configured install behaves identically.

Backwards compatibility

Compatible on every wire shape, with one behaviour change declared below. Nothing is rejected, renamed or removed. _DISCOVERY_DONE goes from "always true after the first run" to "true once a checkout resolved", which only ever adds attempts in the state that had no fleet; a resolved install runs discovery exactly once, as before. RepoNotConfigured stops being terminal for the process lifetime, and every existing catch site already treats it as a per-call condition and recomputes: _upstream_remote degrades to origin without caching, _load_fallback_repos leaves the list None which consumers read as or [], and _auto_prune_reaper re-asks _repo() every cycle. GET /api/crons and every other payload shape is unchanged; the only wire-visible difference is that /fleet can stop reporting needs_setup without a restart.

The one behaviour change, stated plainly because it is a trade rather than a strict improvement: an attempt that cannot parse config.json or its overlay publishes no checkout, where this base falls through to the inferred tiers. While a writer is mid-write that is a one-poll pause. If the file never parses, a stray comma left in config.local.json say, the setup card stays where the base would have served an inferred fleet. That is intended. When the read fails there is no way to tell an operator who set dev_fleet.repo_path from one who set nothing, so inferring serves the second correctly and silently runs Pull + Build, worktree remove and update-ref -d inside a checkout the first never named; refusing costs the second a setup card until the file parses. Given which of those two errors is recoverable, refusing is the safer direction for a surface that runs destructive git. The residual is that the card attributes that state to a missing checkout rather than to the unreadable file, which is tracked in #12513 rather than folded in here.

Tests

test/test_dev_fleet_repo_reresolution.py, 9 cases: an attempt that finds nothing does not latch, the first attempt that resolves does, a resolved-but-invalid path latches, a stale invalid-path message is cleared, the helper warm is paid once across three attempts, a resolved install runs no discovery, a late resolution starts the refresher, a still-unresolved attempt does not, and a disabled-background-tasks mode resolves without starting a task.

Mutation-verified: 7 mutations applied to real source, 7 caught, both sources restored byte-identical. Each breaks one property, including restoring the original unconditional latch and letting the invalid-path verdict survive.

Also green locally: 84 backend cases across the accessor ratchet, component boundaries, gateway routes and the new file; 96 DevFleetPage cases; all 19 i18n checks including changed-passthrough and changed-values; all 11 locale style suites, 95 cases. The gates check_sync_io_in_async, check_loop_bound_locks, check_feature_map, check_black_formatting, check_subprocess_encoding, check_focus_cue, check_comment_history and docs_lint pass, plus black and flake8 on the four changed Python files.

The zh-CN style suite caught a real defect in my first draft: it stacked four possessive particles in one value where its rule permits two.

Catalog edits are textual, 1 line changed and 0 added per file, so the reserialisation that duplicateKeys.test.ts documents dropping eleven Japanese translations is avoided.

Manual verification

N/A for the mechanism, and stated rather than skipped. The behaviour is a module-global lifecycle over three call sites, and the 9 cases plus 7 mutations cover each transition directly, including the two that need an event loop (refresher start, and no start while unresolved). Reproducing it by hand needs a gateway that genuinely cannot find a checkout, which on this host means pointing a pod at a path with no checkout anywhere in its discovery tiers, and the observable result is the same boolean the tests assert.

The copy change is verified by the gates that own it rather than by eye: changed-passthrough at zero for all 11 non-English catalogs, the 11 per-locale register suites, and the existing DevFleetPage assertion that the card still renders its env example.

Related Issues

Fixes #3470

Supersedes #11972, which is this same commit raised from a fork. The fork
review lanes cannot complete: fork-opus-review.yml sets egress-policy: block with an allowlist that omits the Claude Code installer host, so every
Fork Opus run fails with Failed to connect to claude.ai port 443 after 1 ms.
That outage is tracked as #11911; #11976 allowed the bun release-asset host
but not the installer host, and #12081 / #12201 propose the remaining entry.
claude-review.yml, the same-repository lane, declares no egress policy, so
this branch can actually be reviewed. The tree here is byte-identical to
#11972 at 89cb4e2.

Pattern harvest

Rule candidate: review-prompt

Pattern: a single-flight latch records "done" after an attempt that produced no answer, freezing a state the operator can still change from outside the process. The generalization is worth a prompt line because the latch reads as correct at the call site (it is idempotent, it is single-flight, it does cache) and only the negative case is wrong. The same shape shipped in config-default materialization, where a stored value always beat a changed dataclass default. Worth asking of any _DONE / _LOADED / is None guard: does it cache an ANSWER, or the absence of one?

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

No checkout found setup card, dark theme, showing the config.json-first remedy

No checkout found setup card, light theme

@chenmingwei23
chenmingwei23 requested review from a team and Zedmor September 21, 2026 05:54
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 21, 2026
@github-actions

github-actions Bot commented Sep 21, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 9e75f24a0fc7c5fc0c2c286e7305a7c61bef001c and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 9e75f24

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 9e75f24a0fc7c5fc0c2c286e7305a7c61bef001c: <one-sentence reason>

@github-actions

github-actions Bot commented Sep 21, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — ✅ PASS

Premise-level review of 9e75f24a0fc7c5fc0c2c286e7305a7c61bef001c — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: PASS

Verify the declared trade: an unparseable config.json now shows the setup card where base served an inferred fleet — confirm #3470's triage covers that direction.

What this change ships

Inventory (9 items) — 8 justified

Intent: FIX — a user who answers Dev Fleet's setup card keeps seeing it, because a failed discovery latched as final; discovery now retries until a checkout resolves.

  1. Answering the setup card via dev_fleet.repo_path takes effect on the next poll, no gateway restart — justified
  2. Setup-card copy now leads with the config route and says the env var still needs a restart (all locales) — justified
  3. Correcting a typo'd configured path replaces the invalid-checkout banner without a restart — justified
  4. A late-resolved fleet's rows keep refreshing (status refresher restarted on resolution) — justified
  5. A retry that finds nothing clears the earlier attempt's invalid-path verdict instead of inheriting it — justified
  6. An unparseable config.json now shows the setup card instead of serving an inferred fleet — justified
  7. Each attempt acts on one config snapshot, so a mid-write read cannot latch an inferred checkout — justified
  8. The git credential-helper warm stays once-per-process across retries — justified
  9. de/fr help and env-example strings (and bn/hi card tone) switch formal→informal — rides along; mandated by the locale style guides' du/tu register rules

[FIRST-PRINCIPLES-REVIEWED] 9e75f24

@github-actions

github-actions Bot commented Sep 21, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

Design-level review of 9e75f24a0fc7c5fc0c2c286e7305a7c61bef001c — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Verify the declared trade: a permanently unparseable config now yields a setup card blaming a missing checkout, not the unreadable file (#12513).

[DESIGN-REVIEWED] 9e75f24

@github-actions

github-actions Bot commented Sep 21, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Fable 5) — ✅ PASS

UX-level review of 9e75f24a0fc7c5fc0c2c286e7305a7c61bef001c — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

UX-Verdict: PASS

The card's only copy-able snippet (KIROCREW_DEVFLEET_REPO=...) now demonstrates the demoted restart-requiring route — verify it doesn't misdirect first-run users.

Suggestions

  • In DevFleetPage.tsx:2228 / no_checkout_found_env_example, add or swap in a dev_fleet.repo_path config.json snippet so the recommended remedy gets the monospace example; the blind reader anchored on the env line's restart warning ("I wouldn't dare actually use it").

[UX-REVIEWED] 9e75f24

@github-actions

github-actions Bot commented Sep 21, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review — ✅ no blocking findings

Reviewed 9e75f24a0fc7c5fc0c2c286e7305a7c61bef001c — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 9e75f24

Verdict parsed from the review's SHA-scoped output markers for commit 9e75f24a0fc7c5fc0c2c286e7305a7c61bef001c.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 9e75f24a0fc7c5fc0c2c286e7305a7c61bef001c: <one-sentence reason>

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Sep 21, 2026
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Review round 1 disposition

Head 4ecb2f6268fde4a0f7bc1458b09d6ccd0980fa76. Blocking lanes on the previous head are
clean (GPT and Opus: no blocking findings; First Principles PASS; Security Scope success).
Two advisory verdicts, dispositioned below.

Design CONCERNS -- fixed

The finding is correct and the defect is mine. _DISCOVERY_DONE = bool(discovered) counts a
found-but-invalid path as resolved, because a mistyped path is still truthy. So an operator
who mistypes dev_fleet.repo_path, reads the RepoUnreadable banner and corrects
config.json keeps that banner until a restart, which is the freeze this change removes for
the not-found case. The reviewer also caught that my own justification is false: the spec
sentence "tiers 1-2 are taken verbatim, so re-running returns the same path every time" does
not hold for tier 2, which re-reads config.json on every call, and that self-heal is the
property the not-found fix depends on.

Taken the first of the two remedies the verdict names, the string compare with no subprocess.
_invalid_resolution_is_stale reopens the latch when the configured value differs from the
string the latching attempt read. Three details worth naming:

  • It compares against _LATCHED_CONFIGURED, not against MAIN_REPO. MAIN_REPO is the
    _resolve_primary_checkout form of the configured value, so a path pointing into a linked
    worktree is rewritten to its primary and would read as changed on every poll, buying a
    re-resolution for a config nobody edits.
  • A resolved and valid install still returns at the first guard with no await, so an install
    that has a fleet to serve pays nothing. Only the latched-invalid state falls through, and
    it settles under the existing lock so concurrent polls share one config read.
  • An env-set path cannot change inside one process, so the reopening never fires for that
    route and the banner correctly keeps naming a restart as its remedy.

_ensure_repo_resolved now asks through _repo() rather than testing MAIN_REPO for
truthiness, because _status_refresher returns on its first line for an unusable checkout,
so starting it would mint a task per poll that dies immediately.

Five tests cover this, each mutation-verified: correcting the path re-runs discovery; an
unchanged invalid path buys no second attempt; the compare is against the configured string
rather than the resolved one; an env-set path is not reopened by a config edit; and the
/fleet route re-runs discovery while the path is invalid.

UX suggestion -- kept out of this change, with the reason

The mechanism is real: the card's only copyable snippet is no_checkout_found_env_example,
which belongs to the route the new copy demotes, so the affordance and the recommendation
point at different routes.

The consequence the suggestion names is already covered by the adjacent sentence.
no_checkout_found_action reads: "Add dev_fleet.repo_path to config.json in your
{{productName}} data directory (~/.kiro/crew by default), and this page picks it up on its
next refresh. The environment variable below works too, but a running gateway cannot see a
variable set after it started, so that route needs a restart." A reader who copies the env
line is told that route needs a restart, so the never-goes-away loop is not re-entered
silently. What is missing is parity of affordance, not of information.

Closing that gap costs a new i18n key in 12 locale catalogs, plus the generated en-XA
pseudolocale, the en.context.json translator sidecar, and the deadKeys ratchet, whose
baseline reds in both directions. That is more than fifteen files of catalog churn for a copy
addition, on a change whose blocking lanes are already clean and whose review lanes re-roll
on every new head. It is a copy improvement the setup card deserves on its own, sized and
reviewed as copy rather than ridden in on a resolution-latch fix.

CI

One failure on the previous head,
test/test_runtime_cleanup_windows.py::test_windows_owner_shutdown_reclaims_children_after_root_exit
("owned processes still alive"), against 13613 passed. It is Windows process reaping. This
change touches dev_fleet/{http_api,repository,worktree_ops}.py, one test file, the module
spec and the locale catalogs, so there is no file overlap, and the new test file contains no
platform branch, no signal or wait call, and no process spawn. Treated as base-owned and
confirmed against another head rather than adjusted here.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 21, 2026
@chenmingwei23
chenmingwei23 force-pushed the fix/dev-fleet-reresolve-main-checkout-3470 branch from 4ecb2f6 to 83317ed Compare September 21, 2026 08:13
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 21, 2026
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Disposition for head 83317edf81791add7cf9ea5bf07028b263fcde2f

Three things happened since the last round: a rebase onto current main, the
screenshot the UX lane asked for, and the two findings below dispositioned
rather than coded.

UX evidence gap: closed

Two frames of the "No checkout found" card are now attached to the PR body,
dark and light. They were produced by this repository's own
website/scripts/capture-devfleet-discovery.mjs, which drives the isolated
entry website/capture/devfleet-discovery.html and mounts the real
DevFleetPage with fetch stubbed at the network seam. The script asserts its
headline copy before shooting, so a frame of an error boundary or of the wrong
branch fails there instead of shipping as evidence. Each frame was opened and
read before attaching.

UX Watch, German register: no code change, and the remedy is inverted

The finding observes correctly that no_checkout_found_action addresses the
reader informally while its siblings on that card use the formal register. The
proposed remedy, recasting the German value into the formal register, is the
wrong direction, and the authority is this repository's own style guide.

website/src/i18n/style/de.md section 4 states the rule plainly: use the
informal address, not the formal one, to match the casual English voice. The
value this PR wrote follows that rule. The strings it sits beside
(no_checkout_found_help and several others on the same page) use the formal
register and are therefore the ones diverging from the guide. They are
pre-existing and unmodified by this diff, so adopting the remedy would move the
one compliant string on that card out of compliance.

The same informal rule is documented for every other language this diff
touches: es.md, fr.md (which spells out the informal imperative form
explicitly), it.md, ru.md, bn.md, and pt.md. The values written here
match each of those.

One note on evidence, because it cuts against a check a reader might reach for.
website/src/i18n/style/deStyle.test.ts does assert the informal register, but
its pattern only matches the formal pronoun when it is directly followed by one
of seven specific verbs, under a tolerance of 12. The formal recast of this
particular string contains none of those verbs, so that test would pass either
way. Its green result cannot distinguish the two spellings and is not evidence
here. The citable authority is de.md itself.

The pre-existing divergence in the sibling strings is real but belongs to main,
not to this change. Happy to file it as its own issue if that is wanted; it
should not ride along here, since it would mean rewriting untouched strings
across the page.

UX Watch, the copyable snippet: stands as dispositioned

This is the item already answered in
#12463 (comment), and
that disposition stands. The attached frame is useful new evidence on it: the
restart caveat is not in a separate paragraph a scanning reader can miss, it is
the closing clause of the very paragraph the snippet sits directly beneath, so
the warning and the snippet are adjacent on screen rather than separated.

The reviewer is right that the only monospace line on the card is the
environment variable, and right that a copy affordance for the recommended
route would be better. That remains a copy-and-layout change rather than an
information gap, and its cost is a new key across 13 catalogs plus the
generated pseudolocale, the translator-context sidecar, and a two-way dead-key
ratchet. That is a wide catalog change on a PR whose blocking lanes are
otherwise clean, so it is better as its own change.

Design PASS, the human-eye translation ask: verified, all 13 locales

The Design verdict asked for a human-eye check that the restart caveat survived
translation, since the register gates verify style rather than meaning. It did
survive in all 13 locales. Each value carries both halves of the caveat: that a
running gateway cannot see a variable set after it started, and that the
environment-variable route therefore needs a restart.

Worth recording how that was checked, because the first pass got it wrong. An
automated scan reported the caveat missing from the Bengali, Hindi and Korean
values. That was a defect in the scan, not in the translations: it normalized
text by decomposing characters and stripping combining marks, which mangles
Devanagari vowel signs and decomposes Hangul syllables, so it could not match
the very scripts it was asked about. Read directly, all three carry an explicit
restart term. The other ten were already unambiguous.

Rebase, and two failures that were not this diff's

The previous head carried two red lanes that both belonged to the base, and the
rebase onto current main cured both without this diff changing a line.

Backend Lint & Type Check failed on a missing named argument at an
_authorize_upload call site in the AWS Control backend, a file this diff does
not touch. Main had already fixed it; that call site now passes the argument.

Bundle Size Gate failed because the base pinned an older per-chunk ceiling
for the combined chunk while main had already raised it after measuring its own
growth. The measured chunk here sits comfortably under main's ceiling. The gate
script is not part of this diff, so the rebase simply inherited the current
ceiling and nothing was hand-edited.

The diffstat is byte-identical before and after the rebase: same 18 files, same
insertion and deletion counts, so the rebase changed nothing about the change
itself. Locally, 479 tests pass across the three affected dev-fleet test files,
and every pre-push gate passes with its base ref set to current main.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 21, 2026
@chenmingwei23
chenmingwei23 force-pushed the fix/dev-fleet-reresolve-main-checkout-3470 branch from 9846e35 to 7b41f1b Compare September 21, 2026 09:06
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 21, 2026
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 21, 2026
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Advisory dispositions for 05fdbdecabd7cd48f9a81d2ff807f95fc808f9db

Both blocking reviewers are clean on this head. The three CONCERNS below are
advisory, and this is how each is being handled.

UX: the German and French register is correct as written, and the proposed remedy is not

The observation is accurate: the new remedy sentence addresses the reader
informally while the sentence above it on the same card stays formal. The
proposed fix, rewriting both strings into the formal register, is the wrong
direction, and this repository's own style guides say so.

website/src/i18n/style/de.md section 4 states the rule plainly: use the
informal address, not the formal one, to match the casual English voice.
website/src/i18n/style/fr.md section 4 does the same and goes further, giving
the informal imperative as the correct form and the formal imperative as the
incorrect one, by example. The values this change writes follow both guides. The
sentences they sit beside use the formal register and are therefore the ones
diverging from the guide; they are pre-existing and untouched by this diff, so
adopting the remedy would move the one compliant string on that card out of
compliance.

The review's own parenthesis is the tell: Spanish is described as fine "its
siblings already use tu". That is a sibling-consistency test, not a style-guide
test. On this card the siblings are the violators. The same informal rule is
documented for every other language this diff touches, in es.md, it.md,
ru.md, bn.md and pt.md, and each value matches its own guide.

One note on evidence, because it cuts against a check a reader might reach for.
deStyle.test.ts does assert the informal register, but its pattern only matches
the formal pronoun directly followed by one of seven specific verbs, under a
tolerance. The formal recast of this particular string contains none of those
verbs, so that test passes either way and cannot distinguish the two spellings.
The citable authority is the guides themselves.

Bringing the sibling strings into line with the guides is a real cleanup, but it
means rewriting untouched strings across the page and belongs in its own change
rather than here.

UX suggestion: the refresh-cadence wording is declined

Appending a duration to the remedy sentence would mean re-translating one string
across 13 catalogs plus the generated pseudolocale and the translator-context
sidecar. It would also state a cadence the code does not promise: the pickup
happens on the next /fleet poll, whose interval is not a guarantee this copy
should make. Better left unsaid than stated as a number that can drift.

Design and First Principles: confirming the trade, and naming the residual

Both reviews land on the same premise, and the confirmation they ask for is yes:
refusing to resolve while the operator's configuration cannot be read IS the
intended behaviour, including when the file never becomes readable, and it is a
deliberate trade against what the base branch did.

The reasoning. When the config read fails there is no way to tell two situations
apart: an operator who set dev_fleet.repo_path to a specific checkout, and an
operator who set nothing and relies on the inferred tiers. Falling through to
inference serves the second correctly and silently serves the first a checkout
they never named, after which Pull + Build, worktree remove and
update-ref -d run inside it. Refusing serves the first correctly and costs the
second a setup card until the file parses. Given which of those two errors is
recoverable, refusing is the safer direction for a surface that runs destructive
git operations.

The sharper half of the Design finding is not the trade, it is the attribution,
and that part is a real residual. In the persistent case the card says no
checkout was found in the project directory, in the checkout serving the
dashboard, or in the usual clone locations. When the real cause is a file that
will not parse, that sentence is false and it sends the operator looking for a
missing checkout instead of a stray comma. Nothing on any surface names the file.

That is worth closing, and it is cheaper than it looks: the invalid-path banner
is already composed in the backend as plain English rather than through a
catalog, so naming the unreadable file needs no new translation keys. It is not
being folded in here, for one reason: both blocking reviewers are clean on this
head, they re-roll on every new head, and this is an advisory finding about a
state that only arises when the config file is already broken. It will be raised
as its own issue so the message change can be reviewed on its own merits.

Two things will be corrected in the PR description once the current CI round
finishes, since editing the description mid-round cancels runs that are still
going: the sentence saying a marker-failing path still latches, which this diff
changes by reopening that latch on a config edit, and the absence of any mention
of the setup-card trade described above. Those are the two items First Principles
names as undeclared, and they are both fair.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Sep 21, 2026
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: passed Eligible automated validation passed for the current revision readiness: checking Automated validation is still running labels Sep 21, 2026
Dev Fleet resolved its main checkout once per process and latched the answer unconditionally, so a gateway that started before the operator pointed it at a checkout kept answering 'no checkout found' until it was restarted. A found-but-invalid path latched the same way, so an operator who named a readable directory that is not a Kiro Crew checkout met a RepoUnreadable banner that survived every correction they made, while the banner's own remedy was the edit it ignored.

ensure_main_repo_discovered records 'done' only once a checkout RESOLVED, and /fleet re-runs it per poll while nothing is. _invalid_resolution_is_stale reopens an invalid latch once the operator's configured string changes, on that string alone: no git and no stats. It compares against the string the latching attempt read rather than against MAIN_REPO, which is the _resolve_primary_checkout form of it, so a configured path pointing into a linked worktree does not read as changed on every poll. A resolved and valid install returns at its first guard with no await.

Only dev_fleet.repo_path can self-heal. _load_dev_fleet_cfg re-reads config.json on every call, whereas KIROCREW_DEVFLEET_REPO is read off this process's own environment, which no outside shell can change, so that route still needs a restart and the setup card names the two routes separately rather than telling every user to restart. All 13 locales carry that caveat.

Reopening also requires the config read itself to have succeeded. _load_dev_fleet_cfg answers an empty section for a file it cannot parse, so the configured path resolves to the same empty string a config naming no path gives. Treating that difference as a change would reopen the latch on evidence nobody read: discovery would find no configured path, fall through to the INFERRED tiers, and latch a checkout the operator never named while their own setting sat in a file the process merely failed to read, and every later git call, including the destructive ones, would target it.

_load_dev_fleet_cfg_checked reports whether every file present parsed and _configured_main_repo_checked carries that flag beside the path, so a partial read holds the latch while a parseable file carrying no repo_path still reopens. _load_dev_fleet_cfg keeps its plain signature for the callers that read a single setting and have no use for the flag.

_ensure_repo_resolved asks through _repo() rather than testing MAIN_REPO for truthiness, because _status_refresher returns on its first line for an unusable checkout, so starting it would mint a task per poll that dies immediately. An unresolved install spawns no subprocess, and the credential-helper warm keeps its own once-per-process sentinel. A late resolution restarts the status refresher, which returns rather than idles when nothing is resolved.

Tests live in test/test_dev_fleet_repo_reresolution.py and are mutation-verified in both directions, including against the narrower fix that would freeze a genuinely cleared path.

Fixes #3470
@chenmingwei23
chenmingwei23 force-pushed the fix/dev-fleet-reresolve-main-checkout-3470 branch from 05fdbde to 06d621c Compare September 21, 2026 10:41
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/system-specs/modules/aws-control.md, src/kiro_crew/acp/client.py, src/kiro_crew/apps/builtins/aws_control/backend/backup.py, src/kiro_crew/apps/builtins/aws_control/backend/routes.py, src/kiro_crew/dashboard/handlers/agents.py and test/test_aws_control_routes.py since this head went green (3017e6a -> 1fa7f5b); CI re-running.

Scoped tests for those files, re-run on the new head 06d621c: test_acp_client.py, test_aws_control_routes.py and test_aws_control_backup.py, 925 passed. This change's own affected files plus the agents-handler tests: 816 passed, 1 skipped. All 14 local gates green against the new base. The diff is byte-identical to the pre-rebase head, same 18 files and same counts, so the rebase changed history only.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision labels Sep 21, 2026
The staleness test and discovery each needed the configured path, and each read config.json for itself. Two reads of one file can disagree: the first could see a whole, corrected path and reopen the latch while the second returned the empty string from a torn read, sending discovery to the INFERRED tiers.

That latch is the dangerous one. An inferred checkout passes the marker test, so the resolution is VALID and therefore final: nothing re-resolves it, the staleness test only reopens a latched-INVALID resolution, and Pull + Build meanwhile mutates a checkout the operator never named. Only a gateway restart clears it.

The attempt takes one checked read and hands it to _discover_main_repo, which accepts it as an optional argument and reads tier 2 itself only for a caller holding no snapshot, so dev_fleet_startup keeps its existing call. A partial read publishes nothing at all and the next poll retries against a settled file.

Publishing nothing means publishing the UNRESOLVED state rather than leaving the previous one standing. _repo() gates on MAIN_REPO alone and never consults _DISCOVERY_DONE, so an attempt that returned with the provisional import-time hint in place would let every consumer operate on a checkout it could not confirm. That hint is what _default_main_repo_state picks before any config is read, and what dev_fleet_startup exists to replace and normalize, so an attempt that cannot read tier 2 has no basis for endorsing it. Cleared, _repo() raises RepoNotConfigured and the page shows the setup card.

Clearing the published pair is not enough by itself. The reopen path arrives holding _DISCOVERY_DONE True, and the pre-lock gate returns early once MAIN_REPO and the message are both empty, so a torn read there cleared the pair and left the flag standing: the retry this branch promises was unreachable and the page kept the setup card until a gateway restart, the same failure this change exists to end. The branch clears the flag as well.

The German and French cards read in one register. The new action string uses the informal address both style guides mandate, while the adjacent help and env-example strings carried the formal one, so a single card showed both. Those two neighbors move to the informal address in each locale; Spanish already reads that way throughout.

Seven mutations, each reddening its own assertion: dropping the partial-read return, not handing the snapshot to discovery, having discovery ignore the snapshot and re-read, dropping each of the three parts of the clearing, and dropping the _DISCOVERY_DONE clear, which strands the next poll on the reopen path.
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Sep 21, 2026
@chenmingwei23
chenmingwei23 force-pushed the fix/dev-fleet-reresolve-main-checkout-3470 branch from 06d621c to 9e75f24 Compare September 21, 2026 11:09
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision labels Sep 21, 2026
@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • span=cc60d7c3cefe FIXED: the partial-read branch clears _DISCOVERY_DONE

Checked against the code before changing anything, and the finding is correct.
_DISCOVERY_DONE is written in exactly two places, the module initializer and the
publish at the end of a successful attempt, so the partial-read branch returned
without touching it.

Reaching the freeze needs the reopen path. A latched-INVALID resolution whose
config has since been corrected enters the attempt with the flag already True. A
torn read there clears MAIN_REPO and the message and returns, and the pre-lock gate
if _DISCOVERY_DONE and not (_REPO_INVALID_MSG and MAIN_REPO): return then matches
on every later poll. So the retry the branch promises is unreachable, and the setup
card persists until a gateway restart. That is the exact failure this pull request
exists to remove, reintroduced on a narrower path.

Fixed by clearing the flag in that branch. The code comment and the commit message
both carried the same false promise about the next poll and are corrected with it.

The pre-existing test asserted the flag was False after a partial read, but it
started from a fresh chain where the flag was already False, so that assertion was
vacuous for this path. The replacement enters latched, counts config reads, and
asserts the second poll reaches the read rather than returning at the gate. Removing
the one-line fix reddens exactly that test and nothing else, which is the evidence
the test is worth its line.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • span=5a7bbdb99ed0 FIXED: the reopen path leaves the next poll reachable

Checked separately against the code rather than carried over from the sibling lane's
report, and the sequence described is real. Traced state by state: an earlier attempt
latches an INVALID resolution, so _DISCOVERY_DONE is True with both MAIN_REPO and the
message set. The operator corrects config.json. The staleness test reads a whole,
corrected path and reopens. The second read is torn, so configured_whole is False and
the branch clears MAIN_REPO and the message while the flag stays True.

What makes that terminal is the gate rather than the branch. With the pair empty and
the flag set, _DISCOVERY_DONE and not (_REPO_INVALID_MSG and MAIN_REPO) is true, so
every later poll returns before the lock and nothing re-reads the file. _repo() raises
RepoNotConfigured for as long as the process lives, which is a permanent setup card on
a machine whose config is correct.

Fixed by clearing the flag on that branch, so the published state and the flag agree
and the next poll retries against a settled file.

Worth naming precisely because it is the narrower case: the flag value at the end of a
single attempt is identical whether the attempt froze or started fresh, so only a
second attempt distinguishes them. The new test therefore asserts on the read count
across two polls instead of on the flag.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • span=aebcb090921f FIXED: the German and French cards read in one register

The finding is right, and my earlier comment on this answered a different question.
That comment argued about which register is correct, showed that de.md section 4
mandates the informal address and that fr.md section 4 gives the informal imperative
as correct by example, and concluded that the new string was the compliant one and the
formal neighbors were the violators. All of that holds, and none of it addresses the
defect: whoever is at fault, one card renders two registers, and the new string is
what introduced the mix. Declining to act on authorship grounds left a visible defect
in place, so I am treating it as a fix rather than a rebuttal.

Measured before choosing a direction. On this card no_checkout_found_help and
no_checkout_found_env_example carry the formal address in de and fr only, while
no_checkout_found_action is informal; Spanish already reads informally in all three,
which is the in-repo precedent for the target state. Italian, Russian and Portuguese
have no pronoun on this card to conflict.

So the two neighbors move to the informal address in de and fr, four strings in two
catalogs this change already edits. The alternative direction, making the new string
formal to match, would newly violate both style guides, so it was not available.

deStyle.test.ts, frStyle.test.ts and keyReference.test.ts pass, 36 tests. Note for a
later reader that deStyle.test.ts is not evidence either way here: its regex matches
the formal pronoun only when paired with one of seven verbs, so it cannot see this
construct and passed before the fix as well.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Sep 21, 2026

@buluoray buluoray 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.

Verified at 9e75f24a. The fix is real, not a narrowed window — the latch no longer records a negative as final.

_DISCOVERY_DONE has exactly three assignments in repository.py: the module default at :318, the torn-read clear at :443, and _DISCOVERY_DONE = bool(discovered) at :496. That last one is the whole fix: a not-found attempt latches False, so the pre-lock gate at :402 proceeds on the next poll instead of freezing the negative for the process lifetime.

Per-call re-resolution is genuine rather than import-frozen — the class of bug that has shipped here before. The config tier is re-read every attempt through _load_dev_fleet_cfg_checked -> config_dir(), and the import-time MAIN_REPO = _default_main_repo_state() (:313) is stat/env-only and gets overwritten under the lock on each attempt.

The stale GPT BLOCK (posted against head 1805abcd) asked for _DISCOVERY_DONE to be cleared in the partial-read branch; that is present at :442-:443, where the branch also clears MAIN_REPO and _REPO_INVALID_MSG and returns. So the reopen-plus-torn-read path is a retry, not a terminal state.

Caches invalidate on the right key. _LATCHED_CONFIGURED stores the configured string the latching attempt read (:485) and _invalid_resolution_is_stale compares against that, not against the _resolve_primary_checkout-rewritten MAIN_REPO. No cached-None dead branch is introduced: _upstream_remote returns "origin" without assigning _UPSTREAM_REMOTE, and _load_fallback_repos returns leaving _FALLBACK_REPOS as None, so an unresolved poll poisons neither.

MAIN_REPO and its validation verdict are published with no interposed await (:473 then :479), so _repo() — which checks both — can never hand out a path whose markers were not checked. That is what keeps a destructive git op off an unvalidated path.

The sync guard is unaffected: its python -c probe lives in worktree_ops.py and already passes -I to drop cwd from sys.path, and this diff adds no cwd-sensitive probe — discovery is config read, stats, and git -C <repo>.

Concurrency is double-checked locking on _DISCOVERY_LOCK with every safety-critical global written under it; a pre-lock read race self-corrects on the next poll and cannot trigger a git op because _repo() re-validates at each call site.

One behaviour worth knowing rather than fixing: a VALID resolved install returns at the pre-lock guard and will not re-target if the operator later edits dev_fleet.repo_path to a different valid checkout without a restart. That matches the PR's stated scope and is arguably the safer default (no silent mid-run target swap), but the setup-card copy only distinguishes the env-var route, so the restart requirement is not stated anywhere the operator would see it.

@chenmingwei23
chenmingwei23 merged commit 5fab0e2 into main Sep 21, 2026
93 checks passed
@chenmingwei23
chenmingwei23 deleted the fix/dev-fleet-reresolve-main-checkout-3470 branch September 21, 2026 15:14
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 21, 2026
amadsalmon pushed a commit to amadsalmon/KiroCrew that referenced this pull request Sep 22, 2026
kirodotdev#12463)

* fix(dev-fleet): re-resolve the main checkout without a gateway restart

Dev Fleet resolved its main checkout once per process and latched the answer unconditionally, so a gateway that started before the operator pointed it at a checkout kept answering 'no checkout found' until it was restarted. A found-but-invalid path latched the same way, so an operator who named a readable directory that is not a Kiro Crew checkout met a RepoUnreadable banner that survived every correction they made, while the banner's own remedy was the edit it ignored.

ensure_main_repo_discovered records 'done' only once a checkout RESOLVED, and /fleet re-runs it per poll while nothing is. _invalid_resolution_is_stale reopens an invalid latch once the operator's configured string changes, on that string alone: no git and no stats. It compares against the string the latching attempt read rather than against MAIN_REPO, which is the _resolve_primary_checkout form of it, so a configured path pointing into a linked worktree does not read as changed on every poll. A resolved and valid install returns at its first guard with no await.

Only dev_fleet.repo_path can self-heal. _load_dev_fleet_cfg re-reads config.json on every call, whereas KIROCREW_DEVFLEET_REPO is read off this process's own environment, which no outside shell can change, so that route still needs a restart and the setup card names the two routes separately rather than telling every user to restart. All 13 locales carry that caveat.

Reopening also requires the config read itself to have succeeded. _load_dev_fleet_cfg answers an empty section for a file it cannot parse, so the configured path resolves to the same empty string a config naming no path gives. Treating that difference as a change would reopen the latch on evidence nobody read: discovery would find no configured path, fall through to the INFERRED tiers, and latch a checkout the operator never named while their own setting sat in a file the process merely failed to read, and every later git call, including the destructive ones, would target it.

_load_dev_fleet_cfg_checked reports whether every file present parsed and _configured_main_repo_checked carries that flag beside the path, so a partial read holds the latch while a parseable file carrying no repo_path still reopens. _load_dev_fleet_cfg keeps its plain signature for the callers that read a single setting and have no use for the flag.

_ensure_repo_resolved asks through _repo() rather than testing MAIN_REPO for truthiness, because _status_refresher returns on its first line for an unusable checkout, so starting it would mint a task per poll that dies immediately. An unresolved install spawns no subprocess, and the credential-helper warm keeps its own once-per-process sentinel. A late resolution restarts the status refresher, which returns rather than idles when nothing is resolved.

Tests live in test/test_dev_fleet_repo_reresolution.py and are mutation-verified in both directions, including against the narrower fix that would freeze a genuinely cleared path.

Fixes kirodotdev#3470

* fix(dev-fleet): carry one checked config snapshot through discovery

The staleness test and discovery each needed the configured path, and each read config.json for itself. Two reads of one file can disagree: the first could see a whole, corrected path and reopen the latch while the second returned the empty string from a torn read, sending discovery to the INFERRED tiers.

That latch is the dangerous one. An inferred checkout passes the marker test, so the resolution is VALID and therefore final: nothing re-resolves it, the staleness test only reopens a latched-INVALID resolution, and Pull + Build meanwhile mutates a checkout the operator never named. Only a gateway restart clears it.

The attempt takes one checked read and hands it to _discover_main_repo, which accepts it as an optional argument and reads tier 2 itself only for a caller holding no snapshot, so dev_fleet_startup keeps its existing call. A partial read publishes nothing at all and the next poll retries against a settled file.

Publishing nothing means publishing the UNRESOLVED state rather than leaving the previous one standing. _repo() gates on MAIN_REPO alone and never consults _DISCOVERY_DONE, so an attempt that returned with the provisional import-time hint in place would let every consumer operate on a checkout it could not confirm. That hint is what _default_main_repo_state picks before any config is read, and what dev_fleet_startup exists to replace and normalize, so an attempt that cannot read tier 2 has no basis for endorsing it. Cleared, _repo() raises RepoNotConfigured and the page shows the setup card.

Clearing the published pair is not enough by itself. The reopen path arrives holding _DISCOVERY_DONE True, and the pre-lock gate returns early once MAIN_REPO and the message are both empty, so a torn read there cleared the pair and left the flag standing: the retry this branch promises was unreachable and the page kept the setup card until a gateway restart, the same failure this change exists to end. The branch clears the flag as well.

The German and French cards read in one register. The new action string uses the informal address both style guides mandate, while the adjacent help and env-example strings carried the formal one, so a single card showed both. Those two neighbors move to the informal address in each locale; Spanish already reads that way throughout.

Seven mutations, each reddening its own assertion: dropping the partial-read return, not handing the snapshot to discovery, having discovery ignore the snapshot and re-read, dropping each of the three parts of the clearing, and dropping the _DISCOVERY_DONE clear, which strands the next poll on the reopen path.
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.

Dev Fleet: re-resolve the main checkout without a gateway restart

2 participants