agent-relay-server 0.120.1 → 0.120.3

package/src/db/provider-quotas.ts

@@ -125,10 +125,15 @@ function supersededAccountKeys(provider: string, accountKey: string, rawAccountK
   return [...candidates];
 }
 
+// Source priority for quota precedence: "ingest" (WHAM/API) beats "probe" (agent self-report).
+const QUOTA_SOURCE_PRIORITY: Record<string, number> = { ingest: 3, header: 2, probe: 1, statusline: 0, emulated: -1 };
+function quotaSourcePriority(source: string): number { return QUOTA_SOURCE_PRIORITY[source] ?? 1; }
+
 function newestQuotaState(rows: ProviderQuotaRow[]): string | null {
+  const priority = (candidate: ProviderQuotaRow) => { const source = parseJson<Partial<QuotaState>>(candidate.quota_state, { source: "probe" }).source; return quotaSourcePriority(typeof source === "string" ? source : "probe"); };
   const row = rows
     .filter((candidate) => candidate.quota_state)
-    .sort((a, b) => (b.last_updated_at ?? 0) - (a.last_updated_at ?? 0))[0];
+    .sort((a, b) => priority(b) - priority(a) || (b.last_updated_at ?? 0) - (a.last_updated_at ?? 0))[0];
   return row?.quota_state ?? null;
 }
 
@@ -285,12 +290,6 @@ function storedQuotaWindowSampleTimes(quota: StoredQuotaState): Map<string, numb
   return times;
 }
 
