Skip to content

docs: reverse recipe for transcripts in an adopted kiro home - #20650

Merged
bolichen97 merged 1 commit into
mainfrom
docs/13114-transcript-reverse-recipe
Oct 15, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
docs/13114-transcript-reverse-recipe

Conversation

@CrysisDeu

@CrysisDeu CrysisDeu commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Document the manual steps and durability rules for moving session transcripts back from a hand-set KIRO_HOME path 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 (triggering SessionMap.get's lazy prune), the mapping is gone and resume cannot be restored; the guide is honest about that boundary.

Not a goal

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.get has pruned the entries, but the transcript text is still readable. The doctor hint for the old path was removed (no kiro 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.md gets one index row.

Intended? / Repro

Intended? Yes — forward-only today. src/kiro_crew/config/paths.py:kiro_sessions_dir() resolves to kiro_home() / "sessions" / "cli" and kiro_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/. Unset KIRO_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 against src/kiro_crew/session_map.py:1094-1101. The correct stop command was verified against src/kiro_crew/cli.py. The doctor hint was removed after confirming no kiro sessions: string exists in src/kiro_crew/cli_doctor.py.

Screenshots / video

N/A — no user-visible UI change.

Related Issues

Closes #13114

Checklist

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

@CrysisDeu
CrysisDeu requested review from a team and KiroCrewCaptain as code owners October 15, 2026 06:20
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 15, 2026
@github-actions

github-actions Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ⏭️ skipped

Revision 39a73602274447576d1d071d23f39ec3cc04df3a ships no reviewable capability (docs, tests or generated files only), so there is nothing to inventory. Advisory — does not block merge.

@github-actions

github-actions Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 39a73602274447576d1d071d23f39ec3cc04df3a touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Advisory — does not block merge.

@github-actions

github-actions Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Check that a gateway start really calls SessionMap.get, as the "If mappings were already pruned" section says. The "already reverted" steps depend on it.

[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 .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 Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 39a7360

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

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

@CrysisDeu
CrysisDeu force-pushed the docs/13114-transcript-reverse-recipe branch from 0b4455f to f2cab20 Compare October 15, 2026 06:27
@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 Oct 15, 2026
@github-actions

github-actions Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 39a7360

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

@CrysisDeu

Copy link
Copy Markdown
Contributor Author

span=f788dd5dce8a fixed: f2cab20 — intro now names the three real triggers (pod runtime, container supervisor, hand-set KIRO_HOME) and drops the overstated claim that a non-default KIROCREW_HOME alone causes the export.

@CrysisDeu

Copy link
Copy Markdown
Contributor Author

span=6deec7106582 fixed: f2cab20 — batch script now has an explicit branch for the journal-only partial state: when dst_jsonl exists but dst_json is absent, it verifies journal equality then copies .json and continues, matching the matrix.

@CrysisDeu

Copy link
Copy Markdown
Contributor Author

span=6072d704c759 fixed: f2cab20 — diskutil quiet secureErase freespace 0 / alternative removed; step 4 now says sync alone.

@CrysisDeu

Copy link
Copy Markdown
Contributor Author

span=251f8287411f fixed: f2cab20 — (1) kirocrew service stop replaced with kirocrew stop; (2) breadcrumb hint removed; (3) journal-only partial state now handled explicitly in batch script; (4) symlink check added before any copy; (5) diskutil alternative removed.

@CrysisDeu
CrysisDeu force-pushed the docs/13114-transcript-reverse-recipe branch from f2cab20 to f203547 Compare October 15, 2026 06:35
@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 Oct 15, 2026
@CrysisDeu

Copy link
Copy Markdown
Contributor Author

span=advisory fixed: f203547 — guides/README.md index row now says "after reverting KIRO_HOME to the host home", which correctly identifies the trigger.

@CrysisDeu
CrysisDeu force-pushed the docs/13114-transcript-reverse-recipe branch from f203547 to a905709 Compare October 15, 2026 06:43
@CrysisDeu

Copy link
Copy Markdown
Contributor Author

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.

@CrysisDeu

Copy link
Copy Markdown
Contributor Author

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.

@CrysisDeu

Copy link
Copy Markdown
Contributor Author

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.

@CrysisDeu

Copy link
Copy Markdown
Contributor Author

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.

@CrysisDeu
CrysisDeu force-pushed the docs/13114-transcript-reverse-recipe branch from a905709 to c4f3032 Compare October 15, 2026 07:11
@CrysisDeu

Copy link
Copy Markdown
Contributor Author

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.

@CrysisDeu

Copy link
Copy Markdown
Contributor Author

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.

@CrysisDeu
CrysisDeu force-pushed the docs/13114-transcript-reverse-recipe branch from c4f3032 to e56bce2 Compare October 15, 2026 07:18
@CrysisDeu

Copy link
Copy Markdown
Contributor Author

span=60d663f26030 fixed: e56bce2 — the batch script section has been removed entirely; only the manual steps and the failure-mode matrix remain.

@CrysisDeu

Copy link
Copy Markdown
Contributor Author

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.

@CrysisDeu

Copy link
Copy Markdown
Contributor Author

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.

@CrysisDeu

Copy link
Copy Markdown
Contributor Author

span=a166636eef1e fixed: e56bce2 — the Edge cases table has been removed; the collision branches are stated once in step 1 of the recipe.

@CrysisDeu
CrysisDeu force-pushed the docs/13114-transcript-reverse-recipe branch from e56bce2 to f5a85bb Compare October 15, 2026 07:25
@CrysisDeu

Copy link
Copy Markdown
Contributor Author

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.

@CrysisDeu

Copy link
Copy Markdown
Contributor Author

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.

@CrysisDeu

Copy link
Copy Markdown
Contributor Author

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

@CrysisDeu

Copy link
Copy Markdown
Contributor Author

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.

@CrysisDeu
CrysisDeu force-pushed the docs/13114-transcript-reverse-recipe branch from f5a85bb to 96384e6 Compare October 15, 2026 07:32
@CrysisDeu

Copy link
Copy Markdown
Contributor Author

span=8a4e8ef9630c fixed: 96384e6 — all occurrences of 'kirocrew start' replaced with 'kirocrew gateway', the correct command to start the gateway (verified against cli.py).

@CrysisDeu

Copy link
Copy Markdown
Contributor Author

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.

@CrysisDeu

Copy link
Copy Markdown
Contributor Author

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.

@CrysisDeu

Copy link
Copy Markdown
Contributor Author

span=251f8287411f fixed: 96384e6 — (1) kirocrew start replaced with kirocrew gateway; (2) pruning description corrected per _keeps_entry/_stash_and_clear_sid.

@CrysisDeu

Copy link
Copy Markdown
Contributor Author

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.

@CrysisDeu
CrysisDeu force-pushed the docs/13114-transcript-reverse-recipe branch from 96384e6 to 3f1278d Compare October 15, 2026 07:50
@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 Oct 15, 2026
@CrysisDeu
CrysisDeu force-pushed the docs/13114-transcript-reverse-recipe branch from 3f1278d to 39a7360 Compare October 15, 2026 08:28
@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 Oct 15, 2026
@CrysisDeu

Copy link
Copy Markdown
Contributor Author

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.

@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 Oct 15, 2026

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

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.

@bolichen97
bolichen97 merged commit fd09988 into main Oct 15, 2026
103 checks passed
@bolichen97
bolichen97 deleted the docs/13114-transcript-reverse-recipe branch October 15, 2026 18:37
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 15, 2026
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.

Reverse recipe / doctor fix-it for transcripts migrated into an adopted kiro home

2 participants