Skip to content

Product Book Watchdog

Grzegorz Nowak edited this page Oct 12, 2026 · 7 revisions

Context Awareness — Advisory Pressure & the Primacy Zone

Part of the Product Book. Observable product behaviour at pi-schematic @ 36bd569 (main, 2026-10-12).

Pi is a coding-agent harness; pi-schematic is an extension that adds context-management primitives. A coding agent works inside a context window — the fixed budget of tokens the model can consider at once — and pi-schematic treats roughly the first 30% as the primacy zone, the region the model uses most reliably. Because agents can degrade well before the window is full, the system keeps telling the agent how much pressure it is under, so it can decide when to delegate, hand off, or continue.

1. Why the pressure is advisory

Coding agents can degrade as the context grows, often far from the token limit; pi-schematic calls roughly the first 30% of the window the practical primacy zone (PB-WATCHDOG-01). The pressure bands and the high-usage warning exist to make that degradation visible early; they are awareness aids, not an automatic compaction mechanism, and the agent chooses whether to delegate work to a child agent (spawn) or carry the work into a fresh context (**handoff) (PB-WATCHDOG-02`).

A handoff ends the current context and starts a fresh one with a written instruction; a spawn is a child agent that receives isolated work and returns a condensed result. The watchdog suggests both and performs neither.

2. The 30% / 50% / 70% bands

Usage is divided into three bands, with one reminder as the agent enters each. At 30–49% the reminder opens Context at <rounded>% — choose your next step by topic fit.; at 50–69%, Context at <rounded>% — topic discipline matters now.; at 70% or higher, Context at <rounded>% — topic discipline is urgent. (PB-WATCHDOG-04 through PB-WATCHDOG-06). What changes across the bands is urgency: the documented intent is a primacy-zone reminder at 30–49%, advice to consider handoff soon at 50–69%, and a warning that automatic compaction may trigger soon at 70%+ (PB-WATCHDOG-07 through PB-WATCHDOG-09).

The watchdog throttles ordinary reminders to one delivery on entry into each band, so it does not nag the agent every turn (PB-WATCHDOG-10). Returning below 30% clears the remembered band, allowing a later re-entry to remind again (PB-WATCHDOG-11); with no pending boundary hint or requested handoff, ordinary reminders are omitted when usage is unavailable or below 30% (PB-WATCHDOG-03). pi-schematic appends each reminder as a custom message of type pi-schematic-watchdog with display: false, reaching the model without appearing in the visible conversation (PB-WATCHDOG-12).

3. The same pressure in the interface

The status bar shows the same measurement as a rounded ctx <percent>%, tinted dim below 30%, accent for 30–49%, warning for 50–69%, and error at 70% or above; a missing, negative, non-finite, or otherwise malformed percentage renders as ctx --% (PB-WATCHDOG-14, PB-WATCHDOG-15). Finite non-negative percentages are accepted with no 100% cap, so overflow stays displayable (PB-WATCHDOG-16).

At 70% or higher valid usage a warning widget appears above the editor, and its wording adapts: with a topic it says same topic → spawn, different topic → handoff; with no topic it says to hand off soon unless a topic can be assigned cleanly; in readonly it uses readonly-specific wording, where the different-topic path is the readonly handoff trigger (PB-WATCHDOG-17 through PB-WATCHDOG-20). Each agent_end records the latest valid percentage, or null when usage is unavailable or malformed (PB-WATCHDOG-13).

4. Advice that follows the active topic

The reminder is not generic. The active notebook topic is the short label naming the session's current high-level frame; when set, the reminder names it as the current semantic frame (PB-WATCHDOG-21). If the work still fits, isolated noisy subtasks are directed to spawn (PB-WATCHDOG-22); if it no longer fits, the reminder prefers a deliberate handoff when eligible, otherwise continued work until handoff is available (PB-WATCHDOG-23). With no topic, it asks the agent to assign a short stable topic, and at urgent usage either assigns one in the next clean context or now, according to handoff eligibility (PB-WATCHDOG-24).

A pending topic change overrides the default and names the old and new topics, calling the change a strong task-boundary signal (PB-WATCHDOG-25). It recommends handoff when eligible but stays advisory while context is not ready (PB-WATCHDOG-26), and explicitly permits continuing inline when the change was only a rename rather than a real pivot (PB-WATCHDOG-27). The watchdog neither suppresses boundary guidance below 30% nor band-throttles it (PB-WATCHDOG-28).

5. Readonly posture

Readonly is a guard mode in which the agent may research and plan but not edit. Changing readonly posture creates a one-shot hidden pi-schematic-readonly-nudge so the model receives its current constraints (PB-WATCHDOG-29). While readonly is active with neither a pending handoff nor a topic boundary, the watchdog suppresses regular reminders rather than repeating them; visibility then comes from the toggle nudge and blocked tool calls (PB-WATCHDOG-30). A human-set topic boundary is the exception: when eligible it activates the same temporary handoff exception as an explicit /handoff, and the interface warns that the handoff must complete before normal work continues (PB-WATCHDOG-31). While ineligible it stays advisory and is retained, not promoted, until context becomes handoff-eligible (PB-WATCHDOG-32). Handoff eligibility is reached only at 30,000 measured or estimated tokens (PB-WATCHDOG-33).

6. What is injected before a run starts

Before each agent start, pi-schematic appends the context-management primer to the system prompt (PB-WATCHDOG-34). It teaches "one context, one topic" and to hand off when an ask no longer matches the topic; a planning choice between delegating substantial same-topic work with spawn and preferring handoff when the work no longer fits; that child agents isolate noise and return condensed results, preserving the parent as orchestrator; and the notebook as a two-tier work-stream cache that discards recoverable code facts while keeping refreshed guidance, decisions, design, scope, and working memory (PB-WATCHDOG-35 through PB-WATCHDOG-38). It directs the agent to scan the notebook index and read only relevant pages rather than pre-loading bodies, and makes the active topic the semantic frame: same-topic work biases to spawn, a different topic to handoff (PB-WATCHDOG-39, PB-WATCHDOG-40).

Generated sections follow. ## Active Notebook Topic identifies the topic and its source, treats a missing topic as a prompt to establish one, and marks human-set topics authoritative (PB-WATCHDOG-41). ## Active Notebook Pages lists page names in sorted order with a preview capped at the first 80 characters of the first line, and directs the agent to fetch pages by notebook_read rather than pasting page bodies (PB-WATCHDOG-44, PB-WATCHDOG-45). When Model Groups exist, pi-schematic lists their names and effective modalities but withholds membership, thinking level, authentication, validation, and storage details; the agent must use an explicitly requested known group exactly rather than substitute another (PB-WATCHDOG-42, PB-WATCHDOG-43).

7. Limits and edge cases

The ordinary bands inject advice and nothing more — no automatic compaction, no tool call. The readonly human boundary is the one exception that creates a temporary handoff path once the 30,000-token threshold is met. Usage is rounded for copy and status rendering; invalid percentages produce no ordinary low-usage reminder and show ctx --%, while valid values above 100% are retained rather than capped. The live notebook listing intentionally shows a short first-line preview, not a full page body.

Known gaps / open questions (not baseline rows)

  • Gap — 70% message mismatch: the changelog says the 70%+ tier warns that automatic compaction may trigger soon (CHANGELOG.md:161-162), but the current generated default nudge says only that topic discipline is urgent (watchdog.ts:63-72).

Appendix — baseline behaviour rows

PB-WATCHDOG-01 … 45 — 45 atomic behaviour rows

1. Pressure bands and visible context state

ID Behaviour Evidence
PB-WATCHDOG-01 The product treats roughly the first 30% of a context window as the practical “primacy zone,” because performance can degrade before the token limit is reached. docs/why.md:5
PB-WATCHDOG-02 Pressure bands and the high-usage warning are awareness aids, not an automatic compaction mechanism: the agent chooses whether to spawn or hand off. docs/why.md:42-44
PB-WATCHDOG-03 With no pending topic-boundary hint or requested handoff, ordinary watchdog reminders are omitted when usage is unavailable or below 30%. index.ts:890-897
PB-WATCHDOG-04 At 30–49% usage, the default reminder opens with Context at <rounded>% — choose your next step by topic fit. watchdog.ts:63-72
PB-WATCHDOG-05 At 50–69% usage, the default reminder opens with Context at <rounded>% — topic discipline matters now. watchdog.ts:63-72
PB-WATCHDOG-06 At 70% or higher, the default reminder opens with Context at <rounded>% — topic discipline is urgent. watchdog.ts:63-72
PB-WATCHDOG-07 The documented intent of the 30–49% tier is a primacy-zone reminder. CHANGELOG.md:161-162
PB-WATCHDOG-08 The documented intent of the 50–69% tier is to consider handoff soon. CHANGELOG.md:161-162
PB-WATCHDOG-09 The documented intent of the 70%+ tier is to warn that automatic compaction may trigger soon. CHANGELOG.md:161-162
PB-WATCHDOG-10 Ordinary reminders are throttled to one delivery on entry into each band: 30–49%, 50–69%, and 70%+. index.ts:900-909
PB-WATCHDOG-11 Returning below 30% clears the remembered watchdog band, allowing a later re-entry to receive a reminder. index.ts:890-897
PB-WATCHDOG-12 A delivered watchdog reminder is appended as a custom message of type pi-schematic-watchdog with display: false; it reaches the LLM without appearing in the visible conversation. index.ts:911-922
PB-WATCHDOG-13 Each agent_end records the latest valid context percentage; unavailable or malformed usage records null instead. watchdog.ts:127-138
PB-WATCHDOG-14 The status bar shows rounded ctx <percent>% with dim, accent, warning, and error tones for <30%, 30–49%, 50–69%, and >=70%, respectively. tui.ts:39-46
PB-WATCHDOG-15 A missing, negative, non-finite, or otherwise malformed context percentage renders as ctx --%. handoff/eligibility.ts:14-18; tui.ts:39-48
PB-WATCHDOG-16 Finite non-negative percentages are accepted without a 100% cap, so overflow usage remains displayable. handoff/eligibility.ts:14-18
PB-WATCHDOG-17 At >=70% valid usage, the TUI shows an above-editor warning widget; below 70% or with invalid usage, it removes that widget. tui.ts:71-84
PB-WATCHDOG-18 The high-usage widget tells an agent with an active topic: same topic → spawn; different topic → handoff. tui.ts:74-79
PB-WATCHDOG-19 The high-usage widget tells an agent with no topic to hand off soon unless it can assign a topic cleanly. tui.ts:77-79
PB-WATCHDOG-20 The high-usage widget switches to readonly-specific wording: same topic → spawn; different topic → the readonly handoff trigger. tui.ts:74-76

2. Topic and readonly-aware advice

ID Behaviour Evidence
PB-WATCHDOG-21 With an active notebook topic, a default reminder names that topic as the current semantic frame. watchdog.ts:75-82
PB-WATCHDOG-22 For work that still fits the active topic, the default reminder directs isolated noisy subtasks to spawn. watchdog.ts:75-82
PB-WATCHDOG-23 For work that no longer fits the active topic, the default reminder prefers a deliberate handoff when eligible, otherwise continued work until handoff is available. watchdog.ts:73-82
PB-WATCHDOG-24 With no active topic, the reminder asks the agent to assign a short stable topic; at urgent usage it either assigns one in the next clean context or now, according to handoff eligibility. watchdog.ts:84-91
PB-WATCHDOG-25 A pending topic change replaces the default reminder with one that names the old and new topics and calls the change a strong task-boundary signal. watchdog.ts:52-59; watchdog.ts:94-99
PB-WATCHDOG-26 A topic-boundary reminder recommends a handoff when eligible, but says it remains advisory while context is not ready. watchdog.ts:52-59
PB-WATCHDOG-27 A topic-boundary reminder explicitly permits continuing inline when the change was only a rename, not a real pivot. watchdog.ts:57-59
PB-WATCHDOG-28 Pending topic-boundary guidance is not suppressed below 30% or by ordinary band throttling. index.ts:890-909
PB-WATCHDOG-29 Changing readonly posture creates a one-shot, hidden pi-schematic-readonly-nudge so the LLM receives its current readonly constraints. index.ts:825-846
PB-WATCHDOG-30 In readonly mode with neither a pending handoff nor a topic boundary, regular watchdog reminders are suppressed rather than repeated. index.ts:849-873
PB-WATCHDOG-31 In readonly mode, an eligible human-set topic boundary activates the same temporary handoff exception as an explicit /handoff, and the UI warns that the handoff must be completed before normal work continues. readonly-boundary.ts:18-25; readonly-boundary.ts:34-48; notifications.ts:83-85
PB-WATCHDOG-32 An ineligible human topic boundary in readonly mode remains advisory and is retained for later promotion; it is not promoted until context is handoff-eligible. index.ts:854-869; state.ts:30-35
PB-WATCHDOG-33 A handoff is eligible only when measured or estimated context reaches 30,000 tokens. handoff/eligibility.ts:1-2; handoff/eligibility.ts:36-39

3. The teaching surface injected before an agent starts

ID Behaviour Evidence
PB-WATCHDOG-34 Before each agent start, pi-schematic appends its context-management primer to the system prompt. index.ts:754-769
PB-WATCHDOG-35 The primer teaches “one context, one topic” and says to hand off when an ask no longer matches the topic. system-prompt.ts:8-12
PB-WATCHDOG-36 The primer teaches a planning choice: delegate substantial same-topic work with spawn; prefer handoff when the work no longer fits the topic. system-prompt.ts:13-19
PB-WATCHDOG-37 The primer teaches that child agents isolate noise and return condensed results, preserving the parent as an orchestrator. system-prompt.ts:25-29
PB-WATCHDOG-38 The primer defines the notebook as a two-tier, work-stream cache: discard recoverable code facts and keep refreshed guidance, decisions, design, scope, and working memory. system-prompt.ts:31-36
PB-WATCHDOG-39 The primer directs the agent to use notebook_index and then notebook_read only for relevant pages, rather than pre-loading notebook bodies. system-prompt.ts:38-45
PB-WATCHDOG-40 The primer makes the active topic the semantic frame: same-topic work biases to spawn and a different topic biases to handoff. system-prompt.ts:47-51
PB-WATCHDOG-41 The injected active-topic section identifies the topic and its source, and treats a missing topic as a prompt to establish one; human-set topics are authoritative. index.ts:774-784
PB-WATCHDOG-42 When Model Groups exist, the system prompt lists each group’s name and effective modalities/constraints, but explicitly withholds provider/model membership, thinking level, authentication, validation, and storage details. index.ts:457-464
PB-WATCHDOG-43 Model Group guidance tells the agent to use an explicitly requested known group exactly, to pass required capabilities, and not to substitute another group if the requested group lacks them. index.ts:460-464
PB-WATCHDOG-44 When notebook pages exist, the system prompt lists them in sorted order with each name and a preview capped at 80 characters of its first line. index.ts:791-802
PB-WATCHDOG-45 The notebook listing directs the agent to fetch pages by notebook_read and never paste page bodies into prompts; full bodies are not inlined. index.ts:803-806

Clone this wiki locally