Skip to content

fix(acp): cleanup_session deletes the record on the session's own host - #39046

Open
JalaluddinYazdani wants to merge 1 commit into
kirodotdev:mainfrom
JalaluddinYazdani:fix/39035-cleanup-session-host-record
Open

JalaluddinYazdani wants to merge 1 commit into
kirodotdev:mainfrom
JalaluddinYazdani:fix/39035-cleanup-session-host-record

Conversation

@JalaluddinYazdani

@JalaluddinYazdani JalaluddinYazdani commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: When a caller asks to delete a finished session's record, it is deleted on KAS and codex too, not only on kiro-cli.

AcpSessionProvider.cleanup_session only unlinks kiro-cli's <sid>.json and <sid>.jsonl. On kas the record is in the engine's store, and on codex it is the rollout under the child's CODEX_HOME, so the call deletes nothing. The crewmate lessons draft (member_export._draft_turn) depends on this call. Its one-shot session owns its runtime, so the destroy kills the process and keeps the record. That leaves a record holding the crewmate's lessons and the draft.

Why it matters

Every lessons draft on a kas or codex host leaves a session record behind that nothing deletes. The record holds the lessons it read and the draft it wrote. The code comment says the turn has no later use for it.

Not a goal

  • A separate fix for subagent records. SessionManager.release(key, cleanup=True) does reach this change through _safe_cleanup, but only for a key that cannot be continued. There the record is deleted whatever the memory mode, as kiro-cli's unlink already does, because nothing can load that key again. A persistent handle teardown still keeps its codex rollout. subagent: finished kas runs never get their KAS session deleted, 2,402 session dirs (1,545 MB) in 12 days, orphaned for good after the 90-day window #36678's tombstone prune covers the rest. docs/system-specs/modules/acp-client.md says the same.
  • Any change to AcpSessionHandle.destroy, or to AcpProvider.cleanup_session on a host other than KAS.
  • Hosts other than kiro-cli, kas and codex. Their behaviour does not change.

What changed (motivation → approach → change)

Root cause: the provider-level cleanup was the one teardown path still tied to kiro-cli's store. The handle's teardown already asks the harness (delete_disposable_record), and AcpProvider.cleanup_session already routes by backend.

cleanup_session now calls a new session_handle_lifecycle.delete_native_record(runtime, sid), which routes by the runtime's harness:

Host What deletes the record
codex (a harness that names delete_disposable_record) that delete, with the runtime's extra_env, off the loop
kas, runtime alive _kiro/session/delete through runtime.delete_session_record
kas, runtime gone or the delete failed an entry in released_sessions, due now; the existing sweep sends the delete on the background runtime
kas, sandboxed process a warning, no entry (released-sessions/ is masked there)
kiro-cli and the rest the transcript unlink, as before

The lessons draft can also get an AcpProvider (runtime sharing off). On KAS its cleanup_session (providers/acp_lifecycle.py) hands the call to the AcpSessionProvider its runtime start put in _client, so it takes the same path, including the released_sessions entry after its shutdown. Its other hosts keep their own deletes.

The helper lives in session_handle_lifecycle.py because session_provider.py is already past the split size. docs/system-specs/modules/acp-client.md lists the new caller under the codex record delete and the KAS path.

Backwards compatibility

Compatible: kiro-cli keeps the same unlink, and the change only adds deletes on hosts where the call did nothing before.

Reader: src/kiro_crew/dashboard/handlers/member_export.py:_draft_turn -- crew page -- the draft's one-shot session has no later use for its record (test_a_dead_runtime_schedules_the_delete_due_now, test_the_lessons_draft_leaves_a_delete_for_its_record)
Reader: src/kiro_crew/session_allocation.py:_safe_cleanup -- chat -- calls it only for a session it is discarding, so the deleted record has no other reader (test_a_live_runtime_sends_the_engine_delete)

Tests

