Public API

The launch mode one create takes: the request's choice, else this entry's.

choice is CreateWorkspaceRequest.native; None means the caller left it to the roster. The kind gate applies to both roads, so a checkbox on a shell entry cannot ask for a protocol that does not exist.

Store one file for this workspace and say where the AGENT will find it.

Attachments land under the worktree (.grove/attachments/) for one reason that decides everything else: the worktree is the only directory a host process and a containerized agent both see, so a host temp directory would be an address half the fleet could not open. The translation into the agent's namespace is the same re-rooting GROVE_PHASE_FILE gets, and it happens HERE rather than in the store because only the workspace record knows whether there is a container to translate for.

The git exclude is re-asserted on every upload rather than only at create. That is not defensiveness: a workspace that predates this feature has no such exclude, and its first attachment is the moment an untracked file starts blocking its own pause and kill.

Loud by contract, unlike the read paths: an over-size payload (GroveError) or an unwritable worktree must never report success and leave the agent pointed at a file that is not there.

Start ANOTHER agent inside this workspace's container. Returns it.

The whole of the user's ask: "multiple Claude Code instances can also run within the same container if necessary by the person of choice". Never automatic — no lifecycle verb calls this.

The launch is composed through exactly the seams the workspace's own agent uses — _compose_launch for the decoration (session id, hook settings, channels, model, the trailing prompt positional) and _launch_env for the hermetic env — so the second agent is configured identically to the first and the two cannot drift. It differs in three things only: its own in-container session name, -A -d (start it, do not drop the caller into it), and no remain-on-exit. That last is deliberate and follows the rule story 3 established: keeping a corpse is only safe where something owns the clearing, and for the primary agent the launch backend owns it. Nothing owns it here, so an additional agent that exits leaves no session — which container_agents then honestly stops listing.

Not persisted, and that is the design rather than a shortcut: the agent's transcript reaches the workspace's agent axis on its own, since the existing discovery/adoption path adopts any session of the workspace's kind born in its cwd after it was created (see ActivityService.sessions_for). The one honest limitation: an agent of a DIFFERENT kind from the workspace's is not surfaced there, because that scan is kind-scoped on purpose — it runs, it is listable, attachable, peekable and steerable, but the workspace card stays about the workspace's own kind.

A remote-steered kind is refused: a mewbo session runs on a backend, so "add one to this container" names nothing.

How this workspace's agent command exited, or None if it has not.

THE dead-agent seam the activity blend reads, with one answer per runtime because the two record the fact in different places:

• A pane-hosted agent on this host writes its status into a file the launch installed a recorder for.
• A containerized agent under an in-container tmux is the pane's OWN process, so tmux itself holds the fact: remain-on-exit keeps the dead pane, and #{pane_dead_status} is the code. The shell recorder cannot see this — it captures the exit of what the HOST pane ran, which under tmux is the tmux client, so an agent dying inside a live session recorded nothing. That narrowing is what this restores.

Absence keeps meaning "the agent has not exited" on both roads, which is what keeps a slow start from ever reading as a failure: an unreadable docker, a session that is simply gone, and a healthy agent all answer None. Never raises — the caller is a per-tick render path.

Answer a pending question by DISMISSING it and restating the batch as text.

Grove used to drive the provider's own question widget by keystroke, and the cost of that was structural rather than incidental. A picker is a stateful TUI, so a digit's meaning depends on what is currently painted; every provider paints something different; and a batch of four questions with a tab strip and one shared Submit has no keystroke grammar that a second provider shares. The measured failure was the worst possible shape — answers silently mapped onto the wrong questions while the request reported success.

So the widget is not driven at all. Escape takes the provider's own cancel route, the whole batch is rendered into one Grove-fenced message, and that message goes down the ordinary steering path. What is left is provider-neutral by construction: every agent Grove can steer can be sent Escape and a line of text, which is why this now works for Codex and for whatever ships next, where the keystroke grammar worked for exactly one build of one tool.

Dispatch semantics, like send_message: this returns once the message is delivered, and the agent's actual response lands later on the transcript. Gates, in order: the workspace must exist (WorkspaceNotFound → 404); session_id must be the session Grove minted for this workspace's pane (QuestionNotPending → 409, else a foreign session_id could steer into the wrong pane); a captured question for session_id must still match tool_use_id (QuestionNotPending → 409, the human may have answered in the terminal); the plan must fit the captured questions (QuestionAnswerInvalid → 422); a pane must resolve (PaneNotFound → 409).

The capture is re-checked immediately before the send to shrink — never close — the terminal race. Losing that race is now benign in a way it never was under keystrokes: if the human answered a moment earlier, the Escape hits a composer that has nothing to cancel and the text arrives as an ordinary steering message, which is a duplicate answer rather than a wrong one.

Where the client should attach, and to WHOSE multiplexer.

Two arms, chosen by the one predicate the launch already branches on — whether this workspace's container can run a tmux (_container_tmux, i.e. ContainerRuntimeState.tmux_command):

• Container — the container's own tmux owns the session, so the client execs straight into it. There is deliberately no host session to target: a host pane running devcontainer exec … tmux attach is a shadow client that clamps every later client's terminal size to its own (measured: a client asking for 200x50 got 161x41).
• Host — every host workspace, and the container that has no tmux inside it, where the agent really does run in a host pane.

The container argv is composed from the SAME :class:~grove.core.container_agent.ContainerAgentEntry that starts the agent, so the way in cannot drift from the way it was launched.

A NATIVE workspace attaches READ-ONLY on both arms: its pane is Grove's worker printing the session's protocol frames, so a person can watch the wire but a stray keystroke can never reach — or kill — the one process holding the control channel. Steering goes through the verbs.

Attach whatever a human typed — a URL, #42, 42, owner/repo#42.

The one seam between raw text and :meth:attach_ticket: the repo's provider registry resolves the link (inferring provider and issue-vs-PR) and the attach itself is unchanged, so every surface that accepts a pasted link gets identical parsing, identical ambiguity refusal, and identical idempotency. Raises TicketLinkError / TicketLinkAmbiguous before touching the store.

Manually associate a ticket with a workspace (the branch-parse override).

Idempotent by (provider, id): re-attaching the same ticket is a no-op. A pull request is attached the same way, by the same selector carrying kind="pull_request" — one list, no parallel PR surface. The key stays (provider, id) because that is what the forge links on, so re-attaching a ref whose kind was wrong (a branch parse assumed issue) CORRECTS it in place rather than silently keeping the stale kind or growing a duplicate row.

The ref is stored bare (provider + id + kind) — display enrichment (title/status) is the daemon's on-demand fetch, never persisted here, so attach stays pure and offline-safe. Permitted in any status except ORPHANED (same gate as update — a doomed record gains nothing).

Seeds the phase file with an entry for the newly attached key (:meth:PhaseFile.seed, best-effort) right after the store save, so an agent that attaches a ticket mid-task finds the key already there instead of composing it. Deliberately NOT mirrored on :meth:detach_ticket — see that method's docstring, and :meth:PhaseFile.seed's, for why a detached entry is left standing.

Use daemon-maintained runtime facts instead of render-path probes.

The source owner supplies an explicit initial witness before binding; a None result remains an unreadable boundary, never an absence claim. Standalone managers deliberately retain the existing direct probes.

Whether :meth:send_message could deliver to state right now.

