pan-wizard 3.17.0 → 3.19.0

package/README.md

@@ -201,6 +201,29 @@ npm run test:all        # All tests (unit + scenario)
 
 </details>
 
+<details>
+<summary><strong>Experimental: ZCode support (preview) — ZCode is beta</strong></summary>
+
+**PAN-Z** is an experimental, separate subsystem that brings the PAN workflow to
+[ZCode](https://zcode.z.ai), z.ai's GLM coding-agent harness. ZCode has no
+slash-commands or hooks to host PAN directly, so PAN-Z instead exposes PAN's engine to
+ZCode over **MCP**: PAN's agents become ZCode subagents, and the deterministic engine —
+including a model-proof human merge gate — is reached as MCP tools.
+
+> **ZCode is beta**, and its on-disk formats change frequently. PAN-Z is a **preview**:
+> two facts (whether a subagent can call MCP tools, and whether local MCP calls are
+> metered) can only be confirmed on a live ZCode install. See
+> [`pan-zcode/README.md`](pan-zcode/README.md) and
+> [`pan-zcode/KNOWN-BETA-RISKS.md`](pan-zcode/KNOWN-BETA-RISKS.md).
+
+```bash
+# From an installed pan-wizard package, build the ZCode bundle into a target dir
+node "$(npm root -g)/pan-wizard/pan-zcode/bin/install-zcode.js" --target ./zcode-bundle
+# then finish setup inside ZCode per the generated INSTALL-ZCODE.md
+```
+
+</details>
+
 ### Recommended: Skip Permissions Mode
 
 PAN is designed for frictionless automation. Run Claude Code with:

package/bin/install-lib.cjs

@@ -1016,9 +1016,18 @@ function detectModelCapabilities(modelName) {
   const n = modelName.toLowerCase();
 
   // Anthropic Claude family
-  if (n.includes('fable')) {
+  if (n.includes('fable') || n.includes('mythos')) {
     return { has_1m_ctx: true, has_thinking: true, has_cache: true, tier: 'reasoning' };
   }
+  // Claude 5 family (Opus 5, Sonnet 5) — 1M context, extended thinking, prompt caching.
+  // Without this, `claude-opus-5` falls through to `unknown` and the installer prints
+  // a FALSE "your model lacks 1M context / extended thinking" warning on the flagship.
+  if (n.includes('opus-5')) {
+    return { has_1m_ctx: true, has_thinking: true, has_cache: true, tier: 'reasoning' };
+  }
+  if (n.includes('sonnet-5')) {
+    return { has_1m_ctx: true, has_thinking: true, has_cache: true, tier: 'mid' };
+  }
   if (n.includes('opus-4-8') || n.includes('opus-4.8')
     || n.includes('opus-4-7') || n.includes('opus-4.7')
     || n.includes('opus-4-6') || n.includes('opus-4.6')) {

package/bin/install.js

@@ -2492,7 +2492,7 @@ function finishInstall(settingsPath, settings, statuslineCommand, shouldInstallS
           console.log(`
   ${yellow}ℹ${reset} PAN's multi-agent workflows are tuned for frontier reasoning models. Default model "${modelField}" lacks: ${missing}.
      Features degrade gracefully, but for best results select claude-fable-5 (PAN's recommended flagship — deepest
-     long-horizon reasoning for the bot army) or claude-opus-4-8 (same 1M context at half the cost).`);
+     long-horizon reasoning for the bot army), or an Opus-tier model (claude-opus-5 / claude-opus-4-8) at lower cost.`);
         }
       }
     } catch {

package/commands/pan/army.md

@@ -78,13 +78,14 @@ Every cap the conductor enforces applies to the campaign, scaled up:
 |------|---------|--------|
 | `--source` | `backlog` | Work selection (delegates to focus-auto): `backlog` = ranked roadmap/requirements items; `scan` = category code-scan. |
 | `--max-cycles` | 5 | Mission items landed before stopping. |
-| `--total-budget` | 300 | Cumulative point ceiling. |
+| `--total-budget` | 300 | Cumulative point budget. **Advisory by default** — tracked/surfaced but not a hard stop unless `--enforce-budget` / config `budget.enforce: true`. |
+| `--enforce-budget` | off | Make the point budgets hard stops again (also settable via config `budget.enforce: true`). |
 | `--squads` | all | Restrict to a subset, e.g. `--squads architecture,build,quality`. |
 | `--no-build-worktrees` | off | Build in the main tree instead of branch-per-agent worktrees (small/serial projects). |
 | `--push` | off | Push approved merges to origin (still human-gated). |
 | `--clean-seal` | off | One clean build + full verification after the last item (commands from config). |
 | `--schedule` | off | Arm a self-resuming campaign at this cadence (`hourly`/`daily`/`weekly`/`Nh`/`Nd`) instead of running once — writes the schedule descriptor (ADR-0034). Pair with `--daily-budget`. |
-| `--daily-budget` | 300 | Per-day point ceiling for a scheduled campaign; the day's run stops when reached, resumes next day. |
+| `--daily-budget` | 300 | Per-day point budget for a scheduled campaign. Advisory by default (an indicator of the day's spend); it only pauses the day's run when `budget.enforce`/`enforce_budget` is set. |
 | `--dry-run` | off | Plan + squad delegation preview only; STOP. |
 | `--continue` / `--stop` / `--status` | — | Resume / halt / report from `.planning/orchestration/` + focus-auto state. |
 
@@ -141,14 +142,14 @@ PAN is not a daemon — it cannot wake itself while the session is closed. `--sc
 - **Arm:** `/pan:army "<goal>" --schedule daily --daily-budget 200` writes `.planning/orchestration/schedule.json` (cadence, daily budget, next-due) instead of running once.
 - **The trigger (you wire one):** a host scheduler (Claude Code routines / cron / scheduled-tasks) or a `/loop` runs `pan-tools campaign due` and, when it reports due, invokes `/pan:army --continue`. On next session open, a due campaign is surfaced as a nudge.
 - **Resume (`--continue`):** read the schedule + `.planning/orchestration/` + focus-auto state. If `campaign due` is true and the day's `--daily-budget` isn't spent, run the next mission(s), then `campaign record-run` (advances next-due, accrues the day's spend). If not due or budget-spent, report next-due and STOP.
-- **Bounded spend:** the per-day budget caps each day's run; the per-run `--total-budget` and the conductor caps still bound each cycle. A scheduled campaign runs the backlog down to staged, reviewed, green PRs over days — and still waits for a human at every merge.
+- **Bounded spend:** point budgets (`--total-budget`, `--daily-budget`) are **advisory indicators by default** — they're tracked and surfaced, not hard stops, unless `budget.enforce` / `--enforce-budget` is set. The real bounds are `--max-cycles`, the conductor caps, the abort file, and the human merge gate at every integrate. A scheduled campaign runs the backlog down to staged, reviewed, green PRs over days.
 
 Manage it: `pan-tools campaign status` (active/paused, spent today, next-due), `campaign schedule --pause` / `--resume` / `--disable`.
 
 ---
 
 ## Completion contract
-The campaign is complete when ANY holds: `--max-cycles` reached · `--total-budget` exhausted · backlog empty · abort file present · context < 25% · a mission cannot pass Quality and can't be cleanly reverted (HARD STOP — preserve state, report). Always run `--clean-seal` (unless omitted) after the last item.
+The campaign is complete when ANY holds: `--max-cycles` reached · backlog empty · abort file present · context < 25% · a mission cannot pass Quality and can't be cleanly reverted (HARD STOP — preserve state, report). (Budget exhaustion is advisory by default — a stop condition only when `budget.enforce`/`--enforce-budget` is set.) Always run `--clean-seal` (unless omitted) after the last item.
 
 ## NEVER DO
 - Let Mission Control write code, or let a squad agent spawn further agents (depth cap).

package/commands/pan/focus-auto.md

@@ -33,7 +33,7 @@ This command runs improvement campaigns on the **host project's source code**
 <completion_contract>
 A campaign is complete when ANY stop condition is met:
 1. Max cycles reached (--max-cycles, default 10)
-2. Total budget exhausted (--total-budget, default 200)
+2. Total budget exhausted (--total-budget) — **advisory by default**: tracked and surfaced but does NOT stop the run unless `--enforce-budget` (or config `budget.enforce: true`) is set
 3. Scan returns zero items for the selected category
 4. Context window drops below 25% (CRITICAL threshold)
 5. User sends /pan:focus-auto --stop
@@ -100,7 +100,8 @@ Wait for the user's reply before proceeding. Do not guess or pick a default cate
 | `--mode` | category-dependent | bugfix, balanced, features, full |
 | `--budget` | category-dependent | Points per cycle (5-100) |
 | `--max-cycles` | 10 | Maximum iterations (1-50) |
-| `--total-budget` | 500 | Cumulative points cap (5-5000) |
+| `--total-budget` | 500 | Cumulative point budget (5-5000). Advisory by default (tracked/surfaced, not a stop). |
+| `--enforce-budget` | off | Make `--total-budget` a hard stop again (also settable via config `budget.enforce: true`). |
 | `--continue` | — | Resume stopped/interrupted run |
 | `--stop` | — | Gracefully stop active run |
 | `--status` | — | Show current campaign progress |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pan-wizard",
-  "version": "3.17.0",
+  "version": "3.19.0",
   "description": "Command a bot army for your codebase: an Opus Mission Control delegates whole-project goals to specialist squads and ships behind a human merge gate. Five AI CLIs, zero context rot.",
   "bin": {
     "pan-wizard": "bin/install.js"
@@ -12,7 +12,8 @@
     "agents",
     "hooks/dist",
     "scripts",
-    "assets"
+    "assets",
+    "pan-zcode"
   ],
   "keywords": [
     "claude",

package/pan-wizard-core/bin/lib/campaign.cjs

@@ -76,6 +76,9 @@ function writeSchedule(cwd, opts, now) {
     source: opts.source ?? existing.source ?? 'backlog',
     cadence,
     daily_budget: opts.daily_budget != null ? Number(opts.daily_budget) : (existing.daily_budget ?? 300),
+    // Advisory by default: the daily budget is tracked + surfaced but does not block
+    // a due run unless explicitly enforced.
+    enforce_budget: opts.enforce_budget != null ? Boolean(opts.enforce_budget) : (existing.enforce_budget ?? false),
     enabled: opts.enabled != null ? Boolean(opts.enabled) : (existing.enabled ?? true),
     paused: opts.paused != null ? Boolean(opts.paused) : (existing.paused ?? false),
     next_due: existing.next_due ?? at.toISOString(),
@@ -108,7 +111,7 @@ function isRunDue(schedule, now) {
   const spent = spentToday(schedule, at);
   if (!schedule.enabled) return { due: false, reason: 'disabled', next_due: schedule.next_due, spent_today: spent };
   if (schedule.paused) return { due: false, reason: 'paused', next_due: schedule.next_due, spent_today: spent };
-  if (schedule.daily_budget != null && spent >= schedule.daily_budget) {
+  if (schedule.enforce_budget && schedule.daily_budget != null && spent >= schedule.daily_budget) {
     return { due: false, reason: 'budget_exhausted_today', next_due: schedule.next_due, spent_today: spent };
   }
   const due = new Date(schedule.next_due);

package/pan-wizard-core/bin/lib/config.cjs

@@ -62,6 +62,10 @@ function buildConfigDefaults(hasBraveSearch, userDefaults) {
       default_points: 50,
       micro_threshold_tasks: 3,
       micro_threshold_files: 2,
+      // Budget is ADVISORY by default: point/spend caps are tracked and surfaced
+      // (HUD, telemetry) but never STOP a run. Set enforce:true (or pass
+      // --enforce-budget) to make the cap a hard stop again.
+      enforce: false,
     },
     commit: {
       safety_checks: true,

package/pan-wizard-core/bin/lib/core.cjs

@@ -47,34 +47,44 @@ const COST_MULTIPLIERS = { reasoning: 15, mid: 3, fast: 1 };
 
 // ─── Model Profile Table ─────────────────────────────────────────────────────
 
+// COST RESET (2026-07): quality + balanced (the default) both resolve to the
+// `reasoning` tier for EVERY agent — i.e. the DEFAULT model you launched with
+// (`inherit`). PAN no longer silently demotes agents to cheaper models; context
+// isolation (each subagent runs in its own window), not a cheaper model, is what
+// keeps the main conversation clean. Cheapness is now OPT-IN: choose the `budget`
+// profile (the only column that still down-tiers) or pin a specific agent via
+// config `model_overrides`. The 3 security agents additionally pin `model: opus`
+// in their own frontmatter (a native, deliberate exception). resolve-model /
+// MODEL_PROFILES is advisory + cost-estimation; native Claude Code delegation
+// reads each agent file's static `model:` (unset → inherit).
 const MODEL_PROFILES = {
   // Original planning/execution agents (pre-v3.0)
   'pan-planner':              { quality: 'reasoning', balanced: 'reasoning', budget: 'mid' },
-  'pan-roadmapper':           { quality: 'reasoning', balanced: 'mid',      budget: 'mid' },
-  'pan-executor':             { quality: 'reasoning', balanced: 'mid',      budget: 'mid' },
-  'pan-phase-researcher':     { quality: 'reasoning', balanced: 'mid',      budget: 'fast' },
-  'pan-project-researcher':   { quality: 'reasoning', balanced: 'mid',      budget: 'fast' },
-  'pan-research-synthesizer': { quality: 'reasoning', balanced: 'mid',      budget: 'fast' },
-  'pan-debugger':             { quality: 'reasoning', balanced: 'mid',      budget: 'mid' },
-  'pan-document_code':        { quality: 'reasoning', balanced: 'fast',     budget: 'fast' },
-  'pan-verifier':             { quality: 'reasoning', balanced: 'mid',      budget: 'fast' },
-  'pan-plan-checker':         { quality: 'reasoning', balanced: 'mid',      budget: 'fast' },
-  'pan-integration-checker':  { quality: 'reasoning', balanced: 'mid',      budget: 'fast' },
-  'pan-reviewer':             { quality: 'reasoning', balanced: 'fast',     budget: 'fast' },
+  'pan-roadmapper':           { quality: 'reasoning', balanced: 'reasoning', budget: 'mid' },
+  'pan-executor':             { quality: 'reasoning', balanced: 'reasoning', budget: 'mid' },
+  'pan-phase-researcher':     { quality: 'reasoning', balanced: 'reasoning', budget: 'fast' },
+  'pan-project-researcher':   { quality: 'reasoning', balanced: 'reasoning', budget: 'fast' },
+  'pan-research-synthesizer': { quality: 'reasoning', balanced: 'reasoning', budget: 'fast' },
+  'pan-debugger':             { quality: 'reasoning', balanced: 'reasoning', budget: 'mid' },
+  'pan-document_code':        { quality: 'reasoning', balanced: 'reasoning', budget: 'fast' },
+  'pan-verifier':             { quality: 'reasoning', balanced: 'reasoning', budget: 'fast' },
+  'pan-plan-checker':         { quality: 'reasoning', balanced: 'reasoning', budget: 'fast' },
+  'pan-integration-checker':  { quality: 'reasoning', balanced: 'reasoning', budget: 'fast' },
+  'pan-reviewer':             { quality: 'reasoning', balanced: 'reasoning', budget: 'fast' },
   // Spec B v2 agents (v3.0–v3.4) — added v3.7.5 to close MODEL_PROFILES drift
   'pan-conductor':            { quality: 'reasoning', balanced: 'reasoning', budget: 'mid' },
-  'pan-counterfactual':       { quality: 'reasoning', balanced: 'mid',      budget: 'mid' },
-  'pan-hardener':             { quality: 'reasoning', balanced: 'mid',      budget: 'fast' },
-  'pan-meta-reviewer':        { quality: 'reasoning', balanced: 'mid',      budget: 'fast' },
-  'pan-knowledge':            { quality: 'reasoning', balanced: 'mid',      budget: 'fast' },
-  'pan-previewer':            { quality: 'reasoning', balanced: 'fast',     budget: 'fast' },
+  'pan-counterfactual':       { quality: 'reasoning', balanced: 'reasoning', budget: 'mid' },
+  'pan-hardener':             { quality: 'reasoning', balanced: 'reasoning', budget: 'fast' },
+  'pan-meta-reviewer':        { quality: 'reasoning', balanced: 'reasoning', budget: 'fast' },
+  'pan-knowledge':            { quality: 'reasoning', balanced: 'reasoning', budget: 'fast' },
+  'pan-previewer':            { quality: 'reasoning', balanced: 'reasoning', budget: 'fast' },
   // v3.5 agents
-  'pan-optimizer':            { quality: 'reasoning', balanced: 'mid',      budget: 'fast' },
-  'pan-distiller':            { quality: 'reasoning', balanced: 'fast',     budget: 'fast' },
+  'pan-optimizer':            { quality: 'reasoning', balanced: 'reasoning', budget: 'fast' },
+  'pan-distiller':            { quality: 'reasoning', balanced: 'reasoning', budget: 'fast' },
   // v3.7.0 self-improvement loop — observation-only watchdog
-  'pan-experiment-runner':    { quality: 'reasoning', balanced: 'fast',     budget: 'fast' },
+  'pan-experiment-runner':    { quality: 'reasoning', balanced: 'reasoning', budget: 'fast' },
   // ADR-0033 bot-army — Release squad
-  'pan-release':              { quality: 'reasoning', balanced: 'mid',      budget: 'fast' },
+  'pan-release':              { quality: 'reasoning', balanced: 'reasoning', budget: 'fast' },
 };
 
 // ─── Effort Profiles (2026-06, adaptive-thinking era) ───────────────────────
@@ -279,7 +289,7 @@ function loadConfig(cwd) {
       verifier: get('verifier', { section: 'workflow', field: 'verifier' }) ?? defaults.verifier,
       parallelization,
       brave_search: get('brave_search') ?? defaults.brave_search,
-      budget: parsed.budget || { default_points: 50, micro_threshold_tasks: 3, micro_threshold_files: 2 },
+      budget: parsed.budget || { default_points: 50, micro_threshold_tasks: 3, micro_threshold_files: 2, enforce: false },
       commit: parsed.commit || { safety_checks: true, conventional_types: true, sensitive_patterns: ['\\.env$', '\\.pem$', '\\.key$', 'credentials', 'secret', 'password', 'token'] },
       execution: parsed.execution || { default_mode: 'wave_order', rollback_snapshots: true, error_pattern_learning: true },
       focus: parsed.focus || { auto_commit: true },

package/pan-wizard-core/bin/lib/focus.cjs

@@ -863,7 +863,9 @@ function focusAutoCheckpointCommit(cwd, cycle, run) {
 
 function determineStopReason(cycle, run) {
   if (cycle.tests_after < cycle.tests_before) return 'regression';
-  if (run.totals.points_used >= run.total_budget) return 'budget_cap';
+  // Budget is advisory by default — it only STOPS the run when explicitly enforced.
+  // Otherwise the overage is tracked/surfaced (indication) and the loop continues.
+  if (run.budget_enforce && run.totals.points_used >= run.total_budget) return 'budget_cap';
   if (run.totals.cycles_completed >= run.max_cycles) return 'max_cycles';
   if (cycle.items_completed === 0) {
     // Security category gets a descriptive stop reason rather than generic zero_completed
@@ -929,6 +931,10 @@ function focusAutoInit(cwd, raw, getVal, hasFlag) {
   const budget = Number(getVal('--budget', String(defaults.budget)));
   const maxCycles = Number(getVal('--max-cycles', String(DEFAULT_MAX_CYCLES)));
   const totalBudget = Number(getVal('--total-budget', String(DEFAULT_TOTAL_BUDGET)));
+  // Budget is advisory by default (tracked + surfaced, never a hard stop). Enforce
+  // only when the user opts in via config `budget.enforce` or `--enforce-budget`.
+  const budgetConfig = loadConfig(cwd).budget || {};
+  const budgetEnforce = hasFlag('--enforce-budget') || budgetConfig.enforce === true;
 
   if (!FOCUS_MODES.includes(mode)) return error(`Mode must be one of: ${FOCUS_MODES.join(', ')}`);
   if (budget < BUDGET_MIN || budget > BUDGET_MAX) return error(`Budget must be between ${BUDGET_MIN} and ${BUDGET_MAX}`);
@@ -947,6 +953,7 @@ function focusAutoInit(cwd, raw, getVal, hasFlag) {
     budget_per_cycle: budget,
     max_cycles: maxCycles,
     total_budget: totalBudget,
+    budget_enforce: budgetEnforce,
     priority_range: category ? CATEGORY_PRIORITY_RANGE[category] : { min: 0, max: 6 },
     deep_review_enabled: hasFlag('--deep-review'),
     tests_baseline: null,

package/pan-zcode/KNOWN-BETA-RISKS.md

@@ -0,0 +1,36 @@
+# PAN-Z — Known Beta Risks & M0 Open Questions
+
+ZCode is a fast-moving, closed Beta: three subsystems PAN-Z touches (subagent
+frontmatter, plugin/skill layout, MCP config path) changed within a single ~12-day
+window on ZCode's changelog. This ledger tracks what the design deliberately does **not**
+hard-depend on, and the go/no-go facts that can only be settled on a real ZCode install
+(the **M0 verify spike**). Re-check these before trusting any on-disk format.
+
+## M0 — go/no-go (settle empirically on a real ZCode)
+
+| # | Question | If NO → fallback (already in the design) |
+|---|----------|------------------------------------------|
+| 1 | Can a **subagent call MCP tools**? | Primary Agent makes every `pan-mcp` call and feeds results into subagent prompts. Determinism unaffected. |
+| 2 | Are **local stdio MCP calls metered** against the MCP-Calls quota? | Read verbs are MCP *resources*, not tools; batch/cache; never make a hosted z.ai MCP load-bearing. |
+| 3 | Exact **subagent frontmatter schema** / plugin layout / MCP config path? | Drive ZCode's own Import / Settings; treat `pan-zcode/lib/convert-agent.cjs` output as a labelled fallback, not a contract. |
+| 4 | Any **file-based / headless** way to register an MCP server, or GUI-only? | `install-zcode.js` emits a bundle + `INSTALL-ZCODE.md`; the human finishes in ZCode's UI. |
+| 5 | Any **lifecycle hook** that can hard-gate a spawn? | Enforce caps at the MCP-tool-call boundary (the orchestrator), not pre-spawn. |
+
+## Standing constraints (confirmed by the review)
+
+- **The merge gate is not self-sufficient.** Under ZCode Full Access, a raw Bash
+  `git push` bypasses `pan_confirm_merge`. Non-bypassability rests on **server-side
+  branch protection**; the MCP gate is the second, in-process lock. `INSTALL-ZCODE.md`
+  mandates branch protection and "never Full Access during install."
+- **No subagent nesting.** The army flattens to one delegation layer (PAN already caps
+  nesting at 2, so this is tolerable). `Task` is dropped from ported subagents.
+- **User-global subagents only.** No repo-scoped rosters or per-project model profiles.
+- **Genuinely lost:** scheduled self-resuming multi-day campaigns (no headless/daemon),
+  background execution, committable permissions, and custom slash-commands.
+
+## Format-drift policy
+
+Do **not** rely on a passive "write the file and hope" strategy. All three churning
+formats are GUI-owned implementation details: prefer ZCode's authoring surfaces, keep the
+converter output clearly labelled best-effort, and re-verify against this ledger on every
+ZCode version bump.

package/pan-zcode/README.md

@@ -0,0 +1,58 @@
+# PAN-Z — a ZCode-native PAN subsystem
+
+PAN-Z gives [ZCode](https://zcode.z.ai) (z.ai's GLM-5.2 coding harness) the PAN Wizard
+workflow — the multi-phase lifecycle, the bot-army with a human merge gate, deterministic
+state tracking — **without** cloning PAN's slash-commands or hooks (ZCode has neither).
+
+Instead of porting the command surface, PAN-Z **reuses PAN's engine in place** and reaches
+ZCode through the one interface it speaks: **MCP**.
+
+> Design + verified feasibility: [`docs/specs/pan_zcode_mcp_bridge_featureai.md`](../docs/specs/pan_zcode_mcp_bridge_featureai.md).
+> The architecture was confirmed by a 38-agent adversarial review; four optimistic
+> assumptions were refuted and their fixes folded into the design.
+
+## How it fits
+
+```
+ZCode harness (GLM-5.2)          primary Agent drives everything; ported subagents fan out
+        │  MCP · local stdio
+pan-zcode/mcp  (this subsystem)  a thin, zero-dep bridge — verbs → MCP tools/resources
+        │  spawn: node pan-tools.cjs <verb> --raw --cwd <root>
+pan-wizard-core  (reused as-is)  the deterministic engine; .planning/ stays the state store
+```
+
+## Status — M1–M5 built (M0 is the human verify spike)
+
+- **M1 — bridge core.** `mcp/tool-registry.cjs` (pure verb→tool/resource map, with a hard
+  guardrail against exposing a force/reset/rebase/push verb) + `mcp/server.cjs` (a
+  **zero-dependency** JSON-RPC 2.0 stdio MCP server; reads → resources, actions → tools with
+  accurate hints; shell-less `execFile` spawn; `@file:` overflow protocol; protocol-version
+  negotiation; strict per-arg validation).
+- **M2 — determinism grafts.** `mcp/merge-gate.cjs` (two-step, model-proof merge: a human-origin
+  env token that ignores agent-supplied approval; never force/reset/push) + `mcp/orchestrator.cjs`
+  (the deterministic `next-action` state machine with safety caps + regression circuit-breaker),
+  exposed as native MCP tools via `mcp/native-tools.cjs`.
+- **M3 — content port.** `lib/convert-agent.cjs` — Claude agents → ZCode subagents (reusing the
+  installer's frontmatter helpers): drops `Task` (no nesting), maps PAN tiers → `inherit`,
+  preserves the body; plus a command → skill wrapper.
+- **M4 — bundle + install.** `bin/install-zcode.js` — assembles `agents/` + `pan-mcp.json` +
+  manifest + `INSTALL-ZCODE.md` into a `--target` dir; refuses to write inside the source repo;
+  drives ZCode's own Import to finish.
+- **M5 — hardening + docs.** Full test matrix + [`KNOWN-BETA-RISKS.md`](KNOWN-BETA-RISKS.md)
+  (the beta-churn ledger + the M0 go/no-go questions).
+
+Tests: `tests/pan-zcode-mcp.test.cjs`, `tests/pan-zcode-orchestration.test.cjs`,
+`tests/pan-zcode-install.test.cjs`.
+
+## Still pending — M0 (needs a real ZCode install)
+
+Two go/no-go facts can only be settled empirically: **can a subagent call MCP tools?** and **are
+local stdio MCP calls metered?** Both have folded-in fallbacks (see `KNOWN-BETA-RISKS.md`), so the
+design holds either way — but confirm them before relying on the richer paths.
+
+## Zero dependencies
+
+Like the rest of PAN, this subsystem ships **no runtime dependencies**. The MCP protocol is
+implemented directly rather than via an SDK. If protocol drift ever makes that costly, the
+escape hatch is to vendor an MCP SDK **inside this package only**, leaving `pan-wizard-core`
+untouched.

package/pan-zcode/bin/install-zcode.js

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * PAN-Z M4 — assemble the ZCode bundle and emit a pull-based install.
+ *
+ * Produces, into an explicit --target directory:
+ *   agents/*.md              PAN agents converted to ZCode subagents (best-effort)
+ *   pan-mcp.json             the MCP server registration (command/args/env)
+ *   pan-zcode-manifest.json  what was generated
+ *   INSTALL-ZCODE.md         how to finish setup inside ZCode
+ *
+ * It NEVER writes to a real ~/.zcode on its own and NEVER writes inside the PAN
+ * source repo — ZCode's on-disk formats churn weekly, so the human finishes setup by
+ * driving ZCode's own "Import from Claude Code" / Settings surfaces using this bundle.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { convertAgentsDir } = require('../lib/convert-agent.cjs');
+
+/** The MCP registration ZCode reads (Claude-compatible: command/args/env). */
+function mcpServerConfig(panToolsPath, serverPath, projectRoot) {
+  return {
+    mcpServers: {
+      'pan-mcp': {
+        command: 'node',
+        args: [serverPath],
+        env: { PAN_TOOLS_PATH: panToolsPath, PAN_PROJECT_ROOT: projectRoot || '.' },
+      },
+    },
+  };
+}
+
+const INSTRUCTIONS = `# Install PAN-Z into ZCode
+
+PAN-Z bridges PAN's engine to ZCode over MCP. Finish setup inside ZCode:
+
+1. **Register the MCP server.** Add the contents of \`pan-mcp.json\` to ZCode's MCP
+   configuration (Settings → MCP), or point ZCode's MCP config at this file. This
+   exposes the \`pan_*\` tools (state, plan, verify, report, next-action, merge gate).
+
+2. **Import the subagents.** The \`agents/\` folder holds PAN agents in ZCode subagent
+   form. Prefer ZCode's **Import from Claude Code** / Settings → Subagents to register
+   them, since ZCode owns the on-disk format (it is a fast-moving Beta). These files are
+   a fallback, not a contract.
+
+3. **Protect your branches.** The merge gate (\`pan_confirm_merge\`) is one lock; the
+   real, non-bypassable one is **server-side branch protection** on your remote. Enable
+   required reviews so a raw push under Full Access cannot merge. Approve a staged merge
+   by setting \`PAN_MERGE_APPROVAL=<request-id>\` in the MCP server's environment.
+
+4. **Never run the install/import step in ZCode Full Access mode.**
+
+Not yet resolved (the M0 verify spike, on your real ZCode): whether a subagent can call
+MCP tools, and whether local stdio MCP calls are metered. Until confirmed, the primary
+Agent makes every pan-mcp call.
+`;
+
+/** Real path of the nearest EXISTING ancestor of p, with the not-yet-created tail re-attached. */
+function realpathNearest(p) {
+  const tail = [];
+  let cur = path.resolve(p);
+  for (;;) {
+    try {
+      const real = fs.realpathSync(cur);
+      return tail.length ? path.join(real, ...tail) : real;
+    } catch {
+      const parent = path.dirname(cur);
+      if (parent === cur) return path.resolve(p); // hit the root; nothing existed
+      tail.unshift(path.basename(cur));
+      cur = parent;
+    }
+  }
+}
+
+function assertNotInSourceRepo(destDir, repoRoot) {
+  // Resolve symlinks/junctions (a --target under a junction into the repo would else
+  // slip past) and case-fold on case-insensitive filesystems (NTFS/APFS) so a
+  // case-variant path can't bypass the guard.
+  const ci = process.platform === 'win32' || process.platform === 'darwin';
+  const norm = (p) => { const r = realpathNearest(p); return ci ? r.toLowerCase() : r; };
+  const d = norm(destDir);
+  const r = norm(repoRoot);
+  if (d === r || d.startsWith(r + path.sep)) {
+    throw new Error('Refusing to write the PAN-Z bundle inside the PAN source repo. Choose a --target outside it.');
+  }
+}
+
+/**
+ * Build the bundle.
+ * @param {{repoRoot:string, destDir:string, projectRoot?:string}} o
+ * @returns {{agents:number, destDir:string, mcp:Object, files:string[]}}
+ */
+function buildBundle(o) {
+  const repoRoot = path.resolve(o.repoRoot);
+  const destDir = path.resolve(o.destDir);
+  assertNotInSourceRepo(destDir, repoRoot);
+
+  const agentsSrc = path.join(repoRoot, 'agents');
+  const serverPath = path.join(repoRoot, 'pan-zcode', 'mcp', 'server.cjs');
+  const panToolsPath = path.join(repoRoot, 'pan-wizard-core', 'bin', 'pan-tools.cjs');
+
+  fs.mkdirSync(destDir, { recursive: true });
+  const agents = fs.existsSync(agentsSrc) ? convertAgentsDir(agentsSrc, path.join(destDir, 'agents')) : [];
+
+  const mcp = mcpServerConfig(panToolsPath, serverPath, o.projectRoot);
+  fs.writeFileSync(path.join(destDir, 'pan-mcp.json'), JSON.stringify(mcp, null, 2), 'utf8');
+
+  const manifest = {
+    subsystem: 'pan-zcode',
+    agents: agents.map((a) => a.name),
+    mcp_config: 'pan-mcp.json',
+    server: serverPath,
+    pan_tools: panToolsPath,
+  };
+  fs.writeFileSync(path.join(destDir, 'pan-zcode-manifest.json'), JSON.stringify(manifest, null, 2), 'utf8');
+  fs.writeFileSync(path.join(destDir, 'INSTALL-ZCODE.md'), INSTRUCTIONS, 'utf8');
+
+  return { agents: agents.length, destDir, mcp, files: ['agents/', 'pan-mcp.json', 'pan-zcode-manifest.json', 'INSTALL-ZCODE.md'] };
+}
+
+function getArg(args, name) {
+  const i = args.indexOf(name);
+  return i !== -1 && i + 1 < args.length ? args[i + 1] : null;
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const target = getArg(args, '--target');
+  if (!target) {
+    console.error('Usage: install-zcode.js --target <dir> [--project-root <dir>]');
+    console.error('Writes the PAN-Z ZCode bundle to <dir> (outside the PAN source repo).');
+    process.exit(2);
+  }
+  const repoRoot = path.resolve(__dirname, '..', '..');
+  try {
+    const res = buildBundle({ repoRoot, destDir: target, projectRoot: getArg(args, '--project-root') });
+    console.log(`pan-zcode bundle written to ${res.destDir} (${res.agents} subagents + MCP config).`);
+    console.log('Next: open INSTALL-ZCODE.md and finish setup inside ZCode.');
+  } catch (e) {
+    console.error(`install-zcode: ${e.message}`);
+    process.exit(1);
+  }
+}
+
+if (require.main === module) main();
+
+module.exports = { buildBundle, mcpServerConfig, assertNotInSourceRepo };

package/pan-zcode/lib/convert-agent.cjs

@@ -0,0 +1,90 @@
+'use strict';
+
+/**
+ * PAN-Z M3 — content port: Claude agent/command markdown → ZCode subagent/skill.
+ *
+ * Reuses the installer's frontmatter helpers (bin/install-lib.cjs) so the parsing
+ * matches every other runtime converter. ZCode stores subagents as Markdown at
+ * ~/.zcode/agents/<name>.md; the exact frontmatter schema is docs-silent on a
+ * weekly-churning Beta, so this emits a conservative, clearly-labelled best-effort
+ * shape. The installer PREFERS ZCode's own "Import from Claude Code" surface where
+ * available (see install-zcode.js / the M0 verify spike) and treats these files as a
+ * fallback, not a contract.
+ *
+ * Two structural facts from the review are honored here:
+ *  - No subagent nesting → the `Task` tool (PAN's delegation primitive) is dropped;
+ *    a ported subagent is a leaf worker, and the primary Agent orchestrates.
+ *  - Per-subagent model selection exists but PAN's tier aliases (opus/sonnet/haiku)
+ *    are not ZCode model ids → model maps to "inherit" (ZCode's "Inherit default"),
+ *    preserving the original tier as a hint comment.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { extractFrontmatterAndBody, extractFrontmatterField } = require('../../bin/install-lib.cjs');
+
+/** Tools that must not survive the port (no nesting; MCP names are host-specific). */
+function remapTools(toolsCsv) {
+  if (!toolsCsv) return null;
+  const kept = toolsCsv.split(',').map((t) => t.trim()).filter(Boolean)
+    .filter((t) => t !== 'Task' && !t.startsWith('mcp__'));
+  return kept.length ? kept.join(', ') : null;
+}
+
+/** Convert one Claude agent markdown string → a ZCode subagent markdown string. */
+function convertClaudeToZcodeAgent(content) {
+  const { frontmatter, body } = extractFrontmatterAndBody(content);
+  const name = (frontmatter && extractFrontmatterField(frontmatter, 'name')) || 'pan-agent';
+  const description = (frontmatter && extractFrontmatterField(frontmatter, 'description')) || '';
+  const color = frontmatter && extractFrontmatterField(frontmatter, 'color');
+  const tierHint = frontmatter && extractFrontmatterField(frontmatter, 'model');
+  const tools = remapTools(frontmatter && extractFrontmatterField(frontmatter, 'tools'));
+
+  const fm = ['---', `name: ${name}`, `description: ${description}`];
+  // PAN tiers aren't ZCode model ids → inherit the primary Agent's model.
+  fm.push('model: inherit');
+  if (tierHint) fm.push(`# pan-tier: ${tierHint}  (original PAN model tier; mapped to inherit)`);
+  if (color) fm.push(`color: ${color}`);
+  if (tools) fm.push(`tools: ${tools}`);
+  fm.push('---');
+
+  return `${fm.join('\n')}\n${String(body).trimStart()}`;
+}
+
+/** Wrap a Claude /pan command markdown as a ZCode skill doc (best-effort). */
+function convertClaudeCommandToZcodeSkill(content, commandName) {
+  const { body } = extractFrontmatterAndBody(content);
+  const header = [
+    '---',
+    `name: pan-${commandName}`,
+    `description: PAN ${commandName} workflow (invoke via the pan-mcp tools + this playbook).`,
+    '---',
+    '',
+    `> ZCode has no custom slash-commands. This skill carries the ${commandName} playbook;`,
+    '> its deterministic steps run through the pan-mcp tools (see the pan_* tool list).',
+    '',
+  ].join('\n');
+  return header + String(body).trimStart();
+}
+
+/**
+ * Convert every agents/*.md under srcDir into ZCode subagent files under destDir.
+ * @returns {Array<{name:string, dest:string}>}
+ */
+function convertAgentsDir(srcDir, destDir) {
+  const out = [];
+  const files = fs.readdirSync(srcDir).filter((f) => f.endsWith('.md'));
+  fs.mkdirSync(destDir, { recursive: true });
+  for (const f of files) {
+    const content = fs.readFileSync(path.join(srcDir, f), 'utf8');
+    const converted = convertClaudeToZcodeAgent(content);
+    const dest = path.join(destDir, f);
+    fs.writeFileSync(dest, converted, 'utf8');
+    out.push({ name: f.replace(/\.md$/, ''), dest });
+  }
+  return out;
+}
+
+module.exports = {
+  convertClaudeToZcodeAgent, convertClaudeCommandToZcodeSkill, convertAgentsDir, remapTools,
+};

package/pan-zcode/mcp/merge-gate.cjs

@@ -0,0 +1,126 @@
+'use strict';
+
+/**
+ * PAN-Z M2 — the deterministic, model-proof merge gate.
+ *
+ * PAN's non-negotiable rule: nothing reaches a protected branch without a human.
+ * Enforcing this in agent PROSE is not enough (under ZCode Full Access a raw
+ * `git push` sidesteps any advisory check), so the gate lives here, in code, on TWO
+ * locks:
+ *
+ *   Lock 1 (this module): `confirmMerge` refuses unless CI green + verify PASS + a
+ *     HUMAN-ORIGIN approval token all hold. The token is a PER-REQUEST NONCE returned
+ *     by `requestMerge`; the operator, after reviewing, sets PAN_MERGE_APPROVAL to it
+ *     in the MCP server's environment (which the agent's tools cannot write). Because
+ *     the token is fresh per request, it can't be replayed against a later re-request;
+ *     approval is bound to the EXACT branch that was staged, and merging uses the
+ *     recorded branch, not the caller's argument. The token is consumed on success.
+ *   Lock 2 (out of process, documented): server-side branch protection — the truly
+ *     non-bypassable anchor. See docs/specs/pan_zcode_mcp_bridge_featureai.md.
+ *
+ * NEVER exposes force-push / reset / rebase / history-rewrite. Recovery is revert-only.
+ * Git execution is injected so the decision logic is unit-testable.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const APPROVALS_SUBPATH = ['.planning', 'orchestration', 'approvals'];
+const APPROVAL_ENV = 'PAN_MERGE_APPROVAL';
+const BRANCH_RE = /^[A-Za-z0-9][A-Za-z0-9._/-]{0,120}$/;
+
+function approvalsDir(cwd) { return path.join(cwd, ...APPROVALS_SUBPATH); }
+
+/** Filesystem-safe slug used only to LOCATE a branch's request file (not as the token). */
+function slugify(branch) {
+  return String(branch).replace(/[^A-Za-z0-9]+/g, '-').replace(/^-+|-+$/g, '').toLowerCase().slice(0, 80) || 'merge';
+}
+
+function validateBranch(branch) {
+  if (typeof branch !== 'string' || !BRANCH_RE.test(branch)) {
+    throw new Error(`Invalid branch: must match ${BRANCH_RE}`);
+  }
+  return branch;
+}
+
+function recordPath(cwd, branch) { return path.join(approvalsDir(cwd), `${slugify(branch)}.json`); }
+function readJson(p) { try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch { return null; } }
+function writeJson(p, obj) { fs.mkdirSync(path.dirname(p), { recursive: true }); fs.writeFileSync(p, JSON.stringify(obj, null, 2), 'utf8'); }
+
+/**
+ * Stage a merge request. Mints a fresh per-request approval token (nonce), records the
+ * exact branch + the (caller-attested) CI/verify flags, marks it awaiting_approval, and
+ * returns the record. Does NOT merge. The operator sets PAN_MERGE_APPROVAL to
+ * `record.approval_token` after reviewing. (ci_green/verify_pass are agent-attested
+ * advisory context for the human's decision; the token is the sole unfakeable anchor.)
+ */
+function requestMerge(cwd, opts = {}) {
+  const branch = validateBranch(opts.branch);
+  const record = {
+    id: slugify(branch),
+    branch,
+    approval_token: crypto.randomBytes(9).toString('hex'),
+    ci_green: !!opts.ci_green,
+    verify_pass: !!opts.verify_pass,
+    status: 'awaiting_approval',
+    requested_at: opts.now || null,
+  };
+  writeJson(recordPath(cwd, branch), record);
+  return record;
+}
+
+/**
+ * Evaluate whether a merge may proceed — pure decision logic, never merges.
+ * The only human signal is env[PAN_MERGE_APPROVAL] === the request's fresh token; any
+ * agent-supplied approval in `opts` is deliberately not consulted. Approval is bound to
+ * the exact staged branch and refused once the request has been consumed.
+ * @returns {{allowed:boolean, reasons:string[], branch:string, id:string}}
+ */
+function evaluateMerge(cwd, opts = {}, env = process.env) {
+  const branch = validateBranch(opts.branch);
+  const record = readJson(recordPath(cwd, branch));
+  const reasons = [];
+  if (!record) reasons.push('no_merge_request');
+  if (record && record.branch !== branch) reasons.push('branch_mismatch');
+  if (record && record.status !== 'awaiting_approval') reasons.push('already_consumed');
+  if (record && !record.ci_green) reasons.push('ci_not_green');
+  if (record && !record.verify_pass) reasons.push('verify_not_passed');
+  const token = env[APPROVAL_ENV];
+  if (!record || !token || token !== record.approval_token) reasons.push('no_human_approval');
+  return { allowed: reasons.length === 0, reasons, branch: record ? record.branch : branch, id: record ? record.id : slugify(branch) };
+}
+
+/**
+ * Confirm + perform the squash-merge, but only if evaluateMerge allows it. Merges the
+ * RECORDED (approved) branch — never the caller's argument. Git is injected:
+ * gitImpl(argvArray)->{ok,stdout,stderr}. No force/reset/rebase/push verb is ever issued.
+ * On success the request is marked consumed and the human token is cleared from `env`, so
+ * it cannot be replayed without a fresh human approval.
+ */
+function confirmMerge(cwd, opts = {}, env = process.env, gitImpl = null) {
+  const verdict = evaluateMerge(cwd, opts, env);
+  if (!verdict.allowed) return { merged: false, reasons: verdict.reasons, branch: verdict.branch, id: verdict.id };
+  if (typeof gitImpl !== 'function') return { merged: false, reasons: ['no_git_executor'], branch: verdict.branch, id: verdict.id };
+
+  const approvedBranch = verdict.branch; // from the record, not opts
+  const squash = gitImpl(['merge', '--squash', approvedBranch]);
+  if (!squash.ok) return { merged: false, reasons: ['git_merge_failed'], detail: squash.stderr, branch: approvedBranch, id: verdict.id };
+  const commit = gitImpl(['commit', '--no-verify', '-m', `merge: ${approvedBranch} (human-approved)`]);
+  if (!commit.ok) return { merged: false, reasons: ['git_commit_failed'], detail: commit.stderr, branch: approvedBranch, id: verdict.id };
+
+  // Consume: mark the request merged AND clear the one-time token so it can't be reused.
+  const p = recordPath(cwd, approvedBranch);
+  const rec = readJson(p) || { id: verdict.id, branch: approvedBranch };
+  rec.status = 'merged';
+  writeJson(p, rec);
+  if (env && Object.prototype.hasOwnProperty.call(env, APPROVAL_ENV)) delete env[APPROVAL_ENV];
+
+  return { merged: true, branch: approvedBranch, id: verdict.id };
+}
+
+module.exports = {
+  requestMerge, evaluateMerge, confirmMerge,
+  slugify, validateBranch, approvalsDir,
+  APPROVAL_ENV, BRANCH_RE,
+};

package/pan-zcode/mcp/native-tools.cjs

@@ -0,0 +1,63 @@
+'use strict';
+
+/**
+ * PAN-Z M2 — native MCP tools whose logic lives in-process (not a pan-tools spawn).
+ *
+ * These are the deterministic grafts the review demanded: the orchestrator's
+ * `next-action` state machine and the two-step merge gate. A native tool declares a
+ * `handler({ cwd, input, env, gitImpl }) -> { json | text, isError? }` instead of a
+ * `verb`; a thrown Error is surfaced as JSON-RPC -32602 (invalid params) by the server.
+ */
+
+const mergeGate = require('./merge-gate.cjs');
+const orchestrator = require('./orchestrator.cjs');
+
+const NATIVE_TOOLS = [
+  {
+    name: 'pan_next_action',
+    title: 'Next deterministic action',
+    description: 'Given the current phase/run snapshot, return the next step the primary agent should take (plan/execute/verify/request_merge/await_approval/stop). Enforces the safety caps and the regression circuit-breaker.',
+    readOnly: true, destructive: false,
+    inputSchema: {
+      type: 'object', additionalProperties: false, required: ['state'],
+      properties: { state: { type: 'object' }, caps: { type: 'object' } },
+    },
+    handler: ({ input }) => {
+      if (!input.state || typeof input.state !== 'object') throw new Error('Invalid "state": an object snapshot is required');
+      return { json: orchestrator.nextAction(input.state, input.caps) };
+    },
+  },
+  {
+    name: 'pan_request_merge',
+    title: 'Request a gated merge',
+    description: 'Stage a squash-merge request for a branch and mark it awaiting human approval. Records intent only — does NOT merge.',
+    readOnly: false, destructive: false,
+    inputSchema: {
+      type: 'object', additionalProperties: false, required: ['branch'],
+      properties: { branch: { type: 'string' }, ci_green: { type: 'boolean' }, verify_pass: { type: 'boolean' } },
+    },
+    handler: ({ cwd, input }) => ({
+      json: mergeGate.requestMerge(cwd, { branch: input.branch, ci_green: input.ci_green, verify_pass: input.verify_pass }),
+    }),
+  },
+  {
+    name: 'pan_confirm_merge',
+    title: 'Confirm a human-approved merge',
+    description: 'Perform a squash-merge ONLY if CI is green, verify passed, and a human-origin approval token (env PAN_MERGE_APPROVAL equal to the request id) is present. Any agent-supplied approval is ignored; never force-pushes or rewrites history.',
+    readOnly: false, destructive: true,
+    inputSchema: {
+      type: 'object', additionalProperties: false, required: ['branch'],
+      properties: { branch: { type: 'string' } },
+    },
+    handler: ({ cwd, input, env, gitImpl }) => {
+      const res = mergeGate.confirmMerge(cwd, { branch: input.branch }, env, gitImpl);
+      // A refused gate (missing approval / CI / verify) is a normal, non-error result the
+      // agent should read; only a real git failure is flagged isError.
+      const gitFailed = !res.merged && Array.isArray(res.reasons)
+        && res.reasons.some((r) => r === 'git_merge_failed' || r === 'git_commit_failed');
+      return { json: res, isError: gitFailed };
+    },
+  },
+];
+
+module.exports = { NATIVE_TOOLS };

package/pan-zcode/mcp/orchestrator.cjs

@@ -0,0 +1,66 @@
+'use strict';
+
+/**
+ * PAN-Z M2 — the deterministic orchestrator ("next-action" state machine).
+ *
+ * ZCode has no workflow engine and cannot machine-intercept a subagent spawn, so
+ * PAN's sequencing + safety harness (waves, regression circuit-breaker, spawn/budget
+ * caps, the human merge gate) cannot live in agent prose or a pre-spawn hook. The
+ * review's fix: relocate the state machine here and expose ONE `next-action` tool the
+ * primary Agent polls before each step. Enforcement then happens at the (gateable)
+ * MCP-tool-call boundary, not at the (un-gateable) spawn event.
+ *
+ * `nextAction` is a PURE function of a snapshot the caller assembles from PAN's own
+ * state (via the pan-mcp resources) — so it is fully unit-testable and its decisions
+ * are reproducible.
+ */
+
+// Budget is advisory by default (enforceBudget:false) — it never stops the loop
+// unless the caller opts in. maxCycles remains a hard safety stop.
+const DEFAULT_CAPS = { maxCycles: 25, budget: Infinity, enforceBudget: false };
+const PHASE_NEXT = {
+  none: 'plan',
+  researched: 'plan',
+  planned: 'execute',
+  executed: 'verify',
+  verified: 'request_merge',
+};
+
+/**
+ * Decide the next deterministic action.
+ * @param {Object} state snapshot:
+ *   { phases:[{number,status}], cycles?, points_used?, tests_before?, tests_after?,
+ *     awaiting_approval?:boolean, aborted?:boolean }
+ * @param {Object} [caps] { maxCycles, budget }
+ * @returns {{action:string, args?:Object, reason:string, done:boolean}}
+ *   action ∈ plan | execute | verify | request_merge | await_approval | stop
+ */
+function nextAction(state, caps) {
+  const c = Object.assign({}, DEFAULT_CAPS, caps || {});
+  state = state || {};
+
+  // Hard stops first — safety caps and the circuit-breaker outrank all progress.
+  if (state.aborted) return { action: 'stop', reason: 'aborted', done: true };
+  if (
+    typeof state.tests_before === 'number' &&
+    typeof state.tests_after === 'number' &&
+    state.tests_after < state.tests_before
+  ) {
+    return { action: 'stop', reason: 'regression', done: true };
+  }
+  if ((state.cycles || 0) >= c.maxCycles) return { action: 'stop', reason: 'max_cycles', done: true };
+  if (c.enforceBudget && (state.points_used || 0) >= c.budget) return { action: 'stop', reason: 'budget_cap', done: true };
+
+  // The human merge gate is a barrier: while a merge awaits approval, do nothing else.
+  if (state.awaiting_approval) return { action: 'await_approval', reason: 'human_gate', done: false };
+
+  // Advance the first phase that isn't complete.
+  const phases = Array.isArray(state.phases) ? state.phases : [];
+  const phase = phases.find((p) => p && p.status !== 'complete');
+  if (!phase) return { action: 'stop', reason: 'all_complete', done: true };
+
+  const action = PHASE_NEXT[phase.status] || 'plan';
+  return { action, args: { phase: phase.number }, reason: `phase_${phase.status}`, done: false };
+}
+
+module.exports = { nextAction, DEFAULT_CAPS, PHASE_NEXT };

package/pan-zcode/mcp/server.cjs

@@ -0,0 +1,229 @@
+'use strict';
+
+/**
+ * PAN-Z MCP bridge server (M1).
+ *
+ * A dependency-free JSON-RPC 2.0 server over stdio implementing the small MCP
+ * surface ZCode needs: initialize / tools/list / tools/call / resources/list /
+ * resources/read / ping. Each pan-tools verb is reached by spawning
+ *   node <pan-tools.cjs> <verb> [args] --raw --cwd <root>
+ * and returning its JSON — the CLI's JSON contract IS the tool contract, so the
+ * PAN engine (pan-wizard-core) is reused byte-for-byte with no refactor.
+ *
+ * Zero runtime dependencies: PAN is a zero-dep project, so the MCP protocol is
+ * hand-rolled rather than pulled from @modelcontextprotocol/sdk. `handle()` is a
+ * pure function of the request given an injected spawn impl, which makes the whole
+ * protocol layer unit-testable without stdio or a child process.
+ *
+ * Security: the child is launched with execFile (argv array, NO shell), the verb
+ * is always chosen from the registry allowlist, and every tool argument is
+ * validated to a strict shape by the registry before it becomes an argv element.
+ */
+
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const reg = require('./tool-registry.cjs');
+
+const PROTOCOL_VERSION = '2025-06-18';
+// Versions whose method shapes this server actually implements. During
+// `initialize` we echo the client's requested version only if it's one of these,
+// otherwise we answer with our latest — never claim to speak a version we don't.
+const SUPPORTED_PROTOCOL_VERSIONS = new Set(['2025-06-18', '2025-03-26', '2024-11-05']);
+const SERVER_INFO = { name: 'pan-mcp', version: '0.1.0' };
+
+/** Default engine location: pan-wizard-core is a sibling of pan-zcode/. */
+function defaultPanToolsPath() {
+  return path.join(__dirname, '..', '..', 'pan-wizard-core', 'bin', 'pan-tools.cjs');
+}
+
+/** Real spawn: shell-less execFile of `node <argv...>`. */
+function defaultSpawn(nodeArgs) {
+  try {
+    const stdout = execFileSync('node', nodeArgs, {
+      encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 8 * 1024 * 1024,
+    });
+    return { ok: true, stdout: String(stdout).trim(), stderr: '' };
+  } catch (e) {
+    return {
+      ok: false,
+      stdout: e.stdout ? String(e.stdout).trim() : '',
+      stderr: e.stderr ? String(e.stderr).trim() : (e.message || 'spawn failed'),
+    };
+  }
+}
+
+/**
+ * Resolve pan-tools' large-payload overflow protocol. When a JSON result exceeds
+ * ~50KB, `output()` (core.cjs) writes it to a private tmpfile and prints
+ * `@file:<path>` instead. The bridge reads that file back so the MCP client always
+ * receives the actual JSON. Only engine-written files under the system tmpdir named
+ * out.json are honored (the path comes from our own engine, not from tool input,
+ * but this keeps the read narrowly scoped); the tmp dir is cleaned up after read.
+ */
+function resolveOverflow(stdout) {
+  if (typeof stdout !== 'string' || !stdout.startsWith('@file:')) return stdout;
+  const real = path.resolve(stdout.slice(6).trim());
+  const tmpRoot = path.resolve(os.tmpdir());
+  if (!real.startsWith(tmpRoot + path.sep) || path.basename(real) !== 'out.json') return stdout;
+  try {
+    const text = fs.readFileSync(real, 'utf8');
+    try { fs.rmSync(path.dirname(real), { recursive: true, force: true }); } catch { /* best effort */ }
+    return text.trim();
+  } catch {
+    return stdout;
+  }
+}
+
+function rpcResult(id, result) { return { jsonrpc: '2.0', id, result }; }
+function rpcError(id, code, message) { return { jsonrpc: '2.0', id, error: { code, message } }; }
+
+function toMcpTool(t) {
+  return {
+    name: t.name, description: t.description, inputSchema: t.inputSchema,
+    annotations: { title: t.title, readOnlyHint: !!t.readOnly, destructiveHint: !!t.destructive },
+  };
+}
+function toMcpResource(r) {
+  return { uri: r.uri, name: r.name, description: r.description, mimeType: 'application/json' };
+}
+
+/**
+ * Build a server instance.
+ * @param {{panToolsPath?:string, cwd?:string, spawnImpl?:Function}} opts
+ *   spawnImpl(nodeArgs)->{ok,stdout,stderr} is injectable for tests.
+ */
+/** Shell-less git executor bound to a cwd, for native merge-gate tools. */
+function makeDefaultGit(cwd) {
+  return function git(gitArgs) {
+    try {
+      const stdout = execFileSync('git', gitArgs, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+      return { ok: true, stdout: String(stdout).trim(), stderr: '' };
+    } catch (e) {
+      return { ok: false, stdout: '', stderr: e.stderr ? String(e.stderr).trim() : (e.message || 'git failed') };
+    }
+  };
+}
+
+function createServer(opts = {}) {
+  const panToolsPath = opts.panToolsPath || process.env.PAN_TOOLS_PATH || defaultPanToolsPath();
+  const cwd = opts.cwd || process.env.PAN_PROJECT_ROOT || process.cwd();
+  const spawn = opts.spawnImpl || defaultSpawn;
+  const gitImpl = opts.gitImpl || makeDefaultGit(cwd);
+  const env = opts.env || process.env;
+
+  function runVerb(verb, extraArgs) {
+    // Defense in depth: the verb always comes from the registry, but re-check the
+    // forbidden pattern here so no future caller can smuggle a force/reset op past it.
+    if (reg.FORBIDDEN_VERB.test(verb)) {
+      return { ok: false, stdout: '', stderr: `Refused: verb "${verb}" is not permitted` };
+    }
+    // No --raw: pan-tools' default output is structured JSON (which is what the MCP
+    // client wants); --raw would instead emit a bare human scalar. Large results
+    // arrive via the @file: overflow protocol, resolved here.
+    const r = spawn([panToolsPath, verb, ...extraArgs, '--cwd', cwd]);
+    if (r && r.ok) r.stdout = resolveOverflow(r.stdout);
+    return r;
+  }
+
+  // Returns { error:{code,message} } for JSON-RPC protocol errors (unknown tool /
+  // invalid arguments — a bad *request*), or { result:{content,isError} } where
+  // isError:true signals a genuine tool *execution* failure (the verb ran and failed).
+  function callTool(name, input) {
+    const tool = reg.byToolName[name];
+    if (!tool) return { error: { code: -32602, message: `Unknown tool: ${name}` } };
+    // Native, in-process tools (orchestrator / merge gate) run a handler; a thrown
+    // Error means bad params (-32602), matching the spawn-tool validation path.
+    if (typeof tool.handler === 'function') {
+      try {
+        const out = tool.handler({ cwd, input: input || {}, env, gitImpl });
+        const text = (out && out.text != null) ? out.text : JSON.stringify(out && out.json);
+        return { result: { content: [{ type: 'text', text }], isError: !!(out && out.isError) } };
+      } catch (e) {
+        return { error: { code: -32602, message: String((e && e.message) || e) } };
+      }
+    }
+    let extra;
+    try { extra = tool.args ? tool.args(input || {}) : []; }
+    catch (e) { return { error: { code: -32602, message: String((e && e.message) || e) } }; }
+    const r = runVerb(tool.verb, extra);
+    return { result: { content: [{ type: 'text', text: r.ok ? r.stdout : (r.stderr || 'error') }], isError: !r.ok } };
+  }
+
+  // Returns { unknown:true } for an unknown uri, { error:{code,message} } for an
+  // engine failure, or { result:{contents} } on success — so handle() can emit a
+  // real JSON-RPC error instead of a success frame carrying a stderr string
+  // mislabeled as application/json.
+  function readResource(uri) {
+    const res = reg.byResourceUri[uri];
+    if (!res) return { unknown: true };
+    const r = runVerb(res.verb, []);
+    if (!r.ok) return { error: { code: -32603, message: r.stderr || 'resource read failed' } };
+    return { result: { contents: [{ uri, mimeType: 'application/json', text: r.stdout }] } };
+  }
+
+  function handle(req) {
+    if (!req || req.jsonrpc !== '2.0' || typeof req.method !== 'string') {
+      return rpcError(req && req.id != null ? req.id : null, -32600, 'Invalid Request');
+    }
+    const { id, method, params } = req;
+    // A JSON-RPC notification has no id (id=0 is a VALID request id, not a
+    // notification). The server must never reply to a notification, so bail before
+    // the dispatch — this also stops any request-method sent id-less from emitting
+    // an id-less response frame.
+    if (id === undefined || id === null) return null;
+    switch (method) {
+      case 'initialize': {
+        const requested = params && params.protocolVersion;
+        const negotiated = SUPPORTED_PROTOCOL_VERSIONS.has(requested) ? requested : PROTOCOL_VERSION;
+        return rpcResult(id, { protocolVersion: negotiated, capabilities: { tools: {}, resources: {} }, serverInfo: SERVER_INFO });
+      }
+      case 'ping':
+        return rpcResult(id, {});
+      case 'tools/list':
+        return rpcResult(id, { tools: reg.TOOLS.map(toMcpTool) });
+      case 'resources/list':
+        return rpcResult(id, { resources: reg.RESOURCES.map(toMcpResource) });
+      case 'tools/call': {
+        const out = callTool(params && params.name, params && params.arguments);
+        return out.error ? rpcError(id, out.error.code, out.error.message) : rpcResult(id, out.result);
+      }
+      case 'resources/read': {
+        const out = readResource(params && params.uri);
+        if (out.unknown) return rpcError(id, -32602, `Unknown resource: ${params && params.uri}`);
+        return out.error ? rpcError(id, out.error.code, out.error.message) : rpcResult(id, out.result);
+      }
+      default:
+        return rpcError(id, -32601, `Method not found: ${method}`);
+    }
+  }
+
+  return { handle, panToolsPath, cwd, runVerb };
+}
+
+/** Wire the server to stdin/stdout as newline-delimited JSON-RPC (MCP stdio). */
+function main() {
+  const server = createServer();
+  let buf = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => {
+    buf += chunk;
+    let nl;
+    while ((nl = buf.indexOf('\n')) >= 0) {
+      const line = buf.slice(0, nl).trim();
+      buf = buf.slice(nl + 1);
+      if (!line) continue;
+      let req;
+      try { req = JSON.parse(line); }
+      catch { process.stdout.write(JSON.stringify(rpcError(null, -32700, 'Parse error')) + '\n'); continue; }
+      const resp = server.handle(req);
+      if (resp) process.stdout.write(JSON.stringify(resp) + '\n');
+    }
+  });
+  process.stdin.on('end', () => process.exit(0));
+}
+
+if (require.main === module) main();
+
+module.exports = { createServer, defaultPanToolsPath, defaultSpawn, PROTOCOL_VERSION, SERVER_INFO, toMcpTool, toMcpResource };

package/pan-zcode/mcp/tool-registry.cjs

@@ -0,0 +1,94 @@
+'use strict';
+
+/**
+ * PAN-Z MCP tool/resource registry (M1).
+ *
+ * Maps a curated, SAFE subset of `pan-tools` verbs onto MCP tools and resources.
+ * This module is PURE — no I/O, no spawning — so the mapping and its guardrails
+ * are unit-testable in isolation. The server (server.cjs) consumes it.
+ *
+ * Read-only aggregators are exposed as MCP *resources* (cheaper, side-effect-free,
+ * quota-friendly); anything that can act is a *tool* carrying accurate hints.
+ *
+ * Inputs to a tool originate from an LLM tool-call, so each arg is validated to a
+ * strict shape before it becomes a process argument. The spawn is shell-less
+ * (execFile with an argv array — no shell, so no metacharacter risk), but we still
+ * validate early for clear errors and defense in depth.
+ */
+
+/** Validate a string arg against a whitelist regex + length bound, else throw. */
+function str(name, value, re, max = 200) {
+  if (typeof value !== 'string' || value.length === 0 || value.length > max || !re.test(value)) {
+    throw new Error(`Invalid "${name}": must match ${re} and be 1-${max} chars`);
+  }
+  return value;
+}
+
+const AGENT_RE = /^[a-z][a-z0-9_-]{1,60}$/;   // agent type, e.g. pan-planner
+const PHASE_RE = /^[0-9]{1,3}$/;              // phase number, e.g. 03
+const QUERY_RE = /^[\w .,:/&()-]{1,120}$/;    // find-phase query fragment
+
+/** Read-only aggregators → MCP resources (no side effects). */
+const RESOURCES = [
+  { uri: 'pan://state',    name: 'Project state', verb: 'state',    description: 'Current PAN project state snapshot derived from .planning/.' },
+  { uri: 'pan://roadmap',  name: 'Roadmap',       verb: 'roadmap',  description: 'The project roadmap: phases, goals, success criteria.' },
+  { uri: 'pan://phases',   name: 'Phases',        verb: 'phases',   description: 'Phase inventory with per-phase status.' },
+  { uri: 'pan://progress', name: 'Progress',      verb: 'progress', description: 'Requirement and plan completion progress.' },
+];
+
+/** Actionable pan-tools verbs → MCP tools (each spawns `node pan-tools.cjs <verb>`). */
+const SPAWN_TOOLS = [
+  {
+    name: 'pan_resolve_model', title: 'Resolve model for an agent', verb: 'resolve-model',
+    description: 'Resolve the model tier/id PAN would use for an agent under the active profile.',
+    readOnly: true, destructive: false,
+    inputSchema: {
+      type: 'object', additionalProperties: false, required: ['agent'],
+      properties: { agent: { type: 'string', description: 'Agent type, e.g. pan-planner' } },
+    },
+    args: (i) => [str('agent', i && i.agent, AGENT_RE, 64)],
+  },
+  {
+    name: 'pan_find_phase', title: 'Find a phase', verb: 'find-phase',
+    description: 'Locate a phase directory by number or slug fragment.',
+    readOnly: true, destructive: false,
+    inputSchema: {
+      type: 'object', additionalProperties: false, required: ['query'],
+      properties: { query: { type: 'string', description: 'Phase number or slug fragment' } },
+    },
+    args: (i) => [str('query', i && i.query, QUERY_RE, 120)],
+  },
+  {
+    name: 'pan_report_phase', title: 'Generate a phase HTML report', verb: 'report',
+    description: 'Render the self-contained HTML report for one phase (a build deliverable). Writes only its own file; non-destructive and idempotent.',
+    readOnly: false, destructive: false,
+    inputSchema: {
+      type: 'object', additionalProperties: false, required: ['phase'],
+      properties: { phase: { type: 'string', description: 'Phase number, e.g. 03' } },
+    },
+    args: (i) => ['phase', str('phase', i && i.phase, PHASE_RE, 3)],
+  },
+];
+
+/**
+ * Guardrail: this bridge must NEVER expose a history-rewriting or force git op.
+ * merge/commit verbs arrive in M2 behind the deterministic human-token gate, and
+ * force-push/reset/rebase are never exposed at all (recovery is revert-only).
+ */
+const FORBIDDEN_VERB = /(^|-)(push|reset|rebase|force)($|-)/;
+
+// Native, in-process tools (M2: orchestrator + merge gate) join the spawn-backed
+// tools into one advertised list. Required after SPAWN_TOOLS/FORBIDDEN_VERB so the
+// native module (which imports nothing back from here) composes cleanly — no cycle.
+const { NATIVE_TOOLS } = require('./native-tools.cjs');
+const TOOLS = [...SPAWN_TOOLS, ...NATIVE_TOOLS];
+
+const byToolName = Object.create(null);
+for (const t of TOOLS) byToolName[t.name] = t;
+const byResourceUri = Object.create(null);
+for (const r of RESOURCES) byResourceUri[r.uri] = r;
+
+module.exports = {
+  TOOLS, SPAWN_TOOLS, NATIVE_TOOLS, RESOURCES, byToolName, byResourceUri, FORBIDDEN_VERB,
+  AGENT_RE, PHASE_RE, QUERY_RE, str,
+};