@ilya-lesikov/pi-pi 0.9.0 → 0.11.0

package/extensions/orchestrator/state.ts

@@ -56,6 +56,20 @@ export interface TaskState {
   mode?: TaskMode;
   effectiveMode?: TaskMode;
   autonomousConfig?: AutonomousConfig;
+  // Manual auto-review-until-approved (#5/#7): drives the same review-cycle loop
+  // as autonomous mode over ONE phase, independently of effectiveMode (so it
+  // works in force-guided brainstorm/debug/review). advanceOnComplete=false
+  // (item 5) stops in-phase on approve/max-passes; =true (item 7) finalizes and
+  // transitions to the next phase. deferredAdvance carries the next-phase inputs
+  // the plain-continue path would have collected, captured up front because the
+  // headless pp_phase_complete branch cannot prompt.
+  manualAutoReview?: {
+    phase: string;
+    preset: string;
+    maxPasses: number;
+    advanceOnComplete: boolean;
+    deferredAdvance?: { mode?: TaskMode; autonomousConfig?: AutonomousConfig; plannerPreset?: string };
+  };
   plannerFailureAutoRetried?: boolean;
   reviewerFailureAutoRetried?: boolean;
   // Set once afterImplement has run for the current implement phase (either at
@@ -66,6 +80,10 @@ export interface TaskState {
   // set of repos to review; index is the next repo. Persisted so the loop resumes
   // on the next /pp after the agent fixes one repo's feedback. Undefined = no loop.
   plannotatorCursor?: { repoPaths: string[]; index: number };
+  // The phase the task was in when it was marked done. Recorded so the Resume
+  // "reopen a done task" flow (#2) can restore the actual last working phase
+  // (done itself carries no phase history). Absent on legacy done tasks.
+  completedFrom?: Phase;
 }
 
 export interface TaskInfo {
@@ -174,11 +192,18 @@ export function saveTask(taskDir: string, state: TaskState): void {
   writeFileSync(taskStatePath(taskDir), JSON.stringify(state, null, 2) + "\n", "utf-8");
 }
 
-export function listTasks(cwd: string, type?: TaskType): TaskInfo[] {
+export interface ListTasksOptions {
+  type?: TaskType;
+  includeDone?: boolean;
+}
+
+export function listTasks(cwd: string, typeOrOptions?: TaskType | ListTasksOptions): TaskInfo[] {
+  const options: ListTasksOptions =
+    typeof typeOrOptions === "string" ? { type: typeOrOptions } : typeOrOptions ?? {};
   const base = stateDir(cwd);
   if (!existsSync(base)) return [];
 
-  const types: TaskType[] = type ? [type] : ["implement", "debug", "brainstorm", "review", "quick"];
+  const types: TaskType[] = options.type ? [options.type] : ["implement", "debug", "brainstorm", "review", "quick"];
   const results: TaskInfo[] = [];
 
   for (const t of types) {
@@ -193,7 +218,7 @@ export function listTasks(cwd: string, type?: TaskType): TaskInfo[] {
 
       try {
         const state = loadTask(dir);
-        if (state.phase !== "done") {
+        if (state.phase !== "done" || options.includeDone) {
           results.push({ dir, state, type: t });
         }
       } catch {
@@ -229,9 +254,9 @@ export async function lockTask(taskDir: string, timeouts: TimeoutConfig): Promis
   return release;
 }
 
-export function getActiveTask(cwd: string, lockStale?: number): TaskInfo | null {
+export function getUnlockedTasks(cwd: string, lockStale?: number): TaskInfo[] {
   const tasks = listTasks(cwd);
-  if (tasks.length === 0) return null;
+  if (tasks.length === 0) return [];
 
   const stale = lockStale ?? 600000;
   const unlocked: TaskInfo[] = [];
@@ -245,9 +270,24 @@ export function getActiveTask(cwd: string, lockStale?: number): TaskInfo | null
       getLogger().warn({ s: "state", dir: task.dir }, "failed to check lock");
     }
   }
+  return unlocked;
+}
 
-  if (unlocked.length !== 1) return null;
-  return unlocked[0];
+export type ActiveTaskStatus =
+  | { kind: "none" }
+  | { kind: "single"; task: TaskInfo }
+  | { kind: "ambiguous"; tasks: TaskInfo[] };
+
+export function getActiveTaskStatus(cwd: string, lockStale?: number): ActiveTaskStatus {
+  const unlocked = getUnlockedTasks(cwd, lockStale);
+  if (unlocked.length === 0) return { kind: "none" };
+  if (unlocked.length === 1) return { kind: "single", task: unlocked[0]! };
+  return { kind: "ambiguous", tasks: unlocked };
+}
+
+export function getActiveTask(cwd: string, lockStale?: number): TaskInfo | null {
+  const status = getActiveTaskStatus(cwd, lockStale);
+  return status.kind === "single" ? status.task : null;
 }
 
 export function validateFromPath(cwd: string, fromPath: string): { ok: true; dir: string } | { ok: false; reason: string } {
@@ -284,28 +324,60 @@ export function taskName(taskDir: string): string {
   }
 }
 
-// Same as taskName but reuses an already-loaded TaskState (avoids re-reading
-// state.json per resume-menu entry). The only per-entry disk read is the
-// USER_REQUEST.md fallback, which is unavoidable for generic descriptions.
-export function taskNameFromState(taskDir: string, state: TaskState): string {
+// Non-heading, non-empty content of a markdown file, collapsed onto one line
+// (multiple content lines joined with a space), or null. Spanning multiple
+// lines lets a multi-line request survive the later truncate-with-ellipsis
+// instead of being cut off at the first content line. Bounded so a large file
+// (e.g. RESEARCH.md) never builds an unbounded string.
+function firstMarkdownContent(path: string): string | null {
+  if (!existsSync(path)) return null;
+  const content = readFileSync(path, "utf-8");
+  const lines = content.split("\n").map((l) => l.trim()).filter((l) => l.length > 0 && !l.startsWith("#"));
+  if (lines.length === 0) return null;
+  return lines.join(" ").slice(0, 700);
+}
+
+// The full, untrimmed task name (used for the Resume right-pane description).
+// Resolves a real intent for generic-description tasks via a fallback chain:
+// USER_REQUEST.md → RESEARCH.md → first artifact → dir slug.
+export function taskFullName(taskDir: string, state: TaskState): string {
   let desc = state.description ?? "";
 
   if (["implement", "debug", "brainstorm", "review", "quick"].includes(desc)) {
-    const urPath = join(taskDir, "USER_REQUEST.md");
-    if (existsSync(urPath)) {
-      const content = readFileSync(urPath, "utf-8");
-      const lines = content.split("\n").map((l) => l.trim()).filter((l) => l.length > 0);
-      const firstContent = lines.find((l) => !l.startsWith("#"));
-      if (firstContent) desc = firstContent;
-    }
+    const fallback =
+      firstMarkdownContent(join(taskDir, "USER_REQUEST.md")) ??
+      firstMarkdownContent(join(taskDir, "RESEARCH.md")) ??
+      firstArtifactTitle(taskDir);
+    if (fallback) desc = fallback;
   }
 
-  if (desc) {
-    desc = desc.replace(/\s+/g, " ").trim();
-    if (desc.length > 60) desc = desc.slice(0, 57) + "...";
-    return desc;
+  desc = desc.replace(/\s+/g, " ").trim();
+  return desc || dirSlugName(taskDir);
+}
+
+function firstArtifactTitle(taskDir: string): string | null {
+  const artifactsDir = join(taskDir, "artifacts");
+  if (!existsSync(artifactsDir)) return null;
+  const files = readdirSync(artifactsDir).filter((f) => f.endsWith(".md")).sort();
+  for (const file of files) {
+    const content = readFileSync(join(artifactsDir, file), "utf-8");
+    const lines = content.split("\n").map((l) => l.trim()).filter((l) => l.length > 0);
+    const heading = lines.find((l) => l.startsWith("# "));
+    if (heading) return heading.replace(/^#\s+/, "");
+    const firstContent = lines.find((l) => !l.startsWith("#"));
+    if (firstContent) return firstContent;
   }
-  return dirSlugName(taskDir);
+  return null;
+}
+
+// Same as taskName but reuses an already-loaded TaskState (avoids re-reading
+// state.json per resume-menu entry). Returns a TITLE trimmed to fit one line.
+// The cap is conservative (fits within ~80 cols after the `→ N. ` selection
+// prefix and a ` — <age>` suffix are added) so a Resume item never wraps.
+export function taskNameFromState(taskDir: string, state: TaskState): string {
+  const desc = taskFullName(taskDir, state);
+  if (desc.length > 60) return desc.slice(0, 57) + "...";
+  return desc;
 }
 
 function dirSlugName(taskDir: string): string {

package/extensions/orchestrator/suppress-pierre-theme-spam.test.ts

@@ -0,0 +1,56 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { suppressPierreThemeSpam } from "./suppress-pierre-theme-spam.js";
+
+const INSTALLED_KEY = Symbol.for("pi-pi:pierre-theme-spam-suppressed");
+const DUP = "SharedHighlight.registerCustomTheme: theme name already registered";
+
+describe("suppressPierreThemeSpam", () => {
+  let original: typeof console.error;
+
+  beforeEach(() => {
+    original = console.error;
+    (globalThis as any)[INSTALLED_KEY] = undefined;
+  });
+
+  afterEach(() => {
+    console.error = original;
+    (globalThis as any)[INSTALLED_KEY] = undefined;
+  });
+
+  it("drops the benign duplicate-theme error for each known pierre theme", () => {
+    const spy = vi.fn();
+    console.error = spy;
+    suppressPierreThemeSpam();
+
+    for (const name of ["pierre-dark", "pierre-dark-soft", "pierre-light", "pierre-light-soft"]) {
+      console.error(DUP, name);
+    }
+    expect(spy).not.toHaveBeenCalled();
+  });
+
+  it("passes through unrelated console.error calls untouched", () => {
+    const spy = vi.fn();
+    console.error = spy;
+    suppressPierreThemeSpam();
+
+    console.error("something else entirely");
+    console.error(DUP, "some-other-theme"); // same prefix, unknown theme → not ours
+    console.error("real error", new Error("boom"));
+
+    expect(spy).toHaveBeenCalledTimes(3);
+    expect(spy).toHaveBeenNthCalledWith(1, "something else entirely");
+    expect(spy).toHaveBeenNthCalledWith(2, DUP, "some-other-theme");
+  });
+
+  it("installs the filter only once (idempotent, no wrapper stacking)", () => {
+    const spy = vi.fn();
+    console.error = spy;
+    suppressPierreThemeSpam();
+    const afterFirst = console.error;
+    suppressPierreThemeSpam();
+    expect(console.error).toBe(afterFirst);
+
+    console.error("passthrough");
+    expect(spy).toHaveBeenCalledTimes(1);
+  });
+});

package/extensions/orchestrator/suppress-pierre-theme-spam.ts

@@ -0,0 +1,45 @@
+/**
+ * Silences a benign, TUI-corrupting `console.error` from `@pierre/diffs`.
+ *
+ * `@pierre/diffs/dist/highlighter/shared_highlighter.js` registers four custom
+ * themes (`pierre-dark`, `pierre-dark-soft`, `pierre-light`, `pierre-light-soft`)
+ * as an import-time side effect, against a module-singleton Map. When that module
+ * graph is evaluated more than once — which it is here, because pi loads
+ * extensions through jiti with `moduleCache: false` and the /pp menu is pulled in
+ * via a dynamic `import()` — each re-registration trips a
+ * `console.error("SharedHighlight.registerCustomTheme: theme name already registered", name)`.
+ *
+ * pi takes over stdout during the interactive TUI (its output-guard reroutes
+ * stdout→stderr) but does not guard stderr, so that stray error visibly corrupts
+ * the rendered UI (seen when opening/closing /pp).
+ *
+ * We can't dedupe the registration (jiti's cache is off) and there's no
+ * patch-package infra in this repo, so we drop exactly this one third-party
+ * message and delegate everything else untouched. Installed once, process-wide.
+ */
+
+const DUP_THEME_PREFIX = "SharedHighlight.registerCustomTheme: theme name already registered";
+const PIERRE_THEME_NAMES = new Set(["pierre-dark", "pierre-dark-soft", "pierre-light", "pierre-light-soft"]);
+
+// Marked on globalThis rather than a module-local flag: pi loads extensions via
+// jiti with `moduleCache: false`, so this module can be re-evaluated (resetting
+// module scope) — without a process-wide marker we'd stack console.error wrappers.
+const INSTALLED_KEY = Symbol.for("pi-pi:pierre-theme-spam-suppressed");
+
+export function suppressPierreThemeSpam(): void {
+  if ((globalThis as any)[INSTALLED_KEY]) return;
+  (globalThis as any)[INSTALLED_KEY] = true;
+
+  const original = console.error.bind(console);
+  console.error = (...args: unknown[]) => {
+    if (
+      args.length >= 2 &&
+      args[0] === DUP_THEME_PREFIX &&
+      typeof args[1] === "string" &&
+      PIERRE_THEME_NAMES.has(args[1])
+    ) {
+      return;
+    }
+    original(...args);
+  };
+}

package/extensions/orchestrator/validate-artifacts.ts

@@ -5,7 +5,7 @@ const USER_REQUEST_ALLOWED_SECTIONS = ["Problem", "Constraints"] as const;
 const RESEARCH_REQUIRED_SECTIONS = ["Affected Code", "Architecture Context", "Constraints & Edge Cases"] as const;
 const RESEARCH_ALLOWED_SECTIONS = ["Affected Code", "Architecture Context", "Constraints & Edge Cases", "Open Questions"] as const;
 const PLAN_REQUIRED_SECTIONS = ["Scope", "Checklist"] as const;
-const PLAN_ALLOWED_SECTIONS = ["Scope", "Checklist", "Pattern constraints", "Blockers"] as const;
+export const PLAN_ALLOWED_SECTIONS = ["Scope", "Checklist", "Pattern constraints", "Blockers"] as const;
 const PLACEHOLDER_PATTERNS = /^(?:[-*.…—]|tbd|todo|n\/a|na|none|\.{2,})$/i;
 
 function splitLines(content: string): string[] {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ilya-lesikov/pi-pi",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Pi-Pi Coding Agent: based on Pi Coding Agent, but twice as good",
   "keywords": [
     "pi-package",
@@ -35,7 +35,11 @@
   "scripts": {
     "postinstall": "bash scripts/postinstall.sh",
     "test": "vitest run --exclude '3p/**'",
-    "test:watch": "vitest --exclude '3p/**'"
+    "test:watch": "vitest --exclude '3p/**'",
+    "test:3p": "bash scripts/test-3p.sh",
+    "test:package": "bash scripts/test-package.sh",
+    "test:all": "vitest run --exclude '3p/**' && bash scripts/test-3p.sh && bash scripts/test-package.sh",
+    "coverage": "vitest run --exclude '3p/**' --coverage"
   },
   "pi": {
     "extensions": [
@@ -50,8 +54,10 @@
   "dependencies": {
     "@joplin/turndown-plugin-gfm": "^1.0.64",
     "@pierre/diffs": "^1.2.0",
+    "croner": "^10.0.1",
     "effect": "^3.0.0",
     "minimatch": "^10.0.0",
+    "nanoid": "^5.0.0",
     "pino": "^10.3.1",
     "proper-lockfile": "^4.1.2",
     "turndown": "^7.2.0",
@@ -68,6 +74,7 @@
     "@earendil-works/pi-coding-agent": "^0.75.5",
     "@earendil-works/pi-tui": "^0.75.5",
     "@sinclair/typebox": "^0.34.0",
+    "@vitest/coverage-v8": "^4.1.10",
     "typescript": "^5.8.0",
     "vitest": "^4.1.4"
   }

package/scripts/lib/smoke-resolve.mjs

@@ -0,0 +1,99 @@
+// Runs from INSIDE the installed package directory (import.meta.url is under the package), so
+// dynamic import() of a bare specifier resolves through the installed artifact's own
+// node_modules chain — the same resolution pi performs at extension load. Exits non-zero if a
+// registered extension path is missing or a required runtime specifier fails to load.
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PKG_DIR = dirname(fileURLToPath(import.meta.url));
+
+function fail(msg) {
+  console.error(`  ✗ ${msg}`);
+  process.exitCode = 1;
+}
+
+const pkg = JSON.parse(readFileSync(join(PKG_DIR, "package.json"), "utf8"));
+
+const extEntries = pkg?.pi?.extensions ?? [];
+if (extEntries.length === 0) fail("package.json has no pi.extensions entries");
+for (const entry of extEntries) {
+  if (existsSync(resolve(PKG_DIR, entry))) {
+    console.log(`  ✓ extension present: ${entry}`);
+  } else {
+    fail(`registered extension path missing from artifact: ${entry}`);
+  }
+}
+
+// Bare specifiers pi itself supplies to loaded extensions — never mirrored into dependencies.
+const peerSupplied = new Set(Object.keys(pkg.peerDependencies ?? {}));
+
+function isBuiltin(spec) {
+  return spec.startsWith("node:");
+}
+function isRelative(spec) {
+  return spec.startsWith(".") || spec.startsWith("/");
+}
+function packageName(spec) {
+  const parts = spec.split("/");
+  return spec.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0];
+}
+
+function collectTsFiles(dir) {
+  const out = [];
+  for (const name of readdirSync(dir)) {
+    const full = join(dir, name);
+    const st = statSync(full);
+    if (st.isDirectory()) out.push(...collectTsFiles(full));
+    else if (name.endsWith(".ts")) out.push(full);
+  }
+  return out;
+}
+
+// Scope the scan to the pi-subagents source only. Other shipped 3p sources reference SDK
+// specifiers behind lazy `await import()` guards that are intentionally NOT root dependencies;
+// scanning them would produce a permanently failing test.
+const SCAN_DIR = join(PKG_DIR, "3p", "pi-subagents", "src");
+if (!existsSync(SCAN_DIR)) {
+  fail(`expected shipped source dir missing: 3p/pi-subagents/src`);
+  process.exit(process.exitCode ?? 1);
+}
+
+// Value (non-type) import/export ... from "spec" and dynamic import("spec"). `import type` /
+// `export type` statements are type-only and erased at build, so they carry no runtime requirement.
+const FROM_RE = /(^|\n)\s*(import|export)\s+(?!type\b)(?:[^;]*?\sfrom\s+)?["']([^"']+)["']/g;
+const DYN_RE = /\bimport\s*\(\s*["']([^"']+)["']\s*\)/g;
+
+const required = new Set();
+for (const file of collectTsFiles(SCAN_DIR)) {
+  const src = readFileSync(file, "utf8");
+  for (const m of src.matchAll(FROM_RE)) addSpec(m[3]);
+  for (const m of src.matchAll(DYN_RE)) addSpec(m[1]);
+}
+function addSpec(spec) {
+  if (isBuiltin(spec) || isRelative(spec)) return;
+  const name = packageName(spec);
+  if (peerSupplied.has(name)) return;
+  required.add(name);
+}
+
+// Floor: these two are the runtime imports that broke consumer installs; assert them explicitly
+// even if the extractor's shape ever changes.
+required.add("croner");
+required.add("nanoid");
+
+const specs = [...required].sort();
+console.log(`  runtime specifiers to resolve: ${specs.join(", ")}`);
+
+for (const spec of specs) {
+  try {
+    await import(spec);
+    console.log(`  ✓ resolved: ${spec}`);
+  } catch (err) {
+    fail(`cannot resolve '${spec}' from installed package: ${err?.message ?? err}`);
+  }
+}
+
+if (process.exitCode) {
+  console.error("  → the root package is missing a runtime dependency its shipped extensions need.");
+}

package/scripts/test-3p.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# Aggregates the test suites of the vendored 3p/ extensions, each run with its OWN native runner
+# (vitest for pi-subagents/pi-tasks, bun for pi-lsp/pi-ask-user/pi-plannotator). The root
+# `npm test` excludes 3p/**, so without this the fork-delta tests never gate CI.
+#
+# Exit non-zero if any package's suite fails. Runs every package even if an earlier one fails, so
+# one invocation reports all breakage.
+set -uo pipefail
+cd "$(dirname "$0")/.."
+ROOT="$(pwd)"
+
+if ! command -v bun >/dev/null 2>&1; then
+  echo "ERROR: 'bun' is not on PATH — pi-lsp, pi-ask-user and pi-plannotator gate on it." >&2
+  echo "Install bun (https://bun.sh) and re-run, or run the vitest 3p suites individually." >&2
+  exit 127
+fi
+
+failures=()
+
+run() {
+  local name="$1"; shift
+  local dir="$1"; shift
+  echo ""
+  echo "──────────────────────────────────────────────"
+  echo "▶ 3p/$name  ($*)"
+  echo "──────────────────────────────────────────────"
+  ( cd "$ROOT/3p/$dir" && "$@" )
+  if [ $? -ne 0 ]; then
+    failures+=("$name")
+  fi
+}
+
+# vitest packages (use the package's own vitest.config.ts via npx vitest run).
+run "pi-subagents" "pi-subagents" npx vitest run
+run "pi-tasks"     "pi-tasks"     npx vitest run
+
+# bun packages. pi-ask-user has no `test` npm script, so invoke `bun test` directly.
+run "pi-lsp"      "pi-lsp"      bun test
+run "pi-ask-user" "pi-ask-user" bun test
+
+# pi-plannotator: scope explicitly to the shipped pi-extension app + the fork-parity guards.
+# Bare `bun test` would reach unshipped upstream workspace packages that need alias setup.
+run "pi-plannotator" "pi-plannotator" bun test apps/pi-extension tests/parity
+
+echo ""
+echo "──────────────────────────────────────────────"
+if [ ${#failures[@]} -eq 0 ]; then
+  echo "✓ all 3p suites passed"
+  exit 0
+fi
+echo "✗ 3p suites FAILED: ${failures[*]}"
+exit 1

package/scripts/test-package.sh

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+# Release-layout smoke test: pack the root package, install the tarball into a throwaway
+# directory OUTSIDE this checkout, and verify the shipped extension artifact resolves its
+# runtime imports from the installed tree alone.
+#
+# Why this exists: the root `npm test` excludes 3p/** and the vendored suites run inside
+# 3p/*/node_modules, so a bare import that a vendored extension needs but the root package
+# forgets to declare is invisible in the dev checkout (its node_modules still has the package).
+# It only surfaces after a clean `npm install` by a consumer — exactly the croner/nanoid
+# regression this guards against. Resolving bare specifiers from the installed package tree is
+# the only shape that reproduces that failure.
+#
+# Registry access is required (npm install of the tarball fetches deps, runs the root
+# postinstall, and npm v7+ auto-installs peerDependencies). Offline CI: warm the npm cache and
+# export a --prefer-offline-friendly registry mirror.
+set -uo pipefail
+cd "$(dirname "$0")/.."
+ROOT="$(pwd)"
+
+TMPDIR_SMOKE="$(mktemp -d)"
+trap 'rm -rf "$TMPDIR_SMOKE"' EXIT
+
+echo "▶ packing root package"
+PACK_JSON="$(npm pack --json --pack-destination "$TMPDIR_SMOKE" 2>/dev/null)"
+TARBALL="$(node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{const a=JSON.parse(s);process.stdout.write(a[0].filename)})' <<<"$PACK_JSON")"
+if [ -z "$TARBALL" ] || [ ! -f "$TMPDIR_SMOKE/$TARBALL" ]; then
+  echo "ERROR: npm pack did not produce a tarball (got: '$TARBALL')." >&2
+  exit 1
+fi
+echo "  tarball: $TARBALL"
+
+INSTALL_DIR="$TMPDIR_SMOKE/install"
+mkdir -p "$INSTALL_DIR"
+( cd "$INSTALL_DIR" && npm init -y >/dev/null 2>&1 )
+
+echo "▶ installing tarball into a clean consumer directory"
+if ! ( cd "$INSTALL_DIR" && npm install "$TMPDIR_SMOKE/$TARBALL" --no-audit --no-fund 2>&1 ); then
+  echo "ERROR: installing the packed tarball failed." >&2
+  exit 1
+fi
+
+PKG_NAME="$(node -e 'process.stdout.write(require("./package.json").name)')"
+PKG_DIR="$INSTALL_DIR/node_modules/$PKG_NAME"
+if [ ! -d "$PKG_DIR" ]; then
+  echo "ERROR: installed package not found at $PKG_DIR" >&2
+  exit 1
+fi
+
+# Run the resolution check from a helper placed INSIDE the installed package, so bare-specifier
+# resolution provably walks the artifact's own node_modules hierarchy (not this checkout's).
+CHECK="$PKG_DIR/__smoke-resolve.mjs"
+cp "$ROOT/scripts/lib/smoke-resolve.mjs" "$CHECK"
+
+echo "▶ resolving shipped extension runtime imports from the install tree"
+( cd "$PKG_DIR" && node "$CHECK" )
+STATUS=$?
+
+if [ $STATUS -ne 0 ]; then
+  echo "✗ package smoke test FAILED" >&2
+  exit $STATUS
+fi
+echo "✓ package smoke test passed"