@groeponline/pi-wishcraft 1.15.0 → 1.17.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 |
 
@@ -320,3 +322,13 @@ scripts/docker-test.sh -n 4   # 4 parallel containers
 ```
 
 Each container runs `typecheck + test + circular` with a shared read-only `node_modules` bind mount.
+
+## Agent skills
+
+### Issue tracker
+
+Dual-tracker: Linear for planning/features, GitHub for bugs/triage. See `docs/agents/issue-tracker.md`.
+
+### Domain docs
+
+Single-context. Current domain source: AGENTS.md. CONTEXT.md and docs/adr/ to be added via `/domain-modeling` when needed. See `docs/agents/domain.md`.

package/CHANGELOG.md

@@ -2,11 +2,31 @@
 
 ## [Unreleased]
 
+## [1.17.0] - 2026-10-27
+
+### Fixed
+- Bash paste-while-running (issue #72): a bracketed paste performed while a command runs is stripped of its markers and forwarded to the child stdin — including split delivery across input chunks — instead of silently queuing in the editor buffer behind the command.
+- PTY/transcript memory bounds (from jan `fix/runtime-pty-bounds`): a single unterminated output line is capped at a 64 KiB UTF-8 tail with a one-time notice, the partial-escape tail is bounded, and the active transcript command trims head lines/bytes within limits instead of growing unbounded.
+- Segment-options spread hygiene (CodeFactor #86–89): `normalizeSegmentOptions` assigns fields imperatively instead of spreading conditional empty objects.
+
+## [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":"0c1a77045865dbb0dd6138ac1d0b381c067d0395"}

package/docs/agents/domain.md

@@ -0,0 +1,60 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **`AGENTS.md`** at the repo root — the current domain documentation source with architecture, data flow, and conventions.
+- **`CONTEXT.md`** at the repo root, if it exists (currently absent).
+- **`CONTEXT-MAP.md`** at the repo root if it exists: it points at one `CONTEXT.md` per context. Read each one relevant to the topic.
+- **`docs/adr/`**: read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
+
+If `CONTEXT.md` or `docs/adr/` don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved.
+
+## File structure
+
+Single-context repo (this repo):
+
+**Current state:**
+- `AGENTS.md` — Primary domain documentation (architecture, data flow, conventions)
+- `docs/` — Operator guides and design specs (no ADRs currently)
+- `CONTEXT.md` — Not yet created (add via `/domain-modeling` when needed)
+
+**Target state (when CONTEXT.md exists):**
+
+```
+/
+├── AGENTS.md
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0001-event-sourced-orders.md
+│   └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+Multi-context repo (presence of `CONTEXT-MAP.md` at the root):
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/adr/                          ← system-wide decisions
+└── src/
+    ├── ordering/
+    │   ├── CONTEXT.md
+    │   └── docs/adr/                  ← context-specific decisions
+    └── billing/
+        ├── CONTEXT.md
+        └── docs/adr/
+```
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `AGENTS.md` (current domain source) or `CONTEXT.md` (if it exists). Don't drift to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal: either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
+> _Contradicts ADR-0007 (event-sourced orders), but worth reopening because…_

package/docs/agents/issue-tracker.md

@@ -0,0 +1,88 @@
+# Issue tracker: Linear + GitHub
+
+This repo uses a dual-tracker workflow:
+- **Linear**: Long-term planning, roadmap, feature tracking
+- **GitHub**: Bug reports, PR-linked issues, immediate triage
+
+## Conventions
+
+### GitHub (primary for bugs and triage)
+- **Create an issue**: `gh issue create --title "..." --body "..."`. Use a heredoc for multi-line bodies.
+- **Read an issue**: `gh issue view <number> --comments`, filtering comments by `jq` and also fetching labels.
+- **List issues**: `gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'` with appropriate `--label` and `--state` filters.
+- **Comment on an issue**: `gh issue comment <number> --body "..."`
+- **Apply / remove labels**: `gh issue edit <number> --add-label "..."` / `--remove-label "..."`
+- **Close**: `gh issue close <number> --comment "..."`
+
+Infer the repo from `git remote -v`; `gh` does this automatically when run inside a clone.
+
+### Linear (for planning and features)
+- **Create a ticket**: `linear issue create --title "..." --description "..." --team <team-id>`. Use `linear teams list` to find team IDs.
+- **Read a ticket**: `linear issue view <ticket-id>` or `linear issue search --query "<title>"`.
+- **List tickets**: `linear issue list --team <team-id> --state <state>` with appropriate filters (e.g., `--state Backlog`, `--state In Progress`).
+- **Comment on a ticket**: `linear comment create <ticket-id> --body "..."`
+- **Change state**: `linear issue update <ticket-id> --state <state>`
+- **Assign**: `linear issue update <ticket-id> --assignee <user-id>`
+- **Link to GitHub**: Add a GitHub issue URL in the Linear ticket description, or use Linear's GitHub integration if configured.
+
+Use Linear for feature planning, roadmap items, and long-term tracking. Reference Linear tickets in GitHub issue bodies when applicable. Link GitHub PRs to related Linear tickets for traceability.
+
+### Linear conventions
+
+**Labels** (create in Linear):
+- `type:feature` — New features or enhancements
+- `type:bug` — Bugs that belong in the roadmap (not urgent)
+- `type:refactor` — Technical debt or architectural work
+- `type:research` — Investigation or exploration tasks
+- `priority:high` / `priority:medium` / `priority:low` — Priority levels
+
+**States** (use Linear's default workflow or customize):
+- `Backlog` — Planned but not started
+- `In Progress` — Active work
+- `In Review` — Awaiting review
+- `Done` — Completed
+- `Canceled` — Declined or superseded
+
+## Pull requests as a triage surface
+
+**PRs as a request surface: no.** _(Set to `yes` if this repo treats external PRs as feature requests; `/triage` reads this flag.)_
+
+When set to `yes`, PRs run through the same labels and states as issues, using the `gh pr` equivalents:
+
+- **Read a PR**: `gh pr view <number> --comments` and `gh pr diff <number>` for the diff.
+- **List external PRs for triage**: `gh pr list --state open --json number,title,body,labels,author,comments` then fetch `authorAssociation` per PR with `gh api repos/:owner/:repo/pulls/<number> --jq '.author_association'` (the `gh pr list --json` field set does not include `authorAssociation`), keeping only `CONTRIBUTOR`, `FIRST_TIME_CONTRIBUTOR`, or `NONE` (drop `OWNER`/`MEMBER`/`COLLABORATOR`).
+- **Comment / label / close**: `gh pr comment`, `gh pr edit --add-label`/`--remove-label`, `gh pr close`.
+
+GitHub shares one number space across issues and PRs, so a bare `#42` may be either: resolve with `gh pr view 42` and fall back to `gh issue view 42`.
+
+## When a skill says "publish to the issue tracker"
+
+**Use GitHub when:**
+- Bug reports or regressions
+- Urgent issues requiring immediate triage
+- PR-linked issues or feedback from code review
+- Questions or clarifications about implementation
+
+**Use Linear when:**
+- Feature proposals or enhancements
+- Roadmap items or long-term planning
+- Research tasks or investigations
+- Technical debt or architectural refactoring
+- Multi-step work that benefits from project tracking
+
+If unsure, default to GitHub for bugs/immediate work, Linear for features/planning.
+
+## When a skill says "fetch the relevant ticket"
+
+Run `gh issue view <number> --comments` for GitHub issues. For Linear tickets, use the Linear CLI or API.
+
+## Wayfinding operations
+
+Used by `/wayfinder`. The **map** is a single Linear ticket with **child** tickets as tasks.
+
+- **Map**: a single Linear ticket labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body. `linear issue create --title "Map: <topic>" --description "..." --team <team-id> --label wayfinder:map`.
+- **Child ticket**: a Linear ticket linked to the map as a parent using Linear's parent-child relationship. Add the child to the map's sub-issues and put `Part of <map-id>` at the top of the child description. Labels: `wayfinder:<type>` (`research`/`prototype`/`grilling`/`task`). Once claimed, the ticket is assigned to the driving dev.
+- **Blocking**: Use Linear's **native issue dependencies**. Add a blocker with `linear issue update <child> --blocking <blocker-id>`. Linear reports blocking status in the UI. A ticket is unblocked when every blocker is resolved.
+- **Frontier query**: list the map's open children (`linear issue list --team <team-id> --parent <map-id> --state Backlog,In Progress`), drop any with an open blocker or an assignee; first in map order wins.
+- **Claim**: `linear issue update <ticket-id> --assignee @me`, the session's first write.
+- **Resolve**: `linear comment create <ticket-id> --body "<answer>"`, then `linear issue update <ticket-id> --state Done`, then append a context pointer (gist + link) to the map's Decisions-so-far.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groeponline/pi-wishcraft",
-  "version": "1.15.0",
+  "version": "1.17.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. */
+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. */
+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();
 }
 
 // ═══════════════════════════════════════════════════════════════════════════