Skip to content

fix(memory): let a dead legacy binding move to V2 or default - #11736

Merged
iamwhatever merged 1 commit into
mainfrom
fix/member-memory-name-defect-rebind
Sep 18, 2026
Merged

iamwhatever merged 1 commit into
mainfrom
fix/member-memory-name-defect-rebind

Conversation

@bolichen97

Copy link
Copy Markdown
Contributor

Problem / Motivation

A Crew Member bound to a legacy V1 memory store whose name fails the 0.7 shape rule (a name that was legal before memory_stores.py existed, such as AgentForge) is dead and cannot be repaired:

  • every turn fails with memory_unavailable: invalid memory store name 'AgentForge': not lowercase
  • Members → "Initialize private memory" returns 409 member_memory_unavailable with the same text
  • PUT /api/agents/<name> with memory_store: "default" and kirocrew agent update <name> --memory-store=default both return "a member's private memory cannot be rebound or shared"

The only way out was editing config.json by hand.

Why it matters

Anyone upgrading from 0.6 with a mixed-case or underscored store name hits this on every member bound to that store (the reporter had 9 members across 3 stores). The loader's refusal to sanitize the name is right, but the two supported repairs refused the same name, so the member stayed broken in the UI with no supported exit.

What changed (motivation → approach → change)

Surface Before After
Members → Initialize private memory, PUT /api/agents/<name> provision_memory 🟥 409, prior name validated first 🟩 provisions V2
PUT /api/agents/<name> memory_store: "default" 🟥 409 private_memory_immutable 🟩 moves to Global V1
kirocrew agent update <name> --memory-store=default 🟥 exit 1 🟩 moves to Global V1
move to any other store, live V1 name, private store, owned record under a dead name 🟦 refused 🟦 refused

🟩 added · 🟨 changed · 🟥 removed · 🟦 unchanged

Both repairs validated the binding they were about to replace. The dashboard opt-in called require_member_memory_store on the prior binding before provision_member_memory, and that raises on the name. The rebind check refused every change of memory_store regardless of what the prior record was.

unusable_legacy_binding(config, member) in memory_stores.py names the one binding shape the immutability rules protect nothing on: a name memory_store_name_defect refuses, on a record with no ownership claim (owner_member == "", memory_version == 1) or no record at all. No resolver composes a path for such a name, so nothing under memory_stores/ is read, replaced or removed by leaving it.

The dashboard opt-in (dashboard/handlers/agents.py) skips the prior-binding validation when that predicate answers (provision_member_memory re-runs the private-evidence half itself and already skipped the legacy-file half for such a name). PUT /api/agents/{name} and agent update --memory-store (cli_commands.py) accept a move to default for that shape, and only to default; the move is validated as the binding it becomes before publication, so a member that still has a stale private declaration of its own gets 409 member_memory_unavailable rather than a 500 from persist_member_config. Any other destination is still private_memory_immutable, now with an error naming the defect instead of calling a V1 name private. Failed-allocation cleanup never treats the global store as a key to retire. The dead declaration stays in memory_stores verbatim, like every other reported name.

Specs (docs/system-specs/modules/config.md, memory-skills-hooks.md) and the user doc (src/kiro_crew/docs/configuration.md) record the exception; the --memory-store flag help on agent update (cli.py) names it.

Tests

test/test_memory_stores.py — TestUnusableLegacyBindingIsTheOneMovableBinding: movable for a declared unowned V1 record or no record on a malformed name, a non-string binding included; not movable for a usable name, the default store, an unknown member, or any record claiming ownership; and pinned as the exact complement of the runtime refusal (require_member_memory_store fails on the name wherever the predicate answers).

test/test_crew_memory_store_binding.py — TestADeadLegacyBindingHasAWayOut: dashboard provisioning succeeds on a dead name (declared or not) and leaves the declaration and memory_stores/ alone; the move to default succeeds and carries other edits; any other destination is 409 and names the defect; a live named V1 binding stays immutable; stale private evidence of the member is a 409 (not a 500) on both repairs; an owned record under a dead name stays refused on both. TestTheCliRepairsADeadLegacyBinding: agent update --memory-store=default moves the member; any other destination exits 1 naming the defect; stale private evidence exits 1; --provision-memory keeps working; the flag help names the permitted move.

