@mrrlin-dev/mcp 0.4.0 → 0.4.2

package/dist/bin.cjs

@@ -36476,6 +36476,7 @@ var openApiOperationIds = {
   getOperatorSettings: "getOperatorSettings",
   updateOperatorSettings: "updateOperatorSettings",
   recordOperatorPresence: "recordOperatorPresence",
+  pauseAutopilotForLimit: "pauseAutopilotForLimit",
   getAgentPool: "getAgentPool",
   putAgentPool: "putAgentPool",
   getConsensusConfig: "getConsensusConfig",
@@ -36522,6 +36523,13 @@ var mrrlinOperatorSettingsSchema = external_exports.object({
   activeProjectSlug: external_exports.string().min(1).nullable(),
   // The last time an authenticated BROWSER operator session was observed. Null means never seen.
   lastPresenceAt: external_exports.string().datetime().nullable(),
+  // autopilot-limit-pause: READ-ONLY status for an automatic provider-limit pause. These are never
+  // writable via mrrlinOperatorSettingsUpdateSchema (an explicit operator write clears them
+  // server-side). Non-null autoPauseSource => the current pause is machine-owned; autoPauseResetAt
+  // is the absolute reset time (null = indefinite, manual resume required).
+  autoPauseSource: external_exports.string().min(1).nullable(),
+  autoPauseReason: external_exports.string().min(1).nullable(),
+  autoPauseResetAt: external_exports.string().datetime().nullable(),
   createdAt: external_exports.string().datetime(),
   updatedAt: external_exports.string().datetime()
 });
@@ -36533,6 +36541,11 @@ var mrrlinOperatorSettingsUpdateSchema = external_exports.object({
   message: "OperatorSettingsUpdate requires at least one field"
 });
 var operatorSettingsResponseSchema = external_exports.object({ data: mrrlinOperatorSettingsSchema });
+var autopilotLimitPauseRequestSchema = external_exports.object({
+  source: external_exports.string().min(1).default("provider_limit"),
+  reason: external_exports.string().min(1).max(500),
+  resetAt: external_exports.string().datetime().nullable().default(null)
+}).strict();
 var operatorPresenceResponseSchema = external_exports.object({ data: external_exports.object({ lastPresenceAt: external_exports.string().datetime() }) });
 var operatorPresenceRequestSchema = external_exports.object({ projectSlug: external_exports.string().min(1).optional() }).strict().optional();
 var mrrlinConsensusConfigSchema = external_exports.object({ consensusEnabled: external_exports.boolean() });
@@ -38123,7 +38136,7 @@ var wakeDirectorResponseSchema = external_exports.object({
     }))
   })
 });
-var mrrlinInboxItemKindSchema = external_exports.enum(["proposal", "check_in", "question", "handoff", "info"]);
+var mrrlinInboxItemKindSchema = external_exports.enum(["proposal", "check_in", "question", "handoff", "info", "completed"]);
 var mrrlinInboxItemStatusSchema = external_exports.enum(["pending", "approved", "rejected", "acknowledged"]);
 var mrrlinInboxItemIdSchema = external_exports.string().regex(/^II-[A-Za-z0-9._-]+$/);
 var mrrlinInboxItemActionPayloadSchema = external_exports.object({
@@ -38174,6 +38187,9 @@ var mrrlinInboxQuestionOptionsSchema = external_exports.array(mrrlinInboxQuestio
     });
   }
 });
+var REVIEW_AGAIN_ANSWER = "Review the current spec again without changing it.";
+var EDIT_SPEC_ANSWER = "Hold the task until the spec is edited by hand.";
+var PROCEED_ANYWAY_ANSWER = "Proceed without agreement; record the unsettled points on the spec.";
 var mrrlinInboxItemSchema = external_exports.object({
   actionPayload: mrrlinInboxItemActionPayloadSchema.nullable(),
   answer: external_exports.string().nullable(),
@@ -38583,6 +38599,36 @@ function addTurnTokenUsage(total, turn) {
   };
 }
 
+// ../../packages/codex-client/dist/rate-limit.js
+var EXHAUSTION_USED_PERCENT = 100;
+function windowExhausted(window) {
+  if (!window)
+    return false;
+  return typeof window.usedPercent === "number" && Number.isFinite(window.usedPercent) && window.usedPercent >= EXHAUSTION_USED_PERCENT;
+}
+function normalizeResetEpochSeconds(resetsAt, nowMs) {
+  if (typeof resetsAt !== "number" || !Number.isFinite(resetsAt))
+    return null;
+  const resetMs = resetsAt * 1e3;
+  if (resetMs <= nowMs)
+    return null;
+  return new Date(resetMs).toISOString();
+}
+function detectExhaustedProviderLimit(snapshot, nowMs) {
+  if (!snapshot)
+    return null;
+  const reachedType = typeof snapshot.rateLimitReachedType === "string" ? snapshot.rateLimitReachedType.trim() : "";
+  const exhausted = reachedType.length > 0 || windowExhausted(snapshot.primary) || windowExhausted(snapshot.secondary);
+  if (!exhausted)
+    return null;
+  const candidates = [
+    normalizeResetEpochSeconds(snapshot.primary?.resetsAt, nowMs),
+    normalizeResetEpochSeconds(snapshot.secondary?.resetsAt, nowMs)
+  ].filter((value) => value !== null);
+  const resetAt = candidates.length > 0 ? candidates.reduce((a, b) => a > b ? a : b) : null;
+  return { exhausted: true, resetAt };
+}
+
 // ../../packages/client/dist/agent-token-provider.js
 var AgentTokenProviderError = class extends Error {
   code;
@@ -39493,6 +39539,15 @@ function createMrrlinClient(config2) {
       });
       return operatorSettingsResponseSchema.parse(body).data;
     },
