@caupulican/pi-adaptative 0.94.1 → 0.96.0

package/docs/resources.md

@@ -49,7 +49,7 @@ A profile may also bind a **model**, **thinking level**, **soul**, and **modelRo
 
 Pi activates the complete situation as one runtime generation: model/router, thinking, soul, extensions, skills, prompts, agents, themes, and tools are reloaded together. A failed reload restores the prior valid generation instead of persisting a partial selection.
 
-Built-in research lanes still use a fixed read-only profile with `read`, `grep`, `find`, and `ls`. Native worker agents use a different contract: orchestration profiles are optional presets, a profile-free root receives the maximum host-permitted classified core surface, and descendants inherit immutable authority while retaining recursive `delegate`, peer-transcript, messaging, memory, write/edit, and platform-shell capabilities when their parent and live service switches permit them. Lane tool globs expand to exact classified names. Opaque extension tools without orchestration metadata are not guessed into a child surface, and an explicit tool request that cannot be materialized is rejected visibly.
+Built-in research lanes still use a fixed read-only profile with `read`, `grep`, `find`, and `ls`. Native worker agents use a different contract: orchestration profiles are optional presets, a profile-free worker inherits the foreground model, thinking level, every compatible classified core tool, and machine-wide scope permitted by the host. Workers are root-managed leaves: they never receive `delegate`, reflection, or memory-mutation authority and cannot spawn descendants. Top-level `model`, `thinkingLevel`, `path`, and `toolNames` overrides can narrow or focus the inherited worker surface. Lane tool globs expand to exact classified names. Opaque extension tools without orchestration metadata are not guessed into a worker surface, and an explicit tool request that cannot be materialized is rejected visibly.
 
 Profiles are stored in settings under `resourceProfiles`, and the active one(s) in `activeResourceProfile`:
 

package/docs/settings.md

@@ -113,7 +113,7 @@ The agent is instructed to edit only that source checkout, preserve unrelated ch
 | `autonomy.mode` | string | `"off"` | Low-config autonomy preset: `"off"`, `"safe"`, `"balanced"`, or `"full"` |
 | `autonomy.maxStallTurns` | number | `20` | Maximum provider rounds in one foreground goal loop before Pi stops continuing |
 
-Use `/settings` → **Autonomy** to choose one preset and the foreground goal-loop round budget, or `/autonomy off|safe|balanced|full` to switch the preset while preserving the configured round budget. `full` is the standing-autonomy mode: it schedules post-turn reflection whenever concurrency allows and grants autonomous authority for high-confidence memory writes, user/project skill creation or patching, small user/project extension/tool improvements, autonomy/Auto Learn setting tuning, and edits under the authorized `selfModification.sourcePath` when validation and rollback evidence are recorded.
+Use `/settings` → **Autonomy** to choose one preset and the foreground goal-loop round budget, or `/autonomy off|safe|balanced|full` to switch the preset while preserving the configured round budget. Main-session reflection is enabled in every mode, including `off`; eligible turns queue a durable root-only cue for the orchestrator's next ordinary current-session provider turn. It does not create a separate or background model request, and increasing autonomy never disables learning. `full` additionally grants standing authority for broader user/project skill, extension/tool, autonomy-setting, and authorized self-modification work when validation and rollback evidence are recorded.
 
 Hard stops still require explicit foreground approval even in `full`: publishing, npm release, git push, tag creation, credential disclosure or provider-auth changes, destructive user-data deletion, network-exposed services, or authority expansion beyond this policy. An active user-plane `secret_store` grant is the narrow exception: model-blind activation and migration from named accessible sources require no duplicate confirmation. `/autonomy status` shows the active grant and the Auto Learn audit/log directory.
 
@@ -135,10 +135,10 @@ Hard stops still require explicit foreground approval even in `full`: publishing
 | `modelRouter.cheapModel` | string | - | Model pattern for read-only, research, explanation, and question turns |
 | `modelRouter.mediumModel` | string | - | Model pattern for scoped implementation/planning turns |
 | `modelRouter.expensiveModel` | string | - | Model pattern for high-impact, modify, implementation, and escalated tool-heavy turns |
-| `modelRouter.learningModel` | string | `"active"` | Model pattern for background reflection, learn, and skill-creator work; `"active"` uses the current session model |
+| `modelRouter.learningModel` | string | `"active"` | Model pattern for explicit/background Auto Learn, learn, and skill-creator work; automatic reflection uses the orchestrator's current session turn; `"active"` uses the current session model |
 | `failover.subscriptionHop` | boolean | `true` | Allow subscription/OAuth quota failures to switch once to an authenticated provider default; metered/API-key quota failures always halt for explicit user choice |
 
-Use `/settings` → **Model Router** to configure these fields globally or for the current project's `.pi/settings.json`. `/session` and `/usage` show the active router state, diagnostics, and per-tier fitness when the gate is enabled. Profile files can also include a `modelRouter` block so a situation can carry its own cheap, medium, expensive, and learning/reflection models together with its model, thinking level, soul, and resource filters.
+Use `/settings` → **Model Router** to configure these fields globally or for the current project's `.pi/settings.json`. `/session` and `/usage` show the active router state, diagnostics, and per-tier fitness when the gate is enabled. Profile files can also include a `modelRouter` block so a situation can carry its own cheap, medium, expensive, and learning model together with its model, thinking level, soul, and resource filters. Automatic reflection does not select a separate reflection model.
 
 Fitness applicability is intentionally split by autonomy level:
 
@@ -162,17 +162,17 @@ Fitness applicability is intentionally split by autonomy level:
 
 ### Worker Delegation
 
-Pi's native delegation runtime is a durable recursive agent tree. A profile is not required. A profile-free root agent starts from the foreground model and the maximum classified core worker surface the host can materialize: `read`, `grep`, `find`, `ls`, `write`, `edit`, `memory`, the platform shell, and `delegate`. Live service switches can revoke memory, writes, or delegation. Every descendant inherits its parent's immutable execution grant and the tree's remaining budget by default.
+Pi's native delegation runtime manages durable, persistent leaf workers. A profile is not required. A fresh worker inherits the foreground model, live thinking level, and every active classified tool the native lane can materialize. It receives machine-wide read/write/process/network authority by default while raw Pi auth, session, settings, and memory state remain denied. Workers never receive `delegate`, descendant spawning, reflection, or memory mutation.
 
-Whenever `delegate` is active, root and worker prompts use the same provider-neutral decision rule: delegate useful independent research, implementation, tests, or specialist review early; keep dependent or trivial work local. Reasoning level, provider identity, and model identity do not enable or suppress that policy; the model-capability profile may still narrow tools for very small context windows.
+Whenever `delegate` is active, the root prompt uses a provider-neutral decision rule: delegate useful independent research, implementation, tests, or specialist review early; keep dependent or trivial work local. Reasoning level, provider identity, and model identity do not enable or suppress that policy; the model-capability profile may still narrow tools for very small context windows.
 
