@awebai/oats 0.29.4 → 0.30.1

package/docs/design/desktop-ux-plan.md

@@ -1,362 +0,0 @@
-# OATS Desktop — UX plan (phase 1)
-
-Author: ux-designer-desktop-ux · Branch: `ux-designer/desktop-app`
-Scope: design language + UX for `packages/desktop/` (Electron shell,
-xterm.js terminal, brain viewer, markdown viewer, diff viewer, panel port).
-This is a **decision document**: each section states the chosen option and why.
-It is written against the binding contract in
-`briefs/desktop-app-CONTRACT.md` (view modules `mount(el, ctx)` / `unmount()`;
-data from the oats-web HTTP API; tmux-attach terminals).
-
----
-
-## 1. Design research — what we take from VS Code and opencode
-
-### VS Code shell anatomy (what applies)
-
-VS Code's shell is: **activity bar → sidebar → editor group (tabs) → panel →
-status bar**, all keyboard-addressable through a **command palette**, all
-colored through **semantic theme tokens** (`editor.background`,
-`sideBar.foreground`, …) rather than raw hex in components.
-
-Principles we adopt:
-
-1. **One persistent shell, swappable content.** Chrome (sidebar, tabs, status
-   bar) never remounts; only the active view does. This maps 1:1 onto the
-   `mount(el, ctx)` contract — the shell owns chrome, views own their `el`.
-2. **Semantic color tokens.** Components reference roles (`--surface`,
-   `--accent`, `--term-bg`), never palette values. Themes are token maps.
-   The existing panel (`capabilities/oats-web/ui/panel.html`) already does
-   this correctly — we extend its token set, we don't replace it (§4).
-3. **Command palette as the universal escape hatch.** Every action reachable
-   by mouse is reachable by `⌘K` (see §5). This is the cheapest way to be
-   keyboard-first without designing a shortcut for everything.
-4. **Tabs are documents; the sidebar is the world.** Tabs hold *open work*
-   (a terminal, a diff, a markdown file); the sidebar holds *everything that
-   exists* (the roster). Closing a tab never destroys the underlying thing —
-   which matches the contract exactly (detach pty, never kill tmux).
-5. **Status bar for ambient truth**: connection to the oats-web server,
-   active workspace, running-instance count, theme toggle.
-
-What we deliberately **do not** clone:
-
-- **No activity bar.** VS Code's activity bar exists because it has many
-  coequal top-level domains (explorer, SCM, debug, extensions). OATS desktop
-  has *one* primary domain — agents — so a vertical icon rail would be
-  ceremony. The sidebar gets a small segmented header instead
-  (Agents | Hierarchy) — two modes, not five domains.
-- **No multi-root editor-group splitting (phase 2).** The panel's proven
-  ≤3-pane terminal split is enough initially; generalized grid splitting is
-  a later enhancement, not a launch requirement.
-
-### opencode (what applies)
-
-opencode is a TUI-first agent client: session list on the left, one live
-session dominating the screen, minimal chrome, everything driven by keys and
-a fuzzy switcher. Principles we adopt:
-
-1. **The session is the hero.** When you open an instance, its live terminal
-   fills the stage immediately — no dashboard detour, no click-through.
-2. **Fast session switching** (fuzzy, recency-ordered) matters more than
-   deep navigation trees. Our palette's default mode is "jump to instance".
-3. **State is legible at a glance**: running/idle/busy is shown as a colored
-   dot next to every session name, everywhere the name appears (roster,
-   tabs, hierarchy graph, palette). One vocabulary of status dots (§5).
-4. **Terminal fidelity over widgetry.** Don't wrap the agent session in
-   chat-bubble reconstructions; show the real terminal. The contract's
-   direct tmux-attach already commits us to this — the UX embraces it.
-
----
-
-## 2. Information architecture — agents at the heart
-
-**Decision: the primary object is the agent *instance*.** Files, diffs,
-terminals and brains are *facets of an instance*, not siblings of it. The IA
-is instance-centric, not file-centric — this is the single biggest departure
-from VS Code, and the reason the app exists.
-
-### Shell layout
-
-```
-┌──────────────────────────────────────────────────────────────┐
-│ titlebar: ● oats  [workspace ▾]        filter/⌘K      ◐ theme │
-├───────────────┬──────────────────────────────────────────────┤
-│ SIDEBAR       │ TAB STRIP  [dev-1 ⬤][dev-1: diff][README.md] │
-│ ┌───────────┐ ├──────────────────────────────────────────────┤
-│ │Agents|Tree│ │                                              │
-│ └───────────┘ │            ACTIVE VIEW                       │
-│ roster:       │   (terminal / brain / markdown / diff /      │
-│  ws → repo →  │    hierarchy / home)                         │
-│   instances   │                                              │
-│  (children    │                                              │
-│   indented)   │                                              │
-│ ── souls ──   │                                              │
-│  spawnable    │                                              │
-├───────────────┴──────────────────────────────────────────────┤
-│ status bar: ⬤ server · ws:oats · 4 running · branch · theme   │
-└──────────────────────────────────────────────────────────────┘
-```
-
-- **Sidebar (left, collapsible ⌘B)** — the roster, ported from the panel:
-  workspace → repo → instances, with spawn-children indented under parents
-  (the panel's `parentInstance` walk is kept verbatim). Below it, spawnable
-  souls with a Spawn action. A segmented control at the top switches the
-  sidebar between **Agents** (list) and **Hierarchy** (mini-tree; the full
-  graph opens as a view, §3).
-- **Tab strip** — open facets. Tab title = `instance` (terminal),
-  `instance: diff`, `instance: brain`, or file name (markdown). Terminal
-  tabs carry the status dot. Middle-click / `⌘W` closes (detach only).
-- **Status bar** — server reachability, workspace, running count. Clicking
-  the server segment reveals host/port; clicking the count filters to
-  running.
-
-### The home surface
-
-**Decision: home = the hierarchy view with an overview header**, not an
-empty state and not a dashboard of widgets. On launch (no tabs open) the
-stage shows the agent hierarchy graph (§3) topped by a one-line summary
-("*oats workspace — 4 running, 2 idle, 1 retired today*") and a spawn button.
-Rationale: it makes the app's thesis — *you are orchestrating a team* —
-visible in the first second, and every node is one click from its terminal.
-
-### Per-instance facet model
-
-Selecting an instance (sidebar click, palette, or graph node) opens its
-**terminal tab** — the hero facet. From the terminal tab's header (and the
-context menu / palette) the sibling facets are one action away:
-
-| Facet    | Source                        | Opens as              |
-|----------|-------------------------------|-----------------------|
-| Terminal | tmux attach via pty IPC       | tab (default)         |
-| Brain    | `GET /api/brain/<agent>`      | tab `instance: brain` |
-| Diff     | `GET /api/diff/<instance>`    | tab `instance: diff`  |
-| Files    | `GET /api/file?path=…`        | tab per file (markdown viewer) |
-
-Cross-facet links use the contract's `ctx` verbs: brain view lists skills /
-knowledge / STATE.md → `ctx.openFile(path)`; any view can
-`ctx.openTerminal(instance)`. The hierarchy view is itself a view module and
-uses the same two verbs — no new contract surface needed.
-
-**Decision: tabs are per-facet, not per-instance-with-inner-tabs.** Inner
-tab bars (an instance tab containing terminal/brain/diff sub-tabs) were
-considered and rejected: they double the chrome, break `⌘W`/`⌘1..9`
-uniformity, and fight the `mount(el, ctx)` contract, which is flat. Facet
-association is expressed by tab naming + grouping tabs of the same instance
-adjacently.
-
----
-
-## 3. Agent hierarchy visualization
-
-**Decision: an interactive tree-of-trees (layered DAG), not a force-directed
-graph.** Spawn parentage (`parentInstance` in the roster) is a forest —
-force layouts add jitter and non-determinism for zero benefit on tree data.
-Layout: **top-down tidy tree per workspace** (d3-hierarchy-style tidy layout;
-implementable in ~150 lines without a dependency, or with `d3-hierarchy`
-since desktop deps are allowed), workspaces side by side, SVG-rendered,
-pan/zoom.
-
-### Two relationship kinds, two visual languages
-
-1. **Spawn parentage** (who spawned whom): solid edges, the tree structure
-   itself. Source: roster `parentInstance`.
-2. **Coordination** (who works with whom): dashed accent edges *overlaid*
-   on the tree, shown on hover/selection (always-on is noisy). Source:
-   shared workspace/repo membership + aweb team metadata as exposed by
-   `/api/panel`; degrade gracefully if absent — the view must not depend on
-   a new endpoint (if richer comms data is wanted later, that is a phase-2
-   request to the coordinator, not an assumption).
-
-### Node design
-
-A compact card, not a bare circle — names and states must be readable
-without hover:
-
-```
-┌──────────────────────────┐
-│ ⬤ webpanel-dev-brain     │   ⬤ status dot (see states)
-│ webpanel-dev · repo:oats  │   agent · repo, muted
-└──────────────────────────┘
-```
-
-- **States** (same vocabulary app-wide): **running** = green dot +
-  full-opacity card; **idle** = hollow/gray dot, card at ~65% opacity
-  (matching the panel's `.inst.idle`); **retired** = dashed border,
-  faint text, only shown when the "show retired" toggle is on (retired
-  instances known from roster history if available; otherwise omitted).
-- **Busy pulse** (phase-2 nice-to-have): subtle dot pulse when the session
-  produced output in the last N seconds — cheap liveness signal.
-
-### Interactions
-
-- **Click node → focus + detail popover** (task line, branch, dirty chip,
-  buttons: *Open terminal · Brain · Diff*). **Double-click / Enter → open
-  terminal tab** directly.
-- **Hover → highlight lineage** (ancestors + descendants) and show
-  coordination edges for that node.
-- Pan (drag), zoom (pinch/`⌘±`), `f` to fit. Keyboard: arrows walk the tree,
-  Enter opens.
-- Search-as-you-type filters/highlights nodes (reuses the sidebar filter
-  semantics).
-
-The hierarchy is both a **full view** (home surface / `⌘⇧H`) and a
-**sidebar mini-mode** (same data, vertical indented tree — effectively the
-roster's existing child-indentation, promoted).
-
----
-
-## 4. Theming
-
-**Decision: extend the panel's existing token system — it is already
-semantic, already dual-theme, already AA-audited.** The panel's `:root` /
-`[data-theme]` token blocks become `packages/desktop/renderer/theme.css`,
-the single source of truth. Views consume tokens only; a view containing a
-hex literal fails review.
-
-### Token architecture
-
-Three tiers, one file:
-
-1. **Core surface/text/interactive tokens** (exist today): `--bg`,
-   `--surface`, `--surface-2`, `--border`, `--fg`, `--muted`, `--faint`,
-   `--accent`, `--accent-fg`, `--ok`, `--warn`, `--danger`, `--chip-*`,
-   `--sel`, `--shadow`.
-2. **Terminal tokens**: `--term-bg`, `--term-fg`, `--term-sel` (exist) plus
-   a **16-slot ANSI set** `--ansi-black … --ansi-bright-white` (new —
-   xterm.js takes a theme object; we generate it from these tokens so the
-   embedded terminal matches the app theme, including the solarized remap
-   the panel already ships for light mode).
-3. **New component tokens** (thin aliases over tier 1, so themes rarely
-   need to override them): `--tab-active-bg`, `--tab-inactive-fg`,
-   `--statusbar-bg`, `--graph-edge`, `--graph-edge-coord`,
-   `--diff-add-bg`, `--diff-del-bg`, `--md-code-bg`.
-
-### Themes
-
-- **Dark** (default when OS is dark): the panel's GitHub-dark-adjacent
-  palette, unchanged.
-- **Light**: the panel's **solarized-light** palette, unchanged —
-  compatibility with the web panel is a requirement and the palette already
-  passes AA (`--fg` 9.9:1, `--muted` 4.9:1 on surface).
-- Theme = OS-follow by default, manual override persisted
-  (`localStorage`, same keys as the panel: `oatsweb.theme`) so panel and
-  desktop feel like one product. Room for future themes = adding one
-  `[data-theme="x"]` block; no component changes.
-
-### Accessibility commitments (both themes, verified in phase 2)
-
-- Body & secondary text ≥ 4.5:1 on their actual surfaces; UI glyphs/borders
-  ≥ 3:1; status conveyed by **dot shape + label**, never color alone
-  (idle = hollow dot, retired = dashed border — already specified in §3).
-- Visible `:focus-visible` ring (`--accent`, 2px) on every interactive
-  element; full keyboard reachability (tabs, sidebar, graph, palette).
-- Diff colors get text labels (`+`/`−` gutters) in addition to
-  `--diff-add/del-bg`; ANSI light remap keeps terminal output ≥ 4.5:1 as
-  the panel already does.
-- `prefers-reduced-motion`: disable graph pan-inertia, dot pulse, spinner
-  fades.
-
----
-
-## 5. Component inventory + interaction details
-
-**Type & space.** UI font: system stack (as panel). Mono:
-`"SF Mono", ui-monospace, Menlo` (as panel). Type scale (px):
-11 (chips/status) · 12 (secondary) · 13 (body/controls) · 14 (view titles) —
-matching the panel's proven density. Spacing scale: **4-px base**
-(4/8/12/16/24/32); radii: 6 (small controls) / 8 (cards, inputs) / 999
-(chips). Shadows: `--shadow` only.
-
-**Components** (shell-owned unless noted):
-
-- **Tabs**: 32px strip; active tab `--tab-active-bg` + 2px top accent
-  (mirrors the panel's focused-pane inset accent); dirty/status dot on
-  terminal tabs; overflow scrolls; drag-reorder phase-2. `⌘1..9` jump,
-  `⌘W` close, `⌃Tab` MRU cycle.
-- **Sidebar**: as panel roster (filter input, collapsible groups, chips for
-  branch/dirty/runtime) + segmented Agents/Hierarchy header. `⌘B` toggle.
-- **Command palette** (`⌘K`): single input, mode prefixes —
-  default = jump to instance (fuzzy, MRU-boosted); `>` commands
-  (spawn, toggle theme, open diff/brain of current instance, fit graph);
-  `#` open file within current instance's home. Esc closes; results show
-  status dots and repo chips.
-- **Toasts**: bottom-right, `--surface` card + colored left border
-  (`--ok/--warn/--danger`), auto-dismiss 5s (errors sticky with a Close
-  button), max 3 stacked, `aria-live="polite"`. Used for: spawn result,
-  server lost/regained, pty exit.
-- **Loading states**: reuse panel's `.spinner` + `.loading-block`; skeleton
-  rows (pulse animation) for roster and brain tree; terminals show
-  "attaching to `<session>` …" with spinner until first pty bytes.
-- **Empty states**: reuse panel's `.empty` pattern (big glyph, one sentence,
-  one action). E.g. diff view with clean tree: "No changes on
-  `<branch>` — the work tree is clean."
-- **Dialogs**: only for destructive/parameterized actions (spawn with task
-  text). Everything else is inline or palette.
-- **Markdown viewer** (view module): panel typography, `--md-code-bg` code
-  blocks with syntax highlight, heading anchor links, relative links to
-  files resolved through `ctx.openFile`.
-- **Diff viewer** (view module): file list (status/+/− counts) left or top,
-  unified diff with `--diff-*` tokens, per-file collapse, staged toggle.
-- **Brain viewer** (view module): two columns — soul (AGENTS.md, skills,
-  knowledge tree) and instances (state/task/notes) — every leaf is an
-  `openFile` link; skills show their descriptions inline.
-
-**Keyboard-first rules**: `⌘K` palette · `⌘B` sidebar · `⌘T` spawn ·
-`⌘⇧H` hierarchy · `⌘W`/`⌘1..9`/`⌃Tab` tabs · `⌘F` filter. **Ctrl-B is never
-bound** — it is the tmux prefix and always flows to the focused terminal
-(the panel already enforces this rule; we keep it as law).
-
----
-
-## 6. Phase-2 implementation plan (incremental, contract-compatible)
-
-Each step lands independently on the integrated app; none changes the view
-contract or the API contract. Order chosen so every step is visible value.
-
-1. **Token foundation** — extract/extend `renderer/theme.css` (tiers 1–3,
-   ANSI variables), wire `data-theme` + OS-follow + persistence; generate
-   the xterm.js theme object from tokens; contrast-check both themes
-   (automated check script if feasible).
-2. **Shell chrome polish** — tab strip (status dots, accents, keyboard
-   map), status bar, sidebar restyle to spec (segmented header, chips,
-   focus rings), toasts, loading/empty components as shared renderer
-   helpers views can import.
-3. **Command palette** — jump/command/file modes as above; registered
-   commands provided by the shell; instance jump from roster data.
-4. **Hierarchy view** — new view module `views/hierarchy.js` using only
-   roster data + `ctx.openTerminal`/`ctx.openFile`; tidy-tree layout,
-   node cards, states, lineage highlight, popover, keyboard nav; wire as
-   home surface and `⌘⇧H`.
-5. **View polish pass** — apply tokens/typography/empty-loading patterns to
-   the four developer-built views (terminal header, brain, markdown, diff),
-   coordinating any needed hooks through dev-coordinator-1.
-6. **Accessibility + reduced-motion audit** — keyboard walk of every
-   surface, focus-visible sweep, contrast verification, `prefers-reduced-
-   motion` guards; fix list executed before calling phase 2 done.
-
-### Addendum — human directives (received via coordinator before phase-2
-go-ahead; to be re-confirmed in the go-ahead mail)
-
-Binding design directives that supersede anything conflicting above:
-
-1. **Diff viewer surface removed** — no nav entry, no diff tabs. `/api/diff`
-   and `diff.mjs` stay in the tree, dormant; removing dead UI wiring is in my
-   scope. (Step 5 no longer polishes a diff view; `--diff-*` tokens remain
-   defined for a possible return.)
-2. **Markdown reader is the flagship viewer** — `openFile → markdown` gets
-   the depth budget: typography, highlighting, anchors, relative-link
-   resolution via `ctx.openFile`, strong loading/empty states.
-3. **Jira surface hidden entirely** — no nav entry or inline cards; code
-   stays unwired. Verify no remnants during the polish pass.
-4. **Three first-class surfaces**: (a) hierarchy view = home + primary
-   navigation (extra investment beyond step 4); (b) a proper **souls
-   browser** stage view (descriptions + spawn affordances, palette-reachable)
-   — promoted from the sidebar-list sketch in §2; (c) a nice way into agent
-   brains.
-5. Everything else (themes, tokens, palette, a11y) stands as written.
-
-Dependencies/risks flagged to the coordinator up front: (a) step 5 touches
-other developers' view code — I will work on the *integrated* branch only,
-after their merges; (b) coordination-edge data for §3 uses whatever
-`/api/panel` already exposes — if we want explicit aweb-team edges, that is
-a small additive API request, not a blocker.

package/docs/design/launch-configurations.md

@@ -1,168 +0,0 @@
-# Launch configurations and launch recipes
-
-A **launch configuration** is a named way to start a harness, declared by
-the host under `launch-configs:` in the deployment's `oats-local.yaml` (see
-docs/configuration.md; 0.26.0, lead decision 2 — earlier kernels read it
-from a scope's `oats-config.yaml`): runtime, an executable, literal
-arguments, environment (literals or `{fromEnv}` references), model, yolo.
-It is independent of any soul, and a spawn, start or restart selects one by
-name (`--launch-config`, or the Desktop's per-launch choice). A launch
-configuration is a spawn-time host choice, never a soul field: `launch-config:`
-is not a field of a workspace-model soul.yaml (docs/soul.schema.json; discovery
-refuses it), so a v2 soul cannot name one, not even as a default. (A classic
-0.25 soul.yaml could name a preferred entry; 0.26.0 reads no such field.)
-
-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": "/deployment",
-  "executable": "/deployment/tools/claude-wrapper.sh",
-  "executableDeclared": "./tools/claude-wrapper.sh", "executableResolvedFrom": "relative to /deployment",
-  "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 uses no configuration (the runtime's
-  defaults; a soul names 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 uses the runtime's native default (a
-  workspace-model soul declares no model). A model never crosses runtimes.
-- Executable: the configuration's (bare name on PATH; a path resolved against
-  the deployment directory 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, where a selection answers `E_LAUNCH_LEGACY`: re-spawn it);
-`--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/design/okf-mirror-provenance.md

@@ -1,105 +0,0 @@
-# Internal: finalizing the OKF mirror's source provenance
-
-The standalone `oats.okf` distribution is authoritative. The framework's
-`capabilities/oats-okf/` and `scripts/okf-source-inventory.json` are generated
-mirrors, not authoring surfaces. This procedure does not publish the source,
-accept a PR, update the catalog, commit, fetch, or change branches.
-
-## Development versus publication
-
-- `node scripts/check-okf-mirror.mjs --generate --source <standalone-repository>`
-  captures current exported working bytes, including dirty/untracked files.
-  It always records `release.status: pending`, null final refs and
-  `published: false`, even when HEAD happens to have a published tag.
-- `node scripts/check-okf-mirror.mjs --verify` uses only the checked-in inventory
-  and mirror. No Git, clone, credentials or network is needed for either a
-  pending or finalized inventory. It checks exact file sets (including empty
-  directories), file bytes, portable Git executable modes, literal symlink
-  targets, wrapper hashes, and consistent release metadata.
-- `--verify-source --source <standalone-repository>` verifies pending snapshots
-  against their exact recorded working state, including branch/dirty metadata.
-  For published inventories it rechecks the immutable commit, payload, origin
-  tag object and peeled commit, ignoring the recorded local branch name. The
-  checkout must still be clean at the recorded accepted commit; renamed
-  branches and detached HEAD are supported. This published-source check needs
-  origin access. It does not depend on cached remote-tracking refs.
-
-Offline verification is an integrity check of a reviewed checked-in inventory,
-not independent proof that a remote still advertises a tag. The explicit source
-check supplies that evidence. No boolean flag is a publication attestation.
-
-## Post-publication command
-
-Only after source review/merge and actual publication of `v2.0.0`:
-
-1. Obtain the **accepted full merged commit ID** from the source review/release
-   record. Do not substitute a mutable branch name, abbreviated hash, or whatever
-   HEAD happens to resolve to. The legacy inventory field `finalMergedCommit`
-   records this caller-supplied acceptance; Git cannot prove human PR approval.
-2. Have a clean standalone checkout at that commit, with the published tag
-   available locally and `origin` pointing to `awebai/oats-okf`. Fetch/check out
-   deliberately through the parent release procedure; the checker never does it.
-3. From the framework checkout, run:
-
-   ```bash
-   node scripts/check-okf-mirror.mjs --finalize \
-     --source .agents/knowledge-rework/repos/okf \
-     --final-tag v2.0.0 \
-     --final-commit "${OKF_V2_ACCEPTED_COMMIT:?set the reviewed full merged source commit ID}" &&
-   node scripts/check-okf-mirror.mjs --verify-source \
-     --source .agents/knowledge-rework/repos/okf &&
-   node --test test/okf-mirror-parity.test.mjs
-   ```
-
-   The relative source path above is the existing ignored work-view convention;
-   substitute an explicitly resolved standalone repository path in other work
-   views. The command must not be run while source acceptance is still changing.
-
-4. Review the resulting payload/inventory diff, run the remaining release gates,
-   then advance the catalog through the parent integration process. Finalization
-   itself never touches the catalog.
-
-`--finalize` requires both `--final-tag` and a full SHA-1/SHA-256 `--final-commit`.
-It replaces only the mirrored capability and inventory, just like `--generate`,
-but stamps `release.status: published` only after all checks succeed:
-
-- The version tag is exactly `v<distribution version>`; HEAD is the explicitly
-  accepted commit and Git reports a clean source tree. Masked index entries
-  (`assume-unchanged`/`skip-worktree`) are not accepted.
-- Actual exported files and wrappers match raw objects at that commit, not just
-  Git status or filtered checkout content. Ignored exported extras, untracked
-  empty directories, CRLF/filter changes, hidden byte changes, mode drift with
-  `core.filemode=false`, and literal symlink-target differences fail closed.
-  Git replacement objects are disabled. Published inventories also record and
-  hash wrapper file modes; materialization preserves those modes and bytes.
-- Exactly one effective origin fetch URL identifies the official source. The
-  usual official GitHub HTTPS/SSH spellings are equivalent. URL rewrites to an
-  unrelated repository are rejected. The remote query uses canonical public
-  HTTPS with source-local Git configuration disabled, so local upload-pack/SSH
-  overrides cannot fabricate its response. Prompts/helpers are disabled and
-  Git commands have a bounded timeout.
-- The local tag resolves to the accepted commit. A fresh `ls-remote` query must
-  advertise the same tag object and the same peeled commit (or direct commit
-  for a lightweight tag). Both annotated and lightweight tags are supported.
-  Missing/unreachable origin, unpublished tags or mismatched refs fail closed.
-- The source is checked again after staging the copy, before replacing the
-  mirror or inventory. Failed acceptance checks leave both untouched. Ordinary
-  filesystem failures during replacement are not a multi-file transaction.
-
-The published record retains `source.head`, clean-state metadata, the branch
-observed at generation (informational during immutable verification), the
-accepted final tag/commit, `remote: origin`, and the exact `tagObject`. Thus
-changing an annotated tag object without changing its commit still invalidates
-`--verify-source`. Remote checks attest what was advertised when queried; they
-cannot prevent an upstream tag from being moved later. Do not move released
-tags, and re-run source verification at the release gate.
-
-## Isolated regression coverage
-
-`test/okf-mirror-parity.test.mjs` uses temporary source repositories and local bare
-origins only, including tag creation/deletion/movement solely inside fixtures.
-The JavaScript `finalizeOkfMirror`/`verifyOkfSource` APIs accept an explicit
-`repository` expectation for these fixtures and record their real source
-identity; the CLI cannot override the official repository. No tests publish to
-GitHub. Checked-in mirror tests accept consistent pending **or** published
-provenance, so finalizing the source does not require weakening those tests.