@gobing-ai/ts-ai-runner 0.4.55 → 0.4.57

package/dist/ai-runner.d.ts

@@ -2,6 +2,7 @@ import { type BusLifecycleEvents, EventBus, type Logger } from '@gobing-ai/ts-in
 import { type ProcessExecutor, type ProcessOutputChunk, type TracerPort } from '@gobing-ai/ts-runtime';
 import { type AgentName, type PromptOptions, type ShimCommand } from './agents/shims';
 import type { AgentEvents, AiRunnerProcessEvents } from './events';
+import { type QuotaAttribution } from './quota';
 /** Result returned by every AI runner dispatch method. */
 export interface AgentRunResult {
     /** Process exit code; null indicates signal or timeout termination. */
@@ -27,6 +28,12 @@ export interface AgentRunOptions {
     onOutput?: (output: ProcessOutputChunk) => void;
     /** Optional application-owned correlation propagated unchanged to agent lifecycle events. */
     correlation?: AgentRunCorrelation;
+    /**
+     * Optional exact attribution for quota observations (Spur task 0798). Purely
+     * additive metadata: existing callers without it keep byte-identical results,
+     * and missing fields stay absent on emitted observations — never inferred.
+     */
+    quotaContext?: QuotaAttribution;
 }
 /** Application-owned execution identity carried without coupling the runner to a workflow model. */
 export interface AgentRunCorrelation {
@@ -92,6 +99,8 @@ export declare class AiRunner {
     private readonly defaultTimeout;
     private readonly logger;
     private readonly events;
+    /** Single producer path for quota events; no-ops when no agent event bus is configured. */
+    private readonly quotaProducer;
     /** Internal process-level observability bus, parented to `lifecycleBus` when auto-constructed. Exposed for introspection/testing. */
     readonly processEvents: EventBus<AiRunnerProcessEvents> | undefined;
     constructor(options?: AiRunnerOptions);

package/dist/ai-runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ai-runner.d.ts","sourceRoot":"","sources":["../src/ai-runner.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ai-runner.d.ts","sourceRoot":"","sources":["../src/ai-runner.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,kBAAkB,EAAE,QAAQ,EAAa,KAAK,MAAM,EAAc,MAAM,qBAAqB,CAAC;AAC5G,OAAO,EAGH,KAAK,eAAe,EACpB,KAAK,kBAAkB,EAEvB,KAAK,UAAU,EAClB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,KAAK,SAAS,EAAgB,KAAK,aAAa,EAAE,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAC;AACpG,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAEnE,OAAO,EAGH,KAAK,gBAAgB,EAExB,MAAM,SAAS,CAAC;AAGjB,0DAA0D;AAC1D,MAAM,WAAW,cAAc;IAC3B,uEAAuE;IACvE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,uBAAuB;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,uBAAuB;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAC;CACtB;AAED,sCAAsC;AACtC,MAAM,WAAW,eAAe;IAC5B,4CAA4C;IAC5C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yFAAyF;IACzF,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,gFAAgF;IAChF,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,kBAAkB,KAAK,IAAI,CAAC;IAChD,6FAA6F;IAC7F,WAAW,CAAC,EAAE,mBAAmB,CAAC;IAClC;;;;OAIG;IACH,YAAY,CAAC,EAAE,gBAAgB,CAAC;CACnC;AAED,oGAAoG;AACpG,MAAM,WAAW,mBAAmB;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC9B;AACD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,gBAAgB,gBAAgB,CAAC;AAC9C,kFAAkF;AAClF,eAAO,MAAM,sBAAsB,sBAAsB,CAAC;AAC1D,wFAAwF;AACxF,eAAO,MAAM,mBAAmB,mBAAmB,CAAC;AAiBpD,wCAAwC;AACxC,MAAM,WAAW,eAAe;IAC5B,4DAA4D;IAC5D,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,iDAAiD;IACjD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,aAAa,CAAC,EAAE,QAAQ,CAAC,qBAAqB,CAAC,CAAC;IAChD,gEAAgE;IAChE,MAAM,CAAC,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;IAC/B;;;;OAIG;IACH,YAAY,CAAC,EAAE,QAAQ,CAAC,kBAAkB,CAAC,CAAC;IAC5C,kFAAkF;IAClF,MAAM,CAAC,EAAE,UAAU,CAAC;CACvB;AAED,uEAAuE;AACvE,qBAAa,QAAQ;IACjB,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAClD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;IAChD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqB;IACpD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoC;IAC3D,2FAA2F;IAC3F,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA2B;IACzD,qIAAqI;IACrI,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC,qBAAqB,CAAC,GAAG,SAAS,CAAC;gBAExD,OAAO,GAAE,eAAoB;IAiCzC,iCAAiC;IACjC,cAAc,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,cAAc,CAAC;IAIxF,oCAAoC;IACpC,iBAAiB,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,cAAc,CAAC;IAI3F,mCAAmC;IACnC,gBAAgB,CACZ,KAAK,EAAE,SAAS,EAChB,aAAa,EAAE,aAAa,EAC5B,OAAO,GAAE,eAAoB,GAC9B,OAAO,CAAC,cAAc,CAAC;IAI1B,6EAA6E;IAC7E,eAAe,CACX,KAAK,EAAE,SAAS,EAChB,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,aAAa,EAC5B,OAAO,GAAE,eAAoB,GAC9B,OAAO,CAAC,cAAc,CAAC;IAI1B,0DAA0D;IAC1D,kBAAkB,CAAC,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,aAAa,EAAE,OAAO,GAAE,eAAoB,GAAG,WAAW;IAa9G,4EAA4E;IAC5E,cAAc,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,cAAc,CAAC,GAAG,IAAI;YAKjF,MAAM;CAmEvB;AAWD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC7B,KAAK,EAAE,SAAS,EAChB,aAAa,EAAE,aAAa,EAC5B,OAAO,EAAE;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,GAC/B,WAAW,CAKb"}

package/dist/ai-runner.js

@@ -2,6 +2,7 @@ import { EventBus, getLogger, traceAsync } from '@gobing-ai/ts-infra';
 import { getProcessCwd, nodeBunFactory, } from '@gobing-ai/ts-runtime';
 import { getAgentShim } from './agents/shims.js';
 import { buildIdentityPreamble } from './identity.js';
+import { buildQuotaObservation, classifyQuotaErrorRecord, QuotaObservationProducer, } from './quota.js';
 import { translateSlashCommand } from './slash-command.js';
 /**
  * Public environment-variable contract for agent run correlation.
@@ -52,6 +53,8 @@ export class AiRunner {
     defaultTimeout;
     logger;
     events;
+    /** Single producer path for quota events; no-ops when no agent event bus is configured. */
+    quotaProducer;
     /** Internal process-level observability bus, parented to `lifecycleBus` when auto-constructed. Exposed for introspection/testing. */
     processEvents;
     constructor(options = {}) {
@@ -81,6 +84,7 @@ export class AiRunner {
         this.defaultTimeout = options.defaultTimeout;
         this.logger = options.logger ?? getLogger('ai-runner');
         this.events = events;
+        this.quotaProducer = new QuotaObservationProducer(events);
         this.processEvents = processEvents;
     }
     /** Run an agent help command. */
@@ -153,6 +157,17 @@ export class AiRunner {
             ...(options.correlation !== undefined ? { correlation: options.correlation } : {}),
             severity: result.exitCode === 0 || result.exitCode === null ? 'info' : 'error',
         });
+        if (result.exitCode !== null && result.exitCode !== 0) {
+            const classification = classifyQuotaErrorRecord(result.stderr);
+            if (classification.quota) {
+                this.quotaProducer.produce(buildQuotaObservation({
+                    source: 'buffered-error',
+                    reason: classification.reason,
+                    attribution: { agent, ...options.quotaContext },
+                    ...(options.correlation !== undefined ? { correlation: options.correlation } : {}),
+                }));
+            }
+        }
         return {
             exitCode: result.exitCode,
             stdout: result.stdout,

package/dist/events.d.ts

@@ -1,6 +1,7 @@
 import type { EventSeverity } from '@gobing-ai/ts-infra';
 import type { ProcessEvents } from '@gobing-ai/ts-runtime';
 import type { AgentRunCorrelation } from './ai-runner';
+import type { AgentQuotaObservation, AgentQuotaRecovery } from './quota';
 /** Typed event map for agent-runner observability. All events prefixed `agent.`. */
 export type AgentEvents = {
     /** Emitted immediately before an agent CLI invocation starts. */
@@ -41,6 +42,10 @@ export type AgentEvents = {
         ok: boolean;
         severity: EventSeverity;
     }) => void;
+    /** Emitted once per verified quota-exhaustion observation (confirmed usage-allowance or credit exhaustion). */
+    'agent.quota.exhausted': (data: AgentQuotaObservation) => void;
+    /** Explicit-recovery signal; type contract only — no automatic producer exists upstream. */
+    'agent.quota.recovered': (data: AgentQuotaRecovery) => void;
 };
 /** Event map for process-level observability emitted by AiRunner-owned executors. */
 export type AiRunnerProcessEvents = ProcessEvents;

package/dist/events.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAEvD,oFAAoF;AACpF,MAAM,MAAM,WAAW,GAAG;IACtB,iEAAiE;IACjE,oBAAoB,EAAE,CAAC,IAAI,EAAE;QACzB,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,EAAE,MAAM,CAAC;QACd,WAAW,CAAC,EAAE,mBAAmB,CAAC;QAClC,QAAQ,EAAE,aAAa,CAAC;KAC3B,KAAK,IAAI,CAAC;IACX,mDAAmD;IACnD,mBAAmB,EAAE,CAAC,IAAI,EAAE;QACxB,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QACxB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,WAAW,CAAC,EAAE,mBAAmB,CAAC;QAClC,QAAQ,EAAE,aAAa,CAAC;KAC3B,KAAK,IAAI,CAAC;IACX,6DAA6D;IAC7D,eAAe,EAAE,CAAC,IAAI,EAAE;QACpB,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;QACnB,QAAQ,EAAE,aAAa,CAAC;KAC3B,KAAK,IAAI,CAAC;IACX,4DAA4D;IAC5D,eAAe,EAAE,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,QAAQ,EAAE,aAAa,CAAA;KAAE,KAAK,IAAI,CAAC;IACvG,8DAA8D;IAC9D,oBAAoB,EAAE,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,OAAO,CAAC;QAAC,QAAQ,EAAE,aAAa,CAAA;KAAE,KAAK,IAAI,CAAC;CACnG,CAAC;AAEF,qFAAqF;AACrF,MAAM,MAAM,qBAAqB,GAAG,aAAa,CAAC"}
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,KAAK,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAEzE,oFAAoF;AACpF,MAAM,MAAM,WAAW,GAAG;IACtB,iEAAiE;IACjE,oBAAoB,EAAE,CAAC,IAAI,EAAE;QACzB,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,EAAE,MAAM,CAAC;QACd,WAAW,CAAC,EAAE,mBAAmB,CAAC;QAClC,QAAQ,EAAE,aAAa,CAAC;KAC3B,KAAK,IAAI,CAAC;IACX,mDAAmD;IACnD,mBAAmB,EAAE,CAAC,IAAI,EAAE;QACxB,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QACxB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,WAAW,CAAC,EAAE,mBAAmB,CAAC;QAClC,QAAQ,EAAE,aAAa,CAAC;KAC3B,KAAK,IAAI,CAAC;IACX,6DAA6D;IAC7D,eAAe,EAAE,CAAC,IAAI,EAAE;QACpB,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;QACnB,QAAQ,EAAE,aAAa,CAAC;KAC3B,KAAK,IAAI,CAAC;IACX,4DAA4D;IAC5D,eAAe,EAAE,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,QAAQ,EAAE,aAAa,CAAA;KAAE,KAAK,IAAI,CAAC;IACvG,8DAA8D;IAC9D,oBAAoB,EAAE,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,OAAO,CAAC;QAAC,QAAQ,EAAE,aAAa,CAAA;KAAE,KAAK,IAAI,CAAC;IAChG,+GAA+G;IAC/G,uBAAuB,EAAE,CAAC,IAAI,EAAE,qBAAqB,KAAK,IAAI,CAAC;IAC/D,4FAA4F;IAC5F,uBAAuB,EAAE,CAAC,IAAI,EAAE,kBAAkB,KAAK,IAAI,CAAC;CAC/D,CAAC;AAEF,qFAAqF;AACrF,MAAM,MAAM,qBAAqB,GAAG,aAAa,CAAC"}

package/dist/index.d.ts

@@ -9,6 +9,7 @@ export * from './identity';
 export * from './message-store';
 export * from './messages';
 export * from './model-health-probe';
+export * from './quota';
 export * from './slash-command';
 export * from './team-agent-process';
 export * from './team-orchestrator';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC;AAC3B,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC;AAC3B,cAAc,sBAAsB,CAAC;AACrC,cAAc,SAAS,CAAC;AACxB,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC"}

package/dist/index.js

@@ -9,6 +9,7 @@ export * from './identity.js';
 export * from './message-store.js';
 export * from './messages.js';
 export * from './model-health-probe.js';
+export * from './quota.js';
 export * from './slash-command.js';
 export * from './team-agent-process.js';
 export * from './team-orchestrator.js';

package/dist/model-health-probe.d.ts

@@ -10,7 +10,10 @@
  * issuing a minimal 1-token completion request and interpreting the HTTP
  * response (R3).
  */
-import { type APIClientConfig } from '@gobing-ai/ts-infra';
+import { type APIClientConfig, type EventBus } from '@gobing-ai/ts-infra';
+import type { AgentRunCorrelation } from './ai-runner';
+import type { AgentEvents } from './events';
+import { type AgentQuotaObservation, type QuotaAttribution, QuotaObservationProducer } from './quota';
 /** Health status for a single model endpoint. */
 export type ModelHealthStatus = 'available' | 'quota_exhausted' | 'rate_limited' | 'unavailable' | 'unknown';
 /** Result of probing one model's health (R2). */
@@ -91,4 +94,23 @@ export declare class OmpModelProbe implements ModelHealthProbe {
 }
 /** Default probe timeout in milliseconds (R8). */
 export { DEFAULT_PROBE_TIMEOUT_MS };
+/** Options for the explicitly opted-in quota health observation. */
+export interface QuotaHealthObservationOptions {
+    /** Agent event bus receiving `agent.quota.exhausted`. */
+    events: EventBus<AgentEvents>;
+    /** Optional exact attribution; absent fields stay absent — never inferred. */
+    attribution?: QuotaAttribution;
+    /** Optional run correlation carried unchanged onto the observation. */
+    correlation?: AgentRunCorrelation;
+    /** Optional shared producer so multiple observations dedupe across one observation session. */
+    producer?: QuotaObservationProducer;
+}
+/**
+ * Explicitly opted-in health observation → quota event. The ONLY producer seam
+ * on the health path: ordinary doctor runs never call this, so read-only
+ * behavior is preserved. Returns the emitted observation, or null when the
+ * result is not a confirmed quota exhaustion (rate_limited / unavailable /
+ * unknown never produce events).
+ */
+export declare function observeQuotaHealthResult(result: ModelHealthResult, options: QuotaHealthObservationOptions): AgentQuotaObservation | null;
 //# sourceMappingURL=model-health-probe.d.ts.map

package/dist/model-health-probe.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"model-health-probe.d.ts","sourceRoot":"","sources":["../src/model-health-probe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAa,KAAK,eAAe,EAAkC,MAAM,qBAAqB,CAAC;AAEtG,iDAAiD;AACjD,MAAM,MAAM,iBAAiB,GAAG,WAAW,GAAG,iBAAiB,GAAG,cAAc,GAAG,aAAa,GAAG,SAAS,CAAC;AAE7G,iDAAiD;AACjD,MAAM,WAAW,iBAAiB;IAC9B,MAAM,EAAE,iBAAiB,CAAC;IAC1B,6EAA6E;IAC7E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,SAAS,EAAE,MAAM,CAAC;CACrB;AAED,8EAA8E;AAC9E,MAAM,WAAW,WAAW;IACxB,gFAAgF;IAChF,MAAM,EAAE,MAAM,CAAC;IACf,2FAA2F;IAC3F,SAAS,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,8CAA8C;AAC9C,MAAM,WAAW,gBAAgB;IAC7B,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CAC3F;AAED;;;;GAIG;AACH,qBAAa,wBAAwB;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuC;IAE9D,mEAAmE;IACnE,QAAQ,CAAC,cAAc,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,GAAG,IAAI;IAI/D,iFAAiF;IACjF,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI;CAKlD;AAED,kEAAkE;AAClE,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGrD;AAED,6DAA6D;AAC7D,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGtD;AAgBD,QAAA,MAAM,wBAAwB,QAAS,CAAC;AAExC,yDAAyD;AACzD,MAAM,WAAW,oBAAoB;IACjC;;;;;OAKG;IACH,eAAe,CAAC,EAAE,IAAI,CAAC,eAAe,EAAE,SAAS,CAAC,CAAC;CACtD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,aAAc,YAAW,gBAAgB;IAClD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAmC;gBAExD,OAAO,CAAC,EAAE,oBAAoB;IAIpC,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,iBAAiB,CAAC;IA6B7F,kEAAkE;YACpD,YAAY;IAiD1B,oEAAoE;IACpE,OAAO,CAAC,iBAAiB;IAwBzB,4DAA4D;IAC5D,OAAO,CAAC,SAAS;CAOpB;AAED,kDAAkD;AAClD,OAAO,EAAE,wBAAwB,EAAE,CAAC"}
+{"version":3,"file":"model-health-probe.d.ts","sourceRoot":"","sources":["../src/model-health-probe.ts"],"names":[],"mappings":"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"}

package/dist/model-health-probe.js

@@ -11,6 +11,7 @@
  * response (R3).
  */
 import { APIClient, APIError } from '@gobing-ai/ts-infra';
+import { buildQuotaObservation, QuotaObservationProducer, } from './quota.js';
 /**
  * Maps provider prefixes to probe implementations (R9).
  * The provider prefix is extracted from the model string's first path segment
@@ -151,3 +152,25 @@ export class OmpModelProbe {
 }
 /** Default probe timeout in milliseconds (R8). */
 export { DEFAULT_PROBE_TIMEOUT_MS };
+/**
+ * Explicitly opted-in health observation → quota event. The ONLY producer seam
+ * on the health path: ordinary doctor runs never call this, so read-only
+ * behavior is preserved. Returns the emitted observation, or null when the
+ * result is not a confirmed quota exhaustion (rate_limited / unavailable /
+ * unknown never produce events).
+ */
+export function observeQuotaHealthResult(result, options) {
+    if (result.status !== 'quota_exhausted')
+        return null;
+    const producer = options.producer ?? new QuotaObservationProducer(options.events);
+    const observation = buildQuotaObservation({
+        source: 'health-probe',
+        reason: 'provider_quota_exhausted',
+        observedAt: new Date(result.checkedAt),
+        ...(result.detail !== undefined ? { detail: result.detail } : {}),
+        attribution: options.attribution,
+        ...(options.correlation !== undefined ? { correlation: options.correlation } : {}),
+    });
+    producer.produce(observation);
+    return observation;
+}

package/dist/quota.d.ts

@@ -0,0 +1,98 @@
+import type { EventBus } from '@gobing-ai/ts-infra';
+import type { AgentRunCorrelation } from './ai-runner';
+import type { AgentEvents } from './events';
+/**
+ * Canonical quota-exhaustion codes accepted in structured error-record positions
+ * (`error.type` / `error.code`). The set is an exact-match allowlist on purpose:
+ * free text never confirms quota (R2 — Spur task 0798). Generic HTTP 429 without
+ * one of these codes is rate limiting, not quota exhaustion.
+ */
+export type QuotaExhaustionReason = 'insufficient_quota' | 'insufficient_credit_balance' | 'quota_exceeded' | 'usage_limit_reached' | 'credits_exhausted' | 'billing_hard_limit_reached'
+/** Verified by the shipped health probe's quota-aware 429 interpretation (`OmpModelProbe`). */
+ | 'provider_quota_exhausted';
+/** Where a quota observation was verified. Streaming evidence is a bounded trailing window, never a transcript. */
+export type QuotaEvidenceSource = 'buffered-error' | 'streaming-error' | 'health-probe';
+/**
+ * Exact attribution carried on a quota observation. Every field is optional and
+ * only populated from caller-supplied context — the runner never infers project
+ * or executor identity (missing attribution stays observable, not guessed).
+ */
+export interface QuotaAttribution {
+    projectId?: string;
+    executor?: string;
+    agent?: string;
+    model?: string;
+}
+/** A verified quota-exhaustion observation. `observationId` is deterministic, so redelivery keeps identity. */
+export interface AgentQuotaObservation {
+    /** Stable across redelivery: digest over evidence source, reason, and attribution identity — never timestamps. */
+    observationId: string;
+    /** UTC ISO-8601 with millisecond precision. */
+    observedAt: string;
+    evidenceSource: QuotaEvidenceSource;
+    reason: QuotaExhaustionReason;
+    /** Sanitized provider detail. Only carried when the source guarantees sanitization (health probe). */
+    detail?: string;
+    /** Exact attribution when supplied by the caller; absent fields mean unknown. */
+    attribution?: QuotaAttribution;
+    correlation?: AgentRunCorrelation;
+}
+/** Explicit-recovery payload for `agent.quota.recovered`. Type contract only — no automatic producer, timer, or polling. */
+export interface AgentQuotaRecovery {
+    /** The observationId whose quota state recovered. */
+    observationId: string;
+    /** UTC ISO-8601 with millisecond precision. */
+    recoveredAt: string;
+    attribution?: QuotaAttribution;
+    correlation?: AgentRunCorrelation;
+}
+/** Result of classifying one bounded error record. */
+export type QuotaClassification = {
+    quota: true;
+    reason: QuotaExhaustionReason;
+} | {
+    quota: false;
+};
+/** Upper bound for error evidence considered by the classifier (bytes, UTF-8). Keeps streaming memory bounded. */
+export declare const MAX_QUOTA_EVIDENCE_BYTES = 8192;
+/**
+ * Classify one error record as quota exhaustion. Accepts only structured
+ * provider error envelopes — a JSON object with an `error` object whose
+ * `type` or `code` exactly matches a canonical quota code. Free text, quoted
+ * prompt content inside `error.message`, plain HTTP 429 rate-limit codes,
+ * throttling/overload, authentication, context/output limits, and timeouts
+ * all classify as negative (R2). Input is bounded to
+ * {@link MAX_QUOTA_EVIDENCE_BYTES} trailing bytes.
+ */
+export declare function classifyQuotaErrorRecord(record: string): QuotaClassification;
+/** Normalize an observation timestamp to UTC ISO-8601 with millisecond precision. */
+export declare function normalizeObservedAt(at: Date): string;
+/**
+ * Build a quota observation. `observationId` is a SHA-256 digest over the
+ * evidence source, reason, and attribution identity — stable across
+ * redelivery because it excludes timestamps, correlation, and free text.
+ */
+export declare function buildQuotaObservation(params: {
+    source: QuotaEvidenceSource;
+    reason: QuotaExhaustionReason;
+    observedAt?: Date;
+    detail?: string;
+    attribution?: QuotaAttribution;
+    correlation?: AgentRunCorrelation;
+}): AgentQuotaObservation;
+/**
+ * Single producer path for quota events. Emits `agent.quota.exhausted` at most
+ * once per observationId per producer instance (redelivery of the same quota
+ * fact is suppressed). Recovery delivery is explicit-only — callers own
+ * recovery detection; this class never schedules, polls, or times anything.
+ */
+export declare class QuotaObservationProducer {
+    private readonly events;
+    private readonly emitted;
+    constructor(events: EventBus<AgentEvents> | undefined);
+    /** Emit one `agent.quota.exhausted`. Returns true when emitted, false when deduped or bus-less. */
+    produce(observation: AgentQuotaObservation): boolean;
+    /** Deliver an explicit `agent.quota.recovered`. Returns true when emitted, false when bus-less. */
+    produceRecovery(recovery: AgentQuotaRecovery): boolean;
+}
+//# sourceMappingURL=quota.d.ts.map

package/dist/quota.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quota.d.ts","sourceRoot":"","sources":["../src/quota.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5C;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAC3B,oBAAoB,GACpB,6BAA6B,GAC7B,gBAAgB,GAChB,qBAAqB,GACrB,mBAAmB,GACnB,4BAA4B;AAC9B,+FAA+F;GAC7F,0BAA0B,CAAC;AAEjC,mHAAmH;AACnH,MAAM,MAAM,mBAAmB,GAAG,gBAAgB,GAAG,iBAAiB,GAAG,cAAc,CAAC;AAExF;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,+GAA+G;AAC/G,MAAM,WAAW,qBAAqB;IAClC,kHAAkH;IAClH,aAAa,EAAE,MAAM,CAAC;IACtB,+CAA+C;IAC/C,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,mBAAmB,CAAC;IACpC,MAAM,EAAE,qBAAqB,CAAC;IAC9B,sGAAsG;IACtG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAC/B,WAAW,CAAC,EAAE,mBAAmB,CAAC;CACrC;AAED,4HAA4H;AAC5H,MAAM,WAAW,kBAAkB;IAC/B,qDAAqD;IACrD,aAAa,EAAE,MAAM,CAAC;IACtB,+CAA+C;IAC/C,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAC/B,WAAW,CAAC,EAAE,mBAAmB,CAAC;CACrC;AAED,sDAAsD;AACtD,MAAM,MAAM,mBAAmB,GAAG;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,qBAAqB,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,KAAK,CAAA;CAAE,CAAC;AAEpG,kHAAkH;AAClH,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAW7C;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,mBAAmB,CAU5E;AAkBD,qFAAqF;AACrF,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,IAAI,GAAG,MAAM,CAEpD;AAYD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE;IAC1C,MAAM,EAAE,mBAAmB,CAAC;IAC5B,MAAM,EAAE,qBAAqB,CAAC;IAC9B,UAAU,CAAC,EAAE,IAAI,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAC/B,WAAW,CAAC,EAAE,mBAAmB,CAAC;CACrC,GAAG,qBAAqB,CAoBxB;AAED;;;;;GAKG;AACH,qBAAa,wBAAwB;IAGrB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAFnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;gBAEhB,MAAM,EAAE,QAAQ,CAAC,WAAW,CAAC,GAAG,SAAS;IAEtE,mGAAmG;IACnG,OAAO,CAAC,WAAW,EAAE,qBAAqB,GAAG,OAAO;IAOpD,mGAAmG;IACnG,eAAe,CAAC,QAAQ,EAAE,kBAAkB,GAAG,OAAO;CAKzD"}

package/dist/quota.js

@@ -0,0 +1,123 @@
+import { createHash } from 'node:crypto';
+/** Upper bound for error evidence considered by the classifier (bytes, UTF-8). Keeps streaming memory bounded. */
+export const MAX_QUOTA_EVIDENCE_BYTES = 8192;
+const QUOTA_CODES = new Set([
+    'insufficient_quota',
+    'insufficient_credit_balance',
+    'quota_exceeded',
+    'usage_limit_reached',
+    'credits_exhausted',
+    'billing_hard_limit_reached',
+]);
+/**
+ * Classify one error record as quota exhaustion. Accepts only structured
+ * provider error envelopes — a JSON object with an `error` object whose
+ * `type` or `code` exactly matches a canonical quota code. Free text, quoted
+ * prompt content inside `error.message`, plain HTTP 429 rate-limit codes,
+ * throttling/overload, authentication, context/output limits, and timeouts
+ * all classify as negative (R2). Input is bounded to
+ * {@link MAX_QUOTA_EVIDENCE_BYTES} trailing bytes.
+ */
+export function classifyQuotaErrorRecord(record) {
+    const bounded = record.length > MAX_QUOTA_EVIDENCE_BYTES ? record.slice(-MAX_QUOTA_EVIDENCE_BYTES) : record;
+    const envelope = tryParseErrorEnvelope(bounded);
+    if (envelope === null)
+        return { quota: false };
+    const type = typeof envelope.type === 'string' ? envelope.type.toLowerCase() : '';
+    const code = typeof envelope.code === 'string' ? envelope.code.toLowerCase() : '';
+    for (const candidate of [type, code]) {
+        if (QUOTA_CODES.has(candidate))
+            return { quota: true, reason: candidate };
+    }
+    return { quota: false };
+}
+/** Best-effort parse of a JSON provider error envelope (`{ error: { type?, code?, message? } }`). */
+function tryParseErrorEnvelope(record) {
+    const start = record.indexOf('{');
+    const end = record.lastIndexOf('}');
+    if (start < 0 || end <= start)
+        return null;
+    try {
+        const parsed = JSON.parse(record.slice(start, end + 1));
+        if (typeof parsed !== 'object' || parsed === null)
+            return null;
+        const error = parsed.error;
+        if (typeof error !== 'object' || error === null)
+            return null;
+        return error;
+    }
+    catch {
+        return null;
+    }
+}
+/** Normalize an observation timestamp to UTC ISO-8601 with millisecond precision. */
+export function normalizeObservedAt(at) {
+    return at.toISOString();
+}
+/** Keep only defined, non-empty attribution fields; return undefined when nothing is known. */
+function cleanAttribution(attribution) {
+    const cleaned = {};
+    if (attribution.projectId)
+        cleaned.projectId = attribution.projectId;
+    if (attribution.executor)
+        cleaned.executor = attribution.executor;
+    if (attribution.agent)
+        cleaned.agent = attribution.agent;
+    if (attribution.model)
+        cleaned.model = attribution.model;
+    return Object.keys(cleaned).length > 0 ? cleaned : undefined;
+}
+/**
+ * Build a quota observation. `observationId` is a SHA-256 digest over the
+ * evidence source, reason, and attribution identity — stable across
+ * redelivery because it excludes timestamps, correlation, and free text.
+ */
+export function buildQuotaObservation(params) {
+    const attribution = params.attribution === undefined ? undefined : cleanAttribution(params.attribution);
+    const identity = [
+        params.source,
+        params.reason,
+        attribution?.projectId ?? '',
+        attribution?.executor ?? '',
+        attribution?.agent ?? '',
+        attribution?.model ?? '',
+    ].join('\0');
+    const observationId = `qo-${createHash('sha256').update(identity).digest('hex').slice(0, 24)}`;
+    return {
+        observationId,
+        observedAt: normalizeObservedAt(params.observedAt ?? new Date()),
+        evidenceSource: params.source,
+        reason: params.reason,
+        ...(params.detail !== undefined && params.detail !== '' ? { detail: params.detail } : {}),
+        ...(attribution !== undefined ? { attribution } : {}),
+        ...(params.correlation !== undefined ? { correlation: params.correlation } : {}),
+    };
+}
+/**
+ * Single producer path for quota events. Emits `agent.quota.exhausted` at most
+ * once per observationId per producer instance (redelivery of the same quota
+ * fact is suppressed). Recovery delivery is explicit-only — callers own
+ * recovery detection; this class never schedules, polls, or times anything.
+ */
+export class QuotaObservationProducer {
+    events;
+    emitted = new Set();
+    constructor(events) {
+        this.events = events;
+    }
+    /** Emit one `agent.quota.exhausted`. Returns true when emitted, false when deduped or bus-less. */
+    produce(observation) {
+        if (this.events === undefined || this.emitted.has(observation.observationId))
+            return false;
+        this.emitted.add(observation.observationId);
+        void this.events.emit('agent.quota.exhausted', observation);
+        return true;
+    }
+    /** Deliver an explicit `agent.quota.recovered`. Returns true when emitted, false when bus-less. */
+    produceRecovery(recovery) {
+        if (this.events === undefined)
+            return false;
+        void this.events.emit('agent.quota.recovered', recovery);
+        return true;
+    }
+}

package/dist/team-agent-process.d.ts

@@ -1,7 +1,9 @@
 import { Buffer } from 'node:buffer';
-import { type Logger } from '@gobing-ai/ts-infra';
+import { type EventBus, type Logger } from '@gobing-ai/ts-infra';
 import { type ProcessExecutor } from '@gobing-ai/ts-runtime';
 import type { AgentSpec } from './agent-spec';
+import type { AgentEvents } from './events';
+import { type QuotaAttribution } from './quota';
 /** Options for spawning a team agent subprocess. */
 export interface AgentProcessOptions {
     spec: AgentSpec;
@@ -10,6 +12,10 @@ export interface AgentProcessOptions {
     cwd?: string;
     processExecutor?: ProcessExecutor;
     logger?: Logger;
+    /** Optional agent event bus; when present, confirmed quota failures emit `agent.quota.exhausted` (Spur task 0798). */
+    events?: EventBus<AgentEvents>;
+    /** Optional exact quota attribution; absent fields stay absent on observations — never inferred. */
+    quotaContext?: QuotaAttribution;
 }
 type ProcessStatus = 'running' | 'stopped' | 'errored';
 /**
@@ -27,6 +33,11 @@ export declare class TeamAgentProcess {
     private status;
     private exitCode;
     private readonly subscribers;
+    /** Bounded trailing stderr window retained for quota classification — never a full transcript. */
+    private stderrTail;
+    private readonly quotaProducer;
+    private readonly spec;
+    private readonly quotaContext;
     constructor(options: AgentProcessOptions);
     start(): Promise<void>;
     stop(): Promise<void>;
@@ -38,6 +49,10 @@ export declare class TeamAgentProcess {
     getPid(): number | null;
     getExitCode(): number | null;
     private pipe;
+    /** Keep only the trailing {@link MAX_QUOTA_EVIDENCE_BYTES} of stderr; subscribers still see every chunk unchanged. */
+    private retainStderrTail;
+    /** Classify the retained stderr window and emit one attributed quota observation on confirmation. */
+    private classifyQuota;
     private warn;
 }
 export {};

package/dist/team-agent-process.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"team-agent-process.d.ts","sourceRoot":"","sources":["../src/team-agent-process.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAa,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EAAoC,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC/F,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,oDAAoD;AACpD,MAAM,WAAW,mBAAmB;IAChC,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,KAAK,aAAa,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAEvD;;;GAGG;AACH,qBAAa,gBAAgB;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAW;IACnC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAqC;IACzD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAqB;IACzC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAClD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,UAAU,CAA4B;IAC9C,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqC;gBAErD,OAAO,EAAE,mBAAmB;IASlC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAqBtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IA0BrB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAA;KAAE,CAAC;IAerD,SAAS,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI;IAOvD,SAAS,IAAI,aAAa;IAI1B,MAAM,IAAI,MAAM,GAAG,IAAI;IAIvB,WAAW,IAAI,MAAM,GAAG,IAAI;YAId,IAAI;IAiBlB,OAAO,CAAC,IAAI;CAOf"}
+{"version":3,"file":"team-agent-process.d.ts","sourceRoot":"","sources":["../src/team-agent-process.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,KAAK,QAAQ,EAAa,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC5E,OAAO,EAAoC,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC/F,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,EAIH,KAAK,gBAAgB,EAExB,MAAM,SAAS,CAAC;AAEjB,oDAAoD;AACpD,MAAM,WAAW,mBAAmB;IAChC,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sHAAsH;IACtH,MAAM,CAAC,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;IAC/B,oGAAoG;IACpG,YAAY,CAAC,EAAE,gBAAgB,CAAC;CACnC;AAED,KAAK,aAAa,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAEvD;;;GAGG;AACH,qBAAa,gBAAgB;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAW;IACnC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAqC;IACzD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAqB;IACzC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAClD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,UAAU,CAA4B;IAC9C,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqC;IACjE,kGAAkG;IAClG,OAAO,CAAC,UAAU,CAAM;IACxB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA2B;IACzD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAY;IACjC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA+B;gBAEhD,OAAO,EAAE,mBAAmB;IAYlC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAyBtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IA0BrB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAA;KAAE,CAAC;IAerD,SAAS,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI;IAOvD,SAAS,IAAI,aAAa;IAI1B,MAAM,IAAI,MAAM,GAAG,IAAI;IAIvB,WAAW,IAAI,MAAM,GAAG,IAAI;YAId,IAAI;IAkBlB,sHAAsH;IACtH,OAAO,CAAC,gBAAgB;IAIxB,qGAAqG;IACrG,OAAO,CAAC,aAAa;IAgBrB,OAAO,CAAC,IAAI;CAOf"}

package/dist/team-agent-process.js

@@ -1,6 +1,7 @@
 import { Buffer } from 'node:buffer';
 import { getLogger } from '@gobing-ai/ts-infra';
 import { nodeBunFactory } from '@gobing-ai/ts-runtime';
+import { buildQuotaObservation, classifyQuotaErrorRecord, MAX_QUOTA_EVIDENCE_BYTES, QuotaObservationProducer, } from './quota.js';
 /**
  * Manages the lifecycle of a single agent subprocess — start, stop, message send, and stdout/stderr subscription.
  * The identity preamble is built by `TeamOrchestrator` and baked into `command` before the process is constructed.
@@ -16,6 +17,11 @@ export class TeamAgentProcess {
     status = 'stopped';
     exitCode = null;
     subscribers = new Set();
+    /** Bounded trailing stderr window retained for quota classification — never a full transcript. */
+    stderrTail = '';
+    quotaProducer;
+    spec;
+    quotaContext;
     constructor(options) {
         this.agentId = options.spec.id;
         this.command = options.command;
@@ -23,6 +29,9 @@ export class TeamAgentProcess {
         this.cwd = options.cwd ?? options.spec.workspace;
         this.processExecutor = options.processExecutor ?? nodeBunFactory.createProcessExecutor();
         this.logger = options.logger ?? getLogger('team-agent');
+        this.quotaProducer = new QuotaObservationProducer(options.events);
+        this.spec = options.spec;
+        this.quotaContext = options.quotaContext;
     }
     async start() {
         if (this.status === 'running')
@@ -39,14 +48,18 @@ export class TeamAgentProcess {
         });
         this.status = 'running';
         this.exitCode = null;
+        this.stderrTail = '';
         if (this.subprocess.stdout !== null)
-            this.pipe(this.subprocess.stdout);
+            this.pipe(this.subprocess.stdout, false);
         if (this.subprocess.stderr !== null)
-            this.pipe(this.subprocess.stderr);
+            this.pipe(this.subprocess.stderr, true);
         void this.subprocess.exited.then((code) => {
             this.exitCode = code;
-            if (this.status === 'running')
+            if (this.status === 'running') {
                 this.status = code === 0 ? 'stopped' : 'errored';
+                if (this.status === 'errored')
+                    this.classifyQuota();
+            }
         });
     }
     async stop() {
@@ -106,7 +119,7 @@ export class TeamAgentProcess {
     getExitCode() {
         return this.exitCode;
     }
-    async pipe(stream) {
+    async pipe(stream, isStderr) {
         const reader = stream.getReader();
         try {
             while (true) {
@@ -114,6 +127,8 @@ export class TeamAgentProcess {
                 if (chunk.done)
                     break;
                 const buffer = Buffer.from(chunk.value);
+                if (isStderr)
+                    this.retainStderrTail(buffer.toString('utf8'));
                 for (const subscriber of this.subscribers)
                     subscriber(buffer);
             }
@@ -127,6 +142,25 @@ export class TeamAgentProcess {
             reader.releaseLock();
         }
     }
+    /** Keep only the trailing {@link MAX_QUOTA_EVIDENCE_BYTES} of stderr; subscribers still see every chunk unchanged. */
+    retainStderrTail(text) {
+        this.stderrTail = (this.stderrTail + text).slice(-MAX_QUOTA_EVIDENCE_BYTES);
+    }
+    /** Classify the retained stderr window and emit one attributed quota observation on confirmation. */
+    classifyQuota() {
+        const classification = classifyQuotaErrorRecord(this.stderrTail);
+        if (!classification.quota)
+            return;
+        this.quotaProducer.produce(buildQuotaObservation({
+            source: 'streaming-error',
+            reason: classification.reason,
+            attribution: {
+                ...this.quotaContext,
+                agent: this.quotaContext?.agent ?? this.spec.id,
+                executor: this.quotaContext?.executor ?? this.spec.executor ?? this.spec.type,
+            },
+        }));
+    }
     warn(message, op, error) {
         this.logger.warn(message, {
             agentId: this.agentId,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/ts-ai-runner",
-    "version": "0.4.55",
+    "version": "0.4.57",
     "description": "@gobing-ai/ts-ai-runner — Coding-agent shims, detection, doctor checks, and prompt execution.",
     "keywords": [
         "typescript",
@@ -47,12 +47,12 @@
         "release": "echo 'Manual publish is disabled. Releases go through GitHub Actions via Trusted Publishing — push a tag: git tag @gobing-ai/ts-ai-runner-v<version> && git push --tags' && exit 1"
     },
     "dependencies": {
-        "@gobing-ai/ts-infra": "^0.4.55",
-        "@gobing-ai/ts-runtime": "^0.4.55"
+        "@gobing-ai/ts-infra": "^0.4.57",
+        "@gobing-ai/ts-runtime": "^0.4.57"
     },
     "devDependencies": {
         "@types/bun": "1.3.14",
-        "@gobing-ai/ts-db": "^0.4.55"
+        "@gobing-ai/ts-db": "^0.4.57"
     },
     "publishConfig": {
         "access": "public"

package/src/ai-runner.ts

@@ -10,6 +10,12 @@ import {
 import { type AgentName, getAgentShim, type PromptOptions, type ShimCommand } from './agents/shims';
 import type { AgentEvents, AiRunnerProcessEvents } from './events';
 import { buildIdentityPreamble } from './identity';
+import {
+    buildQuotaObservation,
+    classifyQuotaErrorRecord,
+    type QuotaAttribution,
+    QuotaObservationProducer,
+} from './quota';
 import { translateSlashCommand } from './slash-command';
 
 /** Result returned by every AI runner dispatch method. */
@@ -38,6 +44,12 @@ export interface AgentRunOptions {
     onOutput?: (output: ProcessOutputChunk) => void;
     /** Optional application-owned correlation propagated unchanged to agent lifecycle events. */
     correlation?: AgentRunCorrelation;
+    /**
+     * Optional exact attribution for quota observations (Spur task 0798). Purely
+     * additive metadata: existing callers without it keep byte-identical results,
+     * and missing fields stay absent on emitted observations — never inferred.
+     */
+    quotaContext?: QuotaAttribution;
 }
 
 /** Application-owned execution identity carried without coupling the runner to a workflow model. */
@@ -121,6 +133,8 @@ export class AiRunner {
     private readonly defaultTimeout: number | undefined;
     private readonly logger: Logger;
     private readonly events: EventBus<AgentEvents> | undefined;
+    /** Single producer path for quota events; no-ops when no agent event bus is configured. */
+    private readonly quotaProducer: QuotaObservationProducer;
     /** Internal process-level observability bus, parented to `lifecycleBus` when auto-constructed. Exposed for introspection/testing. */
     readonly processEvents: EventBus<AiRunnerProcessEvents> | undefined;
 
@@ -153,6 +167,7 @@ export class AiRunner {
         this.defaultTimeout = options.defaultTimeout;
         this.logger = options.logger ?? getLogger('ai-runner');
         this.events = events;
+        this.quotaProducer = new QuotaObservationProducer(events);
         this.processEvents = processEvents;
     }
 
@@ -251,6 +266,19 @@ export class AiRunner {
             ...(options.correlation !== undefined ? { correlation: options.correlation } : {}),
             severity: result.exitCode === 0 || result.exitCode === null ? 'info' : 'error',
         });
+        if (result.exitCode !== null && result.exitCode !== 0) {
+            const classification = classifyQuotaErrorRecord(result.stderr);
+            if (classification.quota) {
+                this.quotaProducer.produce(
+                    buildQuotaObservation({
+                        source: 'buffered-error',
+                        reason: classification.reason,
+                        attribution: { agent, ...options.quotaContext },
+                        ...(options.correlation !== undefined ? { correlation: options.correlation } : {}),
+                    }),
+                );
+            }
+        }
         return {
             exitCode: result.exitCode,
             stdout: result.stdout,

package/src/events.ts

@@ -1,6 +1,7 @@
 import type { EventSeverity } from '@gobing-ai/ts-infra';
 import type { ProcessEvents } from '@gobing-ai/ts-runtime';
 import type { AgentRunCorrelation } from './ai-runner';
+import type { AgentQuotaObservation, AgentQuotaRecovery } from './quota';
 
 /** Typed event map for agent-runner observability. All events prefixed `agent.`. */
 export type AgentEvents = {
@@ -34,6 +35,10 @@ export type AgentEvents = {
     'agent.stopped': (data: { agentId: string; exitCode: number | null; severity: EventSeverity }) => void;
     /** Emitted when a message is sent to a team agent process. */
     'agent.message.sent': (data: { agentId: string; ok: boolean; severity: EventSeverity }) => void;
+    /** Emitted once per verified quota-exhaustion observation (confirmed usage-allowance or credit exhaustion). */
+    'agent.quota.exhausted': (data: AgentQuotaObservation) => void;
+    /** Explicit-recovery signal; type contract only — no automatic producer exists upstream. */
+    'agent.quota.recovered': (data: AgentQuotaRecovery) => void;
 };
 
 /** Event map for process-level observability emitted by AiRunner-owned executors. */

package/src/index.ts

@@ -9,6 +9,7 @@ export * from './identity';
 export * from './message-store';
 export * from './messages';
 export * from './model-health-probe';
+export * from './quota';
 export * from './slash-command';
 export * from './team-agent-process';
 export * from './team-orchestrator';

package/src/model-health-probe.ts

@@ -10,7 +10,15 @@
  * issuing a minimal 1-token completion request and interpreting the HTTP
  * response (R3).
  */
-import { APIClient, type APIClientConfig, APIError, type RawHttpResponse } from '@gobing-ai/ts-infra';
+import { APIClient, type APIClientConfig, APIError, type EventBus, type RawHttpResponse } from '@gobing-ai/ts-infra';
+import type { AgentRunCorrelation } from './ai-runner';
+import type { AgentEvents } from './events';
+import {
+    type AgentQuotaObservation,
+    buildQuotaObservation,
+    type QuotaAttribution,
+    QuotaObservationProducer,
+} from './quota';
 
 /** Health status for a single model endpoint. */
 export type ModelHealthStatus = 'available' | 'quota_exhausted' | 'rate_limited' | 'unavailable' | 'unknown';
@@ -239,3 +247,40 @@ export class OmpModelProbe implements ModelHealthProbe {
 
 /** Default probe timeout in milliseconds (R8). */
 export { DEFAULT_PROBE_TIMEOUT_MS };
+
+/** Options for the explicitly opted-in quota health observation. */
+export interface QuotaHealthObservationOptions {
+    /** Agent event bus receiving `agent.quota.exhausted`. */
+    events: EventBus<AgentEvents>;
+    /** Optional exact attribution; absent fields stay absent — never inferred. */
+    attribution?: QuotaAttribution;
+    /** Optional run correlation carried unchanged onto the observation. */
+    correlation?: AgentRunCorrelation;
+    /** Optional shared producer so multiple observations dedupe across one observation session. */
+    producer?: QuotaObservationProducer;
+}
+
+/**
+ * Explicitly opted-in health observation → quota event. The ONLY producer seam
+ * on the health path: ordinary doctor runs never call this, so read-only
+ * behavior is preserved. Returns the emitted observation, or null when the
+ * result is not a confirmed quota exhaustion (rate_limited / unavailable /
+ * unknown never produce events).
+ */
+export function observeQuotaHealthResult(
+    result: ModelHealthResult,
+    options: QuotaHealthObservationOptions,
+): AgentQuotaObservation | null {
+    if (result.status !== 'quota_exhausted') return null;
+    const producer = options.producer ?? new QuotaObservationProducer(options.events);
+    const observation = buildQuotaObservation({
+        source: 'health-probe',
+        reason: 'provider_quota_exhausted',
+        observedAt: new Date(result.checkedAt),
+        ...(result.detail !== undefined ? { detail: result.detail } : {}),
+        attribution: options.attribution,
+        ...(options.correlation !== undefined ? { correlation: options.correlation } : {}),
+    });
+    producer.produce(observation);
+    return observation;
+}

package/src/quota.ts

@@ -0,0 +1,188 @@
+import { createHash } from 'node:crypto';
+import type { EventBus } from '@gobing-ai/ts-infra';
+import type { AgentRunCorrelation } from './ai-runner';
+import type { AgentEvents } from './events';
+
+/**
+ * Canonical quota-exhaustion codes accepted in structured error-record positions
+ * (`error.type` / `error.code`). The set is an exact-match allowlist on purpose:
+ * free text never confirms quota (R2 — Spur task 0798). Generic HTTP 429 without
+ * one of these codes is rate limiting, not quota exhaustion.
+ */
+export type QuotaExhaustionReason =
+    | 'insufficient_quota'
+    | 'insufficient_credit_balance'
+    | 'quota_exceeded'
+    | 'usage_limit_reached'
+    | 'credits_exhausted'
+    | 'billing_hard_limit_reached'
+    /** Verified by the shipped health probe's quota-aware 429 interpretation (`OmpModelProbe`). */
+    | 'provider_quota_exhausted';
+
+/** Where a quota observation was verified. Streaming evidence is a bounded trailing window, never a transcript. */
+export type QuotaEvidenceSource = 'buffered-error' | 'streaming-error' | 'health-probe';
+
+/**
+ * Exact attribution carried on a quota observation. Every field is optional and
+ * only populated from caller-supplied context — the runner never infers project
+ * or executor identity (missing attribution stays observable, not guessed).
+ */
+export interface QuotaAttribution {
+    projectId?: string;
+    executor?: string;
+    agent?: string;
+    model?: string;
+}
+
+/** A verified quota-exhaustion observation. `observationId` is deterministic, so redelivery keeps identity. */
+export interface AgentQuotaObservation {
+    /** Stable across redelivery: digest over evidence source, reason, and attribution identity — never timestamps. */
+    observationId: string;
+    /** UTC ISO-8601 with millisecond precision. */
+    observedAt: string;
+    evidenceSource: QuotaEvidenceSource;
+    reason: QuotaExhaustionReason;
+    /** Sanitized provider detail. Only carried when the source guarantees sanitization (health probe). */
+    detail?: string;
+    /** Exact attribution when supplied by the caller; absent fields mean unknown. */
+    attribution?: QuotaAttribution;
+    correlation?: AgentRunCorrelation;
+}
+
+/** Explicit-recovery payload for `agent.quota.recovered`. Type contract only — no automatic producer, timer, or polling. */
+export interface AgentQuotaRecovery {
+    /** The observationId whose quota state recovered. */
+    observationId: string;
+    /** UTC ISO-8601 with millisecond precision. */
+    recoveredAt: string;
+    attribution?: QuotaAttribution;
+    correlation?: AgentRunCorrelation;
+}
+
+/** Result of classifying one bounded error record. */
+export type QuotaClassification = { quota: true; reason: QuotaExhaustionReason } | { quota: false };
+
+/** Upper bound for error evidence considered by the classifier (bytes, UTF-8). Keeps streaming memory bounded. */
+export const MAX_QUOTA_EVIDENCE_BYTES = 8192;
+
+const QUOTA_CODES: ReadonlySet<string> = new Set([
+    'insufficient_quota',
+    'insufficient_credit_balance',
+    'quota_exceeded',
+    'usage_limit_reached',
+    'credits_exhausted',
+    'billing_hard_limit_reached',
+]);
+
+/**
+ * Classify one error record as quota exhaustion. Accepts only structured
+ * provider error envelopes — a JSON object with an `error` object whose
+ * `type` or `code` exactly matches a canonical quota code. Free text, quoted
+ * prompt content inside `error.message`, plain HTTP 429 rate-limit codes,
+ * throttling/overload, authentication, context/output limits, and timeouts
+ * all classify as negative (R2). Input is bounded to
+ * {@link MAX_QUOTA_EVIDENCE_BYTES} trailing bytes.
+ */
+export function classifyQuotaErrorRecord(record: string): QuotaClassification {
+    const bounded = record.length > MAX_QUOTA_EVIDENCE_BYTES ? record.slice(-MAX_QUOTA_EVIDENCE_BYTES) : record;
+    const envelope = tryParseErrorEnvelope(bounded);
+    if (envelope === null) return { quota: false };
+    const type = typeof envelope.type === 'string' ? envelope.type.toLowerCase() : '';
+    const code = typeof envelope.code === 'string' ? envelope.code.toLowerCase() : '';
+    for (const candidate of [type, code]) {
+        if (QUOTA_CODES.has(candidate)) return { quota: true, reason: candidate as QuotaExhaustionReason };
+    }
+    return { quota: false };
+}
+
+/** Best-effort parse of a JSON provider error envelope (`{ error: { type?, code?, message? } }`). */
+function tryParseErrorEnvelope(record: string): { type?: unknown; code?: unknown } | null {
+    const start = record.indexOf('{');
+    const end = record.lastIndexOf('}');
+    if (start < 0 || end <= start) return null;
+    try {
+        const parsed: unknown = JSON.parse(record.slice(start, end + 1));
+        if (typeof parsed !== 'object' || parsed === null) return null;
+        const error = (parsed as { error?: unknown }).error;
+        if (typeof error !== 'object' || error === null) return null;
+        return error as { type?: unknown; code?: unknown };
+    } catch {
+        return null;
+    }
+}
+
+/** Normalize an observation timestamp to UTC ISO-8601 with millisecond precision. */
+export function normalizeObservedAt(at: Date): string {
+    return at.toISOString();
+}
+
+/** Keep only defined, non-empty attribution fields; return undefined when nothing is known. */
+function cleanAttribution(attribution: QuotaAttribution): QuotaAttribution | undefined {
+    const cleaned: QuotaAttribution = {};
+    if (attribution.projectId) cleaned.projectId = attribution.projectId;
+    if (attribution.executor) cleaned.executor = attribution.executor;
+    if (attribution.agent) cleaned.agent = attribution.agent;
+    if (attribution.model) cleaned.model = attribution.model;
+    return Object.keys(cleaned).length > 0 ? cleaned : undefined;
+}
+
+/**
+ * Build a quota observation. `observationId` is a SHA-256 digest over the
+ * evidence source, reason, and attribution identity — stable across
+ * redelivery because it excludes timestamps, correlation, and free text.
+ */
+export function buildQuotaObservation(params: {
+    source: QuotaEvidenceSource;
+    reason: QuotaExhaustionReason;
+    observedAt?: Date;
+    detail?: string;
+    attribution?: QuotaAttribution;
+    correlation?: AgentRunCorrelation;
+}): AgentQuotaObservation {
+    const attribution = params.attribution === undefined ? undefined : cleanAttribution(params.attribution);
+    const identity = [
+        params.source,
+        params.reason,
+        attribution?.projectId ?? '',
+        attribution?.executor ?? '',
+        attribution?.agent ?? '',
+        attribution?.model ?? '',
+    ].join('\0');
+    const observationId = `qo-${createHash('sha256').update(identity).digest('hex').slice(0, 24)}`;
+    return {
+        observationId,
+        observedAt: normalizeObservedAt(params.observedAt ?? new Date()),
+        evidenceSource: params.source,
+        reason: params.reason,
+        ...(params.detail !== undefined && params.detail !== '' ? { detail: params.detail } : {}),
+        ...(attribution !== undefined ? { attribution } : {}),
+        ...(params.correlation !== undefined ? { correlation: params.correlation } : {}),
+    };
+}
+
+/**
+ * Single producer path for quota events. Emits `agent.quota.exhausted` at most
+ * once per observationId per producer instance (redelivery of the same quota
+ * fact is suppressed). Recovery delivery is explicit-only — callers own
+ * recovery detection; this class never schedules, polls, or times anything.
+ */
+export class QuotaObservationProducer {
+    private readonly emitted = new Set<string>();
+
+    constructor(private readonly events: EventBus<AgentEvents> | undefined) {}
+
+    /** Emit one `agent.quota.exhausted`. Returns true when emitted, false when deduped or bus-less. */
+    produce(observation: AgentQuotaObservation): boolean {
+        if (this.events === undefined || this.emitted.has(observation.observationId)) return false;
+        this.emitted.add(observation.observationId);
+        void this.events.emit('agent.quota.exhausted', observation);
+        return true;
+    }
+
+    /** Deliver an explicit `agent.quota.recovered`. Returns true when emitted, false when bus-less. */
+    produceRecovery(recovery: AgentQuotaRecovery): boolean {
+        if (this.events === undefined) return false;
+        void this.events.emit('agent.quota.recovered', recovery);
+        return true;
+    }
+}

package/src/team-agent-process.ts

@@ -1,7 +1,15 @@
 import { Buffer } from 'node:buffer';
-import { getLogger, type Logger } from '@gobing-ai/ts-infra';
+import { type EventBus, getLogger, type Logger } from '@gobing-ai/ts-infra';
 import { nodeBunFactory, type PipeProcess, type ProcessExecutor } from '@gobing-ai/ts-runtime';
 import type { AgentSpec } from './agent-spec';
+import type { AgentEvents } from './events';
+import {
+    buildQuotaObservation,
+    classifyQuotaErrorRecord,
+    MAX_QUOTA_EVIDENCE_BYTES,
+    type QuotaAttribution,
+    QuotaObservationProducer,
+} from './quota';
 
 /** Options for spawning a team agent subprocess. */
 export interface AgentProcessOptions {
@@ -11,6 +19,10 @@ export interface AgentProcessOptions {
     cwd?: string;
     processExecutor?: ProcessExecutor;
     logger?: Logger;
+    /** Optional agent event bus; when present, confirmed quota failures emit `agent.quota.exhausted` (Spur task 0798). */
+    events?: EventBus<AgentEvents>;
+    /** Optional exact quota attribution; absent fields stay absent on observations — never inferred. */
+    quotaContext?: QuotaAttribution;
 }
 
 type ProcessStatus = 'running' | 'stopped' | 'errored';
@@ -30,6 +42,11 @@ export class TeamAgentProcess {
     private status: ProcessStatus = 'stopped';
     private exitCode: number | null = null;
     private readonly subscribers = new Set<(data: Buffer) => void>();
+    /** Bounded trailing stderr window retained for quota classification — never a full transcript. */
+    private stderrTail = '';
+    private readonly quotaProducer: QuotaObservationProducer;
+    private readonly spec: AgentSpec;
+    private readonly quotaContext: QuotaAttribution | undefined;
 
     constructor(options: AgentProcessOptions) {
         this.agentId = options.spec.id;
@@ -38,6 +55,9 @@ export class TeamAgentProcess {
         this.cwd = options.cwd ?? options.spec.workspace;
         this.processExecutor = options.processExecutor ?? nodeBunFactory.createProcessExecutor();
         this.logger = options.logger ?? getLogger('team-agent');
+        this.quotaProducer = new QuotaObservationProducer(options.events);
+        this.spec = options.spec;
+        this.quotaContext = options.quotaContext;
     }
 
     async start(): Promise<void> {
@@ -53,11 +73,15 @@ export class TeamAgentProcess {
         });
         this.status = 'running';
         this.exitCode = null;
-        if (this.subprocess.stdout !== null) this.pipe(this.subprocess.stdout);
-        if (this.subprocess.stderr !== null) this.pipe(this.subprocess.stderr);
+        this.stderrTail = '';
+        if (this.subprocess.stdout !== null) this.pipe(this.subprocess.stdout, false);
+        if (this.subprocess.stderr !== null) this.pipe(this.subprocess.stderr, true);
         void this.subprocess.exited.then((code) => {
             this.exitCode = code;
-            if (this.status === 'running') this.status = code === 0 ? 'stopped' : 'errored';
+            if (this.status === 'running') {
+                this.status = code === 0 ? 'stopped' : 'errored';
+                if (this.status === 'errored') this.classifyQuota();
+            }
         });
     }
 
@@ -121,13 +145,14 @@ export class TeamAgentProcess {
         return this.exitCode;
     }
 
-    private async pipe(stream: ReadableStream<Uint8Array>): Promise<void> {
+    private async pipe(stream: ReadableStream<Uint8Array>, isStderr: boolean): Promise<void> {
         const reader = stream.getReader();
         try {
             while (true) {
                 const chunk = await reader.read();
                 if (chunk.done) break;
                 const buffer = Buffer.from(chunk.value);
+                if (isStderr) this.retainStderrTail(buffer.toString('utf8'));
                 for (const subscriber of this.subscribers) subscriber(buffer);
             }
         } catch (error) {
@@ -138,6 +163,28 @@ export class TeamAgentProcess {
         }
     }
 
+    /** Keep only the trailing {@link MAX_QUOTA_EVIDENCE_BYTES} of stderr; subscribers still see every chunk unchanged. */
+    private retainStderrTail(text: string): void {
+        this.stderrTail = (this.stderrTail + text).slice(-MAX_QUOTA_EVIDENCE_BYTES);
+    }
+
+    /** Classify the retained stderr window and emit one attributed quota observation on confirmation. */
+    private classifyQuota(): void {
+        const classification = classifyQuotaErrorRecord(this.stderrTail);
+        if (!classification.quota) return;
+        this.quotaProducer.produce(
+            buildQuotaObservation({
+                source: 'streaming-error',
+                reason: classification.reason,
+                attribution: {
+                    ...this.quotaContext,
+                    agent: this.quotaContext?.agent ?? this.spec.id,
+                    executor: this.quotaContext?.executor ?? this.spec.executor ?? this.spec.type,
+                },
+            }),
+        );
+    }
+
     private warn(message: string, op: string, error?: unknown): void {
         this.logger.warn(message, {
             agentId: this.agentId,