@humwick/server 0.130.1 → 0.130.3

package/src/runtime-grant.ts

@@ -5,11 +5,11 @@ import { getLaunchFact } from "./db/launch-facts";
 import { getTokenProfile } from "./token-db";
 import { getAgentProfile, spawnGrantForProfile, toolGroupsForProfile } from "./config-store";
 import { FLEET_SCOPE } from "./security";
-import { stringValue } from "@humwick/sdk";
+import { registryToolName, stringValue } from "@humwick/sdk";
 import { canonicalAgentProfileName, hasScope } from "@humwick/sdk/types";
 import { COORDINATOR_PROFILE_NAMES } from "./agent-system-tags";
 import { SECRETS_DEFAULT_PROFILES, SECRETS_TOOL_GROUP, SECRETS_WRITE_SCOPE } from "./secrets-broker/config";
-import { resolveRelayTools, SELF_CARE_TOOL_GROUP } from "./mcp/tool-groups";
+import { RELAY_TOOL_GROUPS, resolveRelayTools, SELF_CARE_TOOL_GROUP } from "./mcp/tool-groups";
 
 // Scopes that turn an agent's runtime token into a spawn-capable one (#221). Appended to the
 // provider-agent base scope only when the resolved profile permits (maxSpawnedAgents > 0).
@@ -24,7 +24,11 @@ const SPAWN_SCOPES = ["command:spawn", "command:shutdown"] as const;
 const FLEET_OPS_PROFILES = new Set(["coordinator", "ops-assistant"]);
 // #1925 H10 — fleet visibility is coordinator-facing. Keep this a fixed trusted-profile allowlist,
 // like command:fleet, rather than a user-editable profile setting that could widen worker tokens.
-const HOST_READ_PROFILES = new Set(["coordinator"]);
+const HOST_WRITE_PROFILES = new Set(["coordinator"]);
+// #3772 — the reboot runbook reads resource_control held/waiter counts from /api/hosts; ops profiles read, never write.
+const HOST_READ_PROFILES = new Set([...HOST_WRITE_PROFILES, "ops-assistant", "sec-ops"]);
+// #3780 — operations and QA need hub diagnostics; coordinators can delegate the read scope.
+const STATS_READ_PROFILES = new Set(["coordinator", "ops-assistant", "qa"]);
 // #3073 — coordinator-only groups (not in WORKER_TOOL_GROUPS) a coordinator always gets, even when its stored override predates them.
 const COORDINATOR_ONLY_TOOL_GROUPS = ["decisions", "workflows", "project", "routing"] as const;
 // #3327 — the coordinator edits routing preferences, like Edin in the dashboard.
@@ -43,11 +47,10 @@ function callerMayMintHostsScope(callerScopes: string[] | undefined, scope: "hos
   return callerScopes === undefined || hasScope(callerScopes, scope);
 }
 
