feat(agent-actions): generalize the review-nag cooldown into a per-command rate limit

The only throttle on the @gittensory command surface was maybeThrottleReviewNagPing,
deliberately narrow (thread's own author only, review-nag policy only). Every
other command in the catalog -- ask, preflight, blockers, packet, the maintainer
queue-digest commands, etc. -- had no cooldown at all, and most dispatch to
real, AI-cost-bearing orchestrator calls a careless or malicious actor could
spam dozens of times on the same thread.

Adds maybeThrottleGittensoryCommand, generalizing review-nag's audit-ledger
counting pattern (countRecentAuditEventsForActorAndTarget) to any command --
keyed by (actor, command, targetKey) so each command gets its own independent
counter. Config-driven per repo via commandRateLimitPolicy ("off"/"hold"),
off by default so existing repos see no behavior change. AI-cost-bearing
commands (ask/blockers/preflight/reviewability/packet/duplicate-check/
next-action/repo-fit) get a tighter default limit than cheap, cache-only
commands. A rate-limited invocation gets a clear cooldown reply, never silence.

Independent of and complementary to review-nag's own narrower thread-author-
only, close-capable cooldown -- this generalizes the pattern without
replacing it.

Closes #2560.

Author: JSONbored

.gittensory.yml.example

@@ -333,3 +333,12 @@ settings:
   # above will reuse this list too), on top of the standing owner/admin/automation-bot exemption.
   # List of GitHub logins. Default: [] (no additional exemptions).
   # autoCloseExemptLogins: [some-trusted-regular]
+
+  # Per-command @gittensory rate limit (#2560, anti-abuse): generalizes review-nag's cooldown pattern to
+  # EVERY @gittensory command (help/ask/preflight/blockers/... and the maintainer queue-digest commands),
+  # not just review-request pings — independent of review-nag's own thread-author-only scope. "hold"
+  # replies with a cooldown notice and skips the command's own dispatch. Off by default.
+  # commandRateLimitPolicy: off             # off | hold. Default: off.
+  # commandRateLimitMaxPerWindow: 20        # Positive integer. Per-command invocation limit for a CHEAP command (cache-only, no AI call) within the window. Default: 20.
+  # commandRateLimitAiMaxPerWindow: 5       # Positive integer. Tighter limit for an AI-cost-bearing command (ask/blockers/preflight/reviewability/packet/duplicate-check/next-action/repo-fit). Default: 5.
+  # commandRateLimitWindowHours: 24         # Positive integer. Rolling window (hours) both limits above count against. Default: 24.

apps/gittensory-ui/public/openapi.json

@@ -8688,6 +8688,28 @@
             "nullable": true,
             "minimum": 0,
             "exclusiveMinimum": true
+          },
+          "commandRateLimitPolicy": {
+            "type": "string",
+            "enum": [
+              "off",
+              "hold"
+            ]
+          },
+          "commandRateLimitMaxPerWindow": {
+            "type": "integer",
+            "minimum": 0,
+            "exclusiveMinimum": true
+          },
+          "commandRateLimitAiMaxPerWindow": {
+            "type": "integer",
+            "minimum": 0,
+            "exclusiveMinimum": true
+          },
+          "commandRateLimitWindowHours": {
+            "type": "integer",
+            "minimum": 0,
+            "exclusiveMinimum": true
           }
         },
         "required": [

migrations/0094_command_rate_limit.sql

@@ -0,0 +1,11 @@
+-- Per-command @gittensory rate limit (#2560, anti-abuse): generalizes the review-nag cooldown's audit-ledger
+-- counting pattern to EVERY @gittensory command, not just review-request pings. Independent of and complementary
+-- to review-nag (that stays scoped to the thread's own author; this covers any actor invoking any command).
+-- Defaults are byte-identical to today: command_rate_limit_policy defaults to 'off' (disabled), so existing
+-- repos see no behavior change until they opt in. The AI-cost-bearing commands (ask/blockers/preflight/
+-- reviewability/packet/duplicate-check/next-action/repo-fit) get their own tighter default limit than the
+-- cheap, cache-only commands (help/miner-context/the maintainer queue-digest commands).
+ALTER TABLE repository_settings ADD COLUMN command_rate_limit_policy TEXT NOT NULL DEFAULT 'off';
+ALTER TABLE repository_settings ADD COLUMN command_rate_limit_max_per_window INTEGER NOT NULL DEFAULT 20;
+ALTER TABLE repository_settings ADD COLUMN command_rate_limit_ai_max_per_window INTEGER NOT NULL DEFAULT 5;
+ALTER TABLE repository_settings ADD COLUMN command_rate_limit_window_hours INTEGER NOT NULL DEFAULT 24;

src/db/repositories.ts

@@ -511,6 +511,10 @@ export async function getRepositorySettings(env: Env, fullName: string): Promise
       reviewNagLabel: "review-nag-cooldown",
       autoCloseExemptLogins: [],
       requireFreshRebaseWindowMinutes: null,
+      commandRateLimitPolicy: "off",
+      commandRateLimitMaxPerWindow: 20,
+      commandRateLimitAiMaxPerWindow: 5,
+      commandRateLimitWindowHours: 24,
     };
   }
   return {
@@ -564,6 +568,10 @@ export async function getRepositorySettings(env: Env, fullName: string): Promise
     reviewNagLabel: row.reviewNagLabel,
     autoCloseExemptLogins: parseAutoCloseExemptLogins(row.autoCloseExemptLoginsJson),
     requireFreshRebaseWindowMinutes: normalizeOpenItemCap(row.requireFreshRebaseWindowMinutes),
+    commandRateLimitPolicy: normalizeCommandRateLimitPolicy(row.commandRateLimitPolicy),
+    commandRateLimitMaxPerWindow: normalizePositiveIntWithDefault(row.commandRateLimitMaxPerWindow, 20),
+    commandRateLimitAiMaxPerWindow: normalizePositiveIntWithDefault(row.commandRateLimitAiMaxPerWindow, 5),
+    commandRateLimitWindowHours: normalizePositiveIntWithDefault(row.commandRateLimitWindowHours, 24),
     createdAt: row.createdAt,
     updatedAt: row.updatedAt,
   };
@@ -649,6 +657,10 @@ export async function upsertRepositorySettings(env: Env, settings: Partial<Repos
     reviewNagLabel: settings.reviewNagLabel ?? "review-nag-cooldown",
     autoCloseExemptLogins: normalizeAutoCloseExemptLogins(settings.autoCloseExemptLogins).logins,
     requireFreshRebaseWindowMinutes: normalizeOpenItemCap(settings.requireFreshRebaseWindowMinutes),
+    commandRateLimitPolicy: normalizeCommandRateLimitPolicy(settings.commandRateLimitPolicy),
+    commandRateLimitMaxPerWindow: normalizePositiveIntWithDefault(settings.commandRateLimitMaxPerWindow, 20),
+    commandRateLimitAiMaxPerWindow: normalizePositiveIntWithDefault(settings.commandRateLimitAiMaxPerWindow, 5),
+    commandRateLimitWindowHours: normalizePositiveIntWithDefault(settings.commandRateLimitWindowHours, 24),
   };
   const db = getDb(env.DB);
   await db
@@ -704,6 +716,10 @@ export async function upsertRepositorySettings(env: Env, settings: Partial<Repos
       reviewNagLabel: resolved.reviewNagLabel,
       autoCloseExemptLoginsJson: jsonString(resolved.autoCloseExemptLogins),
       requireFreshRebaseWindowMinutes: resolved.requireFreshRebaseWindowMinutes,
+      commandRateLimitPolicy: resolved.commandRateLimitPolicy,
+      commandRateLimitMaxPerWindow: resolved.commandRateLimitMaxPerWindow,
+      commandRateLimitAiMaxPerWindow: resolved.commandRateLimitAiMaxPerWindow,
+      commandRateLimitWindowHours: resolved.commandRateLimitWindowHours,
       updatedAt: nowIso(),
     })
     .onConflictDoUpdate({
@@ -760,6 +776,10 @@ export async function upsertRepositorySettings(env: Env, settings: Partial<Repos
         reviewNagLabel: resolved.reviewNagLabel,
         autoCloseExemptLoginsJson: jsonString(resolved.autoCloseExemptLogins),
         requireFreshRebaseWindowMinutes: resolved.requireFreshRebaseWindowMinutes,
+        commandRateLimitPolicy: resolved.commandRateLimitPolicy,
+        commandRateLimitMaxPerWindow: resolved.commandRateLimitMaxPerWindow,
+        commandRateLimitAiMaxPerWindow: resolved.commandRateLimitAiMaxPerWindow,
+        commandRateLimitWindowHours: resolved.commandRateLimitWindowHours,
         updatedAt: nowIso(),
       },
     });
