Repository navigation
docs: reverse recipe for transcripts in an adopted kiro home - #20650
Conversation
First Principles Review (Opus 5.5) — ⏭️ skippedRevision |
UX Review (Opus 5.5) — ⏭️ skippedRevision |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Check that a gateway start really calls [DESIGN-REVIEWED] 39a7360 Description read[DESCRIPTION-READ] cf20b049b7e826ec661731a811f3da3dd26d583039796717efc9e76a295caffc 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 |
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: |
0b4455f to
f2cab20
Compare
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: |
|
span=f788dd5dce8a fixed: f2cab20 — intro now names the three real triggers (pod runtime, container supervisor, hand-set |
|
span=6deec7106582 fixed: f2cab20 — batch script now has an explicit branch for the journal-only partial state: when |
|
span=6072d704c759 fixed: f2cab20 — |
|
span=251f8287411f fixed: f2cab20 — (1) |
f2cab20 to
f203547
Compare
|
span=advisory fixed: f203547 — guides/README.md index row now says "after reverting KIRO_HOME to the host home", which correctly identifies the trigger. |
f203547 to
a905709
Compare
|
span=748fad00cc61 fixed: a905709 — guide now opens with a prominent warning that the move must happen before any gateway restart under the reverted KIRO_HOME, and names the SessionMap prune behavior that makes early restart permanent. |
|
span=3aefcee88471 fixed: a905709 — the "After the move" section now has per-trigger opt-out instructions: hand-set KIRO_HOME removes the shell-profile line; pod runtime and container supervisor own their KIRO_HOME assignment and it ends when the process exits. |
|
span=251f8287411f fixed: a905709 — the "Only the journal exists" branch in step 1 now runs cmp on the host .jsonl before proceeding; if the journal differs, it deletes the host copy and restarts from step 2. |
|
span=daf6065ff15b fixed: a905709 — step 1 "both exist, byte-equal" case now explicitly says "perform step 4 (flush) and then step 5 (retire)"; the batch script already does sync before rm in this path. |
a905709 to
c4f3032
Compare
|
span=daf6065ff15b fixed: c4f3032 — the batch script now canonicalizes both ADOPTED and HOST with realpath/readlink and exits 1 when they resolve to the same path, refusing to run and delete the only resumable copy. |
|
span=advisory rebutted: pod/runtime.py:1300 sets KIRO_HOME in the env dict passed to the subprocess (not os.environ), so it scopes to that process and exits with it; export_kiro_home writes os.environ for the container process and also exits with it. The bullets match. |
c4f3032 to
e56bce2
Compare
|
span=60d663f26030 fixed: e56bce2 — the batch script section has been removed entirely; only the manual steps and the failure-mode matrix remain. |
|
span=736e99341ce9 fixed: e56bce2 — the guide now covers only the hand-set KIRO_HOME case; pod/container triggers are removed from the scenario description because in both cases KIRO_HOME is process-scoped and exits with the process. |
|
span=9464b6c7effe fixed: e56bce2 — the phrase 'with the same durability ordering the forward direction uses' has been removed; the guide says 'journal-first durability ordering' without claiming parity with a forward primitive that is not on main. |
|
span=a166636eef1e fixed: e56bce2 — the Edge cases table has been removed; the collision branches are stated once in step 1 of the recipe. |
e56bce2 to
f5a85bb
Compare
|
span=d939b16a2ff9 fixed: f5a85bb — added "If mappings were already pruned" section explaining that resume cannot be recovered once SessionMap.get prunes the entry, but transcript text is still readable. The two-starting-states structure handles both the ideal and the late-reader case. |
|
span=539af9129b29 fixed: f5a85bb — guide is now structured around two starting states: KIRO_HOME still set (stop gateway before reverting) vs already reverted (check session_map.json first). The ordering now matches the real operator journey. |
|
span=6ae0d36246ad fixed: f5a85bb — removed the kirocrew doctor hint; guide now tells the operator to find the old path in their shell profile (~/.bashrc, ~/.zshrc, etc.). |
|
span=251f8287411f fixed: f5a85bb — removed the kirocrew doctor pointer; the guide now directs the operator to their shell profile for the old KIRO_HOME value. |
f5a85bb to
96384e6
Compare
|
span=8a4e8ef9630c fixed: 96384e6 — all occurrences of 'kirocrew start' replaced with 'kirocrew gateway', the correct command to start the gateway (verified against cli.py). |
|
span=fdb1f8376f6b fixed: 96384e6 — pruning description now distinguishes regular sessions (entry removed) from sessions with channel binding/durable/privacy flag (entry kept, sid moved to discarded_sid). Cites _keeps_entry and _stash_and_clear_sid. |
|
span=daf6065ff15b fixed: 96384e6 — divergent residue section no longer recommends deleting the shorter file; it now says to NOT delete either copy without verifying one is a strict byte-prefix of the other. |
|
span=251f8287411f fixed: 96384e6 — (1) kirocrew start replaced with kirocrew gateway; (2) pruning description corrected per _keeps_entry/_stash_and_clear_sid. |
|
span=advisory rebutted: a gateway start does call session_map.prune() — confirmed in src/kiro_crew/session_pool.py:313, called from _start_bg_and_pool() which runs on pool start at gateway boot. The guide correctly includes "a gateway start" as a prune trigger. |
96384e6 to
3f1278d
Compare
3f1278d to
39a7360
Compare
|
span=advisory rebutted: session_pool.py:313 calls self._owner._session_map.prune() in _start_bg_and_pool(), which runs at pool start during gateway boot. A gateway start does call prune(). The "If mappings were already pruned" section is correct. |
bolichen97
left a comment
There was a problem hiding this comment.
Readiness sweep review: read the full diff (merge-base) and the PR thread. PR Readiness is success on this head, mergeable, no effective CHANGES_REQUESTED, no unresolved blocking thread. Docs-only guide; spot-checked its code claims against the source. No regression to normal use found.
Problem / Motivation
Goal: Document the manual steps and durability rules for moving session transcripts back from a hand-set
KIRO_HOMEpath to the host~/.kiro/sessions/cli/.When an operator sets
KIRO_HOME=<path>in their shell profile, kiro-cli writes sessions to<path>/sessions/cli/. Unsetting the variable re-points kiro-cli at~/.kiro/sessions/cli/, leaving already-written transcripts inaccessible until they are moved back. No documented recipe existed.Why it matters
An operator who accumulated chat history with a hand-set
KIRO_HOME, then unset it, loses resume access to every session written during that period. Without a recipe, recovery requires guesswork about file ordering and can silently lose a transcript. If the operator has already tried to resume (triggeringSessionMap.get's lazy prune), the mapping is gone and resume cannot be restored; the guide is honest about that boundary.Not a goal
doctorfix-it command; the forward move's journaled primitive is not yet on main (PR fix(agent): a non-default KIROCREW_HOME never rewrites the shared ~/.kiro/agents specs #9797 was closed), so there is no primitive to reuse unchanged.KIRO_HOME-governed paths.What changed (motivation → approach → change)
The guide is restructured around two starting states: KIRO_HOME still set (stop gateway first, move files, then revert) vs already reverted (stop gateway, check if session-map entries are still present, then move). Both states are covered because the operator who reads this guide has most likely already reverted. A "If mappings were already pruned" section is honest that resume cannot be recovered once
SessionMap.gethas pruned the entries, but the transcript text is still readable. The doctor hint for the old path was removed (nokiro sessions:line in doctor output); the guide tells the operator to find<path>in their shell profile instead. The batch script and the edge-case table were removed; the recipe and the failure-mode matrix are the only deliverables.docs/guides/README.mdgets one index row.Intended? / Repro
Intended? Yes — forward-only today.
src/kiro_crew/config/paths.py:kiro_sessions_dir()resolves tokiro_home() / "sessions" / "cli"andkiro_home()honors$KIRO_HOME. Unsetting leaves already-written files in place — by design.Repro: Export
KIRO_HOME=/tmp/test-kiro. Open chat sessions — transcripts land in/tmp/test-kiro/sessions/cli/. UnsetKIRO_HOME. kiro-cli now reads~/.kiro/sessions/cli/; sessions from/tmp/test-kiro/no longer appear.Backwards compatibility
Compatible: adds a new guide file and one index row; removes nothing, changes no existing file.
Removes nothing: adds docs/guides/transcript-reverse-migration.md only, and one row to docs/guides/README.md.
Tests
N/A — documentation only; no executable code added.
Manual verification
The recipe was derived from the journal-first / state-last ordering in
src/kiro_crew/pinned_fs.py. The lazy-prune behavior was verified againstsrc/kiro_crew/session_map.py:1094-1101. The correct stop command was verified againstsrc/kiro_crew/cli.py. The doctor hint was removed after confirming nokiro sessions:string exists insrc/kiro_crew/cli_doctor.py.Screenshots / video
N/A — no user-visible UI change.
Related Issues
Closes #13114
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)