# Omnius Context Engineering Behavior Fixes

Date: 2026-06-29

Source observation: current Omnius behavior while supervising a noclip/earth sidebar cleanup task. The observed run mixed internal cognitive-agent artifacts with user-task artifacts, repeated stale edit attempts after the file had changed, and overclaimed completion despite stale or missing verification.

## Work Order

### 1. Isolate Internal Runners From User-Task Artifacts

Status: implemented in this work session.

Problem: DMN, emotion, and SNR evaluator runners instantiate `AgenticRunner` as normal task runners. Their internal prompts can write handoffs, reflections, completion ledgers, provenance, and task memory that later pollute user-task context.

Implementation:
- Add `artifactMode?: "user-task" | "internal"` to `AgenticRunnerOptions`.
- Treat `subAgent: true` as isolated for backward compatibility, but use `artifactMode: "internal"` for cognitive helper runners.
- Disable automatic cross-task handoff read/write in internal mode.
- Disable task reflection read/write in internal mode.
- Avoid creating completion contracts/ledgers for internal mode.
- Avoid writing consolidation/provenance/task-summary artifacts for internal mode.
- Pass `artifactMode: "internal"` from DMN, emotion, and SNR internal runners.

Acceptance:
- Internal runner prompts cannot become `.omnius/handoffs/latest.json`.
- Internal zero-turn failures cannot become task reflections.
- User-task runners continue writing normal artifacts.

### 2. Replace Loop Escape Equals `task_complete`

Status: implemented in this work session.

Problem: the loop intervention still injects a mandatory `task_complete` directive after detecting repetition. This encourages partial or false completion.

Implementation:
- Remove the mandatory `task_complete` wording from loop intervention.
- Instruct the model to stop repeating the implicated tool family.
- Prefer verification when files changed, reread the exact target once for stale edits, ask the user if genuinely blocked, or report incomplete/blocking status.

Acceptance:
- Loop intervention text never says to call `task_complete` with whatever is available.
- Existing `ask_user` circuit-breaker remains the high-tier escape path.

### 3. Hard-Block Stale Edit Loops

Status: implemented in this work session.

Problem: exact duplicate detection does not catch stale edit families. The observed run repeatedly retried an old `file_edit` even after the target text was already absent.

Implementation:
- Add a stale edit fingerprint for `file_edit`, `file_patch`, and `batch_edit`.
- Track repeated failed edit families by path, normalized target text, and error class.
- After the threshold, block the edit before dispatch and provide a concrete recovery instruction.
- When the tool output indicates the old text is absent or no replacement occurred, record the failure family.

Acceptance:
- A repeated `old_string not found` edit is blocked after repeated failures.
- The block tells the model to read the current target once, verify if already satisfied, or choose a different patch.

### 4. Make Completion State Truth-Based, Not Summary-Based

Status: implemented in this work session.

Problem: the completion ledger records tool evidence but only creates claims from model-proposed completion text. Timeout/open runs can end with evidence but no truth-state synthesis.

Implementation:
- Track mutation and verification evidence from tool results.
- Add finalization helpers that derive unresolved items when mutations occur after the last successful verification.
- Mark repeated stale edit blocks as unresolved evidence.
- Finalize open ledgers as `incomplete_verification` when unresolved evidence exists.

Acceptance:
- A run with file mutations after its last verification cannot look cleanly complete.
- A timeout/open run can still explain unresolved evidence without a `task_complete` summary.

### 5. Stop Todo Chunker Overclaiming Completion

Status: implemented in this work session.

Problem: todo context chunks are marked `completed` even when summaries contain unresolved work, failed edit loops, or stale verification.

Implementation:
- Add `partial` and `unverified` chunk statuses.
- Compute chunk status from unresolved and verification text instead of always setting `completed`.
- Make heuristic fallback conservative: never invent completion when evidence is ambiguous.

Acceptance:
- A chunk containing unresolved failures is not marked `completed`.
- A chunk lacking verification is `unverified` unless explicit verification evidence exists.

### 6. Add Defensive Handoff and Reflection Quality Gates

Status: implemented in this work session.

Problem: even with internal isolation, stale/low-quality handoffs and reflections should be rejected at the storage boundary.

