omp-fabric 0.85.0

package/skills/fabric-exec/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: fabric-exec
+description: >-
+  Troubleshooting and advanced API reference for `fabric_exec` TypeScript
+  programs, dynamic providers, agents, and schema recovery. Routine `omp.*`
+  coding calls are documented by ambient guidance; load this skill only after
+  an argument-shape error or when an advanced surface needs exact contracts.
+---
+
+# fabric_exec — core reference
+
+One type-checked TS program in a fresh executor (isolated QuickJS by default). Only the `return` value reaches the model; `print()`/`console.log` go to the activity panel. `payloads` is not a tool.
+
+## `omp` core tools (full code mode only)
+`omp.<tool>(arg)` — single arg: bare string (primary field) or options object, or a two-arg `(primary, options)` merge for the string-primary tools (`read`/`bash`/`ls`/`grep`/`find`): `omp.read('index.ts', { limit: 120 })` becomes `{ path: 'index.ts', limit: 120 }`, the positional string winning the primary field on conflict; a non-object second arg on those is still a type error. Positional tuple calls are accepted for `grep`/`find` (`pattern, path, limit`), `write` (`path, content`), and `edit` (`path, oldText, newText`).
+
+| Tool | Form | Returns |
+|------|------|---------|
+| `read` | `path` \| `{path,offset?,limit?}` \| `(path, options?)` | `string` |
+| `bash` | `command` \| `{command,timeout?,cwd?}` \| `(command, options?)` | `{ok:true,output,details}`; rejects on a nonzero exit (`settle:true` returns `{ok:false,output,details:null,exitCode,error}` instead) |
+| `grep` | `pattern` \| `{pattern,path?,glob?,ignoreCase?,literal?,context?,limit?}` \| `(pattern, path?, limit?)` | `string` |
+| `find` | `pattern` \| `{pattern,path?,limit?}` \| `(pattern, path?, limit?)` | `string` |
+| `ls` | `path?` \| `{path?,limit?}` \| `(path, options?)` | `string` |
+| `edit` | `{path,edits:[{oldText,newText,all?}],all?}` \| `{path,oldText,newText,all?}` \| `(path, oldText, newText)` | `{ok,output,details}` |
+| `write` | `{path,content}` \| `(path, content)` | `{ok,output,details}` |
+
+`omp.bash` has no `stdin` option. When a command needs content input, write it to a file with `omp.write(path, content)`, then pass that path to the command or redirect the file into it; do not interpolate untrusted content into shell code.
+
+For `omp.edit`, entry-level `all:true` applies that replacement to every non-overlapping occurrence; top-level `all:true` applies every entry that way. Omit it for unique anchors.
+
+Shell tools reject on an ordinary nonzero exit; pass `settle:true` to get `{ok:false,output,details:null,exitCode,error}` instead of a rejection. Timeout, cancellation, approval, security, and spawn failures still reject. Other OMP core tool errors reject normally.
+
+Aliases are normalized to canonical fields before host validation. Command aliases include `cmd`/`shell`/`cmdline`/`script`/`commandLine`; pattern aliases include `query`/`regex`/`search` plus `q`/`expression`/`text` for grep and `name`/`filename`/`glob`/`include` for find. Path aliases include `file`, `file_path`, camel-case path variants, `dir`/`folder`/`directory`, and target-file variants. Edit text accepts `old`/`from`/`old_string`-style and `new`/`to`/`replacement`/`new_string`-style spellings, including inside `edits`; write content accepts `contents`/`body`/`text`/`data`/`fileContent`. `ic`/`caseInsensitive`→`ignoreCase`, `globPattern`→`glob`, `ctx`→`context`, `max`→`limit`, and `start`→`offset`.
+
+Shell `timeout` is in seconds; `timeoutMs` is converted from milliseconds. Numeric strings in `limit`, `timeout`, `offset`, and `context` coerce to numbers. `null`/`undefined` is omitted only for known optional fields; required fields remain invalid so authoritative host validation still reports them. Canonical fields win when both canonical and alias spellings are present. Unknown keys still fail the excess-property type check.
+
+`bash`/`edit`/`write` always resolve an envelope `{ ok, output, details }`, never a bare string, and the executor guards those envelopes: a string method or iteration applied to the envelope itself (`r.trim()`, `for (const line of r)`) throws a TypeError naming the fix (`.output`) instead of a context-free "not a function".
+
+A captured extension that registers an exact core name may provide a compatible additive override. Fabric derives a bounded object overload from the current override schema and adds it to the familiar `omp.<name>` surface wherever execution is effectively full-code, including Schema enforce mode; built-in positional calls, bare strings, shorthand, aliases, and normalized result contracts remain Fabric-owned. Override-specific prompt metadata is appended under that same `omp.<name>` identity. Schema enforce still applies its host restrictions to protected mutations and external effects. Unsupported or over-budget schemas use a loose object overload and still pass through authoritative registry validation, so use the effective schema and retry from the validation error when needed.
+
+## Read economy
+
+Search before reading. Run `omp.grep`/`omp.find` first, then `omp.read({ path, offset, limit })` the matching range instead of unbounded whole-file reads:
+
+```ts
+// Locate the symbol, then read only the window around the hit.
+const hits = await omp.grep({ pattern: "targetSymbol", path: "src", context: 2 });
+const window = await omp.read({ path: "src/engine.ts", offset: 120, limit: 80 });
+```
+
+An unbounded `omp.read('/x')` returns at most 2000 lines or 50KB (whichever is hit first); truncated output ends with a `[Showing lines a-b of N. Use offset=n to continue.]` notice — continue with `offset` only when you truly need the full file. Reserve whole-file reads for small files you will use in full (configs, tests or files you are about to edit, sources under a few hundred lines). Batching several large whole-file reads into one program inflates the single tool result, and that enlarged result stays in every later turn's context.
+
+Keep multiline or syntax-heavy payloads out of `code`: pass them through `payloads` and read the exact matching key from `payloads`. For example, `payloads: { content: text }` is read as `omp.content`; do not invent a different reference such as `omp.task`. Every `omp.key` must exist in the same call's top-level `payloads` map. TypeScript still parses template-literal contents, including shell heredocs. The legacy `strings` argument is accepted as an alias.
+
+## First-class provider calls
+Use direct proxies when the action is known. Parallelize only independent calls: provider effect footprints record conflicts for overlapping or unknown non-commutative resources, and Fabric does not silently reorder them. No-argument actions such as `schema.status()`, `state.get()`, and `compact.status()` take no options object. Provider calls still cross the same registry validation, approval, audit, timeout, and cancellation path as generic calls.
+
+### Stable provider return shapes
+
+All calls return promises. Fields ending in `?` are optional; `unknown` marks provider data whose nested schema is not stable at this surface.
+
+| Call | Resolves to |
+|------|-------------|
+| `memory.recall(args?)` | `{total,hits:MemoryRecallHit[],next:{ref:"memory.recall",args}|null,coverage:MemoryCoverage,error?}` |
+| `memory.expand(args)` | `{session?,sourceHash?,branches?,lineageFingerprint?,entryCount?,entries:ExpandedSessionEntry[],next?:{ref:"memory.expand",args}|null,error?}` |
+| `memory.walk(args, visitor)` | `{visited,stopped,error?}`; guest-local paging and full-entry reassembly over `memory.expand` |
+| `memory.sessions(args?)` | `{scope?,branches?,sessions?:SessionInfo[],error?}`; slice `result.sessions ?? []`, not the wrapper |
+| `state.transition(args)` | `{event:FabricMeshEvent,head:unknown}` |
+| `state.get()` | `{head,goal,complexity,certification,recentLabels:string[]}` |
+| `state.history(args?)` | `{transitions:unknown[],labels:string[],certifications:unknown[]}` |
+| `state.complexity(args?)` | `{files:ComplexityFile[],netDelta:number}` |
+| `state.verify(args?)` | `{certified,violated,certificationStatus,results,failures,certificate?,reportingError?,evidenceDigest,resultDigest}` |
+| `state.goal(args)` | mesh state entry `{key,value,version,updatedAt,updatedBy}` |
+| `state.checkGoal(args?)` | `{passed:boolean,output:string,exitCode:number\|null,error?}` |
+| `schema.status()` | `{mode,certificateTtlMs,maxFiles,maxBytes,trustedCommands,generation,lastOutcome,hypotheses}` |
+| `schema.hypothesize(args)` | `{hypothesisId,status,state,fingerprint,generation}` |
+| `schema.verify(args)` | `{verified,hypothesisId,certificate?,issuedAt?,expiresAt?,reason?,results}` |
+| `schema.commit(args)` | `{outcome,transactionId,generation?,paths?,postconditions?,complexityReductionCertified?,stateTransition?,error?,rollbackError?}` |
+| `schema.abort(args)` | `{aborted:true,hypothesisId}` |
+| `components.list()` | `{definitions:Array<{name,description?,revision,requirements,provisions}>,components:FabricComponentInfo[]}` |
+| `components.status({id})` | `FabricComponentInfo` with state, requirements, provisions, targetDigest?, error?, cleanupErrors? |
+| `components.graph()` | `{components:FabricComponentInfo[],edges:Array<{from,to,ref}>,cycles:string[][]}` |
+| `components.reload({id?}?)` | `{components:FabricComponentInfo[]}`; rolls back activation failure when cleanup succeeds |
+| `compact.request(args?)` | `{requested:true,intent:{reason?,instructions?,preserve?,requestedBy,requestedAt}}` |
+| `compact.status()` | `{pending?:CompactIntent,last?:{at,requestedBy,status,summary?,tokensBefore?,estimatedTokensAfter?,error?}}` |
+| `compact.cancel()` | `{cancelled:true}` |
+
+`memory.recall` multi-term literal queries default to ranked `queryMatch: "any"` so wording differences do not hide evidence; use `"all"` to require every canonical term in one indexed entry, and `queryMode: "phrase"` when adjacency matters. Results are hard-bounded either way. Structural filters (`ref`, `provider`, `action`, `outcome`) use exact persisted trace fields. Use `tools.catalog()`/`tools.search()` only to choose a current action head—catalog descriptions are navigation metadata and never become session evidence.
+
+Recall returns one bounded flat hit stream. Every hit has the same copy-ready `{ref,args}` field: `await tools.call(hit.follow)` expands an entry or resolves a cold session. Continue any result with `await tools.call(result.next)` when `next !== null`; `total` is the retained pre-page hit count. Do not locate or parse OMP session JSONL yourself: follow calls, integrity bindings, and continuations are the supported retrieval API.
+
+`memory.expand(args)` requires `session` plus a selector: `indices`, `entryIds`, `operationAddresses`, or `entryRange:{first,last}`. Optional `before`/`after` add adjacent entries. It returns normalized records in `entries`, with one uniform `tool` field and OMP `parentId` links. Long entries use lossless `textRange` chunks. For arbitrary filter/map/reduce/join/traversal work, use guest-local `memory.walk(args, async (entry, index) => { ... })`: it follows every expansion page, reassembles complete entries, awaits nested tool calls, and stops early when the visitor returns `false`. `memory.sessions` accepts an optional `limit`.
+
+Stable-provider arguments normalize near-miss spellings the way `omp.*` does: known aliases and casing/singular variants repair to the canonical key, numeric strings coerce for numeric fields, and scope spellings such as `cwd` repair to `project`. Unknown keys are never silently ignored—they fail validation with the offending property path named (e.g. `/befroe: must NOT have additional properties`).
+
+`SessionInfo` is `{id,file,cwd,mtime,entryCount,tier:"hot"|"cold",branches,lineageFingerprint}`. Memory failures are returned in `error: {code,message,...}`; ambiguous-session failures may return only `{error}`. Check `error` before relying on optional success fields.
+
+### Dynamic provider return shapes
+
+- `mcp.<sanitized_server>.<sanitized_tool>(args)` resolves to the server-defined result, commonly `{text:string,content:unknown[],structuredContent:unknown}`; for example `mcp.fal_ai.get_model_schema({ endpoint_id: "openai/gpt-image-2" })`. `<skill-dir>/references/mcp.md` is a branch pointer for MCP naming and management only when the task needs MCP.
+- `extensions.<tool>(args)` in full code mode resolves to `{content:Array<{type,text?,...}>,text:string,details?,isError:boolean,terminate?,source:{path,source,scope,origin,baseDir?}}`.
+- Captured Fovea tools therefore use refs such as `extensions.fovea_focus`. Discover dynamically with `await tools.search({ query: "fovea_focus" })` (the string shorthand `tools.search("fovea_focus")` is also accepted), then pass the returned `action.ref` to `tools.call({ ref, args })`; never invent a bare or `fovea.*` ref.
+
+The guest TypeScript declarations contain the complete argument and return contracts. For a discovered or dynamic action, use `tools.describe({ref})`; inspect `outputSchema` when supplied, otherwise treat the result as `unknown`.
+
+## `tools` — discovery & generic calls
+Refs are namespaced (`omp.grep`, `extensions.<tool>`, `mcp.<server>.<tool>`, `schema.<action>`, `components.<action>`); bare names are rejected. `tools.providers()`→`[{name,description}]` · `tools.catalog({provider?,limit?})`→current provider/action head tree (navigation metadata, not session evidence) · `tools.search({query,limit?})`→`FabricAction[]`(`ref,name,description,inputSchema,risk`) · `tools.describe({ref})`→full `FabricAction` (read `inputSchema` first) · `tools.call({ref,args?})` · `tools.list({provider?,namespace?,query?,limit?})` · `tools.models()`→OMP `[{provider,id,name,key}]`; `agents.models({runner:"claude"})`→Claude Code runtime models with canonical `claude/<value>` keys. Use `tools.call()` for refs discovered or computed at runtime, or names that cannot use property access—not as the default for known actions. Calling a core-tool name on `tools` (e.g. `tools.read(...)`) throws with a hint to use `omp.read(...)`.
+
+## Error recovery: read, describe, retry
+Read the line-numbered error → `await tools.describe({ref})` for the schema → match `inputSchema`, rerun (don't guess). Common mistakes: bare ref (`grep`→`omp.grep`); a non-object second arg on `read`/`bash`/`ls` (`(primary, optionsObject)` already merges on the string-primary tools; positional tuples exist only for `grep`/`find`/`write`/`edit`).
+
+## Orchestration surfaces (opt-in)
+Advanced workflow skills are user-invoked; never load them autonomously. When the user has explicitly invoked an agent or mesh workflow, `<skill-dir>/references/agents.md` and `<skill-dir>/references/mesh.md` are branch pointers for low-level API detail.
+
+`agents.self()` and `agents.members({scope?,kinds?})` expose one leased directory of intrinsic roots, agents, and actors. `agents.main()` and `agents.peers()` are compatibility views of root participants. **Peer is a reserved Fabric term for another root OMP session, not a child agent.** When the user says “peer,” query `agents.peers()` first; do not infer peer state from `agents.list()` or from `agents.members({ kinds: ["agent"] })`. `agents.list()` defaults to local child agents; use `scope: "lineage" | "project"` for federated agent discovery. Cross-process `steer`, `followUp`, and `stop` resolve `ownerHostId` and return only after the owner acknowledges. `agents.subscribe()` creates a durable source-qualified OMP/run lifecycle route; use it instead of model-authored status polling when another participant boundary should notify Main or an agent. Detached `agents.spawn()` already sends Main a terminal follow-up by default unless the caller later waits. Set `residency: "durable"` on `agents.spawn()` or `agents.create()` only when the participant must outlive the current OMP host; Fabric lazily transfers it to the hidden resident host in a trusted mesh-enabled project.
+
+For an explicit implementation handoff, `agents.handoff({ model, task?, when? })` schedules a visible OMP child at the completed outer `fabric_exec` boundary; later calls in the same program still run, and Main blocks only after the finalized native outer result is ready. `when` is a guest-only pure synchronous predicate over immutable earlier successful-call facts from any resolved Fabric provider and is stripped before the host call. `/fabric prewalk [task]` defaults to in-place Main model switching plus a hidden same-session continuation; child trajectory mode is an opt-in setting. See `<skill-dir>/references/agents.md`.
+
+Persistent actors may declare `requires: ["provider.action", { ref: "provider.optional", optional: true }]`. Each run records and verifies a closed-world descriptor commitment; missing required refs fail the activation instead of widening authority.
+
+Agent requests and persistent actors accept `runner: "omp" | "claude"`. OMP is the default and is required for `recursive: true`, `rlm.query()`, and actors that must call Fabric or mesh APIs themselves. Claude invokes the official `claude -p` harness; it supports mapped Claude Code tools and host-managed persistent actors, but not recursive/direct Fabric APIs. Use `agents.models({ runner: "claude" })` for runtime-enumerated `claude/<value>` model keys.
+
+Omit `timeoutMs` for agents and actors unless requesting longer than the configured `agents.timeoutMs` (60 minutes by default). Per-call values below the configured default are ignored.

package/skills/fabric-exec/references/agents.md

@@ -0,0 +1,211 @@
+# Agents and rlm reference
+
+`fabric_exec` can spawn one-shot child agents, create persistent event-driven actors, and run recursive queries. For the sandbox model and `tools` discovery, see the parent `fabric-exec` skill; for actor coordination across sessions, see `mesh.md`.
+
+Every method takes a single options object.
+
+## One-shot child agents
+
+- `agents.run(args)` runs to completion and returns `FabricAgentResult` with `{ id, runner, status, text, value?, error?, usage, turns, toolCalls, runnerSessionId? }`.
+- `agents.spawn(args)` returns a background `FabricAgentHandle` with an `id`. Then use `agents.wait({ id })`, `agents.status({ id })`, `agents.stop({ id })`.
+- `agents.list({ scope? })` returns agent participants. `scope` defaults to `"local"`; use `"lineage"` for every agent under the same root across recursive runtimes, or `"project"` for all live project agents. Local entries retain full run detail; remote entries are bounded participant summaries.
+- `agents.cleanup({ id, deleteBranch? })` returns `{ cleaned }` and removes a worktree branch.
+
+`args` is a `FabricAgentRequest`: `{ task, name?, runner?, transport?, model?, persona?, thinking?, tools?, timeoutMs?, extensions?, recursive?, cwd?, worktree?, schema? }`. `cwd` is a filesystem path only: absolute values are accepted, relative values resolve from the parent manager cwd, and Fabric reports the canonical directory after resolving symlinks. Invalid or non-directory targets fail without falling back. `persona` selects a Veda persona for that invocation and is rejected for OMP/Claude runners.
+
+For OMP leaf agents, selecting `cwd` neither grants nor requires project trust. Fabric adds no trust gate and passes neither `--approve` nor `--no-approve`; OMP loads `AGENTS.override.md`, `AGENTS.md`, and `CLAUDE.md` under its normal rules, while protected project resources follow OMP's saved decisions and `defaultProjectTrust`. Other runners retain their native startup behavior. Generated worktree paths are evaluated at their own canonical paths.
+
+- `runner` is `omp`, `claude`, or `veda` and defaults to `agents.runner` (`omp`). The `veda` runner drives the Veda CLI as a one-shot headless child; `agents.veda.backend` selects Veda’s underlying CLI (`agy`, `codex`, `claude-code`, `droid`, `pi`, or another backend registered by the installed Veda build), while `persona` selects its behavior. An explicit `agents.run({ model })` overrides `agents.veda.model`; if both are omitted, Veda selects its backend default (see `docs/agents.md`).
+- `transport` is one of `auto`, `process`, `tmux`, `screen`, `localterm`, `herdr` (default `process`). `auto` tries Herdr when the parent runs inside a Herdr workspace, then LocalTerm, tmux, screen, and process.
+- OMP `model` values resolve only within the execution owner's visible `tools.models()` / `agents.models({ runner: "omp" })` set; omitted uses `agents.model` or inherits the host model. Explicit values go through the `agents.switchModel` selector resolution: `models.aliases` names, exact matches, then the closest fuzzy match (pi-model-sort recency ties break toward the recently used model). Unresolved values and exhausted aliases fail before launch, and actor defaults or per-activation overrides are revalidated at their actual owner. Catalog-fresh or custom ids must first be visible in that registry. Claude values are `claude/<value>` keys from `agents.models({ runner: "claude" })`; omitted uses `agents.claude.model` or Claude Code's runtime default. Veda model strings continue to pass through to its backend unchanged. `agents.models()` defaults to the configured runner; Claude discovery is a local CLI control handshake and makes no model inference request.
+- `thinking` is the reasoning effort (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`); defaults to `agents.thinking` (`medium`) and is clamped to the model's supported levels (next highest when unsupported).
+- Extension-enabled OMP children inherit the parent’s full-code mode, including non-recursive leaf runs: `fabric_exec` remains the required outer tool and the optional tool allowlist is enforced on nested OMP/captured-tool calls. `extensions: false` opts out, and a parent outside full-code mode keeps the native surface. Recursive runs additionally receive the delegated `agent` risk; ordinary leaf runs do not. Reload Fabric before launching children to pick up a changed launch policy.
+- `tools` defaults to `agents.defaultTools`. Claude maps `read→Read`, `grep→Grep`, `find/ls→Glob`, `bash→Bash`, `edit→Edit`, and `write→Write`; other tool names fail before launch.
+- `schema` is a JSON Schema; the worker returns validated structured data in `result.value`.
+- `cwd` changes only a leaf child's execution directory. Workflow helpers and `council.run()` forward it; recursive `rlm.query()` deliberately does not accept it. Persistent actor definitions and trajectory handoff also do not accept it. A request combining `cwd` with `recursive: true` is rejected before launch.
+- `worktree: true` creates a dedicated Git worktree on branch `omp-fabric/<name>-<id>` from the repository containing the selected `cwd`, retained until `agents.cleanup()`. Fabric writes it at `<repo>/.omp/fabric/worktrees/<id>` (agent id, not the target repo name) and clone-first copy-on-write keeps ignored build artifacts when the filesystem supports it. A selected repository subdirectory is preserved in the generated worktree when available. The effective cwd is the generated canonical path. Project and mesh ownership remain those of the caller.
+- Worktree path gotcha: the directory name is the agent id, not the target repo. Repo identity lives in the registered worktree list and branch tip. Never instruct an agent to verify its location by directory-name pattern; verify by repo (`git rev-parse --show-toplevel` + `git log -1 --format=%H` against the expected base, or `git remote get-url origin`).
+- Preferred pattern for parallel implementers (deterministic, full branch control): pre-create the worktrees yourself in the target repo (`git worktree add -b <branch> <path> <base>`), pass each canonical path as `cwd`, leave `worktree` unset, and state the exact expected top-level in the task. Canonical-path gotcha on macOS: `git rev-parse --show-toplevel` reports `/private/tmp/...` for worktrees created under `/tmp/...` — assign and verify the canonical `/private` form or the agent's guard will correctly refuse.
+- Give every autonomous coding agent a mandatory first command that verifies repo identity (exact canonical toplevel or remote URL) and a hard rule to abort with zero changes on mismatch. Guards cost one cheap round when wrong and prevent cross-repo contamination when right — four successive guards caught a wrong-repo worktree, a self-inflicted symlink mismatch, and a too-literal directory check at zero bytes of damage.
+- Cleanup after cancelled/failed agent runs: check `agents.list({ scope: "project" })` and `agents.stop` any still-running handles first; worktree registrations live in the repo that OWNS the worktree (check `git worktree list` in every candidate repo; `.omp/fabric/worktrees/<id>` names the agent, not the repo), then `git worktree remove --force` + `git branch -D` + `git worktree prune` in each. Leave pre-existing non-agent worktrees alone; filter by the branch prefix your runs created (e.g. `omp-fabric/<name>`).
+- `residency` is available on `agents.spawn` only: `"session"` (default) ties the run to the current OMP host; `"durable"` launches it on Fabric's hidden resident host so it can finish after Main exits. Durable handles still support `status`, `wait`, `log`, `stop`, and `cleanup` when the same root resumes. It requires a trusted project mesh and is unavailable in Schema enforce mode.
+- Omit `timeoutMs` normally. It defaults to `agents.timeoutMs` (60 minutes by default), and per-call values below that configured default are ignored. Set it only to request a longer run.
+
+```ts
+const result = await agents.run({
+  name: "security-review",
+  task: "Review the current diff for concrete security defects. Do not edit files.",
+  tools: ["read", "grep", "find", "ls"],
+});
+return result;
+```
+
+```ts
+const handle = await agents.spawn({ task: "Map the persistence layer.", transport: "tmux" });
+// independent work here
+return await agents.wait({ id: handle.id });
+```
+
+Detached `agents.spawn()` runs already notify Main on terminal completion when `agents.notifyOnComplete` is enabled (the default). The notification is a triggered follow-up. Use `agents.wait()` when the current Fabric program needs the result, `agents.status()` only for a point-in-time progress inspection, and lifecycle subscriptions when another participant's OMP boundary matters. Calling `wait()` makes that run foreground work and suppresses the detached completion notification.
+
+## Participant lifecycle subscriptions
+
+Lifecycle subscriptions are durable, source-qualified mesh routes. They let Main, an actor, or an active agent react to another root/agent/actor without model-authored polling.
+
+- `agents.subscribe({ from, events, to?, delivery, triggerTurn, once? })` creates a subscription. `from` is an exact participant id; `"main"` means the caller's lineage root. `to` defaults to that Main id.
+- `agents.subscriptions({ from?, to? })` lists project subscriptions.
+- `agents.unsubscribe({ id })` removes one.
+- `delivery` is `steer` or `followUp`. State `triggerTurn: true | false` explicitly; it controls whether delivery to an idle Main starts a turn.
+- `once: true` removes the subscription after its first successful matching delivery. Omitted keeps it active.
+- Creation starts at the current mesh sequence, so old lifecycle events are not replayed. Delivery cursors persist across owner restarts. Delivery is at-least-once across a crash between message insertion and cursor persistence; use the lifecycle event `id` to deduplicate side effects.
+
+Exact OMP events are `omp.input`, `omp.agent_start`, `omp.agent_end`, `omp.turn_end`, `omp.tool_error`, and `omp.session_compact`. Runner-neutral terminal events are `run.completed`, `run.failed`, `run.stopped`, and `run.timed_out`. OMP events are observed from OMP's host/RPC lifecycle; run events also cover Claude-backed children and actor activations. Envelopes contain bounded operational metadata, source identity, timestamps, and a run id when applicable, never a transcript snapshot.
+
+`omp.agent_end` means OMP has no automatic retry, compaction retry, or queued continuation left at that boundary. It does not mean a persistent root or actor can never receive future work. Use a `run.*` event when terminal process/run status is what matters.
+
+```ts
+const peer = (await agents.peers())[0];
+if (!peer) return { subscribed: false };
+return agents.subscribe({
+  from: peer.id,
+  events: ["omp.agent_end"],
+  to: "main",
+  delivery: "followUp",
+  triggerTurn: true,
+  once: true,
+});
+```
+
+## Trajectory handoff
+
+`agents.handoff({ model, task?, when?, ... })` schedules a blocking OMP-to-OMP trajectory handoff at the end of the current outer `fabric_exec`. Inside the guest it returns a deferred marker immediately, so calls after it still run. Once the complete program and all outer result middleware finish, Fabric forks the native assistant `fabric_exec` call plus its exact native `toolResult`, starts the explicit `provider/id` target in the same workspace, and waits before Main can infer again. Do not expect child output inside the same guest program; Main receives it as the final outer tool result.
+
+`when` is guest-only and must be a pure synchronous predicate over immutable successful-call facts. It is deleted before the host validates the request:
+
+```ts
+await omp.edit({ path: "src/guard.ts", edits: [{ oldText, newText }] });
+await agents.handoff({
+  model: "anthropic/claude-haiku-4-5",
+  task: "Continue from this completed Fabric invocation.",
+  when: ({ count }) => count("omp.edit") >= 1,
+});
+await omp.bash({ command: "bun test guard" });
+return "Frontier invocation complete";
+```
+
+Facts include every successful resolved bridge call completed before `agents.handoff()`, from `omp.*`, `extensions.*`, `mcp.*`, external providers, and generic `tools.call()`. Use `count()` for all calls, `count(ref)` for one, or `count([ref, ...])` for a set. Computed calls are recorded under their target ref rather than `fabric.$call`; failed calls do not count. A false or asynchronous predicate starts no child and errors clearly. Omit `when` for unconditional scheduling.
+
+The guest result is `{ scheduled: true, status: "deferred", boundary: "fabric_exec_end" }`; the final outer tool result is `{ handedOff, completed, status, agent, implementation, error? }`. `model` is required and handoff is always OMP-backed. It also accepts `name`, `transport`, `thinking`, `tools`, `timeoutMs`, `extensions`, `recursive`, and `schema`; it deliberately omits `worktree` so implementation remains in the caller's workspace. Do not run handoff in a parallel branch that keeps mutating the same files.
+
+## Automatic prewalk
+
+`/fabric prewalk [task]` arms one automatic continuation when a Fabric invocation contains a successful `omp.edit`, `omp.write`, or `schema.commit`. With a task it submits immediately; without one it captures the next user input. The executor comes from `prewalk.model` or an interactive choice, and its reasoning effort from `prewalk.thinking` (inheriting `agents.thinking` when unset). `prewalk.alwaysRearm` keeps the controller armed until `/fabric prewalk --off`. That command cancels only the session arm; `/fabric prewalk --disable` persists the master switch and survives restarts, while `--enable` restores it.
+
+The default `prewalk.mode: "in-place"` switches Main to the executor model at the finalized outer boundary and queues one hidden follow-up to continue the existing task. It does not spawn or wait for a child. The outer tool terminates the old-model automatic turn, then OMP drains the queued continuation on the newly selected model. This mode requires full code mode but not enabled agents; OMP's public model switch also updates its persisted default model.
+
+Set `prewalk.mode: "trajectory"` to fork the finalized call/result into an OMP child and wait. A hidden follow-up then has Main verify the child's work and summarize, so it never settles idle by design. The parent activity card shows the handoff call, child, progress/current tool, nested tools, metrics, and result. Trajectory mode requires enabled agents. Both modes let all nested calls settle before the boundary, disarm a triggerless completed task, defer to explicit `agents.handoff()`, and are disabled by Schema enforce mode. Use `/fabric prewalk --status` or `/fabric prewalk --off`.
+
+Use `/fabric agents` to list children and `/fabric attach <id>` for the attach command. Abort signals propagate to the transport and selected child process. Claude runs use official `claude -p` stream JSON with `dontAsk`, `--tools`, and `--allowedTools`; `extensions: false` adds Claude safe mode. One-shot Claude sessions use `--no-session-persistence`. Claude cannot use `recursive: true`, `fabric_exec`, or direct mesh APIs.
+
+## Unified participants and steering
+
+Every live root, one-shot/recursive agent, and persistent actor is represented in one project participant directory. Participant kinds are intrinsic (`"root"`, `"agent"`, or `"actor"`); **Main** and **Peer** are UI/API views of root participants, not separate identity classes. **Peer is a reserved Fabric term for another root OMP session.** A request to inspect, wait for, or coordinate with a “peer” means call `agents.peers()` first; `agents.list()` lists child agents and cannot establish whether a peer root has settled. Execution remains local to an `ownerHostId` and authenticated `ownerIdentityId`, while `rootId` and optional `parentId` describe lineage. Host leases remove a crashed host and all participants it owns from live discovery together. Shared records deliberately omit agent prompts, results, and errors; full detail stays local.
+
+- `agents.self()` returns the caller's `FabricParticipantInfo`.
+- `agents.members({ scope?, kinds?, includeStale? })` returns the unified directory. `scope` is `"local"`, `"lineage"`, or `"project"` (default); `kinds` filters intrinsic kinds. Normal discovery excludes stale hosts.
+- `agents.sessions()` returns every live root OMP session, including the caller's root and peers, as symmetric `FabricParticipantInfo` records. This is the primitive for session-to-session awaiting and DAG coordination.
+- `agents.main()` remains the compatibility view of the caller's root as `{ id, name: "Main", kind: "main", ... }`; the stable alias `"main"` resolves to that exact root id.
+- `agents.switchModel({ model, provider? })` switches Main's live OMP session model in place and keeps it. The selector resolves a `models.aliases` name (string target or first-available fallback chain), then an exact `provider/id`, an exact bare id, then the closest fuzzy match across provider, id, and display name (pi-model-sort recency breaks ties); unknown selectors throw instead of switching. The result carries `{ switched, model, previous?, via? }`, where `via` is the alias name or `closest`/`recent`/`latest`, or `{ switched: false, reason: "already-active" }` for the active model. List candidates with `tools.models()` (OMP runner entries).
+- `agents.peers()` remains the compatibility view of other live roots as `Peer <session-prefix>`. It is derived from `agents.members`, not maintained by a second registry.
+- `agents.status({ id })` accepts any known participant id. Local runs/actors return full local detail; remote participants return their bounded directory summary.
+- `agents.steer({ id, message, data? })` and `agents.followUp(...)` target Main, a live one-shot child, or an actor without discarding context.
+- `agents.stop({ id })` can stop a local or remotely owned agent/actor when its participant advertises `"stop"`. It returns the local agent result, local actor info, or an acknowledged remote control result according to the target.
+- `agents.setSteeringMode({ id, mode })` / `agents.setFollowUpMode({ id, mode })` remain local one-shot controls.
+
+Local delivery returns `routed: "main" | "local"`. Cross-process delivery resolves the participant's exact owner host and identity, publishes an owner-addressed control command, and accepts only a version/target/identity-matched acknowledgement. Success returns `{ queued, messageId, routed: "mesh", acknowledged: true }`; an unknown id, stale owner, owner rejection, or acknowledgement timeout throws instead of reporting an unverified queue. This path requires `mesh.enabled`. Ordinary non-recursive OMP children can receive host-routed messages and use Fabric in inherited full-code mode, but do not receive recursive runs’ delegated `agent` risk. Claude children/actors remain host-routed and do not run Fabric themselves.
+
+```ts
+const main = await agents.main();
+const project = await agents.members({ scope: "project" });
+const peerRoot = project.find((participant) => participant.kind === "root" && participant.id !== main.id);
+if (peerRoot) await agents.steer({ id: peerRoot.id, message: "Coordinate on the shared migration." });
+await agents.followUp({ id: main.id, message: "After the audit, reconcile the worker findings." });
+const handle = await agents.spawn({ task: "Audit auth flows.", tools: ["read", "grep", "find", "ls"] });
+// Watch progress, then redirect between turns without losing the child's context.
+const s = await agents.status({ id: handle.id });
+if (s.text.includes("rotating refresh tokens")) {
+  await agents.steer({ id: handle.id, message: "Skip refresh-token rotation; focus on session expiry only." });
+  await agents.setSteeringMode({ id: handle.id, mode: "all" });
+}
+return await agents.wait({ id: handle.id });
+```
+
+Prefer `agents.steer` over `agents.stop` + `agents.spawn` when the child has useful context you would otherwise discard. Use `agents.stop` only when the child is genuinely off-track and a fresh task is cheaper than a redirect. Steering a finished agent throws; check `agents.status` or the participant capabilities first. When the user asks Main to correct a running child, use `agents.steer` directly; do not require the user to open a dashboard. The user can also press Ctrl+Shift+A or run `/fabric chat <id-or-name>` to open a focused conversation with direct steering, follow-ups, and parent/child navigation while Main keeps running. Completed one-shot runs are read-only; actors remain messageable through their mailbox. In the dashboard, `s`, `u`, and `x` use the same ownership-aware path for local and remote participants, and Shift+C opens their focused conversation.
+
+## Persistent actors
+
+`agents.create(args)` returns `FabricActorInfo`. An actor has a fixed `runner`, a serial mailbox, and optional subscriptions to parent events or durable mesh topics. It processes messages one at a time, coalesces repeated host events by default, and restores with the project actor registry. OMP actors resume their Fabric-owned OMP session file. Claude actors persist the session ID emitted by `claude -p` and launch later activations with `--resume <id>` while keeping a Fabric-owned stream transcript.
+
+`args` is a `FabricActorRequest`. `delivery` defaults to `mailbox`. `steer` and `followUp` require `triggerTurn: true | false`; `mailbox` and `nextTurn` reject `triggerTurn: true`.
+
+With project actor scope, all trusted sessions read one definition, mailbox, and history. Each OMP session has its own model and thinking binding. One authenticated owner runs the actor and processes host events once. Fabric stores the resolved values on each mailbox item before it queues:
+
+```text
+call override → session binding → project default → Fabric or runner default
+```
+
+- `runner` is fixed at creation. Omitted uses `agents.runner`. OMP actors are recursively Fabric-equipped; Claude actors retain Claude context and use Claude Code tools, while mailbox/event delivery and coordination remain host-managed (no `fabric_exec` or direct `mesh.*` inside Claude).
+- `residency` is `session` by default. Set `residency: "durable"` to transfer execution to Fabric's hidden resident host. Project sessions can still call `ask`, `tell`, `steer`, `followUp`, and `stop`, and can read the shared definition, mailbox, and logs. Shared runtime settings stay owner-only. Fabric routes durable actor removal to the resident owner. Durable residency requires a trusted project mesh and is unavailable in Schema enforce mode.
+- `model` follows the selected runner's key format. At creation it is the project default. `agents.setModel({ id, model? })` changes this session binding by default; add `scope: "project"` for an owner-gated shared pin. `ask`/`tell` also accept `model` for one activation.
+- `thinking` accepts `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`. It uses the same call/session/project layering as `model`, then inherits `agents.thinking` (default `medium`). Use `agents.setThinking({ id, thinking?, scope? })`; omitting the value clears the selected layer.
+- `events` accepts the supported OMP extension events: `resources_discover`, `session_start`, `session_before_switch`, `session_switch`, `session_before_branch`, `session_branch`, `session_before_compact`, `session.compacting`, `session_compact`, `session_shutdown`, `session_before_tree`, `session_tree`, `goal_updated`, `input`, `before_agent_start`, `agent_start`, `agent_end`, `session_stop`, `turn_start`, `turn_end`, `message_start`, `message_update`, `message_end`, `context`, `before_provider_request`, `after_provider_response`, `tool_execution_start`, `tool_call`, `tool_execution_update`, `tool_result`, `tool_execution_end`, and `user_bash`. Fabric also provides synthetic `tool_error`. `project_trust` is unavailable.
+- Host events automatically forward every OMP `ImageContent` block to the actor's selected model. The JSON envelope and persisted mailbox contain only redacted indexed descriptors; raw base64 travels through the transient worker prompt and may then follow the selected runner's ordinary persistent-session semantics. No media flag is required. Credential-shaped fields and unrelated encoded blobs are redacted before persistence.
+- `topics` lists durable mesh topics to subscribe to (see `mesh.md`).
+- `responseMode` is `text` (every non-empty response becomes an outbox message) or `directive` (validated `{ action, message?, data? }` where `action` is `silent`, `message`, or `stop`; the actor decides whether to intervene).
+- `delivery` is `mailbox`, `steer`, `followUp`, or `nextTurn`. An actor cannot escalate it in a response; the owner can replace it with `agents.setDeliveryPolicy({ id, delivery, triggerTurn, scope? })`.
+- `triggerTurn` is mandatory for `steer`/`followUp`: `true` starts Main when idle; `false` is passive and the delivered message visibly says it will not start Main. `mailbox`/`nextTurn` never start Main. `coalesce` is on by default.
+- `validWhile` is an optional pure synchronous predicate checked before an activation runs and again before its result is delivered. It receives immutable `{ activation, current }` facts. Return `false` or `{ valid: false, reason? }` to record the activation as stale and suppress delivery; an invalidated blocking `agents.ask()` rejects. The predicate source persists with project actors and global templates, so it cannot use closures, tools, promises, or host APIs.
+- `timeoutMs` follows the same floor as one-shot agents: omit it normally and set it only above `agents.timeoutMs` when an activation needs longer.
+- `tools` is the actor's persisted allowlist and defaults to `agents.defaultTools`. Replace it for future activations with `agents.setTools({ id, tools })`; an empty list disables optional tools. OMP actors retain the host-required `fabric_exec` tool unless created with `extensions: false`. Use `scope: "global"` to update a reusable template instead.
+- `extensions` is `true` by default (an OMP actor is recursively Fabric-equipped with the host-required `fabric_exec` tool). Set `extensions: false` to disable Fabric for an OMP actor: the activation runs with `extensions: false` and `recursive: false`, so `fabric_exec` is not injected and the actor cannot call `agents.*` or `mesh.*`; the host still manages its mailbox and delivery (same coordination model as a Claude actor). This does not restrict ordinary tools: also use `tools: ["read", "grep", "find", "ls"]` for a read-only actor or `tools: []` for no tools. Fixed at creation.
+
+```ts
+return agents.create({
+  name: "auth-supervisor",
+  instructions: "Watch the main session until the auth migration is complete and tested. Prefer silence; reply with a directive only for material drift, a blocker, or verified completion.",
+  events: ["agent_end", "tool_error"],
+  validWhile: ({ activation, current }) => {
+    if (activation.kind !== "hostEvent") return true;
+    if (activation.sequence !== current.latestActivationSequence) return false;
+    return activation.event !== "tool_error" || activation.mainRevision === current.mainRevision;
+  },
+  responseMode: "directive",
+  delivery: "steer",
+  triggerTurn: true,
+  tools: ["read", "grep", "find", "ls"],
+});
+```
+
+For a native asynchronous vision handoff, create one actor with an explicit multimodal `model`, `events: ["input"]`, `responseMode: "directive"`, passive `delivery: "steer"`, `triggerTurn: false`, `coalesce: false`, `validWhile: ({ activation }) => activation.kind !== "hostEvent" || (activation.signal?.media?.length ?? 0) > 0`, `tools: []`, and usually `extensions: false`. Instruct it to return `silent` when no image is attached and otherwise return only a compact visual description for Main. Fabric attaches prompt images automatically; do not add base64 to the task or mailbox data. The actor does not block Main's current inference.
+
+Mailbox:
+
+- `agents.ask({ id, message, data?, model?, thinking? })` waits for a `FabricActorMessage` from the live owner. Its deadline follows the actor timeout. Caller cancellation aborts work on that owner. Large text and structured data share the mesh event budget; truncated data carries `fabricTruncated: true`.
+- `agents.tell({ id, message, data?, model?, thinking? })` returns `{ queued, messageId }`. Optional binding values affect only that mailbox item.
+- `agents.actorStatus({ id })` and `agents.actors()` return the shared project actor view. `model`/`thinking` are effective for this caller; `binding` and `projectDefaults` expose the two persisted layers.
+- `agents.setModel({ id, model?, scope? })` and `agents.setThinking({ id, thinking?, scope? })` default to `scope: "session"`. Use `scope: "project"` only to pin a shared default.
+- `agents.setTools({ id, tools, scope? })` replaces the persisted tool allowlist for a project actor (default) or global template.
+- `agents.setDeliveryPolicy({ id, delivery, triggerTurn, scope? })` replaces the explicit project/global continuation policy without recreating the actor. In the dashboard, press `y` on an actor/template for the same control.
+- `agents.messages({ id, limit? })` returns the actor mailbox history. Create the actor with `scope: "session"` when its history must be private to one root OMP session.
+- `agents.remove({ id })` returns `{ removed }`. Session actors require the local owner. Durable actor removal routes to the resident owner.
+- `agents.log({ id, type?, lines?, runId? })` reads the shared actor log or a locally owned one-shot run. `type` is `session` (the actor's `session.jsonl` transcript — every user/assistant turn and tool call), `run` (the last retained run's `events.jsonl` event stream), or `all` (both; default `session` for actors). Actors retain their last `MAX_RETAINED_RUNS` runs so logs survive after success. Returns `{ actorId, actorName, sessionFile, logDir, session, run?, retainedRuns }` (actors) or `{ id, runDirectory, logFile, status?, events }` (one-shot runs). Use this to inspect what an "offending" actor actually sent to its model. From the TUI: `/fabric log <id>` previews, `/fabric export-log <id> [path]` writes the raw `session.jsonl` + retained `runs/` to disk.
+
+## Recursive queries
+
+`rlm.query(args)` is a budget-aware `agents.run({ ...args, runner: "omp", recursive: true })` with Fabric enabled in the child. Claude runners are deliberately rejected for recursion. Its usage counts toward `budget.spent()` and the `tokenBudget` guard. Recursion is rejected at `agents.maxDepth`; the setting accepts any non-negative safe integer, and `0` disables child spawning. Approving the initial recursive call delegates only the `agent` risk capability to recursive children; network, execution, and write approvals are not inherited. Each Fabric process enforces its own concurrency and timeout limits.
+
+```ts
+return rlm.query({ task: "Decompose this repository and produce a compact architecture map.", transport: "process" });
+```
+
+`council.run({ task, roles, synthesize?, ...agentOptions })` runs several `agents.run` calls concurrently under the agent semaphore and optionally synthesizes them. The full council pattern is user-invoked; never load `/skill:fabric-council` autonomously.

package/skills/fabric-exec/references/mcp.md

@@ -0,0 +1,49 @@
+# MCP surface reference
+
+MCP tools are available inside `fabric_exec` through the `mcp` surface, backed by the public `mcporter` runtime (config discovery, imports, OAuth cache, connection pooling). For the sandbox model and `tools` discovery, see the parent `fabric-exec` skill.
+
+## Call a tool
+
+`mcp.<sanitized_server>.<sanitized_tool>(args)` takes one options object matching the tool input schema. JavaScript-safe names work unchanged; other names replace non-identifier characters with `_` (and gain a leading `_` when needed). Fabric resolves those aliases back to the names mcporter loaded.
+
+```ts
+const result = await mcp.context7.resolve_library_id({ libraryName: "react", query: "hooks" });
+const imageSchema = await mcp.fal_ai.get_model_schema({ endpoint_id: "openai/gpt-image-2" });
+return { result, imageSchema };
+```
+
+The second call resolves MCP server `fal-ai` and tool `get-model-schema`.
+
+## Server management
+
+- `mcp.servers()` returns server metadata `{ name, description, transport }` (description may be null; transport is "http" or "stdio"). Credentials are never exposed.
+- `mcp.reload()` returns `{ servers }`. Call it after changing mcporter configuration.
+- `mcp.register({ name, description?, command?, args?, cwd?, baseUrl?, headers?, env?, overwrite? })` returns `{ registered }`. Register an ephemeral server in the pooled runtime after host approval. HTTP servers use `baseUrl` instead of `command`. Dynamic definitions live until `mcp.reload()` or session shutdown; they are not written to config.
+
+```ts
+await mcp.register({ name: "project-docs", command: "npx", args: ["-y", "@example/docs-mcp"], cwd: "." });
+return mcp.project_docs.search({ query: "authentication" });
+```
+
+## Generic call
+
+`mcp.call({ server, tool, args? })` is for exact names that cannot be expressed unambiguously as property access, or for names computed at runtime.
+
+```ts
+return mcp.call({ server: "my-server", tool: "weird-tool-name", args: { q: "x" } });
+```
+
+## Introspect an uncertain tool
+
+MCP tools are discoverable through the generic `tools` surface; refs are `mcp.<server>.<tool>`.
+
+```ts
+const schema = await tools.describe({ ref: "mcp.context7.resolve_library_id" });
+// schema.inputSchema is the tool JSON Schema
+```
+
+## Notes
+
+- When `mcp.disableOAuth` is configured, calls may use cached credentials but cannot launch a new interactive OAuth flow.
+- Call timeout is bounded by `mcp.callTimeoutMs`.
+- Set `mcp.enabled: false` to disable the MCP surface.

package/skills/fabric-exec/references/mesh.md

@@ -0,0 +1,51 @@
+# Durable coordination reference
+
+`mesh` is a project-scoped, event-sourced coordination substrate. With persistent actors (see `agents.md`) it is sufficient to express messenger-style swarms without a daemon or fixed planner/worker roles. For the sandbox model, see the parent `fabric-exec` skill.
+
+Every method takes a single options object. Mesh data defaults to `<project>/.omp/fabric/mesh`; relocate it with `mesh.root` in config, and add `.omp/fabric/mesh/` to your ignore file unless you intentionally version the coordination log.
+
+## Identity and presence
+
+- `mesh.self()` returns the caller's wire identity `{ id, name, kind, sessionId? }`, where the legacy wire `kind` is `main`, `actor`, or `agent`.
+- `mesh.members({ scope?, kinds?, includeStale?, limit? })` returns the same `FabricParticipantInfo[]` as `agents.members`: intrinsic roots, agents, and actors with `rootId`, optional `parentId`, `ownerHostId`, status, capabilities, and `local`/`stale` flags. `scope` defaults to `"project"`.
+- `agents.self()` is the richer intrinsic identity (`kind: "root" | "agent" | "actor"`). `agents.main()` and `agents.peers()` are compatibility views derived from root participants.
+
+The directory stores participant records separately from short-lived execution-host leases. If a host crashes, all records owned by that host become stale atomically from the reader's perspective. Normal discovery excludes them; `includeStale: true` is diagnostic.
+
+## Topics (durable channels)
+
+- `mesh.publish({ topic, kind?, to?, text?, data? })` returns a `FabricMeshEvent`. Use `to` for a direct message.
+- `mesh.read({ after?, topic?, to?, limit? })` returns `FabricMeshEvent[]` by cursor, topic, or recipient. Each event has `{ id, sequence, topic, kind, from, to?, text?, data?, createdAt }`.
+
+Topics provide durable channel and direct-message semantics with sequence cursors.
+
+```ts
+await mesh.publish({ topic: "team.auth", kind: "finding", text: "Refresh-token rotation is not atomic", data: { path: "src/auth/refresh.ts" } });
+const events = await mesh.read({ topic: "team.auth", limit: 50 });
+```
+
+## Shared state (compare-and-swap)
+
+- `mesh.get({ key })` returns a `FabricMeshStateEntry` or null.
+- `mesh.put({ key, value, ifVersion? })` creates or updates; `ifVersion` enables optimistic compare-and-swap.
+- `mesh.delete({ key, ifVersion? })` returns `{ deleted, version? }`.
+- `mesh.list({ prefix?, limit? })` returns matching entries.
+
+Each entry is `{ key, value, version, updatedAt, updatedBy }`. Use `ifVersion` for task claims, leases, reservations, and decisions: create with `ifVersion: 0`, claim by passing the current `version`. Keys below `topology/`, `sessions/`, and `actors/` are host-reserved and reject guest `put`/`delete`; use an application prefix such as `tasks/` or `team/`.
+
+```ts
+const task = await mesh.put({ key: "tasks/auth-review", value: { status: "ready", owner: null }, ifVersion: 0 });
+const claimed = await mesh.put({ key: task.key, value: { status: "claimed", owner: "security-reviewer" }, ifVersion: task.version });
+return claimed;
+```
+
+## Steering across processes
+
+Use `agents.steer`, `agents.followUp`, or `agents.stop` rather than publishing a control topic yourself. Fabric resolves the target in the participant directory, addresses `fabric.control.command` to its `ownerHostId`, and waits for a version/target/owner-identity-matched `fabric.control.ack`. Unknown targets, stale owners, rejection, and acknowledgement timeout fail explicitly. The stable `"main"` alias is resolved locally to the caller's exact root id before routing.
+
+The entire `fabric.control.*` namespace is reserved for internal protocol topics, not application channels. `fabric.participant.lifecycle` is also host-reserved so guest publication cannot spoof source-qualified lifecycle events. `fabric.steer` remains a mixed-version compatibility path for older Fabric participants; direct publication on it has legacy best-effort semantics and no acknowledgement.
+
+## Notes
+
+- Actors subscribe to topics via `agents.create({ topics: [...] })` (see `agents.md`); published events are delivered as `mesh:<topic>` messages.
+- Set `mesh.enabled: false` in config to disable both mesh actions and ambient actor restoration.