Add host-owned Project Actions with remote execution and worktree setup

[jsgrrchg]

Summary

This PR adds first-class Project Actions to Zeron: named shell commands that can be created, imported, edited, deleted, and launched from the selected chat's title bar.

Actions are private, account-scoped configuration owned by the engine that owns the project. Local and remote viewports use the same device-routed RPCs, while the owning engine remains responsible for resolving the project, checkout, environment, shell, and terminal.

One explicitly saved Action may also run automatically when Zeron creates a new worktree. Desktop carries worktree creation in the durable queued Run; the host starts setup before agent dispatch and exposes the already-open terminal through a command-scoped handoff without blocking send on worktree materialization or command completion.

Motivation

Projects often have a small set of commands that are repeatedly needed alongside an agent session: development servers, tests, linters, builds, or one-time worktree setup.

Running those commands from a remote viewport is not a UI-only problem. The project path, checkout, shell, persisted command, and PTY all belong to the device that owns the project. This implementation therefore makes Actions a host-owned engine feature and treats the desktop control as a remote-capable viewport onto that authority.

The trust boundary is also explicit. A repository may suggest commands through zeron.json, but merely opening or cloning it never authorizes execution. Every suggested Action must be imported and saved before it can run manually or become worktree setup.

User-facing behavior

• The selected chat title bar shows a compact split control aligned to the right of the primary title area.
• With saved Actions, the primary segment runs the preferred Action and the chevron opens the complete menu.
• With no saved Actions, the control offers Add action; importable Actions are listed in the menu when zeron.json is present.
• The editor supports six icons, name, multiline command, optional automatic worktree setup, save, and delete with confirmation.
• The last successfully launched Action is remembered per project in viewport-local UI settings and becomes the next primary Action.
• Every manual launch opens a fresh tab in the bottom terminal drawer instead of injecting into a terminal whose foreground state is unknown.
• The control is 24 px tall, keeps its full label when the title bar has enough usable space, and collapses to icon-only when the primary title-bar budget falls below 420 px.
• The control stays immediately before the right-side title-bar controls, clips session metadata safely, and hides on the new-session canvas and during expanded right-pane takeover.
• Temporary host or transport failures leave a visible Actions unavailable retry surface. Engines that do not support the new RPCs hide the control without repeated errors.

Architecture

Host-local storage

ProjectActionsStore persists Actions in the active engine profile's project-actions.json rather than in the synced Loro registry, session documents, or edge state.

The store is versioned, account-scoped, protected by an internal mutex, and written atomically through a temporary file plus rename. Each project entry records both space_id and the observed project root so an id cannot silently reuse commands after its root changes.

The owning engine normalizes all drafts and enforces the following limits:

• At most 50 saved Actions per project.
• Names are trimmed, non-empty, and limited to 80 Unicode characters.
• Commands are trimmed, non-empty, and limited to 16 KiB of UTF-8 data.
• Generated slug ids are limited to 96 bytes and receive deterministic numeric suffixes on collision.
• At most one saved Action can have runOnWorktreeCreate enabled; saving a new setup Action atomically clears the previous one.

An absent, corrupt, or unsupported-version store does not prevent the engine from opening. The engine starts with an empty in-memory store and repairs persistence on the next successful write.

Explicit imports from zeron.json

The owning engine reads an optional zeron.json from the exact project root and returns valid candidates as importableActions:

{
  "actions": [
    {
      "name": "Dev server",
      "command": "pnpm dev",
      "icon": "play",
      "runOnWorktreeCreate": false
    }
  ]
}

The parser rejects malformed JSON, unknown fields, unknown icons, invalid drafts, files above 256 KiB, or lists above 50 entries as a whole. Candidates are hidden when a saved Action already has the same exact command or case-insensitive name.

Imports are suggestions only. They cannot be addressed by RunProjectAction until the user explicitly imports and saves them into the host-local store.

Device-routed RPCs

The PR adds four unary, relay-forwardable methods:

ListProjectActions
UpsertProjectAction
DeleteProjectAction
RunProjectAction

Each desktop request includes targetDeviceId when the selected chat is owned by another device. The destination engine strips the forwarding metadata through the existing relay path and executes the same local handler used by a local viewport.

The client sends stable ids and drafts, never a run-time command, cwd, project root, or reserved environment variables. Before any run, the owning engine verifies that the Space is local, the Chat belongs to the same device and Space, and the requested cwd resolves to a valid checkout of that project.

There is no local fallback when a remote owner is offline or unreachable.

Managed terminal execution

Terminals can now open a login shell with host-resolved environment overrides, while the existing terminal path continues to use an empty override map.

Every Action invocation opens a fresh PTY, writes the saved command followed by carriage return, and returns a ProjectActionRun containing the terminal session. Zeron does not wrap the command in sh -c and does not attempt to infer whether an existing interactive terminal is idle.

Manual runs receive:

ZERON_PROJECT_ROOT=<canonical project root on the owning host>
ZERON_WORKTREE_PATH=<canonical chat worktree, only outside the main checkout>

If initial input fails after opening the PTY, the engine closes the session instead of leaking a terminal slot.

