pantheon-opencode 1.6.0-beta.10 → 1.6.0-beta.11

package/src/instructions/agent-return-format.instructions.md

@@ -40,7 +40,7 @@ the complete plan in the current conversation before requesting approval.
 
 ## Council Specialist Response Format
 
-When responding to a `/pantheon` council synthesis invocation, specialists MUST return this structured format:
+When responding to a `/pantheon` council synthesis invocation, specialists MUST return this structured format. First-round specialists receive independent prompts without peer responses, whether dispatch is parallel or synchronous/sequential; they therefore cannot know actual peer positions. Do not guess them, claim agreement/disagreement with unseen peers, or self-reference in agreement signals. Omit `agreement_signals` or write `none` in the first round. In a rebuttal round, signals may reference only peer responses included in that round's prompt. Zeus derives agreement and disagreement during synthesis by comparing actual responses.
 
 ```
 ## specialist_response
@@ -49,8 +49,8 @@ When responding to a `/pantheon` council synthesis invocation, specialists MUST
 **trade_offs:** <what's gained vs lost, specific>
 **risks:** <what could go wrong, max 3 items>
 **confidence:** High | Medium | Low
-**agreement_signals:** agree:@agent1 on <issue>, agree:@agent2 on <issue> | disagree:@agent3 on <issue>
-**specific_claims:** <count of specific factual claims in response>
+**agreement_signals:** <omit or `none` in first round; rebuttal may cite only visible peer responses>
+**specific_claims:** <optional self-reported count; advisory only, not evidence>
 ```
 
 ### Field Rules
@@ -62,26 +62,28 @@ When responding to a `/pantheon` council synthesis invocation, specialists MUST
 | trade_offs | ✅ | At least one gain and one loss, specific to context |
 | risks | ✅ | Max 3 bullet points |
 | confidence | ✅ | One of: High, Medium, Low |
-| agreement_signals | Optional | Format: `agree:@agent on issue \| disagree:@agent on issue`. Use only when you can reference other specialists expected positions. |
-| specific_claims | ✅ | Integer count of verifiable factual statements in the response |
+| agreement_signals | Optional | Omit or use `none` in the first round. In rebuttal, reference only peer responses visible in the prompt; never speculate or self-reference. Zeus derives synthesis positions from actual responses, not these signals. |
+| specific_claims | Optional | Self-reported integer count only; advisory and not independently validated. Do not treat the count alone as evidence or proof of confidence. |
 
 ### Confidence Guidelines
 
-- **High**: Position backed by 3+ specific claims with evidence or direct experience
-- **Medium**: Position backed by 1-2 specific claims
+- **High**: Position backed by at least 3 verifiable claims supported by evidence in the response; a self-reported count alone does not qualify
+- **Medium**: Position backed by at least 1 verifiable claim supported by evidence in the response
 - **Low**: Position is opinion-based or speculative
 
+Equal self-reported counts (for example, several specialists each reporting 7) do not by themselves prove fabrication; assess whether the actual response contains verifiable, supported claims.
+
 ### Example
 ```
 ## specialist_response
-**position:** The BackgroundJobBoard should be used for council crash recovery
-**reasoning:** The board already supports running→completed→reconciled state machine with persistence. Registering council dispatches there adds ~50ms overhead but prevents total session loss on context crash. The WAL pattern ensures no data loss on restart.
-**trade_offs:** Gain: crash recovery for multi-minute council sessions. Lose: ~50ms registration overhead per council.
-**risks:** Board persistence failure could block council start — implement with fire-and-forget error handling
-**confidence:** High
-**agreement_signals:** agree:@themis on persist-before-notify
-**specific_claims:** 3
+**position:** Use a bounded local cache for the read-heavy endpoint.
+**reasoning:** The endpoint repeatedly reads the same reference data. A bounded cache reduces repeated lookups, while a short TTL limits staleness.
+**trade_offs:** Gain: fewer repeated reads. Lose: results may remain stale until the TTL expires.
+**risks:** Cache invalidation may lag after updates.
+**confidence:** Medium
+**agreement_signals:** none
+**specific_claims:** 2 (self-reported; advisory)
 ```
 
 ## Memory Context
-If memory affected the result, state the takeaway briefly; do not repeat the entry or task context.
+If memory affected the result, state the takeaway briefly; do not repeat the entry or task context. If persistence was expected but no write tool was exposed or a write failed, state that it was not persisted; never imply a successful store without confirmation.

