fix(agent-core-v2): roll back failed session initialization

[wbxl2000]

Related Issue

No linked issue. This fixes Session scopes and on-disk state retained after initialization failures.

Problem

Session handles are registered before metadata, MCP, plan bootstrap, resume replay, and creation hooks finish. If any of those steps rejects, the handle and child DI scope can remain reachable. A fresh create can also leave state.json and partial session files behind, so later list/resume/fork calls treat the failed attempt as a persisted session.

Concurrent same-ID initialization and teardown previously had no single lifecycle owner. One attempt could expose a half-initialized handle, overwrite another handle, return a handle that a hook had already closed, or delete a replacement during rollback.

What changed

• Add one lifecycle-owned, per-session-ID initialization claim shared by create, resume materialization, and fork. Unrelated IDs are not serialized.
• Separate writer ownership from read visibility. get, list, and resume hide unpublished or closing handles; creation hooks can safely call same-ID read APIs after core publication without waiting on themselves.
• Make publication the irreversible commit point: the activity kernel is active before a handle becomes visible, and a later creation-hook failure remains observable to the writer without rolling back a handle already returned to another reader. The committed-session event and telemetry still run once when the handle remains owned.
• Preserve explicit close/archive calls made before a handle exists, make them the single teardown owner after publication, and re-check ownership before create/resume/fork returns.
• Make fork source lookup wait for an unpublished source to publish or fail, and for a closing source to retire, before choosing the live handle or cold persisted fallback. A published, active source can be forked from its own creation hook without waiting on itself.
• For fresh create/fork, claim the final leaf directory with non-recursive mkdir. Only the call that created that leaf may remove it; EEXIST reports SESSION_ALREADY_EXISTS, resume never claims or deletes an existing directory, and identity checks protect concurrent replacements.
• Before removing an owned failed directory, stop agents, wait for initial and queued metadata persistence through ISessionMetadata.whenIdle(), dispose the Session scope, and wait for append-log writes. A failure in those pre-removal barriers retains the directory; every cleanup error is reported together with the original failure through AggregateError.
• Do not delete MiniDB rows by bare session ID during rollback. The query store is derived; FileSessionIndex now requires matching persisted state and createdAt before a cached row can answer get or filtered list.
• Cover failure/retry, create/create and fork/create exclusion, hook self-resume/close, pre-handle close/archive, closing visibility, stable fork sources, exclusive directory ownership, delayed metadata/read-model writes, append-log drain, cleanup failure, and stale cached summaries through public service contracts.

Required follow-up before release

This PR is a prerequisite for the task4-B session-membership change, not a complete cross-process publication transaction, and should not ship by itself.

Task4-B must still own these related contracts once, rather than duplicating them here:

• a per-home, per-session-ID lock shared by v1 and v2 create/fork paths, covering cross-workspace and cross-process admission;
• v1 list/get filtering for final directories that do not contain a valid state.json;
• session_index.jsonl publication only after all fallible initialization, or a durable invalidation record for ambiguous/failed publication;
• removal of MiniDB as session-membership authority. The createdAt comparison in this PR is only a temporary stale-generation guard, not an ownership token.

Latest main, including #1635, is merged into this branch, so cleanup now runs on the stronger append-log flush/retirement contract. A sticky failure in an unrelated append-log key still makes cleanup conservatively retain the directory and return AggregateError; an owner-scoped barrier would be a separate availability improvement. The pre-existing fully-live fork-versus-close race after initialization ownership retires also remains outside this PR.

Validation

• agent-core-v2: 236 files / 3332 tests passed with one worker
• focused lifecycle/metadata/index contracts: 87 tests passed
• kap-server: 55 files / 615 tests passed with one worker; typecheck passed
• server-e2e: v2 in-process smoke 5/5; typecheck passed
• agent-core-v2: build, typecheck, and domain lint passed (848 files)
• independent fixed-diff review: No actionable findings within the stated task4-B boundary
• git diff --check passed

The first kap-server run used an invalid test home shape and also hit the known auth temp-directory ENOTEMPTY cleanup flake. The two exact files passed 26/26 with <temp>/.kimi-code, then the corrected full run passed. One agent-core-v2 full run hit the unchanged five-second full-compaction boundary test; the exact case passed 3/3, then the full suite passed. Changeset generation was re-checked; repository-wide changeset status is currently blocked by an unrelated pre-existing changeset referencing a removed workspace.

