scoutline 0.10.2 → 0.12.0

package/dist/lib/trigger-detection.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Trigger detection (T3b — Plan A, Option B).
+ *
+ * When the user runs a credentialed command without ever having gone
+ * through `scoutline init`, we want one of three classified outcomes
+ * rather than a confusing per-handler stack trace:
+ *
+ *   - **env-only setup**: a key for the effective Provider is present
+ *     in the injected env, but no Provider key is stored in
+ *     `config.json`. We emit a ONE-TIME stderr hint pointing at
+ *     `scoutline init` (so the user learns the wizard exists), persist
+ *     `config.json.hintShown`, and then run the command normally. The
+ *     command's natural output and exit code are preserved.
+ *   - **missing credential everywhere**: the effective Provider has no
+ *     key in env OR in `config.json`. We emit remediation and surface
+ *     the existing `CONFIGURATION_ERROR` exit 3. A refused operation
+ *     is NEVER exit 0 — scripting users must not treat refusal as
+ *     success.
+ *   - **credential-free commands** (`--help`, `--version`, `cache`,
+ *     `init`, `<command> --help`): no config read at all. The T2a
+ *     short-circuit already covers help/version/cache/init; this
+ *     module exposes a helper to recognise per-command help so the
+ *     trigger layer can route around it too (command help must remain
+ *     usable under a corrupt config — see review item 9).
+ *
+ * Doctor and quota are observational: they report per-Provider state
+ * rather than depending on a single effective credential, so trigger
+ * detection does NOT classify them. They keep their existing per-handler
+ * configuration-error behavior (Doctor reports skipped/error states;
+ * quota surfaces its existing CONFIGURATION_ERROR when nothing is
+ * configured).
+ *
+ * Raw Z.AI commands (`tools`, `tool`, `call`, `code`) ARE credentialed
+ * and Z.AI-only, so missing-key remediation applies to them. They do
+ * NOT gain Provider selection or fallback (still Z.AI-only).
+ *
+ * All functions here are pure (they take their inputs as arguments and
+ * touch no module-level state). The dispatcher in `src/index.ts` wires
+ * the real `HintShownStore`, the injected env, the descriptors, and the
+ * stderr sink.
+ */
+import type { ProviderDescriptor } from "../providers/types.js";
+import type { ScoutlineConfig } from "./config-store.js";
+import { ConfigurationError } from "./errors.js";
+/**
+ * Commands that are observational rather than credentialed. They are
+ * exempt from trigger detection because they already report per-Provider
+ * state instead of depending on a single effective credential.
+ */
+export declare const OBSERVATIONAL_COMMANDS: ReadonlySet<string>;
+/**
+ * Commands that are credential-free at the dispatcher level (handled
+ * before the credentialed config read). Listed here for documentation
+ * completeness; the dispatcher short-circuits them before reaching the
+ * trigger layer.
+ */
+export declare const DISPATCHER_CREDENTIAL_FREE: ReadonlySet<string>;
+/**
+ * Commands that are always Z.AI-only (raw Z.AI tools + Code Mode).
+ * Trigger detection treats them as credentialed; their effective
+ * Provider is always `zai` regardless of `--provider`.
+ */
+export declare const ZAI_ONLY_COMMANDS: ReadonlySet<string>;
+/**
+ * The classified credential state for the command being dispatched.
+ * The dispatcher consumes this to decide whether to emit the hint,
+ * refuse, or proceed normally. The classification is computed across
+ * ALL descriptors (not just the effective Provider) so that Provider
+ * fallback can route to a configured candidate even when the effective
+ * is unconfigured — "missing" only fires when NO provider can serve
+ * the request.
+ */
+export type CredentialState = {
+    readonly kind: "env-only";
+} | {
+    readonly kind: "file-configured";
+} | {
+    readonly kind: "env-and-file";
+} | {
+    readonly kind: "missing";
+};
+/**
+ * Inputs to {@link classifyCredentialState}. Kept explicit so the
+ * classifier stays a pure function — no module-level reads, no
+ * descriptor lookup beyond what the caller passes in.
+ */
+export interface CredentialClassificationInput {
+    /** The full provider registry (so fallback candidates are considered). */
+    readonly descriptors: readonly ProviderDescriptor[];
+    /** The injected environment view (env vars only, no file keys). */
+    readonly env: NodeJS.ProcessEnv;
+    /**
+     * The resolved environment view (env + file keys layered in by
+     * `resolveEnvFromConfig`). When this differs from `env`, a file
+     * key is present.
+     */
+    readonly resolvedEnv: NodeJS.ProcessEnv;
+    /** The loaded config (used to detect a file key directly). */
+    readonly config: ScoutlineConfig;
+}
+/**
+ * Classify the credential state across the whole registry.
+ *
+ *   - **missing**: NO descriptor is configured through env OR file.
+ *     The command cannot succeed (no fallback candidate exists), so
+ *     the dispatcher refuses with `CONFIGURATION_ERROR` exit 3.
+ *   - **env-only**: at least one descriptor is configured through env,
+ *     and NO descriptor has a file key. The user is running purely on
+ *     environment variables; the one-time hint points them at `init`.
+ *   - **env-and-file**: env keys and file keys both exist. Env
+ *     precedence means the env value wins at runtime for the providers
+ *     that have both; the file keys cover the rest. No hint needed
+ *     (the user has been through onboarding).
+ *   - **file-configured**: keys exist ONLY in the file (the normal
+ *     post-onboarding steady state). No hint needed.
+ *
+ * The "env-only" classification is the trigger for the one-time hint;
+ * "missing" is the trigger for remediation + exit 3. The other two
+ * states proceed normally.
+ */
+export declare function classifyCredentialState(input: CredentialClassificationInput): CredentialState;
+/**
+ * Format the one-time env-only hint. Sent to stderr so stdout stays
+ * data-only. The hint names the wizard and points at it; it does NOT
+ * repeat on subsequent runs because the dispatcher persists
+ * `config.json.hintShown` after emitting it.
+ */
+export declare function formatEnvOnlyHint(): string;
+/**
+ * Build the missing-credential error. Reuses the existing
+ * `CONFIGURATION_ERROR` / exit-3 contract so a refused operation is
+ * NEVER confused with success. The help text lists the canonical env
+ * vars across all providers so the user can pick one to set, and
+ * points at `init` as the interactive alternative.
+ */
+export declare function missingCredentialError(descriptors: readonly ProviderDescriptor[]): ConfigurationError;
+/**
+ * Detect whether the command being dispatched should bypass trigger
+ * detection because it is rendering command-local help. Command help
+ * (`<command> --help` / `-h`) must remain usable even when config.json
+ * is corrupt or absent — rendering help never needs a credential.
+ *
+ * This is a shallow peek at the arg list: it only looks for the help
+ * flag, mirroring the per-handler short-circuit (`flags.help ||
+ * flags.h`). It does NOT consume the args; the handler still parses
+ * them itself.
+ */
+export declare function isCommandHelpInvocation(commandArgs: readonly string[]): boolean;
+//# sourceMappingURL=trigger-detection.d.ts.map

