@llblab/pi-telegram 0.24.2 → 0.24.3

package/AGENTS.md

@@ -120,7 +120,7 @@ The core product loop is mobile continuation: start or supervise work in the ter
 - `telegram_voice` and `telegram_button` are not Pi tools; keep prompts/docs explicit that agents should author markup while voice synthesis provider extensions own TTS/OGG conversion, and pi-telegram owns button routing plus Telegram delivery
 - Voice reply policy and prompt context are owned by pi-telegram's `telegram.json` `voice.replyMode`: missing, invalid, `hidden`, and legacy `manual` config resolve to `hidden` and add no `[voice]` context; `mirror` adds `[voice] delivery: automatic voice` only for voice/audio input, while `always` adds that same single factual line to every Telegram turn. Place voice context after `[outputs]` when handler output exists, otherwise after `[attachments]`; provider prompt contributions are optional provider-specific additions, not the default policy or delivery-composition channel.
 - Optional `telegram.json` `time` may add `[time] YYYY-MM-DD HH:mm:ss <timezone>` to Telegram-originated prompts for wall-clock context. It is hidden by default, uses `time.injectionMode` values `hidden|always|interval`, stores `time.interval` in milliseconds, uses the system timezone, and should render last after `[attachments]`, `[outputs]`, and `[voice]` sections. The Settings row `🕒 Time injection: hidden|always|interval` controls `time.injectionMode` only.
-- Agent activity status is native-only for the release path: Telegram uses `sendChatAction(typing)` and renders its native `…typing` indicator as the automatic work signal. When a connected instance starts any real agent run, send that indicator to the instance's own thread (and aggregate `All` surface), including Telegram turns, local/TUI prompts, and autonomous continuations such as Grow Loop; stop it at agent/session completion. This signal is independent from terminal `Active`, which remains scoped to Telegram-owned turns. Confirmed manual `/compact` and automatic compaction tied to an active Telegram turn also use native activity. Do not send activity merely for startup/connect/reload/recovery or add extra in-chat work surfaces without a new explicit design decision.
+- Agent activity status is native-only for the release path: Telegram uses `sendChatAction(typing)` and renders its native `…typing` indicator as the automatic work signal. When a connected instance starts any real agent run, send that indicator to the instance's own thread (and aggregate `All` surface), including Telegram turns, local/TUI prompts, and autonomous continuations such as Grow Loop; stop it at agent/session completion. Keep at most one chat action in flight per loop, coalesce identical leader-side actions across follower traffic, and treat Telegram 429 `retry_after` as a shared suppression window rather than a delayed retry or persistent terminal error. This signal is independent from terminal `Active`, which remains scoped to Telegram-owned turns. Confirmed manual `/compact` and automatic compaction tied to an active Telegram turn also use native activity. Do not send activity merely for startup/connect/reload/recovery or add extra in-chat work surfaces without a new explicit design decision.
 - Voice reply mode Settings UI standard: the top-level Settings row is `👄 Voice reply: hidden|mirror|always`; `hidden` is the true default, persists no `voice.replyMode`, adds no voice context, and still allows explicit agent-authored `telegram_voice`; `mirror` activates automatic voice context only for voice/audio input, and `always` activates it for every Telegram turn. The submenu title is `👄 Voice reply mode:`; choice buttons use lowercase labels with a model-style active dot (`🟢 hidden`, `🟢 mirror`) rather than per-mode emoji; the explanatory submenu body uses compact HTML-code bullets such as `<code>-</code> <code>hidden</code> (default): ...`. Preserve this wording/icons unless the operator explicitly asks to redesign it
 - Outbound voice delivery is one fallback pipeline: configured `outboundHandlers` with `type: "voice"` run first in `telegram.json` order, then programmatic voice handlers, then registered voice synthesis providers as zero-config progressive fallbacks; provider extensions must not override operator-configured handlers
 - `telegram_voice` text is arbitrary TTS-target text and the prompt should show only forms that include text to speak: `<!-- telegram_voice text="Short summary" -->` or `<!-- telegram_voice: Short summary -->`. Avoid raw Markdown/code/tables in voice text.
@@ -149,7 +149,7 @@ The core product loop is mobile continuation: start or supervise work in the ter
 
 - Treat queue handling, compaction interaction, and lifecycle-hook state transitions as regression-prone areas; validate them after changing dispatch logic
 - Keep the standard `npm run typecheck` gate strict about unused locals and parameters so stale imports and abandoned adapters fail validation instead of accumulating silently
