Skip to content

cli: agent update --memory-store help offers a rebind to 'default' that the handler refuses, stale after the carve-out was removed #27770

Closed

Description

@jongaffen

Existing issues

  • I searched open issues and this is not already reported.

KiroCrew version

0.11.0

Release channel

Stable

How is it installed?

Desktop app

Platform

Windows

Where

kirocrew agent update --help, the --memory-store option, text at src/kiro_crew/cli_parser_agent.py:815-820 on main. The same exception is described in the comment at src/kiro_crew/dashboard/agent_admin/crew_update.py:454-459.

What is wrong

The help promises a rebind that the handler refuses (cli_parser_agent.py:815-820).

agent_update.add_argument(
    "--memory-store",
    help=(
        "Existing memory store identity (cannot be changed, except to 'default' "
        "from a store name the config refuses)"
    ),
)

The update handler grants no exception. _handle_agent refuses every value that differs from the stored binding (src/kiro_crew/cli_commands_agent.py:330-333).

prior_memory_store = agent.memory_store
if args.memory_store is not None and args.memory_store != prior_memory_store:
    print("Error: a member's memory cannot be rebound or shared", file=sys.stderr)
    sys.exit(1)

The dashboard PUT does the same at crew_update.py:460-467 (409 member_memory_immutable), directly under a comment that still describes the exception ("with one exception: a V1 binding whose name no resolver composes (unusable_legacy_binding) may move to the global store").

Reproduction on the installed 0.11.0 backend, with a scratch KIROCREW_HOME.

  1. Seed a member m1 whose V1 binding is "bad store!", a name the shape rule refuses. memory_stores.unusable_legacy_binding(cfg, "m1") returns does not match ^[a-z0-9](?:[a-z0-9-]{0,78}[a-z0-9])?\Z for it, so this is exactly the help's "store name the config refuses".
  2. Run kirocrew agent update m1 --memory-store default.

The help says the binding moves to default and the command exits 0. In 3 of 3 runs (2026-11-01, 14:01Z to 14:03Z, fresh scratch home each run) it printed this error instead.

Error: a member's memory cannot be rebound or shared

Exit code 1, and memory_store still reads "bad store!" afterwards. kirocrew agent update --help through the installed command printed the exception clause in 3 of 3 runs (14:12Z).

Logs: CLI stderr and --help output above are the only surfaces. The handler writes nothing to kirocrew logs on this path. No portable reproduction is needed because the defect is platform-neutral text versus a platform-neutral branch.

Regression window: PR #11736 added the help clause together with a handler carve-out. Commit bc0d2b0cfc (2026-09-18, "refactor(memory): simplify member memory to one SQLite store", no commit body) removed the carve-out and left the help and the dashboard comment. The mismatch exists on main at 88832d9f and in 0.11.0.

Evidence is a harness on the installed backend (the unusable binding was seeded by editing a scratch config, and how a real member reaches that state was not reproduced) plus the live --help output. Confidence: source mechanism cited and history-confirmed, reachability harness-reached, packaged fix status open.

Suggested correction

Recommended fix: drop the exception from the help text so it reads Existing memory store identity (cannot be changed), and rewrite the crew_update.py:454-459 comment to state the rule the code enforces (a binding is immutable in both directions, no exception). This matches the handler, the dashboard check and docs/guides/install.md:109 ("A member's memory store is chosen when the member is created and cannot be rebound afterwards"). #24022 reached the same rule for install.md, and its closing PR #24028 lists giving an existing member V2 memory as out of scope ("That is a product decision (#12263, #12265)"). Tradeoff: a member left on an unusable legacy name still has no supported repair path, which this text change does not settle.

Declared behavior change: help and comment text only. No code path changes.

Alternatives: restoring the carve-out in both _handle_agent and crew_update.py came second, because it reverses the immutability rule bc0d2b0cfc and install.md:109 state, and #24028 already treats that as a product decision. Deleting unusable_legacy_binding (src/kiro_crew/memory_stores.py:754, no production caller on main) also came second, because test/test_memory_stores.py:271 pins it as the predicate a repair path would use, so it belongs with the repair-path decision.

Sibling cases

Site Status
cli_parser_agent.py:815-820 agent update --memory-store help affected (fixed by the recommended change)
crew_update.py:454-459 comment above the dashboard 409 affected (fixed by the recommended change)
cli_commands_agent.py:331-333 CLI refusal, pinned by test/test_member_memory_ownership.py:669 must-not-change
crew_update.py:460-467 dashboard 409 member_memory_immutable must-not-change
agent create --memory-store (cli_parser_agent.py:795) unaffected (create-time choice)
memory_stores.unusable_legacy_binding and its tests unaffected (repair-path decision, out of scope)

Acceptance criteria

  • kirocrew agent update --help no longer offers an exception the handler refuses. Fails today.
  • crew_update.py describes the rule the PUT handler enforces. Fails today.
  • Existing behaviour unchanged: agent update <m> --memory-store <other> still exits 1 with a member's memory cannot be rebound or shared, and the dashboard PUT still answers 409 member_memory_immutable.
  • Out of scope: whether a member on an unusable legacy store name gets a repair path.

Environment: Windows 11 25H2, build 26200.9818, 64-bit. The help text and both handlers carry no platform gate, so every platform has the same mismatch. Probes ran on the installed backend's Python 3.12.14. Frequency: deterministic, 3 of 3.

Provenance: found while reading the member-memory update paths, then run against the installed 0.11.0 backend through kiro_crew.cli.main() and the installed kirocrew command. The seeded binding is a supplied condition, not a state observed on a real member.

Related

🤖 AI-assisted report 🤖

Activity

  1. added
    tier:T1Bug: behaviour does not match intent; fix keeps the design
    on Nov 2, 2026
  2. KiroCrewCaptain commented on Nov 2, 2026

    @KiroCrewCaptain
    Collaborator

    Thanks for the report. This issue has been triaged by Crew Captain and will be assigned to a maintainer, who will follow up here.

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    channel: stableReported from a stable releasetier:T1Bug: behaviour does not match intent; fix keeps the design

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions