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

package/AGENTS.global.md

@@ -1,7 +1,7 @@
 <!-- pantheon:generated:begin — Pantheon-managed region; regenerated on install/upgrade, never edit inside -->
 <!-- Generated by scripts/build-agents-md.mjs — do not edit directly. -->
 <!-- Source of truth: src/instructions/*.instructions.md + the static sections in this script. -->
-<!-- pantheon:agents-md v2 artifact=global generated-at=2026-10-14T15:44:12-03:00 sha=a305942 -->
+<!-- pantheon:agents-md v2 artifact=global generated-at=2026-10-15T14:32:32-03:00 sha=66bf918 -->
 
 # Pantheon Agent System — OpenCode
 
@@ -76,7 +76,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
@@ -85,8 +85,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
@@ -98,29 +98,31 @@ 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.
 
 <!-- Source: src/instructions/memory-protocol.instructions.md -->
 ## Memory Protocol
@@ -138,12 +140,34 @@ 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.
 
+<!-- Source: src/instructions/test-economy.instructions.md -->
+## 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.
+
 <!-- Source: src/instructions/yagni.instructions.md -->
 ## YAGNI Anti-overengineering
 

package/AGENTS.md

@@ -1,7 +1,7 @@
 <!-- pantheon:generated:begin — Pantheon-managed region; regenerated on install/upgrade, never edit inside -->
 <!-- Generated by scripts/build-agents-md.mjs — do not edit directly. -->
 <!-- Source of truth: the static project sections in scripts/build-agents-md.mjs. -->
-<!-- pantheon:agents-md v2 artifact=project generated-at=2026-10-14T15:44:12-03:00 sha=a305942 -->
+<!-- pantheon:agents-md v2 artifact=project generated-at=2026-10-15T14:32:32-03:00 sha=66bf918 -->
 
 # Pantheon — Repository Setup
 

package/CHANGELOG.md

@@ -18,6 +18,30 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## ✅ Closed Issues
 
+## [v1.6.0-beta.11] - 2026-10-15
+
+## 🆕 What's New
+
+- **record final Beta 11 scope decisions**
+- **record Setup delivery and final-gate lessons in roadmap**
+- **forbid hook bypass in Iris commit contract**
+- **add installer failure reporting and secret-safe output audit**
+- **detect drift between installer plan and apply**
+- **require explicit --yes authorization before installer apply**
+- **exact installer backup set with restore**
+- **add Beta 11 test-economy requirement to shared instructions**
+- **preview per-file change set in installer dry-run**
+- **reconcile Beta 11 roadmap status with completed phases**
+- **describe pantheon_cost window and aggregation limits**
+- **align lean-flow guidance and cost wording**
+- **add project-scoped V2 model overrides**
+- **align host tool and background contracts**
+
+## 🐞 Fixed
+
+- **restore explicit "both" in zeus memory operations instruction**
+- **correct council protocol and persistence bounds**
+
 ## [v1.6.0-beta.10] - 2026-10-12
 
 ## 🆕 What's New

package/README.md

@@ -52,6 +52,23 @@ opencode
 The installer guides you through the available setup. For optional MCP servers,
 project-local installation, or non-interactive setup, see the
 [installation guide](docs/INSTALLATION.md).
+
+A non-interactive apply requires `--yes` (alias `-y`): without a TTY and
+without `--yes`, `init` prints the change plan and applies nothing. Exit codes:
+`0` success or plan/no-apply, `1` failure, `2` apply requested without
+authorization, `3` drift (a planned target changed between plan and apply),
+`130` canceled. Drift is checked within a single run (plan → apply); it cannot
+be detected across two separate CLI invocations (no plan is persisted).
+
+Preview without writing anything with `init --dry-run`. Before the first write,
+`init` saves an exact backup set under `.pantheon/backups/<timestamp>/`
+(directory `0700`, files `0600`, the 5 most recent kept); it is a byte-for-byte
+copy and therefore also contains any API keys or tokens already present in your
+files — it is never printed. Recover with
+`pantheon-opencode restore [--project] [--yes]` (there is no automatic
+rollback; an interrupted apply is recoverable the same way). The
+`postinstall`/`sync-tui` step only refreshes TUI artifacts and is deliberately
+outside this approval flow — no prompt is possible there.
 The bundled Python MCP servers use the pinned MCP SDK 2.2.0 and standalone
 FastMCP 4.0.10 runtime; see the [MCP guide](docs/MCP.md).
 The installer also turns each agent's `mcp_tools` allowlist into native
@@ -182,12 +199,17 @@ session/compaction hooks, so the 1.6 line is not full V2 feature parity.
 | V2 native subagent admission | OpenCode v2.0.29 | `tests/canary/run-v2-permission-proof.sh`; identity, root/child checks and permission-before-child ordering are recorded in [`bench/results/f4a-v229-admission-identity-2026-10-14.md`](bench/results/f4a-v229-admission-identity-2026-10-14.md) |
 | Exact 1.X host version the 1.6 line is exercised against end-to-end | **Unverified.** No V1 host leg exists: the sandbox runner is V2-only and `--run v1` is rejected | — |
 
-## Delegation (native `task()`)
-
-Pantheon delegates exclusively through OpenCode's native `task()` child-session
-engine. The former custom `pantheon_delegate` tool and the V1 delegation engine
-(`delegation.ts`, `delegate-manager.ts` and supporting modules) were removed;
-there is no Pantheon-specific delegation tool surface to configure. See
+## Delegation (root `subagent`; host/API `task()`)
+
+The host's child-session engine is referred to as native `task()` in API and
+implementation documentation. In the user-reported Beta 10 Zeus-root runtime,
+the callable dispatch tool was `subagent`; `task()` was not exposed as a root
+tool. Treat the API name and examples below as host/API terminology, not a
+guaranteed root-tool name or signature. The active runtime determines the
+`subagent` schema, background options, and completion observability. The former
+custom `pantheon_delegate` tool and the V1 delegation engine (`delegation.ts`,
+`delegate-manager.ts` and supporting modules) were removed; there is no
+Pantheon-specific delegation tool surface to configure. See
 [ADR-0011](.pantheon/memory-bank/adr/0011-delegation-engine-contract.md) for the
 historical engine contract.
 
@@ -210,8 +232,12 @@ global database. Both OpenCode services were running, so the 404 in the global
 log may come from the other instance; this remains an end-to-end verification
 item.
 
-Delegated tasks get at most one retry after an initial timeout or failure. If
-that retry fails, the configured fallback or escalation chain applies.
+Delegated work gets at most one retry after an initial transient failure. If no
+completion/status tool is exposed, prefer synchronous `subagent` dispatch or
+wait for a host-provided completion notification; do not assume polling,
+cancellation, job tracking, or board-based recovery. If the runtime does not
+make completion observable, report that limitation. The configured fallback or
+escalation chain still applies.
 
 ## Cost tool backend
 
@@ -230,6 +256,8 @@ available.
 |----------|---------|---------|
 | `PANTHEON_NODE` | `node` from `PATH` | Path to a Node.js >= 22.5 binary used by the CLI fallback; an explicit path must exist and be executable, otherwise the tool fails fast instead of ignoring the override |
 
+Tool interpretation matters: `pantheon_model status` reports configuration, not the model serving a completion. V2 manual model overrides are project-only; global override files are neither read nor applied, and global mutation is unsupported until a future surface can obtain separate explicit human authorization. V2 ignores static presets and applies only explicit per-agent project model/variant overrides, leaving the host default unchanged otherwise; V1 preset behavior remains legacy pending compatibility decisions. `pantheon_cost` is a rolling token aggregate, not a session-level or monetary cost report. See the [OpenCode plugin tool notes](docs/mcp-tools.md#opencode-plugin-tools) for details and measurement limits.
+
 
 ## Code-mode execution (explicit opt-in)
 
@@ -550,23 +578,35 @@ Two freshness guarantees back it up:
   current package.
 
 `init` also gained `--components agents,skills,...` (narrow install),
-`--clean` (alias of `--force`), `--opencode-version auto`, atomic config
-writes with an `opencode.json.bak` backup, preflight checks for python3/npm
-before any file is written, and a non-fatal Python runtime: if the venv fails,
-the install completes but MCP entries are omitted (with a warning) instead of
-pointing at a broken interpreter. Installer messages auto-detect pt-BR via
-`LANG`/`LC_ALL`.
+`--clean` (alias of `--force`), `--opencode-version auto`, preflight checks for
+python3/npm before any file is written, and a non-fatal Python runtime: if the
+venv fails, the install completes but MCP entries are omitted (with a warning)
+instead of pointing at a broken interpreter. Before the first modifying write,
+`init` preserves, byte-for-byte, every regular file it can modify or remove
+inside the config dir (including files a `--clean` run deletes) under
+`.pantheon/backups/<timestamp>/` (directory `0700`, files `0600`, kept 5 deep);
+bulk directories
+(`.venv`, the plugin's `node_modules`) and out-of-target global files
+(`tui.json` copies elsewhere, the global `opencode-vision.json`) are listed in
+the manifest as `notRevertible` rather than silently omitted. The exact-set
+warning is printed once and never echoes file contents. Restore with
+`pantheon-opencode restore [--project] [--yes]` (the old `opencode.json.bak`
+sidecar is gone; the global vision config keeps its own `.bak`). Installer
+messages auto-detect pt-BR via `LANG`/`LC_ALL`.
 
 ## Migrating to 1.5.x (from 1.4.x)
 
 1.5.0 removed the custom `pantheon_delegate` tool (and the V1 delegation
-engine) in favor of OpenCode's native `task()`; see
-[Delegation (native `task()`)](#delegation-native-task). Two things change on
+engine) in favor of the host child-session engine; see
+[Delegation (`subagent` / host API `task()`)](#delegation-root-subagent-hostapi-task). In the
+reported Beta 10 runtime Zeus dispatches through `subagent`; `task()` remains
+host/API terminology, not a guaranteed root tool. Two things change on
 an existing install:
 
 1. **The tool disappears from the plugin surface.** `pantheon_delegate` is no
    longer registered by `src/plugin.ts` or `src/plugin-v2.ts`. Agents now
-   delegate through `task()` only — no configuration is needed.
+   delegate through the dispatch tool actually exposed by the active runtime —
+   no Pantheon-specific delegation tool configuration is needed.
 2. **A lockfile-pinned copy can keep the old tool alive.** `npm install` is
    lockfile-authoritative: a `package-lock.json` pinned to `1.4.1` (which
    satisfies `^1.4.1`) is never re-resolved, so a project's
@@ -839,13 +879,18 @@ with the other.
 
 ### Task-result guard
 
-A `task-result-guard` intercepts calls to the native `task()` tool where the
-child session returns an empty or missing result. Instead of surfacing a silent
+A `task-result-guard` intercepts host/API child-session dispatch calls where the
+child session returns an empty or missing result. In the reported Beta 10 Zeus
+root, dispatch is exposed as `subagent`; host/API `task()` terminology does not
+guarantee a root tool by that name. Instead of surfacing a silent
 `completed` with no payload (which confuses the orchestrator), the guard now
 raises an explicit error. This catches the common free-tier failure mode where a
 child session exceeds the uncached-prefill token budget (`BackendAdmissionRejected`)
-and returns nothing. Prefer `background=true` dispatches with an explicit
-`task_status(wait=true)` fan-in so large payloads are collected deterministically.
+and returns nothing. Background dispatch and status/fan-in facilities are
+runtime-dependent. The reported Beta 10 Zeus root did not expose `task_status`;
+use synchronous `subagent` dispatch or wait for a host-provided completion
+notification when no status tool is visible. Do not claim deterministic fan-in
+or job recovery without an exposed, verified mechanism.
 
 
 ## Configuration (environment variables)

package/bin/pantheon-init.mjs

@@ -21,6 +21,8 @@ import os from 'node:os'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 
+import { resolveInstallExitCode } from '../scripts/install/exit-codes.mjs'
+
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const ROOT = path.resolve(__dirname, '..')
 
@@ -69,10 +71,24 @@ function printUsage() {
   console.log('  npx pantheon-opencode prune               # List legacy artifacts (dry-run)')
   console.log('  npx pantheon-opencode prune --apply       # Remove stale backups')
   console.log('  npx pantheon-opencode doctor [--profile]  # Run health check')
+  console.log(
+    '  npx pantheon-opencode restore [--project] [--yes]  # Restore an exact installer backup',
+  )
   console.log('  npx pantheon-opencode uninstall --project   # Remove project artifacts safely')
   console.log('  npx pantheon-opencode uninstall --global    # Remove global artifacts safely')
   console.log('  npx pantheon-opencode --version, -v       # Print version and exit')
   console.log('  npx pantheon-opencode --help              # Show this help')
+  console.log('')
+  console.log('Apply authorization:')
+  console.log('  A non-interactive run without --yes prints the plan and applies NOTHING.')
+  console.log('  Re-run with --yes to apply; an interactive TTY run prompts (default: no).')
+  console.log('')
+  console.log('Exit codes:')
+  console.log('  0   success, or plan/no-apply (declined)')
+  console.log('  1   failure')
+  console.log('  2   apply was requested without authorization (non-interactive, no --yes)')
+  console.log('  3   drift detected (a planned file changed after the plan)')
+  console.log('  130 canceled')
 }
 
 async function main() {
@@ -109,6 +125,17 @@ async function main() {
     process.exit(result.status ?? 1)
   }
 
+  // restore delegates to scripts/restore.mjs (same spawnSync pattern as prune).
+  if (command === 'restore') {
+    const { spawnSync } = await import('node:child_process')
+    const restoreScript = path.join(ROOT, 'scripts', 'restore.mjs')
+    const result = spawnSync(process.execPath, [restoreScript, ...args.slice(1)], {
+      stdio: 'inherit',
+      cwd: process.cwd(),
+    })
+    process.exit(result.status ?? 1)
+  }
+
   // doctor delegates to scripts/doctor.mjs (same spawnSync pattern as prune).
   // Forwarding the FULL args (profile, target, --fix, ...) keeps the packaged
   // CLI a thin wrapper; the doctor banner reports the resolved profile.
@@ -414,10 +441,11 @@ async function main() {
       console.log('')
     }
 
+    let result
     try {
       const { installOpenCode } = await import('../scripts/install/opencode.mjs')
       const target = isProject ? process.cwd() : undefined
-      await installOpenCode(target, isDryRun, forceReinstall, components, {
+      result = await installOpenCode(target, isDryRun, forceReinstall, components, {
         interactive: forceInteractive,
         headless: forceHeadless,
         yes: autoYes,
@@ -436,6 +464,21 @@ async function main() {
       process.exit(1)
     }
 
+    // Beta 11 Setup phases 3-4: a run that did NOT apply (declined /
+    // unauthorized / drift) must never print a success banner. Exit codes:
+    //   0 ok / no-apply · 2 apply-requested-without-authorization · 3 drift
+    //   130 canceled · 1 failure (thrown above).
+    if (result?.applied === false) {
+      if (!isDryRun) {
+        if (result.reason === 'canceled') console.error(S.canceled)
+        process.exit(resolveInstallExitCode(result, isDryRun))
+      }
+      // Dry-run preview: report honestly instead of the "installed!" banner.
+      console.log('')
+      console.log(`  ${S.dryRunNothingWritten}`)
+      return
+    }
+
     if (runDoctor && !isDryRun) {
       console.log('')
       console.log(`  ${S.runningHealthCheck}`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pantheon-opencode",
-  "version": "1.6.0-beta.10",
+  "version": "1.6.0-beta.11",
   "description": "Multi-agent orchestration for OpenCode — 14 specialized agents, TDD, Themis review gates.",
   "type": "module",
   "workspaces": [
@@ -18,12 +18,12 @@
   "scripts": {
     "postinstall": "node scripts/postinstall.mjs && node scripts/sync-tui.mjs",
     "prepare": "husky",
-    "setup": "node bin/pantheon-init.mjs init",
+    "setup": "node bin/pantheon-init.mjs init --yes",
     "build:agents-md": "node scripts/build-agents-md.mjs",
-    "setup:lite": "node bin/pantheon-init.mjs init --clean --components agents,skills,instructions",
+    "setup:lite": "node bin/pantheon-init.mjs init --yes --clean --components agents,skills,instructions",
     "doctor": "node scripts/doctor.mjs",
     "prune": "node scripts/prune.mjs",
-    "init": "node bin/pantheon-init.mjs init",
+    "init": "node bin/pantheon-init.mjs init --yes",
     "opencode": "OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true opencode",
     "start": "OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true opencode",
     "prepublishOnly": "node scripts/validate-routing.mjs",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pantheon",
   "publisher": "ils15",
-  "version": "1.6.0-beta.10",
+  "version": "1.6.0-beta.11",
   "displayName": "Pantheon",
   "description": "Conductor-Delegate orchestration platform with 14 specialized agents, 20 skills, and OpenCode support.",
   "agents": "./src/agents",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.backends._legacy:_Backend"
 
 [project]
 name = "pantheon"
-version = "1.6.0-beta.10"
+version = "1.6.0-beta.11"
 description = "Multi-agent orchestration framework"
 requires-python = ">=3.11"
 dependencies = []

package/scripts/build-agents-md.mjs

@@ -36,6 +36,8 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSy
 import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
+import { ACTIONS, isRecording, recordChange } from './install/plan.mjs'
+
 const __dirname = dirname(fileURLToPath(import.meta.url))
 export const ROOT = join(__dirname, '..')
 const INSTRUCTIONS_DIR = join(ROOT, 'src', 'instructions')
@@ -323,16 +325,26 @@ export function generateProjectAgentsMd(git = readGitInfo()) {
  * @param {boolean} [dryRun=false] - Do not write when true
  * @returns {'created' | 'skipped' | 'updated' | 'upgraded' | 'merged'}
  */