The mailbox's whole admission rule, and it is deliberately the same predicate steering already enforces rather than a second opinion about liveness — a contact the directory advertises must be one the send can actually reach. Takes a reconciled state, so a listing pays no second reconciliation per row.

A native workspace whose owner has died still answers True: the steer path revives it (_revive_for_steer), so refusing here would hide a peer that one message brings back.

Comprehensive commit history for a workspace, newest first.

git log <diff_base>..branch — every commit made in this workspace since it was created. The anchor is the commit recorded at create (WorkspaceState.diff_base), NOT the base branch: for a ROOT workspace the branch and the base branch are the same ref, so the branch-derived range collapsed to empty however much work was done. Distinct from peek.recent_commits which walks all of branch history (no fork-point filter) and is capped at 3 for the TUI's tight rail.

A record with no recorded anchor is answered by TIME, not by a ref. diff_base's fallback is base_branch, and this is the one consumer for which that degradation does not survive contact with ROOT placement: a root workspace's base_branch is the literal "HEAD", so the range collapses to empty however much work happened, and the card then prints a confident false claim ("no commits on this branch yet") rather than a degraded one. Reproduced on this repo's own root workspace: 0 commits from the ref range against 106 from the --since form. So a null anchor takes branch_commits_since(branch, created_at) — a recorded fact answering a different, well-posed question — and the answer says which question it was via CommitScope, because the count errs high. With an anchor present nothing changes: diff_base IS base_commit there, so the call is byte-identical to what it always was.

A merge-base backfill stays refused, for the reason this module already records: it would be indistinguishable on the wire from a recorded fact. A timestamp is not, and never claims to be the anchor.

The window is taken only where the ref range CANNOT answer, which is a property of the refs and not of the record's shape. On a legacy Grove-created branch base_branch is a real, different ref and the range is exact, so trading it for a window that can over-report would lose precision this method already had. The test is therefore whether the two ends resolve to the same commit — true for root placement (where base_branch is the literal "HEAD"), and the one condition under which the answer is structurally zero rather than measured. An unresolvable base is degenerate for the same reason: branch_commits could only raise on it.

Best-effort: degrades to () on git failure, mirroring the peek-helpers' never-raise contract for read paths. The daemon's GET /workspaces/{id}/commits is the wire shape consumers receive; the TUI doesn't call this method today (its rail keeps the truncated summary).

The argv that attaches a terminal to one in-container agent.

Returned rather than executed for the same reason attach returns an AttachInstruction: the core does not own the caller's process model — the CLI execvps this and becomes the exec.

The session is verified to exist first, which is what lets the argv omit a command entirely (-A ignores one when attaching anyway) instead of re-deriving an agent command tmux would throw away — and it turns "that agent has ended" into Grove's own sentence rather than tmux's.

Every agent running inside this workspace's container.

Read live from the container's own tmux server, never from the record: that server is the only thing that knows an agent ended on its own, and a persisted roster would be a migration plus a way to be wrong. The workspace's own agent is included and flagged primary, because "what is running in here" that omitted the main one would be a trap.

Raises rather than returning empty when docker cannot be read: an empty roster and an unreadable one look identical to a caller and mean opposite things — the standing rule that "cannot tell" must never be spelled as an answer.

Spin up a fresh workspace from a validated client request.

Validation order (no side effects until all pass):

1. The requested agent must exist in the merged config.
2. The resolved BranchPlan must agree with live git state — per-mode rules in _validate_branch_plan: a NEW name must not collide with an existing branch and the base ref must exist; a CHECKOUT name must exist locally and not already be checked out at another worktree.
3. Worktree → init script → tmux session, in that order, with _rollback_create cleaning up any partial state on failure.

Branch provenance (GROVE_CREATED vs USER_ATTACHED) is derived from the resolved plan and persisted on the state, so kill() later knows whether the branch is safe to delete.

The local branch HEAD points to, or None if HEAD is detached.

Best-effort default branch (origin/HEAD → init.defaultBranch → main).

Remove a ticket association. Idempotent — a missing ref is a no-op.

The adapter kind for state — persisted at create, else config.

