Tether: CLI, daemon, MCP, dashboard, viewer
14,628 words41 subsections24 tables4 listingsPlan version 1.1
On this page41
Tether is the surface through which agents and people reach every other subsystem. It owns the verb registry, the result envelope, sessions and capability tokens, the job ledger and the daemon's dispatcher, the MCP server, the terminal dashboard and the viewer. It owns no physics and no statistics. A verb's handler lives in the crate of the subsystem that answers the question; Tether fixes how the question is asked, what it may cost, how the answer is labeled, and what happens when a client, a connection or the daemon fails.
32.1 What Tether owns
| Artifact | Crate or directory | Binary | Tier | First milestone |
|---|---|---|---|---|
Verb registry registries/verbs.toml; generated schemas, envelope, exit codes, refusal table |
frob-verbs |
— | S | M0 |
| Command line | frob-cli |
frob |
S | M0 |
| Daemon: sessions, tokens, budgets, job ledger, dispatcher, device ownership | frob-cli |
frobd |
S | M2 for the job engine; slot dispatch M3 (§43) |
MCP server on fastmcp_rust |
surface/frob-mcp (a member of the core workspace) |
frob-mcp; also hosted by frobd --mcp |
S; Tasks adapter F | M0 smoke, M1 verbs, M3 full |
| Terminal dashboard on FrankenTUI | frob-tui |
frob-tui |
S, optional | M3 |
| Viewer page, overlays, stills, self-contained HTML replay | viewer/ |
— | S; native viewport F | M2 |
| Agent guide, skill file, MCP prompts | generated from the registry | — | S | M1 |
32.2 Principles
- One verb registry.
registries/verbs.tomldefines each verb once: name, cluster, kind (read,run,mutate,admin), required capabilities, input and output schema identifiers, possible refusals, idempotency rule, cost model and examples. The CLI, the MCP tools, the schemas and the agent documentation are generated from it, and a parity gate diffs them (the design FrankenMining adopted, FACT). - Agents ask questions and spend budgets. They do not drive solvers (FrankenSim addendum proposal 8, FACT). A verb takes a question, a confidence or tolerance where relevant, and a budget; it answers, or it refuses and says what would make the question answerable.
- The Five Explicits. Units, seeds, budgets, versions and capabilities are never implicit (FrankenSim P10, FACT).
- One application service, two adapters. The CLI and the MCP server both link
frob-verbsand call the same handlers in process through the same dispatch interface, and both hand long work to the daemon as jobs. Simulation ticks run inside a worker owned by the daemon; calls on the control plane act on whole designs, jobs, chunks and queries, never on single steps (DESIGN: a per-step remote call would put the agent's latency inside the physics loop). - Every answer says what changed. After a run the envelope names the change the agent made, the first physical consequence of it, and the evidence for the comparison (§28, §29).
- What is claimed for this surface. MCP access to a simulator is prior art (FACT, Appendix H: one incumbent ships an MCP server for documentation lookup, and a community server exposes 42 tools that drive that simulator; neither documents compute budgets, provenance or a typed refusal taxonomy). The claim made here is narrower: every verb carries a compute budget, provenance and a typed refusal, and both surfaces are generated from one registry.
32.3 Decisions
| ADR | Decision | Reason |
|---|---|---|
| ADR-TETHER-01 | The registry is compiled into a static table in frob-verbs by its build script. Neither frob-cli nor frob-mcp contains per-verb code, with one exception: the MCP half of session.focus (§32.12.4). |
Parity by construction; GATE-TETHER-02 then checks the served surfaces, not the generator's intentions. |
| ADR-TETHER-02 | frob-verbs has a registry-only feature with no dependency on any physics crate or on frob-fsim. |
It is what KILL-MCP's first fallback links: frob-mcp built as its own workspace must still share the table, the schemas and the envelope types (§32.12.2). In the default build frob-mcp links frob-verbs whole. |
| ADR-TETHER-03 | frob-mcp is a protocol adapter with one dispatch trait and two back ends: in-process handlers, which are the default, and a local socket to frobd. In the default build it links frob-verbs, runs verbs in process and hands long work to frobd as a job. The socket-only form is complete on its own and is KILL-MCP's first fallback. |
The daemon owns devices and jobs in any case; a killed adapter must never own a job; and the fallback must be reachable without redesigning the adapter. |
| ADR-TETHER-04 | Long tools take a bounded synchronous wait, sync_wait_ms, and otherwise return a job handle. |
Most studio verbs finish inside the wait (TARGET: design check under 2 s, control synth under 5 s, §36), and an agent turn is believed to cost 30 to 120 s of thinking (HYPOTHESIS; measured in GATE-TETHER-13), so an avoided poll saves more than the compute it waits for. |
| ADR-TETHER-05 | Wire cancellation of a waiting call ends the wait, not the job. job.cancel cancels the job. |
A client timeout is not a decision to discard admitted, charged work; the job is recoverable by its key. |
| ADR-TETHER-06 | The MCP Tasks extension is an optional adapter over the job ledger, never the primary contract. | The library labels it experimental and provisional (FACT, §32.12.1); the handle contract works on every client and protocol era. |
| ADR-TETHER-07 | The daemon dispatches episodes into slots of a persistent environment per device and shape class, not one environment per job. | One paired comparison fills about 2.3% of a batch (§32.11.1); without sharing, the rest of the device idles. |
| ADR-TETHER-08 | The scheduler decides when work runs and never what is computed. No wall-clock quantity enters a result. | Feedback from load into results breaks replay and makes verdicts depend on who else was running. |
| ADR-TETHER-09 | Integers that can exceed 2⁵³ − 1 travel as decimal strings; counts are range-checked numbers. | Clients that decode JSON numbers as doubles silently change larger values (§32.8.2). |
| ADR-TETHER-10 | The dashboard and the viewer are ordinary clients. Each value they show is obtainable by a named verb. | No private interface means no unaudited path to state, and agents without eyes lose nothing. |
| ADR-TETHER-11 | Mutating and job-submitting verbs bind immutable identifiers. A mutable name is resolved once, before the request is digested, and the resolution is echoed. | Otherwise a retry after a name has moved would mean a different request under the same key. |
32.4 The envelope
With --json, every verb writes exactly one envelope to standard output (long jobs write newline-delimited
progress events, then the envelope). Malformed input and unknown verbs also produce the envelope.
{ "schema": "frob.envelope/1", "verb": "design.check", "ok": true, "exit": 2,
"result": { "mass_kg": 14.2, "closure": "closed", "symmetry": "C2xC2",
"findings": [ { "code": "A-11.knee.continuous", "severity": "high",
"message": "Knee continuous torque demand exceeds the card by 31% in crouch.",
"repairs": [ { "edit": "swap-actuator", "args": {"joints": "*.knee", "to": "qdd-l"},
"predicted": {"mass_kg": "+0.9", "margin": "+46%"} },
{ "edit": "regear", "args": {"joints": "*.knee", "ratio": 1.9} } ] } ] },
"evidence": { "class": "Tested", "tier": "static", "model_id": "m:9f2c…", "determinism": "exact",
"claims": [], "reality": "no-claim" },
"bound": { "design": "d:41aa…" },
"cost": { "wall_ms": 412, "cpu_core_s": 0.4, "gpu_s": 0 },
"budget": { "gpu_s_left": 600, "cpu_core_s_left": 7199.6 },
"warnings": [], "next_actions": [ { "command": "frob design edit quad-a swap-actuator --joints '*.knee' --to qdd-l",
"why": "Largest predicted margin gain per kilogram." } ] }
| Field | Rule |
|---|---|
evidence |
Computed as a claim product (§8, §37.10): the weakest proof class, tier and determinism class among the inputs. claims names which of the seven claims the result may be cited for, and is empty for most studio answers; reality is no-claim unless §30 supplies data. |
bound |
The immutable identifiers every mutable name was resolved to (ADR-TETHER-11). |
refusal (when ok is false) |
code, message, pointer (the field or part at fault), observed, required, unit, affected_claims, retry (never, after-change, backoff), and ranked repairs. |
job (exit 8, and job verbs) |
id, state, progress {done, total, unit}, eta_s with its interval, poll_after_ms, last_committed. Progress always has a denominator. |
cursor, frontier |
Present on paginated results (§32.8.1). A long answer is paginated and says so; it is never cut silently. |
idempotent_replay |
true when the envelope is the stored answer to an earlier request with the same key. |
authorization |
On every verb that exports an artifact: the three no-authorization flags, all false (§37.9). |
| Exit | Meaning | Failure class (§32.5) |
|---|---|---|
| 0 | Completed, nothing to flag | — |
| 2 | Completed with findings or flags | — |
| 3 | Refused input or question (FROB-REF-1xx to 5xx, and 8xx other than conflicts) |
Domain |
| 4 | Budget: refused at admission or stopped; nothing partial is published as a result (70x) |
Domain |
| 5 | Capability not implemented, not admitted, or outside the session token's scopes (72x, 73x) |
Domain |
| 6 | Backend or device unavailable (FROB-REF-6xx) |
Domain |
| 7 | Conflict: idempotency key reuse with different content, stale parent, or lineage conflict | Domain |
| 8 | Accepted and still running: the envelope carries a job handle. Not a failure | — |
| 9 | Indeterminate. Never retry blindly; recover by key (§32.7) | Transport; also integrity faults (FROB-REF-810, 9xx) |
Exit code 1 is never emitted on purpose, so a 1 always means an unhandled failure. Exit 8 is new with the bounded wait (DESIGN: a script must be able to tell "done" from "admitted and running" without parsing the result).
32.5 Three failure classes
A caller meets exactly three kinds of failure, and each is tested on both surfaces (GATE-TETHER-04).
| Class | What happened | CLI | MCP | What the caller does |
|---|---|---|---|---|
| Domain | The verb was reached and it refused, stopped on budget, lacked a capability or a device, or met a conflict. A numerical refusal, a budget stop and a physical failure of the robot are three different outcomes: the first two are refusals, the third is a result with findings. | Envelope with ok: false; exit 3, 4, 5, 6 or 7 |
Tool result with isError: true whose structured content is the same envelope |
Read refusal.repairs and retry. |
| Protocol | The request never reached a verb: unknown verb, or arguments that fail the schema. | Envelope, exit 3, FROB-REF-801 or -802 (the CLI owns its parser) |
Unknown tool: a JSON-RPC error from the library before any handler runs (FACT: InvalidParams, −32602, "Unknown tool", fastmcp_rust/README.md). Schema failure: the library's input-validation error, mapped to an envelope skeleton with exit 3 by the registration-time error hook (§32.12.3) |
Fix the call; nothing was charged. |
| Transport | The connection, the client or the daemon died, or a deadline passed before a receipt arrived. The job may be running. | Exit 9 if the CLI survives the daemon; otherwise whatever the shell reports | No result. The library may deliver a request-cancelled error (FACT: −32004) or nothing | Never resubmit blindly. Reconnect and call job.find with the idempotency key; one job and one charge exist or none do (INV-TETHER-05). |
The one permitted difference between the surfaces is the unknown-verb case in the Protocol row: on MCP the library answers before generated code runs, so no envelope exists. The parity gate lists it as the only exemption.
32.6 Verb clusters
A cluster is a namespace in the registry. Appendix J holds the full registry; a verb introduced by a subsystem
chapter joins the cluster named here. Kinds: R read, U run, M mutate, A admin.
| Cluster | Verbs (kind) | Owner chapter | First milestone |
|---|---|---|---|
| operator | doctor (R), capabilities (R), robot-docs (R), schema (R) |
§32 | M0 |
session |
open (M), show (R), focus (M), close (M) |
§32 | M0; tokens and budgets M2 |
job |
list (R), status (R), wait (R), find (R, by idempotency key), cancel (A) |
§32 | M2 |
artifact |
read (R, by digest and byte range), export (U), list (R) |
§29 | M1 |
spark |
devices (R), probe (U), check (U), precompile (U) |
§21 | M0, M2 |
design |
new (M), show (R), edit (M), diff (R), blame (R), bisect (U), check (R), import (M), export (R), templates (R) |
§14 | M1; bisect M4 |
analyze |
One verb per analysis A-01 to A-16 and each later analysis of §28 (R) | §28 | M1 to M4 |
scene |
gen (U), import (M), compile (U), list (R), show (R), purge (A, §37.6) |
§19 | M2, M3 |
control |
synth (U), show (R) |
§22 | M1 |
sim |
estimate (R; never runs physics), run (U), replay (U; --tier teleports) |
§16, §29 | M0 referee, M2 all tiers |
run |
show (R), list (R), export (U: a .frun bundle or a view of it), fork (U: a new branch from a run and checkpoint with an optional change set; returns the branch, the inherited prefix, the restart time and the fork's class, one of the five of §27.4; --classify-only restores nothing) |
§29 | M1; fork M2 |
train |
start (U), status (R), stop (A), export (R) |
§23 | M2 |
eval |
run (U), compare (U), preanalyze (R: reachable verdicts and power of a fixed-n rule), promote (U), scorecard (R), qualify (U: the blinded lane of §24; returns a verdict and a receipt and nothing per world), ledger (R), rank-agreement (U, §28.10) |
§24; promote §16, §29; rank-agreement §28 |
M2, M3; preanalyze M1; qualify M3; rank-agreement M4 |
study |
plan (M), submit (U), status (R), cancel (A), compare (R) |
§24, §28 | M2; compare M3 |
experiment |
suggest (R: competing designs, uncertainty, remaining budget and allowed changes in; ranked information-gathering proposals with testable predictions out) |
§25; consumer §28 | M4 |
telemetry |
summary (R), query (R), energy (R), failures (R), histogram (R), divergence (R: first divergence between two runs), stills (R), inspect-pixel (R), export-html (R: the self-contained replay; page and viewer in §32.15 and §32.24) |
§29; stills §20 |
M1, M2 |
explain |
run (R), design (R), compare (R) |
§28 | M1; compare M3 |
autopsy |
intervene (U: interventions, placebo forks, replicates and coalitions from a fork made by run.fork), attribute (R: contrasts, flip rates, pairs, labels), repair (U), rerun (U: paired re-run from the episode start), show (R) |
§27 | M3 |
nemesis |
search (U: adversarial worlds inside a declared family), shrink (U: reduce a failing world to a minimal counterexample, .fmcw), oracle (U: classify one world for one candidate), bound (U: certify, refute or estimate a failure probability), audit (U), cover (R), hardset (R, U: show, add, retire and run the hard-world set) |
§26 | M3; audit M4 |
mission |
new (M), check (R: admission of a .fmission; an empty or inconsistent domain is refused; the quantifier order is echoed), synthesize (U: inner and outer design sets with witnesses, exclusions and unresolved cells), refute (U: a scoped impossibility bound, or a witness defeating one design or controller), distinguish (U: the smallest admissible intervention or instrument that separates alternatives), separate (U: an admissible world pair on which a design ordering or a diagnosis reverses), transport (U) M, revalidate (U: the same engine as result.revalidate), show (R) |
§25 | M1 CPU slice; at scale M4 |
result |
show (R), revalidate (U: after a change, which certificates and results survive, which regions are invalidated, which reruns are needed and their cost) |
§28, §12 | M1 for the mission slice (dependency grades 1 and 2 on mission cells); full M4 |
prove |
kernel (R), verify (R: in-tree check of a bundle; the independent frob-verify binary repeats it offline), list (R), bundle (U: assemble a .frobcert), reflect (U) F |
§12 | M0; bundle M1 for the mission slice; full M5 |
opt |
start (U), status (R), archive (R), cascade (U: the six-stage co-design cascade of §28.11; solve.run calls it) |
§28 | M4 |
predict |
register (M), report (R) |
§28 | M4 |
ground |
ingest (M: logs and measurements, as data), excite (R), identify (U), predict (M), score (U), band (R: the reality band for a predicted metric, or no-claim), kit (U) |
§30 | M5 |
foundry |
loads (U), size (R), optimize (U), check (U), tolerance (R), export (U: geometry and the .fbuild build packet; --with-firmware M), lifecycle (U) M |
§31 | M5, M6; export --with-firmware M8 |
report |
design (R), run (R), mission (R), campaign (R) |
§28 | M3; campaign M4 |
solve F |
run (U: one call from a task specification and a budget to a ranked set with verdicts; it calls opt.cascade and the verbs above and adds none of its own evidence) |
§32.6.2 | M4 |
Every name in this table is the name its owner chapter registers; the registry holds no second spelling (Appendix J,
J.4). Clusters whose verbs are specified only in their own chapters and listed in Appendix J: phylum (§17), gait,
shield and skill (§22), policy (§23), task (§24), sense (§20), fidelity (§16), contact (§18), actuator
(§15), module (§14), algebra (§13), fleet (§21), cores, evidence and store (§28, §29).
32.6.1 The two-phase study
study.plan binds a trial manifest to immutable designs, scene, task, seed protocol, budget, backend and one
declared study type: anytime-valid or fixed-n exact, never both in one study. It returns a plan identifier
that is the content address of the resolved manifest, the cost estimate with its interval (§32.9), and, for a
fixed-n study, the pre-analysis of which verdicts are reachable at that n (computed by eval.preanalyze, §24.12).
Planning runs no physics and is idempotent by construction. study.submit takes the plan identifier and an
idempotency key and returns a job. study.compare reads a study and returns, per metric, a verdict of §28.6
(settled, tied or inconclusive; incomparable or infeasible where the study could not be scored), with
intervals, failures, the first divergent event, and pair counts that satisfy a_only + b_only + both + neither +
unscored = planned. eval.compare remains as the one-call form: it plans and submits an anytime-valid paired study with
defaults. DESIGN reason for two phases: the agent sees cost and reachable verdicts before any budget is spent,
and the submitted object cannot drift from the planned one.
32.6.2 The one-call pipeline F
solve.run compiles a task, constraints and a budget into the sequence check, sweep under the baseline
controller, race, promote, and returns a ranked set with verdicts. It is orchestration, not a mechanism: every
number in its answer comes from the verbs it calls. It is the agent-facing form of the cascade: the co-design
cascade itself is run by opt.cascade (§28.8, §28.11), which solve.run calls. HYPOTHESIS: about five-fold fewer
serial agent turns per accepted design; the test is GATE-TETHER-13's second arm, which is the one-verb arm of the A/B
of GATE-ATEL-03. There is one A/B, and KILL-SOLVE is decided on it. Ceiling, stated before any test: the fraction of
turns
in recorded sessions that carry no decision (pure plumbing); if that fraction is below 30% the ceiling is under
1.4-fold and the work package is not funded. Pilot: replay 20 recorded sessions on paper and count plumbing
turns. Kill gate KILL-SOLVE; fallback: the MCP prompts of §32.12.8, which cost nothing to keep.
32.7 Idempotency S
Every mutate verb and every job-submitting run verb takes an idempotency key; omitting it is a refusal
(FROB-REF-805). The protocol binds, in one transaction of the job ledger, six things: the caller's principal
and namespace, the verb, the key, the canonical request digest, the budget reservation and the job identifier.
- Resolve names to immutable identifiers and fill defaults. Serialize the resolved request canonically (sorted keys, no insignificant whitespace, NFC strings, numbers by the rules of §32.8.2) and take its BLAKE3 digest.
- Begin an immediate transaction. Look up (principal, verb, key).
- Found with the same digest: return the stored receipt with
idempotent_replay: true. Found with a different digest: refuse withFROB-REF-803, exit 7, showing both resolutions. Not found: insert the binding, debit the reservation and insert the job row in stateadmitted, all in this transaction. - Commit. Only then enqueue the job and return the receipt.
A crash after step 4's commit and before the receipt reaches the caller is the transport class: the retry with
the same key finds the binding and returns the original job. On restart the daemon enqueues every admitted job
that has no start record. Keys are scoped to (principal, verb) and are kept as long as the job record; for
mutate verbs that create no job the retention is 24 h (TARGET). FACT: the suite's mail server records a key, a
payload fingerprint and the serialized result inside the mutation's own transaction, with a 24 h default window
(mcp_agent_mail_rust/crates/mcp-agent-mail-tools/src/idempotency.rs); this is the same pattern with the
reservation and the job added.
Counterexample for the obvious shortcut (look up, then insert, in two statements): requests A and B carry the same key and payload. A looks up and misses; B looks up and misses; A inserts; B inserts. Two jobs run and the budget is charged twice. The single transaction with a unique index on (principal, verb, key) leaves one.
32.8 Pagination and numbers S
32.8.1 Pagination pinned to a committed frontier
A paginated answer (telemetry.query, mission.show, job.list, any catalog) fixes four things on its first
page and encodes them in an opaque, authenticated cursor (frob.cursor/1): the query digest (run or object,
filters, ordering), the committed frontier of the store at that moment (§32.10), the total-order key of the last
row returned, and the schema version. The order key of a telemetry row is (instant, world address, channel,
sample index), so rows that share a timestamp still have one order. Later pages read only rows at or below the
frontier and strictly after the key. Chunks committed after the first page are invisible to that sequence; a
client that wants them starts a new query or passes follow, and the answer states the new frontier. A cursor
used with changed filters is refused (FROB-REF-806); a cursor whose frontier has been garbage-collected is
refused (FROB-REF-807). FACT: the suite's mail server already distinguishes an expired cursor from one ahead of
the durable tail (mcp_agent_mail_rust/crates/mcp-agent-mail-tools/src/messaging.rs, fetch_inbox_events).
Counterexamples. (a) Offset pagination: rows at t = 1, 2, 3, 4, page size 2. Page one returns {1, 2}. A chunk from a slower world then commits a row at t = 1.5. Offset 2 now returns {2, 3}: row 2 is repeated. (b) A cursor on time alone: two worlds each have a sample at t = 2 and the page ends on the first; "after t = 2" skips the second.
32.8.2 Integers above 2⁵³
A client that decodes JSON numbers as IEEE doubles tells consecutive integers apart only up to magnitude 2⁵³ − 1 = 9,007,199,254,740,991 (FACT). 2⁵³ + 1 = 9,007,199,254,740,993 decodes to 9,007,199,254,740,992. Two schema types therefore replace "integer":
int53: a JSON number. The serializer refuses a value outside ±(2⁵³ − 1); an input outside it is refused (FROB-REF-808). Used for counts: episodes, pairs, steps, bytes.u64strandi64str: a decimal string matching^(0|[1-9][0-9]{0,19})$with an optional leading minus for the signed type. Used for world addresses, seeds and stream counters, tick indices and nanosecond instants.
A schema lint forbids any other integer type. Digests are hexadecimal strings already. FACT: fastmcp_rust
builds serde_json with arbitrary_precision and keeps progress values' original numeric spelling
(fastmcp_rust/Cargo.toml, README.md), so the server side loses nothing; the rule exists for the client's
decoder, which this project does not control.
32.9 Estimates and budgets
Every verb that can cost more than a second accepts --estimate and returns CPU core-seconds, GPU seconds,
memory and disk with an interval, without running. A session carries budgets; a verb that would exceed one is
refused with the estimate attached. Mutating verbs take idempotency keys. Long work is a job with a handle,
progress events, and cancellation that drains (§21).
The interval is conformal S. The cost model of §36 gives a point prediction ŷ. For each stratum (verb, tier,
device family, shape class) the daemon keeps the last n absolute log residuals r_i = |ln(y_i / ŷ_i)| of finished jobs.
At miscoverage α the half-width q is the ⌈(n + 1)(1 − α)⌉-th smallest residual, and the interval is [ŷ·e^(−q),
ŷ·e^(q)]. Under exchangeability of the residuals within a stratum this covers the actual cost with probability at
least 1 − α (the standard split-conformal rank argument; PO-TETHER-04). The index exists only for n ≥ 9 at α = 0.10
and n ≥ 19 at α = 0.05 (DESIGN arithmetic: ⌈(n + 1)(1 − α)⌉ ≤ n). The daemon reports the 90% interval and calls a
stratum calibrated from n = 19, so one stratum serves both levels; below that the envelope marks the interval
uncalibrated and admission uses a fixed factor of 2 (DESIGN, conservative). A driver, compiler or kernel-version
change starts a new stratum, since exchangeability across it is not credible. FACT: the suite has a conformal
calibrator to consume or follow (asupersync/src/lab/conformal.rs, ConformalCalibrator, CalibrationReport).
Admission uses the upper end. A job is admitted when the interval's upper end fits the remaining budget
(FROB-REF-701 otherwise). DESIGN reason: a budget stop publishes nothing, so an underestimate wastes the whole
spend while an overestimate costs only a refusal the agent can answer with a smaller question.
What a budget can cap. Wall time, simulated time, GPU seconds, CPU core-seconds, device memory, trace
bytes, episode count and solver iteration caps. Under shared batches a job is charged attributable device time:
the sum over steps of (its occupied slots ÷ batch capacity) × the step's wall time. Idle reserve is charged to
the daemon's own overhead line and reported by session.show, never to an agent.
32.10 Jobs: the crash-consistent protocol S
States. Submission ends in refused (admission) or admitted. An admitted job becomes running,
failed_to_start or cancelled. A running job may be preempted and resumed (§32.11.2), and ends complete,
failed or cancelled. Each terminal receipt counts completed, failed, refused and unstarted trials, and the four
counts sum to the planned number. Checkpoint and resume events are recorded. Every transition is identified by (job,
logical world, episode, tick).
Chunks. Telemetry and results are published in chunks whose format and store belong to Chronicle (§29).
Tether owns the leases and the publishing transaction. Each (world, episode) has a fixed logical chunk partition
that does not depend on how the device was sharded: chunk k covers ticks [k·C, (k + 1)·C). One transaction
enforces the lease generation, the expected predecessor and a contiguous commit frontier, and publishes the
checked payload hashes, the index and the logical frontier together. A duplicate identical chunk reuses its
original receipt. Different bytes for a committed extent are a replay error (FROB-REF-810), and the job fails
as indeterminate. On restart the daemon ignores unattached chunks and rebuilds from the last committed
checkpoint. Garbage collection is bounded and respects retained checkpoints and the frontiers pinned by open
cursors.
Counterexamples that fix the two design choices. (a) Range-keyed chunks: a retry splits a shard, and ranges [0, 100) and [50, 150) both cover ticks 50 to 99; with range keys both commit. The fixed partition makes the second a duplicate or a conflict. (b) A key of (world, tick): a reset reuses tick zero, and the second episode overwrites the first. The episode index is part of the key.
Cancellation. At a documented safe boundary (the kernel-batch boundary of §21): request, drain in-flight device work, discard unpublished state, acknowledge with the last committed tick per world. The receipt reports outstanding device work at the moment of the request and the observed cancellation latency. A dropped handle is not a cancellation receipt.
The ledger. The job ledger is a FrankenSQLite database under the daemon's state root, with the daemon as its only
writer (DESIGN; FACT to recheck: the suite's mail server warns of a snapshot-drift defect in the engine's
concurrent-writer mode and defaults to a single writer; see crates/mcp-agent-mail-server/src/lib.rs in
mcp_agent_mail_rust). Job logs persist independently of any client connection. The ledger logic is tested under
seeded fault schedules on a deterministic runtime, with a CPU stand-in for the device and dual-run scenarios so a
divergent stand-in is caught (FACT: asupersync/src/lab/ has chaos.rs, ldfi.rs and replay_minimization.rs).
32.11 The daemon
frobd owns devices, kernel caches and the job queue, with fair sharing between agents. frob (the CLI) and
frob-mcp both hand long work to frobd as jobs. Without the daemon both still run CPU-tier verbs in process, and
say in the envelope that they did. frobd can also host the MCP server itself (frobd --mcp), so that one process
serves the job queue and the MCP transports. There is one daemon per host and nothing is replicated (DESIGN:
consensus protocols solve a problem this system does not have). It listens on a Unix-domain socket under its state
root, mode 0600, and speaks newline-delimited JSON (frob.rpc/1): a request frame, zero or more progress frames,
one envelope. Between the two machines a peer link forwards whole jobs F: only seeds, recipes, design and module
differences, receipts and policy weights cross it. Ceiling: the device time one machine idles while the other
queues; pilot: a week of both queue traces replayed on paper; under 10% overlap of idle and queued time (TARGET)
the link is not built and the machines run standalone.
32.11.1 Slot-level episode dispatch [S within a shape class; across model variants with §17]
The daemon keeps one persistent environment per device and shape class (the size bucket of §17). Model variant, scene, task and job are per-world buffers. When a slot's episode ends, the dispatcher resets that slot with the next admitted episode from any job of the same shape class. Results are keyed by world address, never by slot or arrival order. No shape change enters a running environment, because the static launch graph of §21 forbids it; a job of another shape class waits for, or opens, another environment.
The arithmetic that motivates it (DESIGN arithmetic on the reference batch of B = 8,192 worlds; no measurement):
| Work | Slots | Share of the batch |
|---|---|---|
| A mission cell probe of 16 worlds | 16 | 0.2% |
| A fixed-n study of 30 pairs | 60 | 0.7% |
| An anytime-valid comparison at its cap of 96 pairs (the session of §32.16) | 192 | 2.3% |
A 2,048-world sim.run |
2,048 | 25% |
With 20 s episodes at a 2 ms step, one batch-episode is 8,192 × 10,000 = 81.92 M world-steps. Taking a round R = 2 × 10⁶ world-steps/s (the order of §36's targets; TARGET, not measured) it lasts 40.96 s of device time, of which the 96-pair comparison is attributable 192 × 10,000 ÷ R = 0.96 s. With 5% of slots (410) held in reserve, 40 such comparisons fit in one batch-episode with 102 slots to spare. Ceiling, stated before any speed test: the gain over one environment per job is at most min(k, 1 ÷ fill) for k concurrent small jobs, so at most 42-fold for 192-slot jobs and nothing at all for a single agent running one job at a time, who gains only the removal of environment creation from each call. Against a right-sized environment per job the ceiling is the measured ratio of step time at 8,192 worlds to step time at the job's own size, which is unknown until the M2 profile.
- Budgeted mode. At most 64 jobs per environment; 5% of slots reserved for the interactive class; beyond that, queue (TARGET values, recalibrated at M2).
- Proof obligation. Dispatch is a pure function of queue state; no kernel reads another world's rows; so a world's digest is a function of its address and identities alone (PO-TETHER-03, and the batch-independence test of §35).
- Rollout. Shadow on
batch-cpufirst: run each job both ways and compare digests. Rollback isfrobd --dispatch=per-job. Kill gate KILL-SLOT.
32.11.2 Size classes, shortest estimated work, preempt-resume S
- Size classes come from the system's own estimate, never from the agent:
interactive(point estimate at most 30 s of device time),batch, andcampaign(above the machine envelope of OPEN-SPARK-2, refused withFROB-REF-704until the owner approves one). TARGET boundaries. - Order within a class. Deficit round-robin across agents, weighted by remaining budget; within an agent, shortest estimated remaining work first. A waiting job's effective work decays linearly to zero over 600 s (TARGET), so no job waits behind an unbounded stream of shorter ones (PO-TETHER-05).
- Preempt-resume. A batch-class job can be parked at a snapshot boundary (quantum at most 5 s, TARGET) and resumed later with identical digests. The snapshot includes warm starts, packet queues and stream counters (§11, §20). At most one preemption per batch job per 30 s, and the batch class keeps at least 30% of device time (TARGET).
- Admission guard. Utilization is held under 0.8 per device (TARGET); beyond it, new work is refused with
FROB-REF-703andretry: backoff.
Why priority alone is not enough (DESIGN arithmetic, M/G/1 with Poisson arrivals; a model, not a measurement). Take one device, 90% of jobs 10 s and 10% of jobs 30 min: ES = 189 s, E[S²] = 324,090 s². With W₀ = λ·E[S²]/2, first-come-first-served waits W₀/(1 − ρ); a non-preemptive priority for the short class waits W₀/(1 − ρ₁); under preempt-resume the short class sees only itself, λ₁·E[S₁²]/(2(1 − ρ₁)), plus at most one quantum.
| Utilization ρ | First-come wait | Short-class wait, priority only | Short-class wait, preempt-resume | Slowdown of long jobs |
|---|---|---|---|---|
| 0.5 | 857 s | 439 s | 0.12 s + quantum | 2.4% |
| 0.7 | 2,001 s | 621 s | 0.17 s + quantum | 3.4% |
| 0.8 | 3,430 s | 713 s | 0.20 s + quantum | 4.0% |
| 0.9 | 7,716 s | 806 s | 0.22 s + quantum | 4.5% |
The wait under priority is the remainder of the long job already on the device; only preemption removes it. A swarm's arrivals burst, so the capacity table the daemon publishes scales these waits by (c_a² + c_s²)/(1 + c_s²), Kingman's correction, with the squared coefficients of variation of inter-arrival and service times measured from its own trace. The result flips if resume costs several seconds or a device is reserved for interactive work: then run to completion.
32.11.3 The decision model
Each quantum the dispatcher reads integer state from the ledger and applies a guard table with hysteresis. The table is part of the daemon's configuration digest.
| State | Signal | Action | Loss avoided |
|---|---|---|---|
| Under-filled | Free slots beyond the reserve while episodes of this shape class wait | Co-batch at the next reset boundary | Idle slot-seconds |
| Saturated | No free slot and an interactive job waiting | Use the reserve; if it is full, preempt the batch job with the most remaining work at its next snapshot boundary | Agent idle time |
| Mixed shapes | A waiting job's shape class has no environment | Open a second environment if the memory preflight passes and the job's estimated work exceeds the creation cost; otherwise queue | Recompilation and a re-captured launch graph |
| One agent dominant | An agent's deficit exceeds its quantum while others wait | Serve the others first | Unfairness |
| Estimates unreliable | Of the last 50 jobs, 20% ran over twice their estimate; or a resume digest differed | Fall back to round-robin per agent and run to completion; on a digest difference also fall back to per-job dispatch and raise an alarm | Misclassified long jobs; a broken invariant |
Loss, in seconds: L = Σ_j c(j)·wait_j + (idle slot-seconds ÷ B) + Σ_a max(0, deficit_a) + Σ preemption cost, with c = 1 for interactive and 0.1 for batch jobs and the preemption cost equal to its measured snapshot and restore time (DESIGN defaults; nothing here is measured, and the weights are refitted from the M2 queue trace). Three rules keep the scheduler from interfering with evidence. It decides when, never what: e-processes consume episodes in address order, so random preemption and reordering leave digests and verdicts identical. No effort profile of a solver reads the wall clock or changes inside a run. No adaptive rule ships without a replay scenario, evidence records, a calibration report and a demonstrated fallback. Kill gate KILL-PREEMPT.
32.12 The MCP server
frob-mcp is built on fastmcp_rust and is an ordinary member of the core workspace build graph: it links
frob-verbs and calls verb implementations in process (§32.12.2). Text that arrives from imports (design names,
asset metadata, scan annotations) is data and is never interpreted as instructions (§37.3).
32.12.1 What the library is today
All rows are FACT, observed on 2026-11-21 at fastmcp_rust commit 117388bc; paths are relative to that
repository unless another is named.
| Fact | Path |
|---|---|
Workspace version 0.13.0, edition 2024, rust-version = "1.100", toolchain nightly-2026-08-25, unsafe_code = "forbid", exact version pins. Crates: the facade fastmcp-rust, fastmcp-core, fastmcp-protocol, fastmcp-transport, fastmcp-server, fastmcp-client, fastmcp-derive (macros), fastmcp-console, fastmcp-cli. Licence: MIT with a rider. |
Cargo.toml, rust-toolchain.toml, LICENSE |
The source tree pins asupersync = "=0.6.2" since 2026-11-09. The package published as fastmcp-rust 0.13.0 on 2026-10-12 resolves with asupersync 0.5.0. The only supported runtime is asupersync. |
Cargo.toml, UPGRADE_LOG.md; mcp_agent_mail_rust/Cargo.lock |
Handlers are declared with the attribute macros #[tool], #[resource] and #[prompt]; #[derive(JsonSchema)] supplies argument schemas. The macro on fn greet generates the handler value Greet. #[tool] accepts name, description, tags, icon, version, timeout, defaults(..), input_schema, output_schema, error_mapper, tasks, and the flags read_only, idempotent, destructive, open_world_hint. |
crates/fastmcp-macros/src/lib.rs |
A tool may instead be a hand-written impl ToolHandler: definition() -> Tool, call, call_async returning the four-valued McpOutcome (Ok, Err, Cancelled, Panicked), execution_mode() -> ToolExecutionMode (Blocking or Async), timeout(), tags(), annotations(), output_schema(), and final_tool_error_structured_content for the two framework error kinds ToolErrorKind::{InputValidation, Handler}. |
crates/fastmcp-server/src/handler.rs |
Tool has name, description, input_schema, output_schema, icon, version, tags, and annotations: ToolAnnotations { destructive, idempotent, read_only, open_world_hint }. Results are Content::{Text, Image, Audio, Resource}. Resources are Resource, ResourceTemplate (an RFC 6570 uriTemplate) and ResourceContent { uri, mime_type, text, blob } with blob in base64. |
crates/fastmcp-protocol/src/types.rs |
The builder is ServerBuilder::new(name, version), under auto:: (serves MCP 2026-07-28 and the exact 2024-11-05 handshake) or modern:: (2026-07-28 only). Methods used here: .tool, .resource, .resource_template, .prompt, .instructions, .request_timeout (default 30 s), .list_page_size, .strict_input_validation, .mask_error_details, .on_duplicate, .middleware, .rate_limiting, .auth_provider, .subscription_capacity, .task_supervisor, .final_tasks, .on_startup, .on_shutdown, .try_build. |
crates/fastmcp-server/src/builder.rs, README.md |
Transports: stdio through run_stdio_with_cx (a blocking pump) or, on Unix, serve_stdio_io over NativePipeReader::from_stdin and NativePipeWriter::from_stdout (reactor-driven, no blocking pool); HTTP through run_http_with_cx, bind_http, serve_http; WebSocket through bind_websocket and serve_websocket behind an experimental feature; legacy SSE through run_sse_with_cx; an in-memory transport for tests. |
crates/fastmcp-server/src/lib.rs, crates/fastmcp-transport/src/lib.rs, README.md |
McpContext offers checkpoint(), masked(..), budget() (deadline, poll quota, cost quota), is_cancelled(), report_progress, report_progress_with_total, report_progress_exact, has_progress_reporter(), get_state, set_state, disable_tool, enable_tool (per session; a change emits a catalog-changed notification), notify_resource_updated, auth(), join_all, race, and cx() for the asupersync Cx. |
crates/fastmcp-core/src/context.rs |
tools/list omits a session's disabled tools and honors the request's includeTags (all of) and excludeTags (any of). list_page_size pages every list method behind an opaque nextCursor. |
crates/fastmcp-server/src/router.rs, crates/fastmcp-protocol/src/messages.rs |
The 2026-07-28 Tasks methods tasks/get, tasks/update and tasks/cancel run on a process-local in-memory store unless final_tasks supplies one, and task creation needs task_supervisor. The README calls the extension experimental and the implementation provisional. |
README.md |
Stated limits. MCP 2026-07-28 support "is under implementation and remains unverified". Wire cancellation is partly qualified: Unix stdio and native WebSocket route a cancellation while a handler runs; non-Unix stdio, SSE and custom transports keep blocking boundaries; a handler that does not cooperate can outlive the bounded process-exit drain. OAuth and OIDC surfaces are unpromoted. Native HTTP accepts credentials only in Authorization. One measured run (2026-10-12, revision 1c2dc896) passed 112 of 115 named server-mode checks with no failure, which the README says is not a conformance claim. |
README.md |
A consumer in the suite, mcp_agent_mail_rust, registers 45 #[tool] and 32 #[resource] handlers through fastmcp_server::Server::new(..); wraps each tool in a hand-written ToolHandler decorator (InstrumentedTool); maps tools to named clusters (TOOL_CLUSTER_MAP) filtered when the server is built; serves a cluster directory as resource://tooling/directory; and uses templated resource URIs such as resource://agents/{project_key}. It pins the registry package with asupersync 0.5.0 on nightly-2026-08-31. |
mcp_agent_mail_rust/Cargo.toml, .../crates/mcp-agent-mail-server/src/lib.rs, .../crates/mcp-agent-mail-tools/src/{lib.rs,resources.rs} |
32.12.2 The build graph
FACT, the starting state: FrankenSim pins nightly-2026-07-06, which its own toolchain file identifies as rustc
1.99.0-nightly (frankensim/rust-toolchain.toml), and fastmcp_rust declares rust-version = "1.100" and pins
nightly-2026-08-25. As found, the two do not build on one compiler. FACT: the registry package 0.13.0 carries
asupersync 0.5.0 while FrankenSim consumes asupersync by path (0.6.2 today) and FrankenTorch requires 0.6.2.
DESIGN. Both mismatches are fixed in the siblings, by this program, at M0 (§33.8, §33.13). FD-FMCP-01 brings
fastmcp_rust onto T, the one toolchain of the build graph, with its own test suite and its MCP conformance
checks passing there. FD-ASUP-01 aligns FrankenSim's constellation, FrankenTorch and fastmcp_rust on one
published asupersync version.
surface/frob-mcp is then an ordinary member of the core workspace. Its source stays under surface/ because it
is a surface, not because it is a separate workspace. It depends on fastmcp_rust by commit, at or after
117388bc, never on registry 0.13.0, so that one asupersync package is possible. It links frob-verbs and calls
verb implementations in process through the dispatch trait (ADR-TETHER-03), and it shares the one toolchain and
the one asupersync package with the rest of the graph. Long work goes to frobd as a job, as it does from the
CLI; with no daemon running, CPU-tier verbs run in process and the envelope says so (§32.11). frobd --mcp hosts
the same server inside the daemon.
INT-FMCP-01 (§33.6; admission, M0): frob-mcp builds in the core graph on T with exactly one asupersync package
(cargo tree -d shows no duplicate), lists the tools generated from the verb registry, and passes the MCP
protocol smoke test over stdio and HTTP. KILL-MCP (§32.21) applies only if that gate cannot pass within the M0
budget after FD-FMCP-01 and FD-ASUP-01 have been attempted. Its first fallback is frob-mcp as its own
workspace, linking frob-verbs with registry-only (ADR-TETHER-02) and talking to frobd over a local socket in
newline-delimited JSON; its second is the CLI alone.
32.12.3 How a registry entry becomes a tool definition
frob-mcp contains one generic handler, VerbTool, and constructs one instance per admitted registry entry at
startup. There is no macro per verb; the attribute macros are used only for the hand-written handlers: resources,
prompts, and the part of session.focus that edits the visible tool set.
Tool field |
Derived from the registry entry |
|---|---|
name |
The verb name with . and - replaced by _: design.check becomes design_check, telemetry.inspect-pixel becomes telemetry_inspect_pixel. No registry name contains an underscore, and a registry lint checks that the map is one-to-one. |
description |
Generated: one sentence of purpose, when to use it, the cost class, the refusal codes, one example. At most 800 characters (TARGET); the long form is the resource frob://docs/verb/{name}. |
input_schema |
The verb's input schema, plus common properties by kind: run adds sync_wait_ms, idempotency_key, budget, estimate_only, on_cancel; mutate adds idempotency_key and expected_parent. |
output_schema |
frob.envelope/1 with result specialized to the verb's output schema. |
tags |
cluster:<name>, kind:<kind>, task:<task cluster> for each task cluster it belongs to, tier:S, F or M. |
annotations |
read_only for kind read; idempotent from the registry's idempotency rule; destructive only for admin verbs that delete; open_world_hint: false, since every verb acts on the local store. |
version |
The schema version of the entry. |
The server is built with .on_duplicate(DuplicateBehavior::Error) and .try_build(), so a name collision fails
the build; with .strict_input_validation(true), so a misspelt parameter is a refusal and not a default (§35);
and with .mask_error_details(true). Because each tool declares an output schema, the handler supplies envelope
skeletons for the library's two framework error kinds (exit 3 with FROB-REF-802 for input validation, exit 9
for a handler fault), which the library validates against the schema at registration (FACT:
crates/fastmcp-server/src/handler.rs). A domain refusal is returned as a tool error whose structured content is
the full envelope. GATE-TETHER-02 diffs the served tools/list against the registry.
32.12.4 Task clusters of at most seven, and how an agent switches S
A registry cluster can be large (design has ten verbs, analyze sixteen or more). What an agent sees is a task
cluster: at most seven tools chosen for one activity, declared in the registry beside the verbs. A verb may sit in
several task clusters, and a lint requires every verb to sit in at least one. The table lists the principal clusters;
the registry holds the full assignment, including an operate cluster for the job, artifact, device and session
verbs. Three base tools are always listed and are not counted: session_focus, job_wait, job_cancel.
| Task cluster | Activity | Tools |
|---|---|---|
orient (default) |
Find out what exists | capabilities, doctor, robot_docs, schema, design_templates, scene_list, session_show |
author |
Make and change a design | design_new, design_show, design_edit, design_diff, design_check, design_import, control_synth |
analyze-body, analyze-motion, analyze-budget |
Static questions | The analyses of §28, at most seven per cluster |
simulate |
Estimate, run, look | sim_estimate, sim_run, sim_replay, run_fork, telemetry_summary, telemetry_failures, telemetry_stills |
diagnose |
Why it failed | explain_run, autopsy_intervene, autopsy_attribute, autopsy_show, telemetry_query, telemetry_inspect_pixel, telemetry_energy |
compare |
Paired studies | study_plan, study_submit, study_status, study_compare, eval_promote, experiment_suggest, predict_register |
mission |
Inverse design | mission_new, mission_check, mission_synthesize, mission_refute, mission_distinguish, mission_show, result_revalidate |
attack |
Adversarial worlds | nemesis_search, nemesis_shrink, mission_separate, nemesis_bound, nemesis_oracle, nemesis_hardset, scene_show |
qualify |
The blinded lane and certificates | eval_qualify, eval_scorecard, eval_ledger, prove_bundle, prove_verify, report_design, prove_list |
learn |
Training | train_start, train_status, train_stop, train_export, eval_run, sim_estimate, telemetry_summary |
places |
Scenes | scene_gen, scene_import, scene_compile, scene_list, scene_show, telemetry_stills, design_check |
search |
Optimization and lineage | opt_start, opt_status, opt_archive, design_bisect, design_blame, solve_run, experiment_suggest |
reality |
Calibration | ground_ingest, ground_identify, ground_predict, ground_score, ground_band, predict_report, report_run |
make |
Structure and manufacture | foundry_size, foundry_optimize, foundry_check, foundry_tolerance, foundry_export, prove_bundle, report_design |
Switching. session_focus {cluster} enables the tools of the target cluster and disables those of the previous one
with McpContext::enable_tool and disable_tool. The library then omits disabled tools from tools/list, refuses a
direct call to one, and emits its catalog-changed notification (FACT, §32.12.1). The result of session_focus also
lists the names and one-line purposes of the now-visible tools, for clients that do not act on the notification. Focus
is about context size, not authority: authority is the token (§32.13). Three fallbacks, in order: when a connection
has no session state, disable_tool reports failure (FACT) and the client instead filters the list by the tag
task:<cluster> through includeTags; a launch flag --clusters fixes the listed set when the server is built, as
the suite's mail server does; and a compatibility flag exposes one generic tool, verb_invoke {verb, arguments},
validated against the verb's schema, for clients that never re-list. TARGET: the definitions of the base tools plus
one task cluster occupy at most 12 kB of tools/list.
32.12.5 The bounded synchronous wait S
Every tool whose registry kind is run accepts sync_wait_ms: default 5,000, maximum 30,000, 0 for an immediate
handle (DESIGN values, OPEN-TETHER-3; out of range is FROB-REF-802). The handler submits the job under its
idempotency key (§32.7), then waits on the job's completion against the timer. If the job finishes, the envelope
carries the result with exit 0 or 2. If the timer wins, the envelope carries exit: 8 and the job handle with its
progress, an interval for the time remaining and poll_after_ms; next_actions names job_wait. job_wait takes
the same parameter, so an agent can hold a job with a sequence of bounded waits. The server is built with
.request_timeout(40) (DESIGN: the library's default ceiling of 30 s would coincide with the maximum wait; 10 s of
margin covers admission and serialization). On the CLI the default is to wait to completion with progress events;
--sync-wait-ms bounds the wait and exits 8. The per-surface default is a registry field, so the parity gate knows
about it.
32.12.6 Progress and cancellation
Progress. Each daemon progress frame becomes ctx.report_progress_with_total(done, total, Some(message)), or
report_progress_exact when a count needs its exact spelling. Every event has a numerator, a denominator and a
unit (episodes, pairs, rungs, cells). When the client sent no progress token the call is a no-op (FACT).
Cancellation. A verb that runs in process receives the call's Cx (ctx.cx()) and observes cancellation at its
own checkpoints. A handler for a long tool does no device work: it submits a job, waits on the job's frames and
calls ctx.checkpoint() at each one, so it always cooperates with the library's cancellation, including on
transports where that is only checked at a checkpoint. A cancelled wait returns nothing and leaves the job running
(ADR-TETHER-05) unless the call set on_cancel: "cancel_job". job_cancel asks the daemon to cancel; the daemon
drains at the kernel-batch boundary and the receipt names the last committed tick (§32.10). The drain is done by
the daemon's job engine, which owns the device, so the library's unqualified process-exit drain is never the
mechanism that protects device state (INV-TETHER-10).
Tasks adapter F. Where a client negotiates the 2026-07-28 Tasks extension, a run tool may also surface its
job as an MCP Task through an application-owned store backed by the job ledger, so task identifiers survive a
restart of frob-mcp. Ceiling: no compute is saved; the benefit is client-native progress display, bounded by
the number of long jobs in a session. Pilot: 20 scripted jobs over the in-memory transport, comparing Task
states with the ledger; one disagreement falsifies it. Kill gate KILL-MCPTASKS; the handle contract remains.
32.12.7 Resources
Catalogs, stills, reports and schemas are MCP resources under the scheme frob://. A resource URI names a
registry row or a content-addressed object in the store. It is never a filesystem path (§37.6).
| URI | Contents | Form |
|---|---|---|
frob://docs/guide, frob://docs/clusters, frob://docs/verb/{name} |
The agent guide, the task-cluster directory, long verb documentation | Text |
frob://capabilities, frob://registry/verbs, frob://registry/refusals |
What is implemented in the §0.2 sense; the registry; the refusal table | JSON |
frob://schema/{schema_id} |
A schema with a minimal valid example | JSON |
frob://catalog/{kind} |
Catalogs: archetypes, templates, actuators, interfaces, materials, parts, scenes, tasks, fixtures, retrofits, counterexamples, reference-robots |
JSON, paged |
frob://still/{run}/{world}/{instant} |
A still or contact sheet, with overlays (§32.15) | PNG, as blob |
frob://report/{id}, frob://cert/{id} |
A report index; a certificate bundle's manifest | Text, JSON |
frob://job/{id}, frob://run/{id}/summary |
Job state and log tail; a token-budgeted run summary | JSON, text |
Templated URIs use the library's resource templates. A client that subscribes to frob://job/{id} is notified
through notify_resource_updated when the job changes state, which replaces polling where the client supports
it; the listener capacity is set with subscription_capacity and is at most 64 streams server-wide (FACT,
fastmcp_rust/README.md). A resource read returns at most 4 MiB (TARGET); larger artifacts are read with
artifact.read by byte range or exported under the session's export root. An object derived from a private
scene is not listed and is refused without the private:read scope (FROB-REF-731).
32.12.8 Prompts
Standard workflows are MCP prompts declared with #[prompt], generated from the same worked examples as
robot-docs: studio_loop (check, edit, synthesize, estimate, run, explain, compare, promote),
mission_query (author a query, check it, synthesize, read the sets, refute, revalidate), diagnose_failure
(failures, stills, autopsy, an intervention), qualify_design (plan, commit, submit, read the receipt),
compare_designs, import_robot and calibrate_to_reality. Prompt arguments are strings (FACT) and are
accepted only if they match an identifier pattern; no prompt interpolates imported text (INV-TETHER-13).
32.12.9 Transports
| Transport | Offered | Use | Notes |
|---|---|---|---|
| stdio | Yes, the default | An agent harness launches frob-mcp as a subprocess |
On Unix the reactor-driven pairing; elsewhere the blocking pump. The session token comes from the environment. |
| Streamable HTTP on loopback | Yes | A swarm shares one server, which frobd --mcp can host |
Bound to 127.0.0.1 unless configured. A bearer token in Authorization, checked by an AuthProvider, maps to the session's capability token. The library's OAuth surfaces are not used. |
| WebSocket | Behind a flag, unsupported | Experiments only | The library marks it experimental. |
| Legacy SSE | No | — | HTTP covers it; the library's SSE path lacks split routing and resumption. |
| In-memory | Tests only | Conformance tests without a process | — |
The protocol policy is the library's automatic one, which serves 2026-07-28 clients and the exact 2024-11-05 handshake. OPEN-TETHER-2 records the risk that a client speaks neither.
32.12.10 A tool in the library's style
DESIGN. The sketch fixes intent, not signatures. It shows the generic handler and the bounded wait.
// surface/frob-mcp: one handler type serves every registry verb. `Dispatch` is the in-process back end by
// default: it runs the verb through frob-verbs in this process and hands long work to frobd as a job.
struct VerbTool { entry: &'static VerbEntry, dispatch: Arc<dyn Dispatch> }
impl ToolHandler for VerbTool {
fn definition(&self) -> Tool {
Tool { name: self.entry.tool_name(), // "sim_run"
description: Some(self.entry.short_doc()), // generated, at most 800 characters
input_schema: self.entry.input_schema_with_common_fields(),
output_schema: Some(self.entry.envelope_schema()),
tags: self.entry.tags(), // ["cluster:sim", "kind:run", "task:simulate"]
annotations: Some(self.entry.annotations()), // read_only, idempotent, destructive
version: Some(self.entry.schema_version()), icon: None }
}
fn execution_mode(&self) -> ToolExecutionMode { ToolExecutionMode::Async }
fn call(&self, _: &McpContext, _: Value) -> McpResult<Vec<Content>> {
Err(McpError::new(McpErrorCode::InternalError, "async-only handler"))
}
fn call_async<'a>(&'a self, ctx: &'a McpContext, args: Value)
-> BoxFuture<'a, McpOutcome<Vec<Content>>> {
Box::pin(async move { outcome(self.run(ctx, args).await) })
}
}
impl VerbTool {
async fn run(&self, ctx: &McpContext, args: Value) -> McpResult<Vec<Content>> {
ctx.checkpoint()?; // cancellation point before any charge
let req = self.entry.resolve(args, ctx.auth())?; // names to identifiers, defaults, digest
let wait = req.sync_wait_ms(); // 0..=30_000, default 5_000
let mut job = self.dispatch.submit(ctx.cx(), &req).await?; // one atomic binding; replay-safe
let deadline = Deadline::after_ms(wait);
while let Some(frame) = job.next_frame(ctx.cx(), &deadline).await? {
ctx.checkpoint()?; // a cancelled wait leaves the job running
match frame {
Frame::Progress(p) => ctx.report_progress_with_total(p.done, p.total, Some(&p.unit)),
Frame::Envelope(e) => return e.into_tool_result(), // exit 0 or 2, or isError with a refusal
}
}
Envelope::deferred(job.handle()).into_tool_result() // exit 8: job handle, progress, poll_after_ms
}
}
32.13 Capabilities, namespaces and many agents
A session holds a capability token with scopes such as design:write, sim:run, gpu:seconds=600,
scene:import and train:run. Each agent has its own design namespace and lineage; no agent can rewrite
another's history. A shared leaderboard and archive are read-only views. Lineage identifiers are usable as Agent
Mail thread identifiers, so a swarm can coordinate with the tools it already has.
- Scopes separate reading from spending from publishing:
<cluster>:read,<cluster>:run,study:submit,mission:run,nemesis:run,autopsy:run,qual:run(§24.13),cert:write,ground:import,export:report,export:packet,export:policy,private:read,private:export,job:cancel, and budgets (gpu:seconds=N,cpu:core_seconds=N,disk:bytes=N). No scope grants reading a confirmation world (§37.5). - Tokens are minted by
frobdatsession.open, authenticated with a daemon key, and can be attenuated: a holder may derive a token with fewer scopes and a smaller budget for a sub-agent, never a wider one (FROB-REF-723). The budget of a derived token is debited from its parent. - Namespaces. A write outside the caller's namespace is
FROB-REF-725. The shared archive is a grow-only set keyed by content address, merged by union; the leaderboard breaks ties by a total order (metric, then content address), so two daemons that merge reach the same view.
32.14 The dashboard
frob-tui is a terminal dashboard built on FrankenTUI. FACT (frankentui/README.md, Cargo.toml, observed
2026-11-21): workspace version 0.10.0 on nightly-2026-08-31; an Elm-style runtime (Model, Cmd) in
ftui-runtime; inline mode (ScreenMode::Inline) that keeps scrollback; a pane workspace (PaneTree in
ftui-layout); widgets Table, Sparkline, ProgressBar, Tree, Tabs, LogViewer, JsonView and StatusLine
in ftui-widgets; BarChart and LineChart in ftui-extras; a test harness with shadow-run comparison and
determinism fixtures in ftui-harness. FACT: ftui-runtime has an optional asupersync-executor feature pinned to
asupersync 0.5.0 (crates/ftui-runtime/Cargo.toml); it stays off so the build keeps one asupersync package.
| Pane | Shows | Source verb |
|---|---|---|
| Races | Survival brackets of each race and ladder rung; per pair, the e-value, pairs used of the cap, and the verdict; cancelled candidates | opt.status, study.status |
| Budgets | Per agent: GPU seconds, CPU core-seconds and disk spent and left; the qualification error budget with each submission's α_i = α/[i·(i + 1)] and the sum spent | session.show, eval.scorecard |
| Devices | Per device: a slot strip colored by job and agent, the reserve, environments by shape class, arena and kernel-cache use, the requested and actual placement of each stage, temperature on the Mac | spark.devices, job.list |
| Queue | Jobs by size class with wait, estimate against actual, the calibration of the estimate interval, preemptions | job.list |
| Failures | Latest autopsies with their first cause and stability; new minimal counterexample worlds | autopsy.show, nemesis.hardset |
| Evidence | Promotions, results still provisional, alarms from the fidelity ledger and the exchangeability monitor | eval.scorecard, telemetry.summary |
The dashboard issues only read verbs, plus job.cancel under a token that holds that scope and after a
confirmation. It has no private interface (ADR-TETHER-10). It is optional: nothing depends on it, and its kill
gate KILL-TUI has the fallback "no dashboard".
32.15 The viewer and its overlays
This section holds the viewer text, and §20.10 points here. The page is Three.js r186 and consumes telemetry
snapshots. Replays are exported as self-contained HTML by telemetry.export-html, a verb of the telemetry cluster of
§29 (§29.12); the packet is specified in §32.24. Where the
page stays inside FrankenThreeD's admitted feature subset it is packaged through FrankenThreeD's build route
(node tools/ingest/cli.mjs app.html --build-app out --pack-html replay.html); otherwise it ships as plain
Three.js. FACT about FrankenThreeD today: phase 0/1, a general WebGPU route that matches pinned Three.js pixels
for ten scenes on a software Vulkan driver, numeric-island specialization only, and no measured speedup, so it is
a packaging route and a future accelerator, not a dependency. The viewer never feeds anything back to physics: the
simulator owns state and the viewer reads immutable snapshots. FACT: FrankenThreeD has four crates, and its
f3d-runtime pins asupersync 0.5.0 (franken_threed/crates/f3d-runtime/Cargo.toml), so nothing in the core may
link it. A native viewport on the Mac is a possible later addition F; this plan funds no work package for it.
Overlays draw physical quantities, each from a named telemetry channel with its unit, a numeric legend and the evidence class of the run. An overlay is a pure function of the snapshot.
| Overlay | Quantity | Source |
|---|---|---|
| Contact cones | The four-dimensional cone at each contact (normal, two tangential, spin) with friction utilization as color; the contact wrench as an arrow | §18 |
| Film and friction map | Film thickness and effective friction on floors, including film the robot has moved | §18, §19 |
| Clearance | Doorways and passages of a clearance complex, passable or not, with the bottleneck named | §19 |
| Energy flow | Power per actuator, losses by kind, dissipation at contacts; the numerical residual as its own bar | §29 |
| Actuator state | Torque and speed utilization against the card; winding temperature | §15 |
| Balance | Centre of mass, support polygon, margin to tipping | §22, §28 |
| Sensing | Frusta and rays with occlusion; the seven instants of a sample on a timeline | §20 |
| Counterfactual ghost | A fork drawn over its parent, diverging from the first different event | §27 |
| World difference | The edits that separate a minimal counterexample world from its nominal world | §26 |
| Reality band | The calibrated band around a predicted trace, or the words "no claim" | §30 |
Stills carry the same overlays (telemetry.stills --overlay contact-cones,film), and telemetry.inspect-pixel
returns the quantity under a pixel with its unit, channel and world address, so an agent that cannot see still
reads every overlay. An exported replay is one HTML file of at most 15 MB (TARGET) with Three.js vendored by
hash and no network fetch.
32.16 Two sessions, end to end
Numbers in both transcripts are illustrative.
$ frob design new quad-a --template quadruped-12dof --json # exit 0, design d:41aa…
$ frob design check quad-a --json # exit 2: knee undersized (A-11)
$ frob design edit quad-a swap-actuator --joints '*.knee' --to qdd-l # new version d:7c03…, symmetry preserved
$ frob design check quad-a --json # exit 0: closes at 15.1 kg
$ frob control synth quad-a --json # ok: trot from the atlas
$ frob sim estimate quad-a --scene terrain:stairs@0.4 --worlds 2048 --seconds 20 --tier gpu-cuda
# 38 GPU-seconds, 90% interval 31 to 47; 3.1 GB
$ frob predict register --metric success --interval 0.6 0.9 --confidence 0.8 --for next
$ frob sim run quad-a --scene terrain:stairs@0.4 --worlds 2048 --seconds 20 --tier gpu-cuda --json
# exit 2: success 0.44, provisional
$ frob explain run r:19e2… --budget 600 # first cause: slip on stair nosing;
# friction utilization p95 = 1.0 at front feet
$ frob telemetry stills r:19e2… --world 311 --at failure # contact sheet PNG
$ frob design edit quad-a set-param foot.radius 0.022 0.030
$ frob eval compare quad-a@prev quad-a --task stairs-0.4 # B better, e = 310, n = 96 pairs, provisional
$ frob eval promote r:… --tier referee --json # established, inside the envelope
The second session asks a mission query instead of scoring one design.
$ frob session open --scopes design:write,mission:run,nemesis:run,autopsy:run,sim:run,qual:run \
--budget gpu_s=1800,cpu_core_s=7200 --json # exit 0: session s:2f6a…, namespace agent-17
$ frob mission new carrier-wet-strip --template delivery-and-placement --json
# exit 0: query q:5b1e… (.fmission)
$ frob mission check q:5b1e… --json # exit 0: domain nonempty; ∃ policy per design,
# ∀ worlds, ∀ executions; 2 topologies, 412 cells
$ frob mission synthesize q:5b1e… --estimate --json # 640 GPU-seconds, 90% interval 512 to 800
$ frob mission synthesize q:5b1e… --budget gpu_s=900 --key syn-1 --sync-wait-ms 5000 --json
# exit 8: job j:77c0…, 0 of 412 cells
$ frob job wait j:77c0… --json # exit 2: inner 61 cells; outer 233 of 412;
# 179 excluded with witnesses; 172 unresolved
$ frob mission show q:5b1e… --set inner --order cost --limit 3 --json # cheapest inner cell c:0007, part cost 1,480
$ frob mission show q:5b1e… --set unresolved --order cost --limit 3 --json
# cheapest unresolved cell c:0204, cost 1,120;
# next_test: attack c:0204's best controller
$ frob mission refute q:5b1e… --cell c:0119 --json # excluded for every controller: the loaded
# width cannot pass the door; smallest
# relaxing change: track −14 mm
$ frob design new carrier-b --from-cell q:5b1e…/c:0204 --json # design d:a3f1… at the cell centre
$ frob nemesis search carrier-b --mission q:5b1e… --budget gpu_s=240 --key nem-1 --json
# exit 2: 3 failing worlds inside the family
$ frob nemesis shrink w:9d04… --key shr-1 --json # exit 2: .fmcw, 2 edits from nominal: counter
# lip 18 → 22 mm; wet strip 40 mm before it
$ frob autopsy intervene r:5c11… --key aut-1 --json # exit 2: holding strip friction at its dry
# value removes the failure in 60 of 64 forks;
# the placebo flips 2 of 64; stable
$ frob design edit carrier-b set-param wheel.radius 0.055 0.065 --key ed-1 --json
# new version d:b77e…
$ frob result revalidate carrier-b --since d:a3f1… --json # 14 of 19 prior results inherited;
# 5 need rerun, 41 GPU-seconds
$ frob nemesis search carrier-b --mission q:5b1e… --budget gpu_s=240 --key nem-2 --json
# exit 0: none in 4,096 worlds; not a certificate
$ frob eval qualify carrier-b --mission q:5b1e… --dry --json # submission 1 of this lane: α₁ = 0.025;
# 200 sealed worlds; qualified is reachable
# only with at most 3 failures
$ frob eval qualify carrier-b --mission q:5b1e… --key qual-1 --json # exit 0: qualified, 1 failure of 200; receipt
# qr:e2a0…; no per-world data returned
$ frob prove bundle carrier-b --mission q:5b1e… --receipt qr:e2a0… --out carrier-b.frobcert --json
$ frob-verify carrier-b.frobcert # offline: bundle checks; all three
# authorization flags false
Four points of the second session are rules, not illustrations. The inner set contains only cells with a constructive witness, so the agent tests the cheaper unresolved cell instead of trusting it. A rollout that fails refutes one controller, not the design, and the envelope says so. The qualification arithmetic is exact on its illustrative inputs: with requirement "failure probability at most 0.05", total α = 0.05 and 200 sealed worlds, the one-sided exact binomial bound at α₁ = 0.025 admits at most 3 failures (bounds 0.0432 at 3 and 0.0504 at 4), and a second submission at α₂ = α/6 would admit at most 2 (0.0425 at 2 and 0.0505 at 3), so each retry costs power, by design (§24). And the discovery scopes in the token give no way to read the 200 sealed worlds (§37.5).
32.17 Documentation for agents
frob robot-docs prints the guide, the verbs, the schemas and worked examples; --cluster prints one task
cluster. frob capabilities --json lists what is implemented in the §0.2 sense and what is not, with resolved
modes and ceilings per device. frob schema <kind> returns a schema and a minimal valid example. frob doctor
checks toolchains, foundation pins, devices, kernel caches and probe status. A skill file documents the design
loop for agents that load skills, in the way FrankenTextiles ships its fitting loop (FACT). The MCP resources
under frob://docs/ and the prompts are generated from the same source, so the three cannot drift. Summaries are
sized to a token budget with handles for drill-down, and a compact encoding is available (§29).
32.18 Refusals
| Code | Refusal | Exit |
|---|---|---|
FROB-REF-701 |
The estimate's upper end exceeds the remaining budget; the estimate is attached | 4 |
FROB-REF-702 |
Budget exhausted during a run; stopped at a safe boundary; nothing partial published | 4 |
FROB-REF-703 |
Admission guard: device utilization or the per-environment job cap is reached; retry: backoff |
4 |
FROB-REF-704 |
A campaign-class job without an approved compute envelope | 4 |
FROB-REF-720 |
The session token lacks a required scope | 5 |
FROB-REF-724 |
The verb is not implemented in the §0.2 sense in this build | 5 |
FROB-REF-725 |
A write outside the caller's namespace or lineage | 5 |
FROB-REF-723 |
Token invalid or expired, or an attenuation that would widen scopes or budget | 5 |
FROB-REF-801 |
Unknown verb (CLI) | 3 |
FROB-REF-802 |
Arguments fail the schema, including an unknown parameter or an out-of-range sync_wait_ms |
3 |
FROB-REF-803 |
Idempotency key reused with different resolved content | 7 |
FROB-REF-804 |
Stale parent: the expected parent is not the head of the lineage | 7 |
FROB-REF-805 |
A mutating or job-submitting verb without an idempotency key | 3 |
FROB-REF-806 |
Cursor does not match the query | 3 |
FROB-REF-807 |
Cursor expired: its frontier is no longer retained | 3 |
FROB-REF-808 |
An integer outside ±(2⁵³ − 1) in a number-typed field | 3 |
FROB-REF-809 |
Plan not found, or bound to an identity that has since been superseded | 7 |
FROB-REF-810 |
Chunk conflict: different bytes for a committed extent | 9 |
Three standing rules of §35 apply at this boundary: refuse, never truncate; a budget stop publishes nothing partial as a result; a misspelt parameter is a refusal, not a default.
32.19 Invariants and proof obligations
| ID | Statement |
|---|---|
| INV-TETHER-01 | Every surface is generated from the registry. No verb, flag, schema or refusal exists on one surface and not the other, except per-surface defaults declared in the registry and the unknown-verb case of §32.5. |
| INV-TETHER-02 | With --json, exactly one envelope per invocation; malformed input and unknown verbs produce it. Exit code 1 is never emitted on purpose. |
| INV-TETHER-03 | After a budget stop or a cancellation nothing partial is published as a result; the acknowledgement names the last committed tick. |
| INV-TETHER-04 | The four terminal counts of a job sum to its planned trials; the five pair counts of a comparison sum to its planned pairs. |
| INV-TETHER-05 | One job and one budget charge per (principal, verb, idempotency key), under any interleaving and any crash point. |
| INV-TETHER-06 | The pages of one cursor sequence, concatenated, equal the query's rows at the pinned frontier: none skipped, none repeated. |
| INV-TETHER-07 | No integer travels as a JSON number unless its schema type is int53 and its value is within ±(2⁵³ − 1). |
| INV-TETHER-08 | A world's digest and results depend on its address and identities, never on its slot, its co-tenants, dispatch order, preemption or resumption. |
| INV-TETHER-09 | The scheduler decides when work runs, never what is computed; no wall-clock quantity enters a result or an evidence record. |
| INV-TETHER-10 | Killing frob, frob-mcp or frob-tui at any instant leaves the daemon's ledger consistent and every admitted job discoverable by its key. |
| INV-TETHER-11 | A cancelled wait is not a cancelled job unless the call asked for that; a cancelled job drains. |
| INV-TETHER-12 | The viewer and the dashboard read immutable snapshots through verbs; turning either on or off changes no physics digest (with GATE-SENS-03). |
| INV-TETHER-13 | No tool description, prompt, server instruction or next_actions.command contains text that originated in an import. |
| ID | Obligation | Verification |
|---|---|---|
| PO-TETHER-01 | The admission transaction of §32.7 yields INV-TETHER-05. | Exhaustive interleavings of two submitters and one crash over the four steps on the deterministic runtime; the two-statement variant must fail (negative control). |
| PO-TETHER-02 | Keyset pagination over a total order restricted to a fixed frontier partitions the snapshot. | Induction on pages, written in the crate's CONTRACT.md; property test under random appends. |
| PO-TETHER-03 | Slot dispatch preserves digests. | The purity argument of §32.11.1; golden co-tenancy test of GATE-TETHER-09. |
| PO-TETHER-04 | The estimate interval covers with probability at least 1 − α under exchangeability. | The rank argument; empirical coverage in GATE-TETHER-11. Class: Tested. |
| PO-TETHER-05 | With linear ageing no admitted job waits forever. | After 600 s a job's key is the minimum; ties break by admission order. Model check on the guard table. |
32.20 Known answers and counterexamples
| Known answer | Expected |
|---|---|
| Exit-code table on a fixture of malformed, unknown, over-budget, unscoped and conflicting inputs | The exit and refusal code of §32.4 and §32.18 for each |
2⁵³ + 1 through a double-decoding client, as int53 and as u64str |
Refused as int53; preserved exactly as u64str |
| Pair accounting on a planted comparison | a_only + b_only + both + neither + unscored = planned |
| The M/G/1 table of §32.11.2 against a discrete-event simulation of the dispatcher | Each cell within 5% at 10⁶ simulated jobs (TARGET) |
| Conformal index at n = 19, α = 0.05 | The 19th smallest residual, that is, the largest |
| Error budget of the blinded lane | Σ_{i=1..n} α/[i·(i + 1)] = α·n/(n + 1) < α |
| Slot share of a 96-pair comparison in 8,192 worlds | 192 ÷ 8,192 = 2.34% |
| Exact binomial bound, 200 worlds, α = 0.025 | Upper bounds 0.0183, 0.0275, 0.0357, 0.0432, 0.0504 for 0 to 4 failures |
Counterexamples entered in the negative-control registry: the two-statement idempotency check (§32.7); offset pagination under appends and a time-only cursor (§32.8.1); 2⁵³ + 1 (§32.8.2); range-keyed chunks after a shard split and a (world, tick) key across a reset (§32.10); priority without preemption (§32.11.2).
32.21 Gates
| Gate | Claim | Threshold (TARGET) |
|---|---|---|
| GATE-TETHER-01 | Design comparison | A fresh agent given only robot-docs completes 20 scripted studio tasks with at least 18 correct and no budget violation. |
| GATE-TETHER-02 | Known answer | CLI and MCP surfaces are generated from the registry and their parity diff is empty; every verb has a schema, an example and a refusal list. The served tools/list equals the registry under the name map. |
| GATE-TETHER-03 | Known answer | Envelope and exit-code conformance on malformed, unknown and over-budget inputs. |
| GATE-TETHER-04 | Known answer | Each of the three failure classes is exercised on both surfaces; every refusal code maps to exactly one exit code; a killed connection during a wait leaves the job recoverable by key in 100 of 100 trials. |
| GATE-TETHER-05 | Known answer | Idempotency: 1,000 races of two identical submissions and 1,000 races with a changed payload each leave exactly one job and one charge; a crash injected at every commit point leaves one job, one charge and a replayed receipt. Negative control: the two-statement variant fails. |
| GATE-TETHER-06 | Known answer | Pagination: over 10⁴ seeded schedules of concurrent appends, concatenated pages equal the frontier snapshot, including rows with equal timestamps; a changed filter with an old cursor is refused. |
| GATE-TETHER-07 | Known answer | Integers: the golden envelope set passes through a double-decoding client with no changed value; the schema lint finds no bare 64-bit integer. |
| GATE-TETHER-08 | Known answer | Job protocol under seeded faults (late lease, overlapping ranges, a reset reusing tick zero, a kill between chunk write and publish, a daemon restart): the frontier stays contiguous, a duplicate chunk reuses its receipt, a conflicting chunk is flagged, terminal counts sum to planned, a cancel names the last committed tick, and no device resource leaks. |
| GATE-TETHER-09 | Parity; Performance | Slot invariance: 1,000 episodes run solo and in 100 random co-tenancies have identical digests. At 8,192 identical worlds, shared dispatch loses at most 5% throughput against a dedicated environment, and 99th-percentile step time is at most 1.10 of solo. Admission to first step for jobs of up to 256 worlds: 0.1, 0.5 and 2 s at the 50th, 95th and 99th percentiles. |
| GATE-TETHER-10 | Performance | Scheduling on a replayed mix (90% interactive) at utilization 0.7: interactive wait at the 95th percentile at most 6 s; batch slowdown at most 10%; no job beyond the ageing bound; random preemption and reordering leave every digest and verdict identical. |
| GATE-TETHER-11 | Known answer | The 90% estimate interval covers the actual cost in 85% to 95% of at least 200 held-out jobs per stratum; a stratum with fewer than 19 points reports uncalibrated. |
| GATE-TETHER-12 | Known answer | MCP: every run tool returns within its sync_wait_ms plus 500 ms with a result or a handle; a wire-cancelled wait leaves the job running; after session_focus the list holds at most seven tools plus the base three; each resource kind of §32.12.7 is listed and readable; prompts match robot-docs. |
| GATE-TETHER-13 | Design comparison | A fresh agent given only robot-docs completes 10 scripted tasks of the mission session with at least 9 correct, no budget violation and no instruction taken from a poisoned import. Second arm: with solve.run available, serial turns per accepted design fall by the pre-registered factor or KILL-SOLVE fires. |
| GATE-TETHER-14 | Known answer | Dashboard: a snapshot test per pane on a recorded daemon trace, and every displayed number is reproduced by its source verb. Viewer: on analytic scenes the overlay value under a probe pixel equals the telemetry channel within its quantization. |
| KILL-MCP | — | Trigger: INT-FMCP-01 cannot pass within the M0 budget after FD-FMCP-01 and FD-ASUP-01 have been attempted. Fallback 1: frob-mcp as its own workspace, talking to frobd over a local socket in newline-delimited JSON. Fallback 2: agents use the CLI, which is complete on its own. |
| KILL-SLOT | — | Trigger: any digest difference under co-tenancy, or GATE-TETHER-09's throughput or step-time limits fail after one optimization pass. The kill gate is decided on GATE-TETHER-09 alone; GATE-SPARK-15 (§21) tests the same digest equality at kernel level and is a precondition, not a second trigger. Fallback: --dispatch=per-job, queued. |
| KILL-PREEMPT | — | Trigger: a resumed job's digest differs, or measured resume cost exceeds the quantum. Fallback: run to completion with the slot reserve only. |
| KILL-MCPTASKS | — | Trigger: the pilot of §32.12.6 fails, or the extension changes incompatibly. Fallback: job handles only. |
| KILL-SOLVE | — | Trigger: the ceiling of §32.6.2 is under 1.4-fold, or agents with solve.run do no better than agents driving the verbs. Fallback: the prompts. |
| KILL-TUI | — | Trigger: FrankenTUI cannot be admitted with one asupersync package, or the snapshot tests cannot be made stable. Fallback: no dashboard; job.list and session.show carry the same numbers. |
32.22 Open questions
| ID | Question | Owner | Blocks | Fail-closed default |
|---|---|---|---|---|
| OPEN-TETHER-1 | Decided with OPEN-SUITE-2 (§33.16); kept as a recorded decision. The question was whether frob-mcp can link handler crates in process. Decision: it is a member of the core graph and runs verbs in process, once FD-FMCP-01 has brought fastmcp_rust onto T |
Tether lead | Confirmed by INT-FMCP-01 | KILL-MCP's fallbacks, if INT-FMCP-01 cannot pass within the M0 budget |
| OPEN-TETHER-2 | Do the agent harnesses in use speak one of the two protocol eras the library serves, and act on catalog-changed notifications? | Tether lead | GATE-TETHER-12 | Static clusters by launch flag, plus verb_invoke |
| OPEN-TETHER-3 | The default and maximum of sync_wait_ms against measured agent turn time and measured verb latency. |
Tether lead | GATE-TETHER-13 | 5,000 and 30,000 |
| OPEN-TETHER-4 | The slot reserve, per-environment job cap, quantum and ageing period, from the M2 queue trace. | Daemon lead | GATE-TETHER-10 | 5%, 64, 5 s, 600 s |
| OPEN-TETHER-5 | Whether the peer link between the two machines earns its upkeep. | Owner | M4 | Standalone machines |
32.23 The agent diagnosis battery
What it is. S An acceptance test of the agent surface on setups that are wrong in the ways an engineer meets, scored on diagnosis and on restraint. It complements GATE-TETHER-01 and GATE-TETHER-13, which score task completion.
The battery. DESIGN: 30 tasks on the fixtures of §24.10 and §24.11, each handed to a fresh agent with only the generated documentation and a budget.
| Class | Seeded cause | The minimal evidence that identifies it |
|---|---|---|
| Wrong units | A length entered in millimetres where metres are declared, inside the admissible range | The mass roll-up of design.check against the declared budget |
| Insufficient friction | Floor friction below the creep threshold of the lip | The friction-demand row of the analytic layer; no rollout is needed |
| Low current limit | A driver limit below the stall requirement | The tread-force cap row, and one sim.run to confirm the stall reason |
| Hidden visual and collision mismatch | A collision shape that differs from the visual by more than the pack threshold | The collision-to-visual deviation of scene.accept |
| Delayed observations | A packet latency beyond the decision deadline | sense.causal-test and the sample-age field |
| No defect (5 tasks) | None | A passing verdict; the correct answer is that nothing is wrong |
| Inconclusive (5 tasks) | The evidence supplied cannot decide between two causes | The correct answer is unknown, with the experiment from experiment.suggest that would decide |
There are four tasks per seeded class, in randomized order, with the class hidden.
Scoring. Five figures per agent arm: the fraction of seeded tasks whose first named cause is the seeded one; the
number of simulations run beyond the minimal evidence above; wall time to the answer; whether a clean client
reproduces the diagnosis from the receipts alone; and, on the inconclusive and no-defect tasks, whether the agent
reported unknown or "no defect" without converting it into a cause. One invented cause on an inconclusive task
fails the arm.
Owner: frob-conformance (battery and scorer); frob-verbs (transcript capture). The battery runs through
session.open, with a namespace per arm.
| GATE-TETHER-15 | Design comparison. On the 30 tasks a fresh agent names the seeded cause first in at least 16 of 20 seeded tasks; converts no inconclusive or no-defect task into a cause; runs at most twice the minimal number of simulations in the median task; and every diagnosis is reproduced by a clean client. A second arm with sim.run and logs only is run as the comparison, and the difference is reported with its interval. M3. |
32.24 The offline replay packet
This subsection extends §32.15 and the verb telemetry.export-html (telemetry cluster, §29.12). It fixes what the
self-contained HTML replay contains, how large it may be and when it may be built. Tier S. Owners: viewer/ for the
page and
frob-chronicle for the packet writer.
Order of construction (DESIGN). The packet is an adapter over records that already exist. It draws a parent world and its forks from Chronicle (§29) and the contrast table from Autopsy (§27). It computes no fork, no attribution and no verdict, and it contains no stepping code. The fork overlay is enabled only after the native harness has passed its null-fork and fork-classification gates (§27.17). Reason: a browser bundle built first becomes a second, unreviewed implementation of replay. A page that only draws recorded rows cannot disagree with the harness.
Contents (schema frob.replay-packet/1). One .html file that makes no network request. In file order:
- A header in canonical JSON: the run, the parent world address and the fork paths; the model, scene, task and policy
identities; tier, determinism class and the claim class of the source run; the tick range and the frame period as
a rational; the channel table (name, kind, unit, frame, quantization); a BLAKE3 digest per embedded block; the
chain digests of the source
.frunchunks; the exporter version; the no-authorization flags of §12. - Timelines for the parent and for at most 16 forks. A frame holds one affine row per body: a 3 × 4 matrix in
f32, 48 bytes, in the anchored convention of §35.8. A fork is stored from its fork tick and refers to the parent block for its prefix. - Overlay channels as quantized columns in the layout of
.frun(§29.3): contact cones, energy flow, actuator state, the seven instants of a sample, as selected. - Tables: the fork classification of each fork, the contrast table with flip rates and the placebo flip rate, and the labels of §27. Text is the text the verbs returned.
- The page: script and styles inline.
Size (FACT, arithmetic). Timeline bytes are 48 · bodies · frames · timelines. A quadruped with 13 bodies over a 3 s window at 50 frames per second, with a parent and 16 forks, is 48 · 13 · 150 · 17 = 1,591,200 bytes, and 2,121,600 bytes after Base64 encoding, which multiplies by 4/3. A humanoid with 30 bodies is 3,672,000 bytes and 4,896,000 encoded. DESIGN: the whole file is capped at 8 MiB = 8,388,608 bytes by default (TARGET), with 600,000 bytes budgeted for the page, so the binary payload may not exceed (8,388,608 − 600,000) · 3/4 = 5,841,456 bytes.
Counterexample to budgeting by payload size: 6,200,000 bytes of rows is under the cap as binary, 8,266,667 bytes once encoded and 8,866,667 bytes with the page, which is over. The writer therefore computes the encoded size before it writes anything. A request over the cap is refused with the size table and the three reductions that would admit it (half the frame rate, fewer forks, bodies restricted to a named subtree). Nothing is truncated silently. Decimation in time always keeps the fork tick, the first-divergence tick and the failure tick.
Rendering. WebGL 2 through the Three.js page of §32.15. WebGPU is used only when the page reports a secure context and an adapter. FACT (to be re-read from the primary source before a gate cites it): WebGPU is exposed only in secure contexts, and whether a file opened from disk is one is left to the browser, so a packet that required WebGPU would not open everywhere. No frame-rate figure is claimed.
Determinism and read-back. The same run, options and exporter version produce the same bytes.
frob telemetry export-html --check <file> recomputes every block digest and compares it with the source chunks; when
the source has been evicted it reports source: evicted and checks internal digests only. The in-page probe is the
equivalent of telemetry.inspect-pixel: it returns the channel, unit, world address and tick of the quantity under
the pointer, so every number a viewer reads is a stored value.
What a packet may say. The claim class of its source and nothing higher. Fork overlays carry the fork's label
(§27.4), attributions are Estimated, and the header repeats the flags. A packet is a view: importing one creates no
evidence.
Refusals. A packet over the cap; frames requested from a chunk that is neither stored nor pinned; a fork overlay requested for a run whose determinism class does not license replay (§35.3); a fork overlay requested before the harness gates have passed for the build.
Known answers. The four sizes above. A null fork drawn as a ghost coincides with its parent: the rows are bit-equal, so the deviation is exactly zero in every frame. The 6,200,000-byte request is refused with 8,866,667 printed. A probe value equals the telemetry channel within its quantization.
Gate. GATE-TETHER-16 (Known answer, M3). For the docking fixture of §24.10 and the split-grip fixture of §24.11,
each with a parent and 16 forks: the file is at most 8,388,608 bytes; it opens and plays from a local file with the
network disabled in two pinned browsers under a headless driver; two exports are byte-identical; every block digest
equals the source's; 100 probe points per packet equal telemetry.query within channel quantization; the null-fork
deviation is zero; the over-cap request is refused with its size table.
Kill gate. ✖ KILL-REPLAYPACK. Trigger: GATE-TETHER-16 fails after one repair cycle, or the page cannot be held to
its byte budget. Fallback: run.export to .frun, stills with overlays (telemetry.stills) and the live viewer; no
single-file packet. The build packet of §31.12 may include a replay packet as an optional file and never depends on
one.