@pellux/goodvibes-tui 1.20.0 → 1.21.0

package/CHANGELOG.md

@@ -4,6 +4,25 @@ All notable changes to GoodVibes TUI.
 
 ---
 
+## [1.21.0] - 2026-07-25
+
+### Changes
+
+Fixed: the reasoning effort level you choose is no longer lowered permanently by one model. Your configured level is kept as you set it, the runtime uses whatever the current model can actually deliver, and switching back to a capable model restores your level. The display shows both values and says when a model is the reason your level is capped.
+Fixed: the notice explaining that a failover snapped your reasoning level down was being deleted from the transcript by the retry path on every failover, so nobody ever saw it. The notice now stays.
+Fixed: markdown tables no longer silently drop trailing columns — including headers — when the terminal is too narrow for the column count. A table that cannot fit is now stacked as "Header: value" records so every column is still readable.
+Fixed: config file changes are no longer silently lost when the write lands while the settings watcher is still starting up.
+Fixed: saved state now gets real housekeeping when it is recovered — stale entries are reaped, growth is bounded, contents are checked rather than assumed from the file merely existing, and anything removed is disclosed instead of vanishing. An interrupted migration no longer strands your older sessions out of reach.
+Fixed: published packages no longer silently omit the bundled agent and skill content. A packaging rule change dropped those files from the tarball on newer npm versions; installs now get the complete set again.
+Updated: bundled platform runtime to 1.13.1, which adds Telegram inbound messaging and the per-model reasoning effort model behind these changes.
+
+## [1.20.1] - 2026-07-25
+
+### Changes
+
+- fd3b3037 fix: recovery offers and removals behave; active-model surfaces agree; failover is visible and temporary
+- 08237438 docs: replace README screenshots with true terminal captures
+
 ## [1.20.0] - 2026-07-24
 
 ### Changes
