pi-harness-delegate 0.5.0 → 0.6.1

package/extensions/index.ts

@@ -29,7 +29,7 @@ import {
   truncateToWidth,
 } from '@earendil-works/pi-tui';
 import { Type } from 'typebox';
-import { runAcpHarness } from './acp-runner.ts';
+import { acpView, runAcpHarness } from './acp-runner.ts';
 import {
   aggregateSpend,
   buildFanoutReport,
@@ -50,14 +50,26 @@ import {
   ToolCallIndex,
   type VerifyResult,
 } from './activity.ts';
-import { isFanoutSpec, parseDelegateCommand, resolveDefaults, resolveHarnessList } from './command.ts';
+import {
+  isFanoutSpec,
+  parseDelegateCommand,
+  resolveDefaults,
+  resolveHarnessFilter,
+  resolveHarnessList,
+} from './command.ts';
 import { acquireSlot, activeCount } from './concurrency.ts';
 import {
+  buildConfigReport,
   type DelegateConfig,
+  describeConfigSource,
+  getMaxConcurrent,
   outputsDir as getOutputsDir,
   legacyOutputsDir,
   loadConfig,
+  loadConfigWithSource,
   resolveModelForHarness,
+  resolveTransport,
+  writeDelegateConfig,
 } from './config.ts';
 import {
   ALIASES,
@@ -74,7 +86,13 @@ import { NotifyBatcher } from './notify.ts';
 import { type FeedEntry, progressWindow } from './progress.ts';
 import { formatFanoutChip, multiProgressWindow, type RunRow } from './progress-multi.ts';
 import { runHarness } from './runner.ts';
-import { type DelegateTemplate, loadTemplates, resolveNativePermission } from './templates.ts';
+import {
+  type DelegateTemplate,
+  describeSkippedProjectTemplates,
+  loadTemplates,
+  projectTemplatePresence,
+  resolveNativePermission,
+} from './templates.ts';
 import { mapClaudeUsage } from './usage.ts';
 
 /** Render a possibly-unknown cost — `null` means the harness didn't report one, not a measured $0. */
@@ -120,8 +138,9 @@ const FANOUT_LINGER_MS = 3000;
  * callers must not let this flip a run's `isError`.
  *
  * Trust model: a verify command can only come from two places — on-disk template frontmatter
- * (project-local templates are already behind `isTrusted()`) or a human typing `/delegate
- * --verify=<cmd>` at the CLI. It is deliberately **not** a `delegate` tool parameter: a tool
+ * (project-local templates are already gated by `isProjectTrusted(ctx)` — pi's own trust store,
+ * never anything inside the project itself) or a human typing `/delegate --verify=<cmd>` at the
+ * CLI. It is deliberately **not** a `delegate` tool parameter: a tool
  * param is set by the model, whose context includes repo content and delegated-harness output —
  * both attacker-influenceable, so a model-settable `verify` would be a prompt-injection ->
  * arbitrary-host-command path (e.g. injected text in a reviewed file steering the parent agent
@@ -169,6 +188,42 @@ function outputsDirFor(harness: string): string {
   return getOutputsDir(harness);
 }
 
+/**
+ * Whether pi's own trust store (`ctx.isProjectTrusted()`, backed by `~/.pi/agent/trust.json`,
+ * outside any project) considers `ctx.cwd` trusted. This is the sole source of truth for whether
+ * project-local delegate templates load — see the trust-tier comment on `loadTemplates`. Fails
+ * closed (untrusted) if the host is old enough not to expose the method, or if it throws.
+ */
+/**
+ * Warn once per project when trusted-only content was silently skipped.
+ *
+ * Before 0.6.0 a committed `.pi/trusted` file (or `PI_TRUSTED=1`) granted trust; both were removed as
+ * a security fix. A user who relied on either loses their project-local templates on upgrade with no
+ * visible signal — an override shares its name with the builtin it replaces, so the run just uses the
+ * builtin and looks fine. `/delegate status` reports trust state, but nobody runs it unless something
+ * already looks wrong, so this fires on an actual delegation instead — and only when the project
+ * demonstrably has the content being skipped, so it never nags anyone unaffected.
+ */
+const warnedUntrustedProjects = new Set<string>();
+
+function warnIfProjectTemplatesSkipped(ctx: ExtensionContext, trusted: boolean): void {
+  if (trusted || warnedUntrustedProjects.has(ctx.cwd)) return;
+  const lines = describeSkippedProjectTemplates(projectTemplatePresence(ctx.cwd));
+  if (lines.length === 0) return;
+  warnedUntrustedProjects.add(ctx.cwd);
+  const msg = lines.join('\n');
+  if (ctx.hasUI) ctx.ui.notify?.(msg, 'warning');
+  else process.stderr.write(`${msg}\n`);
+}
+
+function isProjectTrusted(ctx: ExtensionContext): boolean {
+  try {
+    return typeof ctx.isProjectTrusted === 'function' && ctx.isProjectTrusted() === true;
+  } catch {
+    return false;
+  }
+}
+
 function formatTemplateRow(t: DelegateTemplate): string {
   const parts = [
     t.name,
@@ -182,15 +237,16 @@ function formatTemplateRow(t: DelegateTemplate): string {
 
 async function showModes(ctx: ExtensionContext, harnessFilter?: string): Promise<void> {
   const all = new Map<string, DelegateTemplate>();
+  const trusted = isProjectTrusted(ctx);
   // collect from all harnesses if no filter
   if (harnessFilter) {
-    for (const [k, v] of loadTemplates(ctx.cwd, harnessFilter)) all.set(k, v);
+    for (const [k, v] of loadTemplates(ctx.cwd, harnessFilter, trusted)) all.set(k, v);
   } else {
     for (const h of [...HARNESS_NAMES, 'shared']) {
-      for (const [k, v] of loadTemplates(ctx.cwd, h)) if (!all.has(k)) all.set(k, v);
+      for (const [k, v] of loadTemplates(ctx.cwd, h, trusted)) if (!all.has(k)) all.set(k, v);
     }
     // also load without harness param
-    for (const [k, v] of loadTemplates(ctx.cwd)) if (!all.has(k)) all.set(k, v);
+    for (const [k, v] of loadTemplates(ctx.cwd, undefined, trusted)) if (!all.has(k)) all.set(k, v);
   }
   const rows = [...all.values()].map(formatTemplateRow);
   if (!ctx.hasUI) {
@@ -357,6 +413,7 @@ async function showHistory(ctx: ExtensionContext, harnessFilter?: string): Promi
     return;
   }
   if (!ctx.hasUI) {
+    if (harnessFilter) process.stdout.write(`delegate — history (${harnessFilter})\n`);
     for (const e of entries)
       process.stdout.write(`${e.harness} ${e.mode} · ${formatCost(e.cost)} · ${e.sessionId ?? '-'}\n`);
     return;
@@ -377,7 +434,10 @@ async function showHistory(ctx: ExtensionContext, harnessFilter?: string): Promi
     list.onSelect = item => done(item.value);
     list.onCancel = () => done(undefined);
     return {
-      render: (w: number) => list.render(w),
+      render: (w: number) => {
+        const rows = list.render(w);
+        return harnessFilter ? [theme.fg('accent', `delegate — history (${harnessFilter})`), ...rows] : rows;
+      },
       invalidate: () => list.invalidate(),
       handleInput: (data: string) => {
         list.handleInput(data);
@@ -392,15 +452,22 @@ async function showHistory(ctx: ExtensionContext, harnessFilter?: string): Promi
 }
 
 async function showStatus(ctx: ExtensionContext, harnessFilter?: string): Promise<void> {
-  const cfg = loadConfig();
+  const { config: cfg, source } = loadConfigWithSource();
   const detection = await detectAll();
+  const trusted = isProjectTrusted(ctx);
   const allHarnesses = harnessFilter ? [harnessFilter].filter(h => isKnownHarness(h)) : HARNESS_NAMES;
   const lines: string[] = [];
   lines.push(`delegate — status${harnessFilter ? ` (${harnessFilter})` : ''}`);
+  lines.push(...describeConfigSource(source));
   lines.push(`defaultHarness: ${cfg.defaultHarness} · defaultMode: ${cfg.defaultMode} · model: ${cfg.model ?? '—'}`);
   lines.push(
     `maxConcurrent: ${typeof cfg.maxConcurrent === 'number' ? cfg.maxConcurrent : JSON.stringify(cfg.maxConcurrent)} · maxTranscripts: ${cfg.maxTranscripts}`,
   );
+  lines.push(
+    trusted
+      ? 'project trust: trusted — project-local templates (.pi/delegate/templates/) are loaded'
+      : "project trust: untrusted — project-local templates skipped (trust this project via pi's trust prompt, or set defaultProjectTrust, to load them)",
+  );
   lines.push('');
   lines.push('harness              binary   ok  version              outputs  templates  active');
   lines.push('─'.repeat(78));
@@ -416,13 +483,15 @@ async function showStatus(ctx: ExtensionContext, harnessFilter?: string): Promis
     } catch {}
     let templates = 0;
     try {
-      templates = loadTemplates(ctx.cwd, h).size;
+      templates = loadTemplates(ctx.cwd, h, trusted).size;
     } catch {}
     // cross-process count via the file registry, combined with the in-process counter as a fallback
     const active = activeCount(h);
+    const cap = getMaxConcurrent(cfg, h);
+    const activeCol = `${active}/${cap > 0 ? cap : '∞'}`;
     const hint = !det.ok && det.hint ? `  ← ${det.hint}` : '';
     lines.push(
-      `${h.padEnd(20)} ${bin.padEnd(8)} ${ok.padEnd(3)} ${ver.padEnd(20)} ${String(outputs).padEnd(8)} ${String(templates).padEnd(10)} ${active}${hint}`,
+      `${h.padEnd(20)} ${bin.padEnd(8)} ${ok.padEnd(3)} ${ver.padEnd(20)} ${String(outputs).padEnd(8)} ${String(templates).padEnd(10)} ${activeCol}${hint}`,
     );
   }
   const historyEntries = harnessFilter ? readAllHistory().filter(e => e.harness === harnessFilter) : readAllHistory();
@@ -435,9 +504,10 @@ async function showStatus(ctx: ExtensionContext, harnessFilter?: string): Promis
   }
   if (!harnessFilter) lines.push(`  total: ${formatSpend(spend.total)}`);
   if (!harnessFilter) {
+    const globalCap = getMaxConcurrent(cfg);
     lines.push('');
     lines.push(
-      `global active: ${activeCount()} · aliases: ${
+      `global active: ${activeCount()}/${globalCap > 0 ? globalCap : '∞'} · aliases: ${
         Object.entries(ALIASES)
           .map(([k, v]) => `${k}→${v}`)
           .join(', ') || '—'
@@ -475,6 +545,61 @@ async function showStatus(ctx: ExtensionContext, harnessFilter?: string): Promis
   });
 }
 
+/**
+ * `/delegate config` — the discoverability gap `/delegate status`'s provenance line only hints at:
+ * shows exactly what was read from `settings.json` (or why it wasn't) plus the effective config
+ * with defaults filled in, formatted as a paste-ready JSON block under the `delegate` key. Print-
+ * only — writing is a separate, explicit action (`/delegate config init`, below), never triggered
+ * from this default view.
+ */
+async function showConfig(ctx: ExtensionContext): Promise<void> {
+  const result = loadConfigWithSource();
+  const lines = ['delegate — config', '', ...buildConfigReport(result)];
+  if (!ctx.hasUI) {
+    process.stdout.write(`${lines.join('\n')}\n`);
+    return;
+  }
+  await ctx.ui.custom((tui, theme, _kb, done) => {
+    let offset = 0;
+    const height = 20;
+    return {
+      render(width: number): string[] {
+        const header = theme.fg('accent', `delegate config — ${result.source.file} (↑↓ scroll · any key to close)`);
+        const visible = lines.slice(offset, offset + height);
+        return [header, ...visible.map(l => theme.fg('muted', truncateToWidth(l, width)))];
+      },
+      handleInput(data: string): void {
+        if (matchesKey(data, Key.up) && offset > 0) {
+          offset--;
+          tui.requestRender();
+        } else if (matchesKey(data, Key.down) && offset < lines.length - 1) {
+          offset++;
+          tui.requestRender();
+        } else done(undefined);
+      },
+      invalidate() {},
+    };
+  });
+}
+
+/**
+ * `/delegate config init` — the one place this extension ever writes to `settings.json`, and only
+ * because a human explicitly typed this subcommand. Writes the current effective config (defaults
+ * merged with whatever was already on disk) into the `delegate` key via `writeDelegateConfig()`
+ * (read-modify-write, atomic, refuses on an unparseable file rather than clobbering it). This is
+ * also the practical fix for the legacy-`claudeDelegate`-only gap `describeConfigSource` warns
+ * about: writing an explicit `delegate` key (with the correctly-resolved values already folded
+ * in — the legacy migration already ran before this point) makes it win from then on, without
+ * this command ever touching or deleting the old `claudeDelegate` key itself.
+ */
+async function initConfig(ctx: ExtensionContext): Promise<void> {
+  const result = loadConfigWithSource();
+  const write = writeDelegateConfig(result.config);
+  const msg = write.ok ? `✓ ${write.message}` : `✗ ${write.message}`;
+  if (!ctx.hasUI) process.stdout.write(`${msg}\n`);
+  else ctx.ui.notify?.(msg, write.ok ? 'info' : 'warning');
+}
+
 function buildPrompt(
   template: DelegateTemplate,
   task: string,
@@ -514,7 +639,9 @@ async function delegate(
     throw new Error(
       `unknown harness "${harnessName}". Available: ${HARNESS_NAMES.join(', ')} (aliases: ${Object.keys(ALIASES).join(', ')})`,
     );
-  const templates = loadTemplates(ctx.cwd, harnessName);
+  const projectTrusted = isProjectTrusted(ctx);
+  warnIfProjectTemplatesSkipped(ctx, projectTrusted);
+  const templates = loadTemplates(ctx.cwd, harnessName, projectTrusted);
   const mode = opts.mode || config.defaultMode;
   const template = templates.get(mode);
   if (!template)
@@ -524,6 +651,11 @@ async function delegate(
   const task = opts.task || template.defaultTask;
   if (!task) throw new Error(`delegate mode "${mode}" requires a task`);
 
+  // Fail-fast, before acquireSlot()/spawn — configuring e.g. transport:'acp' for a harness with no
+  // ACP surface (or 'stdout' for an ACP-only one) should error immediately with a clear message,
+  // not spawn the process and surface a cryptic native failure. See config.ts's resolveTransport.
+  const transport = resolveTransport(config, harnessName, harness);
+
   // concurrency guard — see concurrency.ts. Single runs (waitForSlot unset) fail fast at capacity,
   // exactly as before; fan-out passes waitForSlot:true to queue instead.
   const release = await acquireSlot({
@@ -600,7 +732,10 @@ async function delegate(
       },
       nativePermission: nativePermissionForRun,
     };
-    result = harness.transport === 'acp' ? await runAcpHarness(baseRunOpts) : await runHarness(baseRunOpts);
+    result =
+      transport === 'acp'
+        ? await runAcpHarness({ ...baseRunOpts, harness: acpView(harness) })
+        : await runHarness(baseRunOpts);
   } catch (err) {
     release();
     if (streamedFull.length > 0) {
@@ -1518,8 +1653,9 @@ export default function (pi: ExtensionAPI) {
     // occupying a concurrency slot.
     const specs: FanoutSpec[] = [];
     const immediateFailures: FanoutRunSummary[] = [];
+    const trusted = isProjectTrusted(ctx);
     for (const h of resolved) {
-      const templates = loadTemplates(ctx.cwd, h);
+      const templates = loadTemplates(ctx.cwd, h, trusted);
       const resolvedTaskScope = resolveDefaults(parsed, templates);
       const template = parsed.mode ? templates.get(parsed.mode) : undefined;
       if (!resolvedTaskScope) {
@@ -1609,8 +1745,16 @@ export default function (pi: ExtensionAPI) {
       await showStatus(ctx, h);
       return;
     }
+    if (subLower === 'config init') {
+      await initConfig(ctx);
+      return;
+    }
+    if (subLower === 'config') {
+      await showConfig(ctx);
+      return;
+    }
     // extract --harness flag for list/history subcommands
-    const harnessFlag = sub.match(/--harness=([^\s]+)/)?.[1]?.toLowerCase();
+    const harnessFlag = sub.match(/--harness=([^\s]+)/)?.[1];
     if (sub === 'watch' || sub === 'show') {
       if (activeOverlay) {
         activeOverlay.show();
@@ -1620,44 +1764,45 @@ export default function (pi: ExtensionAPI) {
       }
       return;
     }
-    if (sub === 'list' || subLower.startsWith('list ')) {
-      const h =
-        forcedHarness ??
-        harnessFlag ??
-        (subLower.startsWith('list ') ? sub.slice(5).trim().split(/\s+/)[0]?.toLowerCase() : undefined);
-      if (h && isKnownHarness(h)) {
-        await showModes(ctx, h);
-        return;
-      }
-      if (sub === 'list' || subLower === `list --harness=${h}`) {
-        await showModes(ctx, forcedHarness ?? h);
-        return;
+    // Shared by list/history: resolve their (optional) harness filter to a canonical name via the
+    // same alias/case rules (`omp` -> `amp`, any case), and reject a word that matches nothing —
+    // rather than each falling back to silently showing an unfiltered or empty result.
+    const filterHarness = (bareWord: string | undefined): string | undefined | 'unknown' => {
+      if (forcedHarness) return forcedHarness;
+      const resolution = resolveHarnessFilter(harnessFlag ?? bareWord, {
+        isKnown: isKnownHarness,
+        aliasOf: resolveHarnessName,
+      });
+      if (resolution.kind === 'unknown') {
+        const msg = `unknown harness "${resolution.requested}". Available: ${HARNESS_NAMES.join(', ')} (aliases: ${Object.keys(ALIASES).join(', ')})`;
+        if (!ctx.hasUI) process.stdout.write(`${msg}\n`);
+        else ctx.ui.notify?.(msg, 'warning');
+        return 'unknown';
       }
-      // fallback: list without filter or with unknown word — show filtered if known, otherwise all
-      await showModes(ctx, forcedHarness);
+      return resolution.kind === 'known' ? resolution.harness : undefined;
+    };
+    if (sub === 'list' || subLower.startsWith('list ')) {
+      const h = filterHarness(subLower.startsWith('list ') ? sub.split(/\s+/)[1] : undefined);
+      if (h === 'unknown') return;
+      await showModes(ctx, h);
       return;
     }
     if (sub === 'history' || sub === 'logs' || subLower.startsWith('history ') || subLower.startsWith('logs ')) {
-      const h =
-        forcedHarness ??
-        harnessFlag ??
-        (subLower.startsWith('history ') || subLower.startsWith('logs ')
-          ? sub.split(/\s+/)[1]?.toLowerCase()
-          : undefined);
-      if (h && isKnownHarness(h)) {
-        await showHistory(ctx, h);
-        return;
-      }
-      await showHistory(ctx, forcedHarness);
+      const h = filterHarness(
+        subLower.startsWith('history ') || subLower.startsWith('logs ') ? sub.split(/\s+/)[1] : undefined,
+      );
+      if (h === 'unknown') return;
+      await showHistory(ctx, h);
       return;
     }
 
     // combine forced harness + args for parsing
     const rawForParse = forcedHarness ? `${forcedHarness} ${args}`.trim() : args;
     // gather known modes across all harnesses for parsing
+    const trusted = isProjectTrusted(ctx);
     const allModes = new Set<string>();
-    for (const h of HARNESS_NAMES) for (const k of loadTemplates(ctx.cwd, h).keys()) allModes.add(k);
-    for (const k of loadTemplates(ctx.cwd).keys()) allModes.add(k);
+    for (const h of HARNESS_NAMES) for (const k of loadTemplates(ctx.cwd, h, trusted).keys()) allModes.add(k);
+    for (const k of loadTemplates(ctx.cwd, undefined, trusted).keys()) allModes.add(k);
     const knownHarnessesSet = new Set([...HARNESS_NAMES, ...Object.keys(ALIASES)]);
     const parsed = parseDelegateCommand(rawForParse, allModes, knownHarnessesSet);
     // if forcedHarness provided, it wins
@@ -1671,7 +1816,7 @@ export default function (pi: ExtensionAPI) {
     }
 
     const harnessName = parsed.harness ?? loadConfig().defaultHarness ?? 'claude';
-    const templates = loadTemplates(ctx.cwd, harnessName);
+    const templates = loadTemplates(ctx.cwd, harnessName, trusted);
     const resolved = resolveDefaults(parsed, templates);
     const template = parsed.mode ? templates.get(parsed.mode) : undefined;
     const isDanger =

package/extensions/run-registry.ts

@@ -6,11 +6,15 @@
  * registry I/O failures never break a delegation — callers should combine this with their own
  * in-process counters as a fallback.
  *
- * Concurrency cap is best-effort, not a hard mutex: `countActiveRuns()` (read) and
- * `acquireRun()` (write) are two separate steps with no lock between them, so two pi
- * processes starting at the same instant can both observe a count under the limit and both
- * proceed — `maxConcurrent` can be exceeded by a small margin under a tight race. This is a
- * deliberate simplicity tradeoff (see AGENTS.md); do not rely on it for a hard cap.
+ * `acquireRun()` + `countActiveRuns()` alone are a plain check-then-act pair: read the count,
+ * decide, write — with no lock between the read and the write, so two pi processes starting at
+ * the same instant can both observe a count under the limit and both proceed, over-admitting for
+ * the full lifetime of both runs. `acquireRunWithinLimits()` below closes that specific window by
+ * re-verifying *after* writing: a write that turns out to push either count over its limit is
+ * undone immediately, so the cap can never be permanently exceeded — see its own doc comment for
+ * exactly what guarantee that is (and isn't). Callers that don't need the cap enforced — `/delegate
+ * status`'s display, or a caller happy with the plain best-effort behavior — can still use
+ * `acquireRun`/`countActiveRuns` directly.
  */
 
 import { mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
@@ -88,3 +92,44 @@ export function countActiveRuns(harness?: string): number {
   }
   return count;
 }
+
+export type AcquireWithinLimitsResult =
+  | { status: 'acquired'; handle: RunHandle }
+  /** Writing succeeded, but the run would push a limit over the top — undone, nothing held. */
+  | { status: 'full' }
+  /** Registry I/O failed — best-effort, same as `acquireRun` returning null: caller should fall
+   *  back to in-process-only accounting and proceed rather than block the run. */
+  | { status: 'unavailable' };
+
+/**
+ * Register an active run, then atomically-in-effect verify it's still within `maxGlobal` and
+ * `maxPerHarness` (either `<= 0` means "no limit" for that dimension) — undoing the registration
+ * if not. This turns the classic count-then-act race into a write-then-recheck one: because the
+ * recheck happens strictly *after* the write is committed to disk, whichever of two racing
+ * processes writes last is guaranteed to see both entries and correctly back off — over-admission
+ * (more than the limit standing at once) is impossible by construction, unlike plain
+ * `countActiveRuns()` + `acquireRun()`.
+ *
+ * This is not a perfect mutex, and doesn't try to be: in a tight enough multi-way race, more than
+ * one contender can each write, then each see the other's (or others') entry when it rechecks, and
+ * each concludes it's over the limit and backs off — even though exactly one of them could have
+ * fit. That's a transient *under*-admission (self-heals on the caller's next attempt, e.g. via
+ * `acquireSlot({wait: true})`'s poll loop) — the property this function actually guarantees is
+ * that the limit is never exceeded, not that it's always saturated.
+ */
+export function acquireRunWithinLimits(
+  harness: string,
+  mode: string,
+  maxGlobal: number,
+  maxPerHarness: number,
+): AcquireWithinLimitsResult {
+  const handle = acquireRun(harness, mode);
+  if (!handle) return { status: 'unavailable' };
+  const overGlobal = maxGlobal > 0 && countActiveRuns() > maxGlobal;
+  const overHarness = maxPerHarness > 0 && countActiveRuns(harness) > maxPerHarness;
+  if (overGlobal || overHarness) {
+    releaseRun(handle);
+    return { status: 'full' };
+  }
+  return { status: 'acquired', handle };
+}

package/extensions/templates.ts

@@ -139,16 +139,6 @@ export function projectTemplatesDir(cwd: string, harness?: string): string {
   return join(cwd, '.pi', 'delegate', 'templates');
 }
 
-/** Minimal trust gate for project-local templates — untrusted clones must not override builtins. */
-function isTrusted(cwd: string): boolean {
-  if (process.env.PI_TRUSTED === '1' || process.env.PI_DELEGATE_TRUSTED === '1') return true;
-  try {
-    return readFileSync(join(cwd, '.pi', 'trusted'), 'utf8').trim() === '1';
-  } catch {
-    return false;
-  }
-}
-
 /** Legacy dirs for compat */
 function legacyUserTemplatesDir(): string {
   const dir = process.env.PI_CODING_AGENT_DIR ?? join(homedir(), '.pi', 'agent');
@@ -158,8 +148,17 @@ function legacyProjectTemplatesDir(cwd: string): string {
   return join(cwd, '.pi', 'claude-delegate', 'templates');
 }
 
-/** Legacy root < shared < harness builtins < legacyUser < user < user/harness < legacyProject < project < project/harness (later wins). */
-export function loadTemplates(cwd: string, harnessName?: string): Map<string, DelegateTemplate> {
+/**
+ * Legacy root < shared < harness builtins < legacyUser < user < user/harness < legacyProject <
+ * project < project/harness (later wins).
+ *
+ * `trusted` gates the project-local tiers only (global/user tiers always load — they're the
+ * operator's own files, not the project's). It must come from pi's own trust store
+ * (`ctx.isProjectTrusted()`), never from anything inside `cwd` itself: a trust anchor that lives
+ * in the content it's supposed to gate can simply declare itself trusted. Callers that fail to
+ * resolve trust should pass `false` — untrusted is the safe default.
+ */
+export function loadTemplates(cwd: string, harnessName?: string, trusted = false): Map<string, DelegateTemplate> {
   const out = new Map<string, DelegateTemplate>();
   const harness = harnessName ?? 'claude';
   // legacy root builtins (templates/*.md) lowest — for migration from pi-claude-delegate
@@ -173,7 +172,7 @@ export function loadTemplates(cwd: string, harnessName?: string): Map<string, De
   loadDir(userTemplatesDir(), out);
   loadDir(userTemplatesDir(harness), out);
   // project locals: legacy before new so new wins — only if trusted
-  if (isTrusted(cwd)) {
+  if (trusted) {
     loadDir(legacyProjectTemplatesDir(cwd), out);
     loadDir(projectTemplatesDir(cwd), out);
     loadDir(projectTemplatesDir(cwd, harness), out);
@@ -181,8 +180,8 @@ export function loadTemplates(cwd: string, harnessName?: string): Map<string, De
   return out;
 }
 
-export function loadAllTemplates(cwd: string): Map<string, DelegateTemplate> {
-  return loadTemplates(cwd);
+export function loadAllTemplates(cwd: string, trusted = false): Map<string, DelegateTemplate> {
+  return loadTemplates(cwd, undefined, trusted);
 }
 
 /**
@@ -202,3 +201,56 @@ export function resolveNativePermission(
   if (!nativePermission) return undefined;
   return effectivePermission === templatePermission ? nativePermission : undefined;
 }
+
+/**
+ * What a project has on disk that only loads when the project is trusted.
+ *
+ * Used to warn a user whose project-local templates stopped loading after the 0.6.0 security fix
+ * (§19 of ROADMAP) — before it, a committed `.pi/trusted` file or `PI_TRUSTED=1` granted trust, and
+ * both were removed. The failure is otherwise invisible: an override shares its name with the
+ * builtin it replaces, so the run silently uses the builtin and produces plausible output.
+ *
+ * Pure filesystem inspection — no trust logic. The caller supplies the trust decision.
+ */
+export function projectTemplatePresence(cwd: string): {
+  /** Template dirs that exist and would load if the project were trusted. */
+  dirs: string[];
+  /** A leftover `.pi/trusted` file — strong evidence the user relied on the removed mechanism. */
+  staleTrustFile: boolean;
+} {
+  const candidates = [projectTemplatesDir(cwd), legacyProjectTemplatesDir(cwd)];
+  const dirs: string[] = [];
+  for (const dir of candidates) {
+    try {
+      if (readdirSync(dir).some(f => f.endsWith('.md'))) dirs.push(dir);
+    } catch {
+      // absent or unreadable — nothing to warn about
+    }
+  }
+  let staleTrustFile = false;
+  try {
+    staleTrustFile = existsSync(join(cwd, '.pi', 'trusted'));
+  } catch {
+    staleTrustFile = false;
+  }
+  return { dirs, staleTrustFile };
+}
+
+/** One-line notices for a project whose trusted-only content was skipped. Empty when nothing applies. */
+export function describeSkippedProjectTemplates(presence: { dirs: string[]; staleTrustFile: boolean }): string[] {
+  if (presence.dirs.length === 0 && !presence.staleTrustFile) return [];
+  const out: string[] = [];
+  if (presence.dirs.length > 0) {
+    out.push(
+      `⚠ project-local templates were NOT loaded — this project is untrusted (${presence.dirs.join(', ')})`,
+      "  trust it via pi's trust prompt or defaultProjectTrust; /delegate status shows trust state",
+    );
+  }
+  if (presence.staleTrustFile) {
+    out.push(
+      '  a leftover .pi/trusted file was found — it no longer grants trust (removed in 0.6.0 as a',
+      '  security fix, since a repo could use it to trust itself) and can be deleted',
+    );
+  }
+  return out;
+}

package/extensions/usage.ts

@@ -12,13 +12,21 @@ export interface HarnessUsage {
 export type ClaudeUsage = HarnessUsage;
 
 /**
- * Map harness usage/cost into pi's `Usage` shape so delegated runs appear
- * in the pi footer token/cost stats and /session totals. Returns undefined when cost
- * is unknown — `Usage.cost.total` is mandatory, so there's no honest number to put there,
- * and reporting a fake $0 would silently under-report spend in pi's session totals.
+ * Map harness usage/cost into pi's `Usage` shape so delegated runs appear in the pi footer
+ * token/cost stats and /session totals.
+ *
+ * Deliberate, bounded exception to the "never fake a number" rule: `Usage.cost.total` is
+ * mandatory (unlike `StreamedResult.totalCostUsd`, which stays `number | null` everywhere else
+ * in this codebase — the transcript still renders `cost: —` and `/delegate status`'s
+ * `aggregateSpend` still tracks unknown-cost runs separately). Codex and Devin genuinely report
+ * no dollar cost, so treating "cost unknown" as "usage unknown" here would drop 2 of 5 harnesses'
+ * tokens out of pi's session totals entirely. Reporting `$0` under-reports spend by a knowable
+ * amount (bounded: it's exactly the missing harnesses' true cost, never a guess); reporting no
+ * usage at all loses real token counts outright. Between those two errors, under-reporting spend
+ * is the lesser one — but this exception applies ONLY to this pi-`Usage` mapping. Do not
+ * generalize a `null -> 0` fallback to any other cost/spend path in the codebase.
  */
-export function mapHarnessUsage(u: HarnessUsage): Usage | undefined {
-  if (u.totalCostUsd === null) return undefined;
+export function mapHarnessUsage(u: HarnessUsage): Usage {
   const input = u.inputTokens + u.cacheCreationInputTokens;
   const cacheRead = u.cacheReadInputTokens;
   const output = u.outputTokens;
@@ -34,11 +42,11 @@ export function mapHarnessUsage(u: HarnessUsage): Usage | undefined {
       output: 0,
       cacheRead: 0,
       cacheWrite: 0,
-      total: u.totalCostUsd,
+      total: u.totalCostUsd ?? 0,
     },
   };
 }
 
-export function mapClaudeUsage(u: ClaudeUsage): Usage | undefined {
+export function mapClaudeUsage(u: ClaudeUsage): Usage {
   return mapHarnessUsage(u);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-harness-delegate",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Delegate work to any harness (Claude Code, Muse, OpenCode, Amp) from the pi coding agent \u2014 code reviews, plans, implementation, security audits, docs, or your own custom templates.",
   "type": "module",
   "packageManager": "bun@1.3.14",