-An agent may set `authority` on `delegate` to choose its child's role label, authenticated model, supported reasoning level, and classified tool names. Omitted fields inherit from the parent or selected preset. The model-facing start schema has no per-dispatch budget field: ordinary starts inherit the unbounded baseline, host settings, or an owner-authored profile ceiling. The host validates the request, resolves the concrete model and tools, intersects execution authority with the immutable parent grant and live global switches, then persists the exact result before the child starts. A descendant can specialize or narrow authority but cannot add an execution capability, tool, path, or budget that the parent did not hold. Profile selection also cannot add context: every child resource pointer must fully match an ancestral pointer (ID alone is insufficient), soul text must match exactly, and a verifier stays within its previously admitted ancestral verifier or worker boundary. Roles are descriptive routing and audit labels; the built-in compiler does not impose hidden role ceilings, though an embedding may supply an explicit host ceiling.
+For a fresh `delegate start`, the orchestrator may optionally set `model`, `thinkingLevel`, one `path`, and `toolNames`. Omitted fields inherit. `path` changes the worker's real working directory and narrows direct read/write authority to that workspace; omitting it keeps the parent working directory for process execution without narrowing machine scope. Tool overrides may only narrow the compatible inherited surface and an unavailable or root-only requested tool fails admission instead of being silently ignored. The host derives capabilities and paths, applies global kill switches and private-state denials, and persists the exact immutable grant before execution. Reusing an `agentId` keeps its admitted grant and transcript, so overrides are rejected on reuse.
 
-`workerDelegation.modelPins` optionally lets the owner fix the provider, model, and thinking level used by each fresh worker role. With no pins, delegation keeps the adaptive behavior above exactly. An applicable pin overrides model/thinking chosen by `authority` or a preset, while role, tools, resources, paths, and budgets still follow normal admission. This applies to fresh top-level workers, fresh nested workers, and mandatory verifiers. The admitted binding is persisted and reported by `delegate start`; queued work, retries, resumes, recovery, and later tasks on a reused `agentId` keep that immutable contract even if settings change.
+`workerDelegation.modelPins` optionally lets the owner fix the provider, model, and thinking level used by each fresh worker role. With no pins, delegation keeps the adaptive behavior above exactly. An applicable pin is a hard ceiling: a conflicting explicit `model` or `thinkingLevel` override fails closed with `worker_model_pin_conflict:<role>` instead of silently running a different model, while an omitted override uses the pin. Owner-authored preset bindings are still narrowed to the pin. Tools, resources, workspace, and budgets follow normal admission. This applies to fresh workers and mandatory verifiers. The admitted binding is persisted and reported by `delegate start`; queued work, retries, resumes, recovery, and later tasks on a reused `agentId` keep that immutable contract even if settings change.
 
 Pin precedence is deliberately different from ordinary deep-merged settings: global role, global default, trusted local role, trusted local default, then adaptive routing. A global default therefore wins over every project role. Within trusted local settings, the user-level directory overlay wins over the project file at the same role/default tier. Untrusted project settings are ignored. Every binding must contain an exact `provider`, `modelId`, and supported `thinkingLevel`. Malformed pin configuration blocks fresh worker admission with `worker_model_pins_invalid`; an unavailable applicable pin blocks with `worker_model_pin_unavailable:<role>`. Neither condition falls back to another model. Configure pins directly in JSON; `/settings` does not edit them.
 
-A `roles`-only configuration (no `default` in any scope) leaves every role not listed under `roles` entirely unpinned: a delegation using an unlisted role plus an explicit `authority.model` is not blocked, since there is no applicable pin to enforce, and it uses the caller-requested model exactly as ordinary adaptive routing would. This is expected, not an admission bug, but it is easy to configure by accident. The host surfaces it two ways so it stays observable: a settings diagnostic lists the unpinned roles whenever a `roles`-only policy compiles with no `default`, and a delegation that hits this gap (an active pin policy, no pin for the effective role, and an explicit requested model) reports `modelPinBypass: <role>` on its `delegate start` result. Add a `default` to close the gap for every role, or pin every role explicitly under `roles` if adaptive routing is never intended.
+A `roles`-only configuration (no `default` in any scope) leaves every role not listed under `roles` unpinned. This is valid but easy to configure by accident, so settings diagnostics list unpinned roles. Add a `default` to close the gap for every role, or pin every role explicitly under `roles` if adaptive routing is never intended.
 
 ```json
 {
@@ -207,36 +207,22 @@ For a new logical agent, `forkTurns` chooses immutable sanitized birth context:
   "action": "start",
   "instructions": "Implement and verify the scheduler change.",
   "forkTurns": "3",
-  "authority": {
-    "role": "implementer",
-    "model": { "provider": "openai-codex", "modelId": "gpt-5.5" },
-    "thinkingLevel": "high",
-    "capabilities": [
-      "filesystem.read",
-      "filesystem.write",
-      "worktree.read",
-      "worktree.mutate",
-      "process.exec",
-      "memory.query",
-      "workflow.delegate"
-    ],
-    "toolNames": ["read", "grep", "find", "ls", "write", "edit", "memory", "bash", "delegate"],
-    "readPaths": ["."],
-    "writePaths": ["packages/coding-agent"],
-    "budget": { "maxTokens": 32000, "maxCostUsd": 2, "maxToolCalls": 80 }
-  }
+  "model": { "provider": "openai-codex", "modelId": "gpt-5.5" },
+  "thinkingLevel": "high",
+  "path": "/home/me/GitHub/project",
+  "toolNames": ["read", "grep", "find", "ls", "write", "edit", "python", "bash"]
 }
 ```
 
-Fleet creation is bounded before Pi creates a durable task, conversation, agent, or queue entry: depth is at most 8, one parent may own at most 64 direct children, one session may retain at most 256 logical agents, and the scheduler may retain at most 256 queued dispatches. The profile-free baseline is deliberately lean: the session may retain one nested identity at depth one, and that child is a leaf; additional root workers remain available and can reuse the retained specialists. An owner-authored profile may set `delegationLimits.maxDepth`, `delegationLimits.maxChildrenPerAgent`, and `delegationLimits.maxNestedAgentsPerSession` up to the host ceilings; omitted authored limits retain the host ceilings. Descendant profile selection intersects these limits with the ancestor's immutable contract and cannot widen them. Admission dynamically preserves queue and durable-projection headroom for every implementation whose mandatory verifier has not yet materialized, plus a newly admitted contract's verifier. A verifier dispatch that encounters saturation remains represented by its durable subject and replays on a queue-capacity event. The shared durable projection independently caps agents, tasks, and attempts at 256 each. `workerDelegation.maxConcurrent` remains the global running-agent limit; excess admitted work enters the bounded durable queue. The kernel also rejects an exact recursive cycle when a child repeats the same normalized instructions and effective profile already present in its ancestor chain. Root budgets are cumulative across every descendant and attempt: token, cost, tool-call, active-wall-clock, and attempt usage are reconstructed from durable checkpoints and checked before more work is admitted. The default delegation baseline adds no cost or active-time ceiling; positive global settings, profile budgets, and inherited foreground ceilings remain authoritative when explicitly configured.
+Fleet creation is bounded before Pi creates a durable task, conversation, agent, or queue entry: one session may retain at most 256 logical agents, and the scheduler may retain at most 256 queued dispatches. Every compiled worker profile has zero descendant depth and fan-out even if a legacy profile contains recursive limits. Admission preserves queue and durable-projection headroom for mandatory verifiers. A verifier dispatch that encounters saturation remains represented by its durable subject and replays on a queue-capacity event. `workerDelegation.maxConcurrent` is the global running-agent limit; excess admitted work enters the bounded durable queue. Worker token, cost, tool-call, active-wall-clock, and attempt usage are reconstructed from durable checkpoints and checked before more work is admitted. The default delegation baseline adds no cost or active-time ceiling; positive global settings, profile budgets, and inherited foreground ceilings remain authoritative when explicitly configured.
 
