agent-relay-server 0.121.4 → 0.122.0

package/src/db/messages.ts

@@ -1,6 +1,15 @@
 import { Database } from "bun:sqlite";
 import { randomUUID } from "node:crypto";
-import { isRecord, stringValue, isMechanicalMessageKind, isReportVerbosity, type ReportVerbosity } from "agent-relay-sdk";
+import {
+  isRecord,
+  isTurnFinalSession,
+  stringValue,
+  isMechanicalMessageKind,
+  isReportVerbosity,
+  type MessagePayload,
+  type MessageWorkFinality,
+  type ReportVerbosity,
+} from "agent-relay-sdk";
 import { LIFECYCLE_STATE_WORKING, childSignalKey, stampLifecycleSignal, taskSignalKey } from "../lifecycle-signal-registry";
 import { ORCHESTRATOR_PROTOCOL_VERSION, VERSION } from "../config.ts";
 import { parseJson } from "../utils";
@@ -108,6 +117,19 @@ function sessionStepId(payload: Record<string, unknown> | undefined): string | u
   return stringValue(session?.stepId);
 }
 
+function normalizeMessagePayload(payload: MessagePayload | undefined): MessagePayload {
+  const original = payload ?? {};
+  let next: MessagePayload = original;
+  for (const key of ["session", "responseCapture"] as const) {
+    const value = next[key];
+    if (!isTurnFinalSession(value)) continue;
+    if (value.turnFinal === true && value.final === true) continue;
+    if (next === original) next = { ...original };
+    next[key] = { ...value, turnFinal: true, final: true };
+  }
+  return next;
+}
+
 /**
  * Codex session-mirror upsert (#parity): a provider step that emits more than once — a
  * tool's running→completed lifecycle, a reasoning/response row that streams — carries a
@@ -200,7 +222,7 @@ function responseCaptureMeta(input: Message | SendMessageInput): Record<string,
 }
 
 function isFinalSessionResponse(session: Record<string, unknown>): boolean {
-  return session.type === "response" && session.final === true;
+  return session.type === "response" && isTurnFinalSession(session);
 }
 
 function childStreamForSession(session: Record<string, unknown>): ChildStream | null {
@@ -373,14 +395,19 @@ function childIsBusy(child: AgentCard): boolean {
 // narration flood by the legacy tail budget, never slicing the block we keep.
 const REPORT_UP_DISTILL_THRESHOLD = 800;
 const REPORT_UP_TAIL_MAX = 800;
-const REPORT_UP_ELISION = "[…mid-work narration trimmed by report-up…]";
+// #1058 — distillation only ever runs on a FINAL turn (promoteLineageCapturedResponse gates on
+// isFinalSessionResponse), so the old "[…mid-work narration trimmed…]" label was a lie: it read as
+// if the real report were still coming when THIS is the deliverable. The elision marks that only the
+// LEADING narration was dropped, states plainly that this is the final report, and points at the
+// untrimmed turn via relay_get_message so the coordinator never has to guess whether the child is done.
+const reportUpElision = (messageId: number): string => `[…leading narration trimmed by report-up — this IS the final report; full turn: relay_get_message #${messageId}…]`;
 const REPORT_UP_HEADING = /^#{1,6}\s/m;
 
-function distillLineageReportBody(body: string): string {
+function distillLineageReportBody(body: string, messageId: number): string {
   const trimmed = body.trim();
   if (trimmed.length <= REPORT_UP_DISTILL_THRESHOLD) return body;
   const heading = REPORT_UP_HEADING.exec(trimmed);
-  if (heading) return heading.index === 0 ? body : `${REPORT_UP_ELISION}\n\n${trimmed.slice(heading.index).trim()}`;
+  if (heading) return heading.index === 0 ? body : `${reportUpElision(messageId)}\n\n${trimmed.slice(heading.index).trim()}`;
   const blocks = trimmed.split(/\n{2,}/).map((block) => block.trim()).filter(Boolean);
   const kept: string[] = [];
   let size = 0;
@@ -394,7 +421,7 @@ function distillLineageReportBody(body: string): string {
   // A single oversized trailing block (unsegmented narration) — hard-cap to its own tail.
   if (tail.length > REPORT_UP_TAIL_MAX) tail = tail.slice(tail.length - REPORT_UP_TAIL_MAX).replace(/^\S*\s/, "").trimStart();
   if (tail.length >= trimmed.length) return body; // nothing meaningful trimmed
-  return `${REPORT_UP_ELISION}\n\n${tail}`;
+  return `${reportUpElision(messageId)}\n\n${tail}`;
 }
 
 // #1037 — a quiet child's turn-final response that arrives while the child is still busy is a
@@ -451,7 +478,10 @@ export function listRecentFinalResponseCaptures(sinceMs: number, limit = 1000):
       WHERE kind = 'session'
         AND created_at >= ?
         AND json_extract(payload, '$.session.type') = 'response'
-        AND json_extract(payload, '$.session.final') = 1
+        AND (
+          json_extract(payload, '$.session.turnFinal') = 1
+          OR json_extract(payload, '$.session.final') = 1
+        )
       GROUP BY from_agent
     ) latest ON latest.latest_id = m.id
     ORDER BY m.id DESC
@@ -545,7 +575,7 @@ export function promoteLineageCapturedResponse(message: Message): { message: Mes
     kind: "chat",
     // #1037 — distill the turn-final report-up to a concise result; verbose child-stream captures
     // (an explicit subscriber that asked for the raw stream) are forwarded untouched.
-    body: stream === "responses" ? distillLineageReportBody(message.body) : message.body,
+    body: stream === "responses" ? distillLineageReportBody(message.body, message.id) : message.body,
     replyExpected: false,
     idempotencyKey,
     payload: stream === "responses"
@@ -560,6 +590,14 @@ export function promoteLineageCapturedResponse(message: Message): { message: Mes
   return result;
 }
 
+export function setMessageWorkFinality(messageId: number, finality: MessageWorkFinality): Message | null {
+  const message = getMessage(messageId);
+  if (!message) return null;
+  const payload: MessagePayload = { ...(message.payload ?? {}), finality };
+  getDb().query("UPDATE messages SET payload = ? WHERE id = ?").run(JSON.stringify(payload), messageId);
+  return getMessage(messageId);
+}
+
 // Event time may be queued-then-backfilled, so it can legitimately be older than the
 // receive time — but it must be a sane epoch-ms value. Returns null (column stays NULL, so
 // readers fall back to created_at) for absent/invalid values or anything more than a minute
@@ -586,7 +624,8 @@ export function sendMessagesBatchWithResult(inputs: SendMessageInput[]): SendMes
 
 function sendMessageWithResultInternal(input: SendMessageInput, wrapTransaction: boolean): SendMessageResult {
   const now = Date.now();
-  const payload = input.payload ?? {};
+  const payload = normalizeMessagePayload(input.payload);
+  input.payload = payload;
   const attachmentRefs = cleanAttachmentRefs(payload);
 
   if (!getAgent(input.from)) {

package/src/db/migrations.ts

@@ -148,6 +148,54 @@ function backfillProjectRootRemoteUrls(): void {
   }
 }
 
+function dualStampLegacyTurnFinality(): void {
+  const messagesTable = getDb().query("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'messages'").get();
+  if (!messagesTable) return;
+  const messageCols = getDb().query("PRAGMA table_info(messages)").all() as Array<{ name: string }>;
+  const messageColNames = new Set(messageCols.map((col) => col.name));
+  if (!messageColNames.has("payload") || !messageColNames.has("created_at")) return;
+  getDb().run(`
+    UPDATE messages
+    SET payload = json_set(
+      payload,
+      '$.finality',
+      json_object(
+        'windowId', 'legacy:' || id,
+        'source', 'edge-fallback',
+        'groupOrder', 0,
+        'markedAt', coalesce(occurred_at, created_at)
+      )
+    )
+    WHERE kind = 'session'
+      AND json_extract(payload, '$.session.final') = 1
+      AND json_type(payload, '$.session.turnFinal') IS NULL
+      AND json_type(payload, '$.finality') IS NULL
+  `);
+  getDb().run(`
+    UPDATE messages
+    SET payload = json_set(payload, '$.session.turnFinal', json('true'))
+    WHERE json_extract(payload, '$.session.final') = 1
+      AND json_type(payload, '$.session.turnFinal') IS NULL
+  `);
+  getDb().run(`
+    UPDATE messages
+    SET payload = json_set(payload, '$.session.final', json('true'))
+    WHERE json_extract(payload, '$.session.turnFinal') = 1
+      AND json_type(payload, '$.session.final') IS NULL
+  `);
+  getDb().run(`
+    UPDATE messages
+    SET payload = json_set(payload, '$.responseCapture.turnFinal', json('true'))
+    WHERE json_extract(payload, '$.responseCapture.final') = 1
+      AND json_type(payload, '$.responseCapture.turnFinal') IS NULL
+  `);
+  getDb().run(`
+    UPDATE messages
+    SET payload = json_set(payload, '$.responseCapture.final', json('true'))
+    WHERE json_extract(payload, '$.responseCapture.turnFinal') = 1
+      AND json_type(payload, '$.responseCapture.final') IS NULL
+  `);
+}
 
 // Incremental schema migrations + one-shot backfills, applied after the base DDL
 // in initDb(). Ordering matters: each block guards on the current column/table
@@ -280,6 +328,7 @@ export function applyMigrations(): void {
   if (!colNames.includes("occurred_at")) {
     getDb().run("ALTER TABLE messages ADD COLUMN occurred_at INTEGER");
   }
+  dualStampLegacyTurnFinality();
   getDb().query(
     "UPDATE messages SET claim_expires_at = coalesce(claimed_at, ?) + ? WHERE claimed_by IS NOT NULL AND claim_expires_at IS NULL",
   ).run(Date.now(), CLAIM_LEASE_MS);
@@ -822,6 +871,11 @@ export function applyMigrations(): void {
   if (!providerQuotaCols.includes("quota_advisory_state")) {
     getDb().run("ALTER TABLE provider_quotas ADD COLUMN quota_advisory_state TEXT NOT NULL DEFAULT '{}'");
   }
+  // #1074 — persist quota-band hysteresis state so a relay restart doesn't re-fire already-sent
+  // band-degradation notifications to the whole fleet.
+  if (!providerQuotaCols.includes("quota_band_state")) {
+    getDb().run("ALTER TABLE provider_quotas ADD COLUMN quota_band_state TEXT NOT NULL DEFAULT '{}'");
+  }
   getDb().run(`
     INSERT INTO provider_quotas (
       provider, account_key, quota_state, source_agent_ids, last_updated_at,

package/src/db/provider-quota-burn.ts

@@ -1,28 +1,38 @@
-import { DEFAULT_QUOTA_TARGET_UTILIZATION, quotaPaceMetrics, quotaWindowMetrics } from "agent-relay-sdk/provider-quota";
+import { DEFAULT_QUOTA_TARGET_UTILIZATION, quotaPaceMetrics, quotaTrendProjection, quotaWindowMetrics } from "agent-relay-sdk/provider-quota";
 import type { ProviderQuotaBurn, ProviderQuotaBurnRole, ProviderQuotaBurnWindow, ProviderQuotaSnapshot, QuotaState } from "../types";
 
 const QUOTA_BURN_MIN_SAMPLE_SPAN_MS = 10 * 60_000;
 
-// #760 — nominal window length per role, used to scale the recency half-life.
+// #760 — nominal window length per role. windowStartAt = resetAt − this, and it scales the
+// evidence-confidence horizon below.
 const WINDOW_NOMINAL_MS: Record<ProviderQuotaBurnRole, number> = {
   "5h": 5 * 3_600_000,
   "7d": 7 * 24 * 3_600_000,
 };
 
-// #760 — recency half-life as a fraction of the window length. 0.25 → ~75min for the 5h
-// window (within the issue's ~60–90min trailing-window guidance) and ~42h for the 7d window.
-// A burst at the START of the history span decays out as it ages, so an idle stretch pulls the
-// observed rate (and burnRatio) back toward 0 instead of freezing the endpoint slope.
-const RECENCY_HALFLIFE_FRACTION = 0.25;
-
-// #798 — idle de-bias: once a provider's utilization has held flat for this long, any residual
-// forward-burn rate is a stale-burst artifact (the recency half-life decays it, but for the 7d
-// window — half-life ~42h — far too slowly: codex idle ~24h still projected ~1.07 at reset,
-// walking the band boundary tick-to-tick). When idle this long the forward-burn term is collapsed
-// so projectedUtilAtReset → current utilization. The threshold is absolute (NOT window-scaled): a
-// 5h window resets long before reaching it, so this only de-biases the slow-decaying 7d window;
-// shorter idle stretches keep the graceful #760 recency decay. The over-target avoid is preserved
-// by the position penalty in spawn-targets (a stable, position-based floor), not by this rate.
+// #1072 — SLOW EWMA time constant (dt-correct). This is the sustained-trend requirement made
+// mechanical: a 15-min onset burst barely moves a 24h-τ average, so a transient spawn-burst spike
+// cannot flip the band — only a trend that holds for hours does. Drives the band projection.
+const EWMA_TAU_SLOW_MS: Record<ProviderQuotaBurnRole, number> = {
+  "5h": 2 * 3_600_000,
+  "7d": 24 * 3_600_000,
+};
+
+// #1072 — continuous trend confidence reaches 1 once the observed span covers this horizon (the
+// slow-EWMA τ). A fresh window (tiny observed span) ⇒ ~0 confidence ⇒ the projected (not the
+// measured) overshoot cannot hard-escalate the band; by the time the span covers τ, a sustained
+// trend is real. Absorbs the #1073 confidence-gate stopgap into the model.
+const CONFIDENCE_FULL_EVIDENCE_MS: Record<ProviderQuotaBurnRole, number> = {
+  "5h": 2 * 3_600_000,
+  "7d": 24 * 3_600_000,
+};
+
+// #798 — idle collapse, retained for STABILITY (not for the penalty). Once utilization has held
+// flat for this long, the residual slow-EWMA rate is a stale-burst tail: the slow average decays
+// but never reaches exactly 0 in finite time, so a small rate × a multi-day horizon would still
+// creep the projection tick-to-tick (the band walk from #798). Pinning the rate to 0 once idle
+// this long fixes the projection at current utilization so the band is flat across ticks. The
+// threshold is absolute (a 5h window resets long before reaching it, so this only affects 7d).
 const IDLE_FORWARD_COLLAPSE_MS = 6 * 3_600_000;
 const IDLE_UTILIZATION_EPSILON = 1e-9;
 
@@ -63,32 +73,38 @@ function lowConfidenceBurnWindow(role: ProviderQuotaBurnRole, window: QuotaWindo
     projectedUtilAtReset: null,
     slack: null,
     target: null,
+    confidenceScore: null,
   };
 }
 
-// #760 — recency-weighted consumption rate (utilization-fraction per ms). A weighted slope:
-// each consecutive interval contributes its actual Δutilization and Δt, decayed by the age of
-// its midpoint with the given half-life. A recent idle interval (large Δt, ~0 Δutil, high
-// weight) dominates the denominator and drives the rate toward 0; an old burst is down-weighted.
-function recencyWeightedRatePerMs(
+// #1072 — dt-correct EWMA of the consumption rate (utilization-fraction per ms). Each consecutive
+// interval contributes its mean rate Δutil/Δt, held constant over Δt and decayed by exp(−Δt/τ), so
+// a long idle interval (Δt≫τ, rate ~0) drives the average toward 0 while a short burst barely
+// moves a long-τ average. The EWMA is SEEDED AT 0 (not at the first interval's raw slope) so a
+// sustained trend is required to build the rate up — a single onset interval can never set the
+// full slope. Interval rates are clamped ≥0 (a within-window utilization drop is treated as no
+// consumption, not negative burn).
+function ewmaRatePerMs(
   samples: Array<{ capturedAt: number; utilization: number }>,
   now: number,
-  halfLifeMs: number,
+  tauMs: number,
 ): number {
-  let weightedDelta = 0;
-  let weightedDt = 0;
+  let r = 0;
   for (let i = 1; i < samples.length; i++) {
-    const prev = samples[i - 1]!;
-    const cur = samples[i]!;
-    const dt = cur.capturedAt - prev.capturedAt;
+    const dt = samples[i]!.capturedAt - samples[i - 1]!.capturedAt;
     if (dt <= 0) continue;
-    const midAge = Math.max(0, now - (prev.capturedAt + cur.capturedAt) / 2);
-    const weight = Math.pow(0.5, midAge / halfLifeMs);
-    weightedDelta += weight * (cur.utilization - prev.utilization);
-    weightedDt += weight * dt;
+    const rate = Math.max(0, (samples[i]!.utilization - samples[i - 1]!.utilization) / dt);
+    const decay = Math.exp(-dt / tauMs);
+    r = decay * r + (1 - decay) * rate;
+  }
+  // Idle observability: extend to `now` with a zero-rate interval so a deduped idle stretch (no new
+  // distinct samples arrive while utilization holds) still decays the average instead of freezing
+  // the last observed slope — the same synthetic-tail trick #760 used, applied to the EWMA.
+  const last = samples[samples.length - 1];
+  if (last && now > last.capturedAt) {
+    r *= Math.exp(-(now - last.capturedAt) / tauMs);
   }
-  if (weightedDt <= 0) return 0;
-  return Math.max(0, weightedDelta / weightedDt);
+  return Math.max(0, r);
 }
 
 // #798 — when did utilization last differ from its current value? Scanning back from the newest
@@ -148,62 +164,75 @@ function deriveProviderQuotaBurnWindow(input: {
   const timeToResetMs = resetAt - input.now;
   if (remainingQuota <= 0 || timeToResetMs <= 0) return low;
 
-  // #760 (Defect 1) — recency-weighted rate so an old burst decays and idle relaxes toward 0,
-  // instead of a frozen two-point endpoint slope over the whole span.
-  //
-  // Idle is invisible in the raw samples: identical utilization snapshots are deduped, so during
-  // an idle stretch no new rows arrive and the latest sample stays frozen at the last CHANGE
-  // (this is why codex sat at burn×6.3 — a stale burst slope). We make idle observable by
-  // appending a synthetic "utilization is still X as of now" point, which adds a recent
-  // zero-delta interval [lastSample, now] that the recency weighting lets dominate as it grows.
-  const halfLifeMs = WINDOW_NOMINAL_MS[role] * RECENCY_HALFLIFE_FRACTION;
-  const rateSamples = input.now > current.capturedAt
-    ? [...samples, { capturedAt: input.now, utilization: utilizationNow }]
-    : samples;
-  const observedRatePerMs = recencyWeightedRatePerMs(rateSamples, input.now, halfLifeMs);
-  // #798 — idle de-bias: if utilization has held flat (no change vs. now) for IDLE_FORWARD_COLLAPSE_MS,
-  // treat the forward-burn term as a stale-burst artifact and collapse it to 0 so the projection
-  // pins to current utilization instead of walking the band boundary. lastChangeAt is the moment
-  // utilization last differed from the current value (the synthetic "still X as of now" interval is
-  // what makes a deduped idle stretch observable here).
+  // #1072 — the SLOW EWMA is the burn rate: a sustained trend is required by construction, so a
+  // transient onset burst (100% of a young window's evidence) can't drive the band. The EWMA walks
+  // the real sample timeline and extends a zero-rate tail to `now`, so a deduped idle stretch
+  // decays the rate instead of freezing the last observed slope (the #760 burn×6.3 stale-slope bug).
+  const rSlow = ewmaRatePerMs(samples, input.now, EWMA_TAU_SLOW_MS[role]);
+  // #798 idle collapse (stability only): once utilization has held flat ≥ IDLE_FORWARD_COLLAPSE_MS
+  // the residual slow rate is a stale-burst tail — pin it to 0 so the projection == current
+  // utilization and stays flat tick-to-tick (no band walk). lastChangeAt is when utilization last
+  // differed from the current value.
   const lastChangeAt = lastUtilizationChangeAt(samples, utilizationNow);
-  const effectiveRate = input.now - lastChangeAt >= IDLE_FORWARD_COLLAPSE_MS ? 0 : observedRatePerMs;
-  // #760 (Defect 2) — pace against a configurable target (<100%); slack carries the underburn
-  // signal. The query layer (spawn-targets) may re-derive these against a per-provider target;
-  // the ingest-time values use the default so direct burn consumers (dashboard) have a number.
+  const bandRate = input.now - lastChangeAt >= IDLE_FORWARD_COLLAPSE_MS ? 0 : rSlow;
+
+  // #1072 — evidence span and continuous trend confidence. evidenceMs is how long we've actually
+  // observed this window instance (bounded by both the window's own start and our first sample);
+  // it caps the projection horizon and drives the confidence that gates hard-escalation.
+  const windowStartAt = resetAt - WINDOW_NOMINAL_MS[role];
+  const evidenceMs = Math.max(0, input.now - Math.max(windowStartAt, oldest.capturedAt));
+  const confidence = Math.max(0, Math.min(1, evidenceMs / CONFIDENCE_FULL_EVIDENCE_MS[role]));
+
+  // #1072 — evidence-capped band projection off the slow rate. The query layer (spawn-targets)
+  // re-derives slack/penalty against the per-provider target from this (target-independent)
+  // projection + confidenceScore; the ingest-time values use the default target so direct burn
+  // consumers (dashboard) have a number.
+  const trend = quotaTrendProjection({
+    utilization: utilizationNow,
+    slowRatePerMs: bandRate,
+    timeToResetMs,
+    evidenceMs,
+    confidence,
+    target: DEFAULT_QUOTA_TARGET_UTILIZATION,
+  });
+  // burnRatio (display) paces the same slow rate against the target, so the widget's burn number
+  // and the routing band always agree — a bursty spike shows in the raw sparkline, not here.
   const pace = quotaPaceMetrics({
     utilization: utilizationNow,
-    observedRatePerMs: effectiveRate,
+    observedRatePerMs: bandRate,
     timeToResetMs,
     target: DEFAULT_QUOTA_TARGET_UTILIZATION,
   });
-  if (effectiveRate <= 0) {
-    // Idle (decayed-to-idle, or #798 idle-collapsed): no projected wall, but slack still flags the
-    // headroom (positive = underburn) or, when over target, the position the band-floor avoids.
+  if (bandRate <= 0) {
+    // Idle (flat, decayed-to-idle, or #798 idle-collapsed): no projected wall, but the projection
+    // still pins to current utilization and slack flags headroom (positive) or the over-target
+    // position the penalty avoids (negative).
     return {
       ...low,
       confidence: "high",
       burnRatio: 0,
       observedRatePerMs: 0,
-      projectedUtilAtReset: pace.projectedUtilAtReset,
-      slack: pace.slack,
-      target: pace.target,
+      projectedUtilAtReset: trend.projectedUtilAtReset,
+      slack: trend.slack,
+      target: trend.target,
+      confidenceScore: confidence,
     };
   }
-  const timeToWallMs = remainingQuota / effectiveRate;
+  const timeToWallMs = remainingQuota / bandRate;
   const projectedWallAt = input.now + timeToWallMs;
   return {
     ...low,
     confidence: "high",
     burnRatio: pace.burnRatio,
-    observedRatePerMs: effectiveRate,
+    observedRatePerMs: bandRate,
     timeToWallMs,
     projectedWallAt,
     // #760 (Defect 2) — symmetric: negative means the wall lands AFTER reset (headroom left).
     earlyWallMs: resetAt - projectedWallAt,
-    projectedUtilAtReset: pace.projectedUtilAtReset,
-    slack: pace.slack,
-    target: pace.target,
+    projectedUtilAtReset: trend.projectedUtilAtReset,
+    slack: trend.slack,
+    target: trend.target,
+    confidenceScore: confidence,
   };
 }
 

package/src/db/provider-quotas.ts

@@ -26,12 +26,22 @@ export interface ProviderQuotaAdvisoryInput {
   quota: QuotaState;
   sourceAgentIds: string[];
   previousAdvisoryState?: string | null;
+  // #1074 — serialized quota-band hysteresis state (quota_band_state column). Threaded in so the
+  // band-transition pipeline hydrates instead of re-seeding to "normal" on every relay restart.
+  previousBandState?: string | null;
   now: number;
 }
 
-let providerQuotaAdvisoryHandler: ((input: ProviderQuotaAdvisoryInput) => string) | undefined;
+// #1074 — the handler returns BOTH persisted blobs: the utilization advisory state and the
+// band-transition hysteresis state. Both are written back to their respective columns.
+export interface ProviderQuotaAdvisoryResult {
+  advisoryState: string;
+  bandState: string;
+}
+
+let providerQuotaAdvisoryHandler: ((input: ProviderQuotaAdvisoryInput) => ProviderQuotaAdvisoryResult) | undefined;
 
-export function setProviderQuotaAdvisoryHandler(handler: ((input: ProviderQuotaAdvisoryInput) => string) | undefined): void {
+export function setProviderQuotaAdvisoryHandler(handler: ((input: ProviderQuotaAdvisoryInput) => ProviderQuotaAdvisoryResult) | undefined): void {
   providerQuotaAdvisoryHandler = handler;
 }
 
@@ -42,6 +52,7 @@ type ProviderQuotaRow = {
   codex_reset_credits?: string | null;
   source_agent_ids?: string | null;
   quota_advisory_state?: string | null;
+  quota_band_state?: string | null;
   last_updated_at?: number | null;
   last_attempt_at: number;
   last_error?: string | null;
@@ -182,6 +193,13 @@ function newestQuotaAdvisoryState(rows: ProviderQuotaRow[]): string {
   return row?.quota_advisory_state ?? "{}";
 }
 
+function newestQuotaBandState(rows: ProviderQuotaRow[]): string {
+  const row = rows
+    .filter((candidate) => candidate.quota_band_state)
+    .sort((a, b) => b.updated_at - a.updated_at)[0];
+  return row?.quota_band_state ?? "{}";
+}
+
 function mergeProviderQuotaRows(provider: string, accountKey: string, oldAccountKeys: string[], now: number): number {
   const keys = [...new Set(oldAccountKeys.filter((key) => key && key !== accountKey))];
   if (keys.length === 0) return 0;
@@ -203,9 +221,9 @@ function mergeProviderQuotaRows(provider: string, accountKey: string, oldAccount
   getDb().query(`
     INSERT INTO provider_quotas (
       provider, account_key, quota_state, codex_reset_credits, source_agent_ids, last_updated_at,
-      last_attempt_at, last_error, quota_advisory_state, updated_at, created_at
+      last_attempt_at, last_error, quota_advisory_state, quota_band_state, updated_at, created_at
     )
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     ON CONFLICT(provider, account_key) DO UPDATE SET
       quota_state = excluded.quota_state,
       codex_reset_credits = excluded.codex_reset_credits,
@@ -214,6 +232,7 @@ function mergeProviderQuotaRows(provider: string, accountKey: string, oldAccount
       last_attempt_at = excluded.last_attempt_at,
       last_error = excluded.last_error,
       quota_advisory_state = excluded.quota_advisory_state,
+      quota_band_state = excluded.quota_band_state,
       updated_at = excluded.updated_at
   `).run(
     provider,
@@ -225,6 +244,7 @@ function mergeProviderQuotaRows(provider: string, accountKey: string, oldAccount
     lastAttemptAt || now,
     newestLastError(rows),
     newestQuotaAdvisoryState(rows),
+    newestQuotaBandState(rows),
     updatedAt,
     createdAt,
   );
@@ -552,17 +572,19 @@ export function upsertProviderQuota(input: ProviderQuotaUpdateInput, now = Date.
     recordProviderQuotaUnavailable({ provider, accountKey, error: input.lastError, sourceAgentId: input.sourceAgentId }, now);
   }
   if (hasFreshSuccessfulProviderQuota(input, now) && mergedQuota?.acceptedIncomingWindow) {
-    const quotaAdvisoryState = providerQuotaAdvisoryHandler?.({
+    const advisoryResult = providerQuotaAdvisoryHandler?.({
       provider,
       accountKey,
       previousQuota: existingQuota ? publicQuotaState(existingQuota) : undefined,
       quota: publicQuotaState(mergedQuota.quota),
       sourceAgentIds,
       previousAdvisoryState: existing?.quota_advisory_state,
+      previousBandState: existing?.quota_band_state,
       now,
     });
-    if (quotaAdvisoryState !== undefined) {
-      getDb().query("UPDATE provider_quotas SET quota_advisory_state = ? WHERE provider = ? AND account_key = ?").run(quotaAdvisoryState, provider, accountKey);
+    if (advisoryResult !== undefined) {
+      getDb().query("UPDATE provider_quotas SET quota_advisory_state = ?, quota_band_state = ? WHERE provider = ? AND account_key = ?")
+        .run(advisoryResult.advisoryState, advisoryResult.bandState, provider, accountKey);
     }
   }
   if (!unstableProviderQuotaAccountKey(accountKey)) {

package/src/db/scheduled-timers.ts

@@ -185,6 +185,27 @@ export function countActiveScheduledTimers(createdBy: string): number {
   return row.count;
 }
 
+// #1004 — a command timer whose background command is still pending/running is active work
+// executing on the creator's behalf (a shell command on an orchestrator), even though its
+// provider turn already ended and reports idle. A prompt-wakeup timer (no command) is just a
+// future alarm and never counts. These back the running-command → busy DISPLAY derivation; the
+// timer/command row is the source of truth, so the signal self-heals when the command settles.
+const RUNNING_COMMAND_TIMER_PREDICATE =
+  "enabled = 1 AND command IS NOT NULL AND json_extract(command, '$.status') IN ('pending', 'running')";
+
+export function agentHasRunningCommandTimer(createdBy: string): boolean {
+  return getDb()
+    .query(`SELECT 1 FROM scheduled_timers WHERE created_by = ? AND ${RUNNING_COMMAND_TIMER_PREDICATE} LIMIT 1`)
+    .get(createdBy) != null;
+}
+
+export function agentsWithRunningCommandTimers(): Set<string> {
+  const rows = getDb()
+    .query(`SELECT DISTINCT created_by FROM scheduled_timers WHERE ${RUNNING_COMMAND_TIMER_PREDICATE}`)
+    .all() as Array<{ created_by: string }>;
+  return new Set(rows.map((row) => row.created_by));
+}
+
 export function listDueScheduledTimerIds(now: number, limit = 25): string[] {
   const rows = getDb().query(`
     SELECT id FROM scheduled_timers

package/src/db/schema.ts

@@ -366,6 +366,7 @@ export function initDb(path: string = "agent-relay.db"): Database {
       codex_reset_credits TEXT,
       source_agent_ids TEXT NOT NULL DEFAULT '[]',
       quota_advisory_state TEXT NOT NULL DEFAULT '{}',
+      quota_band_state TEXT NOT NULL DEFAULT '{}',
       last_updated_at INTEGER,
       last_attempt_at INTEGER NOT NULL,
       last_error TEXT,

package/src/db/tasks.ts

@@ -327,15 +327,45 @@ export function renewTaskClaim(taskId: number, agentId: string, guard?: AgentSes
   return { ok: true, task: getTask(taskId)! };
 }
 
-export function updateTaskStatus(taskId: number, input: TaskStatusInput): { ok: boolean; error?: string; task?: Task; event?: TaskEvent } {
+/**
+ * The AUTHENTICATED principal behind a status write, derived at the transport boundary from the
+ * signed token (`ctx.callerAgentId` / scopes) — NEVER from the request body. The ownership fence
+ * keys on this, not `input.agentId`, so omitting/spoofing the body field cannot advance another
+ * agent's claim (#1063).
+ */
+export interface TaskStatusActor {
+  /** The caller's own agent id (`ctx.callerAgentId`). undefined for full-reach/system/multi-agent tokens. */
+  agentId?: string;
+  /** Full-reach `*`, internal `system`, or a task-admin scope: may advance a task it does not own. */
+  privileged?: boolean;
+}
+
+export function updateTaskStatus(taskId: number, input: TaskStatusInput, actor?: TaskStatusActor): { ok: boolean; error?: string; conflict?: boolean; task?: Task; event?: TaskEvent } {
   const task = getTask(taskId);
   if (!task) return { ok: false, error: "task not found" };
   // Fence: the claim-lane status updater writes `claimed_by`; deliverable Tasks must never
   // be mutated here. They transition through setTaskStatus (src/db/task-entity.ts), which
   // never touches claimed_by. (#834)
   if (task.kind === DELIVERABLE_TASK_KIND) return { ok: false, error: "deliverable task: use the task-entity status API" };
+  // Ownership fence (#1061, hardened #1063): once a task is claimed, only its current owner may
+  // advance the status. The acting identity is the AUTHENTICATED caller (`actor.agentId`, resolved
+  // from the signed token at the route) — NEVER the client-supplied `input.agentId`. Trusting the
+  // body let any task:write holder omit or spoof it and steal another agent's claim (#1063).
+  // A privileged caller (full-reach `*`, internal `system`, or a task-admin scope) may advance a
+  // task it does not own — the same escape hatch #1043's `ensureCanMintThread` grants. An undefined
+  // `actor` is an in-process trusted caller (automations, tests) and is likewise privileged.
+  // A null claimed_by still self-claims (fresh status write).
+  const privileged = actor?.privileged ?? actor === undefined;
+  const callerAgentId = actor?.agentId;
+  if (!privileged && task.claimedBy && callerAgentId !== task.claimedBy) {
+    return { ok: false, error: `task claimed by ${task.claimedBy}`, conflict: true };
+  }
   const now = Date.now();
-  const agentId = input.agentId ?? task.claimedBy ?? null;
+  // Effective owner/session identity. A privileged caller may act on behalf of the supplied
+  // `input.agentId` (or the existing owner — the automation/system self-claim path); an ordinary
+  // caller is bound to its authenticated identity and must NOT fall back to `claimedBy` — that
+  // fallback was the #1063 bypass that let a missing `agentId` silently inherit the owner.
+  const agentId = privileged ? (input.agentId ?? task.claimedBy ?? null) : (callerAgentId ?? null);
   if (agentId) {
     const session = validateAgentSession(agentId, input);
     if (!session.ok) return { ok: false, error: session.error };
@@ -360,7 +390,7 @@ export function updateTaskStatus(taskId: number, input: TaskStatusInput): { ok:
     }
   }
   const event = insertTaskEvent(taskId, {
-    source: input.agentId ?? "agent-relay",
+    source: agentId ?? "agent-relay",
     type: `status:${input.status}`,
     severity: task.severity,
     title: `Task ${input.status}`,

package/src/db/work-evidence.ts

@@ -24,13 +24,16 @@ export function hasArtifactCreatedBy(createdBy: string, since: number = 0): bool
 
 export function listFinalResponseCaptureMessages(from: string, since: number = 0, limit: number = 20): Message[] {
   const safeLimit = Math.min(Math.max(Math.floor(limit), 1), 100);
-  const rows = getDb().query(`
-    ${MSG_SELECT}
-    WHERE m.from_agent = ?
-      AND m.kind = 'chat'
-      AND m.created_at >= ?
-      AND json_extract(m.payload, '$.responseCapture.type') = 'response'
-      AND json_extract(m.payload, '$.responseCapture.final') = 1
+	  const rows = getDb().query(`
+	    ${MSG_SELECT}
+	    WHERE m.from_agent = ?
+	      AND m.kind = 'chat'
+	      AND m.created_at >= ?
+	      AND json_extract(m.payload, '$.responseCapture.type') = 'response'
+	      AND (
+	        json_extract(m.payload, '$.responseCapture.turnFinal') = 1
+	        OR json_extract(m.payload, '$.responseCapture.final') = 1
+	      )
     ORDER BY m.id DESC
     LIMIT ?
   `).all(from, since, safeLimit) as any[];