feat(orchestration): add adaptive routing and cooldown continuation

CHANGELOG.md

@@ -2,6 +2,46 @@
 
 ## Unreleased
 
+### Subscription Cooldown Continuation & Compute Survival — vNext.10.2 Phase 8
+
+- Added durable, resource-scoped Strong subscription cooldown state at the
+  Objective/WorkUnit boundary. Quota refusal keeps readiness unchanged,
+  restores the pre-dispatch implementation-attempt number, and records a
+  recoverable wait instead of an implementation defect or human blocker.
+- Changed mission Objective scheduling so an outer Strong quota defer enters
+  the bounded WorkUnit candidate controller. Resource-waiting Strong units no
+  longer hide later READY Secondary/research candidates; dependencies remain
+  authoritative and the Job enters `WAITING_RESOURCE` only when no permitted
+  candidate remains runnable.
+- Preserved candidates, `CANDIDATE_READY` resume, completed Secondary work,
+  and sticky Secondary-to-Strong fallback state across process/supervisor
+  restart and resource recovery. PREFER/AUTO/OFF and API-spend semantics are
+  unchanged, and availability flips never preempt an owned attempt.
+- Added resource episode telemetry and deterministic qualification over a
+  15-WorkUnit mixed graph and fake five-hour outage: eight useful Secondary
+  completions during cooldown, four Strong waits, one restart, final
+  completion, and zero redo, candidate loss, duplicate dispatch, avoidable
+  idle periods, repair-budget resets, unexpected blocks, or human actions.
+
+### Adaptive Secondary Routing, Repair & Strong Fallback — vNext.10.2 Phase 7
+
+- Added additive `OFF` (default), `AUTO`, and `PREFER` Objective-builder
+  routing after Phase 6 eligibility, using existing subscription economic
+  modes and normalized local availability without changing API spend,
+  authority, execution-lane, or compute-locality policy.
+- Added versioned, explainable routing decisions and durable content-bound
+  attempt chains with one Secondary repair by default, deterministic
+  no-progress fingerprints, sticky Strong fallback, restart-safe freshness,
+  and one bounded Phase 5 context widening for `NEEDS_MORE_CONTEXT`.
+- Preserved failed Secondary candidates, patches, changed files, verification
+  evidence, and provider telemetry. Repair replays that work, and Strong
+  fallback receives it in a bounded continuation packet while remaining free
+  to repair or replace bad code through the normal candidate lifecycle.
+- Added routing/outcome/cost telemetry and `StrongBuilderAvoidanceRatio`, plus
+  OFF/PREFER/AUTO, unavailable-provider, repair/fallback, no-progress,
+  persistence, material-reset, API-guard, and mixed 15-unit qualification
+  coverage.
+
 ### Secondary Eligibility & Work Readiness — vNext.10.2 Phase 6
 
 - Added deterministic, versioned `WorkReadinessAssessment` and

contracts/orchestration-contract.json

@@ -462,6 +462,9 @@
     "browser_scenario_completed",
     "browser_scenario_started",
     "budget_exhausted",
+    "builder_routing_attempt_completed",
+    "builder_routing_candidate_finalized",
+    "builder_routing_decided",
     "candidate_failed",
     "candidate_ready",
     "candidate_resume_missing",
@@ -565,7 +568,11 @@
     "research_fallback_started",
     "research_replan_caused",
     "research_used",
+    "resource_cooldown_observed",
+    "resource_cooldown_started",
+    "resource_recovered",
     "resource_wait_ended",
+    "resource_wait_entered",
     "resource_wait_selected",
     "resource_wait_started",
     "runtime_research_eligible",
@@ -591,9 +598,12 @@
     "toolchain_repair_started",
     "toolsmith_grant_denied",
     "toolsmith_grant_issued",
+    "useful_work_during_cooldown",
     "ux_critique_completed",
     "verification_failed",
     "waiting_retry",
+    "work_unit_resource_wait_ended",
+    "work_unit_resource_wait_started",
     "worker_escalated",
     "worker_selected",
     "worker_started",
@@ -1120,6 +1130,12 @@
     "NO_API_SPEND_WITHOUT_AUTHORITY",
     "RECOVERY_REFERENCES_REAL_ATTEMPTS"
   ],
