fix: lock terminal stale restore contract

[Astro-Han]

Summary

• Lock DELETE /pty/:id missing-target behavior to 404 NotFoundError.
• Add backend route coverage for missing PTY remove targets.
• Add a stale terminal restore E2E that rewrites real workspace terminal storage to legacy pty_old, reloads, and verifies restore uses a durable tab_... without hitting /pty/pty_old.

Why

#648 split terminal identity into durable UI tabs and memory-only runtime PTY handles. PR1 added the storage schema, and PR2 wired the runtime lifecycle. PR3 closes the remaining contract gap: missing delete semantics must be explicit, and stale persisted terminal state must not send old runtime ids back to backend PTY routes.

Related Issue

Closes #648.

Human Review Status

Pending. A human should make the final merge decision after reviewing the final diff and verification evidence.

Review Focus

• Check that DELETE /pty/:id now matches the existing GET / PUT / connect missing-target contract.
• Check that frontend durable-tab close behavior still tolerates missing runtime PTYs.
• Check that the new E2E covers the stale persisted restore path without depending on guessed storage keys.

Risk Notes

• terminal-reconnect.spec.ts still fails locally at the known Ghostty input path: the command is typed, but the expected token does not render before the reconnect assertion. This is unchanged from PR2 and is not caused by this diff.
• Manual desktop interaction through Computer Use timed out reading the Electron window. To keep verification bounded, I used isolated desktop startup plus the repo raw CI smoke after building renderer output.
• No UI layout, copy, terminal rendering, or PTY process implementation is redesigned here.

How To Verify

OpenCode PTY route test: bun --cwd packages/opencode test test/server/pty-routes.test.ts -> 5 pass, 0 fail
App terminal unit tests: bun --cwd packages/app test:unit src/context/terminal.test.ts src/context/terminal-storage.test.ts src/context/terminal-lifecycle.test.ts -> 1112 pass, 0 fail
App typecheck: bun --cwd packages/app typecheck -> passed
OpenCode typecheck: bun --cwd packages/opencode typecheck -> passed
Diff check: git diff --check -> passed
Terminal stale restore E2E: bun --cwd packages/app test:e2e:local -- e2e/terminal/terminal-stale-restore.spec.ts -> 1 passed
Terminal init E2E: bun --cwd packages/app test:e2e:local -- e2e/terminal/terminal-init.spec.ts -> 1 passed
Terminal reconnect E2E: bun --cwd packages/app test:e2e:local -- e2e/terminal/terminal-reconnect.spec.ts -> failed at known Ghostty input token render step before reconnect assertion
Desktop build: bun --cwd packages/desktop-electron build -> passed
Desktop raw smoke: bun packages/desktop-electron/scripts/ci-smoke.ts raw dev -> passed

Screenshots or Recordings

N/A. This PR changes runtime recovery contracts and regression coverage, not visible UI layout or copy.

Checklist

• Human review status is stated above as pending, approved, or not required
• I linked the related issue, or stated why there is no issue
• This PR has type, primary area, and priority labels, or I requested maintainer labeling
• I described the review focus and any meaningful risks
• I listed the relevant verification steps and the key result for each
• I did not introduce unrelated refactors, dependencies, generated files, or file changes beyond the stated scope
• I manually checked visible UI or copy changes when needed, with screenshots or recordings
• I considered macOS and Windows impact for platform, packaging, updater, signing, paths, shell, or permissions changes
• I called out docs, release notes, dependencies, permissions, credentials, deletion behavior, generated content, or local file changes when relevant
• I reviewed the final diff for unrelated changes and suspicious dependency changes
• I am targeting dev, and my PR title and commit messages use Conventional Commits in English

Summary by CodeRabbit

Release Notes

• Bug Fixes

  • Enhanced terminal session deletion to validate session existence before removal, providing clearer error messages

• New Features

  • Terminal restoration now creates fresh runtime sessions when resuming previously persisted terminal states

• Tests

  • Added comprehensive test coverage for terminal state restoration workflows and error handling in terminal session operations

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: c7771958-5625-489a-a1dc-88ce87b8c56b

📥 Commits

Reviewing files that changed from the base of the PR and between c279ef5 and d616eae.

📒 Files selected for processing (3)

• packages/app/e2e/terminal/terminal-stale-restore.spec.ts
• packages/opencode/src/server/instance/pty.ts
• packages/opencode/test/server/pty-routes.test.ts

---

📝 Walkthrough

Walkthrough

Backend validation enforces that missing PTY resources return 404 NotFoundError on delete. E2e test validates that restoring legacy persisted terminal state with stale runtime PTY IDs creates fresh PTYs, prevents old resource requests, and migrates persistence to version 2 without embedding runtime handles.

Changes

Stale Terminal Restore and Missing-PTY Contract

Layer / File(s)	Summary
Missing-PTY backend contract packages/opencode/src/server/instance/pty.ts	DELETE :ptyID handler now loads the session first, raises NotFoundError("Session not found") if missing, then removes it.
Backend test for missing PTY packages/opencode/test/server/pty-routes.test.ts	Test verifies that DELETE /pty/<non-existent> returns 404 status with NotFoundError name in JSON body.
E2E test for stale terminal restore packages/app/e2e/terminal/terminal-stale-restore.spec.ts	Injects legacy persisted terminal state into localStorage, reloads the page, opens the terminal, and asserts: new PTY tab ID does not match the old stale ID, no network traffic targets the old /pty/pty_old resource, and persisted state is migrated to v2 without pty_old or runtime runtimePty references.

---

🎯 2 (Simple) | ⏱️ ~12 minutes

---

bug

---

🐰 Stale terminal IDs shuffle off to rest,
Fresh PTYs bloom when sessions are refreshed,
Migrations v2 banish ghosts of the past,
No 404 loops to forever last,
A rabbit hops through clean state at last! 🌿

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'fix: lock terminal stale restore contract' clearly describes the main change: enforcing backend and frontend contract behavior for terminal state restoration.
Description check	✅ Passed	The PR description comprehensively covers all template sections including summary, rationale, related issue, review focus, risk notes, verification steps with results, and a completed checklist.
Linked Issues check	✅ Passed	The PR fully addresses all coding requirements from #648: implements explicit DELETE /pty/:id missing-target semantics [pty.ts], adds server route coverage for missing PTY removal [pty-routes.test.ts], and provides regression E2E coverage for stale persisted restore [terminal-stale-restore.spec.ts].
Out of Scope Changes check	✅ Passed	All three changed files are directly aligned with #648 objectives: contract enforcement (pty.ts), server test coverage (pty-routes.test.ts), and regression E2E (terminal-stale-restore.spec.ts) for terminal stale restore. No unrelated refactors or out-of-scope changes detected.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/i648-terminal-pr3

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

Suggested priority: P2 (includes non-doc, non-test paths outside the low-risk bucket).

P1/P0 are reserved for maintainer confirmation. Please relabel manually if this is a release blocker, security issue, data-loss risk, or updater/runtime failure.

[gemini-code-assist]

Code Review

This pull request introduces an E2E test to verify that restoring legacy terminal state correctly initializes a fresh runtime PTY. It also updates the PTY deletion route to explicitly check for existence and return a 404 error, supported by a new unit test. Feedback suggests optimizing the deletion logic by removing the redundant existence check before removal and using a more generic error message to avoid information leakage.

[Astro-Han]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.