-// Source priority for per-window precedence: "ingest" (WHAM/API) beats "probe" (agent self-report).
-const QUOTA_SOURCE_PRIORITY: Record<string, number> = { ingest: 3, header: 2, probe: 1, statusline: 0, emulated: -1 };
-function quotaSourcePriority(source: string): number {
-  return QUOTA_SOURCE_PRIORITY[source] ?? 1;
-}
-
 function storedQuotaWindowSources(quota: StoredQuotaState): Map<string, string> {
   const sources = new Map<string, string>();
   const rawSources = quota._windowSource && typeof quota._windowSource === "object" ? quota._windowSource : {};

package/src/db/schema.ts

@@ -91,7 +91,7 @@ import type {
 export function initDb(path: string = "agent-relay.db"): Database {
   const conn = new Database(path, { create: true });
   applyConnectionPragmas(conn);
-  setDb(conn);
+  setDb(conn, path);
 
   getDb().run(`
     CREATE TABLE IF NOT EXISTS agents (
@@ -165,6 +165,7 @@ export function initDb(path: string = "agent-relay.db"): Database {
     -- resolved_to_agent ALTER — never inline here (same hazard as #483/#559).
     -- idx_msg_reply_to is also migration-owned because reply_to was added by ALTER.
     CREATE INDEX IF NOT EXISTS idx_msg_to_id ON messages(to_target, id);
+    CREATE INDEX IF NOT EXISTS idx_msg_from_id ON messages(from_agent, id);
     CREATE INDEX IF NOT EXISTS idx_msg_created ON messages(created_at);
     CREATE INDEX IF NOT EXISTS idx_msg_channel ON messages(channel);
     CREATE TABLE IF NOT EXISTS scheduled_timers (

package/src/maintenance/jobs.ts

@@ -13,14 +13,14 @@ import {
   listStaleQueuedDirectTargets,
   pruneOrphanedSharedWorkspaces,
   pruneOfflineAgents,
-  pruneOldMessages,
+  pruneOldMessagesAsync,
   pruneProviderQuotaHistory,
   reapStaleAgents,
   reapStaleOrchestrators,
   releaseExpiredClaims,
   releaseExpiredDriveLeases,
   releaseOrphanedTasks,
-  runDbMaintenance,
+  runDbMaintenanceAsync,
   sweepArtifacts,
 } from "../db";
 import { isAgentUnavailable } from "../db/agent-predicates";
@@ -72,6 +72,10 @@ import type { MaintenanceJobDefinition } from "./types";
 
 let dbMaintenanceRuns = 0;
 
+function isFleetIdleForVacuum(): boolean {
+  return !listAgents({ status: "busy" }).some((agent) => agent.kind === "provider" && agent.id !== "user" && agent.id !== "system");
+}
+
 function isManagedBusyWatchCandidate(agent: ReturnType<typeof listAgents>[number]): boolean {
   if (agent.kind !== "provider") return false;
   if (agent.status !== "busy") return false;
@@ -315,17 +319,17 @@ export const definitions: MaintenanceJobDefinition[] = [
     description: "Stop spawned sessions whose relay agent is offline/gone but whose process the orchestrator still reports running, after a grace period for self-heal.",
     intervalMs: ORPHAN_REAPER_INTERVAL_MS,
     runOnStart: false,
-    handler: reapOrphanedSessions,
+    handler: () => reapOrphanedSessions(),
   },
-  { id: "transient-agent-reaper", title: "Transient agent reaper", description: "Cleanly shut down transient spawned agents once they are idle and any isolated branch work has landed.", intervalMs: REAP_INTERVAL_MS, runOnStart: false, handler: reapTransientAgents },
-  { id: "rate-limit-resume", title: "Rate-limit resume", description: "Auto-resume agents held on a provider usage/rate-limit stall once their reset window has passed (#286).", intervalMs: REAP_INTERVAL_MS, runOnStart: false, handler: resumeRateLimitedAgents },
+  { id: "transient-agent-reaper", title: "Transient agent reaper", description: "Cleanly shut down transient spawned agents once they are idle and any isolated branch work has landed.", intervalMs: REAP_INTERVAL_MS, runOnStart: false, handler: () => reapTransientAgents() },
+  { id: "rate-limit-resume", title: "Rate-limit resume", description: "Auto-resume agents held on a provider usage/rate-limit stall once their reset window has passed (#286).", intervalMs: REAP_INTERVAL_MS, runOnStart: false, handler: () => resumeRateLimitedAgents() },
   {
     id: "stuck-busy-watchdog",
     title: "Stuck busy watchdog",
     description: "Warn when a managed provider stays busy past the threshold without provider progress (#53).",
     intervalMs: REAP_INTERVAL_MS,
     runOnStart: false,
-    handler: runStuckBusyWatchdog,
+    handler: () => runStuckBusyWatchdog(),
   },
   {
     id: "team-reap",
@@ -341,7 +345,7 @@ export const definitions: MaintenanceJobDefinition[] = [
     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,
+    handler: () => runTeamIdleWatchdog(),
   },
   {
     id: "orchestrator-reaper",
@@ -373,9 +377,9 @@ export const definitions: MaintenanceJobDefinition[] = [
     description: "Delete messages outside the configured retention window.",
     intervalMs: DAY_MS,
     runOnStart: false,
-    handler() {
+    handler(context) {
       const retentionDays = Number(process.env.RETENTION_DAYS) || 30;
-      return { prunedMessages: pruneOldMessages(retentionDays * DAY_MS) };
+      return pruneOldMessagesAsync(retentionDays * DAY_MS, { signal: context?.signal });
     },
   },
   {
@@ -385,10 +389,12 @@ export const definitions: MaintenanceJobDefinition[] = [
     intervalMs: DB_MAINTENANCE_INTERVAL_MS,
     runOnStart: false,
     timeoutMs: 5 * 60 * 1000,
-    handler() {
+    async handler(context) {
       dbMaintenanceRuns += 1;
-      const vacuum = DB_VACUUM_EVERY > 0 && dbMaintenanceRuns % DB_VACUUM_EVERY === 0;
-      return runDbMaintenance({ vacuum });
+      const vacuumDue = DB_VACUUM_EVERY > 0 && dbMaintenanceRuns % DB_VACUUM_EVERY === 0;
+      const vacuum = vacuumDue && isFleetIdleForVacuum();
+      const result = await runDbMaintenanceAsync({ vacuum, signal: context?.signal });
+      return vacuumDue && !vacuum ? { ...result, vacuumSkipped: "fleet-busy" } : result;
     },
   },
   {
@@ -492,7 +498,7 @@ export const definitions: MaintenanceJobDefinition[] = [
     intervalMs: 60 * 1000,
     runOnStart: false,
     timeoutMs: 10 * 1000,
-    handler: runAutoMergeWatchdog,
+    handler: () => runAutoMergeWatchdog(),
   },
   {
     id: "workspace-idle-refresh",

package/src/maintenance/scheduler.ts

@@ -118,8 +118,9 @@ async function runJob(definition: MaintenanceJobDefinition, options: { force?: b
     return { id: definition.id, status: "skipped", startedAt, finishedAt: Date.now(), durationMs: 0, result: { reason: "not due or already running", state } };
   }
 
+  const abortController = new AbortController();
   try {
-    const result = await withTimeout(Promise.resolve(definition.handler()), timeoutMs);
+    const result = await withTimeout(Promise.resolve(definition.handler({ signal: abortController.signal })), timeoutMs, abortController);
     const finishedAt = Date.now();
     const durationMs = finishedAt - startedAt;
     db.query(`
@@ -145,10 +146,14 @@ async function runJob(definition: MaintenanceJobDefinition, options: { force?: b
   }
 }
 
-async function withTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T> {
+async function withTimeout<T>(promise: Promise<T>, timeoutMs: number, abortController?: AbortController): Promise<T> {
   let timeout: Timer | undefined;
   const timeoutPromise = new Promise<never>((_, reject) => {
-    timeout = setTimeout(() => reject(new Error(`maintenance job timed out after ${timeoutMs}ms`)), timeoutMs);
+    timeout = setTimeout(() => {
+      const error = new Error(`maintenance job timed out after ${timeoutMs}ms`);
+      abortController?.abort(error);
+      reject(error);
+    }, timeoutMs);
   });
   try {
     return await Promise.race([promise, timeoutPromise]);

package/src/maintenance/types.ts

@@ -1,5 +1,9 @@
 import type { MaintenanceJob } from "../types";
 
+export interface MaintenanceJobContext {
+  signal: AbortSignal;
+}
+
 export interface MaintenanceJobDefinition {
   id: string;
   title: string;
@@ -7,7 +11,7 @@ export interface MaintenanceJobDefinition {
   intervalMs: number;
   timeoutMs?: number;
   runOnStart?: boolean;
-  handler: () => Promise<Record<string, unknown>> | Record<string, unknown>;
+  handler: (context?: MaintenanceJobContext) => Promise<Record<string, unknown>> | Record<string, unknown>;
 }
 
 export interface MaintenanceJobRow {

package/src/mcp/index.ts

@@ -167,11 +167,11 @@ async function callTool(auth: McpAuthContext, params: unknown): Promise<Record<s
     else if (name === "relay_agent_action") result = relayAgentAction(auth, args);
     else if (name === "relay_workspace_status") result = await relayWorkspaceStatus(auth, args);
     else if (name === "relay_workspace_list") result = relayWorkspaceList(auth, args);
-    else if (name === "relay_workspace_ready") result = relayWorkspaceMutation(auth, "ready", args);
-    else if (name === "relay_workspace_deps") result = relayWorkspaceMutation(auth, "deps-refresh", args);
-    else if (name === "relay_workspace_claim") result = relayWorkspaceMutation(auth, "claim", args);
-    else if (name === "relay_workspace_release") result = relayWorkspaceMutation(auth, "release-claim", args);
-    else if (name === "relay_workspace_land") result = relayWorkspaceMutation(auth, "merge", args);
+    else if (name === "relay_workspace_ready") result = await relayWorkspaceMutation(auth, "ready", args);
+    else if (name === "relay_workspace_deps") result = await relayWorkspaceMutation(auth, "deps-refresh", args);
+    else if (name === "relay_workspace_claim") result = await relayWorkspaceMutation(auth, "claim", args);
+    else if (name === "relay_workspace_release") result = await relayWorkspaceMutation(auth, "release-claim", args);
+    else if (name === "relay_workspace_land") result = await relayWorkspaceMutation(auth, "merge", args);
     else if (name.startsWith("relay_merge_")) result = relayMergeTool(auth, name, args); else if (name.startsWith("relay_team_")) result = await relayTeamTool(auth, name, args);
     else if (name.startsWith("relay_plan_")) result = relayPlanTool(auth, name, args);
     else if (name.startsWith("relay_task_memory_")) result = relayTaskMemoryTool(auth, name, args);

package/src/mcp/tools-workspace.ts

@@ -4,6 +4,7 @@ import { McpAuthError, McpNotFoundError } from "../mcp-errors";
 import { AUTO_MERGE_POLICIES } from "../workspace-merge";
 import { describeWorkspacePhase, landReceipt, readyContract } from "../workspace-phase";
 import { LAND_STRATEGIES, applyWorkspaceAction, waitForWorkspaceStatus, type WorkspaceAction } from "../workspace-actions";
+import { refreshWorkspaceGitState } from "../workspace-probe";
 import { optionalEnum } from "../validation";
 import type { Command, WorkspaceAutoMergePolicy, WorkspaceMergeStrategy, WorkspaceRecord } from "../types";
 import type { McpAuthContext, ToolDefinition } from "./types";
@@ -185,9 +186,13 @@ export function relayWorkspaceList(auth: McpAuthContext, args: Record<string, un
   return { workspaces, count: workspaces.length };
 }
 
-export function relayWorkspaceMutation(auth: McpAuthContext, action: WorkspaceAction, args: Record<string, unknown>): Record<string, unknown> {
-  const ws = resolveWorkspaceForCaller(auth, args);
-  const result = applyWorkspaceAction(ws, {
+export async function relayWorkspaceMutation(auth: McpAuthContext, action: WorkspaceAction, args: Record<string, unknown>): Promise<Record<string, unknown>> {
+  let ws = resolveWorkspaceForCaller(auth, args);
+  if (action === "ready" || action === "request-review") {
+    await refreshWorkspaceGitState(ws);
+    ws = getWorkspace(ws.id) ?? ws;
+  }
+  const result = await applyWorkspaceAction(ws, {
     action,
     agentId: callerAgentId(auth) ?? auth.actor,
     detail: optionalString(args.detail, "detail", 4000),

package/src/routes/orchestrator-proxy.ts

@@ -6,6 +6,7 @@ import { cleanStringArray } from "../validation";
 import { emitOrchestratorStatus } from "../sse";
 import { type OrchestratorRuntimeInput, type SpawnProvider } from "../types";
 import { relayToken } from "../config";
+import { isTerminalSessionRequestAuthorized } from "../terminal-authz";
 
 export const getOrchestratorDirectories: Handler = async (req, params) => {
   const orch = getOrchestrator(params.id!);
@@ -146,16 +147,16 @@ export const getOrchestratorLogs: Handler = (req, params) => {
 };
 
 export const getOrchestratorTerminal: Handler = (req, params) => {
-  const denied = authorizeRoute(req, { scope: "terminal:attach", resource: { orchestratorId: params.id!, terminalAttach: true } });
-  return denied ?? proxyOrchestratorGet(req, params.id!, `/api/terminal/${encodeURIComponent(params.session!)}`);
+  if (!isTerminalSessionRequestAuthorized(req, params.id!, params.session!, "read")) return error("forbidden", 403);
+  return proxyOrchestratorGet(req, params.id!, `/api/terminal/${encodeURIComponent(params.session!)}`);
 };
 
 export const postOrchestratorTerminalInput: Handler = (req, params) => {
-  const denied = authorizeRoute(req, { scope: "terminal:attach", resource: { orchestratorId: params.id!, terminalAttach: true } });
-  return denied ?? proxyOrchestratorPost(req, params.id!, `/api/terminal/${encodeURIComponent(params.session!)}/input`);
+  if (!isTerminalSessionRequestAuthorized(req, params.id!, params.session!, "write")) return error("forbidden", 403);
+  return proxyOrchestratorPost(req, params.id!, `/api/terminal/${encodeURIComponent(params.session!)}/input`);
 };
 
 export const postOrchestratorTerminalResize: Handler = (req, params) => {
-  const denied = authorizeRoute(req, { scope: "terminal:attach", resource: { orchestratorId: params.id!, terminalAttach: true } });
-  return denied ?? proxyOrchestratorPost(req, params.id!, `/api/terminal/${encodeURIComponent(params.session!)}/resize`);
+  if (!isTerminalSessionRequestAuthorized(req, params.id!, params.session!, "read")) return error("forbidden", 403);
+  return proxyOrchestratorPost(req, params.id!, `/api/terminal/${encodeURIComponent(params.session!)}/resize`);
 };

package/src/routes/sse.ts

@@ -5,5 +5,6 @@ import { type Handler } from "./_shared";
 export const getEvents: Handler = (req) => {
   const url = new URL(req.url);
   const agentId = url.searchParams.get("for") || null;
-  return createSSEStream(agentId);
+  const lastEventId = Number(req.headers.get("last-event-id") ?? "");
+  return createSSEStream(agentId, Number.isSafeInteger(lastEventId) && lastEventId > 0 ? lastEventId : 0);
 };

package/src/routes/tasks.ts

@@ -29,6 +29,15 @@ function taskDetailOr404(id: number) {
   return detail ? json(detail) : error("deliverable task not found", 404);
 }
 
+function requireTaskMutationAuth(req: Request, id: number): Response | null {
+  if (!getTaskEntity(id)) return error("deliverable task not found", 404);
+  if (isFullReachRequest(req)) return null;
+  const component = getComponentAuth(req);
+  const agentId = component ? agentIdFromComponent(component) : undefined;
+  if (!isTaskReadAuthorized(id, agentId, component?.scope ?? [])) return error("forbidden", 403);
+  return null;
+}
+
 function normalizeTaskStatusInput(body: unknown): TaskStatusInput {
   if (!isRecord(body)) throw new ValidationError("JSON object body required");
   const status = optionalEnum(body.status, "status", VALID_TASK_STATUSES);
@@ -173,6 +182,8 @@ export const getTaskHistoryRoute: Handler = (req, params) => {
 export const patchTaskEntity: Handler = async (req, params) => {
   const id = parseId(params.id);
   if (id === null) return error("invalid task id");
+  const forbidden = requireTaskMutationAuth(req, id);
+  if (forbidden) return forbidden;
   const parsed = await parseBody<Record<string, unknown>>(req);
   if (!parsed.ok) return error(parsed.error, parsed.status);
   const body = parsed.body;
@@ -200,6 +211,8 @@ export const patchTaskEntity: Handler = async (req, params) => {
 export const postTaskEntityStatus: Handler = async (req, params) => {
   const id = parseId(params.id);
   if (id === null) return error("invalid task id");
+  const forbidden = requireTaskMutationAuth(req, id);
+  if (forbidden) return forbidden;
   const parsed = await parseBody<Record<string, unknown>>(req);
   if (!parsed.ok) return error(parsed.error, parsed.status);
   const body = parsed.body;
@@ -220,6 +233,8 @@ export const postTaskEntityStatus: Handler = async (req, params) => {
 export const postTaskEntityStage: Handler = async (req, params) => {
   const id = parseId(params.id);
   if (id === null) return error("invalid task id");
+  const forbidden = requireTaskMutationAuth(req, id);
+  if (forbidden) return forbidden;
   const parsed = await parseBody<Record<string, unknown>>(req);
   if (!parsed.ok) return error(parsed.error, parsed.status);
   const body = parsed.body;
@@ -240,6 +255,8 @@ export const postTaskEntityStage: Handler = async (req, params) => {
 export const postTaskEntityGate: Handler = async (req, params) => {
   const id = parseId(params.id);
   if (id === null) return error("invalid task id");
+  const forbidden = requireTaskMutationAuth(req, id);
+  if (forbidden) return forbidden;
   const parsed = await parseBody<Record<string, unknown>>(req);
   if (!parsed.ok) return error(parsed.error, parsed.status);
   const body = parsed.body;
@@ -261,6 +278,8 @@ export const postTaskEntityGate: Handler = async (req, params) => {
 export const postTaskDependency: Handler = async (req, params) => {
   const id = parseId(params.id);
   if (id === null) return error("invalid task id");
+  const forbidden = requireTaskMutationAuth(req, id);
+  if (forbidden) return forbidden;
   const parsed = await parseBody<{ dependsOnTaskId?: number }>(req);
   if (!parsed.ok) return error(parsed.error, parsed.status);
   const dep = parseId(String(parsed.body?.dependsOnTaskId));
@@ -276,6 +295,8 @@ export const postTaskDependency: Handler = async (req, params) => {
 export const deleteTaskDependency: Handler = async (req, params) => {
   const id = parseId(params.id);
   if (id === null) return error("invalid task id");
+  const forbidden = requireTaskMutationAuth(req, id);
+  if (forbidden) return forbidden;
   const parsed = await parseBody<{ dependsOnTaskId?: number }>(req);
   if (!parsed.ok) return error(parsed.error, parsed.status);
   const dep = parseId(String(parsed.body?.dependsOnTaskId));
@@ -287,6 +308,8 @@ export const deleteTaskDependency: Handler = async (req, params) => {
 export const postTaskRef: Handler = async (req, params) => {
   const id = parseId(params.id);
   if (id === null) return error("invalid task id");
+  const forbidden = requireTaskMutationAuth(req, id);
+  if (forbidden) return forbidden;
   const parsed = await parseBody<Record<string, unknown>>(req);
   if (!parsed.ok) return error(parsed.error, parsed.status);
   const body = parsed.body;
@@ -308,6 +331,8 @@ export const postTaskRef: Handler = async (req, params) => {
 export const deleteTaskRef: Handler = async (req, params) => {
   const id = parseId(params.id);
   if (id === null) return error("invalid task id");
+  const forbidden = requireTaskMutationAuth(req, id);
+  if (forbidden) return forbidden;
   const parsed = await parseBody<Record<string, unknown>>(req);
   if (!parsed.ok) return error(parsed.error, parsed.status);
   const body = parsed.body;
@@ -328,6 +353,8 @@ export const deleteTaskRef: Handler = async (req, params) => {
 export const postTaskAssign: Handler = async (req, params) => {
   const id = parseId(params.id);
   if (id === null) return error("invalid task id");
+  const forbidden = requireTaskMutationAuth(req, id);
+  if (forbidden) return forbidden;
   const parsed = await parseBody<Record<string, unknown>>(req);
   if (!parsed.ok) return error(parsed.error, parsed.status);
   const body = parsed.body;
@@ -345,6 +372,8 @@ export const postTaskAssign: Handler = async (req, params) => {
 export const postTaskComment: Handler = async (req, params) => {
   const id = parseId(params.id);
   if (id === null) return error("invalid task id");
+  const forbidden = requireTaskMutationAuth(req, id);
+  if (forbidden) return forbidden;
   const parsed = await parseBody<Record<string, unknown>>(req);
   if (!parsed.ok) return error(parsed.error, parsed.status);
   const body = parsed.body;

package/src/routes/workspaces.ts

@@ -16,6 +16,7 @@ import { workspaceActiveClaim } from "../workspace-claim";
 import { resolveCoordinatorAgentId } from "../steward-identity";
 import { relayToken } from "../config";
 import { workspaceOwnerOrchestrator } from "../workspace-host";
+import { refreshWorkspaceGitState } from "../workspace-probe";
 
 export const getWorkspaces: Handler = (req) => {
   try {
@@ -423,7 +424,7 @@ export const postWorkspaceAction: Handler = async (req, params) => {
   if (!parsed.ok) return error(parsed.error, parsed.status);
   try {
     if (!isRecord(parsed.body)) return error("body required");
-    const workspace = getWorkspace(params.id!);
+    let workspace = getWorkspace(params.id!);
     if (!workspace) return error("workspace not found", 404);
     const action = optionalEnum(parsed.body.action, "action", WORKSPACE_ACTIONS);
     if (!action) return error("action required", 400);
@@ -464,7 +465,13 @@ export const postWorkspaceAction: Handler = async (req, params) => {
     // Everything else delegates to the shared core (one home, shared with the
     // relay_workspace_* MCP tools); the core self-audits and returns any command to
     // emit, mirroring requestWorkspaceMerge's "caller emits" contract.
-    const result = applyWorkspaceAction(workspace, {
+    if (action === "ready" || action === "request-review") {
+      await refreshWorkspaceGitState(workspace);
+      const refreshed = getWorkspace(workspace.id);
+      if (refreshed) workspace = refreshed;
+    }
+
+    const result = await applyWorkspaceAction(workspace, {
       action,
       agentId,
       detail: cleanString(parsed.body.detail, "detail", { max: 4000 }),

package/src/runtime-tokens.ts

@@ -82,6 +82,8 @@ export function issueOrchestratorRuntimeToken(input: {
       cwdPrefixes: [input.baseDir],
       logsRead: true,
       terminalAttach: true,
+      terminalRead: true,
+      terminalWrite: true,
     },
     createdBy: input.createdBy ?? "runtime",
   });
@@ -190,6 +192,8 @@ export function issueInteractiveRunnerRuntimeToken(input: {
       agents: [agentId],
       cwdPrefixes: [input.cwd],
       terminalAttach: false,
+      terminalRead: false,
+      terminalWrite: false,
       logsRead: false,
       canDelegate: false,
     },

package/src/security.ts

@@ -104,6 +104,9 @@ type AuthorizationResource = {
   spawnRequestId?: string;
   integrationName?: string;
   terminalAttach?: boolean;
+  terminalRead?: boolean;
+  terminalWrite?: boolean;
+  terminalOwner?: boolean;
   logsRead?: boolean;
 };
 
@@ -147,7 +150,7 @@ export function isRequestAuthorizedFor(req: Request, check: AuthorizationCheck):
 }
 
 export function isComponentAuthorizedFor(auth: ComponentToken, check: AuthorizationCheck): boolean {
-  return hasComponentScope(auth, check.scope) && constraintsAllow(auth.constraints, check.resource);
+  return hasComponentScope(auth, check.scope) && constraintsAllow(auth, check.resource);
 }
 
 export function requiredScopeFor(method: string, pathname: string): string | null {
@@ -160,7 +163,8 @@ export function requiredScopeFor(method: string, pathname: string): string | nul
   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\//)) return "terminal:attach";
+  if (pathname.match(/^\/api\/orchestrators\/[^/]+\/terminal\/[^/]+\/input$/)) return "terminal:write";
+  if (pathname.match(/^\/api\/orchestrators\/[^/]+\/terminal\//)) return "terminal:read";
   const settingScope = requiredSettingsScopeFor(method, pathname);
   if (settingScope !== undefined) return settingScope;
   if (pathname.startsWith("/api/artifacts")) {
@@ -259,7 +263,8 @@ export function requiredComponentScopeFor(method: string, pathname: string): str
   if (pathname === "/api/events") return "message:read";
   if (pathname === "/api/mcp") return "mcp:use";
   if (pathname.match(/^\/api\/orchestrators\/[^/]+\/logs\//)) return "logs:read";
-  if (pathname.match(/^\/api\/orchestrators\/[^/]+\/terminal\//)) return "terminal:attach";
+  if (pathname.match(/^\/api\/orchestrators\/[^/]+\/terminal\/[^/]+\/input$/)) return "terminal:write";
+  if (pathname.match(/^\/api\/orchestrators\/[^/]+\/terminal\//)) return "terminal:read";
   const settingScope = requiredSettingsScopeFor(method, pathname);
   if (settingScope !== undefined) return settingScope ?? "system:admin";
   if (pathname.startsWith("/api/commands")) {
@@ -519,10 +524,12 @@ export function resolveTeamLineage(constraints: TokenConstraints | undefined): s
   return constraints?.teamId;
 }
 
-function constraintsAllow(constraints: TokenConstraints | undefined, resource: AuthorizationResource | undefined): boolean {
-  if (!constraints || !resource) return true;
+function constraintsAllow(auth: ComponentToken, resource: AuthorizationResource | undefined): boolean {
+  const constraints = auth.constraints;
+  if (!resource) return true;
+  if (!constraints) return resource.terminalOwner ? terminalOwnerAllowed(auth, undefined, resource) : true;
   const hasConstraints = Object.keys(constraints).length > 0;
-  if (!hasConstraints) return true;
+  if (!hasConstraints && !resource.terminalOwner) return true;
   if (resource.agentId && !listAllows(constraints.agents, resource.agentId)) return false;
   if (resource.policyName && !listAllows(constraints.policies, resource.policyName)) return false;
   if (resource.channel && !listAllows(constraints.channels, resource.channel)) return false;
@@ -533,10 +540,27 @@ function constraintsAllow(constraints: TokenConstraints | undefined, resource: A
   if (resource.cwd && !cwdAllows(constraints, resource.cwd)) return false;
   if (resource.target && !targetAllows(constraints, resource.target)) return false;
   if (resource.terminalAttach && constraints.terminalAttach !== true) return false;
+  if (resource.terminalRead && constraints.terminalRead !== true) return false;
+  if (resource.terminalWrite && constraints.terminalWrite !== true) return false;
   if (resource.logsRead && constraints.logsRead !== true) return false;
+  if (resource.terminalOwner && !terminalOwnerAllowed(auth, constraints, resource)) return false;
   return true;
 }
 
+function terminalOwnerAllowed(auth: ComponentToken, constraints: TokenConstraints | undefined, resource: AuthorizationResource): boolean {
+  if (hasScope(auth.scope, "system:admin")) return true;
+  if (auth.role === "orchestrator") {
+    return !resource.orchestratorId || listAllows(constraints?.orchestrators, resource.orchestratorId);
+  }
+  if (!constraints) return false;
+  if (resource.agentId && constraints.agents?.includes(resource.agentId)) return true;
+  if (resource.policyName && constraints.policies?.includes(resource.policyName)) return true;
+  if (resource.spawnRequestId && constraints.spawnRequestIds?.includes(resource.spawnRequestId)) return true;
+  if (resource.agentId && constraints.targets?.some((target) => target === resource.agentId || target === `agent:${resource.agentId}`)) return true;
+  if (resource.policyName && constraints.targets?.includes(`policy:${resource.policyName}`)) return true;
+  return false;
+}
+
 function targetAllows(constraints: TokenConstraints, target: string): boolean {
   const hasTargetConstraints = Boolean(constraints.targets?.length || constraints.policies?.length || constraints.agents?.length);
   if (constraints.targets?.includes(target)) return true;
@@ -564,7 +588,7 @@ function isTokenConstraints(value: unknown): value is TokenConstraints {
   if (!value || typeof value !== "object" || Array.isArray(value)) return false;
   const record = value as Record<string, unknown>;
   for (const [key, item] of Object.entries(record)) {
-    if (["terminalAttach", "logsRead", "canDelegate"].includes(key)) {
+    if (["terminalAttach", "terminalRead", "terminalWrite", "logsRead", "canDelegate"].includes(key)) {
       if (typeof item !== "boolean") return false;
     } else if (key === "cwd" || key === "spawnedBy" || key === "teamId" || key === "projectId" || key === "profile" || key === "tenantId") {
       if (typeof item !== "string") return false;

package/src/server.ts

@@ -15,6 +15,7 @@ import { startPlanLiveBindings } from "./services/plan-live-bindings";
 import { startRelayScheduler } from "./services/scheduler";
 import { recordWorkspaceIssueActivity } from "./services/spawn-issue-activity";
 import { onWorkspaceCreate } from "./db";
+import { isTerminalSessionRequestAuthorized } from "./terminal-authz";
 import { resolve, sep } from "path";
 import { gzipSync, brotliCompressSync, constants as zlibConstants } from "node:zlib";
 import {
@@ -35,7 +36,6 @@ import {
   isAuthorized,
   isScopedRequestAuthorized,
   isOriginAllowed,
-  isRequestAuthorizedFor,
   unauthorized,
 } from "./security";
 import { startMaintenanceScheduler } from "./maintenance";
@@ -93,20 +93,7 @@ export function startServer(): void {
     hostname: HOST,
     idleTimeout: IDLE_TIMEOUT_SECONDS,
     fetch: createFetchHandler({ publicDir: process.env.PUBLIC_DIR, logRequests: LOG_REQUESTS }),
-    websocket: {
-      open(ws) {
-        if (ws.data?.kind === "terminal-proxy") return openTerminalProxy(ws as TerminalProxySocket);
-        return busHandleOpen(ws as any);
-      },
-      message(ws, data) {
-        if (ws.data?.kind === "terminal-proxy") return sendTerminalProxyFrame(ws as TerminalProxySocket, data);
-        return busHandleMessage(ws as any, data);
-      },
-      close(ws) {
-        if (ws.data?.kind === "terminal-proxy") return closeTerminalProxy(ws as TerminalProxySocket);
-        return busHandleClose(ws as any);
-      },
-    },
+    websocket: createWebSocketHandlers(),
   });
 
   console.log(`agent-relay ${VERSION} running on http://${HOST}:${PORT}`);
@@ -117,6 +104,7 @@ interface TerminalProxySocketData {
   upstreamUrl: string;
   upstreamToken?: string;
   upstream?: WebSocket;
+  writeAuthorized: boolean;
   pending: Array<string | Buffer>;
 }
 
@@ -128,6 +116,23 @@ type RelaySocketData = {
 
 type TerminalProxySocket = ServerWebSocket<TerminalProxySocketData>;
 
+export function createWebSocketHandlers() {
+  return {
+    open(ws: ServerWebSocket<RelaySocketData>) {
+      if (ws.data?.kind === "terminal-proxy") return openTerminalProxy(ws as TerminalProxySocket);
+      return busHandleOpen(ws as any);
+    },
+    message(ws: ServerWebSocket<RelaySocketData>, data: string | Buffer) {
+      if (ws.data?.kind === "terminal-proxy") return sendTerminalProxyFrame(ws as TerminalProxySocket, data);
+      return busHandleMessage(ws as any, data);
+    },
+    close(ws: ServerWebSocket<RelaySocketData>) {
+      if (ws.data?.kind === "terminal-proxy") return closeTerminalProxy(ws as TerminalProxySocket);
+      return busHandleClose(ws as any);
+    },
+  };
+}
+
 function emitAutomationDispatches(results: AutomationDispatchResult[]): void {
   for (const result of results) {
     if (result.command) emitAutomationCommand(result.command);
@@ -195,6 +200,10 @@ function openTerminalProxy(ws: TerminalProxySocket): void {
 }
 
 function sendTerminalProxyFrame(ws: TerminalProxySocket, data: string | Buffer): void {
+  if (!ws.data.writeAuthorized && isTerminalWriteFrame(data)) {
+    ws.send(JSON.stringify({ type: "error", error: "terminal write forbidden" }));
+    return;
+  }
   const upstream = ws.data.upstream;
   if (!upstream || upstream.readyState === WebSocket.CONNECTING) {
     ws.data.pending.push(data);
@@ -204,10 +213,22 @@ function sendTerminalProxyFrame(ws: TerminalProxySocket, data: string | Buffer):
   upstream.send(data);
 }
 
+function isTerminalWriteFrame(data: string | Buffer): boolean {
+  let payload: unknown;
+  try {
+    payload = JSON.parse(typeof data === "string" ? data : data.toString("utf8"));
+  } catch {
+    return false;
+  }
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return false;
+  const frame = payload as Record<string, unknown>;
+  return frame.type === "input" || (frame.type === "interactive" && frame.interactive === true);
+}
+
 function closeTerminalProxy(ws: TerminalProxySocket): void {
   const upstream = ws.data.upstream;
   ws.data.pending = [];
-  if (upstream && upstream.readyState === WebSocket.OPEN) upstream.close();
+  if (upstream && upstream.readyState !== WebSocket.CLOSED) upstream.close();
 }
 
 export function createFetchHandler(
@@ -235,9 +256,10 @@ export function createFetchHandler(
       if (!isAuthorized(req)) return unauthorized(req);
       const orchestratorId = decodeURIComponent(terminalStreamMatch[1]!);
       const session = decodeURIComponent(terminalStreamMatch[2]!);
-      if (!isRequestAuthorizedFor(req, { scope: "terminal:attach", resource: { orchestratorId, terminalAttach: true } })) {
+      if (!isTerminalSessionRequestAuthorized(req, orchestratorId, session, "read")) {
         return forbidden(req);
       }
+      const writeAuthorized = isTerminalSessionRequestAuthorized(req, orchestratorId, session, "write");
       const orch = getOrchestrator(orchestratorId);
       if (!orch) return Response.json({ error: "orchestrator not found" }, { status: 404 });
       if (!orch.apiUrl) return Response.json({ error: "orchestrator does not expose an API" }, { status: 422 });
@@ -248,7 +270,7 @@ export function createFetchHandler(
       // access/proxy logs (#149). The orchestrator accepts both, but headers are safer.
       const token = relayToken();
       const upgraded = server.upgrade(req, {
-        data: { kind: "terminal-proxy", upstreamUrl: upstream.toString(), upstreamToken: token, pending: [] },
+        data: { kind: "terminal-proxy", upstreamUrl: upstream.toString(), upstreamToken: token, writeAuthorized, pending: [] },
       });
       if (!upgraded) return new Response("WebSocket upgrade failed", { status: 400 });
       return undefined;