@groeponline/pi-wishcraft 1.15.0 → 1.16.0

package/AGENTS.md

@@ -252,6 +252,8 @@ function createRuntimeState(hooks: {
 | **Circular import check** | `madge --circular src index.ts bash-mode queue` (via `npm run circular`) |
 | **Import style** | `.ts` extensions on all imports, `node:`-prefixed builtins |
 | **Pi CLI** | Installed at `^0.99.2` (`pi-coding-agent`, `pi-ai`, `pi-tui` move together — the agent depends on matching `pi-ai`/`pi-tui`, so bumping one alone splits the tree); wrapped to run under Node 24 via nvm |
+| **Peer floor** | `peerDependencies` are `"*"` for the three Pi packages because Pi's own docs require it ("declare the host-provided packages listed above in peerDependencies with a `*` range"), and `scripts/verify-pi-package-contract.mjs` enforces it. `"*"` therefore cannot express a floor, so the real one is only enforced by the code using the SDK: `normalizeContext` (added in `pi-ai` 0.86.0, used by `src/working-vibes/provider.ts`) is the binding symbol — probed across every SDK release, all 12 runtime symbols resolve from 0.86.0 up. A consumer on 0.84.3 installs without warning, but the activation-time peer guard (`src/extension/core/peer-guard.ts`) names every missing symbol with its feature and floor, notifies at session start, and turns the `/vibe` failure into an actionable error; `tests/peer-guard.test.ts` keeps the guarded catalog in sync with the published import surface in both directions. |
+| **Dependency audit** | `npm run audit` (`scripts/audit-gate.mjs`) is the gate. `audit-baseline.json` lists accepted advisories, each pinned to its GHSA id **and** the install path(s) it covers, with a required written reason; new high/critical advisories fail even on an already-accepted package, a second vulnerable copy of an accepted package fails, a baselined advisory that stops reporting as high/critical also fails, an `npm audit` that errors out fails the gate instead of reading as "zero findings", and the baseline is excluded from the published tarball. |
 | **Docker** | `fuse-overlayfs` storage driver for nested VM testing |
 | **Compound Engineering** | `.compound-engineering/` overlay; portable skills via `~/.agents/skills/ce-*`; native Cursor plugin disabled |
 

package/CHANGELOG.md

@@ -2,11 +2,24 @@
 
 ## [Unreleased]
 
+## [1.16.0] - 2026-10-03
+
+### Known limitations
+- **`peerDependencies: "*"` cannot express a supported-version floor.** Pi's own docs require the host-provided packages to be declared with a `"*"` range and `verify-pi-package-contract.mjs` enforces it, so the constraint is upstream and cannot be tightened here. The consequence is measured rather than assumed: probing every SDK release for the 12 runtime symbols this package imports, all of them resolve from 0.86.0 up, and the binding one is `normalizeContext` (`src/working-vibes/provider.ts`), which arrived in `pi-ai` 0.86.0. A consumer on 0.84.3 therefore installs this package without warning or resolution error. The manifest side of this stays open — the floor cannot be expressed there at all — but the silent failure is closed: the extension now checks the symbol set at activation and reports the gap (see Fixed).
+
+### Fixed
+- **A Pi SDK below 0.86.0 broke `/vibe` with a bare `TypeError`.** `peerDependencies` are `"*"` by upstream contract, so an old host installs this package without complaint and the breakage surfaced as "normalizeContext is not a function" at the first `/vibe` call. The extension now checks the runtime symbol set it actually imports from the three Pi peers at activation (`src/extension/core/peer-guard.ts`): every missing symbol is named with the feature that depends on it and the version floor to upgrade to, the first session surfaces the same as a UI notification, and the `/vibe` call site fails with that actionable message instead of a TypeError. The guard checks symbol presence rather than version strings because symbols are what the code depends on — a semver comparison would lie across backports or version-skewed trees. `tests/peer-guard.test.ts` keeps the guarded catalog in exact sync with the runtime imports of every published source file in both directions: a newly used SDK symbol that is not guarded fails the suite, as does a catalog entry nothing imports anymore. Each guard was verified against an injected regression rather than only against the passing state.
+- **The dependency audit could never fail CI, so it caught nothing.** The step ran `npm audit --audit-level=high` behind `continue-on-error: true`, labelled "informational" — and it exits 1 today, because of the one finding below. A step that cannot fail is a step that also cannot fail on anything *new*: the `ws@7.5.10` advisory, or the next one, would have shipped silently. The same shape as the coverage gate that printed thresholds while collecting no coverage. `npm run audit` (`scripts/audit-gate.mjs`) now audits against `audit-baseline.json`: a new high or critical advisory fails, the justified inherited advisories are tolerated, a baselined advisory that stops reporting as high/critical fails too (so it cannot become a permanent blanket exemption), and every accepted entry must carry a written reason naming the mechanism that makes it unreachable, its GHSA id, and the install path(s) it covers — so neither a new advisory nor a second vulnerable copy of the same package inherits the exemption. An `npm audit` that errors out (registry down, npm config policy) fails the gate rather than reading as "zero findings". Verified by injecting `ws@7.5.10` into the real tree — the gate named it as new and blocked while still passing the baselined finding.
+- `audit-baseline.json` was shipping inside the npm tarball: `files` contains a `*.json` glob, so a new root-level JSON file is published by default. Excluded, and `tests/audit-gate.test.ts` now reads the real `npm pack` output rather than trusting the `files` array.
+- **The remaining `npm audit` finding was half ours.** The 1.15.0 note recorded that `brace-expansion` "has no fix available at any installable version" — that was wrong on both counts, and it buried a fixable bug under a false exemption. There are two copies in the tree and they have different causes. The top-level one (pulled in via `madge` → `minimatch`) was sitting on 5.0.9 through a stale lockfile pin and is ours: it is now 5.0.12. The copy nested under `@earendil-works/pi-coding-agent` really is out of reach, but not because no fix exists — `brace-expansion@5.0.12` satisfies the `^5.0.8` range the peer's own `minimatch` declares, so the peer can fix it with a lockfile bump alone, no API change. It is unreachable from here for a different reason: the peer publishes an `npm-shrinkwrap.json`, which is authoritative for consumers, and npm installs that pinned tree verbatim without re-resolving it. Confirmed empirically that `overrides` cannot reach it — both a top-level `"brace-expansion": "^5.0.12"` and a path-scoped `"@earendil-works/pi-coding-agent": { "brace-expansion": "^5.0.12" }` left the nested copy at 5.0.9 — so no override is shipped rather than one that would advertise a guarantee it cannot keep.
+- `tests/dependency-provenance.test.ts` guards the distinction: it fails if a vulnerable copy appears anywhere outside the peer's subtree (that one is ours, and names `npm audit fix`), if an unreachable override is ever added, and if the peer's shrinkwrap moves to a fixed version (the finding is then gone and the CHANGELOG needs updating). Each guard was verified against an injected regression rather than only against the passing state. The same file now also guards the general shape: we ship no shrinkwrap ourselves, an `overrides` entry never targets a package that ships one (such an override is a silent no-op), and every baselined advisory names a mechanism rather than just asserting "inherited".
+- Audited the rest of the tree for the same pattern and found no second exemption: one high finding total, no deprecated packages, all 346 registry signatures and 90 attestations verified. A synthetic consumer install (`pi-wishcraft@1.15.0` alongside the three Pi packages) reports exactly the same single finding, so the published package surfaces nothing extra. Of the 146 versions the peer shrinkwraps, 25 are absent from a linux-x64 tree and all 25 are platform-specific `@esbuild/*` binaries with no advisory surface — noted as a real blind spot on other platforms rather than a clean bill of health.
+
 ## [1.15.0] - 2026-10-01
 
 ### Changed
 - **Pi SDK upgraded `0.84.3` -> `0.99.2`** (`@earendil-works/pi-coding-agent`, `pi-ai`, `pi-tui` moved together). These must be bumped as a set: the agent depends on matching `pi-ai`/`pi-tui`, so bumping it alone leaves a version-skewed tree — which is exactly what the queued Dependabot PR #118 does (its lockfile keeps top-level `pi-ai` at `0.84.3` under a `0.99.2` agent). On the coordinated bump npm still nests copies, but at identical versions, so nothing is skewed. One real API change: `Provider.stream()` now takes a branded `TranscriptContext` produced only by `normalizeContext()`, which folds `systemPrompt`/`tools` into a leading system message — `src/working-vibes/provider.ts` now calls it, and the working-vibes tests assert the prompt the way the SDK delivers it (as `messages[0]`) rather than through a `context.systemPrompt` field that no longer exists.
-- Audit findings drop from 3 (1 moderate, 2 high) to 1 inherited high; the `undici` advisories are cleared. The remaining `brace-expansion` finding lives inside the peer package's own tree and has no fix available at any installable version.
+- Audit findings drop from 3 (1 moderate, 2 high) to 1 high; the `undici` advisories are cleared. The remaining `brace-expansion` finding is inherited from the peer package's own dependency tree. (Corrected after release: the claim that it had no fix at any installable version was wrong — see [Unreleased].)
 
 ## [1.14.0] - 2026-10-01
 

package/build-stamp.json

@@ -1 +1 @@
-{"source_sha":"31d28fdadee020f3ee51b452deeab58c6ec9b439"}
+{"source_sha":"1957ea6e4334e28e25770cba4114e33c69062632"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groeponline/pi-wishcraft",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "description": "Pi coding agent extension: operator cockpit with a live powerline status bar, idea queue, skill search, sticky Bash, hooks, policy guardrails, and TUI session UX.",
   "type": "module",
   "engines": {
@@ -10,6 +10,7 @@
     "*.ts",
     "*.md",
     "*.json",
+    "!audit-baseline.json",
     "banner.png",
     "docs/**/*.md",
     "src/**/*.ts",
@@ -64,6 +65,7 @@
     "prepublishOnly": "tsc --noEmit && node scripts/verify-package.mjs && npm run verify:pi-package",
     "verify:package": "node scripts/verify-package.mjs && node scripts/verify-pi-package-contract.mjs",
     "circular": "madge --circular src index.ts bash-mode queue",
+    "audit": "node scripts/audit-gate.mjs",
     "preview": "node --experimental-strip-types scripts/preview.mjs",
     "verify:pi-package": "node scripts/verify-pi-package-contract.mjs"
   },

package/src/extension/core/peer-guard.ts

@@ -0,0 +1,222 @@
+// peer-guard.ts
+// Activation-time guard for the host-provided Pi SDK peers.
+//
+// `peerDependencies` for the three @earendil-works packages must stay "*" (Pi's
+// package contract requires it and `verify-pi-package-contract.mjs` enforces
+// it), so the manifest cannot express the version floor this extension really
+// has. Every runtime symbol it imports exists from 0.86.0 up, and
+// `normalizeContext` (pi-ai) is the binding one — it arrived last. Without a
+// guard, a host on 0.84.3 loads the extension cleanly and only fails at first
+// use: `/vibe` died on a bare `TypeError: normalizeContext is not a function`
+// deep inside provider code.
+//
+// The guard checks the imported *symbol set* rather than a version string:
+// symbol presence is what the code actually depends on, and it survives
+// backports, republishes, and version-skewed trees where a semver comparison
+// would lie. Warn-only by design — an under-floor host still runs every other
+// surface, so blocking activation would break more than it fixes.
+
+import * as piAi from "@earendil-works/pi-ai";
+import * as piCodingAgent from "@earendil-works/pi-coding-agent";
+import * as piTui from "@earendil-works/pi-tui";
+
+/** Oldest Pi SDK release where every imported symbol exists (probed per release). */
+export const PEER_FLOOR_VERSION = "0.86.0";
+
+export type PeerPackage =
+  | "@earendil-works/pi-ai"
+  | "@earendil-works/pi-coding-agent"
+  | "@earendil-works/pi-tui";
+
+export interface PeerSymbolRequirement {
+  pkg: PeerPackage;
+  symbol: string;
+  /** Feature that degrades when the symbol is absent. */
+  usedBy: string;
+}
+
+// The full runtime (non-type) import surface of this package. Type-only
+// imports cannot fail at runtime and are deliberately absent; the structural
+// test in tests/peer-guard.test.ts keeps this list in exact sync with the
+// imports in every published source file, in both directions.
+export const PEER_SYMBOL_REQUIREMENTS: readonly PeerSymbolRequirement[] = [
+  {
+    pkg: "@earendil-works/pi-ai",
+    symbol: "normalizeContext",
+    usedBy: "/vibe working messages",
+  },
+  {
+    pkg: "@earendil-works/pi-ai",
+    symbol: "createAssistantMessageEventStream",
+    usedBy: "studio advice pane",
+  },
+  {
+    pkg: "@earendil-works/pi-coding-agent",
+    symbol: "CustomEditor",
+    usedBy: "sticky Bash mode",
+  },
+  {
+    pkg: "@earendil-works/pi-coding-agent",
+    symbol: "copyToClipboard",
+    usedBy: "copy shortcuts and /vibe test",
+  },
+  {
+    pkg: "@earendil-works/pi-coding-agent",
+    symbol: "loadSkills",
+    usedBy: "skill registry",
+  },
+  {
+    pkg: "@earendil-works/pi-coding-agent",
+    symbol: "SessionManager",
+    usedBy: "/cd",
+  },
+  {
+    pkg: "@earendil-works/pi-tui",
+    symbol: "matchesKey",
+    usedBy: "keyboard shortcuts",
+  },
+  {
+    pkg: "@earendil-works/pi-tui",
+    symbol: "isKeyRelease",
+    usedBy: "keyboard shortcuts",
+  },
+  {
+    pkg: "@earendil-works/pi-tui",
+    symbol: "visibleWidth",
+    usedBy: "status line rendering",
+  },
+  {
+    pkg: "@earendil-works/pi-tui",
+    symbol: "truncateToWidth",
+    usedBy: "status line rendering",
+  },
+  {
+    pkg: "@earendil-works/pi-tui",
+    symbol: "SelectList",
+    usedBy: "select overlays",
+  },
+  {
+    pkg: "@earendil-works/pi-tui",
+    symbol: "TUI_KEYBINDINGS",
+    usedBy: "default keybindings",
+  },
+];
+
+/**
+ * Resolve a symbol from a peer module namespace. Looks on the namespace itself
+ * and, for interop shapes where named exports land under `default` (CJS-style
+ * wrapping during extension load), there too.
+ */
+function lookupExport(moduleNs: unknown, symbol: string): unknown {
+  if (moduleNs === null || typeof moduleNs !== "object") return undefined;
+  const ns = moduleNs as Record<string, unknown>;
+  const direct = ns[symbol];
+  if (direct !== undefined) return direct;
+  const fallback = ns.default;
+  if (fallback !== null && typeof fallback === "object") {
+    return (fallback as Record<string, unknown>)[symbol];
+  }
+  return undefined;
+}
+
+/** Which required symbols are absent from the given peer namespaces? */
+export function findMissingPeerSymbols(
+  exportsByPkg: Readonly<Partial<Record<PeerPackage, unknown>>>,
+  requirements: readonly PeerSymbolRequirement[] = PEER_SYMBOL_REQUIREMENTS,
+): PeerSymbolRequirement[] {
+  return requirements.filter(
+    ({ pkg, symbol }) => lookupExport(exportsByPkg[pkg], symbol) === undefined,
+  );
+}
+
+/** The live peer namespaces, collected for the runtime check. */
+export function collectPeerExports(): Record<PeerPackage, unknown> {
+  return {
+    "@earendil-works/pi-ai": piAi,
+    "@earendil-works/pi-coding-agent": piCodingAgent,
+    "@earendil-works/pi-tui": piTui,
+  };
+}
+
+/** The runtime check against the peers this process actually loaded. */
+export function checkPeerRuntime(): PeerSymbolRequirement[] {
+  return findMissingPeerSymbols(collectPeerExports());
+}
+
+/** Multi-line console warning naming every missing symbol and its blast radius. */
+export function formatPeerGuardWarning(
+  missing: readonly PeerSymbolRequirement[],
+): string {
+  const lines = missing.map(
+    (m) => `  - ${m.symbol} (${m.pkg}) — needed by ${m.usedBy}`,
+  );
+  return [
+    `Pi SDK below the supported floor: ${missing.length} imported symbol${missing.length === 1 ? " is" : "s are"} missing (all of them exist from ${PEER_FLOOR_VERSION} up).`,
+    ...lines,
+    `The extension stays loaded and affected features fall back; upgrade @earendil-works/pi-coding-agent with its matching pi-ai/pi-tui to ${PEER_FLOOR_VERSION} or newer.`,
+  ].join("\n");
+}
+
+/** One-line variant for `ctx.ui.notify`. */
+export function formatPeerGuardNotice(
+  missing: readonly PeerSymbolRequirement[],
+): string {
+  const symbols = missing.map((m) => m.symbol).join(", ");
+  return `Pi SDK < ${PEER_FLOOR_VERSION}: missing ${symbols} — upgrade the Pi SDK to restore full functionality`;
+}
+
+/** Actionable error for a call site that cannot degrade gracefully. */
+export function missingSymbolError(symbol: string): Error {
+  const requirement = PEER_SYMBOL_REQUIREMENTS.find(
+    (r) => r.symbol === symbol,
+  );
+  const pkg = requirement?.pkg ?? "@earendil-works/pi-*";
+  const feature = requirement?.usedBy ?? symbol;
+  return new Error(
+    `${feature} needs ${symbol} from ${pkg}, which the installed Pi SDK does not provide — upgrade @earendil-works/pi-* to ${PEER_FLOOR_VERSION} or newer`,
+  );
+}
+
+/**
+ * Call-site guard: fail with the actionable message instead of letting a
+ * missing export surface later as "x is not a function".
+ */
+export function requirePeerSymbol<T>(
+  value: T | undefined | null,
+  symbol: string,
+): T {
+  if (value === undefined || value === null) throw missingSymbolError(symbol);
+  return value;
+}
+
+let noticeDelivered = false;
+
+/** Minimal slice of Pi's ExtensionContext the warning needs. */
+export interface PeerGuardContext {
+  hasUI?: boolean;
+  ui?: {
+    notify(message: string, level?: "warning" | "error" | "info"): void;
+  };
+}
+
+/**
+ * One-shot UI warning at session start. `check` is injectable so tests can
+ * drive the missing-symbol path without an under-floor SDK.
+ */
+export function maybeNotifyPeerGuard(
+  ctx: PeerGuardContext | undefined,
+  check: () => PeerSymbolRequirement[] = checkPeerRuntime,
+): void {
+  if (noticeDelivered || !ctx?.hasUI || typeof ctx.ui?.notify !== "function") {
+    return;
+  }
+  const missing = check();
+  if (missing.length === 0) return;
+  noticeDelivered = true;
+  ctx.ui.notify(formatPeerGuardNotice(missing), "warning");
+}
+
+/** Reset the one-shot latch (tests only). */
+export function resetPeerGuardNotice(): void {
+  noticeDelivered = false;
+}

package/src/extension/queue/queue-integration.ts

@@ -36,13 +36,33 @@ export function queueItemDescription(item: PowerlineQueueItem): string {
   return item.target.alias ? `@${item.target.alias}` : item.target.cwd;
 }
 
+/**
+ * Pi's working indicator (spinner frame + "Working...") can end up at the start
+ * of captured text when the editor buffer is captured while the agent runs.
+ * Strip that prefix so ideas never render as a permanently "working" card.
+ */
+const CAPTURE_NOISE_PREFIX =
+  /^[\u2800-\u28FF][\u2800-\u28FF ]*\s*Working[.…]+\s*/;
+
+export function stripCaptureNoisePrefix(text: string): string {
+  let out = text;
+  while (CAPTURE_NOISE_PREFIX.test(out)) {
+    out = out.replace(CAPTURE_NOISE_PREFIX, "");
+  }
+  return out.trimStart();
+}
+
 export function captureQueueItem(
   rt: RuntimeState,
   ctx: any,
-  text: string,
+  rawText: string,
   intent: QueueIntent,
   target: QueueTarget,
 ): PowerlineQueueItem {
+  const text = stripCaptureNoisePrefix(rawText);
+  if (!text.trim()) {
+    throw new Error("Nothing to capture");
+  }
   const item = rt.queueStore.add({
     text,
     intent,

package/src/extension/session/activate.ts

@@ -15,8 +15,20 @@ import {
   PRESET_NAMES,
   setConfig,
 } from "../core/state.ts";
+import {
+  checkPeerRuntime,
+  formatPeerGuardWarning,
+} from "../core/peer-guard.ts";
 
 export default function powerlineFooter(pi: ExtensionAPI) {
+  // peerDependencies are "*" by contract, so the manifest cannot express the
+  // real SDK floor. Check the imported symbol set up front and say what is
+  // missing, instead of letting an under-floor host fail at first use.
+  const missingPeers = checkPeerRuntime();
+  if (missingPeers.length > 0) {
+    console.warn(`[wishcraft] ${formatPeerGuardWarning(missingPeers)}`);
+  }
+
   const startupSettings = readSettings();
   // Ambient UI language: resolved before anything renders, so the very first
   // frame of the status line and welcome overlay is already in the right

package/src/extension/session/session-lifecycle.ts

@@ -53,6 +53,7 @@ import {
   setCustomCompactionEnabled,
 } from "../core/state.ts";
 import { CONTEXT_STATUS_RENDER_MS } from "../core/constants.ts";
+import { maybeNotifyPeerGuard } from "../core/peer-guard.ts";
 import type { RuntimeState } from "../core/types.ts";
 import { isStaleExtensionContextError } from "./stale-context.ts";
 import { dismissWelcome } from "../welcome/welcome-control.ts";
@@ -139,6 +140,7 @@ export function registerSessionLifecycle(
     registerCustomSegments(config.segments);
     registerCustomPresets(config.presets);
     warnInvalidSegmentSettings(ctx);
+    maybeNotifyPeerGuard(ctx);
     rt.stashedPromptHistory = readPersistedStashHistory();
     rt.bashModeActive = false;
     rt.bashTranscript = new BashTranscriptStore(rt.bashModeSettings);

package/src/working-vibes/provider.ts

@@ -9,6 +9,7 @@ import type {
   ProviderStreamOptions,
 } from "@earendil-works/pi-ai";
 import { normalizeContext } from "@earendil-works/pi-ai";
+import { requirePeerSymbol } from "../extension/core/peer-guard.ts";
 import { VIBE_SYSTEM_PROMPT, vibeState } from "./storage.ts";
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -41,8 +42,11 @@ export async function completeVibe(
   // `Provider.stream()` now takes a branded `TranscriptContext`, which only
   // `normalizeContext()` produces. It folds `systemPrompt` and `tools` into a
   // leading system message; the brand exists so a raw `Context` cannot reach
-  // provider code unnormalized.
-  return provider.stream(requestModel, normalizeContext(context), options).result();
+  // provider code unnormalized. `requirePeerSymbol` turns a missing export on
+  // an under-floor Pi SDK into an actionable error instead of
+  // "normalizeContext is not a function".
+  const normalize = requirePeerSymbol(normalizeContext, "normalizeContext");
+  return provider.stream(requestModel, normalize(context), options).result();
 }
 
 // ═══════════════════════════════════════════════════════════════════════════