@mrrlin-dev/mcp 0.4.32 → 0.4.36

package/dist/bin.cjs

@@ -36799,6 +36799,24 @@ function date4(params) {
 // ../../node_modules/.pnpm/zod@4.4.3/node_modules/zod/v4/classic/external.js
 config(en_default());
 
+// ../../packages/schemas/dist/artifact-checks.js
+var artifactKindSchema = external_exports.enum([
+  "document",
+  "page",
+  "file_set",
+  "code_change",
+  "structured_data",
+  "message"
+]);
+var ARTIFACT_CHECKS = {
+  document: null,
+  page: { verifier: "url" },
+  file_set: null,
+  code_change: { verifier: "build" },
+  structured_data: null,
+  message: { verifier: "status" }
+};
+
 // ../../packages/schemas/dist/operationIds.js
 var openApiOperationIds = {
   appendExecutionArtifact: "appendExecutionArtifact",
@@ -36889,6 +36907,7 @@ var openApiOperationIds = {
   restartExecutionRun: "restartExecutionRun",
   resolveHandoff: "resolveHandoff",
   touchExecutionRun: "touchExecutionRun",
+  stopExecutionRun: "stopExecutionRun",
   getTaskState: "getTaskState",
   upsertTaskState: "upsertTaskState",
   retireThread: "retireThread",
@@ -36929,7 +36948,15 @@ var openApiOperationIds = {
   getSpecConsensusReview: "getSpecConsensusReview",
   onboardingKickoffTransition: "onboardingKickoffTransition",
   ingestTelemetry: "ingestTelemetry",
-  getTelemetry: "getTelemetry"
+  getTelemetry: "getTelemetry",
+  listCapabilityGrants: "listCapabilityGrants",
+  createCapabilityGrant: "createCapabilityGrant",
+  revokeCapabilityGrant: "revokeCapabilityGrant",
+  listCapabilityRoutes: "listCapabilityRoutes",
+  upsertCapabilityRoute: "upsertCapabilityRoute",
+  resolveCapabilityRoute: "resolveCapabilityRoute",
+  overrideCapabilityToolClass: "overrideCapabilityToolClass",
+  listCapabilityUses: "listCapabilityUses"
 };
 
 // ../../packages/schemas/dist/session.js
@@ -37437,6 +37464,58 @@ function domainScopedReviewHash(rawHash, domain2) {
   const d = normalizeTaskDomain(domain2);
   return d === "code" ? rawHash : `${rawHash}@${d}`;
 }
+var mrrlinDeclaredOutcomeShapeSchema = external_exports.object({
+  sentence: external_exports.string().trim().min(1),
+  requires: external_exports.array(artifactKindSchema).min(1),
+  verification: external_exports.enum(["machine", "human_tap"])
+});
+var mrrlinDeclaredOutcomeSchema = mrrlinDeclaredOutcomeShapeSchema.superRefine((value, ctx) => {
+  const expectedVerifiers = new Set(value.requires.map((kind) => ARTIFACT_CHECKS[kind]?.verifier ?? "human_tap"));
+  if (expectedVerifiers.size > 1) {
+    const spread = value.requires.map((kind) => {
+      const check2 = ARTIFACT_CHECKS[kind];
+      return check2 === null ? `${kind} has no machine check` : `${kind} needs ${check2.verifier}`;
+    }).join(", ");
+    ctx.addIssue({
+      code: external_exports.ZodIssueCode.custom,
+      path: ["requires"],
+      message: `requires spans more than one verifier, so no receipt can ever satisfy it (${spread}). Declare the outcome rather than the steps that produced it; if two things must genuinely exist and neither is a means to the other, split them into linked tasks.`
+    });
+  }
+  const hasVerifiableKind = value.requires.some((kind) => ARTIFACT_CHECKS[kind] !== null);
+  const hasUnverifiableKind = value.requires.some((kind) => ARTIFACT_CHECKS[kind] === null);
+  if (value.verification === "human_tap" && hasVerifiableKind) {
+    ctx.addIssue({
+      code: external_exports.ZodIssueCode.custom,
+      path: ["verification"],
+      message: "human_tap is not permitted: a required kind has a machine verifier"
+    });
+  }
+  if (value.verification === "machine" && hasUnverifiableKind) {
+    ctx.addIssue({
+      code: external_exports.ZodIssueCode.custom,
+      path: ["verification"],
+      message: "machine is not permitted: a required kind has no machine verifier"
+    });
+  }
+});
+var mrrlinReceiptSchema = external_exports.object({
+  kind: external_exports.enum(["outcome", "attempt"]),
+  evidence: external_exports.object({
+    type: external_exports.enum(["url", "build", "status", "human_tap"]),
+    value: external_exports.string().trim().min(1)
+  }),
+  observedAt: external_exports.string().datetime(),
+  requiresCovered: external_exports.array(artifactKindSchema)
+});
+function buildReceipt(input) {
+  return {
+    kind: input.coveredKinds.length === 0 ? "attempt" : "outcome",
+    evidence: { type: input.evidenceType, value: input.evidenceValue },
+    observedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    requiresCovered: input.coveredKinds
+  };
+}
 var mrrlinSpecApprovedSchema = external_exports.enum(["pending", "approved", "skipped", "skipped_legacy"]);
 var mrrlinTaskSourceSchema = external_exports.enum(["fixture-import", "api"]);
 var mrrlinPlanStatusSchema = external_exports.enum(["active", "paused", "done", "archived"]);
@@ -37520,6 +37599,16 @@ var mrrlinRunBlockingReasonCodeSchema = external_exports.enum([
   // start (verifyProviderReadiness returned ready:false) — an environment/infrastructure problem,
   // not a task-content one, so it gets its own code rather than reusing task_blocked.
   "provider_not_ready",
+  // agnostic-delivery: an operator-initiated stop. Parks the run at handoff_requested rather
+  // than cancelling it, so restartParkedExecutionRun can resume it — a zod-only enum extension,
+  // since blocking_reason is a plain text column with no DB CHECK.
+  "operator_stopped",
+  // The agent provider refused work MID-RUN because its usage quota is exhausted — distinct from
+  // `provider_not_ready`, which is the pre-flight readiness gate refusing to start. A quota is
+  // transient and the run is retriable once the limit resets, so this code must never be conflated
+  // with a task-content block; before it existed such a failure fell through to `unknown` and was
+  // handed off to the operator as though the Director had judged the task.
+  "provider_limit_exhausted",
   "unknown"
 ]);
 var mrrlinExecutionArtifactKindSchema = external_exports.enum([
@@ -37632,6 +37721,14 @@ var mrrlinTaskSchema = external_exports.object({
   // resolve it via taskRowToTask. Null reads as the pre-existing default provider and is never
   // backfilled -- it is NOT a mismatch against whatever provider is currently selected.
   directorThreadProvider: external_exports.enum(["codex", "claude"]).nullable().optional(),
+  // agnostic-delivery: asserted before the work, not the deliverable-gate's differently-meaning
+  // `attemptOutcome` asserted after it (design.md). Required at spec approval (task 3.2's API
+  // gate), never at creation -- null on every task until then, forever on legacy tasks. Shape-only
+  // here deliberately (not the cross-check-enforcing mrrlinDeclaredOutcomeSchema): a read must
+  // never crash on a persisted value that fails the manifest cross-check (a raw SQL row, or one
+  // written before task 1.5's superRefine existed) -- only the write path (mrrlinTaskUpdateSchema
+  // below, and task 3.2's approval-time re-check) enforces that stronger rule.
+  declaredOutcome: mrrlinDeclaredOutcomeShapeSchema.nullable().optional(),
   dueDate: external_exports.string().date().nullable(),
   followUpAt: external_exports.string().datetime().nullable(),
   id: mrrlinTaskIdSchema,
@@ -37968,6 +38065,7 @@ var mrrlinTaskUpdateSchema = external_exports.object({
   directorSessionId: external_exports.string().min(1).optional(),
   directorThreadId: external_exports.string().min(1).nullable().optional(),
   directorThreadProvider: external_exports.enum(["codex", "claude"]).nullable().optional(),
+  declaredOutcome: mrrlinDeclaredOutcomeSchema.nullable().optional(),
   dueDate: external_exports.string().date().nullable().optional(),
   impact: mrrlinTaskImpactSchema.optional(),
   notes: external_exports.string().nullable().optional(),
@@ -38475,7 +38573,11 @@ var mrrlinSettleExecutionRunOutcomeSchema = external_exports.object({
   resultSummary: external_exports.string().trim().min(1).max(300),
   deliverablePageId: mrrlinWikiPageIdSchema,
   contentHash: external_exports.string().min(1),
-  leaseId: external_exports.string().min(1)
+  leaseId: external_exports.string().min(1),
+  // Optional: a legacy caller sends none. Absent counts as unsatisfied whenever the task has a
+  // non-null declared_outcome (task 2.7b) — losing dedup must not lose the write, but losing a
+  // receipt must not silently close a task that declared one.
+  receipt: mrrlinReceiptSchema.optional()
 });
 var mrrlinExecutionArtifactSchema = external_exports.object({
   createdAt: external_exports.string().datetime(),
@@ -39041,6 +39143,74 @@ var inboxItemsMarkReadResponseSchema = external_exports.object({
 });
 var inboxItemResponseSchema = external_exports.object({ data: mrrlinInboxItemSchema });
 var inboxItemListResponseSchema = external_exports.object({ data: external_exports.array(mrrlinInboxItemSchema) });
+var capabilityServerIdSchema = external_exports.string().trim().min(1).max(200);
+var capabilityNameSchema = external_exports.string().trim().min(1).max(200);
+var capabilityToolNameSchema = external_exports.string().trim().min(1).max(200);
+var CapabilityReversibilitySchema = external_exports.enum(["reversible", "irreversible"]);
+var CapabilityGateVerdictSchema = external_exports.enum([
+  "silent",
+  "ask_once",
+  "window",
+  "approval",
+  "refused"
+]);
+var capabilityToolClassSourceSchema = external_exports.enum(["annotation", "operator"]);
+var capabilityUseOutcomeSchema = external_exports.enum(["ok", "error", "refused"]);
+var CapabilityGrantSchema = external_exports.object({
+  projectSlug: mrrlinProjectSlugSchema,
+  serverId: capabilityServerIdSchema,
+  grantedAt: external_exports.string().datetime(),
+  // A revoke is a soft revoke: the row stays so `resolveCapabilityRoute` can answer `no_grant`
+  // rather than the indistinguishable `no_route`. A live grant is `revokedAt === null`.
+  revokedAt: external_exports.string().datetime().nullable(),
+  // "First write asks once" is bounded by (project, server) -- exactly this row's key -- so the
+  // confirmation lives here rather than in a second table. `revokeCapability` clears it, which is
+  // what makes a re-grant ask again.
+  firstWriteConfirmedAt: external_exports.string().datetime().nullable()
+});
+var CapabilityRouteSchema = external_exports.object({
+  projectSlug: mrrlinProjectSlugSchema,
+  capability: capabilityNameSchema,
+  // The artifact kind this route delivers. NOT the key -- a project can have two sites, and a key
+  // of `page` would let the second overwrite the first. It is here so a declared outcome, which
+  // carries only artifact kinds, can find its route: without it there is no chain from what a task
+  // promises to where the delivery goes.
+  artifactKind: artifactKindSchema,
+  serverId: capabilityServerIdSchema,
+  toolName: capabilityToolNameSchema,
+  createdAt: external_exports.string().datetime(),
+  updatedAt: external_exports.string().datetime()
+});
+var CapabilityToolClassSchema = external_exports.object({
+  projectSlug: mrrlinProjectSlugSchema,
+  serverId: capabilityServerIdSchema,
+  toolName: capabilityToolNameSchema,
+  toolClass: CapabilityReversibilitySchema,
+  source: capabilityToolClassSourceSchema,
+  setAt: external_exports.string().datetime()
+});
+var CapabilityUseSchema = external_exports.object({
+  id: external_exports.number().int().nonnegative(),
+  projectSlug: mrrlinProjectSlugSchema,
+  serverId: capabilityServerIdSchema,
+  toolName: capabilityToolNameSchema,
+  taskId: mrrlinTaskIdSchema.nullable(),
+  outcome: capabilityUseOutcomeSchema,
+  at: external_exports.string().datetime()
+});
+var capabilityGrantCreateSchema = external_exports.object({ serverId: capabilityServerIdSchema });
+var capabilityRouteUpsertSchema = external_exports.object({
+  artifactKind: artifactKindSchema,
+  serverId: capabilityServerIdSchema,
+  toolName: capabilityToolNameSchema
+});
+var capabilityToolClassOverrideSchema = external_exports.object({ toolClass: CapabilityReversibilitySchema });
+var capabilityGrantResponseSchema = external_exports.object({ data: CapabilityGrantSchema });
+var capabilityGrantListResponseSchema = external_exports.object({ data: external_exports.array(CapabilityGrantSchema) });
+var capabilityRouteResponseSchema = external_exports.object({ data: CapabilityRouteSchema });
+var capabilityRouteListResponseSchema = external_exports.object({ data: external_exports.array(CapabilityRouteSchema) });
+var capabilityToolClassResponseSchema = external_exports.object({ data: CapabilityToolClassSchema });
+var capabilityUseListResponseSchema = external_exports.object({ data: external_exports.array(CapabilityUseSchema) });
 
 // ../../packages/agent-client/dist/providers/codex/render-context-bundle.js
 var DEFAULT_SPEC_BUDGET_CHARS = 6e3;
@@ -39339,6 +39509,36 @@ function detectExhaustedProviderLimit(snapshot, nowMs) {
   const resetAt = candidates.length > 0 ? candidates.reduce((a, b) => a > b ? a : b) : null;
   return { exhausted: true, resetAt };
 }
+var PROVIDER_LIMIT_ERROR_PATTERNS = [
+  // OpenAI / Codex, verbatim from the observed event.
+  /you'?ve hit your usage limit/i,
+  // Anthropic phrasing for the same condition.
+  /you have exceeded your (?:rate limit|usage limit)/i,
+  /credit balance is too low/i,
+  // START-ANCHORED quota wording. Round 2 split on this: the unanchored version was removed in
+  // round 1 for matching task prose ("the quota is being exceeded by another worker"), and a round-2
+  // reviewer then objected that removing it also drops real provider messages that LEAD with the
+  // condition ("Monthly quota exceeded."). Anchoring resolves both — a provider error states the
+  // condition first, prose embeds it — so the pattern is kept, but only at the head of the message.
+  // Note this is a second line of defence either way: a provider that emits a structured
+  // `rate_limits` snapshot is caught by detectExhaustedProviderLimit regardless of wording.
+  // NOTE an unanchored `/usage limit reached/i` used to sit above, and it was the one real leak a
+  // round-4 reviewer's finding pointed at (though not the example they gave): it matched
+  // "[ERROR] memory usage limit reached", where the limit belongs to memory, not the provider. The
+  // anchored pattern below already covers "Usage limit reached …", so the unanchored one was pure
+  // false-positive surface and is gone.
+  //
+  // The optional prefix covers the log decorations providers actually ship with — "Error: ",
+  // "[ERROR] ", "(fatal) " — without letting the condition sit anywhere in a sentence. The noun set
+  // covers "rate limit"/"api limit" forms that carry no "quota" or "credits" at all.
+  /^\s*(?:[[(]?\s*(?:error|fatal|warn(?:ing)?)\s*[\])]?\s*[:-]?\s*)?(?:monthly |daily |monthly\/daily )?(?:quota|usage limit|rate limit|api limit|api credits?|credits?) (?:has been |have been |is |are )?(?:exceeded|exhausted|used up|reached)\b/i
+];
+function detectProviderLimitFromErrorText(text) {
+  if (typeof text !== "string" || text.trim().length === 0)
+    return null;
+  const matched = PROVIDER_LIMIT_ERROR_PATTERNS.some((pattern) => pattern.test(text));
+  return matched ? { exhausted: true, resetAt: null } : null;
+}
 
 // ../../packages/agent-client/dist/providers/codex/adapter.js
 var CodexProviderAdapter = class {
@@ -40855,6 +41055,18 @@ function createMrrlinClient(config2) {
         throw error51;
       }
     },
+    async listCapabilityGrants(projectSlug) {
+      const body = await request(`${projectPath(projectSlug)}/capability-grants`);
+      return capabilityGrantListResponseSchema.parse(body).data;
+    },
+    async listCapabilityUses(projectSlug) {
+      const body = await request(`${projectPath(projectSlug)}/capability-uses`);
+      return capabilityUseListResponseSchema.parse(body).data;
+    },
+    async revokeCapabilityGrant(projectSlug, serverId) {
+      const body = await request(`${projectPath(projectSlug)}/capability-grants/${encodeURIComponent(serverId)}`, { method: "DELETE" });
+      return capabilityGrantResponseSchema.parse(body).data;
+    },
     async listInboxItems(projectSlug, filters = {}) {
       const url2 = appendQuery(`${projectPath(projectSlug)}/inbox`, {
         groupId: filters.groupId,
@@ -40924,6 +41136,12 @@ function createMrrlinClient(config2) {
         throw error51;
       }
     },
+    async stopExecutionRun(projectSlug, runId) {
+      const body = await request(`${projectPath(projectSlug)}/execution-runs/${encodeURIComponent(runId)}/stop`, {
+        method: "POST"
+      });
+      return executionRunResponseSchema.parse(body).data;
+    },
     async requeueExecutionRun(projectSlug, runId, staleSeconds) {
       try {
         const body = await request(`${projectPath(projectSlug)}/execution-runs/${encodeURIComponent(runId)}/requeue`, {
@@ -41853,7 +42071,7 @@ Do NOT derail the current task - if the operator has an in-flight question, answ
 }
 
 // src/_generated/version.ts
-var PKG_VERSION = "0.4.32";
+var PKG_VERSION = "0.4.36";
 
 // src/api-base-url-migrate.ts
 var import_node_fs3 = __toESM(require("node:fs"), 1);
@@ -45657,6 +45875,19 @@ async function findInboxQuestion(client, projectSlug, itemId) {
   const items = await client.listInboxItems(projectSlug, { kind: "question" });
   return items.find((item) => item.id === itemId) ?? null;
 }
+async function cancelDeployGraceWindow(client, projectSlug, runId) {
+  try {
+    await client.decideInboxItem(projectSlug, graceCancelItemId(runId), {
+      verdict: "rejected",
+      decidedBy: "deploy-gate",
+      reason: "operator_stopped"
+    });
+    return true;
+  } catch (error51) {
+    if (error51 instanceof MrrlinApiError && (error51.status === 404 || error51.status === 409)) return false;
+    throw error51;
+  }
+}
 async function autonomyPaused(client) {
   try {
     const settings = await client.getOperatorSettings();
@@ -46515,10 +46746,31 @@ function executionTurnBudgetMessage(budgetMs) {
 function isExecutionTurnTimeoutReason(reason) {
   return reason.startsWith(EXECUTION_TURN_TIMEOUT_PREFIX) || reason.startsWith(EXECUTION_TURN_STALL_PREFIX);
 }
+var PROVIDER_LIMIT_RETRY_CURSOR_PREFIX = "provider_limit_retry:";
+var PROVIDER_LIMIT_RETRY_MAX_ATTEMPTS = 1;
+var PROVIDER_LIMIT_RETRY_CODE = "provider_limit_retry";
+var PROVIDER_LIMIT_PAUSE_REASON = "Agent provider usage limit exhausted during an autonomous execution run.";
+var PROVIDER_LIMIT_HANDOFF_REASON = "The agent provider's usage limit stayed exhausted across every automatic retry, so this run could not proceed. This is a provider quota problem, not a problem with the task.";
+function providerLimitRetryCursor(attempt) {
+  return `${PROVIDER_LIMIT_RETRY_CURSOR_PREFIX}${attempt}`;
+}
+function providerLimitRetryAttempt(checkpointCursor) {
+  if (!checkpointCursor || !checkpointCursor.startsWith(PROVIDER_LIMIT_RETRY_CURSOR_PREFIX)) return 0;
+  const parsed = Number.parseInt(checkpointCursor.slice(PROVIDER_LIMIT_RETRY_CURSOR_PREFIX.length), 10);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : 0;
+}
 function reportAutopilotLimitPause(client, reason, resetAt) {
   void client.pauseAutopilotForLimit({ source: "provider_limit", reason, resetAt }).catch(() => {
   });
 }
+async function applyAutopilotLimitPause(client, reason, resetAt) {
+  try {
+    await client.pauseAutopilotForLimit({ source: "provider_limit", reason, resetAt });
+    return true;
+  } catch {
+    return false;
+  }
+}
 function isDeliverableGateRetryableReason(reason) {
   return DELIVERABLE_GATE_RETRYABLE_REASON_PREFIXES.some((prefix) => reason.startsWith(prefix));
 }
@@ -46574,6 +46826,33 @@ var BASE_INSTRUCTIONS_PREFIX = [
   "concrete progress via MCP tools rather than only narrating it.",
   "",
   "Completion contract (the run is gated on this):",
+  "- Act now, in this turn, whenever the tools to do the work are in reach, the work does not",
+  "  depend on waiting for external state, and any irreversible outward action it takes is already",
+  "  covered by this turn's own recording obligation. The conveyor -- a scheduled follow-up task or",
+  "  plan -- is the exception, entered only for a build-and-test cycle, work still unfinished when",
+  "  the turn ends, or a decision only the operator can make. A task or plan exists to keep",
+  "  unfinished work from being lost, not to authorize doing it later when it could be done now.",
+  "- Never file a clarifying question about anything the operator already answered in this thread.",
+  "  A complete instruction whose work is reachable in this turn gets done, then recorded -- it does",
+  "  not become a question.",
+  // Final-gate finding (round 2, corrected after repo verification -- round 1's comment said
+  // "unconditionally", which overstates it): this line tells the Director not to invoke
+  // run_spec_consensus for such a task. Its OWN mark_spec_ready MCP tool (tools.ts) refuses to
+  // flip spec_ready for the Director-LLM without a CONVERGED review UNLESS the project has
+  // consensus disabled, in which case a DIFFERENT server-side path (the scheduler tick's
+  // auto-promote under the consensus-off policy, tools.ts's own mark_spec_ready comment) can
+  // promote it instead -- that is not a Director-invoked path either. The plain markSpecReady
+  // API/client method (packages/client) has no CONVERGED-review requirement at all and IS directly
+  // reachable (this is what seedApprovedTask in scripts/persona-smoke-agnostic-delivery.ts uses),
+  // but it is not exposed to the Director as an MCP tool. So this instruction does not mean "the
+  // Director marks it ready some other way" -- it means the Director stops short of spec_ready for
+  // a pure form-filling task and leaves that promotion to whichever of the above actually applies
+  // (an operator via the plain route, or the scheduler tick if consensus is disabled for the
+  // project), consistent with such a task being too trivial to need Director-driven review in the
+  // first place. declaredOutcome + the receipt gate (Group 2/3) are unaffected either way -- they
+  // gate on specApproved, which is reachable once spec_ready is set by any caller.
+  "- When a task's entire declared outcome is a submitted form, spec review is unreachable for it --",
+  "  do not route a pure form-filling task through spec review.",
   "- Record evidence with `append_execution_artifact` against the run id shown in the",
   '  "## Open run" section of the context bundle.',
   "- Artifact kinds that count as completion evidence are exactly: checkpoint, test_result, diff_summary, self_review, handoff_judgement.",
@@ -47985,13 +48264,20 @@ async function driveNonCodeRun(deps, projectSlug, runId, leaseId, task, domain2)
       return;
     }
   }
+  const receipt = parsedResult.outcome === "completed" && task.declaredOutcome != null ? buildReceipt({
+    declaredOutcome: task.declaredOutcome,
+    evidenceType: "url",
+    evidenceValue: pageId,
+    coveredKinds: ["page"]
+  }) : void 0;
   try {
     const settled = await deps.client.settleExecutionRunOutcome(projectSlug, runId, {
       leaseId,
       outcome: parsedResult.outcome,
       resultSummary: parsedResult.resultSummary,
       deliverablePageId: pageId,
-      contentHash
+      contentHash,
+      ...receipt ? { receipt } : {}
     });
     if (!settled && await runHasLease(deps, projectSlug, runId, leaseId)) {
       await failRun(
@@ -48027,6 +48313,62 @@ async function failRun(deps, projectSlug, task, runId, leaseId, reason, reasonCo
     return;
   }
   if (currentRun.status !== "running" || currentRun.leaseId !== leaseId) return;
+  let handoffReason = reason;
+  let handoffReasonCode = reasonCode;
+  const providerLimit = detectProviderLimitFromErrorText(reason);
+  if (providerLimit) {
+    const autopilotPaused = await applyAutopilotLimitPause(
+      deps.client,
+      PROVIDER_LIMIT_PAUSE_REASON,
+      providerLimit.resetAt
+    );
+    const attempt = providerLimitRetryAttempt(currentRun.checkpointCursor) + 1;
+    if (attempt <= PROVIDER_LIMIT_RETRY_MAX_ATTEMPTS) {
+      try {
+        await deps.client.updateExecutionRun(projectSlug, runId, {
+          status: "pending",
+          leaseId: null,
+          checkpointCursor: providerLimitRetryCursor(attempt)
+        });
+        await deps.client.appendExecutionArtifact(projectSlug, runId, {
+          id: newArtifactId(),
+          kind: "error",
+          payload: {
+            code: PROVIDER_LIMIT_RETRY_CODE,
+            source: "execution-consumer",
+            attempt,
+            maxAttempts: PROVIDER_LIMIT_RETRY_MAX_ATTEMPTS,
+            // The provider's raw sentence belongs HERE — diagnostic detail on an error artifact —
+            // and never in a handoff `reason`, which the DB trigger caches as the task's judgement.
+            providerMessage: reason,
+            // Whether the brake actually engaged. If it did not, the requeued run is only held
+            // back by its own attempt budget, so this is the difference between "waiting for the
+            // quota" and "about to fail once more"; it must be visible, not swallowed.
+            autopilotPaused,
+            summary: autopilotPaused ? `Agent provider usage limit exhausted; autopilot paused and the run requeued for retry ${attempt}/${PROVIDER_LIMIT_RETRY_MAX_ATTEMPTS}.` : `Agent provider usage limit exhausted; the run was requeued for retry ${attempt}/${PROVIDER_LIMIT_RETRY_MAX_ATTEMPTS}, but pausing autopilot FAILED, so nothing is holding it back.`
+          }
+        }).catch(() => {
+        });
+        return;
+      } catch {
+      }
+    }
+    handoffReason = PROVIDER_LIMIT_HANDOFF_REASON;
+    handoffReasonCode = "provider_limit_exhausted";
+    await deps.client.appendExecutionArtifact(projectSlug, runId, {
+      id: newArtifactId(),
+      kind: "error",
+      payload: {
+        code: PROVIDER_LIMIT_RETRY_CODE,
+        source: "execution-consumer",
+        attempt: PROVIDER_LIMIT_RETRY_MAX_ATTEMPTS,
+        maxAttempts: PROVIDER_LIMIT_RETRY_MAX_ATTEMPTS,
+        providerMessage: reason,
+        summary: "Agent provider usage limit still exhausted after every retry; handing off to the operator."
+      }
+    }).catch(() => {
+    });
+  }
   if (isExecutionTurnTimeoutReason(reason) && currentRun.checkpointCursor !== EXECUTION_TURN_TIMEOUT_RETRY_CURSOR) {
     try {
       await deps.client.updateExecutionRun(projectSlug, runId, {
@@ -48079,11 +48421,11 @@ async function failRun(deps, projectSlug, task, runId, leaseId, reason, reasonCo
   }
   try {
     await deps.client.createExecutionRunHandoff(projectSlug, runId, {
-      reason,
-      ...reasonCode ? { reasonCode } : {}
+      reason: handoffReason,
+      ...handoffReasonCode ? { reasonCode: handoffReasonCode } : {}
     });
   } catch {
-    await notifyOperatorHandoff(deps, projectSlug, task, runId, reason);
+    await notifyOperatorHandoff(deps, projectSlug, task, runId, handoffReason);
   }
 }
 async function reconcileTaskAwaitingMerge(deps, projectSlug, task, runId, reason) {
@@ -48218,6 +48560,12 @@ async function runBackstopSweep(deps, drive = (slug, id) => driveRun(deps, slug,
       await drive(slug, run3.id);
     }
     if (deps.deployGate) {
+      let autonomyPaused2 = false;
+      try {
+        autonomyPaused2 = (await deps.client.getOperatorSettings()).autonomyPaused === true;
+      } catch {
+        autonomyPaused2 = false;
+      }
       for (const status of ["dev_deploy", "prod_deploy"]) {
         let inFlight = [];
         try {
@@ -48229,6 +48577,10 @@ async function runBackstopSweep(deps, drive = (slug, id) => driveRun(deps, slug,
           if (!isDeployGateRunStatus(run3.status)) continue;
           try {
             const task = await deps.client.getTask(slug, run3.taskId);
+            if (autonomyPaused2 || mrrlinTerminalTaskStatuses.includes(task.status)) {
+              await cancelDeployGraceWindow(deps.client, slug, run3.id).catch(() => {
+              });
+            }
             const gateDeps = {
               client: deps.client,
               runVerificationTurn: deps.deployGate.runVerificationTurn,
@@ -48272,6 +48624,17 @@ async function runBackstopSweep(deps, drive = (slug, id) => driveRun(deps, slug,
           }
         }
       }
+      let stoppedRuns = [];
+      try {
+        stoppedRuns = await deps.client.listExecutionRuns(slug, { status: "handoff_requested" });
+      } catch {
+        stoppedRuns = [];
+      }
+      for (const run3 of stoppedRuns) {
+        if (run3.blockingReason !== "operator_stopped") continue;
+        await cancelDeployGraceWindow(deps.client, slug, run3.id).catch(() => {
+        });
+      }
     }
   }
 }
@@ -48506,6 +48869,100 @@ function redactMessage(payload, opts) {
   }
   return { payload: redactValue(payload, 0, counter), redactedCount: counter.count };
 }
+var OUTWARD_TOOL_NAMES = /* @__PURE__ */ new Set([
+  "browser_click",
+  "browser_type",
+  "browser_fill_form",
+  "browser_press_key",
+  "browser_file_upload",
+  "browser_select_option",
+  "create_github_pull_request",
+  "create_github_branch",
+  "dispatch_github_workflow",
+  "dispatch_task_deploy",
+  "deliver_file",
+  "record_produced_url"
+]);
+var READ_TOOL_NAMES = /* @__PURE__ */ new Set([
+  "browser_navigate",
+  "browser_snapshot",
+  "get_execution_run",
+  "get_github_installation_repositories",
+  "get_project",
+  "get_project_scheduler_policy",
+  "get_project_snapshot",
+  "get_scheduler_pending_tasks",
+  "get_task",
+  "get_wiki_page",
+  "list_artifact_files",
+  "list_execution_artifacts",
+  "list_execution_runs",
+  "list_github_installations",
+  "list_github_workflows",
+  "list_inbox_items",
+  "list_plans",
+  "list_project_members",
+  "list_projects",
+  "list_task_dependencies",
+  "list_task_events",
+  "list_tasks",
+  "list_taxonomy",
+  "list_wiki_pages",
+  "retrieve_context",
+  "search_knowledge",
+  "search_wiki_pages",
+  "create_task",
+  "update_task",
+  "create_wiki_page",
+  "update_wiki_page",
+  "create_inbox_item",
+  // Group 4 checkpoint recommendation (claude-opus-5): stop_execution_run (added in Group 3, task
+  // 3.3) is unclassified here otherwise, so it fail-closes to outward -- but its effect (parking a
+  // run's status) is exactly as in-product/already-audited as the 5 writes above, and nothing would
+  // ever resolve it (a stop naturally has no reason to be followed by a create_task/update_task
+  // call), making every turn that stops a run permanently, unfixably "unresolved".
+  "stop_execution_run"
+]);
+function normalizeToolName(toolName) {
+  return toolName.replace(/^mcp__.+?__/, "");
+}
+var MRRLIN_MCP_NAMESPACE_PREFIXES = ["mcp__mrrlin__", "mcp__mrrlin-browser__"];
+function classifyToolEffect(rawToolName) {
+  const toolName = normalizeToolName(rawToolName);
+  if (READ_TOOL_NAMES.has(toolName)) return "read";
+  if (OUTWARD_TOOL_NAMES.has(toolName)) return "outward";
+  if (MRRLIN_MCP_NAMESPACE_PREFIXES.some((prefix) => rawToolName.startsWith(prefix))) return "outward";
+  return "read";
+}
+var BROWSER_OUTWARD_TOOL_NAMES = /* @__PURE__ */ new Set([
+  "browser_click",
+  "browser_type",
+  "browser_fill_form",
+  "browser_press_key",
+  "browser_file_upload",
+  "browser_select_option"
+]);
+var IN_PRODUCT_WRITE_TOOL_NAMES = /* @__PURE__ */ new Set(["create_task", "update_task", "create_wiki_page", "update_wiki_page", "create_inbox_item"]);
+function resolveTurnRecordingObligationEnabled(env = process.env) {
+  const raw = (env.MRRLIN_TURN_RECORDING_OBLIGATION ?? "").trim().toLowerCase();
+  return !(raw === "0" || raw === "false");
+}
+function buildBrowserAttemptReceipt(toolName) {
+  return {
+    kind: "attempt",
+    evidence: { type: "human_tap", value: toolName },
+    observedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    requiresCovered: []
+  };
+}
+function extractSeqAndTurnId(payload) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return { seq: void 0, turnId: void 0 };
+  const p = payload;
+  return {
+    seq: typeof p.seq === "number" ? p.seq : void 0,
+    turnId: typeof p.turnId === "string" ? p.turnId : void 0
+  };
+}
 function resolveBridgeLogEnabled(env = process.env) {
   const raw = (env.MRRLIN_DIRECTOR_BRIDGE_LOG ?? "").trim().toLowerCase();
   return !(raw === "0" || raw === "false");
@@ -48540,6 +48997,29 @@ function createBridgeLogger(stateDir, env = process.env) {
       if (!oldest.done) contextSlugBySession.delete(oldest.value);
     }
   };
+  const turnRecordingObligationEnabled = resolveTurnRecordingObligationEnabled(env);
+  const obligationBySession = /* @__PURE__ */ new Map();
+  const getObligationState = (sessionId) => {
+    let state = obligationBySession.get(sessionId);
+    if (!state) {
+      state = { pending: [], lastSeq: null, lastTurnId: null };
+    } else {
+      obligationBySession.delete(sessionId);
+    }
+    obligationBySession.set(sessionId, state);
+    if (obligationBySession.size > MAX_TRACKED_SESSIONS) {
+      const oldest = obligationBySession.keys().next();
+      if (!oldest.done) obligationBySession.delete(oldest.value);
+    }
+    return state;
+  };
+  const checkSequenceGap = (state, turnId, seq) => {
+    const isNewTurn = turnId === void 0 || turnId !== state.lastTurnId;
+    const isGap = !isNewTurn && state.lastSeq !== null && seq !== state.lastSeq + 1;
+    state.lastSeq = seq;
+    state.lastTurnId = turnId ?? state.lastTurnId;
+    return { isGap, isNewTurn };
+  };
   const gainDay = (sessionId) => {
     const sessionsPath = (0, import_node_path16.join)(logsDir, ".sessions.json");
     let sessionsObj = {};
@@ -48586,6 +49066,48 @@ function createBridgeLogger(stateDir, env = process.env) {
           );
         }
       }
+      let sequenceGap;
+      let syntheticReceipt;
+      let recordingObligationUnresolved;
+      let recordingObligationMultiResolve;
+      if (turnRecordingObligationEnabled && rec.sessionId !== null && dir === "out") {
+        const state = getObligationState(rec.sessionId);
+        const { seq, turnId } = extractSeqAndTurnId(rec.payload);
+        if (seq !== void 0) {
+          const { isGap, isNewTurn } = checkSequenceGap(state, turnId, seq);
+          if (isGap) sequenceGap = true;
+          if (isNewTurn && state.pending.length > 0) recordingObligationUnresolved = state.pending;
+          if (isNewTurn) state.pending = [];
+        }
+        if (projection?.kind === "tool_use" && typeof projection.toolName === "string" && typeof projection.toolId === "string") {
+          const toolName = normalizeToolName(projection.toolName);
+          if (classifyToolEffect(projection.toolName) === "outward") {
+            if (BROWSER_OUTWARD_TOOL_NAMES.has(toolName)) {
+              syntheticReceipt = buildBrowserAttemptReceipt(toolName);
+            } else {
+              state.pending.push({
+                turnSpanId: projection.turnId,
+                toolName,
+                toolId: projection.toolId,
+                seq: projection.seq,
+                armedAt: (/* @__PURE__ */ new Date()).toISOString()
+              });
+            }
+          } else if (IN_PRODUCT_WRITE_TOOL_NAMES.has(toolName) && state.pending.length > 0) {
+            if (state.pending.length > 1) {
+              recordingObligationMultiResolve = {
+                resolvedCount: state.pending.length,
+                toolNames: state.pending.map((p) => p.toolName)
+              };
+            }
+            state.pending = [];
+          }
+        }
+        if (projection?.kind === "turn_lifecycle") {
+          if (state.pending.length > 0) recordingObligationUnresolved = state.pending;
+          state.pending = [];
+        }
+      }
       const { payload: redactedPayload, redactedCount } = redactMessage(rec.payload, { includePrompts });
       const line = JSON.stringify({
         ts: (/* @__PURE__ */ new Date()).toISOString(),
@@ -48598,7 +49120,11 @@ function createBridgeLogger(stateDir, env = process.env) {
         redactedCount,
         projection,
         ...projectionFailed ? { projectionFailed: true } : {},
-        ...projectScopeMismatch ? { projectScopeMismatch } : {}
+        ...projectScopeMismatch ? { projectScopeMismatch } : {},
+        ...sequenceGap ? { sequenceGap } : {},
+        ...syntheticReceipt ? { syntheticReceipt } : {},
+        ...recordingObligationUnresolved ? { recordingObligationUnresolved } : {},
+        ...recordingObligationMultiResolve ? { recordingObligationMultiResolve } : {}
       }) + "\n";
       (0, import_node_fs8.appendFileSync)(fileFor(), line);
       if (rec.sessionId !== null) gainDay(rec.sessionId);
@@ -62415,6 +62941,7 @@ var mcpToolNames = {
   listArtifactFiles: "list_artifact_files",
   reclaimExecutionRunLease: "reclaim_execution_run_lease",
   restartExecutionRun: "restart_execution_run",
+  stopExecutionRun: "stop_execution_run",
   resolveHandoff: "resolve_handoff",
   recordProducedUrl: "record_produced_url",
   updateTaskState: "update_task_state",
@@ -63046,6 +63573,7 @@ var listArtifactFilesInputSchema = projectScopedSchema.merge(
 );
 var reclaimExecutionRunLeaseInputSchema = projectScopedSchema.extend({ runId: mrrlinExecutionRunIdSchema }).merge(mrrlinExecutionRunRequeueSchema);
 var restartExecutionRunInputSchema = projectScopedSchema.extend({ runId: mrrlinExecutionRunIdSchema }).merge(mrrlinRestartExecutionRunSchema);
+var stopExecutionRunInputSchema = projectScopedSchema.extend({ runId: mrrlinExecutionRunIdSchema });
 var listInboxItemsInputSchema = projectScopedSchema.merge(mrrlinInboxItemListFiltersSchema);
 var createInboxItemInputSchema = projectScopedSchema.merge(mrrlinInboxItemCreateSchema);
 var decideInboxItemInputSchema = projectScopedSchema.extend({ itemId: mrrlinInboxItemIdSchema }).merge(mrrlinInboxItemDecideSchema);
@@ -63128,6 +63656,7 @@ var mcpToolInputSchemas = {
   [mcpToolNames.listArtifactFiles]: listArtifactFilesInputSchema,
   [mcpToolNames.reclaimExecutionRunLease]: reclaimExecutionRunLeaseInputSchema,
   [mcpToolNames.restartExecutionRun]: restartExecutionRunInputSchema,
+  [mcpToolNames.stopExecutionRun]: stopExecutionRunInputSchema,
   [mcpToolNames.resolveHandoff]: resolveHandoffInputSchema,
   [mcpToolNames.recordProducedUrl]: recordProducedUrlInputSchema,
   [mcpToolNames.updateTaskState]: updateTaskStateInputSchema,
@@ -63197,6 +63726,7 @@ var mcpToolOperationIds = {
   [mcpToolNames.listArtifactFiles]: openApiOperationIds.listArtifactFiles,
   [mcpToolNames.reclaimExecutionRunLease]: openApiOperationIds.reclaimExecutionRunLease,
   [mcpToolNames.restartExecutionRun]: openApiOperationIds.restartExecutionRun,
+  [mcpToolNames.stopExecutionRun]: openApiOperationIds.stopExecutionRun,
   [mcpToolNames.resolveHandoff]: openApiOperationIds.resolveHandoff
 };
 var mcpToolDescriptions = {
@@ -63267,6 +63797,7 @@ var mcpToolDescriptions = {
   [mcpToolNames.listArtifactFiles]: "List uploaded artifact files for the project (optionally filtered by taskId/runId), newest first.",
   [mcpToolNames.reclaimExecutionRunLease]: "Clear a stale pending execution-run lease when the lease has aged past staleSeconds. Returns the reclaimed run on success, null when the lease is not stale yet, and surfaces a structured conflict when reclaim retries are exhausted.",
   [mcpToolNames.restartExecutionRun]: "Restart a parked execution run (handoff_requested or handoff_queued) back to pending so the queue can resume it.",
+  [mcpToolNames.stopExecutionRun]: "Operator stop: park an in-flight execution run at handoff_requested with blockingReason operator_stopped. Parks rather than cancels, so restart_execution_run can resume it later. Refuses (409) a run already at a terminal status.",
   [mcpToolNames.resolveHandoff]: "Resolve a tool_assisted handoff for an execution run (outcome success|failure). Success returns the task to the board; failure opens a new handoff cycle. Idempotent.",
   [mcpToolNames.registerLocalCheckout]: "Register the operator-local git checkout path for `projectSlug` so execution-run workers run code on this machine instead of the cloud. Validates the path is a git repo whose `origin` remote matches `repo`, then writes the (slug -> absolute path) entry to the operator-local checkout registry. Call this after locating the checkout on disk (e.g. via filesystem search) and confirming the choice with the user in chat \u2014 they should NOT have to paste the path into Settings. Returns `{ projectSlug, path, confirmedAt }`. Idempotent: re-registering overwrites the prior entry.",
   [mcpToolNames.retrieveContext]: "Rehydrate a mrrlin:// handle emitted by the compact-context layer into the full canonical Mrrlin record (task/wiki page/project snapshot/execution run/artifacts). Use whenever you need the full source \u2014 irreversible decisions (closing tasks, dispatching deploys, writing specs) MUST call this first; never act on a compact envelope alone. Returns `{ kind, data }`. Invalid or unsupported handle \u2192 structured `HANDLE_INVALID` error."
@@ -64166,6 +64697,13 @@ function createMrrlinTools(options) {
       "Unable to restart the execution run.",
       async (c, { projectSlug, runId, ...input }) => await c.restartExecutionRun(projectSlug, runId, input)
     ),
+    [mcpToolNames.stopExecutionRun]: makeTool(
+      client,
+      mcpToolNames.stopExecutionRun,
+      "EXECUTION_RUN_STOP_FAILED",
+      "Unable to stop the execution run.",
+      async (c, { projectSlug, runId }) => await c.stopExecutionRun(projectSlug, runId)
+    ),
     [mcpToolNames.resolveHandoff]: makeTool(
       client,
       mcpToolNames.resolveHandoff,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrrlin-dev/mcp",
-  "version": "0.4.32",
+  "version": "0.4.36",
   "type": "module",
   "bin": {
     "mrrlin-mcp": "dist/bin.cjs"
@@ -22,10 +22,10 @@
     "esbuild": "^0.24.0",
     "tsx": "^4.22.3",
     "@mrrlin/client": "0.0.0",
+    "@mrrlin/agent-client": "0.0.0",
     "@mrrlin/director-e2e": "0.0.0",
     "@mrrlin/schemas": "0.0.0",
     "@mrrlin/tsconfig": "0.0.0",
-    "@mrrlin/agent-client": "0.0.0",
     "@mrrlin/wiki": "0.0.0"
   },
   "dependencies": {