-`delegate` exposes the shared durable task/tree state through distinct authority boundaries:
+`delegate` exposes the shared durable worker state to the owning root through distinct control actions:
 
 - `tasks` returns a bounded view of durable DAG tasks, dependencies, status, latest attempt/agent dispatch, verifier state, terminal reason, and persisted retry eligibility. `start.dependsOn` accepts only existing same-objective task IDs; forward, cross-objective, self, and cyclic edges fail before dispatch.
-- `list` returns safe metadata for session agents, including lineage, depth, state, and reusable activity; it does not grant transcript or control authority.
-- `transcript` pages bounded messages only for the session root or the caller's own agent/control subtree, with an opaque raw-entry cursor and page size of 1-64. A page may be empty and still provide `nextCursor` after visiting non-message entries; an individually oversized message is omitted and counted rather than partially returned. Sibling and unrelated peer transcripts are not readable by workers.
+- `list` returns safe metadata for session agents, including state and reusable activity; it does not expose private resume state.
+- `transcript` pages bounded messages for the session root with an opaque raw-entry cursor and page size of 1-64. A page may be empty and still provide `nextCursor` after visiting non-message entries; an individually oversized message is omitted and counted rather than partially returned.
 - `send` and `broadcast` queue bounded, non-waking, threaded peer evidence; broadcast canonicalizes a bounded target set and reports acceptance per target. Peer content is untrusted data, never authority.
-- `follow_up`, `interrupt`, `resume`, and `cancel` may wake or mutate only within the caller's control subtree. `resume` keeps the admitted model, transcript, resources, and grant; a paused objective retains its suspended attempt without starting or cancelling it until objective resume drains the scheduler. `cancel` terminates only the selected current task.
+- `follow_up`, `interrupt`, `resume`, and `cancel` let the owning root steer worker lifecycle. `resume` keeps the admitted model, transcript, resources, and grant; a paused objective retains its suspended attempt without starting or cancelling it until objective resume drains the scheduler. `cancel` terminates only the selected current task.
 - `reply` answers one exact reply-expected request. The session root consumes replies through the acknowledged `inbox`, event-driven `inbox_wait`, and `inbox_ack` flow instead of unsolicited transcript injection.
 - `wait` and `wait_many` are event-driven; `wait_many` accepts a bounded canonical target set and completes in `any` or `all` mode. `retire` replay-safely closes only an idle leaf after its mailbox and reply obligations clear, preserving its binding and transcript.
 
@@ -244,7 +230,7 @@ Transient attempt retries are evidence-gated. A classified provider or transport
 
 `delegate` returns a stable agent/lane identity immediately. A fresh `start` does not accept `laneId`; omit it, retain the returned `agentId`, and pass that `agentId` to a later `start` to reuse the persistent worker. Completion persists a bounded terminal handoff before waking the parent; late output stays in the worker transcript instead of racing into the active foreground transcript. Review-pending results remain `partial` and project blockers remain `blocked` in lane status and terminal handoffs instead of either being collapsed into harness failures. A scheduled transient retry is reported as nonterminal with its durable state retained. A full parent mailbox retains the attempt-keyed handoff until an explicit terminal, mailbox-capacity, state-change, or recovery event drains it—there is no retry polling loop. Exact replays are inert, conflicts fail closed, and delivery errors remain retained. Use `delegate { action: "status", laneId }` for bounded lane-result retrieval.
 
-Global profiles live at `~/.pi/agent/profiles/orchestration/<id>.json`; project profiles live at `.pi/profiles/orchestration/<id>.json`. They are optional presets for model, reasoning, tools, resources, budget, verification, prompt defaults, and recursive `delegationLimits`. Select one with `profileId` on a call or configure `workerDelegation.orchestrationProfile`. `dispatchProfileIds` is preset-routing metadata, not an admission allowlist. Profile `maxConcurrent` is retained in the authored schema but does not override the global scheduler. `delegate` actions `profile_inspect` and `profile_create` manage optional immutable session-scoped narrowings; task profiles inherit the owner-authored base budget unchanged, and direct authority selection does not require a profile.
+Global profiles live at `~/.pi/agent/profiles/orchestration/<id>.json`; project profiles live at `.pi/profiles/orchestration/<id>.json`. They are optional presets for model, reasoning, tools, resources, workspace, budget, verification, and prompt defaults. Select one with `profileId` on a call or configure `workerDelegation.orchestrationProfile`. Profile `maxConcurrent` is retained in the authored schema but does not override the global scheduler. `delegate` actions `profile_inspect` and `profile_create` manage immutable session-scoped narrowings. `profile_create` can omit `baseProfileId`; Pi then derives the foreground model, live thinking, compatible tools, and machine scope before applying optional `model`, `thinkingLevel`, `path`, and `toolNames` narrowing.
 
 A preset with `requireIndependentVerification: true` still names an owner-authored `verificationProfileId`. The runtime creates a separate durable verifier task and accepts the implementation only after a typed verifier decision. A profile using `run_process` must declare `executionPolicy`; that tool launches only listed executables as direct argv. The platform shell is different: it is a real persistent per-agent shell and is not OS/container isolation. Shell commands can exercise the host process, filesystem, network, and credentials available to Pi; direct `write`/`edit` path scopes do not sandbox shell side effects.
 
@@ -252,13 +238,12 @@ Direct `write`/`edit` calls use review-after-apply semantics. The compiled grant
 
 | Setting | Type | Default | Description |
 |---------|------|---------|-------------|
-| `workerDelegation.enabled` | boolean | `true` | Enable autonomous recursive agent trees; explicit `false` is a hard off-switch |
+| `workerDelegation.enabled` | boolean | `true` | Enable autonomous persistent leaf workers; explicit `false` is a hard off-switch |
 | `workerDelegation.orchestrationProfile` | string | - | Optional default execution preset; agents may replace its defaults within inherited authority |
