Add per-model scoped killswitch threshold

[iceteaSA]

What

Adds a third, model-scoped dimension to the per-account killswitch: a scoped threshold that hard-limits traffic to a weekly scoped quota carve-out (the weekly_scoped "Fable only" window) without killing the account for other models.

When the killswitch is enabled and a request's model matches a scoped window at/below the scoped threshold, the request reroutes to a scoped-eligible fallback and hard-blocks with a 429 if none qualify — while Sonnet/Opus traffic on the same account continues normally. Additive to the existing five_hour/seven_day checks; generic over any scoped window (not Fable-hardcoded).

Changes

• killswitchPassesPolicy(quota, storage, accountId?, modelId?) — new optional modelId. When present and a scoped window matches it, the window's remainingPercent is checked against the per-account scoped threshold. When absent, behavior is unchanged. The scoped check runs before the unknown-5h/7d fail-open return, so an exhausted scoped window blocks independently of missing 5h/7d windows.
• Comparison is <= (inclusive) for scoped — deliberately distinct from the strict < on 5h/7d — so the default threshold 0 fires at true exhaustion (matching quotaSnapshotModelScopeIsExhausted's <= 0).
• Config — KillswitchThresholds gains an optional scoped key (default 0); normalizeKillswitchThresholds resolves it with the same finite-guard/default pattern. Backward-compatible: existing two-value configs read scoped as the default.
• Command — /claude-killswitch set main:80,10,0 accepts an optional third number (fh, sd, scoped). Two-number form parses identically to before. Status table gains a Scoped column.
• Enforcement — modelId is threaded into the three routing-path call sites (main killswitch gate + both fallback filters), leaving the sidebar/status callers model-free so account-level killed state is unchanged.
• Block message — a scoped-driven terminal 429 names the model ("<Model> weekly limit reached, …") and killswitchRetryAfterSeconds honors the scoped window's weekly resetsAt. A 5h/7d-driven block keeps the account-level message (classified by the same <= scoped threshold check that drives the block, so message and reason never disagree).

Opencode-only, consistent with the existing killswitch (Pi has no killswitch enforcement).

Verification

• bun run typecheck — clean (all packages)
• bun run lint — clean
• bun test: core 34/0, opencode 770/0, pi 47/0
• New tests cover: model-scoped isolation (same quota, non-matching model → account stays live), the <= boundary at the 0 default and a raised threshold, modelId-absent regression lock, the unknown-window × fail-open × scoped-exhausted interaction, block-message attribution (5h/7d block with a healthy scoped window → generic message; exhausted scoped window → model-named), and config round-trip for the two- and three-value forms.

---

^{Need help on this PR? Tag /codesmith with what you need. Autofix is disabled.}

---

Summary by cubic

Adds a per-model scoped killswitch threshold to enforce weekly model carve-outs (e.g., Fable) without killing the account for other models. Routing, CLI, retry hints, and 429 messages are scope-aware with correct attribution and weekly reset timing; tests lock the priority rules.

• New Features

  • Add scoped threshold (default 0); inclusive <=; evaluated when a request includes modelId; additive to 5h/7d.
  • Thread modelId through the main gate and fallback filters; exhausted scoped windows reroute to scoped-eligible fallbacks or 429.
  • Update retry hints to accept a scopedModelId and use only the matched weekly reset; extend /claude-killswitch set to accept a third number (fh, sd, scoped); status table shows a Scoped column; thresholds normalized; block messages name the model for scoped-driven blocks.

• Bug Fixes

  • Run the scoped check before the unknown 5h/7d fail-open decision (MUST-1).
  • Correct 429 attribution: only label a block as model-scoped when the matched scoped window is at/below the scoped threshold and 5h/7d did not already kill the account (MUST-2, FINDING 2).
  • Fix retry-after for scoped blocks: when scopedModelId is provided, consider only the matched scoped window’s resetsAt so the hint reflects the weekly reset (FINDING 1).
  • Strengthen the MUST-2 test to actually trigger account-level blocks by setting 5h/7d remaining below the strict < thresholds (ensures the priority guard is exercised).

^{Written for commit 660e47d. Summary will update on new commits.}

Greptile Summary

This PR adds a scoped third dimension to the per-account killswitch, enabling model-specific weekly quota enforcement (e.g., Fable carve-outs) without blocking the account for other models. The change threads modelId through the main killswitch gate and both fallback filters, and introduces scope-aware block-message attribution and retry-after hints.

• killswitchPassesPolicy gains an optional modelId; when present and a scoped window matches at/below the scoped threshold, the request is blocked independently of 5h/7d — using <= (inclusive) so the default 0 fires at true exhaustion.
• resolveScopedDrivenBlock distinguishes a scoped-driven block from a 5h/7d-driven one by re-running policy without modelId; if 5h/7d already killed the account, the block is classified as account-level regardless of the scoped window's state (addressing the previous FINDING 2).
• killswitchRetryAfterSeconds now takes a scopedModelId and, when provided, collects only the matched scoped window's weekly resetsAt — ignoring the 5h reset that would otherwise produce a misleadingly short retry hint (addressing the previous FINDING 1).

Confidence Score: 5/5

Safe to merge — the two previously flagged issues (retry-after dominated by 5h/7d resets; misclassification when both 5h/7d and scoped are simultaneously exhausted) are both resolved in this revision, with regression-lock tests co-located alongside each fix.

The scoped check is correctly ordered before the unknown-window fail-open branch, the resolveScopedDrivenBlock priority logic (5h/7d wins over scoped when both are exhausted) matches the stated invariant and is directly verified, and the retry-after split (scoped-only vs 5h/7d) prevents the retry-storm scenario. The change is backward-compatible: existing two-value configs read scoped as 0 on normalization, and callers that omit modelId see identical behavior to before.

No files require special attention.

Important Files Changed

Filename	Overview
packages/core/src/accounts.ts	Adds scoped to KillswitchThresholds, DEFAULT_KILLSWITCH_THRESHOLDS, and normalizeKillswitchThresholds; threads optional modelId into killswitchPassesPolicy with correct ordering (before the unknown-window fail-open branch); splits killswitchRetryAfterSeconds into scoped-only vs 5h/7d paths — all sound.
packages/core/src/killswitch.ts	Extends the command parser regex to accept an optional third number, updates the set-entry type, and adds a Scoped column to the status table via normalizeKillswitchThresholds — backward-compatible and clean.
packages/opencode/src/index.ts	Introduces resolveScopedDrivenBlock and formatKillswitchBlockMessage; threads modelId into the main gate, getRoutableFallbackAccounts, and the second fallback filter; correctly conditions retry-after and block message on isScopedDriven — logic is consistent with the policy functions.
packages/core/src/tests/killswitch.test.ts	New test file with 34 cases covering defaults, normalization, per-model isolation, boundary conditions (<=), MUST-1 fail-open ordering, FINDING 1 retry-after branching, and config round-trips — comprehensive.
packages/opencode/src/tests/killswitch.test.ts	Adds formatKillswitchBlockMessage and resolveScopedDrivenBlock tests covering MUST-2 (5h/7d priority), FINDING 2 regression lock, and message attribution; thoroughly exercises the correct block-attribution logic.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Request with modelId] --> B{killswitch enabled?}
    B -- No --> Z[Pass through to main]
    B -- Yes --> C[killswitchPassesPolicy
mainQuota, storage, undefined, modelId]
    C --> D{5h/7d window
below threshold?}
    D -- Yes return false --> E[Account-level kill]
    D -- No check scoped --> F{modelId provided
and scoped window
matches model?}
    F -- No scoped window --> G{sawUnknownWindow?}
    F -- Window at/below
