agent-relay-server 0.119.11 → 0.120.0

package/src/db/scheduled-timers.ts

@@ -41,6 +41,23 @@ export interface ScheduledTimer {
   lastMessageId?: number;
   claimedBy?: string;
   claimExpiresAt?: number;
+  command?: ScheduledTimerCommand;
+}
+
+export interface ScheduledTimerCommand {
+  commandId?: string;
+  orchestratorId: string;
+  cwd: string;
+  command: string;
+  env?: Record<string, string>;
+  status: "pending" | "running" | "succeeded" | "failed" | "timed_out" | "canceled";
+  startedAt?: number;
+  finishedAt?: number;
+  exitCode?: number | null;
+  durationMs?: number;
+  stdoutTail?: string;
+  stderrTail?: string;
+  logArtifactId?: string;
 }
 
 interface ScheduledTimerRow {
@@ -74,6 +91,7 @@ interface ScheduledTimerRow {
   last_message_id: number | null;
   claimed_by: string | null;
   claim_expires_at: number | null;
+  command: string | null;
 }
 
 export interface CreateScheduledTimerRowInput {
@@ -96,6 +114,7 @@ export interface CreateScheduledTimerRowInput {
   maxRuns?: number;
   expiresAt?: number;
   idempotencyKey?: string;
+  command?: ScheduledTimerCommand;
 }
 
 export function insertScheduledTimer(input: CreateScheduledTimerRowInput, now = Date.now()): ScheduledTimer {
@@ -105,9 +124,9 @@ export function insertScheduledTimer(input: CreateScheduledTimerRowInput, now =
     INSERT INTO scheduled_timers (
       id, target, created_by, created_by_kind, created_by_scopes, created_by_constraints, delivery_from,
       created_at, next_run_at, schedule_kind, schedule_def, message_kind, channel, subject, body, claimable, payload, meta, enabled,
-      run_count, max_runs, expires_at, idempotency_key, correlation_id
+      run_count, max_runs, expires_at, idempotency_key, correlation_id, command
     )
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 1, 0, ?, ?, ?, ?)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 1, 0, ?, ?, ?, ?, ?)
   `).run(
     id,
     input.target,
@@ -131,6 +150,7 @@ export function insertScheduledTimer(input: CreateScheduledTimerRowInput, now =
     input.expiresAt ?? null,
     input.idempotencyKey ?? null,
     correlationId,
+    input.command ? JSON.stringify(input.command) : null,
   );
   return getScheduledTimer(id)!;
 }
@@ -215,12 +235,35 @@ export function completeScheduledTimerRun(input: {
         claimed_by = NULL,
         claim_expires_at = NULL
     WHERE id = ?
-      AND claimed_by = ?
+      AND (claimed_by = ? OR (claimed_by IS NULL AND ? = ''))
       AND enabled = 1
-  `).run(runCount, input.now, input.messageId, candidateNextRunAt, enabled ? 1 : 0, input.timer.id, input.timer.claimedBy ?? "");
+  `).run(runCount, input.now, input.messageId, candidateNextRunAt, enabled ? 1 : 0, input.timer.id, input.timer.claimedBy ?? "", input.timer.claimedBy ?? "");
   return getScheduledTimer(input.timer.id)!;
 }
 
+export function setScheduledTimerCommandId(timerId: string, commandId: string): ScheduledTimer | null {
+  const timer = getScheduledTimer(timerId);
+  if (!timer?.command) return timer;
+  getDb().query("UPDATE scheduled_timers SET command = ? WHERE id = ?")
+    .run(JSON.stringify({ ...timer.command, commandId }), timerId);
+  return getScheduledTimer(timerId);
+}
+
+export function findScheduledTimerByCommandId(commandId: string): ScheduledTimer | null {
+  const row = getDb()
+    .query("SELECT * FROM scheduled_timers WHERE json_extract(command, '$.commandId') = ? ORDER BY created_at DESC LIMIT 1")
+    .get(commandId) as ScheduledTimerRow | undefined;
+  return row ? rowToTimer(row) : null;
+}
+
+export function updateScheduledTimerCommand(timerId: string, patch: Partial<ScheduledTimerCommand>): ScheduledTimer | null {
+  const timer = getScheduledTimer(timerId);
+  if (!timer?.command) return timer;
+  getDb().query("UPDATE scheduled_timers SET command = ? WHERE id = ?")
+    .run(JSON.stringify({ ...timer.command, ...patch }), timerId);
+  return getScheduledTimer(timerId);
+}
+
 export function recordScheduledTimerFailure(input: {
   timer: ScheduledTimer;
   error: string;
@@ -295,6 +338,7 @@ function rowToTimer(row: ScheduledTimerRow): ScheduledTimer {
     lastMessageId: row.last_message_id ?? undefined,
     claimedBy: row.claimed_by ?? undefined,
     claimExpiresAt: row.claim_expires_at ?? undefined,
+    command: parseRecord(row.command) as ScheduledTimerCommand | undefined,
   };
 }
 

package/src/db/schema.ts

@@ -197,7 +197,8 @@ export function initDb(path: string = "agent-relay.db"): Database {
       correlation_id TEXT NOT NULL,
       last_message_id INTEGER REFERENCES messages(id),
       claimed_by TEXT,
-      claim_expires_at INTEGER
+      claim_expires_at INTEGER,
+      command TEXT
     );
     CREATE INDEX IF NOT EXISTS idx_scheduled_timers_due ON scheduled_timers(enabled, next_run_at, claim_expires_at);
     CREATE INDEX IF NOT EXISTS idx_scheduled_timers_creator ON scheduled_timers(created_by, enabled, next_run_at);

package/src/mcp/index.ts

@@ -53,7 +53,8 @@ export const RELAY_TOOL_GROUPS: Record<string, readonly string[]> = {
   memory: ["relay_recall", "relay_compact_and_resume", "relay_memory_write", "relay_memory_promote", "relay_memory_retract", "relay_memory_read", "relay_memory_search"],
   artifacts: ["relay_upload_artifact", "relay_attach_artifact"],
   workspace: ["relay_workspace_status", "relay_workspace_ready", "relay_workspace_deps", "relay_workspace_list", "relay_workspace_claim", "relay_workspace_release", "relay_workspace_land", "relay_merge_pause", "relay_merge_pauses", "relay_merge_renew", "relay_merge_resume"],
-  "spawn-lifecycle": ["relay_spawn_agent", "relay_spawn_targets", "relay_my_agents", "relay_shutdown_agent", "relay_agent_action", "relay_agent_status", "relay_agent_crash_report", "relay_schedule_timer", "relay_list_timers", "relay_cancel_timer"],
+  "spawn-lifecycle": ["relay_spawn_agent", "relay_spawn_targets", "relay_my_agents", "relay_shutdown_agent", "relay_agent_action", "relay_agent_status", "relay_agent_crash_report"],
+  schedule: ["relay_schedule_timer", "relay_list_timers", "relay_cancel_timer"],
   plans: ["relay_plan_create", "relay_plan_add_node", "relay_plan_update_node", "relay_plan_add_edge", "relay_plan_remove_node", "relay_plan_remove_edge", "relay_plan_archive", "relay_plan_delete", "relay_plan_get"],
   tasks: ["relay_task_create", "relay_task_get", "relay_task_list", "relay_task_update", "relay_task_set_status", "relay_task_set_stage", "relay_task_record_gate", "relay_task_add_dependency", "relay_task_remove_dependency", "relay_task_add_ref", "relay_task_remove_ref", "relay_task_assign_agent", "relay_task_history", "relay_task_memory_read", "relay_task_memory_replace_working_state", "relay_task_memory_append_ruled_out", "relay_task_memory_append_decision", "relay_task_dispatch", "relay_task_comment", "relay_task_close_bridge", "relay_release_readiness"],
   teams: ["relay_team_get", "relay_team_set_brief", "relay_team_claim", "relay_team_dissolve"],

package/src/mcp/tools-scheduler.ts

@@ -9,7 +9,7 @@ import { optionalBoolean, optionalPositiveInt, optionalRecord, optionalString, s
 export const SCHEDULER_TOOLS: ToolDefinition[] = [
   {
     name: "relay_schedule_timer",
-    description: "Create a durable Relay timer that wakes a target by enqueueing a normal Relay message when due. Supports one-shot afterMs/at and fixed recurring everyMs. RRULE is intentionally deferred.",
+    description: "Create a durable Relay timer that wakes a target by enqueueing a normal Relay message when due. With command, runs a background orchestrator command and wakes on exit or afterMs timeout.",
     requiredScopes: ["schedule:write"],
     inputSchema: {
       type: "object",
@@ -21,11 +21,13 @@ export const SCHEDULER_TOOLS: ToolDefinition[] = [
         subject: { type: "string" },
         body: { type: "string" },
         payload: { type: "object" },
+        command: { type: "string", description: "Optional background shell command. Requires command:write. When set, afterMs is the max timeout and everyMs/at are rejected." },
+        cwd: { type: "string", description: "Command working directory. Must resolve inside an online orchestrator baseDir. Defaults to the caller agent cwd when available." },
+        env: { type: "object", additionalProperties: { type: "string" }, description: "Optional string environment overrides for the command." },
         maxRuns: { type: "integer", minimum: 1 },
         expiresAt: { oneOf: [{ type: "string" }, { type: "integer", minimum: 1 }] },
         idempotencyKey: { type: "string" },
       },
-      required: ["body"],
       additionalProperties: false,
     },
   },
@@ -94,14 +96,19 @@ function cleanScheduleInput(args: Record<string, unknown>): ScheduleTimerInput {
     at: optionalString(args.at, "at", 80),
     everyMs: optionalPositiveInt(args.everyMs, "everyMs"),
     subject: optionalString(args.subject, "subject", 200),
-    body: stringField(args.body, "body", { required: true }),
+    body: optionalString(args.body, "body", MAX_SAFE_BODY_CHARS),
     payload: optionalRecord(args.payload, "payload"),
+    command: optionalString(args.command, "command", 8_000),
+    cwd: optionalString(args.cwd, "cwd", 500),
+    env: optionalStringRecord(args.env, "env"),
     maxRuns: optionalPositiveInt(args.maxRuns, "maxRuns"),
     expiresAt: typeof args.expiresAt === "number" ? args.expiresAt : optionalString(args.expiresAt, "expiresAt", 80),
     idempotencyKey: optionalString(args.idempotencyKey, "idempotencyKey", 240),
   };
 }
 
+const MAX_SAFE_BODY_CHARS = 64_000;
+
 function authContextPayload(auth: McpAuthContext): Parameters<typeof authContextFromMcp>[0] {
   return { kind: auth.kind, actor: auth.actor, scopes: auth.scopes, component: auth.component };
 }
@@ -128,9 +135,21 @@ function serializeTimer(timer: ScheduledTimer): Record<string, unknown> {
     idempotencyKey: timer.idempotencyKey,
     correlationId: timer.correlationId,
     lastMessageId: timer.lastMessageId,
+    command: timer.command,
   };
 }
 
+function optionalStringRecord(value: unknown, field: string): Record<string, string> | undefined {
+  const record = optionalRecord(value, field);
+  if (!record) return undefined;
+  const out: Record<string, string> = {};
+  for (const [key, item] of Object.entries(record)) {
+    if (typeof item !== "string") throw new ValidationError(`${field}.${key} must be a string`);
+    out[key] = item;
+  }
+  return out;
+}
+
 function withAuthErrors<T>(fn: () => T): T {
   try {
     return fn();

package/src/prompt-resolver.ts

@@ -30,15 +30,17 @@ const DEFAULT_PROMPT_TEMPLATES = [
     description: "Built-in ops-assistant append instruction.",
     template: lines(
       "Ops-assistant standing brief: execute mechanical operations on your coordinator's behalf: test suites, release commands such as `bun run release`, smoke and verification probes, gates, and host/version/status checks.",
-      "When running a self-verifying long script, especially `bun run release` (gates -> CI-watch -> deploy -> host-verify, then one final result), redirect its output to a file rather than letting it stream into your context: `bun run release > /tmp/ar-release.log 2>&1`. Wait for it to exit, then read only the final result with `tail /tmp/ar-release.log`. Never run it with inline streaming output. Do not poll, monitor, tail logs, run parallel status/version checks, or otherwise babysit it while it runs. Trust the script; act only on its final result. This generalizes to any long-running command whose intermediate output you do not need.",
+      "For any long command, start it detached in the background with stdout/stderr redirected to a log so it returns immediately and survives your turn; then call `relay_schedule_timer` with `target: \"me\"`, `afterMs` set near the expected duration, and a body telling your future self to check the log and report the exit code plus tail. End the turn after scheduling. Do not poll, tail, `ps`, or babysit the command in a loop.",
+      "On the timer wake, check the log and process result. If the command is done, report the outcome; if it is still running, reschedule once, or investigate if it is well past the expected duration.",
       "Hold and apply session-local ops conventions the coordinator gives you. Report crisp outcomes only: command/gate, pass/fail, commit/version/host evidence, and the next blocker when one exists. Do not dump logs unless asked.",
-      "Do not make strategy, design, scope, or release-timing calls. Escalate those decisions to your spawn-parent. Report operational results to your spawn-parent by default and keep their context clean.",
+      "Do not make strategy, design, scope, or release-timing calls. Escalate those decisions to your spawn-parent.",
     ),
     defaultTemplate: lines(
       "Ops-assistant standing brief: execute mechanical operations on your coordinator's behalf: test suites, release commands such as `bun run release`, smoke and verification probes, gates, and host/version/status checks.",
-      "When running a self-verifying long script, especially `bun run release` (gates -> CI-watch -> deploy -> host-verify, then one final result), redirect its output to a file rather than letting it stream into your context: `bun run release > /tmp/ar-release.log 2>&1`. Wait for it to exit, then read only the final result with `tail /tmp/ar-release.log`. Never run it with inline streaming output. Do not poll, monitor, tail logs, run parallel status/version checks, or otherwise babysit it while it runs. Trust the script; act only on its final result. This generalizes to any long-running command whose intermediate output you do not need.",
+      "For any long command, start it detached in the background with stdout/stderr redirected to a log so it returns immediately and survives your turn; then call `relay_schedule_timer` with `target: \"me\"`, `afterMs` set near the expected duration, and a body telling your future self to check the log and report the exit code plus tail. End the turn after scheduling. Do not poll, tail, `ps`, or babysit the command in a loop.",
+      "On the timer wake, check the log and process result. If the command is done, report the outcome; if it is still running, reschedule once, or investigate if it is well past the expected duration.",
       "Hold and apply session-local ops conventions the coordinator gives you. Report crisp outcomes only: command/gate, pass/fail, commit/version/host evidence, and the next blocker when one exists. Do not dump logs unless asked.",
-      "Do not make strategy, design, scope, or release-timing calls. Escalate those decisions to your spawn-parent. Report operational results to your spawn-parent by default and keep their context clean.",
+      "Do not make strategy, design, scope, or release-timing calls. Escalate those decisions to your spawn-parent.",
     ),
     variables: [],
   },

