pi-harness-delegate 0.5.0 → 0.6.0

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);
 }
 
 /**

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.0",
   "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",