@mrrlin-dev/mcp 0.3.13 → 0.3.15

package/README.md

@@ -10,7 +10,8 @@ The bridge auto-picks up new `@mrrlin-dev/mcp` versions after `npm install -g`.
 
 - **L1 (self-update loop):** every 15 minutes (env-tunable) the bridge hashes its own `bin.cjs` and, on change, drains the current Codex turn cleanly and exits via `bridgeShutdown`. PM2 restarts. New code loads.
 - **L2 (postinstall nudge):** `npm install -g @mrrlin-dev/mcp@latest` triggers a `SIGUSR2` to every running PM2 bridge, collapsing the L1 wait to seconds.
-- **L3 (in-chat update offer):** every 6 hours the bridge checks `https://registry.npmjs.org/@mrrlin-dev/mcp/latest`. When a newer version is published, on your next chat turn the Director asks: *"Бачу що bridge на X, на npm уже Y — оновити зараз?"*. Say "yes" → Director runs `npm install -g @mrrlin-dev/mcp@latest` itself. 48h cooldown if you decline.
+- **L3 (in-chat update offer):** every 6 hours the bridge checks `https://registry.npmjs.org/@mrrlin-dev/mcp/latest`. When a newer version is published, on your next chat turn the Director explains *why* to update (latest fixes/improvements, changelog link) and offers a choice — let it run the update, or run `npm install -g @mrrlin-dev/mcp@latest` yourself. Say "yes" → Director runs the install itself. 48h cooldown if you decline.
+- **L3.3 (inbox mirror):** the same fire also files a persistent `question` in the active project's inbox ("A newer version of the mrrlin bridge is available…", with the changelog link), so the update isn't only an ephemeral per-turn aside. The body is version-agnostic on purpose: the inbox dedup collapses it to one open row per project (reused across versions), and it re-appears at most once per 48h cooldown after you decide it. It's an opportunistic per-project signal, not a guaranteed cross-project notice.
 - **L4 (process hygiene):** the bridge refuses to start a second instance on the same port and warns about orphan `mrrlin-mcp director-bridge` processes at startup.
 
 ### Env tuning

package/dist/bin.cjs

@@ -20799,9 +20799,8 @@ function renderBlock(block) {
   lines2.push("");
   return lines2.join("\n");
 }