-- Keep push/PR CI on minimum Node `22.19.0` across Ubuntu, macOS, and Windows with typecheck, tests, and package dry-run on every OS; run audit once on Ubuntu, require the native Windows named-pipe roundtrip to execute, and keep Unix-only skips explicit by protected boundary.
+- Keep push/PR CI on minimum Node `22.19.0` across Ubuntu, macOS, and Windows with typecheck, tests, and package dry-run on every OS; run audit once on Ubuntu, require the native Windows named-pipe roundtrip to execute, and keep Unix-only skips explicit by protected boundary. Through 2026-08-21 UTC only, the audit gate may accept the exact two Pi-shrinkwrap advisories documented in `BACKLOG.md`; it must verify source/GHSA/package/version/path/parent graph, fail every unknown finding, and fail closed at expiry.
 - Route important runtime failures through the recent runtime event recorder so `/telegram-status` remains useful for post-mortem debugging. Keep the compact TUI status bar bounded to the generic `error` state; detailed error messages belong only in diagnostics/logs, never inline beside the status label.
 - Treat remaining Markdown-to-HTML rendering as Telegram UI/compat output work, not generic Markdown rendering or assistant reply delivery
 - Preserve literal code content in Telegram rendering

package/BACKLOG.md

@@ -2,6 +2,18 @@
 
 _This backlog tracks only open release-relevant work: hotfixes, bounded maintenance, live runtime verification, evidence-gated Telegram client follow-ups, and upstream Pi API blockers. Completed outcomes and validation evidence belong in `CHANGELOG.md`, not in this queue._
 
+## P0 — Expiring Pi Shrinkwrap Audit Exception
+
+Deadline: 2026-08-21 UTC. The validation gate intentionally fails at `2026-08-22T00:00:00Z` if either exception remains.
+
+Context: `@earendil-works/pi-coding-agent@0.80.6` publishes its own `npm-shrinkwrap.json`, which prevents this consumer package from replacing two installed vulnerable copies. The repository temporarily permits only `brace-expansion@5.0.6` / source `1123898` / `GHSA-3jxr-9vmj-r5cp` and `protobufjs@7.6.4` / source `1123964` / `GHSA-j3f2-48v5-ccww`, plus parent findings whose complete audit graph resolves exclusively to those sources. `npm run audit` verifies the exact graph, installed paths and versions, and expiry; every unknown or changed finding fails closed.
+
+Open work:
+
+- [ ] Upgrade to a Pi release whose published shrinkwrap installs `brace-expansion>=5.0.7` and `protobufjs>=7.6.5`, remove the exception policy, and restore a zero-finding raw `npm audit` before the deadline.
+
+Done when: a clean `npm ci` followed by raw `npm audit` reports zero vulnerabilities and the expiring policy/overrides are removed.
+
 ## P1 — Native Windows Runtime Smoke
 
 Context: Deterministic ownership, persistence, recovery, process, and named-pipe coverage passes on native hosted Windows. A live Telegram client remains the only unverified platform boundary and may be exercised in a later release cycle rather than tied to a specific version.

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+## 0.24.3: Queue And Typing Reliability Hotfix
+
+- `Typing Backpressure`: Serialized each native activity loop to one in-flight action and coalesced identical leader-side chat actions across direct and follower traffic. Telegram 429 `retry_after` now opens a shared suppression window without delayed retry fan-out or terminal-status projection, while non-rate-limit retries and diagnostics remain intact. Impact: concurrent Threaded Mode activity no longer amplifies `sendChatAction` throttling into repeated `Telegram Error` states.
+- `Queue Lifecycle`: Agent-end cleanup ignores only stale-context status failures after typing teardown, and control settlement is fenced to its originating deferred-dispatch generation. Impact: real status failures still reject, while callbacks from a replaced session cannot update status or dispatch queued work through an old context.
+- `Dependency Audit`: Added a fail-closed exception through 2026-08-21 UTC for only `brace-expansion@5.0.6` (`GHSA-3jxr-9vmj-r5cp`) and `protobufjs@7.6.4` (`GHSA-j3f2-48v5-ccww`) copies pinned inside Pi's published shrinkwrap. Impact: all unknown findings, graph/path/version drift, and any still-present exception at the deadline fail validation while an upstream Pi release is pending.
+
 ## 0.24.2: Context Compression Hotfix
 
 - `Project Context`: Consolidated the `0.24.1` release narrative into final domain outcomes, reduced the backlog to concrete open work, and made minimum-Node Ubuntu/macOS/Windows CI a durable engineering contract. Impact: future agents receive a smaller, current project model without losing release behavior or platform-validation requirements.

package/README.md

