@awebai/oats 0.29.3 → 0.30.0

package/capabilities/oats-review/skills/code-review/SKILL.md

@@ -1,44 +0,0 @@
----
-name: code-review
-description: General code review discipline for reviewing a diff or commit range — correctness, design, readability, tests, and API surface, with severity-ranked, actionable findings. Use when asked to review code changes, a commit, a diff, or a PR for quality.
----
-
-# Code review
-
-Review the CHANGE, not the codebase. The standard (from Google's engineering
-practices): approve when the change **improves overall code health**, even if
-imperfect — demand blockers, suggest the rest.
-
-## Pass order (read the diff twice)
-
-**Pass 1 — does it work?**
-- Correctness: logic errors, off-by-one, inverted conditions, wrong operator.
-- Edge cases: empty/null/undefined inputs, zero/negative counts, unicode,
-  concurrent access, timeouts, partial failure mid-operation.
-- Error handling: swallowed exceptions, missing cleanup on the error path,
-  errors that lie about the cause. Every catch must justify itself.
-- State: mutation of shared state, stale caches, ordering assumptions.
-- Resource lifecycle: files/handles/processes/listeners opened but not closed.
-
-**Pass 2 — should it be this way?**
-- Design: is this the simplest change that solves the problem? Flag
-  speculative generality and dead configurability.
-- Consistency: does it follow the codebase's existing patterns, naming, and
-  error conventions? (Local consistency beats personal preference.)
-- Readability: could a maintainer six months from now follow it without the
-  PR description? Names carry meaning; comments explain WHY, not what.
-- API surface: new exports/flags/config keys are forever — are they earned?
-- Tests: does the change carry tests that would FAIL if the logic regressed?
-  Tests that mirror the implementation instead of the behavior are findings.
-- Performance: only flag measurable problems (N+1, unbounded growth,
-  sync-blocking hot paths) — not micro-optimizations.
-
-## Reporting
-
-- Verdict: `APPROVE` / `APPROVE WITH NITS` / `NEEDS CHANGES`.
-- Each finding: `severity — file:line — what + why + concrete fix`.
-  Severities: **blocker** (wrong/unsafe/regression), **important** (should
-  fix before merge), **nit** (better, not required — prefix "Nit:").
-- Ask questions where intent is unclear instead of asserting a fault.
-- Do not pad: no restating the diff, no praise quotas, no style opinions a
-  formatter could hold. If it's clean, say APPROVE and one line why.

package/capabilities/oats-review/skills/security-review/SKILL.md

@@ -1,59 +0,0 @@
----
-name: security-review
-description: Security-focused review of a diff or commit range — injection, secrets, trust boundaries, authz, unsafe deserialization, supply chain, and path/command safety, ranked by exploitability. Use when asked to security-review changes or as the second pass of a full review.
----
-
-# Security review
-
-Review the change as an attacker would read it: every new input is hostile,
-every boundary crossing is an opportunity. Grounded in the OWASP code-review
-model — findings ranked by exploitability, not by pattern-match count.
-
-## Checklist by trust boundary
-
-**Inputs (anything the process didn't create itself)**
-- Command injection: user/config/network data reaching `exec`/`spawn`/shell
-  strings. Quoting is not escaping; prefer argv arrays. Flag every
-  interpolated shell string that carries external data.
-- Path traversal: joins with external segments (`../`), symlink following,
-  zip-slip in extraction. Require canonicalize-then-prefix-check.
-- Injection into interpreters: SQL/NoSQL/LDAP/regex/eval/Function/template
-  engines fed external strings.
-- Deserialization: YAML/JSON/pickle-style loads of untrusted bytes with
-  type resolution or object construction.
-- SSRF: URLs from outside fetched by the server; check scheme/host pinning.
-
-**Secrets & data**
-- Hardcoded credentials, tokens, private keys — including in tests, fixtures,
-  and example configs. Entropy-looking strings deserve a question.
-- Secrets in logs, error messages, process args (visible in `ps`), URLs.
-- New persistence of sensitive data: is it needed, is it protected, is it
-  cleaned up on retire/delete paths?
-
-**AuthN/AuthZ**
-- New endpoints/commands/IPC surfaces: who can reach them, and what do they
-  authorize against? "Bound to localhost" is a real but WEAK boundary — note
-  what a local malicious process could do.
-- Privilege boundaries: does the change let low-trust config/data cause
-  high-trust execution (hooks, plugins, migrations, CI)?
-- TOCTOU: check-then-use on files/permissions/state.
-
-**Supply chain & execution**
-- New dependencies: are they necessary, pinned, and from expected owners?
-- Downloaded/cloned artifacts: integrity-checked before execution?
-- Anything that writes then executes (temp scripts, curl|sh patterns).
-
-**Web-facing (when applicable)**
-- XSS: external strings reaching innerHTML/attributes without escaping.
-- CSRF on state-changing endpoints; CORS wildcards; missing content-type
-  discipline on APIs.
-
-## Reporting
-
-- Verdict shares the scale: `APPROVE` / `APPROVE WITH NITS` / `NEEDS CHANGES`
-  — any credible injection/secret/authz finding is a **blocker**.
-- Each finding: `severity — file:line — attack scenario in one sentence +
-  concrete fix`. If you cannot articulate the attack, downgrade to a
-  question rather than inventing a threat.
-- Distinguish "exploitable now" from "hardening" — both are reportable,
-  only the first blocks.

package/docs/conventions.md

@@ -1,90 +0,0 @@
-# Conventions — canonical files and generated views
-
-OATS uses one canonical source for durable soul content and generated,
-instance-local views for deployment composition.
-
-## Operating documents
-
-```text
-souls/<name>/AGENTS.md          # canonical role instructions (in the member repo)
-souls/<name>/CLAUDE.md -> AGENTS.md
-instance/AGENTS.md              # generated regular file
-instance/CLAUDE.md -> AGENTS.md
-```
-
-Never maintain an independent soul `CLAUDE.md`. Config-dependent capability,
-work-mode, and workspace instructions belong only in generated instance
-`AGENTS.md`; they must not be reconciled into the committed soul.
-
-Generated blocks use `<!-- oats:<source> src=<file> -->` markers for
-provenance. Edit the canonical soul, source file, or target binding, then spawn
-a new instance. `oats doctor --soul <name>` previews the same final composition.
-
-## Skills
-
-The only OATS-managed runtime skill root is the instance:
-
-```text
-instance/.agents/skills/                    # canonical exact set
-instance/.claude/skills -> ../.agents/skills
-```
-
-Spawn copies kernel + soul-private + active capability skills into real
-instance-local directories there. Directory symlinks are not used because
-harness recursive discovery may not descend through them. Under the workspace
-model (0.25) every capability is copied whole into
-`instance/.oats/modules/<capability>/` and its skills into
-`instance/.agents/skills/<capability>/<skill>/`; nothing is installed at a
-config level. Config-level `.agents/skills` is not an OATS capability source
-or an ambient runtime discovery root.
-
-Harnesses start normally (workspace-model decision 13, and the behaviour of
-every launch a 0.25 kernel performs, classic homes included): Pi starts with
-cwd = the instance home, the composed `AGENTS.md` appended to its system
-prompt, and its own skill, context and extension discovery intact — the
-instance's copied skills are found because they sit under cwd; machine-level
-and repo-level skills resolve exactly as without OATS. *(0.24 kernels started
-Pi with ambient skill and context discovery disabled and the one instance path
-explicit; that exclusion is gone.)* Claude runs provider-native: it reads the
-instance's `.claude/skills` and `CLAUDE.md` symlinks, and the operator's own
-user and project configuration — skills, plugins, settings — stays in effect.
-Neither harness gets a redirected config home.
-`composition.materialized.harnessPosture` in `instance.json` records what each
-instance actually exposes. `oats-getting-started` is the sole pre-workspace
-ambient bootstrap.
-
-Duplicate skill directory names within the OATS-composed set are errors
-(`E_SKILL_DUPLICATE`, naming both capabilities) unless the classic config's
-`skill-overrides` selects a source; between a composed skill and an ambient
-repo/machine skill the harness's own precedence decides (decision 16).
-
-## Package locations
-
-**Workspace model (0.25, current):** nothing is installed. A capability lives
-where its owner keeps it and is copied whole into each instance at spawn:
-
-```text
-<member repo>/capabilities/<name>/oats.json           # member-tier capability, latest state (membership is the trust)
-<package repo>/oats-package/oats-package.json         # package-tier: versioned via oats-workspace.yaml packages:
-<deployment>/oats-lock.json                           # lockfileVersion 3: package commit and integrity
-<instance>/.oats/modules/<capability>/                # the copy this instance runs
-```
-
-## Quick map
-
-| Thing | Canonical location |
-|---|---|
-| Shared declaration | `oats-workspace.yaml` in the host repo; `oats-membership.yaml` in every member |
-| Per-machine config | `<deployment>/oats-local.yaml` (uncommitted) |
-| Acquisition lock | `<deployment>/oats-lock.json` (v3) |
-| Soul source | `<member repo>/souls/<name>/` |
-| Soul operating doc | `souls/<name>/AGENTS.md` |
-| Soul Claude view | `souls/<name>/CLAUDE.md -> AGENTS.md` |
-| Soul-private skills | `souls/<name>/skills/` |
-| Instance operating doc | `instance/AGENTS.md` (generated) |
-| Instance skill set | `instance/.agents/skills/` |
-| Instance modules | `instance/.oats/modules/<capability>/` |
-| Instance metadata | `instance/instance.json` (`modules{}`, `providers{}`, `workspace{}`) |
-
-Symlinks prevent compatibility paths from drifting. Generated regular files
-separate canonical portable identity from scope-dependent runtime policy.

package/docs/design/2026-09-07-architecture-reassessment.md

@@ -1,131 +0,0 @@
-# Architecture reassessment: usable agents with replaceable services
-
-Assessment of main `76c0ea4`, September 7, 2026. Requested by Juan after
-operating the Desktop; incorporates Pepe's terminal, shortcut, split and soul
-management feedback. This records the direction and implementation gaps, not a
-claim that every item below has shipped.
-
-The requirements authority for this assessment is Juan's September 3
-“Architecture simplification and generlization” in his OATS project KB:
-souls carry instructions and capabilities; a harvester converts ephemeral
-state into knowledge accessible through the selected knowledge capability;
-packages distribute souls and capabilities; OATS constructs and operates
-instances across runtimes and platforms. The private Bookshelf README points
-to September 1's adoption/sovereignty strategy. Its relevant constraint is that
-changing a runtime or service provider must not erase the team's relationships
-or working knowledge. The older August proposals about genomes, clothes and
-turn-record experiments are background, not reasons to expand this release.
-
-## Decision
-
-Keep the existing package and capability-layer mechanism. Correct the places
-where the CLI and GUI bypass it. The architecture is broadly right; the
-operator experience and some service boundaries are incomplete. More
-abstractions will not fix a terminal that cannot accept a screenshot.
-
-| Component | Owns | Must not assume |
-|---|---|---|
-| OATS kernel | Soul/instance construction, configuration, lifecycle, host placement, scheduling, capability resolution | A particular knowledge provider, messaging service, or GUI |
-| Session backend | Durable terminal, attach/detach, resize, literal input, observation | OATS soul/package semantics or task success |
-| Knowledge capability | Knowledge access and representation; its harvester and promotion policy | Every installation uses OKF or stores memory in the same files |
-| Messaging capability / aweb | Durable messages, identities, event subscriptions and delivery policy | A particular model harness or an open Desktop window |
-| Task capability | Durable work and task semantics | A particular terminal backend |
-| Desktop | Inspect effective configuration; explicit operator actions; terminal input, files, layout | Provider names, SSH commands, or a second lifecycle implementation |
-
-Scheduling belongs to OATS, and a scheduled harvest is one use of scheduling.
-Harvesting behavior belongs to the knowledge capability. Starting an agent,
-writing a prompt, and producing reviewed knowledge are different outcomes.
-The UI must retain those distinctions.
-
-## What already fits, and what does not
-
-`lib/core.mjs` already selects exclusive knowledge/messaging/tasks layers by
-manifest, resolves scoped capability settings, dispatches lifecycle hooks, and
-materializes runtime instructions. Jira and Linear demonstrate that a layer
-can have alternative implementations. OKF's harvester is already an exported
-capability agent. There is no reason to replace this machinery.
-
-The remaining coupling is concrete:
-
-- The retire receipt reads `hookResults.meta["oats.okf"].harvested`, although
-  current OKF does not supply a retire hook. Remove the dead provider-specific
-  inference; do not invent successful harvesting at retirement.
-- Remote capability routing recognizes `okf harvest` specifically in
-  `bin/oats.mjs` and `lib/servers.mjs`.
-- Desktop harvest actions and scheduled-harvest definitions construct
-  `oats okf harvest`; the editor recognizes that exact argv.
-- The “brain” view presents `STATE.md`, `log.md` and `notes/` as universal
-  knowledge structure. These are conventions of the current setup.
-
-The next service contract should expose the **effective knowledge provider and
-its supported operations for a specific soul/home**. Discovering a capability
-command namespace alone is insufficient: it does not promise a `harvest` verb
-or a shared file layout. A provider may offer harvest, different operations,
-or read-only access. Desktop must show only declared operations and route
-execution through the selected CLI capability. The same resolution must apply
-locally, remotely, and when a scheduled operation runs.
-
-Keep that change small: explicit operation metadata, scoped discovery, and one
-invocation route using the existing capability engine. Do not add a plugin
-framework, generic workflow language, or a second knowledge store. Demonstrate
-replaceability with a tiny alternative-provider fixture that uses a different
-command and storage layout; a full second product is unnecessary.
-
-## tmux and Herdr
-
-The current kernel defaults to a shared tmux session (`pi-agents`) with a
-window per instance. An agent does not require another tmux server. The GUI
-creates a temporary session linking only the selected window. That isolates
-viewers: switching a terminal elsewhere cannot redirect a GUI tab to another
-agent, and an agent exiting cannot silently expose a sibling under its label.
-The `oatsdesk-*` name in Juan's screenshot is this viewer. Its status bar can
-be hidden with a viewer-local setting. Do not alter global tmux settings or
-merge/move live agent sessions to solve a display defect.
-
-Herdr 0.8.2 is a separate terminal runtime, not a tmux-compatible superset.
-Its documented direct terminal attachment, socket API, events and SSH support
-are useful. Its semantic agent state comes from detection and/or integrations;
-it is richer evidence, not proof that a particular message was consumed.
-The [socket API](https://herdr.dev/docs/socket-api/) explicitly distinguishes
-agent-state waits from arbitrary command completion. The
-[remote documentation](https://herdr.dev/docs/persistence-remote/) also
-separates a local thin client from running a client entirely on the server;
-only the former can directly bridge the local desktop clipboard.
-
-Keep one OATS session contract and both existing adapters for now. Do not add
-another supervisor above them. Qualify Herdr's actual literal multi-line
-input, exact occupant checks, detach, resize, process exit and remote behavior
-before selecting it as the default for new instances. Inspect `pane run`
-implementation before replacing it merely because its name sounds like shell
-execution. Removing tmux is a later deployment choice, not a prerequisite for
-consistent UI or remote agents. Existing tmux agents stay where they are.
-
-## Desktop correction sequence
-
-1. **Terminal essentials.** Hide viewer chrome, accept dropped files and pasted
-   images without pressing Enter, upload remote files to the execution host,
-   preserve the destination tab across async work, and show transfer failures.
-   Keep a single GUI and bounded viewers. This is the immediate implementation.
-2. **Keyboard and splits.** Restore Ctrl+Tab navigation inside Mac terminals;
-   let an already-open terminal fill an empty split without a second attach;
-   expose draggable and keyboard-operable separators. Follow up specific
-   keyboard reports with real input tests, especially terminal editing keys
-   and non-US layouts. App shortcuts must not silently steal terminal edits.
-3. **Souls & capabilities.** Replace the launch-centric roster with a management
-   surface showing souls, installed capabilities, effective layer providers,
-   source/version, scoped activation and runtime defaults. Inspect and launch
-   are distinct actions. Edits use existing CLI operations with the exact scope
-   visible; installing a capability must not silently activate it. This is not
-   a marketplace or Team Builder project.
-4. **Provider-neutral operations.** Introduce the scoped operation contract
-   above, then use it for manual harvest, schedules and knowledge inspection.
-   No second hardcoded default is accepted as a generalization.
-5. **Operating rollout.** Enable schedules per team with the owner's learning
-   policy. Capture-lock recovery is a separate reliability issue affecting
-   unattended harvesting; it does not block arbitrary scheduled wakes.
-
-Acceptance must include real Electron file objects, actual terminal bytes,
-remote transfer hashes, split focus/resize without extra PTYs, and a provider
-replacement fixture. Unit tests of mocked argv alone do not establish these
-boundaries. Reuse the existing agents and GUI sparingly; no model is needed to
-exercise attachment transport or terminal layout.

package/docs/design/2026-09-07-desktop-souls-capabilities.md

@@ -1,50 +0,0 @@
-# Souls and capabilities in Desktop
-
-Selecting a soul opens its details. Launch and Schedule are explicit actions;
-Quick Open and Enter inspect instead of launching. The existing local Files
-browser remains available. It is separate from provider knowledge inspection.
-
-The inspector reads the kernel's `oats inspect --json` answer on selection,
-Refresh, or after an explicit mutation. The roster's eight-second poll never
-rescans capabilities or replaces an editor. Workspace changes invalidate old
-responses. Same-named souls are addressed by name plus agents root; instances
-are addressed by their exact home.
-
-The Capabilities button inspects workspace defaults, with a member-scope
-selector where a workspace contains several roots. Installed version, source
-and health are separate from effective activation, provenance and settings.
-Enable, explicit disable and return to inheritance call `oats use`; layer-wide
-disable is distinct from excluding a single capability, and is available only
-when inspecting a workspace or member scope, never an individual soul. These changes apply to
-future instances. Existing homes retain their captured bindings and settings.
-
-Authored souls expose only the fields the kernel reports as editable. Desktop
-edits runtime, model, backend, YOLO, description and instructions through
-`oats soul set`. Packaged souls remain read-only and explain where their source
-must be changed. Instructions use a private temporary file; the CLI owns remote
-transfer and mutation. Desktop does not modify YAML or resolve capabilities.
-
-An instance's action menu opens Knowledge & capabilities. The kernel supplies
-its snapshot, differences from current configuration, and declared provider
-operations. View operations return labeled documents; Desktop renders their
-text and treats remote paths as provenance, never as local files to open. Actions
-without required arguments can run here. Operations requiring arguments explain
-that they need the CLI. No provider is assumed to support harvesting.
-
-Schedules store an operation address and exact home with the kernel's generic
-`operation` job kind. The form discovers declared, available actions on demand.
-The server verifies that declaration again at save time, and the kernel resolves
-and validates the provider at execution time. Existing command schedules remain
-visible and runnable, but the GUI does not reverse-parse their argv to edit them.
-
-Every capability request requires an exact advertised workspace. Remote requests
-require its saved server registration and the CLI's operations API feature; all
-routing stays in OATS. The consumer never performs SSH or silently substitutes a
-local workspace. The proxy allows the CLI's bounded operation to return its
-receipt before timing out.
-
-Validation: scope/identity and remote-route refusal; private instructions and
-failure cleanup; declared schedule actions; stale inspection/save responses;
-provider text rendering; explicit launch and existing runtime flows. Native
-Electron rendering is checked with a temporary fixture frame in the existing
-GUI, without starting a model, agent, or another application instance.

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

@@ -1,228 +0,0 @@
-# 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).