Repository navigation
fix(agent): say why a worktree gateway has no agent definition - #36123
Conversation
UX Review (Opus 5.5) — ⏭️ skippedRevision |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks: the change only adds a hint to an error message, the guard it describes is untouched, and if the helper fails the plain reason is still returned. Notes
[DESIGN-REVIEWED] fb7696f Description read[DESCRIPTION-READ] 977ecf289251257f9ac5eaefd8979954d2bbbbbd5049a62163025241850c3924 That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Nothing blocks. The refusal now names the cause the guard already knows. Leaving the guard as it is was a stated choice: What this change shipsInventory (3 items) — 3 justifiedIntent: someone running a gateway from a linked worktree on an empty agent home learns why chats can't start and how to fix it (FIX, #35440).
[FIRST-PRINCIPLES-REVIEWED] fb7696f Description read[DESCRIPTION-READ] 84dbd8be1ff532bb389583532cbbafb531f984f7c5322f07ca253b30ec3b4e31 That sha256 names the PR description this verdict read. Recompute it with |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
|
Review dispositions for
|
A gateway running from a linked git worktree is refused the shared agent home, so on a home with no specs nothing writes kirocrew.json and every chat failed with a bare 'its agent definition is missing'. The refusal now names the worktree guard, the agent home, and what to do instead. Fixes #35440
A home holding kirocrew.json was written by an install, so one agent missing from it is not the worktree guard's doing. Drop the remedy that read as the KIRO_HOME relocation the guard deliberately does not suggest.
93e990f to
fb7696f
Compare
Code change approver recommendation: ApproveWhy: the decider estimates a 10% chance that this change introduces a defect, within the 12% limit for approving on its own, and every check passes. This PR adds a read-only helper. When a linked-worktree gateway has no kirocrew.json and the shared-home guard declines (checked with audit=False), it appends a sentence to the generic missing-agent reason. The call is wrapped in try/except, so a failure drops only the hint and never the reason. Owner modules run in kiro_crew.agent's namespace, so file and the patched names resolve correctly. Private agents dirs, including test redirects, hit the guard's private-target branch and get no hint. The earlier Opus blocking finding was against an earlier commit and is fixed on this head by the kirocrew.json existence check, which a new test pins. The positive test would fail without the change. The guard itself is untouched. CI failures are GitHub API rate-limit errors, not code failures; most backend test jobs were skipped and Analyze (python) was still pending. An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit |
|
Disposition for the Design Review note on |
KiroCrewCaptain
left a comment
There was a problem hiding this comment.
Tier 1 auto-approve: fix (4 files). Criteria: no conflict, no requested changes, security path denylist clean, design-doc gate clean, security checklist all-NO, no reviewer-lane findings, readiness signal fresh for this head SHA, declared category matches the diff. Category: adds a read-only hint to the missing-agent refusal when a linked-worktree gateway is refused the shared agent home; the guard itself is unchanged, and two tests cover the hint and the no-hint case.
bolichen97
left a comment
There was a problem hiding this comment.
Read the full diff. Fixes #35440. missing_agent_reason now appends one sentence when the shared-home guard is why a definition was never written. It fires only when this gateway runs from a linked git worktree, the shared home holds no kirocrew.json, and _decline_shared_agent_home(audit=False) declines it. The sentence names the shared home and says to run from a main clone or a regular install. That refusal already exists on main; this only explains it. The hint is read-only (no audit event, no warning), and any error building it is caught, so it never gates anything. A home that already holds kirocrew.json keeps the plain reason, which is tested both ways. No regex, no new refusal. LGTM.
Problem / Motivation
Goal: A gateway run from a linked git worktree on an agent home with no specs tells the user why its chats cannot start and what to do, instead of "its agent definition is missing".
Every first prompt on such a gateway fails before the model is called with
The agent "kirocrew" can't start: its agent definition is missing.That points the person at a deleted file or a disabled app. The real cause, logged only as a boot warning, is that the shared-home guard refuses to write specs from a linked worktree, and the home has none to fall back on.Why it matters
Anyone who runs a worktree gateway on a fresh home (a new machine, a container, a CI job, a test rig with its own
HOME) gets a dead install with a misleading message, and has to find the boot warning in the gateway log to learn why.Not a goal
_decline_shared_agent_homerefuses. The issue leaves that scope decision to the guard's owners; the guard is untouched.missing_agent_reason, which KAS calls.What changed (motivation → approach → change)
src/kiro_crew/agent_parts/shared_home.pydeclines the shared agent home for a checkout in a linked worktree, sokirocrew.jsonis never written; the refusal reason insrc/kiro_crew/apps/manager_lookup.py(missing_agent_reason) knows nothing about that._worktree_declined_spec_hint()insrc/kiro_crew/agent_parts/shared_home.pyreturns one sentence when this checkout is a linked worktree, the shared home holds nokirocrew.json, AND the guard declines the shared home (audit=False, so no audit event or warning). A home that already haskirocrew.jsonwas written by an install, so one agent missing from it is not the guard's doing and keeps the plain reason. It is composed ontokiro_crew.agentlike every other owner name (src/kiro_crew/agent.pyimport list).missing_agent_reasonappends that sentence to the generic reason: it names the worktree, the agent home path, and the fix (run from a main clone or a regular install). It does not suggest relocating the agent home, matching the guard's own warning, which deliberately offers no KIRO_HOME remedy. The call is wrapped so a failure only drops the hint, never the reason.Backwards compatibility
Compatible: the generic refusal text is unchanged as a prefix; a sentence is added only when the worktree guard is the cause. No contract, key or validator changes.
Removes nothing: the change only appends text to an error message.
Tests
test/test_kas_missing_app_agent.py::test_a_worktree_gateway_refused_the_shared_home_says_so: a linked-worktree checkout whose agents dir is the shared ambient one, with no spec, refuses with the generic reason followed by the worktree sentence, the agents dir path and the fix.test/test_kas_missing_app_agent.py::test_a_worktree_gateway_with_specs_on_the_shared_home_keeps_the_plain_reason: the same worktree gateway on a shared home that already holdskirocrew.jsonkeeps the exact generic reason, with no hint.test_agent_no_app_declares_gets_the_generic_reasonstill pins the exact generic text when the guard is not the cause (the suite's private agents dir).Proof: PROVEN test/test_kas_missing_app_agent.py::test_a_worktree_gateway_refused_the_shared_home_says_so (head 93e990f)
Local: 250 passed across
test/test_kas_missing_app_agent.py,test/test_agent_home_isolation.py,test/test_agent_parts.py,test/test_agent_refactor_contracts.py,test/test_flake_pattern_ratchet.py; black, isort, flake8, mypy and the comment-history gate clean on the touched files.Manual verification
N/A — unit coverage sufficient: the test drives the real KAS
session_extraspath to the refusal with the real guard; only the checkout location and the ambient agents dir are pinned.Related Issues
Fixes #35440
Sibling sweep
Swept: git grep -n "agent definition is missing" -- src/
Sibling: src/kiro_crew/apps/manager_lookup.py -- changed here
Sibling: src/kiro_crew/acp/harness/kas.py -- not affected -- fallback used only when missing_agent_reason itself raises
Pattern harvest
Not generalizable: a single refusal message that lacked the cause the shared-home guard already knows.
Checklist
Contribution License Agreement
Contributed under the project's Apache-2.0 license.