@@ -5703,6 +5723,10 @@ function normalizeReviewNagPolicy(value: string | null | undefined): "off" | "ho
   return value === "hold" || value === "close" ? value : "off";
 }
 
+function normalizeCommandRateLimitPolicy(value: string | null | undefined): "off" | "hold" {
+  return value === "hold" ? value : "off";
+}
+
 // A review-nag threshold/window is a discrete positive count, not a score — reuses the same non-clamping,
 // non-rounding shape as contributorOpenPrCap's normalizeOpenItemCap (#2270): an invalid value (fractional,
 // non-positive, non-finite) falls back to the given default rather than being silently coerced.

src/db/schema.ts

@@ -102,6 +102,12 @@ export const repositorySettings = sqliteTable("repository_settings", {
   // Force-rebase-before-merge window in minutes (#2552): null = never force (default). Enforcement lands in
   // runAgentMaintenancePlanAndExecute, not here.
   requireFreshRebaseWindowMinutes: integer("require_fresh_rebase_window_minutes"),
+  // Per-command @gittensory rate limit (#2560, anti-abuse): generalizes review-nag's cooldown pattern to every
+  // command, keyed by (actor, command, targetKey) independent of review-nag's own thread-author-only scope.
+  commandRateLimitPolicy: text("command_rate_limit_policy").notNull().default("off"),
+  commandRateLimitMaxPerWindow: integer("command_rate_limit_max_per_window").notNull().default(20),
+  commandRateLimitAiMaxPerWindow: integer("command_rate_limit_ai_max_per_window").notNull().default(5),
+  commandRateLimitWindowHours: integer("command_rate_limit_window_hours").notNull().default(24),
   createdAt: text("created_at").notNull().$defaultFn(() => nowIso()),
   updatedAt: text("updated_at").notNull().$defaultFn(() => nowIso()),
 });

