# Workspaces A session workspace identifies the directory where its work runs. The daemon represents it as a local path or an SSH location. [Worktrees](worktrees.md) are separate checkouts that can supply a workspace. ## Locations [`location.parse`](../src/albedo/harness/location.gleam) accepts local strings beginning with `/` or `~`, and remote locations of the form `[user@]host:/absolute/path`. Bracketed IPv6 addresses are supported. Remote paths are normalized lexically. This does not resolve filesystem links. User and host names must begin with a letter or digit. `location.workspace` validates an existing local directory when a session is created or moved. It resolves remote `~` through SSH, but accepts an absolute remote path without checking its existence at that point. A later operation can fail when the host or directory is unavailable. `location.exists` observes a local or remote folder without opening it. An unreachable host returns an error, not a missing-folder result. The remote probe and gather retain their separate time bounds. ## Path completion `GET /sessions/{session_id}/file-paths?query=&limit=8` (capability `file_path_completion: 1`) returns `{items: [paths], truncated}`. [`daemon/file_paths.gleam`](../src/albedo/daemon/file_paths.gleam) owns matching and ranking; `http_resources` resolves the stored session workspace. Bare queries search that workspace and return relative paths. Starting `~` or `~/` anchors at the session host's home, `./` at the workspace, and `/` at that host's filesystem root. The directory through the last slash is a literal scan root; only the remaining tail fuzzy-matches descendant relative paths. Results retain that directory prefix (`~` becomes `~/`). No `~user` expansion is performed. A missing directory fails without broadening the search. Explicit `./../` is allowed: completion is not a workspace sandbox. Local enumeration belongs to `daemon/file_paths.gleam`; remote enumeration uses the existing SSH gather route `file-paths`, including home expansion on that host, never a local fallback. Enumeration uses ripgrep (`rg --files --hidden --no-require-git`), respecting ignore files, excluding `.git` and `.jj`, and not following directory symlinks. Ripgrep must be installed on the workspace's machine; otherwise the request fails `503 workspace_unavailable`. Commands stop after two seconds or 2 MiB of path output, retaining at most 20,000 candidates. Only complete UTF-8 paths of at most 4096 bytes are kept. The output/candidate cap sets `truncated`; the bounded subset need not contain the globally best match when the tree exceeds a cap. Ranking within that subset is deterministic. A timeout fails rather than pretending there are no matches. Anchored scans that encounter filesystem errors after emitting paths return that partial subset as truncated; errors without paths still fail. Bare workspace queries retain their strict error behavior. Bare `/` and `~/` may hit the same caps or timeout; supplying a directory narrows enumeration before it starts. There is no retained index or session-turn work. Queries are case-insensitive subsequences, ranked by matched positions and remaining length, then lexicographically. Empty queries list shortest paths first. `limit` is 1–50; queries accept at most 256 UTF-8 bytes and no NUL. The endpoint never reads file contents. CLI and web replace an `@` token with a plain path (JSON double-quoted when it contains whitespace), preserving the rest of the draft; submission and attachments are unchanged. The [terminal](tui.md#file-path-completion) and [web](web.md#file-path-completion) clients expose this as composer suggestions. ## Linked workspaces [`links`](../src/albedo/harness/links.gleam) stores workspace group membership. Linked workspaces retain their own data while group readers can include the other members. Linking and unlinking are separate from creating a [worktree](worktrees.md). The links extension owns membership changes and session notifications. See its [service](../src/albedo/harness/extensions/links/service.gleam) and [ledger](../src/albedo/harness/extensions/links/ledger.gleam). Group reads also include managed worktrees of each origin, as `links.members` shows. The ledger declares `workspace_links` with its revision tables, because the extension's initialiser creates it through `links.apply` and its ledger writes it. ## Moving a session [`session_workspace`](../src/albedo/daemon/session_workspace.gleam) records workspace changes and tracks their application to family members. A session configuration change and its application are distinct outcomes. The [session configuration owner](../src/albedo/daemon/session_configuration.gleam) and [session workspace owner](../src/albedo/daemon/session_workspace.gleam) govern the persisted state. Moving a session between daemons is a separate transfer. [`transfers`](../src/albedo/daemon/transfers.gleam) owns export and import, and [`http_transfers`](../src/albedo/daemon/http_transfers.gleam) defines the HTTP routes. [`transfer/codec`](../src/albedo/transfer/codec.gleam) owns the segment format and streams rows through SQLite statements prepared on the caller's connection. Its module comment defines the cell encoding. Keep segments byte-identical across changes. The golden case in [`transfer_codec_test.erl`](../test/harness/transfer_codec_test.erl) pins the bytes and digest of a known export. Transfer adapters declare which extension data travels. See [carry rows when a session moves](../docs/extensions.md#carry-rows-when-a-session-moves) for an adapter's tables, shifts, and activation. A transfer is not ongoing synchronization between the daemons. After a move, extensions reach the session's new daemon through `host.Context.ask_moved`, and refuse arrivals for it through `extension.Daemon.tell_refused` and `hook_gone`. These callbacks keep relay and refusal behavior with [`moves`](../src/albedo/daemon/moves.gleam). Each owner keeps its stored states as a type with one codec for the stored and HTTP spelling. `transfers` owns `TransferState` and `TransferRole`, and `moves` owns `MoveState` and the binding status. A move reads the target's import state through `transfers.parse_state`. Build SQL state literals from the codec, and do not match a state's name in text. ### Moves between versions Moves between daemons of different builds are supported in one direction only, from an older daemon to a newer one. Both must speak the same `transfer.protocol`. The source checks the target's protocol before it exports. A move to an older daemon is unsupported when the carried schema differs. The export lists every carried table and every column in the manifest, including empty tables. An older target does not know a table or column added since its build. It refuses the manifest at staging, in `transfers.known`, when a segment: - names an extension the target lacks (`transfer_unsupported`), or one built in there that failed to load (`transfer_extension_unavailable`; older targets answer `transfer_unsupported`) - names a table that extension does not carry there (`transfer_unsupported`) - has a different table version (`transfer_version`) - has a column the target's table lacks (`transfer_version`, as `owner/table here lacks column`) The source keeps the target's detail, which names the first thing it lacks, and reports `transfer_version` as `transfer_target_older` (`relays.staged`). It keeps `transfer_unsupported`, because a target from before `transfer_extension_unavailable` gives it both for an older build and for an extension that failed to load. The move then fails before anything goes live on the target, and before the target writes a receipt or staging directory. The source keeps the session, its bindings stay armed, and it still takes input. The preflight asks the target before a move starts, through `POST /transfers/check` ([`transfers.check`](../src/albedo/daemon/transfers.gleam)). The source sends `transfers.shape`: every table the export would list, with its version and this daemon's columns, without rows. It also sends one file entry for each owner that carries files and no tables, such as memory, when that owner has files to send. The target runs the same `known` checks and nothing else. It reads table columns, and writes no receipt or directory, runs no expiry, and checks no space. The check knows which extensions are quarantined, so the source reads a missing extension or table from it as `transfer_target_older` (`relays.checked`), and `transfer_extension_unavailable` stays as it is. Either makes the preflight unavailable with that `code` and the target's detail. A target from before the route answers 404 or 405. The preflight then offers the move, and staging refuses what that target lacks. Clients read these codes for a person and keep the target's detail as secondary text. `transfer_target_older` asks to update albedo on the target. `transfer_extension_unavailable` says the extension failed to load there, with no update advice. `transfer_unsupported` names both causes. See the [terminal client](tui.md#moving-a-session) and the [web client](web.md#moving-a-session). The daemon has no ordered version to compare. `/server` reports a build label and digest, which tell two builds apart but not which is older. The schema checks are what decide. Keep older-to-newer moves working: - Keep adapter names stable. The target finds a segment's adapter by its owner name, so a renamed or removed adapter refuses segments from older daemons. - Keep the segment format byte-identical, as the [codec](#moving-a-session) requires. - Do not bump a carried table's version. The target accepts only its own version, so segments from older daemons would be refused. - Settle rows imported from an older daemon in the adapter's `activate`, as webhooks does. [`move_versions_test.py`](../test/e2e/move_versions_test.py) moves a session from a pinned older build to this checkout, and checks that the reverse move is refused cleanly. [`move_test.py`](../test/e2e/move_test.py) checks that the preflight refuses a target of this build that lacks a column, and writes and expires nothing there. [`transfer_check_test.gleam`](../test/daemon/transfer_check_test.gleam) covers each refusal code, including a quarantined extension. See [mixed-version moves](testing.md#mixed-version-moves). Starting an older daemon on a whole home that a newer one upgraded is a different case. See [downgrades](migrations.md#downgrades). ## Browsing [`folders.directory`](../src/albedo/daemon/folders.gleam) returns a directory listing for the folder picker. The same module owns file reads and existence checks. Remote locations use the location and SSH handling in that module, so an unavailable host is a distinct failure from a missing local directory. ## Related pages - [All topics](README.md) - [Change guidance](contributing.md) - [Worktrees](worktrees.md) - [Session attachment](sessions.md) - [Test execution](testing.md) - [Terminal client](tui.md) - [Web client](web.md)