package/src/instructions/memory-protocol.instructions.md

@@ -16,8 +16,9 @@ These rules apply to all agents; each agent file may add domain-specific rules.
 - Use a targeted query (`top_k=2`); do not search the whole prompt by default. Missing or irrelevant results never block current work.
 
 ### Persistence
-- `memory_store()` is manual, not automatic. Store at most one concise, reusable top-level result; never persist routine child summaries, phase updates, test logs, or temporary state.
-- Confirm the store succeeded before claiming persistence. There is no automatic memory WAL or recovery. Add ADRs to the memory bank only when explicitly requested.
+- A memory write is optional and conditional on a write tool being exposed and permitted in the active session. Search permission does not imply write permission; in the reported Beta 10 Zeus root, `memory_store` is not exposed/granted.
+- Store at most one concise, reusable top-level result; never persist routine child summaries, phase updates, test logs, or temporary state. Confirm a successful write before claiming persistence.
+- If no write tool is available or the write did not succeed, say that the information was not persisted. Do not imply automatic memory storage or recovery. Add ADRs to the memory bank only when explicitly requested.
 
 ### Relevance and permanent records
 Ignore weak matches; routine summaries do not belong in durable memory.

package/src/instructions/test-economy.instructions.md

@@ -0,0 +1,21 @@
+---
+description: "Test economy — write smaller, focused suites; heavy install/E2E suites are opt-in, never per-phase."
+name: "Test Economy"
+---
+
+Write the smallest test that proves the behavior: one behavior → one focused
+test, never the same coverage duplicated across suites or files.
+
+- Do NOT add E2E, full-install, or network-dependent tests unless the change
+  actually alters that end-to-end path. Prefer unit or integration tests.
+- Do not assert on copy/format strings redundantly, and do not write
+  assertions that only restate the implementation ("test the test").
+- Heavy or slow suites (e.g. real install/E2E) MUST be opt-in via a separate
+  script/tier. Never run them per edit or per phase; run only the affected
+  subset.
+- Respect a per-phase validation time budget: if a suite takes minutes,
+  justify running it and prefer the targeted subset. Reserve the full heavy
+  suites for release gates.
+- Fixing a bug: add one targeted regression test, not a broad new suite.
+- This economy rule does NOT weaken stronger gates: auth, security,
+  data-integrity, and required coverage thresholds stay mandatory.

package/src/instructions/zeus-anti-stall.instructions.md

@@ -16,18 +16,18 @@ You MUST self-monitor for these stall conditions:
 | Symptom | Detection Rule | Recovery Action |
 |---------|---------------|-----------------|
 | Silent loop | 3+ consecutive turns with no tool call AND no visible progress | Output `[STALL_DETECTED]` and re-read your task definition. If still stuck, escalate to user with: "I appear to be stuck on [task]. Options: (1) retry with different approach, (2) delegate to specialist, (3) simplify scope." |
-| Delegation black hole | Agent dispatched but no response after 2x the timeout from routing.yml | Log the hang, cancel via `cancel_task`, then follow the fallback chain in `## ⏱️ Timeout & Retry Enforcement` |
+| Delegation black hole | No result or host completion notification after the applicable timeout | Stop dependent work; do not call an unavailable cancel/status tool. Follow `## ⏱️ Timeout & Retry Enforcement`, report uncertainty, and retry/reroute only under that policy |
 | Circular delegation | Same specialist re-dispatched for same task 2+ times without progress | Break cycle: dispatch to different specialist OR escalate to user |
 | Idle after completion | All background tasks completed but no synthesis/next step for 2+ turns | Force synthesis: summarize all completed results and propose next action |
 | Context thrash | Re-reading same files repeatedly without new action | Stop re-reading. State: "Already have context on [file]. Proceeding with [action]." |
 
 ## Phase Reminder
 
