omnius 1.0.459 → 1.0.461

package/dist/index.js

@@ -566100,6 +566100,11 @@ var init_personality = __esm({
 // packages/orchestrator/dist/critic.js
 function buildCriticGuidanceMessage(call, hits, opts = {}) {
   const argPreview = JSON.stringify(call.args ?? {}).slice(0, 200);
+  const actionReason = call.actionReason ? [
+    call.actionReason.scope ? `scope=${call.actionReason.scope}` : "",
+    call.actionReason.intent ? `intent=${call.actionReason.intent}` : "",
+    call.actionReason.evidence ? `evidence=${call.actionReason.evidence}` : ""
+  ].filter(Boolean).join("; ").slice(0, 500) : "";
   const cached = opts.cachedResult ? `
 Prior evidence preview:
 ${opts.cachedResult.slice(0, 700)}` : "";
@@ -566107,7 +566112,8 @@ ${opts.cachedResult.slice(0, 700)}` : "";
   return `[RUNTIME EVIDENCE CACHE — non-blocking]
 Observation: ${source}
 Call: ${call.tool}(${argPreview})
-State: exact prior evidence exists for these arguments in the current state version.
+` + (actionReason ? `Action reason: ${actionReason}
+` : "") + `State: exact prior evidence exists for these arguments in the current state version.
 Next action contract: let this result inform the next step once, then pivot to a concrete action.
 Suggested next actions: edit/write the implicated file, run verification, read a different specific file, or complete with evidence. Prefer not to repeat this exact call again unless the filesystem, browser, or page state changed.${cached}`;
 }
@@ -573220,6 +573226,7 @@ var init_context_fabric = __esm({
       GOAL: 100,
       ACTION_CONTRACT: 98,
       USER_STEERING: 95,
+      RUNTIME_GUIDANCE: 94,
       TASK_STATE: 80,
       KNOWN_FILES: 70,
       RECENT_FAILURE: 65,
@@ -573236,6 +573243,7 @@ var init_context_fabric = __esm({
     KIND_ORDER = [
       "goal",
       "user_steering",
+      "runtime_guidance",
       "action_contract",
       "task_state",
       "known_files",
@@ -573253,6 +573261,7 @@ var init_context_fabric = __esm({
     KIND_LABELS = {
       goal: "Goal",
       user_steering: "User Steering",
+      runtime_guidance: "Runtime Guidance",
       action_contract: "Next Action Contract",
       task_state: "Task State",
       known_files: "Known Files",
@@ -573270,6 +573279,7 @@ var init_context_fabric = __esm({
     DEFAULT_KIND_CHAR_BUDGET = {
       goal: 900,
       user_steering: 1400,
+      runtime_guidance: 1800,
       action_contract: 1800,
       task_state: 1800,
       known_files: 2400,
@@ -573983,6 +573993,8 @@ ${obs.stateDigest.slice(0, 1800)}
       `This is a loop. Reason about WHY — for THIS specific call, not generically.`,
       ls2.alreadyHave ? `Evidence the agent ALREADY obtained from a prior identical call:
 ${ls2.alreadyHave.slice(0, 900)}` : `(No cached result available for the repeated call.)`,
+      ls2.actionReason ? `Agent's stated action reason:
+  scope=${ls2.actionReason.scope ?? ""}; intent=${ls2.actionReason.intent ?? ""}; evidence=${ls2.actionReason.evidence ?? ""}; expected=${ls2.actionReason.expected_result ?? ""}`.slice(0, 700) : "",
       "",
       stateDigest.trim(),
       "",
@@ -574384,6 +574396,7 @@ function recordDebugToolEvent(input) {
     },
     ...input.focusSupervisor ? { focusSupervisor: input.focusSupervisor } : {},
     ...input.focusDecision ? { focusDecision: input.focusDecision } : {},
+    ...input.actionReason ? { actionReason: compactDebugValue(input.actionReason) } : {},
     ...input.repeatShortCircuit !== void 0 ? { repeatShortCircuit: input.repeatShortCircuit } : {},
     ...input.runtimeAuthored !== void 0 ? { runtimeAuthored: input.runtimeAuthored } : {},
     ...input.runtimeGuidance ? { runtimeGuidancePreview: trim(input.runtimeGuidance, 1200) } : {},
@@ -575053,6 +575066,30 @@ function trim(value2, max) {
   return `${value2.slice(0, max)}
 [truncated ${value2.length - max} chars]`;
 }
+function compactDebugValue(value2, depth = 0) {
+  if (value2 == null)
+    return value2;
+  if (typeof value2 === "string") {
+    return value2.length > 500 ? `${value2.slice(0, 497)}...` : value2;
+  }
+  if (typeof value2 === "number" || typeof value2 === "boolean")
+    return value2;
+  if (Array.isArray(value2)) {
+    if (depth >= 2)
+      return `[array:${value2.length}]`;
+    return value2.slice(0, 8).map((entry) => compactDebugValue(entry, depth + 1));
+  }
+  if (typeof value2 === "object") {
+    if (depth >= 2)
+      return "[object]";
+    const out = {};
+    for (const [key, entry] of Object.entries(value2).slice(0, 12)) {
+      out[key] = compactDebugValue(entry, depth + 1);
+    }
+    return out;
+  }
+  return String(value2);
+}
 function safeId2(value2) {
   return String(value2 || "unknown").replace(/[^a-zA-Z0-9_.:-]/g, "_").slice(0, 160);
 }
@@ -575094,6 +575131,9 @@ function violatesDirective(directive, input) {
   }
   if (input.toolName === "ask_user")
     return false;
+  if (directive.requiredNextAction === "read_authoritative_target" && input.usesAuthoritativeTargetEvidence && isEditTool(input.toolName)) {
+    return false;
+  }
   const family = actionFamily(input.toolName, input.args);
   if (directive.requiredNextAction !== "update_todos") {
     if (directive.forbiddenActionFamilies.includes(family))
@@ -575181,6 +575221,17 @@ function compactCachedEvidence(text2) {
     "Use the cached evidence now, or request a distinct offset/limit/query if genuinely needed."
   ].filter(Boolean).join("\n");
 }
+function actionReasonSummary(actionReason) {
+  if (!actionReason)
+    return "";
+  const parts = [
+    actionReason.scope ? `scope=${actionReason.scope}` : "",
+    actionReason.intent ? `intent=${actionReason.intent}` : "",
+    actionReason.evidence ? `evidence=${actionReason.evidence}` : "",
+    actionReason.expected_result ? `expected=${actionReason.expected_result}` : ""
+  ].filter(Boolean);
+  return parts.length > 0 ? `Action reason observed: ${parts.join("; ").slice(0, 700)}` : "";
+}
 function actionFamily(toolName, args) {
   if (isEditTool(toolName)) {
     const path12 = primaryPath(args);
@@ -575404,8 +575455,9 @@ var init_focusSupervisor = __esm({
                 `${reason}.`,
                 `Required next action: ${prior.requiredNextAction}.`,
                 `Blocked action family: ${family}.`,
+                actionReasonSummary(input.actionReason),
                 "This block is not counted as a new ignored directive."
-              ].join("\n"), false);
+              ].filter(Boolean).join("\n"), false);
             }
             return this.pass();
           }
@@ -575446,8 +575498,9 @@ var init_focusSupervisor = __esm({
               `[FOCUS SUPERVISOR BLOCK] The previous directive was ignored: ${prior.reason}`,
               `Required next action: ${directive.requiredNextAction}.`,
               `Blocked action family: ${family}.`,
+              actionReasonSummary(input.actionReason),
               directive.requiredNextAction === "report_incomplete" ? "Stop trying tool variants. Report incomplete/blocked with the concrete evidence." : "Take the required next action before trying another variant."
-            ].join("\n"), false);
+            ].filter(Boolean).join("\n"), false);
           }
         }
         if (input.stalePreflightMessage) {
@@ -575458,9 +575511,12 @@ var init_focusSupervisor = __esm({
             requiredNextAction: "read_authoritative_target",
             forbiddenActionFamilies: [family]
           });
-          return this.block(directive, `${input.stalePreflightMessage}
-
-[FOCUS SUPERVISOR] Required next action: file_read the authoritative current target once, then build a new edit from current evidence or report incomplete.`, false);
+          return this.block(directive, [
+            input.stalePreflightMessage,
+            "",
+            actionReasonSummary(input.actionReason),
+            "[FOCUS SUPERVISOR] Required next action: file_read the authoritative current target once, then build a new edit from current evidence or report incomplete."
+          ].filter(Boolean).join("\n"), false);
         }
         const duplicateHitCount = input.duplicateHitCount ?? 0;
         if (input.cachedResult && duplicateHitCount > 0) {
@@ -575480,9 +575536,10 @@ var init_focusSupervisor = __esm({
               input.cachedResultFailed ? "[FOCUS SUPERVISOR: CACHED FAILURE]" : "[FOCUS SUPERVISOR: CACHED EVIDENCE]",
               `This ${input.toolName} action family has already produced evidence and should not be re-executed unchanged.`,
               `Required next action: ${directive.requiredNextAction}.`,
+              actionReasonSummary(input.actionReason),
               "",
               compactCachedEvidence(input.cachedResult)
-            ].join("\n"), !input.cachedResultFailed);
+            ].filter(Boolean).join("\n"), !input.cachedResultFailed);
           }
           return this.inject(directive, `[FOCUS SUPERVISOR] ${directive.reason}. Required next action: ${directive.requiredNextAction}.`);
         }
@@ -575536,6 +575593,10 @@ var init_focusSupervisor = __esm({
           this.lastReason = "cached/no-op tool result did not perform the required recovery action";
           return;
         }
+        if (input.success && input.usedAuthoritativeTargetEvidence && isEditTool(input.toolName) && this.directive?.requiredNextAction === "read_authoritative_target") {
+          this.clearSatisfiedDirective("verified edit used authoritative target evidence", input.turn);
+          return;
+        }
         if (input.toolName === "file_read" && input.success) {
           if (this.directive?.requiredNextAction === "read_authoritative_target") {
             this.clearSatisfiedDirective("authoritative evidence refreshed", input.turn);
@@ -578219,7 +578280,9 @@ function sanitizeHistoryThink(messages2) {
   const stripped = messages2.map((m2) => {
     if (m2.role !== "assistant" || typeof m2.content !== "string")
       return m2;
-    return { ...m2, content: stripThinkBlocks(m2.content) };
+    const withoutThink = stripThinkBlocks(m2.content);
+    const collapsed = collapseDegenerateAssistantRepetition(withoutThink);
+    return { ...m2, content: collapsed ?? withoutThink };
   });
   const sanitized = [];
   for (let i2 = 0; i2 < stripped.length; i2++) {
@@ -578231,6 +578294,35 @@ function sanitizeHistoryThink(messages2) {
   }
   return sanitized;
 }
+function collapseDegenerateAssistantRepetition(content) {
+  const trimmed = content.trim();
+  if (trimmed.length < 160)
+    return null;
+  const lineUnits = trimmed.split(/\n+/).map((line) => line.trim()).filter((line) => line.length >= 12);
+  const sentenceUnits = lineUnits.length >= 3 ? lineUnits : trimmed.split(/(?<=[.!?])\s+/).map((part) => part.trim()).filter((part) => part.length >= 12);
+  if (sentenceUnits.length < 3)
+    return null;
+  const counts = /* @__PURE__ */ new Map();
+  for (const unit of sentenceUnits) {
+    const key = unit.toLowerCase().replace(/\s+/g, " ").slice(0, 220);
+    const current = counts.get(key) ?? { count: 0, chars: 0, sample: unit };
+    current.count++;
+    current.chars += unit.length;
+    counts.set(key, current);
+  }
+  let best = null;
+  for (const value2 of counts.values()) {
+    if (!best || value2.count > best.count || value2.count === best.count && value2.chars > best.chars) {
+      best = value2;
+    }
+  }
+  if (!best || best.count < 3)
+    return null;
+  const repeatedRatio = best.chars / Math.max(1, trimmed.length);
+  if (repeatedRatio < 0.55)
+    return null;
+  return `[assistant repetitive text suppressed: repeated ${best.count}x "${best.sample.slice(0, 180)}"]`;
+}
 function isOrphanDuplicateAssistantToolAnchor(messages2, index, referencedToolCallIds) {
   const current = messages2[index];
   if (!current)
@@ -578385,7 +578477,7 @@ function classifyThinkOutcome(raw) {
   }
   return null;
 }
-var TOOL_SUBSETS, TOOL_AUTO_DEMOTE_TURNS, SYSTEM_PROMPT, SYSTEM_PROMPT_MEDIUM, SYSTEM_PROMPT_SMALL, VISUAL_TOOLS, AUDIO_TOOLS, SOCIAL_TOOLS, SPATIAL_TOOLS, CODE_TOOLS, AgenticRunner, OllamaAgenticBackend;
+var TOOL_SUBSETS, TOOL_AUTO_DEMOTE_TURNS, TOOL_ACTION_REASON_KEYS, TOOL_ACTION_REASON_SCOPES, TOOL_ACTION_REASON_SCHEMA, SYSTEM_PROMPT, SYSTEM_PROMPT_MEDIUM, SYSTEM_PROMPT_SMALL, VISUAL_TOOLS, AUDIO_TOOLS, SOCIAL_TOOLS, SPATIAL_TOOLS, CODE_TOOLS, AgenticRunner, OllamaAgenticBackend;
 var init_agenticRunner = __esm({
   "packages/orchestrator/dist/agenticRunner.js"() {
     "use strict";
@@ -578474,6 +578566,56 @@ var init_agenticRunner = __esm({
       skill: ["skill_list", "skill_extract", "skill_execute", "skill_search"]
     };
     TOOL_AUTO_DEMOTE_TURNS = 10;
+    TOOL_ACTION_REASON_KEYS = /* @__PURE__ */ new Set([
+      "action_reason",
+      "actionReason",
+      "justification"
+    ]);
+    TOOL_ACTION_REASON_SCOPES = /* @__PURE__ */ new Set([
+      "discovery",
+      "targeted_patch",
+      "new_file",
+      "full_file_rewrite",
+      "verification",
+      "state_update",
+      "delegation",
+      "completion",
+      "other"
+    ]);
+    TOOL_ACTION_REASON_SCHEMA = {
+      type: "object",
+      description: "Compact public action contract for this exact tool call. Do not include hidden chain-of-thought; use concise task-state facts.",
+      properties: {
+        task_anchor: {
+          type: "string",
+          description: "One compact phrase tying this call to the active user goal/current focus."
+        },
+        intent: {
+          type: "string",
+          description: "One sentence explaining why this tool is the next action."
+        },
+        evidence: {
+          type: "string",
+          description: "Fresh evidence or contract authorizing the action: file hash, focus directive, cached evidence, user request, or explicit absence."
+        },
+        expected_result: {
+          type: "string",
+          description: "The concrete new state or information expected from this call."
+        },
+        scope: {
+          type: "string",
+          enum: Array.from(TOOL_ACTION_REASON_SCOPES),
+          description: "Classify the action scope. Use targeted_patch for constrained edits; full_file_rewrite only for deliberate whole-file replacement."
+        }
+      },
+      required: [
+        "task_anchor",
+        "intent",
+        "evidence",
+        "expected_result",
+        "scope"
+      ]
+    };
     SYSTEM_PROMPT = loadPrompt("agentic/system-large.md");
     SYSTEM_PROMPT_MEDIUM = loadPrompt("agentic/system-medium.md");
     SYSTEM_PROMPT_SMALL = loadPrompt("agentic/system-small.md");
@@ -578529,6 +578671,7 @@ var init_agenticRunner = __esm({
       _onTypedEvent;
       handlers = [];
       pendingUserMessages = [];
+      pendingRuntimeGuidanceMessages = [];
       aborted = false;
       _abortController = new AbortController();
       _paused = false;
@@ -578908,6 +579051,7 @@ var init_agenticRunner = __esm({
       //
       // Kill switch: OMNIUS_DISABLE_REG61_COERCE=1 disables BOTH set and enforce.
       _reg61PerpetualGateActive = false;
+      _reg61DeferredFocusDirectiveId = null;
       // DECOMP-2 (root-cause from batch531-midi-decomp, 2026-05-03): compelling
       // sub_agent delegation. DECOMP-1's informational directive was ignored
       // (0 sub_agent calls in 466 tool-call run despite directive at turn 1).
@@ -579027,28 +579171,58 @@ var init_agenticRunner = __esm({
         return this.options.workboardDir || this._workingDirectory || process.cwd();
       }
       getOrCreateWorkboard() {
-        if (this._workboard)
+        const goal = this._taskState.originalGoal || this._taskState.goal || "";
+        if (this._workboard) {
+          this._workboard = this._seedWorkboardCardsIfNeeded(this._workboard, goal);
           return this._workboard;
+        }
         const dir = this._workboardDir();
         const runId = this._sessionId;
         const existing = loadWorkboardSnapshot(dir, runId);
         if (existing) {
-          this._workboard = existing;
-          return existing;
+          this._workboard = this._seedWorkboardCardsIfNeeded(existing, goal);
+          return this._workboard;
         }
         try {
           this._workboard = createWorkboard(dir, {
             runId,
             owner: this.options.subAgent ? "sub-agent" : "agent",
-            goal: this._taskState.originalGoal || this._taskState.goal || void 0,
+            goal: goal || void 0,
             title: (this._taskState.goal || "").slice(0, 120) || void 0,
-            cards: this._initialWorkboardCardsForGoal(this._taskState.originalGoal || this._taskState.goal || "")
+            cards: this._initialWorkboardCardsForGoal(goal)
           });
         } catch {
           this._workboard = loadWorkboardSnapshot(dir, runId);
         }
+        if (this._workboard) {
+          this._workboard = this._seedWorkboardCardsIfNeeded(this._workboard, goal);
+        }
         return this._workboard;
       }
+      _seedWorkboardCardsIfNeeded(snapshot, goal) {
+        if (snapshot.cards.length > 0)
+          return snapshot;
+        const cards = this._initialWorkboardCardsForGoal(goal);
+        if (cards.length === 0)
+          return snapshot;
+        let current = snapshot;
+        const dir = this._workboardDir();
+        for (const card of cards) {
+          try {
+            current = addWorkboardCard(dir, {
+              ...card,
+              runId: snapshot.runId,
+              actor: this.options.subAgent ? "sub-agent" : "agent",
+              decisionReason: "Seeded missing workboard card after an empty persisted board was detected for an active user task."
+            });
+          } catch {
+            const refreshed = readActiveWorkboardSnapshot(dir, snapshot.runId);
+            if (refreshed)
+              current = refreshed;
+          }
+        }
+        return readActiveWorkboardSnapshot(dir, snapshot.runId) ?? current;
+      }
       _initialWorkboardCardsForGoal(goal) {
         if (!this.writesUserTaskArtifacts())
           return [];
@@ -579166,9 +579340,11 @@ var init_agenticRunner = __esm({
       injectWorkboardContext() {
         if (this._workboard || this.options.subAgent) {
           const dir = this._workboardDir();
-          const snapshot = readActiveWorkboardSnapshot(dir, this._sessionId);
+          let snapshot = readActiveWorkboardSnapshot(dir, this._sessionId);
           if (!snapshot)
             return null;
+          snapshot = this._seedWorkboardCardsIfNeeded(snapshot, this._taskState.originalGoal || this._taskState.goal || "");
+          this._workboard = snapshot;
           const activeCards = snapshot.cards.filter((c9) => c9.status === "in_progress" || c9.status === "open" || c9.status === "needs_changes");
           if (activeCards.length === 0 && snapshot.cards.every((c9) => c9.status === "verified" || c9.status === "completed"))
             return null;
@@ -579198,11 +579374,13 @@ ${parts.join("\n")}
         const dir = this._workboardDir();
         const fromDisk = readActiveWorkboardSnapshot(dir, this._sessionId);
         if (fromDisk) {
-          this._workboard = fromDisk;
-          return fromDisk;
+          this._workboard = this._seedWorkboardCardsIfNeeded(fromDisk, this._taskState.originalGoal || this._taskState.goal || "");
+          return this._workboard;
         }
-        if (this._workboard)
+        if (this._workboard) {
+          this._workboard = this._seedWorkboardCardsIfNeeded(this._workboard, this._taskState.originalGoal || this._taskState.goal || "");
           return this._workboard;
+        }
         const goal = this._taskState.originalGoal || this._taskState.goal || "";
         if (this._initialWorkboardCardsForGoal(goal).length === 0)
           return null;
@@ -579263,7 +579441,7 @@ ${parts.join("\n")}
             cardId: implementation2.id,
             title: implementation2.title,
             reason: "discovery evidence is already present; land the smallest concrete repair",
-            preferredTools: ["file_write", "file_edit", "batch_edit", "file_patch"]
+            preferredTools: ["file_patch", "batch_edit", "file_edit", "file_write"]
           };
         }
         const active = snapshot.cards.find((card) => card.status === "in_progress") ?? snapshot.cards.find((card) => card.status === "needs_changes") ?? snapshot.cards.find((card) => card.status === "open") ?? discovery;
@@ -579273,7 +579451,7 @@ ${parts.join("\n")}
           cardId: active.id,
           title: active.title,
           reason: active.id === "discover-current-state" ? "no authoritative target evidence is recorded yet" : "workboard card is the next unresolved card",
-          preferredTools: active.id === "discover-current-state" ? ["file_read", "grep_search", "list_directory", "shell"] : ["file_write", "file_edit", "batch_edit", "file_patch", "shell"]
+          preferredTools: active.id === "discover-current-state" ? ["file_read", "grep_search", "list_directory", "shell"] : ["file_patch", "batch_edit", "file_edit", "file_write", "shell"]
         };
       }
       _focusToolsForRequiredAction(action) {
@@ -579287,7 +579465,7 @@ ${parts.join("\n")}
           case "disambiguate_edit_match":
             return "file_edit or batch_edit with replace_all=true for identical global changes, or with a more unique old_string copied from current file context";
           case "edit_different_target":
-            return "file_write, file_edit, batch_edit, or file_patch on a different supported target";
+            return "file_patch, batch_edit, file_edit, or hash-guarded file_write on a different supported target";
           case "run_verification":
             return "shell running the verification/runtime command";
           case "report_blocked":
@@ -579299,6 +579477,25 @@ ${parts.join("\n")}
       }
       _renderNextActionContract(turn) {
         const lines = ["[NEXT ACTION CONTRACT]", `turn=${turn}`];
+        const ts = this._taskState;
+        const goal = (ts.originalGoal || ts.goal || "").replace(/\s+/g, " ").trim();
+        if (goal)
+          lines.push(`goal_anchor=${goal.slice(0, 360)}`);
+        if (ts.currentStep) {
+          lines.push(`current_focus=${ts.currentStep.replace(/\s+/g, " ").slice(0, 220)}`);
+        }
+        if (ts.nextAction) {
+          lines.push(`declared_next_action=${ts.nextAction.replace(/\s+/g, " ").slice(0, 220)}`);
+        }
+        lines.push(`progress_anchor=completed_steps:${ts.completedSteps.length} failed_approaches:${ts.failedApproaches.length} modified_files:${ts.modifiedFiles.size} tool_calls:${ts.toolCallCount}`);
+        if (ts.completedSteps.length > 0) {
+          lines.push(`recent_completed=${ts.completedSteps.slice(-3).join(" | ").replace(/\s+/g, " ").slice(0, 420)}`);
+        }
+        if (ts.failedApproaches.length > 0) {
+          lines.push(`recent_failed_approaches=${ts.failedApproaches.slice(-3).join(" | ").replace(/\s+/g, " ").slice(0, 420)}`);
+        }
+        lines.push("tool_call_contract=Each tool call must include action_reason {task_anchor,intent,evidence,expected_result,scope}; compact public facts only, no hidden chain-of-thought.");
+        lines.push(`scope_contract=${Array.from(TOOL_ACTION_REASON_SCOPES).join("|")}; use targeted_patch for constrained code edits and full_file_rewrite only for deliberate whole-file replacement.`);
         const focus = this._focusSupervisor?.snapshot().directive ?? null;
         if (focus) {
           lines.push(`focus_required_next_action=${focus.requiredNextAction}`);
@@ -580551,6 +580748,25 @@ Your hypotheses MUST address this specific error, not generic causes.
         const fa = this._detectFailingApproachSignal(turn);
         return fa ? this._failingApproachDirective(fa) : null;
       }
+      _focusDirectiveSuppressesEditPressure() {
+        return this._focusSupervisor?.currentDirective ?? null;
+      }
+      _deferReg61ToFocusDirective(input) {
+        if (this._reg61PerpetualGateActive) {
+          this._reg61PerpetualGateActive = false;
+        }
+        if (this._reg61DeferredFocusDirectiveId === input.directive.id)
+          return;
+        this._reg61DeferredFocusDirectiveId = input.directive.id;
+        const _cyclePart = input.cycleLabel ? ` (${input.cycleLabel})` : "";
+        const _detail = input.detail ? `; ${input.detail}` : "";
+        this.emit({
+          type: "status",
+          content: `REG-61 deferred to focus supervisor at turn ${input.turn}${_cyclePart}; source=${input.source}; directive_id=${input.directive.id}; required_next_action=${input.directive.requiredNextAction}${_detail}`,
+          turn: input.turn,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        });
+      }
       /**
        * REG-61 sliding-window first-edit / sustained-edit nudge.
        *
@@ -580642,11 +580858,23 @@ Your hypotheses MUST address this specific error, not generic causes.
         }
         if (_readsInWindow < REG61_MIN_READS)
           return;
+        const _gapDesc = this._lastFileWriteTurn < 0 ? `no creative edits yet this run` : `${turn - this._lastFileWriteTurn} turns since last creative edit (turn ${this._lastFileWriteTurn})`;
+        const focusDirective = this._focusDirectiveSuppressesEditPressure();
+        if (focusDirective) {
+          this._deferReg61ToFocusDirective({
+            directive: focusDirective,
+            turn,
+            cycleLabel,
+            source: "trigger",
+            detail: `reads_in_window=${_readsInWindow}; ${_gapDesc}`
+          });
+          return;
+        }
+        this._reg61DeferredFocusDirectiveId = null;
         this._reg61CooldownUntilTurn = turn + REG61_COOLDOWN;
         if (process.env["OMNIUS_DISABLE_REG61_COERCE"] !== "1") {
           this._reg61PerpetualGateActive = true;
         }
-        const _gapDesc = this._lastFileWriteTurn < 0 ? `no creative edits yet this run` : `${turn - this._lastFileWriteTurn} turns since last creative edit (turn ${this._lastFileWriteTurn})`;
         const reg61Msg = `[FIRST-EDIT NUDGE — REG-61]
 You have made ${_readsInWindow} read/exploration calls in the trailing window — ${_gapDesc}. Reading is preparation; writing is progress. Runs that stay in pure-read mode produce zero deliverables.
 
@@ -581569,7 +581797,7 @@ ${context2 ?? ""}`;
             }
             if (critique2) {
               this._visualNudgesEmitted.add(nudgeKey);
-              this.pendingUserMessages.push(critique2);
+              this.enqueueRuntimeGuidance(critique2);
             }
           }
         }
@@ -584418,7 +584646,7 @@ ${blob}
           });
           if (!this._microcompactHintEmitted && this.tools.has("memory_write")) {
             this._microcompactHintEmitted = true;
-            this.pendingUserMessages.push(`[SYSTEM] Older tool results have been cleared to save context. If you discovered important patterns or facts, use memory_write to persist them before they are lost from context.`);
+            this.enqueueRuntimeGuidance(`[SYSTEM] Older tool results have been cleared to save context. If you discovered important patterns or facts, use memory_write to persist them before they are lost from context.`);
           }
         }
       }
@@ -584738,7 +584966,7 @@ ${blob}
           if (seen.has(value2))
             return "#cycle";
           seen.add(value2);
-          const entries = Object.entries(value2).sort(([a2], [b]) => a2.localeCompare(b)).map(([k, v]) => `${JSON.stringify(k)}:${this._canonicalArgValue(v, seen)}`);
+          const entries = Object.entries(value2).filter(([key]) => !TOOL_ACTION_REASON_KEYS.has(key)).sort(([a2], [b]) => a2.localeCompare(b)).map(([k, v]) => `${JSON.stringify(k)}:${this._canonicalArgValue(v, seen)}`);
           return `#object:{${entries.join(",")}}`;
         }
         return String(value2);
@@ -585151,6 +585379,11 @@ ${notice}`;
       injectUserMessage(content) {
         this.pendingUserMessages.push(this.scrubUserInput(content, "injected-user-message"));
       }
+      enqueueRuntimeGuidance(content) {
+        const cleaned = this.scrubUserInput(content, "runtime-guidance").trim();
+        if (cleaned)
+          this.pendingRuntimeGuidanceMessages.push(cleaned);
+      }
       /** Retract the last pending user message (Esc cancel).
        *  Returns the retracted text, or null if queue is empty or already consumed. */
       retractLastPendingMessage() {
@@ -585998,7 +586231,7 @@ TASK: ${scrubbedTask}` : scrubbedTask;
             onCritique: (critique2, sourceTurn) => {
               const runClosed = completed || this._completionIncompleteVerification || this.aborted;
               if (!runClosed && (this._adversaryMode === "skillcoach" || this._adversaryMode === "both")) {
-                this.pendingUserMessages.push(AdversaryStream.formatInjection(critique2));
+                this.enqueueRuntimeGuidance(AdversaryStream.formatInjection(critique2));
               }
               this.emit({
                 type: "adversary_reaction",
@@ -587203,7 +587436,7 @@ ${_staleSamples.join("\n")}` : ``,
                     ``,
                     `  (c) REPLACE_ALL: If you want a global rename, set replace_all=true and the uniqueness check is bypassed.`,
                     ``,
-                    `  (d) FILE_WRITE: If the changes are extensive, rewrite the whole file with file_write instead of patching it. Faster than 6 failed edits.`,
+                    `  (d) CONSTRAINED PATCH: If the exact replacement is too brittle, use file_patch with expected_old_content or batch_edit/file_edit against fresh current text. Use file_write only for new files, dry-run proposals, or deliberate hash-guarded full_file_rewrite actions.`,
                     ``,
                     `Do NOT in your next response: call file_edit or batch_edit on ${_efWorstPath} again with another guess at old_string.`
                   ].join("\n")
@@ -587398,7 +587631,7 @@ ${_staleSamples.join("\n")}` : ``,
               timestamp: (/* @__PURE__ */ new Date()).toISOString()
             });
             messages2.push({
-              role: "user",
+              role: "system",
               content: this.buildHealthCheckPrompt(elapsed, toolCallCount, repetitionScore, selfEvalCount)
             });
             nextSelfEval = now2 + selfEvalInterval;
@@ -587433,6 +587666,7 @@ ${_staleSamples.join("\n")}` : ``,
               });
             }
           }
+          this.drainPendingRuntimeGuidance(turn);
           while (this.pendingUserMessages.length > 0) {
             const userMsg = this.pendingUserMessages.shift();
             await this.appendInjectedUserMessage(userMsg, messages2, turn);
@@ -587440,7 +587674,7 @@ ${_staleSamples.join("\n")}` : ``,
           if (!this.options.disableTodoPlanningNudges) {
             const maybeReminder = this.getTodoReminderContent(turn);
             if (maybeReminder) {
-              messages2.push({ role: "user", content: maybeReminder });
+              messages2.push({ role: "system", content: maybeReminder });
               this.emit({
                 type: "status",
                 content: `todo_reminder injected (turn ${turn}, last todo_write turn ${this._lastTodoWriteTurn})`,
@@ -587459,7 +587693,7 @@ ${_staleSamples.join("\n")}` : ``,
             const isComplex = !explicitSingleTool && (wordCount2 > 40 || hasMultipleActions || hasMultipleFiles);
             if (isComplex) {
               messages2.push({
-                role: "user",
+                role: "system",
                 content: `[TASK DECOMPOSITION — Multi-step task detected]
 
 MANDATORY FIRST ACTION: Call todo_write NOW with the complete plan.
@@ -587485,7 +587719,7 @@ Call todo_write FIRST, then start with step 1.`
             const isGreenfield = /\bcreate\b.*\bnew\b|\bimplement\b.*\bclass\b|\bwrite\b.*\bfrom scratch\b|\bbuild\b.*\bmodule\b/i.test(goal);
             if (isGreenfield && !isComplex) {
               messages2.push({
-                role: "user",
+                role: "system",
                 content: `[GREENFIELD TASK — Write code immediately]
 
 MANDATORY: Your FIRST tool call MUST be file_write.
@@ -587611,7 +587845,7 @@ ${hints.join("\n")}`);
             const isLooping = repetitionRatio > 0.4;
             const highArousal = errorRatio > 0.5 || isLooping;
             if (highArousal && !isLooping && !noProgress) {
-              this.pendingUserMessages.push(`[COGNITIVE STATE: HIGH AROUSAL] Recent error rate is ${Math.round(errorRatio * 100)}%. Your current approach may be hitting a wall. Consider:
+              this.enqueueRuntimeGuidance(`[COGNITIVE STATE: HIGH AROUSAL] Recent error rate is ${Math.round(errorRatio * 100)}%. Your current approach may be hitting a wall. Consider:
 1. Read related files you haven't examined yet
 2. Search for similar patterns in the codebase
 3. Check if your assumptions about the API/framework are correct
@@ -587621,7 +587855,7 @@ State what you've learned from the errors before trying again.`);
               const progress = this._taskState.completedSteps.slice(-3).join("; ");
               const failures = this._taskState.failedApproaches.slice(-2).join("; ");
               messages2.push({
-                role: "user",
+                role: "system",
                 content: `[PROGRESS CHECK — Turn ${turn}]
 **Goal:** ${this._taskState.goal}
 ` + (progress ? `**Done so far:** ${progress}
@@ -588032,7 +588266,7 @@ ${memoryLines.join("\n")}`
                           const result = this.applyRegisteredToolResultTriage(rawResult, resolvedParsedTool.name, tool);
                           messages2.push({ role: "assistant", content });
                           messages2.push({
-                            role: "user",
+                            role: "system",
                             content: `Tool result (${parsed.tool}): ${result.output.slice(0, 2e3)}`
                           });
                           if (resolvedParsedTool.name === "task_complete") {
@@ -588221,7 +588455,7 @@ ${memoryLines.join("\n")}`
                 timestamp: (/* @__PURE__ */ new Date()).toISOString()
               });
               messages2.push({
-                role: "user",
+                role: "system",
                 content: `[SYSTEM] You produced ${consecutiveEmptyResponses} empty responses in a row. You MUST take action now. Your task: ${this._taskState.goal}
 
 ` + (this._taskState.nextAction ? `**DO THIS NOW:** ${this._taskState.nextAction}
@@ -588306,6 +588540,7 @@ ${memoryLines.join("\n")}`
             const executeSingle = async (tc) => {
               if (this.aborted)
                 return null;
+              const actionReasonForAdvisory = this._extractToolActionReason(tc.arguments ?? {});
               const cohortKey = this.buildArgCohortKey(tc.name, tc.arguments);
               const cohort = this._argCohorts.get(cohortKey);
               if (cohort && cohort.failure >= 3 && cohort.success === 0) {
@@ -588319,7 +588554,7 @@ ${memoryLines.join("\n")}`
                   }
                 });
                 if (this._adversaryMode === "skillcoach" || this._adversaryMode === "both") {
-                  this.pendingUserMessages.push(`[ADVERSARY CRITIQUE — non-blocking]
+                  this.enqueueRuntimeGuidance(`[ADVERSARY CRITIQUE — non-blocking]
 Evidence: ${tc.name} with similar arguments has failed ${cohort.failure}× recently.
 Root cause hypothesis: the argument family may be wrong, a prerequisite may be missing, or the tool is being used before enough state is known.
 Corrective action: try a different approach first: read relevant files, adjust arguments, or verify prerequisites.`);
@@ -588332,7 +588567,7 @@ Corrective action: try a different approach first: read relevant files, adjust a
                   const _injKey = `resfix:${_sug.fix.from.join(" ")}=>${_sug.fix.to.join(" ")}`;
                   if (!this._errorGuidanceInjected.has(_injKey)) {
                     this._errorGuidanceInjected.add(_injKey);
-                    this.pendingUserMessages.push(_sug.message);
+                    this.enqueueRuntimeGuidance(_sug.message);
                     this.emit({
                       type: "status",
                       content: `Resolution memory: suggested \`${_sug.fix.from.join(" ")}\`→\`${_sug.fix.to.join(" ")}\` before shell call`,
@@ -588555,7 +588790,16 @@ Corrective action: try a different approach first: read relevant files, adjust a
                 "priority_delegate",
                 "background_run"
               ]);
-              if (this._reg61PerpetualGateActive && !REG61_BYPASS_TOOLS.has(tc.name) && process.env["OMNIUS_DISABLE_REG61_COERCE"] !== "1") {
+              const focusDirectiveForEditPressure = this._focusDirectiveSuppressesEditPressure();
+              if (this._reg61PerpetualGateActive && focusDirectiveForEditPressure) {
+                this._deferReg61ToFocusDirective({
+                  directive: focusDirectiveForEditPressure,
+                  turn,
+                  source: "latched_steer",
+                  detail: `attempted_tool=${tc.name}`
+                });
+              }
+              if (this._reg61PerpetualGateActive && !focusDirectiveForEditPressure && !REG61_BYPASS_TOOLS.has(tc.name) && process.env["OMNIUS_DISABLE_REG61_COERCE"] !== "1") {
                 const _dbgLoop = this._detectDebugLoop([
                   ...toolCallLog,
                   { name: tc.name, argsKey }
@@ -588688,6 +588932,7 @@ Read the current file if needed, make a different concrete edit, or move to veri
                   turn,
                   toolName: tc.name,
                   args: tc.arguments ?? {},
+                  actionReason: actionReasonForAdvisory,
                   fingerprint: toolFingerprint,
                   isReadLike: false,
                   stalePreflightMessage: staleEditBlock,
@@ -588753,6 +588998,7 @@ Read the current file if needed, make a different concrete edit, or move to veri
                   turn,
                   toolName: tc.name,
                   args: tc.arguments ?? {},
+                  actionReason: actionReasonForAdvisory,
                   fingerprint: toolFingerprint,
                   isReadLike: false,
                   stalePreflightMessage: staleRewriteBlock,
@@ -588818,6 +589064,7 @@ Read the current file if needed, make a different concrete edit, or move to veri
                   turn,
                   toolName: tc.name,
                   args: tc.arguments ?? {},
+                  actionReason: actionReasonForAdvisory,
                   fingerprint: toolFingerprint,
                   isReadLike: false,
                   stalePreflightMessage: editReversalBlock,
@@ -588949,7 +589196,11 @@ Read the current file if needed, make a different concrete edit, or move to veri
                 decision: "pass",
                 reason: "adversary critic disabled for isolated evaluation"
               } : evaluate2({
-                proposedCall: { tool: tc.name, args: tc.arguments ?? {} },
+                proposedCall: {
+                  tool: tc.name,
+                  args: tc.arguments ?? {},
+                  actionReason: actionReasonForAdvisory ?? void 0
+                },
                 fingerprint: toolFingerprint,
                 isReadLike,
                 recentToolResults,
@@ -588998,6 +589249,7 @@ Read the current file if needed, make a different concrete edit, or move to veri
                       tool: tc.name,
                       target: _target,
                       count: criticDecision.hitNumber,
+                      actionReason: actionReasonForAdvisory ?? void 0,
                       alreadyHave: _existingFp?.result
                     }
                   });
@@ -589079,10 +589331,12 @@ ${cachedResult}`,
               }
               const focusCachedEntry = recentToolResults.get(toolFingerprint);
               const focusDuplicateHits = criticDecision.decision === "guidance" ? criticDecision.hitNumber : dedupHitCount.get(toolFingerprint) ?? 0;
+              const usesAuthoritativeTargetEvidence = this._toolCallUsesFreshFileReadEvidence(tc.name, tc.arguments ?? {});
               const focusDecision = this._focusSupervisor?.evaluateProposedCall({
                 turn,
                 toolName: tc.name,
                 args: tc.arguments ?? {},
+                actionReason: actionReasonForAdvisory,
                 completionStatus: completionStatusFromTaskCompleteArgs(tc.arguments),
                 fingerprint: toolFingerprint,
                 isReadLike,
@@ -589090,7 +589344,8 @@ ${cachedResult}`,
                 cachedResult: focusCachedEntry?.result,
                 cachedResultFailed: tc.name === "shell" && typeof focusCachedEntry?.result === "string" && focusCachedEntry.result.includes("status: failure"),
                 duplicateHitCount: focusDuplicateHits,
-                context: this._buildFocusContextSnapshot()
+                context: this._buildFocusContextSnapshot(),
+                usesAuthoritativeTargetEvidence
               });
               if (focusDecision && focusDecision.kind !== "pass") {
                 this._emitFocusSupervisorEvent({
@@ -589130,6 +589385,7 @@ ${cachedResult}`,
               const tool = resolvedTool?.tool;
               let result;
               let runtimeSystemGuidance = null;
+              let toolActionReason = actionReasonForAdvisory;
               if (repeatShortCircuit) {
                 result = repeatShortCircuit;
               } else if (tc.arguments && "_raw" in tc.arguments) {
@@ -589145,7 +589401,14 @@ ${cachedResult}`,
                   error: this.unknownToolError(tc.name)
                 };
               } else {
-                let validationError = this._validateFreshExpectedHashesForEdit(resolvedTool?.name ?? tc.name, tc.arguments ?? {});
+                let validationError = this._validateToolActionReason(resolvedTool?.name ?? tc.name, tc.arguments ?? {});
+                if (!validationError) {
+                  tc.arguments = this._stripToolActionReasonArgs(tc.arguments ?? {});
+                  validationError = this._validateFileWriteOverwriteContract(resolvedTool?.name ?? tc.name, tc.arguments ?? {}, toolActionReason);
+                }
+                if (!validationError) {
+                  validationError = this._validateFreshExpectedHashesForEdit(resolvedTool?.name ?? tc.name, tc.arguments ?? {});
+                }
                 if (!validationError && tool.inputSchema) {
                   const parseResult = tool.inputSchema.safeParse(tc.arguments);
                   if (!parseResult.success) {
@@ -589213,7 +589476,7 @@ ${cachedResult}`,
                       });
                       if (this._hookDenyHintCount < 3 && this.tools.has("memory_write")) {
                         this._hookDenyHintCount++;
-                        this.pendingUserMessages.push(`[SYSTEM] Tool "${tc.name}" was blocked: ${hookCheck.reason}. If this constraint should persist across sessions, use memory_write to save it (e.g., memory_write(topic="constraints", key="${tc.name}_blocked", value="${(hookCheck.reason ?? "hook").slice(0, 80)}")).`);
+                        this.enqueueRuntimeGuidance(`[SYSTEM] Tool "${tc.name}" was blocked: ${hookCheck.reason}. If this constraint should persist across sessions, use memory_write to save it (e.g., memory_write(topic="constraints", key="${tc.name}_blocked", value="${(hookCheck.reason ?? "hook").slice(0, 80)}")).`);
                       }
                     } else {
                       const finalArgs = hookCheck.modifiedArgs ?? tc.arguments;
@@ -590451,7 +590714,7 @@ ${bookkeepingGuidance}` : bookkeepingGuidance;
               }
               if (this._isAtomicBatchEditAbort(tc.name, result)) {
                 editFeedbackRequiredBeforeMoreEdits = this._buildBatchEditAtomicAbortGuidance(tc.arguments);
-                this.pendingUserMessages.push(editFeedbackRequiredBeforeMoreEdits);
+                this.enqueueRuntimeGuidance(editFeedbackRequiredBeforeMoreEdits);
               }
               const currentLogEntry = toolCallLog[_toolLogTailIdx];
               if (currentLogEntry) {
@@ -590616,6 +590879,7 @@ Evidence: ${evidencePreview}`.slice(0, 500);
                   turn,
                   toolName: tc.name,
                   args: tc.arguments ?? {},
+                  actionReason: toolActionReason,
                   fingerprint: toolFingerprint,
                   success: result.success,
                   output: result.output ?? result.llmContent ?? "",
@@ -590624,7 +590888,8 @@ Evidence: ${evidencePreview}`.slice(0, 500);
                   isReadLike,
                   noop: tc.name === "todo_write" ? this._isTodoWriteNoopResult(result) : result.noop,
                   alreadyApplied: result.alreadyApplied === true,
-                  runtimeAuthored: result.runtimeAuthored === true
+                  runtimeAuthored: result.runtimeAuthored === true,
+                  usedAuthoritativeTargetEvidence: usesAuthoritativeTargetEvidence
                 });
                 const focusSnapshotAfter = this._focusSupervisor?.snapshot();
                 focusAfterToolResult = focusSnapshotAfter ?? void 0;
@@ -590667,6 +590932,7 @@ Evidence: ${evidencePreview}`.slice(0, 500);
                     reason: focusDecision.directive.reason,
                     requiredNextAction: focusDecision.directive.requiredNextAction
                   },
+                  actionReason: toolActionReason ?? void 0,
                   repeatShortCircuit: Boolean(repeatShortCircuit),
                   runtimeAuthored: result.runtimeAuthored === true,
                   runtimeGuidance: runtimeSystemGuidance
@@ -590700,7 +590966,7 @@ Evidence: ${evidencePreview}`.slice(0, 500);
                 }
                 const consecutiveSameTool = Math.max(sameToolFailStreak, this._taskState.failedApproaches.slice(-2).filter((f2) => f2.startsWith(`${tc.name}(`)).length);
                 if (sameToolFailStreak >= 5 && (this.options.modelTier === "small" || this.options.modelTier === "medium")) {
-                  this.pendingUserMessages.push(`[BRANCH — evaluate alternatives before acting]
+                  this.enqueueRuntimeGuidance(`[BRANCH — evaluate alternatives before acting]
 Tool "${tc.name}" has failed ${sameToolFailStreak} times. STOP and enumerate:
 Option A: [describe a completely different approach]
 Option B: [describe another alternative]
@@ -590710,7 +590976,7 @@ Pick the BEST option and explain why, then execute it. Do NOT retry ${tc.name} w
                   sameToolFailName = null;
                 }
                 if (consecutiveSameTool >= 2 && (this.options.modelTier === "small" || this.options.modelTier === "medium")) {
-                  this.pendingUserMessages.push(`[PIVOT REQUIRED] You have failed ${consecutiveSameTool + 1} times in a row with ${tc.name}. Your current approach is not working. You MUST try something fundamentally different:
+                  this.enqueueRuntimeGuidance(`[PIVOT REQUIRED] You have failed ${consecutiveSameTool + 1} times in a row with ${tc.name}. Your current approach is not working. You MUST try something fundamentally different:
 - If file_edit keeps failing: re-read the file first, then use the EXACT text from the file
 - If shell keeps failing: try a different command or check prerequisites
 - If grep_search finds nothing: try broader patterns or list_directory
@@ -590723,7 +590989,7 @@ Do NOT retry ${tc.name} with similar arguments.`);
                     this._taskState.failedApproaches.shift();
                   }
                   if (this._taskState.failedApproaches.length === 3 && this.tools.has("memory_write")) {
-                    this.pendingUserMessages.push(`[SYSTEM] You have ${this._taskState.failedApproaches.length} failed approaches this session. Consider using memory_write to save these failure patterns so you avoid them in future sessions:
+                    this.enqueueRuntimeGuidance(`[SYSTEM] You have ${this._taskState.failedApproaches.length} failed approaches this session. Consider using memory_write to save these failure patterns so you avoid them in future sessions:
 ` + this._taskState.failedApproaches.map((f2) => `- ${f2}`).join("\n"));
                   }
                 }
@@ -590731,7 +590997,7 @@ Do NOT retry ${tc.name} with similar arguments.`);
                 sameToolFailStreak = 0;
                 sameToolFailName = null;
                 if (isGenerationArtifactSuccess(tc.name, result.output ?? "")) {
-                  this.pendingUserMessages.push(`[GENERATION COMPLETE] ${tc.name} succeeded. Do not call the same generation tool again for the same request. Use the artifact/path from the tool result; if delivery is needed, send it, otherwise call task_complete.`);
+                  this.enqueueRuntimeGuidance(`[GENERATION COMPLETE] ${tc.name} succeeded. Do not call the same generation tool again for the same request. Use the artifact/path from the tool result; if delivery is needed, send it, otherwise call task_complete.`);
                 }
               }
               if (filePath && (tc.name === "file_read" || tc.name === "file_write" || tc.name === "file_edit" || tc.name === "batch_edit" || tc.name === "file_patch")) {
@@ -590759,7 +591025,7 @@ Do NOT retry ${tc.name} with similar arguments.`);
                 if (isModify && (turnTier === "small" || turnTier === "medium")) {
                   const modCount = this._taskState.modifiedFiles.size;
                   if (modCount >= 2 && modCount % 2 === 0) {
-                    this.pendingUserMessages.push(`[Test reminder] You've modified ${modCount} files. Run relevant tests NOW to verify: shell(command="npm test") or the project's test command. Fix any failures before continuing.`);
+                    this.enqueueRuntimeGuidance(`[Test reminder] You've modified ${modCount} files. Run relevant tests NOW to verify: shell(command="npm test") or the project's test command. Fix any failures before continuing.`);
                   }
                 }
               }
@@ -590803,7 +591069,7 @@ Do NOT retry ${tc.name} with similar arguments.`);
               }
               if (isEisdir) {
                 const failedPath = String(tc.arguments?.["path"] ?? tc.arguments?.["file"] ?? "unknown");
-                this.pendingUserMessages.push(`[SYSTEM] "${failedPath}" is a DIRECTORY, not a file. You CANNOT use file_read on directories.
+                this.enqueueRuntimeGuidance(`[SYSTEM] "${failedPath}" is a DIRECTORY, not a file. You CANNOT use file_read on directories.
 Use list_directory("${failedPath}") to see its contents instead.
 Then use file_read on individual FILES inside it.`);
                 this._taskState.failedApproaches.push(`file_read("${failedPath}"): EISDIR — this is a directory, use list_directory`);
@@ -590814,7 +591080,7 @@ Then use file_read on individual FILES inside it.`);
                 if (this._consecutiveEnoent >= 2 || windowEnoents >= 4) {
                   const failedPath = String(tc.arguments?.["path"] ?? tc.arguments?.["file"] ?? "unknown");
                   const triggerReason = this._consecutiveEnoent >= 2 ? `${this._consecutiveEnoent} consecutive file-not-found errors` : `${windowEnoents}/8 recent file operations failed`;
-                  this.pendingUserMessages.push(`[SYSTEM] ${triggerReason} (last: "${failedPath}"). You are repeating failed paths. CHANGE YOUR APPROACH:
+                  this.enqueueRuntimeGuidance(`[SYSTEM] ${triggerReason} (last: "${failedPath}"). You are repeating failed paths. CHANGE YOUR APPROACH:
 1. Call list_directory(".") to see what exists at the project root
 2. Entries in a directory listing are RELATIVE to that directory. If you listed "parent/" and saw "child", the full path is "parent/child" — NOT ".child" or just "child"
 3. If an entry is a directory (marked "d"), use list_directory on it, NOT file_read
@@ -591439,7 +591705,7 @@ Your most recent tool calls SUCCEEDED. If the task is complete, call task_comple
                   timestamp: (/* @__PURE__ */ new Date()).toISOString()
                 });
                 messages2.push({
-                  role: "user",
+                  role: "system",
                   content: "You have been reasoning internally for several turns without producing visible output or tool calls. Please take action now — call a tool or produce a visible response." + successHint
                 });
               }
@@ -591459,7 +591725,7 @@ Your most recent tool calls SUCCEEDED. If the task is complete, call task_comple
               if (shellCommands.length > 0 && shellCommands.length < 2e3) {
                 if (looksLikeShellFileWrite(shellCommands)) {
                   messages2.push({
-                    role: "user",
+                    role: "system",
                     content: `You wrote a shell code block that appears to create or overwrite files. I did NOT auto-execute it because shell redirection bypasses file_write/file_edit/file_patch/batch_edit tracking and version checks. Use file_write/content_base64 for full-file writes, file_edit or batch_edit for exact replacements, or file_patch/new_content_base64 for line-range patches.`
                   });
                   this.emit({
@@ -591519,7 +591785,7 @@ Your most recent tool calls SUCCEEDED. If the task is complete, call task_comple
               } else {
                 correction = `CRITICAL: You cannot use ${toolName} by writing text. After ${narratedToolCallCount} attempts, it is clear this approach will not work. Try a COMPLETELY DIFFERENT tool or approach. For example: if trying skill_execute, try shell("cat .omnius/skills/*/SKILL.md") instead. If trying file_read, try shell("cat path/to/file") instead.`;
               }
-              messages2.push({ role: "user", content: correction });
+              messages2.push({ role: "system", content: correction });
               this.emit({
                 type: "status",
                 content: `Narrated tool call #${narratedToolCallCount}: model wrote ${toolName} as text`,
@@ -591528,11 +591794,12 @@ Your most recent tool calls SUCCEEDED. If the task is complete, call task_comple
             } else {
               narratedToolCallCount = 0;
               messages2.push({
-                role: "user",
+                role: "system",
                 content: "Continue working. Use tools to read files, make changes, and run validation. Call task_complete when done."
               });
             }
             if (adversaryAddedGuidance) {
+              this.drainPendingRuntimeGuidance(turn);
               while (this.pendingUserMessages.length > 0) {
                 const userMsg = this.pendingUserMessages.shift();
                 await this.appendInjectedUserMessage(userMsg, messages2, turn);
@@ -591602,7 +591869,7 @@ Your most recent tool calls SUCCEEDED. If the task is complete, call task_comple
           });
           this._reg61CooldownUntilTurn = -1;
           messages2.push({
-            role: "user",
+            role: "system",
             content: `[CONTINUATION — Cycle ${bruteForceCycle}]
 
 You have used ${totalTurns} turns and ${toolCallCount} tool calls so far. The task is NOT yet complete. DO NOT give up — re-evaluate and continue:
@@ -591693,11 +591960,12 @@ ${this.options.maxTurns && this.options.maxTurns > 0 ? `You have ${this.options.
                 timestamp: (/* @__PURE__ */ new Date()).toISOString()
               });
               messages2.push({
-                role: "user",
+                role: "system",
                 content: this.buildHealthCheckPrompt(elapsed, toolCallCount, repetitionScore, selfEvalCount)
               });
               nextSelfEval = bfNow + selfEvalInterval;
             }
+            this.drainPendingRuntimeGuidance(turn);
             while (this.pendingUserMessages.length > 0) {
               const userMsg = this.pendingUserMessages.shift();
               await this.appendInjectedUserMessage(userMsg, messages2, turn);
@@ -592039,7 +592307,7 @@ Full content available via: repl_exec(code="data = retrieve('${handleId}')")  or
                   this._consecutiveEnoent++;
                   if (this._consecutiveEnoent >= 2) {
                     const failedPath2 = String(tc.arguments?.["path"] ?? tc.arguments?.["file"] ?? "unknown");
-                    this.pendingUserMessages.push(`[SYSTEM] ${this._consecutiveEnoent} consecutive file-not-found errors (last: "${failedPath2}"). You are repeating failed paths. CHANGE YOUR APPROACH:
+                    this.enqueueRuntimeGuidance(`[SYSTEM] ${this._consecutiveEnoent} consecutive file-not-found errors (last: "${failedPath2}"). You are repeating failed paths. CHANGE YOUR APPROACH:
 1. Call list_directory(".") to see what exists at the project root
 2. Entries in a directory listing are RELATIVE to that directory. If you listed "parent/" and saw "child", the full path is "parent/child" — NOT ".child" or just "child"
 3. If an entry is a directory (marked "d"), use list_directory on it, NOT file_read
@@ -592176,7 +592444,7 @@ Full content available via: repl_exec(code="data = retrieve('${handleId}')")  or
                   const recentSucc = this._adversaryToolOutcomes.slice(-3).filter((o2) => o2.succeeded);
                   const succHint = recentSucc.length > 0 ? "\n\nYour most recent tool calls SUCCEEDED. If the task is complete, call task_complete now with a summary." : "";
                   messages2.push({
-                    role: "user",
+                    role: "system",
                     content: "You have been reasoning internally for several turns without producing visible output or tool calls. Please take action now — call a tool or produce a visible response." + succHint
                   });
                 }
@@ -592191,7 +592459,7 @@ Full content available via: repl_exec(code="data = retrieve('${handleId}')")  or
                 break;
               }
               messages2.push({
-                role: "user",
+                role: "system",
                 content: "Continue working. Use tools to read files, make changes, and run validation. Call task_complete when done."
               });
             }
@@ -593371,6 +593639,16 @@ ${marker}` : marker);
             return { args, patchedCount: 0 };
           return { args: { ...args, expected_hash: fresh.hash }, patchedCount: 1 };
         }
+        if (toolName === "file_write" || toolName === "file_patch") {
+          if (this._normalizeExpectedHashValue(this._rawExpectedHashValue(args))) {
+            return { args, patchedCount: 0 };
+          }
+          const path12 = this.extractPrimaryToolPath(args);
+          const fresh = path12 ? this._freshReadHashForEditPath(path12) : null;
+          if (!fresh)
+            return { args, patchedCount: 0 };
+          return { args: { ...args, expected_hash: fresh.hash }, patchedCount: 1 };
+        }
         if (toolName !== "batch_edit" || !Array.isArray(args["edits"])) {
           return { args, patchedCount: 0 };
         }
@@ -593391,6 +593669,151 @@ ${marker}` : marker);
         });
         return patchedCount > 0 ? { args: { ...args, edits }, patchedCount } : { args, patchedCount: 0 };
       }
+      _toolCallUsesFreshFileReadEvidence(toolName, args) {
+        if (toolName !== "file_write" && toolName !== "file_edit" && toolName !== "file_patch" && toolName !== "batch_edit") {
+          return false;
+        }
+        const matchesFresh = (rec) => {
+          const path12 = typeof rec["path"] === "string" ? rec["path"] : typeof rec["file"] === "string" ? rec["file"] : "";
+          if (!path12)
+            return false;
+          const expectedHash = this._normalizeExpectedHashValue(this._rawExpectedHashValue(rec));
+          if (!expectedHash)
+            return false;
+          const fresh = this._freshReadHashForEditPath(path12);
+          return fresh?.hash === expectedHash;
+        };
+        if (toolName === "batch_edit") {
+          const edits = args["edits"];
+          return Array.isArray(edits) && edits.length > 0 && edits.every((edit) => !!edit && typeof edit === "object" && !Array.isArray(edit) && matchesFresh(edit));
+        }
+        return matchesFresh(args);
+      }
+      _requiresToolActionReason(toolName) {
+        if (process.env["OMNIUS_DISABLE_TOOL_ACTION_REASON"] === "1") {
+          return false;
+        }
+        if ((process.env["VITEST"] || process.env["NODE_ENV"] === "test") && process.env["OMNIUS_REQUIRE_TOOL_ACTION_REASON"] !== "1") {
+          return false;
+        }
+        if (this.options.artifactMode === "internal")
+          return false;
+        if (toolName.startsWith("__"))
+          return false;
+        return true;
+      }
+      _withToolActionReasonSchema(toolName, parameters) {
+        if (!this._requiresToolActionReason(toolName)) {
+          return parameters ?? { type: "object", properties: {} };
+        }
+        const base3 = parameters && typeof parameters === "object" && !Array.isArray(parameters) ? { ...parameters } : { type: "object" };
+        const properties = base3["properties"] && typeof base3["properties"] === "object" && !Array.isArray(base3["properties"]) ? { ...base3["properties"] } : {};
+        properties["action_reason"] = TOOL_ACTION_REASON_SCHEMA;
+        const required = Array.isArray(base3["required"]) ? base3["required"].map(String) : [];
+        return {
+          ...base3,
+          type: "object",
+          properties,
+          required: [.../* @__PURE__ */ new Set([...required, "action_reason"])]
+        };
+      }
+      _extractToolActionReason(args) {
+        const raw = args["action_reason"] ?? args["actionReason"] ?? args["justification"];
+        if (!raw || typeof raw !== "object" || Array.isArray(raw))
+          return null;
+        const rec = raw;
+        const reason = {
+          task_anchor: String(rec["task_anchor"] ?? rec["taskAnchor"] ?? "").trim(),
+          intent: String(rec["intent"] ?? "").trim(),
+          evidence: String(rec["evidence"] ?? "").trim(),
+          expected_result: String(rec["expected_result"] ?? rec["expectedResult"] ?? "").trim(),
+          scope: String(rec["scope"] ?? "").trim()
+        };
+        return reason;
+      }
+      _validateToolActionReason(toolName, args) {
+        if (!this._requiresToolActionReason(toolName))
+          return null;
+        const raw = args["action_reason"] ?? args["actionReason"] ?? args["justification"];
+        if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+          return [
+            "[TOOL ACTION REASON CONTRACT]",
+            `Every tool call must include action_reason: { task_anchor, intent, evidence, expected_result, scope }.`,
+            `Use compact public facts only; do not include hidden chain-of-thought.`,
+            `scope must be one of: ${Array.from(TOOL_ACTION_REASON_SCOPES).join(", ")}.`
+          ].join("\n");
+        }
+        const reason = this._extractToolActionReason(args);
+        if (!reason) {
+          return "[TOOL ACTION REASON CONTRACT] action_reason must be an object with compact public task-state fields.";
+        }
+        const missing = [
+          "task_anchor",
+          "intent",
+          "evidence",
+          "expected_result",
+          "scope"
+        ].filter((key) => reason[key].length < 3);
+        if (missing.length > 0) {
+          return `[TOOL ACTION REASON CONTRACT] action_reason missing non-empty field(s): ${missing.join(", ")}.`;
+        }
+        if (!TOOL_ACTION_REASON_SCOPES.has(reason.scope)) {
+          return `[TOOL ACTION REASON CONTRACT] action_reason.scope="${reason.scope}" is invalid. Use one of: ${Array.from(TOOL_ACTION_REASON_SCOPES).join(", ")}.`;
+        }
+        return null;
+      }
+      _stripToolActionReasonArgs(args) {
+        let changed = false;
+        const next = {};
+        for (const [key, value2] of Object.entries(args)) {
+          if (TOOL_ACTION_REASON_KEYS.has(key)) {
+            changed = true;
+            continue;
+          }
+          next[key] = value2;
+        }
+        return changed ? next : args;
+      }
+      _validateFileWriteOverwriteContract(toolName, args, actionReason) {
+        if (toolName !== "file_write")
+          return null;
+        if (process.env["OMNIUS_ALLOW_UNVERIFIED_FILE_WRITE_OVERWRITE"] === "1") {
+          return null;
+        }
+        if (args["dry_run"] === true || args["dryRun"] === true)
+          return null;
+        const path12 = this.extractPrimaryToolPath(args);
+        if (!path12)
+          return null;
+        let exists2 = false;
+        try {
+          const st = _fsStatSync(this._absoluteToolPath(path12), {
+            throwIfNoEntry: false
+          });
+          exists2 = !!st && st.isFile();
+        } catch {
+          exists2 = false;
+        }
+        if (!exists2)
+          return null;
+        if (actionReason && actionReason.scope !== "full_file_rewrite") {
+          return [
+            "[FULL FILE REWRITE CONTRACT]",
+            `file_write targets an existing file: ${path12}.`,
+            `For constrained repairs, use file_patch, batch_edit, or file_edit instead of rewriting the full file.`,
+            `If a whole-file replacement is truly intended, set action_reason.scope="full_file_rewrite" and use expected_hash from a fresh file_read.`
+          ].join("\n");
+        }
+        if (!this._toolCallUsesFreshFileReadEvidence(toolName, args)) {
+          const fresh = this._freshReadHashForEditPath(path12);
+          return [
+            "[FULL FILE REWRITE CONTRACT]",
+            `file_write would overwrite existing file ${path12}, but it is not anchored to fresh file_read evidence.`,
+            fresh ? `Use expected_hash=${fresh.hash} from the current active evidence, or prefer file_patch/batch_edit for a constrained change.` : `First file_read ${path12}, then prefer file_patch/batch_edit; only retry file_write with expected_hash if a whole-file rewrite is necessary.`
+          ].join("\n");
+        }
+        return null;
+      }
       _validateFreshExpectedHashesForEdit(toolName, args) {
         if (process.env["OMNIUS_ALLOW_UNVERIFIED_OLD_STRING_EDIT"] === "1") {
           return null;
@@ -593747,11 +594170,20 @@ ${result.output}`, "utf-8");
         const folded = this.foldOutput(modelContent, maxLen);
         return this.wrapToolOutputForModel(toolName, `[Tool output truncated — ${result.output.length} chars, ${lineCount} lines]
 Full output saved to: ${savedPath}
-To read the complete output, use file_read with path="${savedPath}".
+${this.truncatedToolOutputAccessHint(savedPath)}
 
 Truncated preview (beginning + end):
 ${folded}`);
       }
+      truncatedToolOutputAccessHint(savedPath) {
+        if (this.tools.has("file_read")) {
+          return `To read the complete output, use file_read with path="${savedPath}".`;
+        }
+        if (this.tools.has("shell")) {
+          return `To inspect the complete output, use shell with a read-only command for ${JSON.stringify(savedPath)}.`;
+        }
+        return `No file-reading tool is available in this agent role. Do not call file_read for this saved path; use the truncated preview, or report that the full payload is archived at ${savedPath}.`;
+      }
       wrapToolOutputForModel(toolName, output) {
         if (toolName === "task_complete" || output.startsWith("[trust_tier:")) {
           return output;
@@ -594221,6 +594653,50 @@ ${tail}`;
           timestamp: (/* @__PURE__ */ new Date()).toISOString()
         });
       }
+      drainPendingRuntimeGuidance(turn) {
+        while (this.pendingRuntimeGuidanceMessages.length > 0) {
+          const guidance = this.pendingRuntimeGuidanceMessages.shift();
+          this.appendRuntimeGuidance(guidance, turn);
+        }
+      }
+      appendRuntimeGuidance(guidance, turn) {
+        const packet = this.formatRuntimeGuidance(guidance);
+        const guidanceHash = _createHash("sha256").update(packet).digest("hex").slice(0, 16);
+        const signal = signalFromBlock("runtime_guidance", "runtime.guidance", packet, {
+          id: `runtime-guidance-${turn}-${guidanceHash}`,
+          dedupeKey: `runtime.guidance:${guidanceHash}`,
+          priority: 94,
+          createdTurn: turn,
+          ttlTurns: 8
+        });
+        if (signal)
+          this._contextLedger.upsert(signal);
+        this.emit({
+          type: "status",
+          content: `Runtime guidance queued: ${guidance.replace(/\s+/g, " ").slice(0, 140)}`,
+          turn,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        });
+      }
+      formatRuntimeGuidance(guidance) {
+        if (guidance.trim().startsWith("[RUNTIME_GUIDANCE_INTAKE")) {
+          return guidance;
+        }
+        return [
+          "[RUNTIME_GUIDANCE_INTAKE v1]",
+          "Source: Omnius runtime control/advisory signal, not an external user message.",
+          "",
+          "<<<RUNTIME_GUIDANCE>>>",
+          guidance,
+          "<<<END_RUNTIME_GUIDANCE>>>",
+          "",
+          "Contract:",
+          "- Treat this as diagnostic/control-plane guidance for the next action.",
+          "- Reconcile it with the user goal and fresh tool evidence.",
+          "- Do not quote or summarize this wrapper to the user.",
+          "[/RUNTIME_GUIDANCE_INTAKE]"
+        ].join("\n");
+      }
       formatInjectedUserMessage(userMsg) {
         if (userMsg.trim().startsWith("[MID_TASK_STEERING_INTAKE")) {
           return userMsg;
@@ -595306,6 +595782,7 @@ ${trimmedNew}`;
               args = JSON.parse(tc.function.arguments);
             } catch {
             }
+            const actionReason = this._extractToolActionReason(args);
             const argsKey = this._buildExactArgsKey(args);
             const fingerprint = this._buildToolFingerprint(name10, args);
             const prior = this._adversaryToolOutcomes.find((o2) => o2.succeeded && o2.tool === name10 && o2.fingerprint === fingerprint && o2.stateVersion === this._adversaryStateVersion && o2.turn < turn);
@@ -595319,6 +595796,7 @@ ${trimmedNew}`;
                   tool: name10,
                   target: argsKey.slice(0, 180),
                   count: repeatCount,
+                  actionReason: actionReason ?? void 0,
                   alreadyHave: prior.preview
                 }
               }, `possible repeated action ${name10} after prior same-state success`);
@@ -596552,7 +597030,7 @@ Example: ${tool.name}(${JSON.stringify(meta.examples[0].args ?? {})})` : "";
             function: {
               name: tool.name,
               description: compressDesc ? (desc.split(/\.\s/)[0]?.slice(0, 120) ?? desc.slice(0, 120)) + "." : desc,
-              parameters: tool.parameters
+              parameters: this._withToolActionReasonSchema(tool.name, tool.parameters)
             }
           };
         });
@@ -596574,7 +597052,7 @@ Example: ${tool.name}(${JSON.stringify(meta.examples[0].args ?? {})})` : "";
 
 Available tools (${deferred.length}):
 ${catalog}`,
-              parameters: {
+              parameters: this._withToolActionReasonSchema("tool_search", {
                 type: "object",
                 properties: {
                   query: {
@@ -596583,7 +597061,7 @@ ${catalog}`,
                   }
                 },
                 required: ["query"]