package/dist/lib/trigger-detection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trigger-detection.d.ts","sourceRoot":"","sources":["../../src/lib/trigger-detection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAc,MAAM,uBAAuB,CAAC;AAC5E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEjD;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,EAAE,WAAW,CAAC,MAAM,CAAgC,CAAC;AAExF;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,EAAE,WAAW,CAAC,MAAM,CAA8B,CAAC;AAE1F;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAA8C,CAAC;AAEjG;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GAC7B;IAAE,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAA;CAAE,GACpC;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;CAAE,GACjC;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC;AAEjC;;;;GAIG;AACH,MAAM,WAAW,6BAA6B;IAC5C,0EAA0E;IAC1E,QAAQ,CAAC,WAAW,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACpD,mEAAmE;IACnE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC,UAAU,CAAC;IACxC,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,6BAA6B,GAAG,eAAe,CAqB7F;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAO1C;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,SAAS,kBAAkB,EAAE,GACzC,kBAAkB,CAapB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAE/E"}

package/dist/lib/trigger-detection.js

@@ -0,0 +1,149 @@
+/**
+ * Trigger detection (T3b — Plan A, Option B).
+ *
+ * When the user runs a credentialed command without ever having gone
+ * through `scoutline init`, we want one of three classified outcomes
+ * rather than a confusing per-handler stack trace:
+ *
+ *   - **env-only setup**: a key for the effective Provider is present
+ *     in the injected env, but no Provider key is stored in
+ *     `config.json`. We emit a ONE-TIME stderr hint pointing at
+ *     `scoutline init` (so the user learns the wizard exists), persist
+ *     `config.json.hintShown`, and then run the command normally. The
+ *     command's natural output and exit code are preserved.
+ *   - **missing credential everywhere**: the effective Provider has no
+ *     key in env OR in `config.json`. We emit remediation and surface
+ *     the existing `CONFIGURATION_ERROR` exit 3. A refused operation
+ *     is NEVER exit 0 — scripting users must not treat refusal as
+ *     success.
+ *   - **credential-free commands** (`--help`, `--version`, `cache`,
+ *     `init`, `<command> --help`): no config read at all. The T2a
+ *     short-circuit already covers help/version/cache/init; this
+ *     module exposes a helper to recognise per-command help so the
+ *     trigger layer can route around it too (command help must remain
+ *     usable under a corrupt config — see review item 9).
+ *
+ * Doctor and quota are observational: they report per-Provider state
+ * rather than depending on a single effective credential, so trigger
+ * detection does NOT classify them. They keep their existing per-handler
+ * configuration-error behavior (Doctor reports skipped/error states;
+ * quota surfaces its existing CONFIGURATION_ERROR when nothing is
+ * configured).
+ *
+ * Raw Z.AI commands (`tools`, `tool`, `call`, `code`) ARE credentialed
+ * and Z.AI-only, so missing-key remediation applies to them. They do
+ * NOT gain Provider selection or fallback (still Z.AI-only).
+ *
+ * All functions here are pure (they take their inputs as arguments and
+ * touch no module-level state). The dispatcher in `src/index.ts` wires
+ * the real `HintShownStore`, the injected env, the descriptors, and the
+ * stderr sink.
+ */
+import { ConfigurationError } from "./errors.js";
+/**
+ * Commands that are observational rather than credentialed. They are
+ * exempt from trigger detection because they already report per-Provider
+ * state instead of depending on a single effective credential.
+ */
+export const OBSERVATIONAL_COMMANDS = new Set(["doctor", "quota"]);
+/**
+ * Commands that are credential-free at the dispatcher level (handled
+ * before the credentialed config read). Listed here for documentation
+ * completeness; the dispatcher short-circuits them before reaching the
+ * trigger layer.
+ */
+export const DISPATCHER_CREDENTIAL_FREE = new Set(["cache", "init"]);
+/**
+ * Commands that are always Z.AI-only (raw Z.AI tools + Code Mode).
+ * Trigger detection treats them as credentialed; their effective
+ * Provider is always `zai` regardless of `--provider`.
+ */
+export const ZAI_ONLY_COMMANDS = new Set(["tools", "tool", "call", "code"]);
+/**
+ * Classify the credential state across the whole registry.
+ *
+ *   - **missing**: NO descriptor is configured through env OR file.
+ *     The command cannot succeed (no fallback candidate exists), so
+ *     the dispatcher refuses with `CONFIGURATION_ERROR` exit 3.
+ *   - **env-only**: at least one descriptor is configured through env,
+ *     and NO descriptor has a file key. The user is running purely on
+ *     environment variables; the one-time hint points them at `init`.
+ *   - **env-and-file**: env keys and file keys both exist. Env
+ *     precedence means the env value wins at runtime for the providers
+ *     that have both; the file keys cover the rest. No hint needed
+ *     (the user has been through onboarding).
+ *   - **file-configured**: keys exist ONLY in the file (the normal
+ *     post-onboarding steady state). No hint needed.
+ *
+ * The "env-only" classification is the trigger for the one-time hint;
+ * "missing" is the trigger for remediation + exit 3. The other two
+ * states proceed normally.
+ */
+export function classifyCredentialState(input) {
+    const { descriptors, env, resolvedEnv, config } = input;
+    const anyEnvConfigured = descriptors.some((d) => d.isConfigured(env));
+    const anyResolvedConfigured = descriptors.some((d) => d.isConfigured(resolvedEnv));
+    const anyFileConfigured = Object.values(config.providers).some((provider) => {
+        const key = provider?.apiKey;
+        return typeof key === "string" && key.trim().length > 0;
+    });
+    if (!anyResolvedConfigured) {
+        return { kind: "missing" };
+    }
+    if (anyEnvConfigured && !anyFileConfigured) {
+        return { kind: "env-only" };
+    }
+    if (anyEnvConfigured && anyFileConfigured) {
+        return { kind: "env-and-file" };
+    }
+    // !anyEnvConfigured && anyFileConfigured — the resolved env picked up
+    // the file key; this is the normal post-onboarding steady state.
+    return { kind: "file-configured" };
+}
+/**
+ * Format the one-time env-only hint. Sent to stderr so stdout stays
+ * data-only. The hint names the wizard and points at it; it does NOT
+ * repeat on subsequent runs because the dispatcher persists
+ * `config.json.hintShown` after emitting it.
+ */
+export function formatEnvOnlyHint() {
+    return ("scoutline: using credentials from the environment. " +
+        "Run `scoutline init` to record them in ~/.scoutline/config.json " +
+        "(enables fallback preferences, verification tracking, and re-config). " +
+        "This is a one-time hint; it will not repeat.\n");
+}
+/**
+ * Build the missing-credential error. Reuses the existing
+ * `CONFIGURATION_ERROR` / exit-3 contract so a refused operation is
+ * NEVER confused with success. The help text lists the canonical env
+ * vars across all providers so the user can pick one to set, and
+ * points at `init` as the interactive alternative.
+ */
+export function missingCredentialError(descriptors) {
+    const vars = [];
+    for (const descriptor of descriptors) {
+        if (descriptor.credentialEnvVars && descriptor.credentialEnvVars.length > 0) {
+            vars.push(descriptor.credentialEnvVars[0]);
+        }
+    }
+    const help = vars.length > 0
+        ? `Set one of ${vars.join(", ")} (or run \`scoutline init\` to configure interactively).`
+        : "Run `scoutline init` to configure a Provider, or set the required API key in the environment.";
+    const message = "No Provider credential is configured (neither env nor ~/.scoutline/config.json)";
+    return new ConfigurationError(message, help);
+}
+/**
+ * Detect whether the command being dispatched should bypass trigger
+ * detection because it is rendering command-local help. Command help
+ * (`<command> --help` / `-h`) must remain usable even when config.json
+ * is corrupt or absent — rendering help never needs a credential.
+ *
+ * This is a shallow peek at the arg list: it only looks for the help
+ * flag, mirroring the per-handler short-circuit (`flags.help ||
+ * flags.h`). It does NOT consume the args; the handler still parses
+ * them itself.
+ */
+export function isCommandHelpInvocation(commandArgs) {
+    return commandArgs.includes("--help") || commandArgs.includes("-h");
+}
+//# sourceMappingURL=trigger-detection.js.map

