pantheon-opencode 1.6.0-beta.7 → 1.6.0-beta.9

package/src/plugins/tui/package.json

@@ -1,19 +1,23 @@
 {
   "name": "pantheon-tui",
   "type": "module",
-  "version": "1.6.0-beta.7",
-  "description": "Pantheon TUI plugin — sidebar (version, preset, sessions, real-time delegations) + AI subscription usage gauges incl. OpenCode Go/Zen dollar limits (vendored, MIT)",
+  "version": "1.6.0-beta.9",
+  "description": "Pantheon TUI plugin — V1 rich sidebar and usage gauges; native V2 status, session and delegation sidebar",
   "license": "MIT",
   "engines": {
     "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
   },
   "exports": {
     "./tui": "./dist/tui.js",
+    "./tui-v2": "./dist/tui-v2.js",
     "./server": "./dist/server.js"
   },
   "files": [
     "dist",
-    "src"
+    "src",
+    "tui.ts",
+    "tui-v2.ts",
+    "index-v2.ts"
   ],
   "scripts": {
     "build": "tsdown",
@@ -22,8 +26,6 @@
   "peerDependencies": {
     "@opencode-ai/plugin": "1.18.33",
     "@opencode-ai/sdk": "1.18.33",
-    "@opentui/core": "0.5.10",
-    "@opentui/solid": "0.5.10",
     "solid-js": "1.9.12"
   },
   "devDependencies": {
@@ -39,8 +41,9 @@
   "//overrides": "TUI production advisory fixes: Babel >=7.29.6 and Seroval >=1.6.3; Solid stays at 1.9.12 to satisfy OpenTUI's exact peer. Remove only after upstream ranges include fixed versions; Seroval compatibility is covered by the Solid serializer regression test.",
   "dependencies": {
     "@opencode-ai/plugin": "1.18.33",
-    "@opentui/core": "0.5.10",
-    "@opentui/solid": "0.5.10",
+    "@opencode/plugin": "2.0.26",
+    "@opentui/core": "0.5.17",
+    "@opentui/solid": "0.5.17",
     "solid-js": "1.9.12"
   }
 }

package/src/plugins/tui/src/index-v2.tsx

@@ -0,0 +1,108 @@
+// biome-ignore-all lint/suspicious/noExplicitAny: OpenCode V2 exposes its TUI API at runtime.
+/** @jsxImportSource @opentui/solid */
+
+import { Plugin } from '@opencode/plugin/tui'
+import { createMemo, createSignal, For, onCleanup, onMount, Show } from 'solid-js'
+
+const SINGLETON = Symbol.for('pantheon.tui.v2.loaded')
+
+function Sidebar(props: { context: any; sessionID?: string }) {
+  const { context } = props
+  const [revision, setRevision] = createSignal(0)
+  const location = context.location ?? context.data.location.default()
+
+  const session = createMemo(() => {
+    revision()
+    return props.sessionID ? context.data.session.get(props.sessionID) : undefined
+  })
+  const branch = createMemo(() => {
+    revision()
+    const info = context.data.location.vcs.info(location)
+    return info?.branch?.current ?? null
+  })
+  const delegations = createMemo(() => {
+    revision()
+    const id = props.sessionID
+    if (!id) return []
+    const family: string[] = context.data.session.family(id) ?? []
+    return family
+      .filter((childID) => childID !== id)
+      .map((childID) => context.data.session.get(childID))
+      .filter((child: any) => child?.parentID === id)
+      .slice(0, 6)
+  })
+
+  onMount(() => {
+    const stop: Array<() => void> = []
+    for (const type of [
+      'session.created',
+      'session.updated',
+      'session.status',
+      'session.deleted',
+    ]) {
+      try {
+        stop.push(context.data.on(type, () => setRevision((value) => value + 1)))
+      } catch {
+        // Sidebar remains useful with the initial cached state if an event is unavailable.
+      }
+    }
+    if (props.sessionID) {
+      void context.data.session.sync(props.sessionID).then(() => setRevision((value) => value + 1))
+    }
+    void context.data.location.vcs.sync(location).then(() => setRevision((value) => value + 1))
+    onCleanup(() => {
+      for (const unsubscribe of stop) unsubscribe()
+    })
+  })
+
+  const text = () => context.theme.text?.base
+  const muted = () => context.theme.text?.muted ?? text()
+
+  return (
+    <box flexDirection="column" width="100%" padding={1}>
+      <text fg={text()} attributes={1}>{`Pantheon v${__PANTHEON_VERSION__}`}</text>
+      <text fg={muted()}>OpenCode V2 · plugin TUI ativo</text>
+      <Show when={branch()}>{(value) => <text fg={muted()}>{`Branch: ${value()}`}</text>}</Show>
+      <Show when={session()} fallback={<text fg={muted()}>Nenhuma sessão selecionada</text>}>
+        {(current) => (
+          <>
+            <text fg={text()}>{`Sessão: ${current().title || current().id}`}</text>
+            <Show when={current().agent}>
+              <text fg={muted()}>{`Agente: ${current().agent}`}</text>
+            </Show>
+          </>
+        )}
+      </Show>
+      <Show when={delegations().length > 0}>
+        <text fg={text()} attributes={1}>
+          Delegações
+        </text>
+        <For each={delegations()}>
+          {(child: any) => <text fg={muted()}>{`· ${child.title || child.id}`}</text>}
+        </For>
+      </Show>
+    </box>
+  )
+}
+
+const plugin = Plugin.define({
+  id: 'pantheon.tui',
+  setup(context: any) {
+    const globalState = globalThis as unknown as Record<PropertyKey, unknown>
+    if (globalState[SINGLETON]) return
+    globalState[SINGLETON] = true
+
+    const unregister = context.ui.slot({
+      append: 'sidebar.content',
+      render: ({ sessionID }: { sessionID?: string }) => (
+        <Sidebar context={context} sessionID={sessionID} />
+      ),
+    })
+    return () => {
+      if (typeof unregister === 'function') unregister()
+      delete globalState[SINGLETON]
+    }
+  },
+})
+
+export default plugin

package/src/plugins/tui/src/index.tsx

@@ -5,9 +5,9 @@
 /**
  * pantheon-tui — Pantheon TUI plugin for opencode.
  *
- * Bundled entry: `tsdown` emits `dist/tui.js`, and the package `exports`
- * (`./tui` → ./dist/tui.js, `./server` → ./dist/server.js) is the ONLY load
- * path — no raw TSX copy is shipped. Because the bundle inlines relative
+ * V1 bundle: `tsdown` emits `dist/tui.js`, re-exported by root `tui.ts`.
+ * OpenCode V2 uses the separate `src/index-v2.tsx` entry and native CLI plugin
+ * API. No raw TSX implementation is shipped. Because the bundle inlines relative
  * imports, this entry may be split into modules without breaking the loader.
  *
  * Slots:
@@ -740,27 +740,12 @@ async function loadConfig(configPath: string | undefined): Promise<UsageBarConfi
   }
 }
 
-/** Vendored usage-bar plugin init: reads config, seeds the kv cache, registers
- *  the `app_bottom` slot, then starts the poll loop. Skips everything (and
+/** Vendored usage-bar plugin init: reads config, seeds the kv cache, starts
+ *  the poll loop and registers the `app_bottom` slot. Skips everything (and
  *  registers nothing) when no provider is enabled — mirrors the standalone
  *  plugin's early return. */
 async function setupUsageBar(api: TuiPluginApi) {
-  let disposed = false
-  let clockInterval: ReturnType<typeof setInterval> | undefined
-  const pollTimeouts = new Set<ReturnType<typeof setTimeout>>()
-
-  // This optional feature owns timers independently from the sidebar. A slow
-  // config read may finish after shutdown, so register cleanup before awaiting
-  // anything and check the disposed flag at every async boundary.
-  api.lifecycle.onDispose(() => {
-    disposed = true
-    if (clockInterval !== undefined) clearInterval(clockInterval)
-    for (const timeout of pollTimeouts) clearTimeout(timeout)
-    pollTimeouts.clear()
-  })
-
   const config = await loadConfig(api.state.path?.config)
-  if (disposed) return
   if (api.state.path?.state) opencodeAuthFile = join(api.state.path.state, 'auth.json')
 
   const enabled = providers.filter((p) => config.providers[p.id].enabled)
@@ -777,6 +762,28 @@ async function setupUsageBar(api: TuiPluginApi) {
   const [byStatus, setByStatus] = createSignal<Record<string, StatusIndicator>>({})
   const [now, setNow] = createSignal(Date.now())
 
+  setInterval(() => setNow(Date.now()), 1_000)
+
+  for (const p of enabled) {
+    const cfg = config.providers[p.id]
+    const poll = async () => {
+      // Fetch usage and status concurrently; status pages are CDN-backed and
+      // never throttle, so we poll them on the same cadence as usage.
+      const statusP = config.showStatus && p.statusUrl ? fetchStatus(p.statusUrl) : null
+      const [all, status] = await Promise.all([p.fetchUsage(cfg), statusP])
+      if (all) {
+        const windows = all.filter((w) => cfg.show[w.category] && w.resetsAt > Date.now())
+        setByProvider((prev) => ({ ...prev, [p.id]: windows }))
+        api.kv.set(`usage-bar.${p.id}.windows`, windows)
+      }
+      // `null` means the status fetch failed — keep the last known indicator.
+      if (status !== null) setByStatus((prev) => ({ ...prev, [p.id]: status }))
+      // Back off when the usage fetch failed (e.g. 429 — these endpoints throttle).
+      setTimeout(poll, all ? POLL_MS : POLL_MS * 3)
+    }
+    void poll()
+  }
+
   api.slots.register({
     order: 60,
     slots: {
@@ -864,46 +871,6 @@ async function setupUsageBar(api: TuiPluginApi) {
       },
     },
   })
-
-  // Start background work only once the optional UI slot was accepted. If
-  // registration fails, the outer fail-open handler can suppress it without
-  // leaving a timer or provider request running in the background.
-  clockInterval = setInterval(() => setNow(Date.now()), 1_000)
-
-  const schedulePoll = (run: () => void, delay: number) => {
-    if (disposed) return
-    const timeout = setTimeout(() => {
-      pollTimeouts.delete(timeout)
-      if (!disposed) run()
-    }, delay)
-    pollTimeouts.add(timeout)
-  }
-
-  for (const p of enabled) {
-    const cfg = config.providers[p.id]
-    const poll = async () => {
-      if (disposed) return
-      // Fetch usage and status concurrently; status pages are CDN-backed and
-      // never throttle, so we poll them on the same cadence as usage.
-      const statusP = config.showStatus && p.statusUrl ? fetchStatus(p.statusUrl) : null
-      const [all, status] = await Promise.all([p.fetchUsage(cfg), statusP])
-      if (disposed) return
-      if (all) {
-        const windows = all.filter((w) => cfg.show[w.category] && w.resetsAt > Date.now())
-        setByProvider((prev) => ({ ...prev, [p.id]: windows }))
-        api.kv.set(`usage-bar.${p.id}.windows`, windows)
-      }
-      // `null` means the status fetch failed — keep the last known indicator.
-      if (status !== null) setByStatus((prev) => ({ ...prev, [p.id]: status }))
-      // Back off when the usage fetch failed (e.g. 429 — these endpoints throttle).
-      schedulePoll(runPoll, all ? POLL_MS : POLL_MS * 3)
-    }
-    const runPoll = () => {
-      if (disposed) return
-      void poll().catch(() => schedulePoll(runPoll, POLL_MS * 3))
-    }
-    runPoll()
-  }
 }
 
 /* ─── Delegations (real-time panel) ────────────────────────
@@ -3167,9 +3134,7 @@ const tui: TuiPlugin = (api, _options, _meta) => {
     .catch(() => setVersion(null))
 
   // Vendored feature (MIT): AI subscription usage gauges.
-  // Usage indicators are optional: a config, storage, or slot failure must
-  // never turn an otherwise healthy TUI startup into an unhandled rejection.
-  void setupUsageBar(api).catch(() => undefined)
+  void setupUsageBar(api) // async init — never blocks sidebar registration
 
   // ── Live delegation store (tool-part tracker + sidebar invalidation) ──
   // The Delegations panel's PRIMARY source is `api.client.session.children`

package/src/plugins/tui/src/opencode-v2.d.ts

@@ -0,0 +1,13 @@
+declare module '@opencode/plugin/tui' {
+  export const Plugin: {
+    define<T>(plugin: T): T
+  }
+}
+
+declare module '@opencode/plugin' {
+  export const Plugin: {
+    define<T>(plugin: T): T
+  }
+}
+
+declare const __PANTHEON_VERSION__: string

package/src/plugins/tui/tsdown.config.ts

@@ -26,7 +26,7 @@ async function ensureDistArtifactsEndWithNewline(): Promise<void> {
 }
 
 export default defineConfig({
-  entry: { tui: 'src/index.tsx', server: 'src/server.ts' },
+  entry: { tui: 'src/index.tsx', 'tui-v2': 'src/index-v2.tsx', server: 'src/server.ts' },
   format: ['esm'],
   platform: 'node',
   outDir: 'dist',
@@ -47,7 +47,7 @@ export default defineConfig({
     }),
   ],
   deps: {
-    neverBundle: [/^@opencode-ai\//, /^@opentui\//, /^solid-js/],
+    neverBundle: [/^@opencode-ai\//, /^@opencode\//, /^@opentui\//, /^solid-js/],
   },
   onSuccess: ensureDistArtifactsEndWithNewline,
 })

package/src/plugins/tui/tui-v2.ts

@@ -0,0 +1,2 @@
+// OpenCode V2's CLI loader resolves this root-level TUI entrypoint.
+export { default } from './dist/tui-v2.js'

package/src/plugins/tui/tui.ts

@@ -0,0 +1,3 @@
+// OpenCode V1 compatibility entrypoint. The V2 installer copies tui-v2.ts as
+// the installed root tui.ts instead.
+export { default } from './dist/tui.js'

package/src/routing.yml

@@ -133,7 +133,7 @@ agents:
     - artifact-management
     - context-compression
     - auto-continue
-    - council-synthesis
+    - incremental-implementation
   athena:
     role: Strategic planner
     reasoning_effort: high
@@ -188,6 +188,8 @@ agents:
     - pantheon_code_mode
     skills:
     - tdd-with-agents
+    - file-prompts
+    - streaming-patterns
     - git-workflow-and-versioning
     - incremental-implementation
   aphrodite:
@@ -209,7 +211,7 @@ agents:
     skills:
     - tdd-with-agents
     - visual-review-pipeline
-    - incremental-implementation
+    - file-prompts
   demeter:
     role: Database specialist
     reasoning_effort: medium

package/src/skills/README.md

@@ -4,14 +4,14 @@
 
 Skills are reference modules loaded on demand by agents. Each skill provides domain-specific knowledge — architecture patterns, security checklists, optimization strategies, and implementation guides. Agents load skills when their task matches the skill's description, keeping context focused and token-efficient.
 
-There are **21 skills** divided into **5 domains**.
+There are **20 skills** divided into **5 domains**.
 
 ## Skills by Domain
 
 ### Domain 1: Orchestration & Workflow
 
 1. **agent-coordination** — `agent-coordination/SKILL.md`
-   - Lightweight coordination for substantial tasks with multiple independent specialists.
+   - Multi-agent orchestration with model routing, category delegation, and sprint management.
    - Used by: Zeus
 
 2. **artifact-management** — `artifact-management/SKILL.md`
@@ -23,8 +23,8 @@ There are **21 skills** divided into **5 domains**.
    - Used by: Zeus, Apollo, Hephaestus, Nyx, Gaia
 
 4. **context-compression** — `context-compression/SKILL.md`
-   - Level 2 — Pantheon-native context compression with priority scoring, semantic summarization, budget allocation, and cross-references.
-   - Used by: Zeus, Mnemosyne, Themis
+   - Native compaction guidance and explicit checkpoint rules; no automatic compression MCP calls.
+   - Used by: Zeus, Mnemosyne
 
 5. **memory-bank** — `memory-bank/SKILL.md`
    - Memory bank rules, structure, and optimization — complete guide to Pantheon memory management.
@@ -34,10 +34,6 @@ There are **21 skills** divided into **5 domains**.
    - Pin session objectives to prevent scope creep across long multi-agent sessions.
    - Used by: Zeus, Mnemosyne
 
-- **council-synthesis** — `council-synthesis/SKILL.md`
-  - Full structured council workflow, loaded only for `/pantheon` or a material multi-perspective decision.
-  - Used by: Zeus
-
 ### Domain 2: Development Tools
 
 7. **clonedeps** — `clonedeps/SKILL.md`
@@ -50,7 +46,7 @@ There are **21 skills** divided into **5 domains**.
 
 9. **incremental-implementation** — `incremental-implementation/SKILL.md`
     - Implement in thin vertical slices — one commit per task, testable, rollback-safe.
-    - Used by: Hermes, Aphrodite, Demeter, Prometheus, Talos
+    - Used by: Zeus, Hermes, Aphrodite, Demeter, Prometheus, Talos
 
 10. **loop-engineering** — `loop-engineering/SKILL.md`
     - Iterative refinement pattern for complex problems — solve, review, improve, repeat in controlled cycles.
@@ -128,12 +124,12 @@ The `SKILL.md` file contains YAML frontmatter with `name`, `description`, and pl
 | 1 | agent-coordination | Orchestration & Workflow | Zeus |
 | 2 | artifact-management | Orchestration & Workflow | Zeus, Mnemosyne, Iris |
 | 3 | auto-continue | Orchestration & Workflow | Zeus, Apollo, Hephaestus, Nyx, Gaia |
-| 4 | context-compression | Orchestration & Workflow | Zeus, Mnemosyne, Themis |
+| 4 | context-compression | Orchestration & Workflow | Zeus, Mnemosyne |
 | 5 | memory-bank | Orchestration & Workflow | Mnemosyne, Athena |
 | 6 | session-goal | Orchestration & Workflow | Zeus, Mnemosyne |
 | 7 | clonedeps | Development Tools | Hermes, Hephaestus |
 | 8 | git-workflow-and-versioning | Development Tools | Hermes, Prometheus, Iris |
-| 9 | incremental-implementation | Development Tools | Hermes, Aphrodite, Demeter, Prometheus, Talos |
+| 9 | incremental-implementation | Development Tools | Zeus, Hermes, Aphrodite, Demeter, Prometheus, Talos |
 | 10 | loop-engineering | Development Tools | All agents |
 | 11 | reflect | Development Tools | All agents |
 | 12 | simplify | Development Tools | All agents |
@@ -145,7 +141,6 @@ The `SKILL.md` file contains YAML frontmatter with `name`, `description`, and pl
 | 18 | spec-driven-development | Planning | Athena |
 | 19 | verification-planning | Planning | Athena, Zeus |
 | 20 | visual-review-pipeline | Frontend Development | Aphrodite |
-| 21 | council-synthesis | Orchestration & Workflow | Zeus |
 
 ---
 

package/src/skills/agent-coordination/SKILL.md

@@ -1,25 +1,95 @@
 ---
 name: agent-coordination
-description: "Coordinate two or more specialists for substantial multi-phase work. Skip for questions, bounded fixes, and one-agent tasks."
+description: "Multi-agent orchestration with model routing, category delegation, and sprint management. Use for coordinating Pantheon agents."
 context: fork
 globs: []
 alwaysApply: false
 ---
 
-# Agent coordination
+# Agent Coordination
 
-Load only when the work genuinely needs multiple specialists or dependent phases. For the default routing, retry, and safety rules, follow Zeus and `pantheon://routing`.
+Master guide to orchestrating the multi-agent system. Includes category routing, model selection, and sprint management for rapid, TDD-driven feature development.
 
-## Lean coordination
+---
+
+## Agent Hierarchy
+
+See `AGENTS.md` for the full agent table.
+
+---
+
+## Category Routing
+
+Route tasks to optimized agents based on category instead of specifying agents manually:
+
+| Category | Agent | Use For |
+|----------|-------|---------|
+| **Deep** | Athena, Hephaestus | Complex planning, AI pipelines |
+| **Quick** | Talos, Apollo | Fast fixes, codebase search |
+| **Ultrabrain** | Zeus | Multi-agent orchestration, model routing |
+
+---
+
+## Sprint Workflow
+
+```
+1. User describes feature
+2. @athena creates PLAN with phases and agents
+3. User approves PLAN (GATE 1)
+4. Zeus dispatches agents to phases (parallel when possible)
+5. Each agent: TDD cycle → writes IMPL artifact
+6. @themis reviews all phases (GATE 2)
+7. User reviews Themis findings
+8. If approved → user commits (GATE 3)
+9. @mnemosyne updates memory bank
+```
+
+---
+
+## Parallel Execution Declaration
 
-1. State the desired outcome and split only work with distinct ownership or dependencies. Ask @athena to plan only when scope, architecture, or acceptance criteria are materially unclear.
-2. Assign each bounded task to the most specific configured specialist. Include relevant context, expected result, and focused verification; do not make @apollo rediscover context the implementer can inspect directly.
-3. Dispatch independent tasks together only when native background delegation is enabled. Otherwise use normal `task()` calls. Do not create waves for a single task or poll without a returned task ID.
-4. Collect summaries once, resolve dependencies, and report evidence, remaining risk, and blockers. Add @themis, artifacts, or user approval only where the task's risk or requested workflow requires them.
+```
+🔀 PARALLEL EXECUTION — Phase 2
+Running simultaneously:
+- @hermes   → backend tests   → .tmp/IMPL-phase2-hermes.md
+- @aphrodite → frontend       → .tmp/IMPL-phase2-aphrodite.md
+- @demeter  → migrations      → .tmp/IMPL-phase2-demeter.md
+Themis reviews all three after completion.
+```
+
+---
+
+## Artifact Protocol
+
+All phase outputs go to `.pantheon/memory-bank/.tmp/`. See `skill: artifact-management` for the complete protocol (who generates what, templates, lifecycle).
+
+---
+
+## Safety Gates
+
+| Gate | When | Why |
+|------|------|-----|
+| **GATE 1** | After PLAN | User confirms scope |
+| **GATE 2** | After Themis review | User sees changes |
+| **GATE 3** | Before git commit | User controls history |
+
+---
+
+## Model Selection
+
+Model routing is handled by Prometheus and the platform configuration. Zeus delegates model selection to the tier system (`fast` / `default` / `coding` / `premium`).
+
+- **Deep tasks** → High-quality models (Claude, GPT-4)
+- **Quick tasks** → Fast/cheap models (Haiku, 4o-mini)
+- **Visual tasks** → Multimodal models (GPT-4V, Claude Vision)
+- **Cost optimization** → Route to cheapest model that meets quality bar
+
+---
 
-## Boundaries
+## Anti-Patterns
 
-- Zeus coordinates; implementation agents inspect, edit, and verify their assigned scope.
-- Preserve auth/security, data/schema, destructive-action, production, and permission gates.
-- Do not commit, push, merge, deploy, or broaden scope without explicit authorization.
-- Model selection comes from the active configured preset; do not invent a model tier or price.
+- ❌ Zeus doing implementation work (orchestrates, doesn't code)
+- ❌ Skipping TDD cycle (RED → GREEN → REFACTOR)
+- ❌ Auto-committing without user approval
+- ❌ Parallel phases with dependencies (order matters)
+- ❌ Ignoring Themis CRITICAL findings

package/src/skills/auto-continue/SKILL.md

@@ -52,8 +52,6 @@ Full-auto may continue only within a task and scope the user explicitly authoriz
 
 ---
 
----
-
 ## Implementation Pattern
 
 ```
@@ -165,25 +163,26 @@ Should I now run the migration tests? [waiting]
 
 ## Session Heartbeat & Checkpoints
 
-Use checkpoints only when `context_save` and `context_get` are explicitly present
-in the active session's tool list. Standalone OpenCode V2 agent profiles do not
-currently grant these tools; in that case, do not attempt a checkpoint or guess
-a session ID. Carry forward the phase and remaining tasks in the normal task
-handoff instead.
+Session state is **not** file-based. It lives in **pantheon-persistence** under the
+`checkpoint:<slug>` namespace and is cleaned up automatically by a 4h TTL.
+
+Use checkpoints only when `context_save` and `context_get` are explicitly
+present in the active session's tool list. If unavailable, do not attempt a
+checkpoint or guess a session ID; carry the handoff in the normal response.
 
-When the tools are available, write state with `context_save(slug=slug, key=key, content=JSON.stringify(state), session_id=...)` and read it back with
-`context_get(slug=slug, key="latest", session_id=...)`. Capture `session_id` from the first `context_save`
-of the session and reuse it for the rest of the session, so the `latest` pointer survives
-compaction. `state` must be an object — never pass a bare string as `content`: its
+When available, call `context_save` with `content=JSON.stringify(state)` and an
+explicit `session_id`. A successful save needs no immediate `context_get`; read
+only when resuming or when the save result is uncertain. Reuse the same session
+ID so the `latest` pointer survives compaction. `state` must be an object — never pass a bare string as `content`: its
 `goal`/`phase`/`delegations`/`heartbeat` values are objects and `tail` is an array.
 `goal` is optional; when unset, omit the key rather than passing a string placeholder.
 
 ### Heartbeat Check
-- When checkpoint tools are available, an old heartbeat (>300s) is a stall signal; log it before resuming.
-- Write a heartbeat after anti-stall recovery only when the current session exposes the checkpoint tools.
+- Check heartbeat only when checkpoint tools are available and the workflow needs a durable resume.
+- Write a heartbeat after anti-stall recovery only when the current session exposes checkpoint tools.
 
 ### Checkpoint Rules
-1. Save checkpoints for long-running/multi-phase work, context-loss risk, or substantive parallel work — not a one-off command or bounded fix, and only when the tools are available
+1. Save checkpoints only for long-running/multi-phase work, context-loss risk, or substantive parallel work — not a one-off command or bounded fix
 2. Include current phase and remaining tasks when a checkpoint is warranted
 3. On resume, read the latest checkpoint only with a known session ID; otherwise request the missing handoff context.