-| `workerDelegation.maxUsd` | number | `0` | Cumulative USD ceiling for one root tree; `0` is unbounded and a positive value explicitly enables the ceiling |
-| `workerDelegation.maxWallClockMs` | number | `0` | Cumulative active wall-clock ceiling for one root tree; `0` is unbounded and a positive value explicitly enables the ceiling |
+| `workerDelegation.maxUsd` | number | `0` | USD ceiling for one worker task; `0` is unbounded and a positive value explicitly enables the ceiling |
+| `workerDelegation.maxWallClockMs` | number | `0` | Active wall-clock ceiling for one worker task; `0` is unbounded and a positive value explicitly enables the ceiling |
 | `workerDelegation.maxConcurrent` | number | `20` | Global running-agent concurrency inside the fixed fleet and queue bounds |
 | `workerDelegation.writeEnabled` | boolean | `true` | Expose direct `write`/`edit`; explicit `false` revokes them for newly admitted work and narrows resumed grants |
-| `workerDelegation.writePaths` | string[] | `["."]` | Global envelope for direct child writes; an explicit empty array revokes direct `write`/`edit` |
 | `workerDelegation.modelPins` | object | - | Optional exact `default` and per-role provider/model/thinking bindings for fresh workers; malformed or unavailable applicable pins fail closed |
 
 ### Tool Repair
@@ -287,21 +272,35 @@ Environment kill switches override their diagnostic layers: `PI_TOOL_REPAIR_DISA
 
 ### Auto Learn Advanced
 
+Native reflection belongs only to the main/orchestrator session. Eligible turns append a durable cue to the orchestrator's next ordinary current-session provider turn; reflection never starts a separate/background model request. Workers cannot run reflection or mutate durable memory; they return evidence to the parent, which decides what should be retained. A fresh main session uses this audited learning policy:
+
 | Setting | Type | Default | Description |
 |---------|------|---------|-------------|
-| `autoLearn.enabled` | boolean | derived from `autonomy.mode` (`false` when off) | Autonomously trigger background history scavenging for long sessions |
+| `learningPolicy.enabled` | boolean | `true` | Route reflection writes through the decision/audit/rollback policy |
+| `learningPolicy.autoApplyEnabled` | boolean | `true` | Apply eligible additive or organizational learning without asking the user to babysit it |
+| `learningPolicy.confidenceThreshold` | number | `50` | Minimum confidence for automatic application |
+| `learningPolicy.minObservations` | number | `1` | Minimum repeated observations for automatic application |
+| `learningPolicy.allowedAutoApplyLayers` | string[] | `["memory", "skill"]` | Layers eligible for automatic application; other layers remain proposals |
+| `learningPolicy.requireRollbackPlan` | boolean | `true` | Require an inverse plan before an automatic durable write |
+| `learningPolicy.autoApplySupersessions` | boolean | `false` | Keep memory replacement/removal approval-gated unless explicitly enabled |
+
+Safe `memory_add`, `okf_add`, and `okf_organize` writes can therefore land autonomously, including moving an exact hot-memory fact from `MEMORY.md` into structured OKF storage. Clean skill promotion is also eligible after overlap checks. `memory_replace` and `memory_remove` remain proposals by default because they supersede existing knowledge. Every applied write records its decision, outcome, and rollback data.
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `autoLearn.enabled` | boolean | `true` in every autonomy mode | Enable root-session current-turn reflection. Disabling it immediately dismisses any pending cue and removes the standing reflection contract; re-enabling does not resurrect dismissed evidence. Automatic reflection never schedules a separate or background model request. |
 | `autoLearn.model` | string | `modelRouter.learningModel`, otherwise `"active"` | Legacy/direct override for the background learner; `"active"` uses the current session model, otherwise use a `pi --model` pattern |
-| `autoLearn.longSessionMessages` | number | `32` | Trigger after this many message entries in the active branch |
-| `autoLearn.longSessionContextPercent` | number | `70` | Trigger when current context usage reaches this percent |
-| `autoLearn.cooldownMinutes` | number | `120` | Per-session-tenant cooldown between learner launches |
+| `autoLearn.longSessionMessages` | number | `32` | Readiness threshold after this many message entries in the active branch for an eligible learner run |
+| `autoLearn.longSessionContextPercent` | number | `70` | Readiness threshold when current context usage reaches this percent |
+| `autoLearn.cooldownMinutes` | number | `1440` | Per-session-tenant cooldown between learner launches |
 | `autoLearn.leaseMinutes` | number | `90` | Shared-state lease duration for a running background learner |
-| `autoLearn.maxConcurrentLearners` | number | `2` | Maximum running Auto Learn background learners per session tenant |
+| `autoLearn.maxConcurrentLearners` | number | `1` | Maximum running Auto Learn background learners per session tenant |
 | `autoLearn.applyHighConfidence` | boolean | `false` | Allow the learner to apply high-confidence memory candidates; broader write authority is controlled by `autonomy.mode` |
-| `autoLearn.reflectionReview` | boolean | `true` | When Auto Learn is enabled, also run bounded post-turn reflection after corrective or complex turns |
-| `autoLearn.reflectionMinToolCalls` | number | `5` | Trigger reflection review after this many tool calls in one completed turn |
-| `autoLearn.reflectionCooldownMinutes` | number | `60` | Per-session-tenant cooldown between reflection-review learners |
+| `autoLearn.reflectionReview` | boolean | `true` | When enabled, allow root-only automatic reflection cues after eligible corrective or complex turns; the cue is consumed by the next ordinary current-session turn |
+| `autoLearn.reflectionMinToolCalls` | number | `12` | Queue a root-session reflection cue after this many tool calls in one completed turn |
+| `autoLearn.reflectionCooldownMinutes` | number | `1440` | Per-session-tenant cooldown between automatic root-session reflection cues; corrective and complex-task signals can bypass it |
 
-Use `/settings` → **Model Router** for the preferred place to choose the scavenger/reflection/skill-creator model. Use `/settings` → **Auto Learn Advanced** for trigger/cooldown/concurrency overrides and the legacy direct `autoLearn.model` override. Use `/autonomy status` for the compact preset dashboard, `/auto-learn status` to inspect trigger state, reflection cooldown, and running leases, or `/auto-learn run` to start one learner immediately.
+Use `/settings` → **Model Router** for the preferred place to choose the learner/skill-creator model. Automatic reflection uses the orchestrator's current session turn rather than a separate or background model request. Use `/settings` → **Auto Learn Advanced** for readiness/cooldown/concurrency overrides and the legacy direct `autoLearn.model` override. Use `/autonomy status` for the compact preset dashboard, `/auto-learn status` to inspect readiness and running leases, or `/auto-learn run` to explicitly start one bounded background learner immediately. Workers never receive reflection or durable-memory mutation authority; they return evidence to the root orchestrator.
 
 When enabled, Auto Learn keeps a small shared state file for visibility/cooldowns, but prompt/log/session artifacts are isolated under per-session-tenant directories so one session's learner does not consume another session's concurrency budget. Learners must confront available user/project memory first, using existing rules, preferences, corrections, and project facts to decide whether each candidate is useful, unique versus merge/upgrade-worthy, and agent-improving. Candidate validation is chunked/vectorized instead of one memory query per candidate. Successful Auto Learn workers purge their internal prompt/log/session artifacts after exit; the 7-day retention pruner is a fallback for unfinished or failed artifacts, and active leases are skipped so running learners are not raced. Provider/user history pruning is delegated to the continuous-learning tool after it records a learning outcome: only files older than 7 days whose current fingerprint still matches a successfully extracted index entry are deleted, and active/current sessions are protected.
 
@@ -312,13 +311,13 @@ When enabled, Auto Learn keeps a small shared state file for visibility/cooldown
     "model": "active",
     "longSessionMessages": 32,
     "longSessionContextPercent": 70,
-    "cooldownMinutes": 120,
+    "cooldownMinutes": 1440,
     "leaseMinutes": 90,
-    "maxConcurrentLearners": 2,
+    "maxConcurrentLearners": 1,
     "applyHighConfidence": false,
     "reflectionReview": true,
-    "reflectionMinToolCalls": 5,
-    "reflectionCooldownMinutes": 60
+    "reflectionMinToolCalls": 12,
+    "reflectionCooldownMinutes": 1440
   }
 }
 ```
