agent-relay-server 0.78.9 → 0.80.0

package/src/db/teams.ts

@@ -3,6 +3,7 @@ import { getAgent, setAgentTeam } from "./agents.ts";
 import { getDb, ValidationError } from "./connection.ts";
 import { rowToAgent } from "./mappers.ts";
 import { unpromotedBlackboardEntries, type UnpromotedBlackboardSummary } from "./project-entries.ts";
+import { isProviderBlocked } from "../provider-state.ts";
 import type { AgentCard, Team } from "../types";
 
 interface TeamRow {
@@ -72,6 +73,11 @@ export interface TeamOutcomeAggregates {
   recent: TeamOutcomeRecent[];
 }
 
+interface TeamBusyState {
+  busyMemberIds: string[];
+  lastBusyAt?: number;
+}
+
 export function teamId(): string {
   return `team_${randomUUID().replace(/-/g, "").slice(0, 16)}`;
 }
@@ -132,6 +138,18 @@ export function countLiveTeamMembers(teamId: string, cutoff: number): number {
   return row.n;
 }
 
+export function getTeamBusyState(teamId: string, cutoff: number): TeamBusyState {
+  const rows = (getDb().query(
+    "SELECT * FROM agents WHERE team_id = ? AND status = 'busy' AND last_seen > ? ORDER BY last_seen DESC, id ASC",
+  ).all(teamId, cutoff) as any[])
+    .map(rowToAgent)
+    .filter((agent) => !isProviderBlocked(agent));
+  return {
+    busyMemberIds: rows.map((row) => row.id),
+    ...(rows[0] ? { lastBusyAt: rows[0].lastSeen } : {}),
+  };
+}
+
 export function setTeamZeroMembersSince(teamId: string, ts: number): boolean {
   return getDb().query("UPDATE teams SET zero_members_since = ?, updated_at = ? WHERE id = ?").run(ts, ts, teamId).changes > 0;
 }

package/src/maintenance/jobs.ts

@@ -51,7 +51,7 @@ import {
 } from "./constants";
 import { emitCommand } from "./events";
 import { reapOrphanedSessions } from "./orphaned-sessions";
-import { reapZeroMemberTeams } from "./teams";
+import { reapZeroMemberTeams, runTeamIdleWatchdog } from "./teams";
 import { scanWorkspaceConflicts, workspaceGC } from "./workspaces";
 import type { MaintenanceJobDefinition } from "./types";
 
@@ -208,6 +208,14 @@ export const definitions: MaintenanceJobDefinition[] = [
     runOnStart: false,
     handler: reapZeroMemberTeams,
   },
+  {
+    id: "team-idle-watchdog",
+    title: "Team idle watchdog",
+    description: "Gently ping a team's current coordinator once when the team has had no busy members for the configured threshold.",
+    intervalMs: REAP_INTERVAL_MS,
+    runOnStart: false,
+    handler: runTeamIdleWatchdog,
+  },
   {
     id: "orchestrator-reaper",
     title: "Orchestrator reaper",

package/src/maintenance/teams.ts

@@ -2,12 +2,134 @@ import {
   clearTeamZeroMembersSince,
   countLiveTeamMembers,
   createActivityEvent,
+  getTeamBusyState,
+  getTeamRoster,
   listActiveTeams,
   setTeamZeroMembersSince,
 } from "../db";
 import { STALE_TTL_MS } from "../config";
+import { agentProviderState } from "../provider-state";
 import { dissolveTeamById } from "../services/team";
+import { getTeamsConfig } from "../teams-config-store";
 import { teamReapGraceMs } from "./constants";
+import { notifyTarget } from "./events";
+
+interface TeamIdleTrackerEntry {
+  firstNoBusyAt: number;
+  pinged: boolean;
+}
+
+const teamIdleTracker = new Map<string, TeamIdleTrackerEntry>();
+
+export function resetTeamIdleWatchdogForTests(): void {
+  teamIdleTracker.clear();
+}
+
+function teamIdlePayload(teamId: string, coordinatorId: string, thresholdMinutes: number, idleForMs: number, firstNoBusyAt: number) {
+  const roster = getTeamRoster(teamId).map((member) => {
+    const providerState = agentProviderState(member);
+    return {
+      id: member.id,
+      name: member.name,
+      label: member.label,
+      status: member.status,
+      ready: member.ready,
+      lastSeen: member.lastSeen,
+      blocked: providerState?.state === "blocked",
+      providerState: providerState ?? undefined,
+    };
+  });
+  return {
+    kind: "team.idle",
+    teamId,
+    coordinatorId,
+    thresholdMinutes,
+    thresholdMs: thresholdMinutes * 60_000,
+    idleForMs,
+    firstNoBusyAt,
+    roster,
+    blockedMembers: roster.filter((member) => member.blocked).map((member) => ({
+      id: member.id,
+      providerState: member.providerState,
+    })),
+  };
+}
+
+function notifyTeamIdle(teamId: string, coordinatorId: string, thresholdMinutes: number, idleForMs: number, firstNoBusyAt: number): string | null {
+  const roundedIdleMinutes = Math.max(thresholdMinutes, Math.floor(idleForMs / 60_000));
+  const payload = teamIdlePayload(teamId, coordinatorId, thresholdMinutes, idleForMs, firstNoBusyAt);
+  return notifyTarget(
+    "team.idle",
+    { teamId, agentId: coordinatorId },
+    coordinatorId,
+    "Team idle watchdog",
+    `Team \`${teamId}\` has had no busy members for ${roundedIdleMinutes} min. If the work is done, stand down. If not, check the team roster and restart unfinished work.`,
+    payload,
+  );
+}
+
+export function runTeamIdleWatchdog(input: { now?: number } = {}): Record<string, unknown> {
+  const config = getTeamsConfig();
+  if (!config.enabled) {
+    const cleared = teamIdleTracker.size;
+    teamIdleTracker.clear();
+    return { enabled: false, clearedTrackedTeams: cleared };
+  }
+
+  const now = input.now ?? Date.now();
+  const cutoff = now - STALE_TTL_MS;
+  const thresholdMs = config.thresholdMinutes * 60_000;
+  const seen = new Set<string>();
+  const busyTeamIds: string[] = [];
+  const waitingTeamIds: string[] = [];
+  const pingedTeamIds: string[] = [];
+  const alreadyPingedTeamIds: string[] = [];
+  const missingCoordinatorTeamIds: string[] = [];
+
+  for (const team of listActiveTeams()) {
+    seen.add(team.id);
+    const busy = getTeamBusyState(team.id, cutoff);
+    if (busy.busyMemberIds.length > 0) {
+      teamIdleTracker.delete(team.id);
+      busyTeamIds.push(team.id);
+      continue;
+    }
+
+    const entry = teamIdleTracker.get(team.id) ?? { firstNoBusyAt: now, pinged: false };
+    teamIdleTracker.set(team.id, entry);
+    const idleForMs = now - entry.firstNoBusyAt;
+    if (idleForMs < thresholdMs) {
+      waitingTeamIds.push(team.id);
+      continue;
+    }
+
+    if (entry.pinged) {
+      alreadyPingedTeamIds.push(team.id);
+      continue;
+    }
+    if (!team.coordinatorId) {
+      missingCoordinatorTeamIds.push(team.id);
+      continue;
+    }
+
+    notifyTeamIdle(team.id, team.coordinatorId, config.thresholdMinutes, idleForMs, entry.firstNoBusyAt);
+    entry.pinged = true;
+    pingedTeamIds.push(team.id);
+  }
+
+  for (const key of teamIdleTracker.keys()) if (!seen.has(key)) teamIdleTracker.delete(key);
+
+  return {
+    enabled: true,
+    thresholdMinutes: config.thresholdMinutes,
+    trackedTeams: teamIdleTracker.size,
+    busyTeamIds,
+    waitingTeamIds,
+    pingedTeamIds,
+    alreadyPingedTeamIds,
+    missingCoordinatorTeamIds,
+  };
+}
 
 export function reapZeroMemberTeams(): Record<string, unknown> {
   const now = Date.now();

package/src/notification-types.ts

@@ -10,6 +10,7 @@ export type NotificationType =
   | "agent.resume_budget_exhausted"
   | "agent.transient_land_hold"
   | "agent.rate_limit_resume"
+  | "team.idle"
   | "plan.bound_agent_exited"
   | "workspace.steward_task"
   | "workspace.conflict"
@@ -60,6 +61,7 @@ export const DEFAULT_TTL_MS: Record<NotificationType, number | null> = {
   "agent.resume_budget_exhausted": null,
   "agent.transient_land_hold": null,
   "agent.rate_limit_resume": 15 * MINUTES,
+  "team.idle": null,
   "plan.bound_agent_exited": null,
   "workspace.steward_task": null,
   "workspace.conflict": null,

package/src/quota.ts

@@ -1,7 +1,7 @@
 import { isRecord } from "agent-relay-sdk";
 import type { ProviderQuotaError, QuotaState, QuotaWindowName, QuotaSource, QuotaUnit } from "./types";
 
-const QUOTA_SOURCES = new Set<QuotaSource>(["header", "probe", "ingest"]);
+const QUOTA_SOURCES = new Set<QuotaSource>(["header", "probe", "ingest", "statusline"]);
 const QUOTA_UNITS = new Set<QuotaUnit>(["tokens", "requests", "%"]);
 const QUOTA_WINDOWS = new Set<QuotaWindowName>(["five_hour", "seven_day", "seven_day_sonnet", "seven_day_opus", "primary", "secondary"]);
 

package/src/routes/index.ts

@@ -7,6 +7,7 @@ import { deleteAutomationById, getAutomationById, getAutomationRuns, getAutomati
 import { deleteCommandById, deleteProviderModelRoute, getProviderConfigRoute, getProviderConfigsRoute, getProvidersRoute, patchProviderModelRoute, postProviderConfigTestRoute, putProviderConfigRoute, putProviderModelRoute } from "./provider-config";
 import { getProviderQuotasRoute, postProviderQuotaLeaseAcquireRoute, postProviderQuotaLeaseReleaseRoute, postProviderQuotaRoute } from "./provider-quotas";
 import { getProviderQuotaConfigRoute, getProviderQuotaConfigsRoute, putProviderQuotaConfigRoute } from "./provider-quota-config";
+import { getTeamsConfigRoute, putTeamsConfigRoute } from "./teams-config";
 import { deleteConfigKey, getConfigKey, getConfigKeyHistory, getConfigNamespace, putConfigKey } from "./config";
 import { deleteInboxDraftRoute, getChatHistoryImportsRoute, getInboxStateRoute, patchInboxThreadState, postChatHistoryImportRoute, putInboxDraft } from "./inbox";
 import { deleteMemoryRoute, getMemories, getMemoryBrokerInfo, getMemoryById, getMemoryStats, patchMemory, postMemory, postMemoryInject, postMemorySearch } from "./memory";
@@ -14,7 +15,7 @@ import { deleteMessageById, getCursorRoute, getMessageById, getMessageDeliveryRo
 import { deleteOrchestratorById, getOrchestratorById, getOrchestrators, patchOrchestratorAgents, postOrchestrator, postOrchestratorAction, postOrchestratorHeartbeat } from "./orchestrator";
 import { deleteSpawnPolicyRoute, getSpawnPoliciesHealth, getSpawnPoliciesRoute, getSpawnPolicyHealth, getSpawnPolicyRoute, getSpawnPolicyStatus, postSpawnPolicyRestart, postSpawnPolicyStart, postSpawnPolicyStop, putSpawnPolicyRoute } from "./spawn-policy";
 import { deleteTokenProfileRoute, getTokenById, getTokenMe, getTokenProfiles, getTokens, patchTokenProfile, postIntegrationRuntimeToken, postInteractiveRunnerRuntimeToken, postMcpRuntimeToken, postOrchestratorRunnerToken, postRuntimeTokenRenew, postToken, postTokenProfile, postTokenRevoke } from "./tokens";
-import { deleteWorkspaceById, getWorkspaceById, getWorkspaceDiagnostics, getWorkspaceDiff, getWorkspaceGitState, getWorkspaceMergePreview, getWorkspaceOrphans, getWorkspaceStewards, getWorkspaces, postWorkspaceAction, postWorkspaceCleanupStale, postWorkspaceOrphanReclaim } from "./workspaces";
+import { deleteWorkspaceById, getWorkspaceById, getWorkspaceDiagnostics, getWorkspaceDiff, getWorkspaceGitState, getWorkspaceMergePreview, getWorkspaceOrphans, getWorkspaceRecoveryBranches, getWorkspaceStewards, getWorkspaces, postWorkspaceAction, postWorkspaceCleanupStale, postWorkspaceOrphanReclaim, postWorkspaceRecoveryBranchDiscard } from "./workspaces";
 import { error, type Handler } from "./_shared";
 import { getActivityEvents, postActivityEvent } from "./activity";
 import { getAnalyticsRoute, getHealthRoute, getMaintenanceJobs, getStatsRoute, postMaintenanceJobRun, postSystemReap } from "./stats";
@@ -142,6 +143,8 @@ const routes: Route[] = [
   // Static segments before :id so "/workspaces/orphans" isn't captured as an id.
   route("GET", "/api/workspaces/orphans", getWorkspaceOrphans),
   route("POST", "/api/workspaces/orphans/reclaim", postWorkspaceOrphanReclaim),
+  route("GET", "/api/workspaces/recovery-branches", getWorkspaceRecoveryBranches),
+  route("POST", "/api/workspaces/recovery-branches/discard", postWorkspaceRecoveryBranchDiscard),
   route("GET", "/api/workspaces/stewards", getWorkspaceStewards),
   route("POST", "/api/workspaces/actions/cleanup-stale", postWorkspaceCleanupStale),
   route("GET", "/api/workspaces/:id", getWorkspaceById),
@@ -159,6 +162,8 @@ const routes: Route[] = [
   route("GET", "/api/merges/pauses/:id", getMergePauseById),
 
   route("POST", "/api/system/broadcast", postSystemBroadcast),
+  route("GET", "/api/teams/config", getTeamsConfigRoute),
+  route("PUT", "/api/teams/config", putTeamsConfigRoute),
   route("GET", "/api/teams", getTeamsRoute),
   route("GET", "/api/teams/outcomes", getTeamOutcomesRoute),
   route("GET", "/api/teams/me", getMyTeamRoute),

package/src/routes/provider-quotas.ts

@@ -1,5 +1,6 @@
 import { isRecord } from "agent-relay-sdk";
 import { acquireProviderQuotaLease, getOrchestrator, listProviderQuotas, releaseProviderQuotaLease, upsertProviderQuota } from "../db";
+import { emitRelayEvent } from "../events";
 import { quotaStateFromUnknown, providerQuotaErrorFromUnknown } from "../quota";
 import { cleanString } from "../validation";
 import { authorizeRoute, error, json, parseBody, parseQueryInt, type Handler } from "./_shared";
@@ -44,7 +45,9 @@ export const postProviderQuotaRoute: Handler = async (req) => {
   if (!parsed.ok) return error(parsed.error, parsed.status);
   const input = cleanProviderQuotaUpdate(parsed.body);
   if (typeof input === "string") return error(input);
-  return json(upsertProviderQuota(input), 201);
+  const record = upsertProviderQuota(input);
+  emitRelayEvent({ type: "provider-quota.updated", source: "server", subject: `${record.provider}:${record.accountKey}`, data: {} });
+  return json(record, 201);
 };
 
 function cleanLeaseBody(body: unknown): {

package/src/routes/teams-config.ts

@@ -0,0 +1,15 @@
+import { getTeamsConfig, setTeamsConfig } from "../teams-config-store";
+import { cleanString } from "../validation";
+import { error, json, parseBody, type Handler } from "./_shared";
+import { isRecord } from "agent-relay-sdk";
+
+export const getTeamsConfigRoute: Handler = () => {
+  return json(getTeamsConfig());
+};
+
+export const putTeamsConfigRoute: Handler = async (req) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  const updatedBy = isRecord(parsed.body) ? cleanString(parsed.body.updatedBy, "updatedBy", { max: 200 }) : undefined;
+  return json(setTeamsConfig(parsed.body, { updatedBy }));
+};

package/src/routes/workspaces.ts

@@ -10,7 +10,7 @@ import { createCommand } from "../commands-db";
 import { LAND_STRATEGIES, isOwnerAlive, withOwnerOnline } from "../workspace-merge";
 import { isPathWithinBase } from "../utils";
 import { resolve } from "node:path";
-import { type WorkspaceAutoMergePolicy, type WorkspaceDiagnostics, type WorkspaceGitState, type WorkspaceMergeStrategy, type WorkspaceRecord, type WorkspaceStatus } from "../types";
+import { type WorkspaceAutoMergePolicy, type WorkspaceDiagnostics, type WorkspaceGitState, type WorkspaceMergeStrategy, type WorkspaceRecoveryBranch, type WorkspaceRecord, type WorkspaceStatus } from "../types";
 import { AUTO_MERGE_POLICIES } from "../workspace-merge";
 import { workspaceActiveClaim } from "../workspace-claim";
 import { relayToken } from "../config";
@@ -82,6 +82,149 @@ export const getWorkspaceOrphans: Handler = async () => {
   return json(reason ? { orphans, missingWorktrees, reason } : { orphans, missingWorktrees });
 };
 
+function workspaceCleanupResult(workspace: WorkspaceRecord): Record<string, unknown> | undefined {
+  const result = workspace.metadata.cleanupResult;
+  return isRecord(result) ? result : undefined;
+}
+
+function workspaceBranchKey(repoRoot: string, branch: string): string {
+  return `${repoRoot}\0${branch}`;
+}
+
+function latestWorkspaceByBranch(workspaces: WorkspaceRecord[]): Map<string, WorkspaceRecord> {
+  const byBranch = new Map<string, WorkspaceRecord>();
+  for (const workspace of [...workspaces].sort((a, b) => b.updatedAt - a.updatedAt)) {
+    if (!workspace.branch) continue;
+    const key = workspaceBranchKey(workspace.repoRoot, workspace.branch);
+    if (byBranch.has(key)) continue;
+    byBranch.set(key, workspace);
+  }
+  return byBranch;
+}
+
+function owningOrchestratorForRepo(repoRoot: string) {
+  return listOrchestrators().find((candidate) => candidate.status === "online" && candidate.apiUrl && isPathWithinBase(repoRoot, candidate.baseDir));
+}
+
+async function fetchRecoveryBranchesForRepo(repoRoot: string, opts: { baseRef?: string; baseSha?: string } = {}): Promise<{ branches: WorkspaceRecoveryBranch[]; unavailable?: string }> {
+  const orch = owningOrchestratorForRepo(repoRoot);
+  if (!orch?.apiUrl) return { branches: [], unavailable: "owning orchestrator offline" };
+  const query = new URLSearchParams({ repoRoot });
+  if (opts.baseRef) query.set("baseRef", opts.baseRef);
+  if (opts.baseSha) query.set("baseSha", opts.baseSha);
+  const headers: Record<string, string> = {};
+  const token = relayToken();
+  if (token) headers[RELAY_TOKEN_HEADER] = token;
+  try {
+    const res = await fetch(`${orch.apiUrl}/api/workspace/recovery-branches?${query.toString()}`, { headers, signal: AbortSignal.timeout(10_000) });
+    if (!res.ok) return { branches: [], unavailable: `host returned ${res.status}` };
+    const payload = await res.json() as unknown;
+    if (!isRecord(payload) || !Array.isArray(payload.branches)) return { branches: [], unavailable: "host returned malformed recovery branch list" };
+    return { branches: payload.branches.filter(isRecord) as unknown as WorkspaceRecoveryBranch[] };
+  } catch (e) {
+    return { branches: [], unavailable: `orchestrator unreachable: ${(e as Error).message}` };
+  }
+}
+
+export const getWorkspaceRecoveryBranches: Handler = async (req) => {
+  try {
+    const url = new URL(req.url);
+    const repoRoot = cleanString(url.searchParams.get("repoRoot") ?? undefined, "repoRoot", { max: 1000 });
+    const baseRef = cleanString(url.searchParams.get("baseRef") ?? undefined, "baseRef", { max: 240 });
+    const baseSha = cleanString(url.searchParams.get("baseSha") ?? undefined, "baseSha", { max: 80 });
+    const includeActive = url.searchParams.get("includeActive") === "1";
+    const allWorkspaces = listWorkspaces(repoRoot ? { repoRoot } : {});
+    const repoRoots = repoRoot ? [repoRoot] : [...new Set(allWorkspaces.map((workspace) => workspace.repoRoot))];
+    const byBranch = latestWorkspaceByBranch(allWorkspaces);
+    const branches: WorkspaceRecoveryBranch[] = [];
+    const unavailable: Record<string, string> = {};
+
+    for (const repo of repoRoots) {
+      const fetched = await fetchRecoveryBranchesForRepo(repo, { baseRef, baseSha });
+      if (fetched.unavailable) {
+        unavailable[repo] = fetched.unavailable;
+        continue;
+      }
+      for (const branch of fetched.branches) {
+        const workspace = byBranch.get(workspaceBranchKey(repo, branch.branch));
+        const activeWorkspace = Boolean(workspace && !TERMINAL_WORKSPACE_STATUSES.has(workspace.status));
+        if (activeWorkspace && !includeActive) continue;
+        const owner = workspace?.ownerAgentId ? getAgent(workspace.ownerAgentId) : null;
+        const cleanupResult = workspace ? workspaceCleanupResult(workspace) : undefined;
+        const cleanupPreservedReason = cleanString(cleanupResult?.branchPreservedReason, "branchPreservedReason", { max: 400 });
+        const cleanupCommandId = cleanString(workspace?.metadata.cleanupCommandId, "cleanupCommandId", { max: 160 });
+        branches.push({
+          ...branch,
+          ...(workspace ? { workspaceId: workspace.id } : {}),
+          ...(workspace?.ownerAgentId ? { ownerAgentId: workspace.ownerAgentId } : {}),
+          ...(owner?.status ? { ownerStatus: owner.status } : {}),
+          ...(cleanupCommandId ? { cleanupCommandId } : {}),
+          ...(cleanupPreservedReason ? { cleanupPreservedReason, preservedByCleanup: true } : {}),
+          ...(activeWorkspace ? { activeWorkspace: true } : {}),
+          baseRef: workspace?.baseRef ?? branch.baseRef,
+          baseSha: workspace?.baseSha ?? branch.baseSha,
+        });
+      }
+    }
+
+    branches.sort((a, b) => (b.ageMs ?? 0) - (a.ageMs ?? 0) || a.branch.localeCompare(b.branch));
+    return json({ repoRoot, scannedRepos: repoRoots, branches, ...(Object.keys(unavailable).length ? { unavailable } : {}) });
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+export const postWorkspaceRecoveryBranchDiscard: Handler = async (req) => {
+  const denied = authorizeRoute(req, { scope: "command:write" });
+  if (denied) return denied;
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    if (!isRecord(parsed.body)) return error("body required");
+    const repoRoot = cleanString(parsed.body.repoRoot, "repoRoot", { max: 1000 });
+    const branch = cleanString(parsed.body.branch, "branch", { max: 240 });
+    const baseRef = cleanString(parsed.body.baseRef, "baseRef", { max: 240 });
+    const baseSha = cleanString(parsed.body.baseSha, "baseSha", { max: 80 });
+    const reason = cleanString(parsed.body.reason, "reason", { max: 1000 });
+    const force = parsed.body.force === true;
+    if (!repoRoot || !branch) return error("repoRoot and branch required", 400);
+    if (!branch.startsWith("agent/")) return error("only agent/* branches can be discarded through recovery cleanup", 400);
+    if (force && !reason) return error("reason required for forced recovery branch discard", 400);
+    const orch = owningOrchestratorForRepo(repoRoot);
+    if (!orch?.agentId) return error("no online orchestrator owns this repo", 409);
+    const fetched = await fetchRecoveryBranchesForRepo(repoRoot, { baseRef, baseSha });
+    if (fetched.unavailable) return error(fetched.unavailable, 409);
+    const target = fetched.branches.find((item) => item.branch === branch);
+    if (!target) return error("recovery branch not found", 404);
+    if (target.safeToDelete !== true && !force) {
+      return error(`branch holds work or cannot be proven safe (${target.preserveReason ?? `${target.unmergedAhead ?? target.ahead ?? "?"} unlanded commit(s)`}); land it first or pass force:true with reason to discard`, 409);
+    }
+    const command = createCommand({
+      type: "workspace.recovery-branch-discard",
+      source: "system",
+      target: orch.agentId,
+      correlationId: branch,
+      params: { action: "recovery-branch-discard", repoRoot, branch, baseRef: baseRef ?? target.baseRef, baseSha: baseSha ?? target.baseSha, force, reason, requestedBy: "steward", requestedAt: Date.now() },
+    });
+    emitCommand(command);
+    auditEvent({
+      clientId: `workspace-recovery-branch-discard-${Date.now()}`,
+      kind: "state",
+      title: "Recovery branch discard requested",
+      body: force ? `${branch} — forced discard after review: ${reason}` : `${branch} — confirmed empty/superseded`,
+      meta: repoRoot,
+      icon: "ti-trash",
+      view: "orchestrators",
+      metadata: { repoRoot, branch, commandId: command.id, force, reason, safeToDelete: target.safeToDelete, preserveReason: target.preserveReason, ...authAuditMetadata(req) },
+    });
+    return json({ command, branch: target }, 202);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
 export const postWorkspaceOrphanReclaim: Handler = async (req) => {
   const denied = authorizeRoute(req, { scope: "command:write" });
   if (denied) return denied;

package/src/security.ts

@@ -194,6 +194,7 @@ export function requiredScopeFor(method: string, pathname: string): string | nul
   if (pathname.startsWith("/api/maintenance")) return "system:admin";
   if (pathname.startsWith("/api/tasks")) return method === "GET" ? "task:read" : "task:write";
   if (pathname.startsWith("/api/pairs")) return method === "GET" ? "pairs:read" : "pairs:write";
+  if (pathname === "/api/teams/config") return method === "GET" ? "teams:read" : "settings:write:teams";
   if (pathname.startsWith("/api/teams")) return method === "GET" ? "teams:read" : "teams:write";
   if (pathname.startsWith("/api/blackboard")) return method === "GET" ? "blackboard:read" : "blackboard:write";
   if (pathname.startsWith("/api/issue-associations")) return method === "GET" ? "issue:read" : "issue:write";
@@ -280,6 +281,7 @@ export function requiredComponentScopeFor(method: string, pathname: string): str
   if (pathname === "/api/providers/quota-config" || pathname.match(/^\/api\/providers\/[^/]+\/quota-config$/)) {
     return method === "GET" ? "agent:read" : "settings:write:provider";
   }
+  if (pathname === "/api/teams/config") return method === "GET" ? "teams:read" : "settings:write:teams";
   if (pathname.startsWith("/api/messages") || pathname.startsWith("/api/inbox")) return method === "GET" ? "message:read" : "message:send";
   if (pathname.startsWith("/api/agent-profiles")) return method === "GET" ? "agent:read" : "agent:write";
   if (pathname.startsWith("/api/tasks")) return method === "GET" ? "task:read" : "task:write";
@@ -304,7 +306,7 @@ export function requiredComponentScopeFor(method: string, pathname: string): str
   return "system:admin";
 }
 
-const CONFIG_SETTINGS_NAMESPACES = new Set(["steward", "insights", "notifications", "workspace", "landing", "provider"]);
+const CONFIG_SETTINGS_NAMESPACES = new Set(["steward", "insights", "notifications", "workspace", "landing", "provider", "teams"]);
 
 function requiredSettingsScopeFor(method: string, pathname: string): string | null | undefined {
   if (pathname === "/api/settings") return method === "GET" ? "settings:read" : null;

package/src/settings/registry.ts

@@ -20,11 +20,14 @@ import {
   APPROVAL_MODES,
   errMessage,
   SPAWN_PROVIDERS,
+  TEAM_IDLE_THRESHOLD_MINUTES_MAX,
+  TEAM_IDLE_THRESHOLD_MINUTES_MIN,
   VALID_EFFORTS,
   type JSONSchema,
   type SettingDescriptor,
   type SettingScope,
 } from "agent-relay-sdk";
+import { DEFAULT_TEAMS_CONFIG } from "agent-relay-sdk/teams-config";
 
 /** Fail-closed default scope — a descriptor that omits scope requires admin to
  *  read and write (#385 owns the scope grammar; this layer only declares it). */
@@ -215,6 +218,20 @@ const WORKSPACE_SCHEMA: JSONSchema = {
   },
 };
 
+const TEAMS_SCHEMA: JSONSchema = {
+  type: "object",
+  additionalProperties: false,
+  required: ["enabled", "thresholdMinutes"],
+  properties: {
+    enabled: { type: "boolean" },
+    thresholdMinutes: {
+      type: "integer",
+      minimum: TEAM_IDLE_THRESHOLD_MINUTES_MIN,
+      maximum: TEAM_IDLE_THRESHOLD_MINUTES_MAX,
+    },
+  },
+};
+
 const LANDING_SCHEMA: JSONSchema = {
   type: "object",
   additionalProperties: false,
@@ -347,6 +364,16 @@ function seedBuiltInSettings(): void {
     display: { group: "Workspace", label: "Landing strategy", description: "Default land strategy for workspace branches.", order: 41 },
   });
 
+  registerSetting({
+    namespace: "teams",
+    key: "default",
+    schema: TEAMS_SCHEMA,
+    defaults: DEFAULT_TEAMS_CONFIG,
+    scope: { read: "settings:read:teams", write: "settings:write:teams" },
+    tier: "server-runtime",
+    display: { group: "Teams", label: "Team idle watchdog", description: "Coordinator nudge when a team has no busy members.", order: 45 },
+  });
+
   registerSetting({
     namespace: "provider",
     key: "chatCaptureMode",

package/src/teams-config-store.ts

@@ -0,0 +1,22 @@
+import { getConfig, setConfig } from "./config-store";
+import { emitConfigChanged } from "./sse";
+import {
+  DEFAULT_TEAMS_CONFIG,
+  normalizeTeamsConfig,
+  type TeamsConfig,
+} from "agent-relay-sdk";
+
+const TEAMS_CONFIG_NAMESPACE = "teams";
+const TEAMS_CONFIG_KEY = "default";
+
+export function getTeamsConfig(): TeamsConfig {
+  const entry = getConfig<TeamsConfig>(TEAMS_CONFIG_NAMESPACE, TEAMS_CONFIG_KEY);
+  return entry ? normalizeTeamsConfig(entry.value) : { ...DEFAULT_TEAMS_CONFIG };
+}
+
+export function setTeamsConfig(value: unknown, opts: { updatedBy?: string } = {}): TeamsConfig {
+  const normalized = normalizeTeamsConfig(value);
+  const entry = setConfig(TEAMS_CONFIG_NAMESPACE, TEAMS_CONFIG_KEY, normalized, opts.updatedBy);
+  emitConfigChanged(entry.namespace, entry.key, entry.version);
+  return normalized;
+}