omnius 1.0.540 → 1.0.542

package/dist/index.js

@@ -573266,6 +573266,9 @@ function trajectoryCheckpointFingerprint(checkpoint) {
     checkpoint.goal,
     checkpoint.phase ?? "",
     checkpoint.currentStep ?? "",
+    checkpoint.situationAssessment ?? "",
+    checkpoint.groundingSource ?? "",
+    checkpoint.groundingEvidenceRefs?.join("
") ?? "",
     checkpoint.completedWork.join("
"),
     checkpoint.groundedFacts.map((fact) => `${fact.statement}\0${fact.evidence}\0${fact.freshness}`).join("
"),
     checkpoint.openQuestions.join("
"),
@@ -573381,19 +573384,39 @@ function buildTrajectoryCheckpoint(input) {
   if (state.pendingSteps.length > 0 && !state.nextAction.trim()) {
     openQuestions.push(`Choose the next pending task: ${sanitizeTrajectoryText(state.pendingSteps[0], 180)}`);
   }
+  const generated = input.generatedGrounding ?? null;
+  const canUseGenerated = Boolean(generated?.situationAssessment);
+  const groundingSource = canUseGenerated ? "model" : "deterministic";
+  const situationAssessment = canUseGenerated ? sanitizeTrajectoryText(generated?.situationAssessment, 420) : deterministicSituationAssessment({
+    goal,
+    outcomeText,
+    focus,
+    assessment,
+    targetPath
+  });
+  const currentStep = canUseGenerated && generated?.currentStep ? sanitizeTrajectoryText(generated.currentStep, 180) : sanitizeTrajectoryText(state.currentStep, 180);
+  const generatedOpenQuestions = canUseGenerated ? generated.openQuestions.map((value2) => sanitizeTrajectoryText(value2, 180)) : [];
+  const generatedConstraints = canUseGenerated ? generated.doNotRepeat.map((value2) => sanitizeTrajectoryText(value2, 220)) : [];
+  if (canUseGenerated && assessment === "on_trajectory") {
+    nextAction = sanitizeTrajectoryText(generated?.nextAction, 320) || nextAction;
+    successEvidence = sanitizeTrajectoryText(generated?.successEvidence, 280) || successEvidence;
+  }
   const checkpointWithoutIdentity = {
     schemaVersion: 1,
     trigger: sanitizeTrajectoryText(input.trigger || inferTrigger(outcome), 80),
     assessment,
     goal,
     phase: sanitizeTrajectoryText(state.phase, 60) || void 0,
-    currentStep: sanitizeTrajectoryText(state.currentStep, 180) || void 0,
+    currentStep: currentStep || void 0,
+    situationAssessment,
+    groundingSource,
+    groundingEvidenceRefs: canUseGenerated ? unique2(generated.evidenceRefs, MAX_FACTS) : void 0,
     completedWork,
     groundedFacts: groundedFacts.slice(0, MAX_FACTS),
-    openQuestions: unique2(openQuestions, 2),
+    openQuestions: unique2([...openQuestions, ...generatedOpenQuestions], 2),
     nextAction: sanitizeTrajectoryText(nextAction, 320),
     successEvidence: sanitizeTrajectoryText(successEvidence, 280),
-    doNotRepeat: unique2(doNotRepeat, MAX_CONSTRAINTS)
+    doNotRepeat: unique2([...doNotRepeat, ...generatedConstraints], MAX_CONSTRAINTS)
   };
   const fingerprint = trajectoryCheckpointFingerprint(checkpointWithoutIdentity);
   return {
@@ -573411,19 +573434,87 @@ function renderTrajectoryCheckpoint(checkpoint, maxChars = 1100) {
     `Assessment: ${checkpoint.assessment}`,
     checkpoint.phase ? `Phase: ${checkpoint.phase}` : null,
     checkpoint.currentStep ? `Current step: ${checkpoint.currentStep}` : null,
+    // Keep the action contract ahead of explanatory evidence so truncation can
+    // never hide the guard that the main agent must follow.
+    `Required next action: ${checkpoint.nextAction}`,
+    `Success evidence: ${checkpoint.successEvidence}`,
+    checkpoint.situationAssessment ? `${checkpoint.groundingSource === "model" ? "Reasoned situation" : "Safety orientation"}: ${checkpoint.situationAssessment}` : null,
+    checkpoint.groundingEvidenceRefs?.length ? `Grounding evidence: ${checkpoint.groundingEvidenceRefs.join(", ")}` : null,
     checkpoint.completedWork.length > 0 ? `Completed evidence-backed work: ${checkpoint.completedWork.join("; ")}` : null,
     checkpoint.groundedFacts.length > 0 ? "Grounded facts:" : null,
     ...checkpoint.groundedFacts.map((fact) => `- [${fact.evidence}; ${fact.freshness}] ${fact.statement}`),
     checkpoint.openQuestions.length > 0 ? "Open questions:" : null,
     ...checkpoint.openQuestions.map((question) => `- ${question}`),
-    `Required next action: ${checkpoint.nextAction}`,
-    `Success evidence: ${checkpoint.successEvidence}`,
     checkpoint.doNotRepeat.length > 0 ? "Do not repeat:" : null,
     ...checkpoint.doNotRepeat.map((constraint) => `- ${constraint}`),
     "Attention rule: reconcile the next tool call with this checkpoint. Treat stale or unknown evidence as a reason to read or verify. Do not quote this checkpoint or produce a reasoning transcript."
   ].filter((line) => Boolean(line));
   return truncate(lines.join("\n"), maxChars);
 }
+function buildTrajectoryGroundingPrompt(checkpoint, supplementalEvidence = []) {
+  const evidenceRefs = [
+    "goal",
+    ...checkpoint.groundedFacts.map((fact) => fact.evidence),
+    "unknown"
+  ];
+  const evidence = supplementalEvidence.map((value2) => sanitizeTrajectoryText(value2, 700)).filter(Boolean).slice(0, 6);
+  return [
+    "[TRAJECTORY GROUNDING REQUEST]",
+    "Before the main agent takes its first action, form a compact, task-specific orientation from the supplied evidence.",
+    "Reason about what is known, what remains unknown, and why the next action is the best immediate move. Do not use generic filler such as 'take a narrow action'.",
+    "Do not invent files, source contents, tool results, verification results, or completed work. Do not reveal private chain-of-thought; provide only a concise, auditable situation assessment.",
+    "The deterministic assessment and constraints below are safety facts. You may refine the plan, but never weaken a recovery, verification, or blocker constraint.",
+    "Return ONLY JSON with this schema:",
+    JSON.stringify({
+      situation_assessment: "1-3 concise, evidence-bound sentences",
+      current_step: "optional concrete current phase",
+      open_questions: ["specific unknown that gates the next action"],
+      next_action: "one concrete next action",
+      success_evidence: "what observable result proves the action helped",
+      do_not_repeat: ["specific unsafe or ungrounded retry to avoid"],
+      evidence_refs: ["one or more labels from allowed_evidence_refs"]
+    }),
+    "Authoritative trajectory input:",
+    JSON.stringify({
+      goal: checkpoint.goal,
+      assessment: checkpoint.assessment,
+      current_step: checkpoint.currentStep,
+      completed_work: checkpoint.completedWork,
+      grounded_facts: checkpoint.groundedFacts,
+      open_questions: checkpoint.openQuestions,
+      required_next_action: checkpoint.nextAction,
+      success_evidence: checkpoint.successEvidence,
+      do_not_repeat: checkpoint.doNotRepeat,
+      allowed_evidence_refs: evidenceRefs,
+      supplemental_evidence: evidence
+    }, null, 2)
+  ].join("\n\n");
+}
+function parseTrajectoryGeneratedGrounding(raw, allowedEvidenceRefs) {
+  const parsed = parseJsonObject3(raw);
+  if (!parsed)
+    return null;
+  const situationAssessment = sanitizeTrajectoryText(parsed["situation_assessment"] ?? parsed["situationAssessment"], 420);
+  if (!situationAssessment)
+    return null;
+  const allowed = /* @__PURE__ */ new Set([
+    "goal",
+    "unknown",
+    ...allowedEvidenceRefs.map((value2) => sanitizeTrajectoryText(value2, 160))
+  ]);
+  const refs = stringArray3(parsed["evidence_refs"] ?? parsed["evidenceRefs"], 5).filter((value2) => allowed.has(value2));
+  return {
+    situationAssessment,
+    currentStep: sanitizeTrajectoryText(parsed["current_step"] ?? parsed["currentStep"], 180) || void 0,
+    openQuestions: stringArray3(parsed["open_questions"] ?? parsed["openQuestions"], 3),
+    nextAction: sanitizeTrajectoryText(parsed["next_action"] ?? parsed["nextAction"], 320) || void 0,
+    successEvidence: sanitizeTrajectoryText(parsed["success_evidence"] ?? parsed["successEvidence"], 280) || void 0,
+    doNotRepeat: stringArray3(parsed["do_not_repeat"] ?? parsed["doNotRepeat"], MAX_CONSTRAINTS),
+    // A goal is always an allowed fact; retain it as a conservative fallback
+    // for models that omit the optional citation field.
+    evidenceRefs: refs.length > 0 ? unique2(refs, MAX_FACTS) : ["goal"]
+  };
+}
 function scopeTrajectoryCheckpoint(checkpoint, delegatedScope, exitEvidence) {
   if (!checkpoint)
     return null;
@@ -573521,6 +573612,41 @@ function extractFocusNextAction(value2) {
 function unique2(values, limit) {
   return [...new Set(values.map((value2) => sanitizeTrajectoryText(value2)).filter(Boolean))].slice(0, limit);
 }
+function deterministicSituationAssessment(input) {
+  if (input.outcomeText) {
+    return `The latest observed result is ${input.outcomeText}. The next step must respond to that evidence rather than assume the task state changed.`;
+  }
+  if (input.focus) {
+    return `An active recovery directive is present: ${input.focus}. It takes precedence over a generic continuation plan.`;
+  }
+  if (input.assessment !== "on_trajectory") {
+    return `The runner has classified this task as ${input.assessment.replace(/_/g, " ")}${input.targetPath ? ` around ${input.targetPath}` : ""}; preserve the stated safety contract while collecting the next observation.`;
+  }
+  return `No file, tool, or verifier observation has been recorded yet for "${input.goal}". Treat the user goal as the only established fact until the first project observation is made.`;
+}
+function parseJsonObject3(raw) {
+  if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+    return raw;
+  }
+  const text2 = String(raw ?? "").trim();
+  if (!text2)
+    return null;
+  const start2 = text2.indexOf("{");
+  const end = text2.lastIndexOf("}");
+  if (start2 < 0 || end <= start2)
+    return null;
+  try {
+    const parsed = JSON.parse(text2.slice(start2, end + 1));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+function stringArray3(value2, limit) {
+  if (!Array.isArray(value2))
+    return [];
+  return unique2(value2.map((item) => sanitizeTrajectoryText(item, 280)), limit);
+}
 function truncate(value2, max) {
   const clean5 = String(value2 ?? "").trim();
   return clean5.length > max ? `${clean5.slice(0, Math.max(0, max - 1))}…` : clean5;
@@ -579225,6 +579351,9 @@ function recordDebugTrajectoryCheckpoint(input) {
     trajectory: {
       revision: checkpoint.revision,
       assessment: checkpoint.assessment,
+      groundingSource: checkpoint.groundingSource,
+      situationAssessment: checkpoint.situationAssessment ? trim(checkpoint.situationAssessment, 700) : void 0,
+      groundingEvidenceRefs: checkpoint.groundingEvidenceRefs?.slice(0, 5).map((value2) => trim(value2, 160)),
       nextAction: trim(checkpoint.nextAction, 500),
       successEvidence: trim(checkpoint.successEvidence, 500),
       doNotRepeat: checkpoint.doNotRepeat.slice(0, 3).map((value2) => trim(value2, 300))
@@ -583109,6 +583238,36 @@ var init_completion_resolution_verifier = __esm({
 });
 
 // packages/orchestrator/dist/evidenceBranch.js
+function buildBranchExtractionBrief(input) {
+  const path16 = cleanBriefText(input.path, 320) || "the requested file";
+  const intent = firstBriefText([
+    input.assistantIntent,
+    input.trajectoryNextAction,
+    input.currentStep
+  ]);
+  const openQuestion = cleanBriefText(input.trajectoryOpenQuestion, 280);
+  const focus = openQuestion || intent;
+  const request = openQuestion ? `Determine the exact file-local facts in ${path16} that answer this unresolved agent question: ${openQuestion}` : intent ? `Identify the exact file-local facts in ${path16} that the active agent needs before it can ${asActionClause(intent)}.` : `Identify the exact declarations, behavior, and configuration in ${path16} needed to choose the next narrow action.`;
+  const triggerEvidence = uniqueBriefLines([
+    `The active action is a whole-file read of ${path16}; disk inspection found ${Math.max(0, input.lineCount)} lines / ${Math.max(0, input.byteCount)} bytes, so the parent context would otherwise receive only a preview.`,
+    input.trajectoryAssessment ? `Current trajectory assessment: ${cleanBriefText(input.trajectoryAssessment, 360)}` : "No current file-level evidence has been returned to the parent yet.",
+    input.currentStep ? `Current task step: ${cleanBriefText(input.currentStep, 260)}` : "",
+    input.recentFailure ? `Recent unresolved evidence: ${cleanBriefText(input.recentFailure, 320)}` : ""
+  ]);
+  const returnContract = focus ? `Return only the exact declarations, values, behavior, and line spans that resolve: ${focus}` : "Return only the exact declarations, values, behavior, and line spans needed for the next safe action.";
+  const retrievalQuery = uniqueBriefLines([
+    path16,
+    focus,
+    openQuestion,
+    "relevant declarations behavior configuration line spans"
+  ]).join(" ");
+  return {
+    request: cleanBriefText(request, 520),
+    triggerEvidence: triggerEvidence.slice(0, 4),
+    returnContract: cleanBriefText(returnContract, 520),
+    retrievalQuery: cleanBriefText(retrievalQuery, 700)
+  };
+}
 function buildStructuralPreview2(lines, path16, query) {
   const n2 = lines.length;
   const clip3 = (l2) => l2.length > 180 ? l2.slice(0, 180) + "…" : l2;
@@ -583135,6 +583294,29 @@ function queryTerms(query) {
     ...new Set(query.toLowerCase().replace(/[^a-z0-9_<>./-]+/g, " ").split(/\s+/).filter((w) => w.length > 2 && !STOPWORDS2.has(w)))
   ];
 }
+function cleanBriefText(value2, max) {
+  const clean5 = String(value2 ?? "").replace(/\x1B\[[0-?]*[ -/]*[@-~]/g, "").replace(/[\x00-\x1F\x7F]/g, " ").replace(/\s+/g, " ").trim();
+  return clean5.length > max ? `${clean5.slice(0, Math.max(0, max - 1))}…` : clean5;
+}
+function firstBriefText(values) {
+  for (const value2 of values) {
+    const clean5 = cleanBriefText(value2, 320);
+    if (!clean5)
+      continue;
+    if (/^take one narrow, evidence-backed action/i.test(clean5))
+      continue;
+    return clean5;
+  }
+  return "";
+}
+function uniqueBriefLines(values) {
+  return [
+    ...new Set(values.map((value2) => cleanBriefText(value2, 700)).filter(Boolean))
+  ];
+}
+function asActionClause(value2) {
+  return cleanBriefText(value2, 320).replace(/^to\s+/i, "").replace(/[.?!]+$/, "").replace(/^([A-Z])/, (match) => match.toLowerCase());
+}
 function selectWindows(lines, terms2) {
   const matched = [];
   for (let i2 = 0; i2 < lines.length; i2++) {
@@ -583185,12 +583367,17 @@ function selectWindows(lines, terms2) {
     score: m2.score
   }));
 }
-function extractionPrompt(query, path16, windows) {
+function extractionPrompt(brief, path16, windows) {
   const blocks = windows.map((w) => `--- ${path16} lines ${w.start}-${w.end} ---
 ${w.text}`).join("\n\n");
   return [
-    `You are an extraction worker in a throwaway context. Extract ONLY what answers the query; do not summarize the whole file.`,
-    `Query: ${query}`,
+    `You are an extraction worker in a throwaway context. Extract ONLY the information requested by the active agent; do not summarize the whole file.`,
+    `[AGENTIC BRANCH REQUEST]`,
+    `Request: ${brief.request}`,
+    `Why this branch is needed now:`,
+    ...brief.triggerEvidence.map((evidence) => `- ${evidence}`),
+    `Return contract: ${brief.returnContract}`,
+    `Retrieval focus: ${brief.retrievalQuery}`,
     ``,
     `File excerpts:`,
     blocks,
@@ -583229,7 +583416,14 @@ function parseExtraction(raw) {
   };
 }
 async function extractEvidence(opts) {
-  const { path: path16, query, content, fileVersion, backend } = opts;
+  const { path: path16, content, fileVersion, backend } = opts;
+  const brief = opts.brief ?? buildBranchExtractionBrief({
+    path: path16,
+    lineCount: content.split("\n").length,
+    byteCount: content.length,
+    assistantIntent: opts.query
+  });
+  const query = brief.retrievalQuery || opts.query;
   const lines = content.split("\n");
   const terms2 = queryTerms(query);
   if (terms2.length > 0) {
@@ -583304,7 +583498,7 @@ async function extractEvidence(opts) {
       const resp = await backend.chatCompletion({
         messages: [
           { role: "system", content: "You extract precise facts from file excerpts. Output ONLY a JSON object." },
-          { role: "user", content: extractionPrompt(query, path16, windows) }
+          { role: "user", content: extractionPrompt(brief, path16, windows) }
         ],
         tools: [],
         temperature: 0,
@@ -585808,6 +586002,16 @@ function resolveTrajectoryCheckpointCadence(explicit) {
   const candidate = typeof explicit === "number" ? explicit : Number(process.env["OMNIUS_TRAJECTORY_CHECKPOINT_EVERY_TURNS"] ?? 4);
   return Number.isFinite(candidate) ? Math.max(1, Math.min(32, Math.floor(candidate))) : 4;
 }
+function resolveTrajectoryGroundingMode(explicit, subAgent) {
+  if (explicit === "off" || explicit === "initial" || explicit === "adaptive") {
+    return explicit;
+  }
+  const env2 = String(process.env["OMNIUS_TRAJECTORY_GROUNDING"] ?? "").trim().toLowerCase();
+  if (env2 === "off" || env2 === "initial" || env2 === "adaptive") {
+    return env2;
+  }
+  return subAgent ? "off" : "adaptive";
+}
 function upsertContextFrame(messages2, frame, marker = "[ACTIVE CONTEXT FRAME]") {
   for (let i2 = messages2.length - 1; i2 >= 0; i2--) {
     const m2 = messages2[i2];
@@ -586673,6 +586877,9 @@ var init_agenticRunner = __esm({
       _trajectoryRevision = 0;
       _trajectoryDirtyCauses = /* @__PURE__ */ new Set();
       _trajectoryLastEmittedToolCall = -1;
+      _trajectoryGroundingAttemptedFingerprint = "";
+      _trajectoryGroundingFingerprint = "";
+      _trajectoryGeneratedGrounding = null;
       // -- File State Registry (SWE-agent inspired) --
       _fileRegistry = /* @__PURE__ */ new Map();
       // -- Memex Experience Archive (arXiv:2603.04257 inspired) --
@@ -588115,6 +588322,7 @@ ${parts.join("\n")}
           focusSupervisor: resolveFocusSupervisorMode(options2?.focusSupervisor),
           trajectoryCheckpoint: resolveTrajectoryCheckpointMode(options2?.trajectoryCheckpoint),
           trajectoryCheckpointEveryTurns: resolveTrajectoryCheckpointCadence(options2?.trajectoryCheckpointEveryTurns),
+          trajectoryGrounding: resolveTrajectoryGroundingMode(options2?.trajectoryGrounding, options2?.subAgent),
           supervisorModel: options2?.supervisorModel ?? process.env["OMNIUS_SUPERVISOR_MODEL"] ?? "",
           supervisorTimeoutMs: options2?.supervisorTimeoutMs ?? Number(process.env["OMNIUS_SUPERVISOR_TIMEOUT_MS"] ?? 2e4),
           supervisorMaxTokens: options2?.supervisorMaxTokens ?? 900,
@@ -593645,7 +593853,16 @@ ${String(concreteGoal).replace(/\s+/g, " ").trim().slice(0, 1200)}` : null
         const churnBlock = this._renderWriteChurnBlock(turn);
         const focusBlock = this._focusSupervisor?.renderFrame() ?? null;
         const actionContractBlock = this._renderNextActionContract(turn);
-        const trajectoryCheckpoint = this._refreshTrajectoryCheckpoint(turn, focusBlock);
+        const trajectoryCheckpoint = await this._refreshTrajectoryCheckpoint(turn, focusBlock, [
+          workspaceTreeBlock,
+          filesystemBlock,
+          todoBlock,
+          gitBlock,
+          failureBlock,
+          churnBlock,
+          actionContractBlock,
+          environmentBlock ?? null
+        ].filter((block) => Boolean(block)));
         const trajectoryBlock = this.options.trajectoryCheckpoint === "shadow" ? null : trajectoryCheckpoint ? renderTrajectoryCheckpoint(trajectoryCheckpoint) : null;
         const toolCacheBlock = recentToolResults ? this._renderKnowledgeBlock(recentToolResults) : null;
         const anchorsBlock = this.surfaceAnchors(messages2);
@@ -595137,17 +595354,39 @@ ${notice}`;
           return "unknown";
         return entry.stale ? "stale" : "fresh";
       }
+      /**
+       * Turn a large whole-file read into an explicit request from the active
+       * agent state, rather than treating the original user prompt as the query.
+       */
+      _buildBranchExtractionBrief(input) {
+        const visibleAssistantIntent = [...input.messages].reverse().find((message2) => message2.role === "assistant" && typeof message2.content === "string" && message2.content.trim().length > 0);
+        const assistantIntent = visibleAssistantIntent ? sanitizeTrajectoryText(sanitizeModelVisibleContextText(String(visibleAssistantIntent.content)), 320) : "";
+        const trajectory = this._trajectoryCheckpoint;
+        const latestFailure = this._recentFailures.at(-1);
+        const recentFailure = latestFailure ? `${latestFailure.tool} at turn ${latestFailure.turn}: ${sanitizeTrajectoryText(latestFailure.error || latestFailure.output, 320)}` : "";
+        return buildBranchExtractionBrief({
+          path: input.path,
+          lineCount: input.lineCount,
+          byteCount: input.byteCount,
+          assistantIntent,
+          trajectoryAssessment: trajectory?.situationAssessment,
+          trajectoryNextAction: trajectory?.nextAction || this._taskState.nextAction,
+          trajectoryOpenQuestion: trajectory?.openQuestions[0],
+          currentStep: this._taskState.currentStep,
+          recentFailure
+        });
+      }
       /**
        * Rebuild the one current checkpoint at the context boundary. This shared
        * method is deliberately used by normal and brute-force loops via
        * _buildTurnContextFrame(), preventing separate prompt injections from
        * drifting apart or accumulating in history.
        */
-      _refreshTrajectoryCheckpoint(turn, focusDirective) {
+      async _refreshTrajectoryCheckpoint(turn, focusDirective, supplementalEvidence = []) {
         if (this.options.trajectoryCheckpoint === "off")
           return null;
         const trigger = [...this._trajectoryDirtyCauses].join(",") || (this._trajectoryCheckpoint ? "cadence" : "task_start");
-        const provisional = buildTrajectoryCheckpoint({
+        const buildInput = (generatedGrounding2) => ({
           turn,
           revision: Math.max(1, this._trajectoryRevision || 1),
           trigger,
@@ -595157,8 +595396,12 @@ ${notice}`;
           focusDirective,
           lastVerifier: this._worldFacts.lastTest,
           lastMutationTurn: this._lastFileWriteTurn,
-          evidenceFreshness: (path16) => this._trajectoryEvidenceFreshness(path16)
+          evidenceFreshness: (path16) => this._trajectoryEvidenceFreshness(path16),
+          generatedGrounding: generatedGrounding2
         });
+        const deterministic = buildTrajectoryCheckpoint(buildInput());
+        const generatedGrounding = await this._resolveTrajectoryGrounding(deterministic, trigger, turn, supplementalEvidence);
+        const provisional = buildTrajectoryCheckpoint(buildInput(generatedGrounding));
         const { id: _id2, revision: _revision, turn: _turn, ...fingerprintInput } = provisional;
         const fingerprint = trajectoryCheckpointFingerprint(fingerprintInput);
         const changed = fingerprint !== this._trajectoryFingerprint;
@@ -595167,16 +595410,8 @@ ${notice}`;
           this._trajectoryFingerprint = fingerprint;
         }
         const checkpoint = buildTrajectoryCheckpoint({
-          turn,
-          revision: Math.max(1, this._trajectoryRevision),
-          trigger,
-          taskState: this._taskState,
-          observations: this._trajectoryObservations,
-          recentFailures: this._recentFailures,
-          focusDirective,
-          lastVerifier: this._worldFacts.lastTest,
-          lastMutationTurn: this._lastFileWriteTurn,
-          evidenceFreshness: (path16) => this._trajectoryEvidenceFreshness(path16)
+          ...buildInput(generatedGrounding),
+          revision: Math.max(1, this._trajectoryRevision)
         });
         this._trajectoryCheckpoint = checkpoint;
         const cadenceReached = this._taskState.toolCallCount - this._trajectoryLastEmittedToolCall >= this.options.trajectoryCheckpointEveryTurns;
@@ -595213,6 +595448,84 @@ ${notice}`;
         }
         return checkpoint;
       }
+      /**
+       * Run one bounded, tool-less orientation pass before the main agent acts.
+       * Its output is treated as advisory language over an authoritative
+       * deterministic safety checkpoint, so it can improve attention without
+       * inventing a new file state or bypassing a recovery constraint.
+       */
+      async _resolveTrajectoryGrounding(checkpoint, trigger, turn, supplementalEvidence) {
+        if (this.options.trajectoryCheckpoint === "shadow" || this.options.trajectoryGrounding === "off") {
+          return null;
+        }
+        const { id: _id2, revision: _revision, turn: _turn, ...base3 } = checkpoint;
+        const baseFingerprint = trajectoryCheckpointFingerprint(base3);
+        if (this._trajectoryGroundingFingerprint === baseFingerprint) {
+          return this._trajectoryGeneratedGrounding;
+        }
+        if (this._trajectoryGroundingAttemptedFingerprint === baseFingerprint) {
+          return null;
+        }
+        const isInitial = !this._trajectoryCheckpoint || /(?:^|,)task_start(?:,|$)/.test(trigger);
+        const assessmentChanged = checkpoint.assessment !== this._trajectoryCheckpoint?.assessment;
+        const materialTrigger = /tool_failure|(?:^|,)error(?:,|$)|user_steering|compaction|status_change/.test(trigger);
+        if (!isInitial && (this.options.trajectoryGrounding === "initial" || !assessmentChanged && !materialTrigger)) {
+          return null;
+        }
+        this._trajectoryGroundingAttemptedFingerprint = baseFingerprint;
+        try {
+          this._emitModelResolutionTelemetry("trajectory_grounding", turn);
+          const backend = this._auxInferenceBackend({
+            dumpStage: "trajectory_grounding"
+          });
+          const response = await backend.chatCompletion({
+            messages: [
+              {
+                role: "system",
+                content: "You are Omnius's pre-action trajectory grounder. Return only the requested JSON. Produce a concrete, evidence-bound orientation, not generic process advice and not private chain-of-thought."
+              },
+              {
+                role: "user",
+                content: buildTrajectoryGroundingPrompt(checkpoint, supplementalEvidence)
+              }
+            ],
+            tools: [],
+            temperature: 0.15,
+            maxTokens: 900,
+            timeoutMs: Math.max(5e3, Math.min(this.options.requestTimeoutMs, 3e4)),
+            // The output is an explicit concise assessment, not a hidden-think
+            // transcript. Keep Qwen's structured response path reliable.
+            think: false
+          });
+          const generated = parseTrajectoryGeneratedGrounding(response.choices?.[0]?.message?.content ?? "", checkpoint.groundedFacts.map((fact) => fact.evidence));
+          if (!generated) {
+            this.emit({
+              type: "status",
+              content: "Trajectory grounding returned no usable assessment; retaining deterministic safety orientation",
+              turn,
+              timestamp: (/* @__PURE__ */ new Date()).toISOString()
+            });
+            return null;
+          }
+          this._trajectoryGroundingFingerprint = baseFingerprint;
+          this._trajectoryGeneratedGrounding = generated;
+          this.emit({
+            type: "status",
+            content: `Trajectory grounding: model assessed ${isInitial ? "the initial task state" : "the changed task state"}`,
+            turn,
+            timestamp: (/* @__PURE__ */ new Date()).toISOString()
+          });
+          return generated;
+        } catch {
+          this.emit({
+            type: "status",
+            content: "Trajectory grounding unavailable; retaining deterministic safety orientation",
+            turn,
+            timestamp: (/* @__PURE__ */ new Date()).toISOString()
+          });
+          return null;
+        }
+      }
       emit(event) {
         this._observeTrajectoryEvent(event);
         for (const handler of this.handlers) {
@@ -595512,6 +595825,9 @@ Respond with your assessment, then take action.`;
         this._trajectoryRevision = 0;
         this._trajectoryDirtyCauses = /* @__PURE__ */ new Set(["task_start"]);
         this._trajectoryLastEmittedToolCall = -1;
+        this._trajectoryGroundingAttemptedFingerprint = "";
+        this._trajectoryGroundingFingerprint = "";
+        this._trajectoryGeneratedGrounding = null;
         this._runStartTime = Date.now();
         this._runErrorCount = 0;
         this._runErrorPatterns = [];
@@ -600620,15 +600936,17 @@ Respond with EXACTLY this structure before your next tool call:
                     }
                   }
                   if (fullContent && shouldBranchRead(trueBytes, trueLines, false)) {
-                    const lastAssistant = [...messages2].reverse().find((m2) => m2.role === "assistant" && typeof m2.content === "string");
-                    const query = [
-                      this._taskState.goal ?? "",
-                      typeof lastAssistant?.content === "string" ? lastAssistant.content : ""
-                    ].join(" ").trim().slice(0, 400) || "key facts, configuration, and structure";
+                    const branchBrief = this._buildBranchExtractionBrief({
+                      path: pRaw,
+                      lineCount: trueLines,
+                      byteCount: trueBytes,
+                      messages: messages2
+                    });
                     try {
                       const ev = await extractEvidence({
                         path: pRaw,
-                        query,
+                        query: branchBrief.retrievalQuery,
+                        brief: branchBrief,
                         content: fullContent,
                         // the REAL body, not the preview
                         fileVersion: this._worldFacts.files.get(pRaw)?.writeCount ?? 0,
@@ -600639,7 +600957,11 @@ Respond with EXACTLY this structure before your next tool call:
                       });
                       output = [
                         `[BRANCH-EXTRACT] ${pRaw} is large (${trueLines} lines, ${trueBytes} bytes); a whole-file read only returns a preview, so it was read in an isolated branch and distilled.`,
-                        `Distilled for: "${query.slice(0, 160)}"`,
+                        `[AGENTIC EXTRACTION REQUEST] ${branchBrief.request}`,
+                        `Evidence driving this request:`,
+                        ...branchBrief.triggerEvidence.map((evidence) => `- ${evidence}`),
+                        `Looking for: ${branchBrief.returnContract}`,
+                        `Retrieval focus: "${branchBrief.retrievalQuery.slice(0, 240)}"`,
                         `Relevant evidence (lines ${ev.sourceStart ?? "?"}-${ev.sourceEnd ?? "?"}, confidence ${ev.confidence.toFixed(2)}):`,
                         ev.claim,
                         `If you need a different region, call file_read with a specific offset+limit. Do NOT re-read the whole file — you already have the relevant content above.`
@@ -615887,6 +616209,7 @@ __export(dist_exports3, {
   buildSteeringPacket: () => buildSteeringPacket,
   buildSubAgentSystemPrompt: () => buildSubAgentSystemPrompt,
   buildTrajectoryCheckpoint: () => buildTrajectoryCheckpoint,
+  buildTrajectoryGroundingPrompt: () => buildTrajectoryGroundingPrompt,
   buildUnitTodos: () => buildUnitTodos,
   checkMilestoneComplete: () => checkMilestoneComplete,
   chooseCheapModelRoute: () => chooseCheapModelRoute,
@@ -616033,6 +616356,7 @@ __export(dist_exports3, {
   parseMetaCritique: () => parseMetaCritique,
   parsePlan: () => parsePlan,
   parseTextToolCalls: () => parseTextToolCalls,
+  parseTrajectoryGeneratedGrounding: () => parseTrajectoryGeneratedGrounding,
   partitionToolCalls: () => partitionToolCalls,
   persistAgentTaskSidecar: () => persistAgentTaskSidecar,
   persistPlannerArtefacts: () => persistPlannerArtefacts,
@@ -620024,7 +620348,7 @@ function mergeRecentById(existing, incoming, limit) {
   for (const item of [...existing ?? [], ...incoming]) merged.set(item.id, item);
   return [...merged.values()].sort((a2, b) => b.observedAt - a2.observedAt).slice(0, limit);
 }
-function parseJsonObject3(value2) {
+function parseJsonObject4(value2) {
   if (typeof value2 !== "string" || !value2.trim()) return null;
   try {
     const parsed = JSON.parse(value2);
@@ -620034,7 +620358,7 @@ function parseJsonObject3(value2) {
   }
 }
 function parseJsonObjectFromText(value2) {
-  const direct = parseJsonObject3(value2);
+  const direct = parseJsonObject4(value2);
   if (direct) return direct;
   const text2 = String(value2 ?? "");
   const candidates = [];
@@ -620072,7 +620396,7 @@ function parseJsonObjectFromText(value2) {
     }
   }
   for (const candidate of candidates.reverse()) {
-    const parsed = parseJsonObject3(candidate);
+    const parsed = parseJsonObject4(candidate);
     if (parsed) return parsed;
   }
   return null;
@@ -621083,7 +621407,7 @@ function formatLiveDashboardFromSnapshot(snapshot, opts = {}) {
   return lines;
 }
 function parseLiveMediaPayload(value2) {
-  const parsed = parseJsonObject3(value2);
+  const parsed = parseJsonObject4(value2);
   if (!parsed) return null;
   if (!Array.isArray(parsed["objects"]) && !Array.isArray(parsed["tracks"]) && !Array.isArray(parsed["faces"]) && !Array.isArray(parsed["segments"])) return null;
   return parsed;
@@ -621104,7 +621428,7 @@ function parseFaceIdentity(face) {
     };
   }
   const raw = face.identity_candidates;
-  const parsed = typeof raw === "string" ? parseJsonObject3(raw) : typeof raw === "object" && raw !== null ? raw : null;
+  const parsed = typeof raw === "string" ? parseJsonObject4(raw) : typeof raw === "object" && raw !== null ? raw : null;
   const faces = Array.isArray(parsed?.["faces"]) ? parsed["faces"] : [];
   const identified = faces.find((candidate) => candidate["identified"] === true && typeof candidate["name"] === "string" && candidate["name"]);
   if (identified) {
@@ -641970,6 +642294,17 @@ function buildTrajectoryLiveBlockLines(checkpoint, width, phase, truecolor = sup
   const bottom = `╰${"─".repeat(Math.max(0, w - 2))}╯`;
   const lines = [paint2(top, stage2, phase, 0, truecolor)];
   lines.push(row(`Goal: ${checkpoint.goal}`, inner, stage2, phase, truecolor));
+  if (checkpoint.situationAssessment) {
+    lines.push(
+      row(
+        `${checkpoint.groundingSource === "model" ? "Reasoned" : "Safety"}: ${checkpoint.situationAssessment}`,
+        inner,
+        stage2,
+        phase,
+        truecolor
+      )
+    );
+  }
   lines.push(
     row(
       `Next: ${checkpoint.nextAction}`,
@@ -696240,7 +696575,7 @@ function numberArray(value2) {
   if (!Array.isArray(value2)) return [];
   return [...new Set(value2.map((item) => Number(item)).filter((item) => Number.isFinite(item)).map((item) => Math.trunc(item)))];
 }
-function stringArray3(value2) {
+function stringArray4(value2) {
   if (!Array.isArray(value2)) return [];
   return [...new Set(value2.map((item) => clean4(item, 180)).filter(Boolean))];
 }
@@ -696311,7 +696646,7 @@ function buildTelegramReflectionExtractionPrompt(options2) {
     episodes || "none"
   ].join("\n");
 }
-function parseJsonObject4(raw) {
+function parseJsonObject5(raw) {
   const text2 = raw.trim();
   if (!text2) return null;
   const fenced = text2.match(/```(?:json)?\s*([\s\S]*?)```/i)?.[1]?.trim();
@@ -696325,7 +696660,7 @@ function parseJsonObject4(raw) {
   }
 }
 function parseTelegramReflectionExtraction(raw) {
-  const parsed = parseJsonObject4(raw);
+  const parsed = parseJsonObject5(raw);
   if (!parsed) return null;
   const tags = Array.isArray(parsed.tags) ? parsed.tags.map((item) => {
     const obj = item;
@@ -696334,8 +696669,8 @@ function parseTelegramReflectionExtraction(raw) {
       kind: clean4(obj.kind, 40) || "topic",
       confidence: clampConfidence(obj.confidence),
       sourceMessageIds: numberArray(obj.source_message_ids ?? obj.sourceMessageIds),
-      targetEpisodeIds: stringArray3(obj.target_episode_ids ?? obj.targetEpisodeIds),
-      targetNodeIds: stringArray3(obj.target_node_ids ?? obj.targetNodeIds)
+      targetEpisodeIds: stringArray4(obj.target_episode_ids ?? obj.targetEpisodeIds),
+      targetNodeIds: stringArray4(obj.target_node_ids ?? obj.targetNodeIds)
     };
   }).filter((item) => item.label) : [];
   const summaries = Array.isArray(parsed.summaries) ? parsed.summaries.map((item) => {
@@ -696346,7 +696681,7 @@ function parseTelegramReflectionExtraction(raw) {
       text: clean4(obj.text, 1200),
       confidence: clampConfidence(obj.confidence),
       sourceMessageIds: numberArray(obj.source_message_ids ?? obj.sourceMessageIds),
-      targetEpisodeIds: stringArray3(obj.target_episode_ids ?? obj.targetEpisodeIds)
+      targetEpisodeIds: stringArray4(obj.target_episode_ids ?? obj.targetEpisodeIds)
     };
   }).filter((item) => item.title && item.text) : [];
   const titles = Array.isArray(parsed.titles) ? parsed.titles.map((item) => {
@@ -696356,7 +696691,7 @@ function parseTelegramReflectionExtraction(raw) {
       target: clean4(obj.target, 60) || "artifact",
       confidence: clampConfidence(obj.confidence),
       sourceMessageIds: numberArray(obj.source_message_ids ?? obj.sourceMessageIds),
-      targetEpisodeIds: stringArray3(obj.target_episode_ids ?? obj.targetEpisodeIds)
+      targetEpisodeIds: stringArray4(obj.target_episode_ids ?? obj.targetEpisodeIds)
     };
   }).filter((item) => item.title) : [];
   const extractions = Array.isArray(parsed.extractions) ? parsed.extractions.map((item) => {
@@ -696366,8 +696701,8 @@ function parseTelegramReflectionExtraction(raw) {
       text: clean4(obj.text, 1e3),
       confidence: clampConfidence(obj.confidence),
       sourceMessageIds: numberArray(obj.source_message_ids ?? obj.sourceMessageIds),
-      targetEpisodeIds: stringArray3(obj.target_episode_ids ?? obj.targetEpisodeIds),
-      targetNodeIds: stringArray3(obj.target_node_ids ?? obj.targetNodeIds)
+      targetEpisodeIds: stringArray4(obj.target_episode_ids ?? obj.targetEpisodeIds),
+      targetNodeIds: stringArray4(obj.target_node_ids ?? obj.targetNodeIds)
     };
   }).filter((item) => item.text) : [];
   const links2 = Array.isArray(parsed.links) ? parsed.links.map((item) => {
@@ -696379,7 +696714,7 @@ function parseTelegramReflectionExtraction(raw) {
       confidence: clampConfidence(obj.confidence),
       fact: clean4(obj.fact, 500),
       sourceMessageIds: numberArray(obj.source_message_ids ?? obj.sourceMessageIds),
-      targetEpisodeIds: stringArray3(obj.target_episode_ids ?? obj.targetEpisodeIds)
+      targetEpisodeIds: stringArray4(obj.target_episode_ids ?? obj.targetEpisodeIds)
     };
   }).filter((item) => item.srcNodeText && item.dstNodeText) : [];
   const followups = Array.isArray(parsed.followups) ? parsed.followups.map((item) => {
@@ -751658,7 +751993,10 @@ Only tools allowed by this profile are visible and executable.`
     personality: personality ? getPreset(personality) : void 0,
     personalityName: personality ?? void 0,
     identityInjection,
-    environmentProvider
+    environmentProvider,
+    // A real pre-action orientation is required before the main TUI agent
+    // chooses its first tool; later failure/direction changes re-ground it.
+    trajectoryGrounding: "adaptive"
     // Text tool mode is set dynamically after runner creation (async check)
     // The runner also auto-detects this when Ollama returns HTTP 400 for tools
   });

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "omnius",
-  "version": "1.0.540",
+  "version": "1.0.542",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "omnius",
-      "version": "1.0.540",
+      "version": "1.0.542",
       "bundleDependencies": [
         "image-to-ascii"
       ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omnius",
-  "version": "1.0.540",
+  "version": "1.0.542",
   "description": "AI coding agent powered by open-source models (Ollama/vLLM) — interactive TUI with agentic tool-calling loop",
   "type": "module",
   "main": "./dist/index.js",