@opengeni/db 1.0.1 → 3.2.0-canary.0

package/src/session-control.ts

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import {
   boundWorkspaceControlEvent,
+  childPausedClassification,
   McpPersonalConnectionDelegations,
   workspaceControlUtf8Bytes,
   type SessionMcpApprovalPolicy,
@@ -9,12 +10,25 @@ import {
 import { and, eq, inArray, sql } from "drizzle-orm";
 import type { Database, SessionActivityDatabase } from "./database";
 import { withLosslessContentWriteVersion } from "./lossless-json";
+import { nestedPostgresSqlState } from "./persistence-errors";
 import * as schema from "./schema";
+import {
+  boundedChildPausedReason,
+  childLifecycleNoticesEnabled,
+  childPausedDedupeKey,
+  childPausedSummary,
+  childRequiresActionResolvedDedupeKey,
+  childRequiresActionResolvedSummary,
+} from "./child-lifecycle-notices";
 import { closePendingSessionToolCallsInTransaction } from "./session-tool-call-settlement";
 import {
   mirrorSessionRealtimeContextInTransaction,
   renderRealtimeHumanInputResponseContext,
 } from "./session-realtime-mirror";
+import {
+  requestSessionBackgroundCommandCancellationsInTransaction,
+  requestWorkspaceBackgroundCommandCancellationsInTransaction,
+} from "./session-background-commands";
 
 type SessionEventInsertWithPayload = typeof schema.sessionEvents.$inferInsert & {
   payload: unknown;
@@ -84,6 +98,10 @@ export type EffectiveSessionControl = {
     interruptionPendingCount: number;
     quiescencePendingCount: number;
   } | null;
+  backgroundCommandSettlement: {
+    state: "stopping";
+    commandCount: number;
+  } | null;
 };
 
 type SettlementAttemptCounts = {
@@ -300,23 +318,8 @@ export async function assertAgentCommandAuthorityInTransaction(
   if (input.action === "steer" && input.targetSessionId === input.actor.sessionId) {
     throw new AgentCommandAuthorityError("SELF_STEER", "An agent cannot steer its own session");
   }
-  const targetsSelf = targetSession.id === callerSession.id;
-  const targetsDirectParent = callerSession.parentSessionId === targetSession.id;
-  const targetsDirectChild = targetSession.parentSessionId === callerSession.id;
-  const verticalTargetAllowed =
-    input.action === "goal"
-      ? targetsSelf
-      : input.action === "message"
-        ? targetsSelf || targetsDirectParent || targetsDirectChild
-        : targetsDirectChild;
-  if (!verticalTargetAllowed) {
-    throw new AgentCommandAuthorityError(
-      "TARGET_NOT_VERTICAL",
-      input.action === "message"
-        ? "An agent may message only its own session, direct parent, or direct child"
-        : "An agent may control only a direct child session",
-    );
-  }
+  // Peer, parent, child, and unrelated-root targets are allowed here. Slack-private
+  // and user_private denies remain in requireSessionAuthorization.
 }
 
 function asSafeRevision(value: number | string | null, label: string): number | null {
@@ -360,25 +363,188 @@ function lockClause(mode: WorkspaceControlLockMode) {
   return mode === "update" ? sql.raw("for update") : sql.raw("for share");
 }
 
+/**
+ * Default bounded control-prefix wait for request-scoped API mutations (Send,
+ * Steer, queued Steer, Pause/Resume/Cancel, workspace Pause/Resume, realtime
+ * sync). The bound is one budget across every lock step of the admission
+ * (advisory lock, row lock, and the savepoint escalation of a paused branch),
+ * not a per-statement timeout. A request that cannot enter the workspace
+ * control prefix within the budget fails with the typed, retryable
+ * `WorkspaceControlBusyError` before any write instead of holding a pooled
+ * connection and a snapshot for as long as the HTTP client (or ingress) keeps
+ * the socket open. Worker settlement, claims, and event appends never pass a
+ * bound: a legitimate wait there must not become a failed settlement.
+ * The deployment value is `OPENGENI_WORKSPACE_CONTROL_LOCK_TIMEOUT_MS`, parsed
+ * and validated once at boot by `@opengeni/config`
+ * (`settings.workspaceControlLockTimeoutMs`) and handed to this module through
+ * `configureWorkspaceControlRequestLockTimeoutMs` when the API app is built.
+ * This module never reads `process.env` per request.
+ */
+export const WORKSPACE_CONTROL_REQUEST_LOCK_TIMEOUT_MS = 20_000;
+
+let configuredRequestLockTimeoutMs = WORKSPACE_CONTROL_REQUEST_LOCK_TIMEOUT_MS;
+
+/**
+ * Install the validated request-scoped budget for this process. The value is
+ * process-global and last-writer-wins: the API calls this exactly once from
+ * its settings at app composition (`createApp`), and every later
+ * `workspaceControlRequestLockTimeoutMs()` read observes that value. Workers
+ * never call it because they never pass a bound. A non-positive or
+ * non-integer value is a programming error here (the config layer already
+ * rejected it at boot).
+ */
+export function configureWorkspaceControlRequestLockTimeoutMs(lockTimeoutMs: number): void {
+  if (!Number.isSafeInteger(lockTimeoutMs) || lockTimeoutMs <= 0) {
+    throw new Error("Workspace control request lock timeout must be a positive integer (ms)");
+  }
+  configuredRequestLockTimeoutMs = lockTimeoutMs;
+}
+
+/** The request-scoped budget in milliseconds currently configured for this process. */
+export function workspaceControlRequestLockTimeoutMs(): number {
+  return configuredRequestLockTimeoutMs;
+}
+
+export class WorkspaceControlBusyError extends Error {
+  readonly code = "WORKSPACE_CONTROL_BUSY";
+
+  constructor(
+    readonly workspaceId: string,
+    readonly lockTimeoutMs: number,
+  ) {
+    super("The workspace control row is busy; retry shortly");
+    this.name = "WorkspaceControlBusyError";
+  }
+}
+
+/**
+ * One wall-clock budget shared by every lock step of one control-prefix
+ * acquisition. Each step sets `lock_timeout` to the remaining budget, so the
+ * total wait never exceeds the requested bound even when the advisory lock,
+ * the row lock, and a savepoint escalation each wait in turn.
+ */
+export type WorkspaceControlLockBudget = {
+  readonly totalMs: number;
+  readonly deadlineAt: number;
+};
+
+export function workspaceControlLockBudget(lockTimeoutMs: number): WorkspaceControlLockBudget {
+  if (!Number.isFinite(lockTimeoutMs) || lockTimeoutMs <= 0) {
+    throw new Error("Workspace control lockTimeoutMs must be a positive number");
+  }
+  const totalMs = Math.max(1, Math.floor(lockTimeoutMs));
+  return { totalMs, deadlineAt: Date.now() + totalMs };
+}
+
+export type WorkspaceControlLockOptions = {
+  /**
+   * Bound the whole prefix acquisition in milliseconds. Omit for
+   * worker/lifecycle writers. The previous `lock_timeout` is restored once the
+   * prefix is held.
+   */
+  lockTimeoutMs?: number;
+  /** Share an already running budget (used by the admission helper). */
+  budget?: WorkspaceControlLockBudget;
+};
+
+function advisoryLockFunction(mode: Exclude<WorkspaceControlLockMode, "none">) {
+  return mode === "update"
+    ? sql.raw("pg_advisory_xact_lock")
+    : sql.raw("pg_advisory_xact_lock_shared");
+}
+
+function lockBudgetFor(options: WorkspaceControlLockOptions): WorkspaceControlLockBudget | null {
+  if (options.budget) return options.budget;
+  if (options.lockTimeoutMs === undefined) return null;
+  return workspaceControlLockBudget(options.lockTimeoutMs);
+}
+
+/** Run one lock-acquiring statement under the remaining budget. */
+async function boundedLockStep<T>(
+  db: Database,
+  workspaceId: string,
+  budget: WorkspaceControlLockBudget | null,
+  step: () => Promise<T>,
+): Promise<T> {
+  if (!budget) return await step();
+  const remainingMs = budget.deadlineAt - Date.now();
+  if (remainingMs <= 0) throw new WorkspaceControlBusyError(workspaceId, budget.totalMs);
+  await db.execute(
+    sql`select set_config('lock_timeout', ${`${Math.max(1, Math.floor(remainingMs))}ms`}, true)`,
+  );
+  try {
+    return await step();
+  } catch (error) {
+    if (nestedPostgresSqlState(error) === "55P03") {
+      // Deliberately no `cause`: the 55P03 must not stay reachable through the
+      // cause chain, or persistence-retry classification and the delete-tree
+      // `live_sandboxes` 55P03 mapping would reclassify this typed busy error.
+      throw new WorkspaceControlBusyError(workspaceId, budget.totalMs);
+    }
+    throw error;
+  }
+}
+
+/**
+ * Lock the mandatory workspace inference-control row.
+ *
+ * `share` and `update` first take a transaction-scoped advisory lock on
+ * `hashtextextended('workspace-control:<workspace id>', 0)` in the matching
+ * mode and only then the row lock. The advisory lock is what makes the prefix
+ * fair: PostgreSQL row locks let a new FOR SHARE requester join a share-locked
+ * tuple without queueing behind an already waiting FOR UPDATE, so under
+ * continuous share traffic (claims, settlement, appends across many sessions)
+ * a genuine control mutation can starve indefinitely. Heavyweight locks have a
+ * FIFO wait queue: a shared request conflicts with a waiting exclusive request
+ * and queues behind it, so a mutator waits only for the holders that preceded
+ * it, and sharers keep flowing between mutations. The row lock is retained
+ * unchanged for FK/consistency semantics and for SQL-function writers that
+ * lock the row directly (session-create triggers and capability functions).
+ *
+ * Invariant: a transaction that locks this row through any other path (a
+ * SECURITY DEFINER function, a trigger, raw SQL) must already hold the prefix
+ * through this helper or must never call this helper afterwards for the same
+ * workspace. Requesting the advisory lock after holding the row lock can
+ * deadlock against a mutator that holds the advisory lock and waits for the
+ * row. Every current SQL-function locker either runs in its own transaction or
+ * runs after this helper in the same transaction.
+ */
 export async function lockWorkspaceInferenceControl(
   db: Database,
   workspaceId: string,
   mode: WorkspaceControlLockMode,
+  options: WorkspaceControlLockOptions = {},
 ): Promise<WorkspaceControlRow> {
-  const rows = await db.execute<WorkspaceControlRow>(sql`
-    select
-      workspace_id as "workspaceId",
-      account_id as "accountId",
-      revision,
-      workspace_state as "workspaceState",
-      workspace_pause_revision as "workspacePauseRevision",
-      reason,
-      changed_by as "changedBy",
-      changed_at as "changedAt"
-    from ${schema.workspaceInferenceControls}
-    where workspace_id = ${workspaceId}
-    ${lockClause(mode)}
-  `);
+  const budget = lockBudgetFor(options);
+  const [prior] = budget
+    ? await db.execute<{ value: string }>(sql`select current_setting('lock_timeout') as value`)
+    : [];
+  if (mode !== "none") {
+    await boundedLockStep(db, workspaceId, budget, () =>
+      db.execute(
+        sql`select ${advisoryLockFunction(mode)}(hashtextextended(${`workspace-control:${workspaceId}`}, 0))`,
+      ),
+    );
+  }
+  const rows = await boundedLockStep(db, workspaceId, budget, () =>
+    db.execute<WorkspaceControlRow>(sql`
+      select
+        workspace_id as "workspaceId",
+        account_id as "accountId",
+        revision,
+        workspace_state as "workspaceState",
+        workspace_pause_revision as "workspacePauseRevision",
+        reason,
+        changed_by as "changedBy",
+        changed_at as "changedAt"
+      from ${schema.workspaceInferenceControls}
+      where workspace_id = ${workspaceId}
+      ${lockClause(mode)}
+    `),
+  );
+  if (budget) {
+    await db.execute(sql`select set_config('lock_timeout', ${prior?.value ?? "0"}, true)`);
+  }
   const row = rows[0];
   if (!row) {
     throw new SessionControlInvariantError(
@@ -388,6 +554,69 @@ export async function lockWorkspaceInferenceControl(
   return row;
 }
 
+export type WorkspaceControlAdmissionLock = {
+  control: WorkspaceControlRow;
+  mode: "share" | "update";
+};
+
+const WORKSPACE_CONTROL_ADMISSION_SAVEPOINT = "opengeni_workspace_control_admission";
+
+/**
+ * Lock the workspace control prefix for an admission. Callers that may resume
+ * a paused branch request escalation; inert queue admission stays shared.
+ *
+ * The common case (the target branch is active) holds only `FOR SHARE`. That
+ * still excludes every control mutation (Pause/Resume/Cancel, workspace
+ * control, auto-resume all take `FOR UPDATE`), so the effective state observed
+ * here cannot change for the rest of the transaction, while other Sends,
+ * Steers, claims, and event appends on the workspace proceed concurrently.
+ *
+ * When the branch is paused the admission must advance the workspace control
+ * revision, so it needs `FOR UPDATE`. Upgrading in place would deadlock as soon
+ * as two sharers decide to upgrade together (each waits for the other's share
+ * lock), so the shared prefix is taken inside a savepoint and rolled back
+ * before the exclusive prefix is requested: PostgreSQL releases row locks and
+ * transaction-level advisory locks acquired inside a rolled-back savepoint, so
+ * the exclusive request queues normally behind other holders.
+ *
+ * Callers that already hold the prefix exclusively (for example a realtime
+ * sync that admitted a delegation) simply observe their own stronger lock.
+ */
+export async function lockWorkspaceInferenceControlForAdmission(
+  db: Database,
+  input: {
+    workspaceId: string;
+    sessionId: string;
+    resumePausedBranch: boolean;
+  } & WorkspaceControlLockOptions,
+): Promise<WorkspaceControlAdmissionLock> {
+  // One budget spans the shared attempt and any escalation to the exclusive
+  // prefix, so the caller's bound is the total wait, not a per-step timeout.
+  const lockOptions: WorkspaceControlLockOptions =
+    input.lockTimeoutMs === undefined
+      ? {}
+      : { budget: workspaceControlLockBudget(input.lockTimeoutMs) };
+  await db.execute(sql.raw(`savepoint ${WORKSPACE_CONTROL_ADMISSION_SAVEPOINT}`));
+  const shared = await lockWorkspaceInferenceControl(db, input.workspaceId, "share", lockOptions);
+  if (!input.resumePausedBranch) {
+    await db.execute(sql.raw(`release savepoint ${WORKSPACE_CONTROL_ADMISSION_SAVEPOINT}`));
+    return { control: shared, mode: "share" };
+  }
+  const effective = await evaluateSessionControl(db, input.workspaceId, input.sessionId, {
+    workspaceControl: shared,
+  });
+  if (effective.state === "active") {
+    await db.execute(sql.raw(`release savepoint ${WORKSPACE_CONTROL_ADMISSION_SAVEPOINT}`));
+    return { control: shared, mode: "share" };
+  }
+  await db.execute(sql.raw(`rollback to savepoint ${WORKSPACE_CONTROL_ADMISSION_SAVEPOINT}`));
+  await db.execute(sql.raw(`release savepoint ${WORKSPACE_CONTROL_ADMISSION_SAVEPOINT}`));
+  return {
+    control: await lockWorkspaceInferenceControl(db, input.workspaceId, "update", lockOptions),
+    mode: "update",
+  };
+}
+
 export type SessionEventWriteLockInput = {
   workspaceId: string;
   /**
@@ -414,12 +643,19 @@ export type SessionEventWriteLocks = {
 /**
  * Establish the one canonical lock prefix for every `session_events` writer:
  *
- *   workspace_inference_controls (when control-aware)
+ *   workspace-control advisory lock + workspace_inference_controls row
+ *     (when control-aware; see `lockWorkspaceInferenceControl`)
  *     -> actual workspaces row FOR KEY SHARE
  *     -> session rows FOR NO KEY UPDATE, UUID ordered
  *     -> exact turn rows FOR UPDATE, UUID ordered
  *     -> exact attempt rows FOR UPDATE, UUID ordered
  *
+ * Control-aware writers that do not mutate the control row take it `share`;
+ * only genuine control mutations (Pause/Resume/Cancel, workspace control,
+ * auto-resume, settings narrowing, quiescent tree deletion) take `update`.
+ * Prompt admission declares whether it may resume a paused branch through
+ * `lockWorkspaceInferenceControlForAdmission`.
+ *
  * `FOR KEY SHARE` is deliberate. Event inserts need the workspace key to remain
  * stable for their FK, but they do not mutate the workspace. The old generic
  * `FOR UPDATE` lock serialized unrelated sessions and inverted the activity
@@ -434,6 +670,11 @@ export type SessionEventWriteLocks = {
  * this helper and may discover exact turn IDs only after locking the session.
  * They use the explicit `already_locked` stages, while retaining the same
  * monotonic table order. New event writers should prefer one complete call.
+ *
+ * Retained-screenshot prepare is not an event writer, but its INSERT still
+ * KEY SHAREs the turn and attempt through FKs. It must take this same prefix
+ * first: PostgreSQL fires those FK checks in catalog name/OID order, which can
+ * be attempt-then-turn and otherwise deadlocks against this helper.
  */
 export async function lockSessionEventWriteRows(
   db: Database,
@@ -523,6 +764,7 @@ export async function registerSessionTurnAttemptClaim(
     authorityEpoch: number;
     authorityVisibility: "user_private" | "workspace_shared";
     authorityOwnerOrganizationMembershipId: string | null;
+    personalResourceProtocolVersion: number;
     mcpApprovalPolicies: Record<string, SessionMcpApprovalPolicy>;
     connectorActionPolicies: schema.ConnectorActionPolicySnapshotEntry[];
   },
@@ -577,6 +819,7 @@ export async function registerSessionTurnAttemptClaim(
     existing.temporalWorkflowId !== input.temporalWorkflowId ||
     existing.temporalWorkflowRunId !== input.temporalWorkflowRunId ||
     existing.temporalActivityId !== input.temporalActivityId ||
+    existing.personalResourceProtocolVersion !== input.personalResourceProtocolVersion ||
     JSON.stringify(existing.connectorActionPolicies) !==
       JSON.stringify(input.connectorActionPolicies) ||
     existing.state === "closed"
@@ -912,6 +1155,7 @@ function projectEffectiveControl(
   targetId: string,
   rows: AncestryRow[],
   settlementAttempts: SettlementAttemptCounts,
+  stoppingBackgroundCommandCount: number,
 ): EffectiveSessionControl {
   assertCompleteAncestry(targetId, rows);
   const workspaceRevision = asSafeRevision(workspace.revision, "workspace control revision")!;
@@ -1045,9 +1289,49 @@ function projectEffectiveControl(
           },
     settlement:
       settlementAttempts.attemptCount > 0 ? { state: "stopping", ...settlementAttempts } : null,
+    backgroundCommandSettlement:
+      stoppingBackgroundCommandCount > 0
+        ? { state: "stopping", commandCount: stoppingBackgroundCommandCount }
+        : null,
   };
 }
 
+async function stoppingBackgroundCommandCounts(
+  db: Database,
+  workspaceId: string,
+  sessionIds: string[],
+): Promise<Map<string, number>> {
+  const rows = await db.execute<{ sessionId: string; commandCount: number | string }>(sql`
+    with recursive targets(id) as (values ${targetValues(sessionIds)}),
+    command_ancestry(command_id, ancestor_id, depth, path) as (
+      select command.id, command.session_id, 0::integer, array[command.session_id]::uuid[]
+      from ${schema.sessionBackgroundCommands} command
+      where command.workspace_id = ${workspaceId}
+        and command.state = 'stopping'
+      union all
+      select ancestry.command_id, current.parent_session_id,
+        ancestry.depth + 1, ancestry.path || current.parent_session_id
+      from command_ancestry ancestry
+      join ${schema.sessions} current
+        on current.workspace_id = ${workspaceId}
+       and current.id = ancestry.ancestor_id
+      where current.parent_session_id is not null
+        and not current.parent_session_id = any(ancestry.path)
+        and ancestry.depth < ${SESSION_ANCESTRY_LIMIT}
+    )
+    select target.id as "sessionId", count(distinct ancestry.command_id)::integer as "commandCount"
+    from targets target
+    join command_ancestry ancestry on ancestry.ancestor_id = target.id
+    group by target.id
+  `);
+  return new Map(
+    rows.map((row: { sessionId: string; commandCount: number | string }) => [
+      row.sessionId,
+      Number(row.commandCount),
+    ]),
+  );
+}
+
 async function settlementAttemptCounts(
   db: Database,
   workspaceId: string,
@@ -1170,6 +1454,7 @@ export async function evaluateSessionControls(
     options.workspaceControl ??
     (await lockWorkspaceInferenceControl(db, workspaceId, options.lock ?? "share"));
   const stopping = await settlementAttemptCounts(db, workspaceId, uniqueIds);
+  const stoppingCommands = await stoppingBackgroundCommandCounts(db, workspaceId, uniqueIds);
   const result = new Map<string, EffectiveSessionControl>();
   if (uniqueIds.length <= TARGET_PATH_PROJECTION_LIMIT) {
     // PostgreSQL's direct target-path plan is substantially faster for the
@@ -1189,6 +1474,7 @@ export async function evaluateSessionControls(
           sessionId,
           ancestryByTarget.get(sessionId) ?? [],
           stopping.get(sessionId) ?? NO_SETTLEMENT_ATTEMPTS,
+          stoppingCommands.get(sessionId) ?? 0,
         ),
       );
     }
@@ -1207,6 +1493,7 @@ export async function evaluateSessionControls(
         sessionId,
         ancestryRowsForTarget(sessionId, ancestry),
         stopping.get(sessionId) ?? NO_SETTLEMENT_ATTEMPTS,
+        stoppingCommands.get(sessionId) ?? 0,
       ),
     );
   }
@@ -1500,7 +1787,7 @@ export async function reserveSessionCommandReceipt(
   if (
     identityScope === "goal_operation" &&
     (input.actor.type !== "agent_attempt" ||
-      !["goal.update", "goal.progress"].includes(input.action) ||
+      !["goal.update", "goal.progress", "goal.wait"].includes(input.action) ||
       input.targetSessionId === null ||
       input.targetTurnId !== null)
   ) {
@@ -1940,13 +2227,57 @@ export type SessionControlMutationResult = {
   sessionControlEventId: string;
   workspaceControlEventId: string;
   interruptionCount: number;
+  backgroundCommandCount: number;
   wakeCount: number;
   cancelledSessionCount: number;
   cancelledTurnCount: number;
   affectedSessionEvents: Array<{ sessionId: string; eventIds: string[] }>;
+  workflowWake: SessionControlWorkflowWake | null;
   replay: boolean;
 };
 
+export type SessionControlWorkflowWake = {
+  accountId: string;
+  workspaceId: string;
+  sessionId: string;
+  temporalWorkflowId: string;
+  wakeRevision: number;
+};
+
+async function pendingSessionControlWorkflowWake(
+  db: Database,
+  workspaceId: string,
+  sessionId: string,
+  wakeCount: number,
+): Promise<SessionControlWorkflowWake | null> {
+  if (wakeCount === 0) return null;
+  const [wake] = await db
+    .select({
+      accountId: schema.sessionWorkflowWakeOutbox.accountId,
+      workspaceId: schema.sessionWorkflowWakeOutbox.workspaceId,
+      sessionId: schema.sessionWorkflowWakeOutbox.sessionId,
+      temporalWorkflowId: schema.sessionWorkflowWakeOutbox.temporalWorkflowId,
+      wakeRevision: schema.sessionWorkflowWakeOutbox.wakeRevision,
+      deliveredRevision: schema.sessionWorkflowWakeOutbox.deliveredRevision,
+    })
+    .from(schema.sessionWorkflowWakeOutbox)
+    .where(
+      and(
+        eq(schema.sessionWorkflowWakeOutbox.workspaceId, workspaceId),
+        eq(schema.sessionWorkflowWakeOutbox.sessionId, sessionId),
+      ),
+    )
+    .limit(1);
+  if (!wake || wake.wakeRevision <= wake.deliveredRevision) return null;
+  return {
+    accountId: wake.accountId,
+    workspaceId: wake.workspaceId,
+    sessionId: wake.sessionId,
+    temporalWorkflowId: wake.temporalWorkflowId,
+    wakeRevision: wake.wakeRevision,
+  };
+}
+
 async function loadSessionSubtreeIds(
   db: Database,
   workspaceId: string,
@@ -2013,25 +2344,55 @@ async function loadCancellationTurnIds(
   return rows.map((row) => row.id);
 }
 
-async function enqueueCancelledChildOutboxInTransaction(
+async function loadParentSessionId(
+  db: Database,
+  workspaceId: string,
+  sessionId: string,
+): Promise<string | null> {
+  const [row] = await db
+    .select({ parentSessionId: schema.sessions.parentSessionId })
+    .from(schema.sessions)
+    .where(and(eq(schema.sessions.workspaceId, workspaceId), eq(schema.sessions.id, sessionId)))
+    .limit(1);
+  return row?.parentSessionId ?? null;
+}
+
+/**
+ * The one control-plane child -> parent outbox insert (terminal cancellation,
+ * direct Pause, and cancelled human-input resolutions). The caller holds the
+ * canonical prefix with the child and its parent locked UUID-ordered; the
+ * causal parent-turn personal delegation snapshot is copied verbatim.
+ */
+async function insertChildOutboxRowInTransaction(
   db: Database,
   input: {
     workspaceId: string;
-    rootSession: typeof schema.sessions.$inferSelect;
+    childSession: typeof schema.sessions.$inferSelect;
     parentSession: typeof schema.sessions.$inferSelect | null;
+    dedupeKey: string;
+    kind: "child_terminal_result" | "child_paused" | "child_requires_action_resolved";
+    classification: "info" | "action_required";
+    summary: string;
+    payload: Record<string, unknown> & { type: string };
+    lineage?: Record<string, unknown>;
   },
 ): Promise<void> {
-  const parentSessionId = input.rootSession.parentSessionId;
+  const parentSessionId = input.childSession.parentSessionId;
   if (!parentSessionId) return;
   if (!input.parentSession || input.parentSession.id !== parentSessionId) {
     throw new SessionControlInvariantError(
-      `Parent session ${parentSessionId} was not locked with cancellation root ${input.rootSession.id}`,
+      `Parent session ${parentSessionId} was not locked with child ${input.childSession.id}`,
     );
   }
   if (input.parentSession.status === "cancelled") return;
+  if (input.payload.type !== input.kind) {
+    throw new SessionControlInvariantError(
+      `Child outbox ${input.kind} payload discriminator mismatch`,
+    );
+  }
   let personalConnectionDelegations: (typeof schema.sessionTurns.$inferSelect)["personalConnectionDelegations"] =
     [];
-  if (input.rootSession.parentTurnId) {
+  if (input.childSession.parentTurnId) {
     const [parentTurn] = await db
       .select({
         delegations: schema.sessionTurns.personalConnectionDelegations,
@@ -2041,7 +2402,7 @@ async function enqueueCancelledChildOutboxInTransaction(
         and(
           eq(schema.sessionTurns.workspaceId, input.workspaceId),
           eq(schema.sessionTurns.sessionId, parentSessionId),
-          eq(schema.sessionTurns.id, input.rootSession.parentTurnId),
+          eq(schema.sessionTurns.id, input.childSession.parentTurnId),
         ),
       )
       .limit(1);
@@ -2049,7 +2410,7 @@ async function enqueueCancelledChildOutboxInTransaction(
       const parsed = McpPersonalConnectionDelegations.safeParse(parentTurn.delegations);
       if (!parsed.success) {
         throw new SessionControlInvariantError(
-          `Invalid personal MCP delegation snapshot at session_turns:${input.workspaceId}:${parentSessionId}:${input.rootSession.parentTurnId}`,
+          `Invalid personal MCP delegation snapshot at session_turns:${input.workspaceId}:${parentSessionId}:${input.childSession.parentTurnId}`,
         );
       }
       personalConnectionDelegations = parsed.data.map((delegation) => ({
@@ -2063,26 +2424,23 @@ async function enqueueCancelledChildOutboxInTransaction(
       withLosslessContentWriteVersion(
         withLosslessContentWriteVersion(
           {
-            accountId: input.rootSession.accountId,
+            accountId: input.childSession.accountId,
             workspaceId: input.workspaceId,
-            sourceSessionId: input.rootSession.id,
+            sourceSessionId: input.childSession.id,
             targetSessionId: parentSessionId,
-            dedupeKey: `child-completion:${input.rootSession.id}:cancelled`,
-            kind: "child_terminal_result",
-            classification: "info",
-            sourceId: input.rootSession.id,
-            summary: "Child session was terminally cancelled.",
-            payload: {
-              type: "child_terminal_result",
-              childSessionId: input.rootSession.id,
-              status: "cancelled",
-            },
+            dedupeKey: input.dedupeKey,
+            kind: input.kind,
+            classification: input.classification,
+            sourceId: input.childSession.id,
+            summary: input.summary,
+            payload: input.payload,
             lineage: {
-              childSessionId: input.rootSession.id,
+              childSessionId: input.childSession.id,
               parentSessionId,
-              ...(input.rootSession.parentTurnId
-                ? { parentTurnId: input.rootSession.parentTurnId }
+              ...(input.childSession.parentTurnId
+                ? { parentTurnId: input.childSession.parentTurnId }
                 : {}),
+              ...(input.lineage ?? {}),
             },
             personalConnectionDelegations,
           },
@@ -2101,6 +2459,118 @@ async function enqueueCancelledChildOutboxInTransaction(
     });
 }
 
+async function enqueueCancelledChildOutboxInTransaction(
+  db: Database,
+  input: {
+    workspaceId: string;
+    rootSession: typeof schema.sessions.$inferSelect;
+    parentSession: typeof schema.sessions.$inferSelect | null;
+  },
+): Promise<void> {
+  await insertChildOutboxRowInTransaction(db, {
+    workspaceId: input.workspaceId,
+    childSession: input.rootSession,
+    parentSession: input.parentSession,
+    dedupeKey: `child-completion:${input.rootSession.id}:cancelled`,
+    kind: "child_terminal_result",
+    classification: "info",
+    summary: "Child session was terminally cancelled.",
+    payload: {
+      type: "child_terminal_result",
+      childSessionId: input.rootSession.id,
+      status: "cancelled",
+    },
+  });
+}
+
+/** child_paused notice for a direct Pause of a child; gated by the rollout flag. */
+async function enqueueChildPausedOutboxInTransaction(
+  db: Database,
+  input: {
+    workspaceId: string;
+    childSession: typeof schema.sessions.$inferSelect;
+    parentSession: typeof schema.sessions.$inferSelect;
+    operationId: string;
+    actorKind: "human" | "api" | "agent";
+    reason: string | null;
+  },
+): Promise<void> {
+  if (!childLifecycleNoticesEnabled()) return;
+  const payload = {
+    type: "child_paused" as const,
+    childSessionId: input.childSession.id,
+    operationId: input.operationId,
+    actorKind: input.actorKind,
+    reason: boundedChildPausedReason(input.reason),
+  };
+  await insertChildOutboxRowInTransaction(db, {
+    workspaceId: input.workspaceId,
+    childSession: input.childSession,
+    parentSession: input.parentSession,
+    dedupeKey: childPausedDedupeKey({
+      childSessionId: input.childSession.id,
+      receiptId: input.operationId,
+    }),
+    kind: "child_paused",
+    classification: childPausedClassification(input.actorKind),
+    summary: childPausedSummary(input.childSession.id, payload),
+    payload,
+  });
+}
+
+/**
+ * Terminal cancellation of the selected root's pending human-input rows: each
+ * becomes one child_requires_action_resolved notice for the surviving parent
+ * so its pending child_requires_action can be superseded. Cancelled
+ * descendants do not notify parents inside the same terminal subtree.
+ */
+async function enqueueCancelledChildRequiresActionResolvedOutboxInTransaction(
+  db: Database,
+  input: {
+    workspaceId: string;
+    rootSession: typeof schema.sessions.$inferSelect;
+    parentSession: typeof schema.sessions.$inferSelect | null;
+    cancelledHumanInputs: ReadonlyArray<{
+      id: string;
+      sessionId: string;
+      turnId: string;
+      turnGeneration: number;
+    }>;
+  },
+): Promise<void> {
+  if (!childLifecycleNoticesEnabled() || !input.parentSession) return;
+  for (const humanInput of input.cancelledHumanInputs) {
+    if (humanInput.sessionId !== input.rootSession.id) continue;
+    const payload = {
+      type: "child_requires_action_resolved" as const,
+      childSessionId: input.rootSession.id,
+      childTurnId: humanInput.turnId,
+      childTurnGeneration: humanInput.turnGeneration,
+      requestId: humanInput.id,
+      approvalId: null,
+      outcome: "cancelled" as const,
+      respondedByKind: "system" as const,
+    };
+    await insertChildOutboxRowInTransaction(db, {
+      workspaceId: input.workspaceId,
+      childSession: input.rootSession,
+      parentSession: input.parentSession,
+      dedupeKey: childRequiresActionResolvedDedupeKey({
+        childSessionId: input.rootSession.id,
+        turnId: humanInput.turnId,
+        turnGeneration: humanInput.turnGeneration,
+        requestId: humanInput.id,
+        approvalId: null,
+      }),
+      kind: "child_requires_action_resolved",
+      classification: "info",
+      summary: childRequiresActionResolvedSummary(input.rootSession.id, payload),
+      payload,
+      lineage: { turnId: humanInput.turnId },
+    });
+  }
+}
+
 async function assertSessionBranchIsNotCancelled(
   db: Database,
   workspaceId: string,
@@ -2212,6 +2682,7 @@ async function cancelSessionSubtreeInTransaction(
     id: string;
     sessionId: string;
     turnId: string;
+    turnGeneration: number;
     questions: (typeof schema.sessionHumanInputRequests.$inferSelect)["questions"];
   }> = [];
   if (immediatelyCancelledTurnIds.length > 0) {
@@ -2247,6 +2718,7 @@ async function cancelSessionSubtreeInTransaction(
         id: schema.sessionHumanInputRequests.id,
         sessionId: schema.sessionHumanInputRequests.sessionId,
         turnId: schema.sessionHumanInputRequests.turnId,
+        turnGeneration: schema.sessionHumanInputRequests.turnGeneration,
         questions: schema.sessionHumanInputRequests.questions,
       });
     await db
@@ -2450,6 +2922,12 @@ async function cancelSessionSubtreeInTransaction(
     if (session.id === input.rootSessionId) eventIds.unshift(input.rootControlEventId);
     if (eventIds.length > 0) affectedSessionEvents.push({ sessionId: session.id, eventIds });
   }
+  await enqueueCancelledChildRequiresActionResolvedOutboxInTransaction(db, {
+    workspaceId: input.workspaceId,
+    rootSession,
+    parentSession: rootParentSession,
+    cancelledHumanInputs,
+  });
   await enqueueCancelledChildOutboxInTransaction(db, {
     workspaceId: input.workspaceId,
     rootSession,
@@ -2473,9 +2951,15 @@ export async function mutateSessionControlInTransaction(
     action: "pause" | "resume" | "cancel";
     reason?: string | null;
     expectedControlEtag?: string | null;
+    /** Request-scoped callers bound the control prefix wait; lifecycle callers omit it. */
+    controlLockTimeoutMs?: number;
   },
 ): Promise<SessionControlMutationResult> {
-  const workspace = await lockWorkspaceInferenceControl(db, input.workspaceId, "update");
+  const workspace = await lockWorkspaceInferenceControl(db, input.workspaceId, "update", {
+    ...(input.controlLockTimeoutMs !== undefined
+      ? { lockTimeoutMs: input.controlLockTimeoutMs }
+      : {}),
+  });
   const cancellationSubtree =
     input.action === "cancel"
       ? await loadSessionSubtreeIds(db, input.workspaceId, input.sessionId)
@@ -2485,6 +2969,14 @@ export async function mutateSessionControlInTransaction(
     input.action === "cancel"
       ? await loadCancellationTurnIds(db, input.workspaceId, cancellationSessionIds)
       : [];
+  // A direct Pause of a child notifies its parent (child_paused) through the
+  // outbox in this same commit, so the parent joins the UUID-ordered session
+  // lock exactly like Cancel locks the root's surviving parent.
+  const pauseParentSessionId =
+    input.action === "pause" && childLifecycleNoticesEnabled()
+      ? await loadParentSessionId(db, input.workspaceId, input.sessionId)
+      : null;
+  const lineageParentSessionId = cancellationSubtree.rootParentSessionId ?? pauseParentSessionId;
   const locks = await lockSessionEventWriteRows(db, {
     workspaceId: input.workspaceId,
     controlLock: "already_locked",
@@ -2493,27 +2985,20 @@ export async function mutateSessionControlInTransaction(
         ? [
             input.actor.sessionId,
             ...cancellationSessionIds,
-            ...(cancellationSubtree.rootParentSessionId
-              ? [cancellationSubtree.rootParentSessionId]
-              : []),
+            ...(lineageParentSessionId ? [lineageParentSessionId] : []),
           ]
-        : [
-            ...cancellationSessionIds,
-            ...(cancellationSubtree.rootParentSessionId
-              ? [cancellationSubtree.rootParentSessionId]
-              : []),
-          ],
+        : [...cancellationSessionIds, ...(lineageParentSessionId ? [lineageParentSessionId] : [])],
     turnIds:
       input.actor.type === "agent_attempt"
         ? [input.actor.turnId, ...cancellationTurnIds]
         : cancellationTurnIds,
     attemptIds: input.actor.type === "agent_attempt" ? [input.actor.attemptId] : [],
   });
-  if (input.action === "cancel") {
+  if (input.action === "cancel" || pauseParentSessionId !== null) {
     const rootSession = locks.sessions.find((session) => session.id === input.sessionId);
-    if (!rootSession || rootSession.parentSessionId !== cancellationSubtree.rootParentSessionId) {
+    if (!rootSession || rootSession.parentSessionId !== lineageParentSessionId) {
       throw new SessionControlInvariantError(
-        `Session ${input.sessionId} parent changed while establishing cancellation locks`,
+        `Session ${input.sessionId} parent changed while establishing ${input.action} locks`,
       );
     }
   }
@@ -2543,6 +3028,7 @@ export async function mutateSessionControlInTransaction(
         "Replayed session control receipt has no session event",
       );
     }
+    const wakeCount = Number(reserved.receipt.result.wakeCount ?? 0);
     return {
       receipt: reserved.receipt,
       control: await evaluateSessionControl(db, input.workspaceId, input.sessionId, {
@@ -2551,7 +3037,8 @@ export async function mutateSessionControlInTransaction(
       sessionControlEventId,
       workspaceControlEventId,
       interruptionCount: Number(reserved.receipt.result.interruptionCount ?? 0),
-      wakeCount: Number(reserved.receipt.result.wakeCount ?? 0),
+      backgroundCommandCount: Number(reserved.receipt.result.backgroundCommandCount ?? 0),
+      wakeCount,
       cancelledSessionCount: Number(reserved.receipt.result.cancelledSessionCount ?? 0),
       cancelledTurnCount: Number(reserved.receipt.result.cancelledTurnCount ?? 0),
       affectedSessionEvents: Array.isArray(reserved.receipt.result.affectedSessionEvents)
@@ -2560,6 +3047,12 @@ export async function mutateSessionControlInTransaction(
             eventIds: string[];
           }>)
         : [{ sessionId: input.sessionId, eventIds: [sessionControlEventId] }],
+      workflowWake: await pendingSessionControlWorkflowWake(
+        db,
+        input.workspaceId,
+        input.sessionId,
+        wakeCount,
+      ),
       replay: true,
     };
   }
@@ -2632,6 +3125,14 @@ export async function mutateSessionControlInTransaction(
     input.actor.type === "agent_attempt"
       ? `attempt:${input.actor.attemptId}`
       : input.actor.subjectId;
+  const backgroundCommandCount =
+    input.action === "pause" || input.action === "cancel"
+      ? await requestSessionBackgroundCommandCancellationsInTransaction(db, {
+          workspaceId: input.workspaceId,
+          rootSessionIds: [input.sessionId],
+          subjectId: actor,
+        })
+      : 0;
   const workspaceControlEventId = await insertWorkspaceControlEventInTransaction(db, {
     accountId: input.accountId,
     workspaceId: input.workspaceId,
@@ -2752,10 +3253,36 @@ export async function mutateSessionControlInTransaction(
           cancelledTurnCount: 0,
           affectedSessionEvents: [{ sessionId: input.sessionId, eventIds: [controlEvent.id] }],
         };
+  if (input.action === "pause" && pauseParentSessionId !== null) {
+    // Direct Pause only (a recursive ancestor pause never reaches this command
+    // for the child), and never when the parent's own live attempt issued it:
+    // that parent already knows. Human/API pauses are action-required for the
+    // parent; an agent pause is informational.
+    const pausedSession = locks.sessions.find((session) => session.id === input.sessionId);
+    const parentSession = locks.sessions.find((session) => session.id === pauseParentSessionId);
+    const issuedByParentAttempt =
+      input.actor.type === "agent_attempt" && input.actor.sessionId === pauseParentSessionId;
+    if (pausedSession && parentSession && !issuedByParentAttempt) {
+      await enqueueChildPausedOutboxInTransaction(db, {
+        workspaceId: input.workspaceId,
+        childSession: pausedSession,
+        parentSession,
+        operationId: reserved.receipt.id,
+        actorKind:
+          input.actor.type === "agent_attempt"
+            ? "agent"
+            : input.actor.type === "service"
+              ? "api"
+              : "human",
+        reason: input.reason ?? null,
+      });
+    }
+  }
   const receipt = await updateSessionCommandReceiptResult(db, reserved.receipt.id, {
     controlRevision: revision,
     result: {
       interruptionCount,
+      backgroundCommandCount,
       wakeCount,
       eventId: controlEvent.id,
       workspaceControlEventId,
@@ -2773,10 +3300,17 @@ export async function mutateSessionControlInTransaction(
     sessionControlEventId: controlEvent.id,
     workspaceControlEventId,
     interruptionCount,
+    backgroundCommandCount,
     wakeCount,
     cancelledSessionCount: cancellation.cancelledSessionCount,
     cancelledTurnCount: cancellation.cancelledTurnCount,
     affectedSessionEvents: cancellation.affectedSessionEvents,
+    workflowWake: await pendingSessionControlWorkflowWake(
+      db,
+      input.workspaceId,
+      input.sessionId,
+      wakeCount,
+    ),
     replay: false,
   };
 }
@@ -2787,8 +3321,15 @@ export async function autoResumeSessionBranchInTransaction(
     workspaceId: string;
     sessionId: string;
     actor: string;
-    reason: "human_send" | "human_steer" | "service_send" | "service_steer" | "agent_steer";
+    reason: "human_steer" | "service_steer" | "agent_steer";
     observedControlEtag?: string | null;
+    /**
+     * The admission prefix the caller already holds. A `share` admission
+     * proves the branch was active under a lock that excludes every control
+     * mutation, so it never needs to resume; only an `update` admission may
+     * advance the workspace revision here.
+     */
+    admission?: WorkspaceControlAdmissionLock;
   },
 ): Promise<{
   revision: number;
@@ -2796,10 +3337,12 @@ export async function autoResumeSessionBranchInTransaction(
   changed: boolean;
   workspaceControlEventId: string | null;
 }> {
-  const workspace = await lockWorkspaceInferenceControl(db, input.workspaceId, "update");
+  const workspace =
+    input.admission?.control ??
+    (await lockWorkspaceInferenceControl(db, input.workspaceId, "update"));
   await assertSessionBranchIsNotCancelled(db, input.workspaceId, input.sessionId);
   const before = await evaluateSessionControl(db, input.workspaceId, input.sessionId, {
-    lock: "share",
+    workspaceControl: workspace,
   });
   if (input.observedControlEtag && input.observedControlEtag !== before.controlEtag) {
     throw new SessionControlConflictError();
@@ -2812,6 +3355,13 @@ export async function autoResumeSessionBranchInTransaction(
       workspaceControlEventId: null,
     };
   }
+  if (input.admission?.mode === "share") {
+    // Impossible by construction: the shared prefix observed an active branch
+    // and excludes every control mutation until this transaction ends.
+    throw new SessionControlInvariantError(
+      `Session ${input.sessionId} became paused under a shared workspace control lock`,
+    );
+  }
   const revision = nextRevision(workspace);
   await advanceWorkspaceRevision(db, input.workspaceId, revision);
   await db
@@ -2859,6 +3409,7 @@ export type WorkspaceControlMutationResult = {
   workspaceControlEventId: string;
   workspaceState: EffectiveControlState;
   interruptionCount: number;
+  backgroundCommandCount: number;
   wakeCount: number;
   replay: boolean;
 };
@@ -2873,9 +3424,15 @@ export async function mutateWorkspaceControlInTransaction(
     action: "pause" | "resume";
     reason?: string | null;
     expectedRevision?: number | null;
+    /** Request-scoped callers bound the control prefix wait; lifecycle callers omit it. */
+    controlLockTimeoutMs?: number;
   },
 ): Promise<WorkspaceControlMutationResult> {
-  const workspace = await lockWorkspaceInferenceControl(db, input.workspaceId, "update");
+  const workspace = await lockWorkspaceInferenceControl(db, input.workspaceId, "update", {
+    ...(input.controlLockTimeoutMs !== undefined
+      ? { lockTimeoutMs: input.controlLockTimeoutMs }
+      : {}),
+  });
   const currentRevision = asSafeRevision(workspace.revision, "workspace control revision")!;
   const hash = canonicalSessionCommandHash({
     action: input.action,
@@ -2903,6 +3460,7 @@ export async function mutateWorkspaceControlInTransaction(
       workspaceControlEventId,
       workspaceState: input.action === "pause" ? "paused" : "active",
       interruptionCount: Number(reserved.receipt.result.interruptionCount ?? 0),
+      backgroundCommandCount: Number(reserved.receipt.result.backgroundCommandCount ?? 0),
       wakeCount: Number(reserved.receipt.result.wakeCount ?? 0),
       replay: true,
     };
@@ -2916,6 +3474,13 @@ export async function mutateWorkspaceControlInTransaction(
     input.actor.type === "agent_attempt"
       ? `attempt:${input.actor.attemptId}`
       : input.actor.subjectId;
+  const backgroundCommandCount =
+    input.action === "pause"
+      ? await requestWorkspaceBackgroundCommandCancellationsInTransaction(db, {
+          workspaceId: input.workspaceId,
+          subjectId: actor,
+        })
+      : 0;
   const [updated] = await db
     .update(schema.workspaceInferenceControls)
     .set({
@@ -2968,7 +3533,7 @@ export async function mutateWorkspaceControlInTransaction(
         });
   const receipt = await updateSessionCommandReceiptResult(db, reserved.receipt.id, {
     controlRevision: revision,
-    result: { interruptionCount, wakeCount, workspaceControlEventId },
+    result: { interruptionCount, backgroundCommandCount, wakeCount, workspaceControlEventId },
   });
   return {
     receipt,
@@ -2976,6 +3541,7 @@ export async function mutateWorkspaceControlInTransaction(
     workspaceControlEventId,
     workspaceState: input.action === "pause" ? "paused" : "active",
     interruptionCount,
+    backgroundCommandCount,
     wakeCount,
     replay: false,
   };