pi-pstack-adapter 0.6.0 → 0.8.0

package/src/status.ts

@@ -1,7 +1,7 @@
 import { CERTIFIED } from "./certified.ts";
-import { CAPABILITY_LABELS, MODEL_ROLES, TIER_ORDER } from "./registry.ts";
-import type { AdapterConfig } from "./config.ts";
-import { splitModelSpec, trustWarning } from "./config.ts";
+import { CAPABILITY_LABELS, GENERAL_ROLE, MODEL_ROLES, PANEL_DEFAULT_ROLES, PANEL_ROLES, TIER_ORDER } from "./registry.ts";
+import type { AdapterConfig, ModelSpec } from "./config.ts";
+import { panelEntries, splitModelSpec, trustWarning } from "./config.ts";
 import { DELEGATION_BACKENDS, delegationOrder } from "./delegation.ts";
 import type { PrerequisiteReport } from "./capabilities.ts";
 import type {
@@ -90,9 +90,17 @@ export function renderStatus(input: StatusInput): string {
   lines.push("");
   lines.push(`| role | model | thinking |`);
   lines.push(`| --- | --- | --- |`);
-  const extra = Object.keys(config.models).filter((role) => !MODEL_ROLES.includes(role)).sort();
+  const extra = Object.keys(config.models)
+    .filter((role) => !MODEL_ROLES.includes(role) && !PANEL_ROLES.includes(role))
+    .sort();
+  const general = config.models[GENERAL_ROLE];
   for (const role of [...MODEL_ROLES, ...extra]) {
     const configured = config.models[role];
+    if (configured === undefined && general !== undefined) {
+      const spec = splitModelSpec(general);
+      lines.push(`| ${role} | ${spec.model} (from ${GENERAL_ROLE}) | ${spec.thinking ?? "backend default"} (from ${GENERAL_ROLE}) |`);
+      continue;
+    }
     if (configured === undefined) {
       lines.push(`| ${role} | inherit (parent session model) | inherit (parent session thinking) |`);
       continue;
@@ -102,6 +110,25 @@ export function renderStatus(input: StatusInput): string {
   }
   lines.push("");
 
+  lines.push(`## Panel roles`);
+  lines.push("");
+  lines.push("A panel runs one seat per entry. An unset panel uses `judgment`, then `general`.");
+  lines.push("");
+  lines.push(`| panel | seats | source |`);
+  lines.push(`| --- | --- | --- |`);
+  const panels = PANEL_ROLES.map((panel) => resolvePanel(config, panel));
+  for (const panel of panels) {
+    lines.push(`| ${panel.role} | ${panel.seats.map(describeSeat).join("; ")} | ${panel.configured ? "configured" : `unset, so ${PANEL_DEFAULT_ROLES.join(", ")}`} |`);
+  }
+  lines.push("");
+  for (const panel of panels) {
+    const warning = panelWarning(panel, config);
+    if (warning) {
+      lines.push(`> Warning. ${warning}`);
+      lines.push("");
+    }
+  }
+
   lines.push(`## Support tiers`);
   lines.push("");
   const byTier = groupByTier(input.generation);
@@ -134,6 +161,99 @@ export function renderStatus(input: StatusInput): string {
   return lines.join("\n");
 }
 
+/** One seat of a panel. `spec` is undefined when the seat runs on the model of the agent that starts the panel. */
+export interface PanelSeat {
+  readonly spec?: ModelSpec;
+  /** The role a default seat came from, such as `general` for an unset `judgment`. */
+  readonly from?: string;
+}
+
+export interface ResolvedPanel {
+  readonly role: string;
+  readonly configured: boolean;
+  readonly seats: readonly PanelSeat[];
+}
+
+/** A single role's model as delegation resolves it: the role, then `general`, then the parent. */
+function resolveRoleSeat(config: AdapterConfig, role: string): PanelSeat {
+  const configured = config.models[role];
+  if (configured !== undefined) return { spec: splitModelSpec(configured), from: role };
+  const general = config.models[GENERAL_ROLE];
+  if (general !== undefined) return { spec: splitModelSpec(general), from: GENERAL_ROLE };
+  return { from: role };
+}
+
+export function resolvePanel(config: AdapterConfig, role: string): ResolvedPanel {
+  const configured = config.models[role];
+  if (configured !== undefined) {
+    return {
+      role,
+      configured: true,
+      seats: panelEntries(configured).map((entry) => (entry.kind === "inherit" ? {} : { spec: entry.spec })),
+    };
+  }
+  return { role, configured: false, seats: defaultSeats(config) };
+}
+
+/** The seats an unset panel gets, which are also the default pool arena falls back to. */
+function defaultSeats(config: AdapterConfig): PanelSeat[] {
+  return PANEL_DEFAULT_ROLES.map((name) => resolveRoleSeat(config, name));
+}
+
+function describeSeat(seat: PanelSeat): string {
+  const origin = seat.from ? ` (${seat.from})` : "";
+  if (!seat.spec) return `model of the agent that starts the panel${origin}`;
+  return `${seat.spec.model} at ${seat.spec.thinking ?? "backend default"}${origin}`;
+}
+
+const PARENT_MODEL = "the model of the agent that starts the panel";
+
+/**
+ * Upstream's default panels span two model families. A panel whose seats all land on one model
+ * lost that because of configuration, not because no other model exists, so say so where the
+ * agent reads it. Families are left to the agent, which knows them better than a prefix list.
+ */
+export function panelWarning(panel: ResolvedPanel, config: AdapterConfig): string | undefined {
+  const models = new Set(panel.seats.map((seat) => seat.spec?.model ?? PARENT_MODEL));
+  const pool = panel.role === "arena-cross-judge-pool";
+  // Upstream lets a panel line hold one entry on purpose, so only the judge pool warns at one seat.
+  if (models.size !== 1 || (panel.seats.length < 2 && !pool)) return undefined;
+  const [model] = [...models];
+  const named = model === PARENT_MODEL ? PARENT_MODEL : `\`${model}\``;
+  const cause = panel.configured
+    ? `its configured entries all name ${named}`
+    : `it is unset, and ${PANEL_DEFAULT_ROLES.map((role) => `\`${role}\``).join(" and ")} both resolve to ${named}`;
+  return `Every seat of \`${panel.role}\` runs on ${named}, because ${cause}, ${pool ? poolEffect(panel, config, model) : "so the panel has one model and no second family"}. This comes from the adapter configuration, not from which models are available. Run \`/skill:${config.namespace}-setup\` to put this panel on two model families, as upstream's defaults do.`;
+}
+
+/**
+ * Arena's judge is never from the session's family. When no pool entry qualifies, upstream tries
+ * its default pool, which here is `judgment`, then `general`, before it skips the judge.
+ */
+function poolEffect(panel: ResolvedPanel, config: AdapterConfig, model: string | undefined): string {
+  const fallback = defaultSeats(config);
+  const fallbackModels = new Set(fallback.map((seat) => seat.spec?.model ?? PARENT_MODEL));
+  const lead =
+    model === PARENT_MODEL
+      ? "and an `inherit` entry never judges, so arena"
+      : `so a session on the family of \`${model}\` gets no judge from the pool, and arena`;
+  const sameFallback = !panel.configured || (fallbackModels.size === 1 && fallbackModels.has(model ?? PARENT_MODEL));
+  return sameFallback
+    ? `${lead} skips the judge`
+    : `${lead} tries its default pool, ${fallback.map(describeSeat).join("; ")}, before it skips the judge`;
+}
+
+/** The panels a workflow reads, for its `check` report. */
+export function renderPanels(config: AdapterConfig, roles: readonly string[]): string {
+  const lines = roles.map((role) => {
+    const panel = resolvePanel(config, role);
+    const source = panel.configured ? "configured" : `unset, so ${PANEL_DEFAULT_ROLES.join(", ")}`;
+    const warning = panelWarning(panel, config);
+    return `- \`${role}\` (${source}): ${panel.seats.map(describeSeat).join("; ")}.${warning ? ` Warning. ${warning}` : ""}`;
+  });
+  return `Panels this workflow uses, one seat per entry:\n${lines.join("\n")}`;
+}
+
 function describeDelegation(capabilities: readonly CapabilityStatus[]): string {
   const backend = capabilities.find((capability) => capability.id === "delegation")?.backend;
   if (!backend) return "none available";
@@ -172,6 +292,8 @@ export function renderCheck(
   report: PrerequisiteReport,
   /** The resolved `delegation` capability, named for a workflow that delegates. */
   delegation?: CapabilityStatus,
+  /** The workflow's panels, from `renderPanels`. */
+  panels?: string,
 ): string {
   const parts = [`\`/skill:${skill.generatedName}\` is tier **${skill.tier}**.`];
   if (entry.note) parts.push(entry.note);
@@ -190,6 +312,7 @@ export function renderCheck(
       delegation?.backend ? delegationInstruction(delegation.backend, delegation.tools) : "No delegation tool is usable in this session, so do not delegate.",
     );
   }
+  if (panels && skill.tier !== "unsupported") parts.push(panels);
   if (skill.tier === "experimental" && report.ok) {
     parts.push("Tier `experimental` means parts of this workflow have no Pi equivalent. Expect gaps.");
   }

package/src/upstream.ts

@@ -1,5 +1,5 @@
 import { execFile } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { promisify } from "node:util";
 import { MANIFEST_RELATIVE_PATH } from "./manifest.ts";
@@ -202,7 +202,7 @@ async function reuseCheckout(
   wanted: string,
   pluginPath: string,
 ): Promise<{ commit: string; pluginDir: string } | undefined> {
-  if (!existsSync(join(dir, ".git"))) return undefined;
+  if (!(await isCacheCheckout(git, dir))) return undefined;
   if ((await git(["cat-file", "-e", `${wanted}^{commit}`], dir)).code !== 0) return undefined;
 
   // A read-only cache cannot take the setting. That is fine while its files are already LF, and
@@ -307,15 +307,43 @@ async function headCommit(git: GitRunner, dir: string): Promise<string> {
   return result.code === 0 ? result.stdout.trim() : "";
 }
 
+/**
+ * Git discovers ancestor repositories from an empty cache inside a project. A successful
+ * rev-parse alone therefore does not authorize config, fetch, or checkout. Adapter caches
+ * must own both their worktree and standalone metadata, including the common directory.
+ */
+async function isCacheCheckout(git: GitRunner, dir: string): Promise<boolean> {
+  const metadata = join(dir, ".git");
+  try {
+    const entry = lstatSync(metadata);
+    if (!entry.isDirectory() || entry.isSymbolicLink()) return false;
+    const identity = await git([
+      "rev-parse", "--show-toplevel", "--absolute-git-dir", "--git-common-dir",
+    ], dir);
+    if (identity.code !== 0) return false;
+    const paths = identity.stdout.trim().split(/\r?\n/);
+    if (paths.length !== 3) return false;
+    return [dir, metadata, metadata].every((expected, index) => {
+      const actual = paths[index];
+      return actual !== undefined && relative(realpathSync.native(expected), realpathSync.native(resolve(dir, actual))) === "";
+    });
+  } catch {
+    return false;
+  }
+}
+
 async function bootstrap(git: GitRunner, dir: string, repo: string, ref: string, pluginPath: string): Promise<void> {
   mkdirSync(dir, { recursive: true });
-  if ((await git(["rev-parse", "--git-dir"], dir)).code === 0) {
+  if (await isCacheCheckout(git, dir)) {
     await git(["remote", "set-url", "origin", repo], dir);
   } else {
     // A half-created or damaged cache is disposable. Start it over rather than repairing it.
     rmSync(dir, { recursive: true, force: true });
     mkdirSync(dir, { recursive: true });
     await expect(git(["init", "--quiet", "."], dir), "initialize the adapter cache checkout");
+    if (!(await isCacheCheckout(git, dir))) {
+      throw new Error(`The pstack adapter cache at ${dir} could not verify ownership of its Git worktree and metadata after initialization. Check directory permissions and inherited Git directory overrides, then start Pi again.`);
+    }
     await expect(git(["remote", "add", "origin", repo], dir), `add ${repo} as the cache remote`);
   }
   await pinLineEndings(git, dir);

package/src/vocabulary.ts

@@ -0,0 +1,123 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import type { Diagnostic } from "./types.ts";
+
+/**
+ * A Cursor name that an upstream body can use. `key` must appear in the Cursor column of a
+ * host mapping row, so deleting the row, or adding a term without one, fails certification.
+ */
+export interface CursorTerm {
+  readonly key: string;
+  readonly pattern: RegExp;
+}
+
+/**
+ * Ported from the `TERMS` list in upstream's `scripts/generate-pstack-harness-trees.mjs`, which
+ * fails when a skill uses a term that `pstack/docs/harness/claude-code.md` has no row for. The
+ * keys name this adapter's rows. Upstream's single "Cursor-only features" term is split into one
+ * term per feature, and the terms after it cover rows upstream does not scan for.
+ */
+export const CURSOR_TERMS: readonly CursorTerm[] = [
+  { key: "`Task` tool", pattern: /`Task`|\bTask (tool|subagent|call)/ },
+  { key: "`AskQuestion`", pattern: /AskQuestion/ },
+  { key: "todolist", pattern: /\btodo ?list\b/i },
+  { key: "`subagent_type: generalPurpose`", pattern: /generalPurpose/ },
+  { key: "`poteto-agent`", pattern: /poteto-agent/ },
+  { key: "`comment-sicko`", pattern: /comment-sicko/ },
+  { key: "`readonly: true`", pattern: /readonly: true|readonly\/Ask/ },
+  { key: "`readonly: false`", pattern: /readonly: false/ },
+  { key: "`environment: \"cloud\"`", pattern: /environment: "cloud"/ },
+  { key: "`environment: \"local\"`", pattern: /environment: "local"/ },
+  { key: "`cloud_base_branch`", pattern: /cloud_base_branch/ },
+  { key: "`run_in_background: true`", pattern: /run_in_background/ },
+  { key: "`resume`", pattern: /`resume`/ },
+  { key: "`file_attachments`", pattern: /file_attachments/ },
+  { key: "`claude-opus-5-5-xhigh`", pattern: /\bclaude-[a-z]+-\d/ },
+  { key: "`grok-4.7-xhigh-fast`", pattern: /\bgrok-\d/ },
+  { key: "`gpt-*`", pattern: /\bgpt-\d/ },
+  { key: "`inherit-parent`", pattern: /inherit-parent/ },
+  { key: "`~/.cursor/rules/pstack-models.mdc`", pattern: /pstack-models\.mdc/ },
+  { key: "`.cursor/skills/`", pattern: /\.cursor\/skills/ },
+  { key: "`~/.cursor/plugins/`", pattern: /\.cursor\/plugins|\.cursor-plugin/ },
+  // pstack-models.mdc has its own row, so it does not count as a use of the general rule row.
+  { key: "`.cursor/rules/*.mdc`", pattern: /\.cursor\/rules(?!\/pstack-models\.mdc)|always-applied rule/ },
+  { key: "agent-transcripts", pattern: /agent-transcripts|\.cursor\/projects/ },
+  { key: "Bugbot", pattern: /Bugbot/ },
+  { key: "Cursor Automations", pattern: /Cursor [Aa]utomation|cursor\.(sh|com)\/automations/ },
+  { key: "Cursor cloud agents", pattern: /[Cc]loud [Aa]gent/ },
+  { key: "a built-in PR tool", pattern: /built-in PR tool/i },
+  { key: "`Grep`, `Glob`", pattern: /\bGrep\b|\bGlob\b/ },
+  { key: "`AskUserQuestion`", pattern: /AskUserQuestion/ },
+  { key: "`TodoWrite`", pattern: /TodoWrite|TaskCreate|TaskUpdate/ },
+  { key: "`/visualize`", pattern: /\/visualize\b/ },
+  { key: "Cursor `/loop`", pattern: /(^|[\s(`])\/loop\b/ },
+  { key: "a skill under `plugins/cache/`", pattern: /plugins\/cache\// },
+  { key: "a Custom Mode", pattern: /Custom Mode/ },
+];
+
+/** One upstream Markdown file, named by its skill and its path inside the skill directory. */
+export interface SkillMarkdown {
+  readonly skill: string;
+  readonly path: string;
+  readonly text: string;
+}
+
+/**
+ * The entry file generation reads, then every other Markdown file under the skill directory in
+ * sorted path order. The entry is read through `entryPath` even when it is a symbolic link,
+ * because generation follows it too. Other symbolic links below `dir` are not followed, as
+ * generation skips them when it copies support files. `dir` itself comes from discovery, which
+ * lists only real directories, not symbolic links, under the manifest's skills directory.
+ */
+export function skillMarkdown(skill: string, dir: string, entryPath: string): SkillMarkdown[] {
+  const files: SkillMarkdown[] = [{ skill, path: "SKILL.md", text: readFileSync(entryPath, "utf8") }];
+  const visit = (current: string) => {
+    for (const entry of readdirSync(current, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      const path = join(current, entry.name);
+      if (current === dir && entry.name === "SKILL.md") continue;
+      if (entry.isSymbolicLink()) continue;
+      if (entry.isDirectory()) visit(path);
+      else if (entry.isFile() && entry.name.endsWith(".md")) {
+        files.push({ skill, path: relative(dir, path).split(sep).join("/"), text: readFileSync(path, "utf8") });
+      }
+    }
+  };
+  visit(dir);
+  return files;
+}
+
+/** The Cursor column of every table row in a host mapping document. */
+export function mappedCursorNames(mapping: string): string[] {
+  return mapping
+    .split(/\r?\n/)
+    .filter((line) => line.startsWith("| ") && !/^\| [-\s|]+$/.test(line))
+    .map((line) => {
+      const end = line.indexOf(" | ", 1);
+      return end < 0 ? line.slice(2) : line.slice(2, end);
+    });
+}
+
+/**
+ * One warning per term that an upstream skill uses and no host mapping row names, in term order
+ * with skills sorted, so a revision with new Cursor vocabulary fails certification.
+ */
+export function vocabularyDiagnostics(
+  files: readonly SkillMarkdown[],
+  mapping: string,
+  terms: readonly CursorTerm[] = CURSOR_TERMS,
+): Diagnostic[] {
+  const cursorColumn = mappedCursorNames(mapping);
+  const diagnostics: Diagnostic[] = [];
+  for (const term of terms) {
+    if (cursorColumn.some((cell) => cell.includes(term.key))) continue;
+    const skills = [...new Set(files.filter((file) => term.pattern.test(file.text)).map((file) => file.skill))].sort();
+    if (skills.length === 0) continue;
+    diagnostics.push({
+      level: "warning",
+      resource: `host-mapping:${term.key}`,
+      message: `Upstream ${skills.length === 1 ? "skill" : "skills"} ${skills.map((name) => `\`${name}\``).join(", ")} ${skills.length === 1 ? "uses" : "use"} the Cursor term ${term.key}, but no host mapping row names it in its Cursor column, so Pi would have to guess what it means.`,
+      action: `Read what the term means in those skills and in upstream's pstack/docs/harness/claude-code.md at this commit, then add a row that names ${term.key} to hostMappingDocument in src/generate.ts and rerun the probe.`,
+    });
+  }
+  return diagnostics;
+}