test/test_acp_session_provider_cleanup_host_record.py:

  • kas, live runtime: one _kiro/session/delete for the id, and no entry
  • kas, dead runtime: one entry, due now, that released_sessions.due() returns
  • kas, failed delete: an entry is written
  • kas, sandboxed: no entry, and a warning
  • kas, unsafe id: refused with a warning, no exception
  • codex: that thread's rollout under the runtime's CODEX_HOME is deleted, and another thread's is kept
  • kiro-cli: the transcript pair is unlinked, and no verb is sent
  • KAS AcpProvider after its shutdown: cleanup_session writes the due-now entry
  • member_export._draft_turn on KAS with an AcpProvider: after release and destroy, the draft's record has a due-now entry

On main eight of the nine fail. The kiro-cli case is the unchanged path. With only providers/acp_lifecycle.py reverted, the two AcpProvider cases fail. The SimpleNamespace provider stubs in test_acp_transcript_delete_off_loop.py and test_opencode_pi_disposable_records.py gain is_kas_backend=False. Every test file that names cleanup_session or _draft_turn, plus test_acp_backend_kas.py, test_kas_released_sessions.py and test_acp_bindings.py, passes: 1428 passed.

Proof: not provable -- prove.py timed out

Supporting evidence: on head 407527f5a439, before the rebase onto main, prove.py printed PROVEN for the tests below, and git range-diff shows c41f950 carries the identical patch: test/test_acp_session_provider_cleanup_host_record.py::TestKas::test_a_live_runtime_sends_the_engine_delete, test/test_acp_session_provider_cleanup_host_record.py::TestKas::test_a_failed_delete_schedules_it, test/test_acp_session_provider_cleanup_host_record.py::TestKas::test_a_sandboxed_process_writes_no_entry, test/test_acp_session_provider_cleanup_host_record.py::TestKas::test_an_unsafe_id_is_refused_without_raising, test/test_acp_session_provider_cleanup_host_record.py::TestAcpProviderOnKas::test_a_shut_down_provider_schedules_the_delete (head 407527f5a439)

Manual verification

N/A: the unit tests drive a real AcpRuntime, the real released_sessions store and real codex rollout files. Only the engine reply is mocked.

Real-machine verification

Not run on a real machine. The kas path needs a KAS engine, and that runs no differently on another host than the mocked reply does here.

Related Issues

Closes #39035

Sibling sweep

Swept: git grep -n "cleanup_transcript_files(" -- src/
Sibling: src/kiro_crew/acp/session_handle_lifecycle.py:410 -- not affected -- _cleanup_transcript asks the harness first, and on kas the teardown verb itself deletes the record

Pattern harvest

Not generalizable: the only provider cleanup with a hard-coded host store was this one; the others already ask the harness or route by backend.

Checklist

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

@github-actions github-actions Bot added the fork Pull request from a fork (external contributor) label Nov 18, 2026
@JalaluddinYazdani

Copy link
Copy Markdown
Contributor Author

[operator: JalaluddinYazdani] @bolichen97 @KiroCrewCaptain could you review this? It implements the design in #39035 (comment) (a fork account can't request reviewers directly).

@github-actions github-actions Bot added the readiness: action required A blocking check or review needs attention label Nov 18, 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.

Hand review of head 66d5fef. No blocking findings from me. I am not approving yet: the fork CI and the AI review lanes have not run on this head (5 workflows are still waiting for maintainer approval). I will come back once they report.

What I checked

  • The routing in delete_native_record matches the two sibling paths: the codex branch reuses _disposable_record_delete with the runtime's _extra_env, and the KAS branch uses runtime.delete_session_record, which returns False at once on a dead runtime (_dead or _process is None), so the lessons draft's post-destroy call does not wait on a timeout.
  • The fallback mirrors _release_ending: no entry in a sandboxed process, and released_sessions.schedule errors are caught and logged, so cleanup_session never raises into _draft_turn or _safe_cleanup.
  • Tests: the new file plus test_acp_session_provider*.py, test_acp_transcript_delete_off_loop.py, test_kas_released_sessions.py, test_acp_bindings.py and test_session_allocation_bindings.py: 408 passed locally. With src/ reset to main, 6 of the 7 new tests fail and the kiro-cli case passes, as the body says.
  • flake8 and black are clean on the touched files; session_provider.py gets one line shorter.