src/github/commands.ts

@@ -201,6 +201,26 @@ export function isMaintainerOnlyCommand(command: GittensoryMentionCommandName):
   return isMaintainerQueueDigestCommand(command);
 }
 
+// Commands that dispatch to a real AI orchestrator call (planNextWork / explainBlockersWithAgent /
+// preflightBranchWithAgent / preparePrPacketWithAgent in buildMentionCommandBundle), as opposed to `help`,
+// `miner-context` (both no-op), and every maintainer queue-digest command (cache-only DB reads via
+// buildMaintainerQueueDigestForCommand, no AI call at all) (#2560). Used to apply a tighter per-command rate
+// limit to the AI-cost-bearing surface than the cheap one.
+const AI_COST_BEARING_COMMANDS = new Set<GittensoryMentionCommandName>([
+  "ask",
+  "blockers",
+  "preflight",
+  "reviewability",
+  "packet",
+  "duplicate-check",
+  "next-action",
+  "repo-fit",
+]);
+
+export function isAiCostBearingCommand(command: GittensoryMentionCommandName): boolean {
+  return AI_COST_BEARING_COMMANDS.has(command);
+}
+
 export function isAuthorizedCommandActor(args: {
   commandName?: GittensoryMentionCommandName | undefined;
   commenterLogin?: string | null | undefined;

src/openapi/schemas.ts

@@ -650,6 +650,10 @@ export const RepositorySettingsSchema = z
     reviewNagCooldownDays: z.number().int().positive().optional(),
     reviewNagLabel: z.string().optional(),
     autoCloseExemptLogins: z.array(z.string()).optional(),
+    commandRateLimitPolicy: z.enum(["off", "hold"]).optional(),
+    commandRateLimitMaxPerWindow: z.number().int().positive().optional(),
+    commandRateLimitAiMaxPerWindow: z.number().int().positive().optional(),
+    commandRateLimitWindowHours: z.number().int().positive().optional(),
     createdAt: z.string().nullable().optional(),
     updatedAt: z.string().nullable().optional(),
   })

