specweave 1.0.593 → 2.0.3

package/plugins/specweave/hooks/run-worker.mjs

@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+/**
+ * SpecWeave hook launcher (zero-dependency, cross-platform).
+ *
+ * Invoked by Claude Code in exec form (no shell):
+ *   node ${CLAUDE_PLUGIN_ROOT}/hooks/run.mjs <event>
+ *
+ * Contract:
+ *   - reads the hook JSON from stdin (5 s cap), normalizes backslashes in
+ *     tool_input.file_path, locates the installed `specweave` CLI, imports its
+ *     built hook router and prints exactly ONE JSON object;
+ *   - always exits 0; on ANY failure prints `{}` (pass) — except SessionStart,
+ *     which prints an additionalContext line telling the user the CLI is missing.
+ *
+ * CLI root resolution order:
+ *   1. $SPECWEAVE_HOME
+ *   2. <plugin root>/../..  (plugin shipped inside the npm package / repo checkout)
+ *   3. require.resolve('specweave/package.json') from $CLAUDE_PROJECT_DIR / cwd
+ *   4. `npm root -g` (result cached in a per-user private file under ~/.specweave)
+ *
+ * Fast path: PreToolUse for a file outside `.specweave/increments/` prints `{}`
+ * without loading the CLI at all (the guards only concern increment files).
+ */
+import { createRequire } from 'node:module';
+import { spawnSync } from 'node:child_process';
+import { existsSync, lstatSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const EVENTS = new Set(['session-start', 'pre-tool-use', 'stop', 'pre-compact']);
+const STDIN_CAP_MS = 5000;
+const ROUTER_REL = path.join('dist', 'src', 'core', 'hooks', 'handlers', 'hook-router.js');
+/**
+ * Per-user cache path. NEVER the shared OS temp dir: run.mjs `import()`s the
+ * path it reads back, so a world-writable cache is arbitrary code execution on
+ * every SessionStart/Stop/PreCompact of every session on the machine.
+ */
+const CACHE_DIR = safeHomeDir() ? path.join(safeHomeDir(), '.specweave') : null;
+const CACHE_FILE = CACHE_DIR ? path.join(CACHE_DIR, 'hook-cli-root') : null;
+
+function safeHomeDir() {
+  try {
+    const home = homedir();
+    return home && path.isAbsolute(home) ? home : null;
+  } catch {
+    return null;
+  }
+}
+
+/** True only for a regular file (not a symlink) owned by the current user. */
+function isPrivateOwnedFile(file) {
+  try {
+    const st = lstatSync(file);
+    if (!st.isFile()) return false;
+    const uid = typeof process.getuid === 'function' ? process.getuid() : null;
+    return uid === null || st.uid === uid;
+  } catch {
+    return false;
+  }
+}
+
+const event = process.argv[2] ?? '';
+
+function inactiveOutput() {
+  if (event === 'session-start') {
+    return {
+      hookSpecificOutput: {
+        hookEventName: 'SessionStart',
+        additionalContext:
+          'SpecWeave hooks inactive: specweave CLI not found (npm i -g specweave)',
+      },
+    };
+  }
+  return {};
+}
+
+let printed = false;
+function emit(obj) {
+  if (printed) return;
+  printed = true;
+  let text = '{}';
+  try {
+    text = JSON.stringify(obj && typeof obj === 'object' ? obj : {});
+  } catch {
+    text = '{}';
+  }
+  process.stdout.write(text + '\n', () => process.exit(0));
+}
+
+function readStdin() {
+  return new Promise((resolve) => {
+    const chunks = [];
+    let done = false;
+    const finish = () => {
+      if (done) return;
+      done = true;
+      resolve(Buffer.concat(chunks).toString('utf8'));
+    };
+    const timer = setTimeout(finish, STDIN_CAP_MS);
+    if (timer.unref) timer.unref();
+    try {
+      process.stdin.on('data', (c) => chunks.push(c));
+      process.stdin.on('end', finish);
+      process.stdin.on('error', finish);
+      process.stdin.on('close', finish);
+      if (process.stdin.readableEnded) finish();
+    } catch {
+      finish();
+    }
+  });
+}
+
+/** Returns { raw, skip } — `skip` when the event cannot possibly need the CLI. */
+function normalizeInput(raw) {
+  try {
+    const input = JSON.parse(raw);
+    if (input && typeof input === 'object') {
+      const ti = input.tool_input;
+      let filePath = '';
+      if (ti && typeof ti === 'object' && typeof ti.file_path === 'string') {
+        ti.file_path = ti.file_path.replace(/\\/g, '/');
+        filePath = ti.file_path;
+      }
+      if (typeof input.cwd === 'string') input.cwd = input.cwd.replace(/\\/g, '/');
+      const skip = event === 'pre-tool-use' && !filePath.includes('.specweave/increments/');
+      return { raw: JSON.stringify(input), skip };
+    }
+  } catch {
+    // fall through — the router tolerates a non-JSON payload
+  }
+  return { raw, skip: false };
+}
+
+function isCliRoot(dir) {
+  if (!dir) return false;
+  try {
+    const pkg = path.join(dir, 'package.json');
+    if (!existsSync(pkg) || !existsSync(path.join(dir, ROUTER_REL))) return false;
+    return JSON.parse(readFileSync(pkg, 'utf8')).name === 'specweave';
+  } catch {
+    return false;
+  }
+}
+
+function pluginRoot() {
+  if (process.env.CLAUDE_PLUGIN_ROOT) return path.resolve(process.env.CLAUDE_PLUGIN_ROOT);
+  return path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+}
+
+function fromCache() {
+  if (!CACHE_FILE || !isPrivateOwnedFile(CACHE_FILE)) return null;
+  try {
+    const cached = readFileSync(CACHE_FILE, 'utf8').trim();
+    return isCliRoot(cached) ? cached : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeCache(dir) {
+  if (!CACHE_DIR || !CACHE_FILE) return;
+  try {
+    mkdirSync(CACHE_DIR, { recursive: true, mode: 0o700 });
+    // Drop whatever is there (possibly a planted symlink) before writing.
+    rmSync(CACHE_FILE, { force: true });
+    writeFileSync(CACHE_FILE, dir, { flag: 'wx', mode: 0o600 });
+  } catch {
+    // cache is best-effort
+  }
+}
+
+function fromNpmGlobal() {
+  try {
+    const res = spawnSync('npm root -g', { shell: true, encoding: 'utf8', timeout: 4000 });
+    const root = (res.stdout || '').trim().split(/\r?\n/).pop();
+    if (!root) return null;
+    const dir = path.join(root, 'specweave');
+    if (!isCliRoot(dir)) return null;
+    writeCache(dir);
+    return dir;
+  } catch {
+    return null;
+  }
+}
+
+function resolveCliRoot() {
+  const candidates = [
+    () => process.env.SPECWEAVE_HOME,
+    () => path.resolve(pluginRoot(), '..', '..'),
+    ...[process.env.CLAUDE_PROJECT_DIR, process.cwd()].filter(Boolean).flatMap((dir) => [
+      () => path.dirname(createRequire(path.join(dir, 'package.json')).resolve('specweave/package.json')),
+      () => path.join(dir, 'node_modules', 'specweave'),
+    ]),
+    fromCache,
+    fromNpmGlobal,
+  ];
+  for (const candidate of candidates) {
+    try {
+      const dir = candidate();
+      if (isCliRoot(dir)) return dir;
+    } catch {
+      // try the next strategy
+    }
+  }
+  return null;
+}
+
+async function main() {
+  if (!EVENTS.has(event)) {
+    await readStdin();
+    return emit({});
+  }
+  const { raw, skip } = normalizeInput(await readStdin());
+  if (skip) return emit({});
+  const cliRoot = resolveCliRoot();
+  if (!cliRoot) return emit(inactiveOutput());
+  try {
+    const mod = await import(pathToFileURL(path.join(cliRoot, ROUTER_REL)).href);
+    const result = await mod.hookRouter(event, raw);
+    return emit(result);
+  } catch {
+    return emit(inactiveOutput());
+  }
+}
+
+process.on('uncaughtException', () => emit(inactiveOutput()));
+process.on('unhandledRejection', () => emit(inactiveOutput()));
+main().catch(() => emit(inactiveOutput()));

package/plugins/specweave/hooks/run.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+// SpecWeave hook supervisor: parent deadline remains live while the worker blocks in Git.
+import { spawn, spawnSync } from 'node:child_process';
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+const event = process.argv[2];
+const worker = path.join(path.dirname(fileURLToPath(import.meta.url)), 'run-worker.mjs');
+const budget = event === 'stop' ? 25000 : 7500;
+let child, finished = false, input = '', output = '', size = 0;
+const started = Date.now();
+function record(reason) {
+  try {
+    const dir = path.join(homedir(), '.specweave', 'logs');
+    mkdirSync(dir, {recursive:true, mode:0o700});
+    appendFileSync(path.join(dir, 'hook-health.jsonl'), JSON.stringify({at:new Date().toISOString(),event,reason,elapsedMs:Date.now()-started})+'\n', {mode:0o600});
+  } catch {}
+}
+function killWorker() {
+  if (!child?.pid) return;
+  if (process.platform === 'win32') {
+    spawnSync('taskkill', ['/pid', String(child.pid), '/T', '/F'], {timeout:1000, windowsHide:true, stdio:'ignore'});
+  } else {
+    try { process.kill(-child.pid, 'SIGKILL'); } catch { try {child.kill('SIGKILL');} catch {} }
+  }
+}
+function finish(result = {}, reason) {
+  if (finished) return;
+  finished = true;
+  clearTimeout(deadline);
+  killWorker();
+  if (reason) record(reason);
+  process.stdout.write(JSON.stringify(result)+'\n',()=>process.exit(0));
+}
+const deadline = setTimeout(()=>finish({},'deadline_exceeded'),budget);
+process.on('SIGTERM',()=>finish({},'terminated'));
+process.on('SIGINT',()=>finish({},'interrupted'));
+process.on('uncaughtException',()=>finish({},'adapter_error'));
+process.stdin.setEncoding('utf8');
+process.stdin.on('data',chunk=>{
+  size += Buffer.byteLength(chunk, 'utf8');
+  if(size>1024*1024) return finish({},'input_limit');
+  input+=chunk;
+});
+process.stdin.on('error',()=>finish({},'stdin_error'));
+process.stdin.on('end',()=>{
+  let data;
+  try {data=JSON.parse(input);if(!data || typeof data!=='object'||Array.isArray(data))throw Error();}
+  catch {return finish({},'invalid_input');}
+  if(!['session-start','pre-tool-use','pre-compact','stop'].includes(event))return finish({});
+  const env={...process.env};
+  child=spawn(process.execPath,[worker,event],{env,detached:process.platform !== 'win32',stdio:['pipe','pipe','pipe']});
+  child.stdout.setEncoding('utf8');
+  child.stdout.on('data',chunk=>{
+    output+=chunk;
+    if(output.length>1024*1024)finish({},'output_limit');
+  });
+  child.stderr.resume();
+  child.stdin.on('error',()=>{});
+  child.on('error',()=>finish({},'worker_spawn_failed'));
+  child.on('close',code=>{
+    if(finished)return;
+    if(code!==0)return finish({},'worker_failed');
+    try {
+      const result=JSON.parse(output);
+      if(!result||typeof result!=='object'||Array.isArray(result))throw Error();
+      finish(result);
+    } catch {finish({},'invalid_worker_output');}
+  });
+  child.stdin.end(input);
+});

package/plugins/specweave/lib/external-sync/README.md

@@ -19,7 +19,6 @@ This directory contains extracted boilerplate code that is 80-100% identical acr
 
 | File | Purpose | Used By |
 |------|---------|---------|
-| `hooks-common.sh` | Shared bash functions | All post-task-completion hooks |
 
 ## Usage
 
@@ -65,7 +64,7 @@ class GitHubDuplicateDetector extends DuplicateDetectorBase<GitHubIssue> {
 #!/bin/bash
 # Source shared utilities
 SCRIPT_DIR="$(dirname "$0")"
-source "$SCRIPT_DIR/../../specweave/lib/external-sync/hooks-common.sh"
+# (2.0) shell hook helpers were removed; call the Node modules in this directory directly
 
 # Use shared functions
 PROJECT_ROOT=$(find_project_root)
@@ -107,7 +106,7 @@ When adding support for a new PM tool (e.g., Linear, Notion):
 
 1. Create plugin: `plugins/specweave-{tool}/`
 2. Extend `DuplicateDetectorBase` for the tool
-3. Source `hooks-common.sh` in your hooks
+3. Import the Node modules in this directory (no shell helpers in 2.0)
 4. Use `checkSyncPermissions()` in commands
 5. Implement tool-specific API client
 

package/plugins/specweave/lib/integrations/github/github-access-error.js

@@ -8,11 +8,11 @@ function explainGitHubAccessError(rawError, facts) {
   if (!isLikelyAccessError(rawError)) return null;
   const { login, canPush, owner, repo } = facts;
   if (canPush === true) return null;
-  const who = login ? `The GitHub token in .env belongs to account '${login}', which has no write access to ${owner}/${repo}.` : `The GitHub token in .env is invalid or expired \u2014 its account could not be resolved.`;
+  const who = login ? `The GitHub token belongs to account '${login}', which has no write access to ${owner}/${repo}.` : `The GitHub token is invalid or expired \u2014 its account could not be resolved.`;
   return [
     who,
     `GitHub returns 404 (not 403) when a token's account cannot see a repo, which is why this looked like "Not Found".`,
-    `Fix: point GITHUB_TOKEN / GH_TOKEN in .env at a token whose account can write ${owner}/${repo}, or run \`gh auth login\` with the right account.`,
+    `Fix: point GITHUB_TOKEN / GH_TOKEN (config, shell env or .env \u2014 resolved in that order) at a token whose account can write ${owner}/${repo}, or run \`gh auth login\` with the right account. Run \`specweave sync status\` to see which token is active.`,
     `Original error: ${rawError.trim()}`
   ].join("\n");
 }

package/plugins/specweave/lib/integrations/github/github-access-error.ts

@@ -56,13 +56,13 @@ export function explainGitHubAccessError(
   if (canPush === true) return null;
 
   const who = login
-    ? `The GitHub token in .env belongs to account '${login}', which has no write access to ${owner}/${repo}.`
-    : `The GitHub token in .env is invalid or expired — its account could not be resolved.`;
+    ? `The GitHub token belongs to account '${login}', which has no write access to ${owner}/${repo}.`
+    : `The GitHub token is invalid or expired — its account could not be resolved.`;
 
   return [
     who,
     `GitHub returns 404 (not 403) when a token's account cannot see a repo, which is why this looked like "Not Found".`,
-    `Fix: point GITHUB_TOKEN / GH_TOKEN in .env at a token whose account can write ${owner}/${repo}, or run \`gh auth login\` with the right account.`,
+    `Fix: point GITHUB_TOKEN / GH_TOKEN (config, shell env or .env — resolved in that order) at a token whose account can write ${owner}/${repo}, or run \`gh auth login\` with the right account. Run \`specweave sync status\` to see which token is active.`,
     `Original error: ${rawError.trim()}`,
   ].join('\n');
 }

package/plugins/specweave/lib/integrations/github/github-client-v2.js

@@ -31,13 +31,14 @@ const _GitHubClientV2 = class _GitHubClientV2 {
     return this.token ? { ...process.env, GH_TOKEN: this.token } : process.env;
   }
   /**
-   * Turn a failed `gh` create result into a clear error.
+   * Turn a failed `gh` write (create/edit/close/comment/label) into a clear error.
    *
    * When the failure looks like an auth/access problem (notably a 404 masking a
-   * wrong-account token in .env), resolve the token's account + write access and
-   * explain exactly what to fix; otherwise fall back to the raw gh error.
+   * wrong-account token), resolve the token's account + write access and
+   * explain exactly what to fix ("token has no write access to owner/repo");
+   * otherwise fall back to the raw gh error.
    */
-  async buildCreateError(action, rawError) {
+  async buildWriteError(action, rawError) {
     try {
       const facts = await resolveGitHubAccessFacts(
         execFileNoThrow,
@@ -175,7 +176,7 @@ const _GitHubClientV2 = class _GitHubClientV2 {
     }
     const result = await this.execWithBudget("gh", args, { env: this.getGhEnv() });
     if (result.exitCode !== 0) {
-      throw await this.buildCreateError("create milestone", result.stderr || result.stdout);
+      throw await this.buildWriteError("create milestone", result.stderr || result.stdout);
     }
     return JSON.parse(result.stdout);
   }
@@ -224,7 +225,7 @@ GitHub issues MUST use living docs format:
 WHY: Correct data flow is: Increment \u2192 Living Docs \u2192 GitHub
       Living docs are the source of truth for GitHub sync.
 
-FIX: Use sw:sync-docs to generate living docs, then sync to GitHub.`
+FIX: Run 'specweave docs sync <id>' to generate living docs, then sync to GitHub.`
       );
     }
     const plainIncrementPattern = /^\[\d{3,4}E?\]\s/;
@@ -346,7 +347,7 @@ FIX:
     }
     const createResult = await this.execWithBudget("gh", args, { env: this.getGhEnv() });
     if (createResult.exitCode !== 0) {
-      throw await this.buildCreateError("create issue", createResult.stderr || createResult.stdout);
+      throw await this.buildWriteError("create issue", createResult.stderr || createResult.stdout);
     }
     const issueUrl = createResult.stdout.trim();
     const issueNumber = parseInt(issueUrl.split("/").pop() || "0", 10);
@@ -383,9 +384,7 @@ ${body}`;
       "number,title,body,state,url,labels,milestone"
     ], { env: this.getGhEnv() });
     if (result.exitCode !== 0) {
-      throw new Error(
-        `Failed to get issue #${issueNumber}: ${result.stderr || result.stdout}`
-      );
+      throw new Error(`Failed to get issue #${issueNumber}: ${result.stderr || result.stdout}`);
     }
     const issue = JSON.parse(result.stdout);
     const normalized = {
@@ -460,9 +459,7 @@ ${body}`;
       newBody
     ], { env: this.getGhEnv() });
     if (result.exitCode !== 0) {
-      throw new Error(
-        `Failed to edit issue #${issueNumber}: ${result.stderr || result.stdout}`
-      );
+      throw await this.buildWriteError(`edit issue #${issueNumber}`, result.stderr || result.stdout);
     }
   }
   /**
@@ -479,9 +476,7 @@ ${body}`;
       newBody
     ], { env: this.getGhEnv() });
     if (result.exitCode !== 0) {
-      throw new Error(
-        `Failed to update issue #${issueNumber}: ${result.stderr || result.stdout}`
-      );
+      throw await this.buildWriteError(`update issue #${issueNumber}`, result.stderr || result.stdout);
     }
   }
   /**
@@ -499,9 +494,7 @@ ${body}`;
       this.fullRepo
     ], { env: this.getGhEnv() });
     if (result.exitCode !== 0) {
-      throw new Error(
-        `Failed to close issue #${issueNumber}: ${result.stderr || result.stdout}`
-      );
+      throw await this.buildWriteError(`close issue #${issueNumber}`, result.stderr || result.stdout);
     }
   }
   /**
@@ -522,9 +515,7 @@ ${body}`;
       this.fullRepo
     ], { env: this.getGhEnv() });
     if (result.exitCode !== 0) {
-      throw new Error(
-        `Failed to reopen issue #${issueNumber}: ${result.stderr || result.stdout}`
-      );
+      throw await this.buildWriteError(`reopen issue #${issueNumber}`, result.stderr || result.stdout);
     }
   }
   /**
@@ -541,9 +532,7 @@ ${body}`;
       comment
     ], { env: this.getGhEnv() });
     if (result.exitCode !== 0) {
-      throw new Error(
-        `Failed to add comment to issue #${issueNumber}: ${result.stderr || result.stdout}`
-      );
+      throw await this.buildWriteError(`add comment to issue #${issueNumber}`, result.stderr || result.stdout);
     }
   }
   /**
@@ -635,9 +624,7 @@ ${body}`;
     }
     const result = await this.execWithBudget("gh", args, { env: this.getGhEnv() });
     if (result.exitCode !== 0) {
-      throw new Error(
-        `Failed to add labels to issue #${issueNumber}: ${result.stderr || result.stdout}`
-      );
+      throw await this.buildWriteError(`add labels to issue #${issueNumber}`, result.stderr || result.stdout);
     }
   }
   /**
@@ -729,9 +716,7 @@ ${body}`;
       // Max results
     ], { env: this.getGhEnv() });
     if (result.exitCode !== 0) {
-      throw new Error(
-        `Failed to list issues: ${result.stderr || result.stdout}`
-      );
+      throw new Error(`Failed to list issues: ${result.stderr || result.stdout}`);
     }
     const issues = JSON.parse(result.stdout);
     return issues.map((issue) => ({
@@ -797,9 +782,7 @@ ${body}`;
       ".rate | {remaining: .remaining, limit: .limit, reset: .reset}"
     ], { env: this.getGhEnv() });
     if (result.exitCode !== 0) {
-      throw new Error(
-        `Failed to check rate limit: ${result.stderr || result.stdout}`
-      );
+      throw new Error(`Failed to check rate limit: ${result.stderr || result.stdout}`);
     }
     const data = JSON.parse(result.stdout);
     return {
@@ -888,9 +871,7 @@ ${body}`;
       jqFilter
     ], { env: this.getGhEnv() });
     if (result.exitCode !== 0) {
-      throw new Error(
-        `Failed to fetch recent changes: ${result.stderr || result.stdout}`
-      );
+      throw new Error(`Failed to fetch recent changes: ${result.stderr || result.stdout}`);
     }
     const lines = result.stdout.trim().split("\n").filter((l) => l.trim());
     const issues = [];
@@ -936,9 +917,7 @@ ${body}`;
       ".[].{event, created_at, actor: .actor.login}"
     ], { env: this.getGhEnv() });
     if (result.exitCode !== 0) {
-      throw new Error(
-        `Failed to get issue events: ${result.stderr || result.stdout}`
-      );
+      throw new Error(`Failed to get issue events: ${result.stderr || result.stdout}`);
     }
     const lines = result.stdout.trim().split("\n").filter((l) => l.trim());
     const events = [];

package/plugins/specweave/lib/integrations/github/github-client-v2.ts

@@ -60,13 +60,14 @@ export class GitHubClientV2 {
   }
 
   /**
-   * Turn a failed `gh` create result into a clear error.
+   * Turn a failed `gh` write (create/edit/close/comment/label) into a clear error.
    *
    * When the failure looks like an auth/access problem (notably a 404 masking a
-   * wrong-account token in .env), resolve the token's account + write access and
-   * explain exactly what to fix; otherwise fall back to the raw gh error.
+   * wrong-account token), resolve the token's account + write access and
+   * explain exactly what to fix ("token has no write access to owner/repo");
+   * otherwise fall back to the raw gh error.
    */