@@ -469,7 +488,7 @@ Updated: @pellux/goodvibes-sdk and @pellux/goodvibes-terminal-shell to 1.11.3 (q
 ### Changes
 - 9dbd88e4 fix(daemon): attach handlers for every ws-only gateway verb — fleet.*, checkpoints.*, sessions.search, push.* were 501 on every vendored daemon build
 
-## [1.13.0] — 2026-07-09
+## [1.13.1] — 2026-07-09
 
 ### Changes
 - c3a54b1b fix: clean terminal restore on exit; feat: /resume session picker

package/README.md

@@ -2,11 +2,11 @@
 
 [![CI](https://github.com/mgd34msu/goodvibes-tui/actions/workflows/ci.yml/badge.svg)](https://github.com/mgd34msu/goodvibes-tui/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Version](https://img.shields.io/badge/version-1.20.0-blue.svg)](https://github.com/mgd34msu/goodvibes-tui)
+[![Version](https://img.shields.io/badge/version-1.21.0-blue.svg)](https://github.com/mgd34msu/goodvibes-tui)
 
 GoodVibes is a terminal console for coding and operations work with an AI model. You run `goodvibes` in a project directory and get a full-screen terminal app where you talk to a model that can read and edit your files, run shell commands, search the web, and hand work off to background agents — asking your permission before anything that writes or executes. It talks to many model providers (OpenAI, Anthropic, Gemini, Bedrock, Copilot, OpenRouter and other OpenAI-compatible gateways, plus local servers like Ollama and LM Studio that it finds on startup), keeps its settings, sessions, and secrets on your own machine, and shows you the token count and running cost of every turn. Alongside the conversation, panels turn background work — running agents, git state, diffs, tokens, cost — into live control rooms.
 
-<img src="docs/assets/splash.png" alt="GoodVibes starting up in a terminal: a glitch-art GOODVIBES wordmark in cyan-to-magenta gradient, the version and tagline beneath it, the active model and tool count, the working directory, and a hint line reading Ctrl+P panels / ? help / F2 fleet. A status footer shows mode, token usage, context usage, and the daemon and web listener addresses." width="900">
+<img src="docs/assets/splash.png" alt="GoodVibes starting up in a terminal: a glitch-art GOODVIBES wordmark in cyan-to-magenta gradient, the version and tagline beneath it, the active model and tool count, the working directory, a line offering to resume the last session, and a hint line reading Ctrl+P panels / ? help / F2 fleet. A status footer shows mode, token usage, context usage, and the daemon and web listener addresses." width="900">
 
 ---
 
@@ -45,7 +45,7 @@ Deeper install notes — the installer's environment variables, uninstall, daemo
 
 ### The conversation loop
 
-<img src="docs/assets/conversation.png" alt="A conversation turn in the terminal. The user asks the model to read two source files and explain the project. Below it, an assistant block lists two read tool calls with green checkmarks, followed by a collapsed group labelled tool results, 2 tools, 2 lines. A second assistant block makes one more read call. The final answer is plain prose with an identifier syntax-highlighted in yellow. The footer reads Token Usage: Input 41.3k, Output 337, Cache Read 0, Cache Write 0, Total 41.6k, approximately 0.129 dollars, above a green context usage bar at 5 percent." width="900">
+<img src="docs/assets/conversation.png" alt="Two conversation turns in the terminal. The tail of an earlier answer describes the project as a minimal ISS pass tracker whose calculation is still a stub. Below it the user asks the model to grep for nextPass and list every file that references it; an assistant block shows one find tool call with a green checkmark, and its result is expanded as syntax-highlighted JSON with line numbers listing the two matching file paths and a count of 2. The final answer names src/passes.ts and src/index.ts as a bulleted list. The footer reads Token Usage: Input em dash, Output 264, Cache Read 0, Cache Write 0, Total 264, approximately 0.0040 dollars, above a green context usage bar at 4 percent." width="900">
 
 Tool calls stream inline as the model makes them, then their results fold into a collapsible group so a long working session stays readable — expand any group to see what actually came back. Assistant messages render markdown, syntax-highlighted code, and inline diffs, and any block can be collapsed, bookmarked, copied, or saved to a file.
 
@@ -57,13 +57,13 @@ The footer keeps an honest running total: fresh input tokens separated from cach
 
 The first time you open a directory, GoodVibes asks how much it is allowed to do there. Restricted is read-only: the model can look around, but writes and commands are refused until you trust the workspace.
 
-<img src="docs/assets/permission-prompt.png" alt="An execution approval prompt. A header reads EXECUTE, Shell Execution Approval. Fields list the requesting session, the tool exec, the full command, the working directory, a Risk line reading HIGH write in red, the surface and radius, a summary, the effects: process execution, filesystem mutation, possible network access, and a reviewer checklist. Below, four numbered remember options scope an approval to this exact command, to every mkdir command, to every exec call in this project, or to the rest of the session in memory only. The action line reads: Y Allow once, 1-4 Allow and remember, N Deny, or type a reason to deny." width="900">
+<img src="docs/assets/permission-prompt.png" alt="An execution approval prompt. A header reads EXECUTE, Shell Execution Approval, one more waiting. Fields list the requesting session, the tool exec, the full command mkdir -p build, the working directory, a Risk line reading HIGH write in red, the surface and radius, a summary, the decision class, the effects: process execution, filesystem mutation, possible network access, a reviewer checklist, and the raw tool arguments. Below, four numbered remember options scope an approval to this exact command, to every mkdir command, to every exec call in this project, or to the rest of the session in memory only. The action line reads: Y Allow once, 1-4 Allow and remember, N Deny, or type a reason to deny." width="900">
 
 After that, the default permission mode is `prompt`: writes, edits, shell commands, network fetches, agent spawns, and MCP calls each stop and ask. The prompt shows what will run, in which directory, its assessed risk, and what it can affect. You can allow it once, deny it (optionally typing a reason the model sees), or remember the decision at whichever scope fits — this exact command, this command shape, this tool for the whole project, or just for the rest of the session. Four other modes are available when prompting is not what you want: `accept-edits` auto-approves file writes and edits while exec and the other risky classes still ask, `plan` allows read-only tools and refuses every mutating or exec call, `allow-all` approves everything, and `custom` takes per-tool `allow` / `prompt` / `deny` overrides. `Shift+Tab` cycles the four session postures — normal, accept-edits, plan, auto — and `/plan` toggles plan mode directly.
 
 ### Models and providers
 
-<img src="docs/assets/model-picker.png" alt="A fullscreen model workspace. A left column lists routing targets: Main Chat set, Helper Model off, Tool LLM off, TTS LLM inherit, and Embeddings set. The right pane shows the selected target with its current model and a filter row for search, price, capability, grouping, and availability. Below, a table of models lists model key, display name, provider, context window, tier, and capability flags across 2017 catalogued entries, with a footer of list shortcuts." width="900">
+<img src="docs/assets/model-picker.png" alt="A fullscreen model workspace. A left column lists routing targets: Main Chat set, Helper Model off, Tool LLM off, TTS LLM inherit, and Embeddings set. The right pane shows the selected target with its current model and a filter row for search, price, capability, grouping, and availability. Below, a table of models lists model key, display name, provider, context window, tier, and capability flags across 2030 catalogued entries, with a footer of list shortcuts." width="900">
 
 Models come from a live catalog, so the picker lists far more than a hardcoded set, filterable by search, price, capability, and availability. Separate roles route independently: your main chat model, a cheaper helper model for grunt work, a tool model, a TTS model, and an embeddings model can each point somewhere different.
 
@@ -71,13 +71,13 @@ The `synthetic` provider groups the same model across every backend that serves
 
 ### The Fleet control room
 
-<img src="docs/assets/fleet-panel.png" alt="The Fleet panel open beside the conversation. It lists background work as rows with a kind, a name, elapsed time, token count, and cost — a CI watch poller and a runtime health watcher at 59 seconds each, and a code indexer. The detail region below shows the selected watcher's id, state idle, elapsed time, model, tokens, cost, a headline reading CI watch poller, healthy, an activity phase, and an approvals line. The action hints read j/k navigate, Enter attach, K kill, A archive finish." width="900">
+<img src="docs/assets/fleet-panel.png" alt="The Fleet panel open beside the conversation. It lists background work as rows with a kind, a name, elapsed time, token count, and cost — a CI watch poller and a runtime heartbeat watcher at 4 minutes 23 seconds each, and an idle code indexer. The detail region below shows the selected watcher's id, state idle, elapsed time, model, tokens, cost, a headline reading CI watch poller, healthy, an activity phase, and an approvals line. The action hints read j/k navigate, Enter attach, K kill, A archive finished, v archived, n host agent." width="900">
 
 Work that is not conversation goes into panels instead of scrolling past in the transcript. Fleet — reached with `F2` — is the live control room for agents, workstreams, watchers, and scheduled jobs: what is running, for how long, at what token cost, and what it is waiting on. You can attach to a running agent to watch or steer it, detach again without killing it, pause and resume, and archive finished work. Git, diff, cost, token, and local-auth panels sit alongside it; heavier operator surfaces open as review modals.
 
 ### Everything else is a command
 
-<img src="docs/assets/help-overlay.png" alt="A searchable help overlay titled Help, Commands, with a search field and results grouped by category. Under Provider Accounts is the /accounts command with review, panel, show, routes, and repair subcommands and a one-line description. Under Fleet is /agents, described as hosting third-party coding agents as fleet rows over ACP. A line reads 146 below, and the hints read Up/Down Navigate, Enter Run, / Search, Esc Close." width="820">
+<img src="docs/assets/help-overlay.png" alt="A searchable help overlay titled Help, Commands, with a search field and results grouped by category. Under Provider Accounts is the /accounts command with review, panel, show, routes, and repair subcommands and a one-line description. Under Fleet is /agents, described as hosting third-party coding agents as fleet rows over ACP. Under Experience is /approval, for reviewing action-specific approval classes. A line reads 147 below, and the hints read Up/Down Navigate, Enter Run, / Search, Esc Close." width="820">
 
 Press `?` for a searchable, categorized list of every slash command with its arguments and description. The same list is generated into [docs/commands-reference.md](docs/commands-reference.md).
 

package/docs/foundation-artifacts/operator-contract.json

@@ -3,7 +3,7 @@
   "product": {
     "id": "goodvibes",
     "surface": "operator",
-    "version": "1.12.0"
+    "version": "1.13.1"
   },
   "auth": {
     "modes": [
@@ -4714,10 +4714,14 @@
                       "reasoningEffort": {
                         "type": "string",
                         "enum": [
+                          "none",
                           "instant",
+                          "minimal",
                           "low",
                           "medium",
-                          "high"
+                          "high",
+                          "xhigh",
+                          "max"
                         ]
                       },
                       "thinking": {
@@ -6344,10 +6348,14 @@
                 "reasoningEffort": {
                   "type": "string",
                   "enum": [
+                    "none",
                     "instant",
+                    "minimal",
                     "low",
                     "medium",
-                    "high"
+                    "high",
+                    "xhigh",
+                    "max"
                   ]
                 },
                 "thinking": {
@@ -7332,10 +7340,14 @@
                       "reasoningEffort": {
                         "type": "string",
                         "enum": [
+                          "none",
                           "instant",
+                          "minimal",
                           "low",
                           "medium",
-                          "high"
+                          "high",
+                          "xhigh",
+                          "max"
                         ]
                       },
                       "thinking": {
@@ -8712,10 +8724,14 @@
                 "reasoningEffort": {
                   "type": "string",
                   "enum": [
+                    "none",
                     "instant",
+                    "minimal",
                     "low",
                     "medium",
-                    "high"
+                    "high",
+                    "xhigh",
+                    "max"
                   ]
                 },
                 "thinking": {
@@ -9637,10 +9653,14 @@
                     "reasoningEffort": {
                       "type": "string",
                       "enum": [
+                        "none",
                         "instant",
+                        "minimal",
                         "low",
                         "medium",
-                        "high"
+                        "high",
+                        "xhigh",
+                        "max"
                       ]
                     },
                     "thinking": {
@@ -10648,10 +10668,14 @@
                     "reasoningEffort": {
                       "type": "string",
                       "enum": [
+                        "none",
                         "instant",
+                        "minimal",
                         "low",
                         "medium",
-                        "high"
+                        "high",
+                        "xhigh",
+                        "max"
                       ]
                     },
                     "thinking": {
@@ -11763,10 +11787,14 @@
                       "reasoningEffort": {
                         "type": "string",
                         "enum": [
+                          "none",
                           "instant",
+                          "minimal",
                           "low",
                           "medium",
-                          "high"
+                          "high",
+                          "xhigh",
+                          "max"
                         ]
                       },
                       "thinking": {
@@ -12775,10 +12803,14 @@
                     "reasoningEffort": {
                       "type": "string",
                       "enum": [
+                        "none",
                         "instant",
+                        "minimal",
                         "low",
                         "medium",
-                        "high"
+                        "high",
+                        "xhigh",
+                        "max"
                       ]
                     },
                     "thinking": {
@@ -14036,10 +14068,14 @@
                 "reasoningEffort": {
                   "type": "string",
                   "enum": [
+                    "none",
                     "instant",
+                    "minimal",
                     "low",
                     "medium",
-                    "high"
+                    "high",
+                    "xhigh",
+                    "max"
                   ]
                 },
                 "thinking": {
@@ -15005,10 +15041,14 @@
                       "reasoningEffort": {
                         "type": "string",
                         "enum": [
+                          "none",
                           "instant",
+                          "minimal",
                           "low",
                           "medium",
-                          "high"
+                          "high",
+                          "xhigh",
+                          "max"
                         ]
                       },
                       "thinking": {
@@ -15898,10 +15938,14 @@
                       "reasoningEffort": {
                         "type": "string",
                         "enum": [
+                          "none",
                           "instant",
+                          "minimal",
                           "low",
                           "medium",
-                          "high"
+                          "high",
+                          "xhigh",
+                          "max"
                         ]
                       },
                       "thinking": {
@@ -80001,10 +80045,14 @@
                 "reasoningEffort": {
                   "type": "string",
                   "enum": [
+                    "none",
                     "instant",
+                    "minimal",
                     "low",
                     "medium",
-                    "high"
+                    "high",
+                    "xhigh",
+                    "max"
                   ]
                 }
               },
@@ -80449,10 +80497,14 @@
                     "reasoningEffort": {
                       "type": "string",
                       "enum": [
+                        "none",
                         "instant",
+                        "minimal",
                         "low",
                         "medium",
-                        "high"
+                        "high",
+                        "xhigh",
+                        "max"
                       ]
                     }
                   },
@@ -81015,10 +81067,14 @@
                     "reasoningEffort": {
                       "type": "string",
                       "enum": [
+                        "none",
                         "instant",
+                        "minimal",
                         "low",
                         "medium",
-                        "high"
+                        "high",
+                        "xhigh",
+                        "max"
                       ]
                     }
                   },
@@ -81281,10 +81337,14 @@
                     "reasoningEffort": {
                       "type": "string",
                       "enum": [
+                        "none",
                         "instant",
+                        "minimal",
                         "low",
                         "medium",
-                        "high"
+                        "high",
+                        "xhigh",
+                        "max"
                       ]
                     }
                   },
@@ -81699,10 +81759,14 @@
                       "reasoningEffort": {
                         "type": "string",
                         "enum": [
+                          "none",
                           "instant",
+                          "minimal",
                           "low",
                           "medium",
-                          "high"
+                          "high",
+                          "xhigh",
+                          "max"
                         ]
                       }
                     },
@@ -82147,10 +82211,14 @@
                 "reasoningEffort": {
                   "type": "string",
                   "enum": [
+                    "none",
                     "instant",
+                    "minimal",
                     "low",
                     "medium",
-                    "high"
+                    "high",
+                    "xhigh",
+                    "max"
                   ]
                 }
               },
@@ -82617,10 +82685,14 @@
                         "reasoningEffort": {
                           "type": "string",
                           "enum": [
+                            "none",
                             "instant",
+                            "minimal",
                             "low",
                             "medium",
-                            "high"
+                            "high",
+                            "xhigh",
+                            "max"
                           ]
                         }
                       },
@@ -84091,10 +84163,14 @@
                 "reasoningEffort": {
                   "type": "string",
                   "enum": [
+                    "none",
                     "instant",
+                    "minimal",
                     "low",
                     "medium",
-                    "high"
+                    "high",
+                    "xhigh",
+                    "max"
                   ]
                 }
               },
@@ -84542,10 +84618,14 @@
                     "reasoningEffort": {
                       "type": "string",
                       "enum": [
+                        "none",
                         "instant",
+                        "minimal",
                         "low",
                         "medium",
-                        "high"
+                        "high",
+                        "xhigh",
+                        "max"
                       ]
                     }
                   },
@@ -85977,10 +86057,14 @@
                 "reasoningEffort": {
                   "type": "string",
                   "enum": [
+                    "none",
                     "instant",
+                    "minimal",
                     "low",
                     "medium",
-                    "high"
+                    "high",
+                    "xhigh",
+                    "max"
                   ]
                 }
               },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pellux/goodvibes-tui",
-  "version": "1.20.0",
+  "version": "1.21.0",
   "description": "Terminal-native GoodVibes product for coding, operations, automation, knowledge, channels, and daemon-backed control-plane workflows.",
   "type": "module",
   "main": "src/main.ts",
@@ -104,8 +104,8 @@
     "@anthropic-ai/vertex-sdk": "^0.16.0",
     "@ast-grep/napi": "^0.42.0",
     "@aws/bedrock-token-generator": "^1.1.0",
-    "@pellux/goodvibes-sdk": "1.12.0",
-    "@pellux/goodvibes-terminal-shell": "1.12.0",
+    "@pellux/goodvibes-sdk": "1.13.1",
+    "@pellux/goodvibes-terminal-shell": "1.13.1",
     "bash-language-server": "^5.6.0",
     "fuse.js": "^7.1.0",
     "graphql": "^16.13.2",
@@ -131,10 +131,10 @@
     "typescript": "^5.9.3"
   },
   "optionalDependencies": {
-    "@pellux/goodvibes-tui-linux-x64": "1.20.0",
-    "@pellux/goodvibes-tui-linux-arm64": "1.20.0",
-    "@pellux/goodvibes-tui-darwin-x64": "1.20.0",
-    "@pellux/goodvibes-tui-darwin-arm64": "1.20.0"
+    "@pellux/goodvibes-tui-linux-x64": "1.21.0",
+    "@pellux/goodvibes-tui-linux-arm64": "1.21.0",
+    "@pellux/goodvibes-tui-darwin-x64": "1.21.0",
+    "@pellux/goodvibes-tui-darwin-arm64": "1.21.0"
   },
   "trustedDependencies": [],
   "overrides": {

package/src/cli/bundle-command.ts

@@ -12,7 +12,7 @@ import type { ConfigKey } from '../config/index.ts';
 import type { CliCommandRuntime } from './types.ts';
 import type { CliCommandOutput } from './types.ts';
 import { getPackageVersion } from './help.ts';
-import { classifyProviderSetup } from './provider-classification.ts';
+import { classifyProviderSetup } from '../providers/provider-classification.ts';
 import { buildCliServicePosture } from './service-posture.ts';
 import { REDACTED_VALUE, collectSensitiveConfigValues, isRedactedValue, redactConfig, redactSerializedSecrets } from './redaction.ts';
 import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';

package/src/cli/doctor.ts

@@ -3,6 +3,7 @@ import { PermissionManager, createPermissionConfigReader } from '@pellux/goodvib
 import type { PermissionCategory, PermissionCheckResult } from '@pellux/goodvibes-sdk/platform/permissions';
 import { PolicyRuntimeState, createFeatureFlagManager, deriveFeatureStates } from '@/runtime/index.ts';
 import { getProviderIdFromModel } from '../config/provider-model.ts';
+import { describeConfiguredEffort } from '../providers/reasoning-effort-surface.ts';
 import type { CliCommandOutput } from './types.ts';
 import type { GoodVibesCliOutputFormat } from './types.ts';
 import { buildHooksValidation } from './hooks-report.ts';
@@ -263,7 +264,12 @@ function buildRoutingRoles(config: ConfigManager): RoutingRole[] {
       provider: mainProvider,
       model: mainModel || '(unset)',
       keys: ['provider.model', 'provider.reasoningEffort'],
-      note: `reasoningEffort=${String(config.get('provider.reasoningEffort') ?? '')}`,
+      // Both halves: the level that is configured, and what that level
+      // actually becomes on this model. They differ whenever the model does
+      // not offer the configured level, and a doctor report that printed only
+      // the first would hide exactly the mismatch it exists to find.
+      note: `reasoningEffort=${String(config.get('provider.reasoningEffort') ?? '')}`
+        + ` -> ${describeConfiguredEffort(mainModel, String(config.get('provider.reasoningEffort') ?? ''))}`,
     },
     {
       role: 'Embeddings',

package/src/cli/management.ts

@@ -13,7 +13,7 @@ import { beginOpenAICodexLogin, exchangeOpenAICodexCode } from '@pellux/goodvibe
 import { inspectProviderAuth } from '@/runtime/index.ts';
 import type { CliCommandRuntime, GoodVibesCliParseResult } from './types.ts';
 import { formatProviderAuthRoute, summarizeProviderAuthRoutes } from './provider-auth-routes.ts';
-import { classifyProviderSetup } from './provider-classification.ts';
+import { classifyProviderSetup } from '../providers/provider-classification.ts';
 import { resolveRuntimeEndpointBinding } from './endpoints.ts';
 import { applyRuntimeEndpointFlagOverrides } from './config-overrides.ts';
 import type { RuntimeEndpointId } from './endpoints.ts';

package/src/cli/package-verification.ts

@@ -68,18 +68,103 @@ function verifyBin(root: string, command: typeof REQUIRED_BIN_COMMANDS[number],
   };
 }
 
-function npmPackDryRun(root: string): { readonly files: readonly string[]; readonly entryCount: number; readonly unpackedSize: number } {
+export interface NpmPackDryRunResult {
+  readonly files: readonly string[];
+  readonly entryCount: number;
+  readonly unpackedSize: number;
+}
+
+interface NpmPackJsonEntry {
+  readonly files?: ReadonlyArray<{ readonly path?: string } | null>;
+  readonly entryCount?: number;
+  readonly unpackedSize?: number;
+}
+
+function describeNpmPackOutput(raw: string): string {
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) return 'no output at all';
+  const preview = trimmed.length > 400 ? `${trimmed.slice(0, 400)}...` : trimmed;
+  return `${trimmed.length} characters of output beginning: ${preview}`;
+}
+
+// npm wrappers (version-manager shims, "npm notice" lines) sometimes print plain text
+// on stdout alongside the JSON document. Take the first balanced JSON value and ignore
+// whatever surrounds it, tracking string literals so braces inside paths do not confuse
+// the depth count.
+function extractJsonDocument(raw: string): string | undefined {
+  const start = raw.search(/[[{]/);
+  if (start < 0) return undefined;
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  for (let index = start; index < raw.length; index += 1) {
+    const char = raw[index];
+    if (inString) {
+      if (escaped) escaped = false;
+      else if (char === '\\') escaped = true;
+      else if (char === '"') inString = false;
+      continue;
+    }
+    if (char === '"') {
+      inString = true;
+      continue;
+    }
+    if (char === '[' || char === '{') depth += 1;
+    else if (char === ']' || char === '}') {
+      depth -= 1;
+      if (depth === 0) return raw.slice(start, index + 1);
+    }
+  }
+  return undefined;
+}
+
+function looksLikePackEntry(value: unknown): value is NpmPackJsonEntry {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const candidate = value as Record<string, unknown>;
+  return Array.isArray(candidate.files) || typeof candidate.entryCount === 'number' || typeof candidate.unpackedSize === 'number';
+}
+
+function selectPackEntry(parsed: unknown): NpmPackJsonEntry | undefined {
+  // npm 10/11 emit `[{ files, entryCount, unpackedSize }]`.
+  if (Array.isArray(parsed)) return parsed.find(looksLikePackEntry);
+  // npm 12 emits `{ "<package-name>": { files, entryCount, unpackedSize } }`.
+  if (looksLikePackEntry(parsed)) return parsed;
+  if (parsed && typeof parsed === 'object') return Object.values(parsed as Record<string, unknown>).find(looksLikePackEntry);
+  return undefined;
+}
+
+export function parseNpmPackJson(raw: string): NpmPackDryRunResult {
+  const document = extractJsonDocument(raw);
+  if (document === undefined) {
+    throw new Error(`npm pack --json --dry-run printed no JSON document; npm emitted ${describeNpmPackOutput(raw)}`);
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(document);
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new Error(`npm pack --json --dry-run printed JSON that could not be parsed (${reason}); npm emitted ${describeNpmPackOutput(raw)}`);
+  }
+  const entry = selectPackEntry(parsed);
+  if (!entry) {
+    throw new Error(
+      `npm pack --json --dry-run returned an unrecognized JSON shape; expected an array of pack results or an object keyed by package name, but npm emitted ${describeNpmPackOutput(raw)}`,
+    );
+  }
+  return {
+    files: Array.isArray(entry.files) ? entry.files.map((file) => String(file?.path ?? '')) : [],
+    entryCount: Number(entry.entryCount ?? 0),
+    unpackedSize: Number(entry.unpackedSize ?? 0),
+  };
+}
+
+function npmPackDryRun(root: string): NpmPackDryRunResult {
   const raw = execSync('npm pack --json --dry-run', {
     cwd: root,
     encoding: 'utf-8',
     stdio: ['ignore', 'pipe', 'inherit'],
   });
-  const [packResult] = JSON.parse(raw) as Array<{ files?: Array<{ path?: string }>; entryCount?: number; unpackedSize?: number }>;
-  return {
-    files: Array.isArray(packResult?.files) ? packResult.files.map((entry) => String(entry.path ?? '')) : [],
-    entryCount: Number(packResult?.entryCount ?? 0),
-    unpackedSize: Number(packResult?.unpackedSize ?? 0),
-  };
+  return parseNpmPackJson(raw);
 }
 
 export function verifyPackageCliInstall(root: string): PackageCliVerificationReport {