Task 1: Rename the terminal session layer off `pty`

[AkaraChen]

Summary

Rename the live terminal session layer off Local-implementation pty names for parent plan #463. Local PTY is already deleted (#436 Task 9 / #452): there is no adapter, portable-pty spawn, env/flag backend, or sqlite pty_sessions store. What survives is vocabulary — handler/pty.rs, model/pty.rs, IPC create_pty_session / write_to_pty / resize_pty / scroll_pty / close_pty_session / attach_pty_output / detach_pty_output / flush_pty_output / clear_pty_output, DTOs PtySessionRecord / PtySessionMeta / PtyConfig, AppError::PtyError, and frontend callers (createPtySession, writeToPty, …). This task is a rename. Same IPC semantics, same clicks and labels. No Local anything. Do not start Task 2 (TWOCODE_RUNTIME traces) or Task 3 (repo-wide audit lock).

Herdr is the profile authority. sqlite profiles is not source of truth (the table is DROPped). projects / project_groups / checkout_notes stay in 2code sqlite. Default-runtime switch and deleting Local/PTY/profiles rows already shipped in #436 — do not re-litigate or re-add them. Never let Local and Herdr own the same worktree (Local is gone; do not bring it back). Do not change interaction. IPC command names change; New Tab / tab strip / New Profile / Delete Profile clicks and labels stay.

This is #463 Task 1, not #394 Task 1 (#395) and not #436 Task 1 (#437). Do not implement or close those tickets here.

Dependencies: Parent plan #463. Prerequisites: none on this plan. Stack on task-3-line-count-trackers (PR #462). Open task tickets from #394 / #436 / #458, leftover gaps (#396, #397, #398, #399, #401), and line-count trackers are out of scope.

Work to complete

1. Rename the Rust session modules and DTOs

   • Move src-tauri/src/handler/pty.rs → handler/terminal.rs and src-tauri/crates/model/src/pty.rs → model/session.rs. Update mod / use / lib.rs / handler/mod.rs.
   • Rename types to terminal/session names that match Herdr-backed reality and the existing TerminalRuntime / HerdrTerminalFrame language:
     • PtySessionRecord → TerminalSessionRecord (still a derived GUI DTO from session.snapshot; id = pane_id, profile_id = workspace_id; not a sqlite row)
     • PtySessionMeta → TerminalSessionMeta
     • PtyConfig → TerminalConfig
   • Keep list_project_sessions, get_session_backend, get_session_agent_status, stream_session_agent_status, and stream_herdr_output (already not pty-named). Keep RestoreResult if it still exists; do not revive sqlite restore.
   • Update every Rust caller: runtime.rs, runtime/herdr.rs, and tests that include_str! handler/pty.rs or split on pub fn detach_pty_output / scroll_pty / attach_pty_output / close_pty_session.

2. Rename the IPC commands and move frontend callers in the same commit

   • Commands (Rust snake_case → generated camelCase):
     • create_pty_session → create_terminal_session (createTerminalSession)
     • write_to_pty → write_to_terminal (writeToTerminal)
     • resize_pty → resize_terminal (resizeTerminal)
     • scroll_pty → scroll_terminal (scrollTerminal)
     • close_pty_session → close_terminal_session (closeTerminalSession)
     • attach_pty_output → attach_terminal_output (attachTerminalOutput)
     • detach_pty_output → detach_terminal_output (detachTerminalOutput)
     • flush_pty_output → flush_terminal_output (flushTerminalOutput)
     • clear_pty_output → clear_terminal_output (clearTerminalOutput)
   • Register the new names in lib.rs. Same arguments, return types, fail-closed Herdr behavior, and stream_id attach/detach pairing. stream_herdr_output still owns Channel<HerdrTerminalFrame>.
   • Run cargo tauri-typegen generate (or bun run typegen) in the same commit so src/generated/commands.ts / types.ts match. Do not hand-edit generated bindings if typegen can produce them.
   • Update every frontend caller and mock: hooks.ts, Terminal.tsx, TerminalTabs.tsx, terminalTransport.ts, restoration.ts ([pty-restore] log prefix → session/terminal), src/test/setup.ts, and colocated tests. Same New Tab / write / resize / scroll / close / attach clicks.

3. Rename AppError::PtyError

   • error.rs: PtyError → TerminalError. Display prefix today is PTY error:; change it to Terminal error: so live strings do not say PTY. Frontend does not match that prefix (AppError serializes via to_string()). Inner messages stay. Update every construct site (herdr.rs, runtime.rs, project.rs, profile.rs, filesystem.rs, git.rs, herdr/process.rs, herdr/terminal.rs, handler/updater.rs, tests/common, error unit tests).