-  private async buildCreateError(action: string, rawError: string): Promise<Error> {
+  private async buildWriteError(action: string, rawError: string): Promise<Error> {
     try {
       const facts = await resolveGitHubAccessFacts(
         execFileNoThrow,
@@ -245,7 +246,7 @@ export class GitHubClientV2 {
     const result = await this.execWithBudget('gh', args, { env: this.getGhEnv() });
 
     if (result.exitCode !== 0) {
-      throw await this.buildCreateError('create milestone', result.stderr || result.stdout);
+      throw await this.buildWriteError('create milestone', result.stderr || result.stdout);
     }
 
     return JSON.parse(result.stdout);
@@ -300,7 +301,7 @@ export class GitHubClientV2 {
         `  ❌ WRONG: "[Increment XXXX] Title" (old format)\n\n` +
         `WHY: Correct data flow is: Increment → Living Docs → GitHub\n` +
         `      Living docs are the source of truth for GitHub sync.\n\n` +
-        `FIX: Use sw:sync-docs to generate living docs, then sync to GitHub.`
+        `FIX: Run 'specweave docs sync <id>' to generate living docs, then sync to GitHub.`
       );
     }
 
@@ -459,7 +460,7 @@ export class GitHubClientV2 {
     const createResult = await this.execWithBudget('gh', args, { env: this.getGhEnv() });
 
     if (createResult.exitCode !== 0) {
-      throw await this.buildCreateError('create issue', createResult.stderr || createResult.stdout);
+      throw await this.buildWriteError('create issue', createResult.stderr || createResult.stdout);
     }
 
     const issueUrl = createResult.stdout.trim();
@@ -511,9 +512,7 @@ export class GitHubClientV2 {
     ], { env: this.getGhEnv() });
 
     if (result.exitCode !== 0) {
-      throw new Error(
-        `Failed to get issue #${issueNumber}: ${result.stderr || result.stdout}`
-      );
+      throw new Error(`Failed to get issue #${issueNumber}: ${result.stderr || result.stdout}`);
     }
 
     const issue = JSON.parse(result.stdout);
@@ -605,9 +604,7 @@ export class GitHubClientV2 {
     ], { env: this.getGhEnv() });
 
     if (result.exitCode !== 0) {
-      throw new Error(
-        `Failed to edit issue #${issueNumber}: ${result.stderr || result.stdout}`
-      );
+      throw await this.buildWriteError(`edit issue #${issueNumber}`, result.stderr || result.stdout);
     }
   }
 
@@ -626,9 +623,7 @@ export class GitHubClientV2 {
     ], { env: this.getGhEnv() });
 
     if (result.exitCode !== 0) {
-      throw new Error(
-        `Failed to update issue #${issueNumber}: ${result.stderr || result.stdout}`
-      );
+      throw await this.buildWriteError(`update issue #${issueNumber}`, result.stderr || result.stdout);
     }
   }
 