-export function writeAgentsMdManaged(filePath, generated, dryRun = false) {
+export function writeAgentsMdManaged(filePath, generated, dryRun = false, recorder = null) {
   const existing = existsSync(filePath) ? readFileSync(filePath, 'utf8') : null
   if (existing === null) {
     if (!dryRun) {
       mkdirSync(dirname(filePath), { recursive: true })
       writeFileSync(filePath, generated, 'utf8')
     }
+    recordChange(
+      { path: filePath, action: ACTIONS.CREATE, bytes: Buffer.byteLength(generated, 'utf8') },
+      recorder,
+    )
     return 'created'
   }
-  if (existing === generated) return 'skipped'
+  if (existing === generated) {
+    recordChange(
+      { path: filePath, action: ACTIONS.UNCHANGED, bytes: Buffer.byteLength(existing, 'utf8') },
+      recorder,
+    )
+    return 'skipped'
+  }
 
   const begin = existing.indexOf(MANAGED_BEGIN)
   const end = existing.indexOf(MANAGED_END)
@@ -340,22 +352,41 @@ export function writeAgentsMdManaged(filePath, generated, dryRun = false) {
     const before = existing.slice(0, begin)
     const after = existing.slice(end + MANAGED_END.length)
     const next = `${before}${generated}${after}`
-    if (next === existing) return 'skipped'
+    if (next === existing) {
+      recordChange(
+        { path: filePath, action: ACTIONS.UNCHANGED, bytes: Buffer.byteLength(existing, 'utf8') },
+        recorder,
+      )
+      return 'skipped'
+    }
     if (!dryRun) writeFileSync(filePath, next, 'utf8')
+    recordChange(
+      { path: filePath, action: ACTIONS.UPDATE, bytes: Buffer.byteLength(next, 'utf8') },
+      recorder,
+    )
     return before.trim() === '' && after.trim() === '' ? 'updated' : 'merged'
   }
 
   if (existing.startsWith(GENERATED_BY)) {
     // Legacy format: the header declares the whole file machine-generated.
     if (!dryRun) writeFileSync(filePath, generated, 'utf8')
+    recordChange(
+      { path: filePath, action: ACTIONS.UPDATE, bytes: Buffer.byteLength(generated, 'utf8') },
+      recorder,
+    )
     return 'upgraded'
   }
 
   // Foreign content: preserve it verbatim and append the managed region.
+  const separator = existing.endsWith('\n') ? '\n' : '\n\n'
+  const payload = `${existing}${separator}${generated}`
   if (!dryRun) {
-    const separator = existing.endsWith('\n') ? '\n' : '\n\n'
-    writeFileSync(filePath, `${existing}${separator}${generated}`, 'utf8')
+    writeFileSync(filePath, payload, 'utf8')
   }
+  recordChange(
+    { path: filePath, action: ACTIONS.UPDATE, bytes: Buffer.byteLength(payload, 'utf8') },
+    recorder,
+  )
   return 'merged'
 }
 
@@ -423,9 +454,16 @@ export function generateAgentPrompt(agentName, prompt, instructions = readInstru
  * @param {string} targetDir - OpenCode agents directory
  * @param {boolean} dryRun - Do not write when true
  * @param {boolean} existingOnly - Refresh installed prompts without adding missing agents
+ * @param {(change: object) => void} [recorder] - optional change recorder for --dry-run preview
  * @returns {{ created: number, skipped: number }}
  */
-export function copyAgentPrompts(sourceDir, targetDir, dryRun = false, existingOnly = false) {
+export function copyAgentPrompts(
+  sourceDir,
+  targetDir,
+  dryRun = false,
+  existingOnly = false,
+  recorder = null,
+) {
   const instructions = readInstructions()
   if (!dryRun && !existingOnly) mkdirSync(targetDir, { recursive: true })
   let created = 0
@@ -443,9 +481,25 @@ export function copyAgentPrompts(sourceDir, targetDir, dryRun = false, existingO
     const existing = existsSync(targetPath) ? readFileSync(targetPath, 'utf8') : null
     if (existing === output) {
       skipped++
+      if (isRecording(recorder)) {
+        recordChange(
+          { path: targetPath, action: ACTIONS.UNCHANGED, bytes: Buffer.byteLength(output, 'utf8') },
+          recorder,
+        )
+      }
     } else {
       if (!dryRun) writeFileSync(targetPath, output, 'utf8')
       created++
+      if (isRecording(recorder)) {
+        recordChange(
+          {
+            path: targetPath,
+            action: existing === null ? ACTIONS.CREATE : ACTIONS.UPDATE,
+            bytes: Buffer.byteLength(output, 'utf8'),
+          },
+          recorder,
+        )
+      }
     }
   }
   return { created, skipped }