@mrrlin-dev/mcp 0.3.14 → 0.3.20

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 [];
@@ -20941,10 +20985,15 @@ var import_node_child_process4 = require("node:child_process");
 var import_node_crypto5 = __toESM(require("node:crypto"), 1);
 
 // src/turn-replay-buffer.ts
-var DEFAULT_GRACE_MS = 3e4;
 var DEFAULT_MAX_EVENTS = 2e3;
 var DEFAULT_MAX_BYTES = 4e6;
-var DEFAULT_POST_COMPLETION_TTL_MS = 1e4;
+var DEFAULT_ACK_LINGER_MS = 1e4;
+var DEFAULT_RESULT_RETENTION_MS = 36e5;
+function resultRetentionMs() {
+  const raw = (process.env.MRRLIN_DIRECTOR_BRIDGE_RESULT_RETENTION_SECONDS ?? "").trim();
+  const parsed = Number.parseInt(raw, 10);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed * 1e3 : DEFAULT_RESULT_RETENTION_MS;
+}
 function createReplayBuffer(opts) {
   return {
     turnId: opts.turnId,
@@ -20956,14 +21005,15 @@ function createReplayBuffer(opts) {
     terminalDelivered: false,
     replaying: false,
     outboundQueue: [],
-    graceTimer: null,
     finishedAt: null,
+    finishedSuspendedMs: null,
+    ackedAt: null,
     bytesUsed: 0,
-    graceMs: opts.graceMs ?? DEFAULT_GRACE_MS,
     maxEvents: opts.maxEvents ?? DEFAULT_MAX_EVENTS,
     maxBytes: opts.maxBytes ?? DEFAULT_MAX_BYTES,
-    postCompletionTtlMs: opts.postCompletionTtlMs ?? DEFAULT_POST_COMPLETION_TTL_MS,
-    triggerGrace: null
+    ackLingerMs: opts.ackLingerMs ?? DEFAULT_ACK_LINGER_MS,
+    retentionMs: opts.retentionMs ?? resultRetentionMs(),
+    triggerDetach: null
   };
 }
 function recordOutgoing(buf, msg) {
@@ -20972,9 +21022,10 @@ function recordOutgoing(buf, msg) {
   buf.events.push(entry);
   buf.bytesUsed += approxByteSize(msg);
   while ((buf.events.length > buf.maxEvents || buf.bytesUsed > buf.maxBytes) && buf.events.length > 0) {
-    const dropped = buf.events.shift();
-    if (!dropped) break;
-    buf.bytesUsed -= approxByteSize(dropped.msg);
+    const head = buf.events[0];
+    if (!head || isTerminalEvent(head.msg)) break;
+    buf.events.shift();
+    buf.bytesUsed -= approxByteSize(head.msg);
   }
   return entry;
 }
@@ -20983,19 +21034,7 @@ function eventsAfter(buf, lastSeq) {
   if (first && lastSeq < first.seq - 1) return null;
   return buf.events.filter((e) => e.seq > lastSeq);
 }
-function enterGrace(buf, onExpire) {
-  if (buf.graceTimer !== null) return;
-  buf.state = "grace";
-  buf.graceTimer = setTimeout(onExpire, buf.graceMs);
-}
-function cancelGrace(buf) {
-  if (buf.graceTimer !== null) {
-    clearTimeout(buf.graceTimer);
-    buf.graceTimer = null;
-  }
-  if (buf.state === "grace") buf.state = "live";
-}
-function recordInterrupted(buf) {
+function recordInterrupted(buf, now = Date.now(), suspendedMsNow = 0) {
   if (buf.terminalDelivered) return null;
   const msg = {
     type: "event",
@@ -21003,16 +21042,31 @@ function recordInterrupted(buf) {
   };
   const entry = recordOutgoing(buf, msg);
   buf.terminalDelivered = true;
+  if (buf.finishedAt === null) {
+    buf.finishedAt = now;
+    buf.finishedSuspendedMs = suspendedMsNow;
+  }
   return entry;
 }
-function markCompleted(buf, now) {
+function markCompleted(buf, now, suspendedMsNow = 0) {
   buf.state = "completed";
   buf.finishedAt = now;
+  buf.finishedSuspendedMs = suspendedMsNow;
+}
+function recordAck(buf, turnId, lastSeq, now) {
+  if (buf.turnId !== turnId) return false;
+  if (lastSeq !== buf.lastSeq) return false;
+  if (buf.state !== "completed" && buf.state !== "interrupted") return false;
+  if (buf.ackedAt === null) buf.ackedAt = now;
+  return true;
 }
-function shouldGc(buf, now) {
-  if (buf.state !== "completed") return false;
+function shouldGc(buf, now, suspendedMsNow = 0) {
+  if (buf.state !== "completed" && buf.state !== "interrupted") return false;
   if (buf.finishedAt === null) return false;
-  return now - buf.finishedAt > buf.postCompletionTtlMs;
+  if (buf.ackedAt !== null) return now - buf.ackedAt > buf.ackLingerMs;
+  const suspendedSinceFinish = suspendedMsNow - (buf.finishedSuspendedMs ?? suspendedMsNow);
+  const awakeElapsed = now - buf.finishedAt - Math.max(0, suspendedSinceFinish);
+  return awakeElapsed > buf.retentionMs;
 }
 function incrementBindEpoch(buf) {
   return ++buf.bindEpoch;
@@ -21033,6 +21087,41 @@ function approxByteSize(msg) {
   }
 }
 
+// src/suspension-detector.ts
+var DEFAULT_SUSPEND_TICK_MS = 15e3;
+var DEFAULT_SUSPEND_GAP_MS = 45e3;
+function readPositiveMs(name, fallback) {
+  const raw = (process.env[name] ?? "").trim();
+  const parsed = Number.parseInt(raw, 10);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback;
+}
+function suspendTickMs() {
+  return readPositiveMs("MRRLIN_DIRECTOR_BRIDGE_SUSPEND_TICK_MS", DEFAULT_SUSPEND_TICK_MS);
+}
+function suspendGapMs() {
+  return readPositiveMs("MRRLIN_DIRECTOR_BRIDGE_SUSPEND_GAP_MS", DEFAULT_SUSPEND_GAP_MS);
+}
+function createSuspensionDetector(opts) {
+  const tickMs = opts?.tickMs ?? suspendTickMs();
+  const gapMs = opts?.gapMs ?? suspendGapMs();
+  const now = opts?.now ?? Date.now;
+  const setI = opts?.setIntervalFn ?? setInterval;
+  const clearI = opts?.clearIntervalFn ?? clearInterval;
+  let last = now();
+  let suspended = 0;
+  const timer = setI(() => {
+    const t = now();
+    const gap = t - last;
+    last = t;
+    if (gap >= gapMs) suspended += gap - tickMs;
+  }, tickMs);
+  timer.unref?.();
+  return {
+    suspendedMs: () => suspended,
+    dispose: () => clearI(timer)
+  };
+}
+
 // src/replay-state-machine.ts
 function transition(state, event) {
   if (event.kind === "resume" && !event.epochMatch) return { next: "invalid" };
@@ -21040,7 +21129,12 @@ function transition(state, event) {
     case "live":
       switch (event.kind) {
         case "socket_close":
-          return { next: "grace", sideEffects: ["start_grace_timer"] };
+          return { next: "detached", sideEffects: [] };
+        case "resume":
+          return {
+            next: "live",
+            sideEffects: ["rebind_sink_increment_epoch", "replay_drain"]
+          };
         case "codex_terminal":
           return { next: "completed", sideEffects: ["mark_finished"] };
         case "stop":
@@ -21051,35 +21145,22 @@ function transition(state, event) {
         default:
           return { next: "invalid" };
       }
-    case "grace":
+    case "detached":
       switch (event.kind) {
+        case "socket_close":
+          return { next: "detached", sideEffects: [] };
+        // idempotent
         case "resume":
           return {
             next: "live",
-            sideEffects: [
-              "cancel_grace_timer",
-              "rebind_sink_increment_epoch",
-              "replay_drain"
-            ]
-          };
-        case "grace_expire":
-          return {
-            next: "interrupted",
-            sideEffects: ["record_interrupted", "fire_turn_interrupt"]
+            sideEffects: ["rebind_sink_increment_epoch", "replay_drain"]
           };
+        case "codex_terminal":
+          return { next: "completed", sideEffects: ["mark_finished"] };
         case "stop":
           return {
             next: "interrupted",
-            sideEffects: [
-              "cancel_grace_timer",
-              "record_interrupted",
-              "fire_turn_interrupt"
-            ]
-          };
-        case "codex_terminal":
-          return {
-            next: "completed",
-            sideEffects: ["cancel_grace_timer", "mark_finished"]
+            sideEffects: ["record_interrupted", "fire_turn_interrupt"]
           };
         default:
           return { next: "invalid" };
@@ -36437,10 +36518,12 @@ var mrrlinTaskStatusSchema = external_exports.enum([
   "closed_done",
   "closed_no_result"
 ]);
+var mrrlinTerminalTaskStatuses = ["closed_done", "closed_no_result"];
 var mrrlinTaskTypeSchema = external_exports.enum(["task", "bug"]);
 var mrrlinTaskImpactSchema = external_exports.enum(["low", "medium", "high"]);
 var mrrlinAutonomyLevelSchema = external_exports.enum(["auto", "minimal_human", "human_only"]);
 var mrrlinAutoDeploySchema = external_exports.enum(["off", "dev", "prod"]);
+var mrrlinTaskDomainSchema = external_exports.enum(["code", "seo", "marketing", "content"]);
 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"]);
@@ -36472,6 +36555,27 @@ function normalizeTaskTags(tags) {
   }
   return [...normalized].sort();
 }
+var terminalTaskStatusSet = new Set(mrrlinTerminalTaskStatuses);
+function isTaskTerminalStatus(status) {
+  return terminalTaskStatusSet.has(status);
+}
+function getActiveBlockedByIds(blockedBy, blockers) {
+  const blockersById = /* @__PURE__ */ new Map();
+  for (const blocker of blockers) {
+    if (!blocker)
+      continue;
+    blockersById.set(blocker.id, blocker.status);
+  }
+  const active = [];
+  for (const blockerId of blockedBy ?? []) {
+    const status = blockersById.get(blockerId);
+    if (!status)
+      continue;
+    if (!isTaskTerminalStatus(status))
+      active.push(blockerId);
+  }
+  return active;
+}
 var mrrlinTaskTagSchema = external_exports.string().min(1).max(40).transform(normalizeTaskTagInput).pipe(external_exports.string().min(1).max(40));
 var mrrlinTaskTagsSchema = external_exports.array(mrrlinTaskTagSchema).default([]).transform(normalizeTaskTags);
 var mrrlinExecutionRunStatusSchema = external_exports.enum([
@@ -36525,6 +36629,10 @@ var mrrlinTaskAssigneeSchema = external_exports.union([external_exports.string()
 var mrrlinTaskSchema = external_exports.object({
   assignee: mrrlinTaskAssigneeSchema,
   autoDeploy: mrrlinAutoDeploySchema,
+  // ADR 0020. OUTPUT-optional (not defaulted-required) so hardcoded task fixtures/mocks across the
+  // codebase need no churn; the DB column is NOT NULL default 'code', so real rows always carry it,
+  // and resolveHeads() treats an absent domain as `code`. Persisted create/update use their own forms.
+  domain: mrrlinTaskDomainSchema.optional(),
   autonomyLevel: mrrlinAutonomyLevelSchema,
   autonomyReason: external_exports.string().min(1).max(240),
   blockedBy: external_exports.array(mrrlinTaskIdSchema),
@@ -36642,7 +36750,10 @@ var mrrlinProjectSummarySchema = external_exports.object({
   emoji: mrrlinProjectEmojiSchema,
   github: mrrlinGithubBindingSchema,
   onboardingKickoffState: external_exports.enum(["pending", "sent"]).nullable().optional(),
-  slug: mrrlinProjectSlugSchema
+  slug: mrrlinProjectSlugSchema,
+  // ADR 0020: default consensus domain for this project's plan/project-scoped specs. Output-optional
+  // (DB column is NOT NULL default 'code') so existing project fixtures/upsert callers need no churn.
+  defaultDomain: mrrlinTaskDomainSchema.optional()
 });
 var mrrlinProjectUpsertSchema = mrrlinProjectSummarySchema.omit({
   onboardingKickoffState: true,
@@ -36691,6 +36802,9 @@ var mrrlinProjectSnapshotSchema = external_exports.object({
 });
 var mrrlinTaskCreateSchema = external_exports.object({
   autoDeploy: mrrlinAutoDeploySchema.default("off"),
+  // Input-optional so existing createTask call sites need no churn; createTask fills 'code' for the
+  // INSERT (the pg column is NOT NULL, so a concrete value is required, not undefined→NULL).
+  domain: mrrlinTaskDomainSchema.optional(),
   autonomyLevel: mrrlinAutonomyLevelSchema.default("minimal_human"),
   autonomyReason: external_exports.string().min(1).max(240).default("Needs human review before automation."),
   category: taxonomyCategorySchema,
@@ -36714,6 +36828,7 @@ var mrrlinTaskUpdateSchema = external_exports.object({
   actor: external_exports.string().min(1).optional(),
   assignee: mrrlinTaskAssigneeSchema.optional(),
   autoDeploy: mrrlinAutoDeploySchema.optional(),
+  domain: mrrlinTaskDomainSchema.optional(),
   autonomyLevel: mrrlinAutonomyLevelSchema.optional(),
   autonomyReason: external_exports.string().min(1).max(240).optional(),
   category: taxonomyCategorySchema.optional(),
@@ -37347,6 +37462,43 @@ var mrrlinInboxItemActionPayloadSchema = external_exports.object({
   // (worktree + push/PR path). Scheduler proposals set it; legacy payloads omit it.
   codeExecution: external_exports.boolean().optional()
 });
+var mrrlinInboxQuestionOptionSchema = external_exports.object({
+  answer: external_exports.string().trim().min(1),
+  description: external_exports.string().trim().min(1),
+  label: external_exports.string().trim().min(1),
+  recommended: external_exports.boolean().optional()
+});
+var mrrlinInboxQuestionOptionsSchema = external_exports.array(mrrlinInboxQuestionOptionSchema).min(1).max(3).superRefine((options, context) => {
+  const labels = /* @__PURE__ */ new Set();
+  const answers = /* @__PURE__ */ new Set();
+  let recommendedCount = 0;
+  for (const [index, option] of options.entries()) {
+    if (labels.has(option.label)) {
+      context.addIssue({
+        code: external_exports.ZodIssueCode.custom,
+        message: "questionOptions labels must be unique after trimming",
+        path: [index, "label"]
+      });
+    }
+    labels.add(option.label);
+    if (answers.has(option.answer)) {
+      context.addIssue({
+        code: external_exports.ZodIssueCode.custom,
+        message: "questionOptions answers must be unique after trimming",
+        path: [index, "answer"]
+      });
+    }
+    answers.add(option.answer);
+    if (option.recommended === true)
+      recommendedCount += 1;
+  }
+  if (recommendedCount > 1) {
+    context.addIssue({
+      code: external_exports.ZodIssueCode.custom,
+      message: "questionOptions may mark at most one option as recommended"
+    });
+  }
+});
 var mrrlinInboxItemSchema = external_exports.object({
   actionPayload: mrrlinInboxItemActionPayloadSchema.nullable(),
   answer: external_exports.string().nullable(),
@@ -37362,9 +37514,18 @@ var mrrlinInboxItemSchema = external_exports.object({
   origin: external_exports.string().nullable().optional(),
   planId: mrrlinPlanIdSchema.nullable().default(null),
   projectSlug: mrrlinProjectSlugSchema,
+  questionOptions: mrrlinInboxQuestionOptionsSchema.nullable().default(null),
   readAt: external_exports.string().datetime().nullable(),
   status: mrrlinInboxItemStatusSchema,
   taskId: mrrlinTaskIdSchema.nullable()
+}).superRefine((value, context) => {
+  if (value.kind !== "question" && value.questionOptions !== null) {
+    context.addIssue({
+      code: external_exports.ZodIssueCode.custom,
+      message: "questionOptions are allowed only on question inbox items",
+      path: ["questionOptions"]
+    });
+  }
 });
 var mrrlinInboxItemCreateSchema = external_exports.object({
   actionPayload: mrrlinInboxItemActionPayloadSchema.nullable().optional(),
@@ -37374,7 +37535,16 @@ var mrrlinInboxItemCreateSchema = external_exports.object({
   kind: mrrlinInboxItemKindSchema,
   origin: external_exports.string().min(1).optional(),
   planId: mrrlinPlanIdSchema.nullable().optional(),
+  questionOptions: mrrlinInboxQuestionOptionsSchema.nullable().optional(),
   taskId: mrrlinTaskIdSchema.nullable().optional()
+}).superRefine((value, context) => {
+  if (value.kind !== "question" && value.questionOptions != null) {
+    context.addIssue({
+      code: external_exports.ZodIssueCode.custom,
+      message: "questionOptions are allowed only on question inbox items",
+      path: ["questionOptions"]
+    });
+  }
 });
 var mrrlinInboxItemDecideSchema = external_exports.object({
   answer: external_exports.string().min(1).optional(),
@@ -38564,7 +38734,7 @@ Do NOT derail the current task - if the operator has an in-flight question, answ
 }
 
 // src/_generated/version.ts
-var PKG_VERSION = "0.3.14";
+var PKG_VERSION = "0.3.20";
 
 // src/api-base-url.ts
 var DEFAULT_API_BASE_URL = "http://127.0.0.1:8787";
@@ -38778,10 +38948,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(
@@ -38795,6 +38997,7 @@ async function awaitTurnWithDeadline(opts) {
     }
     throw error51;
   }
+  clearTimers();
 }
 
 // src/worktree.ts
@@ -38987,9 +39190,12 @@ ${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";
@@ -38999,14 +39205,26 @@ function readPositiveIntEnv(name, 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 executionTurnTimeoutMessage(timeoutMs) {
-  return `${EXECUTION_TURN_TIMEOUT_PREFIX} ${timeoutMs}ms.`;
+function executionTurnBudgetMessage(budgetMs) {
+  return `${EXECUTION_TURN_BUDGET_PREFIX} (${budgetMs}ms).`;
 }
 function isExecutionTurnTimeoutReason(reason) {
-  return reason.startsWith(EXECUTION_TURN_TIMEOUT_PREFIX);
+  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);
@@ -39159,11 +39377,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);
@@ -39185,6 +39407,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
@@ -39192,9 +39419,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?.();
       }
@@ -39204,10 +39430,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 }]
@@ -39216,8 +39443,10 @@ async function driveTurn(deps, codex, projectSlug, runId, leaseId, threadId, inp
           await turnEnded;
         },
         interrupt: () => codex.turn.interrupt({ threadId }),
-        timeoutMs,
-        timeoutMessage: executionTurnTimeoutMessage(timeoutMs),
+        timeoutMs: overallMs,
+        timeoutMessage: executionTurnBudgetMessage(overallMs),
+        idleTimeoutMs: idleMs,
+        idleTimeoutMessage: executionTurnStallMessage(idleMs),
         onInterruptFailed: () => {
           interruptFailed = true;
         }
@@ -39226,6 +39455,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();
@@ -39247,7 +39489,38 @@ 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 blockerTasks = task.blockedBy.length ? await Promise.all(task.blockedBy.map((blockerTaskId) => deps.client.getTask(projectSlug, blockerTaskId))) : [];
+  const missingBlockers = task.blockedBy.filter((_, index) => !blockerTasks[index]);
+  if (missingBlockers.length > 0) {
+    await failRun(
+      deps,
+      projectSlug,
+      task,
+      runId,
+      leaseId,
+      `task_blocked: run ${runId} targets ${task.id} but blocker tasks could not be loaded: ${missingBlockers.join(", ")}`
+    );
+    return;
+  }
+  const activeBlockers = getActiveBlockedByIds(task.blockedBy, blockerTasks);
+  if (activeBlockers.length > 0) {
+    await failRun(
+      deps,
+      projectSlug,
+      task,
+      runId,
+      leaseId,
+      `task_blocked: run ${runId} targets ${task.id} but active blockers remain open: ${activeBlockers.join(", ")}`
+    );
+    return;
+  }
   const compactEnabled = (process.env.MRRLIN_MCP_COMPACT_DISABLE ?? "").trim() !== "1";
   const context = await gatherContext(deps.client, projectSlug, task, runId);
   const bundle = renderContextBundle(
@@ -39269,7 +39542,11 @@ async function driveRun(deps, projectSlug, runId) {
   };
   if (claimed.codeExecution) {
     if (!checkout) {
-      const reason = `local_checkout_missing: run ${runId} requires code execution but no confirmed local checkout exists for project ${projectSlug}. Register a checkout via the operator tool before re-queuing.`;
+      const reason = `local_checkout_missing: run ${runId} needs code execution, but project ${projectSlug} has no local git checkout registered on this machine, so there is nowhere to make the changes. Explain this to the operator in plain, non-technical language, then proactively help register one:
+1. Search the usual locations (~/dev, ~/code, ~/work, ~/projects) for a clone of this project's GitHub repo, matching by its \`git remote origin\` URL.
+2. If you find a likely match, tell the operator where you think it is and ask them to confirm \u2014 e.g. "For code changes I need this project's repo checked out here. I think it's at <path> \u2014 should I register that one, or do you want to point me at a different path?"
+3. When the operator confirms a path, call register_local_checkout({ projectSlug: "${projectSlug}", path: "<absolute path>", repo: "<this project's GitHub repo>" }).
+4. If no candidate is found, ask the operator for the absolute path to the checkout (or to clone the repo first), then register it. Once a checkout is registered, the run can be re-queued.`;
       await failRun(deps, projectSlug, task, runId, leaseId, reason);
       return;
     }
@@ -39284,6 +39561,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)
@@ -39334,11 +39612,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);
@@ -39348,7 +39632,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);
@@ -39903,9 +40192,15 @@ function saveThreadIndex(stateDir, entries) {
 function createInactivityWatchdog(opts) {
   const setT = opts.setTimeoutFn ?? setTimeout;
   const clearT = opts.clearTimeoutFn ?? clearTimeout;
+  const now = opts.now ?? Date.now;
+  const suspended = opts.suspendedMs ?? (() => 0);
   let idleTimer = null;
   let maxTimer = null;
   let done = false;
+  const startAt = now();
+  const suspendedAtStart = suspended();
+  let lastPokeAt = startAt;
+  let suspendedAtLastPoke = suspendedAtStart;
   const expire = (reason) => {
     if (done) return;
     done = true;
@@ -39913,16 +40208,41 @@ function createInactivityWatchdog(opts) {
     if (maxTimer) clearT(maxTimer);
     opts.onExpire(reason);
   };
-  idleTimer = setT(() => expire("idle"), opts.idleMs);
-  idleTimer.unref?.();
-  maxTimer = setT(() => expire("max"), opts.maxMs);
-  maxTimer.unref?.();
+  const armIdle = (ms) => {
+    idleTimer = setT(onIdleDeadline, Math.max(1, ms));
+    idleTimer.unref?.();
+  };
+  const armMax = (ms) => {
+    maxTimer = setT(onMaxDeadline, Math.max(1, ms));
+    maxTimer.unref?.();
+  };
+  const onIdleDeadline = () => {
+    if (done) return;
+    const awakeSilence = now() - lastPokeAt - (suspended() - suspendedAtLastPoke);
+    if (awakeSilence < opts.idleMs) {
+      armIdle(opts.idleMs - awakeSilence);
+      return;
+    }
+    expire("idle");
+  };
+  const onMaxDeadline = () => {
+    if (done) return;
+    const awakeElapsed = now() - startAt - (suspended() - suspendedAtStart);
+    if (awakeElapsed < opts.maxMs) {
+      armMax(opts.maxMs - awakeElapsed);
+      return;
+    }
+    expire("max");
+  };
+  armIdle(opts.idleMs);
+  armMax(opts.maxMs);
   return {
     poke: () => {
       if (done) return;
       if (idleTimer) clearT(idleTimer);
-      idleTimer = setT(() => expire("idle"), opts.idleMs);
-      idleTimer.unref?.();
+      lastPokeAt = now();
+      suspendedAtLastPoke = suspended();
+      armIdle(opts.idleMs);
     },
     cancel: () => {
       done = true;
@@ -44098,6 +44418,7 @@ function createBridgeLogger(stateDir, env = process.env) {
 }
 
 // src/director-bridge.ts
+var JSON_GPT_MODEL_REF_RE = /"(?:slug|model)"\s*:\s*"(gpt-[a-z0-9.-]+)"/gi;
 var DEFAULT_DIRECTOR_BRIDGE_ALLOWED_ORIGINS = [
   "http://localhost:*",
   "http://127.0.0.1:*",
@@ -44118,6 +44439,139 @@ function normalizeModel(value) {
   const trimmed = value.trim();
   return trimmed ? trimmed : null;
 }
+function isSelectableModelSlug(value) {
+  return typeof value === "string" && value.startsWith("gpt-");
+}
+function humanizeModelSlug(slug) {
+  if (!slug.startsWith("gpt-")) return slug;
+  const rest = slug.slice(4);
+  if (!rest) return "GPT";
+  const [version2, ...variants] = rest.split("-").filter(Boolean);
+  if (variants.length === 0) return `GPT-${version2}`;
+  return `GPT-${version2} ${variants.map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ")}`;
+}
+function mapBridgeModel(raw) {
+  const model = (raw.model ?? raw.id ?? "").trim();
+  if (!model) return null;
+  return {
+    id: (raw.id ?? model).trim() || model,
+    model,
+    displayName: (raw.displayName ?? model).trim() || model,
+    description: raw.description ?? "",
+    supportedReasoningEfforts: (raw.supportedReasoningEfforts ?? []).map((entry) => ({
+      reasoningEffort: entry.reasoningEffort,
+      description: entry.description ?? ""
+    })),
+    defaultReasoningEffort: raw.defaultReasoningEffort ?? null,
+    isDefault: raw.isDefault === true
+  };
+}
+function addBridgeModel(target, model) {
+  if (!model) return;
+  if (!target.has(model.model)) target.set(model.model, model);
+}
+function readTextIfExists(filePath) {
+  try {
+    return import_node_fs10.default.readFileSync(filePath, "utf8");
+  } catch {
+    return null;
+  }
+}
+function readKnownGptSlugsFromTomlFile(filePath) {
+  const raw = readTextIfExists(filePath);
+  if (!raw) return [];
+  return Array.from(raw.matchAll(/^\s*model\s*=\s*"([^"]+)"/gm)).map((match) => match[1]?.trim() ?? "").filter(isSelectableModelSlug);
+}
+function readCodexFallbackModels() {
+  const codexHome = process.env.CODEX_HOME?.trim() || import_node_path11.default.join(import_node_os7.default.homedir(), ".codex");
+  const models = /* @__PURE__ */ new Map();
+  const cachePath = import_node_path11.default.join(codexHome, "models_cache.json");
+  const cacheRaw = readTextIfExists(cachePath);
+  if (cacheRaw) {
+    try {
+      const parsed = JSON.parse(cacheRaw);
+      if (Array.isArray(parsed.models)) {
+        for (const entry of parsed.models) {
+          if (!entry || typeof entry !== "object") continue;
+          const cached2 = entry;
+          const slug = typeof cached2.slug === "string" ? cached2.slug.trim() : "";
+          if (!isSelectableModelSlug(slug)) continue;
+          const supportedReasoningEfforts = Array.isArray(cached2.supported_reasoning_levels) ? cached2.supported_reasoning_levels.flatMap((level) => {
+            if (!level || typeof level !== "object") return [];
+            const option = level;
+            if (typeof option.effort !== "string" || !option.effort.trim()) return [];
+            return [{ reasoningEffort: option.effort, description: typeof option.description === "string" ? option.description : "" }];
+          }) : [];
+          addBridgeModel(
+            models,
+            mapBridgeModel({
+              id: slug,
+              model: slug,
+              displayName: typeof cached2.display_name === "string" ? cached2.display_name : humanizeModelSlug(slug),
+              description: typeof cached2.description === "string" ? cached2.description : "",
+              supportedReasoningEfforts,
+              defaultReasoningEffort: typeof cached2.default_reasoning_level === "string" ? cached2.default_reasoning_level : null,
+              isDefault: false
+            })
+          );
+        }
+      }
+    } catch {
+    }
+    for (const match of cacheRaw.matchAll(JSON_GPT_MODEL_REF_RE)) {
+      const slug = match[1]?.trim().toLowerCase() ?? "";
+      if (!isSelectableModelSlug(slug)) continue;
+      addBridgeModel(
+        models,
+        mapBridgeModel({
+          id: slug,
+          model: slug,
+          displayName: humanizeModelSlug(slug),
+          description: "",
+          supportedReasoningEfforts: [],
+          defaultReasoningEffort: null,
+          isDefault: false
+        })
+      );
+    }
+  }
+  for (const slug of readKnownGptSlugsFromTomlFile(import_node_path11.default.join(codexHome, "config.toml"))) {
+    addBridgeModel(
+      models,
+      mapBridgeModel({
+        id: slug,
+        model: slug,
+        displayName: humanizeModelSlug(slug),
+        description: "",
+        supportedReasoningEfforts: [],
+        defaultReasoningEffort: null,
+        isDefault: false
+      })
+    );
+  }
+  const automationsDir = import_node_path11.default.join(codexHome, "automations");
+  try {
+    for (const entry of import_node_fs10.default.readdirSync(automationsDir, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      for (const slug of readKnownGptSlugsFromTomlFile(import_node_path11.default.join(automationsDir, entry.name, "automation.toml"))) {
+        addBridgeModel(
+          models,
+          mapBridgeModel({
+            id: slug,
+            model: slug,
+            displayName: humanizeModelSlug(slug),
+            description: "",
+            supportedReasoningEfforts: [],
+            defaultReasoningEffort: null,
+            isDefault: false
+          })
+        );
+      }
+    }
+  } catch {
+  }
+  return [...models.values()];
+}
 function neutralCheckoutCwd(stateDir) {
   const dir = import_node_path11.default.join(stateDir, "no-checkout");
   try {
@@ -44145,13 +44599,16 @@ 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 ...`",
     "  bullets (`- AND ...` as needed). Scenarios make the spec verifiable.",
     "- Keep behavior contracts in the spec; implementation details belong in `## Implementation Plan`.",
     "- Apply this format ONLY to Specs/{id} pages; do not retro-fit it onto other wiki page types.",
-    "- Spec consensus runs ASYNCHRONOUSLY. Call `run_spec_consensus` for a `Specs/{id}` page; it returns IMMEDIATELY. On `already_converged`, the spec is already marked ready \u2014 proceed straight to `create_execution_run`; do NOT call `mark_spec_ready` and do NOT re-run consensus. On `queued` or `already_running`, tell the user it was launched and END your turn \u2014 do NOT poll or call it again; the result arrives in the inbox (an `info` item on CONVERGED, a `handoff` item if it was blocked/failed). When a consensus `info` item says CONVERGED, proceed to `create_execution_run`. When a `handoff` says it was blocked, address the recorded issues in the spec (any edit re-arms the gate) and call `run_spec_consensus` once more.",
+    "- Spec consensus runs ASYNCHRONOUSLY. Call `run_spec_consensus` for a `Specs/{id}` page; it returns IMMEDIATELY. On `already_converged`, the spec is already marked ready \u2014 proceed straight to `create_execution_run`; do NOT call `mark_spec_ready` and do NOT re-run consensus. On `queued` or `already_running`, tell the user it was launched and END your turn \u2014 do NOT poll or call it again; the result arrives in the inbox (an `info` item on CONVERGED, a `handoff` item if it was blocked/failed). When a consensus `info` item says CONVERGED, proceed to `create_execution_run`. When a `handoff` says it was blocked, address the recorded issues in the spec (any edit re-arms the gate) and call `run_spec_consensus` once more. For a NON-code task (domain seo/marketing/content, ADR 0020) the spec is review-only \u2014 do NOT call `create_execution_run` (non-code execution is not yet supported and fail-closes); tell the operator the spec was reviewed.",
     '- When a task needs a browser (login flows, UI verification/clicks, scraping), pass `prerequisites:[{mcp:"mrrlin-browser",reason:"..."}]` to `create_execution_run`. If that run later fails into a handoff, the operator gets a one-click "Launch browser & resume" that brings up the dedicated browser as the turn starts.',
     "- When you actually drive a browser (calling `browser_navigate`, `browser_click`, `browser_snapshot`, `browser_type`, etc.), invoke those tools from the **`mrrlin-browser`** MCP server ONLY. Do NOT use tools from any other browser MCP (`playwright`, `chrome-devtools`, `puppeteer`, etc.) even if they are also connected on this operator's box \u2014 those use a shared/default Playwright profile that is fragile across runs. Only `mrrlin-browser` uses this project's dedicated Chromium + persistent operator profile (`~/.mrrlin/browser/profile`). If your host exposes multiple browser MCPs with overlapping tool names, prefer the `mrrlin-browser` server unconditionally.",
     "",
@@ -44220,8 +44677,12 @@ function buildThreadStartParams(msg, config2, desiredModel) {
     "  assumption on the spec page.",
     "- For any such task-affecting question, ALSO bank it durably before your final reply:",
     '  `create_inbox_item` with `kind="question"`, `taskId` set, `directorSessionId` from the',
-    "  Context JSON, and `body` = the exact question. (The server dedups identical open",
-    "  questions; do not supply a dedup key.)",
+    "  Context JSON, `body` = the exact question, and `questionOptions` = 2-3 concrete answer",
+    "  options. Each option MUST include a short `label`, a concise `description`, and a",
+    "  self-contained durable `answer`; you MAY mark at most one option as `recommended` when",
+    "  you explicitly prefer a path. The operator always has a custom-answer path in the UI, so",
+    "  your options should guide, not trap. (The server dedups identical open questions; do not",
+    "  supply a dedup key.)",
     "- When the operator answers in chat, write the answer into the Specs/{taskId}",
     '  Clarifications section, then `decide_inbox_item` the question with `verdict="acknowledged"`',
     "  and `answer` = the resolved answer.",
@@ -44552,6 +45013,24 @@ function attachBridgeWss(server, opts) {
       return;
     }
     const span = { id: "conn", at: 0 };
+    let isAlive = true;
+    socket.on("pong", () => {
+      isAlive = true;
+    });
+    const pingTimer = setInterval(() => {
+      if (socket.readyState !== socket.OPEN) return;
+      if (!isAlive) {
+        socket.terminate();
+        return;
+      }
+      isAlive = false;
+      try {
+        socket.ping();
+      } catch {
+      }
+    }, wsPingMs());
+    pingTimer.unref?.();
+    socket.on("close", () => clearInterval(pingTimer));
     const send = (msg) => {
       if (socket.readyState !== socket.OPEN) return;
       logger?.logOut({
@@ -44595,6 +45074,20 @@ function attachBridgeWss(server, opts) {
 }
 var TurnInterruptedError = class extends Error {
 };
+var DEFAULT_WS_PING_SECONDS = 30;
+function wsPingMs() {
+  const raw = (process.env.MRRLIN_DIRECTOR_BRIDGE_WS_PING_SECONDS ?? "").trim();
+  const parsed = Number.parseInt(raw, 10);
+  return (Number.isInteger(parsed) && parsed > 0 ? parsed : DEFAULT_WS_PING_SECONDS) * 1e3;
+}
+async function waitFor(pred, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (pred()) return true;
+    await new Promise((r) => setTimeout(r, 25));
+  }
+  return pred();
+}
 function attachSeqMetadata(msg, seq, turnId) {
   if (msg.type === "event" || msg.type === "rateLimits" || msg.type === "error") {
     return { ...msg, seq, turnId };
@@ -44653,11 +45146,11 @@ function createBridgeMessageHandler(deps) {
         logResumeRejected(req.directorSessionId, "superseded");
         return;
       }
-      const tail2 = eventsAfter(buf, req.lastSeq);
+      let tail2 = eventsAfter(buf, req.lastSeq);
+      let truncated = false;
       if (tail2 === null) {
-        sendMsg({ type: "resume", status: "no-buffer", reason: "evicted" });
-        logResumeRejected(req.directorSessionId, "evicted");
-        return;
+        truncated = true;
+        tail2 = [...buf.events];
       }
       const result = transition(buf.state, { kind: "resume", epochMatch: true });
       if (result.next === "invalid") {
@@ -44669,7 +45162,14 @@ function createBridgeMessageHandler(deps) {
       buf.replaying = true;
       deps.bindSessionSink?.(req.directorSessionId, send);
       boundSessions.add(req.directorSessionId);
-      if (buf.triggerGrace) socket.once("close", buf.triggerGrace);
+      if (buf.triggerDetach) {
+        const detach = buf.triggerDetach;
+        const epochAtBind = buf.bindEpoch;
+        socket.once("close", () => {
+          if (buf.bindEpoch !== epochAtBind) return;
+          detach();
+        });
+      }
       const willStreamLive = result.next === "live";
       sendMsg({
         type: "resume",
@@ -44682,6 +45182,14 @@ function createBridgeMessageHandler(deps) {
         eventCount: tail2.length,
         willStreamLive
       });
+      if (truncated) {
+        sendMsg({
+          type: "replay-truncated",
+          directorSessionId: req.directorSessionId,
+          turnId: buf.turnId,
+          droppedBelowSeq: tail2[0]?.seq ?? buf.lastSeq
+        });
+      }
       for (const { msg: bufferedMsg } of tail2) sendMsg(bufferedMsg);
       for (const m of buf.outboundQueue) sendMsg(m);
       buf.outboundQueue.length = 0;
@@ -44760,26 +45268,36 @@ function createBridgeMessageHandler(deps) {
         let models = null;
         let rateLimits = null;
         let bootstrapError;
+        const fallbackModels = readCodexFallbackModels();
         try {
           const codexClient2 = await deps.acquireCodex();
           try {
             try {
-              const res = await codexClient2.model.list({});
+              const res = await codexClient2.model.list({ includeHidden: true });
               const raw = res.data ?? res.models ?? [];
-              models = raw.filter((m) => m.hidden !== true).map((m) => ({
-                id: m.id,
-                model: m.model ?? m.id,
-                displayName: m.displayName ?? m.model ?? m.id,
-                description: m.description ?? "",
-                supportedReasoningEfforts: (m.supportedReasoningEfforts ?? []).map((o) => ({
-                  reasoningEffort: o.reasoningEffort,
-                  description: o.description ?? ""
-                })),
-                defaultReasoningEffort: m.defaultReasoningEffort ?? null,
-                isDefault: m.isDefault === true
-              }));
+              const mergedModels = /* @__PURE__ */ new Map();
+              for (const m of raw) {
+                const modelSlug = (m.model ?? m.id ?? "").trim();
+                if (!modelSlug) continue;
+                if (m.hidden === true && (modelSlug.startsWith("codex-") || !modelSlug.startsWith("gpt-"))) continue;
+                addBridgeModel(
+                  mergedModels,
+                  mapBridgeModel({
+                    id: m.id,
+                    model: m.model ?? m.id,
+                    displayName: m.displayName ?? m.model ?? m.id,
+                    description: m.description ?? "",
+                    supportedReasoningEfforts: m.supportedReasoningEfforts ?? [],
+                    defaultReasoningEffort: m.defaultReasoningEffort ?? null,
+                    isDefault: m.isDefault === true
+                  })
+                );
+              }
+              for (const fallbackModel of fallbackModels) addBridgeModel(mergedModels, fallbackModel);
+              models = [...mergedModels.values()];
             } catch (error51) {
               bootstrapError = error51 instanceof Error ? error51.message : String(error51);
+              models = fallbackModels.length > 0 ? fallbackModels : null;
             }
             try {
               const res = await codexClient2.account.readRateLimits();
@@ -44792,6 +45310,7 @@ function createBridgeMessageHandler(deps) {
           }
         } catch (error51) {
           bootstrapError = error51 instanceof Error ? error51.message : String(error51);
+          models = fallbackModels.length > 0 ? fallbackModels : null;
         }
         sendForSpan({ type: "bootstrap", models, rateLimits, ...deps.bridgeInstanceId ? { bridgeInstanceId: deps.bridgeInstanceId } : {}, ...bootstrapError ? { error: bootstrapError } : {} });
         return;
@@ -44800,6 +45319,20 @@ function createBridgeMessageHandler(deps) {
         handleResumeRequest(msg, sendForSpan);
         return;
       }
+      if (msg.type === "ack") {
+        const ack = msg;
+        const sessionId = typeof ack.directorSessionId === "string" ? ack.directorSessionId.trim() : "";
+        const ackThread = sessionId ? deps.threads.get(sessionId) : void 0;
+        if (ackThread?.replay && typeof ack.turnId === "string" && typeof ack.lastSeq === "number" && recordAck(ackThread.replay, ack.turnId, ack.lastSeq, Date.now())) {
+          logCtx?.logger.logOut({
+            spanId,
+            sessionId,
+            type: "<result-acked>",
+            payload: { sessionId, turnId: ack.turnId, lastSeq: ack.lastSeq }
+          });
+        }
+        return;
+      }
       if (msg.type === "interrupt") {
         const directorSessionId2 = (msg.directorSessionId ?? "").trim();
         const existing = directorSessionId2 ? deps.threads.get(directorSessionId2) : void 0;
@@ -44808,12 +45341,11 @@ function createBridgeMessageHandler(deps) {
           return;
         }
         const interruptBuf = existing.replay;
-        if (interruptBuf && interruptBuf.state === "grace") {
-          const stopResult = transition("grace", { kind: "stop" });
+        if (interruptBuf && interruptBuf.state === "detached") {
+          const stopResult = transition("detached", { kind: "stop" });
           if (stopResult.next !== "invalid") {
             interruptBuf.state = stopResult.next;
-            cancelGrace(interruptBuf);
-            recordInterrupted(interruptBuf);
+            recordInterrupted(interruptBuf, Date.now(), deps.suspendedMs?.() ?? 0);
           }
         }
         const codexClient2 = await deps.acquireCodex();
@@ -44875,6 +45407,36 @@ function createBridgeMessageHandler(deps) {
       }
       const codexClient = await deps.acquireCodex();
       let thread = deps.threads.get(directorSessionId);
+      if (thread?.inFlight && msg.takeover === true) {
+        const takenOver = thread;
+        const oldBuf = takenOver.replay;
+        if (oldBuf && (oldBuf.state === "live" || oldBuf.state === "detached")) {
+          const r = transition(oldBuf.state, { kind: "stop" });
+          if (r.next !== "invalid") {
+            oldBuf.state = r.next;
+            recordInterrupted(oldBuf, Date.now(), deps.suspendedMs?.() ?? 0);
+          }
+        }
+        takenOver.cancel?.();
+        void withTimeout(
+          codexClient.turn.interrupt({ threadId: takenOver.threadId }),
+          DEFAULT_TURN_INTERRUPT_TIMEOUT_MS,
+          "interrupt timed out"
+        ).catch(() => {
+        });
+        const cleared = await waitFor(() => !takenOver.inFlight, DEFAULT_TURN_INTERRUPT_TIMEOUT_MS);
+        if (!cleared) {
+          deps.threads.delete(directorSessionId);
+          deps.persistThreads();
+          thread = void 0;
+        }
+        logCtx?.logger.logOut({
+          spanId,
+          sessionId: directorSessionId,
+          type: "<turn-takeover>",
+          payload: { sessionId: directorSessionId, clean: cleared, oldTurnId: oldBuf?.turnId ?? null }
+        });
+      }
       const desiredModel = normalizeModel(msg.model);
       const desiredEffort = normalizeReasoningEffort(msg.reasoningEffort);
       try {
@@ -44932,7 +45494,13 @@ function createBridgeMessageHandler(deps) {
         return;
       }
       if (thread.inFlight) {
-        sendForSpan({ type: "error", directorSessionId, error: "Director session is busy." });
+        sendForSpan({
+          type: "error",
+          directorSessionId,
+          code: "busy",
+          ...thread.replay ? { inFlightTurnId: thread.replay.turnId } : {},
+          error: "Director session is busy."
+        });
         deps.releaseCodex();
         return;
       }
@@ -44940,7 +45508,8 @@ function createBridgeMessageHandler(deps) {
       thread.replay = createReplayBuffer({
         turnId: (0, import_node_crypto5.randomUUID)(),
         spanId,
-        ...deps.turnGraceMs !== void 0 ? { graceMs: deps.turnGraceMs } : {}
+        ...deps.retentionMs !== void 0 ? { retentionMs: deps.retentionMs } : {},
+        ...deps.ackLingerMs !== void 0 ? { ackLingerMs: deps.ackLingerMs } : {}
       });
       thread.lastUsedAt = Date.now();
       const threadId = thread.threadId;
@@ -45031,6 +45600,7 @@ function createBridgeMessageHandler(deps) {
           const watchdog = createInactivityWatchdog({
             idleMs,
             maxMs,
+            ...deps.suspendedMs ? { suspendedMs: deps.suspendedMs } : {},
             onExpire: (reason) => {
               rejectWatchdog?.(
                 new Error(
@@ -45039,48 +45609,36 @@ function createBridgeMessageHandler(deps) {
               );
               void withTimeout(codexClient.turn.interrupt({ threadId }), DEFAULT_TURN_INTERRUPT_TIMEOUT_MS, "interrupt timed out").catch(
                 () => {
-                  deps.threads.delete(directorSessionId);
-                  deps.persistThreads();
+                  if (deps.threads.get(directorSessionId) === thread) {
+                    deps.threads.delete(directorSessionId);
+                    deps.persistThreads();
+                  }
                 }
               );
             }
           });
+          const turnBuf = thread.replay;
           const onSocketClose = () => {
             const buf = thread.replay;
-            if (!buf || buf.state !== "live") return;
-            const r = transition("live", { kind: "socket_close" });
-            if (r.next === "invalid") return;
+            if (!buf || buf !== turnBuf) return;
+            const r = transition(buf.state, { kind: "socket_close" });
+            if (r.next === "invalid" || r.next === buf.state) return;
             buf.state = r.next;
             logCtx?.logger.logOut({
               spanId,
               sessionId: directorSessionId,
-              type: "<resume-grace-started>",
-              payload: { sessionId: directorSessionId, turnId: buf.turnId, graceMs: buf.graceMs }
-            });
-            enterGrace(buf, () => {
-              const expired = transition("grace", { kind: "grace_expire" });
-              if (expired.next === "invalid") return;
-              buf.state = expired.next;
-              recordInterrupted(buf);
-              logCtx?.logger.logOut({
-                spanId,
-                sessionId: directorSessionId,
-                type: "<grace-expired>",
-                payload: { sessionId: directorSessionId, turnId: buf.turnId, lastSeq: buf.lastSeq }
-              });
-              rejectWatchdog?.(new TurnInterruptedError());
-              void withTimeout(
-                codexClient.turn.interrupt({ threadId }),
-                DEFAULT_TURN_INTERRUPT_TIMEOUT_MS,
-                "interrupt timed out"
-              ).catch(() => {
-                deps.threads.delete(directorSessionId);
-                deps.persistThreads();
-              });
+              type: "<buffer-detached>",
+              payload: { sessionId: directorSessionId, turnId: buf.turnId, lastSeq: buf.lastSeq }
             });
           };
-          socket.once("close", onSocketClose);
-          if (thread.replay) thread.replay.triggerGrace = onSocketClose;
+          {
+            const epochAtBind = turnBuf?.bindEpoch ?? 0;
+            socket.once("close", () => {
+              if (turnBuf && turnBuf.bindEpoch !== epochAtBind) return;
+              onSocketClose();
+            });
+          }
+          if (thread.replay) thread.replay.triggerDetach = onSocketClose;
           pokeActivity = () => watchdog.poke();
           const runSequence = (async () => {
             const turnInput = [];
@@ -45129,10 +45687,20 @@ ${effectiveText}` : effectiveText;
               sendInTurn({ type: "event", directorSessionId, event });
             }
           } finally {
-            if (thread.replay && thread.replay.state === "live") {
-              markCompleted(thread.replay, Date.now());
+            if (thread.replay && (thread.replay.state === "live" || thread.replay.state === "detached")) {
+              markCompleted(thread.replay, Date.now(), deps.suspendedMs?.() ?? 0);
+              logCtx?.logger.logOut({
+                spanId,
+                sessionId: directorSessionId,
+                type: "<result-retained>",
+                payload: {
+                  sessionId: directorSessionId,
+                  turnId: thread.replay.turnId,
+                  lastSeq: thread.replay.lastSeq,
+                  bytes: thread.replay.bytesUsed
+                }
+              });
             }
-            socket.off("close", onSocketClose);
             watchdog.cancel();
             unsub();
             thread.cancel = null;
@@ -45439,6 +46007,7 @@ async function startDirectorBridge() {
     })
   );
   const threads = /* @__PURE__ */ new Map();
+  const suspensionDetector = createSuspensionDetector();
   for (const [directorSessionId, entry] of loadThreadIndex(config2.stateDir, config2.idleThreadTtlMs, Date.now())) {
     threads.set(directorSessionId, {
       threadId: entry.threadId,
@@ -45476,6 +46045,7 @@ async function startDirectorBridge() {
     let changed = false;
     for (const [directorSessionId, thread] of threads.entries()) {
       if (thread.inFlight) continue;
+      if (thread.replay && !shouldGc(thread.replay, now, suspensionDetector.suspendedMs())) continue;
       if (now - thread.lastUsedAt > config2.idleThreadTtlMs) {
         threads.delete(directorSessionId);
         changed = true;
@@ -45491,6 +46061,7 @@ async function startDirectorBridge() {
     acquireCodex: () => codexKeepalive.acquire(),
     releaseCodex: () => codexKeepalive.release(),
     runExclusive: wrappedTurnLock.runExclusive,
+    suspendedMs: () => suspensionDetector.suspendedMs(),
     buildStartParams: (msg, desiredModel) => buildThreadStartParams(msg, config2, desiredModel),
     turnInactivity: () => ({ idleMs: chatTurnIdleMs(), maxMs: chatTurnMaxMs() }),
     checkoutRegistry,
@@ -45653,20 +46224,35 @@ async function startDirectorBridge() {
       );
       enqueueRun(async () => {
         const now = Date.now();
+        const suspendedNow = suspensionDetector.suspendedMs();
+        let retainedBuffers = 0;
+        let retainedBytes = 0;
         for (const [sid, t] of threads) {
-          if (t.replay && shouldGc(t.replay, now)) {
+          if (t.replay && shouldGc(t.replay, now, suspendedNow)) {
             const turnId = t.replay.turnId;
             const lastSeq = t.replay.lastSeq;
+            const expiredUnacked = t.replay.ackedAt === null;
             writeTombstone(tombstones, sid, t.replay, now);
             bridgeLogger.logOut({
               spanId: "gc",
               sessionId: sid,
-              type: "<tombstone-written>",
+              type: expiredUnacked ? "<result-expired>" : "<tombstone-written>",
               payload: { sessionId: sid, turnId, lastSeq }
             });
             t.replay = null;
+          } else if (t.replay) {
+            retainedBuffers += 1;
+            retainedBytes += t.replay.bytesUsed;
           }
         }
+        if (retainedBuffers > 0) {
+          bridgeLogger.logOut({
+            spanId: "gc",
+            sessionId: null,
+            type: "<buffer-stats>",
+            payload: { retainedBuffers, retainedBytes }
+          });
+        }
         const removed = sweepExpiredTombstones(tombstones, now);
         if (removed > 0) {
           bridgeLogger.logOut({
@@ -45721,6 +46307,7 @@ async function startDirectorBridge() {
       () => server.close(),
       () => dispatchServer.close(),
       () => clearInterval(cleanupTimer),
+      () => suspensionDetector.dispose(),
       () => remoteRelay?.stop(),
       () => tokenRefresher?.stop(),
       () => {
@@ -49624,8 +50211,91 @@ ${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/heads.ts
+var DEFAULT_DOMAIN = "code";
+var DOMAINS = ["code", "seo", "marketing", "content"];
+var HEADS_BY_DOMAIN = {
+  code: ["plan-reviewer", "architect", "security-analyst", "scope-analyst"],
+  seo: ["plan-reviewer", "scope-analyst", "seo-analyst"],
+  marketing: ["plan-reviewer", "scope-analyst", "content-editor"],
+  content: ["plan-reviewer", "scope-analyst", "content-editor"]
+};
+var SPEC_HEADS = HEADS_BY_DOMAIN.code;
+function normalizeDomain(value) {
+  if (typeof value !== "string") return DEFAULT_DOMAIN;
+  const v = value.trim().toLowerCase();
+  return DOMAINS.includes(v) ? v : DEFAULT_DOMAIN;
+}
+function resolveHeads(domain2) {
+  return [...HEADS_BY_DOMAIN[normalizeDomain(domain2)]];
+}
+
 // src/consensus/spec-gate.ts
-var SPEC_HEADS = ["plan-reviewer", "architect", "security-analyst", "scope-analyst"];
 async function runSpecGate(_target, deps, opts) {
   if (!await deps.consensusEnabled()) return { outcome: "SKIPPED" };
   const intent = await deps.readIntent();
@@ -49641,10 +50311,12 @@ async function runSpecGate(_target, deps, opts) {
       ]
     };
   }
+  const baseHeads = resolveHeads(intent.domain);
   const extraHeads = opts?.extraHeads ?? [];
-  const heads = [...SPEC_HEADS, ...extraHeads.filter((h) => !SPEC_HEADS.includes(h))];
+  const heads = [...baseHeads, ...extraHeads.filter((h) => !baseHeads.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,
@@ -49656,12 +50328,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
@@ -49671,6 +50351,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,
@@ -49888,6 +50584,40 @@ 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/review-identity.ts
+function domainScopedReviewHash(rawHash, domain2) {
+  const d = normalizeDomain(domain2);
+  return d === "code" ? rawHash : `${rawHash}@${d}`;
+}
+async function resolveSpecDomain(client, projectSlug, page) {
+  try {
+    const taskId = await resolveGatedTaskId(client, projectSlug, page);
+    if (taskId !== null) {
+      const task = await client.getTask(projectSlug, taskId);
+      return normalizeDomain(task?.domain);
+    }
+    const project = await client.getProject(projectSlug);
+    return normalizeDomain(project?.defaultDomain);
+  } catch {
+    return "code";
+  }
+}
+
 // src/consensus/code-gate-git.ts
 var import_node_child_process6 = require("node:child_process");
 var DIFF_MAX_BYTES = 2e5;
@@ -50132,6 +50862,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);
@@ -50142,10 +50889,19 @@ 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) {
+          const project = await client.getProject(projectSlug);
+          return { taskId: null, seed: null, title: null, domain: project.defaultDomain };
+        }
         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 ?? "", domain: task.domain };
       })();
     }
     return intentPromise;
@@ -50170,11 +50926,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.
@@ -50205,6 +50958,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:
@@ -50212,7 +50966,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,9 +51017,10 @@ ${artifact}`,
       }
       const outcome = r["outcome"];
       const rounds2 = r["rounds"];
+      const { domain: domain2 } = await loadIntent();
       try {
         await client.recordSpecConsensusReview(projectSlug, specPageId, {
-          contentHash,
+          contentHash: domainScopedReviewHash(contentHash, domain2),
           outcome: String(outcome),
           rounds: typeof rounds2 === "number" ? rounds2 : 0
         });
@@ -50358,11 +51113,51 @@ ${artifact}`,
 
 // src/async-tools/consensus.ts
 var import_node_crypto6 = require("node:crypto");
+function buildGateQuestionOptions(category) {
+  if (category === "scope") {
+    return [
+      {
+        answer: "Use the narrower scope only. Update the spec to keep the original limited scope and do not add the broader interpretation unless explicitly required.",
+        description: "Do only the originally requested narrower scope and leave the broader bucket out unless explicitly required.",
+        label: "Narrower"
+      },
+      {
+        answer: "Use the broader scope. Update the spec to explicitly include the broader interpretation and any required acceptance criteria.",
+        description: "Treat the broader interpretation as in scope and spell out the extra acceptance criteria it adds.",
+        label: "Broader"
+      }
+    ];
+  }
+  return [
+    {
+      answer: "Use the safer/default interpretation. Update the spec to document that assumption explicitly.",
+      description: "Choose the lower-risk default interpretation and record it explicitly so implementation is unblocked.",
+      label: "Safer default"
+    },
+    {
+      answer: "Use the broader/stronger interpretation. Update the spec to make that interpretation explicit.",
+      description: "Commit to the stronger interpretation instead of a conservative default, and update the spec to match.",
+      label: "Stronger interpretation"
+    }
+  ];
+}
 async function cachedResult(client, input) {
   const page = await client.getWikiPage(input.projectSlug, input.pageId);
   if (!page) return null;
-  const review = await client.getSpecConsensusReview(input.projectSlug, input.pageId, page.contentHash);
+  const domain2 = await resolveSpecDomain(client, input.projectSlug, { id: page.id, taskId: page.taskId ?? null });
+  const review = await client.getSpecConsensusReview(
+    input.projectSlug,
+    input.pageId,
+    domainScopedReviewHash(page.contentHash, domain2)
+  );
   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") {
@@ -50404,7 +51199,8 @@ async function run(ctx, input) {
               kind: "question",
               taskId: scopeId,
               body: clarification.question,
-              origin: "gate"
+              origin: "gate",
+              questionOptions: buildGateQuestionOptions(clarification.category)
             });
           } catch {
           }
@@ -50419,7 +51215,8 @@ async function run(ctx, input) {
               kind: "question",
               planId: scopeId,
               body: clarification.question,
-              origin: "gate"
+              origin: "gate",
+              questionOptions: buildGateQuestionOptions(clarification.category)
             });
           } catch {
           }
@@ -51353,7 +52150,7 @@ var mcpToolDescriptions = {
   [mcpToolNames.resetDirectorThread]: "Clear a task's persisted Director execution thread handle so the next execution run starts a fresh provider thread. Records a director_thread_reset task event.",
   [mcpToolNames.updateWikiPage]: "Update a markdown Wiki page.",
   [mcpToolNames.markSpecReady]: "Mark a wiki page (folder=Specs) as ready (or not) for execution-run gating. The Director sets this true after validating the spec; any edit to the page's markdown auto-resets it to false.",
-  [mcpToolNames.runSpecConsensus]: 'Enqueue the consensus review gate over a Specs/{id} page. Returns IMMEDIATELY with one of: already_converged (a CONVERGED review already exists for the current content \u2014 proceed straight to create_execution_run, do NOT call mark_spec_ready, it is already set), already_reviewed (a terminal CONSENSUS_BLOCKED for this content), already_running (a consensus job is in flight), or queued (a new job was launched). The review runs in the background; its result/blocker arrives in the inbox (info on CONVERGED, handoff on failure) and is surfaced into the open chat. Do NOT call again for the same spec and do NOT poll. On queued/already_running, tell the user it was launched and end the turn. Pass extraHeads: ["researcher"] for specs referencing external libraries/APIs, or ["debugger"] for root-cause/investigation specs to add opt-in specialist reviewers on top of the fixed four.',
+  [mcpToolNames.runSpecConsensus]: 'Enqueue the consensus review gate over a Specs/{id} page. Returns IMMEDIATELY with one of: already_converged (a CONVERGED review already exists for the current content \u2014 proceed straight to create_execution_run, do NOT call mark_spec_ready, it is already set), already_reviewed (a terminal CONSENSUS_BLOCKED for this content), already_running (a consensus job is in flight), or queued (a new job was launched). The review runs in the background; its result/blocker arrives in the inbox (info on CONVERGED, handoff on failure) and is surfaced into the open chat. Do NOT call again for the same spec and do NOT poll. On queued/already_running, tell the user it was launched and end the turn. Pass extraHeads: ["researcher"] for specs referencing external libraries/APIs, or ["debugger"] for root-cause/investigation specs to add opt-in specialist reviewers on top of the fixed four. For a NON-code task (domain seo/marketing/content, ADR 0020) the spec is REVIEW-ONLY: do NOT call create_execution_run (it fail-closes with non_code_execution_unsupported until Phase 2) \u2014 report that the spec was reviewed and end the turn.',
   [mcpToolNames.runCodeReviewerGate]: `Review the current branch's code diff (vs baseRef) with a Code Reviewer gate \u2014 independent reviewers iterate review\u2192fix\u2192re-check (checkpoint, scope-limited reviser edits, typecheck/build fast-gate, rollback) until the diff converges or is blocked. Run before opening a PR. Pass extraHeads: ["security-analyst"] for sensitive diffs (auth, secrets, input handling, new endpoints).`,
   [mcpToolNames.appendExecutionArtifact]: "Append a durable artifact (plan, checkpoint, command output, test result, diff summary, self-review, error, deploy attempt, or handoff judgement) to an execution run.",
   [mcpToolNames.recordProducedUrl]: 'Call this after publishing each web page produced by the task, so the UI link opens the page itself instead of the deployed site root. Pass the page\'s full https URL (for external pages, e.g. "https://dev.to/<slug>") OR a path starting with "/" for the deploy environment (e.g. "/blog/<slug>") \u2014 paths are resolved against the run\'s deployed env URL at render time. Optional `label` (\u226440 chars) is shown next to the link; omit and the UI defaults to the page title. Call once per page; multiple calls dedupe by resolved URL in the UI.',
@@ -51810,7 +52607,12 @@ function createMrrlinTools(options) {
         if (!page || page.folder !== "Specs") {
           return await c.markSpecReady({ projectSlug, pageId, ready });
         }
-        const review = await c.getSpecConsensusReview(projectSlug, pageId, page.contentHash);
+        const reviewDomain = await resolveSpecDomain(c, projectSlug, { id: page.id, taskId: page.taskId ?? null });
+        const review = await c.getSpecConsensusReview(
+          projectSlug,
+          pageId,
+          domainScopedReviewHash(page.contentHash, reviewDomain)
+        );
         if (review && review.outcome === "CONVERGED") {
           try {
             const promotion = await c.promoteSpecReadyCas(projectSlug, pageId, {
@@ -52585,6 +53387,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,
@@ -52631,8 +53440,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)
 
@@ -52747,6 +53566,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}
 `);