Workspaces #
A session workspace identifies the directory where its work runs. The daemon represents it as a local path or an SSH location. Worktrees are separate checkouts that can supply a workspace.
Locations #
location.parse 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=<text>&limit=8 (capability
file_path_completion: 1) returns {items: [paths], truncated}.
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 and web clients expose this as composer suggestions.
Linked workspaces #
links 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.
The links extension owns membership changes and session notifications. See its
service and
ledger. 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 records
workspace changes and tracks their application to family members. A session
configuration change and its application are distinct outcomes. The
session configuration owner
and session workspace owner
govern the persisted state.
Moving a session between daemons is a separate transfer.
transfers owns export and import, and
http_transfers defines the HTTP
routes. transfer/codec 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 pins the
bytes and digest of a known export. Transfer adapters declare which extension
data travels. See
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.
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 answertransfer_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, asowner/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). 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 and the
web client.
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 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 moves a session
from a pinned older build to this checkout, and checks that the reverse move is
refused cleanly. 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 covers
each refusal code, including a quarantined extension. See
mixed-version moves.
Starting an older daemon on a whole home that a newer one upgraded is a different case. See downgrades.
Browsing #
folders.directory 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.