package/src/routes/agent-profiles.ts

@@ -2,6 +2,7 @@
 import { ValidationError, withResolvedProvisioning } from "../db";
 import { cleanString, optionalEnum } from "../validation";
 import { deleteAgentProfile, getAgentProfile, listAgentProfiles, setAgentProfile } from "../config-store";
+import { RELAY_TOOL_GROUPS } from "../mcp";
 import { emitConfigChanged } from "../sse";
 import { error, isRootCredentialRequest, json, normalizeConfigPathParam, parseBody, type Handler } from "./_shared";
 import { getComponentAuth, hasComponentScope } from "../security";
@@ -10,6 +11,14 @@ import { SPAWN_PROVIDERS, type AgentProfile, type SpawnProvider } from "../types
 
 export const getAgentProfilesRoute: Handler = () => json(listAgentProfiles());
 
+/**
+ * The canonical tool-group catalog (#970): name + member tool names, read straight off
+ * `RELAY_TOOL_GROUPS` so the dashboard multiselect can never drift from the code registry
+ * that `visibleTools` (src/mcp/index.ts) actually enforces at tools/list time.
+ */
+export const getAgentProfileToolGroupsRoute: Handler = () =>
+  json(Object.entries(RELAY_TOOL_GROUPS).map(([name, tools]) => ({ name, tools: [...tools] })));
+
 export const getAgentProfileRoute: Handler = (_req, params) => {
   const name = normalizeConfigPathParam(params.name, "name");
   const profile = getAgentProfile(name);

package/src/routes/commands.ts

@@ -12,6 +12,7 @@ import { isRecord, sanitizeFsName, type LandGateRunResult } from "agent-relay-sd
 import { storeTextArtifact } from "../artifact-text";
 import { authContextFromRequest } from "../services/auth-context";
 import { commandAuthorizationResource as dispatchCommandAuthorizationResource, dispatchCommand } from "../services/dispatch-command";
+import { prepareScheduledCommandResultForStorage, settleScheduledCommandTimer } from "../services/scheduler-command";
 import { emitWorkspaceTaskSemanticNotifications } from "../services/task-lifecycle";
 import { ServiceAuthError } from "../services/errors";
 import { notifyBaseWorktreeStrand, notifyBranchLandFailed, notifyBranchLanded, notifyLandGateFailed, notifyLandGateWarnings } from "../branch-landed";
@@ -204,7 +205,10 @@ export const patchCommand: Handler = async (req, params) => {
     const denied = authorizeRoute(req, { scope: "command:write", resource: dispatchCommandAuthorizationResource(current) });
     if (denied) return denied;
     const status = optionalEnum(parsed.body.status, "status", VALID_COMMAND_STATUSES);
-    const result = cleanParams(parsed.body.result, "result");
+    let result = cleanParams(parsed.body.result, "result");
+    if (result && current.type === "scheduler.command") {
+      result = await prepareScheduledCommandResultForStorage(current, result);
+    }
     const err = cleanString(parsed.body.error, "error", { max: 4000 });
     const command = updateCommand(params.id!, { status: status as CommandStatus | undefined, result, error: err });
     if (!command) return error("command not found", 404);
@@ -225,6 +229,9 @@ export const patchCommand: Handler = async (req, params) => {
       getCompactionWatch().noteCommandSucceeded(command.type, command.id, command.target);
     }
     enqueueContinuationInjectionAfterSelfResume(command);
+    if (command.type === "scheduler.command") {
+      await settleScheduledCommandTimer(command);
+    }
     if (command.type === "workspace.cleanup" && command.status === "succeeded" && isRecord(command.result)) {
       const workspaceId = cleanString(command.result.workspaceId, "result.workspaceId", { max: 160 });
       if (workspaceId) {

package/src/routes/index.ts

@@ -1,6 +1,6 @@
 // Auto-split from routes.ts (#299). Router: route table + matchRoute dispatch.
 import { deleteAgentActiveMemories, deleteAgentById, findAgents, getAgentActiveMemories, getAgentById, getAgentChatHistory, getAgentContextSnapshots, getAgentCrashReportRoute, getAgentQuotaSnapshots, getAgentReplyObligations, getAgentTimelineRoute, getAgents, getMessageArtifactsRoute, getTaskArtifactsRoute, patchAgentLabel, patchAgentReady, patchAgentStatus, patchAgentTags, postHeartbeat } from "./agents";
-import { deleteAgentProfileRoute, getAgentProfileRoute, getAgentProfilesRoute, getResolvedAgentProfileRoute, putAgentProfileRoute } from "./agent-profiles";
+import { deleteAgentProfileRoute, getAgentProfileRoute, getAgentProfilesRoute, getAgentProfileToolGroupsRoute, getResolvedAgentProfileRoute, putAgentProfileRoute } from "./agent-profiles";
 import { deleteAgentTerminalSession, getAgentDrive, getAgentPresence, postAgentAction, postAgentDrive, postAgentPermissionDecision, postAgentPresence, postAgentPrompt, postAgentTerminalSession } from "./agent-sessions";
 import { deleteMyAvatar, deleteUserAvatarById, getMe, getUserAvatar, getUsers, headUserAvatar, patchMe, patchUserById, postMyAvatar, postUserAvatarById } from "./users";
 import { deleteArtifactById, getArtifactById, getArtifactContent, getArtifacts, headArtifactContent, postArtifact } from "./artifacts";
@@ -235,6 +235,7 @@ const routes: Route[] = [
   route("PATCH", "/api/commands/:id", patchCommand),
   route("DELETE", "/api/commands/:id", deleteCommandById),
   route("GET", "/api/agent-profiles", getAgentProfilesRoute),
+  route("GET", "/api/agent-profiles/tool-groups", getAgentProfileToolGroupsRoute),
   route("GET", "/api/agent-profiles/:name/resolved", getResolvedAgentProfileRoute),
   route("GET", "/api/agent-profiles/:name", getAgentProfileRoute),
   route("PUT", "/api/agent-profiles/:name", putAgentProfileRoute),

package/src/services/dispatch-command.ts

@@ -14,9 +14,10 @@ import { isRecord, stringValue } from "agent-relay-sdk";
 import { createCommand } from "../commands-db";
 import { emitCommandEvent } from "../command-events";
 import { isComponentAuthorizedFor } from "../security";
+import { listOrchestrators } from "../db";
 import { ServiceAuthError } from "./errors";
 import type { AuthContext } from "./auth-context";
-import type { Command, CreateCommandInput } from "../types";
+import type { Command, ComponentToken, CreateCommandInput, TokenConstraints } from "../types";
 
 /** THE single home for the command authorization resource. Was duplicated in
  * routes/commands.ts and bus.ts (diverging on `cleanString` vs `stringValue`) plus their
@@ -34,6 +35,130 @@ export function commandAuthorizationResource(input: Pick<CreateCommandInput, "ta
   };
 }
 
+/** Does the token pin the cwd(s) a command may run in? An absent path resource field must NOT
+ * silently bypass such a constraint (the orchestrator would default it to baseDir — a full
+ * cwd-constraint escape, #968 hole 1), so we force-resolve the effective paths before the check. */
+function hasCwdConstraint(constraints: TokenConstraints | undefined): boolean {
+  return Boolean(constraints?.cwd || constraints?.cwdPrefixes?.length);
+}
+
+/** THE universe of param fields that can carry a host filesystem path a command executes at.
+ * A constrained token's `cwd`/`cwdPrefixes` must cover EVERY such field a command runs at — the
+ * round-1/2 fixes only ever looked at `cwd`, so commands that execute at `worktreePath`/`repoRoot`
+ * (workspace.* → execProcess/git in orchestrator/src/workspace-probe/*) escaped the constraint
+ * entirely (#968 round-3). Adding a NEW path-bearing param field means adding it here — otherwise
+ * the fail-closed check below cannot see it. */
+const PATH_AXIS_FIELDS = ["cwd", "worktreePath", "repoRoot"] as const;
+type PathAxisField = (typeof PATH_AXIS_FIELDS)[number];
+
+/** Declarative map: command type → the path-bearing param field(s) it executes host work at.
+ * The orchestrator runs a shell/git at these paths (scheduler.command → control.ts; workspace.* →
+ * control.ts → workspace-probe/*). A constrained token must have EACH resolved axis inside its
+ * cwdPrefixes/cwd.
+ *
+ * A command type absent from BOTH this map and NON_PATH_COMMAND_TYPES is UNKNOWN: under a
+ * constrained token it FAILS CLOSED if it carries any PATH_AXIS_FIELD (a new host-executing type
+ * that forgot to declare its axes cannot silently bypass the constraint). This is deliberately
+ * NOT an allowlist of "types that run at cwd" — that's exactly what was too narrow twice. */
+const COMMAND_PATH_AXES: Record<string, readonly PathAxisField[]> = {
+  "scheduler.command": ["cwd"],
+  "workspace.merge": ["worktreePath", "repoRoot"],
+  "workspace.cleanup": ["worktreePath", "repoRoot"],
+  "workspace.reconcile": ["worktreePath", "repoRoot"],
+  "workspace.pr-arm-auto-merge": ["worktreePath", "repoRoot"],
+  "workspace.pr-merge": ["worktreePath", "repoRoot"],
+  "workspace.pr-refresh": ["worktreePath", "repoRoot"],
+  "workspace.deps-refresh": ["worktreePath", "repoRoot"],
+  "workspace.idle-refresh": ["worktreePath", "repoRoot"],
+  "workspace.recovery-branch-discard": ["repoRoot"],
+  "workspace.prune": ["repoRoot"],
+};
+
+/** Command types that do NOT execute host filesystem work at a param-supplied path — a cwd
+ * constraint must not gate them, or we regress unrelated dispatch. agent.* operate on tmux
+ * sessions / relay state; orchestrator.migrate-provider-config only reads local config. Any OTHER
+ * unmapped type is trusted only if it carries no path field at all (see assertPathAxesWithinConstraint). */
+const NON_PATH_COMMAND_TYPES = new Set<string>([
+  "agent.restart",
+  "agent.shutdown",
+  "orchestrator.migrate-provider-config",
+]);
+
+/** The cwd a dispatched command will ACTUALLY run in — the same default the orchestrator applies.
+ * If `params.cwd` is set, that's it. Otherwise the orchestrator (`orchestrator-<id>` target, or
+ * `params.orchestratorId`) defaults a missing cwd to its own `baseDir` (control.ts). We resolve
+ * that baseDir here so the auth gate evaluates the REAL cwd, not an absent (constraint-skipping)
+ * one. Returns undefined only when the effective cwd genuinely can't be determined. */
+function resolveEffectiveCommandCwd(input: Pick<CreateCommandInput, "target" | "params">): string | undefined {
+  const params = isRecord(input.params) ? input.params : {};
+  const explicit = stringValue(params.cwd);
+  if (explicit) return explicit;
+  const orchestratorId = stringValue(params.orchestratorId)
+    ?? (typeof input.target === "string" && input.target.startsWith("orchestrator-")
+      ? input.target.slice("orchestrator-".length)
+      : undefined);
+  if (!orchestratorId) return undefined;
+  return listOrchestrators().find((item) => item.id === orchestratorId)?.baseDir;
+}
+
+/** Effective value of one path axis, applying the SAME defaulting the orchestrator would.
+ * Only `cwd` has a baseDir default (scheduler.command); `worktreePath`/`repoRoot` have none —
+ * an absent value stays absent and drives the fail-closed "no axis resolved" deny below. */
+function resolveAxisValue(field: PathAxisField, input: CreateCommandInput, params: Record<string, unknown>): string | undefined {
+  const explicit = stringValue(params[field]);
+  if (explicit) return explicit;
+  if (field === "cwd") return resolveEffectiveCommandCwd(input);
+  return undefined;
+}
+
+/** Is a single resolved path inside the token's cwd/cwdPrefixes? Reuses the exact production
+ * matcher (`constraintsAllow` → `cwdAllows`) via a cwd-only authorization resource. */
+function pathAxisAllowed(component: ComponentToken, value: string): boolean {
+  return isComponentAuthorizedFor(component, { scope: "command:write", resource: { cwd: value } });
+}
+
+/** #968 round-3 — the COMPREHENSIVE cwd-constraint gate. For a cwd-constrained component token,
+ * every host path the command executes at must be inside the constraint. Single choke point for
+ * BOTH transports (HTTP `POST /api/commands`, WS bus command frame). Throws to DENY. */
+function assertPathAxesWithinConstraint(input: CreateCommandInput, component: ComponentToken): void {
+  const params = isRecord(input.params) ? input.params : {};
+  const declared = COMMAND_PATH_AXES[input.type];
+
+  if (!declared) {
+    // Unmapped type. If it carries ANY known path field, it's a host-executing command that failed
+    // to declare its axes → FAIL CLOSED. Otherwise it's a non-path command (agent.* etc.) and a cwd
+    // constraint must not gate it — but only trust that for types explicitly known non-path, or that
+    // simply carry no path field at all (so a stray unmapped type can't smuggle a path through).
+    const strayPath = PATH_AXIS_FIELDS.some((field) => stringValue(params[field]));
+    if (strayPath && !NON_PATH_COMMAND_TYPES.has(input.type)) {
+      throw new ServiceAuthError("component token lacks command scope");
+    }
+    return;
+  }
+
+  // Mapped host-executing type: resolve + constrain-check each declared axis (and, defensively, any
+  // other present path field), DENY if any is out of bounds. If NONE of the axes resolve to a value,
+  // the command's run location can't be proven inside the constraint — the orchestrator would default
+  // it out of bounds — so fail closed.
+  let anyResolved = false;
+  const checked = new Set<PathAxisField>();
+  for (const field of declared) {
+    const value = resolveAxisValue(field, input, params);
+    if (!value) continue;
+    anyResolved = true;
+    checked.add(field);
+    if (!pathAxisAllowed(component, value)) throw new ServiceAuthError("component token lacks command scope");
+  }
+  for (const field of PATH_AXIS_FIELDS) {
+    if (checked.has(field)) continue;
+    const value = stringValue(params[field]);
+    if (!value) continue;
+    anyResolved = true;
+    if (!pathAxisAllowed(component, value)) throw new ServiceAuthError("component token lacks command scope");
+  }
+  if (!anyResolved) throw new ServiceAuthError("component token lacks command scope");
+}
+
 /** Authorize a command dispatch from the unified auth context. Mirrors BOTH old paths
  * exactly: only a COMPONENT token carries per-resource constraints, so the gate is a no-op
  * for admin/system/integration principals (which already cleared the coarse `command:write`
@@ -42,10 +167,16 @@ export function commandAuthorizationResource(input: Pick<CreateCommandInput, "ta
  * "no component token ⇒ allow; else `isComponentAuthorizedFor(command:write, resource)`". */
 function assertCommandAuthorized(ctx: AuthContext, input: CreateCommandInput): void {
   if (!ctx.component) return;
-  const ok = isComponentAuthorizedFor(ctx.component, {
-    scope: "command:write",
-    resource: commandAuthorizationResource(input),
-  });
+  const resource = commandAuthorizationResource(input);
+  // #968 round-3: a cwd-constrained token must have EVERY host path the command executes at
+  // (not just `params.cwd` — also `worktreePath`/`repoRoot`, and any future path axis) inside its
+  // constraint. Force-resolve each declared axis (applying the orchestrator's baseDir defaulting)
+  // and constrain-check it; an unmapped-but-path-bearing command fails closed. Covers both the
+  // round-1 (absent cwd) and round-2 (scheduler-only) narrowness in one declarative choke point.
+  if (hasCwdConstraint(ctx.component.constraints)) {
+    assertPathAxesWithinConstraint(input, ctx.component);
+  }
+  const ok = isComponentAuthorizedFor(ctx.component, { scope: "command:write", resource });
   if (!ok) throw new ServiceAuthError("component token lacks command scope");
 }