@mgiles/perk 1.1.0 → 2.0.0

package/extension/substrate/config.ts

@@ -4,8 +4,9 @@
 // `perk:plan-context` injection (extension/factories/planMode.ts) when present.
 //
 // Deliberately dependency-free: rather than pull a runtime TOML dependency into the published
-// extension for a single optional string, this reads the narrow TOML subset perk actually uses —
-// `[section]` headers + `key = "basic"` / `key = """multiline"""` string values + `#` comments.
+// extension, this reads the narrow TOML subset perk actually uses — `[section]` headers +
+// `[[name]]` array-of-tables + `key = "basic"` / `key = """multiline"""` strings + native
+// booleans/numbers + `#` comments.
 // Read-only, LBYL: a missing/unreadable file is `{}`; anything outside the subset is ignored.
 // Dynamic `resources_discover` skill/prompt contribution is a flagged follow-up, not built here.
 
@@ -14,7 +15,13 @@ import { parseUserBindings, type SkillBinding } from "./bindings.ts";
 import { configFile, localConfigFile } from "./paths.ts";
 
 /**
- * One configured CI check (a `[[ci]]` array-of-tables row). `name`/`command` are required
+ * A TOML scalar the subset parser reads: quoted strings plus native booleans and numbers.
+ * Anything else (dates, arrays, inline tables) is still deliberately ignored.
+ */
+export type TomlScalar = string | boolean | number;
+
+/**
+ * One configured CI check (a `[[ci.checks]]` array-of-tables row). `name`/`command` are required
  * non-blank strings; an optional `glob` (a single comma-separated pattern string, e.g.
  * `"*.ts,*.tsx"`) declares which changed files the check is relevant to — the read-only CI
  * executor skips it on the run-all path when no changed file (vs trunk) matches.
@@ -29,19 +36,26 @@ export interface PerkConfig {
   /** Optional project-supplied plan-authoring addendum (`[workflow] plan_authoring = "..."`). */
   planAuthoring?: string;
   /**
-   * The `[[ci]]` checks (an ordered array-of-tables, each row name/command/optional glob); the
-   * read-only CI executor consumes it. Always-present ordered array (mirror of
-   * `bindings`/`providers`); absent/empty ⇒ `[]`.
+   * The `[ci]` verification namespace. `checks` is the `[[ci.checks]]` ordered array-of-tables
+   * (each row name/command/optional glob) the read-only CI executor consumes; absent/empty ⇒ `[]`.
+   * `trusted` (`[ci] trusted = true`, a native boolean) declares those project-supplied checks
+   * trusted, so the executor runs them WITHOUT a per-session confirm on every surface, including
+   * headless (it overrides the fail-closed refuse). Absent/`false`/non-boolean ⇒ untrusted
+   * (confirm with UI; refuse headless). Always present; defaults `{trusted: false, checks: []}`.
    */
