@passioncode-ai/fabric-agent-adapter 0.18.0 → 0.20.0

package/CHANGELOG.md

@@ -1,5 +1,98 @@
 # Changelog
 
+## 0.20.0 - 2026-10-12
+
+Runner routes in both kits: the closed probe results and the route checks FAC-SEM-028…034. These come from contract
+DEC-0026 and DEC-0029, at the pin (FAA-11).
+
+### Added
+
+- **The closed probe result.** `runner_check` / `runnerCheck` answer with `probe`. The values follow the walk's order:
+  - `not-installed`: no catalogued binary is on PATH;
+  - `not-responding`: the version probe did not answer, failed or did not match, or the `auth` probe did not answer;
+  - `not-connected`: the runner answers but is signed out;
+  - null: the runner can serve.
+
+  The doctor still names every problem it found.
+- **The route checks.** `route_problems(kind, value)` / `routeProblems(kind, value)` are the contract's `routeRules`,
+  finding for finding: code, path and message.
+  - `runner-route`: one candidate per runner kind (FAC-SEM-028), and every candidate can attach or spawn (029).
+  - `route-bundle`:
+    - provider revisions are admitted by id, revision and hash (030);
+    - the binding agrees with the route (032);
+    - kinds and drives are in the runner catalogue (033).
+  - `route-event` tells the truth about its route (034):
+    - candidates by position;
+    - probes in order;
+    - the session, hold and recovery policy.
+- `PROBE_RESULTS` lists the closed vocabulary of a passed-over candidate.
+- **Tests.** `test/fixtures/contract/route-vectors.json` holds 43 cases, generated by `make_route_vectors.mjs` from the
+  contract's own `src/route-rules.ts` at the pin. Both kits answer every case exactly.
+  - Mutation testing: 23 planted defects, all caught.
+- **Docs.** `references/profiles.md` gains *Runner routes* and the probe result. `SKILL.md` points to it. The scenario
+  eval `runner-routes-and-probe-results` and a trigger came first.
+
+## 0.19.0 - 2026-10-12
+
+Settings backups, every spending limit and the feed client's token header in both kits. These are the
+service-side surfaces the pinned contract already carries: DEC-0025 and DEC-0027 (FAA-13).
+
+### Added
+
+- **Settings backups (`fabric-settings-backup/1`, FAC-SEM-035).** Each function exists in both kits.
+  - **Location.** Snapshots live under `<root>/settings-backups/<id>/<instance>/`, outside the data directory.
+    `<root>` is per system: `~/Library/Application Support/PassionCode`, `%APPDATA%\PassionCode` or
+    `$XDG_CONFIG_HOME/PassionCode`.
+  - **Writing.** `make_settings_backup` builds a snapshot from allow-listed tables of JSON scalars. It refuses
+    secret tables, credential columns and fractions.
+  - `write_settings_backup` writes atomically, 0600 in a 0700 folder.
+    - It does not rewrite an unchanged snapshot.
+    - It removes a temporary file an interrupted write left behind.
+    - It keeps the 14 newest snapshots.
+  - `backup_due` decides when the next snapshot is due.
+  - **Reading.** `read_settings_backup` refuses a damaged file and names why.
+  - `newest_intact_backup` skips damaged files and empty snapshots.
+  - `restore_plan` adds rows and never overwrites them. It names what it drops, leaves to defaults or refuses.
+  - **The checksum** uses the settings canonical form: `settings_canonical_json` and `settings_backup_digest`.
+    They are checked against the contract's vectors.
+  - **Parity.** Both kits write byte-identical files.
+- **Every spending limit (DEC-0027, FAC-SEM-031).**
+  - `usage_report` and `usageReport` take a `budgets` list.
+  - A machine day or month limit is counted from the receipts, so it always agrees with `budget`.
+  - A per-order limit gets `spentUsd: null`.
+  - The report is refused when its limits break FAC-SEM-031.
+  - `usage_limit_problems` and `usageLimitProblems` check a report.
+- **The feed client (FAC-SEM-036).** `token_header` and `tokenHeader` give the one header the descriptor
+  declares. `check_service.py` now sends its token through it.
+- **An independent review found 20 moderate defects; all are fixed with tests.**
+  - **The readers follow the schema exactly**, and the two kits accept the same files:
+    - a trailing newline is refused (Python matches a whole string now);
+    - a timestamp is any RFC 3339 date-time with a real calendar date, including an offset;
+    - a string holds at most 1 MiB and a row at most 512 values;
+    - every `extensions` key is a URI;
+    - NaN is refused;
+    - in Node, invalid UTF-8 and a `1.0` integer are refused the way Python refuses them.
+  - **A damaged file never stops anything.** The scan skips it, the digest does not crash, a damaged newest file
+    does not suppress a good snapshot, and an impossible file name makes a snapshot due.
+  - **Safer writes:**
+    - only a temporary file older than an hour is removed;
+    - the snapshot just written is never pruned, even after the clock steps back.
+  - **The restore preview** refuses a key the snapshot holds twice.
+  - **Limits:**
+    - a machine limit over a rolling window is counted from the receipts;
+    - a limit that is not an object is refused.
+  - **Both descriptor validators** check `auth.header` and `auth.scheme` the way the schema does.
+- **Tests.**
+  - The contract's fixtures at the pin are copied to `test/fixtures/contract/dec-0025-0027/`.
+  - The Windows CI job runs both kits' new cases.
+  - Mutation testing: 79 planted defects, all caught.
+- **Docs.**
+  - `references/settings-backups.md` is new.
+  - `usage.md` covers every limit.
+  - `events-and-notifications.md` covers reading a feed.
+  - Updated: `SKILL.md` step 5 and the lifecycle reference's directory table.
+  - The scenario eval `settings-backups-and-every-limit` and two triggers came first.
+
 ## 0.18.0 - 2026-10-12
 
 Services on Linux and Windows in both kits (contract DEC-0032, DEC-0033; FAA-21): the supervisor files the