scoped threshold --> E
    F -- Window above
scoped threshold --> G
    G -- failClosed=true --> E
    G -- failClosed=false --> Z
    E --> H[getRoutableFallbackAccounts
filtered by modelId scoped check]
    H --> I{survivingFallbacks > 0?}
    I -- Yes --> J[Route to fallback]
    I -- No --> K[resolveScopedDrivenBlock
check 5h/7d WITHOUT modelId]
    K --> L{5h/7d passes
without modelId?}
    L -- No account-level --> M[Generic 429 message
retryAfter from 5h/7d resets]
    L -- Yes + scoped window
at/below threshold --> N[Scoped-driven 429
model-named message
retryAfter from weekly resetsAt]

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A[Request with modelId] --> B{killswitch enabled?}
    B -- No --> Z[Pass through to main]
    B -- Yes --> C[killswitchPassesPolicy
mainQuota, storage, undefined, modelId]
    C --> D{5h/7d window
below threshold?}
    D -- Yes return false --> E[Account-level kill]
    D -- No check scoped --> F{modelId provided
and scoped window
matches model?}
    F -- No scoped window --> G{sawUnknownWindow?}
    F -- Window at/below
scoped threshold --> E
    F -- Window above
scoped threshold --> G
    G -- failClosed=true --> E
    G -- failClosed=false --> Z
    E --> H[getRoutableFallbackAccounts
filtered by modelId scoped check]
    H --> I{survivingFallbacks > 0?}
    I -- Yes --> J[Route to fallback]
    I -- No --> K[resolveScopedDrivenBlock
check 5h/7d WITHOUT modelId]
    K --> L{5h/7d passes
without modelId?}
    L -- No account-level --> M[Generic 429 message
retryAfter from 5h/7d resets]
    L -- Yes + scoped window