+    async pauseAutopilotForLimit(input) {
+      const parsed = autopilotLimitPauseRequestSchema.parse(input);
+      const body = await request(`/operator/autopilot/limit-pause`, {
+        body: JSON.stringify(parsed),
+        headers: { "content-type": "application/json" },
+        method: "POST"
+      });
+      return operatorSettingsResponseSchema.parse(body).data;
+    },
     async recordOperatorPresence(input) {
       const projectSlug = input?.projectSlug;
       const body = await request(`/operator/presence`, {
@@ -40135,7 +40190,7 @@ function startCodexProbe(deps = {}) {
 }
 
 // src/_generated/version.ts
-var PKG_VERSION = "0.4.0";
+var PKG_VERSION = "0.4.2";
 
 // src/api-base-url-migrate.ts
 var import_node_fs2 = __toESM(require("node:fs"), 1);
@@ -41260,7 +41315,7 @@ async function runConsensus(input) {
   let decision;
   for (let round = 1; round <= effectiveRounds; round++) {
     if (calls + input.heads.length > input.maxHeadCalls) {
-      return { outcome: "CONSENSUS_BLOCKED", rounds: round - 1, finalArtifact: artifact, history, ...decision ? { escalation: decision } : {} };
+      return { outcome: "CONSENSUS_BLOCKED", rounds: round - 1, finalArtifact: artifact, history, unresolved: history[history.length - 1]?.accepted ?? [], ...decision ? { escalation: decision } : {} };
     }
     const dismissedBlock = dismissedFwd.length ? `PREVIOUSLY DISMISSED (do not re-raise unless new information):
 ${dismissedFwd.slice(-20).join("\n")}` : "";
@@ -41282,7 +41337,7 @@ ${dismissedFwd.slice(-20).join("\n")}` : "";
       (r) => r.res.ok
     );
     if (responding.length === 0) {
-      return { outcome: "CONSENSUS_UNAVAILABLE", rounds: round, finalArtifact: artifact, history };
+      return { outcome: "CONSENSUS_UNAVAILABLE", rounds: round, finalArtifact: artifact, history, unresolved: [] };
     }
     const headOutcomes = input.heads.map((persona) => ({
       persona,
@@ -41308,7 +41363,7 @@ ${dismissedFwd.slice(-20).join("\n")}` : "";
     let adj;
     if (issues.length > 0) {
       if (calls + 1 > input.maxHeadCalls) {
-        return { outcome: "CONSENSUS_BLOCKED", rounds: round, finalArtifact: artifact, history, ...decision ? { escalation: decision } : {} };
+        return { outcome: "CONSENSUS_BLOCKED", rounds: round, finalArtifact: artifact, history, unresolved: history[history.length - 1]?.accepted ?? [], ...decision ? { escalation: decision } : {} };
       }
       calls++;
       try {
@@ -41322,7 +41377,7 @@ ${dismissedFwd.slice(-20).join("\n")}` : "";
     history.push({ round, accepted: adj.accepted, dismissed: adj.dismissed, headOutcomes });
     adj.dismissed.forEach((d) => dismissedFwd.push(`- ${d.id}: ${d.reason}`));
     if (adj.accepted.length === 0) {
-      return { outcome: "CONVERGED", rounds: round, finalArtifact: artifact, history, ...decision ? { escalation: decision } : {} };
+      return { outcome: "CONVERGED", rounds: round, finalArtifact: artifact, history, unresolved: [], ...decision ? { escalation: decision } : {} };
     }
     if (round === effectiveRounds) {
       if (!decision) {
@@ -41332,12 +41387,12 @@ ${dismissedFwd.slice(-20).join("\n")}` : "";
         escalated = true;
         effectiveRounds = Math.min(effectiveRounds + decision.grantedRounds, input.rounds * 2);
       } else {
-        return { outcome: "CONSENSUS_BLOCKED", rounds: round, finalArtifact: artifact, history, ...decision ? { escalation: decision } : {} };
+        return { outcome: "CONSENSUS_BLOCKED", rounds: round, finalArtifact: artifact, history, unresolved: history[history.length - 1]?.accepted ?? [], ...decision ? { escalation: decision } : {} };
       }
     }
     artifact = await input.revise(artifact, adj.accepted);
   }
-  return { outcome: "CONSENSUS_BLOCKED", rounds: effectiveRounds, finalArtifact: artifact, history };
+  return { outcome: "CONSENSUS_BLOCKED", rounds: effectiveRounds, finalArtifact: artifact, history, unresolved: history[history.length - 1]?.accepted ?? [] };
 }
 
 // src/consensus/spec-identity.ts
@@ -41636,7 +41691,8 @@ async function runSpecGate(_target, deps, opts) {
       outcome: "CONSENSUS_BLOCKED",
       ...keptClarifications.length > 0 ? { operatorClarifications: keptClarifications } : {},
       ...droppedByCap.length > 0 ? { droppedByCap } : {},
-      ...result.escalation ? { escalation: result.escalation } : {}
+      ...result.escalation ? { escalation: result.escalation } : {},
+      unresolved: result.unresolved
     };
   }
   return { outcome: result.outcome };
@@ -42946,7 +43002,7 @@ function onComplete(outcome, input) {
     }
     const taskRef = parsed.taskTitle ? `${input.taskId} \u2014 ${parsed.taskTitle}` : input.taskId;
     return {
-      kind: "info",
+      kind: "completed",
       taskId: input.taskId,
       body: `Spec drafted automatically for ${taskRef} \u2014 page ${parsed.pageId ?? "?"} in Specs/. The next scheduler tick will run the consensus review.`
     };
@@ -44006,6 +44062,10 @@ function executionTurnBudgetMessage(budgetMs) {
 function isExecutionTurnTimeoutReason(reason) {
   return reason.startsWith(EXECUTION_TURN_TIMEOUT_PREFIX) || reason.startsWith(EXECUTION_TURN_STALL_PREFIX);
 }
+function reportAutopilotLimitPause(client, reason, resetAt) {
+  void client.pauseAutopilotForLimit({ source: "provider_limit", reason, resetAt }).catch(() => {
+  });
+}
 function isDeliverableGateRetryableReason(reason) {
   return DELIVERABLE_GATE_RETRYABLE_REASON_PREFIXES.some((prefix) => reason.startsWith(prefix));
 }
@@ -44085,17 +44145,16 @@ var BASE_INSTRUCTIONS_PREFIX = [
   "  qualifies, produce the file; never merely offer one.",
   "- Mixed output counts as retrieved: if any material part came from a retrieval, treat the whole",
   "  result as retrieved rather than splitting it between inline text and a file.",
-  "- When your output is a file (markdown report, HTML, screenshot), upload it with",
-  "  `upload_artifact` and embed the returned markdown link \u2014 never inline large blobs",
-  "  into chat, spec, or note text.",
+  "- When your output is a file (markdown report, HTML), call `deliver_file`: pass the body inline",
+  "  as `content` and embed the returned markdown link. It needs no writable path, so it is the",
+  "  default even when this run path cannot write files \u2014 never inline large blobs into chat,",
+  "  spec, or note text.",
   "- class=temp for one-off operator hand-offs (48h); class=durable for anything a spec",
   "  or evidence page will reference (180 days). Always pass taskId/runId when known.",
-  "- Anything user-facing delivered as a file MUST be uploaded. Files are capped at 5MB \u2014",
-  "  split or summarize larger outputs.",
-  "- `upload_artifact` needs a real local file path, so it presupposes you can write one. When this",
-  "  run path CAN write files, produce the artifact normally \u2014 that is the default. ONLY when it",
-  "  cannot write, do NOT attempt the file: put the summary in your result text and state what a",
-  "  file would have held. Never fake a path you did not write.",
+  "- Anything user-facing delivered as a file MUST go through `deliver_file`. Files are capped at",
+  "  5MB \u2014 split or summarize larger outputs.",
+  "- Use `upload_artifact` only for a file already on disk (e.g. a screenshot the browser wrote);",
+  "  it needs a real local path, so never fake a path you did not write.",
   "",
   "Produced URLs \u2014 the operator's per-page links come only from you:",
   "- Call `record_produced_url` after publishing EACH web page this task produced, so the task UI",
@@ -44425,6 +44484,17 @@ async function driveTurn(deps, codex, projectSlug, runId, leaseId, threadId, inp
       }
       const usage = !notifThreadId || notifThreadId === threadId ? extractTurnTokenUsage(method, params) : null;
       if (usage) turnUsage = usage;
+      if (method === "account/rateLimits/updated") {
+        const snapshot = params?.rateLimits ?? null;
+        const signal = detectExhaustedProviderLimit(snapshot, Date.now());
+        if (signal) {
+          reportAutopilotLimitPause(
+            deps.client,
+            "Codex provider limit exhausted during an autonomous execution run.",
+            signal.resetAt
+          );
+        }
+      }
       const events = mapper.mapNotification(
         { method, params },
         threadId
@@ -51060,10 +51130,11 @@ function buildThreadStartParams(msg, config2, desiredModel) {
     "  treat the whole answer as retrieved rather than splitting it between chat and a file.",
     '- When it qualifies, PRODUCE the file. Offering one ("I can give you this as CSV/JSON") is the',
     "  failure, not the courtesy.",
-    "- When it is a file: write it (`.md` for linear prose, `.html` when structure or layout",
-    "  carries meaning), upload with `upload_artifact` (class=temp for one-off downloads,",
-    "  class=durable when a spec/evidence page references it; pass taskId when known), and paste",
-    "  the returned markdown link into your reply.",
+    "- When it is a file: choose the format (`.md` for linear prose, `.html` when structure or",
+    "  layout carries meaning), then call `deliver_file` \u2014 pass the body inline as `content` and it",
+    "  needs no local file (class=temp for one-off downloads, class=durable when a spec/evidence",
+    "  page references it; pass taskId when known), and paste the returned markdown link into your",
+    "  reply. Use `upload_artifact` only for a file that already exists on disk (e.g. a screenshot).",
     "- The chat reply must still stand alone as a complete answer even if the file is never opened:",
     "  the headline finding, the few points that matter, then the link. Never reduce it to",
     '  "see attached" or "details in the report".',
@@ -51300,6 +51371,10 @@ var DEFAULT_WORKTREE_RETENTION_HOURS = 48;
 function worktreeRetentionMs() {
   return readEnvInt("MRRLIN_DIRECTOR_WORKTREE_RETENTION_HOURS", DEFAULT_WORKTREE_RETENTION_HOURS) * 36e5;
 }
+function reportAutopilotLimitPause2(client, reason, resetAt) {
+  void client.pauseAutopilotForLimit({ source: "provider_limit", reason, resetAt }).catch(() => {
+  });
+}
 async function runOrphanWorktreeSweep(client, opts) {
   const cutoff = Date.now() - worktreeRetentionMs();
   const isReapable = (worktreePath) => {
@@ -52310,7 +52385,13 @@ function createBridgeMessageHandler(deps) {
             pokeActivity();
             if (method === "account/rateLimits/updated") {
               const snapshot = params?.rateLimits ?? null;
-              if (snapshot) sendInTurn({ type: "rateLimits", directorSessionId, rateLimits: snapshot });
+              if (snapshot) {
+                sendInTurn({ type: "rateLimits", directorSessionId, rateLimits: snapshot });
+                const signal = detectExhaustedProviderLimit(snapshot, Date.now());
+                if (signal) {
+                  deps.reportLimitPause?.("Codex provider limit exhausted during a Director turn.", signal.resetAt);
+                }
+              }
             }
             const events = mapper.mapNotification({ method, params }, threadId);
             for (const event of events) {
@@ -52412,6 +52493,10 @@ ${effectiveText}` : effectiveText;
               forward(event);
             }
             if (outputEvents === 0) {
+              deps.reportLimitPause?.(
+                "Director turn completed without output; Codex likely hit its usage or credits limit.",
+                null
+              );
               sendInTurn({
                 type: "error",
                 directorSessionId,
@@ -52909,6 +52994,7 @@ async function startDirectorBridge() {
     turnInactivity: () => ({ idleMs: chatTurnIdleMs(), maxMs: chatTurnMaxMs() }),
     checkoutRegistry,
     setCodexAuth: (s) => health.setCodexAuth(s),
+    reportLimitPause: (reason, resetAt) => reportAutopilotLimitPause2(client, reason, resetAt),
     getPairingQr: async () => {
       if (!relayConfigured || !remoteRelay) return { status: "not-configured" };
       const payload = remoteRelay.qrPayload;
@@ -57383,32 +57469,49 @@ var HUMANIZE_TEMPLATE_BY_KIND = {
   missing_requirement: "A required part of the task is still missing from the spec. What should it say?",
   acceptance_criteria_detail: "The direction is clear, but the spec still needs a sharper success check. What should count as done?"
 };
-var HUMANIZE_CONTEXT_CAP = 200;
-function truncateToSentenceBoundary(text, cap) {
-  if (text.length <= cap) return text;
-  const sentences = text.match(/.+?[.!?](?=\s|$)/g);
-  if (sentences) {
-    let kept = "";
-    let keptCount = 0;
-    for (const sentence of sentences) {
-      const candidate = kept ? `${kept} ${sentence.trim()}` : sentence.trim();
-      if (candidate.length > cap) break;
-      kept = candidate;
-      keptCount++;
-    }
-    if (kept) return keptCount < sentences.length ? `${kept} \u2026` : kept;
-  }
-  const cutIdx = text.lastIndexOf(" ", cap);
-  return text.slice(0, cutIdx > 0 ? cutIdx : cap).trim() + "\u2026";
-}
 function humanizeClarificationBody(clarification) {
   const prefix = HUMANIZE_TEMPLATE_BY_KIND[clarification.kind];
-  const context = truncateToSentenceBoundary(
-    clarification.rawQuestion.replace(/\b(?:parseable|SPEC_IDENTITY_MISMATCH|machine-usable)\b/gi, "").replace(/\s+/g, " ").trim(),
-    HUMANIZE_CONTEXT_CAP
-  );
+  const context = clarification.rawQuestion.replace(/\b(?:parseable|SPEC_IDENTITY_MISMATCH|machine-usable)\b/gi, "").replace(/\s+/g, " ").trim();
   return context ? `${prefix} ${context}` : prefix;
 }
+var BLOCK_DECISION_OPENER = "The reviewers could not agree on this spec";
+var BLOCK_BODY_TRAILER = " How should I proceed?";
+function renderUnresolvedPoints(unresolved) {
+  return unresolved.map(
+    (issue2) => issue2.text.replace(/\b(?:parseable|SPEC_IDENTITY_MISMATCH|machine-usable)\b/gi, "").replace(/\s+/g, " ").trim()
+  ).join("; ");
+}
+function renderBlockDecisionBody(taskRef, unresolved) {
+  if (unresolved.length === 0) {
+    return `${BLOCK_DECISION_OPENER} (task ${taskRef}), and their objections could not be read back.${BLOCK_BODY_TRAILER}`;
+  }
+  return `${BLOCK_DECISION_OPENER} (task ${taskRef}). Still unsettled: ${renderUnresolvedPoints(unresolved)}.${BLOCK_BODY_TRAILER}`;
+}
+function buildBlockDecisionOptions(diagnosis, reviewAgainAvailable) {
+  const recommendReviewAgain = reviewAgainAvailable && (diagnosis === "INFRA" || diagnosis === "SUBSTANCE");
+  const recommendEditSpec = !reviewAgainAvailable || diagnosis === "AMBIGUITY";
+  const options = [];
+  if (reviewAgainAvailable) {
+    options.push({
+      label: "Review again",
+      description: "Send the current spec back for another review.",
+      answer: REVIEW_AGAIN_ANSWER,
+      ...recommendReviewAgain ? { recommended: true } : {}
+    });
+  }
+  options.push({
+    label: "Edit spec",
+    description: "Open the spec and change it by hand; the review restarts on save.",
+    answer: EDIT_SPEC_ANSWER,
+    ...recommendEditSpec ? { recommended: true } : {}
+  });
+  options.push({
+    label: "Proceed anyway",
+    description: "Start the work with these points unsettled and recorded.",
+    answer: PROCEED_ANYWAY_ANSWER
+  });
+  return options;
+}
 var defaultNativeSpecGateBuilders = { buildSpecGateDeps, runSpecGate };
 async function runNativeSpecGate(ctx, input, builders = defaultNativeSpecGateBuilders) {
   const deps = builders.buildSpecGateDeps({
@@ -57455,6 +57558,7 @@ function stripHumanizeOpener(body) {
   }
   return body;
 }
+var DID_NOT_CONVERGE_ERROR = "Consensus blocked: reviewers did not converge within budget.";
 async function handleConsensusBlocked(result, ctx, input, resolvedTaskId) {
   const operatorClarifications = result.operatorClarifications ?? [];
   const diagnostics = result.diagnostics ?? [];
@@ -57462,9 +57566,10 @@ async function handleConsensusBlocked(result, ctx, input, resolvedTaskId) {
   const taskId = page?.taskId ?? null;
   if (!resolvedTaskId && taskId) resolvedTaskId = taskId;
   const adjudicated = [];
+  let taskInboxItems = [];
   if (taskId) {
     try {
-      const taskInboxItems = await ctx.client.listInboxItems(input.projectSlug, { taskId });
+      taskInboxItems = await ctx.client.listInboxItems(input.projectSlug, { taskId });
       for (const item of taskInboxItems) {
         if (item.origin === "gate" && (item.status === "acknowledged" || item.status === "rejected")) {
           adjudicated.push({ body: stripHumanizeOpener(item.body), answer: item.answer, status: item.status });
@@ -57533,6 +57638,35 @@ async function handleConsensusBlocked(result, ctx, input, resolvedTaskId) {
       filedQuestionCount = toFile.length;
     }
   }
+  if (filedQuestionCount === 0 && diagnostics.length === 0 && taskId && page) {
+    const domain2 = await resolveSpecDomain(ctx.client, input.projectSlug, {
+      id: page.id,
+      taskId: page.taskId ?? null
+    });
+    const reviewHash = domainScopedReviewHash2(page.contentHash, domain2);
+    const baseBlockItemId = `II-${taskId}-gateblock-${(0, import_node_crypto9.createHash)("sha256").update(reviewHash).digest("hex").slice(0, 10)}`;
+    let taskRef = taskId;
+    try {
+      const t = await ctx.client.getTask(input.projectSlug, taskId);
+      if (t?.title) taskRef = `${taskId} \u2014 ${t.title}`;
+    } catch {
+    }
+    const reviewAgainAvailable = !taskInboxItems.some(
+      (item) => item.id === baseBlockItemId && item.status !== "pending" && item.answer === REVIEW_AGAIN_ANSWER
+    );
+    const blockItemId = reviewAgainAvailable ? baseBlockItemId : `${baseBlockItemId}-2`;
+    try {
+      await ctx.client.createInboxItem(input.projectSlug, {
+        id: blockItemId,
+        kind: "question",
+        taskId,
+        body: renderBlockDecisionBody(taskRef, result.unresolved ?? []),
+        origin: "gate_block",
+        questionOptions: buildBlockDecisionOptions(result.escalation?.diagnosis, reviewAgainAvailable)
+      });
+    } catch {
+    }
+  }
   if (operatorClarifications.length > 0) {
     try {
       if (page) {
@@ -57573,7 +57707,7 @@ async function handleConsensusBlocked(result, ctx, input, resolvedTaskId) {
   } else if (operatorClarifications.length > 0) {
     error51 = `Consensus blocked on ${operatorClarifications.length} clarification(s), but the spec page is not linked to a task or plan, so none could be filed as questions.`;
   } else {
-    error51 = "Consensus blocked: reviewers did not converge within budget.";
+    error51 = DID_NOT_CONVERGE_ERROR;
   }
   if (result.escalation) {
     error51 += ` (diagnosis: ${result.escalation.diagnosis})`;
@@ -57701,7 +57835,7 @@ function onComplete2(outcome, input) {
       };
     }
     return {
-      kind: "info",
+      kind: "completed",
       ...taskId ? { taskId } : {},
       body: taskRef ? `Consensus CONVERGED for ${taskRef} (spec Specs/${input.pageId}); spec_ready set. Ready to create an execution run.` : `Consensus CONVERGED for Specs/${input.pageId}; spec_ready set. Ready to create an execution run.`
     };
@@ -57715,6 +57849,14 @@ function onComplete2(outcome, input) {
       body: taskRef ? `Consensus blocked on ${taskRef} (Specs/${input.pageId}); filed ${n} clarifying question${n === 1 ? "" : "s"} \u2014 answer to unblock the run.` : `Consensus blocked on Specs/${input.pageId}; filed ${n} clarifying question${n === 1 ? "" : "s"} \u2014 answer to unblock the run.`
     };
   }
+  if (outcome.kind === "failed" && outcome.error.startsWith(DID_NOT_CONVERGE_ERROR) && taskId) {
+    return {
+      kind: "info",
+      suppressInbox: true,
+      ...taskId ? { taskId } : {},
+      body: taskRef ? `Consensus blocked on ${taskRef} (Specs/${input.pageId}); the reviewers did not agree \u2014 answer the decision question to unblock the run.` : `Consensus blocked on Specs/${input.pageId}; the reviewers did not agree \u2014 answer the decision question to unblock the run.`
+    };
+  }
   const handoffTaskRef = taskRef ? ` (${taskRef})` : "";
   return {
     kind: "handoff",
@@ -57832,7 +57974,7 @@ function onComplete3(outcome, input) {
       };
     }
     return {
-      kind: "info",
+      kind: "completed",
       ...taskId ? { taskId } : {},
       body: taskRef ? `Deliverable consensus CONVERGED for ${taskRef} (Deliverables/${input.pageId}); it meets the acceptance criteria.` : `Deliverable consensus CONVERGED for Deliverables/${input.pageId}; it meets the acceptance criteria.`
     };
@@ -57955,6 +58097,7 @@ var mcpToolNames = {
   runSpecConsensus: "run_spec_consensus",
   runCodeReviewerGate: "run_code_reviewer_gate",
   uploadArtifact: "upload_artifact",
+  deliverFile: "deliver_file",
   listArtifactFiles: "list_artifact_files",
   reclaimExecutionRunLease: "reclaim_execution_run_lease",
   restartExecutionRun: "restart_execution_run",
@@ -58540,6 +58683,20 @@ var uploadArtifactInputSchema = projectScopedSchema.merge(
     description: external_exports.string().optional().describe("Shown in the run's artifact history; ignored when runId is not provided.")
   })
 );
+var deliverFileInputSchema = projectScopedSchema.merge(
+  external_exports.object({
+    filename: external_exports.string().min(1).describe(
+      "Bare filename with extension (e.g. 'notes.md'). No path separators or '..' allowed."
+    ),
+    content: external_exports.string().describe("UTF-8 text content of the file."),
+    class: mrrlinArtifactFileClassSchema.describe(
+      "temp = 48h one-off hand-off; durable = 180d, for spec/evidence references."
+    ),
+    taskId: mrrlinTaskIdSchema.optional(),
+    runId: mrrlinExecutionRunIdSchema.optional(),
+    description: external_exports.string().optional().describe("Shown in the run's artifact history; ignored when runId is not provided.")
+  })
+);
 var listArtifactFilesInputSchema = projectScopedSchema.merge(
   external_exports.object({
     taskId: mrrlinTaskIdSchema.optional(),
@@ -58625,6 +58782,7 @@ var mcpToolInputSchemas = {
   [mcpToolNames.createInboxItem]: createInboxItemInputSchema,
   [mcpToolNames.decideInboxItem]: decideInboxItemInputSchema,
   [mcpToolNames.uploadArtifact]: uploadArtifactInputSchema,
+  [mcpToolNames.deliverFile]: deliverFileInputSchema,
   [mcpToolNames.listArtifactFiles]: listArtifactFilesInputSchema,
   [mcpToolNames.reclaimExecutionRunLease]: reclaimExecutionRunLeaseInputSchema,
   [mcpToolNames.restartExecutionRun]: restartExecutionRunInputSchema,
@@ -58762,6 +58920,7 @@ var mcpToolDescriptions = {
   [mcpToolNames.createInboxItem]: "Create an operator-inbox item (proposal, check_in, question, handoff, or info) for a project.",
   [mcpToolNames.decideInboxItem]: "Approve, reject, or acknowledge an operator-inbox item. Rejection requires a reason.",
   [mcpToolNames.uploadArtifact]: "Upload a local file (md/txt/html/csv/json/pdf/png/jpg/webp/gif, <=5MB) as a project artifact. Returns a stable markdown link to embed in chat/spec/handoff text. Use class=temp for one-off hand-offs, class=durable for anything referenced by specs or evidence. Pass runId to record the file in that run's artifact history; pass taskId to surface it on the task's Artifacts list.",
+  [mcpToolNames.deliverFile]: "This is the DEFAULT way to deliver a file the agent just composed; it takes the body inline as UTF-8 `content` in one call and needs no local file or writable path; `upload_artifact` is for a file that already exists on disk; use class=temp / class=durable and taskId/runId semantics with a 5MB cap.",
   [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.",
@@ -58908,6 +59067,68 @@ function makeReadTool(client, name, fallbackCode, fallbackMessage, handler, proj
 }
 function createMrrlinTools(options) {
   const client = createMrrlinClient(withAuth(options));
+  async function uploadArtifactBytes(c, args) {
+    const { bytes: bytes3, class: artifactClass, contentType, description, filename, projectSlug, runId, taskId } = args;
+    const created = await c.createArtifactFile(projectSlug, {
+      class: artifactClass,
+      contentType,
+      filename,
+      runId,
+      sizeBytes: bytes3.byteLength,
+      taskId
+    });
+    let stage = "upload";
+    try {
+      if (created.upload.kind === "presigned-post") {
+        const form = new FormData();
+        for (const [field, value] of Object.entries(created.upload.fields)) {
+          form.append(field, value);
+        }
+        form.append("file", new Blob([bytes3], { type: contentType }), filename);
+        const bareFetch = options.fetch ?? globalThis.fetch;
+        const uploadResponse = await bareFetch(created.upload.url, { body: form, method: "POST" });
+        if (!uploadResponse.ok) {
+          throw new Error(
+            `Presigned upload failed: ${uploadResponse.status} ${await uploadResponse.text()}`
+          );
+        }
+      } else {
+        await c.uploadArtifactFileContent(projectSlug, created.artifact.id, bytes3, contentType);
+      }
+      stage = "complete";
+      const completed = await c.completeArtifactFile(projectSlug, created.artifact.id);
+      if (completed.runId) {
+        stage = "append-run-artifact";
+        await c.appendExecutionArtifact(projectSlug, completed.runId, {
+          id: `EA-${completed.id}`,
+          kind: "file",
+          payload: {
+            artifactFileId: completed.id,
+            class: completed.class,
+            contentType: completed.contentType,
+            description: description ?? null,
+            filename: completed.filename,
+            sizeBytes: completed.sizeBytes,
+            stableUrl: created.stableUrl
+          }
+        });
+      }
+      const markdown = contentType.startsWith("image/") ? `![${completed.filename}](${created.stableUrl})` : `[${completed.filename}](${created.stableUrl})`;
+      return {
+        artifactFile: completed,
+        markdown,
+        stableUrl: created.stableUrl
+      };
+    } catch (error51) {
+      const original = error51 instanceof MrrlinApiError ? error51.code : error51 instanceof McpToolCodedError ? error51.code : "ARTIFACT_FILE_UPLOAD_FAILED";
+      const message = error51 instanceof Error ? error51.message : String(error51);
+      const note = stage === "append-run-artifact" ? "file uploaded and completed successfully; only the run-history append failed \u2014 do NOT re-upload, reference the stableUrl directly" : "a pending row may remain; it is reaped automatically after 1h";
+      throw new McpToolCodedError(
+        original,
+        `artifactFileId=${created.artifact.id} stableUrl=${created.stableUrl} (failed at ${stage}; ${note}): ${message}`
+      );
+    }
+  }
   return {
     [mcpToolNames.archivePlan]: makeTool(
       client,
@@ -59475,65 +59696,61 @@ function createMrrlinTools(options) {
           );
         }
         const filename = import_node_path20.default.basename(filePath);
-        const created = await c.createArtifactFile(projectSlug, {
+        return uploadArtifactBytes(c, {
+          bytes: bytes3,
           class: artifactClass,
           contentType,
+          description,
           filename,
+          projectSlug,
           runId,
-          sizeBytes: bytes3.byteLength,
           taskId
         });
-        let stage = "upload";
-        try {
-          if (created.upload.kind === "presigned-post") {
-            const form = new FormData();
-            for (const [field, value] of Object.entries(created.upload.fields)) {
-              form.append(field, value);
-            }
-            form.append("file", new Blob([bytes3], { type: contentType }), filename);
-            const bareFetch = options.fetch ?? globalThis.fetch;
-            const uploadResponse = await bareFetch(created.upload.url, { body: form, method: "POST" });
-            if (!uploadResponse.ok) {
-              throw new Error(
-                `Presigned upload failed: ${uploadResponse.status} ${await uploadResponse.text()}`
-              );
-            }
-          } else {
-            await c.uploadArtifactFileContent(projectSlug, created.artifact.id, bytes3, contentType);
-          }
-          stage = "complete";
-          const completed = await c.completeArtifactFile(projectSlug, created.artifact.id);
-          if (completed.runId) {
-            stage = "append-run-artifact";
-            await c.appendExecutionArtifact(projectSlug, completed.runId, {
-              id: `EA-${completed.id}`,
-              kind: "file",
-              payload: {
-                artifactFileId: completed.id,
-                class: completed.class,
-                contentType: completed.contentType,
-                description: description ?? null,
-                filename: completed.filename,
-                sizeBytes: completed.sizeBytes,
-                stableUrl: created.stableUrl
-              }
-            });
-          }
-          const markdown = contentType.startsWith("image/") ? `![${completed.filename}](${created.stableUrl})` : `[${completed.filename}](${created.stableUrl})`;
-          return {
-            artifactFile: completed,
-            markdown,
-            stableUrl: created.stableUrl
-          };
-        } catch (error51) {
-          const original = error51 instanceof MrrlinApiError ? error51.code : error51 instanceof McpToolCodedError ? error51.code : "ARTIFACT_FILE_UPLOAD_FAILED";
-          const message = error51 instanceof Error ? error51.message : String(error51);
-          const note = stage === "append-run-artifact" ? "file uploaded and completed successfully; only the run-history append failed \u2014 do NOT re-upload, reference the stableUrl directly" : "a pending row may remain; it is reaped automatically after 1h";
+      }
+    ),
+    [mcpToolNames.deliverFile]: makeTool(
+      client,
+      mcpToolNames.deliverFile,
+      "ARTIFACT_FILE_UPLOAD_FAILED",
+      "Unable to deliver artifact file.",
+      async (c, { projectSlug, filename, content, class: artifactClass, taskId, runId, description }) => {
+        if (filename.includes("/") || filename.includes("\\") || filename.includes("..")) {
+          throw new McpToolCodedError(
+            "ARTIFACT_FILE_NAME_INVALID",
+            `Invalid filename '${filename}'; provide a bare filename with no path separators or '..'.`
+          );
+        }
+        const extension2 = import_node_path20.default.extname(filename).toLowerCase();
+        const contentType = ARTIFACT_EXTENSION_TYPES[extension2];
+        if (!contentType) {
           throw new McpToolCodedError(
-            original,
-            `artifactFileId=${created.artifact.id} stableUrl=${created.stableUrl} (failed at ${stage}; ${note}): ${message}`
+            "ARTIFACT_FILE_TYPE_UNSUPPORTED",
+            `Unsupported artifact extension '${extension2}'. Allowed: ${Object.keys(ARTIFACT_EXTENSION_TYPES).join(", ")}.`
           );
         }
+        const bytes3 = new Uint8Array(Buffer.from(content, "utf8"));
+        if (bytes3.byteLength === 0) {
+          throw new McpToolCodedError(
+            "ARTIFACT_FILE_EMPTY",
+            "File is empty (0 bytes); write content before uploading."
+          );
+        }
+        if (bytes3.byteLength > MRRLIN_ARTIFACT_FILE_MAX_BYTES) {
+          throw new McpToolCodedError(
+            "ARTIFACT_FILE_TOO_LARGE",
+            "Artifact exceeds 5MB; split or summarize instead."
+          );
+        }
+        return uploadArtifactBytes(c, {
+          bytes: bytes3,
+          class: artifactClass,
+          contentType,
+          description,
+          filename,
+          projectSlug,
+          runId,
+          taskId
+        });
       }
     ),
     [mcpToolNames.listArtifactFiles]: makeTool(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrrlin-dev/mcp",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "type": "module",
   "bin": {
     "mrrlin-mcp": "dist/bin.cjs"
@@ -23,10 +23,10 @@
     "tsx": "^4.22.3",
     "@mrrlin/client": "0.0.0",
     "@mrrlin/codex-client": "0.0.0",
-    "@mrrlin/director-e2e": "0.0.0",
-    "@mrrlin/schemas": "0.0.0",
     "@mrrlin/tsconfig": "0.0.0",
-    "@mrrlin/wiki": "0.0.0"
+    "@mrrlin/wiki": "0.0.0",
+    "@mrrlin/schemas": "0.0.0",
+    "@mrrlin/director-e2e": "0.0.0"
   },
   "dependencies": {
     "@iarna/toml": "^2.2.5",
@@ -47,7 +47,7 @@
     "dev": "tsx watch src/bin.ts serve",
     "lint": "eslint .",
     "start": "node dist/bin.cjs serve",
-    "test": "node scripts/write-version.mjs && node --import tsx --test $(find src -name '*.test.ts' | sort | tr '\\n' ' ')",
+    "test": "pnpm --filter @mrrlin/codex-client build && node scripts/write-version.mjs && node --import tsx --test $(find src -name '*.test.ts' | sort | tr '\\n' ' ')",
     "typecheck": "node scripts/write-version.mjs && pnpm --filter @mrrlin/schemas build && pnpm --filter @mrrlin/client build && pnpm --filter @mrrlin/wiki build && pnpm --filter @mrrlin/codex-client build && pnpm --filter @mrrlin/director-e2e build && tsc -p tsconfig.json --noEmit"
   }
 }