One question (non-blocking)

"Not a goal" lists the subagent records from SessionManager.release(key, cleanup=True), but that path does reach this change through _safe_cleanup (the Reader list names it). On codex, a non-continuable subagent's rollout is now deleted whatever its memory mode, where the handle teardown keeps a persistent one. That looks right to me, since the key cannot be continued and kiro-cli already unlinks there. Could you confirm that is intended, so the body and the spec line say the same thing?

AI-assisted, sent by Bolin Review bot

@bolichen97

Copy link
Copy Markdown
Contributor

@JalaluddinYazdani two reds on 66d5fef, neither about the logic:

  1. Fast Gate → comment-history gate flags src/kiro_crew/acp/session_handle_lifecycle.py:459: "An engine answers success for an id it no longer holds". The gate treats "no longer" as history narration. A present-tense wording passes, for example "An engine answers success for an id it does not hold". CI's "Await Fast Gate" fails only because of this.
  2. Dependency License Gate could not run: GitHub's dependency-graph API returned "API rate limit exceeded for installation". That is not a license finding, and I'll rerun it once the limit resets.

The AI review lanes have not posted on this head yet. I'll look again after your next push.

AI-assisted, sent by Bolin Review bot

@JalaluddinYazdani
JalaluddinYazdani force-pushed the fix/39035-cleanup-session-host-record branch from 66d5fef to 903a8ca Compare November 18, 2026 10:57
@JalaluddinYazdani

Copy link
Copy Markdown
Contributor Author

[operator: JalaluddinYazdani] @bolichen97 thanks. Pushed 903a8ca (still one commit):

  1. Comment-history gate: session_handle_lifecycle.py:459 now says "An engine answers success for an id it does not hold". COMMENT_HISTORY_BASE_REF=HEAD~1 python3 scripts/check_comment_history.py passes locally.
  2. Subagent question: yes, that is intended. SessionManager.release(key, cleanup=True) reaches cleanup_session through _safe_cleanup only for a key that cannot be continued. There the codex rollout is deleted whatever the memory mode, the same as kiro-cli's unlink, because nothing can load that key again. The persistent handle teardown still keeps its rollout. I reworded "Not a goal" in the body and added the same line to the acp-client.md spec bullet, so they now agree.

black and flake8 are clean. The new test file, test_acp_transcript_delete_off_loop.py, test_kas_released_sessions.py and test_acp_bindings.py pass: 272 passed.

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5, fork) — ✅ PASS

Premise-level review of c41f95080f71d5b6796e8db8cc43cebeddf3a603 via the fork AI-review pipeline — 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 does not.

First-Principles-Verdict: PASS

Nothing blocks: every item is aimed at the stated cause and reuses the existing delete mechanisms (harness delete_disposable_record, runtime.delete_session_record, the released_sessions sweep).

What this change ships

Inventory (7 items) — 7 justified

Intent: when a caller asks to delete a finished session's record, it should go on KAS and codex too, not only on kiro-cli. This is a FIX (#39035).

  1. On KAS with a live runtime, AcpSessionProvider.cleanup_session now sends _kiro/session/delete for the session — justified
  2. On KAS with a dead runtime or a failed delete, a delete is scheduled due now in released_sessions — justified
  3. In a sandboxed KAS process, a warning is logged and no entry is written — justified
  4. On codex, AcpSessionProvider.cleanup_session deletes the thread's rollout under the runtime's CODEX_HOME, whatever the memory mode — justified
  5. On KAS, AcpProvider.cleanup_session hands the call to the AcpSessionProvider in _client, so the unshared lessons draft deletes its record too — justified
  6. A new helper _teardown_deletes_record identifies KAS by its teardown verb; can_release() can't be used because it needs a live handshake — justified
  7. The acp-client.md spec lists the new caller and the KAS path — justified