-After dispatching background specialists, you MUST:
-1. DO NOT poll running jobs or consume their partial output
-2. DO NOT advance dependent work until terminal results arrive
-3. Continue orchestration ONLY on non-overlapping independent work
-4. If nothing independent remains, briefly report what was launched and WAIT
+Use the root `subagent` dispatch observed in the Beta 10 runtime; `task()` is host/API terminology, and the exact signature/background options depend on the active runtime. Prefer synchronous delegation unless the visible schema supports background and the host exposes a way to observe completion. For asynchronous work:
+1. Do not invoke `task_status`, `cancel_task`, or board methods unless a corresponding tool is actually exposed (none was exposed in the reported Beta 10 root catalog).
+2. Do not advance dependent work until a result or host-provided completion notification arrives.
+3. Continue orchestration only on non-overlapping independent work.
+4. If nothing independent remains, briefly report what was dispatched and wait for host notification; do not claim job tracking or recovery.
 
 Self-check every 3 turns: "Am I waiting on a delegate? Have I polled without need? Is there independent work I can do?"
 

package/src/instructions/zeus-council-synthesis.instructions.md

@@ -13,19 +13,18 @@ Use an inline specialist council for material trade-offs, architecture/security
 
 1. **Precedent:** Run the separate `council_decisions` search defined in `## Memory Protocol`. Apply its age/score rules; if no fast-path decision applies, continue.
 2. **Research (optional):** For `/pantheon --research <question>`, ask @apollo for a 30s pre-scan and pass findings as `shared_context` to every specialist.
-3. **Register:** Before dispatch, call `board.registerLaunch` with a council task ID, parent session, Zeus, question, and synthesis objective. This enables crash recovery.
-4. **Select and dispatch:** Choose at most 3 agents using the domain map below. Send all `task()` calls in one message. Each prompt includes the question, shared context, required response format, and role timeout (120s reviewers; 60s explorers/implementers).
-5. **Collect:** Wait for all responses and note timeouts. Partial responses are acceptable only from read-only @apollo or @gaia.
-6. **Validate confidence:** High requires at least 3 verifiable claims; otherwise downgrade to Medium and state why. Medium requires at least 1 claim; Low needs no minimum. Opinions alone are not specific claims.
-7. **Resolve divergence:** Compute agreement rate as `min(agreements, divergences) / total_points` from structured `agreement_signals`. Below 50%, and only if no agent timed out, run one rebuttal round with all responses and the current synthesis draft. Treat revised responses as final. If disagreement remains below 50%, research factual divergence points with official docs, benchmarks, or issues (max 3 searches; seek 2 independent sources per point when possible). Skip research for subjective-only disagreements. Send responses and a cited evidence brief to @themis as moderator; request verdicts, overall direction, confidence, and unresolved issues. Low confidence or unresolved points remain explicit in the synthesis. Moderator and audit roles are separate.
-8. **Synthesize and audit:** Use the output format below, then ask @themis to compare raw responses with the synthesis. Check representation of every specialist, preserved divergences, accurate attribution, and confidence specificity. Fix any issue before delivery.
-9. **Persist:** Store the decision using the `council_decisions` write format in `## Memory Protocol`, then call `board.markReconciled(task_id)`.
+3. **Select and dispatch:** Choose at most 3 agents using the domain map below. Dispatch through the root `subagent` tool observed in the Beta 10 runtime. `task()` is host/API terminology; signature, background mode, and parallel dispatch depend on the active runtime schema. Keep first-round prompts independent: do not include other specialists' responses. Dispatch in parallel when the observed tool/runtime supports it; synchronous or sequential dispatch is also valid if each first-round prompt excludes prior first-round responses. Specialists therefore cannot know actual peer positions in the first round: do not ask them to guess, signal agreement/disagreement, or refer to themselves/peers speculatively. First-round `agreement_signals` must be omitted or set to `none`.
+4. **Collect:** Use returned subagent results or host-provided completion notifications. Do not call `task_status` or claim job tracking/recovery when unavailable. Note timeouts and missing responses explicitly. Partial responses are acceptable only from read-only @apollo or @gaia.
+5. **Validate confidence:** High requires at least 3 verifiable claims; otherwise downgrade to Medium and state why. Medium requires at least 1 claim; Low needs no minimum. Opinions alone are not specific claims. Assess the claims and evidence actually present in each response; a self-reported `specific_claims` count is advisory, not evidence or proof of confidence.
+6. **Resolve divergence:** After all initial responses arrive, Zeus groups their actual substantive positions by issue and derives agreement from those positions, not from speculative or self-reported `agreement_signals`. For each comparable issue, compare every unordered pair of specialists who provided a comparable substantive position on that issue. A pair agrees only when its substantive positions are compatible; every pair whose positions are not aligned counts as divergent. For an issue with `n` specialists providing comparable positions, include `n*(n-1)/2` pairs in `total_comparable_pairs`; sum this across included issues. Exclude issues with fewer than two comparable positions and state that they were excluded. Calculate `agreement_rate = agreeing_pairs / total_comparable_pairs`: unanimity is 100%, all pairs in divergence is 0%, and non-aligned pairs are divergences. If the denominator is zero, the rate is indeterminate/has no basis; never substitute an artificial zero or trigger rebuttal from an undefined rate. Below 50%, and only if no agent timed out, run one rebuttal round with all responses and the current synthesis draft. In that round, signals may refer only to peer responses visible in the rebuttal prompt; treat revised responses as final and recompute the rate from their actual positions. If the defined rate remains below 50%, research factual divergence points with official docs, benchmarks, or issues (max 3 searches; seek 2 independent sources per point when possible). Skip research for subjective-only disagreements. Send responses and a cited evidence brief to @themis as moderator; request verdicts, overall direction, confidence, and unresolved issues. Low confidence or unresolved points remain explicit in the synthesis. Moderator and audit roles are separate.
+7. **Synthesize and audit:** Use the output format below, then ask @themis to compare raw responses with the synthesis. Check representation of every specialist, preserved divergences, accurate attribution, and confidence specificity. Fix any issue before delivery.
+8. **Persist (conditional):** Store the decision only if a memory-write tool is explicitly exposed and permitted in the active root tool list; require its success result before saying it was saved. Otherwise say the decision was not persisted. The `BackgroundJobBoard` is internal and has no root-callable board tool in the reported runtime.
 