-  ci: CiCheck[];
+  ci: { trusted: boolean; checks: CiCheck[] };
   /**
-   * The agent-keyed `[subagents]` table: a per-agent model override for each perk-owned
+   * The agent-keyed `[models.subagents]` table: a per-agent model override for each perk-owned
    * project agent (`pr-reviewer`, `review-classifier`, `objective-explorer`, `conflict-resolver`,
-   * `learn-analyst`). Each configured
+   * `learn-analyst`, `adversarial-reviewer`). Each configured
    * value is injected as a per-call inline `model` override on that agent's `subagent` spawn; when
    * a key is absent the agent's frontmatter `model` (in `.pi/agents/<name>.md`) is the default.
    * (`subagents.agentOverrides` does NOT reach project agents — `pi-subagents`'
    * `applyBuiltinOverrides` applies only to builtins — so this inline override is the mechanism.)
+   * A value may carry a `:thinking` suffix (`"anthropic/claude-sonnet-4-5:high"`) or be the
+   * `"inherit"` sentinel (child inherits the parent session's model) — both resolved by
+   * pi-subagents on the inline override (the last-colon segment counts as thinking only when it
+   * is a pi level, so ollama-style tags stay part of the model id).
    * Always-present object; absent keys omitted (mirror of `providers`).
    */
   subagents: {
@@ -50,11 +64,13 @@ export interface PerkConfig {
     "objective-explorer"?: string;
     "conflict-resolver"?: string;
     "learn-analyst"?: string;
+    "adversarial-reviewer"?: string;
   };
   /**
-   * Optional `[objective] compact_threshold` — the context-usage fraction (0,1] that triggers
-   * threshold compaction while an objective is active. Because the TOML subset reads only
-   * string values, it must be written as a quoted string (e.g. `compact_threshold = "0.8"`).
+   * Optional `[compaction] objective_threshold` — the context-usage fraction (0,1] that triggers
+   * threshold compaction while an objective is active. A native TOML float (e.g.
+   * `objective_threshold = 0.8`); string/out-of-range values are ignored. The Python plane
+   * deliberately ignores this key (it converges the rest of `[compaction]` into settings).
    */
   objectiveCompactThreshold?: number;
   /** The `[[bindings]]` user overlay, resolved against shipped defaults downstream. */
@@ -64,28 +80,25 @@ export interface PerkConfig {
    * `shared/providers.yaml`. Absent keys mean “use the seam default”; resolution against the
    * supported set is a downstream concern.
    */
-  providers: { plan?: string; todo?: string; askuser?: string; footer?: string; web?: string };
-  /**
-   * The `[trust]` per-repo trust table. `trust.ci === true` (written `ci = "true"` — the subset
-   * parser reads strings only) declares the project's `[ci]` checks trusted, so the read-only CI
-   * executor runs them WITHOUT a per-session confirm on every surface, including headless
-   * (it overrides the fail-closed refuse). Absent/"false" ⇒ unchanged (confirm with UI; refuse
-   * headless). Always-present object; absent keys omitted (mirror of `providers`). The table may
-   * grow further trust keys later.
-   */
-  trust: { ci?: boolean };
+  providers: {
+    plan?: string;
+    todo?: string;
+    askuser?: string;
+    footer?: string;
+    web?: string;
+  };
 }
 
-/** A nested string table: `{ section: { key: value } }` (the only shape perk reads today). */
-type StringTable = Record<string, Record<string, string>>;
+/** A nested scalar table: `{ section: { key: scalar } }` (dotted section names kept literal). */
+type ScalarTable = Record<string, Record<string, TomlScalar>>;
 
 /**
- * The narrow TOML subset perk reads: `[section]`/top-level string tables plus `[[name]]`
- * array-of-tables (each row a string table). Mirrors `tomllib`'s shape for the keys perk uses.
+ * The narrow TOML subset perk reads: `[section]`/top-level scalar tables plus `[[name]]`
+ * array-of-tables (each row a scalar table). Mirrors `tomllib`'s shape for the keys perk uses.
  */
 interface TomlSubset {
-  tables: StringTable;
-  arrays: Record<string, Array<Record<string, string>>>;
+  tables: ScalarTable;
+  arrays: Record<string, Array<Record<string, TomlScalar>>>;
 }
 
 function unescapeBasic(raw: string): string {
@@ -98,16 +111,17 @@ function unescapeBasic(raw: string): string {
 
 /**
  * Parse the narrow TOML subset perk consumes. Returns `{ tables, arrays }`: `tables` is a
- * `{ section: { key: stringValue } }` map (top-level keys under the `""` section); `arrays` is a
- * `{ name: [{ key: stringValue }, ...] }` map fed by `[[name]]` array-of-tables. Non-string values
- * and unknown syntax are skipped — this is intentionally NOT a full TOML parser.
+ * `{ section: { key: scalar } }` map (top-level keys under the `""` section); `arrays` is a
+ * `{ name: [{ key: scalar }, ...] }` map fed by `[[name]]` array-of-tables. Scalars are quoted
+ * strings, native `true`/`false` booleans, and numeric literals; anything else is skipped —
+ * this is intentionally NOT a full TOML parser.
  */
 export function parseTomlSubset(text: string): TomlSubset {
-  const root: Record<string, string> = {};
-  const tables: StringTable = { "": root };
-  const arrays: Record<string, Array<Record<string, string>>> = {};
+  const root: Record<string, TomlScalar> = {};
+  const tables: ScalarTable = { "": root };
+  const arrays: Record<string, Array<Record<string, TomlScalar>>> = {};
   // The current write target for `key = value` lines (a section table or an array-of-tables row).
-  let dest: Record<string, string> = root;
+  let dest: Record<string, TomlScalar> = root;
   const lines = text.split(/\r?\n/);
   for (let i = 0; i < lines.length; i++) {
     const line = (lines[i] ?? "").trim();
@@ -117,7 +131,7 @@ export function parseTomlSubset(text: string): TomlSubset {
     const arrayHeader = line.match(/^\[\[([^\]]+)\]\]$/);
     if (arrayHeader) {
       const name = (arrayHeader[1] ?? "").trim();
-      const row: Record<string, string> = {};
+      const row: Record<string, TomlScalar> = {};
       let rows = arrays[name];
       if (!rows) {
         rows = [];
@@ -173,8 +187,21 @@ export function parseTomlSubset(text: string): TomlSubset {
     const basic = value.match(/^"((?:[^"\\]|\\.)*)"/);
     if (basic) {
       dest[key] = unescapeBasic(basic[1] ?? "");
+      continue;
+    }
+
+    // Unquoted scalar: strip an inline `#` comment, then read native booleans and numbers.
+    const hash = value.indexOf("#");
+    const bare = (hash === -1 ? value : value.slice(0, hash)).trim();
+    if (bare === "true" || bare === "false") {
+      dest[key] = bare === "true";
+      continue;
     }
-    // Non-string scalars are intentionally ignored (perk reads only strings today).
+    if (/^[+-]?\d[\d_]*(\.[\d_]+)?([eE][+-]?\d+)?$/.test(bare)) {
+      const parsed = Number(bare.replace(/_/g, ""));
+      if (Number.isFinite(parsed)) dest[key] = parsed;
+    }
+    // Other value shapes (dates, arrays, inline tables) are intentionally ignored.
   }
   return { tables, arrays };
 }
@@ -199,12 +226,12 @@ function readTomlFile(path: string): TomlSubset {
  * replace as a whole array (mirror of perk/substrate/config.py's list-replaces-list overlay).
  */
 function overlay(base: TomlSubset, over: TomlSubset): TomlSubset {
-  const tables: StringTable = {};
+  const tables: ScalarTable = {};
   for (const [section, kv] of Object.entries(base.tables)) tables[section] = { ...kv };
   for (const [section, kv] of Object.entries(over.tables)) {
     tables[section] = { ...(tables[section] ?? {}), ...kv };
   }
-  const arrays: Record<string, Array<Record<string, string>>> = { ...base.arrays };
+  const arrays: Record<string, Array<Record<string, TomlScalar>>> = { ...base.arrays };
   for (const [name, rows] of Object.entries(over.arrays)) arrays[name] = rows;
   return { tables, arrays };
 }
@@ -217,30 +244,33 @@ export function loadPerkConfig(cwd: string): PerkConfig {
   }
 
   const planAuthoring = merged.tables.workflow?.plan_authoring;
-  const rawThreshold = merged.tables.objective?.compact_threshold;
-  const parsedThreshold = rawThreshold != null ? Number.parseFloat(rawThreshold) : Number.NaN;
+  // `[compaction] objective_threshold` is a native float in (0,1]; strings/out-of-range ignored.
+  const rawThreshold = merged.tables.compaction?.objective_threshold;
   const objectiveCompactThreshold =
-    Number.isFinite(parsedThreshold) && parsedThreshold > 0 && parsedThreshold <= 1
-      ? parsedThreshold
+    typeof rawThreshold === "number" && rawThreshold > 0 && rawThreshold <= 1
+      ? rawThreshold
       : undefined;
   return {
     planAuthoring:
       typeof planAuthoring === "string" && planAuthoring.trim() ? planAuthoring : undefined,
-    ci: parseCiChecks(merged.arrays.ci ?? []),
-    subagents: parseSubagentsSelection(merged.tables.subagents),
+    ci: {
+      trusted: merged.tables.ci?.trusted === true,
+      checks: parseCiChecks(merged.arrays["ci.checks"] ?? []),
+    },
+    subagents: parseSubagentsSelection(merged.tables["models.subagents"]),
     objectiveCompactThreshold,
     bindings: parseUserBindings(merged.arrays.bindings ?? []),
     providers: parseProvidersSelection(merged.tables.providers),
-    trust: parseTrustSelection(merged.tables.trust),
   };
 }
 
 /**
- * Read the `[[ci]]` array-of-tables into an ordered `CiCheck[]`. A row is kept only when both
- * `name` and `command` are non-blank strings; `glob` is kept only when a non-blank string. Declared
- * order is preserved; ill-typed rows are silently dropped (mirror of `parseProvidersSelection`).
+ * Read the `[[ci.checks]]` array-of-tables into an ordered `CiCheck[]`. A row is kept only when
+ * both `name` and `command` are non-blank strings; `glob` is kept only when a non-blank string.
+ * Declared order is preserved; ill-typed rows are silently dropped (mirror of
+ * `parseProvidersSelection`).
  */
-export function parseCiChecks(rows: Array<Record<string, string>>): CiCheck[] {
+export function parseCiChecks(rows: Array<Record<string, TomlScalar>>): CiCheck[] {
   const checks: CiCheck[] = [];
   for (const row of rows) {
     const name = row.name;
@@ -255,22 +285,23 @@ export function parseCiChecks(rows: Array<Record<string, string>>): CiCheck[] {
   return checks;
 }
 
-/** The perk-owned project agents configurable via the `[subagents]` table. */
+/** The perk-owned project agents configurable via the `[models.subagents]` table. */
 const SUBAGENT_KEYS = [
   "pr-reviewer",
   "review-classifier",
   "objective-explorer",
   "conflict-resolver",
   "learn-analyst",
+  "adversarial-reviewer",
 ] as const;
 
 /**
- * Read the agent-keyed `[subagents]` table into a selection (string values only). For each known
- * agent key, the value is kept only when it is a non-blank string; absent/ill-typed/unknown keys
- * are omitted (mirror of `parseProvidersSelection`).
+ * Read the agent-keyed `[models.subagents]` table into a selection (string values only). For each
+ * known agent key, the value is kept only when it is a non-blank string; absent/ill-typed/unknown
+ * keys are omitted (mirror of `parseProvidersSelection`).
  */
 function parseSubagentsSelection(
-  table: Record<string, string> | undefined,
+  table: Record<string, TomlScalar> | undefined,
 ): PerkConfig["subagents"] {
   const selection: PerkConfig["subagents"] = {};
   for (const key of SUBAGENT_KEYS) {
@@ -280,16 +311,8 @@ function parseSubagentsSelection(
   return selection;
 }
 
-/** Read the `[trust]` table into a `{ci?}` selection. `ci` is true only for the string "true". */
-function parseTrustSelection(table: Record<string, string> | undefined): { ci?: boolean } {
-  const selection: { ci?: boolean } = {};
-  if (typeof table?.ci === "string" && table.ci.trim().toLowerCase() === "true")
-    selection.ci = true;
-  return selection;
-}
-
-/** Read the flat `[providers]` table into a `{plan?, todo?, askuser?, footer?, web?}` selection (string values only). */
-function parseProvidersSelection(table: Record<string, string> | undefined): {
+/** Read the flat `[providers]` table into a `{plan?, todo?, askuser?, footer?, web?}` selection (string values only). A retired `review` key is silently ignored (the TS fail-safe posture; the Python plane's tripwire is the loud surface). */
+function parseProvidersSelection(table: Record<string, TomlScalar> | undefined): {
   plan?: string;
   todo?: string;
   askuser?: string;

package/extension/substrate/git.ts

@@ -32,3 +32,46 @@ export function mainCheckoutRoot(cwd: string): string {
   const common = isAbsolute(out) ? out : resolve(cwd, out);
   return resolve(common, "..");
 }
+
+/** Run one git command; trimmed stdout, or null on any failure (the module's fail-open style). */
+function git(cwd: string, args: string[], timeout?: number): string | null {
+  try {
+    const out = execFileSync("git", args, {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      ...(timeout !== undefined ? { timeout } : {}),
+    }).trim();
+    return out === "" ? null : out;
+  } catch {
+    return null;
+  }
+}
+
+/** The bounded best-effort `git fetch` budget (ms) — see `sinceBaseSha` step 2. */
+const FETCH_TIMEOUT_MS = 15_000;
+
+/**
+ * The since-base merge-base of the working tree: `merge-base(HEAD, origin/<base>)` — the sha the
+ * terminal review door diffs the active worktree against. **Fail-open**: null on any failure
+ * (not a repo, no such ref, git missing), never throws.
+ *
+ * 1. Resolve the base branch name: `base` when given; else the repo default via
+ *    `git symbolic-ref --short refs/remotes/origin/HEAD` (`origin/main` → `main`).
+ * 2. Best-effort `git fetch origin <branch>` with a bounded timeout — a failure (offline, no
+ *    remote) is swallowed and the stale local ref is used, keeping the door usable offline (and
+ *    the test scaffold network-free).
+ * 3. `git merge-base HEAD origin/<branch>` → the full sha.
+ */
+export function sinceBaseSha(cwd: string, base: string | null | undefined): string | null {
+  let branch = base ?? null;
+  if (branch === null) {
+    const head = git(cwd, ["symbolic-ref", "--short", "refs/remotes/origin/HEAD"]);
+    if (head === null) return null;
+    // `origin/main` → `main` (keep anything after the first slash — branch names may carry `/`).
+    branch = head.includes("/") ? head.slice(head.indexOf("/") + 1) : head;
+  }
+  if (branch === "") return null;
+  git(cwd, ["fetch", "origin", branch], FETCH_TIMEOUT_MS);
+  return git(cwd, ["merge-base", "HEAD", `origin/${branch}`]);
+}

package/extension/substrate/paths.ts

@@ -6,7 +6,7 @@
 // `.pi/perk.toml` migration is Python-side). The workflow family lives in the established cache
 // seam (substrate/cache.ts's `workflowDir`); together these two modules own every perk-owned
 // dot-path on this plane.
-// Objective #878 migrates each family to `.perk/` one phase at a time — redirecting a family is a
+// Remaining families migrate to `.perk/` one at a time — redirecting a family is a
 // single edit here. **Pi-native** `.pi/...` paths (`.pi/settings.json`, `.pi/agents/`, `.pi/npm`,
 // `.pi/APPEND_SYSTEM.md`) are intentionally NOT owned here — `.pi/` is not generally perk-owned.
 //

package/extension/substrate/prompts.ts

@@ -15,8 +15,8 @@
 // keeps the extension zero-runtime-dep / loadable from a bare git clone (guarded by
 // extension/bareImportGuard.test.ts).
 //
-// This seam is LIVE in production: render is imported by extension/worker/worker.ts, the
-// learn/address/learnDocs/lifecycleGates doors, and extension/factories/objectivePlan.ts.
+// This seam is LIVE in production: render is imported by the worker, the warm doors, the
+// factories, and the mode/adapter context modules (the `prompts/contexts/` injections).
 
 import { render as miniJinjaRender } from "./miniJinja.ts";
 

package/extension/substrate/providers.ts

@@ -2,8 +2,8 @@
 //
 // Twin of perk/substrate/providers.py: both planes parse the SAME bundled file (no codegen). This is the
 // THIRD parsed cross-plane contract (after registry.yaml and bindings.yaml). It is the SUPPORTED
-// SET — the catalog of plan/todo/askuser/footer/web providers perk knows how to wire — distinct from
-// the per-repo SELECTION (the flat `[providers]` table in .perk/config.toml).
+// SET — the catalog of plan/todo/askuser/footer/web providers perk knows how to wire —
+// distinct from the per-repo SELECTION (the flat `[providers]` table in .perk/config.toml).
 //
 // The Python CLI is the authoritative validator (perk/substrate/providers.py); this side does a thin
 // structural parse only — no deep content validation here. `resolveProviders` is CONSUMED by
@@ -113,6 +113,47 @@ export interface ResolvedProviders {
   issues: string[];
 }
 
+/**
+ * The synthesized reference fallback per seam — the provider `resolveProviders` returns when the
+ * bundled catalog carries no `default: true` entry for that seam (version skew: a long-lived warm
+ * session's in-memory code reading a live-edited `shared/providers.yaml` across a seam
+ * add/retire, in either direction). Guarantees PER-SEAM ISOLATION: one seam's catalog gap can
+ * never collapse another seam's resolution (the plannotator plan_review no-launch incident — the
+ * retired review seam's gap collapsed the plan seam to first-party through a thrown
+ * `requireDefault` + a silent caller catch).
+ */
+const REFERENCE_FALLBACKS: Record<(typeof PROVIDER_SEAMS)[number], Provider> = {
+  plan: { id: PERK_PLAN_PROVIDER_ID, seam: "plan", package: null, adapter: null, default: true },
+  todo: {
+    id: PERK_CHECKPOINTS_PROVIDER_ID,
+    seam: "todo",
+    package: null,
+    adapter: null,
+    default: true,
+  },
+  askuser: {
+    id: PERK_ASK_USER_PROVIDER_ID,
+    seam: "askuser",
+    package: null,
+    adapter: null,
+    default: true,
+  },
+  footer: {
+    id: PERK_FOOTER_PROVIDER_ID,
+    seam: "footer",
+    package: null,
+    adapter: null,
+    default: true,
+  },
+  web: {
+    id: PI_WEB_ACCESS_PROVIDER_ID,
+    seam: "web",
+    package: "npm:pi-web-access",
+    adapter: null,
+    default: true,
+  },
+};
+
 /** The first `default: true` provider for `seam` (the validator enforces exactly one). */
 function defaultFor(set: Provider[], seam: string): Provider | undefined {
   return set.find((p) => p.seam === seam && p.default);
@@ -131,22 +172,35 @@ function byId(set: Provider[]): Map<string, Provider> {
  * For each seam, the selection resolves to the named provider **iff** the id exists AND its `seam`
  * matches the key; otherwise it falls back to `defaultFor(seam)` and appends a loud-but-non-fatal
  * issue (unknown id / seam mismatch). An **absent** key falls back to the default **silently** (the
- * zero-config default — no issue). Defaults are trusted (not re-validated). Throws if the bundled
- * set has no default for a seam (a corrupt install — the caller's try/catch fails safe). Omitting
- * `set` loads the bundled `providers.yaml`.
+ * zero-config default — no issue). Defaults are trusted (not re-validated). A seam with NO
+ * `default: true` entry in the set is PER-SEAM FAIL-OPEN: it resolves to the synthesized
+ * REFERENCE_FALLBACKS entry with a loud-but-non-fatal issue — never a throw (a throw here let one
+ * seam's catalog gap collapse every other seam's resolution through the callers' fail-safe
+ * catches; §8.10 names this a deliberate cross-plane difference — the Python `_require_default`
+ * stays strict because short-lived processes reading the wheel-bundled `perk/_shared` cannot
+ * skew). Omitting `set` loads the bundled `providers.yaml`.
  */
 export function resolveProviders(
-  selection: { plan?: string; todo?: string; askuser?: string; footer?: string; web?: string },
+  selection: {
+    plan?: string;
+    todo?: string;
+    askuser?: string;
+    footer?: string;
+    web?: string;
+  },
   set?: Provider[],
 ): ResolvedProviders {
   const providers = set ?? loadProviders();
   const ids = byId(providers);
   const issues: string[] = [];
 
-  const requireDefault = (seam: string): Provider => {
+  const requireDefault = (seam: (typeof PROVIDER_SEAMS)[number]): Provider => {
     const def = defaultFor(providers, seam);
     if (def === undefined) {
-      throw new Error(`perk: no default provider for seam \`${seam}\` — reinstall perk`);
+      issues.push(
+        `seam \`${seam}\` has no default in the bundled catalog (version skew?) — using the built-in reference`,
+      );
+      return REFERENCE_FALLBACKS[seam];
     }
     return def;
   };

package/extension/substrate/sessionPointers.ts

@@ -84,6 +84,13 @@ export function readSessionPointers(root: string, runId: string): SessionPointer
  * Best-effort: returns `true` on a successful write, `false` (with a stderr warning) on any
  * failure. Never throws. Serialized byte-compatibly with the Python writer (key order +
  * 2-space indent + trailing newline).
+ *
+ * `preserveForeign` makes the slot first-write-wins (defense in depth against pointer
+ * shadowing): when set and the slot already holds a pointer whose `pi_session_id` differs from
+ * the incoming one, the write is SKIPPED with a loud stderr warning naming both session ids
+ * (returns `false`) — so any future shadow vector surfaces instead of silently corrupting
+ * evidence. A same-session re-capture still refreshes the slot. Default `false` keeps today's
+ * overwrite semantics (each default-caller slot has exactly one legitimate writer).
  */
 export function recordSessionPointer(
   cwd: string,
@@ -91,11 +98,24 @@ export function recordSessionPointer(
   klass: SessionClass,
   site: SessionSite,
   pointer: SessionPointer,
+  opts: { preserveForeign?: boolean } = {},
 ): boolean {
   if (!runId) return false;
   const root = mainCheckoutRoot(cwd);
   try {
     const record = readSessionPointers(root, runId) ?? emptyRecord(runId);
+    const existing = record[klass][site];
+    if (
+      opts.preserveForeign === true &&
+      existing !== null &&
+      existing.pi_session_id !== pointer.pi_session_id
+    ) {
+      console.error(
+        `perk: warning: session pointer ${klass}.${site} for run ${runId} already held by ` +
+          `${existing.pi_session_id} — skipping foreign overwrite by ${pointer.pi_session_id}`,
+      );
+      return false;
+    }
     // The run id is authoritative — a record read from disk keeps its own; a fresh one is minted
     // with `runId`. (A mismatched on-disk run_id is left as-is; self-keying guarantees a match.)
     record[klass][site] = pointer;
@@ -113,6 +133,7 @@ export function recordSessionPointer(
  * Capture one session pointer into `<class>.<site>` from a session file path — the call-site
  * convenience over `recordSessionPointer`. Derives `pi_session_id` from the basename and stamps
  * `at`. A `null`/empty `sessionFile` or `runId` is a no-op (`false`) — best-effort, never throws.
+ * `preserveForeign` threads through to `recordSessionPointer`'s first-write-wins guard.
  */
 export function captureSessionPointer(args: {
   cwd: string;
@@ -121,15 +142,23 @@ export function captureSessionPointer(args: {
   site: SessionSite;
   sessionFile: string | null | undefined;
   parentSessionId?: string | null;
+  preserveForeign?: boolean;
 }): boolean {
   const { cwd, runId, klass, site, sessionFile } = args;
   if (!sessionFile || !runId) return false;
-  return recordSessionPointer(cwd, runId, klass, site, {
-    pi_session_id: basename(sessionFile),
-    session_file: sessionFile,
-    parent_pi_session_id: args.parentSessionId ?? null,
-    at: new Date().toISOString(),
-  });
+  return recordSessionPointer(
+    cwd,
+    runId,
+    klass,
+    site,
+    {
+      pi_session_id: basename(sessionFile),
+      session_file: sessionFile,
+      parent_pi_session_id: args.parentSessionId ?? null,
+      at: new Date().toISOString(),
+    },
+    { preserveForeign: args.preserveForeign },
+  );
 }
 
 /** Serialize a record byte-compatibly with the Python writer (explicit key order, null slots). */

package/extension/substrate/structuredOutput.ts

@@ -13,7 +13,6 @@
 import {
   type Api,
   type Context,
-  complete,
   type Model,
   type Static,
   type Tool,
@@ -21,6 +20,9 @@ import {
   type TSchema,
   validateToolCall,
 } from "@earendil-works/pi-ai";
+// `complete` (the old global API) lives on the /compat entrypoint from pi-ai 0.80; the root
+// keeps the types. Pi's extension loader aliases both the root and /compat to the compat entry.
+import { complete } from "@earendil-works/pi-ai/compat";
 
 /** Structurally-minimal slice of `ExtensionContext` needed to reuse the session's model + auth. */
 export interface ModelAuthContext {