@mgiles/perk 1.0.1 → 1.1.0

package/extension/substrate/sessionPointers.ts

@@ -0,0 +1,155 @@
+// The run-cache session-pointer carrier (contracts.md §8.35) — the capture side of the cross-run
+// session-pointer record. The TS twin of perk/state/session_pointers.py; both planes read/write the
+// same `session-pointers.json` (the cross-plane contract is the file).
+//
+// Each run writes only its OWN record, keyed by `run_id`, under the SHARED MAIN CHECKOUT
+// (`mainCheckoutRoot(cwd)`) so a linked-worktree run and a later resolver agree on one location. A
+// run fills only the slots it owns (planning runs → `planning.*`; implement runs →
+// `implementation.*`); the four class/site slots are always present (null when unset) so this
+// read-modify-write merges trivially and never clobbers a sibling write.
+//
+// Seam doctrine — best-effort + loud-but-non-fatal: every write is wrapped so a failure (unwritable
+// root, bad disk) warns to stderr and returns false, NEVER throws. A capture failure must never
+// wedge the save/launch/drive it rides on. Node builtins + cache.ts + git.ts only (loads under
+// `node --test`).
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { runScratchDir } from "./cache.ts";
+import { mainCheckoutRoot } from "./git.ts";
+
+export const SESSION_POINTERS_FILE = "session-pointers.json";
+
+/** One captured session pointer (a `main` or `worker` slot of a class). */
+export interface SessionPointer {
+  /** The session-file basename (matches the `perk:workflow-state` stamp). */
+  pi_session_id: string;
+  /** The absolute path known at capture (informational). */
+  session_file: string;
+  /** The inherited parent session (fork/replacement provenance), else null. */
+  parent_pi_session_id: string | null;
+  /** ISO-8601 capture time. */
+  at: string;
+}
+
+/** The two capture sites of one session class (`main` = interior, `worker` = headless). */
+export interface SessionClassPointers {
+  main: SessionPointer | null;
+  worker: SessionPointer | null;
+}
+
+/** A run's full session-pointer record (`session-pointers.json`). */
+export interface SessionPointers {
+  run_id: string;
+  planning: SessionClassPointers;
+  implementation: SessionClassPointers;
+}
+
+export type SessionClass = "planning" | "implementation";
+export type SessionSite = "main" | "worker";
+
+/** The empty four-slot record for a run (all slots null until a capture fills one). */
+function emptyRecord(runId: string): SessionPointers {
+  return {
+    run_id: runId,
+    planning: { main: null, worker: null },
+    implementation: { main: null, worker: null },
+  };
+}
+
+function sessionPointersPath(root: string, runId: string): string {
+  return join(runScratchDir(root, runId), SESSION_POINTERS_FILE);
+}
+
+/**
+ * Read a run's session-pointers record from the shared main checkout; `null` when absent or
+ * unparseable (best-effort — a corrupt record is treated as absent, never thrown). `root` is the
+ * MAIN checkout (resolve via `mainCheckoutRoot(cwd)` at the call site).
+ */
+export function readSessionPointers(root: string, runId: string): SessionPointers | null {
+  const path = sessionPointersPath(root, runId);
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf8")) as SessionPointers;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Record one session pointer into `<class>.<site>` of the run's record, under the shared main
+ * checkout (`mainCheckoutRoot(cwd)`). Read-modify-write: an existing record is loaded (or a fresh
+ * four-slot record minted), only the named slot is set, and the whole record is written back — so
+ * a planning write and an implementation write to the SAME run record never clobber each other.
+ * 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).
+ */
+export function recordSessionPointer(
+  cwd: string,
+  runId: string,
+  klass: SessionClass,
+  site: SessionSite,
+  pointer: SessionPointer,
+): boolean {
+  if (!runId) return false;
+  const root = mainCheckoutRoot(cwd);
+  try {
+    const record = readSessionPointers(root, runId) ?? emptyRecord(runId);
+    // 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;
+    const dir = runScratchDir(root, runId);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(sessionPointersPath(root, runId), serialize(record), "utf8");
+    return true;
+  } catch (error) {
+    console.error(`perk: warning: could not record session pointer (${klass}.${site}): ${error}`);
+    return false;
+  }
+}
+
+/**
+ * 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.
+ */
+export function captureSessionPointer(args: {
+  cwd: string;
+  runId: string;
+  klass: SessionClass;
+  site: SessionSite;
+  sessionFile: string | null | undefined;
+  parentSessionId?: string | null;
+}): 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(),
+  });
+}
+
+/** Serialize a record byte-compatibly with the Python writer (explicit key order, null slots). */
+function serialize(record: SessionPointers): string {
+  const slot = (p: SessionPointer | null): Record<string, unknown> | null =>
+    p === null
+      ? null
+      : {
+          pi_session_id: p.pi_session_id,
+          session_file: p.session_file,
+          parent_pi_session_id: p.parent_pi_session_id,
+          at: p.at,
+        };
+  const payload = {
+    run_id: record.run_id,
+    planning: { main: slot(record.planning.main), worker: slot(record.planning.worker) },
+    implementation: {
+      main: slot(record.implementation.main),
+      worker: slot(record.implementation.worker),
+    },
+  };
+  return `${JSON.stringify(payload, null, 2)}\n`;
+}