Implementation:
- Add handoff metadata for artifact mode and quality.
- Reject handoffs for internal prompt families, zero-turn/no-tool runs, empty summaries with no files/tools, and known SNR/DMN/emotion evaluator prompts.
- Reject task reflections for the same internal prompt families and zero-progress helper failures.
- Fix duplicate `failedPaths` assignment in reflection serialization.

Acceptance:
- Internal prompt families cannot be persisted as user-task handoff/reflection artifacts.
- Empty zero-tool helper failures are quarantined instead of injected into later user tasks.

## Verification Plan

- Add focused unit coverage for artifact isolation, stale edit blocking, loop intervention wording, handoff/reflection quality gates, completion ledger finalization, and todo chunk status.
- Run the affected test files first:
  - `packages/orchestrator/tests/critic.test.ts`
  - `packages/orchestrator/tests/completionLedger.test.ts`
  - `packages/orchestrator/tests/reflection.test.ts`
  - `packages/cli/tests/task-handoff.test.ts`
  - `packages/cli/tests/dmn-engine.test.ts`
  - `packages/cli/tests/emotion-engine.test.ts`
- Run the relevant package test command after focused tests pass.

## Live Multimodal Regression Work Order

Date: 2026-06-30

Source observation: aggressive live testing surfaced visual-memory CLIP wrapper failures, active todo overclaiming after failed tool calls, JSON/headless lifecycle drift, and noisy global context recall. Follow-up correction: context selection must be semantic/vector/inference based, not hard-coded English keyword filters.

### 7. Fix CLIP/SigLIP Feature Output Unwrapping

Status: implemented.

Problem: `visual_memory teach` and related multimodal CLIP paths failed when transformers returned `BaseModelOutputWithPooling` instead of a tensor, causing `.norm(...)` to crash.

Implementation:
- Add a shared Python helper that unwraps `image_embeds`, `text_embeds`, `pooler_output`, `last_hidden_state[:, 0]`, tuple/list outputs, or plain tensors before normalization.
- Inject the helper into `visual_memory` object teach/recognize paths.
- Inject the helper into multimodal episode image/text CLIP embedding paths.
- Add source-level unit coverage for wrapper support.

### 8. Make Vision Failures Actionable First

Status: implemented.

Problem: warnings and dependency noise could hide the actual traceback root cause from the model.

Implementation:
- Export and harden `summarizeProcessFailure`.
- Put the final exception line first as `Root cause: ...`.
- Preserve traceback context and tail output below it.

### 9. Truth-Reconcile Active Todos From Tool Evidence

Status: implemented.

Problem: the live agent marked “Teach each object to visual_memory” completed even though every matching `visual_memory teach` call failed.

Implementation:
- Add `todoTruth` reconciliation.
- Downgrade completed todos to `blocked` when matching tool-family evidence failed and no later same-family success exists.
- Run reconciliation immediately after successful `todo_write`, before verification nudges and todo chunking.
- Add a system message instructing the model to reconfigure the affected subtask instead of overclaiming.

### 10. First-Class Nested Todo Decomposition

Status: implemented.

Problem: `parentId` existed in storage but was not an explicit task decomposition contract and parents could overclaim child completion.

Implementation:
- Expand `todo_write` instructions for stable ids, `parentId`, leaf-subtask work, and evidence-driven tree rewrites.
- Add parent truth reconciliation: a parent cannot be completed while any child is pending, in progress, or blocked.
- Render nested todos in the TUI with indentation.
- Add tests for parent/child persistence and parent downgrade behavior.

### 11. Semantic Context Selection, Not English Keyword Filters

Status: implemented.

Problem: persisted failure modes and preflight memories must not be admitted by hard-coded English regex/stopword heuristics.

Implementation:
- Remove semantic keyword filtering from `failureHandoff`.
- Add runner-side task-to-failure-pattern selection using embedding batch cosine similarity.
- Add inference fallback for failure-pattern relevance when embeddings are unavailable.
- If neither vector nor inference scoring is available, inject no persisted failure patterns rather than guessing.
- Convert preflight memory recall to async embedding retrieval and cosine scoring over stored episode embeddings.
- Add source guards to prevent reintroducing the keyword matcher/internal-recall filter.

### 12. Explicit Degraded Completion Contract

Status: implemented.

Problem: the resolution gate blocked completion even when the original user task explicitly allowed documenting a tool failure as the desired fallback outcome.

Implementation:
- Add an auxiliary inference verdict for degraded-completion allowance.
- Accept degraded completion only when the inference verdict says the original request permits it, the summary discloses the failure, and fallback evidence exists.
- Update the verifier prompt to understand explicitly permitted degraded fallback.