src/queue/processors.ts

@@ -131,6 +131,7 @@ import {
   buildMaintainerQueueDigest,
   buildPublicAgentCommandComment,
   type GittensoryMentionCommandName,
+  isAiCostBearingCommand,
   isAuthorizedCommandActor,
   isMaintainerQueueDigestCommand,
   parseAgentCommandFeedbackContext,
@@ -8827,6 +8828,90 @@ async function maybeThrottleReviewNagPing(
   return true;
 }
 
+// Audit eventType for one recorded @gittensory command invocation (#2560). Shared between the recorder below
+// and the cooldown-window count query so a naming drift can't silently under/over-count.
+const COMMAND_RATE_LIMIT_EVENT_TYPE = "github_app.command_invocation";
+
+/**
+ * Per-command @gittensory rate limit (#2560, anti-abuse): generalizes review-nag's audit-ledger counting
+ * pattern (`countRecentAuditEventsForActorAndTarget`) to EVERY `@gittensory` Q&A command, not just
+ * review-request pings. Keyed by `(actor, command, targetKey)` — the command name is folded into targetKey so
+ * repeatedly invoking ONE command never counts against a DIFFERENT command's own limit. Independent of, and
+ * complementary to, `maybeThrottleReviewNagPing` above: that one stays scoped to the thread's OWN author and
+ * can close a PR; this covers ANY authorized actor invoking ANY command and only ever holds (declines with a
+ * notice), never closes. Off (`commandRateLimitPolicy: "off"`, the default) is a complete no-op.
+ */
+async function maybeThrottleGittensoryCommand(
+  env: Env,
+  args: {
+    deliveryId: string;
+    repoFullName: string;
+    issueNumber: number;
+    installationId: number;
+    commenter: string;
+    command: GittensoryMentionCommandName;
+    settings: RepositorySettings;
+    mode: ReturnType<typeof resolveAgentActionMode>;
+  },
+): Promise<boolean> {
+  /* v8 ignore next -- resolveRepositorySettings always resolves a concrete "off"/"hold"; the undefined side is defensive against the field's optional TS type. */
+  const policy = args.settings.commandRateLimitPolicy ?? "off";
+  if (policy === "off") return false;
+
+  const targetKey = `${args.repoFullName}#${args.issueNumber}#${args.command}`;
+  const aiCostBearing = isAiCostBearingCommand(args.command);
+  /* v8 ignore next -- resolveRepositorySettings always resolves a concrete positive integer; the undefined side is defensive against the field's optional TS type. */
+  const maxPerWindow = aiCostBearing
+    ? (args.settings.commandRateLimitAiMaxPerWindow ?? 5)
+    : (args.settings.commandRateLimitMaxPerWindow ?? 20);
+  /* v8 ignore next -- resolveRepositorySettings always resolves a concrete positive integer; the undefined side is defensive against the field's optional TS type. */
+  const windowHours = args.settings.commandRateLimitWindowHours ?? 24;
+  const sinceIso = new Date(Date.now() - windowHours * 60 * 60 * 1000).toISOString();
+  const priorInvocations = await countRecentAuditEventsForActorAndTarget(env, args.commenter, COMMAND_RATE_LIMIT_EVENT_TYPE, targetKey, sinceIso);
+  const invocationCount = priorInvocations + 1; // this invocation counts too
+
+  // Always record the invocation first so the running count reflects reality even when the rest of this
+  // handler short-circuits below (a failed recordAuditEvent must never block command dispatch).
+  await recordAuditEvent(env, {
+    eventType: COMMAND_RATE_LIMIT_EVENT_TYPE,
+    actor: args.commenter,
+    targetKey,
+    outcome: "completed",
+    detail: `invocation ${invocationCount}/${maxPerWindow} within ${windowHours}h window`,
+    metadata: { deliveryId: args.deliveryId, repoFullName: args.repoFullName, command: args.command, aiCostBearing },
+  }).catch(
+    /* v8 ignore next -- fail-safe: an audit write failure never blocks command dispatch */
+    () => undefined,
+  );
+
+  if (invocationCount <= maxPerWindow) return false; // under threshold — normal dispatch proceeds unchanged
+
+  if (args.mode === "live") {
+    await createIssueComment(
+      env,
+      args.installationId,
+      args.repoFullName,
+      args.issueNumber,
+      `@${args.commenter} the \`${args.command}\` command has reached its rate limit (${maxPerWindow} within ${windowHours}h). Please wait for the window to pass before trying again. This is an automated maintenance action.`,
+    ).catch(
+      /* v8 ignore next -- fail-safe: a comment-post failure must not crash the throttle decision itself */
+      () => undefined,
+    );
+  }
+  await recordAuditEvent(env, {
+    eventType: "github_app.command_rate_limit_applied",
+    actor: "gittensory",
+    targetKey,
+    outcome: args.mode === "live" ? "completed" : "denied",
+    detail: `hold applied: ${args.commenter} invoked ${args.command} ${invocationCount} times (limit ${maxPerWindow})`,
+    metadata: { deliveryId: args.deliveryId, repoFullName: args.repoFullName, mode: args.mode, command: args.command },
+  }).catch(
+    /* v8 ignore next -- fail-safe: an audit write failure never blocks the handler */
+    () => undefined,
+  );
+  return true;
+}
+
 async function maybeProcessGittensoryMentionCommand(
   env: Env,
   deliveryId: string,
@@ -9024,6 +9109,21 @@ async function maybeProcessGittensoryMentionCommand(
     return true;
   }
 
+  if (
+    await maybeThrottleGittensoryCommand(env, {
+      deliveryId,
+      repoFullName,
+      issueNumber: issue.number,
+      installationId,
+      commenter,
+      command: command.name,
+      settings,
+      mode: mentionMode,
+    })
+  ) {
+    return true;
+  }
+
   const answerId = crypto.randomUUID();
   const login = pullRequestAuthor ?? commenter;
   const maintainerDigest = isMaintainerQueueDigestCommand(command.name)

src/signals/focus-manifest.ts

@@ -150,6 +150,10 @@ export type FocusManifestSettings = Partial<
     | "reviewNagCooldownDays"
     | "reviewNagLabel"
     | "autoCloseExemptLogins"
+    | "commandRateLimitPolicy"
+    | "commandRateLimitMaxPerWindow"
+    | "commandRateLimitAiMaxPerWindow"
+    | "commandRateLimitWindowHours"
   >
 >;
 
@@ -864,6 +868,15 @@ function parseSettingsOverride(value: JsonValue | undefined, warnings: string[])
     warnings.push(...exemptWarnings);
     if (logins.length > 0) out.autoCloseExemptLogins = logins;
   }
+  // Per-command @gittensory rate limit (#2560): generalizes review-nag's cooldown pattern to every command.
+  const commandRateLimitPolicy = normalizeOptionalEnum(r.commandRateLimitPolicy, "settings.commandRateLimitPolicy", ["off", "hold"] as const, warnings);
+  if (commandRateLimitPolicy !== null) out.commandRateLimitPolicy = commandRateLimitPolicy;
+  const commandRateLimitMaxPerWindow = normalizeOptionalPositiveInteger(r.commandRateLimitMaxPerWindow, "settings.commandRateLimitMaxPerWindow", warnings);
+  if (commandRateLimitMaxPerWindow !== null) out.commandRateLimitMaxPerWindow = commandRateLimitMaxPerWindow;
+  const commandRateLimitAiMaxPerWindow = normalizeOptionalPositiveInteger(r.commandRateLimitAiMaxPerWindow, "settings.commandRateLimitAiMaxPerWindow", warnings);
+  if (commandRateLimitAiMaxPerWindow !== null) out.commandRateLimitAiMaxPerWindow = commandRateLimitAiMaxPerWindow;
+  const commandRateLimitWindowHours = normalizeOptionalPositiveInteger(r.commandRateLimitWindowHours, "settings.commandRateLimitWindowHours", warnings);
+  if (commandRateLimitWindowHours !== null) out.commandRateLimitWindowHours = commandRateLimitWindowHours;
   return out;
 }
 