-function tablesEqual(actual, expected) {
-  if (typeof actual !== "object" || actual === null) return false;
-  const candidate = actual;
+var KNOWN_MRRLIN_ENV_KEYS = /* @__PURE__ */ new Set(["MRRLIN_STAGING", "MRRLIN_API_BASE_URL", "MRRLIN_API_ALLOW_REMOTE"]);
+function commandArgsTimeoutEqual(candidate, expected) {
   if (candidate.command !== expected.command) return false;
   if (!Array.isArray(candidate.args)) return false;
   if (candidate.args.length !== expected.args.length) return false;
@@ -20811,6 +20810,12 @@ function tablesEqual(actual, expected) {
   if (candidate.startup_timeout_sec !== void 0 && candidate.startup_timeout_sec !== expected.startup_timeout_sec) {
     return false;
   }
+  return true;
+}
+function tablesEqual(actual, expected) {
+  if (typeof actual !== "object" || actual === null) return false;
+  const candidate = actual;
+  if (!commandArgsTimeoutEqual(candidate, expected)) return false;
   const expectedEnv = expected.env ?? {};
   const actualEnv = candidate.env && typeof candidate.env === "object" ? candidate.env : {};
   const expectedKeys = Object.keys(expectedEnv);
@@ -20820,6 +20825,34 @@ function tablesEqual(actual, expected) {
   }
   return true;
 }
+function isCoherentMrrlinEnv(env) {
+  const keys = Object.keys(env);
+  const staging = env.MRRLIN_STAGING;
+  const url2 = env.MRRLIN_API_BASE_URL;
+  const allowRemote = env.MRRLIN_API_ALLOW_REMOTE;
+  const hasUrl = typeof url2 === "string" && url2.trim() !== "";
+  if (keys.length === 1 && staging === "1") return true;
+  if (keys.length === 1 && hasUrl) return true;
+  if (keys.length === 2 && hasUrl && allowRemote === "1") return true;
+  return false;
+}
+function classifyExistingBlock(actual, expected) {
+  if (tablesEqual(actual, expected)) return "equal";
+  if (typeof actual !== "object" || actual === null) return "conflict";
+  const candidate = actual;
+  if (expected.env && Object.keys(expected.env).length > 0) return "conflict";
+  if (!commandArgsTimeoutEqual(candidate, expected)) return "conflict";
+  const env = candidate.env && typeof candidate.env === "object" ? candidate.env : {};
+  const keys = Object.keys(env);
+  if (keys.length === 0) return "conflict";
+  if (!keys.every((key) => KNOWN_MRRLIN_ENV_KEYS.has(key))) return "conflict";
+  if (!isCoherentMrrlinEnv(env)) return "conflict";
+  return "preserve-env-noop";
+}
+function renderEnvPreservedNotice(blockId, envKeys) {
+  const keys = [...envKeys].sort().join(", ");
+  return `[mrrlin-mcp install-codex] kept your existing [mcp_servers.${blockId}] env keys (${keys}) so your API target is preserved. Re-run with --force to replace or remove it.`;
+}
 async function pathExists(target) {
   try {
     await import_promises.default.access(target);
@@ -20845,7 +20878,7 @@ async function installCodex(options) {
   if (!await pathExists(configPath)) {
     const content2 = blocks.map(renderBlock).join("").replace(/^\n/, "");
     await import_promises.default.writeFile(configPath, content2, { mode: 384 });
-    return { action: "created", configPath, prompts: await writePrompts() };
+    return { action: "created", configPath, prompts: await writePrompts(), preservedEnvBlocks: [] };
   }
   const realPath = await resolveRealConfigPath(configPath);
   let content = await import_promises.default.readFile(realPath, "utf8");
@@ -20862,10 +20895,19 @@ async function installCodex(options) {
     throw Object.assign(new Error(err.detail), err);
   }
   let action = "noop";
+  let mutated = false;
+  const preservedEnvBlocks = [];
   for (const block of blocks) {
     const existingTable = parsed?.mcp_servers?.[block.id];
     if (existingTable !== void 0) {
-      if (tablesEqual(existingTable, block.expected)) continue;
+      const classification = classifyExistingBlock(existingTable, block.expected);
+      if (classification === "equal") continue;
+      if (classification === "preserve-env-noop") {
+        const env = existingTable.env ?? {};
+        preservedEnvBlocks.push({ blockId: block.id, envKeys: Object.keys(env).sort() });
+        if (action === "noop") action = "env-preserved";
+        continue;
+      }
       if (!options.force) {
         const err = {
           code: "CODEX_CONFIG_CONFLICT",
@@ -20876,15 +20918,17 @@ async function installCodex(options) {
       }
       content = replaceBlock(content, block.blockRe, renderBlock(block));
       action = "replaced";
+      mutated = true;
     } else {
       content = appendBlock(content, renderBlock(block));
       if (action !== "replaced") action = "appended";
+      mutated = true;
     }
   }
-  if (action !== "noop") {
+  if (mutated) {
     await import_promises.default.writeFile(realPath, content, { mode: 384 });
   }
-  return { action, configPath: realPath, prompts: await writePrompts() };
+  return { action, configPath: realPath, prompts: await writePrompts(), preservedEnvBlocks };
 }
 async function installPrompts(codexHome, prompts, forcePrompts) {
   if (prompts.length === 0) return [];
@@ -38336,6 +38380,7 @@ var DEFAULT_STARTUP_JITTER_MS = 30 * 1e3;
 var DEFAULT_COOLDOWN_MS = 48 * 60 * 60 * 1e3;
 var REGISTRY_URL_DEFAULT = "https://registry.npmjs.org/@mrrlin-dev/mcp/latest";
 var STRICT_SEMVER = /^\d+\.\d+\.\d+(-[A-Za-z0-9.-]+)?(\+[A-Za-z0-9.-]+)?$/;
+var UPDATE_INBOX_BODY = "A newer version of the mrrlin bridge is available. Updating pulls the latest fixes and improvements. Changelog: https://mrrlin-changelog.s3.eu-central-1.amazonaws.com/index.html . Ask the Director to update, or run `npm install -g @mrrlin-dev/mcp@latest` yourself.";
 function isDisabled() {
   return process.env.MRRLIN_DIRECTOR_BRIDGE_SELF_UPDATE === "0";
 }
@@ -38382,9 +38427,15 @@ function startSelfUpdate(deps) {
     });
     return `[bridge:update] An update for @mrrlin-dev/mcp is available: ${pkgVersion} -> ${latestVersion}.
 
-This turn, at a natural pause, ASK the operator a yes/no question IN THE OPERATOR'S LANGUAGE (mirror the language they are chatting in) - e.g. in English: "The bridge is on ${pkgVersion} but npm already has ${latestVersion} - update now? (I'll run \`npm install -g @mrrlin-dev/mcp@latest\`)". Do NOT install without explicit confirmation.
+This turn, at a natural pause, RAISE this with the operator IN THEIR LANGUAGE (mirror the language they are chatting in). Frame it as a short offer with a choice, and ALWAYS explain WHY it is worth doing:
 
-If the operator confirms: immediately run \`npm install -g @mrrlin-dev/mcp@latest\` via your shell tool and report the outcome in chat. After a successful install, the bridge auto-restarts via its self-update loop within a couple of minutes - you do NOT need to call pm2.
+1. WHY (never skip this): give a one-line reason the update matters - do NOT present a bare version bump. Prefer specifics: if you can read the release notes, summarize in one short sentence what is new/fixed. The changelog is at https://mrrlin-changelog.s3.eu-central-1.amazonaws.com/index.html. If you cannot get specifics, fall back to a generic but honest reason, e.g. "it pulls the latest bug fixes and improvements for the bridge".
+
+2. THE CHOICE: offer both paths and let the operator pick - "want me to update it for you now?" OR "you can run it yourself: \`npm install -g @mrrlin-dev/mcp@latest\`". Phrase it as a yes/no, e.g. in English: "The bridge is on ${pkgVersion} but npm already has ${latestVersion}. It brings <why> - want me to run \`npm install -g @mrrlin-dev/mcp@latest\`, or would you rather run it yourself?".
+
+ASK the operator first - do NOT install without explicit confirmation.
+
+If the operator confirms you should do it: immediately run \`npm install -g @mrrlin-dev/mcp@latest\` via your shell tool and report the outcome in chat. After a successful install, the bridge auto-restarts via its self-update loop within a couple of minutes - you do NOT need to call pm2.
 
 If the operator declines / says "later": acknowledge briefly and do not bring it up again this turn. The bridge has a cooldown and will re-offer in 48h.
 
@@ -38392,6 +38443,12 @@ If the install fails (permission denied, registry pinned, sudo required, network
 
 Do NOT derail the current task - if the operator has an in-flight question, answer that first; the update offer is a brief aside, not the main subject.`;
   }
+  function updateInboxBody() {
+    if (disabled) return null;
+    if (latestVersion === null) return null;
+    if (!import_semver.default.gt(latestVersion, pkgVersion)) return null;
+    return UPDATE_INBOX_BODY;
+  }
   let startupBinSha = null;
   try {
     startupBinSha = sha256(readFile2(deps.binPath));
@@ -38545,12 +38602,13 @@ Do NOT derail the current task - if the operator has an in-flight question, answ
     getDrainOnQuiet: () => drainOnQuiet,
     getLatestVersion: () => latestVersion,
     isStale: () => latestVersion !== null && import_semver.default.gt(latestVersion, pkgVersion),
-    maybeUpdateOffer
+    maybeUpdateOffer,
+    updateInboxBody
   };
 }
 
 // src/_generated/version.ts
-var PKG_VERSION = "0.3.13";
+var PKG_VERSION = "0.3.15";
 
 // src/api-base-url.ts
 var DEFAULT_API_BASE_URL = "http://127.0.0.1:8787";
@@ -38764,10 +38822,42 @@ function withTimeout(promise2, ms, message) {
   });
 }
 async function awaitTurnWithDeadline(opts) {
+  const hasIdle = opts.idleTimeoutMs != null && opts.idleTimeoutMessage != null;
+  const overallDeadlineAt = Date.now() + opts.timeoutMs;
+  let overallTimer = null;
+  let idleTimer = null;
+  let settled = false;
+  const clearTimers = () => {
+    settled = true;
+    if (overallTimer) clearTimeout(overallTimer);
+    if (idleTimer) clearTimeout(idleTimer);
+    overallTimer = null;
+    idleTimer = null;
+  };
+  const activity = { touch: () => {
+  } };
+  const idleTimeoutMs = opts.idleTimeoutMs;
+  const idleTimeoutMessage = opts.idleTimeoutMessage;
+  const deadline = new Promise((_, reject) => {
+    overallTimer = setTimeout(() => reject(new Error(opts.timeoutMessage)), opts.timeoutMs);
+    if (idleTimeoutMs != null && idleTimeoutMessage != null) {
+      const armIdle = () => {
+        if (settled) return;
+        if (idleTimer) clearTimeout(idleTimer);
+        idleTimer = setTimeout(() => {
+          reject(new Error(Date.now() >= overallDeadlineAt ? opts.timeoutMessage : idleTimeoutMessage));
+        }, idleTimeoutMs);
+      };
+      activity.touch = armIdle;
+      armIdle();
+    }
+  });
   try {
-    await withTimeout(opts.run(), opts.timeoutMs, opts.timeoutMessage);
+    await Promise.race([opts.run(activity), deadline]);
   } catch (error51) {
-    const isDeadline = error51 instanceof Error && error51.message === opts.timeoutMessage;
+    clearTimers();
+    const message = error51 instanceof Error ? error51.message : String(error51);
+    const isDeadline = message === opts.timeoutMessage || hasIdle && message === opts.idleTimeoutMessage;
     if (isDeadline) {
       try {
         await withTimeout(
@@ -38781,6 +38871,7 @@ async function awaitTurnWithDeadline(opts) {
     }
     throw error51;
   }
+  clearTimers();
 }
 
 // src/worktree.ts
@@ -38973,16 +39064,41 @@ ${lines2.join("\n")}`;
 var DEFAULT_STALE_SECONDS = 300;
 var DEFAULT_TOUCH_INTERVAL_MS = 6e4;
 var DEFAULT_CLAIM_INTERVAL_SECONDS = 30;
-var DEFAULT_EXEC_TURN_TIMEOUT_SECONDS = 900;
+var DEFAULT_EXEC_TURN_IDLE_TIMEOUT_SECONDS = 600;
+var DEFAULT_EXEC_RUN_MAX_SECONDS = 3600;
 var DEFAULT_CONTEXT_MAX_ARTIFACTS = 50;
+var EXECUTION_TURN_TIMEOUT_PREFIX = "Execution turn did not complete within";
+var EXECUTION_TURN_STALL_PREFIX = "Execution turn stalled: no Codex activity within";
+var EXECUTION_TURN_BUDGET_PREFIX = "Execution turn exceeded the run wall-clock budget";
+var EXECUTION_TURN_TIMEOUT_RETRY_CODE = "execution_turn_timeout_retry";
+var EXECUTION_TURN_TIMEOUT_RETRY_SUMMARY = "Execution turn timed out; requeued for one automatic retry.";
+var EXECUTION_TURN_TIMEOUT_RETRY_CURSOR = "execution_turn_timeout_retry:1";
 function readPositiveIntEnv(name, fallback) {
   const raw = (process.env[name] ?? "").trim();
   if (!raw) return fallback;
   const parsed = Number.parseInt(raw, 10);
   return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback;
 }
-function execTurnTimeoutMs() {
-  return readPositiveIntEnv("MRRLIN_DIRECTOR_BRIDGE_EXEC_TURN_TIMEOUT_SECONDS", DEFAULT_EXEC_TURN_TIMEOUT_SECONDS) * 1e3;
+function execTurnIdleTimeoutMs() {
+  return readPositiveIntEnv("MRRLIN_DIRECTOR_BRIDGE_EXEC_TURN_IDLE_TIMEOUT_SECONDS", DEFAULT_EXEC_TURN_IDLE_TIMEOUT_SECONDS) * 1e3;
+}
+function execRunMaxMs() {
+  return readPositiveIntEnv("MRRLIN_DIRECTOR_BRIDGE_EXEC_RUN_MAX_SECONDS", DEFAULT_EXEC_RUN_MAX_SECONDS) * 1e3;
+}
+function explicitLegacyTurnTimeoutMs() {
+  const raw = (process.env.MRRLIN_DIRECTOR_BRIDGE_EXEC_TURN_TIMEOUT_SECONDS ?? "").trim();
+  if (!raw) return null;
+  const parsed = Number.parseInt(raw, 10);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed * 1e3 : null;
+}
+function executionTurnStallMessage(idleMs) {
+  return `${EXECUTION_TURN_STALL_PREFIX} ${idleMs}ms.`;
+}
+function executionTurnBudgetMessage(budgetMs) {
+  return `${EXECUTION_TURN_BUDGET_PREFIX} (${budgetMs}ms).`;
+}
+function isExecutionTurnTimeoutReason(reason) {
+  return reason.startsWith(EXECUTION_TURN_TIMEOUT_PREFIX) || reason.startsWith(EXECUTION_TURN_STALL_PREFIX);
 }
 function contextMaxArtifacts() {
   return readPositiveIntEnv("MRRLIN_DIRECTOR_BRIDGE_CONTEXT_MAX_ARTIFACTS", DEFAULT_CONTEXT_MAX_ARTIFACTS);
@@ -39135,11 +39251,15 @@ async function runHasLease(deps, projectSlug, runId, leaseId) {
     return false;
   }
 }
-async function driveTurn(deps, codex, projectSlug, runId, leaseId, threadId, inputText) {
+async function driveTurn(deps, codex, projectSlug, runId, leaseId, threadId, inputText, overallMs, phase) {
   const mapper = new CodexBridgeEventMapper();
   mapper.reset();
   let turnError = null;
   let interruptFailed = false;
+  let touch = () => {
+  };
+  const turnStartedAt = Date.now();
+  let lastActivityAt = turnStartedAt;
   const persist = async (event) => {
     if (event.type === "error") turnError = event.content;
     const kind = artifactKindForEvent(event);
@@ -39161,6 +39281,11 @@ async function driveTurn(deps, codex, projectSlug, runId, leaseId, threadId, inp
     });
     let acceptedTurnId = null;
     const unsub = codex.onNotification((method, params) => {
+      const notifThreadId = params?.threadId;
+      if (!notifThreadId || notifThreadId === threadId) {
+        lastActivityAt = Date.now();
+        touch();
+      }
       const events = mapper.mapNotification(
         { method, params },
         threadId
@@ -39168,9 +39293,8 @@ async function driveTurn(deps, codex, projectSlug, runId, leaseId, threadId, inp
       for (const event of events) pending.push(persist(event));
       if (method === "turn/completed") {
         const p = params;
-        const notifThreadId = p?.threadId;
         const notifTurnId = p?.turn?.id;
-        const threadMatches = !notifThreadId || notifThreadId === threadId;
+        const threadMatches = !p?.threadId || p.threadId === threadId;
         const turnMatches = !acceptedTurnId || !notifTurnId || notifTurnId === acceptedTurnId;
         if (threadMatches && turnMatches) resolveTurnEnded?.();
       }
@@ -39180,10 +39304,11 @@ async function driveTurn(deps, codex, projectSlug, runId, leaseId, threadId, inp
       });
     }, deps.touchIntervalMs);
     touchTimer.unref?.();
+    const idleMs = execTurnIdleTimeoutMs();
     try {
-      const timeoutMs = execTurnTimeoutMs();
       await awaitTurnWithDeadline({
-        run: async () => {
+        run: async (activity) => {
+          touch = activity.touch;
           const accepted = await codex.turn.start({
             threadId,
             input: [{ type: "text", text: inputText }]
@@ -39192,8 +39317,10 @@ async function driveTurn(deps, codex, projectSlug, runId, leaseId, threadId, inp
           await turnEnded;
         },
         interrupt: () => codex.turn.interrupt({ threadId }),
-        timeoutMs,
-        timeoutMessage: `Execution turn did not complete within ${timeoutMs}ms.`,
+        timeoutMs: overallMs,
+        timeoutMessage: executionTurnBudgetMessage(overallMs),
+        idleTimeoutMs: idleMs,
+        idleTimeoutMessage: executionTurnStallMessage(idleMs),
         onInterruptFailed: () => {
           interruptFailed = true;
         }
@@ -39202,6 +39329,19 @@ async function driveTurn(deps, codex, projectSlug, runId, leaseId, threadId, inp
       await Promise.all(pending);
     } catch (error51) {
       turnError = error51 instanceof Error ? error51.message : String(error51);
+      if (turnError.startsWith(EXECUTION_TURN_STALL_PREFIX) || turnError.startsWith(EXECUTION_TURN_BUDGET_PREFIX)) {
+        console.warn(
+          JSON.stringify({
+            event: "execution_turn_deadline",
+            projectSlug,
+            runId,
+            phase,
+            kind: turnError.startsWith(EXECUTION_TURN_BUDGET_PREFIX) ? "budget" : "stall",
+            elapsedMs: Date.now() - turnStartedAt,
+            sinceLastActivityMs: Date.now() - lastActivityAt
+          })
+        );
+      }
     } finally {
       clearInterval(touchTimer);
       unsub();
@@ -39223,6 +39363,12 @@ async function driveRun(deps, projectSlug, runId) {
     return;
   }
   const leaseId = claimed.leaseId;
+  const attemptDeadlineMs = Date.now() + execRunMaxMs();
+  const remainingTurnBudgetMs = () => {
+    const remaining = attemptDeadlineMs - Date.now();
+    const legacy = explicitLegacyTurnTimeoutMs();
+    return legacy != null ? Math.min(legacy, remaining) : remaining;
+  };
   const task = await deps.client.getTask(projectSlug, claimed.taskId);
   const compactEnabled = (process.env.MRRLIN_MCP_COMPACT_DISABLE ?? "").trim() !== "1";
   const context = await gatherContext(deps.client, projectSlug, task, runId);
@@ -39260,6 +39406,7 @@ async function driveRun(deps, projectSlug, runId) {
         runId,
         defaultBranch: await getDefaultBranch(projectSlug)
       });
+      if (!await runHasLease(deps, projectSlug, runId, leaseId)) return;
       await deps.client.updateExecutionRun(projectSlug, runId, {
         worktreeId: worktreePath,
         branch: worktreeBranch(runId)
@@ -39310,11 +39457,17 @@ async function driveRun(deps, projectSlug, runId) {
         ephemeral: null
       },
       onThreadIdChanged: async (newId) => {
+        if (!await runHasLease(deps, projectSlug, runId, leaseId)) return;
         await deps.client.updateTask(projectSlug, task.id, { directorThreadId: newId });
       }
     });
     if (!resumed) {
-      const primed = await driveTurn(deps, codex, projectSlug, runId, leaseId, threadId, bundle);
+      const primingBudgetMs = remainingTurnBudgetMs();
+      if (primingBudgetMs <= 0) {
+        await failRun(deps, projectSlug, task, runId, leaseId, executionTurnBudgetMessage(execRunMaxMs()));
+        return;
+      }
+      const primed = await driveTurn(deps, codex, projectSlug, runId, leaseId, threadId, bundle, primingBudgetMs, "priming");
       if (!primed.ok) {
         await resetWedgedThread(deps, projectSlug, task.id, primed.interruptFailed);
         await failRun(deps, projectSlug, task, runId, leaseId, primed.error);
@@ -39324,7 +39477,12 @@ async function driveRun(deps, projectSlug, runId) {
     const executionPrompt = resumed ? `${bundle}
 
 Continue executing task ${task.id}. Make the next concrete increment of progress and record artifacts/judgements via MCP tools.` : `Continue executing task ${task.id}. Make the next concrete increment of progress and record artifacts/judgements via MCP tools.`;
-    const outcome = await driveTurn(deps, codex, projectSlug, runId, leaseId, threadId, executionPrompt);
+    const workBudgetMs = remainingTurnBudgetMs();
+    if (workBudgetMs <= 0) {
+      await failRun(deps, projectSlug, task, runId, leaseId, executionTurnBudgetMessage(execRunMaxMs()));
+      return;
+    }
+    const outcome = await driveTurn(deps, codex, projectSlug, runId, leaseId, threadId, executionPrompt, workBudgetMs, "work");
     if (!outcome.ok) {
       await resetWedgedThread(deps, projectSlug, task.id, outcome.interruptFailed);
       await failRun(deps, projectSlug, task, runId, leaseId, outcome.error);
@@ -39452,7 +39610,36 @@ async function resetWedgedThread(deps, projectSlug, taskId, interruptFailed) {
   });
 }
 async function failRun(deps, projectSlug, task, runId, leaseId, reason) {
-  if (!await runHasLease(deps, projectSlug, runId, leaseId)) return;
+  let currentRun;
+  try {
+    currentRun = await deps.client.getExecutionRun(projectSlug, runId);
+  } catch {
+    return;
+  }
+  if (currentRun.status !== "running" || currentRun.leaseId !== leaseId) return;
+  if (isExecutionTurnTimeoutReason(reason) && currentRun.checkpointCursor !== EXECUTION_TURN_TIMEOUT_RETRY_CURSOR) {
+    try {
+      await deps.client.updateExecutionRun(projectSlug, runId, {
+        status: "pending",
+        leaseId: null,
+        checkpointCursor: EXECUTION_TURN_TIMEOUT_RETRY_CURSOR
+      });
+      await deps.client.appendExecutionArtifact(projectSlug, runId, {
+        id: newArtifactId(),
+        kind: "error",
+        payload: {
+          code: EXECUTION_TURN_TIMEOUT_RETRY_CODE,
+          source: "execution-consumer",
+          attempt: 1,
+          reason,
+          summary: EXECUTION_TURN_TIMEOUT_RETRY_SUMMARY
+        }
+      }).catch(() => {
+      });
+      return;
+    } catch {
+    }
+  }
   try {
     await deps.client.createExecutionRunHandoff(projectSlug, runId, { reason });
   } catch {
@@ -44092,6 +44279,9 @@ function buildThreadStartParams(msg, config2, desiredModel) {
     "request behind the task (pure system bookkeeping) \u2014 note that omitting it makes the gate fail-closed.",
     "",
     "Spec authoring contract \u2014 when creating or updating a `Specs/{id}` wiki page:",
+    "- BEGIN the page with YAML frontmatter naming the gated task: a first line `---`, then",
+    "  `task: {taskId}` (the task this spec gates, e.g. `task: GT-1023`), then `---`. Never change it",
+    "  to another task id \u2014 it is the machine-readable identity the consensus gate validates against.",
     "- In `## Specification`, write each requirement as `### Requirement: <name>` followed by one",
     "  SHALL sentence stating the externally visible behavior.",
     "- Give every requirement at least one `#### Scenario: <name>` with `- WHEN ...` / `- THEN ...`",
@@ -44136,6 +44326,24 @@ function buildThreadStartParams(msg, config2, desiredModel) {
     "- Do not create a handoff for transient provider quota/runtime failures, retriable tool",
     "  errors, or vague uncertainty; retry cheaply or explain the transient issue in chat.",
     "",
+    "Deferred-verification contract \u2014 when the RESULT can only be judged later:",
+    "- When a task's implementation is DONE but its outcome cannot be confirmed now because it",
+    "  depends on a delay you do not control \u2014 SEO ranking/traffic effects after (re)indexing,",
+    "  ad-campaign performance data accumulating, cache/DNS propagation, a scheduled external",
+    "  event \u2014 do NOT close the task and do NOT leave it `in_progress`. Move it to",
+    "  `awaiting_verification` via `update_task` and set `verificationDueAt` to the ISO-8601",
+    "  datetime when the effect should be measurable (e.g. ~2 weeks out for an SEO article).",
+    "  Use `followUpAt` instead when it is a softer check-in rather than a hard verification.",
+    "- In the same `update_task`, or in the task notes, record WHAT to measure and HOW so a later",
+    "  turn can verify objectively (the metric, the baseline, the success threshold).",
+    "- Do NOT use `awaiting_verification` for results you CAN confirm now \u2014 verify immediately",
+    "  (browser/HTTP/tests) and close or advance the task instead. It is only for genuinely",
+    "  time-delayed evidence, not for avoiding verification work.",
+    "- When the task is later woken (its `verificationDueAt`/`followUpAt` has passed), gather the",
+    "  evidence, then close it \u2014 `closed_done` if the outcome met the bar, or `closed_no_result`",
+    "  if it did not (that state REQUIRES a linked Evidence wiki page); or, if the effect still",
+    "  is not measurable, re-set `verificationDueAt` to a new date with a reason.",
+    "",
     "File artifacts: when you produce a file for the operator (report, HTML, screenshot),",
     "upload it 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",
@@ -45016,6 +45224,10 @@ function createBridgeMessageHandler(deps) {
             const effectiveText = inputText.length > 0 ? inputText : imageDataUri ? DEFAULT_IMAGE_ONLY_PROMPT : "";
             if (effectiveText.length > 0) {
               const updateOffer = deps.maybeUpdateOffer ? deps.maybeUpdateOffer() : null;
+              const updateOfferProjectSlug = msg.context?.projectSlug?.trim();
+              if (updateOffer !== null && updateOfferProjectSlug && deps.fileUpdateInboxItem) {
+                void deps.fileUpdateInboxItem(updateOfferProjectSlug);
+              }
               const composedPrefix = updateOffer ? contextPrefix ? `${updateOffer}
 
 ${contextPrefix}` : updateOffer : contextPrefix;
@@ -45433,7 +45645,32 @@ async function startDirectorBridge() {
       sessionSinks.unbind(directorSessionId, send);
     },
     getSessionSink: (directorSessionId) => sessionSinks.get(directorSessionId),
-    maybeUpdateOffer: () => selfUpdateHandle.maybeUpdateOffer()
+    maybeUpdateOffer: () => selfUpdateHandle.maybeUpdateOffer(),
+    fileUpdateInboxItem: async (projectSlug) => {
+      const body = selfUpdateHandle.updateInboxBody();
+      if (!body) return;
+      const id = `II-MCPUPD-${(0, import_node_crypto5.randomUUID)()}`;
+      try {
+        const row = await client.createInboxItem(projectSlug, { id, kind: "question", body });
+        process.stderr.write(
+          `[mrrlin-mcp director-bridge] info bridge.self_update.inbox_filed ${JSON.stringify({
+            projectSlug,
+            itemId: row.id,
+            deduped: row.id !== id
+          })}
+`
+        );
+      } catch (err) {
+        process.stderr.write(
+          `[mrrlin-mcp director-bridge] warn bridge.self_update.inbox_file_failed ${JSON.stringify({
+            projectSlug,
+            errorClass: "inbox_write_failed",
+            message: String(err?.message ?? err)
+          })}
+`
+        );
+      }
+    }
   };
   const bridgeLogger = createBridgeLogger(config2.stateDir, process.env);
   let bridgeBinShaShort = "unknown00000";
@@ -49524,6 +49761,71 @@ ${dismissedFwd.slice(-20).join("\n")}` : "";
   return { outcome: "CONSENSUS_BLOCKED", rounds: input.rounds, finalArtifact: artifact, history };
 }
 
+// src/consensus/spec-identity.ts
+function validateSpecIdentity(markdown, taskId) {
+  const target = taskId.toUpperCase();
+  const fieldToken = frontmatterTaskToken(markdown);
+  if (fieldToken !== null && fieldToken.toUpperCase() !== target) return false;
+  const headingToken = firstHeadingToken(markdown);
+  if (headingToken !== null && headingToken.toUpperCase() !== target) return false;
+  return true;
+}
+var TASK_ID_TOKEN = /\b[A-Za-z]{1,12}-\d{1,10}\b/;
+var ATX_HEADING = /^ {0,3}#{1,6}\s+(.*)$/;
+var FRONTMATTER_TASK = /^task(?:_id)?:\s*(.+)$/i;
+function frontmatterTaskToken(markdown) {
+  const lines2 = markdown.split("\n");
+  const firstContent = lines2.findIndex((l) => l.trim() !== "");
+  if (firstContent === -1 || lines2[firstContent]?.trim() !== "---") return null;
+  for (let i = firstContent + 1; i < lines2.length; i++) {
+    const trimmed = (lines2[i] ?? "").trim();
+    if (trimmed === "---") break;
+    const m = FRONTMATTER_TASK.exec(trimmed);
+    if (m) return firstTaskIdToken(m[1] ?? "");
+  }
+  return null;
+}
+function firstHeadingToken(markdown) {
+  const heading = firstHeading(markdown);
+  return heading === null ? null : firstTaskIdToken(heading);
+}
+function firstHeading(markdown) {
+  const lines2 = markdown.split("\n");
+  let i = 0;
+  const firstContent = lines2.findIndex((l) => l.trim() !== "");
+  if (firstContent !== -1 && lines2[firstContent]?.trim() === "---") {
+    i = firstContent + 1;
+    while (i < lines2.length && lines2[i]?.trim() !== "---") i++;
+    i++;
+  }
+  let inFence = false;
+  let inComment = false;
+  for (; i < lines2.length; i++) {
+    const line = lines2[i] ?? "";
+    const trimmed = line.trim();
+    if (inComment) {
+      if (trimmed.includes("-->")) inComment = false;
+      continue;
+    }
+    if (trimmed.startsWith("```") || trimmed.startsWith("~~~")) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) continue;
+    if (trimmed.startsWith("<!--")) {
+      if (!trimmed.includes("-->")) inComment = true;
+      continue;
+    }
+    const m = ATX_HEADING.exec(line);
+    if (m) return m[1] ?? "";
+  }
+  return null;
+}
+function firstTaskIdToken(text) {
+  const m = TASK_ID_TOKEN.exec(text);
+  return m ? m[0] : null;
+}
+
 // src/consensus/spec-gate.ts
 var SPEC_HEADS = ["plan-reviewer", "architect", "security-analyst", "scope-analyst"];
 async function runSpecGate(_target, deps, opts) {
@@ -49545,6 +49847,7 @@ async function runSpecGate(_target, deps, opts) {
   const heads = [...SPEC_HEADS, ...extraHeads.filter((h) => !SPEC_HEADS.includes(h))];
   const spec = await deps.readSpec();
   let currentHash = spec.contentHash;
+  let currentMarkdown = spec.markdownBody;
   let conflicted = false;
   const result = await runConsensus({
     artifact: spec.markdownBody,
@@ -49556,12 +49859,20 @@ async function runSpecGate(_target, deps, opts) {
     revise: async (artifact, accepted) => {
       const revised = await deps.runReviser(artifact, accepted);
       if (!revised.ok) return artifact;
+      if (intent.taskId !== null && !validateSpecIdentity(revised.text, intent.taskId)) {
+        process.stderr.write(
+          `[spec-gate] discarding drifted revision for ${spec.pageId}: heading does not identify ${intent.taskId}
+`
+        );
+        return artifact;
+      }
       const cas = await deps.casUpdateSpec(revised.text, currentHash);
       if (!cas.ok) {
         conflicted = true;
         throw new Error("SPEC_CHANGED_DURING_REVIEW");
       }
       currentHash = cas.contentHash;
+      currentMarkdown = revised.text;
       return revised.text;
     }
     // Only OUR conflict throw is swallowed (→ null). Anything else is a real
@@ -49571,6 +49882,22 @@ async function runSpecGate(_target, deps, opts) {
     await deps.writeEvidence({ specPageId: spec.pageId, outcome: "SPEC_CHANGED_DURING_REVIEW" });
     return { outcome: "SPEC_CHANGED_DURING_REVIEW" };
   }
+  if (result.outcome === "CONVERGED" && intent.taskId !== null && !validateSpecIdentity(currentMarkdown, intent.taskId)) {
+    process.stderr.write(
+      `[spec-gate] blocking promotion for ${spec.pageId}: converged spec heading does not identify ${intent.taskId}
+`
+    );
+    return {
+      outcome: "CONSENSUS_BLOCKED",
+      clarifications: [
+        {
+          question: `SPEC_IDENTITY_MISMATCH: this spec page gates ${intent.taskId}, but its heading identifies a different task \u2014 rewrite the spec heading and content for ${intent.taskId}, or re-link the task.`,
+          whyBlocking: "converged spec content belongs to a different task than the one it gates",
+          category: "scope"
+        }
+      ]
+    };
+  }
   await deps.writeEvidence({
     specPageId: spec.pageId,
     outcome: result.outcome,
@@ -49788,6 +50115,21 @@ var import_node_fs11 = __toESM(require("node:fs"), 1);
 var import_node_path13 = __toESM(require("node:path"), 1);
 var import_node_url2 = require("node:url");
 
+// src/consensus/resolve-gated-task.ts
+async function resolveGatedTaskId(client, projectSlug, page) {
+  const tasks = await client.listTasks(projectSlug);
+  const linking = tasks.find((t) => t.specWikiPageId === page.id);
+  if (linking) {
+    if (page.taskId !== linking.id) {
+      throw new Error(
+        `spec page ${page.id} is linked by task ${linking.id} (tasks.spec_wiki_page_id) but its wiki_pages.task_id back-pointer is ${page.taskId === null ? "null" : page.taskId} \u2014 refusing to gate with a drifted identity`
+      );
+    }
+    return linking.id;
+  }
+  return page.taskId;
+}
+
 // src/consensus/code-gate-git.ts
 var import_node_child_process6 = require("node:child_process");
 var DIFF_MAX_BYTES = 2e5;
@@ -50032,6 +50374,23 @@ function loadPersona(name) {
   personaCache.set(name, content);
   return content;
 }
+function specHeadIntentBlock(taskId, title, seed) {
+  const identity = taskId ? `--- TASK IDENTITY (the spec MUST be about THIS task; if its scope or direction contradicts this identity, raise a \`scope\` issue instead of steering the spec elsewhere) ---
+TASK ${taskId}: ${title ?? ""}
+
+` : "";
+  const intent = seed ? `--- OPERATOR INTENT (the operator's own words \u2014 judge the spec against THIS) ---
+${seed}
+
+` : "";
+  return `${identity}${intent}`;
+}
+function reviserIdentityInstructions(taskId, title) {
+  const lock = taskId ? `This spec gates task ${taskId}${title ? ` ("${title}")` : ""}. You MUST NOT change the spec's task identity or heading, retarget it to a different task id, or invert its direction (e.g. live-submission vs preparation-only). Preserve the leading \`task: ${taskId}\` frontmatter EXACTLY; never change it to another task id. Address ONLY the accepted issues.
+
+` : "";
+  return `${lock}You revise a spec to address accepted issues. Return ONLY the full revised markdown, no commentary.`;
+}
 function buildSpecGateDeps(args) {
   const { client, projectSlug, specPageId, cwd, codexExecutable, extraHeadCount = 0 } = args;
   const rounds = Number(process.env["MRRLIN_CONSENSUS_ROUNDS"] ?? 3);
@@ -50042,10 +50401,16 @@ function buildSpecGateDeps(args) {
     if (!intentPromise) {
       intentPromise = (async () => {
         const page = await client.getWikiPage(projectSlug, specPageId);
-        const taskId = page?.taskId ?? null;
-        if (taskId === null) return { taskId: null, seed: null };
+        if (!page) {
+          throw new Error(`spec page ${projectSlug}/${specPageId} not found \u2014 cannot gate`);
+        }
+        const taskId = await resolveGatedTaskId(client, projectSlug, { id: page.id, taskId: page.taskId ?? null });
+        if (taskId === null) return { taskId: null, seed: null, title: null };
         const task = await client.getTask(projectSlug, taskId);
-        return { taskId, seed: task?.operatorSeedRequest ?? null };
+        if (!task) {
+          throw new Error(`gated task ${projectSlug}/${taskId} not found for spec ${specPageId} \u2014 cannot gate`);
+        }
+        return { taskId, seed: task.operatorSeedRequest ?? null, title: task.title ?? "" };
       })();
     }
     return intentPromise;
@@ -50070,11 +50435,8 @@ function buildSpecGateDeps(args) {
     },
     async runHead(personaName, artifact, dismissed) {
       const persona = loadPersona(personaName);
-      const { seed } = await loadIntent();
-      const intentBlock = seed ? `--- OPERATOR INTENT (the operator's own words \u2014 judge the spec against THIS) ---
-${seed}
-
-` : "";
+      const { taskId, title, seed } = await loadIntent();
+      const intentBlock = specHeadIntentBlock(taskId, title, seed);
       return runCodexExec(
         {
           prompt: `Review this spec against the operator's intent.
@@ -50105,6 +50467,7 @@ ${artifact}`,
     },
     async runReviser(artifact, accepted) {
       const acceptedList = accepted.map((a) => `- (${a.category}) ${a.text}`).join("\n");
+      const { taskId, title } = await loadIntent();
       return runCodexExec(
         {
           prompt: `Accepted issues:
@@ -50112,7 +50475,7 @@ ${acceptedList}
 
 --- SPEC ---
 ${artifact}`,
-          developerInstructions: "You revise a spec to address accepted issues. Return ONLY the full revised markdown, no commentary.",
+          developerInstructions: reviserIdentityInstructions(taskId, title),
           cwd,
           timeoutMs,
           sandbox: "read-only",
@@ -50263,6 +50626,13 @@ async function cachedResult(client, input) {
   if (!page) return null;
   const review = await client.getSpecConsensusReview(input.projectSlug, input.pageId, page.contentHash);
   if (review?.outcome === "CONVERGED") {
+    const gatedTaskId = await resolveGatedTaskId(client, input.projectSlug, {
+      id: page.id,
+      taskId: page.taskId ?? null
+    });
+    if (gatedTaskId !== null && !validateSpecIdentity(page.markdownBody, gatedTaskId)) {
+      return null;
+    }
     return { status: "already_converged", payload: { outcome: "CONVERGED", contentHash: page.contentHash } };
   }
   if (review?.outcome === "CONSENSUS_BLOCKED") {
@@ -52485,6 +52855,13 @@ Usage:
                                 non-loopback URL (see \`mrrlin-mcp serve\` above).
                                 URL and MRRLIN_STAGING are mutually exclusive at
                                 bake time \u2014 URL wins, mirrors serve's resolver.
+                                Re-running BARE (no env vars) over a block you
+                                already pinned to staging/a remote target is safe:
+                                it keeps your env verbatim (reported as
+                                'env-preserved') instead of conflicting, so the
+                                same setup command doubles as an update command.
+                                To CHANGE or REMOVE the baked target, re-run with
+                                --force (or the new env vars).
                                 --force replaces an existing conflicting block.
                                 --force-prompts overwrites prompt files that
                                 already exist with different content. WITHOUT it,
@@ -52531,8 +52908,18 @@ Usage:
                                 - MRRLIN_DIRECTOR_BRIDGE_CODEX_IDLE_SECONDS (default 300;
                                   how long the warm codex app-server is kept alive
                                   between turns before it is released)
-                                - MRRLIN_DIRECTOR_BRIDGE_EXEC_TURN_TIMEOUT_SECONDS (default 900;
-                                  whole-turn deadline for one autonomous execution turn)
+                                - MRRLIN_DIRECTOR_BRIDGE_EXEC_TURN_IDLE_TIMEOUT_SECONDS (default 600;
+                                  an execution turn is cut only after this long with NO codex
+                                  signal at all \u2014 long-but-active turns keep running. A stall
+                                  earns one automatic retry)
+                                - MRRLIN_DIRECTOR_BRIDGE_EXEC_RUN_MAX_SECONDS (default 3600;
+                                  overall wall-clock budget for the active-turn portion of one
+                                  claim attempt, measured from claim. Exceeding it hands off with
+                                  NO retry. Setup/post-turn hangs are bounded by the stale reaper,
+                                  not by this budget)
+                                - MRRLIN_DIRECTOR_BRIDGE_EXEC_TURN_TIMEOUT_SECONDS (DEPRECATED;
+                                  unset by default. When set, an extra per-turn hard cap: the
+                                  effective turn deadline becomes min(this, remaining run budget))
                                 - MRRLIN_DIRECTOR_BRIDGE_CONTEXT_MAX_ARTIFACTS (default 50;
                                   most-recent artifacts kept in the execution context bundle)
 
@@ -52647,6 +53034,10 @@ async function main() {
       });
       process.stderr.write(`[mrrlin-mcp install-codex] ${result.action} ${result.configPath}
 `);
+      for (const preserved of result.preservedEnvBlocks) {
+        process.stderr.write(`${renderEnvPreservedNotice(preserved.blockId, preserved.envKeys)}
+`);
+      }
       for (const p of result.prompts) {
         process.stderr.write(`[mrrlin-mcp install-codex] prompt ${p.name}: ${p.action} ${p.promptPath}
 `);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrrlin-dev/mcp",
-  "version": "0.3.13",
+  "version": "0.3.15",
   "type": "module",
   "bin": {
     "mrrlin-mcp": "dist/bin.cjs"
@@ -22,11 +22,11 @@
     "@types/ws": "^8.18.1",
     "esbuild": "^0.24.0",
     "tsx": "^4.22.3",
+    "@mrrlin/client": "0.0.0",
     "@mrrlin/codex-client": "0.0.0",
     "@mrrlin/director-e2e": "0.0.0",
-    "@mrrlin/client": "0.0.0",
-    "@mrrlin/schemas": "0.0.0",
     "@mrrlin/tsconfig": "0.0.0",
+    "@mrrlin/schemas": "0.0.0",
     "@mrrlin/wiki": "0.0.0"
   },
   "dependencies": {