pi-fabric 0.22.0 → 0.22.2

package/skills/fabric-ambient/references/setup.md

@@ -0,0 +1,71 @@
+# Ambient actor setup
+
+Pass `strings.name`, `strings.instructions`, JSON `strings.events`, `strings.triggerTurn` (`"true"`/`"false"`), and `strings.model` (key/substring; empty when unset).
+
+```ts
+const events = JSON.parse(π.events) as FabricActorHostEvent[];
+const triggerTurn = π.triggerTurn === "true";
+let model: string | undefined;
+let runner: FabricAgentRunner | undefined;
+if (π.model) {
+  const models: Array<FabricModelInfo & { runner: FabricAgentRunner }> = (
+    await tools.models()
+  ).map((entry) => ({ ...entry, runner: "pi" as const }));
+  try {
+    models.push(...(await agents.models({ runner: "claude" })).map((entry) => ({
+      ...entry,
+      runner: "claude" as const,
+    })));
+  } catch {}
+  const needle = π.model.toLowerCase();
+  const selected = models.find((entry) =>
+    entry.key.toLowerCase() === needle ||
+    entry.id.toLowerCase().includes(needle) ||
+    entry.name.toLowerCase().includes(needle)
+  );
+  if (!selected) throw new Error(`Model "${π.model}" not found: ${models.map((entry) => entry.key).join(", ")}`);
+  model = selected.key;
+  runner = selected.runner;
+}
+
+const existing = (await agents.actors()).find(
+  (actor) => actor.name === π.name && actor.status !== "stopped",
+);
+if (existing) {
+  await agents.setInstructions({ id: existing.id, instructions: π.instructions });
+  if (existing.events.length !== events.length || events.some((event) => !existing.events.includes(event))) {
+    await agents.setEvents({ id: existing.id, events });
+  }
+  if (existing.delivery !== "steer" || existing.triggerTurn !== triggerTurn) {
+    await agents.setDeliveryPolicy({ id: existing.id, delivery: "steer", triggerTurn });
+  }
+  const runnerMatches = !runner || existing.runner === runner;
+  const modelMatches = !model || existing.model === model;
+  return {
+    reused: true,
+    actor: await agents.actorStatus({ id: existing.id }),
+    warnings: [
+      ...(existing.responseMode !== "directive" ? ["recreate for responseMode=directive"] : []),
+      ...(existing.coalesce !== true ? ["recreate for coalesce=true"] : []),
+      ...(!runnerMatches ? [`runner "${runner}" requires recreation`] : []),
+      ...(runnerMatches && !modelMatches ? [`model "${model}" requires a dashboard change or recreation`] : []),
+    ],
+  };
+}
+
+const actor = await agents.create({
+  name: π.name,
+  instructions: π.instructions,
+  events,
+  responseMode: "directive",
+  delivery: "steer",
+  triggerTurn,
+  coalesce: true,
+  tools: ["read", "grep", "find", "ls"],
+  ...(runner ? { runner } : {}),
+  ...(model ? { model } : {}),
+});
+return { started: true, actor };
+```
+
+Reuse updates instructions/events/delivery. Recreate for runner, `responseMode`, or `coalesce`; use dashboard/recreation for model. Report ID/warnings and messages/stop; do not wait.

package/skills/fabric-council/SKILL.md

@@ -1,14 +1,12 @@
 ---
 name: fabric-council
-description: Runs a bounded multi-perspective Pi Fabric council with independent reviewers and an optional synthesis decision. Use for architecture choices, plans, reviews, and adversarial cross-checking.
+description: Runs a bounded multi-perspective Pi Fabric council with independent reviewers and optional synthesis. Use for architecture choices, plans, reviews, and adversarial cross-checking.
 disable-model-invocation: true
 ---
 
 # Fabric Council
 
-Use one `fabric_exec` call and `council.run()`. Choose roles that disagree usefully rather than duplicating one another.
-
-A council runs N role agents concurrently plus a sequential synthesizer, all inside the single `fabric_exec` sandbox. The sandbox has a hard wall-clock ceiling (`executor.timeoutMs`, default 120s; raise it in `fabric.json` or `/fabric` settings for read-heavy councils). Keep roles and per-role tool work bounded so `max(role durations) + synthesizer` fits the ceiling, or the sandbox times out and aborts every in-flight agent. Council and `rlm.query` usage counts toward `budget.spent()` and the `tokenBudget` guard.
+Use one `fabric_exec` call and `council.run()`. Choose three to five roles that disagree usefully rather than duplicating one another, such as correctness, security, operability, maintainability, and requirements skepticism.
 
 ```ts
 const roles = JSON.parse(π.roles) as string[];
@@ -17,25 +15,14 @@ await workflow.configure({
   description: `${roles.length} independent perspectives with synthesis`,
 });
 await phase("Deliberate", { total: roles.length });
-const decision = await council.run({
+return council.run({
   task: π.task,
   roles,
   tools: ["read", "grep", "find", "ls"],
   synthesize: true,
 });
-return decision;
 ```
 