Prefers the kind persisted at create (resolves a repo-scoped agent the daemon's global config never loaded); falls back to a config lookup for legacy records written before agent_kind existed, then generic. THE single definition, so the remap/create kind gate and the dashboard can't disagree about what a workspace runs. ActivityService used to carry a verbatim copy (_effective_kind); it was deleted in favour of calling this, because two implementations of "which adapter reads this workspace" is exactly the drift that kind-scoping was cleaning up. Public because SessionExplorer also restricts its per-workspace scan to this one kind, so the picker never offers a foreign-kind session the remap gate below would reject.

Resolve the workspace tracking ticket (provider, ticket_id), if any.

The issue-ops routing seam: "does a workspace already exist for this ticket, so steer it instead of creating a new one." Scans list() (already reconciled to each workspace's displayed status) for a ticket_refs match — no new persisted state, no separate index.

kill() deletes the persisted record outright rather than marking it KILLED, so a killed workspace can never surface here — "the newest non-killed match" is true of everything list() returns by construction. When more than one live workspace tracks the same ticket (hand-attached twice, or a fresh workspace opened for a ticket an older one already tracks), the tie-break is the NEWEST by created_at — the most recent workspace is the one issue-ops should steer.

Interrupt one supported agent without sending a process signal.

Claude Code's REPL routes Escape to its abort controller, the same path its native remote-control interrupt frame uses. A pending permission prompt instead takes its onAbort() path, so Escape's effect is deliberately state-dependent. SIGINT is never used: Claude Code has no interactive SIGINT handler and the signal can kill the session. Other tmux-hosted kinds retain SteeringUnsupported rather than receiving a guessed cancel key.

Invoke a named session control — a slash command or a skill.

Thin trigger: composes the tool's /name invocation and delivers it through the EXISTING steer path (:meth:send_message → tmux keystroke / native channel / remote), so it reuses the whole dispatch, the settle window, and the audit trail rather than adding a second delivery mechanism. Kind-gated to the tools that actually expose a slash-control surface (_CONTROL_KINDS); a generic shell or a remote orchestrator raises CapabilityUnavailable (well-formed, but the runtime can't act on it). Best-effort dispatch semantics like send_message — 204/return is "delivered", not "ran".

Tear down the workspace's tmux session (always) and worktree.

For worktree placement the worktree is always removed; the local branch is deleted only when delete_branch is True. Default (None) resolves from state.branch_provenance: GROVE_CREATED → True (Grove made the branch; safe to drop), USER_ATTACHED → False (the user's pre-existing branch stays).

For root placement the worktree IS the repo root and the branch is the live checkout, so kill never removes the directory and never deletes the branch — even if the caller passes delete_branch=True. It only stops the session and forgets the record.

Remote branches are never touched. Period — there is no flag to opt into remote deletion. That's git push --delete territory and stays in the user's shell, with their own credentials. Best-effort on each step; a failure on one stage does not prevent later stages from running — but it IS reported: the killed event's branch_deleted is the outcome (not the request) and a residue key names every stage that failed, because the record that could otherwise be used to find the leftovers is deleted a line later.

One failure is not forgiven: a container teardown that did not happen. Every other stage fails toward something the user can still see and fix by hand — a worktree on disk, a branch that stayed. A container Grove cannot remove is nameable only through this record, so deleting the record would leave it running and unreachable forever. The workspace is kept as ERROR carrying the reason and this raises instead.

End one ADDITIONAL agent's in-container session. Idempotent.

Refuses the workspace's own agent by name: that one has lifecycle verbs of its own (pause / respawn / kill), which also deal with the container, the worktree and the record — ending its session from here would leave the workspace looking alive with nothing in it, and no verb would report why.

The workspace's current task text, UNCAPPED — the engine seam the issueops sticky-comment publisher reads in-process.

The :meth:latest_todo sibling in every respect: same :meth:_todo_session_id resolution (NOT agent_session_id alone — codex mints no id and a rotated claude id is a dead pointer), same AgentSessionNotFound on a genuinely sessionless workspace so a caller that NAMED a workspace can tell 404 from "a session exists and carries no task text yet" (None), same best-effort adapter read.

The text is the one AgentActivity.current_task carries, minus the adapters' _TASK_TEXT_CAP truncation. The wire field stays capped: it rides the ~1 Hz activity delta for every workspace on the host plus every TUI row and webapp card, where an arbitrarily large pasted prompt is a real cost. A reader that renders the text ONCE per flush — the sticky comment, inside a collapsed <details> — pays nothing for the whole text, so it reads it here instead of re-deriving a truncated one.

:meth:latest_task for a state a caller ALREADY holds reconciled — the :meth:latest_todo_for split, for the identical reason.

Degrades to None for a sessionless workspace rather than raising (the 404-vs-None distinction is the id seam's contract), does NO discovery of its own (a scan per workspace per tick is the daemon-CPU bug the transcript cache exists to prevent), and reads transcript_scan_cwds[0] because both filesystem adapters resolve a transcript by globbing the session id. Scoped, like every transcript read here: an unscoped read on a profile-pinned workspace answers None and the sticky comment silently drops the task line.

The workspace's current todo/checklist state — the engine seam both the issueops sticky-comment publisher (in-process) and the GET /workspaces/{id}/todo daemon route read.

Resolves the workspace's session through :meth:_todo_session_id — which is NOT agent_session_id alone: a codex workspace mints no id at all and a rotated/ended claude id is a dead pointer, so keying the axis on the mint made it blank for a whole provider. RAISES AgentSessionNotFound only when neither the mint nor discovery names a session — the same convention _steer_remote/_steer_native use, so a caller can tell "no session yet" (404) apart from "a session exists but no todo tool has been called yet" (None, a real answer). The adapter read itself stays best-effort (never raises) like every projection here.

:meth:latest_todo for a state a caller ALREADY holds reconciled.

The pane_target/pane_target_for split, for the same reason: the activity poll hands every read its own tick-reconciled WorkspaceState, and an id-taking sibling would re-fetch it from the store and re-run _reconcile_status — per workspace, per tick — for an answer the caller already has. Degrades to None for a sessionless workspace rather than raising: the 404-vs-None distinction is the id seam's contract (a caller that named a workspace is owed the difference), whereas a render path enumerating every workspace only ever wants "nothing to show".

session_id is the session a caller has ALREADY resolved, and passing it is what keeps this seam cheap AND correct. ActivityService hands over the primary its own tick just adopted — which is the codex / dead-pointer answer :meth:_todo_session_id reaches by scanning, for free and one step more accurate (it carries the tick's dead-mint promotion). Omitted, this falls back to agent_session_id and does NO discovery of its own: a scan per workspace per ~1 Hz tick is the daemon-CPU bug the incremental transcript cache exists to prevent, so the expensive arm lives only on the per-request id seam.

The cwd handed to the adapter stays transcript_scan_cwds[0], and iterating the union here would be inert surface: both filesystem adapters resolve a transcript by GLOBBING the session id (Claude across every projects folder, Codex across the date-partitioned tree) and use cwd only to break a tie between files claiming the same id — so a session recorded at the worktree root of a nested workspace already resolves from the first entry. The union matters where the SESSION is being found rather than read, which is _scan_workspace's job.

Scoped. This seam has THREE consumers now — the daemon route, the issueops sticky-comment publisher in-process, and the dashboard card — so an unscoped read here doesn't just blank a panel, it posts an empty checklist into a real issue comment. The adapter read stays best-effort on its own.

Workspaces in this repo, with each persisted intent promoted to its currently-displayed status (ACTIVE / IDLE / OFFLINE / ORPHANED).

Reconciliation calls live tmux + filesystem helpers per running workspace — bounded subprocess work, the same shape we already do for has_session. See _reconcile_status for the policy.

Every local branch in the repo, with HEAD marker, upstream, and checkout site.

Tuple, not list, because the return is a point-in-time snapshot — mutating it after the call would mislead the caller about live repo state. A fresh call rebuilds. Same shape for the remote helper below.

Every remote-tracking branch (excluding origin/HEAD symref).

Begin one revisioned collaboration over an existing worktree diagram.

The descriptor is persisted only after the file has been safely opened. Reopening the active path is idempotent; opening another path is refused rather than silently abandoning a browser that can still autosave.

Resolve the shared pane identity and transport for event observation.

Resolve the tmux target the rail should capture / resize for workspace_id.

Fetches and reconciles fresh from the store — the right call when a caller has only an id. A caller that already holds a WorkspaceState reconciled THIS tick (ActivityService.poll_once/snapshot, off mgr.list()) must use pane_target_for instead: re-reconciling here redid a full _reconcile_status (has_session + list_windows + pane_activity_seconds_ago) that list() had just paid for one line earlier — 3 redundant tmux forks per workspace per poll, ~4 once the target resolution's own list_windows call is added, at fleet scale (24 workspaces, every poll).

Policy (in order): 1. Workspace not RUNNING → None. 2. The agent runs under a tmux INSIDE its container → that session, reached through the container. It is the agent's OWN pane rather than the host viewport onto it. 3. Configured agent_window_name exists → "<session>:agent". 4. Any non-shell window exists → "<session>:<first-non-shell>" (a renamed agent, an init window, etc. — usually where the live work is). 5. Only shell exists → "<session>:shell" (last-resort fallback so the rail at least shows the bare prompt). 6. Session reports no windows at all → None.

Best-effort: tmux.list_windows never raises, so this is safe to call from the peek hot path. Returning None is the contract for "no live pane to look at"; callers should render the empty state.

Resolve the tmux target for a WorkspaceState ALREADY reconciled this tick — the pane_target(workspace_id) sibling for a caller (ActivityService._workspace_activity) that got its state from list() and would otherwise pay for a second full reconciliation to ask the same question list() already answered.

Rich snapshot for the rail: branch metrics, recent commits, and a one-shot agent-pane capture. Recompute it whenever you want a fresh frame; nothing here is cached or animated.

Failures in the underlying git/tmux helpers degrade to zeros / empty rather than raise — peek must never break a render loop. Status reconciliation (RUNNING → ACTIVE/IDLE/OFFLINE/ORPHANED, see _reconcile_status) is applied to the returned state but never persisted — list() does the same promotion for the table.

Tmux-only fast path: just the agent-pane snapshot. Used by the rail's fast pane-tick (~250 ms) so we don't redo git ahead/behind and diff stats — those move at human pace, the pane moves at agent pace. Best-effort: returns (None, None) on any failure or for non-live workspaces.

agent names one of the ADDITIONAL agents a container may host; empty is the workspace's own agent and is unchanged. Naming one on a workspace that cannot host several is a typed refusal rather than a silent empty snapshot — this is the one place best-effort would be actively misleading, because "that agent printed nothing" and "there is no such agent" are different answers a user acts on differently.

A workspace that no longer exists is one of those failures, and it is the ordinary one on this path: the ~250 ms tick fires against whatever the rail last selected, so a kill between two ticks leaves the next one asking about a deleted record. Only the lookup is guarded — the typed refusal above still raises, for the reason its own paragraph gives.

What the harness is holding for this workspace but has not delivered — the engine seam GET /workspaces/{id}/queue reads.

The :meth:latest_todo sibling in every respect that matters, and for the same reasons. Resolution is :meth:_todo_session_id, NOT agent_session_id: codex mints no id at all and a rotated claude id is a dead pointer, so keying on the mint would exclude a whole provider by construction — the exact bug the todo route already documents. AgentSessionNotFound is raised only when neither the mint nor discovery names a session, so a caller that NAMED a workspace can tell 404 from "a session exists and nothing is queued" (an empty tuple, a real answer). The adapter read stays best-effort on its own.

:meth:pending_queue for a state a caller ALREADY holds reconciled — the :meth:latest_todo_for split, for the identical reason.

Degrades to () for a sessionless workspace rather than raising (the 404-vs-empty distinction is the id seam's contract), does NO discovery of its own (a scan per workspace per ~1 Hz tick is the daemon-CPU bug the transcript cache exists to prevent), and reads transcript_scan_cwds[0] because a filesystem adapter resolves a session by globbing its id — and because the codex arm ignores cwd outright, its queue being keyed by thread id in a config-root-global store.

Scoped, like every adapter read here: an unscoped read on a profile-pinned workspace resolves the wrong config dir and answers empty, which on this axis is indistinguishable from "nothing queued".

:meth:phase_for by workspace id — the CLI/MCP read seam.

The agent's own claim about how far through its task it is, or None.

Read from <worktree>/.grove/phase/<workspace id>.json — the worktree root, never agent_cwd, and the two differ for a nested project_subpath. Three reasons, in ascending order of how expensive getting it wrong would be:

1. .grove/ is already a worktree-root concept (it holds the project's committed config.json); a second .grove inside a subdirectory would be a new location a user has to learn.
2. The worktree root is the one directory that is unique per workspace AND is the bind-mount root inside a container, so host and containerized agents name the same file.
3. The git exclude that keeps pause/kill working is ANCHORED. A pattern containing a slash in info/exclude matches only relative to the working-tree root, so .grove/phase/ excludes <worktree>/.grove/phase/ and NOT <worktree>/sub/.grove/phase/ (verified against real git). Anchoring at agent_cwd would therefore leave every nested-project workspace's phase file untracked, and git worktree remove refuses on untracked files — pause and kill would break for exactly the workspaces the subpath feature exists to serve.

The per-workspace key is what stops two ROOT workspaces (whose worktree IS the shared repo root) from overwriting each other; the legacy single file is read only when the keyed one is absent, so a workspace that reported before that layout landed keeps its badge.

Best-effort by contract, like peek: a paused workspace whose worktree is gone, an unreadable file, or an agent's typo yields None rather than breaking a caller's snapshot.

Transcript file(s) for the workspace's agent session, or () if untracked.

Resolves the adapter from the agent's kind and the persisted session id, then asks it to locate the file(s) under the worktree cwd. Read-only and best-effort — the adapter never raises. Empty for a generic/shell agent (no session id), a legacy record, or before the transcript is first written (the STARTING window). The ActivityService builds on this to parse activity.

A tuple (point-in-time snapshot), matching list_local_branches — the files on disk may change after the call, so an immutable return can't mislead the caller about live state.

Honors state.transcript_context: a session launched under a different runtime context records a cwd/config dir the host reader can't guess, so an override substitutes that recorded cwd and scopes the adapter's config-dir env var for this one call. No override (the default) is byte-for-byte the behavior that predates the override.

Kind comes from effective_kind — the persisted-agent_kind-wins rule every other read path follows. A bare find_agent lookup fell to "generic" (blank result) whenever the agent wasn't in this manager's config, which builtin_agents: false and repo-scoped rosters make far more reachable than the legacy-record case it was written for.

How far along this workspace's container provision is.

The id seam over :meth:ProvisionProgress.read, which is the state seam a caller holding a reconciled state should use instead — the pane_target_for / latest_todo_for split, for the same reason: this one re-fetches from the store.

Answers for a FINISHED provision too, and deliberately so: a user who arrives late still wants the log of the build they waited through, and a failed one is exactly when its tail is worth reading.

Whether this workspace's provider can report an empty queue honestly.

Return the current persisted document, never a browser-side draft.

Return the current revision's browser-rendered first-page PNG only.

One workspace with its persisted intent promoted, exactly as list does.

The single-workspace counterpart to list, and it exists because a per-workspace read is now the ORDINARY path rather than a special case: an event-driven projection refreshes one row at a time, where the old poll rebuilt the fleet through list and got reconciliation for free. Reading get there published the RAW persisted status — so a container mid-build showed RUNNING instead of PROVISIONING, and every other computed status (ORPHANED, OFFLINE) was equally unreachable for any workspace the projection had already seen.

Status is the first element of WorkspaceActivity.fingerprint, which is what made this invisible: the row still changed, still emitted, and still looked alive — it was simply answering with a different question's answer. _maybe_emit_status_drift fires here too, so a drift observed through one row is reported exactly as one observed through the fleet.

Manually pin an existing agent session as this workspace's primary.

The trusted-operator counterpart to the automatic discovery/adoption path: when /clear rotated the id (the minted pointer went dead), or a hand-started session should own the card, the user names it and Grove records it as agent_session_id — the very field create() mints — so every read path (the dashboard blend, sessions_for, the CLI inspector) tracks it by construction, no discovery heuristic needed.

Resolution runs through the project's :class:SessionExplorer (resolve accepts a unique id-prefix, scoped to this repo's worktrees), so a typo or a foreign id fails loudly before the write — re-raised as :class:AgentSessionNotFound (404) rather than the bare GroveError resolve emits. Idempotent by resolved id, mirroring attach_ticket: re-pinning the same session is a no-op (no re-persist, no event).

Manual pinning is TRUSTED: unlike discovery it applies no created_at birth-gate — the operator's explicit choice outranks the heuristic, exactly as a grove_launched session is never gated. It DOES enforce adapter-kind equality: pinning a codex session onto a claude_code workspace would leave the workspace's adapter permanently unable to read it (a dead pointer that returns 200) — so a kind mismatch is rejected as AgentSessionNotFound naming both kinds. Permitted in any status except ORPHANED (the attach_ticket gate — a doomed record gains nothing). Emits updated with session_remapped: <id>.

Recover a missing session or explicitly restart a host-native owner.

OFFLINE means the persisted intent is RUNNING but the tmux session has vanished externally (the Grove user closed it, the host rebooted, a peer killed it). The worktree is intact, so we don't touch git — we only spin up a fresh session in the existing worktree and restart the agent. Init script is NOT re-run by default (the worktree was already initialized at create time); set init_script.run_on_resume to opt in for parity with resume. Root placement never re-runs init on respawn even with run_on_resume — init for a root workspace is a deliberate create-time choice and must not fire unattended in the user's real repo root.

Save a browser-rendered first-page PNG only for the current document.

The attachment is intentionally stored only after the active descriptor and raw diagram bytes both match the browser's echoed session/revision. The operation lock makes that pair, attachment publication, and a concurrent stop/reopen one serialized transaction.

Deliver one named key, without interpreting what the application does.

Unlike interrupt's provider-level intent, this requires a live terminal. The caller names only a workspace and a closed enum member: pane and server resolution stay identical to peek and ordinary message delivery. Remote agents must not receive keys in an unrelated local shell.

Type text into the workspace's agent pane and submit it.

Grove's follow-up/steer surface for tmux-hosted agents. Policy lives here; the literal-safe injection mechanism is tmux.send_text. Gates, in order: remote-steered kinds dispatch to the adapter arm; the session must be live (OFFLINE/PAUSED → typed WorkspaceStateError); a pane must resolve via the same pane_target policy peek captures from (None → PaneNotFound).

attachments names files already uploaded through :meth:add_attachment. They are appended to the human's own text as a Grove-fenced block naming each file and its path — the agent reads a file with the tools it already has, so an attachment needs an address rather than a new capability. The client sends IDS, never paths: a path supplied by a caller is a caller choosing what the agent opens.

agent names one of the ADDITIONAL agents a container may host; empty is the workspace's own agent and every gate below is unchanged. A named agent takes the container arm and only that arm: a remote (mewbo) session and a paneless runtime have no container tmux to hold a second agent, so naming one there is refused rather than misdelivered to the primary — which would be exactly the "silently pick one and pretend" this story is not allowed to do.

The message_sent audit event carries the resolved target and the text length, never the content — steering text can hold secrets and events fan out to every subscriber and log sink.

Enumerate the input controls available to this workspace's session.

The read behind the webapp's control panel: TIER 1 filesystem scan via the workspace's adapter (slash commands / skills / MCP servers — cheap, works with NO running session), plus the config-derived model catalog (resolve_models — the single catalog seam every surface shares) and the Grove-hosted permission posture. current_model is a best-effort transcript read (the running session's model), guarded so a parse hiccup just leaves it None.

Best-effort by contract — it feeds a render panel, so a scan/parse failure degrades the surface rather than raising (the peek discipline). The workspace must exist (store.get raises WorkspaceNotFound); past that, everything is guarded.

Record a phase claim for a workspace, or for one of its tickets — the CLI verb / MCP tool seam.

The in-workspace agent never comes through here; it writes the file directly (that is the whole point of the file channel). This is for an orchestrator or a human setting or correcting a claim from outside, so it is LOUD where :meth:phase_for is best-effort — a caller that asked to write is entitled to know it did not happen.

ticket, when given, MUST be one of state.ticket_refs' own .key — never validated against free text, because a key this workspace never attached would seed a per-ticket claim the store, the sticky publisher and every other joiner can never reach. Checked against a FRESH read of the store (never a caller-cached list), so a detach that raced this call is honoured rather than silently overwritten. Raises :class:TicketNotAttached, naming both the rejected key and the workspace's actual attached keys, before touching the file. Omit it to set the workspace's own claim, unchanged from before.

No event is emitted: the phase is derived per poll tick from the file rather than persisted on the record, so the existing session_activity delta already streams it (the fingerprint carries it). A workspace_changed wake-up would only tell clients to re-fetch a record that does not carry the phase at all.

Which transcript this workspace's PUBLIC link shows.

THE SINGLE RESOLVER, and being single is the whole point. The public overview names a session and the public turns route serves one; while those were two independent derivations they disagreed in production — the overview reported the workspace's own session while the transcript rendered whichever file in the scan cwd had been touched most recently, which under ROOT placement is another workspace's conversation entirely. Any future public read that needs a session calls THIS, never a listing index.

The recorded pin wins. None — a link issued before pinning existed, or one whose pin was never captured — falls back to :meth:_todo_session_id, the same per-request resolution the todo and task-text axes use, which is the workspace's own primary session. So an unpinned link is not broken, merely un-frozen: it follows the workspace the way the authenticated surface does.

The answer may name a session with no transcript on disk yet (a mint inside the STARTING window). That is honest rather than a failure — the turns route finds no listing for it and says the workspace has nothing readable, which is exactly the state it is in.

Fence an active collaboration and retain the document as read-only.

Register a sync callback. Returns an unsubscribe handle.

Switch the running session's model where the agent exposes a switch control.

claude_code/codex expose it as the interactive /model <id> slash command, delivered through the same steer path as :meth:invoke_control (the provider boundary — the command shape is the tool's, the id forwarded verbatim, never interpreted). A kind with no model-switch channel (a bare shell, a remote session whose model is fixed at create) raises CapabilityUnavailable.

Apply kind's root override for one adapter read.

Filesystem adapters resolve their roots from the task-local helper before consulting os.environ. This preserves the established signature and None no-op behavior without process-global mutation: executor workers reading different workspace profiles cannot cross-read each other's transcripts. An empty string remains an explicit clearing override, matching the existing scope contract.

THE scope every adapter read for state must run inside.

Wrap each adapter call that resolves a transcript, a rollout, or a config-dir-derived surface in this. The workspace's agent may have been launched under a pinned CLAUDE_CONFIG_DIR/CODEX_HOME that this process — the daemon, the TUI — does not share, and every filesystem adapter resolves that env ambiently at call time. An unscoped read therefore searches the reader's own profile and finds nothing.

Resolves the kind itself rather than taking one, so no caller can scope a read with a kind that disagrees with the workspace's own (effective_kind is already the single answer to "which adapter is this workspace's"). Pass the state; there is nothing else to get wrong.

Returns a context manager instead of being one so the unpinned case — no transcript_context, the overwhelming majority — is a bare nullcontext: the hot poll path allocates nothing else and behaves byte-for-byte as it did before any of this existed. The env it mutates is process-global, so hold the returned scope around the adapter call ONLY, never across a whole request or a whole workspace.

Why this is a public seam rather than four inline with blocks: the invariant was independently forgotten at four separate read sites (the fleet drill-in 404, an empty todo posted to a Gitea issue, the wrong profile's slash commands, a blank current_model). Four bespoke blocks would distribute the same forgettable rule four more ways; one named seam gives it a home a new read path can find.

Rename the title, set/clear the description, or share the workspace.

Metadata-only — never touches the worktree, the tmux session, or the branch. Title is the slug seed for the worktree path and tmux session name at create time; both are persisted strings after that and renaming the title does NOT rebuild them. The user keeps the on-disk worktree dir and the live tmux session they already have; only the displayed title changes.

Sentinel semantics: _UNSET (the default) means "leave alone". title="..." sets a new title (must be 1..120 chars after stripping). description=None or description="" clears it (stored as None — empty string and None are equivalent and we normalize on write). description="..." sets it.

share=True mints a public capability token (and share=False clears it), which is what makes the workspace readable through the daemon's unauthenticated /public namespace. It lives here rather than on a share() method of its own because this method already owns all four things such a method would need: the ORPHANED gate, the read-modify-write against persisted state, the no-op short-circuit, and the updated event. A second copy of those is how two mutation paths drift.

Enabling is IDEMPOTENT — an already-shared workspace keeps the token it has, so re-enabling never invalidates a link somebody is already holding. Disabling clears it outright, which permanently kills that link; a later re-share mints a fresh one rather than resurrecting it.

Minting a token also PINS the transcript the link will show, to the workspace's session as resolved at that moment (:meth:_todo_session_id). A link is a capability handed to somebody who cannot see this record, so what it renders must not change identity under them — and derived at read time it does, three ways: a respawn mints a new session id, adoption can promote a different one, and under ROOT placement the scan cwd is the shared repo root holding every other workspace's transcript. Revoking clears the pin with the token.

share_session_id RE-PINS explicitly, and it is the only way to move a live link: enabling is idempotent, so re-sharing an already-shared workspace cannot re-pin by itself, and that silence is deliberate — clicking "share" twice must not quietly change what a circulated URL shows. It resolves through :meth:_resolve_session_ref (unique prefix, kind-checked, no birth-gate) BEFORE any write, exactly like remap_session, and requires share=True because a pin without a link is a claim about nothing.

Refuses if every arg is unset (nothing to do) and if the workspace is ORPHANED (worktree gone; record headed for kill). Emits an "updated" event with title_changed / description_changed / share_changed / share_session_changed flags so subscribers know what shifted without diffing themselves. The event carries only the FLAGS, never the token — an event bus fans out to subscribers with no business holding a credential. The pinned session id is not a credential and rides the ordinary state view, but it is still not on the event: a subscriber that needs it re-reads the record, the same rule share_changed follows.

Replace the active document only when its generation and bytes match.

Every file this workspace has changed since it was created.

Scope is the worktree against the recorded creation anchor (WorkspaceState.base_commit), INCLUDING untracked files — so a file the agent committed an hour ago is still in the answer. Anchoring on HEAD instead made the patch go blank the moment the agent committed, which is precisely when a reviewer wants it, and it is the only axis a ROOT workspace has: there the branch IS the base branch, so the committed-vs-base stats collapse to zero.

The anchor is a fact recorded once, never a range re-derived here — the base branch moving on afterwards must not change what this workspace is credited with. A record written before the anchor existed falls back to HEAD, i.e. exactly the historical uncommitted-only patch; that is the honest degradation, not a fabricated baseline. This is why the patch's file count no longer matches peek's dirty_files once anything has been committed: that counter deliberately stays the uncommitted churn signal the activity stream fingerprints.

Untracked files are appended as individual all-additions patches because git diff omits them entirely (see untracked_patch for why the index is never touched to get them).

Bounded by max_bytes, cut at a whole-file boundary so the result is always a parseable patch, with truncated saying so. A caller wanting one file passes path — the per-file form is what lets a client read a big tree one file at a time instead of raising the cap.

Never raises: an unreadable worktree is available=False with a reason, which is a materially different answer from an empty patch.

Return (or create) a Manager for repo_root.

repo_root is canonicalized via Path.resolve() so distinct symlink paths to the same repo collapse to a single Manager. The Manager's config is resolved once per repo via config_loader (or the shared cfg when none was injected) and cached with it.

Listable projects, by union of two sources — the listing seam.

Where known_roots() answers "which repos exist" (the Manager-dispatch + repo-validation seam), this answers "which projects should a client offer", which is a superset: a single repo can expose several nested subdirectory projects. The deduped (by cwd) union of:

• store-derived repo roots, each as a repo-level Project (cwd == repo_root) — the empty-project-visibility arm carried forward;
• config-declared projects, each Project(repo_root=<enclosing repo>, cwd=<declared path>) so a declared subdirectory lists distinctly while still anchoring its worktrees at the true repo root.

Reads fresh from the store each call (new repos appear without a restart), the same contract known_roots() holds.

Repos that exist, by union of two sources.

The deduped union (Path.resolve() collapses symlinks) of: store-derived roots (every repo with ≥1 persisted workspace) and config-declared roots (cfg.projects). The config arm is what keeps an empty project visible — a freshly-added repo, or one whose workspaces were all killed, has no store row but stays a known project.

This is the single place that decides "which repos exist", so every downstream consumer (GET /workspaces, ActivityService, the pickers) inherits empty-project visibility with no further change. Reads fresh from the store each call so newly created repos appear without a restart.

The workspace a public share token names, or None.

The ONE place a token becomes an identity, which is why it belongs here rather than on a Manager: a token is host-wide by construction (the public reader is handed a bare string and has no repo to scope it with), so resolution has to happen above the per-repo cache.

It reads the STORE directly rather than walking known_roots() and asking each Manager. One store read answers for every repo, where the walk would resolve every project's whole config cascade — and instantiate a Manager per repo — on a request that is unauthenticated by design. Only the single matching repo's Manager is then materialized, through the ordinary cache.

None covers every failure identically: no such token, an expired token, a token belonging to a workspace that has since been unshared, or an empty string. A caller must not distinguish them; the whole point of the capability is that a wrong guess learns nothing.

The workspace ref names, and a Manager bound to ITS repo.

A workspace id is unique across the host, and the repo a workspace belongs to is recorded on the workspace — so naming one is enough to reach it, and asking the caller to also be standing in the right directory is a precondition the operation never had. Every id-addressed verb (attach, message, pause, kill, …) resolves here, which is why they work from anywhere: the record supplies the repo the Manager binds to.

Same shape and same reason as :meth:resolve_share — one store read answers for every repo, and only the single matching repo's Manager is materialized, through the ordinary cache. Walking known_roots() instead would resolve every project's whole config cascade to answer a question one record already answers.

Raises GroveError naming the candidates when the ref matches nothing or several. Ambiguity is judged HOST-wide, so a prefix that was unique inside one repo can now be ambiguous — which is the honest answer for a ref that no longer carries a repo to disambiguate it.

Every publicly-shared workspace in one repo, newest first.

What the public view's rail lists. Scoped by repo_root — the repo, not the nested Project — because "the same project" to somebody reading a shared link means the codebase, and a security-adjacent path is the wrong place to introduce a second notion of project identity.

The caller is trusted to already hold a token for ONE of these, and the consequence is deliberate and stated on the wire contract: sharing a workspace makes it discoverable from every other shared workspace in its repo. A private workspace never appears here.

Observe existing and newly materialized managers without rescanning readers.

Every persisted workspace without status reconciliation or Manager setup.

Host-wide read indexes use this when they need workspace identity to annotate one filesystem edge. WorkspaceManager.list() additionally reaches tmux and lifecycle state, which is neither needed nor affordable for a path-local catalog update. The store supplies independent values from its signature-indexed snapshot.

Publish a prepared snapshot and report every row changed by recovery.

Collection runs off-loop. This owner-side half keeps persistence and event publication fenced to a live runtime generation, and makes a lost source edge visible to already-connected SSE clients rather than only to a later full snapshot reader.

Publish the owner-approved result of one prepared workspace read.

Build initial state once before accepting source events or readers.

Tear down all manager-bus bridges and subscribers (daemon shutdown).

Next monotonic event id. Public so the daemon's SSE layer stamps its snapshot/heartbeat frames from the same sequence as the deltas, keeping Last-Event-ID replay coherent across both.

Compatibility entry for explicit reconciliation, not recurring discovery.

Delegates to apply_reconcile(emit=True) rather than diffing itself. The earlier shape snapshotted _rows, called reconcile() — which REPLACES _rows on its way through apply_reconcile — and then compared against a baseline that had already been overwritten, so it emitted nothing and every notification trigger driven by an explicit poll went silent. apply_reconcile already owns the diff, the removal deltas and the cursor, so the second copy could only ever be the wrong one.

Read the authoritative fleet snapshot without mutating the projection.

Read only invalidated parts of one maintained workspace row.

reconciled rather than get keeps the displayed status on every path. Unknown/lifecycle recovery keeps the default full refresh; an edge-specific caller reuses all retained immutable facts it did not invalidate.

Synchronously recover the projection for non-runtime callers.

Synchronously refresh one key for non-runtime callers.

The workspace's agent session(s) with blended activity.

Public seam with two consumers — the daemon's poll (via _workspace_activity) and the TUI list screen's slow tick — so the blend + hook-sidecar policy stays in this single site.

Discovery is a read-only fs glob over state.transcript_scan_cwds — agent_cwd (worktree/subpath, where the agent runs) unioned with the worktree root (a session hand-started at the repo root of a nested project records its cwd), led by the transcript context's own recorded cwd when the workspace has one. It always runs, adapter-gated only (generic/shell discover nothing): cfg.hooks.enabled gates the sidecar push, never read-only discovery.

Every adapter read below is wrapped in mgr.transcript_scope(state) — an agent launched under a pinned CLAUDE_CONFIG_DIR/CODEX_HOME wrote its transcript where this process's ambient env does not point, and an unscoped read finds nothing and pins the card at STARTING. That is the manager's shared seam, not a local copy: this file once kept its own two-line version, which is exactly how the same invariant came to be forgotten at four other read sites.

Two paths, by whether Grove minted a deterministic id at create:

• Minted id present (the happy path): that grove_launched session is the primary; only the discovered sessions this workspace adopts ride along as fs_discovered extras. Candidates are pre-filtered on CHEAP head metadata (birth) + the sidecar BEFORE any full parse (#F5), so per-tick cost is O(new sessions), not O(history) — a historical transcript predating the workspace is excluded from the card entirely (the "adopt only what's ours; the rest is noise" precedent). Exception: a minted id that is a dead pointer yields the primary slot to the newest adopted session; the minted entry rides behind and reclaims primary the moment it materializes.
• No minted id — a workspace whose agent wasn't kind="claude_code" at create, one created before minting existed, or a purely hand-started run. With no minted session there is no reference pane, so adoption is birth-only (#F1); adopt the single most-recent session that passes. Nothing adopted (every candidate predates this workspace, e.g. a reused ROOT cwd) → honestly sessionless.

Adoption weighs transcript birth AND a hook sidecar proving the session was live in this workspace's own PANE after creation (ClaudeHook.adopts) — the sidecar arm lets a session resumed inside the pane (born before the workspace) be adopted, and the pane check keeps a shared cwd (ROOT placement) from adopting another live workspace's session (#F1).

Read the maintained projection, bootstrapping it if nobody has yet.

ORDINARILY THIS IS A PURE READ: the runtime owner bootstraps at startup and every later change arrives as an event, so the projection is already there and this takes the lock and returns. The fallback exists because the alternative for an unbootstrapped projection is answering with an EMPTY FLEET — indistinguishable on the wire from a host that genuinely has no workspaces, which is the one answer a maintained projection must never invent.

Building it here rather than blocking startup is what keeps daemon readiness independent of fleet size: /healthz reads no projection, and a caller that does read one is the caller that should wait for it. bootstrap is idempotent under its own lock, so concurrent first readers do one scan between them, not one each.

Capture state and its applied watermark under the same publication lock.

THE BOOTSTRAP HAPPENS BEFORE THE LOCK, NEVER INSIDE IT. snapshot may now build the projection on demand, and building it takes _bootstrap_lock and then _projection_lock (through apply_reconcile). Calling it while already holding _projection_lock inverted that order, and two threads — one bootstrapping, one reading a cursor — deadlocked the whole daemon: every request including /healthz hung, because the loop thread was among them.

Bootstrapping first costs nothing in the steady state (the projection exists, so it is one uncontended lock round-trip) and the pair stays atomic, because the snapshot and the sequence are still read together under one acquisition below.

Invalidate content queries even when activity counters stayed equal.

Register a delta callback. Returns an unsubscribe handle (idempotent).

One workspace's activity row, without ever scanning the fleet.

The per-request seam behind GET /workspaces/{id}/activity. It exists because a page about ONE workspace was reading its session id off snapshot(), and snapshot BOOTSTRAPS when no projection exists yet — so the first reader after a daemon start paid for every workspace on the host before the page could paint. Measured on the reference host: a 40.6 s bootstrap, 22.4 s of it spent on two OFFLINE workspaces whose transcripts that page never renders.

Two paths, and which one runs is the whole design:

• The projection already holds this row — the ordinary case, because the ~1 Hz poll maintains it. Then this is a dict lookup under the existing lock and costs nothing (measured: the maintained fleet read answers in ~2 ms for exactly this reason). The row is the same object the stream publishes, so a page cannot disagree with its own stream.
• It does not (no projection yet, or a workspace created since the last tick). Then exactly ONE workspace is computed. This is the path that used to be a fleet bootstrap, and the whole point is that a page about one workspace now waits for one workspace.

Deliberately neither bootstraps nor publishes: a request must not build the shared projection (that is the poll's job, and the cost this exists to avoid) and must not advance a sequence the stream's consumers order on. None for an unknown workspace, so the route owns the 404.

Every session recorded in one workspace's directories, newest-first, UNGATED — the remap-picker seam.

The ungated sibling of :meth:for_workspace: the same bounded one-cwd scan (cheap per request), but applying NO adopts_session birth/pane gate. So a session the auto-adoption heuristic rejects — a dead-minted-pointer's live successor born before the workspace, or a foreign session sharing a ROOT cwd — is still offered. This is exactly the set a human picks from to remap: the operator supplies the attribution the gate withholds (and manager.remap_session, the write it feeds, is likewise ungated). Provenance is still grove_launched for the minted id, fs_discovered otherwise. Raises :class:~grove.core.errors.WorkspaceNotFound for an unknown id.

A browse-everything counterpart to the ungated project-wide :meth:list, but scoped to one workspace's scan_cwds — so a picker pays one directory's parse, not the whole project's. Returns a tuple (the list-method shadowing trap, as in :meth:for_workspace).

One row re-read by IDENTITY so its parse products are populated.

session_summary is the adapter seam that may full-parse; it resolves one known id through locate_transcripts rather than scanning, so this costs one parse per DISPLAYED row. Best-effort by contract: a row that cannot be re-read keeps its metadata-only form rather than raising out of a listing.

The selected root's child-session projection for the fleet reader.

A selected root is the explicit session_id when present, otherwise the workspace's own minted session — read directly off the record rather than through :meth:primary_for_workspace, which requires a materialized transcript and would misreport an honestly-supported root as unsupported during the STARTING window before its first transcript line lands (the same window the live hook roster already renders through). An explicit session_id must belong to this workspace's own scan — never a stranger's — so it is checked against :meth:for_workspace and refused (unsupported, no children) rather than resolved against a foreign workspace's cwd.

The adapter capability decides whether an empty tuple means "no children"; an adapter lacking it is honestly unsupported. This is a targeted, on-demand read, never an activity poll.

Every session recorded for one workspace's directory, newest-first.

The bounded variant of :meth:list for per-request consumers (the daemon's GET /workspaces/{id}/sessions): scans only the workspace's own cwd instead of every worktree, so the transcript-parse cost stays one directory regardless of project size. Raises :class:~grove.core.errors.WorkspaceNotFound for an unknown id.

Scans the union of state.agent_cwd (worktree/subpath — where a nested project's agent runs) and the worktree root (a session hand-started at the repo root records its cwd, #F7), deduped for a flat workspace. Both are where filesystem adapters exact-match a transcript's recorded cwd.

A discovered (fs_discovered) listing is kept only when state.adopts_session accepts it — its transcript birth postdates this workspace's created_at, OR a hook sidecar proves it was live in this workspace's own PANE after creation (the same pane-verified evidence rule ActivityService.sessions_for uses, so a session resumed in the pane — born before the workspace — still attributes here, while a shared cwd can't steal another workspace's live session, #F1). Without the gate, a fresh workspace whose cwd already holds older transcripts (especially ROOT placement, whose cwd is the shared repo root) would present a stale, unrelated session as its own. A grove_launched listing is never gated — Grove minted it for this workspace regardless of birth. :meth:list and the project-scoped listing stay ungated by design: those are browse-everything history views, not workspace attribution.

Returns a tuple — in this class body a list[...] annotation would resolve to the :meth:list method, not the builtin (the documented mypy shadowing trap).

Build an explorer for the project enclosing cwd.

Works from inside any worktree: the main worktree (first entry of git worktree list) is the root the workspace store is keyed by, so the explorer always binds its manager there — binding to the linked worktree's own root would find zero workspaces.

Every session across the project, newest-first, optionally filtered.

agent matches the adapter kind exactly; workspace matches a workspace id prefix or a case-insensitive title substring; since keeps sessions modified at/after that instant; limit caps the result after sorting.

enrich is the OPT-IN full parse, for the one consumer that renders parse products (the grove sessions table). It runs AFTER filtering and limiting, so the cost is one identity-keyed read per DISPLAYED row rather than one per transcript sharing the directory.

The readable primary session for one workspace.

The recorded session id wins when it has materialized. Otherwise a Claude id rotated by /clear or a Codex workspace with no mint falls back to the newest adoption-gated session in the workspace's own scan. This is a request-time reader, not an activity-poll resolution: it may read the bounded transcript listing because an explicit recollection request earns that cost.

Project direct human messages from an adapter-filtered message spine.

The adapter has already applied its provider-specific real-turn filter while assigning the user role; this generic projection deliberately makes no second classification judgement.

Every direct user query in the uniquely resolved session, oldest first.

Every direct user query in one session, oldest first.

Reads the complete normalized message spine before applying last: a user query can follow any amount of agent work, and compaction only changes the agent's context, never the transcript. The adapter's existing real-turn filter is authoritative — it excludes provider and harness machinery while admitting human slash commands and messages delivered while the agent was busy. A slash command is included because it is an explicit direct instruction from the user, not an echo.

The unique session whose id matches ref exactly or by prefix.

Raises :class:GroveError when nothing matches or the prefix is ambiguous (the message lists the candidates, so the user can extend the prefix without re-running list).

Every directory whose sessions belong to this project, de-duplicated.

Union of the live git worktree list (main first; covers hand-made worktrees Grove never managed), every workspace's persisted agent_cwd (worktree/subpath — where a nested project's agent actually runs and records its transcript's cwd), its worktree_path (covers paused workspaces whose directory is gone — their transcripts still live under the encoded-cwd projects folder), and, for a workspace with a transcript_context override, the recorded cwd it names instead — a container-launched agent's real cwd, which can never equal either host path. agent_cwd collapses to the worktree root for the common empty-subpath case, so the extra entries only matter for nested or overridden projects.

The resolution fallback for a fleet-child thread_id — one that for_workspace never lists.

A fleet row's session_id IS the Claude sub-agent thread id (agentId), and discover_paths deliberately skips subagents/ — so it never appears in any workspace's own session listing, and a direct id lookup always misses. Kind-scoped to claude_code exactly like ActivityService._fleet_entries (a direct :class:ClaudeCodeAdapter instantiation, never a widened AgentAdapter Protocol for one kind's capability — the in-session sidechain fleet is a Claude Code transcript concept). Tries thread_id against each of the workspace's own top-level sessions (its own :meth:for_workspace listing) via the adapter's subagent_turns/fleet_activity projections — both already read off the same memoized spine, so this pays no second parser — and returns the first match's turns plus a SessionListing synthesized from that SAME per-thread identity (title/current_task degrade exactly as fleet_activity already does: the .meta.json sidecar, else the truncated first task prompt). None when thread_id belongs to none of them, or the workspace isn't claude_code.

One of a workspace session's tool calls, resolved the way its turns are.

The listing whose id matches answers first. A session_id that names no listing is the fleet-child case the turns route already handles (subagent_turns): a sub-agent thread never appears in a workspace's own listing, but its records ride its PARENT session's spine, so the fallback searches the workspace's top-level sessions for the id. The search is by tool_use_id, which is unique across the spine, so the widened scan can only find the call the caller named.

ONE tool call out of an already-resolved session, by its id.

The drill-in half of the head+drill-in pairing the windowed /turns read introduced: a turn list that withheld settled bodies (ToolCallView.body == "available") is the head, and this serves any one of those bodies whole. Built as a PROJECTION over :meth:AgentAdapter.read_messages — the same spine every other projection here reads, memoized per transcript — so an opened body costs a walk rather than a parse once the turn list is warm.

Deliberately a sibling of :meth:recollect_for rather than a new adapter capability: "which call carries this id" is answered identically for every provider off the normalized spine, so a per-adapter method would be one implementation duplicated per kind. Scoped to the owning workspace's config-dir override for the same reason :meth:turns_for is.

Every transcript file for the session — main thread first, then sub-agent files — via the owning adapter's locator. Empty for a remote-backed session (no local files).

Scoped to the owning workspace's transcript_context.config_dir override, if any — _session_cwd already resolves to the session's own recorded cwd (a container path, when relevant), so only the adapter's config-dir env needs redirecting to find that host directory at all.

The normalized conversation for the session matching ref.

The normalized conversation for an already-resolved listing.

Split from :meth:turns so a caller holding a listing (the daemon's turns endpoint, fed by :meth:for_workspace) skips the full-project :meth:resolve scan.

Scoped to the owning workspace's config-dir override, if any — same reasoning as :meth:transcripts.

Whether a discovered (non-minted) session belongs to this workspace.

Two independent kinds of evidence, either sufficient — each measured against this workspace's own created_at (a session is ours only if it was alive here at/after we came into being):

• born_at — the session's transcript BIRTH (first-record timestamp). Immutable, so a stale file merely being touched or re-read can't fake it. A workspace's cwd can hold transcripts written before it existed — most commonly ROOT placement, whose cwd is the shared repo root — and treating "newest transcript in the cwd" as "our session" (the pre-fix bug) presented a stale, unrelated conversation as a brand-new workspace's own. Birth, not recency, is the correct test.
• live_here_at — the timestamp of a hook sidecar proving the session was live in this workspace (the caller attributes it by cwd/pane at the boundary; this predicate stays pure and never reads a sidecar). A session the user RESUMED inside this workspace's pane is born earlier than the workspace, so birth can never adopt it — but its post-create sidecar ts does. Birth alone silently drops every resumed session; the >= created_at guard still rejects a previous tenant of a reused cwd, whose sidecar predates this workspace.

Used by both discovery-adoption sites (ActivityService.sessions_for, SessionExplorer.for_workspace); a session Grove itself minted and launched never calls this — it is unconditionally ours, born or not.

Both timestamps are optional (unknown birth, no sidecar) and never adopt when absent — unproven evidence can't be shown to postdate creation. A tz-naive value is coerced to UTC defensively so a malformed timestamp degrades the comparison rather than raising on the poll path (the peek/best-effort discipline).