# 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.