Desktop reserves a named placeholder tab before the RPC completes, attaches the returned host-side session to it, and reuses the existing subscribe/reconnect/replay pipeline. Output emitted before subscription is therefore recovered from terminal replay, and subsequent subscribe, resize, write, and close requests preserve the terminal's owning targetDeviceId.

Worktree setup

Desktop includes an optional spaceId in RunRequest.worktree. The owning engine materializes that worktree while draining the durable command, validates the Space root, starts the saved setup Action, and records its terminal in a short-lived handoff keyed by the queued command id.

Desktop polls TakeProjectActionSetup after QueueCommand acknowledges. This poll is detached from composer send state, relay-forwardable through targetDeviceId, one-shot, and ignored when an older host does not implement it. Setup always receives both ZERON_PROJECT_ROOT and ZERON_WORKTREE_PATH.

The setup launch waits only until the PTY accepts the command. It does not wait for command exit or readiness. A setup failure is logged and handed to desktop as setupError; the created worktree remains valid and the first agent turn continues.

Desktop attaches the handoff terminal to the exact minted chat, even if selection changes while setup is in flight. Direct CreateWorktree callers, including iOS, retain the optional spaceId and flattened CreateWorktreeOutcome path.

Only NewWorktree triggers setup. The main checkout and reused worktrees retain their existing behavior.

UI state and resilience

The desktop controller caches snapshots by (device_id, space_id) and models idle, loading, ready, saving, unavailable, and unsupported states.

Load generations prevent a late response from a previously selected project from replacing the active snapshot. Mutation generations additionally prevent superseded save/delete responses from closing or updating an editor for a different project.

Transport failures preserve the last successful snapshot when one exists. An initial failure synthesizes an empty visible snapshot so the title-bar control remains recoverable and can expose the retry menu instead of disappearing permanently.

UnknownMethod is treated as version skew rather than a transport failure, allowing a new desktop to continue using chats hosted by an older engine without rendering a broken control.

End-to-end flows

Manual Action

Desktop title bar
  -> RunProjectAction { spaceId, chatId, actionId, cols, rows, targetDeviceId? }
  -> owning engine validates Space + Chat + checkout
  -> owning engine loads the saved command from its private store
  -> owning engine opens a fresh PTY with host-resolved cwd and environment
  -> owning engine writes command + CR
  -> ProjectActionRun { actionId, actionName, terminal }
  -> desktop attaches the terminal to the reserved bottom-drawer tab
  -> SubscribeTerminal replays early output and continues streaming live output

New worktree with setup

Desktop
  -> QueueCommand { RunRequest.worktree: { repoPath, base, spaceId }, targetDeviceId? }
  -> owning engine validates Space, creates the worktree, and starts setup
  -> owning engine dispatches the first agent turn
  -> QueueCommand { commandId }
  -> TakeProjectActionSetup { chatId, commandId, targetDeviceId? }
  -> { ready, setupAction?, setupError? }
  -> desktop attaches setupAction to the minted chat when present

Compatibility

Caller	Engine	Behavior
New desktop	New local engine	Full CRUD, manual runs, imports, and setup terminals.
New desktop	New remote engine	Full behavior routed through targetDeviceId; paths and PTYs remain on the owner.
New desktop	Old remote engine	UnknownMethod hides Actions; the chat remains usable and no local fallback occurs.
Old client	New engine	Unknown response fields are ignored; callers without spaceId retain legacy worktree behavior and do not trigger setup.
New client	Old engine	Flattened legacy Worktree replies decode as CreateWorktreeOutcome with absent setup fields.
iOS	New remote engine	spaceId enables host-side setup; iOS continues decoding the returned worktree path only.

The flattened outcome preserves the existing top-level Worktree fields, so serializing it still decodes as the legacy Worktree type.

Trust, safety, and failure semantics

• Actions are intentionally shell commands, but only explicitly saved host-owned Actions are executable.
• A cloned zeron.json never authorizes execution by itself.
• Commands are not synced through the registry or edge and are isolated by engine profile.
• The run RPC accepts an Action id rather than arbitrary command text.
• The owning engine resolves cwd and reserved environment variables and rejects cross-device, cross-Space, missing, or invalid checkout relationships.
• Remote failures never fall back to the viewing device, home directory, ., or the viewer's interpretation of a remote path.
• Every manual run gets a new PTY, avoiding accidental input into a server, REPL, editor, or another foreground process.
• Early terminal output remains available through replay.
• Setup failure does not roll back the worktree or block the first agent turn.
• Setup is started once for a newly created worktree and is not repeated when that worktree is reused.
• Stale list, save, and delete responses cannot overwrite the currently selected project's UI state.

Validation

The current branch was validated with:

• cargo test -p zeron-proto — 19 passed.
• cargo test -p zeron-engine project_actions --lib — 7 passed.
• cargo test -p zeron-engine --test device_routing — 3 passed, including remote CRUD/run/setup ownership, replay, and offline forwarding behavior.
• cargo test -p zeron-engine --test m5_repos_diffs_terminals — 21 passed, including host-resolved manual runs, setup, fresh PTYs, environment injection, cleanup, and legacy worktree behavior.
• cargo test -p zeron-ui project_actions --lib — 5 passed, including preferred selection, responsive collapse, version skew, retry visibility, and stale load/mutation protection.
• iOS simulator build for the updated CreateWorktree caller.
• git diff --check main...HEAD.
• Static audit confirms that this branch does not add Project Actions to registry, edge, shortcuts, or keymap files.

