@gotgenes/pi-subagents 4.1.1 → 5.1.0

package/CHANGELOG.md

@@ -5,6 +5,45 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.1.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v5.0.0...pi-subagents-v5.1.0) (2026-05-19)
+
+
+### Features
+
+* add debugLog utility gated on PI_SUBAGENTS_DEBUG ([#57](https://github.com/gotgenes/pi-packages/issues/57)) ([2b8874a](https://github.com/gotgenes/pi-packages/commit/2b8874aeaa28bc09550dd0f8977b7b57d996b254))
+* thread debugLog into agent-manager and notification catch blocks ([#57](https://github.com/gotgenes/pi-packages/issues/57)) ([07943a3](https://github.com/gotgenes/pi-packages/commit/07943a341fbe0a0a35f25af3f4b15bc28cdee7a2))
+* thread debugLog into custom-agents and memory catch blocks ([#57](https://github.com/gotgenes/pi-packages/issues/57)) ([e239925](https://github.com/gotgenes/pi-packages/commit/e2399253410dc644b38269b52de6e6a4bfa75d3a))
+* thread debugLog into env catch blocks ([#57](https://github.com/gotgenes/pi-packages/issues/57)) ([f5ff82f](https://github.com/gotgenes/pi-packages/commit/f5ff82f0c06be3c1dfe5d5ec0ff3621105b55ad0))
+* thread debugLog into output-file catch block ([#57](https://github.com/gotgenes/pi-packages/issues/57)) ([a72b11b](https://github.com/gotgenes/pi-packages/commit/a72b11bc1f36bf256f520b9f13e546295fc6cb64))
+* thread debugLog into skill-loader catch block ([#57](https://github.com/gotgenes/pi-packages/issues/57)) ([b57231c](https://github.com/gotgenes/pi-packages/commit/b57231cc5de56a834c34f9e171b909d03939505c))
+* thread debugLog into worktree catch blocks ([#57](https://github.com/gotgenes/pi-packages/issues/57)) ([049f489](https://github.com/gotgenes/pi-packages/commit/049f4891ab5b09c9d1a301f7d8af797cb165cb4c))
+
+
+### Documentation
+
+* plan structured debug logging for silenced catch blocks ([#57](https://github.com/gotgenes/pi-packages/issues/57)) ([28e403e](https://github.com/gotgenes/pi-packages/commit/28e403ea2605405da1a57871af946ee2971ee289))
+
+## [5.0.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v4.1.1...pi-subagents-v5.0.0) (2026-05-19)
+
+
+### ⚠ BREAKING CHANGES
+
+* All @earendil-works/pi-* peerDependencies and devDependencies now require >=0.75.0, aligning with Pi's Node 22 minimum.
+* Minimum supported Node.js version is now >=22, aligning with Pi v0.75.0. tsconfig target raised from ES2023 to ES2024.
+    - ES2024 APIs (Promise.withResolvers, Object.groupBy, Map.groupBy, Array.fromAsync) are now allowed.
+    - @types/node catalog aligned to ^22.15.3.
+    - pi-autoformat now declares engines.node for consistency.
+
+### Features
+
+* raise minimum Node.js version to 22 and bump tsconfig target to ES2024 ([98a5b01](https://github.com/gotgenes/pi-packages/commit/98a5b01ca20aa1feed14a60bfa7bb9e082c9914b))
+* raise minimum Pi dependency to v0.75.0 ([1068329](https://github.com/gotgenes/pi-packages/commit/10683290d2a789880848bf7eb093d4307b6eff40))
+
+
+### Documentation
+
+* **retro:** add retro notes for issue [#54](https://github.com/gotgenes/pi-packages/issues/54) ([d753eb3](https://github.com/gotgenes/pi-packages/commit/d753eb3f836a28f089197a45dd582dc4be88872d))
+
 ## [4.1.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v4.1.0...pi-subagents-v4.1.1) (2026-05-18)
 
 

package/docs/plans/0057-structured-debug-logging.md

@@ -0,0 +1,184 @@
+---
+issue: 57
+issue_title: "feat: structured debug logging for silenced catch blocks"
+---
+
+# Structured debug logging for silenced catch blocks
+
+## Problem Statement
+
+The codebase contains ~20 `catch { /* ignore */ }` blocks spread across
+`agent-manager.ts`, `worktree.ts`, `output-file.ts`, `skill-loader.ts`,
+`custom-agents.ts`, `memory.ts`, `env.ts`, and `notification.ts`.
+Each block correctly suppresses a non-essential side-effect failure, but
+in development the silence makes it impossible to diagnose what is actually
+failing inside those paths.
+
+## Goals
+
+- Add a `debugLog(context, err)` utility in `src/debug.ts` gated on
+  `PI_SUBAGENTS_DEBUG=1`.
+- Thread `debugLog` into every silenced `catch` block listed in the issue scope.
+- Leave production behavior **completely unchanged** — no new log output unless
+  the env var is explicitly set.
+- Provide a `debug.test.ts` unit test covering the on/off branching.
+
+## Non-Goals
+
+- `usage.ts` catch blocks — they return `0`/`null` on failure and are already
+  recoverable, not truly "silent drops"; they are out of scope.
+- `settings.ts` catch block — it returns `false` on failure, already surfaced
+  to the caller; out of scope.
+- Log rotation, structured JSON output, or stderr vs. stdout routing.
+- Wiring debug output to the Pi UI; `console.warn` to stderr is sufficient.
+
+## Background
+
+The `AGENTS.md` rule "prefer explicit configuration over hidden behavior" aligns
+with gating noise behind an opt-in env var rather than always-on logging.
+The code-style skill notes that business logic should remain pure — `debug.ts`
+must not import the Pi SDK; it only reads `process.env`.
+
+The `DEBUG` constant is evaluated once at module import time (top-level `const`).
+That matches how similar opt-in env vars work in Node.js tooling and keeps the
+hot path to a single boolean branch.
+
+### Catch blocks in scope
+
+| File               | Line(s)                              | Context label(s)                                        |
+| ------------------ | ------------------------------------ | ------------------------------------------------------- |
+| `env.ts`           | 15, 23                               | `"git rev-parse"`, `"git branch"`                       |
+| `skill-loader.ts`  | 74                                   | `"readdirSync skill root"`                              |
+| `custom-agents.ts` | 37, 47                               | `"readdirSync agents dir"`, `"readFileSync agent file"` |
+| `memory.ts`        | 33, 47                               | `"lstatSync"`, `"readFileSync"`                         |
+| `output-file.ts`   | 83                                   | `"write JSONL chunk"`                                   |
+| `worktree.ts`      | 40, 56, 110, 130, 132, 147, 151, 161 | `"git rev-parse"`, `"git worktree add"`, etc.           |
+| `agent-manager.ts` | 233, 249, 266, 275, 480              | `"outputCleanup"`, `"onComplete callback"`, etc.        |
+| `notification.ts`  | 145                                  | `"notification render"`                                 |
+
+## Design Overview
+
+### `src/debug.ts`
+
+```typescript
+export const DEBUG = process.env.PI_SUBAGENTS_DEBUG === "1";
+
+export function debugLog(context: string, err: unknown): void {
+  if (DEBUG) console.warn(`[pi-subagents:debug] ${context}:`, err);
+}
+```
+
+The module-level `DEBUG` constant is the canonical source.
+`debugLog` is a pure side-effect function: no return value, no SDK dependency,
+no coupling to Pi types.
+
+### Threading pattern
+
+Every silenced `catch` block is updated from:
+
+```typescript
+} catch { /* ignore */ }
+```
+
+to:
+
+```typescript
+} catch (err) { debugLog("<context label>", err); }
+```
+
+When the block already had a named error (`catch (err)`), only the `debugLog`
+call is added; the existing comment, if descriptive, is removed in favour of
+the context string.
+
+### Context label convention
+
+Labels read as `"<verb> <noun>"`, lower-case, mirroring the surrounding
+function name when unambiguous (e.g., `"removeWorktree"`, `"outputCleanup"`).
+
+## Module-Level Changes
+
+| File                   | Change                                                                       |
+| ---------------------- | ---------------------------------------------------------------------------- |
+| `src/debug.ts`         | **New.** Exports `DEBUG` constant and `debugLog` function.                   |
+| `test/debug.test.ts`   | **New.** Unit tests for `debugLog` on/off behaviour.                         |
+| `src/env.ts`           | Add `debugLog` import; name the two bare `catch` errors; call `debugLog`.    |
+| `src/skill-loader.ts`  | Add `debugLog` import; name the bare `catch` error; call `debugLog`.         |
+| `src/custom-agents.ts` | Add `debugLog` import; name the two bare `catch` errors; call `debugLog`.    |
+| `src/memory.ts`        | Add `debugLog` import; name the two bare `catch` errors; call `debugLog`.    |
+| `src/output-file.ts`   | Add `debugLog` import; name the bare `catch` error; call `debugLog`.         |
+| `src/worktree.ts`      | Add `debugLog` import; name the eight bare `catch` errors; call `debugLog`.  |
+| `src/agent-manager.ts` | Add `debugLog` import; name/update the five `catch` blocks; call `debugLog`. |
+| `src/notification.ts`  | Add `debugLog` import; name the bare `catch` error; call `debugLog`.         |
+
+## Test Impact Analysis
+
+1. **New tests enabled** — `debug.test.ts` can directly unit-test `debugLog` in
+   isolation.
+   Asserting `console.warn` is/isn't called based on the env var is now trivial.
+   Previously this path was entirely untested.
+
+2. **Existing tests become redundant** — None.
+   The catch blocks were never exercised by existing tests (they were silent
+   drops), so no existing test coverage needs to be removed.
+
+3. **Tests that must stay as-is** — All existing tests remain valid.
+   The threading adds a call inside each catch but does not change control flow,
+   return values, or thrown exceptions; no test expectations change.
+
+## TDD Order
+
+1. **`src/debug.ts` + `test/debug.test.ts`**
+   Test surface: `debugLog` calls `console.warn` when `PI_SUBAGENTS_DEBUG=1`;
+   does nothing when unset or `"0"`.
+   Use `vi.spyOn(console, 'warn')` + `vi.stubEnv('PI_SUBAGENTS_DEBUG', '1')` +
+   `vi.resetModules()` + dynamic import to exercise both branches.
+   Suggested commit: `feat: add debugLog utility gated on PI_SUBAGENTS_DEBUG (#57)`
+
+2. **Thread into `env.ts`**
+   Test surface: `env.test.ts` — existing tests still pass (no new assertions
+   required because the catch paths are tested implicitly by the non-git-dir
+   test already covering the swallowed failures).
+   Suggested commit: `feat: thread debugLog into env catch blocks (#57)`
+
+3. **Thread into `skill-loader.ts`**
+   Test surface: `skill-loader.test.ts` — existing tests still pass.
+   The readdirSync-error catch is exercised when the skill root does not exist
+   (covered by existing "not found" test paths).
+   Suggested commit: `feat: thread debugLog into skill-loader catch block (#57)`
+
+4. **Thread into `custom-agents.ts` and `memory.ts`**
+   These two files have structurally identical filesystem-error catch blocks and
+   can land in a single step.
+   Test surface: `custom-agents.test.ts`, `memory.test.ts` — existing tests
+   still pass.
+   Suggested commit: `feat: thread debugLog into custom-agents and memory catch blocks (#57)`
+
+5. **Thread into `output-file.ts`**
+   Test surface: `output-file.test.ts` — existing tests still pass.
+   Suggested commit: `feat: thread debugLog into output-file catch block (#57)`
+
+6. **Thread into `worktree.ts`**
+   Test surface: `worktree.test.ts` — existing tests still pass.
+   Eight catch sites; name each with its enclosing function for label clarity.
+   Suggested commit: `feat: thread debugLog into worktree catch blocks (#57)`
+
+7. **Thread into `agent-manager.ts` and `notification.ts`**
+   Test surface: `agent-manager.test.ts`, `notification.test.ts` — existing
+   tests still pass.
+   Suggested commit: `feat: thread debugLog into agent-manager and notification catch blocks (#57)`
+
+## Risks and Mitigations
+
+| Risk                                                                                                          | Mitigation                                                                                                                                  |
+| ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `DEBUG` is a module-level constant — `vi.stubEnv` alone won't flip it mid-test                                | Use `vi.resetModules()` + dynamic `import()` inside a test that sets the env var before re-importing; the test skill documents this pattern |
+| Adding `(err)` to a bare `catch` in TypeScript is type-safe (`unknown`) but a `noImplicitAny`-adjacent change | `tsconfig` already uses `"useUnknownInCatchVariables": true` (default in strict mode); no cast needed                                       |
+| Verbose worktree.ts threading (8 sites) could miss one                                                        | The TDD step runs `pnpm vitest run worktree` and `pnpm run check` before committing                                                         |
+
+## Open Questions
+
+- Should a future issue expose `debugLog` as part of the public `service.ts` API
+  so consumer extensions can share the same debug flag?
+  Deferred — out of scope for this change; no consumer currently needs it.
+- Should `PI_SUBAGENTS_DEBUG` be documented in the package `README.md`?
+  Likely yes, but deferred to a follow-up doc PR.

package/docs/retro/0054-decompose-index-into-modules.md

@@ -0,0 +1,38 @@
+---
+issue: 54
+issue_title: "refactor: decompose src/index.ts into tool + menu modules"
+---
+
+# Retro: #54 — decompose index.ts into tool + menu modules
+
+## Final Retrospective (2026-05-18T02:20:00Z)
+
+### Session summary
+
+Decomposed `src/index.ts` from 1,619 lines to 265 lines across 8 commits.
+Extracted 7 new modules (`tools/helpers.ts`, `renderer.ts`, `notification.ts`, `tools/agent-tool.ts`, `tools/get-result-tool.ts`, `tools/steer-tool.ts`, `ui/agent-menu.ts`) with 66 new tests (379 → 445 total).
+Released as `pi-subagents-v4.1.1`.
+Filed follow-up #66 (replace `as any` casts with proper SDK types) and #67 (flaky `pi-autoformat` acceptance test).
+
+### Observations
+
+#### What went well
+
+- Leaf-first extraction order worked cleanly — helpers, then renderer, then notification, then tools, then menu. Each step left the repo green with no cascading breakage.
+- The `createNotificationSystem` factory pattern with arrow-closure capture of `widget` (assigned after `AgentManager` construction) preserved the existing deferred-reference semantics without restructuring initialization order.
+
+#### What caused friction (agent side)
+
+- `wrong-abstraction` — Applied the code-style skill's "keep Pi SDK imports out of business-logic modules" rule to tool/menu modules, which are SDK consumers, not business logic. Used `unknown` for `ExtensionContext`, `AgentSession`, `ModelRegistry` in factory dep interfaces, requiring 9 `as any` casts in `index.ts`. User caught this post-ship. Impact: filed #66 as a follow-up cleanup; the casts are cosmetic (no runtime effect) but degrade type safety. Fixed the code-style skill to clarify the boundary. (user-caught)
+
+- `missing-context` — Four test files (`notification.test.ts`, `get-result-tool.test.ts`, `steer-tool.test.ts`, `agent-tool.test.ts`) omitted `compactionCount: 0` from `AgentRecord` factories. Caught at the final `pnpm run check` step, not during test writing. The testing skill already says "grep for ALL test files that construct a compatible mock." Impact: one extra fix cycle delegated to a subagent, no rework beyond that step. (self-identified)
+
+- `other` — `Edit` tool failed 3 times matching the UTF-8 middle dot (`·`, U+00B7) in the steer tool's `stateParts.join(" · ")` line. The third attempt produced a partial match that left the file in a broken state (dangling orphan code after the replacement anchor). Required `git restore` and a fallback to `python3` line-range replacement. The same `python3` approach for the menu extraction lost the closing `}` of the default export function. Impact: ~5 minutes of rework across the two extraction steps, plus one `git restore`.
+
+#### What caused friction (user side)
+
+- The `as any` casts could have been caught earlier if the user had flagged the `unknown` types during the planning phase. However, the plan didn't prescribe exact interface types — that was an implementation decision. The user's post-ship review ("Why did we have to cast `as any`? Take a look at `packages/pi-permission-system/` as a model") was an efficient redirect that immediately scoped the investigation.
+
+### Changes made
+
+1. `.pi/skills/code-style/SKILL.md` — Clarified SDK-boundary guidance: tool definitions, event handlers, and command handlers may import SDK types directly; the restriction targets pure helpers and domain modules.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "4.1.1",
+  "version": "5.1.0",
   "exports": {
     ".": "./src/service.ts"
   },
@@ -30,20 +30,20 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": ">=0.74.0",
-    "@earendil-works/pi-coding-agent": ">=0.74.0",
-    "@earendil-works/pi-tui": ">=0.74.0"
+    "@earendil-works/pi-ai": ">=0.75.0",
+    "@earendil-works/pi-coding-agent": ">=0.75.0",
+    "@earendil-works/pi-tui": ">=0.75.0"
   },
   "dependencies": {
     "@sinclair/typebox": "^0.34.49",
     "nanoid": "^5.0.0"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.14",
-    "@types/node": "^25.6.2",
+    "@types/node": "^22.15.3",
     "typescript": "^6.0.3",
     "vitest": "^4.1.5",
     "rumdl": "^0.1.93"

package/src/agent-manager.ts

@@ -10,6 +10,7 @@ import { randomUUID } from "node:crypto";
 import type { Model } from "@earendil-works/pi-ai";
 import type { AgentSession, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { resumeAgent, runAgent, type ToolActivity } from "./agent-runner.js";
+import { debugLog } from "./debug.js";
 import type { AgentInvocation, AgentRecord, IsolationMode, SubagentType, ThinkingLevel } from "./types.js";
 import { addUsage } from "./usage.js";
 import { cleanupWorktree, createWorktree, pruneWorktrees, } from "./worktree.js";
@@ -230,7 +231,7 @@ export class AgentManager {
 
         // Final flush of streaming output file
         if (record.outputCleanup) {
-          try { record.outputCleanup(); } catch { /* ignore */ }
+          try { record.outputCleanup(); } catch (err) { debugLog("outputCleanup", err); }
           record.outputCleanup = undefined;
         }
 
@@ -246,7 +247,7 @@ export class AgentManager {
 
         if (options.isBackground) {
           this.runningBackground--;
-          try { this.onComplete?.(record); } catch { /* ignore completion side-effect errors */ }
+          try { this.onComplete?.(record); } catch (err) { debugLog("onComplete callback", err); }
           this.drainQueue();
         }
         return responseText;
@@ -263,7 +264,7 @@ export class AgentManager {
 
         // Final flush of streaming output file on error
         if (record.outputCleanup) {
-          try { record.outputCleanup(); } catch { /* ignore */ }
+          try { record.outputCleanup(); } catch (err) { debugLog("outputCleanup on error", err); }
           record.outputCleanup = undefined;
         }
 
@@ -272,7 +273,7 @@ export class AgentManager {
           try {
             const wtResult = cleanupWorktree(ctx.cwd, record.worktree, options.description);
             record.worktreeResult = wtResult;
-          } catch { /* ignore cleanup errors */ }
+          } catch (err) { debugLog("cleanupWorktree on agent error", err); }
         }
 
         if (options.isBackground) {
@@ -477,6 +478,6 @@ export class AgentManager {
     }
     this.agents.clear();
     // Prune any orphaned git worktrees (crash recovery)
-    try { pruneWorktrees(process.cwd()); } catch { /* ignore */ }
+    try { pruneWorktrees(process.cwd()); } catch (err) { debugLog("pruneWorktrees on dispose", err); }
   }
 }

package/src/custom-agents.ts

@@ -6,6 +6,7 @@ import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { basename, join } from "node:path";
 import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
 import { BUILTIN_TOOL_NAMES } from "./agent-types.js";
+import { debugLog } from "./debug.js";
 import type { AgentConfig, MemoryScope, ThinkingLevel } from "./types.js";
 
 /**
@@ -34,7 +35,8 @@ function loadFromDir(dir: string, agents: Map<string, AgentConfig>, source: "pro
   let files: string[];
   try {
     files = readdirSync(dir).filter(f => f.endsWith(".md"));
-  } catch {
+  } catch (err) {
+    debugLog("readdirSync agents dir", err);
     return;
   }
 
@@ -44,7 +46,8 @@ function loadFromDir(dir: string, agents: Map<string, AgentConfig>, source: "pro
     let content: string;
     try {
       content = readFileSync(join(dir, file), "utf-8");
-    } catch {
+    } catch (err) {
+      debugLog("readFileSync agent file", err);
       continue;
     }
 

package/src/debug.ts

@@ -0,0 +1,12 @@
+/**
+ * debug.ts — Debug logging utility for silenced catch blocks.
+ *
+ * Set PI_SUBAGENTS_DEBUG=1 to reveal silent failures in catch blocks
+ * throughout the package. Production behavior is unchanged when unset.
+ */
+
+export const DEBUG = process.env.PI_SUBAGENTS_DEBUG === "1";
+
+export function debugLog(context: string, err: unknown): void {
+  if (DEBUG) console.warn(`[pi-subagents:debug] ${context}:`, err);
+}

package/src/env.ts

@@ -3,6 +3,7 @@
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { debugLog } from "./debug.js";
 import type { EnvInfo } from "./types.js";
 
 export async function detectEnv(pi: ExtensionAPI, cwd: string): Promise<EnvInfo> {
@@ -12,15 +13,16 @@ export async function detectEnv(pi: ExtensionAPI, cwd: string): Promise<EnvInfo>
   try {
     const result = await pi.exec("git", ["rev-parse", "--is-inside-work-tree"], { cwd, timeout: 5000 });
     isGitRepo = result.code === 0 && result.stdout.trim() === "true";
-  } catch {
-    // Not a git repo or git not installed
+  } catch (err) {
+    debugLog("git rev-parse", err);
   }
 
   if (isGitRepo) {
     try {
       const result = await pi.exec("git", ["branch", "--show-current"], { cwd, timeout: 5000 });
       branch = result.code === 0 ? result.stdout.trim() : "unknown";
-    } catch {
+    } catch (err) {
+      debugLog("git branch", err);
       branch = "unknown";
     }
   }

package/src/memory.ts

@@ -10,6 +10,7 @@
 import { existsSync, lstatSync, mkdirSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, } from "node:path";
+import { debugLog } from "./debug.js";
 import type { MemoryScope } from "./types.js";
 
 /** Maximum lines to read from MEMORY.md */
@@ -30,7 +31,8 @@ export function isUnsafeName(name: string): boolean {
 export function isSymlink(filePath: string): boolean {
   try {
     return lstatSync(filePath).isSymbolicLink();
-  } catch {
+  } catch (err) {
+    debugLog("lstatSync", err);
     return false;
   }
 }
@@ -44,7 +46,8 @@ export function safeReadFile(filePath: string): string | undefined {
   if (isSymlink(filePath)) return undefined;
   try {
     return readFileSync(filePath, "utf-8");
-  } catch {
+  } catch (err) {
+    debugLog("readFileSync", err);
     return undefined;
   }
 }

package/src/notification.ts

@@ -1,3 +1,4 @@
+import { debugLog } from "./debug.js";
 import type { AgentRecord, NotificationDetails } from "./types.js";
 import type { AgentActivity } from "./ui/agent-widget.js";
 import { getLifetimeTotal, getSessionContextPercent } from "./usage.js";
@@ -142,8 +143,8 @@ export function createNotificationSystem(deps: NotificationDeps): NotificationSy
         pendingNudges.delete(key);
         try {
           send();
-        } catch {
-          /* ignore stale completion side-effect errors */
+        } catch (err) {
+          debugLog("notification render", err);
         }
       }, delay),
     );

package/src/output-file.ts

@@ -9,6 +9,7 @@ import { appendFileSync, chmodSync, mkdirSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { AgentSession, AgentSessionEvent } from "@earendil-works/pi-coding-agent";
+import { debugLog } from "./debug.js";
 
 /**
  * Encode a cwd path as a filesystem-safe directory name. Handles:
@@ -80,7 +81,9 @@ export function streamToOutputFile(
       };
       try {
         appendFileSync(path, JSON.stringify(entry) + "\n", "utf-8");
-      } catch { /* ignore write errors */ }
+      } catch (err) {
+        debugLog("write JSONL chunk", err);
+      }
       writtenCount++;
     }
   };

package/src/skill-loader.ts

@@ -23,6 +23,7 @@ import { existsSync, readdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { debugLog } from "./debug.js";
 import { isSymlink, isUnsafeName, safeReadFile } from "./memory.js";
 
 export interface PreloadedSkill {
@@ -71,7 +72,8 @@ function findSkillDirectory(root: string, name: string): string | undefined {
     let entries: Dirent<string>[];
     try {
       entries = readdirSync(current, { withFileTypes: true });
-    } catch {
+    } catch (err) {
+      debugLog("readdirSync skill root", err);
       continue;
     }
 

package/src/worktree.ts

@@ -11,6 +11,7 @@ import { randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { debugLog } from "./debug.js";
 
 export interface WorktreeInfo {
   /** Absolute path to the worktree directory. */
@@ -37,7 +38,8 @@ export function createWorktree(cwd: string, agentId: string): WorktreeInfo | und
   try {
     execFileSync("git", ["rev-parse", "--is-inside-work-tree"], { cwd, stdio: "pipe", timeout: 5000 });
     execFileSync("git", ["rev-parse", "HEAD"], { cwd, stdio: "pipe", timeout: 5000 });
-  } catch {
+  } catch (err) {
+    debugLog("createWorktree git rev-parse", err);
     return undefined;
   }
 
@@ -53,8 +55,8 @@ export function createWorktree(cwd: string, agentId: string): WorktreeInfo | und
       timeout: 30000,
     });
     return { path: worktreePath, branch };
-  } catch {
-    // If worktree creation fails, return undefined (agent runs in normal cwd)
+  } catch (err) {
+    debugLog("git worktree add", err);
     return undefined;
   }
 }
@@ -107,8 +109,8 @@ export function cleanupWorktree(
         stdio: "pipe",
         timeout: 5000,
       });
-    } catch {
-      // Branch already exists — use a unique suffix
+    } catch (err) {
+      debugLog("git branch", err);
       branchName = `${worktree.branch}-${Date.now()}`;
       execFileSync("git", ["branch", branchName], {
         cwd: worktree.path,
@@ -127,9 +129,9 @@ export function cleanupWorktree(
       branch: worktree.branch,
       path: worktree.path,
     };
-  } catch {
-    // Best effort cleanup on error
-    try { removeWorktree(cwd, worktree.path); } catch { /* ignore */ }
+  } catch (err) {
+    debugLog("cleanupWorktree", err);
+    try { removeWorktree(cwd, worktree.path); } catch (removeErr) { debugLog("removeWorktree on cleanup error", removeErr); }
     return { hasChanges: false };
   }
 }
@@ -144,11 +146,11 @@ function removeWorktree(cwd: string, worktreePath: string): void {
       stdio: "pipe",
       timeout: 10000,
     });
-  } catch {
-    // If git worktree remove fails, try pruning
+  } catch (err) {
+    debugLog("git worktree remove", err);
     try {
       execFileSync("git", ["worktree", "prune"], { cwd, stdio: "pipe", timeout: 5000 });
-    } catch { /* ignore */ }
+    } catch (pruneErr) { debugLog("git worktree prune", pruneErr); }
   }
 }
 
@@ -158,5 +160,5 @@ function removeWorktree(cwd: string, worktreePath: string): void {
 export function pruneWorktrees(cwd: string): void {
   try {
     execFileSync("git", ["worktree", "prune"], { cwd, stdio: "pipe", timeout: 5000 });
-  } catch { /* ignore */ }
+  } catch (err) { debugLog("pruneWorktrees", err); }
 }