@@ -278,6 +278,8 @@ Full validation:
 npm run validate
 ```
 
+`npm run audit` executes raw npm audit and then applies a fail-closed temporary policy for two findings pinned inside Pi's published shrinkwrap: `brace-expansion@5.0.6` (`GHSA-3jxr-9vmj-r5cp`) and `protobufjs@7.6.4` (`GHSA-j3f2-48v5-ccww`). It verifies exact advisory sources, graph, installed paths/versions, and rejects every other finding. The exception expires after 2026-08-21 UTC; see [BACKLOG.md](./BACKLOG.md).
+
 Project context:
 
 - [AGENTS.md](./AGENTS.md) — engineering and runtime conventions.

package/docs/architecture.md

@@ -251,7 +251,7 @@ Native typing during compaction follows connected-instance activity rather than
 - Automatic/session compaction without an active Telegram turn uses the connected instance's assigned target; an unconnected instance sends nothing.
 - Thread-targeted typing is sent to the concrete thread and mirrored to `All` as the aggregate activity surface; completion, timeout, and shutdown stop the keyed loop.
 
-At every connected instance `agent_start`, the lifecycle binding starts Telegram's native `…typing` indicator in that instance's assigned target, whether the run came from Telegram, the local TUI, or an autonomous continuation such as Grow Loop. Terminal `Active` remains Telegram-turn-specific; the native indicator answers the separate question of whether the instance is doing agent work. Assistant message start/update hooks still re-arm it during Telegram-owned turns so transient provider/model errors do not leave a continuing run without activity feedback, and agent/session completion stops it.
+At every connected instance `agent_start`, the lifecycle binding starts Telegram's native `…typing` indicator in that instance's assigned target, whether the run came from Telegram, the local TUI, or an autonomous continuation such as Grow Loop. Terminal `Active` remains Telegram-turn-specific; the native indicator answers the separate question of whether the instance is doing agent work. Each loop keeps one action in flight, while the leader API runtime coalesces identical chat/thread/action calls across local and follower traffic for two seconds; expired gates prune opportunistically and at most 256 currently active keys are retained. A Telegram 429 response opens the exact action's shared `retry_after` suppression window without scheduling delayed retries or projecting expected activity throttling as a terminal status error. Assistant message start/update hooks still re-arm it during Telegram-owned turns so transient provider/model errors do not leave a continuing run without activity feedback, and agent/session completion stops it.
 
 ### Rendering And Delivery
 

package/index.ts

@@ -502,6 +502,9 @@ export default function (pi: Pi.ExtensionAPI) {
       isIdle,
       hasPendingMessages,
       hasDispatchContext: deferredQueueDispatchRuntime.isBound,
+      getDispatchGeneration: deferredQueueDispatchRuntime.getGeneration,
+      isDispatchGenerationActive:
+        deferredQueueDispatchRuntime.isGenerationActive,
       isQueueItemTransportActive(item) {
         return telegramTransportStampRuntime.isActive(item.transportStamp);
       },

package/lib/queue.ts

@@ -1258,20 +1258,27 @@ export async function handleTelegramAgentEndRuntime<
   const isDeliveryActive = (): boolean =>
     deps.isSessionActive?.() !== false &&
     (!turn || deps.isTurnTransportActive?.(turn) !== false);
+  const updateStatusIgnoringStaleContext = (): void => {
+    try {
+      deps.updateStatus();
+    } catch (error) {
+      if (!isTelegramStaleContextError(error)) throw error;
+    }
+  };
   if (!isDeliveryActive()) {
     deps.resetRuntimeState();
-    deps.updateStatus();
+    updateStatusIgnoringStaleContext();
     deps.dispatchNextQueuedTelegramTurn();
     return;
   }
   deps.resetRuntimeState();
   await deps.waitForTypingIdle?.();
   if (!isDeliveryActive()) {
-    deps.updateStatus();
+    updateStatusIgnoringStaleContext();
     deps.dispatchNextQueuedTelegramTurn();
     return;
   }
-  deps.updateStatus();
+  updateStatusIgnoringStaleContext();
   const endPlan = buildTelegramAgentEndPlan({
     hasTurn: !!turn,
     stopReason: assistant.stopReason,
@@ -2117,6 +2124,8 @@ export interface TelegramDeferredQueueDispatchRuntime<TContext = unknown> {
   bind: (ctx: TContext) => void;
   unbind: () => void;
   isBound: () => boolean;
+  getGeneration: () => number;
+  isGenerationActive: (generation: number) => boolean;
   request: (dispatchNextQueuedTelegramTurn: (ctx: TContext) => void) => void;
 }
 
@@ -2149,6 +2158,9 @@ export function createTelegramDeferredQueueDispatchRuntime<TContext = unknown>(
       clearTimers();
     },
     isBound: () => boundContext !== undefined,
+    getGeneration: () => generation,
+    isGenerationActive: (expectedGeneration) =>
+      boundContext !== undefined && generation === expectedGeneration,
     request: (dispatchNextQueuedTelegramTurn) => {
       if (boundContext === undefined) return;
       const scheduledGeneration = generation;
@@ -2265,6 +2277,8 @@ export interface TelegramQueueDispatchControllerDeps<
   setQueuedItems: (items: TelegramQueueItem<TContext>[]) => void;
   canDispatch: (ctx: TContext) => boolean;
   hasDispatchContext?: () => boolean;
+  getDispatchGeneration?: () => number;
+  isDispatchGenerationActive?: (generation: number) => boolean;
   updateStatus: (ctx: TContext, error?: string) => void;
   sendTextReply: TelegramControlRuntimeDeps<TContext>["sendTextReply"];
   onPromptDispatchStart: (ctx: TContext, chatId: number) => void;
@@ -2318,6 +2332,8 @@ export function createTelegramQueueDispatchRuntime<TContext = unknown>(
       hasPendingMessages: deps.hasPendingMessages,
     }),
     hasDispatchContext: deps.hasDispatchContext,
+    getDispatchGeneration: deps.getDispatchGeneration,
+    isDispatchGenerationActive: deps.isDispatchGenerationActive,
     updateStatus: deps.updateStatus,
     sendTextReply: deps.sendTextReply,
     onPromptDispatchStart: deps.onPromptDispatchStart,
@@ -2363,6 +2379,7 @@ export function createTelegramQueueDispatchController<TContext = unknown>(
       executeTelegramQueueDispatchPlan(dispatchPlan, {
         executeControlItem: (item) => {
           controlDispatchPending = true;
+          const dispatchGeneration = deps.getDispatchGeneration?.();
           deps.updateStatus(ctx);
           void executeTelegramControlItemRuntime(item, {
             ctx,
@@ -2371,6 +2388,13 @@ export function createTelegramQueueDispatchController<TContext = unknown>(
             onSettled: () => {
               controlDispatchPending = false;
               if (deps.hasDispatchContext && !deps.hasDispatchContext()) return;
+              if (
+                dispatchGeneration !== undefined &&
+                deps.isDispatchGenerationActive &&
+                !deps.isDispatchGenerationActive(dispatchGeneration)
+              ) {
+                return;
+              }
               deps.updateStatus(ctx);
               controller.dispatchNext(ctx);
             },

package/lib/runtime.ts

@@ -455,7 +455,12 @@ export function startTelegramTypingLoop(
   state.typingLoopKey = nextKey;
   const sendTyping = (): void => {
     const activeDeps = state.typingLoopDeps;
-    if (!activeDeps || activeDeps.chatId === undefined || activeDeps.chatId === 0)
+    if (
+      !activeDeps ||
+      activeDeps.chatId === undefined ||
+      activeDeps.chatId === 0 ||
+      state.typingInFlight
+    )
       return;
     const targetChatId = activeDeps.chatId;
     const threadParams = getTelegramTypingLoopThreadParams(activeDeps.target);

package/lib/telegram-api.ts

@@ -333,6 +333,7 @@ interface TelegramApiResponse<T> {
 export interface TelegramApiCallOptions {
   signal?: AbortSignal;
   maxAttempts?: number;
+  retryRateLimit?: boolean;
   retrySafety?: "safe" | "non-idempotent";
   retryBaseDelayMs?: number;
   sleep?: (ms: number) => Promise<void>;
@@ -435,6 +436,9 @@ export interface TelegramBridgeApiRuntimeDeps {
     error: unknown,
     details?: Record<string, unknown>,
   ) => void;
+  now?: () => number;
+  chatActionMinIntervalMs?: number;
+  chatActionMaxGates?: number;
 }
 
 export interface TelegramBridgeApiRuntime {
@@ -995,7 +999,13 @@ async function callTelegramWithRetry<TResponse>(
         ),
       );
     } catch (error) {
-      const retryable = isRetryableTelegramApiError(error);
+      const retryable =
+      isRetryableTelegramApiError(error) &&
+      !(
+        options?.retryRateLimit === false &&
+        error instanceof TelegramApiHttpError &&
+        error.status === 429
+      );
       if (!retrySafe) {
         if (error instanceof TelegramApiHttpError && error.status === 429) {
           if (attempt >= maxAttempts - 1) throw error;
@@ -1321,11 +1331,100 @@ export function createDefaultTelegramBridgeApiRuntime(deps: {
 export function createTelegramBridgeApiRuntime(
   deps: TelegramBridgeApiRuntimeDeps,
 ): TelegramBridgeApiRuntime {
+  const now = deps.now ?? Date.now;
+  const chatActionMinIntervalMs = Math.max(
+    0,
+    deps.chatActionMinIntervalMs ?? 2_000,
+  );
+  const chatActionMaxGates = Math.max(1, deps.chatActionMaxGates ?? 256);
+  const chatActionGates = new Map<
+    string,
+    { inFlight?: Promise<unknown>; notBeforeMs: number }
+  >();
+  const getChatActionKey = (
+    method: string,
+    body: Record<string, unknown>,
+  ): string | undefined => {
+    if (method !== "sendChatAction") return undefined;
+    const chatId = body.chat_id;
+    const action = body.action;
+    if (
+      (typeof chatId !== "number" && typeof chatId !== "string") ||
+      typeof action !== "string"
+    ) {
+      return undefined;
+    }
+    const threadId = body.message_thread_id;
+    return `${String(chatId)}:${
+      typeof threadId === "number" || typeof threadId === "string"
+        ? String(threadId)
+        : "all"
+    }:${action}`;
+  };
   const callRecorded = async <TResponse>(
     method: string,
     body: Record<string, unknown>,
     options?: TelegramApiCallOptions,
   ): Promise<TResponse> => {
+    const chatActionKey = getChatActionKey(method, body);
+    if (chatActionKey) {
+      const nowMs = now();
+      for (const [key, candidate] of chatActionGates) {
+        if (!candidate.inFlight && nowMs >= candidate.notBeforeMs) {
+          chatActionGates.delete(key);
+        }
+      }
+      let gate = chatActionGates.get(chatActionKey);
+      if (!gate) {
+        if (chatActionGates.size >= chatActionMaxGates) return true as TResponse;
+        gate = { notBeforeMs: 0 };
+        chatActionGates.set(chatActionKey, gate);
+      }
+      if (gate.inFlight) return (await gate.inFlight) as TResponse;
+      if (now() < gate.notBeforeMs) return true as TResponse;
+      let request: Promise<TResponse>;
+      request = Promise.resolve()
+        .then(() =>
+          deps.client.call<TResponse>(method, body, {
+            ...options,
+            retryRateLimit: false,
+          }),
+        )
+        .then((result) => {
+          gate.notBeforeMs = now() + chatActionMinIntervalMs;
+          return result;
+        })
+        .catch((error: unknown) => {
+          if (error instanceof TelegramApiHttpError && error.status === 429) {
+            const retryAfterMs = Math.max(
+              chatActionMinIntervalMs,
+              (error.retryAfterSeconds ?? 0) * 1_000,
+            );
+            gate.notBeforeMs = now() + retryAfterMs;
+            deps.recordRuntimeEvent(
+              "api",
+              error,
+              withTelegramTransportDiagnostics(error, {
+                method,
+                rateLimited: true,
+                retryAfterMs,
+              }),
+            );
+            return true as TResponse;
+          }
+          deps.recordRuntimeEvent(
+            "api",
+            error,
+            withTelegramTransportDiagnostics(error, { method }),
+          );
+          throw error;
+        })
+        .finally(() => {
+          if (gate.inFlight === request) gate.inFlight = undefined;
+        });
+      gate.inFlight = request;
+      return request;
+    }
     try {
       return await deps.client.call<TResponse>(method, body, options);
     } catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.24.2",
+  "version": "0.24.3",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -30,7 +30,7 @@
     "test": "node --experimental-strip-types --test --test-reporter=dot tests/*.test.ts",
     "test:verbose": "node --experimental-strip-types --test --test-reporter=spec tests/*.test.ts",
     "typecheck": "tsc --noEmit",
-    "audit": "npm audit",
+    "audit": "node --experimental-strip-types scripts/audit-dependencies.ts",
     "pack:check": "npm pack --dry-run",
     "validate": "npm run typecheck && npm test && npm run audit && npm run pack:check"
   },
@@ -43,6 +43,7 @@
     "BACKLOG.md",
     "CHANGELOG.md",
     "docs/",
+    "scripts/",
     "screenshot.png"
   ],
   "exports": {
@@ -75,22 +76,24 @@
     "typescript": "latest"
   },
   "overrides": {
-    "protobufjs": "7.6.4",
+    "brace-expansion": "5.0.7",
+    "protobufjs": "7.6.5",
     "undici": "8.5.0",
     "ws": "8.21.0",
     "@earendil-works/pi-coding-agent": {
-      "protobufjs": "7.6.4",
+      "brace-expansion": "5.0.7",
+      "protobufjs": "7.6.5",
       "undici": "8.5.0",
       "ws": "8.21.0",
       "@google/genai": {
-        "protobufjs": "7.6.4",
+        "protobufjs": "7.6.5",
         "ws": "8.21.0"
       },
       "@earendil-works/pi-ai": {
-        "protobufjs": "7.6.4",
+        "protobufjs": "7.6.5",
         "ws": "8.21.0",
         "@google/genai": {
-          "protobufjs": "7.6.4",
+          "protobufjs": "7.6.5",
           "ws": "8.21.0"
         }
       }

package/scripts/audit-dependencies.ts

@@ -0,0 +1,78 @@
+/**
+ * Dependency audit command adapter
+ * Runs raw npm audit, prints its output, and applies the fail-closed repository policy
+ */
+
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+
+import {
+  evaluateDependencyAudit,
+  type AuditReport,
+} from "./dependency-audit-policy.ts";
+
+function readInstalledPackageVersion(root: string, nodePath: string): string {
+  if (
+    path.isAbsolute(nodePath) ||
+    nodePath.includes("..") ||
+    !nodePath.startsWith("node_modules/")
+  ) {
+    throw new Error(`unsafe installed package path: ${nodePath}`);
+  }
+  const packageJsonPath = path.join(root, nodePath, "package.json");
+  const parsed = JSON.parse(readFileSync(packageJsonPath, "utf8")) as {
+    version?: unknown;
+  };
+  if (typeof parsed.version !== "string") {
+    throw new Error(`installed package has no valid version: ${nodePath}`);
+  }
+  return parsed.version;
+}
+
+function run(): void {
+  const result = spawnSync("npm", ["audit", "--json"], {
+    cwd: process.cwd(),
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  if (result.stdout) process.stdout.write(result.stdout);
+  if (result.stderr) process.stderr.write(result.stderr);
+  if (result.error) throw result.error;
+  if (result.signal || (result.status !== 0 && result.status !== 1)) {
+    throw new Error(
+      `npm audit command failed: status=${String(result.status)} signal=${String(result.signal)}`,
+    );
+  }
+
+  let report: AuditReport;
+  try {
+    report = JSON.parse(result.stdout) as AuditReport;
+  } catch (error) {
+    throw new Error(`could not parse npm audit JSON: ${String(error)}`);
+  }
+  const evaluation = evaluateDependencyAudit(
+    report,
+    (nodePath) => readInstalledPackageVersion(process.cwd(), nodePath),
+  );
+  const expectedStatus = evaluation.vulnerabilityCount === 0 ? 0 : 1;
+  if (result.status !== expectedStatus) {
+    throw new Error(
+      `npm audit exit status mismatch: expected ${expectedStatus}, got ${String(result.status)}`,
+    );
+  }
+  if (evaluation.vulnerabilityCount === 0) {
+    console.log("Dependency audit passed with zero vulnerabilities.");
+    return;
+  }
+  console.warn(
+    `Accepted ${evaluation.vulnerabilityCount} audit graph entries rooted only in approved sources ${evaluation.acceptedAdvisorySources.join(", ")}; exception expires after 2026-08-21 UTC.`,
+  );
+}
+
+try {
+  run();
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}

package/scripts/dependency-audit-policy.ts

@@ -0,0 +1,300 @@
+/**
+ * Fail-closed dependency audit policy
+ * Zones: repository validation, dependency security
+ * Validates the exact expiring Pi-shrinkwrap exception and installed package evidence
+ */
+
+const EXCEPTION_EXPIRES_AT = Date.parse("2026-08-22T00:00:00Z");
+
+interface AuditAdvisory {
+  source: number;
+  name: string;
+  url: string;
+  severity: string;
+}
+
+interface AuditVulnerability {
+  name: string;
+  severity: string;
+  via: Array<string | AuditAdvisory>;
+  nodes: string[];
+}
+
+export interface AuditReport {
+  error?: unknown;
+  metadata?: {
+    vulnerabilities?: {
+      info?: number;
+      low?: number;
+      moderate?: number;
+      high?: number;
+      critical?: number;
+      total?: number;
+    };
+  };
+  vulnerabilities?: Record<string, AuditVulnerability>;
+}
+
+interface AllowedAdvisory {
+  source: number;
+  packageName: string;
+  version: string;
+  severity: string;
+  url: string;
+  nodes: readonly string[];
+}
+
+const ALLOWED_ADVISORIES = new Map<number, AllowedAdvisory>([
+  [
+    1123898,
+    {
+      source: 1123898,
+      packageName: "brace-expansion",
+      version: "5.0.6",
+      severity: "high",
+      url: "https://github.com/advisories/GHSA-3jxr-9vmj-r5cp",
+      nodes: [
+        "node_modules/@earendil-works/pi-coding-agent/node_modules/brace-expansion",
+      ],
+    },
+  ],
+  [
+    1123964,
+    {
+      source: 1123964,
+      packageName: "protobufjs",
+      version: "7.6.4",
+      severity: "moderate",
+      url: "https://github.com/advisories/GHSA-j3f2-48v5-ccww",
+      nodes: [
+        "node_modules/@earendil-works/pi-coding-agent/node_modules/protobufjs",
+      ],
+    },
+  ],
+]);
+
+const ALLOWED_GRAPH: Readonly<Record<string, readonly string[]>> = {
+  "brace-expansion": [],
+  protobufjs: [],
+  "@google/genai": ["protobufjs"],
+  "@earendil-works/pi-ai": ["@google/genai"],
+  "@earendil-works/pi-agent-core": ["@earendil-works/pi-ai"],
+  "@earendil-works/pi-coding-agent": [
+    "@earendil-works/pi-agent-core",
+    "@earendil-works/pi-ai",
+  ],
+};
+
+const ALLOWED_GRAPH_SEVERITIES: Readonly<Record<string, string>> = {
+  "brace-expansion": "high",
+  protobufjs: "moderate",
+  "@google/genai": "moderate",
+  "@earendil-works/pi-ai": "moderate",
+  "@earendil-works/pi-agent-core": "moderate",
+  "@earendil-works/pi-coding-agent": "moderate",
+};
+
+const ALLOWED_GRAPH_NODES: Readonly<Record<string, readonly string[]>> = {
+  "brace-expansion": [
+    "node_modules/@earendil-works/pi-coding-agent/node_modules/brace-expansion",
+  ],
+  protobufjs: [
+    "node_modules/@earendil-works/pi-coding-agent/node_modules/protobufjs",
+  ],
+  "@google/genai": [
+    "node_modules/@google/genai",
+    "node_modules/@earendil-works/pi-coding-agent/node_modules/@google/genai",
+  ],
+  "@earendil-works/pi-ai": [
+    "node_modules/@earendil-works/pi-ai",
+    "node_modules/@earendil-works/pi-coding-agent/node_modules/@earendil-works/pi-ai",
+  ],
+  "@earendil-works/pi-agent-core": [
+    "node_modules/@earendil-works/pi-agent-core",
+    "node_modules/@earendil-works/pi-coding-agent/node_modules/@earendil-works/pi-agent-core",
+  ],
+  "@earendil-works/pi-coding-agent": [
+    "node_modules/@earendil-works/pi-coding-agent",
+  ],
+};
+
+export interface AuditEvaluation {
+  acceptedAdvisorySources: number[];
+  vulnerabilityCount: number;
+}
+
+function hasExactMembers(actual: readonly string[], expected: readonly string[]): boolean {
+  return (
+    actual.length === expected.length &&
+    new Set(actual).size === actual.length &&
+    expected.every((value) => actual.includes(value))
+  );
+}
+
+export function evaluateDependencyAudit(
+  report: AuditReport,
+  readInstalledVersion: (nodePath: string) => string,
+  nowMs = Date.now(),
+): AuditEvaluation {
+  if (report.error !== undefined) {
+    throw new Error("npm audit returned an error payload");
+  }
+  const vulnerabilities = report.vulnerabilities;
+  if (!vulnerabilities || typeof vulnerabilities !== "object") {
+    throw new Error("npm audit output is missing vulnerabilities");
+  }
+
+  const entries = Object.entries(vulnerabilities);
+  const counts = report.metadata?.vulnerabilities;
+  if (!counts) {
+    throw new Error("npm audit output is missing vulnerability metadata");
+  }
+  const countKeys = [
+    "info",
+    "low",
+    "moderate",
+    "high",
+    "critical",
+    "total",
+  ] as const;
+  for (const key of countKeys) {
+    if (!Number.isInteger(counts[key]) || (counts[key] ?? -1) < 0) {
+      throw new Error(`npm audit metadata has invalid ${key} count`);
+    }
+  }
+  const severityTotal =
+    (counts.info ?? 0) +
+    (counts.low ?? 0) +
+    (counts.moderate ?? 0) +
+    (counts.high ?? 0) +
+    (counts.critical ?? 0);
+  if (severityTotal !== counts.total || counts.total !== entries.length) {
+    throw new Error(
+      `npm audit vulnerability total mismatch: metadata=${String(counts.total)}, severities=${severityTotal}, graph=${entries.length}`,
+    );
+  }
+  if (entries.length === 0) {
+    return { acceptedAdvisorySources: [], vulnerabilityCount: 0 };
+  }
+  if (nowMs >= EXCEPTION_EXPIRES_AT) {
+    throw new Error(
+      "approved dependency audit exception expired at 2026-08-22T00:00:00Z",
+    );
+  }
+
+  const acceptedSources = new Set<number>();
+  for (const [name, vulnerability] of entries) {
+    if (vulnerability.name !== name) {
+      throw new Error(`npm audit graph key/name mismatch for ${name}`);
+    }
+    const allowedParents = ALLOWED_GRAPH[name];
+    const allowedNodes = ALLOWED_GRAPH_NODES[name];
+    const allowedSeverity = ALLOWED_GRAPH_SEVERITIES[name];
+    if (!allowedParents || !allowedNodes || !allowedSeverity) {
+      throw new Error(`unapproved vulnerable package: ${name}`);
+    }
+    if (vulnerability.severity !== allowedSeverity) {
+      throw new Error(
+        `unapproved severity for ${name}: expected ${allowedSeverity}, got ${vulnerability.severity}`,
+      );
+    }
+    if (!Array.isArray(vulnerability.via) || !Array.isArray(vulnerability.nodes)) {
+      throw new Error(`malformed npm audit graph entry for ${name}`);
+    }
+    if (!hasExactMembers(vulnerability.nodes, allowedNodes)) {
+      throw new Error(
+        `audit graph paths differ for ${name}: expected ${allowedNodes.join(",")}, got ${vulnerability.nodes.join(",")}`,
+      );
+    }
+
+    const parentEdges = vulnerability.via.filter(
+      (via): via is string => typeof via === "string",
+    );
+    const advisories = vulnerability.via.filter(
+      (via): via is AuditAdvisory => typeof via !== "string",
+    );
+    if (allowedParents.length > 0) {
+      if (advisories.length > 0 || !hasExactMembers(parentEdges, allowedParents)) {
+        throw new Error(
+          `audit graph edges differ for ${name}: expected ${allowedParents.join(",")}, got ${parentEdges.join(",")}`,
+        );
+      }
+      for (const parent of parentEdges) {
+        if (!vulnerabilities[parent]) {
+          throw new Error(`missing npm audit graph node: ${parent}`);
+        }
+      }
+      continue;
+    }
+    if (parentEdges.length > 0 || advisories.length !== 1) {
+      throw new Error(`audit leaf shape differs for ${name}`);
+    }
+    const advisory = advisories[0];
+    const allowed = ALLOWED_ADVISORIES.get(advisory.source);
+    if (
+      !allowed ||
+      advisory.name !== allowed.packageName ||
+      advisory.url !== allowed.url ||
+      advisory.severity !== allowed.severity ||
+      name !== allowed.packageName ||
+      vulnerability.severity !== allowed.severity
+    ) {
+      throw new Error(
+        `unapproved advisory for ${name}: source=${String(advisory.source)} url=${advisory.url}`,
+      );
+    }
+    acceptedSources.add(advisory.source);
+  }
+
+  const rootsByPackage = new Map<string, Set<number>>();
+  const resolveRoots = (name: string, stack: Set<string>): Set<number> => {
+    const cached = rootsByPackage.get(name);
+    if (cached) return cached;
+    if (stack.has(name)) throw new Error(`cycle in npm audit graph at ${name}`);
+    const vulnerability = vulnerabilities[name];
+    if (!vulnerability) throw new Error(`missing npm audit graph node: ${name}`);
+    const nextStack = new Set(stack).add(name);
+    const roots = new Set<number>();
+    for (const via of vulnerability.via) {
+      if (typeof via === "string") {
+        for (const source of resolveRoots(via, nextStack)) roots.add(source);
+      } else {
+        roots.add(via.source);
+      }
+    }
+    if (roots.size === 0) {
+      throw new Error(`npm audit graph node has no approved advisory root: ${name}`);
+    }
+    rootsByPackage.set(name, roots);
+    return roots;
+  };
+
+  for (const name of Object.keys(vulnerabilities)) resolveRoots(name, new Set());
+
+  for (const source of acceptedSources) {
+    const allowed = ALLOWED_ADVISORIES.get(source);
+    if (!allowed) throw new Error(`missing policy for advisory source ${source}`);
+    const vulnerability = vulnerabilities[allowed.packageName];
+    if (!vulnerability) {
+      throw new Error(`missing leaf package for advisory source ${source}`);
+    }
+    for (const nodePath of vulnerability.nodes) {
+      if (!allowed.nodes.includes(nodePath)) {
+        throw new Error(
+          `unapproved installed path for advisory source ${source}: ${nodePath}`,
+        );
+      }
+      const version = readInstalledVersion(nodePath);
+      if (version !== allowed.version) {
+        throw new Error(
+          `unapproved installed version at ${nodePath}: expected ${allowed.version}, got ${version}`,
+        );
+      }
+    }
+  }
+
+  return {
+    acceptedAdvisorySources: [...acceptedSources].sort((a, b) => a - b),
+    vulnerabilityCount: entries.length,
+  };
+}