package/dist/lib/trigger-detection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trigger-detection.js","sourceRoot":"","sources":["../../src/lib/trigger-detection.ts"],"names":[],"mappings":"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"}

package/dist/lib/tty.d.ts

@@ -41,7 +41,14 @@ import type { QuotaDashboard } from "../capabilities/quota.js";
  * Provider-neutral TTY rendering of a {@link QuotaDashboard}. Each
  * Provider entry is labelled with its Provider id and each category by
  * its normalized name; progress bars represent the REMAINING percentage.
+ *
+ * PB-T5: a successful row carries a `quotaSource` label rendered as a
+ * separate `source` line beneath the categories (snapshot/live, fresh/
+ * stale). The new `"none"` status (no quota Capability — Exa) renders
+ * a single dim line; it never appears as a failure. The `now` argument
+ * defaults to `Date.now()` so existing callers keep working; tests
+ * inject a fixed clock for deterministic age labels.
  */
-export declare function formatQuotaDashboard(dashboard: QuotaDashboard): string;
+export declare function formatQuotaDashboard(dashboard: QuotaDashboard, now?: number): string;
 export {};
 //# sourceMappingURL=tty.d.ts.map

package/dist/lib/tty.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tty.d.ts","sourceRoot":"","sources":["../../src/lib/tty.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,KAAK,OAAO,GAAG,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;AAUrC,eAAO,MAAM,KAAK;IAChB,IAAI;IACJ,GAAG;IACH,IAAI;IACJ,KAAK;IACL,MAAM;IACN,GAAG;IACH,OAAO;IACP,IAAI;CACL,CAAC;AAEF,wBAAgB,KAAK,IAAI,OAAO,CAE/B;AAED,uFAAuF;AACvF,wBAAgB,cAAc,CAC5B,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,IAAI,EAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,GAClD,KAAK,GAAG,SAAS,CAKnB;AAED,UAAU,gBAAgB;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,gBAAgB,EAAE,GAAG,MAAM,CAe7E;AAED,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAsE/D;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,cAAc,GAAG,MAAM,CAkBtE"}
+{"version":3,"file":"tty.d.ts","sourceRoot":"","sources":["../../src/lib/tty.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,KAAK,OAAO,GAAG,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;AAUrC,eAAO,MAAM,KAAK;IAChB,IAAI;IACJ,GAAG;IACH,IAAI;IACJ,KAAK;IACL,MAAM;IACN,GAAG;IACH,OAAO;IACP,IAAI;CACL,CAAC;AAEF,wBAAgB,KAAK,IAAI,OAAO,CAE/B;AAED,uFAAuF;AACvF,wBAAgB,cAAc,CAC5B,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,IAAI,EAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,GAClD,KAAK,GAAG,SAAS,CAKnB;AAED,UAAU,gBAAgB;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,gBAAgB,EAAE,GAAG,MAAM,CAe7E;AAED,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAyH/D;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,cAAc,EAAE,GAAG,GAAE,MAAmB,GAAG,MAAM,CAyBhG"}

package/dist/lib/tty.js

@@ -96,12 +96,56 @@ function renderCategory(category, lines) {
         lines.push(`      ${color.gray("weekly")} ${remainingBar(w.remainingPercent)} ${w.remainingPercent}%`);
     }
 }
