@penclipai/server 2026.704.0 → 2026.714.0

package/dist/services/routines.js

@@ -1,6 +1,6 @@
 import crypto from "node:crypto";
-import { and, asc, desc, eq, inArray, isNotNull, isNull, lte, not, or, sql } from "drizzle-orm";
-import { agents, companySecretBindings, companySecretVersions, companySecrets, documentRevisions, documents, executionWorkspaces, goals, heartbeatRuns, issueInboxArchives, issueReadStates, issues, pluginManagedResources, plugins, projects, routineRevisions, routineRuns, routineDocuments, routines, routineTriggers, } from "@penclipai/db";
+import { and, asc, desc, eq, gt, inArray, isNotNull, isNull, lte, not, or, sql } from "drizzle-orm";
+import { agents, activityLog, companies, companyMemberships, companySecretBindings, companySecretVersions, companySecrets, documentRevisions, documents, executionWorkspaces, goals, heartbeatRuns, issueInboxArchives, issueReadStates, issues, pluginManagedResources, plugins, projects, routineRevisions, routineRuns, routineDocuments, routines, routineTriggers, } from "@penclipai/db";
 import { WORKSPACE_BRANCH_ROUTINE_VARIABLE, getBuiltinRoutineVariableValues, extractRoutineVariableNames, interpolateRoutineTemplate, isValidRoutineDateString, pluginOperationIssueOriginKind, stringifyRoutineVariableValue, syncRoutineVariablesWithTemplate, } from "@penclipai/shared";
 import { trackRoutineRun } from "@penclipai/shared/telemetry";
 import { conflict, forbidden, notFound, unauthorized, unprocessable } from "../errors.js";
@@ -9,11 +9,13 @@ import { getTelemetryClient } from "../telemetry.js";
 import { getConfiguredSecretProvider } from "../secrets/configured-provider.js";
 import { issueService } from "./issues.js";
 import { assertAssignableAgent } from "./agent-assignability.js";
+import { visibleIssueCondition } from "./issue-visibility.js";
 import { secretService } from "./secrets.js";
 import { getSecretProvider } from "../secrets/provider-registry.js";
 import { parseCron, validateCron } from "./cron.js";
 import { isUniqueViolation } from "./db-errors.js";
 import { heartbeatService } from "./heartbeat.js";
+import { instanceSettingsService, isTruthyRuntimeEnvValue, resolveWorktreeRunExecutionActivationState, } from "./instance-settings.js";
 import { queueIssueAssignmentWakeup } from "./issue-assignment-wakeup.js";
 import { logActivity } from "./activity-log.js";
 const OPEN_ISSUE_STATUSES = ["backlog", "todo", "in_progress", "in_review", "blocked"];
@@ -21,6 +23,12 @@ const LIVE_HEARTBEAT_RUN_STATUSES = ["queued", "running", "scheduled_retry"];
 const TERMINAL_ISSUE_STATUSES = new Set(["done", "cancelled"]);
 const MAX_CATCH_UP_RUNS = 25;
 const MAX_ROUTINE_REVISIONS = 100;
