@opengeni/api-router 0.30.3 → 2.2.0-canary.0

package/src/mcp/server.ts

@@ -14,7 +14,6 @@ import {
   stableJson,
   compactSessionEventResult,
   sessionEventLatestClassToSemanticClass,
-  MemorySlackPublicationDistribution,
   SessionMcpCredentialUpdateInput,
   ToolAuthNeededPayload,
   VariableSetVariableName,
@@ -38,19 +37,20 @@ import {
   SESSION_GOAL_RATIONALE_MAX_BYTES,
   SESSION_GOAL_SUCCESS_CRITERIA_MAX_BYTES,
   SESSION_GOAL_TEXT_MAX_BYTES,
+  SESSION_INSTRUCTIONS_MAX_CHARACTERS,
   sessionGoalUtf8Bytes,
   TASK_NOTE_LIST_DEFAULT_LIMIT,
   TASK_NOTE_LIST_MAX_LIMIT,
   TASK_NOTE_MAX_LIFETIME_DAYS,
   TASK_NOTE_REASON_MAX_BYTES,
   TASK_NOTE_TEXT_MAX_BYTES,
+  SubmitHumanInputResponseRequest,
 } from "@opengeni/contracts";
 import {
   countVariableSets,
   beginRigChangeVerificationAttempt,
   createVariableSet,
   decryptVariableSetValue,
-  deleteScheduledTask,
   encryptVariableSetValue,
   getSession,
   getSessionGoal,
@@ -63,7 +63,9 @@ import {
   listScheduledTaskRuns,
   listScheduledTasks,
   listSessionEventPage,
+  listOutstandingSessionSystemUpdates,
   listSessionDiscoverySummaries,
+  listEnrollments,
   projectEffectiveControlForRelatedAccess,
   projectSessionForRelatedAccess,
   type SessionDiscoveryCursor,
@@ -77,8 +79,6 @@ import {
   readVariableSetSecretAtomically,
   recordSyncedSocialPosts,
   listVariableSets,
-  MEMORY_CORRECT_TOOL_DESCRIPTION,
-  MEMORY_SAVE_TOOL_DESCRIPTION,
   MEMORY_SEARCH_TOOL_DESCRIPTION,
   requireScheduledTask,
   requireSession,
@@ -86,8 +86,10 @@ import {
   serializeEffectiveSessionControl,
   setSessionGoalStatusWithEvent,
   recordSessionGoalProgressWithEvent,
+  holdSessionGoalContinuationWithEvent,
+  SESSION_GOAL_HOLD_MAX_SECONDS,
+  SESSION_GOAL_HOLD_MIN_SECONDS,
   setVariableSetVariable,
-  updateScheduledTask,
   updateSessionGoalWithEvent,
   upsertSessionGoalWithEvent,
   RigChangeTransitionError,
@@ -100,13 +102,12 @@ import {
   archiveTaskNote,
   createTaskNote,
   listTaskNotes,
+  replaceTaskNote,
+  acceptSessionHumanInputResponse,
+  HumanInputResponseValidationError,
 } from "@opengeni/db";
-import {
-  appendAndPublishEvents,
-  appendAndPublishTurnEventsFenced,
-  publishDurableSessionEvents,
-} from "@opengeni/events";
-import { allowedFirstPartyMcpToolsForSession } from "@opengeni/config";
+import { appendAndPublishTurnEventsFenced, publishDurableSessionEvents } from "@opengeni/events";
+import { allowedFirstPartyMcpToolsForSession, codemodeWorkspaceUrl } from "@opengeni/config";
 import {
   createSignedState,
   GitHubAppConfigurationError,
@@ -128,24 +129,24 @@ import {
   authorizedAtlassianConnectionsForGrant,
   buildCapabilityCatalog,
   nativeConnectionCapabilityRecommendations,
-  correctWorkspaceMemoryWithSlackPublication,
   requireLiveAgentAttemptAuthorization,
   requireSessionAuthorization,
   requireSessionAuthorizationListScope,
   SessionAuthorizationDeniedError,
   SessionAuthorizationUnavailableError,
-  saveWorkspaceMemoryWithSlackPublication,
   searchCapabilityCatalogItems,
   type ResolvedSessionAuthorization,
 } from "@opengeni/core";
 import { recordWorkspaceUsage, requireLimit } from "@opengeni/core";
 import type { ApiRouteDeps } from "@opengeni/core";
+import { retryWhileMissing } from "@opengeni/storage";
 import {
   githubBindingStatus,
   listWorkspaceGitHubInstallationBindings,
   listWorkspaceGitHubRepositories,
 } from "../github-access";
 import { githubBrowserBaseUrl, githubBrowserGrantClaims } from "../github-browser-flow";
+import { publishSandboxFileArtifact } from "../sandbox-file-artifacts";
 import {
   assertSocialConnectionProvider,
   socialMentionsLive,
@@ -154,7 +155,6 @@ import {
   socialSearchLive,
   socialThreadLive,
 } from "../integrations/social-api";
-import { revokeKnowledgeSourceScheduleAuthorization } from "../integrations/google-drive";
 import {
   promoteVerifiedDefinitionEditChangeForApi,
   proposeRigChangeForApi,
@@ -179,6 +179,7 @@ import {
   syncCreatedScheduledTask,
   syncUpdatedScheduledTask,
   validateScheduledTaskTarget,
+  updateScheduledTaskForApi,
   validatedScheduledTaskUpdate,
 } from "@opengeni/core";
 import {
@@ -213,6 +214,14 @@ import {
   boundRigDetailMcp,
   SESSION_EVENT_MCP_MAX_BYTES,
 } from "./session-view";
+import {
+  SESSION_WAIT_DEFAULT_SECONDS,
+  SESSION_WAIT_EVENT_TYPES,
+  SESSION_WAIT_EVENTS_PER_TARGET,
+  SESSION_WAIT_MAX_SECONDS,
+  SESSION_WAIT_MAX_TARGETS,
+  waitForSessionChanges,
+} from "./session-wait";
 import { mcpMutationReceipt, sessionCreateMutationReceipt } from "./receipts";
 import {
   boundScheduledTaskDetailMcp,
@@ -228,11 +237,15 @@ import { createFikenClient, resolveFikenConnectionForTool } from "../integration
 import {
   browseAtlassianSources,
   getAtlassianLiveItem,
-  revokeAtlassianScheduleAuthorization,
   searchAtlassianLive,
 } from "../integrations/atlassian";
 import { AtlassianConnectionMetadata } from "@opengeni/contracts/atlassian";
 import { registerEditableArtifactAgentTools } from "./editable-artifacts";
+import { registerCompanyBrainGovernedWriteTools } from "./company-brain-governed-writes";
+import { registerCompanyProfileAgentAdminTools } from "./company-profile-agent-admin";
+import { registerRememberTools } from "./remember";
+import { mintSandboxCodemodeToken } from "@opengeni/runtime/sandbox";
+import { deleteScheduledTaskWithDurableCleanup } from "../scheduled-task-deletion";
 
 export type McpServerOptions = {
   // Origin of the HTTP request that reached the MCP route. Browser-oriented
@@ -322,12 +335,17 @@ function orchestrationFailureEnvelope(tool: OrchestrationToolName, error: unknow
       : typedCode === "CALLER_INTERRUPTED"
         ? ["caller_interrupted", "The calling session was interrupted before delivery."]
         : typedCode === "TARGET_NOT_VERTICAL"
-          ? ["target_not_vertical", "Agents may message only their parent or immediate children."]
+          ? ["target_not_vertical", "The calling agent cannot act on that session."]
           : typedCode === "CONTROL_CHANGED"
             ? ["conflict", "The target session control state changed; refresh and retry."]
             : typedCode === "IDEMPOTENCY_KEY_REUSED"
               ? ["idempotency_key_reused", "The idempotency key was reused with different input."]
-              : null;
+              : typedCode === "WORKSPACE_CONTROL_BUSY"
+                ? [
+                    "workspace_busy",
+                    "The workspace is busy applying other session commands; nothing was applied. Retry the same call shortly.",
+                  ]
+                : null;
   if (knownFailure) {
     return {
       error: {
@@ -369,9 +387,13 @@ const FIRST_PARTY_TOOL_AUTHORIZATION = {
   goal_set: { sessionRequired: true, allOf: ["goals:manage"] },
   goal_update: { sessionRequired: true, allOf: ["goals:manage"] },
   goal_progress: { sessionRequired: true, allOf: ["goals:manage"] },
+  goal_wait: { sessionRequired: true, allOf: ["goals:manage"] },
   goal_complete: { sessionRequired: true, allOf: ["goals:manage"] },
   goal_pause: { sessionRequired: true, allOf: ["goals:manage"] },
   memory_search: { sessionRequired: true, allOf: ["documents:search"] },
+  // Retired: never registered, so these are never consulted. The map must stay
+  // total over the tool-name union, which still carries both names so that
+  // previously written scheduled-task snapshots keep parsing.
   memory_save: { sessionRequired: true, allOf: ["documents:search"] },
   memory_correct: { sessionRequired: true, allOf: ["documents:search"] },
   preference_registry_summary: {
@@ -382,6 +404,47 @@ const FIRST_PARTY_TOOL_AUTHORIZATION = {
   task_notes_list: { sessionRequired: true, allOf: ["sessions:read"] },
   task_note_save: { sessionRequired: true, allOf: ["sessions:control"] },
   task_note_archive: { sessionRequired: true, allOf: ["sessions:control"] },
+  task_note_replace: { sessionRequired: true, allOf: ["sessions:control"] },
+  knowledge_propose: { sessionRequired: true, allOf: ["documents:search"] },
+  knowledge_correct: { sessionRequired: true, allOf: ["documents:search"] },
+  task_note_promote_knowledge: {
+    sessionRequired: true,
+    allOf: ["documents:search", "sessions:control"],
+  },
+  task_note_promote_instruction_policy: {
+    sessionRequired: true,
+    allOf: ["documents:search", "sessions:control", "workspace:read"],
+  },
+  task_note_promote_preference: {
+    sessionRequired: true,
+    allOf: ["documents:search", "sessions:control", "workspace:read"],
+  },
+  instruction_policy_propose: {
+    sessionRequired: true,
+    allOf: ["documents:search", "workspace:read"],
+  },
+  preference_propose: {
+    sessionRequired: true,
+    allOf: ["documents:search", "workspace:read"],
+  },
+  // Explicit user-directed remember composes task-note evidence with the
+  // governed promotion path, so it needs the union of both permission sets.
+  remember: {
+    sessionRequired: true,
+    allOf: ["documents:search", "sessions:control", "workspace:read"],
+  },
+  remember_confirm: {
+    sessionRequired: true,
+    allOf: ["documents:search", "sessions:control", "workspace:read"],
+  },
+  company_profile_propose: {
+    sessionRequired: true,
+    allOf: ["sessions:control", "workspace:read"],
+  },
+  company_profile_confirm: {
+    sessionRequired: true,
+    allOf: ["sessions:control", "workspace:read"],
+  },
   sandboxes_list: { sessionRequired: true, allOf: ["sessions:read"] },
   sandbox_attach: { sessionRequired: true, allOf: ["sessions:control"] },
   sandbox_swap: { sessionRequired: true, allOf: ["sessions:control"] },
@@ -396,11 +459,17 @@ const FIRST_PARTY_TOOL_AUTHORIZATION = {
   sessions_list: { allOf: ["sessions:read"] },
   session_get: { allOf: ["sessions:read"] },
   session_events: { allOf: ["sessions:read"] },
+  // Blocking wait inside a running turn: the live attempt's own session is the
+  // self target, so the tool exists only for session-scoped grants.
+  session_wait: { sessionRequired: true, allOf: ["sessions:read"] },
   session_create: { allOf: ["sessions:create"] },
   session_send_message: { allOf: ["sessions:control"] },
   session_pause: { allOf: ["sessions:control"] },
   session_resume: { allOf: ["sessions:control"] },
   session_steer: { sessionRequired: true, allOf: ["sessions:control"] },
+  // A live attempt may answer another session's structured human-input
+  // request (never a tool approval, which stays human-only).
+  session_human_input_respond: { sessionRequired: true, allOf: ["sessions:control"] },
   set_other_session_title: { allOf: ["sessions:control"] },
   interaction_discover: { sessionRequired: true, allOf: ["sessions:read"] },
   browser_open: { sessionRequired: true, allOf: ["sessions:control"] },
@@ -483,6 +552,7 @@ const FIRST_PARTY_TOOL_AUTHORIZATION = {
     anyOf: ["scheduled_tasks:manage", "scheduled_tasks:run"],
   },
   slack_bot_list_channels: { allOf: ["connections:read"] },
+  slack_bot_search: { allOf: ["connections:read"] },
   slack_bot_channel_history: { allOf: ["connections:read"] },
   slack_bot_thread_replies: { allOf: ["connections:read"] },
   slack_bot_list_users: { allOf: ["connections:read"] },
@@ -511,6 +581,10 @@ const FIRST_PARTY_TOOL_AUTHORIZATION = {
   artifacts_create: { sessionRequired: true, allOf: ["artifacts:publish"] },
   artifacts_publish: { sessionRequired: true, allOf: ["artifacts:publish"] },
   artifacts_rollback: { sessionRequired: true, allOf: ["artifacts:publish"] },
+  sandbox_file_publish: {
+    sessionRequired: true,
+    allOf: ["files:read", "files:upload"],
+  },
   editable_artifact_list: { sessionRequired: true, allOf: ["artifacts:read"] },
   editable_artifact_create: {
     sessionRequired: true,
@@ -706,15 +780,57 @@ export function buildOpenGeniMcpServer(
       grant,
       sessionId,
       json,
-      options.workspaceMemoryPromptMode ?? "legacy_standing",
+      options.workspaceMemoryPromptMode ?? "retrieval_only",
     );
   }
   if (sessionId !== null && exactAgentAttemptClaims(grant) !== null) {
     registerPreferenceRegistryTools(server, deps, grant, json);
     registerTaskNoteTools(server, deps, grant, sessionId, json);
+    const attempt = exactAgentAttemptClaims(grant)!;
+    registerCompanyBrainGovernedWriteTools({
+      server,
+      db: deps.db,
+      attempt: {
+        accountId: grant.accountId,
+        workspaceId: grant.workspaceId,
+        ...attempt,
+      },
+      authorize: async () => {
+        await authorizeFirstPartySession(deps, grant, sessionId, "session.first_party_mcp.call");
+      },
+      json,
+    });
+    registerCompanyProfileAgentAdminTools({
+      server,
+      db: deps.db,
+      attempt: {
+        accountId: grant.accountId,
+        workspaceId: grant.workspaceId,
+        ...attempt,
+        agentSubjectId: grant.subjectId,
+      },
+      authorize: async () => {
+        await authorizeFirstPartySession(deps, grant, sessionId, "session.first_party_mcp.call");
+      },
+      json,
+    });
+    registerRememberTools({
+      server,
+      db: deps.db,
+      attempt: {
+        accountId: grant.accountId,
+        workspaceId: grant.workspaceId,
+        ...attempt,
+      },
+      authorize: async () => {
+        await authorizeFirstPartySession(deps, grant, sessionId, "session.first_party_mcp.call");
+      },
+      json,
+    });
   }
   if (sessionId !== null && exactAgentAttemptClaims(grant) !== null) {
     registerWorkspaceArtifactTools(server, deps, grant, sessionId, json);
+    registerSandboxFileArtifactTool(server, deps, grant, sessionId, json);
     registerEditableArtifactAgentTools({
       server,
       deps,
@@ -736,7 +852,7 @@ export function buildOpenGeniMcpServer(
     registerFleetTools(server, deps, grant, sessionId, json);
   }
   if (can("enrollments:manage") && deps.settings.sandboxSelfhostedEnabled) {
-    registerConnectedMachineTools(server, deps, grant, json);
+    registerConnectedMachineTools(server, deps, grant, sessionId, json);
   }
   registerRigTools(server, deps, grant, can, sessionId, json);
   registerSlackBotTools(server, deps, grant, sessionId, json);
@@ -1383,6 +1499,9 @@ export function buildOpenGeniMcpServer(
           overlapPolicy: z4.string().optional(),
           agentConfig: z4.unknown(),
           status: z4.string().optional(),
+          // Explicit credential-free connection authority selections; declared
+          // so MCP validation doesn't strip them before the contract parse.
+          connectionAuthorities: z4.array(z4.unknown()).optional(),
           variableSetId: z4.string().uuid().optional(),
           // Deprecated alias of variableSetId; declared so MCP validation doesn't
           // strip it before the contract parse maps it (rename back-compat).
@@ -1447,6 +1566,9 @@ export function buildOpenGeniMcpServer(
           overlapPolicy: z4.string().optional(),
           agentConfig: z4.unknown().optional(),
           status: z4.string().optional(),
+          // Omitted preserves the frozen selections, [] clears them, and an
+          // array replaces them; declared so MCP validation doesn't strip it.
+          connectionAuthorities: z4.array(z4.unknown()).optional(),
           variableSetId: z4.string().uuid().nullable().optional(),
           // Deprecated alias of variableSetId (rename back-compat); declared so MCP
           // validation doesn't strip it before the contract parse maps it.
@@ -1475,7 +1597,7 @@ export function buildOpenGeniMcpServer(
         if (!scheduledTaskUpdateChangesState(existing, update)) {
           return json(scheduledTaskReceipt("scheduled_tasks_update", existing, "unchanged", false));
         }
-        const task = await updateScheduledTask(deps.db, grant.workspaceId, id, update);
+        const task = await updateScheduledTaskForApi(deps.db, grant.workspaceId, id, update);
         await syncUpdatedScheduledTask({
           db: deps.db,
           workflowClient: deps.workflowClient,
@@ -1498,7 +1620,7 @@ export function buildOpenGeniMcpServer(
           return json(scheduledTaskReceipt("scheduled_tasks_pause", existing, "unchanged", false));
         }
         const previous = await captureScheduledTaskRestoreState(deps.db, existing);
-        const task = await updateScheduledTask(deps.db, grant.workspaceId, id, {
+        const task = await updateScheduledTaskForApi(deps.db, grant.workspaceId, id, {
           status: "paused",
         });
         await syncUpdatedScheduledTask({
@@ -1523,9 +1645,17 @@ export function buildOpenGeniMcpServer(
           return json(scheduledTaskReceipt("scheduled_tasks_resume", existing, "unchanged", false));
         }
         const previous = await captureScheduledTaskRestoreState(deps.db, existing);
-        const task = await updateScheduledTask(deps.db, grant.workspaceId, id, {
-          status: "active",
+        const update = await validatedScheduledTaskUpdate({
+          settings: deps.settings,
+          db: deps.db,
+          objectStorage: deps.objectStorage,
+          grant,
+          existing,
+          payload: { status: "active" },
+          sessionAuthorization: deps.sessionAuthorization,
+          authorizationSurface: "first_party_mcp",
         });
+        const task = await updateScheduledTaskForApi(deps.db, grant.workspaceId, id, update);
         await syncUpdatedScheduledTask({
           db: deps.db,
           workflowClient: deps.workflowClient,
@@ -1629,41 +1759,19 @@ export function buildOpenGeniMcpServer(
         inputSchema: { id: z4.string().uuid() },
       },
       async ({ id }) => {
-        const task = await requireScheduledTask(deps.db, grant.workspaceId, id);
-        if (task.metadata.connectorKind === "atlassian") {
-          await revokeAtlassianScheduleAuthorization(deps, {
-            task,
-            subjectId: grant.subjectId,
-          });
-        } else {
-          await revokeKnowledgeSourceScheduleAuthorization(deps, {
-            task,
-            subjectId: grant.subjectId,
-          });
-        }
-        await deps.workflowClient.deleteScheduledTaskSchedule({
-          temporalScheduleId: task.temporalScheduleId,
+        const { task, changed } = await deleteScheduledTaskWithDurableCleanup(deps, {
+          workspaceId: grant.workspaceId,
+          taskId: id,
+          subjectId: grant.subjectId,
         });
-        try {
-          await deleteScheduledTask(deps.db, grant.workspaceId, id);
-        } catch {
-          return json(
-            scheduledTaskReceipt("scheduled_tasks_delete", task, "partial_failure", true, {
-              partialFailure: { stage: "database_delete", retryable: true },
-              warnings: [
-                "The Temporal schedule was deleted, but the task database record remains.",
-              ],
-            }),
-          );
-        }
         return json(
           mcpMutationReceipt({
             operation: "scheduled_tasks_delete",
             committed: true,
             outcome: "deleted",
-            changed: true,
+            changed,
             resource: { type: "scheduled_task", id: task.id, state: "deleted" },
-            idempotency: { status: "not_supported" },
+            idempotency: { status: changed ? "applied" : "replayed" },
           }),
         );
       },
@@ -1692,6 +1800,36 @@ export function buildOpenGeniMcpServer(
   return server;
 }
 
+function registerSandboxFileArtifactTool(
+  server: McpServer,
+  deps: ApiRouteDeps,
+  grant: AccessGrant,
+  sessionId: string,
+  json: JsonResult,
+): void {
+  server.registerTool(
+    "sandbox_file_publish",
+    {
+      description:
+        "Publish one exact file from this session's /workspace into durable workspace storage. Use this before presenting a ZIP, CSV, JSON, Markdown, HTML, PDF, Office file, or other sandbox output as downloadable. Returns a permanent, authenticated artifact receipt; never invent or expose a sandbox: URL as the durable result.",
+      inputSchema: {
+        path: z4.string().min(1).max(4_096),
+      },
+    },
+    async ({ path }) => {
+      await authorizeFirstPartySession(deps, grant, sessionId, "session.first_party_mcp.call");
+      const session = await requireSession(deps.db, grant.workspaceId, sessionId);
+      return json(
+        await publishSandboxFileArtifact(deps, {
+          grant,
+          session,
+          path,
+        }),
+      );
+    },
+  );
+}
+
 function registerSlackBotTools(
   server: McpServer,
   deps: ApiRouteDeps,
@@ -1731,6 +1869,57 @@ function registerSlackBotTools(
       ),
   );
 
+  server.registerTool(
+    "slack_bot_search",
+    {
+      description:
+        "Search public Slack channels workspace-wide as the workspace-shared OpenGeni bot: messages by default, plus files and channels via contentTypes. Public content only; private channels, DMs, and group DMs are searchable only through a member's personal Slack connection. Requires a bot install with the search scopes; older installs must be reinstalled by an admin. Continue with cursor for more results.",
+      inputSchema: {
+        connectionId: z4.string().uuid().optional(),
+        query: z4.string().min(1).max(500),
+        contentTypes: z4
+          .array(z4.enum(["messages", "files", "channels"]))
+          .min(1)
+          .max(3)
+          .optional(),
+        includeBots: z4.boolean().optional(),
+        before: z4.number().int().min(0).optional(),
+        after: z4.number().int().min(0).optional(),
+        sort: z4.enum(["score", "timestamp"]).optional(),
+        sortDir: z4.enum(["asc", "desc"]).optional(),
+        cursor: z4.string().max(1024).optional(),
+        limit: z4.number().int().min(1).max(20).optional(),
+      },
+    },
+    async ({
+      connectionId,
+      query,
+      contentTypes,
+      includeBots,
+      before,
+      after,
+      sort,
+      sortDir,
+      cursor,
+      limit,
+    }) =>
+      json(
+        await (
+          await clientFor(connectionId)
+        ).searchContext({
+          query,
+          ...(contentTypes ? { contentTypes } : {}),
+          ...(includeBots !== undefined ? { includeBots } : {}),
+          ...(before !== undefined ? { before } : {}),
+          ...(after !== undefined ? { after } : {}),
+          ...(sort ? { sort } : {}),
+          ...(sortDir ? { sortDir } : {}),
+          ...(cursor ? { cursor } : {}),
+          ...(limit !== undefined ? { limit } : {}),
+        }),
+      ),
+  );
+
   server.registerTool(
     "slack_bot_channel_history",
     {
@@ -2331,20 +2520,23 @@ function registerGoalTools(
     "goal_set",
     {
       description:
-        "Create a goal when this session has none. While active, idle moments synthesize continuation turns until goal_complete or goal_pause. To change an existing goal, use goal_update with its objective revision, a change kind, and rationale.",
+        "Create a goal when this session has none, or replace a completed goal with a new one. While active, idle moments synthesize continuation turns until goal_complete or goal_pause. To change an active or paused goal, use goal_update with its objective revision, a change kind, and rationale.",
+      // `maxAutoContinuations` is deliberately not agent-facing: the ceiling is
+      // API/scheduled-task pacing configuration, and an agent that set its own
+      // cap used to silence its orchestration for hours. Continuation pacing is
+      // the deployment's input-aware idle backoff instead.
       inputSchema: {
         text: goalText,
         successCriteria: successCriteriaSchema.optional(),
-        maxAutoContinuations: z4.number().int().positive().optional(),
       },
     },
-    async ({ text, successCriteria, maxAutoContinuations }) => {
+    async ({ text, successCriteria }) => {
       await authorizeFirstPartySession(deps, grant, sessionId, "session.goal.write");
       await requireSession(deps.db, grant.workspaceId, sessionId);
       const existing = await getSessionGoal(deps.db, grant.workspaceId, sessionId);
-      if (existing) {
+      if (existing && existing.status !== "completed") {
         throw new Error(
-          `this session already has a goal at objective revision ${existing.objectiveRevision}; use goal_update to revise it`,
+          `this session's goal is ${existing.status} at objective revision ${existing.objectiveRevision}; use goal_update to revise it`,
         );
       }
       const callerTurnId =
@@ -2358,7 +2550,7 @@ function registerGoalTools(
         sessionId,
         text,
         successCriteria: successCriteria ?? null,
-        maxAutoContinuations: maxAutoContinuations ?? null,
+        maxAutoContinuations: null,
         createdBy: "agent",
         actor: "agent",
       });
@@ -2390,19 +2582,13 @@ function registerGoalTools(
     "goal_update",
     {
       description:
-        "Propose or apply a semantic goal revision under the session's mutation policy. Retain the standing goal unless explicit user direction or meaningful new evidence justifies the declared refinement, adaptation, or replacement. A rewrite never counts as execution progress; use goal_progress for that.",
+        "Propose or apply a semantic goal revision under the session's mutation policy. Retain the standing goal unless explicit user direction or meaningful new evidence justifies the declared refinement, adaptation, or replacement. Every rewrite must use the exact expected objective revision and a concise rationale. Root constraints cannot be changed by an agent. A rewrite is not an execution-progress audit fact; use the optional goal_progress tool when such a fact should be recorded.",
       inputSchema: {
         text: goalText.optional(),
         successCriteria: successCriteriaSchema.nullable().optional(),
-        // Optional for rolling compatibility with the former goal_update
-        // surface. Omitted semantic metadata is classified as a refinement of
-        // the currently fenced objective; new callers should always supply it.
-        changeKind: z4.enum(["refinement", "adaptation", "replacement"]).optional(),
-        rationale: goalRationale.optional(),
-        expectedObjectiveRevision: z4.number().int().positive().optional(),
-        // Deprecated compatibility input. It is committed through the new
-        // progress operation and never makes a semantic rewrite count itself.
-        progressNote: progressNoteSchema.optional(),
+        changeKind: z4.enum(["refinement", "adaptation", "replacement"]),
+        rationale: goalRationale,
+        expectedObjectiveRevision: z4.number().int().positive(),
         idempotencyKey: z4.string().uuid(),
       },
     },
@@ -2412,12 +2598,11 @@ function registerGoalTools(
       changeKind,
       rationale,
       expectedObjectiveRevision,
-      progressNote,
       idempotencyKey,
     }) => {
       await authorizeFirstPartySession(deps, grant, sessionId, "session.goal.write");
-      if (text === undefined && successCriteria === undefined && progressNote === undefined) {
-        throw new Error("goal_update requires semantic content or a progressNote");
+      if (text === undefined && successCriteria === undefined) {
+        throw new Error("goal_update requires text or successCriteria");
       }
       const context = exactAgentCommandContext(grant, sessionId);
       const command = {
@@ -2431,36 +2616,22 @@ function registerGoalTools(
         },
         operationKey: idempotencyKey,
       };
-      const semantic =
-        text !== undefined || successCriteria !== undefined
-          ? await updateSessionGoalWithEvent(deps.db, grant.workspaceId, sessionId, {
-              ...(text !== undefined ? { text } : {}),
-              ...(successCriteria !== undefined ? { successCriteria } : {}),
-              changeKind: changeKind ?? "refinement",
-              rationale: rationale ?? "Compatibility refinement from goal_update",
-              ...(expectedObjectiveRevision !== undefined ? { expectedObjectiveRevision } : {}),
-              actor: "agent",
-              command,
-            })
-          : null;
-      const progress = progressNote
-        ? await recordSessionGoalProgressWithEvent(deps.db, grant.workspaceId, sessionId, {
-            progressNote,
-            command,
-          })
-        : null;
-      await publishDurableSessionEvents(deps.bus, grant.workspaceId, sessionId, [
-        ...(semantic?.events ?? []),
-        ...(progress?.events ?? []),
-      ]);
-      const goal = progress?.goal ?? semantic?.goal;
-      if (!goal) throw new Error("goal_update produced no mutation");
+      const semantic = await updateSessionGoalWithEvent(deps.db, grant.workspaceId, sessionId, {
+        ...(text !== undefined ? { text } : {}),
+        ...(successCriteria !== undefined ? { successCriteria } : {}),
+        changeKind,
+        rationale,
+        expectedObjectiveRevision,
+        actor: "agent",
+        command,
+      });
+      await publishDurableSessionEvents(deps.bus, grant.workspaceId, sessionId, semantic.events);
       return json({
-        ...goal,
-        operationId: semantic?.operationId ?? progress?.operationId ?? null,
-        replay: Boolean(semantic?.replay || progress?.replay),
-        outcome: semantic?.outcome ?? "progress_recorded",
-        proposalId: semantic?.proposalId ?? null,
+        ...semantic.goal,
+        operationId: semantic.operationId,
+        replay: semantic.replay,
+        outcome: semantic.outcome,
+        proposalId: semantic.proposalId,
       });
     },
   );
@@ -2502,6 +2673,64 @@ function registerGoalTools(
     },
   );
 
+  server.registerTool(
+    "goal_wait",
+    {
+      description:
+        "Hold the active goal's automatic continuation while progress depends on child sessions or an external event. Use it instead of sleeping or polling sessions_list/session_get/session_events, and only after re-checking the child or external state once. Always end your turn right after calling it: you will be woken by a child result, an agent message, a human prompt, or at the deadline, and the goal stays active. The deadline (untilSeconds) is mandatory and capped at 7 days. Never use goal_wait instead of goal_pause when you are blocked on a human decision.",
+      inputSchema: {
+        reason: goalRationale,
+        untilSeconds: z4
+          .number()
+          .int()
+          .min(SESSION_GOAL_HOLD_MIN_SECONDS)
+          .max(SESSION_GOAL_HOLD_MAX_SECONDS),
+        idempotencyKey: z4.string().uuid().optional(),
+      },
+    },
+    async ({ reason, untilSeconds, idempotencyKey }) => {
+      await authorizeFirstPartySession(deps, grant, sessionId, "session.goal.write");
+      const context = exactAgentCommandContext(grant, sessionId);
+      // Without a caller-supplied key the operation is idempotent per (goal
+      // target, turn, exact arguments): a replacement attempt replaying the
+      // same call receives the stored result instead of re-stamping the hold,
+      // while a genuinely new same-turn wait (different reason/deadline) is a
+      // new operation whose later hold wins.
+      const operationKey =
+        idempotencyKey ??
+        `goal-wait:${context.callerTurnId}:${createHash("sha256")
+          .update(JSON.stringify({ reason, untilSeconds }))
+          .digest("hex")
+          .slice(0, 32)}`;
+      const { goal, events, operationId, replay, untilAt } =
+        await holdSessionGoalContinuationWithEvent(deps.db, grant.workspaceId, sessionId, {
+          reason,
+          untilSeconds,
+          command: {
+            accountId: grant.accountId,
+            actor: {
+              type: "agent_attempt",
+              attemptId: context.callerAttemptId,
+              sessionId: context.callerSessionId,
+              turnId: context.callerTurnId,
+              executionGeneration: context.callerExecutionGeneration,
+            },
+            operationKey,
+          },
+        });
+      await publishDurableSessionEvents(deps.bus, grant.workspaceId, sessionId, events);
+      return json({
+        status: "held",
+        goalId: goal.id,
+        untilAt,
+        operationId,
+        replay,
+        nextAction:
+          "End your turn now; you will be woken by a child result, a message, a human prompt, or at untilAt.",
+      });
+    },
+  );
+
   server.registerTool(
     "goal_complete",
     {
@@ -2713,7 +2942,9 @@ function registerWorkspaceArtifactTools(
         getWorkspaceArtifact(deps.db, grant.workspaceId, artifactId),
         getWorkspaceArtifactContentRef(deps.db, grant.workspaceId, artifactId, versionId),
       ]);
-      const object = await deps.objectStorage.getObjectBytes(ref.contentKey);
+      const object = await retryWhileMissing(async () =>
+        deps.objectStorage!.getObjectBytes(ref.contentKey),
+      );
       if (!object) throw new Error("Artifact content is unavailable");
       const actualHash = createHash("sha256").update(object.bytes).digest("hex");
       if (actualHash !== ref.version.contentSha256)
@@ -2857,7 +3088,11 @@ function registerTaskNoteTools(
     if (!resolved || resolved.sessionId !== sessionId) {
       throw new Error("Exact signed task-note attempt authority is required.");
     }
-    return { accountId: grant.accountId, workspaceId: grant.workspaceId, ...resolved };
+    return {
+      accountId: grant.accountId,
+      workspaceId: grant.workspaceId,
+      ...resolved,
+    };
   };
   const authorize = async () => {
     await authorizeFirstPartySession(deps, grant, sessionId, "session.first_party_mcp.call");
@@ -2891,7 +3126,13 @@ function registerTaskNoteTools(
     },
     async ({ includeArchived, limit }) => {
       await authorize();
-      return json(await listTaskNotes(deps.db, { ...attemptClaims(), includeArchived, limit }));
+      return json(
+        await listTaskNotes(deps.db, {
+          ...attemptClaims(),
+          includeArchived,
+          limit,
+        }),
+      );
     },
   );
 
@@ -2946,6 +3187,53 @@ function registerTaskNoteTools(
       );
     },
   );
+
+  server.registerTool(
+    "task_note_replace",
+    {
+      description:
+        "Atomically correct one exact active coordination note: archive the old immutable note and create a fresh linked replacement. Exact retries replay safely; stale versions or changed input fail closed.",
+      inputSchema: {
+        operationId: z4.string().uuid(),
+        replacedNoteId: z4.string().uuid(),
+        expectedReplacedVersion: z4.number().int().min(1).max(1),
+        replacementKind: z4.enum([
+          "finding",
+          "decision",
+          "blocker",
+          "ownership",
+          "artifact",
+          "handoff",
+        ]),
+        replacementText: boundedUtf8(TASK_NOTE_TEXT_MAX_BYTES, "Task note replacement text"),
+        replacementExpiresInDays: z4.number().int().min(1).max(TASK_NOTE_MAX_LIFETIME_DAYS),
+        reason: boundedUtf8(TASK_NOTE_REASON_MAX_BYTES, "Task note replacement reason"),
+      },
+    },
+    async ({
+      operationId,
+      replacedNoteId,
+      expectedReplacedVersion,
+      replacementKind,
+      replacementText,
+      replacementExpiresInDays,
+      reason,
+    }) => {
+      await authorize();
+      return json(
+        await replaceTaskNote(deps.db, {
+          ...attemptClaims(),
+          operationId,
+          replacedNoteId,
+          expectedReplacedVersion,
+          replacementKind,
+          replacementText,
+          replacementExpiresInDays,
+          reason,
+        }),
+      );
+    },
+  );
 }
 
 function registerPreferenceRegistryTools(
@@ -3060,11 +3348,6 @@ function scheduledTaskUpdateChangesState(
   return false;
 }
 
-function memoryPreview(text: string): string {
-  const normalized = text.replace(/\s+/g, " ").trim();
-  return normalized.length <= 120 ? normalized : `${normalized.slice(0, 119)}…`;
-}
-
 export function memorySlackPublicationActor(
   actor: Extract<SessionAuthorizationActor, { kind: "agent_attempt" }>,
   sessionId: string,
@@ -3091,24 +3374,10 @@ function registerMemoryTools(
   json: JsonResult,
   promptMode: WorkspaceMemoryPromptMode,
 ): void {
-  const publicationActor = async () => {
-    const actor = await requireLiveAgentAttemptAuthorization(deps.db, grant, sessionId);
-    return memorySlackPublicationActor(actor, sessionId, grant.subjectLabel ?? null);
-  };
-  const publicationInputSchema = z4.object({
-    importance: z4.enum(["major", "normal", "minor"]),
-    audience: z4.literal("workspace"),
-    slackMode: z4.enum(["auto", "review", "never"]),
-    shareSummary: z4.string().trim().min(1).max(4_096),
-  });
-
   server.registerTool(
     "memory_search",
     {
-      description:
-        promptMode === "retrieval_only"
-          ? `${MEMORY_SEARCH_TOOL_DESCRIPTION} Legacy preference-kind records are excluded here because structured preferences are the only behavioral authority.`
-          : MEMORY_SEARCH_TOOL_DESCRIPTION,
+      description: `${MEMORY_SEARCH_TOOL_DESCRIPTION} Legacy preference-kind records are excluded from this tool because structured preferences are the only behavioral authority. To save something the user explicitly asked to keep, use \`remember\`; for your own findings use task notes and their promotion tools.`,
       inputSchema: {
         query: z4.string().min(1),
         kind: MemoryKindSchema.optional(),
@@ -3131,204 +3400,10 @@ function registerMemoryTools(
       }),
   );
 
-  server.registerTool(
-    "memory_save",
-    {
-      description:
-        promptMode === "retrieval_only"
-          ? `${MEMORY_SAVE_TOOL_DESCRIPTION} A preference-kind save is retained only as a legacy observation and cannot become behavioral authority; use the structured preference proposal surface for behavioral guidance.`
-          : MEMORY_SAVE_TOOL_DESCRIPTION,
-      inputSchema: {
-        text: z4.string().min(1),
-        kind: MemoryKindSchema,
-        confidence: z4.number().min(0).max(1).optional(),
-        replaces_id: z4.string().min(1).optional(),
-        slack_publication: publicationInputSchema.optional(),
-      },
-    },
-    async ({ text, kind, confidence, replaces_id, slack_publication }) => {
-      const principal = slack_publication ? await publicationActor() : null;
-      const result = await saveWorkspaceMemoryWithSlackPublication(
-        deps.db,
-        {
-          accountId: grant.accountId,
-          workspaceId: grant.workspaceId,
-          sessionId,
-          text,
-          kind,
-          ...(confidence !== undefined ? { confidence } : {}),
-          ...(replaces_id ? { replacesId: replaces_id } : {}),
-          origin: "agent",
-        },
-        slack_publication
-          ? {
-              distribution: MemorySlackPublicationDistribution.parse(slack_publication),
-              actor: principal!.actor,
-              ownerLabel: principal!.ownerLabel,
-            }
-          : null,
-        deps.getDocumentServices().embedder,
-      );
-      await appendAndPublishEvents(deps.db, deps.bus, grant.workspaceId, sessionId, [
-        {
-          type: "memory.saved",
-          payload: {
-            memoryId: result.memory.id,
-            kind: result.memory.kind,
-            preview: memoryPreview(result.memory.text),
-            deduped: result.deduped,
-            ...(result.superseded ? { supersededMemoryId: result.superseded.id } : {}),
-          },
-        },
-      ]);
-      const changed = !result.deduped || result.updated || result.superseded !== null;
-      const outcome =
-        result.updated || result.superseded !== null
-          ? "updated"
-          : result.deduped
-            ? "unchanged"
-            : "created";
-      return json(
-        mcpMutationReceipt({
-          operation: "memory_save",
-          committed: true,
-          outcome,
-          changed,
-          resource: {
-            type: "knowledge_memory",
-            id: result.memory.id,
-            state: result.memory.status,
-          },
-          relatedResources: result.superseded
-            ? [
-                {
-                  type: "knowledge_memory",
-                  id: result.superseded.id,
-                  state: result.superseded.status,
-                },
-              ]
-            : undefined,
-          timestamp: result.memory.updatedAt,
-          idempotency: { status: "not_supported" },
-          warnings: !result.embedded
-            ? ["Memory committed without a vector embedding; keyword search remains available."]
-            : [],
-          facts: {
-            deduped: result.deduped,
-            dedupeReason: result.dedupeReason,
-            updatedInPlace: result.updated,
-            embedded: result.embedded,
-            slackPublicationDecision: result.slackPublication.decision?.eligible
-              ? "eligible"
-              : (result.slackPublication.decision?.reason ?? "not_requested"),
-            slackPublicationId:
-              result.slackPublication.enqueue?.kind === "enqueued" ||
-              result.slackPublication.enqueue?.kind === "replayed"
-                ? result.slackPublication.enqueue.publication.id
-                : null,
-            slackPublicationState:
-              result.slackPublication.enqueue?.kind === "enqueued" ||
-              result.slackPublication.enqueue?.kind === "replayed"
-                ? result.slackPublication.enqueue.publication.state
-                : null,
-          },
-        }),
-      );
-    },
-  );
-
-  server.registerTool(
-    "memory_correct",
-    {
-      description: MEMORY_CORRECT_TOOL_DESCRIPTION,
-      inputSchema: {
-        id: z4.string().min(1),
-        reason: z4.string().min(1).optional(),
-        replacement_text: z4.string().min(1).optional(),
-        slack_publication: publicationInputSchema.optional(),
-      },
-    },
-    async ({ id, reason, replacement_text, slack_publication }) => {
-      const principal = slack_publication ? await publicationActor() : null;
-      const result = await correctWorkspaceMemoryWithSlackPublication(
-        deps.db,
-        {
-          accountId: grant.accountId,
-          workspaceId: grant.workspaceId,
-          sessionId,
-          id,
-          ...(reason ? { reason } : {}),
-          ...(replacement_text ? { replacementText: replacement_text } : {}),
-        },
-        slack_publication
-          ? {
-              distribution: MemorySlackPublicationDistribution.parse(slack_publication),
-              actor: principal!.actor,
-              ownerLabel: principal!.ownerLabel,
-            }
-          : null,
-        deps.getDocumentServices().embedder,
-      );
-      await appendAndPublishEvents(deps.db, deps.bus, grant.workspaceId, sessionId, [
-        {
-          type: "memory.corrected",
-          payload: {
-            memoryId: result.memory.id,
-            kind: result.memory.kind,
-            preview: memoryPreview(result.memory.text),
-            action: result.action,
-            ...(reason ? { reason: memoryPreview(reason) } : {}),
-            ...(result.replacement
-              ? {
-                  replacementMemoryId: result.replacement.id,
-                  replacementPreview: memoryPreview(result.replacement.text),
-                }
-              : {}),
-          },
-        },
-      ]);
-      return json(
-        mcpMutationReceipt({
-          operation: "memory_correct",
-          committed: true,
-          outcome: "updated",
-          changed: true,
-          resource: {
-            type: "knowledge_memory",
-            id: result.memory.id,
-            state: result.memory.status,
-          },
-          relatedResources: result.replacement
-            ? [
-                {
-                  type: "knowledge_memory",
-                  id: result.replacement.id,
-                  state: result.replacement.status,
-                },
-              ]
-            : undefined,
-          timestamp: (result.replacement ?? result.memory).updatedAt,
-          idempotency: { status: "not_supported" },
-          facts: {
-            correctionAction: result.action,
-            slackPublicationDecision: result.slackPublication.decision?.eligible
-              ? "eligible"
-              : (result.slackPublication.decision?.reason ?? "not_requested"),
-            slackPublicationId:
-              result.slackPublication.enqueue?.kind === "enqueued" ||
-              result.slackPublication.enqueue?.kind === "replayed"
-                ? result.slackPublication.enqueue.publication.id
-                : null,
-            slackPublicationState:
-              result.slackPublication.enqueue?.kind === "enqueued" ||
-              result.slackPublication.enqueue?.kind === "replayed"
-                ? result.slackPublication.enqueue.publication.state
-                : null,
-          },
-        }),
-      );
-    },
-  );
+  // Memory V1 writes are retired. Explicit user-directed knowledge goes
+  // through `remember`; an agent's own findings go through task notes and
+  // governed promotion. `memory_search` stays: reading the existing record
+  // set is still how an agent recalls what a workspace already knows.
 }
 
 // Fleet tools (M7 bring-your-own-compute). Session-scoped (they steer THIS
@@ -3353,7 +3428,12 @@ function registerFleetTools(
       const session = await requireSession(deps.db, ctx.workspaceId, ctx.sessionId);
       return await ensureViewerSessionGroupReady(
         { db: deps.db, settings: deps.settings, bus: deps.bus },
-        { accountId: ctx.accountId, workspaceId: ctx.workspaceId, session },
+        {
+          accountId: ctx.accountId,
+          workspaceId: ctx.workspaceId,
+          session,
+          subjectId: ctx.subjectId ?? null,
+        },
       );
     },
   };
@@ -3362,12 +3442,49 @@ function registerFleetTools(
   // call-time via the shared helper (same context the user-authenticated swap
   // REST route builds). Throws when the session has no box (backend:none) — the
   // fleet is only meaningful for a session that runs in a sandbox.
-  const fleetContext = async (): Promise<FleetContext> =>
-    await buildFleetContextForSession(deps, {
+  const fleetContext = async (): Promise<FleetContext> => {
+    const claims = exactAgentAttemptClaims(grant);
+    const actor = claims
+      ? await requireLiveAgentAttemptAuthorization(deps.db, grant, sessionId)
+      : null;
+    return await buildFleetContextForSession(deps, {
       accountId: grant.accountId,
       workspaceId: grant.workspaceId,
       sessionId,
+      ...(actor?.initiatingHumanSubjectId ? { subjectId: actor.initiatingHumanSubjectId } : {}),
+      ...(actor?.initiatingHumanSubjectId && claims
+        ? {
+            attemptAuthority: {
+              turnId: claims.turnId,
+              attemptId: claims.attemptId,
+              executionGeneration: claims.executionGeneration,
+              initiatingHumanSubjectId: actor.initiatingHumanSubjectId,
+            },
+          }
+        : {}),
     });
+  };
+
+  const oneOffCodemodeEnvironment = async (
+    op: RunOnOp,
+  ): Promise<Readonly<Record<string, string>> | undefined> => {
+    if (op.kind !== "exec") return undefined;
+    const claims = exactAgentAttemptClaims(grant);
+    if (!claims || claims.sessionId !== sessionId) return undefined;
+    const material = await mintSandboxCodemodeToken(
+      deps.settings,
+      { accountId: grant.accountId, workspaceId: grant.workspaceId },
+      claims,
+    );
+    if (!material) return undefined;
+    return {
+      OPENGENI_CODEMODE_URL: codemodeWorkspaceUrl(deps.settings, grant.workspaceId),
+      OPENGENI_CODEMODE_TOKEN: material.token,
+      ...(deps.settings.ogtoolPackageSpec
+        ? { OPENGENI_OGTOOL_PACKAGE_SPEC: deps.settings.ogtoolPackageSpec }
+        : {}),
+    };
+  };
 
   server.registerTool(
     "sandboxes_list",
@@ -3383,7 +3500,7 @@ function registerFleetTools(
     "sandbox_attach",
     {
       description:
-        'Attach this session to a sandbox for the next tool call. The target must be owned and verified ready. A same-target attach is a repair request: it revalidates readiness and advances the route epoch rather than returning unchanged success. Recovery-in-progress/degraded/unrecoverable outcomes are typed. Use a sandboxes_list `id`, or "session"/"default" for home.',
+        'Attach this session to a sandbox for subsequent sandbox operations. The target must be owned and verified ready. A managed-home session currently running on a Connected Machine crosses a safe attempt boundary when attached back to home: OpenGeni checkpoints completed work and continues the same logical turn on home without another user message. A same-target attach is a repair request: it revalidates readiness and advances the route epoch rather than returning unchanged success. Recovery-in-progress/degraded/unrecoverable outcomes are typed. Use a sandboxes_list `id`, or "session"/"default" for home.',
       inputSchema: { target: z4.string().min(1) },
     },
     async ({ target }) => json(await swapActiveSandbox(services, await fleetContext(), target)),
@@ -3393,7 +3510,7 @@ function registerFleetTools(
     "sandbox_swap",
     {
       description:
-        'Swap the active sandbox for this session mid-conversation. Validates ownership and verified readiness, then advances the route epoch. Same-target swaps also revalidate and fence stale route caches. An operation that encountered provider disappearance is not replayed; retry only after a typed recovery-ready result. Use a sandboxes_list `id`, or "session"/"default" for home.',
+        'Swap the active sandbox for this session mid-conversation. Validates ownership and verified readiness, then advances the route epoch. A managed-home session currently running on a Connected Machine crosses a safe attempt boundary when swapped back to home: OpenGeni checkpoints completed work and continues the same logical turn on home without another user message. Same-target swaps also revalidate and fence stale route caches. An operation that encountered provider disappearance is not replayed; retry only after a typed recovery-ready result. Use a sandboxes_list `id`, or "session"/"default" for home.',
       inputSchema: { target: z4.string().min(1) },
     },
     async ({ target }) => json(await swapActiveSandbox(services, await fleetContext(), target)),
@@ -3421,8 +3538,15 @@ function registerFleetTools(
         ]),
       },
     },
-    async ({ target, op }) =>
-      json(await runOnSandbox(services, await fleetContext(), target, op as RunOnOp)),
+    async ({ target, op }) => {
+      const typedOp = op as RunOnOp;
+      const transientExecEnvironment = await oneOffCodemodeEnvironment(typedOp);
+      return json(
+        await runOnSandbox(services, await fleetContext(), target, typedOp, {
+          ...(transientExecEnvironment ? { transientExecEnvironment } : {}),
+        }),
+      );
+    },
   );
 
   server.registerTool(
@@ -3454,13 +3578,14 @@ function registerConnectedMachineTools(
   server: McpServer,
   deps: ApiRouteDeps,
   grant: AccessGrant,
+  sessionId: string | null,
   json: JsonResult,
 ): void {
   server.registerTool(
     "connected_machine_remove",
     {
       description:
-        "Remove one enrolled self-hosted machine while it is offline. Access is revoked, future heartbeat/reconnect credentials are rejected, session/route/lease/archive history is retained, and a fresh human-approved device-flow enrollment is required to reconnect. Pass the enrollmentId from the Machines surface, never a Modal sandbox id. Blocked outcomes include every dependent session and the action needed before retrying. Move each dependent session through the canonical sandbox_swap target=default path before retrying removal; the removal authority never rewrites routes directly.",
+        "Remove one enrolled self-hosted machine while it is offline. Access is revoked, future heartbeat/reconnect credentials are rejected, and session, route, lease, archive, and audit history is retained. Idle dependent sessions are detached atomically; machine-home sessions become compute-less (backend none) until another sandbox is selected. Active turns, live leases, and recovery work remain fail-closed blockers whose typed outcome explains what must settle before retrying. Pass the enrollmentId from the Machines surface, never a Modal sandbox id. Reconnecting later requires a fresh human-approved device-flow enrollment.",
       inputSchema: {
         enrollmentId: z4.string().uuid(),
         expectedUpdatedAt: z4.string().datetime({ offset: true }).optional(),
@@ -3468,13 +3593,31 @@ function registerConnectedMachineTools(
       },
     },
     async ({ enrollmentId, expectedUpdatedAt, idempotencyKey }) => {
+      const resourceGrant =
+        sessionId && exactAgentAttemptClaims(grant)
+          ? {
+              ...grant,
+              subjectId:
+                (await requireLiveAgentAttemptAuthorization(deps.db, grant, sessionId))
+                  .initiatingHumanSubjectId ?? grant.subjectId,
+            }
+          : grant;
+      const enrollment = (await listEnrollments(deps.db, resourceGrant, { status: "active" })).find(
+        (candidate) => candidate.id === enrollmentId,
+      );
+      if (!enrollment) {
+        throw new Error("machine enrollment not found in this access scope");
+      }
+      if (enrollment.scope === "organization" && !grant.permissions.includes("account:admin")) {
+        throw new Error("missing permission: account:admin");
+      }
       const result = await removeEnrollment(deps.db, {
         accountId: grant.accountId,
-        workspaceId: grant.workspaceId,
+        workspaceId: enrollment.workspaceId,
         enrollmentId,
         operationKey: idempotencyKey?.trim() || randomUUID(),
         ...(expectedUpdatedAt ? { expectedUpdatedAt } : {}),
-        subjectId: grant.subjectId,
+        subjectId: resourceGrant.subjectId,
       });
       if (!result) {
         throw new Error("machine enrollment not found in this workspace");
@@ -3518,6 +3661,22 @@ function registerRigTools(
   sessionId: string | null,
   json: JsonResult,
 ): void {
+  const resourceGrant = async (): Promise<AccessGrant> => {
+    if (!sessionId || exactAgentAttemptClaims(grant) === null) return grant;
+    const actor = await requireLiveAgentAttemptAuthorization(deps.db, grant, sessionId);
+    return actor.initiatingHumanSubjectId
+      ? { ...grant, subjectId: actor.initiatingHumanSubjectId }
+      : grant;
+  };
+  const requireMutableRig = async (rigId: string) => {
+    const rig = await requireRigForApi(deps.db, await resourceGrant(), rigId);
+    if (rig.scope === "organization") {
+      throw new Error(
+        "Organization rig mutation requires account-admin authority through the authenticated REST surface.",
+      );
+    }
+    return rig;
+  };
   if (can("rigs:use")) {
     server.registerTool(
       "rig_list",
@@ -3525,7 +3684,7 @@ function registerRigTools(
         description: "List workspace rigs and their active versions.",
         inputSchema: {},
       },
-      async () => json({ rigs: await listRigs(deps.db, grant.workspaceId) }),
+      async () => json({ rigs: await listRigs(deps.db, await resourceGrant()) }),
     );
 
     server.registerTool(
@@ -3540,17 +3699,17 @@ function registerRigTools(
         },
       },
       async ({ rigId, versionLimit, changeLimit }) => {
-        const rig = await requireRigForApi(deps.db, grant.workspaceId, rigId);
+        const rig = await requireRigForApi(deps.db, await resourceGrant(), rigId);
         const [versions, changes] = await Promise.all([
           listRigVersionMonitoringSummaries(
             deps.db,
-            grant.workspaceId,
+            rig.workspaceId,
             rig.id,
             boundedRigHistoryLimit(versionLimit),
           ),
           listRigChangeMonitoringSummaries(
             deps.db,
-            grant.workspaceId,
+            rig.workspaceId,
             rig.id,
             boundedRigHistoryLimit(changeLimit),
           ),
@@ -3571,10 +3730,11 @@ function registerRigTools(
         },
       },
       async ({ rigId, command, note }) => {
-        const rig = await requireRigForApi(deps.db, grant.workspaceId, rigId);
+        const rig = await requireMutableRig(rigId);
+        const originGrant = { ...(await resourceGrant()), workspaceId: rig.workspaceId };
         const change = await proposeRigChangeForApi(
           { db: deps.db },
-          grant,
+          originGrant,
           rig,
           {
             kind: "setup_append",
@@ -3582,11 +3742,11 @@ function registerRigTools(
           },
           sessionId ? { proposedBy: `session:${sessionId}` } : {},
         );
-        const verifying = await beginMcpRigVerificationAttempt(deps, grant.workspaceId, change.id);
+        const verifying = await beginMcpRigVerificationAttempt(deps, rig.workspaceId, change.id);
         const attempt = verificationAttempt(verifying);
         try {
           await deps.workflowClient.startRigVerification({
-            workspaceId: grant.workspaceId,
+            workspaceId: rig.workspaceId,
             changeId: change.id,
             workflowId: `rig-verification-change-${change.id}-attempt-${attempt}`,
           });
@@ -3651,18 +3811,14 @@ function registerRigTools(
         },
       },
       async ({ rigId, changeId }) => {
-        const rig = await requireRigForApi(deps.db, grant.workspaceId, rigId);
+        const rig = await requireMutableRig(rigId);
         if (changeId) {
-          const change = await requireRigChangeForApi(deps.db, grant.workspaceId, rig.id, changeId);
-          const verifying = await beginMcpRigVerificationAttempt(
-            deps,
-            grant.workspaceId,
-            change.id,
-          );
+          const change = await requireRigChangeForApi(deps.db, rig.workspaceId, rig.id, changeId);
+          const verifying = await beginMcpRigVerificationAttempt(deps, rig.workspaceId, change.id);
           const attempt = verificationAttempt(verifying);
           try {
             await deps.workflowClient.startRigVerification({
-              workspaceId: grant.workspaceId,
+              workspaceId: rig.workspaceId,
               changeId: change.id,
               workflowId: `rig-verification-change-${change.id}-attempt-${attempt}`,
             });
@@ -3721,7 +3877,7 @@ function registerRigTools(
           throw new Error("rig has no active version");
         }
         await deps.workflowClient.startRigVerification({
-          workspaceId: grant.workspaceId,
+          workspaceId: rig.workspaceId,
           versionId: rig.activeVersion.id,
           workflowId: `rig-verification-version-${rig.activeVersion.id}-${crypto.randomUUID()}`,
         });
@@ -3758,11 +3914,12 @@ function registerRigTools(
         },
       },
       async ({ rigId, changeId }) => {
-        const rig = await requireRigForApi(deps.db, grant.workspaceId, rigId);
-        const change = await requireRigChangeForApi(deps.db, grant.workspaceId, rig.id, changeId);
+        const rig = await requireMutableRig(rigId);
+        const change = await requireRigChangeForApi(deps.db, rig.workspaceId, rig.id, changeId);
+        const originGrant = { ...(await resourceGrant()), workspaceId: rig.workspaceId };
         const promoted = await promoteVerifiedDefinitionEditChangeForApi(
           { db: deps.db },
-          grant,
+          originGrant,
           rig,
           change,
         );
@@ -3841,7 +3998,7 @@ function registerWorkspaceOrchestrationTools(
     server.registerTool(
       "sessions_list",
       {
-        description: `List compact high-level session status in this workspace. Defaults to creation order; use orderBy=updatedAt with decimal activity-revision updatedAfter/updatedThrough tokens for gap-free indexed incremental monitoring independent of application clocks. Cursors are opaque revision-fenced keysets. includeLastMessage is opt-in; its rendered previews share a deterministic ${SESSION_DISCOVERY_PREVIEW_MAX_BYTES}-byte UTF-8 aggregate budget, and omitted previews include a bounded session_events drill-down input (exact message type, direction=before, limit=1, monitoring summary). Use session_get for exact known targets and detailed resources/tools/settings. The list never returns full session objects or history.`,
+        description: `List compact high-level session status in this workspace. Defaults to creation order; use orderBy=updatedAt with decimal activity-revision updatedAfter/updatedThrough tokens for gap-free indexed incremental monitoring independent of application clocks. Cursors are opaque revision-fenced keysets. includeLastMessage is opt-in and never previews a human/API prompt whose turn was never claimed (still queued, or deleted/edited/cancelled before any claim): waiting work is represented by queuedPromptCount until the turn is claimed. Rendered previews share a deterministic ${SESSION_DISCOVERY_PREVIEW_MAX_BYTES}-byte UTF-8 aggregate budget, and omitted previews include a bounded session_events drill-down input (exact message type, direction=before, limit=1, monitoring summary). Use session_get for exact known targets and detailed resources/tools/settings. The list never returns full session objects or history.`,
         inputSchema: {
           limit: z4.number().int().positive().max(100).optional(),
           cursor: z4.string().max(512).optional(),
@@ -3888,7 +4045,7 @@ function registerWorkspaceOrchestrationTools(
       "session_get",
       {
         description:
-          "Get another session you are managing: status, goal-bearing metadata, resources, tools, and variableSet attachment (names/ids only, never variable values). Do not call this with your own current session id to reconstruct context; your model-facing conversation history and persistent setting state are already supplied directly. Unbounded agent-set fields are clamped so monitoring another session cannot flood this context.",
+          "Get another session you are managing: status, goal-bearing metadata, resources, persisted tool refs, exact bounded effectiveToolPolicy, and variableSet attachment (names/ids only, never variable values). effectiveToolPolicy distinguishes selected refs from workspace defaults, mandatory carriers, configured/deferred refs, and dropped refs. Do not call this with your own current session id to reconstruct context; your model-facing conversation history and persistent setting state are already supplied directly. Unbounded agent-set fields are clamped so monitoring another session cannot flood this context.",
         inputSchema: { sessionId: z4.string().uuid() },
       },
       async ({ sessionId }) => {
@@ -3925,7 +4082,7 @@ function registerWorkspaceOrchestrationTools(
       "session_events",
       {
         description:
-          "Read a compact semantic tail only when session_get status is insufficient. With no cursor, this returns the newest matching events and excludes raw message/reasoning/command/PTY deltas. Use `latest` as an exclusive lookup for the authoritative newest durable sequence in exactly one semantic class; `receipt` is the concise alias for `tool_receipt`, and latest cannot be combined with type or class filters. Add `resultMode=compact` to latest for one bounded result-bearing completion/checkpoint/receipt without another inference. Use nextBefore to page older or explicit after/nextAfter to page forward. Type/class filters run in the RLS-scoped database query. payloadMode none|summary|full controls retained audit payload projection, but every model result is independently byte-capped with explicit truncation and exact covered sequence bounds. Exact retained forensic payloads require the access-controlled REST/SDK events API with mode=forensic&payloadMode=full; generic source bytes never retained by the audit boundary remain unavailable.",
+          "Read a compact semantic tail only when session_get status is insufficient. With no cursor, this returns the newest matching events and excludes raw message/reasoning/command/PTY deltas. Monitoring mode also omits a human/API user.message whose turn was never claimed (still queued, or deleted/edited/cancelled before any claim; waiting work is represented by sessions_list queuedPromptCount); the row appears at its own sequence once the turn is claimed. Use `latest` as an exclusive lookup for the authoritative newest durable sequence in exactly one semantic class; `receipt` is the concise alias for `tool_receipt`, and latest cannot be combined with type or class filters. Add `resultMode=compact` to latest for one bounded result-bearing completion/checkpoint/receipt without another inference. Use nextBefore to page older or explicit after/nextAfter to page forward. Type/class filters run in the RLS-scoped database query. payloadMode none|summary|full controls retained audit payload projection, but every model result is independently byte-capped with explicit truncation and exact covered sequence bounds. Exact retained forensic payloads, including unclaimed prompt rows, require mode=forensic or the access-controlled REST/SDK events API with mode=forensic&payloadMode=full; generic source bytes never retained by the audit boundary remain unavailable.",
         inputSchema: {
           sessionId: z4.string().uuid(),
           after: z4.number().int().nonnegative().optional(),
@@ -3998,6 +4155,7 @@ function registerWorkspaceOrchestrationTools(
           includeClasses: latestClass ? [latestClass] : (includeClasses ?? []),
           excludeClasses: excludeClasses ?? [],
           ...(mode === "monitoring" ? { defaultExcludeTypes: SESSION_EVENT_RAW_DELTA_TYPES } : {}),
+          ...(mode === "monitoring" ? { excludeUnclaimedHumanPrompts: true } : {}),
           ...(latestClass ? { authoritativeLatest: true } : {}),
           maxBytes: SESSION_EVENT_MCP_MAX_BYTES * 4,
         });
@@ -4032,13 +4190,106 @@ function registerWorkspaceOrchestrationTools(
         );
       },
     );
+
+    server.registerTool(
+      "session_wait",
+      {
+        description: `Block until a watched session has new durable events after your cursor, until your own session has pending machine input (a child result, an agent message, a steer), or until maxWaitSeconds (default ${SESSION_WAIT_DEFAULT_SECONDS}, max ${SESSION_WAIT_MAX_SECONDS}) elapses. Use this for short waits inside the current turn instead of sleeping and polling session_events/session_get/sessions_list while a child or peer session works; for long waits end this turn with goal_wait rather than looping session_wait for hours while holding the turn and sandbox. Pass each target's sessionId and afterSequence (its last seen sequence, 0 for a new session); returns immediately when anything already changed. Only turn lifecycle, agent.message.completed, blocking failures, goal facts, and session status/control changes count as a change; raw deltas, tool receipts, and sandbox diagnostics never wake it. Each changed target returns a bounded compact summary of up to ${SESSION_WAIT_EVENTS_PER_TARGET} exact durable events plus latestSequence (pass it back as the next afterSequence) and hasMore (drill down with session_events after=latestSequence). ownPendingUpdates > 0 means your own session has machine input that is delivered only when your next turn is claimed: finish this turn to receive it, or pass includeOwnPendingUpdates=false to keep waiting on the targets. timedOut=true means nothing changed; liveFanout=false means the live bus was unavailable and the wait relied on the deadline re-check. The whole result is byte-bounded: summaries are shortened first, then newest rows dropped, so a changed target may come back with events=[] and hasMore=true; read those rows with session_events after=latestSequence. The wait cannot exceed ${SESSION_WAIT_MAX_SECONDS} seconds because the MCP client request timeout is 60 seconds.`,
+        inputSchema: {
+          targets: z4
+            .array(
+              z4.object({
+                sessionId: z4.string().uuid(),
+                afterSequence: z4.number().int().nonnegative(),
+              }),
+            )
+            .min(1)
+            .max(SESSION_WAIT_MAX_TARGETS),
+          includeOwnPendingUpdates: z4
+            .boolean()
+            .optional()
+            .describe(
+              "Also return when your own session has pending machine input (default true).",
+            ),
+          maxWaitSeconds: z4.number().int().min(1).max(SESSION_WAIT_MAX_SECONDS).optional(),
+        },
+      },
+      async ({ targets, includeOwnPendingUpdates, maxWaitSeconds }, extra) => {
+        const distinct = new Set(targets.map((target) => target.sessionId));
+        if (distinct.size !== targets.length) {
+          throw new Error("session_wait targets must name distinct sessions");
+        }
+        // Authorize and resolve every target exactly as session_events does,
+        // before any live-fanout subscription exists for it.
+        for (const target of targets) {
+          await authorizeFirstPartySession(deps, grant, target.sessionId, "session.events.read");
+          await requireSession(deps.db, grant.workspaceId, target.sessionId);
+        }
+        const ownSessionId = includeOwnPendingUpdates === false ? null : callerSessionId;
+        // The API serves one transport per POST, so the worker's MCP cancel
+        // notification never reaches this handler; the route binds the HTTP
+        // request's abort to transport.close() (mcp/request-abort.ts), which
+        // aborts `extra.signal` when the worker drops the call on Steer/Pause.
+        // The deadline bounds the wait regardless. Direct handler invocation
+        // (tests) may pass no extra at all.
+        const signal: AbortSignal | undefined = extra?.signal;
+        const workspaceId = grant.workspaceId;
+        // A NATS subscription is live fanout only; the durable session_events
+        // read below is the authority. Bun.serve idleTimeout (255 s) and the
+        // 60 s MCP client request timeout both exceed the 50 s cap.
+        return json(
+          await waitForSessionChanges({
+            targets,
+            ownSessionId,
+            maxWaitMs: (maxWaitSeconds ?? SESSION_WAIT_DEFAULT_SECONDS) * 1_000,
+            signal,
+            source: {
+              reauthorizeTargets: async (sessionIds) => {
+                for (const targetSessionId of sessionIds) {
+                  await authorizeFirstPartySession(
+                    deps,
+                    grant,
+                    targetSessionId,
+                    "session.events.read",
+                  );
+                }
+              },
+              readTargetEvents: async (target) => {
+                const page = await listSessionEventPage(deps.db, workspaceId, target.sessionId, {
+                  after: target.afterSequence,
+                  direction: "after",
+                  limit: SESSION_WAIT_EVENTS_PER_TARGET,
+                  payloadMode: "full",
+                  includeTypes: SESSION_WAIT_EVENT_TYPES,
+                  maxBytes: SESSION_EVENT_MCP_MAX_BYTES * 4,
+                });
+                return { events: page.events, hasMore: page.hasMore };
+              },
+              readOwnPendingUpdateKinds:
+                ownSessionId === null
+                  ? null
+                  : async () =>
+                      (
+                        await listOutstandingSessionSystemUpdates(
+                          deps.db,
+                          workspaceId,
+                          ownSessionId,
+                        )
+                      ).map((update) => update.kind),
+              subscribe: (targetSessionId, onEvents) =>
+                deps.bus.subscribe(workspaceId, targetSessionId, onEvents),
+            },
+          }),
+        );
+      },
+    );
   }
 
   if (can("sessions:create") && sessionCreateVisible) {
     const sessionCreateInput = z4
       .object({
         initialMessage: z4.string().min(1),
-        instructions: z4.string().min(1).max(32768).optional(),
+        instructions: z4.string().min(1).max(SESSION_INSTRUCTIONS_MAX_CHARACTERS).optional(),
         goal: z4.unknown().optional(),
         resources: z4.array(z4.unknown()).optional(),
         tools: z4.array(z4.unknown()).optional(),
@@ -4099,7 +4350,7 @@ function registerWorkspaceOrchestrationTools(
       "session_create",
       {
         description:
-          "Spawn a new agent session (a worker). Omit sandbox for the safe default: compatible children share the creator's box, while a different Variable Set or Rig gets its own compatible box. Use 'new' for deliberate isolation or {groupId} for a strict compatible sibling join. Put targetSandboxId and its optional workingDir together inside machineTarget. To create a non-delegating leaf, pass a narrowed firstPartyMcpTools list that omits session_create; do not use a child-local depth override. Public REST/SDK callers retain advanced absolute depth and explicit shared-placement controls.",
+          "Spawn a new agent session (a worker). The child inherits this session's visibility; a private session can only create a same-owner private child. Give a goal-bearing child its delegated objective. Its goal.rootConstraints may be an exact applicable subset of this accepted turn's frozen root constraints; omit that field to inherit all of them. Omit sandbox for the safe default: compatible children share the creator's box, while a different Variable Set, Rig, or machineTarget gets its own box. Use 'new' for deliberate isolation or {groupId} for a strict compatible sibling join. Put targetSandboxId and its optional workingDir together inside machineTarget; a machineTarget is always an own-box create even when the parent is backend none. To create a non-delegating leaf, pass a narrowed firstPartyMcpTools list that omits session_create; do not use a child-local depth override. Public REST/SDK callers retain advanced absolute depth and explicit shared-placement controls.",
         inputSchema: sessionCreateInput,
       },
       async (args) => {
@@ -4211,7 +4462,11 @@ function registerWorkspaceOrchestrationTools(
               },
               relatedResources: [
                 { type: "session", id: targetSessionId },
-                { type: "session_event", id: accepted.id, state: accepted.type },
+                {
+                  type: "session_event",
+                  id: accepted.id,
+                  state: accepted.type,
+                },
               ],
               timestamp: accepted.occurredAt,
               idempotency: { status: replay ? "replayed" : "applied" },
@@ -4404,6 +4659,85 @@ function registerWorkspaceOrchestrationTools(
           );
         },
       );
+
+      server.registerTool(
+        "session_human_input_respond",
+        {
+          description:
+            "Answer (or skip, when the request allows it) a structured human-input request that another session is blocked on, typically a worker you spawned after a `child_requires_action` update named its requestId. Use it only when you actually know the answer; otherwise report the exact blocker to the user. Tool approvals are decided by humans only and cannot be answered here. The response is recorded as an agent-attempt answer and resumes that session's blocked turn.",
+          inputSchema: {
+            sessionId: z4.string().uuid(),
+            requestId: z4.string().uuid(),
+            response: z4.unknown(),
+            idempotencyKey: z4.string().uuid(),
+          },
+        },
+        async ({ sessionId, requestId, response, idempotencyKey }) => {
+          await authorizeFirstPartySession(deps, grant, sessionId, "session.human_input.write");
+          const context = exactAgentCommandContext(grant, callerSessionId, "first_party_mcp");
+          const parsedResponse = SubmitHumanInputResponseRequest.parse(response);
+          let accepted: Awaited<ReturnType<typeof acceptSessionHumanInputResponse>>;
+          try {
+            accepted = await acceptSessionHumanInputResponse(deps.db, {
+              accountId: grant.accountId,
+              workspaceId: grant.workspaceId,
+              sessionId,
+              requestId,
+              response: parsedResponse,
+              respondedBy: `agent_attempt:${context.callerAttemptId}`,
+              respondedByKind: "agent_attempt",
+              clientEventId: idempotencyKey,
+            });
+          } catch (error) {
+            if (error instanceof HumanInputResponseValidationError) {
+              throw new Error(`human-input response rejected: ${error.message}`, { cause: error });
+            }
+            throw error;
+          }
+          if (accepted.action === "not_found") {
+            throw new Error("human-input request not found");
+          }
+          await publishDurableSessionEvents(
+            deps.bus,
+            grant.workspaceId,
+            sessionId,
+            accepted.events,
+          );
+          if (accepted.workflowWakeRevision !== null) {
+            await deps.workflowClient.signalApprovalDecision({
+              accountId: grant.accountId,
+              workspaceId: grant.workspaceId,
+              sessionId,
+              eventId: accepted.events[0]?.id ?? requestId,
+              workflowId: `session-${sessionId}`,
+              workflowWakeRevision: accepted.workflowWakeRevision,
+            });
+          }
+          if (accepted.action === "conflict") {
+            throw new Error(`human-input request is ${accepted.request.status}`);
+          }
+          return json(
+            mcpMutationReceipt({
+              operation: "session_human_input_respond",
+              committed: true,
+              outcome: accepted.events.length === 0 ? "replayed" : "updated",
+              changed: accepted.events.length > 0,
+              resource: {
+                type: "session_human_input_request",
+                id: requestId,
+                state: accepted.request.status,
+              },
+              relatedResources: [{ type: "session", id: sessionId }],
+              timestamp: accepted.request.respondedAt ?? new Date().toISOString(),
+              idempotency: {
+                status: accepted.events.length === 0 ? "replayed" : "applied",
+              },
+              facts: { outcome: accepted.request.response?.outcome ?? null },
+              nextAction: { tool: "session_get", arguments: { sessionId } },
+            }),
+          );
+        },
+      );
     }
 
     server.registerTool(
@@ -4441,6 +4775,11 @@ function registerVariableSetTools(
   sessionId: string | null,
   json: JsonResult,
 ): void {
+  const variableSetAccess = {
+    accountId: grant.accountId,
+    workspaceId: grant.workspaceId,
+    subjectId: grant.subjectId,
+  };
   const registerListTool = (name: string, description: string): void => {
     server.registerTool(
       name,
@@ -4449,7 +4788,7 @@ function registerVariableSetTools(
         inputSchema: {},
       },
       async () => {
-        const variableSets = await listVariableSets(deps.db, grant.workspaceId);
+        const variableSets = await listVariableSets(deps.db, variableSetAccess);
         return json({ variableSets, environments: variableSets });
       },
     );
@@ -4491,14 +4830,14 @@ function registerVariableSetTools(
       let created = false;
       let variableSet =
         targetId !== undefined
-          ? await getVariableSet(deps.db, grant.workspaceId, targetId)
-          : await getVariableSetByName(deps.db, grant.workspaceId, trimmedVariableSetName!);
+          ? await getVariableSet(deps.db, variableSetAccess, targetId)
+          : await getVariableSetByName(deps.db, variableSetAccess, trimmedVariableSetName!);
       if (!variableSet && targetId !== undefined) {
         throw new Error("variable set/environment not found");
       }
       if (!variableSet) {
         if (
-          (await countVariableSets(deps.db, grant.workspaceId)) >= MAX_ENVIRONMENTS_PER_WORKSPACE
+          (await countVariableSets(deps.db, variableSetAccess)) >= MAX_ENVIRONMENTS_PER_WORKSPACE
         ) {
           throw new Error(
             `a workspace supports at most ${MAX_ENVIRONMENTS_PER_WORKSPACE} variable sets`,
@@ -4507,6 +4846,8 @@ function registerVariableSetTools(
         variableSet = await createVariableSet(deps.db, {
           accountId: grant.accountId,
           workspaceId: grant.workspaceId,
+          scope: "workspace",
+          subjectId: grant.subjectId,
           name: trimmedVariableSetName!,
         });
         created = true;
@@ -4525,6 +4866,7 @@ function registerVariableSetTools(
       const metadata = await setVariableSetVariable(deps.db, {
         accountId: grant.accountId,
         workspaceId: grant.workspaceId,
+        subjectId: grant.subjectId,
         variableSetId: variableSet.id,
         name: parsedName.data,
         valueEncrypted: encryptVariableSetValue(key, value),
@@ -4982,7 +5324,8 @@ function registerGitHubConnectTool(
 }
 
 // Defense-in-depth for invariant "agents cannot self-attach": the worker's
-// first-party delegated token never carries variable-sets:use, so sandboxed
+// first-party delegated token must carry both exact attachment and use
+// permissions, so a token narrowed to only one cannot attach a variable set.
 // agents calling these MCP tools cannot attach a variable set.
 // Explicit detach (variableSetId: null) is also an attachment change and is
 // blocked the same way.
@@ -4990,12 +5333,23 @@ function requireVariableSetsUseForMcpAttachment(
   grant: AccessGrant,
   variableSetId: string | null | undefined,
 ): void {
-  if (variableSetId !== undefined && !hasPermission(grant.permissions, "variable-sets:use")) {
+  if (variableSetId === undefined) return;
+  if (!hasPermission(grant.permissions, "variable-sets:attach")) {
+    throw new Error("missing permission: variable-sets:attach");
+  }
+  if (variableSetId !== null && !hasPermission(grant.permissions, "variable-sets:use")) {
     throw new Error("missing permission: variable-sets:use");
   }
 }
 
-function repositoryWithScheduledTaskResource(
+/**
+ * Project one allowlisted GitHub App repository into the resource an agent or
+ * scheduled task attaches. Every listed repository is in the workspace
+ * allowlist, public or private, so every resource carries the stable ids
+ * that mint the scoped installation token; a bare URI would clone anonymously
+ * and could never push.
+ */
+export function repositoryWithScheduledTaskResource(
   repository: GitHubRepository,
 ): GitHubRepository & { resource: ResourceRef } {
   const uri = normalizedRepositoryUri(repository.cloneUrl);
@@ -5007,12 +5361,8 @@ function repositoryWithScheduledTaskResource(
       ref: repository.defaultBranch,
       provider: "github",
       mountPath: defaultRepositoryMountPath(uri, "github"),
-      ...(repository.private
-        ? {
-            githubInstallationId: repository.installationId,
-            githubRepositoryId: repository.id,
-          }
-        : {}),
+      githubInstallationId: repository.installationId,
+      githubRepositoryId: repository.id,
     },
   };
 }