+/**
+ * Format a relative-age label for an epoch-ms timestamp (PB-T5).
+ * Returns a short "Xm"/"Xh"/"Xd" string suitable for a TTY row. Used
+ * to surface `observedAt` age so a user can judge whether a selection
+ * pick was made against stale or fresh data. The `now` parameter is
+ * injected by the caller so a deterministic test clock produces a
+ * deterministic label.
+ */
+function formatObservedAge(observedAt, now) {
+    const diff = Math.max(0, now - observedAt);
+    const sec = Math.floor(diff / 1000);
+    if (sec < 60)
+        return `${sec}s`;
+    const min = Math.floor(sec / 60);
+    if (min < 60)
+        return `${min}m`;
+    const hr = Math.floor(min / 60);
+    if (hr < 24)
+        return `${hr}h`;
+    const day = Math.floor(hr / 24);
+    return `${day}d`;
+}
+/**
+ * Render the quotaSource label for a successful row (PB-T5). Mirrors
+ * the public {@link QuotaSourceLabel} shape: source/observedAt/
+ * authoritative. A non-authoritative row is dimmed so a user can see
+ * at a glance that the displayed numbers may be stale. The age label
+ * is computed against the injected clock so tests stay deterministic.
+ */
+function renderSourceLabel(source, lines, now) {
+    const age = formatObservedAge(source.observedAt, now);
+    const authority = source.authoritative
+        ? color.green("fresh")
+        : color.yellow("stale · non-authoritative");
+    const sourceTxt = source.source === "snapshot" ? color.gray("snapshot") : color.cyan("live");
+    lines.push(`      ${color.gray("source")} ${sourceTxt} · ${authority} ${color.gray(`(${age} ago`)}`);
+}
 /**
  * Provider-neutral TTY rendering of a {@link QuotaDashboard}. Each
  * Provider entry is labelled with its Provider id and each category by
  * its normalized name; progress bars represent the REMAINING percentage.
+ *
+ * PB-T5: a successful row carries a `quotaSource` label rendered as a
+ * separate `source` line beneath the categories (snapshot/live, fresh/
+ * stale). The new `"none"` status (no quota Capability — Exa) renders
+ * a single dim line; it never appears as a failure. The `now` argument
+ * defaults to `Date.now()` so existing callers keep working; tests
+ * inject a fixed clock for deterministic age labels.
  */
-export function formatQuotaDashboard(dashboard) {
+export function formatQuotaDashboard(dashboard, now = Date.now()) {
     const lines = [""];
     for (const entry of dashboard.providers) {
         if (entry.status === "ok") {
@@ -111,6 +155,14 @@ export function formatQuotaDashboard(dashboard) {
             for (const category of success.categories) {
                 renderCategory(category, lines);
             }
+            if (success.quotaSource) {
+                renderSourceLabel(success.quotaSource, lines, now);
+            }
+        }
+        else if (entry.status === "none") {
+            const none = entry;
+            lines.push(`  ${color.bold(none.provider)} ${color.dim("(no quota)")}`);
+            lines.push(`    ${color.gray("no quota capability — skipping probe")}`);
         }
         else {
             const failure = entry;

package/dist/lib/tty.js.map

@@ -1 +1 @@
-{"version":3,"file":"tty.js","sourceRoot":"","sources":["../../src/lib/tty.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tty.js","sourceRoot":"","sources":["../../src/lib/tty.ts"],"names":[],"mappings":"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"}

package/dist/providers/brave/adapter.d.ts

@@ -18,14 +18,34 @@
  */
 import type { ProviderDescriptor } from "../types.js";
 import { type BraveTransportDeps } from "./client.js";
+import type { BraveRateLimitHeaders } from "./client.js";
 /**
  * Dependencies the Brave Adapter accepts. The unified `transport`
  * seam carries `fetch` and timer injection; the Search Capability
  * threads it through to the direct-HTTP transport.
+ *
+ * `onRateLimitHarvest` (PB-T1) is the passive-harvest callback invoked
+ * with Brave's `X-RateLimit-*` headers after every successful web
+ * search. Production wires a default that normalizes the headers via
+ * `normalizeBraveQuota` and writes a raw-category snapshot to
+ * `~/.scoutline/state.json` through `writeQuotaSnapshot`; the write is
+ * awaited (so it survives the bin's immediate `process.exit`) and
+ * fail-open (a write error is isolated to a stderr warning and never
+ * converts the search success into a fallback). Tests inject a double
+ * to keep harvest assertions hermetic. `undefined` disables the
+ * harvest (used by tests that only exercise search-result
+ * normalization).
  */
 export interface BraveAdapterDependencies {
     /** Optional transport injection (fetch, timers, env). */
     readonly transport?: BraveTransportDeps;
+    /**
+     * Optional passive-harvest callback fired with Brave's
+     * `X-RateLimit-*` headers after a successful web search. Production
+     * wires a default (see {@link createDefaultBraveHarvest}); tests
+     * inject a recorder or `undefined` to disable.
+     */
+    readonly onRateLimitHarvest?: (headers: BraveRateLimitHeaders) => Promise<void> | void;
 }
 /**
  * Build the Brave Provider Descriptor. The descriptor advertises the
@@ -37,6 +57,12 @@ export interface BraveAdapterDependencies {
  * (typically a fake-fetch wrapper); production uses the no-argument
  * factory which resolves to the global `fetch` and timers inside the
  * transport Module.
+ *
+ * PB-T1: the no-argument factory wires the production passive-harvest
+ * callback ({@link createDefaultBraveHarvest}) so every successful web
+ * search writes a rate-limit snapshot to `state.json`. Tests inject
+ * `onRateLimitHarvest` (or `undefined` to disable) through
+ * `BraveAdapterDependencies`.
  */
 export declare function createBraveDescriptor(dependencies?: BraveAdapterDependencies): ProviderDescriptor;
 //# sourceMappingURL=adapter.d.ts.map

package/dist/providers/brave/adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../src/providers/brave/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,OAAO,KAAK,EAIV,kBAAkB,EACnB,MAAM,aAAa,CAAC;AAqBrB,OAAO,EAML,KAAK,kBAAkB,EACxB,MAAM,aAAa,CAAC;AAIrB;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,yDAAyD;IACzD,QAAQ,CAAC,SAAS,CAAC,EAAE,kBAAkB,CAAC;CACzC;AAweD;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,YAAY,CAAC,EAAE,wBAAwB,GAAG,kBAAkB,CAqBjG"}
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../src/providers/brave/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,OAAO,KAAK,EAIV,kBAAkB,EACnB,MAAM,aAAa,CAAC;AAqBrB,OAAO,EAML,KAAK,kBAAkB,EACxB,MAAM,aAAa,CAAC;AAGrB,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAGzD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,wBAAwB;IACvC,yDAAyD;IACzD,QAAQ,CAAC,SAAS,CAAC,EAAE,kBAAkB,CAAC;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC,OAAO,EAAE,qBAAqB,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACxF;AA6iBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CAAC,YAAY,CAAC,EAAE,wBAAwB,GAAG,kBAAkB,CA4BjG"}

package/dist/providers/brave/adapter.js

@@ -22,7 +22,8 @@ import { applySearchTopic } from "../../lib/search-topic.js";
 import { requireBraveApiKey, isBraveConfigured } from "./credentials.js";
 import { fetchBraveSearch, fetchBraveNewsSearch, fetchBraveVideoSearch, fetchBraveLlmContext, } from "./client.js";
 import { createBraveDiagnosticsCapability } from "./diagnostics.js";
-import { createBraveQuotaCapability } from "./quota.js";
+import { createBraveQuotaCapability, normalizeBraveQuota } from "./quota.js";
+import { writeQuotaSnapshot } from "../../lib/quota-store.js";
 // ---------------------------------------------------------------------------
 // Provider-owned credential fingerprint
 // ---------------------------------------------------------------------------
@@ -382,7 +383,7 @@ function normalizeBraveError(error) {
     return new ApiError("Brave request failed", inferStatusCode(lower));
 }
 function createBraveSearchCapability(options) {
-    const { env, transport } = options;
+    const { env, transport, onRateLimitHarvest } = options;
     const capability = {
         validate(request) {
             if (!request || typeof request.query !== "string" || request.query.trim() === "") {
@@ -450,7 +451,7 @@ function createBraveSearchCapability(options) {
                         ? await fetchBraveLlmContext(apiKey, effectiveQuery, params, transport)
                         : isNews
                             ? await fetchBraveNewsSearch(apiKey, effectiveQuery, params, transport)
-                            : await fetchBraveSearch(apiKey, effectiveQuery, params, transport);
+                            : await fetchBraveSearch(apiKey, effectiveQuery, params, transport, onRateLimitHarvest);
                 return isVideo
                     ? normalizeBraveTopLevelResults(raw)
                     : isHigh
@@ -467,6 +468,54 @@ function createBraveSearchCapability(options) {
     return capability;
 }
 // ---------------------------------------------------------------------------
+// Passive harvest default (PB-T1)
+// ---------------------------------------------------------------------------
+/**
+ * Build the production passive-harvest callback for Brave rate-limit
+ * headers. Normalizes the four `X-RateLimit-*` headers via the SAME
+ * `normalizeBraveQuota` the explicit quota probe uses (so the
+ * harvested snapshot matches the probed snapshot's category shape
+ * exactly), then writes a raw-category snapshot to the quota store
+ * through {@link writeQuotaSnapshot}. The write advances `observedAt`
+ * only; `locallyUpdatedAt` is preserved by the store (PB-T2 advances
+ * it).
+ *
+ * Fail-open: any error (header parse failure, store write failure) is
+ * caught and routed to a stderr notice. The returned callback never
+ * rejects, so the transport's `try/catch` around the callback is
+ * belt-and-suspenders — a harvest failure cannot convert a search
+ * success into a fallback.
+ *
+ * `now` is injectable so tests can assert deterministic `observedAt` /
+ * `resetsAt` values without touching `Date.now`.
+ */
+function createDefaultBraveHarvest(now = Date.now) {
+    return async (headers) => {
+        // Skip silently when no rate-limit headers are present — Brave
+        // does not always attach them (e.g. metered plans, proxy
+        // gateways). An absent header set is the common case, not an
+        // error worth a stderr notice.
+        if (headers.policy === null &&
+            headers.limit === null &&
+            headers.remaining === null &&
+            headers.reset === null) {
+            return;
+        }
+        try {
+            const result = normalizeBraveQuota(headers, now);
+            const snapshot = {
+                observedAt: now(),
+                categories: result.categories,
+            };
+            await writeQuotaSnapshot("brave", snapshot);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            process.stderr.write(`scoutline: brave quota harvest failed: ${message}\n`);
+        }
+    };
+}
+// ---------------------------------------------------------------------------
 // Descriptor factory
 // ---------------------------------------------------------------------------
 /**
@@ -479,9 +528,16 @@ function createBraveSearchCapability(options) {
  * (typically a fake-fetch wrapper); production uses the no-argument
  * factory which resolves to the global `fetch` and timers inside the
  * transport Module.
+ *
+ * PB-T1: the no-argument factory wires the production passive-harvest
+ * callback ({@link createDefaultBraveHarvest}) so every successful web
+ * search writes a rate-limit snapshot to `state.json`. Tests inject
+ * `onRateLimitHarvest` (or `undefined` to disable) through
+ * `BraveAdapterDependencies`.
  */
 export function createBraveDescriptor(dependencies) {
     const transport = dependencies?.transport;
+    const onRateLimitHarvest = dependencies?.onRateLimitHarvest ?? createDefaultBraveHarvest();
     return {
         id: "brave",
         isConfigured(env) {
@@ -494,11 +550,17 @@ export function createBraveDescriptor(dependencies) {
             return new Set(["search", "diagnostics", "quota"]);
         },
         create(context) {
-            const search = createBraveSearchCapability({ env: context.env, transport });
+            const search = createBraveSearchCapability({
+                env: context.env,
+                transport,
+                onRateLimitHarvest,
+            });
             const diagnostics = createBraveDiagnosticsCapability({ env: context.env, transport });
             const quota = createBraveQuotaCapability({ env: context.env, transport });
             return { id: "brave", search, diagnostics, quota };
         },
+        // Provider-fallback Ticket 02 — see ProviderDescriptor.credentialEnvVars.
+        credentialEnvVars: ["BRAVE_SEARCH_API_KEY"],
     };
 }
 //# sourceMappingURL=adapter.js.map