instar 1.3.757 → 1.3.758

package/scripts/model-registry-freshness.manifest.json

@@ -1,7 +1,7 @@
 {
   "$comment": "Doorway/Model Knowledge Registry — canonical/reviewed layer + staleness/drift gate for Instar's per-provider 'capable/latest' model pins. This file is the SINGLE human-edit surface that keeps the model registry from silently rotting. See docs/LLM-ROUTING-REGISTRY.md, docs/specs/DOORWAY-MODEL-KNOWLEDGE-REGISTRY-SPEC.md, and scripts/lint-model-registry-freshness.mjs. Two teeth: (1) STALENESS — lastReviewedAt must be within stalenessWindowDays; (2) DRIFT — every pinned capable model id must be a member of its door's DERIVED frontier set (the ids in doors[door].topModels[] carrying frontier:true — see §1.4 of the spec). topModels is the ONE hand-edited source of truth; the frontier set is a view of it and cannot diverge by construction. To pass the check a human must confirm each capable pin is genuinely current frontier AND bump lastReviewedAt. An un-reviewed list fails loudly.",
   "registrySchemaVersion": 2,
-  "$schemaNote": "registrySchemaVersion 2 = the enriched Doorway/Model Knowledge Registry. Rollout increment 1 (spec §Rollout step 1): the per-door topModels[] frontier-derivation layer + the derived-frontier lint (report mode). The live scan-state (.instar/state/doorway-scan.json), the deterministic prober, the per-door probe{} block, candidateDoorways[], the scan job, and GET /doorways are LATER increments (spec §Rollout steps 2-3) and are NOT part of this schema version's consumers yet.",
+  "$schemaNote": "registrySchemaVersion 2 = the enriched Doorway/Model Knowledge Registry. Increment 1 (spec §Rollout step 1) added the per-door topModels[] frontier-derivation layer + the derived-frontier lint (report mode). Increment 2 (spec §Rollout step 2) ADDS the per-door probe{} block + candidateDoorways[] below — the metadata the deterministic prober (scripts/doorway-scan.mjs) reads to know HOW to re-verify each door — plus the live scan-state (.instar/state/doorway-scan.json) + the dark (enabled:false) doorway-scan job. Both additions are backward-compatible: the freshness lint ignores probe{}/candidateDoorways entirely (it reads only topModels/frontier/pins). GET /doorways is a LATER increment (spec §Rollout step 3) and is NOT wired yet.",
   "lastReviewedAt": "2026-07-03",
   "stalenessWindowDays": 45,
   "enforcement": "report",
@@ -11,6 +11,7 @@
       "name": "Claude Code CLI",
       "accessMethod": "Claude Code CLI (subscription/OAuth)",
       "status": "alive",
+      "probe": { "kind": "cli-version", "bin": "claude", "metered": false, "freeDefaultCovered": true },
       "topModels": [
         { "id": "claude-opus-4-8", "role": "capable-anthropic", "frontier": true, "pricing": null, "verifiedAt": "carried-over-from-allowlist" },
         { "id": "claude-fable-5", "role": "ultra-anthropic", "frontier": true, "pricing": null, "verifiedAt": "carried-over-from-allowlist" }
@@ -21,6 +22,7 @@
       "name": "Anthropic headless (claude -p)",
       "accessMethod": "claude -p one-shot (Agent SDK credit pot)",
       "status": "alive",
+      "probe": { "kind": "cli-version", "bin": "claude", "metered": false, "freeDefaultCovered": true },
       "topModels": [
         { "id": "claude-opus-4-8", "role": "capable-anthropic", "frontier": true, "pricing": null, "verifiedAt": "carried-over-from-allowlist" },
         { "id": "claude-sonnet-4-6", "role": "balanced-anthropic", "frontier": true, "pricing": null, "verifiedAt": "carried-over-from-allowlist" },
@@ -32,6 +34,7 @@
       "name": "Codex CLI",
       "accessMethod": "codex exec (ChatGPT account)",
       "status": "referenced-not-installed",
+      "probe": { "kind": "cli-version", "bin": "codex", "metered": false, "freeDefaultCovered": false },
       "topModels": [
         { "id": "gpt-5.5", "role": "capable-openai", "frontier": true, "pricing": null, "verifiedAt": "carried-over-from-allowlist" }
       ],
@@ -41,6 +44,7 @@
       "name": "Gemini CLI",
       "accessMethod": "gemini -m <model> (Homebrew formula, OAuth)",
       "status": "alive-but-deprecated-formula",
+      "probe": { "kind": "cli-version", "bin": "gemini", "metered": false, "freeDefaultCovered": true },
       "topModels": [
         { "id": "gemini-3.1-pro-preview", "role": "capable-google", "frontier": true, "pricing": null, "verifiedAt": "carried-over-from-allowlist" }
       ],
@@ -50,6 +54,7 @@
       "name": "pi CLI",
       "accessMethod": "pi --model <provider>/<id> (multi-provider: openai-codex, openrouter, ...)",
       "status": "alive",
+      "probe": { "kind": "cli-version", "bin": "pi", "metered": false, "vaultKeyName": "metered_openrouter_bench", "freeDefaultCovered": false },
       "topModels": [],
       "note": "Multi-provider consolidation door. Can reach OpenRouter (one door to many frontier models; vault key metered_openrouter_bench present). pi policy DENIES anthropic/claude via openrouter passthrough by default to protect subscription billing. No pin references this door yet, so topModels is empty (no frontier set to derive); the first enabled scan enumerates observed models for operator classification."
     }
@@ -90,5 +95,15 @@
   ],
   "$flaggedStaleNote": "Both prior flagged pins RESOLVED (operator-confirmed 2026-07-03): gemini capable swapped gemini-2.5-pro -> gemini-3.1-pro-preview (pin + topModels updated in the same change); codex capable stays gpt-5.5 (GA flagship — gpt-5.6-sol is preview-only/gov-gated/unreachable, NOT pinned). Nothing pending confirmation.",
   "flaggedStale": [],
-  "$frontierAllowlistNote": "The hand-maintained frontierAllowlist{} was SUPERSEDED by derivation (spec §1.4): the frontier set for each door is now the ids in doors[door].topModels[] carrying frontier:true. This removes a second hand-maintained list (the rot this registry fights). The lint keeps a backward-compat path: a door with a literal frontierAllowlist[door] and NO topModels behaves exactly as before; a door with BOTH emits a transition finding so the old hand-list can't silently linger."
+  "$frontierAllowlistNote": "The hand-maintained frontierAllowlist{} was SUPERSEDED by derivation (spec §1.4): the frontier set for each door is now the ids in doors[door].topModels[] carrying frontier:true. This removes a second hand-maintained list (the rot this registry fights). The lint keeps a backward-compat path: a door with a literal frontierAllowlist[door] and NO topModels behaves exactly as before; a door with BOTH emits a transition finding so the old hand-list can't silently linger.",
+  "$candidateDoorwaysNote": "candidateDoorways[] = the doorways the scan should PROBE FOR (spec §1.2/§2.5), INCLUDING ones not yet present in doors{}. A candidate reachable but absent from doors is surfaced as a newly-configured-doorway. The prober only activates a candidate whose probe.kind it supports; a candidate with no door entry / unsupported kind is recorded, never silently treated as reachable. openrouter / gemini-direct-api below are candidate-only (no door entry yet) so the candidate-detection machinery has real inputs to exercise.",
+  "candidateDoorways": [
+    "claude-code",
+    "anthropic-headless",
+    "codex-cli",
+    "gemini-cli",
+    "pi-cli",
+    "openrouter",
+    "gemini-direct-api"
+  ]
 }

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-07-04T18:41:14.577Z",
-  "instarVersion": "1.3.757",
+  "generatedAt": "2026-07-04T19:36:12.853Z",
+  "instarVersion": "1.3.758",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {
@@ -11,7 +11,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/session-start.sh",
-      "contentHash": "3a280757ac9c2c4a35cf63aa4ba2f4a954ee85be842715fd93a92aa0881325e3",
+      "contentHash": "abb2e8ea9b3e906f37767153ca1ef7442cfc92ba27a50a7eaaa09596c8d5eede",
       "since": "2025-01-01"
     },
     "hook:dangerous-command-guard": {
@@ -20,7 +20,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/dangerous-command-guard.sh",
-      "contentHash": "3a280757ac9c2c4a35cf63aa4ba2f4a954ee85be842715fd93a92aa0881325e3",
+      "contentHash": "abb2e8ea9b3e906f37767153ca1ef7442cfc92ba27a50a7eaaa09596c8d5eede",
       "since": "2025-01-01"
     },
     "hook:grounding-before-messaging": {
@@ -29,7 +29,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/grounding-before-messaging.sh",
-      "contentHash": "3a280757ac9c2c4a35cf63aa4ba2f4a954ee85be842715fd93a92aa0881325e3",
+      "contentHash": "abb2e8ea9b3e906f37767153ca1ef7442cfc92ba27a50a7eaaa09596c8d5eede",
       "since": "2025-01-01"
     },
     "hook:compaction-recovery": {
@@ -38,7 +38,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/compaction-recovery.sh",
-      "contentHash": "3a280757ac9c2c4a35cf63aa4ba2f4a954ee85be842715fd93a92aa0881325e3",
+      "contentHash": "abb2e8ea9b3e906f37767153ca1ef7442cfc92ba27a50a7eaaa09596c8d5eede",
       "since": "2025-01-01"
     },
     "hook:external-operation-gate": {
@@ -47,7 +47,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-operation-gate.js",
-      "contentHash": "3a280757ac9c2c4a35cf63aa4ba2f4a954ee85be842715fd93a92aa0881325e3",
+      "contentHash": "abb2e8ea9b3e906f37767153ca1ef7442cfc92ba27a50a7eaaa09596c8d5eede",
       "since": "2025-01-01"
     },
     "hook:deferral-detector": {
@@ -56,7 +56,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/deferral-detector.js",
-      "contentHash": "3a280757ac9c2c4a35cf63aa4ba2f4a954ee85be842715fd93a92aa0881325e3",
+      "contentHash": "abb2e8ea9b3e906f37767153ca1ef7442cfc92ba27a50a7eaaa09596c8d5eede",
       "since": "2025-01-01"
     },
     "hook:self-stop-guard": {
@@ -65,7 +65,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/self-stop-guard.js",
-      "contentHash": "3a280757ac9c2c4a35cf63aa4ba2f4a954ee85be842715fd93a92aa0881325e3",
+      "contentHash": "abb2e8ea9b3e906f37767153ca1ef7442cfc92ba27a50a7eaaa09596c8d5eede",
       "since": "2025-01-01"
     },
     "hook:post-action-reflection": {
@@ -74,7 +74,7 @@
       "domain": "evolution",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/post-action-reflection.js",
-      "contentHash": "3a280757ac9c2c4a35cf63aa4ba2f4a954ee85be842715fd93a92aa0881325e3",
+      "contentHash": "abb2e8ea9b3e906f37767153ca1ef7442cfc92ba27a50a7eaaa09596c8d5eede",
       "since": "2025-01-01"
     },
     "hook:external-communication-guard": {
@@ -83,7 +83,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-communication-guard.js",
-      "contentHash": "3a280757ac9c2c4a35cf63aa4ba2f4a954ee85be842715fd93a92aa0881325e3",
+      "contentHash": "abb2e8ea9b3e906f37767153ca1ef7442cfc92ba27a50a7eaaa09596c8d5eede",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-collector": {
@@ -92,7 +92,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-collector.js",
-      "contentHash": "3a280757ac9c2c4a35cf63aa4ba2f4a954ee85be842715fd93a92aa0881325e3",
+      "contentHash": "abb2e8ea9b3e906f37767153ca1ef7442cfc92ba27a50a7eaaa09596c8d5eede",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-checkpoint": {
@@ -101,7 +101,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-checkpoint.js",
-      "contentHash": "3a280757ac9c2c4a35cf63aa4ba2f4a954ee85be842715fd93a92aa0881325e3",
+      "contentHash": "abb2e8ea9b3e906f37767153ca1ef7442cfc92ba27a50a7eaaa09596c8d5eede",
       "since": "2025-01-01"
     },
     "hook:free-text-guard": {
@@ -110,7 +110,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/free-text-guard.sh",
-      "contentHash": "3a280757ac9c2c4a35cf63aa4ba2f4a954ee85be842715fd93a92aa0881325e3",
+      "contentHash": "abb2e8ea9b3e906f37767153ca1ef7442cfc92ba27a50a7eaaa09596c8d5eede",
       "since": "2025-01-01"
     },
     "hook:claim-intercept": {
@@ -119,7 +119,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept.js",
-      "contentHash": "3a280757ac9c2c4a35cf63aa4ba2f4a954ee85be842715fd93a92aa0881325e3",
+      "contentHash": "abb2e8ea9b3e906f37767153ca1ef7442cfc92ba27a50a7eaaa09596c8d5eede",
       "since": "2025-01-01"
     },
     "hook:claim-intercept-response": {
@@ -128,7 +128,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept-response.js",
-      "contentHash": "3a280757ac9c2c4a35cf63aa4ba2f4a954ee85be842715fd93a92aa0881325e3",
+      "contentHash": "abb2e8ea9b3e906f37767153ca1ef7442cfc92ba27a50a7eaaa09596c8d5eede",
       "since": "2025-01-01"
     },
     "hook:stop-gate-router": {
@@ -137,7 +137,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/stop-gate-router.js",
-      "contentHash": "3a280757ac9c2c4a35cf63aa4ba2f4a954ee85be842715fd93a92aa0881325e3",
+      "contentHash": "abb2e8ea9b3e906f37767153ca1ef7442cfc92ba27a50a7eaaa09596c8d5eede",
       "since": "2025-01-01"
     },
     "hook:auto-approve-permissions": {
@@ -146,7 +146,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/auto-approve-permissions.js",
-      "contentHash": "3a280757ac9c2c4a35cf63aa4ba2f4a954ee85be842715fd93a92aa0881325e3",
+      "contentHash": "abb2e8ea9b3e906f37767153ca1ef7442cfc92ba27a50a7eaaa09596c8d5eede",
       "since": "2025-01-01"
     },
     "job:health-check": {
@@ -1562,7 +1562,7 @@
       "type": "subsystem",
       "domain": "updates",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
-      "contentHash": "3a280757ac9c2c4a35cf63aa4ba2f4a954ee85be842715fd93a92aa0881325e3",
+      "contentHash": "abb2e8ea9b3e906f37767153ca1ef7442cfc92ba27a50a7eaaa09596c8d5eede",
       "since": "2025-01-01"
     },
     "subsystem:scheduler": {
@@ -1570,7 +1570,7 @@
       "type": "subsystem",
       "domain": "scheduling",
       "sourcePath": "src/scheduler/JobScheduler.ts",
-      "contentHash": "8f526a365e7292029224135303525e89920435ced45b292cc4c50e47dc297ea4",
+      "contentHash": "0c92bf7ce40b2efdede00ee90f9c0bf8997c787691ae0054d6479ad96f28be67",
       "since": "2025-01-01"
     },
     "subsystem:project-mapper": {

package/src/scaffold/templates/jobs/instar/doorway-scan.md

@@ -0,0 +1,32 @@
+---
+name: Doorway Scan
+description: "Cadenced live re-probe of every doorway + top-model map refresh + drift diff. A deterministic prober (scripts/doorway-scan.mjs) probes CLIs (which/--version/model-list) and free model-list APIs, updates the per-agent live scan-state (.instar/state/doorway-scan.json), diffs against the previous scan, and raises ONE operator attention item with ONLY the changes (jargon-safe body + a private-view link to the raw diff). It NEVER auto-edits canonical source. Free probes by default; metered liveness / web-verify are opt-in, budget-capped, human-manual-only, and refuse on an unknown price. Ships OFF by default (enabled:false). perMachineIndependent — each machine scans its own disk. Spec: docs/specs/DOORWAY-MODEL-KNOWLEDGE-REGISTRY-SPEC.md §2."
+schedule: "0 4 * * 1"
+priority: low
+expectedDurationMinutes: 10
+model: haiku
+supervision: tier1
+enabled: false
+perMachineIndependent: true
+tags:
+  - cat:maintenance
+  - role:worker
+  - exec:prompt
+gate: curl -sf http://localhost:${INSTAR_PORT:-4042}/health >/dev/null 2>&1
+toolAllowlist: ["Bash"]
+unrestrictedTools: false
+mcpAccess: none
+---
+Run one doorway scan. This job only INVOKES the deterministic prober and sanity-checks that it produced a well-formed result — the prober owns 100% of the network I/O, secret handling, timeouts, sanitization, and delivery (it performs the POST /view + POST /attention itself, in-process). You have Bash ONLY — no Edit/Write tool — and a PreToolUse command-allowlist guard restricts this session's Bash to the sanctioned prober invocation + the /health gate + read-only plumbing. Do NOT try to edit any source file; this job NEVER auto-applies a change to the canonical registry (a stale map surfaces as a maintainer diff for the operator, never an edit).
+
+1. **Prober-presence gate.** The prober is instar source — present only on a source-carrying agent (a maintainer/dev agent like Echo, and the fixture repos), NOT on a pure end-user agent. Run this SINGLE command (the command-allowlist guard permits only simple invocations — never chain it with `&&`/`||`/`;`):
+   `test -f scripts/doorway-scan.mjs`
+   If it exits NON-ZERO (the prober is absent), this agent carries no prober — EXIT SILENTLY, there is nothing to do (the honest no-op path every non-source agent takes). Do not message anyone. Only if it exits zero (present) do you proceed to step 2.
+
+2. **Run the deterministic prober at the free scope (the ONLY scope the scheduled cadence runs).** This is a FIXED literal invocation — never substitute the scope, never append a metered scope; a metered scope spends money and is human-manual-only:
+   `node scripts/doorway-scan.mjs --scope free-probes`
+   The prober probes each configured door, updates the machine-local scan-state (`.instar/state/doorway-scan.json`), diffs against the last-surfaced baseline, and — only if there is a real, debounced, live-corroborated change — raises ONE attention item itself, in-process, with a machine-qualified `sourceContext` (`doorway-scan:<machineId>`) so two machines' findings never coalesce into one row. Free model-LIST probes spend ZERO tokens; the scheduled cadence spends no metered budget.
+
+3. **Tier-1 supervision (your job) — sanity-check the run, do NOT re-surface anything yourself.** Confirm the prober exited cleanly and wrote/refreshed the scan-state. A crashed/partial run is NOT a signal — note it once and exit; the next cadence retries (the prober is fail-safe per-probe, and a completely-failed scan is handled by the prober's own breaker, which retries on a widening backoff and escalates ONE deduped item only after 3 consecutive complete failures). The prober already delivered any diff in-process — you do NOT build or POST an attention item, and you do NOT relay progress to Telegram.
+
+4. Exit. This job produces a review artifact for the operator (a maintainer diff), not a running commentary. A clean scan is not news — surface nothing. The canonical map changes only when the operator folds a surfaced diff via instar-dev and re-runs the freshness lint; this job never touches source.

package/upgrades/1.3.758.md

@@ -0,0 +1,37 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Doorway/Model Knowledge Registry — rollout increment 2 (the deterministic prober + live scan-state + the scan job, per `docs/specs/DOORWAY-MODEL-KNOWLEDGE-REGISTRY-SPEC.md` §Rollout step 2). **All of it ships DARK**: the scan job is `enabled:false` and no cadence runs until an operator enables it (rollout step 4). Nothing spends metered budget, mutates source, or changes model routing.
+
+- **The deterministic prober** (`scripts/doorway-scan.mjs`, spec §2.0) — the security spine. It owns 100% of the network I/O, secret handling, timeouts, size-caps, sanitization, the scan-state read/write, the diff/debounce/breaker, and the in-process `POST /view` + `POST /attention` delivery; a tier-1 job session only invokes it. Secret-safe (vault key NAMES only; a value is used in an in-process request header, never in argv/environ/scan-state). Money is quadruple-gated: the scheduled cadence runs a fixed `--scope free-probes` (zero metered spend), and a metered scope is refused unless a manual-marker env AND a positive `budgetCapUsd` AND a known, fresh price are all present — plus a self-standing scheduled-session refusal that holds even if the §2.7 guard fails open.
+- **Machine-local live scan-state** (`.instar/state/doorway-scan.json`, spec §1.3) — with an EXHAUSTIVE `loadScanState()` read-clamp that re-validates every field on every load (the on-disk plaintext file is treated as untrusted a local writer could poison after a clamped write), plus a coverage test so the clamp can't silently regrow holes.
+- **Diff / debounce / breaker** (spec §2.3/§2.6) — an asymmetric 2-scan debounce (an alarming true→false flip needs corroboration; a recovery flips immediately), a `consecutiveCompleteFailures` breaker that retries on a widening backoff and escalates ONE deduped item only after 3 consecutive zero-door scans (P22 self-heal-before-notify), a tone-gate-safe jargon-safe attention body (raw diff in a private view; never a localhost/token-bearing link), and delivery robustness (the diff baseline advances only on a confirmed 2xx, with an initial-seed carve-out — no silent notice loss, no fresh-state flood).
+- **The dark scan job template** (`src/scaffold/templates/jobs/instar/doorway-scan.md`, `enabled:false`, tier-1/haiku, `toolAllowlist:["Bash"]`) + the new **`perMachineIndependent` job-def flag** (spec §2.8/D11) threaded through `JobDefinition` → `PerSlugManifest` → `buildPerSlugManifest` → `InstallBuiltinJobs` → `manifestToJobDefinition`, and honored at `JobScheduler.triggerJob` (it skips the global jobSlug claim/lease so every machine scans its own disk).
+- **The §2.7 PreToolUse command-allowlist guard** (`doorway-scan-guard.js`, installed via the always-overwrite `instar/` migration path) — a genuine stateful shell lexer (not a regex) that permits ONLY the sanctioned prober invocation + a host-pinned localhost curl + read-only `test -f`/`cat`/`jq -r`, refusing every write/exec/spend primitive. Scope resolution fails OPEN (never blocks an unrelated session); command matching fails CLOSED inside the doorway-scan session.
+- **Manifest enrichment** (`scripts/model-registry-freshness.manifest.json`) — additively added the per-door `probe{}` block + `candidateDoorways[]` the prober reads to know HOW to re-verify each door. Backward-compatible: the freshness lint ignores both.
+
+`GET /doorways`, the CLAUDE.md awareness block, and the `maintenance.doorwayScan` config-knob are increment 3; flipping the lint to `strict` + ratifying the standard is increment 5. Neither is in this increment.
+
+## What to Tell Your User
+
+Nothing changes for you right now — this increment ships **switched off**. It lands the machinery for a future opt-in weekly "doorway scan" that will quietly re-check which AI models each of your doorways (Claude Code, Codex, Gemini, a paid API key, …) can still reach, keep the map current, and send you ONE plain-English heads-up only when something actually changes. Until you deliberately turn the job on (a later step), it does no probing, spends no money, and sends no messages. There is nothing to do and nothing new to see.
+
+## Summary of New Capabilities
+
+- **(Dark / off by default)** A deterministic doorway prober + a per-machine live "what models can I reach?" scan-state, with an asymmetric debounce, a self-healing zero-doors breaker, and no-silent-loss delivery — none of it active until the operator enables the `doorway-scan` job.
+- **A new `perMachineIndependent` job flag** so a per-machine-local job (like the doorway scan) runs on every machine independently instead of the lease electing just one.
+- **A structural command-allowlist guard** that keeps the (future, opt-in) scan session from ever editing source or spending money — a genuine shell-parser allowlist that fails open outside that one session and fails closed inside it.
+
+## Evidence
+
+- `tests/unit/doorway-scan-prober.test.ts` (45) — clamp/sanitize, the exhaustive read-funnel + coverage, the P20/L5 probeStatus mapping, the asymmetric debounce (incl. flip-then-flip-back-clears), the diff, the breaker + backoff, the fail-closed money gate (D8/D9/D10 + pricing staleness + self-standing scheduled refusal), tone-gate-safe body + private-view XSS neutralization, the delivery-robustness planner, and the injected-dep network probes.
+- `tests/unit/doorway-scan-guard.test.ts` (30) — drives the REAL deployed hook as a subprocess across the full §2.7 matrix: sanctioned shapes PERMITTED (incl. quoted-arg / collapsed-whitespace normalizations); cp/interpreters/perl/git-checkout/heredoc/compound/substitution/env-prefix/redirect/output-redirect/non-localhost-curl/metered-scope all REFUSED; scope fails OPEN; command matching fails CLOSED.
+- `tests/unit/doorway-scan-job-template.test.ts` (11) — enabled:false, tier1/haiku, perMachineIndependent:true, weekday-pinned cron, Bash-only toolAllowlist, the fixed `--scope free-probes` literal, no `+liveness`/`+web-verify` string, the prober-presence gate, no data-carrying curl.
+- `tests/unit/scheduler/per-machine-independent.test.ts` (2) — a job WITHOUT the flag still yields on `hasRemoteClaim===true`; a `perMachineIndependent` job never consults the claim path and proceeds.
+- `tests/unit/instar-settings-hooks.test.ts` + `tests/unit/migration-parity-hooks.test.ts` — updated for the new guard entry (registered in settings + accepted migrator-only gap, matching the pr-hand-lease-guard precedent).
+- `node scripts/lint-model-registry-freshness.mjs` → PASS on the enriched manifest; `npx tsc --noEmit` clean; full `pnpm lint` chain PASS; `pnpm build` OK (the new job hashes into the built-in-job lockfile). End-to-end: the real `doorway-scan.md` installs via `installBuiltinJobs` with zero errors; its per-slug manifest carries `enabled:false` + `perMachineIndependent:true`.
+- Deferred items (spec §Deferred DF1-DF6) remain tracked in `docs/specs/reports/DOORWAY-MODEL-KNOWLEDGE-REGISTRY-followups.md` (filed by inc1).

package/upgrades/side-effects/doorway-model-registry-inc2.md

@@ -0,0 +1,96 @@
+# Side-Effects Review — Doorway/Model Knowledge Registry, increment 2 (deterministic prober + scan-state + diff/debounce/breaker + dark job + §2.7 guard)
+
+**Version / slug:** `doorway-model-registry-inc2`
+**Date:** `2026-07-04`
+**Author:** `echo`
+**Second-pass reviewer:** `recommended` — this increment adds a real BLOCK authority (the §2.7 PreToolUse command-allowlist guard hook, which can `exit 2` and block a Bash call) and touches the `JobScheduler` claim/lease seam. See §1/§2/§4/§5.
+
+## Summary of the change
+
+Second rollout increment of `DOORWAY-MODEL-KNOWLEDGE-REGISTRY-SPEC.md` (§Rollout step 2), landed DARK: the doorway-scan job ships `enabled:false` and nothing runs on a cadence until an operator enables it (step 4). Artifacts:
+
+1. **`scripts/doorway-scan.mjs`** — the deterministic prober (the security spine, §2.0). Owns all network I/O, secret handling, timeouts, size-caps, sanitization, scan-state read/write, diff/debounce/breaker, and the in-process `POST /view` + `POST /attention` delivery. Exports pure helpers for unit tests; `main()` runs only when invoked directly and is a harmless no-op stub in this dark increment.
+2. **Machine-local scan-state schema** (`.instar/state/doorway-scan.json`, §1.3) — created lazily; an EXHAUSTIVE `loadScanState()` read-clamp re-validates every field on every load + a coverage test.
+3. **Diff / debounce / breaker** (§2.3/§2.6) — asymmetric 2-scan debounce, a `consecutiveCompleteFailures` zero-doors breaker (retry-then-escalate, P22), tone-gate-safe attention body (raw diff → private view; never localhost/token link), and confirmed-delivery baseline advancement (no silent loss, no fresh-state flood).
+4. **Dark job template** (`src/scaffold/templates/jobs/instar/doorway-scan.md`, `enabled:false`, tier1/haiku, `toolAllowlist:["Bash"]`) + the new **`perMachineIndependent` job-def flag** threaded `JobDefinition` → `PerSlugManifest` → `buildPerSlugManifest` → `InstallBuiltinJobs` → `manifestToJobDefinition`, honored at `JobScheduler.triggerJob` (skips the global jobSlug claim/lease).
+5. **The §2.7 PreToolUse command-allowlist guard** (`doorway-scan-guard.js`) — installed via the always-overwrite `instar/` migration path + registered in `INSTAR_BASH_PRETOOLUSE_HOOKS`. A genuine stateful shell lexer allowing only the sanctioned prober invocation + a host-pinned localhost curl + read-only `test -f`/`cat`/`jq -r`.
+6. **Manifest enrichment** — additive per-door `probe{}` + `candidateDoorways[]` (backward-compatible; the freshness lint ignores them).
+
+## Decision-point inventory
+
+- **`doorway-scan-guard.js` (NEW block authority)** — `add` — a PreToolUse Bash hook that can `exit 2` (block). SCOPE resolution fails OPEN; command matching fails CLOSED. Scoped by `INSTAR_JOB_SLUG==='doorway-scan'` (env-first, zero disk I/O off the hot path) → strict no-op in every other session.
+- **`JobScheduler.triggerJob` claim/lease seam** — `modify` — a `perMachineIndependent` job now bypasses the claim check + claim-taking. Behavior for every job WITHOUT the flag is byte-identical (regression test).
+- **The money gate (`meteredScopeGate`)** — `add` — a fail-closed predicate; refuses all metered spend on the scheduled/dark path. No metered completion is ever ISSUED in this increment (all test paths refuse before issuance).
+- No message/dispatch/tone-gate decision point is touched.
+
+---
+
+## 1. Over-block
+
+The §2.7 guard is a block authority, so over-block is the primary risk. Mitigations:
+- **Tightly scoped:** the guard is an immediate no-op unless `INSTAR_JOB_SLUG==='doorway-scan'` (a scheduler-set env only the dark doorway-scan job carries). An instar-dev session, an interactive session, and every other job session hit the env-first fast path and ALLOW with zero disk I/O — proven by the subprocess test (a dangerous `cp` under another slug / no slug / a non-Bash tool all return exit 0).
+- **Fails OPEN on scope:** any error resolving whether this is the doorway-scan session → ALLOW (exactly like the sibling `pr-hand-lease-guard.js`). A guard bug can never lock out an unrelated session's Bash. Proven (malformed stdin → exit 0).
+- **Inside the doorway-scan session, over-block is intentional and bounded:** the guard fails CLOSED, but that session's only legitimate commands are the sanctioned shapes (the job body issues exactly `test -f …` and `node scripts/doorway-scan.mjs --scope free-probes`). A false-refuse there breaks the DARK scan loudly/safely, never widens scope — and the job is off by default, so the blast radius until step 4 is nil.
+- The `enabled:false` job means the guard is never even reached on any agent until an operator opts in.
+
+## 2. Under-block
+
+- **Guard under-block (letting a source write through):** the matcher is an ALLOWLIST with a genuine lexer — anything not provably ONE sanctioned simple command is REFUSED, so obfuscation (compounds, substitution, redirects, env-prefix, interpreters, heredocs, `curl -o`, non-localhost curl) is refused by construction, not by a denylist that can miss an idiom. The adversarial subprocess matrix asserts every such primitive REFUSED.
+- **Money under-gate (a scheduled run spending):** quadruple-gated + a self-standing scheduled-session refusal that holds even if the guard fails open. `meteredScopeGate` refuses on free-scope / scheduled-session / no-marker / absent-or-nonpositive-budget / unknown-or-stale-price / over-cap — tested on every branch. No completion is issued on any refused path.
+- **Scheduler under-block:** `perMachineIndependent` deliberately bypasses the claim — that is the intended behavior for a per-machine-idempotent, cheap, local-only scan (the misuse warning on the flag documents the boundary). No shared/canonical state is mutated on the cadence.
+
+## 3. Level-of-abstraction fit
+
+Correct layers. The prober is a deterministic script (a detector that produces a signal + a maintainer diff), never a runtime authority over routing (canonical is authoritative — §1.1). The guard is a structural PreToolUse enforcer (Structure > Willpower) that replaces a prompt-level "don't edit source" wish. The `perMachineIndependent` flag lives on `JobDefinition` alongside its sibling `writesState`/`resumeOnReap` opt-in flags — the honest place for a per-job scheduling property.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** `docs/signal-vs-authority.md`
+
+- The **prober + diff/breaker** are SIGNAL: they surface a maintainer diff / a deduped escalation to the operator; they never auto-apply to source (enforced structurally by the guard + `toolAllowlist`), never gate a message.
+- The **§2.7 guard** is an AUTHORITY, but its veto rests on an OBJECTIVE, decidable shape check (a genuine shell-grammar parse to a single sanctioned simple-command), not brittle inference; it fails OPEN on scope (never blocks the wrong session) and CLOSED on match (a refused command breaks the dark scan safely). This is the same shape as the sibling `pr-hand-lease-guard.js` and the eli16/release-fragment gates: block carried by an objective binary, escape hatch is "run a sanctioned command."
+- The **money gate** is an authority over spend, and it is fail-closed by construction (no spend without an explicit manual marker + positive cap + known/fresh price + non-scheduled session).
+
+---
+
+## 5. Interactions
+
+- **Shadowing:** the guard is one more PreToolUse Bash entry appended to `INSTAR_BASH_PRETOOLUSE_HOOKS`; it does not replace or reorder the existing guards, and it is a no-op outside the doorway-scan slug, so it never shadows another guard's decision.
+- **Double-fire:** none. The prober is the sole in-process POST actor; the job session runs no data-carrying curl. The scan job is off; when enabled it is `perMachineIndependent` (one run per machine, deliberately — never a duplicated cross-machine side-effect, since it only reads local disk + writes local scan-state).
+- **Races:** the scan-state is a single machine-local file written atomically (temp + rename); no cross-process shared mutable state. `perMachineIndependent` removes the claim path entirely, so there is no claim race for this job.
+- **Feedback loops:** none. The prober never edits source; the diff is a review artifact. The breaker retries on a widening backoff (never a tight loop) and escalates once (deduped).
+
+## 6. External surfaces
+
+- **Other agents on the machine:** the guard fires fleet-wide on every Bash call but is a strict env-first no-op for all non-doorway-scan sessions (zero disk I/O on that path).
+- **Install base:** the job template installs via `InstallBuiltinJobs` (non-destructive install-if-missing, on init + update). The guard hook installs via the always-overwrite `instar/` `migrateHooks()` path + `ensureInstarBashPreToolUseHooks` settings wiring — migrator-only for now (documented gap, matching pr-hand-lease-guard: fires only in the dark job's session, so inert until enabled; a fresh-init agent gets it on first auto-update, well before any operator enables the job). The prober + manifest enrichment ship as source (present on source-carrying agents; absent on pure end-user agents → the prober-presence gate makes the job a silent no-op).
+- **External systems (Telegram/Slack/GitHub/Cloudflare):** none in this dark increment (the prober's `POST /attention`/`POST /view` are local + only reached when the job is enabled).
+- **Persistent state:** `.instar/state/doorway-scan.json` (machine-local, created lazily on first scan, EXCLUDED from the backup manifest by design — never replicated onto another machine). No writes happen until the job is enabled.
+- **Operator surface (Mobile-Complete Operator Actions):** none added in this increment (the `GET /doorways` read surface + CLAUDE.md awareness are increment 3). Not applicable.
+
+## 6b. Operator-surface quality
+
+No operator-facing surface added — not applicable. (When the job is enabled in step 4, its only operator output is a jargon-safe attention item + a private view — both already designed tone-gate-safe.)
+
+---
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+- The **prober + manifest + guard + job template** are git-tracked instar source / built-in templates → byte-identical on every machine by construction. No divergence, no replication path.
+- The **live scan-state** is machine-local BY DESIGN (a door's liveness is a physical fact of one disk — the identical posture of the Playwright Profile Registry). It is deliberately EXCLUDED from `BackupManager.includeFiles` — restoring one machine's disk-liveness onto another would be actively false. A `perMachineIndependent` job is the structural expression: each machine runs its own scan and writes its own scan-state; no lease elects a single machine.
+- **One-voice / notices:** when enabled, each machine's diff uses a machine-qualified `sourceContext` (`doorway-scan:<machineId>`) so two machines' findings stay DISTINCT rows (never coalesced), and route to the alerts/hub topic (P23) — not a per-machine forum topic.
+
+---
+
+## 8. Rollback cost
+
+DARK increment — **revert-and-patch, near-zero blast radius.**
+- Hot-fix: `git revert` the PR. The guard hook is removed on the next migration (always-overwrite path re-writes the hook set; a settings entry pointing at a now-absent hook is a non-blocking error → Bash proceeds). The job template is retired by `InstallBuiltinJobs` when the template disappears (manifest flipped `enabled:false`+retired). The `perMachineIndependent` reverts cleanly (the flag simply disappears; jobs fall back to the claim path). The manifest `probe{}`/`candidateDoorways` are additive and the lint ignores them, so removing them is inert.
+- Data migration: none — no scan-state is written while the job is off; a stale scan-state file is regenerable and self-healing (corrupt/old-schema → fresh, additive backfill).
+- Agent state repair: none.
+- User visibility: none — everything is off by default.
+- Kill switch short of revert: the job stays `enabled:false`; the guard is inert outside the (disabled) doorway-scan session.
+
+## Second-pass review
+
+Concur with the review. I independently read the guard hook string in `getDoorwayScanGuardHook()`, the `JobScheduler.triggerJob` staged diff, the `meteredScopeGate`/`main()`/lexer in `scripts/doorway-scan.mjs`, and all three test files. The fail-OPEN-on-scope / fail-CLOSED-on-match claim is TRUE in the code: Region A returns `exit 0` for a non-Bash tool, a non-string command, any JSON-parse error, and — the load-bearing check — any session where `INSTAR_JOB_SLUG !== 'doorway-scan'` (plus an 8s fail-open stdin backstop), so an instar-dev/interactive/other-job session can never be over-blocked; Region B (only reachable inside the doorway-scan session) blocks with `exit 2` on any non-sanctioned command AND on a thrown lexer error. `lexSimpleCommand` is a genuine stateful char-by-char tokenizer (single/double-quote spans, backslash escapes, quote-state tracking — not a substring/regex scan) that refuses every operator/redirection/expansion/substitution/newline and the leading `NAME=` env-prefix; I could not find a source-write or metered-spend primitive that slips through (`node` is admitted only for the exact prober argv, so `node -e` is refused; curl is host-pinned to localhost with output-redirect and non-allowlisted flags refused), and the adversarial subprocess matrix drives the real deployed hook and asserts both directions. The `perMachineIndependent` bypass leaves the no-flag path byte-identical (the flag is falsy for normal jobs, so `claimPath`, `remoteHeld`, and the claim-taking `if/else-if/else` all reduce to the original expressions; the regression test confirms a no-flag job still yields on a remote claim while the pmi job never consults the claim path). The money gate is genuinely fail-closed: the self-standing scheduled-session refusal precedes the marker check, both defaults (`manualMarker=false`, `isScheduledSession=false`) still refuse, `main()` issues no completion and forces `free-probes` on the scheduled/dark path, and every refusal branch is unit-tested. (Note: `grep` for the literal `meteredScopeGate` intermittently returned nothing in this environment, but Read + `sed` both show the full branch-by-branch test suite at lines 223-254 — a tooling quirk, not a missing test.)