[FIRST-PRINCIPLES-REVIEWED] c41f950

Description read

[DESCRIPTION-READ] 8645bb45ed15a20e69647f21ce66d8bab0623250e51aa9a0b32d43a5a7edfac4

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5, fork) — ⏭️ skipped

Revision c41f95080f71d5b6796e8db8cc43cebeddf3a603 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — ✅ PASS

Design-level review of c41f95080f71d5b6796e8db8cc43cebeddf3a603 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: provider cleanup now goes through the same per-harness delete the handle teardown already uses. The KAS AcpProvider.shutdown change only affects incognito and temporary chats, which are meant to be thrown away.

Notes

  • On KAS, every non-persistent AcpProvider.shutdown now writes a due-now released_sessions entry even when the handle teardown already deleted the record. That costs one redundant background delete per shutdown. The description names _draft_turn and _safe_cleanup as readers, but not this broader shutdown path.

[DESIGN-REVIEWED] c41f950

Description read

[DESCRIPTION-READ] d59769d0e9e34747ff0c39fdd1b84949a55ed4f4713a3beafc700e75905a8725

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 Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings

Reviewed c41f95080f71d5b6796e8db8cc43cebeddf3a603 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] c41f950

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

Thanks for the comment fix. The GPT 6.1 finding on 903a8ca looks real to me, and it hits the exact case #39035 describes, so I'm requesting changes.

AcpSessionProvider.cleanup_session (src/kiro_crew/acp/session_provider.py:690) now calls delete_native_record. But a provider that get_or_create hands out can also be an AcpProvider, and its cleanup_session is src/kiro_crew/providers/acp_lifecycle.py:289. That function handles Claude, Codex and OpenCode, and then falls through to _delete_kiro_session_files for everything else, KAS included. It never reaches delete_native_record. If the lessons draft (member_export._draft_turn) cleans up through that path on KAS with runtime sharing off, the record with the lessons and the draft is still left behind. That is the leak this PR sets out to close.

Could you either route providers/acp_lifecycle.cleanup_session to delete_native_record for a KAS-hosted session (including after shutdown, through the released_sessions fallback), or show that _draft_turn always gets an AcpSessionProvider? A test that drives _draft_turn's cleanup on KAS would pin it either way.

The adjudication stage didn't run on this head (an API error), so GPT's verdict was never downgraded. Everything else from my earlier review still holds. I approved the held fork CI runs.

AI-assisted, sent by Bolin Review bot

@JalaluddinYazdani
JalaluddinYazdani force-pushed the fix/39035-cleanup-session-host-record branch from 903a8ca to c41f950 Compare November 18, 2026 12:42
@JalaluddinYazdani

Copy link
Copy Markdown
Contributor Author

self-added: no
mechanism: KAS AcpProvider.cleanup_session hands the call to its AcpSessionProvider

  • span=0026cc4096ba Lessons drafts bypass the new record cleanup

fixed in c41f950: on KAS, providers/acp_lifecycle.cleanup_session hands the call to the AcpSessionProvider in _client, so delete_native_record runs, including the due-now released_sessions entry after shutdown.
Pinned by TestAcpProviderOnKas::test_the_lessons_draft_leaves_a_delete_for_its_record, which drives member_export._draft_turn with a KAS AcpProvider; it fails with acp_lifecycle.py reverted.

@JalaluddinYazdani

Copy link
Copy Markdown
Contributor Author