@@ -349,10 +348,21 @@ The checkpoint owns user intent mechanically: `## Active Task` copies the latest
 
 | Setting | Type | Default | Description |
 |---------|------|---------|-------------|
-| `costGuard.maxTurnUsd` | number | `0` | Projected per-turn USD warning ceiling; disabled by default, positive values explicitly enable it |
+| `costGuard.enabled` | boolean | `false` | Explicitly enable foreground per-turn cost projections and enforcement |
+| `costGuard.maxTurnUsd` | number | `0` | Projected per-turn USD ceiling; a positive legacy value remains dormant until `enabled` is `true` |
 | `costGuard.action` | string | `"warn"` | `"warn"` only reports the estimate; `"downgrade"` also lowers reasoning one rung for that request without changing saved/profile state |
 
-The projection uses the session response reserve, cached-input rates, and model-declared long-context tiers. ChatGPT subscription usage is marked `(sub)` and does not enter the USD guard.
+The projection uses the session response reserve, cached-input rates, and model-declared long-context tiers. ChatGPT subscription usage is marked `(sub)` and does not enter the USD guard. Enable it explicitly through `/settings` → **Foreground cost guard**, or in JSON:
+
+```json
+{
+  "costGuard": {
+    "enabled": true,
+    "maxTurnUsd": 0.5,
+    "action": "warn"
+  }
+}
+```
 
 ### Context GC
 

package/docs/task-steps.md

@@ -8,6 +8,8 @@ Task steps complement the native goal and delegation systems:
 - `goal` records durable outcome requirements and evidence.
 - `delegate` starts worker lanes, retrieves status, reviews claims, and coordinates them.
 
+For the canonical Survey → Contract → Plan/Route → Execute → Prove/Deliver flow and the ownership boundary between these systems, see [Five-step work lifecycle](work-lifecycle.md).
+
 ## Statuses
 
 Each step has one of these statuses:

package/docs/tmux-agent-manager.md

@@ -31,13 +31,18 @@ Run `/tmux-agents` or call `tmux_agent_manager` with `action: "status"` to check
 
 ## Completion contract
 
-`fire_task` creates panes, injects prompts, and arms one event-driven `tmux pipe-pane` watcher per worker before returning. Each watcher:
+`fire_task` creates idle panes and arms one event-driven `tmux pipe-pane` watcher per worker. It then
+starts every provider with the initial prompt file as part of the same CLI command
+(`--prompt-interactive` for Agy), so task delivery cannot race TUI startup. Each watcher:
 
 1. consumes pane output as it arrives;
 2. writes one atomic terminal result when it sees the worker's `DONE` or `BLOCKED` marker, the pane closes, or its one-shot deadline expires;
 3. updates tmux status metadata and emits a display notification.
 
-The parent Pi session watches result-file events. Once a turn's worker is terminal, it records a per-agent notification marker (`notifiedTurn`) and sends a bounded, source-labelled untrusted handoff with `triggerTurn: true`. Startup performs one reconciliation pass for terminal events produced while Pi was offline, and also reconciles tmux **sessions**: see [Persistence](#persistence-follow-ups-reconcile-dismiss) below.
+On deadline, the watcher persists `timeout` first and then terminates its owned pane. A timed-out
+provider process therefore cannot remain live and continue spending resources.
+
+The parent Pi session watches result-file events. Once a turn's worker is terminal, it records a per-agent notification marker (`notifiedTurn`) and sends a bounded, source-labelled untrusted handoff with `triggerTurn: true`. Startup reconciles every persisted terminal turn into host lane state, including turns whose user-facing handoff was already delivered, so a rehydrated running projection cannot outlive the worker. It also reconciles tmux **sessions**: see [Persistence](#persistence-follow-ups-reconcile-dismiss) below.
 
 Do not poll pane state, capture pane output, or inspect logs merely to detect completion. Use `job_status` or terminal artifacts after the handoff only when its bounded evidence is insufficient.
 
@@ -53,13 +58,14 @@ actions manage that persistence:
   (relaunch with `fire_task` instead) or if the job was `dismiss`ed.
 - **`dismiss`** — stops tracking a job (no more re-arming, no more handoffs) without killing its tmux
   session; the pane keeps running and can still be attached to (`tmux attach -t <session>`) or stopped
-  later with `stop_job`/`stop_session`.
+  later with `stop_job`/`stop_session`. Dismiss detaches the completion watcher, so its old deadline no
+  longer owns that pane.
 - **Session reconcile** — on session start, Pi diffs live tmux sessions against its own job records for
   jobs it started. A session that has disappeared while its job was not yet terminal is marked orphaned