src/types.ts

@@ -666,6 +666,28 @@ export type RepositorySettings = {
    *  force -- a `mergeable_state: clean` read is trusted exactly as it is today. Layered like every other
    *  settings field (`.gittensory.yml` `gate.requireFreshRebaseWindow` > DB > `null`). */
   requireFreshRebaseWindowMinutes?: number | null | undefined;
+  /** Per-command @gittensory rate limit (#2560, anti-abuse): generalizes the review-nag cooldown's counting
+   *  pattern (the audit-events ledger) to EVERY `@gittensory` command, keyed by `(actor, command, targetKey)` --
+   *  independent of, and complementary to, review-nag's own narrower thread-author-only scope. `"off"` (default)
+   *  is a no-op; `"hold"` posts a deterministic cooldown reply and skips the command's own dispatch. Always
+   *  populated by the DB layer (default `"off"`); optional so existing settings fixtures/callers need not be
+   *  touched. */
+  commandRateLimitPolicy?: "off" | "hold" | undefined;
+  /** Per-command rate limit (#2560): how many invocations of a single command an actor may make within
+   *  {@link commandRateLimitWindowHours} before the (N+1)th is throttled -- for a CHEAP command (cache-only,
+   *  no AI orchestrator call). Always populated by the DB layer (default `20`); optional so existing settings
+   *  fixtures/callers need not be touched. Only meaningful when {@link commandRateLimitPolicy} is not `"off"`. */
+  commandRateLimitMaxPerWindow?: number | undefined;
+  /** Per-command rate limit (#2560): the same threshold as {@link commandRateLimitMaxPerWindow}, but for an
+   *  AI-cost-bearing command (dispatches to a real orchestrator call: `ask`, `blockers`, `preflight`,
+   *  `reviewability`, `packet`, `duplicate-check`, `next-action`, `repo-fit`). Deliberately tighter than the
+   *  cheap-command default. Always populated by the DB layer (default `5`); optional so existing settings
+   *  fixtures/callers need not be touched. */
+  commandRateLimitAiMaxPerWindow?: number | undefined;
+  /** Per-command rate limit (#2560): the rolling window (in hours) both {@link commandRateLimitMaxPerWindow}
+   *  and {@link commandRateLimitAiMaxPerWindow} count against. Always populated by the DB layer (default `24`);
+   *  optional so existing settings fixtures/callers need not be touched. */
+  commandRateLimitWindowHours?: number | undefined;
   /** Agent-layer autonomy dial (#773): per-action-class level. Always populated by the DB layer (default
    *  `{}` = deny-by-default = "observe" for every class); optional so existing settings fixtures/callers
    *  need not be touched. The single source the action layer (#778) reads via `resolveAutonomy`. */