package/extension/substrate/toolGating.ts

@@ -33,6 +33,14 @@ export const READ_ONLY_TOOLS = [
   // working-objective artifact in the session data dir (fixed artifact name, seam-derived
   // path); the gate's edit/write/bash blocking is unchanged.
   "objective_draft",
+  // The objective_node carve-out: it never touches the worktree — it delegates a bounded,
+  // workflow-owned node transition to the canonical Python plane (`perk objective node`). Both
+  // objective-plan factory paths run gated (the cold door hands off `mode: read-only`; the warm
+  // `/objective-plan` enters the gate before seeding), and the factory loop's
+  // `objective_node_claim` carrier — which the approval-driven save's node-link recovery depends
+  // on — can only be written by calling this tool inside the gated session. Excluding it
+  // silently breaks the warm `/objective-plan` path: the plan saves unlinked.
+  "objective_node",
   // The `web` seam providers' research tools: the UNION of all known web-provider tool
   // names, allowlisted statically and inert when the package is absent (the plan_review precedent
   // — setActiveTools simply has nothing to enable). None mutate the repo — fetch_content's

package/extension/surfaces/surfaces.ts

@@ -192,7 +192,7 @@ export function createPerkStatus(): PerkStatusHandle {
 /**
  * The raw material for one composed footer line. Left group (charter order 1–3): `identity`,
  * `objective`, `checkpoints` — the segments render verbatim (they carry their own 🎯/📋 marks).
- * Right group (charter order 4, 5, +context, 6): `branch`, `model`, `context`, `guests` —
+ * Right group (charter order 4, 5, +context, 6): `branch`, `model`, `thinking`, `context`, `guests` —
  * right-aligned, non-segment system text dim-themed.
  */
 export interface FooterParts {
@@ -206,6 +206,8 @@ export interface FooterParts {
   branch?: string;
   /** Model id (dim); omitted when no model. */
   model?: string;
+  /** The session thinking level (dim; e.g. `high`/`off`); omitted when there is no model. */
+  thinking?: string;
   /** Context usage — rendered `<pct>%/<window>` (dim; warning >70, error >90; `?` when null). */
   context?: { percent: number | null; contextWindow: number };
   /** Guest extension statuses (dim), pre-sorted by slot key; sanitized here. */
@@ -236,14 +238,15 @@ function formatContextSegment(
  * Compose THE one footer line (FOOTER_MAX_LINES = 1): left group = identity + objective +
  * checkpoints (two-space-joined, charter order); right group = branch + model + context + guests
  * (two-space-joined), right-aligned with ≥2 spaces of padding. When the line exceeds `width`,
- * whole segments drop in the extended D9 order — guests (rightmost-first) → model → branch →
- * context → checkpoints; `identity` and `objective` are NEVER dropped — then `truncateToWidth`
+ * whole segments drop in the extended D9 order — guests (rightmost-first) → thinking → model →
+ * branch → context → checkpoints; `identity` and `objective` are NEVER dropped — then `truncateToWidth`
  * as the last resort (ANSI- and 2-cell-emoji-aware).
  */
 export function composeFooterLine(parts: FooterParts, theme: ThemeLike, width: number): string {
   const keep = {
     guests: parts.guests.map((g) => sanitizeGuestStatus(g)),
     model: true,
+    thinking: true,
     branch: true,
     context: true,
     checkpoints: true,
@@ -255,6 +258,7 @@ export function composeFooterLine(parts: FooterParts, theme: ThemeLike, width: n
     const right: string[] = [];
     if (keep.branch && parts.branch !== undefined) right.push(theme.fg("dim", parts.branch));
     if (keep.model && parts.model !== undefined) right.push(theme.fg("dim", parts.model));
+    if (keep.thinking && parts.thinking !== undefined) right.push(theme.fg("dim", parts.thinking));
     if (keep.context && parts.context !== undefined) {
       right.push(formatContextSegment(parts.context, theme));
     }
@@ -268,6 +272,7 @@ export function composeFooterLine(parts: FooterParts, theme: ThemeLike, width: n
   let line = compose();
   while (visibleWidth(line) > width) {
     if (keep.guests.length > 0) keep.guests.pop();
+    else if (keep.thinking) keep.thinking = false;
     else if (keep.model) keep.model = false;
     else if (keep.branch) keep.branch = false;
     else if (keep.context) keep.context = false;
@@ -293,6 +298,7 @@ export interface PerkFooterDeps {
   identity: string;
   status: PerkStatusHandle;
   getModelId(): string | null;
+  getThinkingLevel(): string | null;
   getContext(): { percent: number | null; contextWindow: number } | null;
 }
 
@@ -331,6 +337,7 @@ export function perkFooter(deps: PerkFooterDeps): PerkFooterFactory {
           checkpoints: deps.status.get("checkpoints"),
           branch: footerData.getGitBranch() ?? undefined,
           model: deps.getModelId() ?? undefined,
+          thinking: deps.getThinkingLevel() ?? undefined,
           context: deps.getContext() ?? undefined,
           guests,
         };

package/extension/worker/worker.ts

@@ -14,7 +14,9 @@
 //
 // Inverse of `extension/worker/readOnlySession.ts`: that builds a fully-isolated READ-ONLY child (loads
 // nothing, `["read","grep","find","ls"]`); the worker is the OPPOSITE — read-write defaults + the
-// real perk extension loaded from the worktree's `.pi/settings.json` (cwd-discovery), with the
+// real perk extension loaded from the worktree's `.pi/settings.json` (disk-layered settings:
+// `SettingsManager.create(worktree, throwawayAgentDir)` resolves the managed project-tier
+// `packages` list — perk + the borrowed set, the same package set as a warm session), with the
 // user-global tier locked out via a throwaway `agentDir`.
 
 import { appendFileSync, mkdtempSync } from "node:fs";
@@ -25,7 +27,6 @@ import type { Api, Model } from "@earendil-works/pi-ai";
 import {
   AuthStorage,
   type CreateAgentSessionRuntimeFactory,
-  type CreateAgentSessionServicesOptions,
   createAgentSessionFromServices,
   createAgentSessionRuntime,
   createAgentSessionServices,
@@ -37,6 +38,7 @@ import { planReadInstruction } from "../doors/lifecycleGates.ts";
 import { ensureRunScratch, type PlanRef, readPlanRef, runEventsPath } from "../substrate/cache.ts";
 import { loadPerkConfig } from "../substrate/config.ts";
 import { render } from "../substrate/prompts.ts";
+import { captureSessionPointer } from "../substrate/sessionPointers.ts";
 import { rebuildWorkflowState } from "../substrate/workflowState.ts";
 import { capForModel } from "./readOnlySession.ts";
 
@@ -115,7 +117,12 @@ export interface DriveStageOptions {
   stage: DriveStage;
   /** The seeded first prompt (see `initialPromptFor`). */
   initialPrompt: string;
-  /** Explicit model; else the first available from the registry (Gap 5). */
+  /**
+   * Explicit model; else the SDK's own default resolution picks one at session creation
+   * (settings `defaultModel` → pi's per-provider defaults → first available — Gap 5). Never
+   * pre-pinned here: `getAvailable()` sorts alphabetically, so `[0]` is the *oldest* model of
+   * the first provider (a since-removed `claude-3-5-haiku` date-pin 404'd a whole remote drive).
+   */
   model?: Model<Api>;
   authStorage?: AuthStorage;
   modelRegistry?: ModelRegistry;
@@ -126,12 +133,11 @@ export interface DriveStageOptions {
 
 /**
  * The offline seam (mirrors `readOnlySession.test.ts`'s `runTask` injection). `createRuntime`
- * overrides the production runtime factory so tests drive synthetic sessions; `resourceLoaderOptions`
- * tunes the project-tier load; `now` injects the clock for deterministic `elapsed_ms`.
+ * overrides the production runtime factory so tests drive synthetic sessions; `now` injects the
+ * clock for deterministic `elapsed_ms`.
  */
 export interface DriveStageDeps {
   createRuntime?: (opts: DriveStageOptions) => Promise<DriveRuntimeLike>;
-  resourceLoaderOptions?: CreateAgentSessionServicesOptions["resourceLoaderOptions"];
   now?: () => number;
   /** The structured run-event sink. Absent ⇒ the default run-scoped NDJSON file sink. */
   eventSink?: RunEventSink;
@@ -162,7 +168,13 @@ export interface DriveSessionLike {
   prompt(text: string): Promise<void>;
   abort(): Promise<void>;
   dispose(): void;
-  sessionManager: { getBranch(): unknown[] };
+  sessionManager: { getBranch(): unknown[]; getSessionFile?(): string | null };
+  /**
+   * Optional (presence-gated): when the session exposes its extension runner, `driveStage`
+   * preflights the stage's terminating perk tool post-bind and fails fast (zero-turn
+   * `no_extension_tools`) instead of burning the budget on a tool-less session.
+   */
+  extensionRunner?: { getAllRegisteredTools(): { definition: { name: string } }[] };
 }
 
 /** The runtime surface (structurally satisfied by pi's `AgentSessionRuntime`). */
@@ -314,6 +326,17 @@ export function evaluateTerminal(args: {
   };
 }
 
+/**
+ * The post-bind preflight rule (pure): the stage's terminating perk tool must be registered —
+ * `implement` → `submit`, `address` → `resolve_review_threads`. Returns the required tool name
+ * when absent, else `null`. Deliberately does NOT require the `subagent` tool for `address` — the
+ * subagent-under-worker live smoke stays the §8.11 carried risk.
+ */
+export function missingTerminatingTool(stage: DriveStage, toolNames: string[]): string | null {
+  const required = stage === "implement" ? "submit" : "resolve_review_threads";
+  return toolNames.includes(required) ? null : required;
+}
+
 /** Pull a `{ number, url }` PR from a captured `submit` details block; null when malformed. */
 function extractPr(
   details: Record<string, unknown> | null,
@@ -548,20 +571,24 @@ export function createBindManager(binding: unknown, listener: (event: DriveEvent
 /**
  * Build the asymmetric runtime: `cwd = worktree` (project tier — perk's `@mgiles/perk` extension via the
  * managed `.pi/settings.json`, the managed `AGENTS.md`/`APPEND_SYSTEM.md`) and `agentDir = throwaway`
- * (user-global tier OUT), compaction-off + retry-off settings, env-var/registry auth+model (Gap 5).
- * No `tools` allowlist — read-write defaults + extension tools. The `createAgentSessionServices`
- * factory builds the `DefaultResourceLoader` internally from `cwd`/`agentDir` (recipe correction #1).
+ * (user-global tier OUT — the throwaway dir has no `settings.json`, so the global tier is empty),
+ * env-var/registry auth+model (Gap 5). Settings are DISK-LAYERED (`SettingsManager.create` +
+ * `applyOverrides`, the SDK's sanctioned "with overrides" shape — docs/sdk.md "Settings
+ * Management"): the project tier resolves the managed `packages` list, while the compaction-off/
+ * retry-off determinism overrides ride the merged view only (package resolution reads the
+ * per-scope raws — overrides cannot leak into it). Missing `npm:` packages auto-install into
+ * `.pi/npm` during the loader's reload (skipped under `PI_OFFLINE`); an install failure throws →
+ * `driveStage`'s catch arm → a loud `failed`/`drive_error`. No `tools` allowlist — read-write
+ * defaults + extension tools. The `createAgentSessionServices` factory builds the
+ * `DefaultResourceLoader` internally from `cwd`/`agentDir` (recipe correction #1).
  */
 async function defaultCreateRuntime(
   opts: DriveStageOptions,
-  deps: DriveStageDeps,
-  resolved: { authStorage: AuthStorage; modelRegistry: ModelRegistry; model: Model<Api> },
+  resolved: ResolvedAuth,
 ): Promise<DriveRuntimeLike> {
   const agentDir = mkdtempSync(join(tmpdir(), "perk-worker-agent-"));
-  const settingsManager = SettingsManager.inMemory({
-    compaction: { enabled: false },
-    retry: { enabled: false },
-  });
+  const settingsManager = SettingsManager.create(opts.worktree, agentDir);
+  settingsManager.applyOverrides({ compaction: { enabled: false }, retry: { enabled: false } });
   const factory: CreateAgentSessionRuntimeFactory = async (factoryOpts) => {
     const services = await createAgentSessionServices({
       cwd: factoryOpts.cwd,
@@ -569,14 +596,29 @@ async function defaultCreateRuntime(
       authStorage: resolved.authStorage,
       settingsManager,
       modelRegistry: resolved.modelRegistry,
-      resourceLoaderOptions: deps.resourceLoaderOptions,
     });
     const result = await createAgentSessionFromServices({
       services,
       sessionManager: factoryOpts.sessionManager,
       sessionStartEvent: factoryOpts.sessionStartEvent,
+      // `undefined` ⇒ the SDK's initial-model resolution picks the model (see `resolveAuth`).
       model: resolved.model,
     });
+    // Name the model that will actually drive (the SDK may have picked it) — the remote step
+    // log is otherwise silent about it until a provider error.
+    const chosen = result.session.model;
+    console.error(
+      `perk worker: model ${chosen ? `${chosen.provider}/${chosen.id}` : "unresolved"}`,
+    );
+    // Loud construction diagnostics (the CAUSE behind a later `no_extension_tools` symptom):
+    // settings I/O errors and extension load errors are recorded, not raised, by the SDK —
+    // surfacing them is the app layer's job. Fail-soft reporting only; never throws.
+    for (const entry of result.extensionsResult.errors) {
+      console.error(`perk worker: extension load error — ${entry.path}: ${entry.error}`);
+    }
+    for (const entry of settingsManager.drainErrors()) {
+      console.error(`perk worker: settings error (${entry.scope}) — ${String(entry.error)}`);
+    }
     return { ...result, services, diagnostics: services.diagnostics };
   };
   const runtime = await createAgentSessionRuntime(factory, {
@@ -589,19 +631,25 @@ async function defaultCreateRuntime(
 
 // --- model/auth resolution (Gap 5) --------------------------------------------------------------
 
-interface ResolvedAuth {
+export interface ResolvedAuth {
   authStorage: AuthStorage;
   modelRegistry: ModelRegistry;
-  model: Model<Api>;
+  /** The EXPLICIT model only; `undefined` defers the pick to the SDK at session creation. */
+  model: Model<Api> | undefined;
 }
 
-/** Resolve auth + model; returns null (never throws) when no model is available. */
-function resolveAuth(opts: DriveStageOptions): ResolvedAuth | null {
+/**
+ * Resolve auth; returns null (never throws) when no model is available at all. The model is NOT
+ * pre-pinned from the registry: an `undefined` model lets `createAgentSession` run its own
+ * initial-model resolution (settings `defaultModel` → pi's curated per-provider defaults → first
+ * available), which picks a current-generation model instead of the registry's
+ * alphabetically-first (= oldest) entry.
+ */
+export function resolveAuth(opts: DriveStageOptions): ResolvedAuth | null {
   const authStorage = opts.authStorage ?? AuthStorage.create();
   const modelRegistry = opts.modelRegistry ?? ModelRegistry.create(authStorage);
-  const model = opts.model ?? modelRegistry.getAvailable()[0];
-  if (!model) return null;
-  return { authStorage, modelRegistry, model };
+  if (!opts.model && modelRegistry.getAvailable().length === 0) return null;
+  return { authStorage, modelRegistry, model: opts.model };
 }
 
 // --- the drive primitive ------------------------------------------------------------------------
@@ -677,12 +725,50 @@ export async function driveStage(
     runtime = deps.createRuntime
       ? await deps.createRuntime(opts)
       : // biome-ignore lint/style/noNonNullAssertion: resolved is non-null on the production path.
-        await defaultCreateRuntime(opts, deps, resolved!);
+        await defaultCreateRuntime(opts, resolved!);
 
     let boundSession = runtime.session;
     await bindManager.bind(boundSession);
     emitter.emit({ kind: "run_started", run_id: runId, stage: opts.stage });
 
+    // Terminating-tool preflight (presence-gated on `extensionRunner`): disk discovery has a
+    // silent-zero arm — a missing/unparseable `.pi/settings.json` or an unresolvable local-path
+    // package yields ZERO extension tools without throwing — so fail fast (zero turns) instead of
+    // burning the whole budget on a drive that can never call its terminating tool. Reuses the
+    // `model_error` terminal signal with a distinct `error.type` (the `no_model` precedent).
+    if (boundSession.extensionRunner) {
+      const toolNames = boundSession.extensionRunner
+        .getAllRegisteredTools()
+        .map((t) => t.definition.name);
+      const missing = missingTerminatingTool(opts.stage, toolNames);
+      if (missing !== null) {
+        return finish({
+          status: "failed",
+          terminal_signal: "model_error",
+          pr: null,
+          errorType: "no_extension_tools",
+          errorMessage:
+            `perk extension tools did not register — the ${opts.stage} stage's terminating ` +
+            `tool \`${missing}\` is missing. Check the worktree's .pi/settings.json packages ` +
+            "list (perk init converges it); construction diagnostics are on stderr.",
+        });
+      }
+    }
+
+    // Implementation/worker session pointer (contracts.md §8.35): the headless drive records the
+    // inner driven session's file under THIS run id into the shared main checkout (the worktree's
+    // `mainCheckoutRoot`), labelled `.worker` by capture site. The inner session's own
+    // `session_start` records the matching `.main`. Best-effort + non-fatal (carrier warns).
+    if (opts.stage === "implement") {
+      captureSessionPointer({
+        cwd: opts.worktree,
+        runId,
+        klass: "implementation",
+        site: "worker",
+        sessionFile: boundSession.sessionManager.getSessionFile?.() ?? null,
+      });
+    }
+
     // Budget/abort wiring (Gap 2): wall-clock timer + external signal both trip → session.abort().
     const timer = setTimeout(() => trip("budget"), opts.budget.wallClockMs);
     if (opts.signal) {

package/extension/workerMain.ts

@@ -11,7 +11,7 @@
 import { argv, env, exit, stderr, stdout } from "node:process";
 import type { Api, Model } from "@earendil-works/pi-ai";
 import { AuthStorage, ModelRegistry } from "@earendil-works/pi-coding-agent";
-import { runEventsPath } from "./substrate/cache.ts";
+import { runEventsPath, workflowDir } from "./substrate/cache.ts";
 import {
   type DriveBudget,
   type DriveStage,
@@ -90,12 +90,14 @@ async function main(): Promise<number> {
   const initialPrompt = initialPromptForWorktree(parsed.worktree, parsed.stage);
   if (initialPrompt === null) {
     stderr.write(
-      `perk worker: no plan-ref under ${parsed.worktree}/.pi/workflow — cannot seed the ${parsed.stage} prompt.\n`,
+      `perk worker: no plan-ref under ${workflowDir(parsed.worktree)} — cannot seed the ${parsed.stage} prompt.\n`,
     );
     return 2;
   }
 
-  // Headless auth/model (Gap 5): env-var key resolution; `--model provider/id` else first available.
+  // Headless auth/model (Gap 5): env-var key resolution; `--model provider/id` else the SDK's
+  // default resolution at session creation (settings default → pi's per-provider defaults →
+  // first available).
   const authStorage = AuthStorage.create();
   const modelRegistry = ModelRegistry.create(authStorage);
   let model: Model<Api> | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mgiles/perk",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "perk Pi extension (session interior) for the plan-oriented workflow.",
   "license": "MIT",
   "repository": {
@@ -34,9 +34,6 @@
     "lint": "biome check extension",
     "format": "biome format --write extension"
   },
-  "dependencies": {
-    "nunjucks": "3.2.4"
-  },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",
@@ -48,7 +45,6 @@
     "@earendil-works/pi-ai": "0.78.1",
     "@earendil-works/pi-coding-agent": "0.78.1",
     "@types/node": "22.19.19",
-    "@types/nunjucks": "3.2.6",
     "typescript": "6.0.3",
     "yaml": "2.9.0"
   }

package/prompts/README.md

@@ -1,6 +1,14 @@
-# prompts — canonical cross-plane prompt templates
+# prompts — perk's externalized prompt prose
 
-perk's prompt templates, authored once and **bundled into every build artifact**
+This directory is the canonical home for **all** of perk's externalized prompt prose. A
+template may be **cross-plane** (rendered in production by both planes) or **single-plane**
+(rendered by only one plane — e.g. a warm-door-only or cold-door-only seed/guidance prompt);
+either way it is authored within the frozen mini-jinja subset below and listed in
+`_fixtures/live.yaml`, where it is rendered on **both** engines and asserted byte-equal
+regardless of which plane consumes it in production (a free cross-engine portability guarantee,
+costing nothing since the subset is shared).
+
+The templates are authored once and **bundled into every build artifact**
 (the Python wheel as package data `perk/_prompts/`; the npm package under `prompts/`),
 exactly like `shared/`. Each plane locates this directory at runtime through its own
 resolver — `prompts_dir()` (`perk/_resources.py`) and `promptsDir()`
@@ -10,6 +18,49 @@ Templates are rendered by jinja2 (Python) and a vendored TS subset (the extensio
 are loaded by explicit name through the resolver — never by scanning the directory, so
 this README is a durable doc, not a template.
 
-The render seam, the frozen template-grammar spec, and the real prompt content land in
-later nodes; for now this file is the bundling/resolution probe that gives the directory
-tracked content.
+## Frozen template grammar
+
+The templates use a deliberately tiny, **frozen** subset of jinja syntax — the canonical
+"mini-jinja" surface. jinja2 is the reference engine; the extension renders the same subset. A
+**cross-plane conformance guard** (`tests/test_prompt_grammar.py` +
+`extension/substrate/promptGrammar.test.ts`) fails CI if any template uses a construct outside the
+subset.
+
+## Render parity — two decoupled tiers
+
+The two render seams (jinja2 on Python, the vendored mini-jinja on TS) are kept byte-identical by
+two tiers that separate the frozen render **contract** from real prompt **prose**:
+
+- **Tier A — contract snapshots.** `_fixtures/cases.yaml` lists purpose-built fixture templates
+  under `_fixtures/templates/` (one per render feature) with committed goldens under
+  `_fixtures/golden/` (jinja2's output). Both planes assert `render == golden`
+  (`tests/test_prompts.py` + `extension/substrate/prompts.test.ts`). These goldens change only when
+  the render contract changes — never when a real prompt's prose changes.
+- **Tier B — live cross-engine equality.** `_fixtures/live.yaml` lists every real template with
+  representative vars and **no** golden. `tests/test_prompt_parity.py` renders each real template
+  with jinja2, shells out once to `extension/testing/renderLive.ts` (mini-jinja), and asserts the
+  two outputs are byte-equal — so editing a real prompt's prose touches no fixture. A coverage
+  guard asserts every real template is listed in `live.yaml`.
+
+The subset is exactly four categories:
+
+1. **Variable substitution** — `{{ name }}`, where the contents are a single bare identifier
+   (`[A-Za-z_][A-Za-z0-9_]*`). Nothing else: no filters, no dotted access, no parentheses, no
+   literals, no operators.
+2. **Include** — `{% include "path/to/file.md" %}`, a double-quoted root-relative path only.
+3. **Conditionals** — `{% if cond %}` / `{% elif cond %}` / `{% else %}` / `{% endif %}`, where
+   `cond` uses only bare identifiers (truthiness), double-quoted string literals, `==`, and the
+   keywords `and` / `or` / `not`. For example: `{% if provider == "github" or provider == "linear" %}`,
+   `{% if not pr_id %}`.
+4. **Plain tags** — `{% %}` only. The whitespace-control markers `{%- … -%}` / `{{- … -}}` are
+   **not allowed**; tag-line stripping is handled by the render env's `trim_blocks` setting.
+
+**Not allowed** (the guard fails on these): `{% for x in y %}` / `{% endfor %}`, `{% set %}`,
+`{% macro %}` / `{% block %}` / `{% extends %}` / `{% raw %}`, `{# comments #}`, filters
+(`{{ x | upper }}`), attribute access (`{{ user.name }}`), `!=` / `<` / `>`, `in`, `is`,
+parentheses, and numeric literals.
+
+This README is **excluded** from the guard's scan — it is documentation, never rendered, and the
+out-of-subset examples above are shown deliberately as prose. The canonical spec lives in
+[`shared/contracts.md` §8.31](../shared/contracts.md). Widening the subset is a deliberate
+decision that amends §8.31 **and** both guards.