-If context is lost, use `board.recoverRunningJobs()` and `board.formatForPrompt()` to find unreconciled work. Re-dispatch a crashed council with the same question and label it as a retry.
+The `BackgroundJobBoard` is internal bookkeeping, not a tool available to Zeus root; do not call `board.registerLaunch`, `markReconciled`, `recoverRunningJobs`, or `formatForPrompt`, and do not assume crash recovery. If context is lost, continue only from results still present in the conversation or a host handoff; otherwise report the missing context and ask how to proceed.
 
 ## Specialist Response Format
 
-Require `## specialist_response` from `## Agent Return Format`: `position`, `reasoning`, `trade_offs`, `risks`, `confidence`, `agreement_signals`, and `specific_claims`.
+Require `## specialist_response` from `## Agent Return Format`. The first round must not prompt specialists to infer other agents' views; agreement signals are omitted or `none` until actual peer responses are visible.
 
 ## Domain Map
 
@@ -53,7 +52,7 @@ Question / date / response rate / timed-out agents / precedent / research contex
 - Points shared by multiple specialists
 
 ### Divergences
-| Issue | Sides | Resolution |
+| Issue | Specialist positions (attribute each side to its agent) | Resolution |
 
 ### Evidence & Moderation (when used)
 Research points, evidence, moderator verdict, cited sources, unresolved issues