+  "strongResourceAvailabilities": [
+    "AVAILABLE",
+    "COOLDOWN",
+    "QUOTA_EXHAUSTED",
+    "RATE_LIMITED"
+  ],
   "subscriptionGapReasons": [
     "FIVE_HOUR_EXHAUSTED",
     "PRE_RESET_BURN_UNSAFE",

contracts/schema-versions.json

@@ -8,6 +8,9 @@
   "autonomyTelemetry": "1.0.0",
   "browserScenario": "1.0.0",
   "builderPacketCompilation": "1.0.0",
+  "builderRoutingDecision": "1.0.0",
+  "builderRoutingState": "1.0.0",
+  "builderRoutingTelemetry": "1.0.0",
   "candidateArtifact": "1.1.0",
   "closureLedger": "1.0.0",
   "contextMetrics": "1.0.0",
@@ -40,6 +43,7 @@
   "missionCoverage": "1.0.0",
   "missionSeal": "1.0.0",
   "missionState": "1.0.0",
+  "objectiveCooldownState": "1.0.0",
   "objectiveWorker": "1.0.0",
   "orchestrationCheckpoint": "1.0.0",
   "orchestrationState": "1.0.0",

docs/README.md

@@ -162,6 +162,12 @@ the intent in the evening, run one command, read the report in the morning.
 - [Secondary Work Readiness](orchestration/secondary-work-readiness.md)
   — deterministic Phase 6 per-WorkUnit admission, blockers, freshness, and
   telemetry without automatic routing.
+- [Adaptive Secondary routing](orchestration/adaptive-secondary-routing.md)
+  — Phase 7 OFF/AUTO/PREFER routing, bounded repair, preserved candidate
+  continuation, Strong fallback, resume state, and token-avoidance telemetry.
+- [Subscription cooldown continuation](orchestration/subscription-cooldown-continuation.md)
+  — Phase 8 resource-scoped Strong waits, mixed READY-set continuation,
+  restart/recovery, no-redo guarantees, and fake five-hour qualification.
 - [Context projection](orchestration/context-projection.md) — share truth,
   not context: what each isolated worker sees, hashed and staleness-checked.
 - [Sub-agent isolation](orchestration/subagent-isolation.md) — worker

docs/local-model.md

@@ -12,8 +12,10 @@ selects fresh source and tests first, so the direct model needs no repository
 tools for ordinary bounded implementation work. Phase 6
 [Secondary Work Readiness](orchestration/secondary-work-readiness.md) then
 checks the individual WorkUnit's knowledge, entropy, specificity, trusted
-verification, context, authority, mutation scope, and dependencies. This is
-admission evidence only; it does not automatically route work to the model.
+verification, context, authority, mutation scope, and dependencies. Phase 7
+[Adaptive Secondary routing](orchestration/adaptive-secondary-routing.md) can
+then opt eligible Objective work into `AUTO` or `PREFER`; the default remains
+`OFF`, and an unavailable local model immediately falls through to Strong.
 
 The local model is a **worker**, never an authority: its answers are
 schema-validated structured proposals that deterministic policy accepts,

docs/orchestration/adaptive-secondary-routing.md

@@ -0,0 +1,206 @@
+# Adaptive Secondary routing, repair, and Strong fallback
+
+Phase 7 of vNext.10.2 turns the Phase 6 readiness decision into an
+explainable Objective-builder route. Eligibility and preference remain two
+different decisions:
+
+> `ELIGIBLE` means Secondary is legitimate. It never means Secondary is
+> mandatory.
+
+```text
+READY WorkUnit
+      ↓ Phase 5 packet + Phase 6 readiness
+SecondaryEligibilityDecision
+      ├─ NEEDS_RESEARCH  → existing research/replan path
+      ├─ NEEDS_AUTHORITY → existing human-authority path
+      ├─ NEEDS_CONTEXT   → bounded context recovery
+      ├─ NOT_READY       → wait for dependencies; no builder call
+      ├─ STRONG_REQUIRED → Strong Builder
+      └─ ELIGIBLE
+             ↓ OFF / AUTO / PREFER + current availability/economics
+        Secondary or Strong
+             ↓
+        trusted verification
+             ├─ PASS → normal candidate lifecycle
+             └─ FAIL → one bounded Secondary repair by default
+                            ├─ PASS → normal candidate lifecycle
+                            └─ FAIL → Strong repair-oriented fallback
+```
+
+The route is additive to the existing scheduler. It does not rename or
+reinterpret `LOCAL`, `SUBSCRIPTION`, `API`, compute locality, or API Gap
+Bridge concepts, and it cannot authorize spend or authority that the existing
+hard policies forbid.
+
+## Configuration
+
+The compatibility default is `OFF`:
+
+```json
+{
+  "orchestration": {
+    "jobs": {
+      "objectives": {
+        "secondaryBuilder": {
+          "strategy": "OFF",
+          "maxRepairAttempts": 1
+        }
+      }
+    }
+  }
+}
+```
+
+`strategy` accepts:
+
+- `OFF`: the legacy Strong-only Objective path remains unchanged and does not
+  compile a routing-only packet or readiness record. An explicit qualification
+  selection may still exercise Secondary and its Phase 6 admission gate.
+- `PREFER`: eligible work uses Secondary when its provider is usable. If it
+  is absent, unhealthy, misconfigured, or times out during readiness probing,
+  Strong runs immediately; the job never waits solely for optional Secondary.
+- `AUTO`: eligible work uses the current deterministic subscription/economic
+  mode. `HARVEST` may select Strong to use expiring prepaid capacity;
+  `CONSERVE` and exhausted modes prefer Secondary; `NORMAL` currently selects
+  Secondary for eligible, available work. Prior failures for the same content
+  identity can make Strong sticky. There is no learned score or model router.
+
+`maxRepairAttempts` is an integer from 0 through 3. It counts implementation
+repairs after the initial Secondary attempt. The default chain is therefore:
+
+```text
+Secondary initial + 1 Secondary repair + 1 Strong fallback = at most 3
+builder attempts for this Phase 7 chain
+```
+
+Existing job worker-run, elapsed-time, cancellation, safety, authorization,
+and spend budgets remain hard ceilings. Phase 7 does not create additional
+budget when one of those ceilings is exhausted. Structured-output correction
+inside the existing Secondary executor remains separately and narrowly
+bounded; it is not multiplied into an unbounded code-repair loop.
+
+## Hard readiness routing
+
+When Phase 7 routing is entered (`AUTO`, `PREFER`, or an explicit Secondary
+qualification), Phase 6 hard gates run before strategy or availability. No
+strategy, including `PREFER`, may route a non-eligible unit to Secondary.
+Plain `OFF` with no explicit selection bypasses the new routing layer and
+preserves the existing Strong-only behavior:
+
+| Readiness | Route | Builder usage before recovery |
+| --- | --- | --- |
+| `ELIGIBLE` | apply OFF/AUTO/PREFER | Secondary or Strong |
+| `STRONG_REQUIRED` | Strong | Strong only |
+| `NEEDS_RESEARCH` | research/replan handoff | none |
+| `NEEDS_AUTHORITY` | human-authority handoff | none |
+| `NEEDS_CONTEXT` | bounded context recovery | none |
+| `NOT_READY` | dependency wait/recovery | none |
+
+Availability is observational routing input, not readiness. A local provider
+outage does not rewrite an `ELIGIBLE` assessment. The next route records the
+normalized status (`AVAILABLE`, `UNAVAILABLE`, `MISCONFIGURED`, `UNHEALTHY`,
+`START_FAILED`, or `TIMEOUT`) and selects Strong when permitted. The health
+check uses the existing managed local server startup/health boundary; it does
+not run a coding inference as a probe.
+
+## Repair and continuation
+
+Secondary execution reuses the Phase 4 and Phase 5 path exactly: a bounded
+Builder Packet enters the provider-neutral direct-model boundary, strict edits
+are validated and applied in the isolated Objective worktree, and trusted
+configured verification judges the result. A passing candidate proceeds
+through deterministic and any required semantic evaluation, aggregation, and
+single-writer integration. No Strong review is inserted merely because the
+candidate came from Secondary.
+
+For a repairable failure, the next fresh worktree deterministically replays
+the prior candidate patch before inference. The repair packet carries bounded
+delta evidence: the prior candidate summary, changed files, a patch excerpt,
+the failure summary, refreshed selected source, dependency evidence, and an
+instruction to repair the current implementation without redesigning
+unrelated code. Full job history and unbounded logs are not included.
+
+An explicit `NEEDS_MORE_CONTEXT` result may move Phase 5 once from
+`ADJACENT_DEPENDENCIES` to `MODULE_CONTEXT`, recompile the packet, and use the
+same repair budget. It cannot walk the entire expansion ladder.
+
+Problem fingerprints bind the failure kind, bounded verification summary,
+and candidate patch hash. Repeating the same fingerprint marks no progress
+and makes the Strong fallback sticky. Provider unavailability and cancellation
+do not consume the implementation-repair count. Cancellation never triggers a
+Strong fallback.
+
+After repair exhaustion, Strong receives the original approved WorkUnit
+context plus the prior Secondary patch, changed files, verification failures,
+and bounded attempt summaries. Its prompt explicitly continues the existing
+WorkUnit and permits it to repair, partially replace, or fully replace bad
+Secondary work. Strong gains reasoning capability, not product or contract
+authority.
+
+## Durability, resume, and inspection
+
+Routing state is written atomically below:
+
+```text
+.specbridge/jobs/<jobId>/objectives/<nodeId>/routing/
+  <workUnitId>-<workIdentity>.json
+  telemetry.json
+```
+
+Each content-identity record contains the decisions, typed reasons,
+availability/economic facts, attempt chain, consumed repair budget,
+no-progress marker, escalation state, and final backend. Candidate proposals,
+patches, changed files, verification evidence, and provider telemetry remain
+in the existing candidate and `secondary-attempts` artifacts.
+
+Ordinary resume reads this state. A chain that exhausted Secondary repair goes
+to Strong rather than retrying Secondary. The identity excludes timestamps,
+attempt numbers, prior-failure prose, and packet quality recalculated from the
+candidate's own replayed bytes. It remains bound to the semantic WorkUnit,
+approved contract snapshot, targets, verification policy, dependencies, and
+relevant research. A material replan or approved-truth/dependency/research
+change therefore starts a fresh chain without permanently blacklisting the
+WorkUnit ID.
+
+`renderBuilderRouting` exposes readiness, strategy, route, every attempt,
+repair-budget use, escalation, and final backend. Typed reason codes include
+policy, availability, subscription mode, verification/no-progress, repair
+exhaustion, and Strong fallback causes.
+
+Phase 8 keeps routing eligibility separate from temporary compute health. A
+Strong decision made while the subscription is cooling remains a Strong
+decision, but the WorkUnit is removed from the current runnable set without
+consuming its attempt. Independent Secondary candidates continue, and sticky
+`STRONG_FALLBACK_REQUIRED` state survives until Strong recovers. See
+[Subscription cooldown continuation](subscription-cooldown-continuation.md).
+
+## Telemetry
+
+Routing telemetry records:
+
+- `SecondaryEligible`, `SecondarySelected`, `SecondaryInitialPass`,
+  `SecondaryRepairPass`, `SecondaryToStrongFallback`,
+  `StrongRequiredDirect`, `SecondaryUnavailableFallback`, and
+  `NoModelNeeded` counts;
+- route counts, repair count, Strong fallback usage, observed Secondary input
+  and output tokens, and Secondary latency; missing provider usage remains
+  `null` rather than being invented;
+- `StrongBuilderAvoidanceRatio`, defined as:
+
+```text
+eligible implementation content identities completed without any Strong attempt
+───────────────────────────────────────────────────────────────────────────────
+eligible implementation content identities completed
+```
+
+`STRONG_REQUIRED`, research, authority, context, and dependency-wait routes
+are excluded from that denominator.
+
+## Phase 8 boundary
+
+Phase 7 supplies the bounded production routing and recovery mechanism. It
+does **not** certify multi-hour Claude subscription cooldown continuation,
+resume-after-reset behavior under a prolonged outage, or a long soak. That is
+the dedicated Phase 8 qualification. Phase 7 also does not add an LLM Gateway,
+remote or multiple Secondary targets, metered API fallback, learned routing,
+OpenMind, vector RAG, or remote agent worktrees.

docs/orchestration/configuration.md

@@ -78,6 +78,42 @@ Trusted verification commands still come only from `verification.commands`,
 as argv arrays — never from plan text, spec text, clarification text, or
 repository content.
 
+## Objective Secondary routing (vNext.10.2 Phase 7)
+
+Automatic direct-model implementation is opt-in and scoped to Objective
+WorkUnits that Phase 6 marks `ELIGIBLE`:
+
+```json
+{
+  "orchestration": {
+    "jobs": {
+      "objectives": {
+        "secondaryBuilder": {
+          "strategy": "OFF",
+          "maxRepairAttempts": 1
+        }
+      }
+    }
+  }
+}
+```
+
+`OFF` is the backward-compatible default. `PREFER` chooses an available
+Secondary first for eligible work; `AUTO` combines eligibility and health with
+the existing deterministic quota/economic mode. Neither mode can override a
+readiness blocker or authorize API spend. `maxRepairAttempts` accepts 0–3 and
+counts only code/context repair after a Secondary implementation actually ran.
+See [Adaptive Secondary routing](adaptive-secondary-routing.md) for the full
+attempt, fallback, resume, and telemetry semantics.
+
+During a Strong subscription cooldown, mission Objectives enter the Phase 8
+resource controller. READY WorkUnits that require Strong remain durably
+resource-waiting while independent permitted Secondary or research work
+continues. The Job uses `WAITING_RESOURCE` only after the runnable candidate
+set becomes empty. This does not add a configuration switch or change API
+spend authority. `PREFER`, `AUTO`, and `OFF` retain the meanings above. See
+[Subscription cooldown continuation](subscription-cooldown-continuation.md).
+
 ## Inspecting and validating
 
 ```bash