Skip to content

fix(agent): say why a worktree gateway has no agent definition - #36123

Merged
KiroCrewCaptain merged 2 commits into
mainfrom
fix/35440-worktree-empty-agent-home
Nov 13, 2026
Merged

KiroCrewCaptain merged 2 commits into
mainfrom
fix/35440-worktree-empty-agent-home

Conversation

@JLargent42

@JLargent42 JLargent42 commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

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

  • Changing what the worktree arm of _decline_shared_agent_home refuses. The issue leaves that scope decision to the guard's owners; the guard is untouched.
  • The non-default-home arm's refusal message.
  • Other backends' wording; the message is built once in missing_agent_reason, which KAS calls.

What changed (motivation → approach → change)

  • Symptom: generic "agent definition is missing" on every chat.
  • Cause: src/kiro_crew/agent_parts/shared_home.py declines the shared agent home for a checkout in a linked worktree, so kirocrew.json is never written; the refusal reason in src/kiro_crew/apps/manager_lookup.py (missing_agent_reason) knows nothing about that.
  • Change: a read-only helper _worktree_declined_spec_hint() in src/kiro_crew/agent_parts/shared_home.py returns one sentence when this checkout is a linked worktree, the shared home holds no kirocrew.json, AND the guard declines the shared home (audit=False, so no audit event or warning). A home that already has kirocrew.json was written by an install, so one agent missing from it is not the guard's doing and keeps the plain reason. It is composed onto kiro_crew.agent like every other owner name (src/kiro_crew/agent.py import list). missing_agent_reason appends 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 holds kirocrew.json keeps the exact generic reason, with no hint.
  • Existing test_agent_no_app_declares_gets_the_generic_reason still 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_extras path 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

  • At most two commits (one is the norm), with a Conventional Commits title
  • 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

Contribution License Agreement

Contributed under the project's Apache-2.0 license.

@JLargent42
JLargent42 requested review from a team and KiroCrewCaptain as code owners November 12, 2026 21:50
@JLargent42 JLargent42 self-assigned this Nov 12, 2026
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 12, 2026
@github-actions

github-actions Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision fb7696fbb0a518bde626e80f7d7d364194051b81 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of fb7696fbb0a518bde626e80f7d7d364194051b81 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

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

  • apps/manager_lookup.py now imports kiro_crew.agent lazily just to read one guard helper. Importing straight from kiro_crew.agent_parts.shared_home would depend only on the module that owns the helper, not on the whole agent facade.

[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 .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of fb7696fbb0a518bde626e80f7d7d364194051b81 — 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 does not.

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: ## Not a goal says so, and the comment at shared_home.py:484 gives the owners' scoping reason.

What this change ships

Inventory (3 items) — 3 justified

Intent: 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).

  1. On such a gateway, the "agent definition is missing" refusal now adds a sentence naming the worktree, the agent home path and the fix — justified
  2. New read-only helper _worktree_declined_spec_hint, re-exported through kiro_crew.agent and used only by missing_agent_reason — justified
  3. If building the hint fails, the hint is dropped and the plain reason stays — justified

[FIRST-PRINCIPLES-REVIEWED] fb7696f

Description read

[DESCRIPTION-READ] 84dbd8be1ff532bb389583532cbbafb531f984f7c5322f07ca253b30ec3b4e31

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] fb7696f

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

False positive or not applicable? A repository writer can comment:
/ai-review override fable fb7696fbb0a518bde626e80f7d7d364194051b81 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of fb7696fbb0a518bde626e80f7d7d364194051b81 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] fb7696f

False positive or not applicable? A repository writer can comment:
/ai-review override gpt fb7696fbb0a518bde626e80f7d7d364194051b81 false-positive: <reason, 20 to 500 characters>

@JLargent42

Copy link
Copy Markdown
Contributor Author

Review dispositions for 55e61bf38437466f826c6209b905e8ed20eea687, addressed in 93e990fa7da8d895a93d561790ca61f1678edffb:

  • Opus 5.5 BLOCKING (src/kiro_crew/apps/manager_lookup.py:360, hint on a home that already has specs): fixed. _worktree_declined_spec_hint() in src/kiro_crew/agent_parts/shared_home.py now returns nothing when kiro_agents_dir_path() / AGENT_FILENAME exists, so a missing user agent or a custom agent.default_agent on a populated shared home keeps the plain reason. That uses the second of the two remedies the finding suggested, which is also the Design Review note. New test: test_a_worktree_gateway_with_specs_on_the_shared_home_keeps_the_plain_reason.
  • First Principles note (remedy reads as the KIRO_HOME relocation): fixed. I dropped "or start it with a home that already has the agent definitions". The hint now says only "Run it from a main clone or a regular install."
  • First Principles note (worktree arm still declines on an empty home): deferred, as the PR's Not a goal states. A gateway run from a linked git worktree with an empty agent home fails every chat with "agent definition is missing" #35440 leaves changing the guard's scope to its owners.
  • Build Wheel / Build Desktop TS2304 GitFork: inherited from main, not this diff. website/src/pages/chat/AssistantMessage.tsx on main uses GitFork without importing it. fix(chat): import the GitFork icon the reply menu uses #36124 fixes that. This PR touches nothing under website/.

@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 Nov 12, 2026
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.
@JLargent42
JLargent42 force-pushed the fix/35440-worktree-empty-agent-home branch from 93e990f to fb7696f Compare November 12, 2026 22:58
@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 labels Nov 12, 2026
@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: Approve

Why: 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 fb7696fbb0 · 81 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@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 Nov 12, 2026
@JLargent42

Copy link
Copy Markdown
Contributor Author

Disposition for the Design Review note on fb7696fbb0a518bde626e80f7d7d364194051b81 (importing kiro_crew.agent lazily in src/kiro_crew/apps/manager_lookup.py): kept as is, by rule. The package docstring of src/kiro_crew/agent_parts/__init__.py says nothing but kiro_crew.agent imports an agent_parts module. The owners' functions run on kiro_crew.agent's globals, so the facade is both the import path and the patch target. A direct import from kiro_crew.agent_parts.shared_home would break that contract and get around the patch seam that test/test_agent_parts.py sweeps.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention labels Nov 13, 2026
@KiroCrewCaptain
KiroCrewCaptain enabled auto-merge (squash) November 13, 2026 05:05

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

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 bolichen97 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.

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.

@KiroCrewCaptain
KiroCrewCaptain merged commit 500b9f9 into main Nov 13, 2026
136 of 148 checks passed
@KiroCrewCaptain
KiroCrewCaptain deleted the fix/35440-worktree-empty-agent-home branch November 13, 2026 05:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

readiness: passed Eligible automated validation passed for the current revision

Projects

None yet

Development

Successfully merging this pull request may close these issues.

A gateway run from a linked git worktree with an empty agent home fails every chat with "agent definition is missing"

3 participants