@@ -68,4 +67,4 @@ Themis approved, or issues corrected
 Confidence adjusted for response rate
 ```
 
-The user invokes this flow with `/pantheon <question>`; `--research` enables the Apollo pre-scan. Preserve actual specialist timeout or unresolved-tie details in the response.
+Initial agreement signals remain omitted/`none`; consensus and agreements are derived by Zeus from compared substantive positions and presented in the synthesis. Preserve actual specialist timeout or unresolved-tie details in the response. The user invokes this flow with `/pantheon <question>`; `--research` enables the Apollo pre-scan.

package/src/instructions/zeus-memory-operations.instructions.md

@@ -18,9 +18,13 @@ Before a council, search separately from the task-level lookup only when a past
 Use a recent, directly matching decision only after checking current context;
 otherwise treat it as background, never as authority to skip a needed review.
 
-Persist only reusable, material decisions. Use
-`key="council:<yyyy-mm-dd>:<slug>"`; JSON-stringify both `value` and
-`metadata` for `memory_store(namespace="council_decisions", ...)`. Keep the
-record concise: question, recommendation, specialists, confidence, unresolved
-trade-off, and timestamp. Do not store routine subtask summaries or status
-updates. Use the memory bank for ADRs only when explicitly requested.
+Persist only reusable, material decisions, and only if a memory-write tool is
+explicitly exposed and permitted in the active root tool list. The reported Beta
+10 Zeus root has `memory_search` but no `memory_store` grant/tool; search access
+does not imply write access. If a write tool is available, use
+`key="council:<yyyy-mm-dd>:<slug>"`, JSON-stringify both `value` and `metadata`,
+and confirm success before claiming persistence. Otherwise tell the user the
+decision was not persisted. Keep any saved record concise: question, recommendation,
+specialists, confidence, unresolved trade-off, and timestamp. Do not store routine
+subtask summaries or status updates. Use the memory bank for ADRs only when
+explicitly requested.

package/src/instructions/zeus-timeout-retry.instructions.md

@@ -9,6 +9,13 @@ fallback: shared
 
 When a delegated agent does not respond in time, enforce the timeout policy from `routing.yml`.
 
+Use the root `subagent` dispatch observed in the Beta 10 runtime. `task()` is
+host/API terminology; the active runtime determines the callable schema and any
+background options. Do not assume root `task_status`, `cancel_task`, or board
+tracking/recovery tools. Prefer synchronous dispatch unless background completion
+is observable through the host, and keep any retry list in the current context
+only; do not claim persistent job tracking.
+
 ## Timeout Behavior by Agent Role
 
 | Agent Role | Timeout | Retry Policy | Partial Results OK? | Reasoning Effort |
@@ -43,14 +50,18 @@ at most once, and an exhausted chain is never restarted automatically.
 
 For a domain/scope refusal, do not retry with a rephrased prompt. Correct the
 route once only when the right specialist is clear; otherwise stop and ask.
-Record one `DelegationCacheDecision` telemetry item for the corrected route,
-including `reroute_from`, `reroute_to`, and `delegation_id` when available.
+Record one `DelegationCacheDecision` telemetry item only when telemetry recording
+is actually exposed; otherwise keep the corrected route in the current handoff
+and do not claim telemetry was persisted. Include `reroute_from`, `reroute_to`,
+and `delegation_id` when available.
 
 ### Escalation Protocol
 When all fallbacks fail, report the tried agents and errors, offer a different approach/simpler scope/manual fix, and stop. Never retry the same chain automatically.
 
 ### Session Reuse Check
-Check for a reusable session before dispatch and obey `session_max` in `routing.yml`.
+Reuse a prior specialist session only when the active host exposes that capability;
+otherwise dispatch through `subagent` with necessary context. Treat `session_max`
+as policy context, not as a claim that Zeus can enumerate sessions.
 
 ---
 
@@ -65,19 +76,23 @@ Use the lightest path that safely meets the request. A multi-file but bounded lo
 ### Subtask Decision Tree (run BEFORE every delegation)
 
 ```
-□ Is the scope clear, bounded, and reversible?                 [YES→continue | NO→clarify/plan]
-□ Does it avoid auth/security, data/schema, and destructive risk? [YES→continue | NO→full review/gates]
-□ Is there no required Themis/audit handoff for this change?     [YES→continue | NO→preserve that review]
+□ Is the scope clear, bounded, reversible, and low-uncertainty?  [YES→continue | NO→clarify/plan]
+□ Does it avoid auth/security, data/schema, destructive, broad/material, and user-visible API risk? [YES→continue | NO→relevant gates]
+□ Is there no required Themis/audit handoff for this change?      [YES→continue | NO→preserve that review]
 
-ALL YES → direct/lightweight execution; no routine plan or artifact
+ALL YES → one correct domain specialist; they inspect needed context, implement, and verify; no routine plan/artifact, separate discovery, council, or review
 ANY NO  → add only the planning, artifact, specialist review, and approval gates the risk requires
 ```
 
 ### Safety Rules
 1. **Bounded scope** — can be a small multi-file change or a read-only investigation
-2. **Low risk** — no security implications, no data loss, no breaking changes
+2. **Low risk and uncertainty** — no security implications, data loss, breaking/user-visible API impact, broad material scope, or unresolved high uncertainty
 3. **No required Themis dependency** — sensitive/material output retains its review gate
 
+The selected specialist, not a routine Apollo discovery pass, inspects the relevant
+local context for a lightweight implementation. Keep specialist roles available for
+on-demand routing; do not remove an agent based on one task or one overhead observation.
+
 ## Subtask Return Format
 Return the required `## subtask_summary` fields defined in `## Agent Return Format`; include `memory_context` when memory was used.
 
