loopforge 3.7.0 → 3.8.1

package/dist/protocol.d.ts

@@ -9,7 +9,6 @@ export declare enum Mode {
     LOOP_COMPILE = "loop_compile",
     FEEDBACK = "feedback"
 }
-import type { PresentedStateSnapshot } from "./canonical-state.js";
 export declare enum AgentStatus {
     OK = "ok",
     ERROR = "error",
@@ -22,27 +21,6 @@ export interface ExecutionFeedback {
     manual_fixes_needed: string;
 }
 export declare function makeExecutionFeedback(overrides?: Partial<ExecutionFeedback>): ExecutionFeedback;
-/** P4: Structured execution evidence reported by the agent after each round.
- *  Gives LoopForge visibility into what actually happened — files changed,
- *  test results, success criteria met, and a subjective progress estimate.
- *  Enables the compiler to cross-validate agent claims and compute real progress. */
-export interface ExecutionEvidence {
-    /** Files changed in this round. Empty if no files were modified. */
-    files_changed: string[];
-    /** Test results. null if no tests were run. */
-    test_results: {
-        passed: number;
-        failed: number;
-        skipped: number;
-    } | null;
-    /** Success criteria from the Loop Objective that were MET this round. */
-    success_criteria_met: string[];
-    /** Success criteria from the Loop Objective that REMAIN unmet. */
-    success_criteria_remaining: string[];
-    /** Agent's own estimate of overall progress (0.0 to 1.0). */
-    progress_estimate: number;
-}
-export declare function makeExecutionEvidence(overrides?: Partial<ExecutionEvidence>): ExecutionEvidence;
 /** P5: A revision to a success criterion — the old form and the new form.
  *  The agent proposes this when it discovers the original criterion was
  *  wrong, unrealistic, or needs refinement. */
@@ -50,43 +28,6 @@ export interface CriterionRevision {
     old: string;
     new: string;
 }
-/** v3.3: Round Contract. v3.4 semantics: the field on a submission is a
- *  PROPOSAL for the NEXT round — it becomes the ACTIVE contract (rendered
- *  as the Current Task and checked for execution conformance) only after
- *  the declaring round commits, and stays active until a committed eval
- *  lists every done_when item in success_criteria_met (complete) or
- *  reports outcome="blocked". While active it is restated unchanged each
- *  round; on completion or block, the next contract is declared instead.
- *  The ACTIVE contract is machine-derived from committed rounds
- *  (round-contract.ts) — never read from last_round_result. Optional:
- *  absent = no contract this round, all contract checks stay silent and
- *  rendering is identical to a contract-less round.
- *
- *  Every field is machine-checkable:
- *  - done_when items are claimed satisfied by listing them in
- *    execution_evidence.success_criteria_met (verified per-round claim
- *    model); leaving them out while success is claimed is premature_boundary
- *    against the ACTIVE contract.
- *  - verification_plan names must reference configured, enabled
- *    evidence.commands (round_unverifiable otherwise).
- *  - scope lists the files/directories the round may touch; actual git
- *    changes outside it trigger round_scope_drift against the ACTIVE
- *    contract. */
-export interface RoundContract {
-    /** Round focus, one line. Rendered as the Current Task's first line. */
-    work_item?: string;
-    /** Completion conditions: cr-XXXXXXXX criterion IDs or free text.
-     *  Claimed met = listed in success_criteria_met; still open = listed in
-     *  success_criteria_remaining. ≤ 20 items. */
-    done_when: string[];
-    /** Verification plan: names of configured, enabled evidence commands
-     *  (policy.evidence.commands[].name). ≤ 20 items. */
-    verification_plan: string[];
-    /** Files/directories this round may touch (workspace-relative paths,
-     *  forward or back slashes, "./" prefix and trailing slashes accepted).
-     *  Out-of-scope git changes = round_scope_drift. ≤ 50 items. */
-    scope: string[];
-}
 /** Structured self-evaluation submitted at the round boundary.
  *  The agent outputs this after completing each round.
  *  Every field is consumed by at least one downstream function.
@@ -101,8 +42,8 @@ export interface SelfEvaluation {
      *  computeConstraintRetirement (activity detection), vault lineage. */
     output_summary: string;
     /** Constraints the agent actually violated this round.
-     *  Feeds: checkLoopHealth (constraint_integrity),
-     *  buildRollingSummary (recurring_issues), computeConstraintRetirement. */
+     *  Feeds: deriveRecurringFlags (the constraint_violation kind) and
+     *  computeConstraintRetirement. */
     constraint_violations: string[];
     /** false ONLY when the entire task is complete. Tells the autonomous
      *  runner to stop the loop. Not consumed by the compiler. */
@@ -117,12 +58,22 @@ export interface SelfEvaluation {
     objective_refinement?: string;
     /** P2: Sub-problems that surfaced during execution and may need
      *  separate attention. Feed into the next-task suggestion.
-     *  Omit or leave empty if none emerged. */
+     *  Omit or leave empty if none emerged.
+     *  v3.7.1: this is the ONLY creation channel. A text matching the
+     *  sg-XXXXXXXX ID pattern is rejected — creation never accepts an
+     *  ID reference (that would fabricate a phantom hashed item). */
     emerged_subtasks?: string[];
+    /** v3.7.1: Explicit status transitions for EXISTING sub-goals. Each
+     *  entry must reference a committed sub-goal ID (sg-XXXXXXXX) and a
+     *  legal target status; unknown IDs, terminal (done/canceled)
+     *  references, and illegal migrations are evaluation_invalid before
+     *  the round advances. in_progress is only reachable through this
+     *  field — the runtime no longer infers it. */
+    subgoal_updates?: SubGoalUpdate[];
     /** P4: Structured evidence of what was executed this round.
      *  Files changed, test results, criteria met/remaining, progress estimate.
      *  Enables the compiler to validate claims and compute real progress. */
-    execution_evidence?: ExecutionEvidence;
+    execution_report?: ExecutionReport;
     /** P5: Constraints that the agent now believes are wrong or irrelevant.
      *  Removed from the active constraint set by the compiler.
      *  Omit or leave empty if none. */
@@ -146,28 +97,12 @@ export interface SelfEvaluation {
      *  The engine automatically writes these to the delegation journal.
      *  Omit or leave empty if no delegations occurred. */
     worker_results?: WorkerResult[];
-    /** v1.16: Agent's declared next action — what it plans to do in the
-     *  following round. Stored as loop state and rendered in the next prompt
-     *  so the agent's self-planning persists across rounds. Optional —
-     *  no next_action means the compiler generates the next task as before. */
-    next_action?: string;
-    /** v2.2: Sub-tasks the agent completed this round. Each entry may be a
-     *  sub-goal ID (e.g. "sg-a3f2b1c0" from the Sub-Goal Dashboard) for
-     *  exact matching, or a natural-language description for Jaccard
-     *  similarity fallback. Omit if none. */
-    completed_subtasks?: string[];
-    /** v2.2: Sub-tasks that are now blocked (cannot proceed). Same ID-or-
-     *  description matching as completed_subtasks. Omit if none. */
-    blocked_subtasks?: string[];
-    /** v2.2: Sub-tasks the agent is canceling (no longer needed). Same ID-or-
-     *  description matching as completed_subtasks. Omit if none. */
-    canceled_subtasks?: string[];
     /** v2.5: Why the agent is stopping. Only meaningful when
      *  should_continue=false and success=false. Defaults to "gave_up"
      *  (current behavior) when absent. "blocked" means work cannot proceed
      *  under current constraints; "needs_human_input" requires intervention. */
     stop_reason?: "gave_up" | "blocked" | "needs_human_input";
-    /** v2.12: Declared tri-state outcome. When absent, derived from success
+    /** v2.12: Declared outcome (four values). When absent, derived from success
      *  (true → "success", false → "failed"). "partial" and "blocked" can only
      *  be declared explicitly. A declared non-success outcome suppresses the
      *  success-class verification checks even when success=true. */
@@ -187,13 +122,14 @@ export interface SelfEvaluation {
      *  Downgrades the success_without_verified_evidence check from error to
      *  info. Flat string, ≤ 200 chars. */
     no_change_reason?: string;
-    /** v2.8: When the previous round's verification flagged intent_drift or
-     *  subgoal_drift, the agent explains why its actions diverged from its
-     *  stated plan. Populated from the self-eval block when the prompt
-     *  injected the field. Empty or absent when no drift was flagged.
-     *  Used by the enforcement gate R7 to distinguish intentional pivots
-     *  from unacknowledged drift. */
-    drift_clarification?: string;
+    /** v3.7.1: gate_opened ids this round's work depended on (returned by
+     *  loopforge_gate_check). Lenient format — non-string entries are
+     *  ignored, ≤ 20 entries. Enforced ONLY when policy.gate.enabled: a
+     *  cited gate that does not exist, is not a user gate, or has no
+     *  approved gate_decision produces the user_gate_unresolved error and
+     *  the round is rejected. Safe pre-work (investigation, dry-runs,
+     *  rollback evidence) never needs a gate. */
+    gate_ids?: string[];
     /** Model's information needs for the next round's prompt.
      *  Consumed by the Compiler — not durable across rounds. */
     prompt_requests?: PromptRequests;
@@ -202,7 +138,7 @@ export interface SelfEvaluation {
      *  it completes or blocks). Becomes the ACTIVE contract only once this
      *  round commits; it is then derived at compile time from committed
      *  rounds — see round-contract.ts. Optional. */
-    round_contract?: RoundContract;
+    round_contract?: RoundContractProposal;
 }
 /** v2.12: Tri-state round outcome. Declared via SelfEvaluation.outcome;
  *  derived from `success` when absent. Shared by the dual gates, the stop
@@ -218,13 +154,15 @@ export interface LoopProjection {
         what: string;
         since_round: number;
     } | null;
-    /** Suggested next steps: agent-declared intent vs compiler-derived
-     *  pending/blocked sub-goals. Non-authoritative. */
+    /** Suggested next steps, derived from the active contract, sub-goals, and
+     *  open gates/recovery requirements. Non-authoritative. v3.8: the
+     *  `agent_intent` source was deleted with `next_action` — the agent's own
+     *  plan is no longer a projection input. */
     todo: Array<{
         id: string;
         item: string;
         reason: string;
-        source: "derived" | "agent_intent";
+        source: "derived";
         priority: number;
     }>;
     /** Phase boundaries from milestone history. */
@@ -254,6 +192,12 @@ export interface LoopProjection {
         verified: string[];
         open_risks: string[];
     };
+    /** v3.8: Sub-goals a machine-verified contract item backs. The machine's
+     *  separate statement about a `done` sub-goal — it never rewrites
+     *  `SubGoal.status`. Derived in cognitive-facts.ts, exposed here so the
+     *  projection carries the same verification view the prompt and state file
+     *  do. */
+    verified_subgoals: VerifiedSubGoalFact[];
 }
 export declare function makeLoopProjection(overrides?: Partial<LoopProjection>): LoopProjection;
 /** v2.12: Structured high-risk action descriptor (internal — audit display
@@ -294,11 +238,11 @@ export declare function makeGateDecision(overrides?: Partial<GateDecision>): Gat
  *  Compiler when assembling the next prompt. Transient — each round's
  *  requests apply to that round only. */
 export interface PromptRequests {
-    /** Items to emphasize. Matched against active state via Jaccard
-     *  similarity. Matching items are pulled into a "Critical Context"
-     *  section rendered before optional sections. No content is added —
-     *  only reordered. Max entries: policy-driven (L2: 5, L1: 3).
-     *  L0: ignored. */
+    /** Items to emphasize. Matched against active state by stable id or
+     *  normalized-exact text (v3.8.1 — the Jaccard arm is gone). Matching items
+     *  are pulled into a "Critical Context" section rendered before optional
+     *  sections. No content is added — only reordered. An unmatched entry is
+     *  dropped. Max entries: policy-driven (L2: 5, L1: 3). L0: ignored. */
     emphasize?: string[];
     /** Things the model is confused about. Rendered at the prompt top
      *  as "Confusion Alerts" before the Objective section. Compiler
@@ -310,7 +254,7 @@ export interface PromptRequests {
  *  rolling-window eviction. Triggered by three signals in priority order:
  *
  *  1. agent_declared    — compression_checkpoint === true (agent marks phase complete)
- *  2. criteria_milestone — new success_criteria_met detected (semantic dedup)
+ *  2. criteria_milestone — a new met criterion_claim detected (semantic dedup)
  *  3. auto              — safety net after N rounds without a milestone
  *
  *  Built from raw round data in vault entries — no new persistent storage.
@@ -340,16 +284,18 @@ export interface MilestoneSummary {
     generated_at_round: number;
 }
 export declare function makeMilestoneSummary(overrides?: Partial<MilestoneSummary>): MilestoneSummary;
-/** A single sub-agent / Worker delegation result (v1.9 — multi-agent). */
+/** A single sub-agent / Worker delegation result (v1.9 — multi-agent).
+ *  v3.7.1: `outcome` is the single reported fact. `success` is deleted —
+ *  entries without a valid outcome are dropped by the parser, never
+ *  derived. The whole array is optional and informational: it buys no
+ *  machine verdict and an absent/empty array (no delegation this round)
+ *  is always accepted. */
 export interface WorkerResult {
     agentId: string;
-    subAgentType: string;
+    subAgentType?: string;
     subTask: string;
     resultSummary: string;
-    success: boolean;
-    /** v2.12: Declared worker outcome. When absent, derived from success
-     *  (true → "success", false → "failed"). "partial" is explicit only. */
-    outcome?: "success" | "partial" | "failed";
+    outcome: "success" | "partial" | "failed";
     discoveredConstraints?: string[];
 }
 export declare function makeSelfEvaluation(overrides?: Partial<SelfEvaluation>): SelfEvaluation;
@@ -376,17 +322,23 @@ export interface LoopObjective {
     refinement_history?: string[];
 }
 /** v3.2: Derived per-criterion status for the progress dashboard — the
- *  "goal → criteria → evidence" vertical view. Zero persistence: derived from
- *  vault entries each round (met/remaining reports + Jaccard sub-goal links). */
+ *  "goal → criteria → evidence" vertical view. Zero persistence: derived
+ *  from committed rounds each round.
+ *
+ *  v3.8 states: `claimed` (the agent claims it met), `remaining` (declared
+ *  outstanding), `verified` (a verified contract item references it),
+ *  `contradicted` / `insufficient` (machine evidence denies / cannot back
+ *  the claim), `unknown` (never mentioned). */
 export interface CriterionStatus {
     /** Stable ID derived from the criterion text (cr-XXXXXXXX). */
     id: string;
     /** The criterion text as declared in the objective. */
     text: string;
-    status: "met" | "remaining" | "unknown";
+    status: "unknown" | "claimed" | "remaining" | "insufficient" | "contradicted" | "verified";
     /** Round when the criterion was first reported met (machine-backed). */
     met_at_round?: number;
-    /** Sub-goals whose description matches this criterion (Jaccard). */
+    /** Sub-goals an item referencing this criterion also names, via explicit
+     *  `subgoal_refs` (v3.8.1 — never a text-similarity guess). */
     related_subgoal_ids: string[];
 }
 /** v3.2: A deterministic "lesson learned" — a constraint or verification
@@ -394,30 +346,32 @@ export interface CriterionStatus {
  *  immunize the agent against repeating the same mistakes. Zero persistence:
  *  derived from vault entries each round; presentation only — never feeds
  *  the enforcement gate's decisions. */
-export interface Lesson {
-    /** Constraint text or verification check name. */
-    text: string;
+/** v3.8.1: a repeated machine fact, keyed by what it is ABOUT.
+ *
+ *  One derivation over the whole committed history replaces the three
+ *  separate views of "what keeps going wrong" this release removed:
+ *  `Lesson` (whole history, count >= 2), `rolling_summary.recurring_issues`
+ *  (the last 5 rounds' raw violation texts, no threshold at all despite the
+ *  name), and the L1/L2 prompt sections built on top of each. Callers FILTER
+ *  this list — the state file renders the genuinely recurring set, the prompt
+ *  renders the recent tail. */
+export interface RecurringFlag {
+    /** Constraint text (for a violation) or the verification check id. */
+    subject: string;
     kind: "constraint_violation" | "verification_error" | "verification_warning";
-    /** How many rounds this lesson occurred in. */
+    /** `VerificationFlag.ref` — the command id, `rci-`/`sg-`/`cr-` id or path
+     *  the flag was about. Empty when the check recorded no subject. */
+    ref: string;
+    /** Occurrences across the whole committed history. */
     count: number;
-    /** The rounds it occurred in, ascending. */
+    /** The distinct rounds it occurred in, ascending. */
     rounds: number[];
 }
 export declare function makeLoopObjective(overrides?: Partial<LoopObjective>): LoopObjective;
-export interface LoopHealth {
-    goal_alignment: number;
-    constraint_integrity: number;
-    drift_detected: boolean;
-    strategy_stability: boolean;
-    task_continuity: number;
-    escalation_recommended: string;
-}
-export declare function makeLoopHealth(overrides?: Partial<LoopHealth>): LoopHealth;
 export interface RollingSummary {
     /** v1.12: Unified key outcomes — merged from what_worked + key_lessons.
      *  Format: "[R{round}] ✓/✗ ({technique}): {summary}" */
     key_outcomes: string[];
-    recurring_issues: string[];
     rounds_sampled: number;
     generated_at_round: number;
     /** v1.7: Detected failure patterns — repeated failed rounds with
@@ -431,14 +385,28 @@ export interface RollingSummary {
     milestones?: MilestoneSummary[];
 }
 export declare function makeRollingSummary(overrides?: Partial<RollingSummary>): RollingSummary;
+/** v3.7.1: One explicit sub-goal status transition. The closed migration
+ *  matrix (loop-compiler.ts, single source) governs legality:
+ *  in_progress from pending|blocked; done from pending|in_progress|blocked;
+ *  blocked|canceled from pending|in_progress; blocked → canceled. done and
+ *  canceled are terminal — re-opening requires a NEW emerged_subtasks item. */
+export interface SubGoalUpdate {
+    /** The sub-goal to transition (sg-XXXXXXXX). Unknown IDs are invalid. */
+    id: string;
+    status: "in_progress" | "done" | "blocked" | "canceled";
+    /** Optional free-text note (≤ 300 chars). Lenient — never validated. */
+    note?: string;
+}
 /** v2.2: A structured sub-goal tracked by the compiler across rounds.
- *  Declared by the agent via emerged_subtasks (string[]), managed by
- *  the compiler with derived status. Never creates sub-loops — the
- *  agent still owns execution; the compiler only tracks state. */
+ *  Declared by the agent via emerged_subtasks (creation) and
+ *  subgoal_updates (explicit transitions); statuses are compiler-derived
+ *  from committed round facts. Never creates sub-loops — the agent still
+ *  owns execution; the compiler only tracks state. */
 export interface SubGoal {
     /** Stable identifier derived from description hash (sg-XXXXXXXX). */
     id: string;
-    /** Agent-declared description, deduplicated by similarity. */
+    /** Agent-declared description. Exact repeats within one declaration round
+     *  keep only the first entry (v3.8.1 — no similarity dedup). */
     description: string;
     /** Compiler-derived status. */
     status: "pending" | "in_progress" | "done" | "blocked" | "canceled";
@@ -450,6 +418,9 @@ export interface SubGoal {
     completed_at_round?: number;
     /** Priority hint: 0 = highest. Derived from declaration order. */
     priority: number;
+    /** v3.8: The agent's note from the transition that set the current status.
+     *  Lenient — it never affects validation, only what the agent reads back. */
+    status_note?: string;
 }
 export declare function makeSubGoal(overrides?: Partial<SubGoal>): SubGoal;
 /** v2.3: Per-constraint lifecycle metadata for the active constraint set.
@@ -458,8 +429,9 @@ export declare function makeSubGoal(overrides?: Partial<SubGoal>): SubGoal;
  *  was removed — active constraints never auto-demote. */
 export interface ConstraintMeta {
     /** v2.11: Stable identifier derived from text hash (c-XXXXXXXX).
-     *  Enables exact ID-first matching by the agent and compiler.
-     *  Eliminates Jaccard false positives/negatives. */
+     *  The only name an agent can use to refer to this constraint — v3.8.1
+     *  deleted every similarity fallback, so stable ids and normalized-exact
+     *  text are the whole matching surface. */
     id: string;
     /** Normalized constraint text (the key). */
     text: string;
@@ -470,13 +442,6 @@ export interface ConstraintMeta {
     source: "hard" | "plan" | "criteria" | "discovered";
 }
 export declare function makeConstraintMeta(overrides?: Partial<ConstraintMeta>): ConstraintMeta;
-export interface TaskAlignment {
-    is_aligned: boolean;
-    alignment_score: number;
-    warning: string;
-    escalation: string;
-}
-export declare function makeTaskAlignment(overrides?: Partial<TaskAlignment>): TaskAlignment;
 export interface LoopRoundResult {
     round: number;
     success: boolean;
@@ -489,8 +454,11 @@ export interface LoopRoundResult {
     objective_refinement?: string;
     /** P2: Sub-problems that emerged during this round. */
     emerged_subtasks?: string[];
+    /** v3.7.1: Explicit sub-goal transitions declared this round.
+     *  Set from SelfEvaluation.subgoal_updates during buildLoopRequest. */
+    subgoal_updates?: SubGoalUpdate[];
     /** P4: Execution evidence from this round. */
-    execution_evidence?: ExecutionEvidence;
+    execution_report?: ExecutionReport;
     /** P5: Constraints retracted this round. */
     retracted_constraints?: string[];
     /** P5: Success criteria revised this round. */
@@ -504,21 +472,10 @@ export interface LoopRoundResult {
     compression_checkpoint?: boolean;
     /** v1.10: Human-readable label for the checkpoint. */
     checkpoint_label?: string;
-    /** v1.16: Agent's declared next action for the following round. */
-    next_action?: string;
-    /** v2.2: Sub-tasks completed this round. */
-    completed_subtasks?: string[];
-    /** v2.2: Sub-tasks blocked this round. */
-    blocked_subtasks?: string[];
-    /** v2.2: Sub-tasks canceled this round. */
-    canceled_subtasks?: string[];
-    /** v2.8: Agent's explanation for intent/subgoal drift detected in
-     *  the previous round. Carried forward from SelfEvaluation. */
-    drift_clarification?: string;
     /** Model's information needs for the next round's prompt.
      *  Carried forward from SelfEvaluation. Consumed by the Compiler. */
     prompt_requests?: PromptRequests;
-    /** v2.12: Declared tri-state outcome. Carried forward from SelfEvaluation. */
+    /** v2.12: Declared outcome. Carried forward from SelfEvaluation. */
     outcome?: RoundOutcome;
     /** v2.12: Flat blocker description (outcome==="blocked" only). */
     blocker?: string;
@@ -546,7 +503,6 @@ export interface LoopCompileRequest {
     new_since_last_round: string;
     last_round_result: LoopRoundResult | null;
     force_level: string;
-    health_check_interval: number;
     /** Optional context supplied explicitly by the embedding Agent. */
     external_context?: string;
     /** Maximum rounds for this loop. Used by the state file header to show
@@ -566,18 +522,40 @@ export interface LoopCompileRequest {
 }
 export declare function makeLoopCompileRequest(overrides?: Partial<LoopCompileRequest>): LoopCompileRequest;
 /** Immutable record of the exact prompt delivered for one round attempt. */
+/** v3.8.1: the artifact schema version, next to the type it versions. The
+ *  transaction envelope parser reads it, so the constant lives here rather
+ *  than in the renderer. */
+export declare const PROMPT_ARTIFACT_SCHEMA_VERSION: 2;
 export interface PromptArtifact {
-    schemaVersion: 1;
+    /** v3.8.1: schema 2. Version 1 is a HARD break — a round whose artifact
+     *  does not parse is not committed history, and `legacyTransactionRounds`
+     *  reports the loss rather than letting it vanish. */
+    schemaVersion: typeof PROMPT_ARTIFACT_SCHEMA_VERSION;
+    /** Round identity: `loop:<loopId>:round:<n>`. */
     roundId: string;
+    /** The round number on its own, so a reader does not re-parse roundId. */
+    round: number;
     attempt: number;
     level: "l0" | "l1" | "l2";
     renderedPrompt: string;
     promptHash: string;
     stateHash: string;
-    /** v3.2: What the rendered prompt actually presented (L1 only). Persisted
-     *  on the lineage entry as the diff baseline for L1 collapse. Absent for
-     *  L0/L2 compiles. */
-    presentedState?: PresentedStateSnapshot;
+    /** Section ids actually rendered, in render order. */
+    sections: string[];
+    /** Section ids the deterministic budget rule dropped. */
+    droppedSections: string[];
+    /** True when the PROTECTED sections alone exceeded the budget. Recorded so
+     *  an over-budget prompt is visible rather than silently over-long. */
+    protectedOverflow: boolean;
+    /** The ceiling this render was measured against: the level's configured
+     *  budget (`lN_max_chars`) minus the fixed footer, which is appended after
+     *  budgeting because it is never dropped. Measured over the SAME region as
+     *  `renderedChars`. */
+    budget: number;
+    /** Characters the budgeted region produced: the fixed header, the confusion
+     *  alerts and the rendered sections — everything except the footer. NOT the
+     *  full prompt length; `renderedPrompt` adds the footer on top. */
+    renderedChars: number;
 }
 export interface LoopCompileResponse {
     status: AgentStatus;
@@ -592,8 +570,6 @@ export interface LoopCompileResponse {
     goal_id: string;
     goal_text_hash: string;
     loop_objective: LoopObjective | null;
-    loop_health: LoopHealth | null;
-    task_alignment: TaskAlignment | null;
     rolling_summary: RollingSummary | null;
     /** v2.2: Structured sub-goals tracked across rounds. Compiler-managed
      *  lifecycle with derived status. Rendered as Sub-Goal Dashboard. */
@@ -602,17 +578,16 @@ export interface LoopCompileResponse {
     constraint_metadata?: ConstraintMeta[];
     /** v2.5: Current round's agent trust score [0, 1]. Derived from verification
      *  flags: -0.15 per error, -0.03 per warn. Always 1.0 for round 1. */
-    agent_trust_score?: number;
     /** v2.5: Trust scores from the last 10 rounds, newest last. Empty for
      *  round 1. Reconstructed from vault entries — zero new persistence. */
-    agent_trust_trend?: number[];
     /** v3.2: Derived per-criterion status (goal → criteria → evidence view).
      *  Zero persistence — re-derived from vault entries each round. */
     criterion_statuses?: CriterionStatus[];
-    /** v3.2: Deterministic lessons learned (repeated violations / repeated
-     *  verification failures). Presentation only — never feeds enforcement. */
-    lessons?: Lesson[];
-    suggested_next_task: string;
+    /** v3.8.1: repeated machine facts over the whole committed history, keyed
+     *  by check id / constraint text and the id they were about. Presentation
+     *  only — never feeds enforcement. Replaces the former Lessons list; callers
+     *  filter it (state file: count >= 2, prompt: recent tail). */
+    recurring_flags?: RecurringFlag[];
     plan_source: string | null;
     warnings: string[];
     error: string;
@@ -657,7 +632,6 @@ export interface LoopForgeResponse {
     rolling_summary?: RollingSummary | null;
     sub_goals?: SubGoal[];
     criterion_statuses?: CriterionStatus[];
-    suggested_next_task?: string;
 }
 export interface SessionState {
     task_id: string;
@@ -675,7 +649,11 @@ export interface AgentLoopResult {
  *  `cancelled` is manual stop via loopforge_stop. */
 export type StopReason = "completed" | "failed" | "blocked" | "cancelled" | "max_rounds" | "stalled" | "enforcement_terminated"
 /** Loop was paused by user or signal. */
- | "paused";
+ | "paused"
+/** v3.8: The agent stopped, but machine verification did not close the
+ *  active contract (or the observations are insufficient to prove the task
+ *  complete). Never reported as `completed`. */
+ | "incomplete";
 /** Result of round-boundary enforcement. Decides whether to accept the round,
  *  reject it (force the agent to redo the SAME round), or terminate the loop.
  *
@@ -696,10 +674,10 @@ export interface EnforcementResult {
      *  Used by callers to track consecutive rejections per-rule
      *  so unrelated rejections don't accumulate toward the max. */
     check?: string;
-    /** v2.12: True when the enforcement gate accepted the round via
-     *  drift_clarification waiver (R7). The caller uses this to track
-     *  clarification streaks independently of rejection streaks. */
-    clarification_accepted?: boolean;
+    /** v3.8: The stop reason a `terminate` decision must map to. Absent means
+     *  the historical `enforcement_terminated`; `incomplete` is set by the
+     *  verification-debt row. */
+    stopReason?: StopReason;
 }
 export declare function makeEnforcementResult(overrides?: Partial<EnforcementResult>): EnforcementResult;
 /** Context supplied to an embedding-owned provider before compilation. */
@@ -734,6 +712,12 @@ export interface VerificationFlag {
     check: string;
     /** Human-readable description of the inconsistency found. */
     detail: string;
+    /** v3.8.1: the id this flag is ABOUT — a configured command id, an
+     *  `rci-` / `sg-` / `cr-` id, or a workspace path. Optional: only checks with
+     *  a concrete subject set it. Recurring-warning grouping keys on
+     *  `(check, ref)` so it reports WHICH item keeps failing rather than
+     *  re-parsing `detail` prose. */
+    ref?: string;
 }
 export declare function makeVerificationFlag(overrides?: Partial<VerificationFlag>): VerificationFlag;
 /** Result of cross-round self-evaluation verification.
@@ -748,7 +732,266 @@ export declare function makeVerificationFlag(overrides?: Partial<VerificationFla
 export interface VerificationResult {
     verdict: "trusted" | "suspect" | "contradicted";
     flags: VerificationFlag[];
+    /** v3.8.1: the round's success claim is MACHINE-backed — a passed
+     *  after-phase command observed by the runtime (`deriveEvidenceStatus`).
+     *  Carried as a fact so a consumer never re-derives it; the progress
+     *  evaluator reads it as "this round is finishing, not churning". */
+    machineBackedSuccess: boolean;
 }
 export declare function makeVerificationResult(overrides?: Partial<VerificationResult>): VerificationResult;
+/** v3.8: The agent's self-report for a round — renamed from ExecutionReport
+ *  because these fields are claims, not evidence. The whole object is
+ *  optional; a mistyped optional field is dropped with a warning and never
+ *  rejects the round. */
+export interface ExecutionReport {
+    /** Files the agent says it changed. Informational — compared against the
+     *  git observation, never trusted as the observation. */
+    files_changed?: string[];
+    /** Test counts the agent reports. Informational. */
+    tests_reported?: {
+        passed: number;
+        failed: number;
+        skipped: number;
+    } | null;
+    /** Advisory claims about objective criteria. LENIENT: unknown/duplicate
+     *  criterion ids and malformed outcomes are dropped with a warning. */
+    criterion_claims?: CriterionClaim[];
+    /** Claims about ACTIVE contract items. STRICT: an unknown/duplicate item id
+     *  or an illegal outcome is a structural defect (contract_invalid). */
+    contract_item_claims?: ContractItemClaim[];
+    /** The agent's own progress estimate (0.0–1.0). Informational. */
+    progress_estimate?: number;
+}
+export declare function makeExecutionReport(overrides?: Partial<ExecutionReport>): ExecutionReport;
+/** v3.8: An advisory claim about an objective criterion. Lenient by design —
+ *  the criterion layer is advisory; the contract item layer is the machine
+ *  verification skeleton. */
+export interface CriterionClaim {
+    /** cr-XXXXXXXX (or the criterion text for plain-text matching). */
+    criterion_id: string;
+    outcome: "met" | "remaining";
+}
+/** v3.8: A claim about an ACTIVE contract item, cited by the derived
+ *  rci-XXXXXXXX id the prompt rendered. */
+export interface ContractItemClaim {
+    item_id: string;
+    outcome: "met" | "remaining";
+}
+/** v3.8: One declared contract item. `verify_with` must name configured,
+ *  enabled, after-capable evidence commands — the declaration is strict.
+ *
+ *  `subgoal_refs` lives HERE, not on the contract: a machine-verified item
+ *  backs exactly the sub-goals it names, so "item A verifies SubGoal 1, item B
+ *  verifies SubGoal 2" is expressible and `VerifiedSubGoalFact` attribution is
+ *  per-item instead of "every verified item backs every sub-goal". */
+export interface ContractItemProposal {
+    description: string;
+    /** cr-XXXXXXXX criterion ids this item is evidence for (or free text). */
+    criterion_refs: string[];
+    /** sg-XXXXXXXX sub-goals this item is evidence for. */
+    subgoal_refs: string[];
+    /** Evidence command ids (policy.evidence.commands[].name). */
+    verify_with: string[];
+}
+/** v3.8: A Round Contract proposal for the NEXT round. It becomes ACTIVE only
+ *  after the declaring round commits. Identity (rc-/rci-) is derived from
+ *  CONTENT ONLY — restating an unchanged contract keeps the same identity,
+ *  unlike a SubGoal whose id includes its declaration round. */
+export interface RoundContractProposal {
+    work_item?: string;
+    /** Files/directories the round may touch. Empty = no scope constraint. */
+    scope: string[];
+    items: ContractItemProposal[];
+}
+/** v3.8: The machine's record of what a contract bound at its declaration
+ *  round. Stamped by the runtime when the declaring round COMMITS (policy is
+ *  not part of the Vault, so the command configuration in force at
+ *  declaration could not otherwise be recovered). It is machine-recomputed,
+ *  never agent-supplied, and adds no second truth. */
+export interface ContractBinding {
+    rc_id: string;
+    item_ids: string[];
+    config_hash_by_command: Record<string, string>;
+}
+/** v3.8: Runtime-derived contract item status. The agent may only claim
+ *  `met` / `remaining`; the other three are machine-derived. */
+export type ContractItemStatus = "pending" | "insufficient" | "contradicted" | "verified";
+/** v3.8: The round-level verification posture. `trusted` means every claim in
+ *  the round is machine-backed; `insufficient` means claims are unbacked but
+ *  not contradicted; `contradicted` means machine facts deny a claim. */
+export type RoundVerificationStatus = "trusted" | "insufficient" | "contradicted";
+/** v3.8: Machine observation status. A configured provider always produces an
+ *  observation — the failure modes are recorded, not filtered away.
+ *
+ *  Who reports what: `timeout` and `unavailable` are the runtime's own words
+ *  for "the provider exceeded its deadline" and "the provider yielded
+ *  nothing" (the collector synthesizes both, so a provider cannot hide a
+ *  failure by returning nothing). `aborted` is what a PROVIDER reports when
+ *  its own capture was aborted — a command killed mid-flight, say. A
+ *  collector deadline aborts the capture AS a timeout, so the round records
+ *  the runtime's measured cause, not the provider's. */
+export type ObservationStatus = "observed" | "passed" | "failed" | "timeout" | "unavailable" | "error" | "aborted";
+/** v3.8: Common machine-observation fields. Observations are the factual
+ *  record of what the machine saw; they are persisted with the round and are
+ *  the only input that can create a `verified` fact. */
+export interface MachineObservationBase {
+    schemaVersion: 1;
+    providerId: string;
+    kind: "git" | "command" | "custom";
+    phase: "before" | "after";
+    startedAt: number;
+    finishedAt: number;
+    status: ObservationStatus;
+    /** Files this observation reports (git: changed paths; command: resolved
+     *  entrypoint files). */
+    files: string[];
+}
+export interface GitObservationData {
+    tracked: string[];
+    staged: string[];
+    untracked: string[];
+    /** path -> "<mode>:<sha256>" (or the literal "missing"). */
+    fingerprints: Record<string, string>;
+    head?: string;
+}
+export interface GitObservation extends MachineObservationBase {
+    kind: "git";
+    data: GitObservationData;
+}
+export interface CommandObservationData {
+    commandId: string;
+    argv: string[];
+    cwd: string;
+    /** sha256 of the normalized command configuration at capture time. */
+    configHash: string;
+    required: boolean;
+    exitCode: number | null;
+    signal: string | null;
+    durationMs: number;
+    /** Why a non-passed observation did not pass (e.g. "ENOENT", "cwd leaves
+     *  the workspace"). Free text for the audit trail — never a verdict. */
+    failureDetail?: string;
+    /** sha256 over the FULL stdout stream — never the truncated excerpt. */
+    stdoutSha256: string;
+    /** sha256 over the FULL stderr stream. */
+    stderrSha256: string;
+    stdoutExcerpt: string;
+    stderrExcerpt: string;
+    truncated: boolean;
+    entrypointFiles: string[];
+}
+export interface CommandObservation extends MachineObservationBase {
+    kind: "command";
+    data: CommandObservationData;
+}
+export interface CustomObservation extends MachineObservationBase {
+    kind: "custom";
+    data: Record<string, unknown>;
+}
+export type MachineObservation = GitObservation | CommandObservation | CustomObservation;
+/** v3.8: Static, policy-derived verification capability. A pure function of
+ *  policy — no probing, no filesystem, no provider registry — so it can be
+ *  hashed into stateHash and reproduced by replay/audit from committed facts.
+ *  Provider REGISTRATION is code state and is deliberately excluded; it is
+ *  reported as an unhashed readiness diagnostic instead. */
+export interface ConfiguredCapability {
+    schemaVersion: 1;
+    providers: Array<{
+        providerId: string;
+    }>;
+    commands: Array<{
+        commandId: string;
+        enabled: boolean;
+        phase: "after" | "both";
+        required: boolean;
+        configHash: string;
+    }>;
+    /** policy.evidence.providers is non-empty. */
+    observationConfigured: boolean;
+    /** At least one enabled, after-capable command. */
+    contractVerificationAvailable: boolean;
+}
+/** v3.8: Live observation capability. Rendered only — never hashed, never
+ *  persisted independently of the observations it is derived from. */
+export interface ObservedCapability {
+    providers: Array<{
+        providerId: string;
+        status: ObservationStatus;
+    }>;
+    commands: Array<{
+        commandId: string;
+        status: ObservationStatus;
+        configHash: string;
+    }>;
+}
+/** v3.8: The single capability fact a prepared round returns — the union of
+ *  the two halves, split so that only the POLICY half is hashable.
+ *
+ *  `ConfiguredCapability` is a pure function of policy and feeds
+ *  `stateHash`/`promptHash`; `ObservedCapability` carries live statuses and is
+ *  rendered only. `provider.available` is provider-REGISTRY state (code, not
+ *  policy) and therefore never enters the hash either — it is reported here and
+ *  by `doctor`. Every surface that speaks about capability (MCP start / next /
+ *  status, the warning list) calls this one function, so they cannot drift
+ *  apart — and none of them carries a second copy of the fact. */
+export interface EvidenceCapability {
+    schemaVersion: 1;
+    providers: Array<{
+        providerId: string;
+        /** A factory for this name is registered in this runtime. */
+        available: boolean;
+        status: ObservationStatus;
+    }>;
+    commands: Array<{
+        commandId: string;
+        enabled: boolean;
+        phase: "after" | "both";
+        configHash: string;
+        /** Enabled and after-capable — i.e. usable as a contract item's evidence. */
+        ready: boolean;
+    }>;
+    contractVerificationAvailable: boolean;
+    /** Human-readable capability gaps (the same text start/resume/status show). */
+    warnings: string[];
+}
+/** v3.8: A machine-verified sub-goal fact. DERIVED in cognitive-facts.ts,
+ *  never persisted: it exists only while a committed contract item references
+ *  the sub-goal AND that item is verified. It never writes SubGoal.status —
+ *  `done` stays the agent's declaration. */
+export interface VerifiedSubGoalFact {
+    subgoal_id: string;
+    contract_item_ids: string[];
+    verified_at_round: number;
+}
+/** v3.8: The STABLE error codes every tool answers with. A client can branch
+ *  on these; the human sentence rides in `ToolError.message` and never doubles
+ *  as the code.
+ *
+ *  - `evaluation_invalid` / `contract_invalid` / `policy_invalid` — a payload
+ *    or configuration defect; the same roundId may be retried.
+ *  - `round_id_required` / `round_id_mismatch` — the anchor is missing or no
+ *    longer names the current round.
+ *  - `session_not_found` / `state_unavailable` — the named session or read
+ *    model is not there.
+ *  - `invalid_argument` — the request itself is malformed at the tool boundary.
+ *  - `gate_disabled` / `loop_already_running` — a state condition, not a defect.
+ *
+ *  Note: a `loopforge_next` submission whose roundId no longer matches is NOT
+ *  `round_id_mismatch` — it returns the held prompt with a warning and
+ *  `ok: true` so the agent can recover the response it missed. That recovery
+ *  contract (v3.0.1) is deliberate; `round_id_mismatch` is for the places with
+ *  no held prompt to return (the gate preflight). */
+export type ToolErrorCode = "evaluation_invalid" | "contract_invalid" | "policy_invalid" | "session_not_found" | "round_id_required" | "round_id_mismatch" | "state_unavailable" | "invalid_argument" | "gate_disabled" | "loop_already_running";
+/** v3.8: The structured error inside the uniform `{ok: false}` envelope. */
+export interface ToolError {
+    code: ToolErrorCode;
+    /** Human-readable cause. Never the code. */
+    message: string;
+    /** Whether the fix is a corrected payload the agent may resend. */
+    retryable: boolean;
+    sessionId?: string;
+    roundId?: string;
+    details?: Record<string, unknown>;
+}
 export declare function makeTaskId(taskDescription: string): string;
 //# sourceMappingURL=protocol.d.ts.map