omp-fabric 0.85.0

package/docs/entropy.md

@@ -0,0 +1,396 @@
+# Tool entropy
+
+Tool entropy is the corrective freedom a tool surface leaves open per unit of
+work: the number of distinct ways a call can be non-canonical, weighted by
+how often models exercise them. The [catalog repair table](repairs.md)
+is the running profile of that freedom: every promoted row is one dimension
+the surface exposed and a model hit. The entropy meter turns the repairs KPI
+(*repeat invocation fingerprints → 0*) into a measured quantity, and the
+compiler loop drives it down and keeps it there.
+
+Everything is deterministic by construction. The meter is a pure function over
+typed artifacts Fabric already persists: trace V1 operations, live JSON
+schemas, and the repair table. No model judges anything, no prose is parsed,
+and the same inputs plus the same `ENTROPY_METRIC_VERSION` always produce the
+same report, which is what makes the score bisectable and CI-gateable.
+
+## Inputs
+
+- **Traces**: `FabricExecutionTraceV1` operations (`ref`, projected `args`,
+  `outcome`, `failureStage`, `sequence`) extracted from session JSONL tool
+  result details. Trace V1 is deliberately prose-free, which is exactly what
+  makes deterministic measurement possible.
+- **Surface**: an optional snapshot of `{ ref, inputSchema }` actions. When
+  present the meter adds static freedom; without it the report covers
+  behavioral terms only.
+- **Repairs**: the normalized catalog repair table (`keyAlias` /
+  `actionAlias` rows). Each row is a standing lexicon tax on its target ref.
+- **Audits**: persisted verbatim call arguments (`details.audits`). They are
+  the value corpus for enum-tighten: trace V1 projects values away per ref,
+  while audits carry every argument the call used. They stay local to the
+  session record, and the machine-wide observation pool accumulates their
+  counts across windows with exact per-session deltas, so sparse parameters
+  still reach the derivation thresholds.
+
+## The metric
+
+`measureEntropy({ traces, surface?, repairs?, catalogDigest? })` returns a
+report with per-ref and global terms, all rounded to 1e-6:
+
+| Term | Formula | Weight |
+| --- | --- | --- |
+| Shape entropy | Shannon entropy (bits) over canonical argument-shape signatures per ref, calls-weighted | 1 |
+| Failure-stage entropy | Entropy over `failureStage` among failed ops per ref, failed-weighted | 1 |
+| Retry churn | Mean normalized Levenshtein distance between a failed op's signature and the next same-ref signature | 4 |
+| Navigation | `fabric.discovery.*` operations per action operation | 4 |
+| Flow entropy | Occurrence-weighted entropy over action-ref sequences per task key | 1 |
+| Lexicon tax | Repair rows targeting the ref | 2 |
+| Static freedom | Per-schema freedom score (below) for called refs | 0.25 |
+
+The global `score` is `(Σ per-ref scores + navigation + flow) / max(1,
+succeeded action operations)`. Lower is better; the compiler's contract is
+that it never increases. The report decomposes it into `staticScore` (the
+surface share: static freedom of the refs the corpus used) and
+`behavioralScore` (everything models exercised: wobble, churn, rejections,
+navigation, flow, lexicon tax).
+
+Additional totals: `invocationRejections` counts failures at `resolve`,
+`prepare`, or `validate`: the offline residue class behind repair
+fingerprints. `invocationRejectionsPer1k` is that rate per 1,000 action
+operations and is the entropy production signal: it should trend to zero as
+the surface converges, and it spikes when a new model or tool arrives.
+
+Reports also carry `byModel`: per-model behavioral attribution. Traces stamp
+the producing model from the session scan (`model_change` records and the
+assistant turn's provider/model), and each model's behavioral terms measure
+against the same surface. The surface share is global truth about the
+schema, while behavioral entropy is attributable to the model that
+exercised it: a slipping ratchet with every model's slope up means the
+surface regressed, while one model's slope up names the entropy producer.
+Unstamped traces (older corpora, synthetic fixtures) contribute to the
+global report only.
+
+### Fingerprints
+
+- **Shape signature**: sorted parameter names with a bounded value-type tag
+  (`(limit:num,path:str)`), nested objects to depth 3, at most 32 keys. Key
+  order and value contents never matter, only the shape the model chose.
+- **Static freedom**: per JSON Schema parameter: free string 1.0, enum
+  `min(1, log2(k)/6)`, literal/const 0, number 0.5, boolean 0.1, arrays
+  `0.5 + 0.5·items`, objects recursed; optional parameters add 0.25,
+  `additionalProperties !== false` adds 0.5, free-form objects score 1.0.
+  Computable with an empty corpus, which is what lets the compiler score
+  candidate surfaces before deployment.
+
+### What good means
+
+- **Behavioral entropy → 0.** The bits of freedom models exercised, per
+  successful call. Zero means no call in the corpus needed correcting. This
+  is the primary target and the general form of the repairs KPI (repeat
+  invocation fingerprints → 0).
+- **Surface share shrinks by compilation, never by behavior.** It is the
+  priced potential of the refs the corpus used. It falls only when
+  a compiled surface (enum tightening, splits, or quarantines) removes real
+  freedom; track it across surface releases, bounded by function.
+- **Slope ≤ 0.** The per-session least-squares slope is the ratchet line:
+  flat means the surface converged, negative means it is compiling down,
+  positive means something regressed (a new model, a new tool, or a schema
+  change).
+- `/fabric entropy` prints `ratchet holding` when the latest session logged
+  zero invocation rejections and the slope is at or below zero, and
+  `ratchet slipping` otherwise.
+
+## Proposals
+
+`proposeEntropyReductions({ report, traces, surface?, repairs? })` emits
+reviewable, evidence-carrying proposals with fixed thresholds:
+
+- `enum-tighten`: a closed-domain parameter with ≥ 8 observations, 2–8
+  distinct values, and a ≥ 50% top share tightens beneath the enum its
+  schema already declares, removing values the corpus never uses. The
+  closed-domain rule is the guard rail: the auto loop may only subtract
+  freedom the schema claimed is bounded, never invent a domain. Value
+  observations come from the verbatim audits when supplied
+  (`entropyValueObservationsFromSessionJsonl`); the projected trace args
+  are the fallback. Boolean-typed parameters never propose: they are
+  already closed, and a two-value enum prices above the declared boolean.
+  A declared or previously compiled enum is a floor: observed values
+  outside it are pre-birth evidence (recorded before the overlay existed,
+  or after a digest proof fell) and are dropped, never re-proposed, so a
+  converged surface stops contesting its own tightness every turn. Later
+  compiles may tighten beneath the floor but never widen past it; widening
+  resets only when the base schema drifts (the digest proof drops the
+  overlay) or through review. Validate-rejected attempts record as
+  failed-call audits carrying only values the live schema's own enums
+  declare, so nothing a validator refused enters the durable record: the
+  refused value is already the author's public vocabulary, and typos or
+  out-of-domain payloads drop at the boundary. The attempt stays pre-birth
+  while the overlay holds, and the reset re-derives with it included, so a
+  refused in-domain value un-locks at the first drift and survives in the
+  corpus.
+- `declare-enum`: observations over an open parameter do not establish a
+  finite domain. A schema author must first mark a declared property with
+  `"x-fabric-enum-candidate": true`; only then does the same ≥ 8 observation,
+  2–8 value, and ≥ 50% top-share evidence surface a review signal naming the
+  observed vocabulary. Ordinary free strings, numeric ranges, undeclared
+  keys, and refs absent from the surface produce no enum suggestion. Once
+  the author replaces the annotation with a declared enum, later compiles
+  can tighten beneath it automatically. The auto loop never applies an enum
+  declaration.
+
+- `overload-split`: a ref with ≥ 1.0 bits of shape entropy and ≥ 2 disjoint
+  key-set clusters with ≥ 2 calls each splits into separate actions.
+- `sequence-fuse`: a contiguous sequence of 3–6 successful high-level
+  action refs, all distinct, that recurs in at least three independent
+  `fabric_exec` executions can become a composite action or skill. Core
+  `omp.*` primitives are excluded because they are implementation steps to
+  batch, not domain actions to fuse; failed and excluded operations break
+  contiguity.
+- `noise-quarantine`: a ref with ≥ 3 calls, more failures than successes,
+  and ≥ 1.0 bits of failure-stage entropy hides from the model-facing
+  catalog.
+
+Repair rows do not produce proposals. They are already guarded compatibility
+aliases from a spilled key or action spelling to its canonical declaration.
+An alias hit proves the compatibility map is useful, not that the alias should
+replace the canonical public name. `/fabric repairs` shows the mappings and
+`/fabric entropy` reports their count and hits separately.
+
+`applyProposalsToSurface` applies the mechanical subset (enum-tighten and
+noise-quarantine) as a pure surface rewrite. Declare-enum, overload-split, and
+sequence-fuse stay review-only.
+
+## The gate (ratchet)
+
+`evaluateGate(before, after)` passes only when the compiled surface does not
+increase the score. `compileEntropySurface` adds the second half of the
+contract: replay preservation. Every successful call to a ref the compile
+touched must still parse against the candidate surface, checked with the
+same TypeBox validation the registry's validate stage runs. When a
+touched ref has verbatim audit calls, they are the replay corpus: trace
+V1 projects values away per ref, so projected trace args cannot judge a
+candidate. Audits the declared surface already rejected are not
+protected, because those calls never executed. The compile step
+is measure → propose → apply → re-measure → gate; a gate failure keeps the
+old surface and records the rejection. Monotonicity and preservation are
+measured, never argued. A converged surface stops proposing, which the
+certification proves by requiring an empty second round.
+
+The autonomous loop applies only the mechanically safe kinds
+(`enum-tighten` and `noise-quarantine`), and only beneath a domain the
+declared schema already bounds. `overload-split` and `sequence-fuse` author
+new composite definitions, while `declare-enum` requires explicit author
+intent, so all three stay surfaced for review and never auto-apply. Review
+notifications describe the suggestions in plain language and emit each
+distinct suggestion set once per session. Evidence
+counts changing underneath the same suggestion do not repeat it; a changed
+vocabulary, split, or sequence does.
+
+## The compile loop
+
+The reducer is autonomous, mirroring the repair loop: no command, no
+approval, machine-checked bounds replace review. Every turn that invoked
+`fabric_exec` may have produced new action evidence, so at `turn_end` Fabric
+enqueues a background compile and returns the hook immediately. A 250 ms grace
+period lets OMP finish appending the turn; triggers that arrive during a compile
+coalesce into one follow-up using the newest context. The worker reads the live
+session window, snapshots the declared surface through the discovery path, and
+runs measure → propose → apply → gate against it. Directory discovery, stat,
+JSONL scanning, lock waits, and atomic persistence use asynchronous I/O;
+scoring, safety replay, evidence hashing, and observation pooling yield in fixed deterministic chunks. Session
+files stream line by line with bounded concurrency. A bounded metadata-keyed
+cache reuses unchanged evidence; when the active JSONL grows, the scanner reads
+only the appended byte range and carries its model-attribution cursor forward.
+Replacement, truncation, or an incomplete trailing record falls back safely.
+Large logs therefore no longer impose one whole-window synchronous read/parse
+stall on every turn, and a lock held by another OMP
+process no longer blocks TUI timers while compilation proceeds.
+
+The window is machine-wide, covering the newest sessions across every project
+under the agent dir, so evidence breadth matches enforcement breadth: the
+artifact governs the whole machine, so it learns from the whole machine. The
+current project's newest session is always included so the live session that
+produced this turn's evidence is never crowded out. The snapshot keeps
+quarantined refs visible because digest proofs and artifact carry-forward read
+the declared schema; the model-facing catalog keeps hiding them. Session
+shutdown awaits the queued final compile for durability, but all of that work
+remains cooperative with the event loop.
+
+A notification appears only when a newly persisted artifact changes the live
+surface. It starts with `background optimization complete`, includes elapsed
+work time, names up to three concrete targets and values, prints enough decimal
+places to distinguish the before/after scores (with an explicit signed delta),
+states that lower is better, and says that the safety checks passed. An equal
+score is labeled `entropy score unchanged`. Review suggestions point to
+`/fabric entropy`; internal proposal-kind jargon stays out of user-facing
+notices.
+
+Value observations pool machine-wide with exact per-session deltas:
+`<agent dir>/fabric/entropy/observation-pool.json` accumulates per-value
+counts across every window the compiler reads, so a sparse closed domain
+(a parameter used once or twice per session) still reaches the ≥ 8
+observation threshold without widening the gate-local window. A session
+contributes exactly once per content: unchanged files skip by digest,
+growing files contribute only their delta, and evicted sessions bake with
+their digest remembered, so no evidence can inflate by re-reading. The
+pool is bounded (16 tracked values per parameter, above the 8-value
+eligibility guard, so an overflowed domain stays provably open) and is
+pure derived evidence: damage surfaces and blocks the merge, never
+silently rebuilds.
+
+A passing compile persists the compiled surface to
+`<agent dir>/fabric/entropy/compiled.json` beside the repair table: overlay
+entries and quarantines, the applied-proposal ledger, the gate record, and
+the evidence digest. The artifact is clock-free, so identical evidence
+compiles to identical bytes and saving them is a no-op. The runtime loads it at session start, a passing compile
+activates the new artifact immediately, and enforcement is live:
+
+- the compiled schema overlays the declared schema at the registry's prepare
+  and validate stages, so enum-tightened parameters reject off-modal
+  values;
+- quarantined refs resolve as unknown actions and disappear from the
+  model-facing catalog, exactly like retired actions;
+- every consult re-proves the recorded base digest against the live declared
+  schema, so a surface that changed underneath a compile drops its overlay
+  and never mis-enforces.
+
+Failure modes stay visible, never silent: a gate rejection keeps the old
+surface and notifies once per distinct reason set; a damaged
+`compiled.json` surfaces in `/fabric entropy`, blocks compiles from
+overwriting it, and keeps enforcement off. `entropy.compile: false` in the
+Fabric config disables the loop and the enforcement entirely.
+
+## On-demand measurement
+
+Session JSONL is the source of truth, so nothing is recorded. `/fabric
+entropy` asynchronously discovers the newest machine sessions (window of 8
+files total, newest first by mtime, spanning every project under the agent dir
+with the current project's newest session guaranteed), streams each file
+against the live surface snapshot, and reports the latest session's score plus
+the least-squares slope across the window's session scores
+(`trendFromScores`). The command shares the bounded evidence cache with the
+background compiler. Lines without a trace envelope are skipped by a cheap
+substring filter before parsing. The repair table, the compiled entropy
+surface, and the machine-wide observation pool remain the only durable derived
+artifacts; only the first two change runtime behavior, the pool only moves
+thresholds.
+
+## Commands and certification
+
+```text
+/fabric entropy                          # live surface freedom + observed session entropy trend
+/fabric entropy export [path]             # write the live surface snapshot (default <agent dir>/fabric/entropy/surface.json)
+/fabric entropy export-artifact [path]    # write the compiled artifact (default <agent dir>/fabric/entropy/artifact.json)
+/fabric entropy import <path>             # merge a peer artifact (digest-proven entries only)
+```
+
+Repo-side only (development and CI; these scripts are not part of the
+installed package):
+
+```text
+bun run certify:entropy                                     # offline fixtures, exact math, ratchet proof, ingestion
+bun run certify:entropy --sessions <dir> --surface <snap>   # measure an arbitrary session corpus
+bun run certify:entropy --sessions <dir> --surface <snap> --trial   # also run the held-out trial
+```
+
+`/fabric entropy` measures on demand: the newest machine sessions are read
+from the session logs (all projects; `--project` scopes to the current
+project's window), measured against the effective surface (live plus
+the compiled overlay), and the trend is the per-session slope; the display
+carries a `compiled:` line with the artifact's applied proposals and last
+gate outcome, and a `review:` line listing the signals the compiler declined
+to apply (opted-in enum vocabularies, overload splits, and high-level
+sequence fusions), derived read-only from the current window and the
+observation pool. Repair rows appear separately as aliases; they are already
+active compatibility mappings and are not review suggestions. Gate rejections
+are silent by design: the ratchet kept the old surface, and the display shows
+the compiled state on demand. `/fabric entropy export [path]` snapshots the
+live registry through the discovery path (read-only, authorization-free),
+defaulting to `<agent dir>/fabric/entropy/surface.json` beside the repair table, as
+`{ version: 1, actions: [{ ref, inputSchema }] }`, sorted by ref so it
+hashes stably. Pass an exported snapshot with `--surface` to measure a
+copied corpus against the surface it ran on; the report then carries the
+surface hash as its catalog digest, so scores compare like against like.
+
+## Federation
+
+The compiled artifact is the shareable unit of improvement:
+`/fabric entropy export-artifact [path]` writes the machine's compiled
+surface, and `/fabric entropy import <path>` merges a peer's artifact into
+the local one. Merging is digest-proven, never trusted: an incoming entry
+earns a slot only while its recorded base digest matches the live declared
+schema, and only where the local artifact has nothing to say about that ref
+(conflicts skip; local wins). Unproven entries are dropped and counted in
+the import notification. The applied ledgers union by identity, local
+first, capped at the store's maximum. A merged artifact saves through the
+locked store and activates immediately when compiles are enabled, and every
+consult keeps re-proving entries against the live schema, so an import can
+tighten the local surface but never reshape it. One machine's head start
+becomes every machine's.
+
+## Held-out trials
+
+The trial is the falsifiable half of the compiler: with `--trial` (plus
+`--sessions` and `--surface`), every recorded call in the corpus replays
+against both the declared surface and the compiled artifact (`--artifact
+<path>` overrides the agent dir's `compiled.json`), and each divergence is
+classified deterministically. Calls the declared schema already rejected
+credit nothing. Refs with verbatim audit calls replay from the audit
+arguments, never the projected trace args; audits record executed calls
+without outcomes, so a compiled rejection of an audited call counts as a
+tightening cost, never a win. The falsifier stays pessimistic where the
+record is silent. Succeeded calls the compiled schema would reject count as
+tightening costs: the compile overfit its window, and the certification
+fails on any of them, because the in-loop replay gate promised exactly
+that. Calls that failed anyway count as wins when the artifact would have
+rejected them: a cheap typed rejection replaces an expensive failure. A
+quarantined ref's succeeded calls count as quarantine costs and are
+reported without failing, because retiring a ref that once succeeded is
+what a quarantine is allowed to do. The report carries the verdict
+(`clean`, `costly`, or `no-evidence`), both window scores, and the
+per-ref divergence counts.
+
+The certification harness exits nonzero on any failed check, mirroring
+`certify:context`: determinism (double-run hash equality), exact metric math
+on fixed corpora, the full ratchet loop with convergence, the compile loop
+with a gate-rejected round and a converged second pass, surface-apply
+purity, synthetic session-JSONL ingestion, and audit-derived value
+observations. The `Entropy` GitHub workflow runs the certification on every
+push to `main` and weekly, uploading the JSON report as an artifact; a red
+certification fails the build, so the metric and ratchet stay verified per
+commit.
+
+## Determinism contract
+
+- Fixed canonicalization, fixed thresholds, fixed weights; changes bump
+  `ENTROPY_METRIC_VERSION` so ledger trends never mix formulas.
+- No clocks, randomness, or model calls inside measured values.
+- Only typed records are consumed; prose is never classified, the same
+  discipline as [schema enforcement](schema-enforcement.md).
+- Metric v2 adds `byModel` attribution; every v1 weight and formula is
+  unchanged.
+- The report hashes stably (`entropyReportHash`), so per-commit scores are
+  bisectable.
+
+## Limitations
+
+- Trace V1 projects arguments per ref (grep patterns, edit contents, and
+  external arguments are dropped), so shape signatures see the projected
+  key sets. Value-level passes read the verbatim audits through
+  `entropyValueObservationsFromSessionJsonl`, which keeps enum-tighten
+  working for value-dropped parameters as long as the session record (or an
+  exported corpus) travels with the measurement.
+- The gate proves score monotonicity on the retained corpus, not equivalence
+  of future behavior. Quarantine preconditions (more failures than
+  successes) carry the replay-safety argument for retired refs.
+- Flow entropy groups executions by the persisted first workflow phase (or
+  `(none)`), which is a coarse task key.
+- The on-demand trend covers the newest machine sessions only (mtime
+  ordered, machine-wide window of 8): sessions the user prunes leave the
+  trend, and the slope is only as strong as the window. Widening the corpus
+  scope shifts measured scores, so certification baselines recorded against
+  a per-project corpus must be re-recorded once against the machine window.
+- The compile trigger is per-turn, but pooled observations outlive the
+  window: evidence stays eligible until the schema beneath it changes. The
+  gate and the replay stay scoped to the current window, so a pooled
+  proposal still has to keep every recorded call parsing.

package/docs/interface.md

@@ -0,0 +1,149 @@
+# Interface & commands
+
+Fabric builds its UI on the public `pi-code-previews` cooperative shell and on a general-purpose, theme-aware activity surface. You do not need to install `pi-code-previews` separately.
+
+## Code previews
+
+`fabric_exec` inherits the user's border/background mode, collapsed-result behavior, error styling, and tool-call timing. It does not take ownership of OMP's built-in tool renderers. Its renderer adds a numbered TypeScript preview, live phase and call activity, and compact phase and nested-call summaries. Preview settings live in the unified Fabric configuration: the `codePreview` section of `<active OMP agent dir>/fabric.json` (global) or `.omp/fabric.json` (trusted project). You can edit them live under `/fabric settings` → **Code previews**. Fabric no longer reads the standalone `code-previews.json` file or the `codePreview` keys in OMP settings. `codePreview.shikiTheme` defaults to `"auto"`. That value tracks OMP's resolved light/dark variant (GitHub Light on light terminals, Dark+ on dark) as OMP auto-switches. A `"<light>/<dark>"` value pins both variants. Any other value fixes one shiki theme.
+
+Nested `omp.read`, `omp.bash`, `omp.grep`, `omp.find`, `omp.ls`, `omp.write`, and `omp.edit` calls share the preview settings and presentation vocabulary of `pi-code-previews`: offset-aware read gutters, syntax and secret warnings, grouped and highlighted grep matches, iconized path trees, bash warnings and output metadata, and proposed or applied edit and overwrite diffs with compact context, line gutters, full-row backgrounds, and word-level emphasis. Large inputs fall back to escaped plain text with an explicit notice. The same layer renders in-memory Activity call details. Fabric keeps rich call data only in current-session renderer and activity state. Durable traces keep their existing bounded confidentiality projection.
+
+Fabric keeps its orchestration-specific behavior around those previews. Multi-call rows stay compact, and live write composition with phase/call progress stays visible during the run. Agent and actor audits can expose their current child tools directly in the parent card, with owner, runner, and run metadata. One execution-wide throttle coalesces parallel nested-call updates before they reach OMP, and continuous streams are not starved. Long ANSI rows are bounded without clearing the enclosing tool background. The widget lease plus result-to-source row transfer keep completion height stable. The highlighter initializes lazily and falls back to plain text until it is ready. When OMP switches between its light and dark variants, the highlighter swaps themes live. Collapsed previews use the configured expand keybinding, for example `Ctrl-O`.
+
+## Focused conversations
+
+Press **Ctrl+Shift+A** or run **`/fabric chat`** to open a full-screen conversation without going through the dashboard. `/fabric chat <id-or-name>` opens a specific agent or actor; Tab completes exact participant IDs, including nested agents. Ambiguous names or ID prefixes are rejected; use an exact participant ID to select the intended target. In the dashboard, **Shift+C** opens the selected participant.
+
+The first implicit open prefers a currently active child over stale history; later opens remember a valid selection. The view keeps a lossless native OMP transcript and a multiline OMP editor together, independently of the dashboard’s bounded transcript projection. It uses OMP’s real user, assistant, thinking, tool, skill, custom-message, and summary components, including registered tool renderers such as `fabric_exec`, with complete tool details and native expansion behavior. User backgrounds and editor rules span the terminal width. Fabric reads only `terminal.showImages` and `hideThinkingBlock` from OMP’s global settings plus a trusted project layer; untrusted sessions use an in-memory OMP instance with schema defaults (`terminal.showImages: true`, `hideThinkingBlock: false`). Removed appearance keys keep explicit compatibility defaults: `editorPaddingX: 0`, `outputPad: 0`, and `codeBlockIndent: "  "`. Markdown and tool previews use the configured Shiki theme. The footer below the editor shows the selected participant’s directory, known branch, model, thinking level, and run-scoped token/cache/cost statistics. Unknown usage and context occupancy are marked explicitly; Main’s statistics are never substituted. Breadcrumbs preserve `Main → child → grandchild` lineage. Main and other participants keep running: opening, navigating, and closing the view never calls OMP’s session-replacement API or starts another worker. Selecting Main restores the original OMP conversation, including its editor. Child drafts and scroll positions survive switching targets and reopening the view for the lifetime of this OMP session.
+
+| Control | Action |
+| --- | --- |
+| Enter | Send a steering message to the selected live participant |
+| Follow-up key (Alt+Enter by default; Ctrl+Q on Windows) | Queue a follow-up for the selected participant |
+| Shift+Enter | Insert a newline |
+| Ctrl+N or `/agents` | Open the searchable participant picker |
+| Alt+Left / Alt+Right at an empty editor | Navigate to parent / first child |
+| Ctrl+Tab / Ctrl+Shift+Tab | Cycle conversations |
+| Mouse wheel / configured OMP scroll keys | Scroll locally and fetch older history; prompt, line, and page jumps work in both TUI modes |
+| End | Follow the latest output |
+| OMP's tool-expand key (Ctrl+O by default) | Toggle tool details |
+| `/stop` | Explicitly stop the selected participant after confirmation |
+| Esc or `/back` | Return to Main without interrupting any agent |
+
+Direct actor messages appear as normal user text, with paired RPC start/end events shown once. Session branches and compaction remain authoritative over overlapping RPC history. Native message errors remain visible. Use `/fabric log <id>` to inspect worker startup diagnostics. The widget advertises `Ctrl+Shift+A chat` only while an agent or actor is active, and removes the hint when work settles. The command and shortcut remain available for idle and historical conversations.
+
+Pending messages use OMP’s native labels and spacing. When a compatible loaded `pi-queue-steer` provides `queue-steer:conversation-queue:request:v1`, the view uses its actual per-target queue, execution-outline widget, and inline editor. A stopped actor’s Alt+Enter input is parked for editing or explicit Enter release. Accepted sends remain visible until native delivery is observed; they cannot be retracted or edited locally. Queues stay isolated from Main and other targets, survive preview close/reopen within the session, and are cleared on session reset. Older queue-extension releases without the bridge use the native display.
+
+Messages use the same ownership-aware route as `agents.steer` / `agents.followUp`. A failed delivery keeps the draft. Capability and lifecycle checks run again at dispatch, so a child that finishes while you type cannot silently receive a message in Main or be respawned. Persistent actors accept subsequent mailbox messages, including while idle. Finished one-shot runs remain readable but cannot continue; Veda one-shot runs do not support mid-run messaging. A remote participant without an accessible transcript shows an explicit transcript-unavailable notice.
+
+This is a focused view over the existing worker, not a second native OMP runtime. Other OMP slash commands, shell shortcuts (`!`), and child extension dialogs are not routed through this view. Unsupported commands are rejected visibly, never forwarded to Main. Native image attachment and full command/extension parity require a separate worker attachment protocol. The existing dashboard retains model, actor-policy, and configuration controls.
+
+## Activity surface
+
+Fabric ships a general-purpose, theme-aware activity surface that works with any agent setup:
+
+- A compact widget above the chat (like `pi-supervisor`) follows the current phase in its header. It lists active and completed one-shot agents plus active actor workers. Their recent or running child tools nest beneath the owner, with compact edit/write change lines and owner metadata. Extensions, custom items, and shared tasks/state stay summarized by the header or appear in the dashboard, so they never occupy widget rows. The widget retains completed agent rows and a per-run high-water height, which stops tool finalization from pulling the chat upward. It resets that lease when a newer run starts, and the latest completed summary stays visible until that newer run replaces it. Snapshot bounds first preserve every active local agent, then local history, and only then admit remote project records. When a collapsed Fabric result becomes shorter at completion, the card reveals a bounded number of otherwise hidden TypeScript source lines. Those lines replace the removed rows without blank padding, and any residual deficit shrinks naturally.
+- `/fabric` (or `/fabric dashboard`) opens a responsive interactive overlay with two views: **Activity** and a unified **Topology**. Press `1` for Activity and `2` for Topology.
+  - **Activity** lays out the workflow phase sidebar on the left and the selected phase's activity on the right. The user-facing OMP agent is always present as **Main**, including when no Fabric child exists and regardless of the status filter. Main remains an actionable queue target. The right pane orders entities under type headings for agents, actors, tools, extensions, tasks, custom items, and shared state, with a blank row between groups. The selectable order matches the rendered group order. One-shot agents stay stable in creation order. Attention-priority work keeps the default focus, so Main does not steal it.
+  - **Topology** merges the selected retained run with the live project mesh in one graph rooted at **Main**. It deduplicates agents observed through both run and participant data, and it separates execution membership from coordination infrastructure:
+
+    ```text
+    Main
+    ├─ Participants
+    │  ├─ Sessions       peers and remote root OMP sessions
+    │  ├─ Agents         local, remote, and recursively owned agents
+    │  └─ Actors         local and remote persistent actors
+    └─ Mesh
+       ├─ Topics
+       │  ├─ Fabric      fabric.state, fabric.schema, and fabric.<family>.*
+       │  └─ Project     arbitrary topics grouped by their first namespace
+       └─ State
+          ├─ World state
+          │  ├─ current
+          │  ├─ goal
+          │  └─ Complexity
+          │     └─ <project directories> → <file ledger>
+          ├─ Schema
+          │  ├─ workspace
+          │  ├─ Hypotheses → <id>
+          │  ├─ Certificates → <token hash>
+          │  └─ <future schema namespaces>
+          └─ Project state
+             └─ <key directories> → <entry>
+    ```
+
+    Explicit ownership stays intact below those categories. Recursive agents nest under their parents. Actor workers remain under their actor, and remote descendants keep their place under the remote root. State ownership uses a mesh relationship. Owned state remains in the State tree. A state entry that identifies a project-relative file (including every `state/complexity/<file>` ledger) exposes a bounded, line-numbered Shiki source preview in both the topology inspector and full dashboard detail. The preview resolver rejects absolute paths, traversal, symlink escapes, non-files, and binary content. It caches by real path, mtime, and size. Internal membership and control keys (`topology/*`, legacy `sessions/*`, and actor registry `actors/*`) are filtered from shared state, because their canonical entities already appear under Participants. Global actor templates are absent because they are not running project nodes.
+  - Topic names accept `.`, `:`, and `/`. A `fabric.*` topic uses the Fabric branch. Every other name uses Project topics, grouped by its first namespace. Built-in host traffic includes `fabric.actor.*`, `fabric.control.*`, `fabric.participant.lifecycle`, `fabric.steer`, and `fabric.compact`. System-only topics stay suppressed as standalone nodes unless someone explicitly subscribes to them, and their traffic can still appear in the bounded event feed. State keys preserve `/` hierarchy. The known durable families are `state/current`, `state/goal`, `state/complexity/<file>`, `schema/workspace`, `schema/hypothesis/<id>`, and `schema/certificate/<hash>`. Every other visible mesh key falls back to Project state without losing its directory structure.
+  - The graph renders status-coloured node shapes, orthogonal connectors, animated traffic, an optional fixed-width selected-node inspector, and directional off-canvas summaries. Traffic follows the same structural branches through the source/target lowest common ancestor. It never draws direct lines through unrelated subtrees. A large or deeply recursive graph opens around the attention-priority node. When you move between nodes, a damped spring camera retargets smoothly and the viewport does not snap. Live and replay animation drives renders only while the dashboard is open. Narrow terminals keep the centred graph and drop the inspector.
+  - Retained-run selection works as a lens over the same topology. Pressing `[` or `]` changes the highlighted run and its phase context, and live actors and remote project participants stay visible. Route records remain selectable, and they aggregate repeated traffic by source, target, topic, and kind. The recent event feed is a bounded live window. It does not replace audit history.
+  - **Inspection and control** work the same way in both views. Agent detail includes Markdown-rendered tasks and results, highlighted YAML values, model, current tool, usage, worktree, and attach metadata. Tool-call details show highlighted command, file, and edit inputs, with Markdown or YAML outputs. Persisted bash calls keep their command text. Space peeks at an agent or actor transcript. `t` toggles between summary and transcript detail. The initial bounded tail is paged directly from OMP RPC, OMP session, and Claude stream-JSON logs. At the loaded top, `k` or Up fetches one older page, `g` loads and jumps to the true beginning, and `G` jumps to the growing tail and resumes follow mode. Assistant text uses native Markdown. Tool calls retain structured arguments and results, so they get the same read, bash, search, edit, and write previews as the parent card. Credential and token redaction applies before rendering. You can steer Main and active one-shot agents or queue them a follow-up, and one-shot agents can also be stopped safely. Persistent actors accept `s` mailbox messages. Where configured, they expose model (`m`), thinking (`e`), the complete session-bound OMP host-event catalog (`v`), instructions (`i`), mailbox clearing (`c`), and export (`x`). Remote participants expose only their advertised capabilities. Control resolves their owner and reports success after acknowledgement. From Activity, global templates stay available for import (`p`), instruction editing (`i`), and deletion (`d`).
+- `/fabric settings` opens an inline settings view that mirrors OMP core's `/settings`, with top and bottom borders, fuzzy search, and section submenus, and it writes changes to `fabric.json`. Trusted projects default to `<project>/.omp/fabric.json`. Pressing **Ctrl+G** anywhere in the view switches both the displayed configuration layer and the save destination between project and global `<active OMP agent dir>/fabric.json`. The global view keeps global edits visible even when a project override remains effective, and its scope banner states that precedence explicitly. Untrusted sessions stay global-only. In RPC hosts, the same hierarchy is exposed through recursive select/input dialogs; a root save-scope action replaces the Ctrl+G shortcut, while Back returns one section at a time. Full code mode, capture, executor, approvals, and UI changes apply immediately when they change the effective configuration. Mesh, agent, retention, and MCP changes persist and take effect on the next `/fabric reload`. The UI section includes **Tool display** (`full` by default or `compact`), a default-on **Agent tool preview** toggle, and a global **Update debounce** (`0`/Off through `1000ms`, default `100ms`); all apply immediately. Compact display makes the declared Fabric display name/description the card header, hides outer TypeScript at every expansion level, and retains bounded nested tool details. The Agents section selects the default runner, keeps independent OMP and runtime-enumerated Claude model pickers, and exposes free-text Veda backend, persona, and model fields for the Veda runner. List editors for `agents.defaultTools` and `capture.keepVisible` toggle known tools on and off. The `keepVisible` candidates include `fabric_exec` plus every captured extension tool.
+
+### Keybindings
+
+- In `/fabric settings`, **Ctrl+G** switches the displayed values and the save destination between project overrides and global defaults. Untrusted sessions remain global-only.
+- Press `1` for Activity and `2` for the unified Topology. In Topology, arrow keys move spatially between graph nodes, `h`/`l` mirror left and right, `j`/`k` follow deterministic entity order, and Tab advances to the next node. In Activity, arrows or Tab switch panes and select rows. `g` and `G` jump to the first and last selectable entity, Enter inspects, `f` cycles status filters, `[`/`]` change the retained-run lens, and `?` opens contextual help.
+- On Main, `s` sends a user-authored message or steer, and `u` queues a user-authored follow-up through OMP's host queue.
+- On agents and actors, Space peeks at the transcript and `t` toggles transcript/summary detail. Inside a transcript, `g` loads and jumps to the true top, and `G` jumps to the bottom and follows new output. On active one-shot agents, `s` opens a steer editor, `u` queues a follow-up, and pressing `x` twice stops the run. Remote participants expose capability-aware, owner-acknowledged `s`, `u`, and `x` controls.
+- On actors, `s` queues a serial mailbox message. Lowercase `m` and `e` change this OMP session's model and thinking. Uppercase `M` and `E` change the shared project defaults and appear only on the owner. Actor detail shows both layers, the effective values, and the live owner.
+- Owner views also expose `v` for host events, `i` for instructions, and other shared actor settings. Passive views hide those controls but keep session bindings, messaging, reads, and `x` export. `p` imports a global template, `d` deletes one, and Esc backs out or closes.
+
+## Data-driven activity
+
+The surface is data-driven. Fabric automatically instruments nested provider calls, agents, persistent actors, and task-shaped mesh entries. A workflow can add domain-specific labels and arbitrary progress, and it needs no extension UI code:
+
+```ts
+await workflow.configure({ name: "Release train", description: "Build, verify, and publish" });
+await phase("Build", { total: packages.length });
+await workflow.item({
+  id: "docs",
+  label: "Documentation",
+  status: "running",
+  completed: 2,
+  total: 5,
+});
+await workflow.event({ message: "Canary passed", level: "success" });
+```
+
+External Fabric providers can emit structured `context.activity()` updates for an entity, a progress message, or metrics. The TUI stays generic, and a virtual provider can still expose richer live state.
+
+```ts
+async invoke(actionName, args, context) {
+  context.activity?.({ type: "entity", id: job.id, kind: "custom", name: job.name });
+  context.activity?.({ type: "progress", message: "Indexing package 3/12" });
+  context.activity?.({ type: "metrics", tokens: 4200, toolCalls: 9 });
+  return job.result;
+}
+```
+
+## Commands
+
+```text
+/fabric status
+/fabric dashboard
+/fabric chat [participant-id-or-name]
+/fabric settings
+/fabric reload
+/fabric providers
+/fabric captured [query]
+/fabric agents
+/fabric actors
+/fabric messages <actor-id>
+/fabric attach <agent-id>
+/fabric stop <actor-or-agent-id>
+/fabric repairs
+/fabric entropy
+```
+
+Actor slash commands mirror the [global template API](agents.md#global-actor-templates). `/fabric global` lists templates. `/fabric import <name> [as <new>]` stamps one into the project. `/fabric export <id> [--overwrite]` promotes a project actor. `/fabric log <id>` previews an actor or run transcript, and `/fabric export-log <id> [path]` writes the raw `session.jsonl` plus retained `runs/` to disk.
+
+## Headless focused agents
+
+OMP already runs one-shot, non-interactive agents with `omp -p` (`--print`), and it reads piped stdin as part of the prompt. A focused agent composes with pipes, cron, git hooks, and CI like a Unix program, and it needs no wrapper:
+
+```bash
+git diff | omp -p --no-session --tools read,grep "Review this diff for concrete defects."
+omp -p --no-session --mode json -e <path-to-omp-fabric> "Map the persistence layer."
+```
+
+`--no-session` keeps the run ephemeral. `--tools` restricts the tool allowlist. `--mode json` emits a structured event stream for scripting through `| jq`. `-e <omp-fabric>` loads Fabric so the agent can use `fabric_exec`. The process exits non-zero on failure. Run `omp --help` for the full flag list.