[operator: JalaluddinYazdani] @bolichen97 you were right, thanks. Pushed c41f950 (one commit, rebased on main):

  • Fix: on KAS, providers/acp_lifecycle.cleanup_session hands the call to the AcpSessionProvider that _start_kiro_runtime_impl puts in _client (providers/acp_runtime_start.py:1437). On KAS, an AcpProvider always starts through the runtime path, so _client is that provider after start, and it stays there after shutdown. The call goes through delete_native_record: _kiro/session/delete on a live runtime, or the due-now released_sessions entry once the runtime is gone. Claude, codex, OpenCode and kiro-cli keep their own deletes.
  • Tests: TestAcpProviderOnKas has two tests. One drives a shut-down KAS AcpProvider.cleanup_session. The other drives member_export._draft_turn with a KAS AcpProvider through release, destroy and cleanup, and checks that the draft's record has a due-now entry. Both fail with only acp_lifecycle.py reverted. The SimpleNamespace provider stubs in test_acp_transcript_delete_off_loop.py and test_opencode_pi_disposable_records.py gain is_kas_backend=False.
  • Runs: every test file naming cleanup_session or _draft_turn, plus test_acp_backend_kas.py, test_kas_released_sessions.py and test_acp_bindings.py: 1428 passed. black, isort, flake8, the comment-history gate and the flake-pattern ratchet are clean.

The body's "Not a goal" now leaves out only non-KAS hosts of AcpProvider.cleanup_session, and the spec bullet in acp-client.md names this path. The GPT disposition for span=0026cc4096ba is posted separately.

@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 Nov 18, 2026
@github-actions

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — 🔴 changes requested (blocking)

Reviewed c41f95080f71d5b6796e8db8cc43cebeddf3a603 via the fork AI-review pipeline; updated in place on each push.

Every incognito or temporary KAS chat that owns its runtime now leaves a released_sessions entry for a record that was already deleted when the chat ended. When the gateway's default backend is not KAS, those entries never drain, and after 7 days the operator gets a warning telling them to switch backends.

BLOCKING — src/kiro_crew/providers/acp_lifecycle.py:172

if self.is_kas_backend:
    ...
        await self._client.cleanup_session(session_id)

Trigger: A dashboard session is created with session_create(backend=kas) on a gateway whose agent.acp_backend is kiro. select_provider_backend honours backend_override, and the chat is incognito or temporary. When it ends, AcpProvider.shutdown calls _client.shutdown(). In AcpSessionProvider._shutdown_session, the owned non-persistent arm runs _handle.destroy(), which calls terminate_session and sends _kiro/session/delete; then _runtime.kill(...) runs. shutdown then calls self.cleanup_session(session_id). That path goes AcpSessionProvider.cleanup_session → delete_native_record, where delete_session_record returns False because _process is None/_dead. So released_sessions.schedule(..., backend="kas", delay_secs=0.0) runs.
Outcome: Each such chat adds a permanent file under released-sessions/ for a record the engine no longer holds. sweep only sends entries whose backend == agent.acp_backend, so while the default stays kiro they pile up without limit. After _STRANDED_GRACE_SECS, _warn_if_stranded tells the operator to kirocrew config set agent.acp_backend kas and restart. That instruction is false, because nothing is left to delete. In a sandbox-launched process, the same path logs cleanup: could not delete the record at WARNING on every such shutdown.
Anchor: defect
Fix: Don't schedule a fallback when the handle's teardown already ran the delete verb. For example, skip the KAS delegation from shutdown when memory_mode != "persistent" and the provider owned the runtime, since destroy() already sent _kiro/session/delete. Keep the delegation only for explicit cleanup_session callers such as the lessons draft.

[BLOCK-MERGE] c41f950
[OPUS-REVIEWED] c41f950

This branch has not been deployed

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

Labels

fork Pull request from a fork (external contributor) readiness: checking Automated validation is still running

Projects

None yet

Development

Successfully merging this pull request may close these issues.

session cleanup: AcpSessionProvider.cleanup_session deletes only kiro-cli files, so a kas or codex session keeps its record

2 participants