4. Update live docs and tests that pin the old names

   • Rewrite docs that still say handlers keep create_pty_session / handler/pty.rs / PtySessionRecord: docs/api-reference.md, docs/architecture.md (drop “Existing IPC names stay” for these commands), docs/data-flow.md, docs/herdr-integration.md (command/DTO names and handler/pty.rs links only), plus AGENTS.md / CLAUDE.md copies that list the PTY command table (src-tauri/AGENTS.md, src-tauri/src/handler/AGENTS.md, src-tauri/crates/model/AGENTS.md, src/features/terminal/AGENTS.md and their CLAUDE.md twins; keep the two copies in each directory in sync).
   • Do not keep live docs advertising deleted get_pty_session_history / restore_pty_session just so an absence-assert still matches. Update docs_client_mode.rs to pin the new command/DTO names and a durable “no sqlite history restore command” invariant that does not require the docs to name a deleted *_pty_* IPC.
   • Rewrite herdr.rs source-string tests that include_str! handler/pty.rs and assert scroll_pty / detach_pty_output to the new path and names. Keep proving stream_herdr_output / HerdrTerminalFrame / stream_id pairing.
   • Historical Diesel migration filenames and SQL table name pty_sessions stay. Do not rename or edit src-tauri/migrations/. Do not rewrite integration_migrations.rs / DROP-table asserts in integration_pty_db.rs / db.rs that must still query the applied table name. That leftover vocabulary is Task 3, not this rename.
   • Do not edit openspec/changes/archive/.

5. Prove without swallowing Task 2 or Task 3

   • App still builds. Existing suites pass with unchanged behavior: New Tab is still Herdr tab.create returning pane_id; write/resize/scroll/close/attach/detach still hit the same RuntimeRouter methods; Herdr-down still fail-closes; restore is still reattach of a live pane_id; projects still round-trip in sqlite.
   • Do not delete TWOCODE_RUNTIME comment/test/doc traces (Task 2). Do not add the repo-wide grep lock that fails on any live pty / TWOCODE_RUNTIME (Task 3). After this branch, live IPC/modules/DTOs/frontend callers must not say pty; leftover DROP-table / “no portable-pty” / TWOCODE_RUNTIME strings may remain until later tasks.
   • If line count grows past the estimate, open a tracking issue; do not fold Task 2 or Task 3 into this branch.

Likely files and directories

• Rename: src-tauri/src/handler/pty.rs → handler/terminal.rs; src-tauri/crates/model/src/pty.rs → model/session.rs.
• Update: src-tauri/src/handler/mod.rs, src-tauri/src/lib.rs, src-tauri/crates/model/src/lib.rs, src-tauri/crates/model/src/error.rs.
• Update: src-tauri/crates/service/src/runtime.rs, src-tauri/crates/service/src/runtime/herdr.rs, plus PtyError construct sites in project.rs / profile.rs / filesystem.rs / git.rs / herdr/process.rs / herdr/terminal.rs / handler/updater.rs / tests/common.
• Update frontend: src/features/terminal/hooks.ts, Terminal.tsx, TerminalTabs.tsx, lib/terminalTransport.ts, restoration.ts, colocated tests, src/test/setup.ts.
• Regenerate: src/generated/commands.ts, src/generated/types.ts via typegen.
• Update docs: docs/api-reference.md, docs/architecture.md, docs/data-flow.md, docs/herdr-integration.md (names/links only), AGENTS.md / CLAUDE.md copies listed above.
• Update tests: herdr.rs handler include_str! guards, docs_client_mode.rs, error Display tests.
• Do not change: src-tauri/migrations/, sidecar pin v0.9.0, Settings runtime toggle (gone), Git/file-tree/notes/tab UI, lib.rs naming HerdrRuntimeSync, flattened-split mapping, Diesel schema, TWOCODE_RUNTIME traces, a new repo-wide pty grep audit.

Estimated changes: 500–900 lines total, additions plus deletions, including tests and docs; excluding generated files, lockfile churn and binary artifacts. Material scope growth (Task 2 flag purge, Task 3 audit lock, rewriting DROP-table migration tests) should become a separate issue.

Acceptance criteria

