pi-harness-delegate 0.6.0 → 0.6.2

package/README.md

@@ -134,7 +134,7 @@ You are a senior engineer delegated by the pi coding agent.
 
 Custom templates are just files dropped in the above dirs — any registered name becomes a valid `mode`.
 
-**Project trust:** project-local templates (`.pi/delegate/templates/`) load only when pi itself considers the current project trusted (`ctx.isProjectTrusted()`, backed by pi's own trust store outside the project — the same trust that gates other project-scoped behavior). Trust it via pi's own trust prompt (shown the first time you open an untrusted directory) or your `defaultProjectTrust` setting; `/delegate status` reports whether the current project is trusted and, if not, that project-local templates are being skipped. There is **no way to grant trust from inside the project** — no `.pi/trusted` file, no environment variable. Earlier versions supported both (`.pi/trusted` containing `1`, or `PI_TRUSTED=1`/`PI_DELEGATE_TRUSTED=1` in the environment); both were removed as a security fix — a repo could commit `.pi/trusted` and declare itself trusted, letting a cloned hostile repo's templates silently override a builtin (e.g. widening `review` from `readonly` to `edit` and attaching a `verify:` command that runs host-side). If you relied on either, switch to pi's trust prompt or `defaultProjectTrust`.
+**Project trust:** project-local templates (`.pi/delegate/templates/`) load only when pi itself considers the current project trusted (`ctx.isProjectTrusted()`, backed by pi's own trust store outside the project — the same trust that gates other project-scoped behavior). Trust it via pi's own trust prompt (shown the first time you open an untrusted directory) or your `defaultProjectTrust` setting; `/delegate status` reports whether the current project is trusted and, if not, that project-local templates are being skipped. There is **no way to grant trust from inside the project** — no `.pi/trusted` file, no environment variable. Earlier versions supported both (`.pi/trusted` containing `1`, or `PI_TRUSTED=1`/`PI_DELEGATE_TRUSTED=1` in the environment); both were removed as a security fix — a repo could commit `.pi/trusted` and declare itself trusted, letting a cloned hostile repo's templates silently override a builtin (e.g. widening `review` from `readonly` to `edit` and attaching a `verify:` command that runs host-side). If you relied on either, switch to pi's trust prompt or `defaultProjectTrust`. **On upgrade this is otherwise silent** — a project override shares its name with the builtin it replaces, so the run just uses the builtin and looks fine — so a delegation in an untrusted project that actually has `.pi/delegate/templates/` now prints a one-time warning saying they were skipped, and points out a leftover `.pi/trusted` file if one is present (it no longer does anything and can be deleted).
 
 ## How the main session consumes the output
 
@@ -184,7 +184,7 @@ In `~/.pi/agent/settings.json`:
 
 Run `/delegate config` to see exactly what was read from `settings.json` (or why nothing was — no file, no `delegate` key, or a parse error), plus the effective config with defaults filled in, as a paste-ready JSON block for the `delegate` key. `/delegate status` shows the same provenance as one summary line.
 
-`/delegate config init` writes that effective config into `settings.json` under the `delegate` key — the only thing this extension ever writes there, and only on this explicit command. It reads the whole file, replaces only the `delegate` key, and preserves every other key (pi's `theme`/`defaultProvider`/`packages`/…, and a leftover `claudeDelegate`, verbatim). The write is atomic (temp file + rename in the same directory — no torn file if the process dies mid-write) and refuses outright if the existing file fails to parse, rather than clobbering whatever's actually in it; `/delegate config`'s paste-ready block is the fallback in that case.
+`/delegate config init` writes the parts of that effective config that differ from the built-in defaults into `settings.json` under the `delegate` key (an unmodified setup writes `{}`) — defaults are deliberately *not* written, because a value present in the file is treated as your choice and would stop later releases' default changes (e.g. `maxConcurrent` 1 → 4) from reaching you — the only thing this extension ever writes there, and only on this explicit command. It reads the whole file, replaces only the `delegate` key, and preserves every other key (pi's `theme`/`defaultProvider`/`packages`/…, and a leftover `claudeDelegate`, verbatim). The write is atomic (temp file + rename in the same directory — no torn file if the process dies mid-write) and refuses outright if the existing file fails to parse, rather than clobbering whatever's actually in it. It also keeps the file's mode, writes through a symlinked `settings.json` rather than replacing the link, matches the file's trailing-newline convention, and takes pi's own `settings.json.lock` — if another pi session holds it, the command refuses and you retry; `/delegate config`'s paste-ready block is the fallback in that case.
 
 Legacy `claudeDelegate` is auto-migrated into `delegate.harnesses.claude` (deprecated) — most fields migrate, including per-harness settings like `harnesses.<name>.transport`. Two things never migrate, though, and stay silently unreachable as long as `claudeDelegate` is your *only* key (no `delegate` key at all): `defaultHarness` (stays pinned to `claude`) and a top-level default `model` (only `claudeDelegate.model` → `harnesses.claude.model` migrates — there's no global fallback). Both `/delegate status` and `/delegate config` call this out when it's happening; fix it by renaming `claudeDelegate` to `delegate`, or by running `/delegate config init`, which writes an explicit `delegate` key (with the legacy values already correctly migrated) without touching `claudeDelegate` itself.
 

package/extensions/config.ts

@@ -1,4 +1,14 @@
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { DEFAULT_TIMEOUT_MS, type Harness, type Transport } from './harnesses/types.ts';
@@ -83,17 +93,9 @@ function sanitizeHarnessConfig(v: HarnessConfig): HarnessConfig {
   return out;
 }
 
-/**
- * Loads `delegate` config from `~/.pi/agent/settings.json` alongside `ConfigSource`, describing
- * how that happened (file present? which key won? did it fail to parse?) — see `ConfigSource`'s
- * doc comment. `loadConfig()` below is a thin wrapper for the existing call sites that only want
- * the resolved values; this is the one place that actually reads/parses the file, so a caller
- * needing both never pays for a second parse. Never throws — any failure (missing file, bad JSON,
- * a non-object root) is recorded on `source` and falls back to the same defaults `loadConfig()`
- * has always returned.
- */
-export function loadConfigWithSource(): ConfigLoadResult {
-  const cfg: DelegateConfig = {
+/** Built-in defaults — a fresh object each call, since callers mutate the result. */
+export function defaultDelegateConfig(): DelegateConfig {
+  return {
     timeoutMs: DEFAULT_TIMEOUT_MS,
     defaultMode: 'general',
     defaultHarness: 'claude',
@@ -105,6 +107,44 @@ export function loadConfigWithSource(): ConfigLoadResult {
     maxTranscripts: 100,
     harnesses: {},
   };
+}
+
+/**
+ * Only the top-level settings whose effective value differs from the built-in default.
+ *
+ * What `/delegate config init` writes. Writing the full effective config would pin every default
+ * into settings.json, and the loader treats a present value as user intent — so a later release
+ * that changes a default (maxConcurrent 1 -> 4 already did) would never reach that user.
+ */
+export function nonDefaultConfig(cfg: DelegateConfig): Partial<DelegateConfig> {
+  const defaults = defaultDelegateConfig() as unknown as Record<string, unknown>;
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(cfg as unknown as Record<string, unknown>)) {
+    if (v === undefined) continue;
+    if (k === 'modelAliases') {
+      // The loader merges aliases additively onto the defaults, so only the keys that differ need
+      // writing — whole-object diffing would pin the untouched default aliases next to a custom one.
+      const d = defaults.modelAliases as Record<string, string>;
+      const diff = Object.fromEntries(Object.entries(v as Record<string, string>).filter(([a, t]) => d[a] !== t));
+      if (Object.keys(diff).length > 0) out[k] = diff;
+      continue;
+    }
+    if (JSON.stringify(v) !== JSON.stringify(defaults[k])) out[k] = v;
+  }
+  return out as Partial<DelegateConfig>;
+}
+
+/**
+ * Loads `delegate` config from `~/.pi/agent/settings.json` alongside `ConfigSource`, describing
+ * how that happened (file present? which key won? did it fail to parse?) — see `ConfigSource`'s
+ * doc comment. `loadConfig()` below is a thin wrapper for the existing call sites that only want
+ * the resolved values; this is the one place that actually reads/parses the file, so a caller
+ * needing both never pays for a second parse. Never throws — any failure (missing file, bad JSON,
+ * a non-object root) is recorded on `source` and falls back to the same defaults `loadConfig()`
+ * has always returned.
+ */
+export function loadConfigWithSource(): ConfigLoadResult {
+  const cfg = defaultDelegateConfig();
   const file = join(agentDir(), 'settings.json');
   const source: ConfigSource = { file, fileExists: false, usedKey: 'none', legacyKeyPresent: false };
   try {
@@ -273,8 +313,8 @@ export function buildConfigReport(result: ConfigLoadResult): string[] {
   lines.push('from file (as written, before defaults are applied):');
   lines.push(JSON.stringify(result.source.raw ?? {}, null, 2));
   lines.push('');
-  lines.push('effective config (file merged with defaults) — paste under "delegate" in settings.json,');
-  lines.push('or run `/delegate config init` to write it there directly:');
+  lines.push('effective config (file merged with defaults) — for reference; you only need to put the values');
+  lines.push('you want to change under "delegate" (`/delegate config init` writes just those, not defaults):');
   lines.push(JSON.stringify({ delegate: result.config }, null, 2));
   return lines;
 }
@@ -298,13 +338,27 @@ export interface WriteConfigResult {
  * on the strength of a read like `loadConfig()`/`showStatus`.
  */
 export function writeDelegateConfig(delegateSubtree: unknown): WriteConfigResult {
-  const file = join(agentDir(), 'settings.json');
+  const configured = join(agentDir(), 'settings.json');
+  // Write through a symlink to its real target rather than replacing the link with a regular file.
+  let file = configured;
+  try {
+    file = realpathSync(configured);
+  } catch {
+    // absent — created below
+  }
+  // pi locks the path as configured (proper-lockfile realpath:false), not a symlink's target.
+  const lock = `${configured}.lock`;
+  const tmp = join(dirname(file), `settings.json.${process.pid}.tmp`);
+  let locked = false;
   try {
     let root: Record<string, unknown> = {};
+    let mode: number | undefined;
+    let trailingNewline = false;
     if (existsSync(file)) {
+      const raw = readFileSync(file, 'utf8');
       let parsed: unknown;
       try {
-        parsed = JSON.parse(readFileSync(file, 'utf8'));
+        parsed = JSON.parse(raw);
       } catch (err) {
         return {
           ok: false,
@@ -316,16 +370,56 @@ export function writeDelegateConfig(delegateSubtree: unknown): WriteConfigResult
         return { ok: false, file, message: `refusing to write: ${file} exists but its root isn't a JSON object` };
       }
       root = parsed as Record<string, unknown>;
+      mode = statSync(file).mode & 0o777;
+      trailingNewline = raw.endsWith('\n');
+    }
+    mkdirSync(dirname(file), { recursive: true });
+    // pi saves settings.json under proper-lockfile (`<file>.lock`, a directory taken with an atomic
+    // mkdir). Take the same lock, without waiting, so we neither lose a concurrent pi write nor have
+    // ours overwritten mid-read-modify-write. The read above is repeated under the lock.
+    try {
+      mkdirSync(lock);
+      locked = true;
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === 'EEXIST') {
+        return {
+          ok: false,
+          file,
+          message: `refusing to write: ${file} is locked (another pi session is saving settings, or a crashed one left a stale lock that pi clears after ~10s) — retry in a moment`,
+        };
+      }
+      throw err;
+    }
+    if (existsSync(file)) {
+      const again: unknown = JSON.parse(readFileSync(file, 'utf8'));
+      if (again === null || typeof again !== 'object' || Array.isArray(again)) {
+        return { ok: false, file, message: `refusing to write: ${file} changed and its root isn't a JSON object` };
+      }
+      root = again as Record<string, unknown>;
     }
     root.delegate = delegateSubtree;
-    const dir = dirname(file);
-    mkdirSync(dir, { recursive: true });
-    const tmp = join(dir, `settings.json.${process.pid}.tmp`);
-    writeFileSync(tmp, `${JSON.stringify(root, null, 2)}\n`, 'utf8');
+    // Match the file's own format: pi writes JSON.stringify(x, null, 2) with no trailing newline.
+    writeFileSync(tmp, `${JSON.stringify(root, null, 2)}${trailingNewline ? '\n' : ''}`, { encoding: 'utf8' });
+    if (mode !== undefined) chmodSync(tmp, mode);
     renameSync(tmp, file);
     return { ok: true, file, message: `wrote "delegate" key to ${file}` };
   } catch (err) {
     return { ok: false, file, message: `failed to write ${file}: ${err instanceof Error ? err.message : String(err)}` };
+  } finally {
+    // Cleanup is best-effort: this function must never throw.
+    try {
+      rmSync(tmp, { force: true });
+    } catch {
+      // nothing useful to do
+    }
+    // Separate from the tmp cleanup so a failure there can never leave pi's lock behind.
+    if (locked) {
+      try {
+        rmSync(lock, { recursive: true, force: true });
+      } catch {
+        // nothing useful to do
+      }
+    }
   }
 }
 

package/extensions/index.ts

@@ -67,6 +67,7 @@ import {
   legacyOutputsDir,
   loadConfig,
   loadConfigWithSource,
+  nonDefaultConfig,
   resolveModelForHarness,
   resolveTransport,
   writeDelegateConfig,
@@ -86,7 +87,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. */
@@ -188,6 +195,28 @@ function outputsDirFor(harness: string): string {
  * 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;
@@ -557,7 +586,8 @@ async function showConfig(ctx: ExtensionContext): Promise<void> {
 /**
  * `/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()`
+ * merged with whatever was already on disk, minus anything still at its default — pinning defaults would
+ * stop later releases' default changes reaching the user) 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
@@ -566,7 +596,7 @@ async function showConfig(ctx: ExtensionContext): Promise<void> {
  */
 async function initConfig(ctx: ExtensionContext): Promise<void> {
   const result = loadConfigWithSource();
-  const write = writeDelegateConfig(result.config);
+  const write = writeDelegateConfig(nonDefaultConfig(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');
@@ -611,7 +641,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, isProjectTrusted(ctx));
+  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)

package/extensions/templates.ts

@@ -201,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-harness-delegate",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "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",
@@ -65,7 +65,6 @@
   "pi": {
     "extensions": [
       "./extensions/index.ts"
-    ],
-    "image": "https://raw.githubusercontent.com/yorch/pi-harness-delegate/main/docs/assets/claude-delegate-preview.png"
+    ]
   }
 }