Skip to content
Merged
Show file tree
Hide file tree
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -109,6 +109,14 @@ A host's `port` is the loopback port on this machine through which its own hub i
}
```

`editor` is the command the "Open in editor" button at the right end of the tab bar runs to open the selected worktree; the default is `kate`. `{path}` stands for the worktree path, as one argument however it is spelled; without `{path}`, the path is added at the end. The command is split into words like a shell would, with `'…'`, `"…"` and `\` quoting, but nothing is expanded (`~`, `$VAR`) and no shell runs. The hub starts it on this machine, in the worktree, so only worktrees on this machine can be opened, not those of remote hosts or from a remote hub's page. Right-clicking the button edits `editor` here, and "Reset to default" removes it; every open page shows the change.

```json
{
"editor": "code --new-window {path}"
}
```

## Memory and out-of-memory kills

With a systemd user manager that outlives your session (the process runs under `user@<uid>.service`, as anything started from a desktop session does, or lingering is on), every process worktree-term starts gets a cgroup of its own in the slice `app-wtd.slice`: the daemon `wtd-<h>-daemon-<r>.scope`, the hub `wtd-<h>-hub-<r>.scope`, and each terminal, with everything it starts, `wtd-<h>-term-<instance>-<id>.scope`, where `<h>` hashes the state directory. systemd-oomd and the kernel then kill only the terminal that ran out of memory, never the daemon, the hub or another terminal; its tab says `killed: out of memory`, and `memory.log` gets an `oom-kill` line and each terminal's cgroup figures. A daemon run as `worktree-term-daemon.service` stays in that unit. Terminal shells also get an `oom_score_adj` of at least 500, so a system-wide OOM picks a terminal before the daemon or hub.
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-11-12
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
## Context

See proposal.md for motivation. The browser reaches only its hub; within the hub only `links` spawns processes (hub principle 2) and `router` already depends on `links` and `config`. Presets show the pattern for a page-edited, hub-owned setting: a `config.json` key edited through `ConfigEditor`, pushed to every session. The hub and the daemon of host 0 run on the same machine; remote hosts' daemons and remote pages' hubs run on machines without the user's display. The hub enters a transient scope of its own at start when a lasting user manager is reachable, so anything it spawns lands in that scope unless moved.

## Goals / Non-Goals

**Goals:**
- One shared, pure editor-command parser used by the config schema, the wire schemas, the page's form validation and the hub's launch.
- An editor launch that detects a missing program without a shell or timing guesses and leaves the editor independent of the hub.

**Non-Goals:**
- Opening worktrees of remote hosts or from remote pages (deferred by the user).
- Observing the editor's exit status after it started, including a shell's exit 127.
- A keyboard shortcut for the control; a ring on repo tabs, terminal tabs or pane headers.
- Per-host editor commands.

## Decisions

1. **The local hub launches the editor; the control works only for worktrees on the browser's own machine.** Options: hub launch, local only; hub launch plus a second remote command template run locally with `{host}`/`{path}`; daemon of the owning host launches (the issue's wording). The hub launch needs no daemon protocol change, fits the existing arrows, and always opens the editor on the user's display; a daemon launch on a remote host opens on a machine without the user's display. The control is disabled for remote hosts on a home page and on remote pages. (user)
2. **Remote opening is deferred.** The user: "running that remotely is a pain, so let's leave that for later". (user)
3. **Ring on worktree rows only.** Options: worktree rows only; rows and repo tabs. Rows are where the user scans for open sessions; most open repo tabs have terminals. (user)
4. **The ring counts every terminal the daemon lists for the worktree**, exited ones whose tab is still open and those of a gone worktree included; it shows only where no mark shows. Its element is distinct from the mark's (own test id) so existing mark assertions keep their meaning. (default)
5. **Own word splitter, no shell.** Options: split the command ourselves and spawn directly; run `sh -c` with the path as `$1`. Direct spawn reports a missing program as a spawn `ENOENT` at once; through a shell, a missing program is an exit 127 that can only be told apart from a running editor by waiting an arbitrary time, since the shell execs the long-running editor. Cost: no `$VAR` or `~` expansion in the command. The parser lives in `protocol` (pure, zod-only) and backs the `editorCommand` schema. (default)
6. **The issue's "exit 127 through a shell" is not handled.** Codex proposed a bounded early-exit watch mapping 127 to `editor-missing`; rejected because no shell is ever run, so 127 can only come from a user-written `sh -c …` command, and catching it needs a timing heuristic. rejected (codex)
7. **The editor is moved into a transient scope of its own** (`platform.scopes` helper `editorUnit(stateDir)` beside `daemonUnit`/`hubUnit`, Codex finding) when a lasting user manager is reachable, via the existing enter-scope call on the started pid; a failure is reported to the hub log and does not fail the launch. Left in the hub's scope, the editor's memory would be attributed to the hub and an OOM kill of the hub's cgroup would take the editor with it. (default) (codex)
8. **Launch primitive.** `platform.dialer`'s detached spawn gains a working-directory option and returns the started child's pid, keeping the spawn error (with its `code`) as `cause`; existing callers keep their behaviour, guarded by regression tests. `hub.links` exposes the editor launch built on it. (codex)
9. **Missing directory vs missing program.** Node reports a missing `cwd` as `ENOENT` too. The launch primitive checks that the working directory is an existing directory before spawning and, on a spawn `ENOENT`, checks again (the directory can vanish in between, Codex finding), failing with a typed error that tells a missing directory, a missing program and any other failure apart; the hub maps them to `editor-failed` naming the path, `editor-missing` naming the program, and `editor-failed` with the reason. The check sits in `platform.dialer` through a new `platform.files` directory helper, because `hub.links` may not use `fs` (dependency allowlist) while `platform.dialer → platform.files` exists. (default) (codex)
10. **Per-session editor command.** Each session holds its own editor command, initialised from its snapshot and replaced by the same broadcast that sends `editor`, so `openEditor` always runs the command that session's page shows, including edits made from another page. (codex)
11. **Removing a config key.** `ConfigEditor`'s field edit gains an explicit "remove the key" result distinct from "no edit"; `setEditor(null)` uses it, keeping every other value as written. (codex)
12. **Default command `kate`, path appended**, as in the issue; reset removes the `editor` key rather than writing the default. (default)
13. **Wire.** Browser→hub `openEditor{req, worktree}` and `setEditor{req, command | null}`; hub→browser `editor{command}`, sent after `presets` and before `hosts`; hub error codes `editor-missing` and `editor-failed`; `BROWSER_PROTOCOL_VERSION` 14 → 15, wire golden re-blessed, frozen golden unchanged. `openEditor` carries no host: the hub always launches on its own machine. (default)
14. **Dialog wording names the missing program** rather than always "Kate", since the command may name another editor. (user, approved wording) — editor-missing: "Could not find `<program>`. Install it, or right-click the editor button to set the command of the editor you prefer."; editor-failed: "Could not open the editor: <message>"; form hint: "{path} stands for the worktree path; without it, the path is added at the end."; control title: "Open in editor (right-click to change the command)". `<program>` is the first word of the command the page shows.
15. **The control is disabled while its request is unanswered**, preventing double launches; it does not depend on the host's connection status, since the launch does not involve the daemon. (default)
16. **Right-click works on the disabled control** (a disabled button receives no pointer events, so the context-menu handler sits on a wrapper), except on a remote page, whose hub's command would never be used. (default)
17. **Stale shared-constants requirement fixed.** The protocol spec's "Shared constants" requirement still states daemon 10 / browser 13 while the code and the version requirement say 11 / 14; this change states 11 / 15 in both. (default)
18. **OpenSpec deltas.** Codex flagged missing spec updates; they are this change's `web`, `hub` and `protocol` deltas. rejected (codex)
19. **No architecture change.** Uses existing arrows `web.ui → web.client`, `hub.router → hub.links`, `hub.router → hub.config`, `hub.links → platform.dialer`, `hub.links → platform.scopes`. Applicable principles: system 5 (command parsed by schema at the boundary), 6 (launch and scope failures reported), 8 (tests per tier); hub 2 (only `links` spawns), 5 (the command is config); protocol 2–4 (schema-defined command, strict decoding, version bump); web 2 (only `client` encodes wire data). (default)

## Risks / Trade-offs

- [The hub's `PATH` or display variables may differ from the user's shell when the hub was started from a desktop entry] → `editor-missing` names the program; the user can set an absolute path in the command.
- [Processes the editor forks before it is moved into its scope stay in the hub's scope] → the move happens right after spawn; editors fork their GUI later or hand off to a running instance.
- [Commands relying on shell features (`$VAR`, `~`, pipes) do not work] → documented in the form hint's spirit; a user can write `sh -c '…' sh {path}` explicitly, accepting that a missing inner program is not detected.
- [A browser-link bump reloads open pages of the old version] → same as every browser-link change; daemons are unaffected.
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
## Why

There is no way to open the selected worktree in an editor from the UI; the user has to copy the path and launch the editor by hand. The sidebar also cannot tell a worktree that has quiet open terminals from one with none, so finding where sessions run means hovering each row.

## What Changes

- An "Open in editor" control at the right end of the terminal tab bar, after the split controls, opens the selected worktree with the configured editor command (default `kate`), launched detached by the local hub on its own machine.
- The control is disabled with no worktree selected, for prunable or gone worktrees, for remote hosts and on remote pages (remote opening is out of scope).
- A missing editor program shows a pop-up telling the user to install it or set another command; other launch failures show their error in the same pop-up.
- Right-clicking the control opens a form to edit the command (`{path}` placeholder, else the path is appended) or reset it to the default.
- The command is stored in the hub's `config.json` under a new `editor` key and pushed to every open page.
- Worktree rows with at least one terminal and no attention mark show a hollow ring.
- Browser link: new messages `openEditor`, `setEditor`, `editor`; new hub error codes `editor-missing`, `editor-failed`; `BROWSER_PROTOCOL_VERSION` becomes 15. The daemon protocol is unchanged.

## Capabilities

### New Capabilities

### Modified Capabilities
- `web`: open-in-editor control, its command form and error pop-up; hollow ring on worktree rows with terminals but no mark.
- `hub`: `editor` configuration key, editing it from the page, sending it to sessions, and launching the editor.
- `protocol`: browser-link messages and error codes for the editor; editor command value rules; browser protocol version 15.

## Impact

- Code: `src/web/ui` (control, form, pop-up, ring), `src/web/client` (messages, editor state), `src/hub/config` (schema, `ConfigEditor` key removal), `src/hub/router` (session editor state, requests), `src/hub/links` (launch), `src/platform/dialer` (detached spawn with `cwd` returning the PID), `src/platform/scopes` (editor scope unit), `src/protocol` (schemas, command parser, version, goldens).
- No architecture model or arc42 change; no new dependencies.
- Pages of the previous browser protocol version reload as on any browser-link bump; daemons are unaffected.
Loading
Loading