@awebai/oats 0.22.17 → 0.22.19

package/docs/design/2026-09-07-mobile-agent-management-proposal.md

@@ -0,0 +1,228 @@
+# Proposal: manage server agents from an iPhone
+
+Status: proposed, September 7, 2026. Requested by Juan following a feasibility
+assessment. This document authorizes no implementation, deployment, or changes
+to running teams. Recommendations below are not shipped functionality.
+
+## Purpose and recommendation
+
+Let an operator manage OATS agents on a server and talk to them from an iPhone.
+Agents keep working when the phone is locked, disconnected, or switched off.
+Screenshots and files are part of the first useful experience.
+
+Start with one server reached privately through Tailscale and a mobile web app
+that can be installed on the iPhone Home Screen. Build on the existing OATS
+control and session contracts. A native iPhone app can consume the same service
+later if sharing, voice, notifications, or other native integration justify it.
+
+The substantial work is making the client/server boundary explicit and making
+conversation delivery reliable. A narrow management and terminal client is
+feasible without rewriting the kernel. A polished conversation experience is
+more than embedding the Desktop terminal in a small screen.
+
+This extends the [architecture reassessment](2026-09-07-architecture-reassessment.md)
+and its interpretation of Juan's KB direction: standard components with clear
+contracts, replaceable service providers, and preserved identity and knowledge
+across runtime changes. It does not supersede those contracts.
+
+## What exists and what is missing
+
+Assessment baseline: source main `d20f082`, with Desktop behavior inspected in
+the lead worktree containing that main. These are reusable pieces, not a claim
+that a remote mobile API already exists.
+
+| Area | Existing basis | Work needed for mobile |
+| --- | --- | --- |
+| Lifecycle and configuration | CLI-backed roster, spawn/start, model choices, retirement and schedule operations | Authenticated network access with exact target selection and truthful results |
+| Terminal access | Session adapters, HTTP pane capture/input, Electron PTY attachment | Network streaming, resize, reconnect and bounded viewer lifetime outside Electron |
+| Attachments | Desktop file/image ingestion and execution-host upload | Browser or native file selection, authenticated upload and visible transfer state |
+| Provider operations | Scoped inspection and declared capability operations | Reuse the same discovery and invocation routes in mobile views |
+| Conversations | aweb is the intended owner of durable identity, messages and delivery | Qualify the human/agent conversation, reply and replay contracts before promising chat |
+| Background operation | Durable agent sessions and OATS scheduling mechanisms | Qualify service, scheduler and message wake operation with every GUI closed |
+
+The current [Desktop HTTP backend](../../packages/desktop/server/oats-web.mjs)
+binds to loopback and checks local Host/Origin values. It assumes a trusted
+local client; it is not an authenticated remote service. Live terminal data,
+resize and attachment calls currently cross
+[Electron IPC](../../packages/desktop/main.mjs). Exposing the current port
+unchanged or running Electron headlessly would not complete the required work.
+
+## Architecture and ownership
+
+```mermaid
+flowchart TD
+    Phone[iPhone: mobile web or native client] -->|HTTPS over Tailscale| Service[OATS host control service]
+    Desktop[Desktop client] -->|Shared control contracts| Service
+    Service --> Kernel[Existing OATS CLI and kernel]
+    Kernel --> Sessions[Session adapters: tmux or Herdr]
+    Service --> Messaging[Selected messaging provider: aweb initially]
+    Kernel --> Providers[Selected knowledge and task capabilities]
+```
+
+The service is a proposed independently runnable form of the existing control
+backend, with the necessary terminal transport moved out of Electron. It
+delegates lifecycle mutations to the supported OATS CLI. Desktop adoption can
+be incremental; mobile must not introduce a second lifecycle implementation.
+
+| Component | Responsibility |
+| --- | --- |
+| OATS kernel | Construction, lifecycle, runtime/model configuration, host placement, schedules and capability resolution |
+| Host control service | Authenticated client access, scoped command dispatch, bounded live observations, attachments and terminal viewers |
+| Session backend | Durable execution, attach/detach, literal input, resize and terminal observation |
+| Messaging provider | Durable identity, conversations, events, delivery and any missing human/agent messaging semantics |
+| Knowledge provider | Knowledge representation, access, harvest and promotion policy |
+| Phone and Desktop | Operator interaction and presentation of the same contracts |
+
+Use one control service for the selected deployment on a host, not a process
+per agent or client. Existing schedulers and message wake mechanisms remain
+responsible for their work; do not build another scheduler or wake broker in
+the mobile client. Share bounded subscriptions and roster refreshes where
+possible. Open terminal viewers only when needed, apply output backpressure,
+and detach abandoned viewers without stopping agents.
+
+tmux and Herdr remain interchangeable session adapters. Mobile access does not
+require a Herdr migration. Start with a direct connection to one execution
+host; later add saved server endpoints or reuse OATS registered-host routing.
+SSH credentials for routed hosts stay on the routing server, not the phone.
+
+## Private access through Tailscale
+
+Install the ordinary Tailscale app on the iPhone and connect the server to the
+same tailnet. Use Tailscale Serve to proxy the loopback service over HTTPS,
+accessible only through the tailnet's access rules. No embedded VPN or public
+Funnel endpoint is needed. This is a proposed deployment choice, not a current
+OATS installation instruction. [Tailscale Serve documentation](https://tailscale.com/docs/features/tailscale-serve)
+
+Network membership must map to an explicit authorized operator. For an initial
+single-owner deployment, choose a simple revocable application session or
+validated Tailscale identity; do not add a second account platform. If trusting
+Serve's identity headers, keep the backend reachable only through the trusted
+local proxy path and follow its header-handling requirements. Configure the
+actual HTTPS Host/Origin rather than removing the existing checks.
+[Tailscale identity headers](https://tailscale.com/docs/features/tailscale-serve#identity-headers)
+
+Authorize every action, terminal attachment and upload against a registered
+workspace and exact instance home. Keep runtime permission settings such as
+`yolo` separate from who may control the agent. Exclude multi-tenant hosting
+and elaborate permissions administration from the first version.
+
+## Phone experience
+
+The primary screen lists workspaces and their agents, with readable names and
+running, stopped, needs-input or unknown states. A disconnected server is
+unreachable, not evidence that its agents stopped. Do not infer needs-input
+or task completion solely from terminal activity.
+
+An agent page offers conversation, start controls and session details. Starting
+a stopped agent uses its existing home and shows runtime/model options and
+effective permission mode. Make a launch override distinct from editing future
+defaults. A running agent's model does not silently change because a setting
+was edited. Interrupt and retirement are explicit actions with their existing
+semantics; retirement is not relabeled as a harmless Stop button.
+
+The composer supports text and selected photos/files with visible upload state.
+Upload to the agent's execution host, preserve the destination while a transfer
+is in flight, and submit only when attachments are ready. Failed transfers stay
+visible and must not silently redirect to another agent. Start with a file/photo
+picker; system dictation can supply text. A native share extension and realtime
+spoken conversation are later options.
+
+Terminal access is a secondary view for interactive harness prompts and tools.
+Provide touch-accessible Escape, interrupt and other essential terminal keys.
+Avoid exposing tmux session names, Desktop split layouts or backend chrome.
+Pasting or uploading into a terminal does not automatically press Enter; a
+conversation Send action is an explicit submission.
+
+## Reliable conversations and background behavior
+
+Terminal input is useful across harnesses, but a pane transcript is not a
+durable conversation model. Rich chat should use the selected messaging
+provider, initially aweb. Missing durable reply, read-state or replay semantics
+belong in that provider's contract, not an OATS-specific message database or an
+ANSI-output parser. An installation without those capabilities can still offer
+management and a terminal, with chat availability described honestly.
+
+Before qualifying chat, establish the following behavior:
+
+- The operator has their own sender identity; the client does not impersonate
+  the destination agent. Replies remain associated with the conversation.
+- Stable message IDs and replay cursors allow reconnect and missed-message
+  retrieval. Retry after an uncertain send does not submit the same request
+  twice. Offline text remains a draft until explicitly sent; do not queue
+  terminal keystrokes or destructive controls for automatic replay.
+- Accepted, delivered and acted-on are different observations. An input write
+  or agent wake is not proof of a completed task. Unknown outcomes remain
+  unknown until the existing operation can be reconciled.
+- Delivery and wake continue on the server while clients are absent. Waking a
+  running harness and starting a stopped instance are different actions;
+  follow explicit policy before a message starts an agent or consumes compute.
+
+iOS normally suspends background apps. Do not depend on an always-connected
+phone SSE, WebSocket or SSH session. The server retains state; a notification
+signals new activity, and reopening the client fetches authoritative updates.
+Notifications can be delayed or disabled and are not delivery receipts.
+[Apple background execution documentation](https://developer.apple.com/documentation/uikit/extending-your-app-s-background-execution-time)
+
+Home Screen web apps support Web Push on iOS/iPadOS 16.4 and later, with
+permission requested through user interaction. Native applications can use
+APNs. Both require a server-side notification path and device testing. Keep
+sensitive message bodies out of lock-screen notifications by default. Private
+application access can remain on Tailscale while the server makes outbound
+connections to the push service; test this combination on a real phone rather
+than assuming VPN reconnection or notification behavior.
+[WebKit Web Push documentation](https://webkit.org/blog/13878/web-push-for-web-apps-on-ios-and-ipados/)
+[Apple remote notification documentation](https://developer.apple.com/documentation/usernotifications/setting-up-a-remote-notification-server)
+
+## Proposed delivery sequence
+
+1. **Prove the service boundary.** Extract only what an independent client
+   needs, retain existing CLI dispatch and add authenticated network access.
+   Qualify one server over Tailscale, including operation with Desktop closed.
+2. **Deliver mobile management and terminal access.** Workspace/agent list,
+   start with model choices, explicit lifecycle actions, terminal input/output,
+   screenshots/files and reconnect. Reuse existing schedule controls and
+   provider inspection. This is useful without claiming polished chat.
+3. **Qualify conversations and notifications.** Resolve the messaging-provider
+   contract gaps, then implement conversation presentation, replay, send
+   deduplication and opt-in notifications. Prove delivery while the app sleeps.
+4. **Decide on native and broader hosting.** Use actual phone experience to
+   choose whether native sharing, voice and polish justify another client.
+   Expand to multiple servers through existing routes or explicit endpoints;
+   avoid adding a fleet control platform as a prerequisite.
+
+The browser client is the recommended first delivery vehicle, not an
+architectural dependency. If native is chosen first, the same server and
+messaging requirements apply. No calendar estimate is justified until the
+service extraction and conversation-contract gaps have been scoped.
+
+## Acceptance before calling it usable
+
+- With Desktop closed and the phone locked or disconnected, existing agents
+  keep running and an explicitly enabled test schedule and message wake work.
+  No production team or harvest schedule is changed to demonstrate this.
+- Start the intended stopped home with the chosen runtime/model. Same-named
+  instances elsewhere cannot receive its actions. Unreachable hosts display
+  uncertainty and retrying an interrupted mutation does not blindly repeat it.
+- Upload an actual iPhone screenshot and a file to the execution host; verify
+  complete bytes and destination, and demonstrate a visible transfer failure.
+- Switch Wi-Fi/cellular, lock/unlock, and reconnect. Conversation history catches
+  up without duplicate sends. A terminal reconnect can show a bounded current
+  capture; it must not pretend to recover a durable conversation transcript.
+- Close terminal views and disconnect abruptly without killing agent sessions
+  or accumulating PTYs. Repeated reconnects and slow clients leave bounded
+  memory/process use; share observations instead of polling each agent per view.
+- Test a real notification, denied notification permission, expired client
+  access and tailnet disconnection. The UI preserves drafts and accurately
+  states what it knows, without showing an unsuccessful send as delivered.
+- A different knowledge provider's declared operations remain usable without
+  mobile code assuming OKF, a particular file layout or a universal harvester.
+
+Open implementation decisions are the initial operator authentication method,
+the existing aweb contracts that need extension, notification ownership under
+the messaging provider, and the precise terminal stream protocol. Settle them
+with narrow proofs before expanding scope. This proposal changes neither
+current deployment defaults nor the priority of ongoing reliability work.
+
+Related contracts: [provider operations](operations-contract.md),
+[Desktop CLI API](../desktop-cli-api.md), [servers](../servers.md),
+[schedules](../schedules.md), and [Desktop](../desktop.md).

package/docs/design/launch-configurations.md

@@ -0,0 +1,164 @@
+# Launch configurations and launch recipes
+
+A **launch configuration** is a named way to start a harness, declared per
+scope under `launch-configs:` in `oats-config.yaml` (see
+docs/configuration.md): runtime, an executable, literal arguments,
+environment (literals or `{fromEnv}` references), model, yolo. It is
+independent of any soul; a soul may name one as its default
+(`launch-config:` in soul.yaml, `oats soul set --launch-config`), and a
+spawn, start or restart selects one by name.
+
+A **launch recipe** is what a start is made of, recorded in the instance's
+`instance.json` under `launch` beside the rendered `command`:
+
+```json
+{
+  "version": 1,
+  "runtime": "claude",
+  "launchConfig": "personal", "launchConfigSource": "/scope",
+  "executable": "/scope/tools/claude-wrapper.sh",
+  "executableDeclared": "./tools/claude-wrapper.sh", "executableResolvedFrom": "relative to /scope",
+  "args": ["--settings", "/abs/settings.json"],
+  "env": { "KEY": { "fromEnv": "SRC" }, "LIT": "plain" },
+  "model": "claude-opus-5", "yolo": true,
+  "hooks": {
+    "launch": { "claude": "--dangerously-load-development-channels plugin:aweb-channel@awebai-marketplace" },
+    "env": { "AWEB_DELIVERY": "session" },
+    "contributions": [{ "capability": "oats.aweb", "layer": "messaging", "level": "/scope", "settings": { "delivery": "session" }, "trust": { "trusted": true, "integrity": "sha256-..." }, "launch": { "claude": "..." }, "env": ["AWEB_DELIVERY"] }]
+  },
+  "prompt": { "kind": "task-file", "file": "TASK.md" }
+}
+```
+
+The rendered `command` is produced by one renderer from the recipe. With no
+configuration it is byte-identical to what spawn rendered before recipes
+existed, so an older kernel starts such a home unchanged, and the golden
+matrix freezes that. Configuration `args` go after the runtime's own
+options and before capability launch arguments (for claude and codex the
+`--` separator keeps them from consuming the task; for pi they follow the
+task, like capability arguments). Every argument and literal value is
+single-quoted: spaces, quotes and metacharacters are literal.
+
+## Environment references
+
+`{fromEnv: SRC}` renders as `NAME="$SRC"` in the command: the persisted
+command, the pending receipt and every answer carry the reference, never a
+value. At start the execution host checks each source variable is set
+(`E_LAUNCH_ENV_MISSING` before anything is created or stopped) and hands the
+source variables to the pane only (tmux `-e`; a Herdr launch exports them in
+the launched shell). Literal values are non-secret by contract but no answer
+shows them: `list` and `preview` redact every environment value.
+
+## Selection rules
+
+- A named configuration is a unit. `--launch-config NAME` with a `--runtime`
+  that disagrees with the configuration's runtime is refused
+  (`E_LAUNCH_CONFIG_MISMATCH`) before anything happens; the same runtime may
+  be repeated; `--model` and `--yolo` override the configuration's fields.
+- Without `--launch-config`: a spawn takes the soul's `launch-config` default
+  or none; an existing home keeps its recorded configuration, except that
+  `--runtime` alone deliberately leaves it behind and renders the new
+  runtime's defaults (no old executable or args are carried).
+- Model: explicit, else the configuration's, else on an existing home the
+  recorded model when the runtime is unchanged, else the runtime's native
+  default; a spawn without either resolves the soul's preference for the
+  runtime. A model never crosses runtimes.
+- Executable: the configuration's (bare name on PATH; a path resolved against
+  the declaring scope when relative) or the runtime's default (claude through
+  `oats-claude-config`). It must be a regular executable file; it is never
+  run to probe it. Capability runtime-package requirements are checked with
+  the runtime's default binary, as at spawn.
+
+## Capability boundary
+
+Spawn hooks contribute `launch` arguments keyed by runtime and `env` values.
+Launch arguments are runtime-specific by construction; environment is
+runtime-neutral by contract. The recipe records both with per-capability
+provenance (settings and trust at spawn). A later start on the same runtime
+reuses them. A runtime switch reuses the environment and needs the new
+runtime's launch arguments from the same capabilities: a capability that
+answered arguments for the old runtime and none for the new one refuses the
+switch (`E_LAUNCH_PREPARATION`) with the remedy (change that capability's
+setting, or the provider declares a `launch` hook). Spawn hooks are never
+re-run by a start or restart.
+
+## `oats launch-config preview`
+
+Read-only; nothing is locked or started. `--home ABS` describes an existing
+home under a selection (`selection.source`: `frozen` when nothing was
+selected, `config` when re-resolved, `frozen-command` for a home that
+predates recipes, whose selection needs the restart conversion);
+`--soul NAME [--dir SCOPE] [--agents-root ABS]` describes a new instance.
+Answer: `{context, selected, selection:{source, launchConfig, runtime,
+model, yolo}, runtime, model, modelSource, yolo, launchConfig,
+launchConfigSource, executable:{path, declared, resolvedFrom}, argv,
+environment:[{name, redacted|fromEnv}], command (redacted rendering),
+prompt:{kind:"task-file", file:"TASK.md"}, hooks (redacted),
+preflight:[{check: executable|environment|model|capabilities, ok, detail}],
+ok}`. The TASK body is never included.
+
+## Starting and restarting an existing home
+
+`oats session start --home ABS` runs the recorded recipe as it is (a
+`--model` re-renders the model in place and the recipe follows). With
+`--launch-config`, `--runtime` or `--yolo` the recipe is re-resolved by the
+same planner preview uses, against the home's recorded context, and every
+check runs before anything is observed: the recipe's shape, the executable
+(regular file, executable), the references (set on this host), the
+capabilities' contributions (below), the runtime packages. A recorded
+reference is re-checked on every start path, model-only starts included,
+and the pane receives the source's value under the kernel alias.
+
+`oats session restart --home ABS [same flags] [--stop-grace SECONDS]` stops
+the running harness and starts again in place under the one per-home lock:
+
+1. Every preflight above, first. A refusal leaves the harness running.
+2. The stop: SIGTERM to every process under the pane's launcher (a wrapper
+   that does not exec, the harness, their children), then a bounded wait
+   (default 20 s) for the signalled processes to be gone and the session to
+   read as a bare shell or stopped. Nothing is escalated: a harness still
+   there when the wait ends is reported (`E_SESSION_STOP_FAILED`, with the
+   processes still running) and nothing is launched. Elapsed time is never
+   taken as exit; a turn interruption is never taken as exit.
+3. The in-place start, with the pending receipt carrying the new recipe,
+   runtime and yolo, exactly as a start does; `.oats-restart.json` keeps the
+   stop's facts (what was signalled, when, whether exit was observed).
+
+What the harnesses do on SIGTERM, from their installed sources and
+documentation as read by the operating lead on 2026-09-07 (no live process
+signalled): pi (@earendil-works/pi-coding-agent 0.84.2) registers
+SIGTERM/SIGHUP handlers that end tracked children, dispose extensions and
+exit; Claude Code's documentation makes Ctrl-C state-dependent (interrupt,
+clear, double-press exit) and does not establish that an external SIGTERM
+runs its SessionEnd hook; Codex's documentation establishes no SIGTERM
+cleanup guarantee. So the contract is the request and the observation, not
+a promise that a harness flushes its latest conversation: OATS preserves
+the home, work, identity and notes; an old native conversation's unsaved
+state is the harness's own. Wrappers should exec the harness or forward
+signals. A longer `--stop-grace` can accommodate hook cleanup.
+
+## Homes that predate recipes
+
+A home with a recorded `command` and no `launch` is converted narrowly when
+a start selects something: only the kernel's own generated shapes are
+recognized (identity environment, the binary, the runtime's template
+arguments, `--model`, yolo, the task prompt). Other environment is kept and
+attributed to the capability whose recorded declaration (`environment`,
+`environmentNamespaces` in `capabilityRuntime`) owns it, so a session-delivery
+home switches runtime with its `AWEB_DELIVERY` intact; spawn hooks are never
+re-run. Any other argument is unclassified: the start is refused, naming the
+arguments, unless an active trusted capability declares a `launch` hook that
+prepares the launch anew (then its answer replaces them). The conversion is
+recorded (`launch.legacy`) by the start that uses it.
+
+## The `launch` hook
+
+A capability may declare `hooks.launch`. It runs on a start or restart of an
+existing home (never at spawn, never spawn's identity work), side-effect-free
+by contract, with `OATS_RUNTIME` set to the target runtime and
+`OATS_PREVIOUS_RUNTIME` to the recorded one, and answers `{launch:{<runtime>:
+args}, env:{...}}` for that runtime; its answer replaces the capability's
+recorded contribution. Without it, a capability that contributed
+runtime-specific arguments at spawn cannot follow a runtime change
+(`E_LAUNCH_PREPARATION`), and a capability the scope no longer trusts has its
+recorded arguments withheld the same way.

package/docs/desktop-cli-api.md

@@ -20,6 +20,14 @@ prints exactly one JSON object on stdout:
 `version` is the installed package's exact semver (e.g. `0.20.0`).
 Desktop 0.22 accepts `desktopApi === 1` and semver `>=0.22.0 <0.23.0`.
 
+Optional features are negotiated from the probe's `features` array. Starting
+an existing home requires `session-start`; named launch configurations and
+runtime/permission overrides require `launch-config`; restarting a running
+home also requires `session-restart`. Desktop checks the corresponding
+`remote` entries before offering these operations for a server. The router
+then probes the execution host before sending a mutation. An absent feature
+means an update is needed; it is not inferred from the version number.
+
 The band is widened one kernel minor at a time, after confirming this v1
 surface is unchanged, and always admits the kernel published by the same
 release — Desktop and the CLI are built from one tag, so a band excluding its
@@ -36,7 +44,65 @@ no progress prose (progress goes to stderr):
 
 ## Mutations exposed to Desktop v1
 
-Only two:
+The commands below use the same envelope. Additional capability operations
+are described in [the operations contract](design/operations-contract.md).
+
+### Existing-home launch and restart
+
+```text
+oats session start --home /absolute/home [--server id] \
+  [--launch-config name] [--runtime pi|claude|codex] \
+  [--model id] [--yolo|--no-yolo] --json
+oats session restart --home /absolute/home [the same options] --json
+```
+
+Desktop addresses the exact existing home from the selected workspace's
+roster. Restart is one kernel command. The kernel owns configuration
+validation, stop observation, the lifecycle lock, launch recovery and session
+metadata. Desktop does not implement restart by retiring and spawning.
+Failure or timeout requires a fresh status check before retrying: a lost
+response does not establish that launch failed.
+
+For a remote home, its saved route supplies the execution host even if its
+registration has subsequently changed. The remote kernel validates the new
+configuration before stopping the current harness. A missing feature fails
+before any stop/start command is sent.
+
+### Launch configurations
+
+```text
+oats launch-config list [--dir /scope | --home /home | --soul name --agents-root /scope/agents] --json
+oats launch-config set name --file /private/definition.json [--keep-env] --dir /scope --json
+oats launch-config remove name --dir /scope --json
+oats launch-config preview (--home /home | --soul name --agents-root /scope/agents --dir /scope) \
+  [--launch-config name] [--runtime runtime] [--model id] [--yolo|--no-yolo] --json
+```
+
+All accept `--server id`. Scope edits follow the registration; inspection and
+preview of an existing home follow its saved route. A local definition file
+is serialized to SSH stdin and read on the host with `--file -`; the local
+filename is never passed to the server as though it existed there.
+
+The list result supplies `context`, `selected` and `configurations`. Each
+configuration has a name, runtime, executable, literal argument array,
+environment, model, permission choice and declaring `source`. Environment
+literals appear as `{ "redacted": true }`; references appear as
+`{ "fromEnv": "VARIABLE_NAME" }`. Optional executable/model/yolo fields can be
+null. An editor must not write redaction markers back. `--keep-env`, with
+`env` omitted from the replacement definition, copies the effective named
+configuration's environment once into the complete replacement.
+
+Preview is read-only and returns a redacted invocation plus `preflight`
+checks. A successful inspection envelope can contain `result.ok: false`:
+the selected launch is not ready. Desktop displays the failed checks rather
+than treating successful inspection as permission to launch. Environment
+references resolve on the execution host at launch, including subsequent
+starts of the saved recipe. Editing a named definition does not change a
+running instance or silently update its frozen launch recipe. Select the
+configuration explicitly on a later start/restart to apply the new definition.
+
+See [launch configuration syntax](configuration.md) and
+[the Desktop start/restart workflow](desktop-instance-start.md).
 
 ### `oats spawn <agent> … --json`
 

package/docs/desktop-instance-start.md

@@ -5,25 +5,61 @@ The Desktop roster is the place to return to it:
 
 - A running row opens its terminal.
 - A stopped row offers **Start…**. Clicking the row opens the same dialog.
+- A running row's action menu offers **Restart with…** to change harness or launch configuration in the same home.
 - The hierarchy's action popover offers **Start…** for a stopped instance.
 - An unknown status is shown as unknown, not as permission to launch another process.
 
-The Start dialog names the existing instance, runtime and host. Enter a model
-or leave the field blank to retain its recorded choice. Available local model
+The Start/Restart dialog names the existing instance, runtime and host. Choose
+a named launch configuration or keep the recorded launch. Without a selected
+configuration, the harness can also be changed directly. A named configuration
+fixes its harness; model and permission choices can override its defaults.
+Enter a model or leave the field blank to use the selected launch's default.
+An old harness's model is not carried to a different harness. Available local model
 suggestions are advisory; a model ID can also be typed. Start uses the saved
 briefing and state in a new harness conversation; it does not resume an old
 harness conversation ID. After the launch appears in the roster, Desktop
 opens the instance's terminal.
 
-If the instance is already running when the dialog checks, its action becomes
+If an ordinary Start dialog finds the instance already running, its action becomes
 **Open terminal**. A failed or timed-out start requires **Refresh status** before
 another attempt, because the launch may have succeeded before the reply was
 lost. Changing workspaces dismisses the dialog and prevents a delayed launch
 reply from opening a terminal in the wrong workspace.
 
+**Restart with…** is explicit: after validating the new configuration, the
+kernel stops the current harness and starts the selected one. It does not
+retire the instance, rerun identity creation or replace its worktree. A stop
+that cannot be confirmed does not authorize another launch. Save in-progress
+work before restarting; the old harness conversation is not transferred to
+another harness.
+
+Restart requests termination and waits for the current process to stop before
+launching its replacement. If stopping times out, it leaves the instance for
+inspection instead of forcing a kill or launching a second harness. OATS
+preserves the home and work; it cannot guarantee that a harness or custom
+wrapper saves all of its in-flight conversation state. Wrappers should
+`exec` the harness or forward termination signals correctly.
+
+**Preview invocation** asks the execution host for the resolved command and
+displays it as text, with environment values redacted. It never launches an
+agent. **Manage launch configurations** in the dialog creates or updates named
+configurations at the displayed scope, including executable/wrapper, a JSON
+argument list, environment references, model and permissions. Saving a
+configuration changes its definition; applying it to an existing home requires
+an explicit Start or Restart. When editing redacted environment values, keep
+**Preserve the saved environment** selected or enter a complete replacement.
+Use the server's workspace to manage configurations defined on that server.
+
 Desktop sends `POST /api/start/<instance>?ws=…&home=…` (and `server=…` for a
 remote instance). The backend resolves that exact roster identity and calls
 `oats session start --home <absolute-home> [--server <id>] [--model <model>] --json`.
+Launch choices add `--launch-config`, `--runtime` or `--yolo`/`--no-yolo`.
+Restart uses `POST /api/restart/<instance>?ws=…&home=…` and the single kernel
+command `oats session restart` with the same selectors and choices.
+Configuration inspection and editing use `POST /api/launch-configs?ws=…`,
+routed through `oats launch-config list/set/remove/preview`. These features
+require the CLI's `launch-config` and `session-restart` capabilities; old
+clients/hosts receive an update explanation instead of unsupported arguments.
 The installed CLI must advertise `session-start`; remote starting also needs
 the remote operation. The execution host checks the actual saved session
 before launch. Desktop does not scaffold a home or execute a launcher itself.

package/docs/oats-config.schema.json

@@ -84,6 +84,34 @@
       "required": ["name"],
       "additionalProperties": false
     },
+    "launch-configs": {
+      "type": "object",
+      "description": "Named ways to start a harness, independent of any soul. The closest scope declaring a name provides the whole entry (no merging between scopes). Selected by name at spawn or session start/restart; explicit flags override its fields.",
+      "propertyNames": { "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$" },
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["runtime"],
+        "properties": {
+          "runtime": { "type": "string", "enum": ["pi", "claude", "codex"], "description": "The harness family this configuration starts; it decides the kernel's own baseline arguments (skills, instructions, task) and how model/yolo are expressed." },
+          "executable": { "type": "string", "minLength": 1, "description": "The program to run instead of the runtime's default binary: a bare name is looked up on PATH on the execution host; a path containing a slash is resolved against the declaring scope's directory when relative. Checked to exist and be executable before any start; never executed just to probe it." },
+          "args": { "type": "array", "items": { "type": "string" }, "description": "Extra arguments, each passed literally (no shell interpretation): native configuration files or profiles go here as ordinary arguments." },
+          "env": {
+            "type": "object",
+            "propertyNames": { "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
+            "additionalProperties": {
+              "oneOf": [
+                { "type": "string" },
+                { "type": "object", "additionalProperties": false, "required": ["fromEnv"], "properties": { "fromEnv": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" } } }
+              ]
+            },
+            "description": "Environment for the harness. A string is a literal (non-secret by contract; still redacted in every answer). {fromEnv: NAME} is resolved from the execution host's environment at start time; the reference, never the value, is recorded. A missing reference refuses the start before anything stops."
+          },
+          "model": { "type": "string", "minLength": 1, "description": "Model for this configuration's runtime; overrides the soul default when this configuration is selected." },
+          "yolo": { "type": "boolean", "description": "Permission bypass for this configuration; overrides scope and soul defaults when selected." }
+        }
+      }
+    },
     "agent-types": {
       "type": "object",
       "description": "Agent families declared by name; membership is `type: <name>` in each soul.yaml.",