@@ -89,4 +104,8 @@ Only agents marked ✅ in the Timeout Behavior table above may return partial re
 
 # 📊 TIMEOUT TRACKING
 
-Track in-flight delegations against the Timeout Behavior table above. Log timeouts to `/memories/session/timeout-log.md` for later analysis.
+Keep only an in-context list of active delegations and already-tried agents when
+needed. Use results returned by `subagent` or host completion notifications; do
+not poll, cancel, or write a timeout log unless the corresponding tool is exposed.
+Report any timeout and the retry/fallback taken in the user-facing handoff; do
+not claim persistent tracking or recovery.

package/src/mcp/mcp_persistence.py

@@ -914,15 +914,35 @@ def _validate_delegations(delegations: object) -> None:
 
 def _validate_tail(tail: object, payload_bytes: int | None = None) -> list[str]:
     """Validate bounded serialized tail lines."""
-    if not isinstance(tail, list) or len(tail) > MAX_TAIL_ITEMS:
-        raise ValueError("tail exceeds its size limit")
+    if not isinstance(tail, list):
+        raise ValueError("tail must be an array")
+    if len(tail) > MAX_TAIL_ITEMS:
+        raise ValueError(
+            f"tail has {len(tail)} items; maximum is {MAX_TAIL_ITEMS}; "
+            "remove tail entries or omit tail"
+        )
     for line in tail:
-        if not isinstance(line, str) or len(line.encode()) > MAX_TAIL_LINE_LENGTH:
-            raise ValueError("tail entries exceed their size limit")
+        if not isinstance(line, str):
+            raise ValueError("tail entries must be strings")
+        line_bytes = len(line.encode())
+        if line_bytes > MAX_TAIL_LINE_LENGTH:
+            raise ValueError(
+                f"tail entries are {line_bytes:,} UTF-8 bytes; maximum is "
+                f"{MAX_TAIL_LINE_LENGTH:,}; remove or shorten tail entries, "
+                "or omit tail"
+            )
     if payload_bytes is not None and payload_bytes > MAX_CONTEXT_CONTENT_BYTES:
-        raise ValueError("tail payload exceeds its size limit")
-    if sum(len(line.encode()) for line in tail) > MAX_CONTEXT_CONTENT_BYTES:
-        raise ValueError("tail payload exceeds its size limit")
+        raise ValueError(
+            f"tail payload is {payload_bytes:,} UTF-8 bytes; maximum is "
+            f"{MAX_CONTEXT_CONTENT_BYTES:,}; remove tail entries or omit tail"
+        )
+    tail_bytes = sum(len(line.encode()) for line in tail)
+    if tail_bytes > MAX_CONTEXT_CONTENT_BYTES:
+        raise ValueError(
+            f"tail contains {tail_bytes:,} UTF-8 bytes across strings; maximum "
+            f"is {MAX_CONTEXT_CONTENT_BYTES:,} bytes; remove tail entries or "
+            "omit tail"
+        )
     return tail
 
 