-Pass the full task and role array through `strings`. Usually use three to five roles. Examples:
-
-- implementation correctness reviewer
-- security and abuse-case reviewer
-- test and operability reviewer
-- simplicity and maintenance reviewer
-- user-requirements skeptic
-
-Council members must inspect evidence independently. The synthesizer must preserve material disagreement, reject unsupported claims, and make a concrete recommendation. Use `synthesize: false` only when the user asked for raw independent opinions.
-
-Do not use a council for a simple lookup or a decision with no meaningful competing considerations.
+Pass the task as `strings.task` and the JSON role array as `strings.roles`. Members inspect evidence independently; synthesis must preserve material disagreement, reject unsupported claims, and make a concrete recommendation. Use `synthesize: false` only for raw opinions.
 
-For a long-running deliberation where a member drifts, you can run members with `agents.spawn` and redirect one between its turns via `agents.steer({ id, message })` instead of `council.run`'s blocking fan-out; `agents.status({ id }).pendingMessages` shows the queued steers. See the `agents` reference.
+A council costs N concurrent role agents plus one sequential synthesizer and must fit `executor.timeoutMs`; its usage counts toward the execution budget. Keep roles bounded and set top-level `agentBudget`/`tokenBudget` for large runs. Do not use a council for a simple lookup or a decision with no meaningful competing considerations.

package/skills/fabric-exec/SKILL.md

@@ -1,13 +1,10 @@
 ---
 name: fabric-exec
 description: >-
-  Reference for writing `fabric_exec` TypeScript programs in the isolated
-  QuickJS runtime (or the trusted unsafe Node-process escape hatch): the mental model (one program, return only the final value), the
-  core `pi` tools (read/bash/edit/write/grep/find/ls) with exact signatures,
-  `tools` discovery, `π` named strings, first-class Fabric provider and MCP
-  proxies, and the validate, describe, retry error loop. Load before your first
-  `fabric_exec` call and whenever a call errors on argument shape. See
-  `references/mcp.md` for MCP naming and management.
+  Reference for `fabric_exec` TypeScript programs: Pi core tool signatures,
+  discovery, provider and MCP proxies, named strings, return shapes, and
+  schema-driven error recovery. Load before the first Fabric call or after an
+  argument-shape error.
 ---
 
 # fabric_exec — core reference
@@ -29,6 +26,8 @@ One type-checked TS program in a fresh executor (isolated QuickJS by default). O
 
 Aliases (normalized to canonical before the host validates args): `cmd`/`shell`/`cmdline`→`command`, `timeoutMs`→`timeout`; `query`/`regex`/`search`→`pattern`; `ic`/`caseInsensitive`→`ignoreCase`; `globPattern`→`glob`; `ctx`→`context`; `max`→`limit`; `file`/`dir`→`path`; `start`→`offset`; `old`→`oldText`; `new`/`replacement`→`newText`; `contents`/`body`/`text`→`content`. Misspelled keys still fail the excess-property type check.
 
+When a program needs a string containing literal `${...}` (shell snippets, tool arguments, or grep patterns), do not use a TypeScript template literal: TypeScript will interpolate it. Use a plain quoted string or pass the content through `strings` and read it from `π.key`.
+
 ## First-class provider calls
 Use direct proxies when the action is known. 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.
 