at/below threshold --> N[Scoped-driven 429
model-named message
retryAfter from weekly resetsAt]

Loading

Comments Outside Diff (1)

1. packages/opencode/src/index.ts, line 886-911 (link)

   resolveScopedDrivenBlock misclassifies when 5h/7d and scoped are both exhausted

   resolveScopedDrivenBlock checks only whether the scoped window is at/below threshold — it does not verify that 5h/7d windows are themselves healthy. When 5h/7d exhaustion (e.g. remainingPercent: 4 vs a threshold of 5) caused killswitchPassesPolicy to return false, a simultaneously exhausted scoped window still produces { isScopedDriven: true }. The caller then emits "<Model> weekly limit reached, no routable accounts", misleading operators into thinking Sonnet requests on the same account would succeed — when in reality the account is blocked for all models due to the 5h/7d breach.

   The fix is to confirm that no 5h/7d window is independently below its threshold before declaring the block scoped-driven: if any finite 5h/7d window is < thresholds[key], return { isScopedDriven: false } immediately so the generic account-level message is used instead.

_{Reviews (3): Last reviewed commit: "test(killswitch): make MUST-2 5h/7d prem..." | Re-trigger Greptile}

[cubic-dev-ai]

2 issues found across 5 files

Confidence score: 3/5

• In packages/core/src/accounts.ts, scoped-driven killswitch blocks can return an overly aggressive Retry-After by taking the minimum across unrelated 5h/7d reset windows, which may throttle users longer than necessary and cause misleading backoff behavior — compute killswitchRetryAfterSeconds from the matching scoped reset window only before merging.
• In packages/opencode/src/index.ts, resolveScopedDrivenBlock re-implements scoped-threshold checks already handled by core killswitchPassesPolicy, which risks cross-package drift and inconsistent block decisions as logic evolves — de-duplicate by delegating to the core policy path (or add parity tests) before merging.

Architecture diagram

sequenceDiagram
    participant Client
    participant API as API Route (opencode)
    participant KSW as killswitchPassesPolicy
    participant ScopeHelper as getScopedQuotaWindowForModel
    participant Storage as AccountStorage (config)
    participant Fallback as Fallback Filter Loop
    participant Resolve as resolveScopedDrivenBlock
    participant Formatter as formatKillswitchBlockMessage
    participant CLI as /claude-killswitch set

    Note over Client,CLI: NEW: Per-model scoped killswitch threshold

    %% Happy path: request with modelId, window healthy
    Client->>API: POST /v1/messages (modelId: "claude-fable-5")
    API->>KSW: killswitchPassesPolicy(quota, storage, accountId?, modelId)
    KSW->>KSW: Check killswitch enabled, normalize thresholds<br/>including scoped (default 0)
    KSW->>KSW: Evaluate five_hour (strict <) and seven_day (strict <)
    alt ModelId provided
        KSW->>ScopeHelper: getScopedQuotaWindowForModel(quota, modelId)
        ScopeHelper-->>KSW: scopedWindow or null
        alt scopedWindow exists AND remainingPercent finite AND remainingPercent <= thresholds.scoped
            KSW-->>API: false (block)
        else scopedWindow missing or above threshold
            KSW-->>API: true (pass)
        end
    else No modelId
        KSW-->>API: true (pass, no scoped check)
    end

    %% Main killed, routing to fallbacks
    API->>API: Eager killswitch refresh (QuotaManager)
    alt Main quota fails (killswitchPassesPolicy returned false)
        API->>Fallback: Loop over fallback accounts
        loop each fallback account
            Fallback->>KSW: killswitchPassesPolicy(fallbackQuota, storage, account.id, modelId)
            KSW-->>Fallback: true/false (scoped check included)
        end
        alt No fallbacks qualify
            API->>Resolve: resolveScopedDrivenBlock(mainQuota, requestModelId, storage)
            Resolve->>ScopeHelper: getScopedQuotaWindowForModel (same as above)
            ScopeHelper-->>Resolve: matchedWindow
            alt matchedWindow.remainingPercent <= thresholds.scoped
                Resolve-->>API: { isScopedDriven: true, modelName, modelId }
            else
                Resolve-->>API: { isScopedDriven: false }
            end
            API->>Formatter: formatKillswitchBlockMessage(retryAfterSeconds, modelName?)
            Formatter-->>API: "<Model> weekly limit reached" or "Killswitch: no routable accounts"
            API->>Client: 429 { type: "rate_limit_error", message }
        else Fallback account qualifies
            API->>Client: Route to fallback (normal flow)
        end
    else Main ok
        API->>Client: Normal response
    end

    %% CLI configuration flow
    rect rgb(240, 240, 240)
        Note over CLI,Storage: CLI configuration (/threshold)
        Client->>CLI: /claude-killswitch set main:5,10,0
        CLI->>CLI: parseKillswitchCommandAction()<br/>NEW: optional third number (scoped)
        CLI->>Storage: Save killswitch config with scoped field
        Storage-->>CLI: Confirmed
        CLI->>Client: Status table with Scoped column
    end

    Note over KSW: NEW: Scoped check runs BEFORE unknown-window fail-closed return<br/>so exhausted scoped window blocks even if 5h/7d windows are missing.
    Note over API: killswitchRetryAfterSeconds also includes scoped window's resetsAt<br/>when scopedModelId is provided.