Repo-wide formatting, clippy, and workspace-test commands still encounter pre-existing baseline issues outside this change, including existing formatting drift, warnings promoted to errors, and an unrelated shell-environment test. The targeted suites covering this PR are green.

Manual QA checklist

• Create, edit, and delete Actions from a local project.
• Confirm that enabling setup on one Action disables it on the previous setup Action.
• Launch two manual Actions and verify that they receive distinct terminal ids and tabs in the bottom drawer.
• Verify pwd, ZERON_PROJECT_ROOT, and ZERON_WORKTREE_PATH from both the main checkout and a worktree.
• Add a valid zeron.json, confirm imports remain inert, import one, and verify that it becomes executable only after saving.
• Add an invalid zeron.json and confirm that the issue appears without hiding saved Actions.
• From desktop A, manage and run Actions for a project owned by desktop B; verify that files and PTYs exist only on B.
• Disconnect B, confirm that Actions remain visibly retryable and never execute locally, then reconnect and retry.
• Create a remote worktree with setup and confirm that the setup terminal attaches to the newly minted chat and replays early output.
• Create a worktree from iOS and confirm that setup starts on the owning desktop.
• Reuse an existing worktree and confirm that setup does not run again.
• Use a new desktop against an older engine and confirm that the unsupported control stays hidden without affecting the chat.
• Resize the window and open/close the right pane; confirm right alignment, full-label mode, icon-only mode, clean title truncation, and takeover visibility.

Reviewer guide

Suggested review order:

1. crates/proto/src/entities.rs, crates/rpc/src/lib.rs, and crates/engine/src/project_actions.rs for the domain model, trust boundary, persistence, imports, and limits.
2. crates/engine/src/rpc.rs and crates/engine/src/terminals.rs for device ownership, checkout validation, forwarding, PTY creation, and setup integration.
3. crates/ui/src/terminal/panel.rs for placeholder tabs and attachment of already-open local or remote terminal sessions.
4. crates/ui/src/project_actions.rs and crates/ui/src/shell/actions_ui.rs for UI state, stale-response protection, unavailable recovery, editor behavior, and launch handoff.
5. crates/ui/src/shell/tabs.rs, crates/ui/src/settings.rs, and the Action icon assets for title-bar integration and viewport-local preference.
6. crates/ui/src/composer.rs, crates/ui/src/shell.rs, and the iOS caller for worktree setup propagation.
7. crates/engine/tests/device_routing.rs, crates/engine/tests/m5_repos_diffs_terminals.rs, and docs/reference/project-actions.md for end-to-end guarantees and user-facing documentation.

Out of scope

• Global Action keybindings or changes to Settings -> Shortcuts.
• Preview URLs, an embedded browser, port forwarding, or remote localhost tunneling.
• A native Action management UI on iOS.
• Cloud synchronization of executable commands between hosts.
• Automatic execution directly from zeron.json.
• Heuristic reuse of an existing terminal.
• Waiting for setup completion or readiness before the first agent turn.
• Durable run history, scheduling, or Action-specific exit notifications.

[wingleeio]

Requesting changes for two reproduced functional regressions at d48351a9a5c0c5bb801900daeea130d8a8a8354d (inline findings below).

Validation on the PR head:

• cargo test --locked -p zeron-proto: 26 passed.
• cargo test --locked -p zeron-engine --lib project_actions: 8 passed.
• Engine integration suites device_routing, m5_repos_diffs_terminals, and worktree_on_run: 7 + 23 + 1 passed.
• cargo test --locked -p zeron-ui --lib project_actions: 5 passed.
• git diff --check origin/main...HEAD: passed.
• Additional regression test: a 1,000-character printf payload executes, but a 6,000-character payload produces no output file. Reproduced separately with SHELL=/bin/sh, /bin/bash, and /bin/zsh through launch_project_action; the launch reports success in each failing case.
• Native Linux UI, built from this head with an isolated engine/project and an added capture example: imported a suggested Action, explicitly saved it, and launched it through the actual title-bar control. The terminal displayed the host-resolved project and checkout paths. Populated 50 saved Actions through the real RPC and confirmed that scrolling cannot reach the lower menu entries.

The 70 targeted tests pass, but do not cover these two failures. The PR's Linux browser CI also currently fails with browser input did not return after menu dismissal; this review does not establish whether that separate failure is caused by this change. I did not run macOS or iOS locally.

Screenshots below are native application captures from the isolated fixture, uploaded as GitHub user attachments. No screenshot assets or audit harness changes were committed to the PR.

Import and manual execution

Imported command awaiting explicit save

Saved Action launched from the title bar; output replayed in the terminal

50-action menu overflow

At 1100 × 760, the menu extends below the window after Action 21

After 12 downward wheel events, later Actions and Add action remain unreachable