@@ -1020,8 +1040,14 @@ def _collect_context_content_errors(
     if not isinstance(content, str):
         errors.shape(prefix, "a string", content)
         return
-    if len(content.encode()) > MAX_CONTEXT_CONTENT_BYTES:
-        errors.add(prefix, f"exceeds the {MAX_CONTEXT_CONTENT_BYTES}-byte limit")
+    content_bytes = len(content.encode())
+    if content_bytes > MAX_CONTEXT_CONTENT_BYTES:
+        errors.add(
+            prefix,
+            f"is {content_bytes:,} UTF-8 bytes; maximum is "
+            f"{MAX_CONTEXT_CONTENT_BYTES:,} bytes. Reduce content or omit "
+            "optional tail if it contributes",
+        )
         return
     try:
         parsed = json.loads(content)
@@ -1030,11 +1056,10 @@ def _collect_context_content_errors(
         # it as a checkpoint. It is still bounded above.
         return
     if isinstance(parsed, list) and key == "tail":
-        if len(parsed) > MAX_TAIL_ITEMS or any(
-            not isinstance(line, str) or len(line.encode()) > MAX_TAIL_LINE_LENGTH
-            for line in parsed
-        ):
-            errors.add(f"{prefix}.tail", "exceeds its size limit")
+        try:
+            _validate_tail(parsed)
+        except ValueError as exc:
+            errors.reroot(prefix, str(exc))
         return
     if not isinstance(parsed, dict):
         # The message already names 'content': do not prepend the path again.
@@ -1164,6 +1189,11 @@ def _upsert_context_entry(
     name="context_save",
     description="Save a context checkpoint for a session/phase. "
     "Stores structured JSON in persistence KV with a key-specific TTL. "
+    "The serialized content is limited to 65,536 UTF-8 bytes. An included "
+    "tail may contain at most 100 strings, each at most 4,096 UTF-8 bytes, "
+    "with at most 65,536 UTF-8 bytes across all tail strings. Oversized "
+    "content or tail is rejected, never truncated; remove or omit optional "
+    "tail data when applicable. "
     "content is a JSON STRING; when it parses to an object, 'goal', 'phase', "
     "'delegations' and 'heartbeat' must each be JSON OBJECTS and 'tail' must "
     "be a JSON ARRAY. 'phase' is an object {current,total,name} — NOT a phase "
@@ -1180,7 +1210,12 @@ async def context_save(
         str,
         Field(
             description=(
-                "JSON checkpoint string. When it parses to an object, 'goal', "
+                "JSON checkpoint string, limited to 65,536 UTF-8 bytes. An "
+                "included 'tail' may contain at most 100 strings, each at "
+                "most 4,096 UTF-8 bytes, with at most 65,536 UTF-8 bytes "
+                "across all tail strings. Oversized input is rejected, never "
+                "truncated; remove or omit optional 'tail' when applicable. "
+                "When it parses to an object, 'goal', "
                 "'phase', 'delegations' and 'heartbeat' must be objects and "
                 "'tail' must be an array; all are optional. 'phase' is an "
                 "object {current,total,name}, not a counter. Example: "

package/src/pantheon/cost-command.ts

@@ -129,7 +129,7 @@ const costArgs = {
     .min(1)
     .max(365)
     .optional()
-    .describe('Number of days of delegation history to include (default 7).'),
+    .describe('Number of rolling 24-hour days of history to include (default 7).'),
 } satisfies z.ZodRawShape
 
 /** The XDG state directory every real host installation writes its ledger to. */
@@ -459,6 +459,9 @@ function renderMarkdown(query: CostQuery, days: number): string {
   const header = `## Token usage by agent and phase (last ${days} days)`
   const footer = [
     formatCoverage(coverage, days),
+    'Window: rolling 24-hour days from query time (not calendar days or session boundaries).',
+    'Aggregation: per agent and phase; phase may be unknown on V2.',
+    'Limits: not grouped by session, task, model, or provider; tokens only (no dollar costs), so this cannot establish model-specific savings or deltas.',
     `Source: opencode.db (read-only) — table families: ${coverage.sources.join(' + ')} — ${coverage.assistantRows} assistant row(s) scanned`,
   ].join('\n')
   if (rows.length === 0) {
@@ -823,7 +826,7 @@ export function createCostCommand(options?: CostCommandOptions): CostCommand {
   return {
     pantheon_cost: {
       description:
-        'Report input, output, and total token usage by agent and phase over the last N days, read from opencode.db (read-only, no monetary values). The report states the coverage window it actually covers.',
+        'Report input, output, and total token usage by agent and phase in a rolling N × 24-hour window from query time (read-only, no monetary values). It is not grouped by session, task, model, or provider; phase may be unknown on V2, so it cannot establish model-specific savings or deltas. The report states the coverage window it actually covers.',
       args: costArgs,
       execute,
     },

package/src/pantheon/model-agents.ts

@@ -0,0 +1,19 @@
+/** Canonical agent IDs shared by model routing and V2 override validation. */
+export const KNOWN_AGENTS = [
+  'zeus',
+  'athena',
+  'apollo',
+  'hermes',
+  'aphrodite',
+  'demeter',
+  'themis',
+  'prometheus',
+  'hephaestus',
+  'nyx',
+  'gaia',
+  'iris',
+  'mnemosyne',
+  'talos',
+] as const
+
+export type KnownAgent = (typeof KNOWN_AGENTS)[number]