package/README.md

@@ -230,8 +230,8 @@ FABRIC_CONTRACT_OLD=/path/to/legacy-contract FABRIC_CONTRACT_NEW=/path/to/curren
 ```
 
 Without both environment variables, those tests explicitly skip as `NOT_RUN`.
-This source checkout is 0.18.0. 0.17.0 is the latest published GitHub/npm release (2026-10-12; 0.7.0 and 0.11.0
-were never released); 0.18.0 is published by its `v0.18.0` tag. Source delivery does not update installed skills or live sessions.
+This source checkout is 0.20.0. 0.19.0 is the latest published GitHub/npm release (2026-10-12; 0.7.0 and 0.11.0
+were never released); 0.20.0 is published by its `v0.20.0` tag. Source delivery does not update installed skills or live sessions.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@passioncode-ai/fabric-agent-adapter",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "Create Fabric-compatible agents, run them as always-alive local services with dashboards (fabric-service/0.1), and adapt existing projects to the Fabric Agent Contract. This package is the installer CLI.",
   "scripts": {
     "test": "python3 test/validate.py && python3 -m unittest discover -s test -q && node --test 'test/*.test.mjs'"

package/plugins/fabric-agent-adapter/.claude-plugin/plugin.json

@@ -3,7 +3,7 @@
   "name": "fabric-agent-adapter",
   "displayName": "Fabric Agent Adapter",
   "description": "Create new Fabric-compatible agents, build them as always-alive local services with dashboards (fabric-service/0.1), and adapt existing projects to the Fabric Agent Contract through evidence-backed MCP, A2A, or local-runner provider bundles.",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "author": {
     "name": "PassionCode.ai",
     "url": "https://passioncode.ai/"

package/plugins/fabric-agent-adapter/skills/adapting-projects-to-fabric/SKILL.md

@@ -5,7 +5,7 @@ license: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 compatibility: Requires filesystem access and Python 3.9+. Exact schema checks additionally need git, Node.js, pnpm, and the pinned fabric-agent-contract checkout (a public repository). Works without those tools in an explicitly degraded structural-check mode.
 metadata:
   author: PassionCode.ai
-  version: "0.18.0"
+  version: "0.20.0"
   contract-version: "0.1.0"
   contract-commit: "0cacd08b0e95b6abf131eae1206b60792138bc3c"
 ---

package/plugins/fabric-agent-adapter/skills/building-fabric-services/SKILL.md

@@ -16,7 +16,7 @@ license: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 compatibility: Python 3.9+ or Node.js 20+ for the kits; the probe needs Python 3.9+. launchd steps are macOS-only; Linux services install a systemd user unit and Windows ones a per-user Scheduled Task with the kits' writers. Dashboard handoff optionally uses Fabric Dashboards MCP link/host_status/open; without it, report unresolved host capability. The contract checkout is optional.
 metadata:
   author: PassionCode.ai
-  version: "0.18.0"
+  version: "0.20.0"
   contract-version: "0.1.0"
   extension: "fabric-service/0.1"
   extension-commit: "0cacd08b0e95b6abf131eae1206b60792138bc3c"
@@ -84,7 +84,8 @@ are in [`scripts/fabric_interop.py`](scripts/fabric_interop.py) and
 service checks each call's delegation token (DEC-0039): read [the delegation reference](references/delegation.md);
 the verifier is [`scripts/fabric_delegation.py`](scripts/fabric_delegation.py) /
 [`scripts/fabric-delegation.mjs`](scripts/fabric-delegation.mjs). When Fabric chooses the service's runner and models
-(DEC-0046), read [the profiles reference](references/profiles.md).
+(DEC-0046), or a project routes its work through an ordered list of runners (DEC-0026: the doctor's closed probe
+results, the route checks FAC-SEM-028…034), read [the profiles reference](references/profiles.md).
 
 ## Step 2 — the non-negotiables
 
@@ -228,8 +229,12 @@ log, retention and notification policy.
 
 An agent that calls paid models reports **what it spent**: one receipt per call from the
 provider's own usage numbers, served behind the token at `surfaces.usage` as the DEC-0021 usage
-report. An unknown cost is null, never 0. Read [the usage reference](references/usage.md)
-before wiring it.
+report. An unknown cost is null, never 0. It lists **every** spending limit the service applies
+in `budgets`, enforced or not. Read [the usage reference](references/usage.md) before wiring it.
+
+A service whose store holds what the operator decided keeps **settings backups** outside its data
+directory, restores only on a fresh database and never overwrites. Read
+[the settings backups reference](references/settings-backups.md).
 
 ## Step 6 — verify
 

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/events-and-notifications.md

@@ -11,6 +11,15 @@
 
 The feed is a view: never copy rows into a second store that can drift from the first.
 
+## Reading a feed (FAC-SEM-036)
+
+A client of `GET /fabric/v1/events` — or of any token-protected route — sends the token in the
+header the descriptor's `auth.header` names, in the form `auth.scheme` names: the raw token for
+`none`, `Bearer <token>` for `Bearer`. Never assume `Authorization: Bearer`: a client that did
+was refused on every poll and silently dropped every notify event. `token_header(auth, token)` /
+`tokenHeader(auth, token)` gives the one header; the token never travels in another header or
+in the URL.
+
 ## Writing an event
 
 - `kind`: dotted, stable, past tense or state (`job.failed`, `job.awaiting_choice`,

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/lifecycle.md

@@ -88,6 +88,7 @@ remove; the back-off only stops the loop from costing the machine.
 | logs | `~/Library/Logs/<id>/` | `${XDG_STATE_HOME:-~/.local/state}/<id>/logs/` | `%LOCALAPPDATA%\<id>\Logs\` |
 | cache (deletable any time) | `~/Library/Caches/<id>/` | `${XDG_CACHE_HOME:-~/.cache}/<id>/` | `%LOCALAPPDATA%\<id>\Cache\` |
 | code | `~/.local/share/<id>/releases/…` | same | under `%LOCALAPPDATA%` too, never a network share |
+| settings backups ([DEC-0025](settings-backups.md)) | `~/Library/Application Support/PassionCode/settings-backups/<id>/<instance>/` | `${XDG_CONFIG_HOME:-~/.config}/PassionCode/settings-backups/…` | `%APPDATA%\PassionCode\settings-backups\…` |
 
 A repository that versions the data itself (a registry, a plan) may hold the data; the
 service's own code checkout and its releases may not. Directories 0700, secret files 0600. A store carries a schema version and the service

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/profiles.md

@@ -13,6 +13,7 @@ Python: [`scripts/fabric_profiles.py`](../scripts/fabric_profiles.py); Node:
 - Checking the documents
 - Declaring and showing what applies
 - The doctor
+- Runner routes
 - Usage by route
 
 ## Resolving the model profile
@@ -58,6 +59,28 @@ catalogued binary found on `PATH`, only with the catalogued version argv (and `a
 the entry's timeout (at most 5 s); an entry outside these rules is refused and nothing runs. `model_usable(model,
 catalogue, policy)` names why a model cannot be used here: not catalogued, or a class the project does not allow.
 
+`probe` is the contract's closed probe result for that runner, the one Fabric's walk records (DEC-0026):
+`not-installed` (no catalogued binary on `PATH`), `not-responding` (the version probe did not answer in its bound,
+failed or did not match the catalogue's pattern, or the `auth` probe did not answer), `not-connected` (it answers but
+the `auth` probe says signed out), or `None`/`null` when the runner can serve. The order is the walk's: installed,
+then responding, then connected. `problems` still names every problem the doctor found.
+
+## Runner routes
+
+A project may pin a **runner route** (DEC-0026, DEC-0029, `runners.md` §"Runner routes"): the ordered terminal agents
+that serve one capability, each with a session policy (`attach`, `spawn`), what happens when all are unavailable
+(`exhausted`) and whether a conversation returns to a preferred runner (`recovery`). Fabric walks it; a service that
+pins, records or shows routes checks them with `route_problems(kind, value)` / `routeProblems(kind, value)`, the
+contract's `routeRules` finding for finding:
+
+| `kind` | value | rules |
+|---|---|---|
+| `runner-route` | the route | one candidate per runner kind (FAC-SEM-028); a candidate can attach or spawn (029) |
+| `route-bundle` | `{route, admissions, binding?, catalogue?}` | every candidate's provider revision admitted for the capability by id, revision and hash (030); the binding agrees — project, capability, local-runner, a candidate as provider, this route as `runnerRoute` (032); every kind and named drive is in the runner catalogue (033) |
+| `route-event` | `{route, event}` | the event names this route, project and capability; candidates by position; the probes cover every candidate above the selection in order (all for an exhausted walk, none for a sticky relaunch); attach, spawn, `no-held-session` and `spawn-failed` obey the session policy; `held` only under `exhausted: hold`; `preferred-available` only under `recovery: reprobe`, moving up (034) |
+
+A probe result in an event is one of `PROBE_RESULTS`; a host never appends a runner the route does not name.
+
 ## Usage by route
 
 `make_usage_receipt(..., route="subscription"|"key")` records how the call was paid — the operator's own login in its

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/settings-backups.md

@@ -0,0 +1,67 @@
+# Settings backups — what the operator decided survives the data directory (DEC-0025)
+
+Fabric Agent Contract DEC-0025, `docs/specification/service.md` → *Settings backup*, schema
+`schemas/settings-backup.schema.json`, rule `FAC-SEM-035`. A service whose store holds what the operator
+decided — which projects it serves, how each is bound, which secret slot each binding uses, their overrides —
+SHOULD keep settings backups, so a lost, purged or wrongly migrated data directory costs the operator nothing.
+
+## Where
+
+`<root>/settings-backups/<id>/<instance>/settings-<UTC %Y%m%dT%H%M%S%fZ>.json`, outside the data directory:
+
+| System | `<root>` (`settings_backup_root` / `settingsBackupRoot`) |
+|---|---|
+| macOS | `~/Library/Application Support/PassionCode` |
+| Windows | `%APPDATA%\PassionCode` |
+| Linux | `$XDG_CONFIG_HOME/PassionCode`, default `~/.config/PassionCode` |
+
+`settings_backup_dir(id, instance)` / `settingsBackupDir(id, instance)` names the folder. Directories are 0700
+(on Windows a protected ACL), files 0600, writes atomic.
+
+## Take a snapshot
+
+```python
+dirs = fs.settings_backup_dir(ID, INSTANCE)
+if fs.backup_due(dirs):                                   # none yet, or the newest is older than 24 hours
+    doc = fs.make_settings_backup(service_id=ID, instance=INSTANCE, version=VERSION, schema=SCHEMA_VERSION,
+                                  tables=allow_listed_tables(db), reason="start")      # or daily, uninstall, manual
+    fs.write_settings_backup(doc, dirs)                   # None when unchanged; keeps the 14 newest
+```
+
+```js
+const dir = k.settingsBackupDir(ID, INSTANCE);
+if (k.backupDue(dir)) k.writeSettingsBackup(k.makeSettingsBackup({ id: ID, instance: INSTANCE, version, schema, tables, reason: 'daily' }), dir);
+```
+
+- **Tables on an allow-list**, each `{"columns": [...], "rows": [[...], ...]}` of JSON scalars. A fraction is its
+  decimal string (`"0.25"`), binary data is never stored, and an integer stays within ±(2^53 − 1).
+- **Secrets by name only.** `make_settings_backup` refuses a table that can only hold connections, tokens,
+  secrets, credentials, passwords, login codes or sessions, and a column whose name says it holds a credential
+  value (`access_token`, `client_secret`); `secret_name` and `token_slot` pass. The names cannot see values, so
+  back up what is on the allow-list, never everything except a deny-list.
+- **When:** at start when `backup_due`, then daily; on uninstall a last one, read-only (open the store without
+  migrating or writing). An unchanged snapshot is not rewritten; a temporary file an interrupted write left is
+  removed first. A fresh, empty database writes none: it would hide the good snapshot before it is restored.
+- Both kits write byte-identical files (`test/fabric-service-backups.test.mjs`, last case).
+
+## Read and restore
+
+`read_settings_backup` / `readSettingsBackup` refuses a file whose checksum, counts or row widths disagree with
+its tables, that carries a value with no canonical form, or whose `format` it does not know, naming why
+(`FAC-SEM-035`). The checksum is SHA-256 of the settings canonical form of `tables`
+(`settings_canonical_json` / `settingsCanonicalJson`: Python's `json.dumps(sort_keys=True,
+ensure_ascii=False)`).
+
+Restore **adds and never overwrites**:
+
+```python
+path, doc, skipped = fs.newest_intact_backup(dirs)        # the newest intact snapshot with content; damaged ones named
+plan = fs.restore_plan(doc, {"projects": {"columns": [...], "key": ["id"], "required": ["id", "name"],
+                                          "existing": existing_keys("projects")}})
+# plan["tables"]["projects"]: insert, present, droppedColumns, defaultedColumns, missingRequired, refused
+```
+
+- **Automatic restore** only on a *fresh* database — no domain records **and** the service has never started —
+  so a restart never undoes a deletion. Insert `plan[...]["insert"]` and add every row the database refuses to
+  `refused` with its key and reason.
+- **Manual restore** shows the plan first; applying it is the operator's act, never an agent's.

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/usage.md

@@ -50,6 +50,29 @@ left out.
 **Budget.** Pass `budget` only if the service **enforces** that limit itself. The report states
 it, and the host only shows it.
 
+**Every limit (DEC-0027).** Pass `budgets` to list every spending limit the service applies,
+enforced or not, so the spend view shows all of them — the operator asked for that on 2026-10-07:
+
+```python
+ledger.report(service_id=ID, budget={"period": "month", "limitUsd": 100}, budgets=[
+    {"id": "machine.monthly", "scope": "machine", "kind": "monthly", "period": "month", "limitUsd": 100, "enforced": True},
+    {"id": "project.demo.daily", "scope": "project", "subject": "demo", "kind": "daily", "windowSeconds": 86400,
+     "limitUsd": 5, "spentUsd": 0.31, "enforced": True},
+    {"id": "job.cap", "scope": "job", "kind": "per_job", "limitUsd": 2, "enforced": True},
+])
+```
+
+- A machine limit with a `period` and no `spentUsd` is counted by the kit from the receipts, the
+  way `budget` is, so `budget` and its twin in `budgets` never disagree. A per-order limit
+  (`per_job`, `approval`) gets `spentUsd: null`. Every other limit states its own spend.
+- `scope` is `machine`, `project`, `pool` or `job`; a `project` or `pool` limit names its
+  `subject`. A limit has at most one window — `period`, `windowSeconds` or `since` — and it agrees
+  with the kind (`daily`: the day or 86400 s; `monthly`: the month or 28–31 days; `velocity`: a
+  rolling window). `tripped: true` (work stopped by it now) needs `enforced: true`. An unknown
+  kind is shown generically, never refused.
+- The kits refuse a report that breaks these (`usage_limit_problems` / `usageLimitProblems`,
+  `FAC-SEM-031`). A breach is not refused: the report shows it, and the host shows it first.
+
 Call `ledger.prune()` at start (or daily) to keep the file at the reported window (LC-12).
 
 `JsonlUsageLedger` appends 0600 JSON lines. A line torn by a killed writer is skipped, and the

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/check_service.py

@@ -162,10 +162,9 @@ class Probe:
             conn.close()
 
     def auth_headers(self) -> Dict[str, str]:
-        auth = self.d.get("auth", {})
-        header = auth.get("header", "Authorization")
-        value = self.token or ""
-        return {header: ("Bearer " + value) if auth.get("scheme", "Bearer") == "Bearer" else value}
+        # The header and form the descriptor declares, never an assumed `Authorization: Bearer` (FAC-SEM-036).
+        name, value = fs.token_header(self.d.get("auth"), self.token or "")
+        return {name: value}
 
     # descriptor ------------------------------------------------------------
     def descriptor_rules(self) -> None:

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-profiles.mjs

@@ -126,6 +126,10 @@ function which(name, searchPath) {
  * runners.md C2: is the catalogued runner installed, which version answers, and is it signed in. Only a bare
  * catalogued binary on PATH is run, only with the catalogued version (and auth) argv, without a shell, within its
  * timeout (at most 5 s). An entry outside these rules is refused and nothing runs.
+ *
+ * `probe` is the contract's closed probe result for a walk (DEC-0026): `not-installed`, `not-responding` (the version
+ * probe did not answer, failed or did not match), `not-connected` (signed out by the `auth` probe), or null when the
+ * runner can serve. The twin of fabric_profiles.runner_check.
  */
 export function runnerCheck(entry, { searchPath = process.env.PATH, run = spawnSync } = {}) {
   const { kind, binaries } = entry ?? {};
@@ -136,10 +140,10 @@ export function runnerCheck(entry, { searchPath = process.env.PATH, run = spawnS
   const timeoutMs = version.timeoutMs ?? MAX_PROBE_MS;
   if (!Number.isInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > MAX_PROBE_MS) throw new ProfileError(`version.timeoutMs is at most ${MAX_PROBE_MS}`);
   const authArgv = 'auth' in entry ? argvOf(entry.auth, 'auth') : null;
-  const out = { kind, installed: false, binary: null, version: null, signedIn: null, problems: [] };
+  const out = { kind, installed: false, binary: null, version: null, signedIn: null, probe: 'not-installed', problems: [] };
   const binary = binaries.map((name) => which(name, searchPath)).find(Boolean) ?? null;
   if (!binary) { out.problems.push(`${kind} is not installed: none of ${binaries.join(', ')} is on PATH`); return out; }
-  Object.assign(out, { installed: true, binary });
+  Object.assign(out, { installed: true, binary, probe: 'not-responding' });
   const probe = (argv) => {
     const result = run(binary, argv, { encoding: 'utf8', timeout: timeoutMs, shell: false });
     if (result.error?.code === 'ETIMEDOUT' || result.signal === 'SIGTERM') { out.problems.push(`${kind} ${argv.join(' ')} did not answer within ${timeoutMs} ms`); return null; }
@@ -153,10 +157,12 @@ export function runnerCheck(entry, { searchPath = process.env.PATH, run = spawnS
     if (match && match.length > 1) out.version = match[1];
     else out.problems.push(`${kind} answered, but its version did not match the catalogue's pattern`);
   }
