fix(cli): resolve plan_exit to the plan file actually saved

[johnnyeric]

Issue

Fixes #11859

Context

Plan mode had two related bugs on finalize: plan_exit reported a filename that didn't match what was actually written, and the "implement in new session?" follow-up prompt would silently fail to appear.

Root cause: plan_exit fell back to Session.plan()'s randomly-slugged path whenever the model omitted an explicit path. That was fine while the reminder pinned an exact filename, but a later change (#11170) moved to agent-chosen descriptive filenames without updating the fallback - so whenever the model omitted path, plan_exit reported a file that was never written. The follow-up flow read a plan file at that same wrong path, got an empty read, and silently skipped the prompt - same root cause, different symptom.

Implementation

plan_exit and the follow-up flow now verify the plan file exists on disk instead of trusting a guessed path:

• PlanFile.resolve() now rejects a path that exists but isn't a file (e.g. a directory), in addition to its existing containment check.
• New PlanFile.locate() recovers the real file in tiers: exact target → newest file matching the session's generated-name pattern (<session-created>-*.md) → the last markdown file written by a planning agent (covers custom architect-slug agents too, via a caller-supplied agent name). This is intentionally narrow - a false-positive match in this fallback would finalize the wrong file, so it only looks at write/edit tool calls from plan/architect-agent turns.
• plan_exit now fails with an actionable error ("write the plan file first, or pass the exact path") instead of silently succeeding with a nonexistent path.
• Filesystem.stat was hardened to never throw (it previously only suppressed ENOENT; ENOTDIR/EACCES could throw and crash the new verification path) - every existing caller already treated its result as optional, so this only removes latent crash paths.

This diff went through several rounds of adversarial code review; each round found and fixed real issues (a too-loose write-history fallback, a directory passing as a valid plan path, an agent-name filter that excluded custom architect slugs) before converging.

Screenshots / Video

plan.mov

How to Test

Manual/local verification

• bun test test/kilocode/plan-file.test.ts test/kilocode/plan-followup.test.ts test/kilocode/plan-exit-detection.test.ts — 54 passing (agent)
• bunx tsc --noEmit -p packages/opencode — clean (agent)
• bun turbo typecheck (full monorepo, via pre-push hook) — 20/20 tasks passing (agent)

Reviewer test steps

1. Start Plan mode, let the agent write a plan under a descriptive filename it chose itself, and call plan_exit without an explicit path - the "Plan is ready at X" link should point at the real file.
2. At the follow-up prompt, choose "Start new session" — the new session's plan-file reference should point at the same real file.
3. Delete the plan file mid-planning and call plan_exit - expect a visible "Plan file not found" tool error (not a silent success or a stuck session).

Checklist

• Issue linked above, or exception explained
• Tests/verification described
• Screenshots/video included for visual changes, or marked N/A
• Changeset considered for user-facing changes
• I personally reviewed the diff and can explain the changes, including any AI-assisted work.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e9d94c2d36

ℹ️ About Codex in GitHub

Your team has set up Codex to 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 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

The saved()/written() tiered recovery logic in plan-file.ts correctly bounds fallback lookups to the project or canonical plan directory (via containsPath/Filesystem.contains), the previously flagged stale-fallback issue is fixed with a regression test (fresh file now wins the mtime comparison), and the filesystem.ts stat() hardening is scoped with kilocode_change markers and consistent with how all 8 existing callers already treat the result as optional. New tests exercise the real implementation against a tmp filesystem/git repo rather than mocks.

Files Reviewed (6 files)

• .changeset/plan-file-finalize.md
• packages/opencode/src/kilocode/plan-file.ts
• packages/opencode/src/kilocode/plan-followup.ts
• packages/opencode/src/kilocode/tool/plan.ts
• packages/opencode/src/util/filesystem.ts
• packages/opencode/test/kilocode/plan-file.test.ts

---

_{Reviewed by claude-sonnet-5-20260630 · Input: 34 · Output: 19.1K · Cached: 1.3M}

_{Review guidance: REVIEW.md from base branch main}