Two files, one repository
stablyai/orca ships 1 format across 3 indexed files. The question worth asking is whether the second one says anything the first does not.
| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 16 | 3 | 0% |
| Commands | 0 | 2 | 0 | 0% |
| Section tags | 1 | 7 | 1 | 11% |
What each file covers
Sections
0 shared · 16 only in A · 3 only in B- − Design System
- − Electron UI Validation
- − Style
- − Concise/Brief Non-obviosu comments ONLY
- − Lint Rules: Do Not Disable Max Lines
- − File and Module Naming
- − Type Declarations: Prefer `.ts` Over `.d.ts`
- − Considerations
- − Worktree Safety
- − Cross-Platform Support
- − SSH Use Case
- − Folder Workspace Use Case
- − Remote Wire Compatibility
- − Git Binary Compatibility
- − Git Provider Compatibility
- − GitHub CLI Usage
- + AGENTS.md — Terminal Daemon
- + Endpoint Ownership: Who May Touch the Socket Path
- + Traps That Already Cost Us
Commands
0 shared · 2 only in A · 0 only in B- − eslint-disable max-lines
- − git --version
Section tags
1 shared · 7 only in A · 1 only in B- − lint-format
- − code-style
- − types
- − git-pr
- − ui
- − monorepo
- − docs
- + api
- do-not
Line diff
stablyai/orca · AGENTS.md
@@ −1 @@
1# Design System
2
3All UI work — layout, color, typography, spacing, component selection, UX behavior — must follow [`docs/STYLEGUIDE.md`](./docs/STYLEGUIDE.md). Use the tokens defined in `src/renderer/src/assets/main.css` (the canonical source) and the shadcn primitives in `src/renderer/src/components/ui/`. Don't invent new color values, font sizes, or shadow tiers when a documented one already covers the role. When STYLEGUIDE.md is silent, follow the resolution order in its final section.
4
5## Electron UI Validation
6
7Use the `$electron` skill and Playwright CDP for rendered Orca UI checks. Do not use computer-use for Orca UI validation.
8
9# Style
10## Concise/Brief Non-obviosu comments ONLY
11 * DO NOT: be verbose, explain the obvious, walk through the code ("WHY not HOW")
12 * BE CONCISE. 1 LINE if possible
13
14## Lint Rules: Do Not Disable Max Lines
15
16NEVER add a `max-lines` disable (`eslint-disable max-lines`, `oxlint-disable max-lines`, or line-specific variants), and never add a per-file `max-lines` bump in `mobile/.oxlintrc.json`.
17
18## File and Module Naming
19
20Never use vague names like `helpers`, `utils`, `common`, `misc`, or `shared-stuff` for files, folders, or modules. They carry zero info and tend to become dumping grounds. Name files after what they _actually_ contain — prefer the concrete domain concept (e.g. `tab-group-state.ts`, `terminal-orphan-cleanup.ts`) over the generic role (`tabs-helpers.ts`, `terminal-utils.ts`). If you find yourself reaching for `helpers`, the file probably has more than one responsibility and should be split, or there's a better name hiding in the code that describes what the functions operate on.
21
22## Type Declarations: Prefer `.ts` Over `.d.ts`
23
24# Considerations
25## Worktree Safety
26
27Always use the primary working directory (the worktree) for all file reads and edits. Never follow absolute paths from subagent results that point to the main repo.
28
29## Cross-Platform Support
30
31Orca targets macOS, Linux, and Windows. Keep all platform-dependent behavior behind runtime checks:
32
33- **Keyboard shortcuts**: Never hardcode `e.metaKey`. Use a platform check (`navigator.userAgent.includes('Mac')`) to pick `metaKey` on Mac and `ctrlKey` on Linux/Windows. Electron menu accelerators should use `CmdOrCtrl`.
34- **Shortcut labels in UI**: Display `⌘` / `⇧` on Mac and `Ctrl+` / `Shift+` on other platforms.
35- **File paths**: Use `path.join` or Electron/Node path utilities — never assume `/` or `\`.
36- **Windows setup scripts**: the setup/issue-command runner is a `.cmd` batch file unless the script starts with a `#!` line — never derive that from the user's terminal-shell preference, and never launch a `.cmd` runner with a bare `cmd.exe /c` from a Git Bash pane (MSYS rewrites the `/c`). See [`docs/reference/windows-setup-shell.md`](./docs/reference/windows-setup-shell.md).
37- **Linux native modules**: keep the glibc floor at Ubuntu 20.04 / glibc 2.31. A module compiled from source on a newer runner can reference symbol versions absent on the floor and crash the app on startup. See [`docs/reference/linux-glibc-compatibility.md`](./docs/reference/linux-glibc-compatibility.md); packaging fails if a bundled native binary needs newer glibc.
38
39## SSH Use Case
40
41All changes must consider the SSH use case. Don't assume local-only execution.
42
43## Folder Workspace Use Case
44
45All changes must consider folder workspaces as well as git worktrees. Don't assume every workspace is a git worktree.
46
47## Remote Wire Compatibility
48
49Clients and remote Orca servers update independently, so mixed versions are the normal state. Before changing anything a paired client and host exchange — RPC params, stream frames, or the content either side publishes over them — follow [`docs/reference/remote-wire-compatibility.md`](./docs/reference/remote-wire-compatibility.md). A new optional field is safe; a new stream opcode must be capability-negotiated because decoders drop unknown opcodes silently; and changing what the host publishes reaches old clients even with no wire change.
50
51## Git Binary Compatibility
52
53Orca runs the user's Git binary on native, WSL, and SSH hosts, which may all have different versions. Treat Git 2.25 as the core-workflow baseline and follow [`docs/reference/git-compatibility.md`](./docs/reference/git-compatibility.md).
54
55When adding or changing a Git command:
56
57- Check when every subcommand and option was introduced. For newer behavior, keep a baseline-compatible fallback or degrade safely.
58- Use `GitCapabilityCache` with a narrow unsupported-error predicate so recurring operations do not retry a known-invalid command. Do not rely only on `git --version`; wrappers such as `simple-git` do not remove host-version differences.
59- Scope capability state to the host that executes Git: native, WSL distro, SSH provider, or relay connection. Cover the first fallback, later cached calls, concurrent probes, and relevant host isolation in tests.
60- Keep the real-binary compatibility contract in PR CI current. When adopting a newer Git feature, add its version boundary so the preferred command and fallback both run against representative Git releases.
61- Preserve commands that begin with global Git options such as `-c` before the subcommand, including auto-maintenance suppression used by worktree-create fetches.
62
63## Git Provider Compatibility
64
65Source-control and review changes must consider GitLab and other supported git providers, not only GitHub. Keep provider-specific behavior behind explicit checks, and avoid GitHub-only naming for generic review concepts.
66
67## GitHub CLI Usage
68
69Be mindful of the user's `gh` CLI API rate limit — batch requests where possible and avoid unnecessary calls. All code, commands, and scripts must be compatible with macOS, Linux, and Windows.
70
stablyai/orca · src/main/daemon/AGENTS.md
@@ +1 @@
1# AGENTS.md — Terminal Daemon
2
3## Endpoint Ownership: Who May Touch the Socket Path
4
5Two invariants govern the daemon's canonical socket path. Read this before changing anything that
6links, renames, unlinks or stats it — or that treats its existence as evidence a daemon is running.
7
8> **Only a daemon publishing itself onto the canonical endpoint may mutate that directory entry,
9> and only by replacing an entry it has itself just proven dead.**
10>
11> **No actor removes a name it did not create.**
12
13**Why it exists.** `net.Server.close()` unlinks the pathname it bound with no ownership check, so a
14departing daemon deleted whichever socket then sat at the canonical path — including a live
15replacement's. The replacement stayed alive hosting PTYs no client could reach, which reads to the
16user as terminals that accept keystrokes and never run them. Seven review rounds against the older
17"launcher reclaims a dead process's name" shape produced twenty-three defects, all the same
18interleaving: a third party observing liveness at T and acting on the directory entry at T+1.
19
20**The protocol** (`daemon-endpoint-ownership.ts`): bind a private `.p<hex>` name → try an exclusive
21`link` → on `EEXIST` prove the incumbent dead by connecting → re-check the entry hasn't changed
22hands → probe once more → `rename` in one syscall → verify we kept it.
23
24## Traps That Already Cost Us
25
26- **Never collapse "can't tell" into "dead."** Only `connected` means occupied; only
27 `refused`/`missing` prove death. A timeout or `EPERM` proves nothing and must decline — treating
28 it as death deletes an endpoint still serving every terminal on the host.
29- **`link` first, never an unconditional `rename`.** `rename` replaces whatever it finds, so it
30 would let a starting daemon destroy a healthy one. `link` fails loudly and forces the liveness
31 question.
32- **`rename`, never `unlink`-then-`link`.** The latter leaves the name absent between two calls;
33 measured across a live handover it gapped on essentially every observation, where `rename` gapped
34 on none in ~14,500 probes.
35- **Do not identify an entry by `birthtimeMs`.** Node documents it as sometimes holding the ctime,
36 filesystems without a birth time report the epoch, and its granularity is often coarser than the
37 events it must separate. Three attempts to patch around this produced three more defects; inode
38 recycling is now settled by asking whether anything is _serving_.
39- **Do not add a sweeper.** Deciding whether someone else's leftover is safe to delete is the
40 question this design retired; the last one produced five defects, including deleting a live
41 listener's only pathname. Every actor removes its own scratch name on each non-crash path.
42- **Scratch namespaces must stay out of released builds' patterns.** Shipped versions sweep
43 `^\.b[0-9a-f]{10}$` on age alone with no liveness check, which is why the bind name is `.p`.
44 Deleting our sweeper does not un-ship theirs.
45- **Never remove the endpoint on shutdown.** A departing daemon leaves a dead entry; the next
46 publisher replaces it in one rename.
47
48**Residual risk.** The final probe and the `rename` are two syscalls, and POSIX has no
49rename-if-target-is-inode-X. The harm is separately unreachable: a daemon never creates a session
50on an endpoint it no longer holds (`daemon-server.ts`), and it drains rather than serving on.
51
@@ −1 +1 @@
1−# Design System
1+# AGENTS.md — Terminal Daemon
22
3−All UI work — layout, color, typography, spacing, component selection, UX behavior — must follow [`docs/STYLEGUIDE.md`](./docs/STYLEGUIDE.md). Use the tokens defined in `src/renderer/src/assets/main.css` (the canonical source) and the shadcn primitives in `src/renderer/src/components/ui/`. Don't invent new color values, font sizes, or shadow tiers when a documented one already covers the role. When STYLEGUIDE.md is silent, follow the resolution order in its final section.
3+## Endpoint Ownership: Who May Touch the Socket Path
44
5−## Electron UI Validation
5+Two invariants govern the daemon's canonical socket path. Read this before changing anything that
6+links, renames, unlinks or stats it — or that treats its existence as evidence a daemon is running.
67
7−Use the `$electron` skill and Playwright CDP for rendered Orca UI checks. Do not use computer-use for Orca UI validation.
8+> **Only a daemon publishing itself onto the canonical endpoint may mutate that directory entry,
9+> and only by replacing an entry it has itself just proven dead.**
10+>
11+> **No actor removes a name it did not create.**
812
9−# Style
10−## Concise/Brief Non-obviosu comments ONLY
11− * DO NOT: be verbose, explain the obvious, walk through the code ("WHY not HOW")
12− * BE CONCISE. 1 LINE if possible
13+**Why it exists.** `net.Server.close()` unlinks the pathname it bound with no ownership check, so a
14+departing daemon deleted whichever socket then sat at the canonical path — including a live
15+replacement's. The replacement stayed alive hosting PTYs no client could reach, which reads to the
16+user as terminals that accept keystrokes and never run them. Seven review rounds against the older
17+"launcher reclaims a dead process's name" shape produced twenty-three defects, all the same
18+interleaving: a third party observing liveness at T and acting on the directory entry at T+1.
1319
14−## Lint Rules: Do Not Disable Max Lines
20+**The protocol** (`daemon-endpoint-ownership.ts`): bind a private `.p<hex>` name → try an exclusive
21+`link` → on `EEXIST` prove the incumbent dead by connecting → re-check the entry hasn't changed
22+hands → probe once more → `rename` in one syscall → verify we kept it.
1523
16−NEVER add a `max-lines` disable (`eslint-disable max-lines`, `oxlint-disable max-lines`, or line-specific variants), and never add a per-file `max-lines` bump in `mobile/.oxlintrc.json`.
24+## Traps That Already Cost Us
1725
18−## File and Module Naming
26+- **Never collapse "can't tell" into "dead."** Only `connected` means occupied; only
27+ `refused`/`missing` prove death. A timeout or `EPERM` proves nothing and must decline — treating
28+ it as death deletes an endpoint still serving every terminal on the host.
29+- **`link` first, never an unconditional `rename`.** `rename` replaces whatever it finds, so it
30+ would let a starting daemon destroy a healthy one. `link` fails loudly and forces the liveness
31+ question.
32+- **`rename`, never `unlink`-then-`link`.** The latter leaves the name absent between two calls;
33+ measured across a live handover it gapped on essentially every observation, where `rename` gapped
34+ on none in ~14,500 probes.
35+- **Do not identify an entry by `birthtimeMs`.** Node documents it as sometimes holding the ctime,
36+ filesystems without a birth time report the epoch, and its granularity is often coarser than the
37+ events it must separate. Three attempts to patch around this produced three more defects; inode
38+ recycling is now settled by asking whether anything is _serving_.
39+- **Do not add a sweeper.** Deciding whether someone else's leftover is safe to delete is the
40+ question this design retired; the last one produced five defects, including deleting a live
41+ listener's only pathname. Every actor removes its own scratch name on each non-crash path.
42+- **Scratch namespaces must stay out of released builds' patterns.** Shipped versions sweep
43+ `^\.b[0-9a-f]{10}$` on age alone with no liveness check, which is why the bind name is `.p`.
44+ Deleting our sweeper does not un-ship theirs.
45+- **Never remove the endpoint on shutdown.** A departing daemon leaves a dead entry; the next
46+ publisher replaces it in one rename.
1947
20−Never use vague names like `helpers`, `utils`, `common`, `misc`, or `shared-stuff` for files, folders, or modules. They carry zero info and tend to become dumping grounds. Name files after what they _actually_ contain — prefer the concrete domain concept (e.g. `tab-group-state.ts`, `terminal-orphan-cleanup.ts`) over the generic role (`tabs-helpers.ts`, `terminal-utils.ts`). If you find yourself reaching for `helpers`, the file probably has more than one responsibility and should be split, or there's a better name hiding in the code that describes what the functions operate on.
21−
22−## Type Declarations: Prefer `.ts` Over `.d.ts`
23−
24−# Considerations
25−## Worktree Safety
26−
27−Always use the primary working directory (the worktree) for all file reads and edits. Never follow absolute paths from subagent results that point to the main repo.
28−
29−## Cross-Platform Support
30−
31−Orca targets macOS, Linux, and Windows. Keep all platform-dependent behavior behind runtime checks:
32−
33−- **Keyboard shortcuts**: Never hardcode `e.metaKey`. Use a platform check (`navigator.userAgent.includes('Mac')`) to pick `metaKey` on Mac and `ctrlKey` on Linux/Windows. Electron menu accelerators should use `CmdOrCtrl`.
34−- **Shortcut labels in UI**: Display `⌘` / `⇧` on Mac and `Ctrl+` / `Shift+` on other platforms.
35−- **File paths**: Use `path.join` or Electron/Node path utilities — never assume `/` or `\`.
36−- **Windows setup scripts**: the setup/issue-command runner is a `.cmd` batch file unless the script starts with a `#!` line — never derive that from the user's terminal-shell preference, and never launch a `.cmd` runner with a bare `cmd.exe /c` from a Git Bash pane (MSYS rewrites the `/c`). See [`docs/reference/windows-setup-shell.md`](./docs/reference/windows-setup-shell.md).
37−- **Linux native modules**: keep the glibc floor at Ubuntu 20.04 / glibc 2.31. A module compiled from source on a newer runner can reference symbol versions absent on the floor and crash the app on startup. See [`docs/reference/linux-glibc-compatibility.md`](./docs/reference/linux-glibc-compatibility.md); packaging fails if a bundled native binary needs newer glibc.
38−
39−## SSH Use Case
40−
41−All changes must consider the SSH use case. Don't assume local-only execution.
42−
43−## Folder Workspace Use Case
44−
45−All changes must consider folder workspaces as well as git worktrees. Don't assume every workspace is a git worktree.
46−
47−## Remote Wire Compatibility
48−
49−Clients and remote Orca servers update independently, so mixed versions are the normal state. Before changing anything a paired client and host exchange — RPC params, stream frames, or the content either side publishes over them — follow [`docs/reference/remote-wire-compatibility.md`](./docs/reference/remote-wire-compatibility.md). A new optional field is safe; a new stream opcode must be capability-negotiated because decoders drop unknown opcodes silently; and changing what the host publishes reaches old clients even with no wire change.
50−
51−## Git Binary Compatibility
52−
53−Orca runs the user's Git binary on native, WSL, and SSH hosts, which may all have different versions. Treat Git 2.25 as the core-workflow baseline and follow [`docs/reference/git-compatibility.md`](./docs/reference/git-compatibility.md).
54−
55−When adding or changing a Git command:
56−
57−- Check when every subcommand and option was introduced. For newer behavior, keep a baseline-compatible fallback or degrade safely.
58−- Use `GitCapabilityCache` with a narrow unsupported-error predicate so recurring operations do not retry a known-invalid command. Do not rely only on `git --version`; wrappers such as `simple-git` do not remove host-version differences.
59−- Scope capability state to the host that executes Git: native, WSL distro, SSH provider, or relay connection. Cover the first fallback, later cached calls, concurrent probes, and relevant host isolation in tests.
60−- Keep the real-binary compatibility contract in PR CI current. When adopting a newer Git feature, add its version boundary so the preferred command and fallback both run against representative Git releases.
61−- Preserve commands that begin with global Git options such as `-c` before the subcommand, including auto-maintenance suppression used by worktree-create fetches.
62−
63−## Git Provider Compatibility
64−
65−Source-control and review changes must consider GitLab and other supported git providers, not only GitHub. Keep provider-specific behavior behind explicit checks, and avoid GitHub-only naming for generic review concepts.
66−
67−## GitHub CLI Usage
68−
69−Be mindful of the user's `gh` CLI API rate limit — batch requests where possible and avoid unnecessary calls. All code, commands, and scripts must be compatible with macOS, Linux, and Windows.
48+**Residual risk.** The final probe and the `rename` are two syscalls, and POSIX has no
49+rename-if-target-is-inode-X. The harm is separately unreachable: a daemon never creates a session
50+on an endpoint it no longer holds (`daemon-server.ts`), and it drains rather than serving on.
7051