@@ -78,3 +77,5 @@ Multi-agent orchestration is opt-in: load `/skill:fabric-workflow`, `/skill:fabr
 `agents.main()` returns the dashboard-owning root Pi session; `agents.peers()` lists other live root sessions in the shared project mesh as `Peer <session-prefix>` targets. Peers support `agents.steer()` and `agents.followUp()` by exact id.
 
 Agent requests and persistent actors accept `runner: "pi" | "claude"`. Pi 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 subagents and actors unless requesting longer than the configured `subagents.timeoutMs` (60 minutes by default). Per-call values below the configured default are ignored.

package/skills/fabric-fusion/SKILL.md

@@ -1,16 +1,14 @@
 ---
 name: fabric-fusion
-description: Multi-model deliberation. A panel of up to 8 distinct models answers a task in parallel (each with web access), then a judge model compares their responses into structured analysis (consensus, contradictions, coverage gaps, unique insights, blind spots) that the caller turns into a better final answer. Use for research, expert critique, and compare-and-contrast where the cost of being wrong outweighs the cost of a few extra completions.
+description: Multi-model deliberation. Up to 8 distinct models answer in parallel with web-capable tools, then a judge compares consensus, contradictions, coverage gaps, unique insights, and blind spots. Use when the cost of being wrong justifies multiple completions.
 disable-model-invocation: true
 ---
 
 # Fabric Fusion
 
-Use one `fabric_exec` call. A panel of up to 8 distinct models answers the task in parallel, each with web access, then a judge model compares (does not merge) their responses and returns structured analysis: consensus, contradictions, partial coverage, unique insights, blind spots. Return that analysis; the caller writes the final answer from it. This mirrors OpenRouter's Fusion Router (`openrouter/fusion`): the panel and the judge are the inner deliberation, and the program hands back analysis rather than a merged answer.
+Use one `fabric_exec` call for a 1–8 model panel followed by one judge. The judge compares rather than merges responses; return its structured analysis so the caller writes the final answer. Use fusion for model-diverse research or critique, not tactical work or a lookup.
 
-Use when a single model is not enough: research questions, expert critique, compare-and-contrast, or anything where the cost of being wrong outweighs the cost of a few extra completions. Do not use it for a short tactical prompt or a lookup with no meaningful competing considerations.
-
-Pass the task and panel through `strings` and reference them as `π.*`. `π.task` is the prompt. `π.panel` is OpenRouter's `analysis_models`, a JSON `Array<{ model, label? }>` of 1–8 models; `label` defaults to the model id and is used only for attribution in the judge's input and the dashboard, never injected into a member's prompt. `π.judge` is OpenRouter's judge `model` (defaults to the first panel model). `π.tools` is the panel+judge tool allowlist (defaults to read, grep, find, ls, and bash; `bash` is the `web_search`/`web_fetch` analog via `gsearch`/`curl`). `π.thinking` is the reasoning effort for panel+judge (maps to OpenRouter's `reasoning`; defaults to `subagents.thinking`, medium). Pass every referenced key, using empty string for the optionals (`judge`, `tools`, `thinking`) when not setting them.
+Pass every key: `strings.task`; JSON `strings.panel` as `Array<{ model, label? }>`; and optional `strings.judge`, `strings.tools`, and `strings.thinking` as empty strings when unset. Labels are attribution only. Tools default to `read`, `grep`, `find`, `ls`, and `bash`; thinking defaults to configured subagent thinking.
 
 ```ts
 type FusionAnalysis = {
@@ -130,12 +128,8 @@ await workflow.event({ message: `Fusion complete · ${members.length}-model pane
 return analysis;
 ```
 
-The default panel size is 3 (OpenRouter's Quality preset). Pick a panel by intent; these mirror OpenRouter's presets, which you encode directly since pi-fabric has no model catalog: the strongest all-round models you have (`general-high`), a cheaper panel with one frontier judge (`general-budget`), or a latency-homogeneous panel (models with similar TTFT, so none gates the fan-out) for fast agentic turns (`general-fast`).
-
-Cost is N panel + 1 judge: a 3-model panel is roughly 4× a single answer. The run counts toward `budget.spent()` and the `tokenBudget` guard; `subagents.budgetUsd` bounds total spend. Set `agentBudget` and `tokenBudget` on `fabric_exec` when the panel or per-member work is large.
-
-Deliberation is bounded to one level. Members and the judge run as plain `agent()` calls without `recursive: true`, so they do not receive `fabric_exec` and cannot launch their own fusion panel, the same invariant OpenRouter enforces with its `x-openrouter-fusion-depth` header. Unlike OpenRouter, where the outer model decides per request whether to call `openrouter:fusion`, here the caller decides by running this skill; once invoked, the panel + judge always run.
+Choose distinct models by intent: strongest available, budget-balanced with a frontier judge, or similar-latency models for faster fan-out. The default panel size is three. Cost is N panel calls plus one judge; set top-level `agentBudget` and `tokenBudget`, while `subagents.budgetUsd` bounds spend.
 
-Web access requires `bash`, which is gated by the `execute` approval policy; without it, members answer from their own knowledge (a panel without web tools). Members run concurrently up to `subagents.maxConcurrent` (default 4); raise it in `fabric.json` or `/fabric` settings to run larger panels fully in parallel. OpenRouter exposes `max_tool_calls`, `max_completion_tokens`, and `temperature` per inner call; pi-fabric has no per-call equivalents, so members and the judge inherit provider defaults, with `thinking` for reasoning effort.
+Panel members and the judge are plain, non-recursive agents, so deliberation is one level. `bash` enables web access through local search/fetch commands and requires execute approval. Concurrency is capped by `subagents.maxConcurrent`; inner calls otherwise inherit provider limits and use `thinking` for reasoning effort.
 
-Do not use fusion for a single-model lookup, a simple edit, or a decision with no meaningful competing considerations; use a plain `agent()` or `council.run()` instead. For same-model, role-diverse review (one model, several perspectives), `/skill:fabric-council` is the closer match; fusion is for model-diverse deliberation.
+Use `/skill:fabric-council` instead for same-model, role-diverse review. Use a plain agent when competing model perspectives do not justify the cost.

package/skills/fabric-rlm/SKILL.md

@@ -1,26 +1,14 @@
 ---
 name: fabric-rlm
-description: Recursively decomposes a large task by delegating bounded subtasks to child Pi agents via rlm.query(), where each child gets a fresh context window and can itself recurse. Use for tasks too big for one context window — whole-repo audits, massive-context analysis, multi-file refactors.
+description: Recursively decomposes oversized tasks into bounded child Pi agents with fresh context windows. Use for whole-repo audits, massive-context analysis, and multi-file refactors that do not fit one context.
 disable-model-invocation: true
 ---
 
-# Fabric Recursive Decomposition (RLM)
+# Fabric Recursive Decomposition
 
-Inspired by Recursive Language Models: an LLM with a sub-call function can recursively decompose problems by self-delegation. `rlm.query()` is `agents.run()` with `recursive: true` — it spawns a child Pi agent with a fresh context window that can call `rlm.query()` again, bounded by `subagents.maxDepth`.
+Use recursion for context size, not mere difficulty. If the relevant material fits one context, work directly. Otherwise pass the root task as `strings.task` and use one `fabric_exec` program to size up → orient → delegate bounded chunks → combine.
 
-Recurse not because a task is hard, but because it is too big for one context window. Each child gets a fresh context budget; you get back only its compact answer instead of all the raw material.
-
-## Core pattern: size up → search → delegate → combine
-
-1. **Size up** — `wc -l`, `wc -c`, file counts, grep scope. If it fits one context window, do it directly; do not delegate.
-2. **Search** — `grep`, `find`, `ls`, `read` to orient before delegating.
-3. **Delegate** — hand clear, bounded subtasks to children. Use `rlm.query()` when the child should be able to recurse again; use `agent()` for a one-shot leaf worker that does not need to recurse.
-4. **Combine** — aggregate, deduplicate, resolve conflicts, produce the final output.
-5. **Do it directly when it's small** — never delegate what you can do in one step.
-
-## One fabric_exec program
-
-Turn the request into a single type-checked `fabric_exec` program. The program holds the decomposition loop and branches. Pass the root task through `strings.task`.
+`rlm.query()` is `agents.run({ runner: "pi", recursive: true })`: each child gets a fresh context and may recurse up to `subagents.maxDepth`. Use plain `agent()` for leaves that do not need recursion.
 
 ```ts
 await workflow.configure({
@@ -28,10 +16,9 @@ await workflow.configure({
   description: "Size up, delegate bounded subtasks, combine",
 });
 
-// Size up and orient with read-only tools before delegating.
 await phase("Orient", { total: 1 });
 const scope = await agent<{ paths: string[] }>(
-  `Identify the bounded set of files relevant to this task. Return structured output.\n\nTask:\n${π.task}`,
+  `Identify only the files relevant to this task.\n\nTask:\n${π.task}`,
   {
     label: "scope",
     tools: ["read", "grep", "find", "ls"],
@@ -44,15 +31,12 @@ const scope = await agent<{ paths: string[] }>(
   },
 );
 
-// Delegate each bounded subtask to a recursive child. Each child gets a fresh
-// context window and may call rlm.query() again up to subagents.maxDepth.
 await phase("Decompose", { total: scope.paths.length });
 const findings = await parallel(
-  scope.paths.map((p) => () =>
+  scope.paths.map((path) => () =>
     rlm.query({
-      runner: "pi",
-      task: `Analyze ${p} for this objective and report concrete, bounded findings.\n\nObjective:\n${π.task}`,
-      name: `analyze ${p}`.slice(0, 50),
+      task: `Analyze ${path} for this objective; return concrete evidence.\n\nObjective:\n${π.task}`,
+      name: `analyze ${path}`.slice(0, 50),
       tools: ["read", "grep", "find", "ls"],
     }),
   ),
@@ -60,27 +44,16 @@ const findings = await parallel(
 );
 
 await phase("Combine", { total: 1 });
-const summary = await agent(
-  `Synthesize these independent findings into one compact result. Drop unsupported claims and resolve conflicts:\n${JSON.stringify(findings)}`,
+return agent(
+  `Deduplicate, reconcile, and synthesize these findings; drop unsupported claims:\n${JSON.stringify(findings)}`,
   { label: "combine", tools: ["read", "grep", "find", "ls"] },
 );
-return summary;
 ```
 
-Adapt the phases, tools, and fan-out to the request. Use `schema` on a worker when machine-readable output makes aggregation safer.
-
-## When to recurse vs do it directly
-
-- A 30-line file or a single function: read it and act directly. No delegation.
-- A multi-file refactor: delegate per file or per module and combine.
-- A whole-repo audit or massive-context analysis: size up first, fan out bounded subtasks, then synthesize.
-
-## Guardrails
+Guardrails:
 
-- `subagents.maxDepth` bounds recursion depth; `subagents.budgetUsd` optionally bounds total USD spend across the whole tree (0 disables it).
-- When a budget is active, each recursive result carries a `budget` summary (`limit`, `spent`, `remaining`, `tokens`). Stop spawning children when `remaining` is low and finish the remaining work directly.
-- Approving the initial recursive call delegates only the `agent` risk capability to children; network, execution, and write approvals are not inherited. Give children edit tools only when they must change files.
-- Deeper children should be more conservative: fewer sub-calls, more direct action. Teach the pattern once — size-first → search → chunk → delegate → combine — and let it repeat at every depth.
-- For edits, partition ownership by path or set `worktree: true`; never let concurrent recursive children edit the same files.
-- The pre-spawn budget check is best-effort (concurrent children can overshoot slightly); the race-free ceiling is `subagents.maxPerExecution`.
-- A recursive child that drifts can be redirected without losing its context: `agents.steer({ id, message })` is delivered between the child's turns (after its current tool calls, before the next LLM call), and `agents.status({ id }).pendingMessages` shows the queued steers. Prefer steering over abandoning a child that has accumulated useful context. See the `agents` reference.
+- Size scope before spawning; deeper children should make fewer calls and act more directly.
+- Partition edit ownership by path or use `worktree: true`; concurrent children must not edit the same files.
+- `subagents.maxDepth` bounds each branch. The shared `subagents.budgetUsd` ledger is a best-effort whole-tree spend guard, not a hard cap; concurrent branches can overshoot its pre-spawn check. `maxPerExecution` and top-level `agentBudget` cap calls only in the current process.
+- `budget.remaining()` reports the current execution's token budget from completed usage; it does not expose agent-call or USD budget. Concurrent fan-out can overshoot that observation, so dispatch sequentially or in checked batches when the token ceiling matters.
+- Initial approval delegates only agent risk; network, execution, and write approvals are not inherited. Redirect a valuable drifting child with `agents.steer` rather than discarding its context.

package/skills/fabric-schema/SKILL.md

@@ -1,54 +1,42 @@
 ---
 name: fabric-schema
-description: Uses Fabric's typed Schema evidence loop and, when enabled, the host-owned bounded local-file transaction channel. Use when surprise must void a plan and mutation claims need explicit postconditions.
+description: Uses Fabric's typed Schema evidence loop and, when enabled, its bounded local-file transaction channel. Use when surprise must void a plan and mutation claims need explicit postconditions.
 disable-model-invocation: true
 ---
 
 # Fabric Schema
 
-First read the active mode through the typed first-class provider proxy. Use `tools.call()` only when a provider ref is computed at runtime.
+Start with `const status = await schema.status();`.
 
-```ts
-const status = await schema.status();
-```
-
-- `off` is the compatibility default. `state.*` can be used as workflow discipline, but it does not gate direct `pi.edit`, `pi.write`, or `pi.bash`.
-- `audit` preserves current behavior and durably reports actions that enforce mode would block.
-- `enforce` is a host authorization boundary for model-originated protected-workspace file changes. Direct mutations, agents, state/mesh writes, compaction requests, MCP, extensions, and external providers are blocked. Use one same-`fabric_exec` `schema.hypothesize → schema.verify → schema.commit` sequence.
+- `off`: compatibility mode; state discipline is optional and does not gate direct `pi.edit`, `pi.write`, or `pi.bash`.
+- `audit`: reports actions enforce mode would block without changing behavior.
+- `enforce`: host authorization for protected-workspace file changes. Reads remain available; mutations require one same-`fabric_exec` `schema.hypothesize → schema.verify → schema.commit` sequence. Direct mutations, agents, state/mesh writes, compaction, MCP, extensions, and external providers are blocked.
 
-Evidence is not proof. A typed evidence item is a falsifiable observation or a host-configured check. Verification confirms that the item held at one fingerprinted workspace state. Postconditions confirm scoped observations after declared file operations. Passing either does not establish general semantic correctness.
+Evidence is not proof. Verification confirms falsifiable observations at one fingerprinted workspace state; postconditions confirm scoped observations after declared operations. Either can pass without establishing general semantic correctness.
 
 ## Enforce loop
 
-Observe with allowed reads. Build literal or SHA evidence; use a trusted command only by a name supplied in trusted Fabric configuration. Never invent shell text: enforce-mode evidence has no command field or model arguments.
+Observe, hypothesize with literal/SHA evidence or a host-configured trusted command, verify, then commit only with the returned short-lived certificate and observed SHA:
 
 ```ts
 await pi.read({ path: "src/parser.ts" });
-
 const hypothesis = await schema.hypothesize({
   label: "parser-local-form",
-  summary: "Relative to the current head, the declared parser edit accepts the local form while focused tests remain green",
+  summary: "The declared parser edit accepts the local form while focused checks remain green",
   evidence: [
     { kind: "file_contains", path: "src/parser.ts", literal: "old literal" },
-    { kind: "trusted_command", name: "parser-focused-tests" }
-  ]
+    { kind: "trusted_command", name: "parser-focused-tests" },
+  ],
 });
+const verification = await schema.verify({ hypothesisId: hypothesis.hypothesisId });
+if (!verification.verified || !verification.certificate) return verification;
 
-const verification = await schema.verify({
-  hypothesisId: hypothesis.hypothesisId
-});
-
-if (!verification.verified || !verification.certificate) {
-  // Missing, empty, stale, nonconfirmed, errored, timed-out, cancelled, or
-  // workspace-changing evidence voids the plan. Do not act.
-  return verification;
-}
-const parserEvidence = verification.results.find(
+const observed = verification.results.find(
   (result) => result.evidence.path === "src/parser.ts",
-);
-if (!parserEvidence?.observedSha256) return { void: true, reason: "missing observed SHA-256" };
+)?.observedSha256;
+if (!observed) return { void: true, reason: "missing observed SHA-256" };
 
-const outcome = await schema.commit({
+return schema.commit({
   hypothesisId: hypothesis.hypothesisId,
   certificate: verification.certificate,
   operations: [{
@@ -56,56 +44,51 @@ const outcome = await schema.commit({
     path: "src/parser.ts",
     oldText: "old literal",
     newText: "new literal",
-    expectedSha256: parserEvidence.observedSha256
+    expectedSha256: observed,
   }],
   postconditions: [
     { kind: "file_contains", path: "src/parser.ts", literal: "new literal" },
-    { kind: "trusted_command", name: "parser-focused-tests" }
-  ]
+    { kind: "trusted_command", name: "parser-focused-tests" },
+  ],
 });
-return outcome;
 ```
 
-Use `write` with `expected: { absent: true }` for a new file or `expected: { sha256 }` for replacement. Use `delete` with `expectedSha256`. Paths are project-relative regular files; path and symlink escape are rejected. Keep every operation local, declared, and small.
+Any missing, stale, failed, timed-out, cancelled, or workspace-changing evidence voids the plan. Never invent trusted-command shell text or arguments: names resolve to static host configuration.
 
-The certificate is random, short-lived, single-use, and bound to the hypothesis, state head/version, workspace fingerprint/generation, and current `fabric_exec` invocation. Do not return it for later use. Fabric abandons an uncommitted hypothesis/certificate when this invocation ends. Call `schema.abort` explicitly when stopping early:
+The certificate is random, single-use, invocation-bound, and tied to the hypothesis, state head/version, workspace fingerprint, and generation. Do not return it for later use. If stopping after verification, call this with the values from that verification:
 
-```ts
+```text
 await schema.abort({
   hypothesisId: hypothesis.hypothesisId,
-  certificate: verification.certificate
+  certificate: verification.certificate,
 });
 ```
 
-A commit result is `committed`, `rolled_back`, or `quarantined`. Treat only `committed` as success. `rolled_back` means declared paths were restored after failure. `quarantined` means rollback could not be fully established and needs operator inspection.
+Operations are project-relative regular files:
 
-## Evidence vocabulary
+- `edit`: `oldText`, `newText`, `expectedSha256`
+- `write`: `expected: { absent: true }` for creation or `{ sha256 }` for replacement
+- `delete`: `expectedSha256`
 
-- `{ kind: "file_exists", path }`
-- `{ kind: "file_absent", path }`
-- `{ kind: "file_contains", path, literal }` — literal containment, not a regex
-- `{ kind: "file_sha256", path, sha256 }`
-- `{ kind: "trusted_command", name }` — static host-configured executable/argv
+Path/symlink escape is rejected. Keep operations declared, local, and small. Treat only `committed` as success; `rolled_back` restored declared paths after failure, while `quarantined` means rollback needs operator inspection.
 
-Trusted commands are an explicit trusted computing base. They should be deterministic, local, and read-only. Tests and type checks are evidence for their scoped claim, not mathematical proof. Remote/network/database effects are not transactional and remain blocked in enforce mode.
+Evidence/postcondition forms are `file_exists`, `file_absent`, `file_contains` (literal, not regex), `file_sha256`, and `trusted_command` (static host executable/argv). Trusted commands should be deterministic, local, and read-only. Remote/network/database effects are not transactional and remain blocked in enforce mode.
 
-For a claimed complexity reduction, set `complexityReduction: true` on the hypothesis and include behavior-preservation postconditions. Fabric reports it certified only after all postconditions pass; this does not turn tests into proof or objectively measure complexity.
+For a complexity-reduction claim, set `complexityReduction: true` and include behavior-preservation postconditions. Certification means those scoped checks passed, not that complexity was objectively measured.
 
 ## Off-mode state discipline
 
-When mode is `off`, the older labeled state layer remains useful:
+When mode is `off`, the independent labeled state layer can still record and verify a falsifiable claim:
 
 ```ts
 const transition = await state.transition({
   label: "claim",
   to: "claim-stated",
   summary: "A falsifiable delta",
-  evidence: ["pnpm exec vitest run tests/focused.test.ts"]
+  evidence: ["pnpm exec vitest run tests/focused.test.ts"],
 });
 const verification = await state.verify();
 if (!verification.certified) return { void: true, transition, verification };
 ```
 
-This is discipline over the typed state provider, not an enforcement boundary. `state` evidence and goals accept trusted workflow shell commands, unlike strict Schema evidence. In enforce mode those state write/execute actions are blocked; use `schema.*`.
-
-See `docs/schema-enforcement.md` for the exact guarantee, trusted-command argv/shell behavior, fingerprint coverage, recovery model, and limitations. See `docs/state-layer.md` for the independent labeled state timeline.
+This is workflow discipline, not enforcement. See `../../docs/schema-enforcement.md` for the guarantee and recovery model, and `../../docs/state-layer.md` for the labeled timeline.

package/skills/fabric-supervisor/SKILL.md

@@ -1,75 +1,20 @@
 ---
 name: fabric-supervisor
-description: Starts a persistent, event-driven Pi Fabric supervisor that watches the main session toward a concrete goal and steers only when needed. Use for long-running goal supervision without another extension.
+description: Starts a persistent Pi Fabric supervisor that watches the main session toward a concrete goal and steers only when needed. Use for long-running goal supervision without another extension.
 disable-model-invocation: true
 ---
 
 # Fabric Supervisor
 
-Start an emergent supervisor using `fabric_exec`; never install or invoke an external supervisor extension.
+Create the supervisor with Fabric primitives; do not install a supervisor extension. Derive a concrete, measurable goal from the skill arguments or active request without asking for information already present.
 
-Derive the goal from the skill arguments. If arguments are empty, use the active user request and conversation. Make the goal concrete and measurable without asking for information already present.
+Read `../fabric-ambient/references/setup.md` completely, then use its program with:
 
-Call `fabric_exec` once. Put the completed supervisor prompt in `strings.instructions` and the stable name `supervisor` in `strings.name`, then execute:
-
-```ts
-await workflow.configure({
-  name: `Supervisor · ${π.name}`,
-  description: "Persistent ambient goal supervision",
-});
-await phase("Start actor", { total: 1 });
-const current = await agents.actors();
-const existing = current.find((actor) => actor.name === π.name && actor.status !== "stopped");
-if (existing) {
-  const migrated: string[] = [];
-  await agents.setInstructions({ id: existing.id, instructions: π.instructions });
-  if (
-    existing.events.length !== 2 ||
-    !existing.events.includes("agent_settled") ||
-    !existing.events.includes("tool_error")
-  ) {
-    await agents.setEvents({ id: existing.id, events: ["agent_settled", "tool_error"] });
-    migrated.push("events");
-  }
-  if (existing.delivery !== "steer" || existing.triggerTurn !== true) {
-    await agents.setDeliveryPolicy({
-      id: existing.id,
-      delivery: "steer",
-      triggerTurn: true,
-    });
-    migrated.push("deliveryPolicy");
-  }
-  const warnings = [
-    ...(existing.responseMode !== "directive" ? ["responseMode should be directive; recreate the actor"] : []),
-    ...(existing.coalesce !== true ? ["coalesce should be true; recreate the actor"] : []),
-  ];
-  return {
-    reused: true,
-    actor: await agents.actorStatus({ id: existing.id }),
-    migrated,
-    warnings,
-  };
-}
-
-const actor = await agents.create({
-  name: π.name,
-  instructions: π.instructions,
-  events: ["agent_settled", "tool_error"],
-  responseMode: "directive",
-  delivery: "steer",
-  triggerTurn: true,
-  coalesce: true,
-  tools: ["read", "grep", "find", "ls"],
-});
-return {
-  started: true,
-  actor,
-  inspect: `/fabric messages ${actor.id.slice(0, 8)}`,
-  stop: `/fabric stop ${actor.id.slice(0, 8)}`,
-};
-```
-
-Use this prompt, replacing `GOAL`:
+- `strings.name`: `supervisor`
+- `strings.events`: `["agent_settled","tool_error"]`
+- `strings.triggerTurn`: `true`
+- `strings.model`: model key or substring, or an empty string when unset
+- `strings.instructions`: the prompt below with `GOAL` replaced
 
 ```text
 You are an ambient supervisor for this goal:
@@ -78,19 +23,11 @@ You are an ambient supervisor for this goal:
 GOAL
 </goal>
 
-Review each supplied parent-session event and recent transcript as an outside observer, not a second implementer.
+Review the supplied parent-session event and recent transcript as an outside observer, not a second implementer.
 
-Return {"action":"silent"} while work is productively advancing. Return {"action":"message","message":"..."} only when the main agent is idle with material work missing, is drifting from the goal, is stuck after a tool error, or needs one concrete next action. Keep a steer direct and at most three sentences. Do not repeat prior guidance. Never request credentials or invent a decision only the user can make.
+Return {"action":"silent"} while work is productively advancing. Return {"action":"message","message":"..."} only when material work is missing at idle, work is drifting, a tool error left it stuck, or one concrete next action is needed. Keep guidance direct and at most three sentences. Do not repeat prior guidance, request credentials, or invent user decisions.
 
-The goal is complete only when the requested result and its relevant validation are evident in the transcript. At that point return {"action":"stop","message":"Goal verified complete."}.
+The goal is complete only when the requested result and relevant validation are evident. Then return {"action":"stop","message":"Goal verified complete."}.
 ```
 
-## Heuristic: steer on good signals, not every turn
-
-The supervisor subscribes to `agent_settled` and `tool_error`, not `turn_end` or `input`. It runs at decision points (idle and on failures) and stays silent while work is productively advancing, so it does not invoke a model review on every turn. Intervene only on a concrete, high-confidence signal: material work missing at idle, drift from the goal, a stuck state after a tool error, or verified completion.
-
-After creation, report the goal, actor short ID, and inspect/stop commands. Do not wait for it; host events drive it across later turns.
-
-## Steering running subagents
-
-A supervisor (or any orchestrator) can redirect a running worker without discarding its context: `agents.steer({ id, message })` delivers between the child's turns, and `agents.status({ id }).pendingMessages` shows the queued steers. See the `agents` reference. Prefer this over stopping and respawning a worker that has accumulated useful context but is drifting from the goal. Because Pi actors run with Fabric, the supervisor can call `agents.main()` plus `agents.steer`/`agents.followUp` to message the user-facing Main session, redirect a running child directly, or route to an exact agent id in another process.
+Idle/error events avoid a model run on every turn. `triggerTurn: true` lets a material steer resume an idle Main session. Report the goal and setup result; do not wait for the actor.