-              }
+              })
             }
           });
           const activatedToolsRef = this._activatedTools;
@@ -596625,7 +597103,7 @@ ${catalog}`,
                       lines.push(`Aliases: ${tool.aliases.join(", ")}`);
                     }
                     lines.push(`${getDesc(tool)}${customToolDetails(tool)}`);
-                    lines.push(`Parameters: ${JSON.stringify(tool.parameters)}`);
+                    lines.push(`Parameters: ${JSON.stringify(this._withToolActionReasonSchema(tool.name, tool.parameters))}`);
                   }
                 }
                 if (alreadyAvailable.length > 0) {
@@ -596677,7 +597155,7 @@ ${catalog}`,
               for (const t2 of matches)
                 activatedToolsRef.add(t2.name);
               const result = matches.map((t2) => {
-                const paramsStr = JSON.stringify(t2.parameters, null, 2);
+                const paramsStr = JSON.stringify(this._withToolActionReasonSchema(t2.name, t2.parameters), null, 2);
                 const aliases = t2.aliases?.length ? `
 Aliases: ${t2.aliases.join(", ")}` : "";
                 return `## ${t2.name}${aliases}
@@ -743079,13 +743557,15 @@ The user pasted a clipboard image saved at ${relPath}. Use the OCR, vision analy
     },
     savePendingTaskState() {
       if (lastSubmittedPrompt && activeTask) {
+        const activeToolCallCount = activeTask.toolCallCount;
+        const activeFilesTouched = Array.from(activeTask.filesTouched);
         savePendingTask(repoRoot, {
           prompt: lastSubmittedPrompt,
-          progressSummary: `Task paused by user. ${sessionToolCallCount} tool calls completed.`,
-          filesModified: sessionFilesTouched,
+          progressSummary: `Task paused by user. ${activeToolCallCount} tool calls completed.`,
+          filesModified: activeFilesTouched,
           bruteForce: bruteForceEnabled,
           savedAt: (/* @__PURE__ */ new Date()).toISOString(),
-          toolCallCount: sessionToolCallCount
+          toolCallCount: activeToolCallCount
         });
         return true;
       }