Loading

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

1 issue found across 5 files

Confidence score: 3/5

• In packages/opencode/src/tests/killswitch.test.ts, the MUST-2 boundary case uses remainingPercent values equal to the 5h/7d thresholds even though the logic is described as strict <, so the test may assert behavior that doesn’t match production edge conditions and could hide a real killswitch regression at exactly-threshold values—update the fixture/expectation (or explicitly change the operator semantics) before merging.

Architecture diagram

sequenceDiagram
    participant Client as API Client
    participant Router as Routing Engine
    participant KS as Killswitch Gate
    participant Quota as Quota Manager
    participant CLI as Killswitch CLI
    participant Storage as Account Storage

    Note over Client,Storage: NEW: Per-Model Scoped Killswitch Flow

    CLI->>Storage: set main:5,10,3 (fh, sd, scoped)
    Storage-->>CLI: Config updated
    CLI->>CLI: normalizeKillswitchThresholds(s)
    Note over CLI: Parsed thresholds: {five_hour: 5, seven_day: 10, scoped: 3}

    Client->>Router: Request with modelId (e.g. claude-fable-5)
    Router->>KS: killswitchPassesPolicy(quota, storage, accountId?, modelId?)
    
    alt Killswitch disabled
        KS-->>Router: true → pass through
    else Killswitch enabled
        KS->>KS: Check 5h window vs threshold (strict <)
        alt 5h remaining < threshold
            KS-->>Router: false → block (account-level)
        else 5h passes
            KS->>KS: Check 7d window vs threshold (strict <)
            alt 7d remaining < threshold
                KS-->>Router: false → block (account-level)
            else 7d passes
                Note over KS: NEW: Scoped check (runs BEFORE unknown-window fail-open)
                alt modelId provided
                    KS->>Quota: getScopedQuotaWindowForModel(quota, modelId)
                    Quota-->>KS: matching window or null
                    alt window found AND remainingPercent <= scoped threshold (inclusive)
                        KS-->>Router: false → block (model-scoped)
                    else window not found or above threshold
                        KS->>KS: Check sawUnknownWindow
                        alt failClosedOnUnknown
                            KS-->>Router: false
                        else failOpen
                            KS-->>Router: true
                        end
                    end
                else no modelId
                    KS->>KS: Check sawUnknownWindow (unchanged)
                end
            end
        end
    end

    Note over Router: NEW: Model-scoped 429 Response

    alt Block triggered
        Router->>Router: resolveScopedDrivenBlock()
        Note over Router: First: killswitchPassesPolicy WITHOUT modelId (5h/7d only)
        alt 5h/7d alone blocks
            Router->>Router: isScopedDriven = false (account-level)
        else 5h/7d passes (block is scoped-only)
            Router->>Router: check matched scoped window <= threshold
            Router->>Router: isScopedDriven = true
        end
        
        Router->>Router: killswitchRetryAfterSeconds(quota, fallbacks, now, scopedModelId?)
        alt scopedModelId present
            Router->>Router: Only consider scoped window's resetsAt
            Note over Router: Ignore 5h/7d resets (weekly window)
        else no scopedModelId
            Router->>Router: Check 5h + 7d resets (unchanged)
        end
        
        Router->>Router: formatKillswitchBlockMessage()
        alt scoped-driven
            Router->>Router: "Claude Fable 5 weekly limit reached..."
        else account-level
            Router->>Router: "Killswitch: no routable accounts..."
        end
        Router-->>Client: 429 + Retry-After header
    end

    Note over Router: NEW: Fallback Filter with modelId
    
    alt Main killed, checking fallbacks
        Router->>Router: Filter fallbacks with killswitchPassesPolicy(quota, storage, id, modelId)
        Note over Router: Accounts with exhausted Fable scoped are excluded from Fable routing
        alt Qualified fallbacks found
            Router->>Client: Route to fallback
        else No qualified fallbacks
            Router->>Client: 429 (same message as above)
        end
    end

Loading

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>