Repository navigation
fix(memory): upgrade pre-identity member stores and restore cron tools - #12103
Conversation
|
Intent: Make Crew Members created on 0.7.0 usable again after the one-store memory refactor by upgrading their stores and identities in place at start, keeping every lesson; and fix the four defects the same smoke test surfaced (pooled cron tools 403, |
First Principles Review (Fable 5) — 🟡 CONCERNSPremise-level review of First-Principles-Verdict: CONCERNS
Not justified as shipped
What this change shipsInventory (10 items) — 9 justifiedIntent: FIX — a crew member created on 0.7.0 (and cron tooling generally) works again after upgrading past #11780, without data loss.
More than 10 differences exist; the import-cycle fix (artifact cap moved to the [FIRST-PRINCIPLES-REVIEWED] e9b7483 |
Design Review (Fable 5) — ✅ PASSDesign-level review of Design-Verdict: PASS Verify the control-plane spawn verdict on Windows and pipx/ [DESIGN-REVIEWED] e9b7483 |
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 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: |
Opus 4.8 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: |
4b1a01d to
9ff94f1
Compare
The gate is no longer the name. At spawn, |
Added |
Taken the clearing condition the finding names: a ratchet test ( |
The set is the same set and must stay so; a ratchet test now pins the two equal ( |
9ff94f1 to
28afba7
Compare
28afba7 to
8eb6018
Compare
Every nonempty owner label the old build left behind must now equal the one alias bound today: |
The fallback now requires POSITIVE CLI provenance: |
The spawn site now awaits |
|
span=0e21ddd67f91 — the global Python-env scrub can break third-party backends: fixed by scoping the strip to where the fence applies. Correct, and it is the mirror of a defect I had already found on the previous head from the other side. The whole-namespace strip exists only to make the reserved-name token fence costless. A third-party backend is never handed a token, so scrubbing its environment bought zero security and changed its behaviour for nothing — and
Verified in the parent rather than taken on report: |
|
span=13e93e1f8df2 — the better alternative of unpooling the control planes was never considered in the description: fixed. Fair: the description justified the fence in detail without ever stating why the alternative that removes the need for it was not taken. The description now weighs it, with the cost named. Unpooling The unwrap exemption the item offers as the other clearing path is rejected on the same arithmetic: leaving these two servers unwrapped has the same per-session process cost, which is what the pooled fence exists to avoid. |
|
span=191fffafdfcb — the picker now also hides a refused pre-identity store, leaving the remedy only in The observation is accurate, but it describes a narrower population than it appears to, and the alternative is worse on the path it would change. A pre-identity store is not normally refused: the whole point of this change is that one bound to exactly one agent is repaired automatically at the next process start, before any picker render. What stays refused is the genuinely ambiguous set — zero or two bound agents, an identity already present, a manifest naming another owner, a missing database — where the correct action differs per case and cannot be inferred. Against that, the behaviour being replaced was not discoverability but a row that returned 503 on every click, with no indication of why or what to do. A "needs repair" affordance that carries the reason and the remedy would be better than both, but it is new dashboard surface — a row state, its copy, and its per-reason remedy text — and adding it here would widen a change that has already taken nine review rounds on one span, in a subsystem where every earlier widening produced a real defect. Recorded as a deliberate scope decision and a worthwhile follow-up, not an oversight. |
|
span=0e21ddd67f91 — per-user site-packages can shadow Correct, and it survived two earlier rounds on this span because the earlier fix addressed the wrong half of the mechanism. Stripping The fence now inspects per-user site-packages as a second root alongside the fixed local one, with the same test it already applies: the root shadows when it holds an importable The obvious remedy was rejected because it is actively wrong here. Setting Reading the root is sound because the spawn is already pinned by realpath to the managed spec's own launcher, so the child runs this install's interpreter — the same one the gateway reads Verified in the parent: 282 scoped tests pass; black (pinned 26.3.1), isort, flake8, mypy |
|
span=0e21ddd67f91 — per-user site-packages runs startup hooks that attestation cannot see: fixed by removing the surface, not inspecting it. Correct, and it defeats the previous round's fix on its own terms. A An accepted control plane is now launched with That combination is why this is a closure rather than another instance patch: for every install where user-site could carry a hostile hook, the directory is gone from the child's path entirely, and the only install that keeps it is the one whose user-site content the fence has already matched against this process's own package. |
|
span=fd987581e1b2 — a stale configuration can permanently strand a legacy store identity: fixed, and it was reachable from this upgrade's own write order. Real, and worse than "stale config": the upgrade publishes the MEMBER's identity before the STORE record's, so an interruption between the two leaves the member holding an id the store lacks — and three separate checks then refused that shape forever. The candidate scan refused on All three now turn on agreement rather than presence. The bound member's own id resumes; any other holder is still a conflict and still refuses; a damaged non-string disagrees and still refuses. Two tests pin both directions, and on the previous code the resume test fails with |
|
span=5ccf98a58a41 — Correct. The scan is global and the migration calls it per store, so a single unreadable record cost every other store its repair, each logging only a generic line with the real cause buried in a traceback. That is the failure this upgrade exists to end. Allocation now takes Verified rather than assumed: the migration loop already catches per store, so boot was never at risk — the cost was lost repairs, not a crash. On the previous code the new test fails with |
|
span=037553bb3c6e — the Accurate, and the asymmetry is the reason it is worth stating: only control planes lose the pair to the namespace strip, yet the re-apply is unconditional. It is unconditional deliberately — scoping it to control planes would make a third-party backend's stdio encoding depend on whether the strip had touched it, which is a worse contract than simply pinning UTF-8 for every pooled child, and it matches what The description now names it as a consequence of the fence rather than a fix of its own, together with why it is applied after the verdict. |
|
span=6fe3e449cd8c — the black-baseline removals are reformat mechanics, not one of the declared fixes: fixed in the description. Correct, and they are not optional: the two files this change touches are listed in The description now says so explicitly and separates it from the six fixes rather than leaving a reader to infer that a seventh change was smuggled in. |
UX Review (Fable 5) — ⏭️ skippedRevision |
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 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: |
Member memory stores created on 0.7.0 carry no member identity: the config record has an empty owner_member_id and the agent has no member_id, so after the one-SQLite-store refactor every such member fails with "member identity is missing or ambiguous" and the product offers no repair (provision_memory is refused, the Initialize button is gone). Add a one-shot start-of-process upgrade that, for a V2 store bound to exactly one agent, completes the database's identity tables and rows in place and then publishes member_id / owner_member_id to the config, keeping every existing lesson. Ambiguous or damaged stores are left alone with one warning and a doctor line that names the remedy. Fix the four defects the same smoke test surfaced: - gatewayd spawns pooled backends from its own environment, so the per-session token never reached kirocrew-cron and every cron tool got 403 once the gateway required X-Session-Token. Forward the token in the caller block to Kiro Crew's own control planes only. - kirocrew chat with no gateway lost its cron tools; a refused dial from a process-local identity now falls back to the direct host store. - artifacts imported hooks at module scope, closing an import cycle that broke any process reaching members before validation. - kirocrew token reported a 403 as "could not reach gateway", hiding the provenance reason the gateway returned. Omit a deleted member's retained V2 store from the memory picker, since no route can read it.
Problem / Motivation
A crew member created on 0.7.0 stops working after upgrading to a build with the one-SQLite-store member memory (#11780). Picking the member in chat fails with
memory_unavailable, its DM thread does not open, and switching an older session to it returns 503member_binding_unavailable.kirocrew doctorprints "member identity is missing or ambiguous" and nothing else. There is no way to repair it:provision_memoryis refused (400), rebinding is refused (409), and the old Initialize button is gone. The only way out is to delete the member and lose its memory.The same upgrade smoke test found four more defects:
mcp_gateway.enabledon, everykirocrew-cronMCP tool returns 403member_session_unverified.kirocrew chatwith no gateway running lost all cron tools; they used to write the local store.kiro_crew.validationwas imported raisedImportError(circular import throughartifacts->hooks->webhooks->validation->artifacts).kirocrew tokenreported a 403 as "Could not reach gateway", hiding the reason the gateway returned.Deleting a member also left its retained store in the dashboard memory picker, where every click was a 503, and a hand-edited non-string identity in
config.jsonmade the picker raise on hashing it.Why it matters
Every internal toolbox 0.7.0.x install that created a crew member breaks on the next upgrade, with data loss as the only remedy. The cron 403 turns off scheduling for anyone using the pooled MCP gateway. The
kirocrew chatregression removes a working feature for users who never run a gateway.What changed (motivation → approach → change)
repair_legacy_member_storesmemory_stores.py,cli.py(prologue),slack/gateway.py(memory worker),cli_doctor.pymcp_gateway/gatewayd.py,mcp_caller.py,mcp_core.pykirocrew chatlost cron toolsmcp_core.py,mcp_cron.pyconstantsleaf, sovalidationno longer importsartifactsconstants.py,validation.py,artifacts.pykirocrew tokenhides the 403 reasoncli_server.pydashboard/handlers/memory_admin.pymemory_stores.pyA 0.7.0 store record has an empty
owner_member_idand its agent has nomember_id; the new resolvers refuse it outright, and nothing later can publish the identity. So the upgrade runs once at the start of every process, before any member is resolved. For a V2 store bound to exactly one agent it completes the database identity tables and rows in place (database first, then config, so a crash resumes instead of allocating a second id), publishesmember_id/owner_member_id, and keeps every existing lesson. A store bound to zero or two agents, already carrying an identity, naming another owner, or missing its database is left alone with one warning;doctornames the store, the reason and the remedy; a repairable store is reported as pending through its bound member and is not an issue, so it does not fail the command. The gateway is exempt from the CLI prologue because its boot path admits no new work; it runs the same repair in its post-readiness memory worker instead.doctorand themcp-*servers are exempt too (read-only triage; children of a gateway that already ran it).gatewayd spawns pooled backends from its own environment, so the per-session
KIROCREW_STUB_SESSION_TOKENnever reachedkirocrew-cron; the gateway now requiresX-Session-Token, so every call failed. gatewayd now puts the token in the per-call caller block, but only for a backend it decided at spawn (off the event loop) is Kiro Crew's own control plane: the name is inCONTROL_PLANE_BACKENDS, the exec'd command and args match the managed spec's invocation, the child's environment carries no non-emptyPYTHON*variable, and the one remaining fixed root (its CWD under-m, else the launcher's directory) holds nokiro_crewother than this process's package. ThePYTHON*namespace is rejected as a whole rather than by a list of known variables: entries add import roots, run hooks or relocate user-site, so a prefix rule fails closed when a later Python adds one. gatewayd's own resolver removes that namespace from the inherited environment, so a value present at the verdict is a hand-declared overlay. An accepted control plane is then launched withPYTHONSAFEPATHas defense in depth; the verdict never depends on it. Two ride-alongs the table does not cover, both consequences of the fence rather than fixes of their own: every pooled backend gets Kiro Crew's ownPYTHONUTF8/PYTHONIOENCODINGre-applied after the verdict, because the namespace strip that serves the fence would otherwise take that pinning from a control plane and leave a pooled interpreter building stdio from a Windows ANSI codepage; and.github/black-baseline.txtloses the two files this change reformats, which is reformat mechanics the black gate requires, not a seventh fix.mcp_core._session_token_headerreads it from the caller before the environment. A third-party backend, or a project checkout shadowingkiro_crew, never sees it.The alternative of not pooling the control planes at all was weighed and rejected. Spawning
kirocrew-coreandkirocrew-cronper session would remove the token hand-over entirely, because each child could carry its own session's token in its environment at spawn. The cost is paid on every session: two extra Python interpreters per concurrent session, each importing thekiro_crewpackage and its MCP stack, against two processes shared across all of them. That is cold-start latency on the first tool call of every new session and a per-session memory floor that scales with concurrency — on a host already running one agent process per session. Pooling is also what themcp_gatewayrewrite exists to provide, so unpooling these two servers would carve a permanent exception into it. The fence keeps the shared processes and pays instead with one spawn-time verdict, which is cheaper and does not scale with session count. The unwrap exemption (leaving these two servers unwrapped, as the rewriter already does for an env-declaring opted-in server when forwarding is off) has the same per-session cost and is therefore rejected for the same reason.mcp_core._sendmarks the one failure where nothing reached a gateway asrefused;mcp_cronuses that, together with a process-local identity, to fall back to the direct host store, which is whatkirocrew chatalways had. Specs updated:docs/architecture/mcp.md,docs/system-specs/modules/cli.md,config.md,memory-skills-hooks.md..github/black-baseline.txtdrops the two files this change reformats.Backwards compatibility
Compatible: the upgrade only touches V2 store records with an empty
owner_member_idbound to exactly one agent, and it adds identity rows; it never deletes data, never creates a database, and refuses anything ambiguous. Token forwarding is additive and limited to Kiro Crew's own backends. The local fallback restores pre-#11780 behavior for a case that had none.Tests
test/test_member_memory_upgrade.py(new, 18 tests): a 0.7.0 store resolves after the upgrade and its lessons survive; a second run changes nothing; an interrupted upgrade resumes with the identity already in the database; slug collisions get a suffix; zero or two bound agents, an existing identity, another owner's manifest, another store's database identity, and a missing database are all refused with one warning;doctorreports refused stores with a remedy and repairable ones as pending; the hook runs in the CLI prologue and in the gateway memory worker.test/test_mcp_gateway_stub_session_token.py,test/test_private_cron_proxy.py,test/test_mcp_caller.py: the token reacheskirocrew-cronthrough the caller block, never a third-party backend;_session_token_headerprefers the caller's token;refusedtriggers the local fallback only for a process-local identity.test/test_agent_import_hoist.py:membersandartifactsimport in either order in a fresh interpreter, andvalidationnever importsartifacts.test/test_cli_server_more_coverage.py:kirocrew tokenprints the gateway's error body on HTTP errors.test/test_member_memory_ownership.py: the picker omits a V2 store whose owner no longer exists.Manual verification
Reproduced the upgrade failure on macOS with a 0.7.0-shaped store (
member_id='',owner_member_id=''):require_member_memory_storeraisedUnknownMemoryStore: member identity is missing or ambiguous. After the upgrade the same store resolves,memory_recallreturnspolicy_revision=member-v2, and the pre-existing lesson is returned. The token and fallback fixes were verified on a scratch copy of gatewayd against a pooledkirocrew-cronbackend.Related Issues
no linked issue: found by the post-merge smoke test of #11780; the reports it would have produced (#11471, #11569) were closed with the upgrade caveat stated in their closing comments.
Pattern harvest
Rule candidate: review-prompt
Pattern: a refactor that adds a required identity field to a persisted record must ship the one-shot backfill for records written before the field existed, plus a test that loads a pre-refactor fixture.
Checklist
feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)