@@ -649,9 +644,7 @@ export class GitHubClientV2 {
     ], { env: this.getGhEnv() });
 
     if (result.exitCode !== 0) {
-      throw new Error(
-        `Failed to close issue #${issueNumber}: ${result.stderr || result.stdout}`
-      );
+      throw await this.buildWriteError(`close issue #${issueNumber}`, result.stderr || result.stdout);
     }
   }
 
@@ -675,9 +668,7 @@ export class GitHubClientV2 {
     ], { env: this.getGhEnv() });
 
     if (result.exitCode !== 0) {
-      throw new Error(
-        `Failed to reopen issue #${issueNumber}: ${result.stderr || result.stdout}`
-      );
+      throw await this.buildWriteError(`reopen issue #${issueNumber}`, result.stderr || result.stdout);
     }
   }
 
@@ -696,9 +687,7 @@ export class GitHubClientV2 {
     ], { env: this.getGhEnv() });
 
     if (result.exitCode !== 0) {
-      throw new Error(
-        `Failed to add comment to issue #${issueNumber}: ${result.stderr || result.stdout}`
-      );
+      throw await this.buildWriteError(`add comment to issue #${issueNumber}`, result.stderr || result.stdout);
     }
   }
 
@@ -813,9 +802,7 @@ export class GitHubClientV2 {
     const result = await this.execWithBudget('gh', args, { env: this.getGhEnv() });
 
     if (result.exitCode !== 0) {
-      throw new Error(
-        `Failed to add labels to issue #${issueNumber}: ${result.stderr || result.stdout}`
-      );
+      throw await this.buildWriteError(`add labels to issue #${issueNumber}`, result.stderr || result.stdout);
     }
   }
 