prove.py --per-hunk: every code hunk caught. Two hunks report inconclusive because reverting them makes the tests fail at import (the new symbol's definition and one of its imports), not because a test misses them.

Manual verification

N/A — unit coverage exercises the real handler and CLI against a real per-test config; no UI change (the Members page already sends provision_memory: true).

Review note

Local lanes (gpt-5.6-sol per codex-review.yml, claude-opus-4.8 per claude-review.yml) reviewed 317ad3724 against 99dc588b9: Opus no findings; GPT one non-blocking top-level-imports finding on the in-handler require_member_memory_store import, folded into this commit as a module-level import (the only delta since that review). Full prepare-pr profile: 49/51 gates green on this head; the two scoped-test gates ran on the pre-rebase head, 40,861 backend tests passed with 3 reds that reproduce byte-for-byte on a clean origin/main worktree (a /Applications Kiro CLI shadowing PATH on the dev host), and 1 frontend timing red that passes unloaded. No open PR touches memory_stores.py; open PRs touching dashboard/handlers/agents.py or cli_commands.py (#11324, #11121, #10414, #11658, #11532) edit unrelated regions.

Related Issues

no linked issue: reported directly by an operator upgrading from 0.6 to 0.7; the same report's retire-meshclaw --force finding is a separate companion-plugin issue and is not part of this change.

Pattern harvest

Rule candidate: review-prompt
Pattern: a repair path validates the very state it exists to replace (precondition on the prior value blocks the only transition out of an invalid prior value)

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

A member bound to a V1 store whose name fails the shape rule (a name
that was legal before memory_stores.py existed, such as AgentForge)
is dead on every surface: each turn raises at
require_member_memory_store, and both repairs refused too. The
dashboard V1-to-V2 opt-in validated the prior binding before
provisioning, so it returned 409 member_memory_unavailable on the very
name it was the way out of; and rebinding to default was refused as
private_memory_immutable on both the dashboard and the CLI, although
the record claims no ownership and the name composes no path.

unusable_legacy_binding names exactly that shape: a binding whose name
memory_store_name_defect refuses, on a record with no ownership claim
or no record at all. The opt-in skips the prior-binding validation
for it (provision_member_memory re-runs the private-evidence check
itself), and PUT /api/agents/{name} plus agent update --memory-store
accept a move to default for it, and only to default. A live V1 name,
a private store, and a record claiming ownership under a dead name all
stay immutable. The dead declaration is left in memory_stores verbatim,
like every other reported name, and nothing under memory_stores/ is
read, replaced or removed.

The retire-meshclaw --force finding in the same ticket is a separate
companion-plugin issue and is not part of this change.
@bolichen97
bolichen97 requested review from a team and CrysisDeu September 18, 2026 08:11
@bolichen97
bolichen97 enabled auto-merge (squash) September 18, 2026 08:11
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 18, 2026
@github-actions

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

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

Design-Verdict: PASS

Confirm the reporter's actual store records are unowned V1 — a record claiming ownership under the dead name stays refused, so their 9 members must match the predicate.

[DESIGN-REVIEWED] 4dea9f8

@github-actions

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — ✅ PASS

Premise-level review of 4dea9f82187483c27076e68bdce9471d7b92001b — 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

No linked issue: the defect's provenance is the description's reproduction — corroborated by the base hunk's unconditional 409 — worth a maintainer's confirming glance.

What this change ships

Inventory (9 items) — 9 justified

Intent: give an operator whose member is bound to a pre-0.7 store name (refused by the shape rule, so the member fails every turn) a supported way out — this is a FIX.

  1. Dashboard "Initialize private memory" succeeds on a dead legacy name instead of 409 — justified
  2. PUT /api/agents/<name> accepts memory_store: "default" for a dead legacy binding — justified
  3. kirocrew agent update --memory-store=default moves a dead-bound member instead of exit 1 — justified
  4. Refusal of any other destination now names the store's defect, not "cannot be rebound" — justified
  5. Stale private-memory evidence yields 409 on both repairs instead of a 500 — justified
  6. A failed move no longer retires the global store during cleanup (CLI and dashboard) — justified
  7. --memory-store flag help names the one permitted move — justified
  8. New callable unusable_legacy_binding (grepped: 3 call sites across 2 modules; not a second spelling of memory_store_binding_defect, which checks name shape only) — justified
  9. Specs and user doc record the exception in the same commit — justified

Root-cause note: the cause ("a repair validates the state it replaces") is fixed at all its instances — grepped require_member_memory_store across src/; the remaining call sites are runtime/turn validation that must keep refusing, and the CLI --provision-memory path never validated (pinned by a new test). Zero unfixed siblings.

[FIRST-PRINCIPLES-REVIEWED] 4dea9f8

@github-actions

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 4dea9f82187483c27076e68bdce9471d7b92001b and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 4dea9f8

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

@github-actions

Copy link
Copy Markdown
Contributor

Opus 4.8 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 4dea9f8

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

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

@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 18, 2026
@bolichen97
bolichen97 disabled auto-merge September 18, 2026 17:33
@iamwhatever
iamwhatever enabled auto-merge (squash) September 18, 2026 21:23
@iamwhatever
iamwhatever merged commit 335f290 into main Sep 18, 2026
77 checks passed
@iamwhatever
iamwhatever deleted the fix/member-memory-name-defect-rebind branch September 18, 2026 21:24
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 18, 2026
amadsalmon pushed a commit to amadsalmon/KiroCrew that referenced this pull request Sep 22, 2026
…dev#11736)

A member bound to a V1 store whose name fails the shape rule (a name
that was legal before memory_stores.py existed, such as AgentForge)
is dead on every surface: each turn raises at
require_member_memory_store, and both repairs refused too. The
dashboard V1-to-V2 opt-in validated the prior binding before
provisioning, so it returned 409 member_memory_unavailable on the very
name it was the way out of; and rebinding to default was refused as
private_memory_immutable on both the dashboard and the CLI, although
the record claims no ownership and the name composes no path.

unusable_legacy_binding names exactly that shape: a binding whose name
memory_store_name_defect refuses, on a record with no ownership claim
or no record at all. The opt-in skips the prior-binding validation
for it (provision_member_memory re-runs the private-evidence check
itself), and PUT /api/agents/{name} plus agent update --memory-store
accept a move to default for it, and only to default. A live V1 name,
a private store, and a record claiming ownership under a dead name all
stay immutable. The dead declaration is left in memory_stores verbatim,
like every other reported name, and nothing under memory_stores/ is
read, replaced or removed.

The retire-meshclaw --force finding in the same ticket is a separate
companion-plugin issue and is not part of this change.
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.

2 participants