AgentHub/docs/plans/workspace-rename

Retiring the old name "lane" from the CLI and API

Phase 0 (docs/plans/workspace-redesign/00-rename-lane-to-workspace.md) changed the word in the UI and docs only. This plan takes the user-facing NAMES of the CLI and API the same way, in four steps spread over releases so nobody is broken by an update and nothing stored is touched.

R = the first release after v2.0.1 that ships steps 1–3 (write its version here when it is cut: R = v2.1.0).

Steps

#	What	When	Status
1	Aliases: /api/workspaces = /api/lanes (same two routers mounted twice, server/index.js LANE_MOUNTS); agenthub workspace/workspaces = agenthub lanes (COMMAND_ALIASES/canonicalArgv in bin/agenthub.js); --workspace <id> = --lane <id> (resolveLaneArg).	R	done
2	Help, usage and hint text, the UI's command hints and the user docs say agenthub workspace … / --workspace; docs/API.md documents both paths.	R	done
3	Deprecation: agenthub lanes or --lane prints ONE stderr line naming the new spelling (warnOldNames), stdout unchanged; the help footer and docs/CLI.md call them the old names.	R	done
4	Remove the old CLI names (below).	not before R+3	open

Three releases is the window for an install to update gradually: anyone who runs the CLI in that time sees the step-3 note on every old-name call, and a release that skips straight from < R to ≥ R+3 still gets a clear error (4a), never a silent change of behaviour.

Step 4 — what it does

4a. CLI (do this).

• agenthub lanes … no longer runs; it exits 1 with renamed: use agenthub workspace … (not "Unknown command", and not help).
• --lane <id> exits 1 with renamed: use --workspace <id>.
• The handler is renamed workspace in runCommand; COMMAND_ALIASES keeps only workspaces → workspace; warnOldNames goes away.
• Tests: lanes-cli.test.js "agenthub workspaces" suite flips to assert the refusal; every remaining cli(["lanes", …]) call in the server suites moves to workspace.

4b. Client and CLI requests move to /api/workspaces (do this).

• client/src/lib/api.ts (and the ~105 /lanes… request paths) and the 29 /api/lanes calls in bin/agenthub.js switch to /api/workspaces. Safe at R+3 because every server ≥ R answers it — a CLI updated before its server restarted (installed_not_running) is talking to a server ≥ R by then.

4c. The /api/lanes mount — decide at R+3, default KEEP. Removing it saves one array entry and breaks every user script, bookmark and cached browser tab that still names it. Keep it as a silent, undocumented compatibility path unless there is a concrete reason. If it is removed, answer 410 Gone with {error:{code:"ERENAMED", message:"use /api/workspaces"}} for one more release before dropping it.

What step 4 must NEVER touch (no data loss)

Step 4 renames only how a request is ROUTED. Nothing below is renamed, moved or migrated — they are where users' data and running work live:

• SQLite: tables lanes, lane_sources, lane_features, lane_stage_events; columns lane_id, needs_action_session, …; no table rename, no column rename, no migration.
• JSON keys in API responses (lane, lanes, lane_id, counts) and the WebSocket message types — an older client or script reads them.
• tmux session names agenthub-lane-<id> / agenthub-lane-<id>-<slot> — renaming orphans every live pane (Stop/Reset could no longer reach it).
• Env vars AGENTHUB_LANE_ID, LANES_ROOT, LANE_DEAD_SEC, LANE_BRANCH_PREFIX — a pane started before the update still carries them.
• On-disk paths: LANES_ROOT (~/.claude/agenthub-lanes/, managed worktrees), LANES_ROOT/.state/lane<slot>/, <data dir>/workspace-context/<lane id>/, <data dir>/workspace-prompts/<lane id>.md, .agenthub/profile/.
• Browser storage keys (agenthub.workspace.*, agenthub.sidebar.*) — a rename resets everyone's layout and order.
• Error codes (EBADLANE, ERUNLIVE, …) and file/component names.

Release checklist for step 4

1. package.json version ≥ R+3 (count R from the table above).
2. Release notes, EN + VI, top of the list: "agenthub lanes and --lane are removed — use agenthub workspace and --workspace. Your workspaces, sessions and history are unchanged."
3. grep -rn "agenthub lanes\|--lane\b" skills plugins docs README* INSTALL.md finds nothing outside docs/plans/ (a shipped skill calling the old name would break the moment the plugin updates).
4. Pipeline templates are user files (DASHBOARD_PIPELINES_DIR) and may run agenthub lanes hook … as a node command: the release note says so, and the 4a error names the replacement, so the failing node tells the user what to edit.
5. Both suites green; open an existing install's DB before and after the update and compare SELECT count(*) FROM lanes / sessions / events — step 4 must not change a single row.