Checklist

• I have read the CONTRIBUTING document.
• I have linked a related issue, or explained the problem above.
• I have added tests that prove my feature works.
• Ran gen-changesets skill, or this PR needs no changeset.
• Ran gen-docs skill, or this PR needs no doc update.

[changeset-bot]

🦋 Changeset detected

Latest commit: b7a9100

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages

Name	Type
@moonshot-ai/agent-core-v2	Patch
@moonshot-ai/kimi-code	Patch
@moonshot-ai/kap-server	Patch
@moonshot-ai/klient	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[wbxl2000]

@codex review

[pkg-pr-new]

pnpm dlx https://pkg.pr.new/@moonshot-ai/kimi-code@20e75ae

npx https://pkg.pr.new/@moonshot-ai/kimi-code@20e75ae

commit: 20e75ae

[wbxl2000]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7a5dd5318d

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[wbxl2000]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 833858caf7

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[wbxl2000]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

kimi-code/packages/agent-core-v2/src/app/sessionLifecycle/sessionLifecycleService.ts

Line 636 in 9e4679d

const sourceHandle = this.sessions.get(sourceId);

Gate fork sources on published sessions

When fork() is requested while the source session's create/resume has registered its handle but has not published yet (for example, it is blocked in ensureMcpReady() or later fails), this raw sessions lookup bypasses the new initializations visibility gate and treats a half-initialized source as forkable. That can persist a fork of a source session that is subsequently rolled back or closed, violating the new invariant that initializing sessions stay hidden; wait for the source initialization to publish/settle or resolve it through get()/resume() before using the handle.

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[wbxl2000]

Addressed the source-visibility finding in 6d8c880dd. Fork-source resolution is now treated as a write path: it waits for every active same-ID initialization/lifecycle claim to fully settle, rechecks replacement claims, and only then uses the final live handle or the existing cold index fallback. Added deferred public regressions for create-source MCP, resume-source MCP, failed source initialization, and closing-to-cold fallback (54/54 targeted; fixed-diff review clean). The pre-existing race between an already fully live source and a simultaneous close after claim retirement remains explicitly outside this lifecycle-initialization fix.

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6d8c880dd8

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[wbxl2000]

@codex review

New HEAD: 20e75aed9.

Scope note: this PR remains draft and must not ship independently. It still depends on task4-B for the shared cross-process/global session-ID lock, v1 filtering of final directories without valid state, safe final session_index.jsonl publication or invalidation, and removal of MiniDB membership authority. It also requires #1635 append-log retirement semantics before release. Those dependencies are documented in the PR body and are not claimed as solved here.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 20e75aed95

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[wbxl2000]

@codex review

New HEAD: 75502ee8d.

The published-handle rollback P2 is fixed with publication as the irreversible commit point; full agent-core-v2 is 236/236 files and 3289/3289 tests. This PR remains draft and still depends on task4-B for the shared global/cross-process session-ID lock, v1 invalid-directory filtering, safe final JSONL publication/invalidation, and removal of MiniDB membership authority. It also requires #1635 before release; none of those dependencies are claimed as solved here.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 75502ee8da

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[wbxl2000]

@codex review

New HEAD: 1783b485f.

The creation-hook fork deadlock is fixed by distinguishing unpublished, published, and closing source claims. Lifecycle is 64/64 and full agent-core-v2 is 236/236 files, 3290/3290 tests. The PR remains draft and still depends on task4-B for global/cross-process ID ownership, v1 invalid-directory filtering, safe final JSONL publication/invalidation, and removal of MiniDB membership authority; #1635 is also required before release.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Keep them coming!

Reviewed commit: 1783b485f9

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[wbxl2000]

@codex review

Final merge HEAD: b7a9100d5.

The logical fix at 1783b485f was clean. This ordinary merge incorporates latest main (e49b3b877, including #1635/#1636/#1637); the only content resolution preserves both the session initialization ownership changes and caller mcpServers forwarding. git diff origin/main contains only the 11 #1642 files. Post-merge lifecycle is 65/65, full agent-core-v2 is 236/236 files and 3332/3332 tests, with typecheck/domain/build and downstream typechecks green. The PR remains draft and still explicitly depends on task4-B.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. 🚀

Reviewed commit: b7a9100d5e

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".