+const ACTIVITY_GATE_IGNORED_ACTIONS = [
+    "issue.read_marked",
+    "issue.read_unmarked",
+    "issue.inbox_archived",
+    "issue.inbox_unarchived",
+];
 const WEEKDAY_INDEX = {
     Sun: 0,
     Mon: 1,
@@ -30,6 +38,39 @@ const WEEKDAY_INDEX = {
     Fri: 5,
     Sat: 6,
 };
+async function resolveCompanyDefaultResponsibleUserId(db, companyId) {
+    const company = await db
+        .select({ defaultResponsibleUserId: companies.defaultResponsibleUserId })
+        .from(companies)
+        .where(eq(companies.id, companyId))
+        .then((rows) => rows[0] ?? null);
+    if (company?.defaultResponsibleUserId)
+        return company.defaultResponsibleUserId;
+    const owner = await db
+        .select({ userId: companyMemberships.principalId })
+        .from(companyMemberships)
+        .where(and(eq(companyMemberships.companyId, companyId), eq(companyMemberships.principalType, "user"), eq(companyMemberships.status, "active"), eq(companyMemberships.membershipRole, "owner")))
+        .orderBy(asc(companyMemberships.createdAt), asc(companyMemberships.id))
+        .limit(1)
+        .then((rows) => rows[0] ?? null);
+    return owner?.userId ?? null;
+}
+async function resolveRoutineResponsibleUserId(db, companyId, actorUserId, parentIssueId) {
+    if (actorUserId)
+        return actorUserId;
+    if (parentIssueId) {
+        const parent = await db
+            .select({ responsibleUserId: issues.responsibleUserId, createdByUserId: issues.createdByUserId })
+            .from(issues)
+            .where(and(eq(issues.companyId, companyId), eq(issues.id, parentIssueId)))
+            .then((rows) => rows[0] ?? null);
+        if (parent?.responsibleUserId)
+            return parent.responsibleUserId;
+        if (parent?.createdByUserId)
+            return parent.createdByUserId;
+    }
+    return resolveCompanyDefaultResponsibleUserId(db, companyId);
+}
 const ROUTINE_DESCRIPTION_DOCUMENT_KEY = "description";
 function routineWebhookSecretConfigPath(secretId) {
     return `webhookSecret:${secretId}`;
@@ -349,6 +390,7 @@ function routineRevisionSnapshotRoutine(routine) {
         catchUpPolicy: routine.catchUpPolicy,
         variables: routine.variables ?? [],
         env: routine.env ?? null,
+        responsibleUserId: routine.responsibleUserId ?? null,
     };
 }
 function routineRevisionSnapshotTrigger(trigger) {
@@ -413,6 +455,8 @@ function mapRoutineDescriptionDocument(row) {
 export function routineService(db, deps = {}) {
     const issueSvc = issueService(db);
     const secretsSvc = secretService(db);
+    const instanceSettings = instanceSettingsService(db);
+    const runtimeEnv = deps.runtimeEnv ?? process.env;
     const heartbeat = deps.heartbeat ?? heartbeatService(db, {
         pluginWorkerManager: deps.pluginWorkerManager,
     });
@@ -636,6 +680,7 @@ export function routineService(db, deps = {}) {
             createdByAgentId: actor.agentId ?? null,
             createdByUserId: actor.userId ?? null,
             createdByRunId: actor.runId ?? null,
+            responsibleUserId: snapshot.routine.responsibleUserId ?? null,
             createdAt: now,
         })
             .returning();
@@ -818,7 +863,7 @@ export function routineService(db, deps = {}) {
         })
             .from(issues)
             .innerJoin(heartbeatRuns, and(eq(heartbeatRuns.id, issues.executionRunId), inArray(heartbeatRuns.status, LIVE_HEARTBEAT_RUN_STATUSES)))
-            .where(and(eq(issues.companyId, companyId), eq(issues.originKind, "routine_execution"), inArray(issues.originId, routineIds), inArray(issues.status, OPEN_ISSUE_STATUSES), isNull(issues.hiddenAt)))
+            .where(and(eq(issues.companyId, companyId), eq(issues.originKind, "routine_execution"), inArray(issues.originId, routineIds), inArray(issues.status, OPEN_ISSUE_STATUSES), visibleIssueCondition()))
             .orderBy(issues.originId, desc(issues.updatedAt), desc(issues.createdAt));
         const rowsByOriginId = new Map();
         for (const row of executionBoundRows) {
@@ -840,7 +885,7 @@ export function routineService(db, deps = {}) {
             })
                 .from(issues)
                 .innerJoin(heartbeatRuns, and(eq(heartbeatRuns.companyId, issues.companyId), inArray(heartbeatRuns.status, LIVE_HEARTBEAT_RUN_STATUSES), sql `${heartbeatRuns.contextSnapshot} ->> 'issueId' = cast(${issues.id} as text)`))
-                .where(and(eq(issues.companyId, companyId), eq(issues.originKind, "routine_execution"), inArray(issues.originId, missingRoutineIds), inArray(issues.status, OPEN_ISSUE_STATUSES), isNull(issues.hiddenAt)))
+                .where(and(eq(issues.companyId, companyId), eq(issues.originKind, "routine_execution"), inArray(issues.originId, missingRoutineIds), inArray(issues.status, OPEN_ISSUE_STATUSES), visibleIssueCondition()))
                 .orderBy(issues.originId, desc(issues.updatedAt), desc(issues.createdAt));
             for (const row of legacyRows) {
                 if (!row.originId)
@@ -884,10 +929,113 @@ export function routineService(db, deps = {}) {
                 .where(eq(routineTriggers.id, input.triggerId));
         }
     }
-    // Records a skipped scheduled firing without creating an execution issue. Used when the
-    // routine's project is paused: the tick is still claimed/advanced upstream (no backfill),
-    // and run history + trigger audit reflect the pause-specific skip.
-    async function recordSuppressedScheduleRun(input) {
+    async function getAutomaticRoutineDispatchEligibility(routine, activation) {
+        if (!isTruthyRuntimeEnvValue(runtimeEnv.PAPERCLIP_IN_WORKTREE))
+            return { eligible: true };
+        const resolvedActivation = activation ?? await resolveWorktreeRunExecutionActivationState({
+            getExperimental: instanceSettings.getExperimental,
+            runtimeEnv,
+        });
+        if (!resolvedActivation.armed)
+            return { eligible: false };
+        const cutoff = new Date(resolvedActivation.cutoff);
+        if (Number.isNaN(cutoff.getTime()) || routine.createdAt < cutoff)
+            return { eligible: false };
+        return { eligible: true };
+    }
+    async function evaluateActivityGate(routine, now) {
+        const lastDispatchedRun = await db
+            .select({ triggeredAt: routineRuns.triggeredAt })
+            .from(routineRuns)
+            .where(and(eq(routineRuns.companyId, routine.companyId), eq(routineRuns.routineId, routine.id), sql `${routineRuns.status} not in ('skipped', 'coalesced')`))
+            .orderBy(desc(routineRuns.triggeredAt), desc(routineRuns.id))
+            .limit(1)
+            .then((rows) => rows[0] ?? null);
+        if (!lastDispatchedRun) {
+            return { fire: true, windowStart: null, matchedActivity: null };
+        }
+        const projectScopeCondition = routine.activityGateScope === "project"
+            ? routine.projectId
+                ? sql `(
+          (${activityLog.entityType} = 'project' and ${activityLog.entityId} = ${routine.projectId})
+          or (${activityLog.details} ->> 'projectId') = ${routine.projectId}
+          or exists (
+            select 1
+            from ${issues} activity_issue
+            where activity_issue.company_id = ${routine.companyId}
+              and activity_issue.project_id = ${routine.projectId}
+              and activity_issue.id::text = ${activityLog.entityId}
+              and ${activityLog.entityType} = 'issue'
+          )
+          or exists (
+            select 1
+            from ${heartbeatRuns} activity_run
+            inner join ${issues} run_issue
+              on run_issue.company_id = ${routine.companyId}
+              and run_issue.id::text = activity_run.context_snapshot ->> 'issueId'
+            where activity_run.company_id = ${routine.companyId}
+              and activity_run.id = ${activityLog.runId}
+              and run_issue.project_id = ${routine.projectId}
+          )
+          or exists (
+            select 1
+            from ${routines} activity_routine
+            where activity_routine.company_id = ${routine.companyId}
+              and activity_routine.project_id = ${routine.projectId}
+              and activity_routine.id::text = ${activityLog.entityId}
+              and ${activityLog.entityType} = 'routine'
+          )
+          or exists (
+            select 1
+            from ${routineRuns} activity_routine_run
+            inner join ${routines} activity_routine
+              on activity_routine.company_id = ${routine.companyId}
+              and activity_routine.id = activity_routine_run.routine_id
+            where activity_routine_run.company_id = ${routine.companyId}
+              and activity_routine_run.id::text = ${activityLog.entityId}
+              and activity_routine.project_id = ${routine.projectId}
+              and ${activityLog.entityType} = 'routine_run'
+          )
+          )`
+                : sql `false`
+            : undefined;
+        const matchedActivity = await db
+            .select({
+            id: activityLog.id,
+            action: activityLog.action,
+            createdAt: activityLog.createdAt,
+        })
+            .from(activityLog)
+            .where(and(eq(activityLog.companyId, routine.companyId), gt(activityLog.createdAt, lastDispatchedRun.triggeredAt), lte(activityLog.createdAt, now), sql `${activityLog.action} not in (${sql.join(ACTIVITY_GATE_IGNORED_ACTIONS.map((action) => sql `${action}`), sql `, `)})`, sql `not (
+            ${activityLog.actorId} = 'routine-scheduler'
+            and (
+              (${activityLog.details} ->> 'routineId') = ${routine.id}
+              or (${activityLog.entityType} = 'routine' and ${activityLog.entityId} = ${routine.id})
+            )
+          )`, sql `not exists (
+            select 1
+            from ${heartbeatRuns} own_run
+            inner join ${issues} own_issue
+              on own_issue.company_id = ${routine.companyId}
+              and own_issue.id::text = own_run.context_snapshot ->> 'issueId'
+            where own_run.company_id = ${routine.companyId}
+              and own_run.id = ${activityLog.runId}
+              and own_issue.origin_kind = 'routine_execution'
+              and own_issue.origin_id = ${routine.id}
+          )`, projectScopeCondition))
+            .orderBy(asc(activityLog.createdAt), asc(activityLog.id))
+            .limit(1)
+            .then((rows) => rows[0] ?? null);
+        return {
+            fire: matchedActivity !== null,
+            windowStart: lastDispatchedRun.triggeredAt,
+            matchedActivity,
+        };
+    }
+    // Records an automatic firing that was claimed but intentionally not dispatched. The
+    // scheduler advances its tick before calling this helper, so suppressed work is never
+    // replayed after a setting or project state changes.
+    async function recordSuppressedAutomaticRun(input) {
         const triggeredAt = new Date();
         const run = await db.transaction(async (tx) => {
             const txDb = tx;
@@ -897,20 +1045,26 @@ export function routineService(db, deps = {}) {
                 companyId: input.routine.companyId,
                 routineId: input.routine.id,
                 triggerId: input.trigger.id,
-                source: "schedule",
+                source: input.source,
                 status: "skipped",
                 triggeredAt,
                 failureReason: input.reason,
                 completedAt: triggeredAt,
                 linkedIssueId: null,
                 routineRevisionId: input.routine.latestRevisionId,
+                responsibleUserId: input.routine.responsibleUserId ?? null,
+                triggerPayload: input.details ?? null,
             })
                 .returning();
             await updateRoutineTouchedState({
                 routineId: input.routine.id,
                 triggerId: input.trigger.id,
                 triggeredAt,
-                status: "skipped_paused",
+                status: input.reason === "paused"
+                    ? "skipped_paused"
+                    : input.reason === "no_external_activity"
+                        ? "skipped_no_activity"
+                        : "skipped_worktree_execution_cutoff",
                 nextRunAt: input.nextRunAt,
             }, txDb);
             return createdRun;
@@ -919,16 +1073,17 @@ export function routineService(db, deps = {}) {
             await logActivity(db, {
                 companyId: input.routine.companyId,
                 actorType: "system",
-                actorId: "routine-scheduler",
+                actorId: input.source === "schedule" ? "routine-scheduler" : "routine-webhook",
                 action: "routine.run_skipped",
                 entityType: "routine_run",
                 entityId: run.id,
                 details: {
                     routineId: input.routine.id,
                     triggerId: input.trigger.id,
-                    source: "schedule",
+                    source: input.source,
                     status: "skipped",
                     reason: input.reason,
+                    ...(input.details ?? {}),
                 },
             });
         }
@@ -952,7 +1107,7 @@ export function routineService(db, deps = {}) {
             .select()
             .from(issues)
             .innerJoin(heartbeatRuns, and(eq(heartbeatRuns.id, issues.executionRunId), inArray(heartbeatRuns.status, LIVE_HEARTBEAT_RUN_STATUSES)))
-            .where(and(eq(issues.companyId, routine.companyId), eq(issues.originKind, originKind), eq(issues.originId, originId), inArray(issues.status, OPEN_ISSUE_STATUSES), isNull(issues.hiddenAt), ...(fingerprintCondition ? [fingerprintCondition] : [])))
+            .where(and(eq(issues.companyId, routine.companyId), eq(issues.originKind, originKind), eq(issues.originId, originId), inArray(issues.status, OPEN_ISSUE_STATUSES), visibleIssueCondition(), ...(fingerprintCondition ? [fingerprintCondition] : [])))
             .orderBy(desc(issues.updatedAt), desc(issues.createdAt))
             .limit(1)
             .then((rows) => rows[0]?.issues ?? null);
@@ -962,7 +1117,7 @@ export function routineService(db, deps = {}) {
             .select()
             .from(issues)
             .innerJoin(heartbeatRuns, and(eq(heartbeatRuns.companyId, issues.companyId), inArray(heartbeatRuns.status, LIVE_HEARTBEAT_RUN_STATUSES), sql `${heartbeatRuns.contextSnapshot} ->> 'issueId' = cast(${issues.id} as text)`))
-            .where(and(eq(issues.companyId, routine.companyId), eq(issues.originKind, originKind), eq(issues.originId, originId), inArray(issues.status, OPEN_ISSUE_STATUSES), isNull(issues.hiddenAt), ...(fingerprintCondition ? [fingerprintCondition] : [])))
+            .where(and(eq(issues.companyId, routine.companyId), eq(issues.originKind, originKind), eq(issues.originId, originId), inArray(issues.status, OPEN_ISSUE_STATUSES), visibleIssueCondition(), ...(fingerprintCondition ? [fingerprintCondition] : [])))
             .orderBy(desc(issues.updatedAt), desc(issues.createdAt))
             .limit(1)
             .then((rows) => rows[0]?.issues ?? null);
@@ -1153,6 +1308,21 @@ export function routineService(db, deps = {}) {
             }
             const triggeredAt = new Date();
             const manualRunnerUserId = input.source === "manual" ? input.actor?.userId ?? null : null;
+            const latestRevisionResponsibleUserId = input.routine.latestRevisionId
+                ? await txDb
+                    .select({
+                    responsibleUserId: routineRevisions.responsibleUserId,
+                    snapshot: routineRevisions.snapshot,
+                })
+                    .from(routineRevisions)
+                    .where(and(eq(routineRevisions.companyId, input.routine.companyId), eq(routineRevisions.routineId, input.routine.id), eq(routineRevisions.id, input.routine.latestRevisionId)))
+                    .then((rows) => {
+                    const row = rows[0] ?? null;
+                    const snapshot = row?.snapshot;
+                    return row?.responsibleUserId ?? snapshot?.routine.responsibleUserId ?? null;
+                })
+                : null;
+            const responsibleUserId = manualRunnerUserId ?? latestRevisionResponsibleUserId ?? input.routine.responsibleUserId ?? null;
             const [createdRun] = await txDb
                 .insert(routineRuns)
                 .values({
@@ -1166,6 +1336,7 @@ export function routineService(db, deps = {}) {
                 triggerPayload,
                 dispatchFingerprint,
                 routineRevisionId: input.routine.latestRevisionId,
+                responsibleUserId,
             })
                 .returning();
             const nextRunAt = input.trigger?.kind === "schedule" && input.trigger.cronExpression && input.trigger.timezone
@@ -1216,6 +1387,8 @@ export function routineService(db, deps = {}) {
                         assigneeAgentId,
                         createdByAgentId: input.source === "manual" ? input.actor?.agentId ?? null : null,
                         createdByUserId: manualRunnerUserId,
+                        responsibleUserId,
+                        trustExplicitResponsibleUserId: true,
                         originKind: issueOriginKind,
                         originId: issueOriginId,
                         originRunId: createdRun.id,
@@ -1339,6 +1512,7 @@ export function routineService(db, deps = {}) {
         return run;
     }
     return {
+        evaluateActivityGate,
         get: getRoutineById,
         getTrigger: getTriggerById,
         list: async (companyId, filters) => {
@@ -1490,6 +1664,10 @@ export function routineService(db, deps = {}) {
             const variables = syncRoutineVariablesWithTemplate([input.title, input.description], sanitizeRoutineVariableInputs(input.variables));
             assertRoutineVariableDefinitions(variables);
             const status = normalizeDraftRoutineStatus(input.status, input.assigneeAgentId);
+            const responsibleUserId = await resolveRoutineResponsibleUserId(db, companyId, actor.userId, input.parentIssueId ?? null);
+            if (!responsibleUserId) {
+                throw unprocessable("Routine requires a responsible user");
+            }
             const createdRoutine = await db.transaction(async (tx) => {
                 const txDb = tx;
                 const [created] = await txDb
@@ -1508,6 +1686,7 @@ export function routineService(db, deps = {}) {
                     catchUpPolicy: input.catchUpPolicy,
                     variables,
                     env,
+                    responsibleUserId,
                     createdByAgentId: actor.agentId ?? null,
                     createdByUserId: actor.userId ?? null,
                     updatedByAgentId: actor.agentId ?? null,
@@ -1567,6 +1746,10 @@ export function routineService(db, deps = {}) {
             if (enabledScheduleTriggers) {
                 assertScheduleCompatibleVariables(nextVariables);
             }
+            const responsibleUserId = await resolveRoutineResponsibleUserId(db, existing.companyId, actor.userId, patch.parentIssueId === undefined ? existing.parentIssueId : patch.parentIssueId);
+            if (!responsibleUserId) {
+                throw unprocessable("Routine requires a responsible user");
+            }
             const updatedRoutine = await db.transaction(async (tx) => {
                 const txDb = tx;
                 await tx.execute(sql `select id from ${routines} where ${routines.id} = ${id} for update`);
@@ -1596,6 +1779,7 @@ export function routineService(db, deps = {}) {
                     catchUpPolicy: patch.catchUpPolicy ?? locked.catchUpPolicy,
                     variables: nextVariables,
                     env: nextEnv,
+                    responsibleUserId: locked.responsibleUserId ?? responsibleUserId,
                     updatedByAgentId: actor.agentId ?? null,
                     updatedByUserId: actor.userId ?? null,
                 };
@@ -1631,6 +1815,7 @@ export function routineService(db, deps = {}) {
                     catchUpPolicy: candidate.catchUpPolicy,
                     variables: candidate.variables,
                     env: candidate.env,
+                    responsibleUserId: candidate.responsibleUserId,
                     updatedByAgentId: actor.agentId ?? null,
                     updatedByUserId: actor.userId ?? null,
                     updatedAt: new Date(),
@@ -2135,6 +2320,15 @@ export function routineService(db, deps = {}) {
                 if (!valid)
                     throw unauthorized();
             }
+            const eligibility = await getAutomaticRoutineDispatchEligibility(routine);
+            if (!eligibility.eligible) {
+                return recordSuppressedAutomaticRun({
+                    routine,
+                    trigger,
+                    source: "webhook",
+                    reason: "worktree_execution_cutoff",
+                });
+            }
             return dispatchRoutineRun({
                 routine,
                 trigger,
@@ -2219,6 +2413,12 @@ export function routineService(db, deps = {}) {
             }));
         },
         tickScheduledTriggers: async (now = new Date()) => {
+            const worktreeActivation = isTruthyRuntimeEnvValue(runtimeEnv.PAPERCLIP_IN_WORKTREE)
+                ? await resolveWorktreeRunExecutionActivationState({
+                    getExperimental: instanceSettings.getExperimental,
+                    runtimeEnv,
+                })
+                : undefined;
             const due = await db
                 .select({
                 trigger: routineTriggers,
@@ -2239,9 +2439,11 @@ export function routineService(db, deps = {}) {
                 // at the next cron boundary instead of replaying missed firings. Routines with no
                 // project are never suppressed here.
                 const projectPaused = !!(row.routine.projectId && row.projectPausedAt);
+                const automaticEligibility = await getAutomaticRoutineDispatchEligibility(row.routine, worktreeActivation);
+                const worktreeSuppressed = !automaticEligibility.eligible;
                 let runCount = 1;
                 let claimedNextRunAt = nextCronTickInTimeZone(row.trigger.cronExpression, row.trigger.timezone, now);
-                if (!projectPaused && row.routine.catchUpPolicy === "enqueue_missed_with_cap") {
+                if (!projectPaused && !worktreeSuppressed && row.routine.catchUpPolicy === "enqueue_missed_with_cap") {
                     let cursor = row.trigger.nextRunAt;
                     runCount = 0;
                     while (cursor && cursor <= now && runCount < MAX_CATCH_UP_RUNS) {
@@ -2261,15 +2463,36 @@ export function routineService(db, deps = {}) {
                     .then((rows) => rows[0] ?? null);
                 if (!claimed)
                     continue;
-                if (projectPaused) {
-                    await recordSuppressedScheduleRun({
+                if (projectPaused || worktreeSuppressed) {
+                    await recordSuppressedAutomaticRun({
                         routine: row.routine,
                         trigger: row.trigger,
-                        reason: "paused",
+                        source: "schedule",
+                        reason: worktreeSuppressed ? "worktree_execution_cutoff" : "paused",
                         nextRunAt: claimedNextRunAt,
                     });
                     continue;
                 }
+                const activityGate = row.routine.activityGatePolicy === "require_external_activity"
+                    ? await evaluateActivityGate(row.routine, now)
+                    : null;
+                if (activityGate && !activityGate.fire) {
+                    await recordSuppressedAutomaticRun({
+                        routine: row.routine,
+                        trigger: row.trigger,
+                        source: "schedule",
+                        reason: "no_external_activity",
+                        nextRunAt: claimedNextRunAt,
+                        details: {
+                            activityGate: {
+                                verdict: "quiet",
+                                windowStart: activityGate.windowStart?.toISOString() ?? null,
+                                matchedActivityId: null,
+                            },
+                        },
+                    });
+                    continue;
+                }
                 for (let i = 0; i < runCount; i += 1) {
                     await dispatchRoutineRun({
                         routine: row.routine,