• Live session-layer identifiers no longer use pty: no handler/pty.rs, model/pty.rs, create_pty_session / write_to_pty / resize_pty / scroll_pty / close_pty_session / attach_pty_output / detach_pty_output / flush_pty_output / clear_pty_output, no PtySessionRecord / PtySessionMeta / PtyConfig, no AppError::PtyError, no createPtySession / writeToPty / … callers.
• Replacement names are terminal/session (handler/terminal.rs, model/session.rs, create_terminal_session, TerminalSessionRecord, AppError::TerminalError). list_project_sessions, stream_herdr_output, and get_session_* / stream_session_agent_status stay. Session id is still a live pane_id; profile_id is still workspace_id.
• src/generated/ and every frontend caller moved in the same commit. The app builds. New Tab / write / resize / scroll / close / attach / detach / restore behavior is unchanged. Same clicks and labels.
• Live docs no longer say handlers keep the old *_pty_* IPC names. docs/architecture.md no longer claims those IPC names stay. AGENTS.md / CLAUDE.md copies stay in sync. Docs/tests do not keep naming deleted get_pty_session_history as current vocabulary.
• No behavior change. No Local adapter / portable-pty spawn / env-flag backend. sqlite profiles is not source of truth. projects still round-trip in sqlite. No second events.subscribe. lib.rs still does not name HerdrRuntimeSync. v0.9.0 pin unchanged. GUI exit still does not server stop.
• Named UX exceptions: none new. Existing Herdr-backed exceptions stay (route ids workspace_id; tab ids pane_id; splits flattened as extra tabs; non-git New Profile is folder workspace.create; Herdr-down New Tab errors). IPC rename is not a click/label redesign. Display prefix PTY error: → Terminal error: is vocabulary, not a GUI exception.
• Migrations under src-tauri/migrations/ are untouched. DROP-table tests that query sqlite table name pty_sessions may still say that applied name (Task 3). TWOCODE_RUNTIME traces are not deleted (Task 2). No new repo-wide pty/TWOCODE_RUNTIME audit test (Task 3).
• Tests: cargo test --workspace from src-tauri (or cargo test --workspace --exclude code where GTK is unavailable). Frontend lint/typecheck/tests for terminal hooks/transport/Terminal/restoration scope. bun run typegen if IPC signatures change; do not hand-edit src/generated/.
• No push. No pull request.

Out of scope

• Parent-plan Task 2 (delete every TWOCODE_RUNTIME trace) and Task 3 (prove-and-lock audit).
• Renaming or editing files under src-tauri/migrations/. Rewriting migration-history tests whose SQL must use the applied table name pty_sessions.
• Reintroducing a Local adapter, Settings runtime toggle, portable-pty spawn, or sqlite profiles / pty_sessions authority.
• Changing the Herdr-only runtime decision, the v0.9.0 pin, GUI exit / server stop, flattened-split mapping, or Git/file-tree/notes/tab UI.
• Implementing or closing Plan: migrate 2code to Herdr-backed architecture #394 / Plan: 2code as a Herdr client (profiles derived from Herdr) #436 / Plan: close out the Herdr client migration (gap verification, docs, tracking) #458 task tickets or leftover gaps Herdr v0.9.0 has no Windows live terminal attach (Task 10 gap) #396 / Herdr v0.9.0 has no create-time startup command (Task 17 gap) #397 / Live Herdr agent detection not verified on v0.9.0 (Task 13 gap) #398 / Windows named-pipe JSON transport not verified for Herdr v0.9.0 (Task 5 gap) #399 / macOS Unix sockets and terminal session attach not verified for Herdr v0.9.0 (Task 5/10 gap) #401.
• Opening a pull request.

Standing constraints

• No behavior change. This is a rename and a documentation/test cleanup. Same IPC semantics, same clicks and labels.
• No Local anything. Do not reintroduce an adapter, env flag, CLI flag, dependency, or fallback path, not even behind a cfg or a comment.
• Migrations are history. Do not rename or edit files under src-tauri/migrations/.
• Frontend callers move with the commands. If an IPC command is renamed, update generated bindings and every caller in the same commit so the app still builds and behaves identically.
• Do not treat sqlite profiles as source of truth. projects stay in 2code sqlite.
• Never let Local and Herdr own the same worktree (Local is already removed; do not bring it back).
• Default-runtime switch and deleting Local/PTY/profiles rows already shipped in Plan: 2code as a Herdr client (profiles derived from Herdr) #436; this task does not re-litigate those decisions and does not change them.
• Do not change interaction unless the old UX cannot be backed by Herdr. This task has no named interaction exception.
• One task; stack on task-3-line-count-trackers. Do not push. Do not open a PR.

Why this is next

#463 has three tasks. None are done and none have sub-issues. Task 1 is the session-layer rename; Tasks 2–3 depend on the live IPC/modules no longer being named pty. The leftover open gaps (#396/#397/#398/#399/#401) are Linux-unverifiable or upstream-capability leftovers, not in-flight replacements for this work.