Turn Lifecycle & Coordinator
Relevant source files
The following files were used as context for generating this wiki page:
The Turn Lifecycle & Coordinator represents the central orchestration engine of the Noesis system. Its primary purpose is to manage individual interaction "turns" between a user and an agent, ensuring that every action is grounded in evidence, governed by a frozen intelligence plan, and contributes to the system's long-term autonomous compounding loop. The coordinator bridges the gap between foreground execution (useful work) and ambient background learning (reflection and capability revision).
At a high level, the turn lifecycle guarantees that Noesis becomes more effective through use without requiring manual user intervention in the learning pipeline. It manages the transition from a user message to a settled response, followed by an asynchronous feedback loop that attributes outcomes to specific experiments and capability revisions.
Sources: plans/noesis-autonomous-compounding-implementation-plan.html, plans/compounding-partnership-product-loop.html
Architecture and Components
The coordinator operates within the packages/runtime module and acts as the composition root for turn-based intelligence. It relies on WorkspaceStore for authoritative persistence and the Pi AgentHarness for model execution.
Key Structural Entities
| Entity | Description | Authority |
|---|---|---|
TurnIntelligencePlan | A frozen snapshot of all definitions (prompts, tools, capabilities) used for a specific turn. | SQLite |
ActivationSnapshot | A record of exactly which capability revisions were active at the time of the turn. | SQLite |
TurnSettlement | The finalized state of a turn, categorizing it as accepted, corrected, failed, or aborted. | SQLite |
Coordinator | Orchestrates opportunistic reflection, evaluation, and background work budgets. | Process Memory / SQLite |
Sources: plans/noesis-autonomous-compounding-implementation-plan.html:437-470, plans/noesis-high-leverage-correction-plan.html:623-644
Turn Lifecycle Flow
The lifecycle follows a strict sequence to ensure causality and data integrity. Before any model execution occurs, the system "freezes" the environment to prevent mid-turn state drift.
The turn must freeze one activation ID, posture decision, selected definition revisions, retrieval citations, and permission snapshots before execution.
Sources: plans/compounding-partnership-product-loop.html:450-464, plans/noesis-high-leverage-correction-plan.html:360-385
The Frozen Intelligence Plan
A critical architectural invariant is the use of a FrozenTurnPlan. This ensures that the plan inspected after a turn is identical to the one that served it.
Plan Composition
The plan includes:
- Capability Subset: Exactly which tools and skills are enabled for this turn.
- Immutable Revisions: Byte-stable snapshots of prompt layers, tool source, and routing rules.
- Retrieval Citations: Specific evidence fragments used to ground the model response.
- Permission Snapshot: A point-in-time record of what the agent was authorized to do.
Sources: plans/noesis-high-leverage-correction-plan.html:367-377, AGENTS.md:38-41
Prompt Ownership Layers
The coordinator assembles the prompt using a layered approach:
- Protected Kernel: Core authority and dangerous-effect rules.
- User Constitution: Explicit instructions provided by the user.
- Learned Profile: Style and reasoning modules learned automatically.
- Capability Layer: Modules tied to active capability revisions.
- Retrieved Context: Bounded history fragments with exact citations.
Sources: plans/noesis-autonomous-compounding-implementation-plan.html:565-573
Settlement and Outcome Attribution
Turn settlement occurs in packages/runtime/src/turn-settlement.ts. It categorizes the result of an interaction to guide the background coordinator.
Settlement Categories
- Accepted: The work was successful and requires no immediate adjustment.
- Corrected: The user steered the agent, providing high-leverage evidence for learning.
- Failed: A technical or behavioral failure that may trigger a
revertoutcome in an open experiment. - Aborted: The turn was terminated before completion; excluded from learning by default.
Sources: plans/noesis-high-leverage-correction-plan.html:623-644, plans/compounding-partnership-product-loop.html:707-720
The Background Coordinator
The coordinator (managed via packages/runtime/src/coordinator.ts) handles "ambient" work. This includes reflection, candidate authoring, and preflight evaluation.
Durable Orchestration
The coordinator manages a durable queue of work items with the following properties:
- Leases: Prevents multiple processes from executing the same learning task.
- Idempotency: Bindings between operation IDs and principal/effect identities to ensure safe retries.
- Fail-Closed Execution: Ambiguous reservations that lack an outcome are treated as failures rather than being automatically retried.
Sources: plans/noesis-autonomous-compounding-implementation-plan.html:774-789, plans/compounding-partnership-product-loop.html:478-485
Compounding Loop Monitoring
The coordinator continuously monitors open experiments. Based on real-world feedback attributed to a revision, it executes one of three outcomes:
- Keep: Closes the experiment and leaves the revision active.
- Revise: Authors a successor revision based on new evidence.
- Revert: Restores a prior activation pointer if a hard regression is detected.
Sources: plans/noesis-autonomous-compounding-implementation-plan.html:840-850, plans/compounding-partnership-product-loop.html:926-938
Technical Constraints
- Single Authority: SQLite is the authoritative store for operational state (turns, grants, activations).
- Restart Recovery: Interrupted turns must be rehydrated from SQLite; completions cannot be inferred from absence.
- Pi Isolation: Only
packages/runtime-pihandles the implementation of model roles, ensuring the coordinator remains adapter-neutral. - No Self-Modification: The coordinator ensures that generated content can propose revisions but cannot update activation or permission tables directly.
Sources: AGENTS.md:36-40, plans/noesis-high-leverage-correction-plan.html:692-705, plans/noesis-autonomous-compounding-implementation-plan.html:541-550