agterm

# agterm project notes

agterm is a native macOS SwiftUI terminal on libghostty with a workspace-to-session sidebar.
Read `site/docs.html` for product behavior and `ARCHITECTURE.md` for modules, surface ownership, and
C-boundary concurrency before changing the bridge.
`README.md` is the product synopsis, not the reference.

## Working norms

- For nonstandard or risky UI requests, first explain the AppKit/SwiftUI cost and offer the standard
  alternative. Proceed if the user still prefers the custom behavior.
- Judge any change that can leave a long-standing visual artifact by what the user is left looking at,
  never by whether the mechanism is sound. A panel, badge, marker or overlay that outlives the thing it
  describes is a defect however correct the code that posted it. Give it a way to clear itself, and put
  that in the control API rather than in a private timer inside one caller, or every other caller ships
  the same artifact.
- For every new capability, propose useful control API/CLI coverage: protocol command and arguments,
  dispatch, `agtermctl`, read-back, and tests. Control-native features count; skip only chrome with nothing
  meaningful to drive.
- For each hideable titlebar/sidebar element, ask whether it should join host-free `InterfaceElement` and
  Settings > Interface. Never add that preference without approval.
- When adding a process that runs user commands or reparents a session, weigh its effect on macOS TCC
  attribution per service, up front. The responsible process is not always TCC's authorization subject:
  the #574 microphone test recorded `agterm-session-host` as responsible, `com.umputun.agterm` as the
  subject, and access allowed. Check each service rather than assuming one answer covers all of them. A
  passive `AXIsProcessTrusted` false can also be a stale grant, not a code bug: a stored grant may require
  a specific old cdhash (an ad-hoc build's requirement is a bare cdhash), so verify the row's full
  requirement against the running binary before suspecting attribution.
- Start Swift work with the relevant skills: `swiftui-expert` for UI/AppKit/Observation/rendering,
  `swift-testing-expert` for tests, and `swift-concurrency` for actors, Sendable, async, and C callbacks.
- “Show me” means build and launch a separate interactive Debug instance, not a screenshot. Use isolated
  state and socket paths, leave it running, and explain how to reach the feature.
- An isolated state dir also redirects config to `<stateDir>/config`. Copy
  `keymap.conf`, `ghostty.conf`, and `restore-denylist.conf` when real custom behavior is required.
  Set only a short `/tmp` `AGTERM_STATE_DIR` so app and inherited CLI derive the same socket.
  Prepend the Debug app's `Contents/MacOS` to PATH for custom commands; login shells may restore the
  deployed CLI, so manual commands should use the Debug binary's full path.
- A fresh isolated state dir reads as a first launch and opens the welcome alert.
  `mkdir -p "$AGTERM_STATE_DIR/windows"` before launching to skip it: `FirstRunWelcome.hasPriorState`
  looks for `settings.json`, `workspaces.json`, or `windows` before the app writes anything.
  Leave the marker out only when the welcome itself is under test.
- The control socket binds from the window scene's task, so a backgrounded `open -n -g` can leave the app
  running with no socket until a window renders. Activate the instance when the socket never appears.
- `agtermctl` never reads `AGTERM_SOCKET`; it resolves `--socket`, then `AGTERM_STATE_DIR`, then
  `~/Library/Application Support/agterm`. A shell inside the live terminal therefore defaults onto the
  live socket, and exporting a short `AGTERM_STATE_DIR` is what keeps inherited commands off it.
- After launching an instance for manual testing, do not touch it. For an assisted experiment, announce
  every action. Ask before acting when unclear.
- Put nontrivial work in an isolated worktree and remove it after merge. See the build section for artifact
  links and cleanup.
- Comments and docs are liabilities kept short. Keep only non-obvious constraints, rejected alternatives,
  or reasons the obvious implementation fails. Never narrate code, repeat a fact across surfaces, use a
  paragraph where a clause works, or preserve change history. Own each contract once and cross-reference it.
  If 25 lines of logic seem to need 100 lines of comment, fix the code.
- A doc comment longer than the body it documents is wrong. The usual cause is writing it to justify a
  review fix rather than to document the code, which belongs in the commit message.
- Test comments are rare and one line. Add one only when neither the test name nor setup reveals the goal.
  Never label arrange/act/assert, restate an assertion, or explain why a test exists.
- Review severity follows user-visible consequences: critical for data loss or broken primary paths, major
  for wrong results or broken secondary paths, minor otherwise. Documentation inaccuracies are never
  critical or major. Documentation-heavy review findings usually call for less prose.

## Toolchain and gates

- Xcodegen creates the app project; Xcode 26 builds it. Call `xcodegen`, `xcodebuild`, and `swift`
  directly through repository scripts; `mise` is unused.
- Swift 6 `agtermCore` uses complete concurrency checking and has no Xcode/libghostty dependency.
- `scripts/setup.sh` builds pinned libghostty and zmx with Homebrew `zig@0.16` and Xcode's Metal Toolchain.
  It is idempotent after artifacts exist. zmx is the plain upstream pin plus `scripts/zmx-patches/`,
  whose README says what each patch is for and how to regenerate one.
- Commands:
  - `scripts/run.sh`: setup, generate, Debug build, launch.
  - `scripts/build.sh`: setup, generate, Release build.
  - `cd agtermCore && swift test`: host-free tests; `scripts/test.sh` wraps it.
  - `scripts/test-app.sh`: isolated hosted AppKit tests.
  - `make prep|build|run|release|deploy|test|test-app|lint|clean`; `make dist VERSION=x.y.z [PUBLISH=1]`.
- `make lint` runs strict SwiftLint from the root. Root limits are 200-column lines, 1000-line source
  files, and 800-line types; test configs raise file/type limits to 2000 and inherit all other rules.
  Disabled/tuned rules reflect deliberate conventions. Zero findings are required.
- Every change must build, pass `swift test`, `make test-app`, and `make lint`.
- Run each gate ONCE, at the end, and scope everything else to what changed: a new or changed test runs
  via `-only-testing:<Target>/<Class>/<test>`. Never re-run a whole XCUITest suite to verify a narrow
  change; `agtermUITests/ControlAPIUITests` alone is 82 methods and about 7.5 minutes, and tells you
  nothing the targeted run did not.
- **An XCUITest run started from a shell inside a live agterm window can die at runner init** with
  `Failed to initialize for UI testing ... Timed out while enabling automation mode` after 60s, before any
  test case runs. The block is at runner initialization, so app code under test cannot reach it; it is not
  a defect in the diff under test. The timeout is intermittent: one retry passed on the same stale host
  minutes after a failure (2026-09-26), so retry once before treating it as blocking.
  [Unverified] cause: TCC attributes the authorization to the responsible process,
  `/Applications/agterm.app/Contents/MacOS/agterm-session-host` hosting that shell; when a deploy replaced
  the app after that process launched, the running image stops matching the file and tccd logs
  `IDENTITY_ATTRIBUTION: Failed to copy signing info for <pid> ... #-67034` (errSecCSStaticCodeChanged) in
  the same window. The correlation is measured; the causal link to the timeout is not. Diagnose with
  `log show --predicate 'subsystem == "com.apple.TCC"' --last 6m --style compact` plus
  `ps -p <pid> -o lstart` against the binary's mtime. If the retry also fails, diagnose the attribution
  issue before considering a restart; restarting agterm is Eugene's decision, never the agent's. Hosted
  `agtermTests` are unaffected; only the XCUITest runner needs the automation grant.
- For maintainer work, ask before splitting a touched long file and do not raise limits reflexively.
  Contributors need not refactor preexisting length; mention it without blocking or suggesting a limit bump.

## Worktrees and local builds

- Fetch `origin master` before creating a native Claude worktree so it forks the current remote tip.
  Do not manually `git worktree add`.
- Fresh worktrees lack ignored `GhosttyKit.xcframework`, `agterm/Resources/{ghostty,terminfo,zmx}`,
  `.ghostty-build-stamp`, and `.zmx-build-stamp`. Symlink all six from the main checkout instead of rebuilding;
  use absolute targets for resources. Each stamp makes its staged artifacts count as current. They remain
  untracked and disappear with worktree removal.
- Symlink an artifact set only while the main checkout's matching stamp equals what the worktree's
  `setup.sh` would write for that set: the revision for ghostty, and `ZMX_REV`, `ZMX_TARGET` and the
  digest of `scripts/zmx-patches/*.patch` for zmx, so a target or a patch change invalidates a set whose
  revision still matches. When either differs, remove that
  set's artifact and stamp links before setup runs and let it build locally. `setup.sh` writes stamps
  through symlinks while replacing linked artifacts with local files and directories, so a linked build
  leaves the main checkout claiming a build its artifacts never came from.
- After merge, verify the PR merge commit on fetched `origin/master`, then remove the worktree without
  changing the main checkout's branch. Squash/rebase makes removal report unmerged commits; after
  verification, discard the worktree safely. Native removal may leave a renamed branch, which must be
  deleted separately after checking the remote.
- Debug Swift code lives in `agterm.debug.dylib`; inspect it or object files, not the stub executable.
- For throwaway launch-time probes, append to a temp file. `NSLog` from `open -n` is unreliable; production
  logging uses `os.Logger`.
- `scripts/run.sh` activates an existing instance instead of loading a rebuild. Use a distinct isolated
  launch for current code.
- `make deploy` copies Release to `~/Applications`, whose app, PATH CLI, and installed hooks shadow Debug.
  Test fresh CLI/hooks with the Debug binary or redeploy and reinstall them. Debug uses
  `com.umputun.agterm.debug`, distinct from Release, but state/socket paths still require isolation.
- Launching a second instance without `AGTERM_STATE_DIR` still shares state, but no longer takes the
  running app's control socket. `ControlServer.init` takes an exclusive `flock` on `<socket>.lock` and
  `start` refuses to bind while another live instance holds it, logging `already served by another
  instance`. Ownership is settled at init so the launch window's first shell, whose environment is
  snapshotted before `start` runs, cannot bake the owner's path.
  A refused instance advertises `<socket>.unavailable` in `AGTERM_SOCKET`, so a command passing
  `--socket "$AGTERM_SOCKET"` fails rather than reaching the owner. A BARE `agtermctl` still reaches it:
  the CLI never reads that variable and resolves the default path. Isolate anyway — state is shared and
  persisted session ids resolve in both instances, so an untargeted command lands on the live terminal.
- `lsof -p <pid> | grep agterm.sock` showing an fd on a socket path `ls` cannot find means an orphaned
  socket; a window scene that never bound one is a different fault. Reaching it now takes a build
  predating the lock, or the socket file being deleted by hand.

## Protect the live terminal

- Never run a mutating `agtermctl` command on the default socket. It controls the user's live deployed
  terminal. Read-only `tree` and `window list` are tolerable; writes require explicit isolated socket.
  Never execute bundled recipes against the default instance.
- Every delegated agent that might touch the app or CLI must receive verbatim:
  “never execute `agterm`/`agtermctl` against the default socket, never launch or quit the app, static
  reading only.”
- Never kill or relaunch `~/Applications/agterm.app`, and never `pkill agterm` or `osascript … to quit`
  (both also reach dev instances). Deployment replaces files but the user decides when to restart.
- Manual Debug UI work uses a separate `open -n` instance with isolated state and short socket. Address
  its CLI with `--socket` after the subcommand. Stop only its known PID with SIGTERM; clean quit triggers
  the visible quit-confirmation alert. Use clean quit only when testing its final cwd/running-command flush.
- A stopped Debug instance can leave its Dock tile; a click on it relaunches the bundle with no
  `AGTERM_STATE_DIR`, onto the live state and daemons, and its quit rewrites the live windows files.
  After SIGTERM, confirm the tile is gone with `lsappinfo list | grep agterm.debug` and tell Eugene when
  one lingers.
- A manual-test pane opens in `$HOME`, and a pane restored from a daemon keeps whatever directory it had.
  Never type a bare `claude` into one. Always send `cd <dir> && claude` with a directory Claude Code
  already trusts, `~/dev.umputun/agterm` by default. A session rooted at `$HOME` treats every dotfile and
  repo as its project, and it stops on the folder-trust prompt, which is never yours to answer.
- Never run the Help ▸ Install installers (agent hooks, CLI, agent skill) from a Debug or worktree
  instance, and never invoke `AgentHooksInstaller` in a manual run. They write `~/.config/agterm/`,
  `~/.claude/settings.json`, and `~/.codex/`, which `AGTERM_STATE_DIR` does not isolate, and bake
  `Bundle.main`'s `agtermctl` path into the installed wrappers. A Debug install silently repoints the
  user's live hooks at DerivedData, and removing the worktree leaves them dead with no error.
  Verify installer behavior through `agtermCore` tests, or redeploy Release and reinstall from it.
- Unix socket paths cap near 104 bytes. A long scratch path lets the app launch while control bind fails.
- Use absolute repo-root paths for existence checks. Tool cwd persists across calls and often drifts into
  `agtermCore`.
- CI and release mechanics live in `.claude/rules/ci.md` and `release.md`. `CHANGELOG.md` is release-only;
  feature PRs update relevant product, skill, or engineering docs instead.

## GhosttyKit

- `scripts/setup.sh` builds upstream `ghostty-org/ghostty` at `GHOSTTY_REV` using
  `zig build -Demit-xcframework=true -Dxcframework-target=native`. No fork or disposable daily build is used.
- `GHOSTTY_REV` is `683d8db` (2026-08-25), a plain reproducibility pin carrying upstream's hidden-surface
  GPU release.
  It sat at `4dcb09ada` (2026-04-30) from June while later builds blanked scrollback on a font-size
  increase; upstream fixed that and the case was re-verified by hand before the bump. Re-test the
  font-increase case when moving it, and check `minimum_zig_version` in `build.zig.zon` against
  `ZIG_FORMULA`. The 0.15 to 0.16 jump came with the `0ba6250` bump, not this one.
- `.ghostty-build-stamp` records the rev the staged artifacts came from and is what decides a rebuild.
  Presence alone would serve an xcframework built from a different rev silently, so a `GHOSTTY_REV`
  change costs everyone exactly one libghostty rebuild and nobody keeps a stale core by accident.
- Setup stages the xcframework and `zig-out/share/{ghostty,terminfo}`. All are ignored build artifacts.
- Link the xcframework with `embed: false`; embedding breaks non-Developer-ID signatures.

## Module and callback boundaries

- `agtermCore` imports no GhosttyKit, AppKit, Metal, or CoreGraphics. Use Double-backed geometry and
  convert in the app target. Darwin Foundation can expose CG types that pass Debug/tests but crash Xcode
  26.5 Release WMO deserialization with an unresolved CoreFoundation cross-reference.
- Put model, persistence, parsing, validation, routing, response shaping, and static catalogs in
  `agtermCore`; keep the app target a side-effect adapter, continuing the #78 hoist series. Control uses `ControlDispatcher` plus
  `ControlActions`, with unmigrated commands returning nil to the app switch. Installers, status sound,
  and watermark follow the same split.
- `agtermCore` is a `.library` product consumed by the `agterm-linux` fork, so a `public` symbol may have
  a caller outside this repo and narrowing it can break that build.
  GitHub code search excludes forks by default; use `fork:true` or inspect a clone before concluding no
  downstream caller exists. The app target has no downstream consumer.
- `GhosttyCallbacks` is `@unchecked Sendable`, not `@MainActor`. C closures capture nothing and reach
  `GhosttyApp.shared`. Copy `char*` before hopping; every main-actor touch uses
  `DispatchQueue.main.async`.
- Wakeup coalesces through an `OSAllocatedUnfairLock` into one main-queue `ghostty_app_tick`. Painting is
  libghostty's own render thread, not an app callback: the embedded apprt cannot emit
  `GHOSTTY_ACTION_RENDER`, so agterm handles no draw action. Never restore the rejected continuous 120Hz
  poll or use `assumeIsolated`. See [[libghostty]] before advancing `GHOSTTY_REV`.
- `close_surface_cb` only recovers the view and dispatches; it never frees synchronously.
- A libdispatch callback closure written inside a `@MainActor` method inherits main-actor isolation, and
  libdispatch running it on another queue aborts under `dispatch_assert_queue`. Declare such closures
  `@Sendable` explicitly (`HookProcessRunner`'s `DispatchIO` cleanup and write handlers).
- The session-wide overlay slot holds a caller's program, an HTML page, or a HUD. Raw `overlayActive` answers
  only "the slot is occupied"; a layer asking "does a cover own this session's input" reads
  `Session.coverOverlayActive`, and one asking about the covering terminal surface reads
  `programOverlayActive`. Deck gates, focus routing, zoom, and scratch focus all turn on that distinction,
  so never spell a predicate inline. `control-api.md` lists the sites.
- A terminal ask has a separate slot on `Session`, independent of the HUD/program overlay slot; see [[control-api]].
- A long-lived process spawned into a surface needs a stop condition of its own. A hard-killed app runs no
  teardown, and no SIGHUP reaches the process because the pty's session leader is the surviving `login`, so
  it outlives the app in whatever loop it was in. `hud.sh` takes the app's pid through its input file and
  exits on a builtin `kill -0`.
- A confirmed Live sessions reset (Help item or `zmx.reset`) is the one path that ends CLAIMED daemons at a
  Live launch: `LiveResetConsumer` consumes the marker before any kill and only narrows it, then the
  ordinary reap runs. Nothing arms it but the dialog or an explicit `--force` request; `control-api.md`
  owns the contract.
- Live-session reap follows the requested restore mode. A requested-live launch preserves claimed daemons
  when eligibility falls back to fresh shells; a deliberate Fresh shells or Re-run commands launch reaps
  every detached app daemon in the state directory. Semantic deletion kills the named daemon, while app and
  reopenable-window close only end attach clients. Keep reap, semantic kill, and leader refresh synchronous:
  launch ordering, termination finalization, and same-call tree foreground depend on their completion.
- Live fallback capture and replay are paired across two boundaries. Clean-exit capture reads zmx-backed panes
  from one fresh resolver snapshot under the exit deadline. A restored factory consumes the pending argv only
  after `.wrapped` is established, then passes it to zmx as a create-only attach payload. A surviving daemon
  ignores it; a missing daemon runs it. Never add an app-side daemon preflight or consume on fallback.

## Cross-surface contracts

- A new user action is incomplete until protocol, dispatcher, CLI, and protocol/end-to-end tests exist.
  Toolbar/footer, menu, and control share the same action/store seam. Call out genuine visual-only exemptions.
- A state-setting command must expose its result on `ControlSessionNode`, window node, or tree top level.
  Examples include background, unseen, status and overrides, flag, split focus/ratio, overlay size,
  sidebar state/mode, workspace focus, quick visibility, geometry, fullscreen, zoom, and minimize.
  A deliberate exemption is recorded where the command's own contract lives, never left implicit; the
  captured restore slots are the one today, in `control-api.md`'s Restore section.
- Event arguments must appear in `EventFormatter.human`, not only JSON payloads.
- Control API, keymap, and model changes also update bundled
  `plugins/agterm/skills/agterm/`, the sole source for installed Claude/Codex copies.
  A capability agents should discover unprompted needs a trigger in SKILL.md's `description` and a section
  or pointer there; a reference.md entry alone is insufficient for discovery.
- `site/docs.html` is the canonical user guide and `site/commands.html` the canonical command reference.
  `README.md` is the product synopsis: pitch, install, the model, and the control-API demo.
  `site/llms.txt` is the crawler-oriented summary and discovery index.
  These three facts stay synchronized across every surface that states them: the install commands, the
  minimum macOS version, and the positioning claim
  (`a simply good terminal with a full control API`).
  The command count is NOT one of them and must not become one: no surface states a total, which is what
  keeps a new command off every page that merely mentions the catalog. `control-api.md` owns that rule.
  The positioning claim must stay consistent in substance, not byte-identical: `site/index.html`'s title and
  social tags insert `macOS` for search intent, and `site/llms.txt` carries a libghostty-based variant.
- `site/index.html` reflects major features and current `softwareVersion`; `site/commands.html` mirrors
  every command, arguments, and read-back field.
- `cookbook/` is not a synchronized surface. Recipes pin a minimum version and are fixed reactively;
  its CI checks structure and shell hygiene, not current API parity.
- Cookbook recipes are third-party work published by their author, not code the project owns.
  Review asks only three things: it does no harm, deliberately or accidentally; it does what it claims;
  and it follows `cookbook/CONTRIBUTING.md`.
  Edge cases, minor bugs, and other small findings never block the PR: approve and merge, leaving a note
  for the contributor. That note is where a recipe finding ends: never file it in `docs/backlog/`, which
  is for code the project owns, and never edit a recipe's prose unprompted.
- agterm runs only on macOS, so POSIX portability is never a finding by itself. A shellcheck SC3xxx on a
  recipe is a CI lint gate, not a runtime defect: `/bin/sh` there is bash 3.2 and `printf %q` works.
  Never propose a bash shebang as the fix; the mac shell is zsh, and CI's `.zsh` path is `zsh -n`.

## Website

- `agterm.com` is the static `site/` directory on Cloudflare Pages with no build step or repository deploy
  config. Dashboard-owned wiring deploys every master push. Canonical URLs omit `.html` because Pages
  redirects with 308.
- Assets are self-hosted: CSS, latin woff2 fonts, WebP screenshots, 1200x630 social card, and favicons.
  Inline page styles come from a design-tool export whose source archive is on the maintainer's Desktop.
- Hero images must match the fixed `1187 / 696` ratio, about 1.70:1; capture dense dashboards at that
  ratio before WebP conversion; existing shots are 2374x1392. Dashboard images may floor near 200k versus
  85-172k for single-window shots. Crossfade duration is slides times 5 seconds, delays advance by
  5 seconds, and the opaque keyframe plateau is about `1/slides`.
- Auto-fit feature grids can strand orphan cards. Use a fixed column count, explicit spans, and narrow
  media fallbacks as in `.surfaces-grid`.

## Path-scoped rules

Read the matching `.claude/rules/*.md` before subsystem work, including cross-cutting hub-file changes.
Keep these notes in semantic lines: one sentence per line, split long clauses near 100 columns, keep code
spans intact, and format long catalogs as lists.

- `sidebar.md`: outline, reorder, flagged/focus views, scoped navigation, reconciliation, persistence.
- `menu-actions.md`: actions, menus, split panes, navigation, palettes, MRU, rename, search.
- `windows.md`: window library, restoration, quick terminal, active-store resolution, quit, controls.
- `control-api.md`: protocol layers, catalog, addressing, CLI/hooks/skill installers.
- `settings.md`: settings model/UI, Ghostty config emission, translucency.
- `theme-picker.md`: preview/commit/cancel and seeded default.
- `keymap.md`: keymap parser, built-ins, custom commands/tokens, reload/edit.
- `notifications.md`: OSC/control notifications, suppression, reveal, badges, status.
- `ui-tests.md`: launch isolation including FB11763863, AppKit/XCUITest traps, cadence.
- `libghostty.md`: surfaces, rendering, AppKit, theme, overlays, cursor.
- `app-icon.md`: adaptive Icon Composer build.
- `ci.md`: jobs, filters, coverage, badge.
- `release.md`: local signing, notarization, release, Homebrew, changelog.