-// #3110 — the secrets broker scope follows the `secrets` tool group: an explicit group list must name
-// it; a full-surface profile (no list) gets it only by default (coordinator, ops-assistant). A caller
-// cannot confer it onto a child it spawns without holding it.
-function grantsSecretsScope(profile: string | undefined, toolGroups: string[] | undefined, callerScopes: string[] | undefined): boolean {
-  const inGroup = toolGroups ? toolGroups.includes(SECRETS_TOOL_GROUP) : Boolean(profile && SECRETS_DEFAULT_PROFILES.has(profile));
+// #3110/#3817 — broker groups and exact includes request the same scope, capped by the caller.
+function grantsSecretsScope(profile: string | undefined, toolGroups: string[] | undefined, explicitlySelected: boolean, callerScopes: string[] | undefined): boolean {
+  const inGroup = (toolGroups ? toolGroups.includes(SECRETS_TOOL_GROUP) : Boolean(profile && SECRETS_DEFAULT_PROFILES.has(profile)))
+    || explicitlySelected;
   return inGroup && (callerScopes === undefined || hasScope(callerScopes, SECRETS_WRITE_SCOPE));
 }
 
@@ -72,6 +75,8 @@ function nonTrustedBaseline(agentInitiated: boolean): string[] {
 interface RunnerGrant {
   scope: string[];
   canSpawn: boolean;
+  /** A sub-coordinator under its root coordinator's project delegation: it places spawns on any host its parent can (#3804). */
+  delegated: boolean;
   maxSpawnedAgents: number;
   toolGroups: string[] | undefined;
   toolInclude?: string[];
@@ -93,7 +98,7 @@ export function deriveRunnerGrant(profile: string | undefined, authority: Deriva
   const selection = profile ? getAgentProfile(profile)?.value.relay.tools : undefined;
   let toolGroups = toolGroupsForProfile(profile);
   // #2897/#3073/#3110 — stored overrides predate newer trusted-profile groups: coordinators always get the coordinator-only
-  // groups, and the secrets profiles (coordinator, ops-assistant) always get `secrets`. Keep explicit NONE and full-surface semantics.
+  // groups, and the coordinator gets `secrets`. Keep explicit NONE and full-surface semantics.
   if (toolGroups?.length) {
     const extra: string[] = [];
     if ((COORDINATOR_PROFILE_NAMES as readonly string[]).includes(profile ?? "")) extra.push(...COORDINATOR_ONLY_TOOL_GROUPS);
@@ -104,19 +109,21 @@ export function deriveRunnerGrant(profile: string | undefined, authority: Deriva
   }
   const fleetOps = !agentInitiated && Boolean(profile && FLEET_OPS_PROFILES.has(profile)) && callerMayMintFleetScope(callerScopes);
   const hostsRead = !agentInitiated && Boolean(profile && HOST_READ_PROFILES.has(profile)) && callerMayMintHostsScope(callerScopes, "hosts:read");
-  resolveRelayTools({ ...selection, groups: toolGroups });
+  const selected = resolveRelayTools({ ...selection, groups: toolGroups });
+  const explicitSecrets = selection?.include?.map(registryToolName).some(name => selected.has(name) && RELAY_TOOL_GROUPS[SECRETS_TOOL_GROUP]!.includes(name)) ?? false;
   let scope = [
     ...nonTrustedBaseline(agentInitiated),
     ...(fleetOps ? [FLEET_SCOPE] : []),
     ...(hostsRead ? ["hosts:read"] : []),
-    ...(!agentInitiated && Boolean(profile && HOST_READ_PROFILES.has(profile)) && callerMayMintHostsScope(callerScopes, "hosts:write") ? ["hosts:write"] : []),
-    ...(grantsSecretsScope(profile, toolGroups, callerScopes) ? [SECRETS_WRITE_SCOPE] : []),
+    ...(profile && STATS_READ_PROFILES.has(profile.toLowerCase()) && (callerScopes === undefined || hasScope(callerScopes, "stats:read")) ? ["stats:read"] : []),
+    ...(!agentInitiated && Boolean(profile && HOST_WRITE_PROFILES.has(profile)) && callerMayMintHostsScope(callerScopes, "hosts:write") ? ["hosts:write"] : []),
+    ...(grantsSecretsScope(profile, toolGroups, explicitSecrets, callerScopes) ? [SECRETS_WRITE_SCOPE] : []),
     ...(!agentInitiated && (COORDINATOR_PROFILE_NAMES as readonly string[]).includes(profile ?? "") && (callerScopes === undefined || hasScope(callerScopes, ROUTING_WRITE_SCOPE)) ? [ROUTING_WRITE_SCOPE] : []),
     ...(grant.canSpawn ? SPAWN_SCOPES.filter(scope => !agentInitiated || callerScopes === undefined || hasScope(callerScopes, scope)) : []),
     ...(delegated && callerScopes && hasScope(callerScopes, "teams:write") ? ["teams:write"] : []),
   ];
   if (lineage?.participating && callerScopes) scope = scope.filter(scope => hasScope(callerScopes, scope));
-  return { scope, canSpawn: grant.canSpawn, maxSpawnedAgents: grant.maxSpawnedAgents, toolGroups,
+  return { scope, canSpawn: grant.canSpawn, delegated, maxSpawnedAgents: grant.maxSpawnedAgents, toolGroups,
     ...(selection?.include === undefined ? {} : { toolInclude: selection.include }),
     ...(selection?.exclude === undefined ? {} : { toolExclude: selection.exclude }),
   };
@@ -149,6 +156,7 @@ export function successorGrant(agentId: string, profile: string | undefined, dep
   return {
     scope: derived.scope.filter((scope) => ceiling.scope.includes(scope)),
     canSpawn: derived.canSpawn && ceiling.canSpawn,
+    delegated: derived.delegated && ceiling.delegated,
     maxSpawnedAgents: Math.min(derived.maxSpawnedAgents, ceiling.maxSpawnedAgents),
     toolGroups: derived.toolGroups,
     toolInclude: derived.toolInclude,

package/src/runtime-tokens.ts

@@ -1,9 +1,10 @@
-import { registryToolName } from "@humwick/sdk";
+import { stringValue } from "@humwick/sdk";
 import { writeChildEnv } from "@humwick/sdk/env";
 import { deriveRunnerGrant, successorGrant } from "./runtime-grant";
 export { runnerSpawnGrantForAgent } from "./runtime-grant";
-import { TOKEN_RECOVERY_WINDOW_SECONDS, createToken, getToken, getTokenProfile, type CreateTokenInput } from "./token-db";
-import { createTokenAsync, handoffTokenAsync } from "./token-db-write";
+import { TOKEN_RECOVERY_WINDOW_SECONDS, createToken, getToken, getTokenProfile, type CreateTokenInput, type HandoffTokenInput, type TokenHandoff } from "./token-db";
+import { runnerTokenMintLimit } from "./runner-token-mint-limit";
+import { createRunnerTokenAsync, createTokenAsync, handoffTokenAsync } from "./token-db-write";
 import { FLEET_SCOPE, verifyComponentTokenAllowExpired } from "./security";
 import { getAgentProfile, hostPinForProfile, spawnGrantForProfile, toolGroupsForProfile } from "./config-store";
 import { toolAllowlistForRunner } from "./mcp-tool-allowlist";
@@ -12,11 +13,9 @@ import { getLaunchFact, recordLaunchFact, type LaunchFact } from "./db/launch-fa
 import type { ComponentToken, SpawnApprovalMode, TokenConstraints, TokenRecord } from "./types";
 import { listManagedOrchestratorsForAgent } from "./orchestrator-lookup";
 import { sameHostIdentity } from "./utils";
-import { stringValue } from "@humwick/sdk";
-import { canonicalAgentProfileName, hasScope } from "@humwick/sdk/types";
+import { canonicalAgentProfileName } from "@humwick/sdk/types";
 import { COORDINATOR_PROFILE_NAMES } from "./agent-system-tags";
 import { SECRETS_DEFAULT_PROFILES, SECRETS_TOOL_GROUP, SECRETS_WRITE_SCOPE } from "./secrets-broker/config";
-import { INCLUDED_TOOL_SCOPE_NEEDS, RELAY_TOOL_GROUPS, resolveRelayTools, SELF_CARE_TOOL_GROUP } from "./mcp/tool-groups";
 
 /**
  * Who vouches for a runner launch's authority (#3110 review). A launch without a positively identified
@@ -38,6 +37,22 @@ interface RuntimeTokenResult {
   record: TokenRecord;
 }
 
+/** A refused successor mint; `retryAfterSeconds` marks a per-subject rate limit (HTTP 429). */
+export type RunnerTokenMintRefusal = { error: string; retryAfterSeconds?: number };
+
+/** #3775 — the one way a runner token's successor is minted: within the subject's mint limit, charged per new token. */
+export async function handoffRunnerTokenAsync(sub: string, input: HandoffTokenInput): Promise<TokenHandoff | null | { retryAfterSeconds: number }> {
+  const retryAfterSeconds = runnerTokenMintLimit.refusal(sub);
+  if (retryAfterSeconds !== undefined) return { retryAfterSeconds };
+  const handoff = await handoffTokenAsync(input);
+  if (handoff && !handoff.replayed) runnerTokenMintLimit.charge(sub);
+  return handoff;
+}
+
+function mintRateLimited(handoff: object | null): handoff is { retryAfterSeconds: number } {
+  return handoff !== null && "retryAfterSeconds" in handoff;
+}
+
 function runnerTokenOwnedByOrchestratorHost(
   constraints: NonNullable<ReturnType<typeof verifyComponentTokenAllowExpired>>["constraints"],
   orchestratorId: string,
@@ -68,7 +83,7 @@ export async function reissueRunnerRuntimeToken(input: {
   expiredToken: string;
   orchestratorId: string;
   createdBy?: string;
-}): Promise<RuntimeTokenResult | { error: string }> {
+}): Promise<RuntimeTokenResult | RunnerTokenMintRefusal> {
   const payload = verifyComponentTokenAllowExpired(input.expiredToken, { allowStaleRevoked: true });
   // #3133 — recovery hands off from the token's record, which holds its standing; a token without one recovers nothing.
   if (!payload?.jti) return { error: "invalid or revoked runner token" };
@@ -95,7 +110,8 @@ export async function reissueRunnerRuntimeToken(input: {
     constraints: payload.constraints,
     createdBy: input.createdBy ?? `remint:${payload.jti}`,
   };
-  const handoff = await handoffTokenAsync({ jti: payload.jti, successor, recoverExpiredWithinSeconds: TOKEN_RECOVERY_WINDOW_SECONDS, createdBy: successor.createdBy });
+  const handoff = await handoffRunnerTokenAsync(payload.sub, { jti: payload.jti, successor, recoverExpiredWithinSeconds: TOKEN_RECOVERY_WINDOW_SECONDS, createdBy: successor.createdBy });
+  if (mintRateLimited(handoff)) return { error: "runner token mint rate limited", retryAfterSeconds: handoff.retryAfterSeconds };
   return handoff ?? { error: "invalid or revoked runner token" };
 }
 
@@ -122,7 +138,7 @@ function runnerGrantKey(scope: readonly string[] | undefined, constraints: Token
  * (current profile, lineage ceiling) and the presented token's launch identity. An identical grant is left
  * alone; otherwise the token is handed off like a renewal, so a lost response is recovered by a retry.
  */
-export async function remintRunnerRuntimeToken(auth: ComponentToken, createdBy: string): Promise<RunnerTokenRemint | { unchanged: true; jti: string } | { error: string }> {
+export async function remintRunnerRuntimeToken(auth: ComponentToken, createdBy: string): Promise<RunnerTokenRemint | { unchanged: true; jti: string } | RunnerTokenMintRefusal> {
   const previous = auth.jti ? getToken(auth.jti) : null;
   const c = auth.constraints ?? {};
   const agentId = c.agents?.length === 1 ? c.agents[0] : undefined;
@@ -149,7 +165,8 @@ export async function remintRunnerRuntimeToken(auth: ComponentToken, createdBy:
   });
   if (token.constraints?.orchestrators?.includes("")) return { error: "the agent's host is unknown, so its host pin cannot be kept" };
   if (runnerGrantKey(previous.scope, previous.constraints) === runnerGrantKey(token.scope, token.constraints)) return { unchanged: true, jti: previous.jti };
-  const handoff = await handoffTokenAsync({ jti: previous.jti, allowedProfileIds: ["provider-agent"], successor: token, createdBy });
+  const handoff = await handoffRunnerTokenAsync(auth.sub, { jti: previous.jti, allowedProfileIds: ["provider-agent"], successor: token, createdBy });
+  if (mintRateLimited(handoff)) return { error: "runner token mint rate limited", retryAfterSeconds: handoff.retryAfterSeconds };
   if (!handoff) return { error: "the presented token was already rotated" };
   const { record } = handoff;
   return {
@@ -175,8 +192,8 @@ export function issueOrchestratorRuntimeToken(input: {
 }
 
 /** #1870 S6c — the mint on the writer thread, for the async routes. */
-export function issueOrchestratorRuntimeTokenAsync(input: Parameters<typeof issueOrchestratorRuntimeToken>[0]): Promise<RuntimeTokenResult> {
-  return createTokenAsync(orchestratorTokenSpec(input));
+export async function issueOrchestratorRuntimeTokenAsync(input: Parameters<typeof issueOrchestratorRuntimeToken>[0]): Promise<RuntimeTokenResult> {
+  return (await createTokenAsync(orchestratorTokenSpec(input)));
 }
 
 function orchestratorTokenSpec(input: Parameters<typeof issueOrchestratorRuntimeToken>[0]): CreateTokenInput {
@@ -250,21 +267,15 @@ function runnerTokenSpec(input: RunnerRuntimeTokenInput): { token: CreateTokenIn
   const grant = authority.kind === "successor" ? successorGrant(input.agentId, profile)
     : { ...deriveRunnerGrant(profile, authority.kind === "delegated" ? { agentInitiated, callerScopes: authority.callerScopes, parentAgentId: input.spawnedBy, projectId: input.projectId, maxSpawnedAgents: input.maxSpawnedAgents } : { agentInitiated }), agentInitiated };
   const { canSpawn, maxSpawnedAgents, toolGroups, toolInclude, toolExclude } = grant;
-  const selected = resolveRelayTools({ groups: toolGroups, include: toolInclude, exclude: toolExclude });
-  for (const authoredName of toolInclude ?? []) {
-    const name = registryToolName(authoredName);
-    if (!selected.has(name)) continue;
-    const needs = INCLUDED_TOOL_SCOPE_NEEDS[name];
-    if (RELAY_TOOL_GROUPS.kernel!.includes(name) || (needs && !needs.some((need) => hasScope(grant.scope, need)))) {
-      throw new Error(`relay.tools.include: ${name} requires ${needs?.join(" or ") ?? "kernel control scopes"}; profile ${profile} cannot grant that scope under this launch authority`);
-    }
-  }
+  // Includes choose the surface, not launch authority. MCP scope filtering hides unavailable tools (#3817).
   // #1570 — provider-split: a Codex worker eager-loads every listed tool schema every turn (no
   // client-native deferral), so trim its always-loaded MCP surface to the lean worker set. Classified
   // by explicit worker profile (not tool-group shape — reviewers share the groups but aren't workers).
   const toolAllowlist = toolInclude !== undefined || toolExclude !== undefined
     ? undefined : toolAllowlistForRunner(input.provider, profile);
-  const hostPinned = grant.agentInitiated ? true : (input.hostPinned ?? hostPinForProfile(input.profile));
+  // #3804 — an agent-spawned child stays on its launch host, except a delegated sub-coordinator: its home host is
+  // often full, so it places spawns wherever its parent can unless the launch pinned it.
+  const hostPinned = grant.agentInitiated && !grant.delegated ? true : (input.hostPinned ?? hostPinForProfile(input.profile));
   const subject = input.policyName
     ? `runner:policy:${input.policyName}`
     : input.spawnRequestId
@@ -306,6 +317,7 @@ function runnerTokenSpec(input: RunnerRuntimeTokenInput): { token: CreateTokenIn
     : { kind: "root", ...(authority.kind === "delegated" ? { launcherScopes: authority.callerScopes } : {}), ...(profile ? { profile } : {}) } };
 }
 
+/** Sync twin for in-process tests; every runtime launch path mints through the writer op below. */
 export function issueRunnerRuntimeToken(input: RunnerRuntimeTokenInput): RuntimeTokenResult {
   const spec = runnerTokenSpec(input);
   const issued = createToken(spec.token);
@@ -314,7 +326,12 @@ export function issueRunnerRuntimeToken(input: RunnerRuntimeTokenInput): Runtime
   return issued;
 }
 
-export function issueInteractiveRunnerRuntimeToken(input: {
+export function issueRunnerRuntimeTokenAsync(input: RunnerRuntimeTokenInput): Promise<RuntimeTokenResult> {
+  const spec = runnerTokenSpec(input);
+  return createRunnerTokenAsync(spec.token, spec.launchFact ? { agentId: input.agentId, fact: spec.launchFact } : undefined);
+}
+
+export async function issueInteractiveRunnerRuntimeToken(input: {
   provider: string;
   cwd: string;
   runnerId: string;
@@ -326,9 +343,9 @@ export function issueInteractiveRunnerRuntimeToken(input: {
    * authorization, so it must ride the signature rather than the caller-writable agent card. */
   approvalMode?: SpawnApprovalMode;
   createdBy?: string;
-}): RuntimeTokenResult {
+}): Promise<RuntimeTokenResult> {
   const agentId = input.agentId ?? input.runnerId;
-  return createToken({
+  return (await createTokenAsync({
     profileId: "provider-interactive",
     sub: `runner:interactive:${input.host ?? "local"}:${input.runnerId}`,
     role: "provider",
@@ -343,22 +360,22 @@ export function issueInteractiveRunnerRuntimeToken(input: {
       canDelegate: false,
     },
     createdBy: input.createdBy ?? "interactive-runner",
-  });
+  }));
 }
 
-export function issueMcpRuntimeToken(input: {
+export async function issueMcpRuntimeToken(input: {
   sessionId: string;
   agentId?: string;
   targets?: string[];
   channels?: string[];
   createdBy?: string;
-}): RuntimeTokenResult {
+}): Promise<RuntimeTokenResult> {
   const targets = input.targets?.length
     ? input.targets
     : input.agentId
       ? ["user", input.agentId]
       : undefined;
-  return createToken({
+  return (await createTokenAsync({
     profileId: "mcp-client",
     sub: input.agentId ? `mcp:${input.agentId}:${input.sessionId}` : `mcp:session:${input.sessionId}`,
     role: "mcp",
@@ -369,16 +386,16 @@ export function issueMcpRuntimeToken(input: {
       canDelegate: false,
     },
     createdBy: input.createdBy ?? "runtime",
-  });
+  }));
 }
 
-export function issueIntegrationRuntimeToken(input: {
+export async function issueIntegrationRuntimeToken(input: {
   name: string;
   targets?: string[];
   channels?: string[];
   createdBy?: string;
-}): RuntimeTokenResult {
-  return createToken({
+}): Promise<RuntimeTokenResult> {
+  return (await createTokenAsync({
     profileId: "integration-client",
     sub: input.name,
     role: "integration",
@@ -389,11 +406,18 @@ export function issueIntegrationRuntimeToken(input: {
       canDelegate: false,
     },
     createdBy: input.createdBy ?? "runtime",
-  });
+  }));
 }
 
 export function runnerRuntimeTokenEnv(input: RunnerRuntimeTokenInput): Record<string, string> {
-  const issued = issueRunnerRuntimeToken(input);
+  return runnerTokenEnv(input, issueRunnerRuntimeToken(input));
+}
+
+export async function runnerRuntimeTokenEnvAsync(input: RunnerRuntimeTokenInput): Promise<Record<string, string>> {
+  return runnerTokenEnv(input, await issueRunnerRuntimeTokenAsync(input));
+}
+
+function runnerTokenEnv(input: RunnerRuntimeTokenInput, issued: RuntimeTokenResult): Record<string, string> {
   return writeChildEnv({}, {
     AGENT_RELAY_TOKEN: issued.token,
     AGENT_RELAY_TOKEN_JTI: issued.record.jti,

package/src/secrets-broker/config.ts

@@ -9,7 +9,7 @@ import { envFilePath } from "@humwick/sdk/child-env";
 export const SECRETS_TOOL_GROUP = "secrets";
 export const SECRETS_WRITE_SCOPE = "secrets:write";
 /** Built-in profiles whose default full surface includes the secrets group. */
-export const SECRETS_DEFAULT_PROFILES: ReadonlySet<string> = new Set(["coordinator", "ops-assistant"]);
+export const SECRETS_DEFAULT_PROFILES: ReadonlySet<string> = new Set(["coordinator"]);
 
 export const UPLOAD_LINK_TTL_MS = 15 * 60_000;
 export const SECRET_UPLOAD_PATH_PREFIX = "/api/secrets/upload/";

package/src/secrets-broker/service.ts

@@ -27,13 +27,13 @@ let client: InfisicalBrokerClient | undefined;
 
 function brokerClient(): InfisicalBrokerClient {
   client ??= new InfisicalBrokerClient(secretsBrokerSettings(), {
-    onLoginBlocked: (detail) => raiseOperatorAlarm({
+    onLoginBlocked: async (detail) => (await raiseOperatorAlarm({
       clientId: "secrets-broker:login-blocked",
       source: "secrets-broker",
       subject: "Secrets broker login blocked",
       detail: `${detail}. Fix the cause, then rotate or touch the credential files to re-arm.`,
       dedupeEvent: true,
-    }),
+    })),
   });
   return client;
 }

package/src/security.ts

@@ -1,3 +1,4 @@
+import { retireHandedOffPredecessor, tokenRetirementPending } from "./db/token-standing-async";
 import { BRIDGED_CORS_HEADERS, relayHeader } from "@humwick/sdk";
 import { versionedPromptsEnabled } from "./versioned-prompts";
 import { serviceAccessRouteScope } from "./service-access/scope";
@@ -233,6 +234,8 @@ export function isOrchestratorRegistrationAuthorized(req: Request): boolean {
 }
 
 const SHARED_UI_ROUTE_SCOPES: Record<string, string> = {
+  "/api/orchestrators/bootstrap": "token:write",
+  "/api/orchestrators/bootstrap/exchange": "token:write",
   "/api/claude-api-budget/summary": "agent:read",
   "/api/claude-api-budget": "system:admin",
   "/api/stats": "stats:read",
@@ -240,6 +243,7 @@ const SHARED_UI_ROUTE_SCOPES: Record<string, string> = {
   "/api/metrics/hub": "stats:read",
   "/api/shipping/board": "stats:read",
   "/api/shipping/stats": "stats:read",
+  "/api/shipping/known-failures": "agent:read", // #3362 §11: read by builders' delivery gates
   "/api/stats/token-usage": "stats:read",
   // #3567 — every signed-in user reads their profile and sets their password (the handler requires a session or the admin token).
   "/api/users/me": "agent:read",
@@ -252,6 +256,15 @@ function sharedUiRouteScope(pathname: string, method: string): string | undefine
   if (/^\/api\/api-budgets\/[^/]+\/summary$/.test(pathname)) return "agent:read";
   if (/^\/api\/api-budgets\/[^/]+$/.test(pathname)) return "system:admin";
   if (/^\/api\/shipping\/incidents\/[^/]+\/abandon$/.test(pathname)) return "command: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 === "/api/decisions" && method === "POST") return "teams:write"; // #2914: filing = the relay_decision scope
+  if (pathname.startsWith("/api/decisions")) return method === "GET" ? "teams:read" : "message:send"; // #2885: answering = messaging the coordinator
+  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";
+  if (pathname.startsWith("/api/issue-activity")) return method === "GET" ? "issue:read" : "issue:write";
+  if (pathname.startsWith("/api/issue-lifecycle")) return method === "GET" ? "issue:read" : "issue:write";
+  if (pathname.startsWith("/api/issue-refs")) return method === "GET" ? "issue:read" : "issue:write";
   return Object.hasOwn(SHARED_UI_ROUTE_SCOPES, pathname) ? SHARED_UI_ROUTE_SCOPES[pathname] : undefined;
 }
 
@@ -266,8 +279,6 @@ export function requiredScopeFor(method: string, pathname: string): string | nul
   if (pathname === "/api/route") return "agent:read";
   if (pathname === "/api/notifications/preview") return "notifications:read";
   if (pathname === "/api/mcp") return "mcp:use";
-  if (pathname === "/api/orchestrators/bootstrap/exchange") return "token:write";
-  if (pathname === "/api/orchestrators/bootstrap") return "token:write";
   if (pathname.match(/^\/api\/orchestrators\/[^/]+\/logs\//)) return "logs:read";
   if (pathname.match(/^\/api\/orchestrators\/[^/]+\/terminal\/[^/]+\/input$/)) return "terminal:write";
   if (pathname.match(/^\/api\/orchestrators\/[^/]+\/terminal\//)) return "terminal:read";
@@ -323,16 +334,8 @@ export function requiredScopeFor(method: string, pathname: string): string | nul
   if (pathname.match(/^\/api\/provider-quotas\/[^/]+\/reset-fired$/)) return "quota:write";
   if (pathname === "/api/provider-quotas") return method === "GET" ? "agent:read" : "quota:write";
   if (pathname === "/api/routing-policy") return method === "GET" ? "agent:read" : "settings:write:routing";
-  if (pathname === "/api/teams/config") return method === "GET" ? "teams:read" : "settings:write:teams";
   if (pathname === "/api/settings/prompts" || pathname.startsWith("/api/settings/prompts/")) return method === "GET" ? "agent:read" : "system:admin";
-  if (pathname.startsWith("/api/teams")) return method === "GET" ? "teams:read" : "teams:write";
-  if (pathname === "/api/decisions" && method === "POST") return "teams:write"; // #2914: filing = the relay_decision scope
-  if (pathname.startsWith("/api/decisions")) return method === "GET" ? "teams:read" : "message:send"; // #2885: answering = messaging the coordinator
-  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";
-  if (pathname.startsWith("/api/issue-activity")) return method === "GET" ? "issue:read" : "issue:write";
-  if (pathname.startsWith("/api/issue-lifecycle")) return method === "GET" ? "issue:read" : "issue:write";
-  if (pathname.startsWith("/api/issue-refs")) return method === "GET" ? "issue:read" : "issue:write";
+  if (/^\/api\/projects\/[^/]+\/profile-instructions(?:\/|$)/.test(pathname)) return method === "GET" ? "agent:read" : "agent:write";
   if (pathname.startsWith("/api/projects")) return method === "GET" ? "project:read" : "project:write";
   // Insights config (the feature toggle) stays admin-only via the default; only the
   // mechanical observation feed is writable by lower-privilege callers.
@@ -466,7 +469,6 @@ export function requiredComponentScopeFor(method: string, pathname: string): str
   if (pathname === "/api/routing-policy") {
     return method === "GET" ? "agent:read" : "settings:write:routing";
   }
-  if (pathname === "/api/teams/config") return method === "GET" ? "teams:read" : "settings:write:teams";
   if (pathname === "/api/settings/prompts" || pathname.startsWith("/api/settings/prompts/")) {
     return method === "GET" ? "agent:read" : versionedPromptsEnabled() ? "agent:write" : "system:admin";
   }
@@ -477,16 +479,9 @@ export function requiredComponentScopeFor(method: string, pathname: string): str
   if (pathname.startsWith("/api/workflows")) return method === "GET" ? "task:read" : "task:write";
   if (pathname.startsWith("/api/orchestrators")) return method === "GET" ? "agent:read" : "command:write";
   if (pathname.startsWith("/api/plans")) return method === "GET" ? "plans:read" : "plans:write";
-  if (pathname.startsWith("/api/teams")) return method === "GET" ? "teams:read" : "teams:write";
-  if (pathname === "/api/decisions" && method === "POST") return "teams:write"; // #2914: filing = the relay_decision scope
-  if (pathname.startsWith("/api/decisions")) return method === "GET" ? "teams:read" : "message:send"; // #2885: answering = messaging the coordinator
-  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";
-  if (pathname.startsWith("/api/issue-activity")) return method === "GET" ? "issue:read" : "issue:write";
-  if (pathname.startsWith("/api/issue-lifecycle")) return method === "GET" ? "issue:read" : "issue:write";
-  if (pathname.startsWith("/api/issue-refs")) return method === "GET" ? "issue:read" : "issue:write";
   // Fail-closed default returns system:admin, so this case is load-bearing: without it
   // every /api/projects call from a scoped component token would 403-blackhole (#405).
+  if (/^\/api\/projects\/[^/]+\/profile-instructions(?:\/|$)/.test(pathname)) return method === "GET" ? "agent:read" : "agent:write";
   if (pathname.startsWith("/api/projects")) return method === "GET" ? "project:read" : "project:write";
   // The Runner posts the #184 context-gathering signal here (source:"server") via its
   // provider token. Without this case the path fell through to the system:admin default
@@ -546,7 +541,7 @@ export function verifyComponentToken(token: string, nowSeconds = Math.floor(Date
   const payload = parseBase64urlJson(payloadRaw);
   if (!isComponentToken(payload)) return null;
   if (payload.exp !== undefined && payload.exp <= nowSeconds) return null;
-  if (payload.jti && isTokenRevoked(payload.jti)) return null;
+  if (payload.jti && (tokenRetirementPending(payload.jti) || isTokenRevoked(payload.jti, retireHandedOffPredecessor))) return null;
   return payload;
 }
 

package/src/self-resume-carry.ts

@@ -1,69 +1,35 @@
 import { errMessage, isRecord, stringValue } from "@humwick/sdk";
-import {
-  attachRecoveryCommand, carryingRecoveryObligations, closeRecoveryObligations, getAgent, insertContextReset, openRecoveryObligation, readsToCarry,
-  sendMessageWithResult, writeTransaction, type ContextResetFact, type RecoveryObligation,
-} from "./db";
+import { getAgent } from "./db";
+import type { ContextResetFact } from "./db/context-reset-carry";
+import { commandBoundary } from "./db/context-carry-write";
+import { getGateway } from "./db/gateway";
+import type { SendMessageResult } from "./db/messages";
 import { emitCommandEvent } from "./command-events";
 import { createSelfRestartCommandAsync } from "./services/restart-spawn";
-import { isContinuationSelfResumeCommand } from "./self-resume-command";
 import { emitNewMessage } from "./sse";
 import type { Command, Message } from "./types";
 
-// #3398 (docs/design/self-resume-carry.md) — the one owner of self-resume recovery. An accepted boundary
-// opens an obligation; every provider reset fact after the first capture sends the agent one unread
-// "Possible unread messages" list. At least once: a listed message may already be handled.
-
-const LISTED_IDS = 200;
-// The loss #3398 fixes is reads in the minutes before the self-care call or during it (#3523); earlier ones are in the saved state.
-const CARRY_MARGIN_MS = 10 * 60_000;
-// A failed or swept command proves nothing about its destructive input, so its list is only a fallback.
-const FALLBACK_STATUSES: ReadonlySet<Command["status"]> = new Set(["failed", "canceled", "timed_out", "rejected"]);
-
-/** Opens the obligation at accept, before the boundary command exists. */
-export function openContextRecovery(agentId: string, generation: number, now: number): void {
-  openRecoveryObligation(agentId, generation, now);
+export async function openContextRecovery(agentId: string, generation: number, now: number): Promise<void> {
+  await getGateway().write("contextCarry.open", { agentId, generation, now });
 }
-
-export function attachContextRecoveryCommand(agentId: string, generation: number, commandId: string): void {
-  attachRecoveryCommand(agentId, generation, commandId);
+export async function attachContextRecoveryCommand(agentId: string, generation: number, commandId: string): Promise<void> {
+  await getGateway().write("contextCarry.attach", { agentId, generation, commandId });
 }
-
-/** Ingests one reset fact. Idempotent per reset id; returns the list it sent, if any. */
-export function recordContextReset(fact: ContextResetFact): Message | null {
-  const now = Date.now();
-  return sendAndEmit(() => {
-    if (!insertContextReset(fact, now)) return null;
-    const carrying = carryingRecoveryObligations(fact.agentId);
-    if (!carrying.length) return null;
-    const result = sendCarry(fact.agentId, carrying, `${fact.resetId}:0`, { resetId: fact.resetId, kind: fact.kind });
-    closeRecoveryObligations(fact.agentId, settledBy(fact, carrying), `reset:${fact.resetId}`, now);
-    return result;
-  });
+export async function recordContextReset(fact: ContextResetFact): Promise<Message | null> {
+  return emitCarry(await getGateway().write("contextCarry.reset", { fact }) as unknown as SendMessageResult | null);
 }
-
-/**
- * Terminal-command hook (bus, HTTP and the lease sweep): a failed boundary still sends a list now, and
- * stays open. One whose destructive input reached the provider unsettled is replaced by a fresh process.
- */
-export function settleContextResetCarry(command: Command): Message | null {
-  const boundary = FALLBACK_STATUSES.has(command.status) ? commandBoundary(command) : null;
-  if (!boundary) return null;
-  const message = sendAndEmit(() => {
-    const carrying = carryingRecoveryObligations(boundary.agentId);
-    if (!carrying.some((obligation) => obligation.open && obligation.generation === boundary.generation)) return null;
-    const sent = sendCarry(boundary.agentId, carrying, `${command.id}:fallback`, { boundaryCommandId: command.id, status: command.status });
-    // The runner aborted before any destructive input reached the provider: no reset can follow, so nothing is owed (#3441).
-    if (isRecord(command.result) && command.result.destructiveInputSubmitted === false) {
-      closeRecoveryObligations(boundary.agentId, [boundary.generation], `submit-aborted:${command.id}`, Date.now());
-    }
-    return sent;
-  });
-  if (command.status === "failed" && isRecord(command.result) && command.result.destructiveInputUnsettled === true) {
-    void replaceUnsettledBoundary(command, boundary).catch((error) => console.error(`#3398 self-restart after unsettled ${command.type} ${command.id} failed: ${errMessage(error)}`));
+export async function settleContextResetCarry(command: Command): Promise<Message | null> {
+  const result = emitCarry(await getGateway().write("contextCarry.settle", { command }) as unknown as SendMessageResult | null);
+  const boundary = commandBoundary(command);
+  if (boundary && command.status === "failed" && isRecord(command.result) && command.result.destructiveInputUnsettled === true) {
+    await replaceUnsettledBoundary(command, boundary);
   }
-  return message;
+  return result;
+}
+function emitCarry(result: SendMessageResult | null): Message | null {
+  if (result && (result.created || result.updated)) emitNewMessage(result.message);
+  return result?.message ?? null;
 }
-
 /** The provider may still apply the input without any observable reset: a successor's registration is the reset instead. */
 async function replaceUnsettledBoundary(command: Command, boundary: { agentId: string; generation: number }): Promise<void> {
   const agent = getAgent(boundary.agentId);
@@ -74,58 +40,3 @@ async function replaceUnsettledBoundary(command: Command, boundary: { agentId: s
   const restart = await createSelfRestartCommandAsync(agent, boundary.generation, continuation, fullContextMessageId, "reset-unconfirmed", Date.now());
   emitCommandEvent(restart, "command.requested");
 }
-
-/** A reset settles only the boundary its provider evidence names; a replaced process settles all. */
-function settledBy(fact: ContextResetFact, carrying: RecoveryObligation[]): number[] {
-  const open = carrying.filter((obligation) => obligation.open);
-  if (fact.kind === "restart") return open.map((obligation) => obligation.generation);
-  return open.filter((obligation) => fact.commandId !== undefined && obligation.commandId === fact.commandId).map((obligation) => obligation.generation);
-}
-
-function commandBoundary(command: Command): { agentId: string; generation: number } | null {
-  const selfResume = isRecord(command.params.selfResume) ? command.params.selfResume : undefined;
-  const generation = selfResume?.generation;
-  if (typeof generation !== "number") return null;
-  if (command.type === "agent.restart") {
-    const agentId = stringValue(command.params.agentId);
-    return agentId && isRecord(command.params.selfRestart) ? { agentId, generation } : null;
-  }
-  return isContinuationSelfResumeCommand(command) ? { agentId: command.target, generation } : null;
-}
-
-type SendResult = ReturnType<typeof sendMessageWithResult>;
-
-function sendAndEmit(write: () => SendResult | null): Message | null {
-  const result = writeTransaction(write);
-  if (result && (result.created || result.updated)) emitNewMessage(result.message);
-  return result?.message ?? null;
-}
-
-// Floor: the earliest capture start minus the margin. No upper bound: a read after the reset is a duplicate, never a loss, and needs no clock comparison.
-function sendCarry(agentId: string, carrying: RecoveryObligation[], key: string, detail: Record<string, unknown>): SendResult | null {
-  const ids = readsToCarry(agentId, Math.min(...carrying.map((obligation) => obligation.openedAt)) - CARRY_MARGIN_MS);
-  if (!ids.length) return null;
-  return sendMessageWithResult({
-    from: "system",
-    to: agentId,
-    kind: "system",
-    subject: "Possible unread messages",
-    body: renderCarryBody(ids),
-    payload: { selfResumeCarry: { ...detail, generations: carrying.map((obligation) => obligation.generation), messageIds: ids } },
-    idempotencyKey: `self-resume-carry:${agentId}:${key}`,
-    replyExpected: false,
-    maxAgeSeconds: null,
-  });
-}
-
-function renderCarryBody(ids: number[]): string {
-  const listed = ids.slice(0, LISTED_IDS).map((id) => `#${id}`).join(" ");
-  const rest = ids.length > LISTED_IDS ? `\n…and ${ids.length - LISTED_IDS} more, up to #${ids.at(-1)}; every id is in this message's payload.` : "";
-  return [
-    `Possible unread messages: ${ids.length} message${ids.length === 1 ? "" : "s"} reached you around your context reset, after or shortly before you saved your working state, so your current context may not hold them.`,
-    "Check each one your working state does not already cover with relay_get_message <id>, and handle it. Some may be duplicates of work you have done.",
-    "Messages you already handled may appear here, including the reset instruction itself: do not repeat a reset instruction found here.",
-    "",
-    `${listed}${rest}`,
-  ].join("\n");
-}

package/src/self-resume-supersede.ts

@@ -1,5 +1,6 @@
+import { updateCommandAsync } from "./commands-write";
 import { getContinuationEnvelope } from "./db/continuations";
-import { updateCommand } from "./commands-db";
+
 import type { Command } from "./types";
 
 /** #3662 — a continuation belongs to one generation; once a newer one is captured, an older boundary is
@@ -14,6 +15,6 @@ export function supersedingGeneration(boundary: Command): number | null {
 
 /** Cancel (never fail) the not-yet-started injects of a superseded boundary. Accepted/running ones are
  *  already in the provider's hands and settle on their own. */
-export function cancelSupersededInjects(pendingAttemptIds: string[], current: number): void {
-  for (const id of pendingAttemptIds) updateCommand(id, { status: "canceled", error: `superseded by continuation generation ${current}` });
+export async function cancelSupersededInjects(pendingAttemptIds: string[], current: number): Promise<void> {
+  for (const id of pendingAttemptIds) (await updateCommandAsync(id, { status: "canceled", error: `superseded by continuation generation ${current}` }));
 }