@@ -928,9 +915,7 @@ export class GitHubClientV2 {
     ], { env: this.getGhEnv() });
 
     if (result.exitCode !== 0) {
-      throw new Error(
-        `Failed to list issues: ${result.stderr || result.stdout}`
-      );
+      throw new Error(`Failed to list issues: ${result.stderr || result.stdout}`);
     }
 
     const issues = JSON.parse(result.stdout);
@@ -1014,9 +999,7 @@ export class GitHubClientV2 {
     ], { env: this.getGhEnv() });
 
     if (result.exitCode !== 0) {
-      throw new Error(
-        `Failed to check rate limit: ${result.stderr || result.stdout}`
-      );
+      throw new Error(`Failed to check rate limit: ${result.stderr || result.stdout}`);
     }
 
     const data = JSON.parse(result.stdout);
@@ -1129,9 +1112,7 @@ export class GitHubClientV2 {
     ], { env: this.getGhEnv() });
 
     if (result.exitCode !== 0) {
-      throw new Error(
-        `Failed to fetch recent changes: ${result.stderr || result.stdout}`
-      );
+      throw new Error(`Failed to fetch recent changes: ${result.stderr || result.stdout}`);
     }
 
     // Parse NDJSON output (one JSON object per line)
@@ -1183,9 +1164,7 @@ export class GitHubClientV2 {
     ], { env: this.getGhEnv() });
 
     if (result.exitCode !== 0) {
-      throw new Error(
-        `Failed to get issue events: ${result.stderr || result.stdout}`
-      );
+      throw new Error(`Failed to get issue events: ${result.stderr || result.stdout}`);
     }
 
     // Parse NDJSON output