-  if (authArgv) {
-    const signed = probe(authArgv);
-    if (signed) { out.signedIn = signed.status === 0; if (!out.signedIn) out.problems.push(`${kind} is installed but not signed in`); }
-  }
+  const signed = authArgv ? probe(authArgv) : null;
+  if (signed) { out.signedIn = signed.status === 0; if (!out.signedIn) out.problems.push(`${kind} is installed but not signed in`); }
+  // The walk's order (runners.md): installed, then responding, then connected. The doctor still reports every problem.
+  if (out.version === null || (authArgv && !signed)) out.probe = 'not-responding';
+  else if (out.signedIn === false) out.probe = 'not-connected';
+  else out.probe = null;
   return out;
 }
 
@@ -194,3 +200,131 @@ export function configurationSummary(doc) {
   if (resolved.modelProfile) tiles.push({ label: 'Model', value: [resolved.modelProfile, (resolved.models ?? [])[0]].filter(Boolean).join(' · ') });
   return tiles;
 }
+
+// ---- runner routes (DEC-0026, DEC-0029; FAC-SEM-028…034) ----
+// The contract's routeRules (src/route-rules.ts), finding for finding: code, path and message. The twin of
+// fabric_profiles.route_problems.
+
+/** The closed probe results a walk records for a candidate it passed over (runner-route-event.schema.json). */
+export const PROBE_RESULTS = Object.freeze(['not-catalogued', 'not-admitted', 'not-installed', 'not-responding', 'not-connected', 'no-held-session', 'quota-unknown', 'refused', 'spawn-failed']);
+
+const routeCandidates = (value) => (Array.isArray(value?.candidates) ? value.candidates.filter(isObject) : []);
+const objectAt = (value, key) => (isObject(value?.[key]) ? value[key] : {});
+const refKey = (ref) => (isObject(ref) ? `${String(ref.id)}@${String(ref.revision)}#${String(ref.contentHash)}` : '');
+const sameRef = (a, b) => refKey(a) !== '' && refKey(a) === refKey(b);
+
+function runnerRoute(value) {
+  const findings = [];
+  const kinds = new Set();
+  routeCandidates(value).forEach((candidate, index) => {
+    const kind = String(candidate.runnerKind);
+    if (kinds.has(kind)) findings.push(finding('FAC-SEM-028', `/candidates/${index}/runnerKind`, `runner kind ${kind} appears in the route more than once`));
+    kinds.add(kind);
+    const session = objectAt(candidate, 'session');
+    if (session.attach === 'never' && session.spawn === 'never') findings.push(finding('FAC-SEM-029', `/candidates/${index}/session`, `candidate ${kind} can never run: attach and spawn are both "never"`));
+  });
+  return findings;
+}
+
+function routeBundle(value) {
+  const route = objectAt(value, 'route');
+  const admissions = Array.isArray(value.admissions) ? value.admissions.filter(isObject) : [];
+  const admitted = new Set(admissions.filter((a) => a.state === 'admitted' && a.capability === route.capability).map((a) => refKey(a.provider)));
+  const findings = [];
+  routeCandidates(route).forEach((candidate, index) => {
+    const key = refKey(candidate.provider);
+    if (!admitted.has(key)) findings.push(finding('FAC-SEM-030', `/route/candidates/${index}/provider`, `candidate ${String(candidate.runnerKind)} names provider ${key}, which is not a revision admitted for ${String(route.capability)}`));
+  });
+  if (isObject(value.binding)) {
+    const binding = value.binding;
+    const disagree = (where, message) => findings.push(finding('FAC-SEM-032', `/binding/${where}`, message));
+    if (binding.project !== route.project) disagree('project', `the binding is for ${String(binding.project)}, the route for ${String(route.project)}`);
+    if (binding.capability !== route.capability) disagree('capability', `the binding binds ${String(binding.capability)}, the route orders ${String(route.capability)}`);
+    if (binding.profileKind !== 'local-runner') disagree('profileKind', `a runner route serves the local-runner profile, not ${String(binding.profileKind)}`);
+    if (!routeCandidates(route).some((c) => sameRef(c.provider, binding.provider))) disagree('provider', `the binding's provider ${refKey(binding.provider)} is not a candidate of the route`);
+    if (binding.runnerRoute !== undefined && !sameRef(binding.runnerRoute, route.meta)) disagree('runnerRoute', `the binding pins ${refKey(binding.runnerRoute)}, not this route ${refKey(route.meta)}`);
+  }
+  if (Array.isArray(value.catalogue)) {
+    const byKind = new Map(value.catalogue.filter(isObject).map((entry) => [String(entry.kind), entry]));
+    routeCandidates(route).forEach((candidate, index) => {
+      const kind = String(candidate.runnerKind);
+      const entry = byKind.get(kind);
+      if (!entry) { findings.push(finding('FAC-SEM-033', `/route/candidates/${index}/runnerKind`, `runner kind ${kind} has no entry in the host's catalogue`)); return; }
+      if (candidate.drive !== undefined && !Object.hasOwn(objectAt(entry, 'drives'), String(candidate.drive))) findings.push(finding('FAC-SEM-033', `/route/candidates/${index}/drive`, `the catalogue entry for ${kind} offers no drive ${String(candidate.drive)}`));
+    });
+  }
+  return findings;
+}
+
+function routeEvent(value) {
+  const route = objectAt(value, 'route');
+  const event = objectAt(value, 'event');
+  const list = routeCandidates(route);
+  const findings = [];
+  const wrong = (where, message) => findings.push(finding('FAC-SEM-034', `/event${where}`, message));
+  if (!sameRef(event.route, route.meta)) wrong('/route', `the event names route ${refKey(event.route)}, not ${refKey(route.meta)}`);
+  if (event.project !== route.project) wrong('/project', `the event is for ${String(event.project)}, the route for ${String(route.project)}`);
+  if (event.capability !== route.capability) wrong('/capability', `the event names ${String(event.capability)}, the route orders ${String(route.capability)}`);
+  const indexOf = (ref) => (typeof ref.index === 'number' && Number.isInteger(ref.index) ? ref.index : -1);
+  const candidateAt = (ref, where) => {
+    const index = indexOf(ref);
+    const candidate = index >= 0 ? list[index] : undefined;
+    if (!candidate || candidate.runnerKind !== ref.runnerKind || (ref.provider !== undefined && !sameRef(candidate.provider, ref.provider))) {
+      wrong(where, `candidate ${String(ref.index)} (${String(ref.runnerKind)}) is not that position of the route`);
+      return undefined;
+    }
+    return candidate;
+  };
+  const probes = Array.isArray(event.probes) ? event.probes.filter(isObject) : [];
+  probes.forEach((probe, position) => {
+    const candidate = candidateAt(probe, `/probes/${position}`);
+    if (candidate && probe.result === 'no-held-session' && objectAt(candidate, 'session').spawn !== 'never') wrong(`/probes/${position}/result`, `${String(probe.runnerKind)} may spawn, so finding no held session does not pass it over`);
+    if (candidate && probe.result === 'spawn-failed' && objectAt(candidate, 'session').spawn !== 'allowed') wrong(`/probes/${position}/result`, `${String(probe.runnerKind)} has spawn: never, so it cannot have failed to spawn`);
+  });
+  const expectProbes = (count) => {
+    const indexes = probes.map(indexOf);
+    const expected = Array.from({ length: Math.max(count, 0) }, (_, index) => index);
+    if (indexes.length !== expected.length || indexes.some((index, position) => index !== expected[position])) {
+      wrong('/probes', `the walk must record candidates ${expected.join(', ') || 'none'} in order; it records ${indexes.join(', ') || 'none'}`);
+    }
+  };
+  if (event.kind === 'runner-exhausted') {
+    expectProbes(list.length);
+    if (event.answer === 'held' && route.exhausted !== 'hold') wrong('/answer', 'the route does not declare exhausted: hold, so an exhausted walk answers capability-unavailable');
+    return findings;
+  }
+  const selected = objectAt(event, 'selected');
+  const chosen = candidateAt(selected, '/selected');
+  if (chosen) {
+    const session = objectAt(chosen, 'session');
+    if (selected.session === 'attached' && session.attach !== 'preferred') wrong('/selected/session', `${String(selected.runnerKind)} has attach: never, so the host cannot attach it`);
+    if (selected.session === 'spawned' && session.spawn !== 'allowed') wrong('/selected/session', `${String(selected.runnerKind)} has spawn: never, so the host cannot spawn it`);
+    if (chosen.drive !== undefined && selected.drive !== undefined && selected.drive !== chosen.drive) wrong('/selected/drive', `the route runs ${String(selected.runnerKind)} through ${String(chosen.drive)}, not ${String(selected.drive)}`);
+    if (event.sticky === true) {
+      // A sticky relaunch keeps the conversation's runner and walks nothing above it.
+      if (route.recovery === 'reprobe') wrong('/sticky', 'a route with recovery: reprobe walks from the top at every launch');
+      if (event.conversation === undefined) wrong('/sticky', 'only a conversation can keep its runner');
+      expectProbes(0);
+    } else expectProbes(indexOf(selected));
+  }
+  if (event.kind === 'runner-switched') {
+    const from = objectAt(event, 'from');
+    candidateAt(from, '/from');
+    if (indexOf(from) === indexOf(selected)) wrong('/from', 'a switch moves to another candidate');
+    if (event.reason === 'preferred-available') {
+      if (route.recovery !== 'reprobe') wrong('/reason', 'only a route with recovery: reprobe moves a conversation back to a preferred runner');
+      if (!(indexOf(selected) < indexOf(from))) wrong('/reason', 'preferred-available moves to a higher-preference candidate');
+    }
+  }
+  return findings;
+}
+
+/**
+ * The contract's routeRules: findings for a `runner-route` (FAC-SEM-028, 029), a `route-bundle` `{route, admissions,
+ * binding?, catalogue?}` (030, 032, 033) or a `route-event` `{route, event}` (034); undefined for another kind or a
+ * value that is not an object.
+ */
+export function routeProblems(kind, value) {
+  if (!isObject(value)) return undefined;
+  return { 'runner-route': runnerRoute, 'route-bundle': routeBundle, 'route-event': routeEvent }[kind]?.(value);
+}