-  (informational only — nothing is ever killed to produce this state, and the job directory is never
+  (informational only — reconciliation never kills it to produce this state, and the job directory is never
   deleted automatically). A session that is still alive with a pending turn has its watcher re-armed so
-  the job can still complete normally. Killing a session always stays behind the explicit
-  `stop_job`/`stop_session` confirm path.
+  the job can still complete normally. Manual early termination stays behind the explicit
+  `stop_job`/`stop_session` confirm path; a managed deadline terminates only its owned pane.
 
 An idle worker (no turn currently dispatched) does not hold this session's reload-quiesce; `/reload` is
 never blocked merely because a persistent tmux worker exists between turns.
@@ -68,33 +74,36 @@ Running managed lanes are checkpointed at dispatch and rehydrated with the same
 `/reload`. A later terminal event therefore completes the existing goal binding instead of minting a
 replacement lane or risking a duplicate dispatch.
 
-## Approval-gated dispatch: the standing grant
-
-A real (non-dry-run) `fire_task` or `send_followup` launch requires either a **standing grant** or a
-one-shot interactive approval — never a silent launch:
-
-- **`grant_dispatch`** authorizes repeated unattended dispatch. Set `agent` (required), `maxLaunches`
-  (required), and optionally `goalId` (an unscoped grant covers any goal), `allowedTools`,
-  `resourceProfile`, `writePaths`, and `expiresInMinutes`. Requires interactive confirmation when a UI is
-  attached; in print/rpc/non-interactive mode, requires the `--allow-tmux-dispatch` CLI flag instead.
-  Once granted, matching launches proceed unattended. Team launches validate every child against the
-  grant and consume one unit of `maxLaunches` for each child process launched; a single-provider grant
-  cannot authorize a mixed-provider team.
-- **`revoke_grant`** ends a standing grant early (defaults to whichever grant is currently active).
-- With **no covering grant**: an interactive session is prompted for a one-shot approval; a
-  non-interactive session (no UI, no grant) is **refused** with a clear error — never launched silently.
-
-A grant-covered (or one-shot-approved) `pi` child is launched with a **restricted profile**: `--tools`
-(or a read-biased default), `--resource-profile` (or `--no-extensions --no-skills`), and a scoped
-`--append-system-prompt` naming the grant and a fixed hard-stop list (publish/push/tag/credential
-changes/destructive deletion must come back BLOCKED, never self-approved). This pushes the envelope into
-the **child's own** launch configuration — it is not an in-process sandbox, and non-`pi` agents
-(`agy`/`claude`/`codex`/`opencode`/custom) are bounded only at the launch layer; their internal tool-loop
-behavior is that CLI's own responsibility.
-
-Grant budget (`maxLaunches`, `expiresInMinutes`) is real and enforced. `maxUsdAdvisory` and any
-self-reported worker usage are **advisory** — a claim to review, never a hard cap across the process
-boundary (the child bills under its own authentication).
+## Autonomous dispatch profiles
+
+A real `fire_task` or `send_followup` runs autonomously without a UI prompt or CLI allow flag. Tmux
+availability detection happens inside every action; `guard` is diagnostic only and is never a required
+handshake.
+
+Before `fire_task` creates any pane, watcher, prompt, or job artifact, it derives one immutable internal
+execution profile per worker and durably reserves that worker's managed lane. Omitted tool and thinking
+fields inherit the orchestrator's eligible worker surface. Omitted `path` uses the normal process cwd
+while inheriting the host-derived full-machine scope except private harness paths. An explicit `path`
+sets the process cwd and passes an immutable child-scope channel that enforces that workspace for Pi's
+structured filesystem tools. Follow-up turns reuse the persisted profile and may change instructions,
+never authority.
+
+For `pi` workers, `tools`, `resourceProfile`, `thinkingLevel`, and `worktreeLane` become Pi CLI flags. The shared worker
+ceiling removes memory, root-owned durable state, and agent-launching controls while retaining ordinary
+inherited capabilities such as Python. When `resourceProfile` is omitted, the host compiles the
+orchestrator's effective extension/skill/prompt/theme/agent/tool filters into a one-shot child profile;
+an explicit value overrides that inheritance. The structured read/write/edit/search tools hard-deny
+Pi's private auth, session, memory, settings, state, and work roots, and an explicit `path` further
+restricts those structural calls to that workspace. Arbitrary process tools such as bash and
+Python remain deliberate host-trust boundaries and can reach OS-visible files; this profile is not
+misrepresented as process sandboxing. These fields are rejected for non-Pi providers because arbitrary
+external CLIs own their own tool, thinking, and workspace controls; put native provider options in
+`command` instead. A non-Pi `path` changes its cwd only. Its durable profile records one machine-wide,
+host-trusted process (`bash` capability) rather than projecting the parent's Pi tool names or claiming
+CLI/OS sandbox enforcement.
+
+Any cooperative self-reported worker usage is **advisory** — a claim to review, never a hard cap across
+the process boundary (the child bills under its own authentication).
 
 Dispatched tmux workers appear as `tmux-worker` lanes alongside in-process worker lanes in `/autonomy`
 and `delegate { action: "status" }`; a worker's self-reported changed files are re-checked against the session's active
@@ -105,16 +114,14 @@ write scope and flagged for parent review when out of scope, exactly like an in-
 The `goal` tool's `dispatch_worker` action can bind a single open requirement to a persistent tmux worker
 instead of the default in-process one: pass `dispatchTarget: "tmux"`. Core invokes `fire_task` itself (the
 same call the model would make) with exactly one `pi` agent, so the dispatch maps 1:1 to the
-requirement's bound lane; the launch still goes through the standing-grant authorization above unchanged
-— an unattended goal/idle loop with no covering grant is honestly refused, never silently launched. The
-requirement's binding is recorded either way; a successful tmux dispatch waits and resumes through the
-same lane machinery as an in-process worker.
+requirement's bound lane. The same autonomous profile derivation and pre-launch durable reservation
+apply. A successful tmux dispatch waits and resumes through the same lane machinery as an in-process
+worker.
 
 When no worker was dispatched, the tool response's `dispatchSkipReason` explains why:
 
-- `no_standing_grant` — no covering grant, and this call had no UI to prompt (run `grant_dispatch` first).
 - `tmux_extension_not_loaded` — `tmux_agent_manager` is not loaded in this session (see Enable above).
-- `tmux_dispatch_failed` — the `fire_task` launch threw for a reason other than the grant (a bad jobId, a
+- `tmux_dispatch_failed` — the `fire_task` launch threw (an invalid `launchKey`, a
   live session-name collision, an environment failure).
 - `tmux_dispatch_incomplete` — the launch call returned without the job/agent details needed to identify
   the new lane.
@@ -130,8 +137,8 @@ When no worker was dispatched, the tool response's `dispatchSkipReason` explains
 
 ## Safety
 
-Launch actions run directly unless `dryRun: true` is requested, and are approval-gated per the standing
-grant above. Stop actions can discard active pane work, so they remain previews by default and require
+Launch actions run directly unless `dryRun: true` is requested. Stop actions can discard active pane
+work, so they remain previews by default and require
 `confirm: "yes-tmux-stop"` for execution. Existing sessions are never replaced silently; `force: true`
 archives an old job directory but does not kill a live tmux session.
 

package/docs/usage.md

@@ -316,6 +316,6 @@ pi --exclude-tools ask_question
 
 ## Design Principles
 
-Pi keeps the core focused and pushes project-specific workflows into extensions, skills, prompt templates, and packages. Core includes the cross-project lifecycle primitives it depends on itself: native goals, task steps, durable recursive agent orchestration, and a platform-selected shell. Broader integrations such as MCP and external-provider teams remain extension/package territory.
+Pi keeps the core focused and pushes project-specific workflows into extensions, skills, prompt templates, and packages. Core includes the cross-project lifecycle primitives it depends on itself: native goals, task steps, durable root-managed leaf-worker orchestration, and a platform-selected shell. Broader integrations such as MCP and external-provider teams remain extension/package territory.
 
 For the full rationale, read the [blog post](https://mariozechner.at/posts/2025-11-30-pi-coding-agent/).

package/docs/work-lifecycle.md

@@ -0,0 +1,137 @@
+# Five-step work lifecycle
+
+This document is the canonical design for how Pi carries a request from first inspection to verified delivery. It defines five phases only, then maps each phase onto existing `goal`, `task_steps`, delegation, evidence, and approval owners. For tool syntax, read [Task steps](task-steps.md) and [Task worker presets](worker-profiles.md); this document does not duplicate those references.
+
+## Confidence and scope
+
+**Confirmed:** current Pi claims were checked against the source paths cited below. **External comparison:** Codex observations were checked against the adjacent `external/codex` checkout and are not claims about Pi. **Not checked:** provider-specific compliance beyond the deterministic prompt and gate tests, stochastic routing quality, and runtime performance under a large worker fleet.
+
+## Core invariant
+
+Pi uses this one five-phase spine:
+
+1. **Survey**
+2. **Contract**
+3. **Plan/Route**
+4. **Execute**
+5. **Prove/Deliver**
+
+The phase list is source-owned by `WORK_LIFECYCLE_PHASES`. Every root prompt receives the phase contract; the owner-specific line appears only when a goal or planning tool is active, and child workers keep their narrower contract (`packages/coding-agent/src/core/provider-prompt-contracts.ts`; `packages/coding-agent/src/core/system-prompt-builder.ts`). Chat and minimal-class models receive the same five phases in a 56-character compact form so their stable prompts remain inside their 2,048- and 4,096-character capability envelopes; larger root profiles retain the full contract (`packages/coding-agent/src/core/model-capability.ts`). Short or read-only work may collapse phases, but it must not invent a sixth phase or another workflow state machine.
+
+State ownership stays singular:
+
+- `goal` owns the desired outcome, acceptance requirements, and trusted evidence.
+- `task_steps` owns the foreground execution plan.
+- `delegate` and the orchestration runtime own worker identity, attempts, grants, results, and independent verifier lanes.
+- the risk and policy gates own authorization decisions.
+- the root session owns integration and the final acceptance decision.
+
+The runtime already joins these owners through a read-only projection; it does not cross-write their stores (`packages/coding-agent/src/core/orchestration/work-state-projection.ts:111-167`; `packages/coding-agent/src/core/goals/goal-runtime-snapshot.ts:18-87,136-151`).
+
+## 1. Survey
+
+Start project work with bounded, read-only discovery. Read the relevant project instructions, entry points, nearby tests, affected contracts, and existing implementation owners. Stop discovery when the evidence is sufficient to state a delivery contract and its uncertainty; do not scan the whole repository by default.
+
+Survey happens before project mutation and before final delivery classification. Pi's existing model router is intentionally not the delivery classifier: routing receives the expanded original prompt during request preparation, before request-model validation and tool execution (`packages/coding-agent/src/core/agent-session.ts:2602-2624`; `packages/coding-agent/src/core/model-router-controller.ts:438-464`; `packages/coding-agent/src/core/risk-classifier.ts:87-179`). Reusing that prompt-only classifier for project scope would make POC-versus-complete decisions without source evidence.
+
+**Exit condition:** relevant project facts, affected surfaces, uncertainty, and consequential owner choices are known. Routine implementation choices remain with Pi.
+
+## 2. Contract
+
+Translate the request and Survey evidence into a project-relative outcome contract. Record that contract in the goal objective and requirements, not in task titles. Goal state already owns requirement status and evidence bindings (`packages/coding-agent/src/core/goals/goal-state.ts:34-128`), and the goal tool now tells the root to make delivery depth explicit after Survey (`packages/coding-agent/src/core/tools/goal.ts:428-442`).
+
+Use these delivery meanings:
+
+- **POC:** a bounded executable proof that establishes whether the requested capability works. Production integration is intentionally outside the contract unless explicitly named.
+- **MVP:** the smallest usable project slice that proves the requested feature in its real context. Deliberately omitted integrations must be explicit.
+- **Complete feature:** a production-ready feature integrated across every affected project surface. A demo, isolated helper, or passing happy-path test is not complete.
+
+For a complete feature, inspect and include every applicable surface: public entry points and callers; types and wire contracts; configuration and defaults; persistence, migration, and compatibility; cancellation, failure, retry, and resume behavior; UI or CLI exposure; tests and production-shaped verification; documentation and changelog; obsolete-path cleanup. “Applicable” matters: the contract must not manufacture irrelevant work merely to fill a checklist.
+
+**Exit condition:** acceptance criteria distinguish requested outcome from implementation method, name the delivery depth, cover applicable project integration, preserve authority boundaries, and identify what evidence can prove each criterion.
+
+## 3. Plan/Route
+
+Create the mutation plan in `task_steps`, link steps to goal requirements, and keep one step active. `task_steps` already enforces one active item and preserves notes/evidence (`packages/coding-agent/src/core/tasks/task-state.ts:358-400,431-488`); its tool contract now makes Plan/Route precede project mutation and forbids a second outcome state (`packages/coding-agent/src/core/tools/task-steps.ts:316-332`). Detailed plans may contain more than five checklist items—the five-item limit applies to lifecycle phases, not implementation decomposition.
+
+Choose solo versus team execution adaptively. Long duration alone never mandates a team. Evaluate:
+
+- risk and invariant sensitivity;
+- uncertainty and missing expertise;
+- urgency and available parallelism;
+- reversibility and blast radius;
+- test strength and verification cost;
+- cognitive load and integration coupling.
+
+Keep dependent, trivial, context-heavy, or interactive work local. Delegate separable discovery, implementation, tests, or specialist review when doing so improves speed or confidence. Require a different reviewer identity when the factors make implementation self-review insufficient. Worker profiles already support mandatory independent verification and resolve a dedicated verifier shipment (`packages/coding-agent/src/core/delegation/worker-delegation-controller.ts:710-734`).
+
+**Exit condition:** ordered work, stable owners, dependencies, acceptance evidence, verification depth, and solo/team route are explicit before mutation.
+
+## 4. Execute
+
+Work the first open plan item. The root remains integration owner; a worker result is evidence, not accepted truth. Workers receive immutable authority and result contracts through the existing orchestration runtime rather than a lifecycle-specific executor (`packages/coding-agent/src/core/orchestration/contracts.ts:367-509`; `packages/coding-agent/src/core/orchestration/policy-gate.ts:10-30`).
+
+Record changed files, focused tests, rejected hypotheses, and blockers on the relevant task and goal requirement. Wait event-driven at true dependencies. Worker terminals already pass through one durable notification coordinator and one foreground handoff path; matching active-goal completions wake the parent (`packages/coding-agent/src/core/background-lane-controller.ts:174-200`; `packages/coding-agent/src/core/foreground-terminal-handoff-controller.ts:197-205,341-429`). The goal continuation decision waits on bound in-flight workers and resumes once work can advance (`packages/coding-agent/src/core/goals/goal-continuation-controller.ts:284-353`).
+
+A failed implementation or review does not create a new phase. Update Contract only if the requested outcome changed; otherwise return to Plan/Route or continue Execute with the new evidence.
+
+**Exit condition:** planned mutations are integrated, no required work is silently deferred, and evidence is ready for independent acceptance.
+
+## 5. Prove/Deliver
+
+Verify from narrow to broad in proportion to risk: focused reproduction and negative control, adjacent tests, type/build/static gates, then production-shaped checks when the contract requires them. Independent review must inspect the integrated result, not only worker claims or exit codes. Goal completion already distinguishes proven requirements from open work, waits for cited background tasks, and requires an explicit completion transition (`packages/coding-agent/src/core/goals/goal-continuation-controller.ts:198-237`; `packages/coding-agent/src/core/goal-loop-controller.ts:88-199`).
+
+When checks are green and the owner requested or authorized a checkpoint, create a local commit inside Prove/Deliver. Commit is not a sixth lifecycle state. The risk classifier now admits one plain local `git commit` as a reversible scoped write, while composed shell commands, history-rewriting commits, push, reset, clean, stash, rebase, release, deploy, and publish operations stay approval-gated (`packages/coding-agent/src/core/risk-classifier.ts:220-265`; `packages/coding-agent/src/core/autonomy/gates.ts:189-219`). A commit message containing words such as “release” does not turn a local checkpoint into publication.
+
+`git push`, tags, releases, package publication, deployment, destructive operations, credential/authentication changes, settings/authority expansion, and other external side effects remain owner-gated. Approval produces authority for the requested operation; it is not proof that the feature is correct (`packages/coding-agent/src/core/orchestration/contracts.ts:486-509`; `packages/coding-agent/src/core/orchestration/policy-compiler.ts:161-186`).
+
+**Exit condition:** every required criterion has trusted evidence, integrated review is clean, no active work remains, authorized local checkpointing is complete, and either delivery is complete or Pi is explicitly waiting at an external authorization boundary. Any failed criterion loops to Contract, Plan/Route, or Execute.
+
+## Current-code audit
+
+### Retained as authoritative
+
+**Confirmed:** goal state, task state, delegated task runtime, worker lifecycle, foreground handoff, continuation, risk assessment, and approval compilation are live owners with focused tests. The goal/task/worker read model already links stable IDs without merging their mutation paths (`packages/coding-agent/src/core/orchestration/work-state-projection.ts:89-167`). Historical hardening of these owners is documented in [Goal/Task-Steps/Subagent Fix Cycle](goal-task-subagent-cycle-2026-07-19.md); this document links rather than restating that dated fix ledger.
+
+### Rewired in this feature
+
+**Confirmed:**
+
+- one root-only lifecycle contract is always assembled, with goal/task/delegate ownership wording added only when the corresponding planning surface is available;
+- goal and task tool guidance directs Contract and Plan/Route into their existing owners;
+- delegation guidance makes team use adaptive rather than duration-triggered;
+- plain local commits no longer hit the publication/destructive approval path;
+- focused tests lock the five exact phases, root/child/tool-surface prompt gating, project-relative delivery wording, adaptive factors, and local-commit negative controls.
+
+No lifecycle database, controller, event type, planner store, or delivery enum was added. Delivery completeness is contextual and belongs in acceptance requirements; a global enum could not determine which project surfaces are applicable after discovery.
+
+### Deliberately not reused as delivery classification
+
+**Confirmed:** `classifyModelRouterRoute(prompt)` and its `intent-classifier.ts` re-export remain model-cost/risk routing mechanisms. They run on prompt text before Survey and cannot safely decide project delivery depth. The orchestration event store remains the delegated execution owner; mirroring root lifecycle phases into it would duplicate goal/task state.
+
+### Residual limits
+
+**Confirmed limitation:** adaptive routing and the decision to request an independent reviewer are semantic decisions made by the root under the lifecycle contract. The host deterministically enforces worker authority and a profile's required verifier once selected, but it does not infer project risk after Survey or auto-spawn reviewers for solo work.
+
+**Confirmed limitation:** automatic local checkpointing means the root invokes a plain `git commit` after green evidence. Pi does not run an ambient auto-commit daemon, because that could capture unrelated owner changes without a proven patch boundary.
+
+**Not checked:** prompt conformance cannot prove every provider follows the lifecycle under all context-pressure conditions. Deterministic prompt-shape tests and completion gates reduce that risk; evidence-gated review remains necessary.
+
+## Codex mechanisms considered
+
+**External comparison, confirmed against the adjacent checkout:** Codex's Thread Store exposes one raw history append API, one metadata update API, and a preferred `LiveThread` path for active persistence (`../../external/codex/codex-rs/thread-store/README.md:3-30`). That supports Pi's one-owner-per-invariant decision; it does not justify copying Codex's storage types.
+
+Codex review launches a one-shot subagent with an explicit review prompt, disables collaboration features inside that reviewer, and marks it as `SubAgentSource::Review` (`../../external/codex/codex-rs/core/src/tasks/review.rs:103-140`). Pi retains the same useful separation—implementation evidence is reviewed by a distinct identity when warranted—through its existing verifier shipment instead of adding a second review subsystem.
+
+Codex approval handling is tool/operation scoped rather than a generic “commit phase”: the tool orchestrator computes an execution approval requirement, requests approval when needed, then attempts the tool under the selected sandbox (`../../external/codex/codex-rs/core/src/tools/orchestrator.rs:154-233`). Pi follows the same separation: lifecycle acceptance and execution authority remain different decisions. No Codex rollout or thread-store code is copied.
+
+## Verification map
+
+- Prompt lifecycle and tool-surface gating: `packages/coding-agent/test/system-prompt-builder-tool-selection.test.ts`.
+- Stable compact base prompt: `packages/coding-agent/test/system-prompt.test.ts`.
+- Local commit and approval negative controls: `packages/coding-agent/test/autonomy-risk-assessment.test.ts`.
+- Existing goal/task/delegate behavior: the focused suites referenced by [Task steps](task-steps.md) and [Goal/Task-Steps/Subagent Fix Cycle](goal-task-subagent-cycle-2026-07-19.md).
+
+## Documentation scope note
+
+Covered in depth: lifecycle semantics, delivery-depth contract, ownership, current wiring, local checkpoint authorization, and the directly compared Codex mechanisms. Structurally checked: goal continuation, worker verifier admission, terminal handoff, work-state projection, and approval compilation. Not checked in depth: every provider adapter, every worker profile, UI rendering, pipeline internals, release automation, and performance under fleet load.