### 13. Headless JSON Lifecycle

Status: implemented.

Problem: `omnius --json` could emit a final JSON object but keep running post-task trajectory/memory side effects and could report completed without the actual runner result.

Implementation:
- Add `onRunResult` callback to `runWithTUI`.
- JSON mode uses runner `completed/status/summary/turns/toolCalls/filesEdited/testsRun`.
- Headless mode skips non-critical post-run identity/archive/trajectory/cohere side effects.
- Headless errors throw back to JSON mode instead of directly exiting inside `runWithTUI`.
- Add controlled force-exit for JSON CLI with test opt-out.

### 14. Model Resolution Telemetry

Status: implemented.

Problem: live testing showed ambiguity between requested visible model and models used by auxiliary/background calls.

Implementation:
- Emit status telemetry for main runner model resolution.
- Emit status telemetry for completion-resolution and failure-pattern relevance inference calls.

### 15. Crossmodal Self-Test Isolation

Status: implemented.

Problem: crossmodal self-test used the live repo `.omnius/memory.db`, printed false retrieval results, and still exited successfully.

Implementation:
- Use temporary isolated memory DBs.
- Fail when image/text embeddings are unavailable or retrieval top result is false.
- Close stores and remove temp directories.

### 16. Truth-Based Terminal Completion After Verified Todo Closure

Status: implemented in source; pending publish/live reinstall verification.

Problem: live headless testing with `robit/ornith:35b` completed the nested todo tree, edited the requested files, ran the declared verification command successfully, and then stalled after the REG-31 "call task_complete" prompt. The runner had enough structured truth evidence but still depended on another model turn for the final terminal action.

Implementation:
- Add a pure truth-based completion decision module.
- Require all todos completed, zero unresolved verification failures, and a fresh successful declared `verifyCommand`.
- Prefer structural matching against `todo.verifyCommand` for validation success.
- Move generic command-name completion detection behind `OMNIUS_ENABLE_GENERIC_COMPLETION_COMMAND_HEURISTIC=1`.
- Synthesize terminal completion before another model request, while still running existing completion/provenance/backward-pass gates.

Acceptance:
- A fully verified todo tree can finish headless JSON without waiting on a final model-generated `task_complete`.
- Partial work, open children, stale validation, or unresolved verification failures remain incomplete.
- Completion automation is anchored to declared verification evidence, not English command-name filters.

### 17. Keep Verify-Command Evidence Separate From Artifact Evidence

Status: implemented in source; pending publish/live reinstall verification.

Problem: a live local run marked a final todo completed with a combined `verifyCommand` it had not run exactly. REG-37 recorded the missing verifier, but REG-38 artifact inspection then cleared the same aggregate failure because the files existed. The model then called `task_complete` and overclaimed the combined verifier as proven.

Implementation:
- Add structural verification-command matching.
- Accept exact verifier commands and reliable `verify && echo ...` suffixes.
- Reject `verify && echo ok || echo failed` wrappers because they can mask failure with exit 0.
- Allow a conjunctive verifier to be satisfied by separately successful reliable component commands.
- Track verify-command failures and artifact-inspection failures separately, then combine them into the completion gate.
- Block `task_complete` while any todo verification failure remains unresolved.
- Replace todo-write verification nudge content regex with structured `verifyCommand` / `declaredArtifacts` evidence checks.

Acceptance:
- Artifact existence cannot clear a missing `verifyCommand`.
- A `task_complete` call is held when the todo tree still has unresolved verification evidence.
- Verification nudges are structural, not English content heuristics.

### 18. Preserve Phase Archives in ESM Builds

Status: implemented in source; pending publish/live reinstall verification.

Problem: live local JSON runs emitted `Phase archive failed (non-fatal): require is not defined`. Phase archives are context-continuity artifacts for long tasks; losing them weakens later phase recall and forensic review.

Implementation:
- Replace runtime `require("node:fs")` and `require("node:path")` uses in `agenticRunner.ts` with existing ESM-safe top-level imports.
- Cover phase archives, KG summary writes/pruning, and checkpoint persistence in the same pass.

Acceptance:
- ESM-built CLI runs can write `.omnius/phases/` archives without `require` failures.
- Long-task context contraction keeps disk-backed phase recovery available.