@cyanautomation/kaseki-agent 1.15.0 → 1.16.0

package/dist/github-operations-monitor.d.ts

@@ -0,0 +1,37 @@
+/**
+ * github-operations-monitor.ts
+ *
+ * Monitoring module for analyzing kaseki github operations failures.
+ * Provides functions to detect, classify, and analyze github operations stage failures.
+ */
+interface DiagnosticResult {
+    hasFailed: boolean;
+    failureType: string;
+    description: string;
+    exitCode: number;
+    stage: string;
+    apiError?: {
+        type: string;
+        message: string;
+        httpStatus: string;
+    };
+    logs: {
+        gitPushLogTail?: string[];
+        lastCommandLog?: string[];
+        healthCheckLog?: string[];
+    };
+}
+/**
+ * Detect if kaseki run had a github operations failure
+ */
+export declare function isGithubOperationFailure(metadataPath: string): boolean;
+/**
+ * Analyze a kaseki run for github operations failures
+ */
+export declare function analyzeGithubOperations(resultsDir: string): DiagnosticResult;
+/**
+ * Format diagnostic result as human-readable markdown
+ */
+export declare function formatDiagnosticResult(result: DiagnosticResult): string;
+export {};
+//# sourceMappingURL=github-operations-monitor.d.ts.map

package/dist/github-operations-monitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-operations-monitor.d.ts","sourceRoot":"","sources":["../src/github-operations-monitor.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAeH,UAAU,gBAAgB;IACxB,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE;QACT,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;IACF,IAAI,EAAE;QACJ,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;QAC1B,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;QAC1B,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;KAC3B,CAAC;CACH;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAQtE;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,MAAM,GAAG,gBAAgB,CAoG5E;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAoCvE"}

package/dist/github-operations-monitor.js

@@ -0,0 +1,162 @@
+/**
+ * github-operations-monitor.ts
+ *
+ * Monitoring module for analyzing kaseki github operations failures.
+ * Provides functions to detect, classify, and analyze github operations stage failures.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+/**
+ * Detect if kaseki run had a github operations failure
+ */
+export function isGithubOperationFailure(metadataPath) {
+    try {
+        const content = fs.readFileSync(metadataPath, 'utf8');
+        const metadata = JSON.parse(content);
+        return metadata.current_stage === 'github operations' && (metadata.exit_code ?? 0) !== 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Analyze a kaseki run for github operations failures
+ */
+export function analyzeGithubOperations(resultsDir) {
+    const metadataPath = path.join(resultsDir, 'metadata.json');
+    const failurePath = path.join(resultsDir, 'failure.json');
+    const gitPushLogPath = path.join(resultsDir, 'git-push.log');
+    const lastCommandLogPath = path.join(resultsDir, 'last-command.log');
+    const healthCheckLogPath = path.join(resultsDir, 'github-health-check.log');
+    const result = {
+        hasFailed: false,
+        failureType: 'unknown',
+        description: 'No failure detected',
+        exitCode: 0,
+        stage: 'unknown',
+        logs: {},
+    };
+    // Read metadata
+    let metadata = {};
+    try {
+        const content = fs.readFileSync(metadataPath, 'utf8');
+        metadata = JSON.parse(content);
+    }
+    catch (e) {
+        result.description = `Failed to read metadata: ${e}`;
+        return result;
+    }
+    // Read failure.json for additional context
+    try {
+        if (fs.existsSync(failurePath)) {
+            const content = fs.readFileSync(failurePath, 'utf8');
+            JSON.parse(content); // Validate JSON format
+        }
+    }
+    catch (e) {
+        // Failure.json might not exist if success
+    }
+    result.stage = metadata.current_stage ?? 'unknown';
+    result.exitCode = metadata.exit_code ?? 0;
+    // Classify failure
+    if (metadata.current_stage !== 'github operations') {
+        result.hasFailed = false;
+        result.description = `Failure occurred in stage '${metadata.current_stage}', not github operations`;
+        return result;
+    }
+    if (result.exitCode === 0) {
+        result.hasFailed = false;
+        result.description = 'GitHub operations completed successfully';
+        return result;
+    }
+    result.hasFailed = true;
+    // Determine failure type
+    const pushExit = metadata.github_push_exit_code ?? 0;
+    const prExit = metadata.github_pr_exit_code ?? 0;
+    if (pushExit !== 0 && prExit === 0) {
+        result.failureType = 'git_push_failed';
+        result.description = `Git push failed with exit code ${pushExit}`;
+    }
+    else if (prExit !== 0) {
+        result.failureType = 'pr_creation_failed';
+        result.description = `GitHub PR creation failed with exit code ${prExit}`;
+        // Include API error details
+        if (metadata.github_api_error_type || metadata.github_api_error_message) {
+            result.apiError = {
+                type: metadata.github_api_error_type ?? 'unknown',
+                message: metadata.github_api_error_message ?? '',
+                httpStatus: metadata.github_api_http_status ?? '',
+            };
+            result.description += ` (${result.apiError.type}: ${result.apiError.message})`;
+        }
+    }
+    else if (pushExit === 0 && prExit === 0) {
+        result.failureType = 'post_github_ops_failure';
+        result.description =
+            'GitHub operations succeeded but overall exit code is non-zero (failure in cleanup/trap)';
+    }
+    else {
+        result.failureType = 'unknown_failure_pattern';
+        result.description = `Unknown failure pattern: push_exit=${pushExit}, pr_exit=${prExit}, overall_exit=${result.exitCode}`;
+    }
+    // Collect logs
+    if (fs.existsSync(gitPushLogPath)) {
+        const content = fs.readFileSync(gitPushLogPath, 'utf8');
+        result.logs.gitPushLogTail = content.split('\n').slice(-30).filter((l) => l.trim());
+    }
+    if (fs.existsSync(lastCommandLogPath)) {
+        const content = fs.readFileSync(lastCommandLogPath, 'utf8');
+        result.logs.lastCommandLog = content.split('\n').filter((l) => l.trim());
+    }
+    if (fs.existsSync(healthCheckLogPath)) {
+        const content = fs.readFileSync(healthCheckLogPath, 'utf8');
+        result.logs.healthCheckLog = content.split('\n').filter((l) => l.trim());
+    }
+    return result;
+}
+/**
+ * Format diagnostic result as human-readable markdown
+ */
+export function formatDiagnosticResult(result) {
+    let output = '# GitHub Operations Diagnostic\n\n';
+    output += `**Stage:** ${result.stage}\n`;
+    output += `**Exit code:** ${result.exitCode}\n`;
+    output += `**Failure detected:** ${result.hasFailed ? 'Yes' : 'No'}\n`;
+    output += `**Failure type:** ${result.failureType}\n\n`;
+    output += `## Summary\n\n${result.description}\n\n`;
+    if (result.apiError) {
+        output += '## API Error Details\n\n';
+        output += `- **Type:** ${result.apiError.type}\n`;
+        output += `- **Message:** ${result.apiError.message}\n`;
+        output += `- **HTTP Status:** ${result.apiError.httpStatus}\n\n`;
+    }
+    if (result.logs.gitPushLogTail && result.logs.gitPushLogTail.length > 0) {
+        output += '## Git Push Log (last 30 lines)\n\n```\n';
+        output += result.logs.gitPushLogTail.join('\n');
+        output += '\n```\n\n';
+    }
+    if (result.logs.lastCommandLog && result.logs.lastCommandLog.length > 0) {
+        output += '## Last Command Log\n\n```\n';
+        output += result.logs.lastCommandLog.join('\n');
+        output += '\n```\n\n';
+    }
+    if (result.logs.healthCheckLog && result.logs.healthCheckLog.length > 0) {
+        output += '## Health Check Log\n\n```\n';
+        output += result.logs.healthCheckLog.join('\n');
+        output += '\n```\n\n';
+    }
+    return output;
+}
+// CLI usage
+if (require.main === module) {
+    const resultsDir = process.argv[2];
+    if (!resultsDir) {
+        console.error('Usage: npx ts-node github-operations-monitor.ts <results-directory>');
+        process.exit(1);
+    }
+    const result = analyzeGithubOperations(resultsDir);
+    const formatted = formatDiagnosticResult(result);
+    console.log(formatted);
+    process.exit(result.hasFailed && result.failureType === 'post_github_ops_failure' ? 1 : 0);
+}
+//# sourceMappingURL=github-operations-monitor.js.map

package/dist/github-operations-monitor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-operations-monitor.js","sourceRoot":"","sources":["../src/github-operations-monitor.ts"],"names":[],"mappings":"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"}

package/kaseki-agent.sh

@@ -28,7 +28,7 @@ KASEKI_AGENT_GUARDRAILS="${KASEKI_AGENT_GUARDRAILS:-1}"
 KASEKI_RESTORE_DISALLOWED_CHANGES="${KASEKI_RESTORE_DISALLOWED_CHANGES:-1}"
 KASEKI_VALIDATION_FAIL_FAST="${KASEKI_VALIDATION_FAIL_FAST:-1}"
 KASEKI_STRICT_SCRIPT_CHECK="${KASEKI_STRICT_SCRIPT_CHECK:-0}"
-GITHUB_APP_ENABLED="${GITHUB_APP_ENABLED:-0}"
+GITHUB_APP_ENABLED="${GITHUB_APP_ENABLED:-1}"
 KASEKI_PUBLISH_MODE="${KASEKI_PUBLISH_MODE:-auto}"
 KASEKI_GITHUB_PR_RETRIES="${KASEKI_GITHUB_PR_RETRIES:-3}"
 START_EPOCH="$(date +%s)"
@@ -84,6 +84,10 @@ REPO_MEMORY_FILE=""
 REPO_MEMORY_STATUS="disabled"
 REPO_MEMORY_COMMIT_SHA="unknown"
 
+# Track last executed command for better error reporting
+LAST_COMMAND=""
+LAST_COMMAND_LOG="/results/last-command.log"
+
 # Signal handler for graceful termination
 handle_termination() {
   local signal="$1"
@@ -99,6 +103,9 @@ handle_termination() {
 trap 'handle_termination SIGTERM' SIGTERM
 trap 'handle_termination SIGINT' SIGINT
 
+# DEBUG trap: capture last command before execution for better error diagnostics
+trap 'LAST_COMMAND="$BASH_COMMAND"' DEBUG
+
 setup_host_logging_mirror() {
   local base_name="$1"
   local stamp host_log_file
@@ -160,6 +167,55 @@ case "$KASEKI_GIT_CACHE_MODE" in
     ;;
 esac
 
+# Helper function to run Node.js subprocesses with comprehensive error logging
+# Usage: run_node_subprocess <output_var_name> "<node_code>" [<input_data>] [<error_log_file>]
+# Captures stderr, logs errors, and returns exit code for caller to check
+run_node_subprocess() {
+  local output_var_name="$1"
+  local node_code="$2"
+  local input_data="${3:-}"
+  local error_log_file="${4:-/tmp/node-error.log}"
+  local node_stderr_tmp node_exit_code output_value
+  
+  node_stderr_tmp="$(mktemp /tmp/node-stderr.XXXXXX)" || {
+    printf 'ERROR: Failed to create temp file for Node.js stderr\n' >&2
+    eval "$output_var_name=''"
+    return 1
+  }
+  
+  # Run Node.js and capture both stdout and stderr
+  if [ -n "$input_data" ]; then
+    output_value=$(printf '%s' "$input_data" | node -e "$node_code" 2>"$node_stderr_tmp")
+  else
+    output_value=$(node -e "$node_code" 2>"$node_stderr_tmp")
+  fi
+  node_exit_code=$?
+  
+  # Handle errors
+  if [ $node_exit_code -ne 0 ]; then
+    local stderr_content
+    stderr_content="$(cat "$node_stderr_tmp" 2>/dev/null || echo '<unable to read stderr>')"
+    {
+      printf '[node-subprocess-error] Command failed with exit code %d\n' "$node_exit_code"
+      if [ -n "$stderr_content" ]; then
+        printf '[node-subprocess-error] stderr: %s\n' "$stderr_content"
+      fi
+      printf '[node-subprocess-error] code: %.200s\n' "$node_code"
+      if [ -n "$input_data" ]; then
+        printf '[node-subprocess-error] input (first 150 chars): %.150s\n' "$input_data"
+      fi
+    } | tee -a "$error_log_file" >&2
+    rm -f "$node_stderr_tmp"
+    eval "$output_var_name=''"
+    return "$node_exit_code"
+  fi
+  
+  # Success: store output in variable and return 0
+  eval "$output_var_name='$output_value'"
+  rm -f "$node_stderr_tmp"
+  return 0
+}
+
 # Safely encode value as JSON string; fallback to empty string if node unavailable
 json_encode() {
   if ! command -v node &>/dev/null; then
@@ -712,8 +768,20 @@ check_secret_scan_allowlist() {
 finish() {
   local code=$?
   if [ "$code" -ne 0 ] && [ "$STATUS" -eq 0 ]; then
+    # Capture diagnostic context for the catch-all error
     STATUS="$code"
     FAILED_COMMAND="unexpected shell failure"
+    # Log the last command that was executed
+    {
+      printf '[unexpected-failure] Exit code: %d\n' "$code"
+      printf '[unexpected-failure] Last command: %s\n' "$LAST_COMMAND"
+      printf '[unexpected-failure] Current stage: %s\n' "$CURRENT_STAGE"
+      if [ -f /results/progress.log ]; then
+        printf '[unexpected-failure] Last 5 progress entries:\n'
+        tail -5 /results/progress.log | sed 's/^/  /'
+      fi
+    } | tee -a "$LAST_COMMAND_LOG" >&2
+    emit_error_event "unexpected_shell_failure" "Uncaught shell error (exit $code) in stage '$CURRENT_STAGE'. Last command: $LAST_COMMAND. See $LAST_COMMAND_LOG for context." "exit"
   fi
   # Authoritative call site: this runs at EXIT so artifacts reflect final repo state.
   collect_git_artifacts
@@ -1266,6 +1334,73 @@ $memory_section
 EOF
 }
 
+check_github_operations_health() {
+  # Preflight health check for github operations before pi agent runs
+  # Tests: GitHub App secrets, git config, Node.js token generation capability
+  local health_log="/results/github-health-check.log"
+  : > "$health_log"
+  
+  printf '[preflight] github operations health check started\n' | tee -a "$health_log"
+  
+  # Check 1: GitHub App secrets are readable
+  if ! [ -r /run/secrets/github_app_id ]; then
+    printf '[health-check] ERROR: Cannot read GitHub App ID from /run/secrets/github_app_id\n' | tee -a "$health_log" >&2
+    return 1
+  fi
+  if ! [ -r /run/secrets/github_app_client_id ]; then
+    printf '[health-check] ERROR: Cannot read GitHub App client ID from /run/secrets/github_app_client_id\n' | tee -a "$health_log" >&2
+    return 1
+  fi
+  if ! [ -r /run/secrets/github_app_private_key ]; then
+    printf '[health-check] ERROR: Cannot read GitHub App private key from /run/secrets/github_app_private_key\n' | tee -a "$health_log" >&2
+    return 1
+  fi
+  printf '[health-check] ✓ GitHub App secrets are readable\n' | tee -a "$health_log"
+  
+  # Check 2: Verify git is available
+  if ! git --version >/dev/null 2>&1; then
+    printf '[health-check] ERROR: git command is not available\n' | tee -a "$health_log" >&2
+    return 1
+  fi
+  printf '[health-check] ✓ git is available\n' | tee -a "$health_log"
+  
+  # Check 3: Test Node.js github-app-token helper script exists
+  if ! [ -x /usr/local/bin/github-app-token ]; then
+    printf '[health-check] ERROR: github-app-token helper not found at /usr/local/bin/github-app-token\n' | tee -a "$health_log" >&2
+    return 1
+  fi
+  printf '[health-check] ✓ github-app-token helper is available\n' | tee -a "$health_log"
+  
+  # Check 4: Test Node.js is available
+  if ! command -v node >/dev/null 2>&1; then
+    printf '[health-check] ERROR: Node.js is not available\n' | tee -a "$health_log" >&2
+    return 1
+  fi
+  printf '[health-check] ✓ Node.js is available\n' | tee -a "$health_log"
+  
+  # Check 5: Test Node.js JSON parsing
+  local test_output
+  test_output=$(printf '{"test":"value"}' | node -e "const d = JSON.parse(require('fs').readFileSync(0, 'utf8')); process.stdout.write(d.test);" 2>&1) || {
+    printf '[health-check] ERROR: Node.js JSON parsing failed: %s\n' "$test_output" | tee -a "$health_log" >&2
+    return 1
+  }
+  if [ "$test_output" != "value" ]; then
+    printf '[health-check] ERROR: Node.js JSON parsing returned unexpected output: %s\n' "$test_output" | tee -a "$health_log" >&2
+    return 1
+  fi
+  printf '[health-check] ✓ Node.js JSON parsing works\n' | tee -a "$health_log"
+  
+  # Check 6: Test curl is available
+  if ! command -v curl >/dev/null 2>&1; then
+    printf '[health-check] ERROR: curl is not available\n' | tee -a "$health_log" >&2
+    return 1
+  fi
+  printf '[health-check] ✓ curl is available\n' | tee -a "$health_log"
+  
+  printf '[preflight] github operations health check PASSED\n' | tee -a "$health_log"
+  return 0
+}
+
 validate_github_api_response() {
   local http_status response log_file error_type error_message
   http_status="$1"
@@ -1393,13 +1528,19 @@ run_github_operations() {
     return 7
   }
   
-  token="$(printf '%s' "$token_data" | node -e "const d = JSON.parse(require('fs').readFileSync(0, 'utf8')); process.stdout.write(d.token || '')" 2>/dev/null)"
-  if [ -z "$token" ]; then
+  # Use helper to extract token from JSON response
+  if ! run_node_subprocess token "const d = JSON.parse(require('fs').readFileSync(0, 'utf8')); process.stdout.write(d.token || '')" "$token_data" /results/git-push.log; then
     printf -- 'Failed to extract token from response: %s\n' "$token_data" | tee -a /results/git-push.log >&2
     GITHUB_PUSH_EXIT=7
     return 7
   fi
   
+  if [ -z "$token" ]; then
+    printf -- 'Failed to extract token from response (empty result)\n' | tee -a /results/git-push.log >&2
+    GITHUB_PUSH_EXIT=7
+    return 7
+  fi
+  
   printf 'Token generated successfully\n' | tee -a /results/git-push.log
   
   # Create and push feature branch
@@ -1510,6 +1651,19 @@ EOF
       printf 'Debug: Creating PR with head=%s, base=%s, draft=true\n' "$feature_branch" "$GIT_REF" | tee -a /results/git-push.log
     fi
     
+    # Encode PR title and body as JSON strings
+    local pr_title_json pr_body_json
+    if ! run_node_subprocess pr_title_json "console.log(JSON.stringify(require('fs').readFileSync(0, 'utf8')))" "$pr_title" /results/git-push.log; then
+      printf 'ERROR: Failed to JSON encode PR title\n' | tee -a /results/git-push.log >&2
+      GITHUB_PR_EXIT=8
+      return 8
+    fi
+    if ! run_node_subprocess pr_body_json "console.log(JSON.stringify(require('fs').readFileSync(0, 'utf8')))" "$pr_body" /results/git-push.log; then
+      printf 'ERROR: Failed to JSON encode PR body\n' | tee -a /results/git-push.log >&2
+      GITHUB_PR_EXIT=8
+      return 8
+    fi
+    
     # Use curl with -w to capture HTTP status separately
     # curl exit code: 0=success, non-0=failure
     local curl_exit
@@ -1517,7 +1671,7 @@ EOF
       -H "Authorization: token $token" \
       -H "Accept: application/vnd.github.v3+json" \
       "https://api.github.com/repos/$owner/$repo/pulls" \
-      -d "{\"title\": $(printf '%s' "$pr_title" | node -e "console.log(JSON.stringify(require('fs').readFileSync(0, 'utf8')))"), \"body\": $(printf '%s' "$pr_body" | node -e "console.log(JSON.stringify(require('fs').readFileSync(0, 'utf8')))"), \"head\": \"$feature_branch\", \"base\": \"$GIT_REF\", \"draft\": true}" > "$temp_status_file" 2>&1
+      -d "{\"title\": $pr_title_json, \"body\": $pr_body_json, \"head\": \"$feature_branch\", \"base\": \"$GIT_REF\", \"draft\": true}" > "$temp_status_file" 2>&1
     curl_exit=$?
     
     # Split response and status code
@@ -1552,8 +1706,13 @@ EOF
     
     # Validate the API response
     if validate_github_api_response "$pr_http_status" "$pr_response" /results/git-push.log; then
-      # API returned success (201); now extract the URL
-      pr_url="$(printf '%s' "$pr_response" | node -e "const d = JSON.parse(require('fs').readFileSync(0, 'utf8')); process.stdout.write(d.html_url || '')" 2>/dev/null || true)"
+      # API returned success (201); now extract the URL using helper
+      if ! run_node_subprocess pr_url "const d = JSON.parse(require('fs').readFileSync(0, 'utf8')); process.stdout.write(d.html_url || '')" "$pr_response" /results/git-push.log; then
+        printf 'ERROR: Failed to extract PR URL from API response\n' | tee -a /results/git-push.log >&2
+        emit_error_event "github_pr_response_malformed" "Failed to parse PR API response to extract html_url" "exit"
+        GITHUB_PR_EXIT=9
+        pr_url=""
+      fi
       
       if [ -n "$pr_url" ]; then
         GITHUB_PR_URL="$pr_url"
@@ -1612,6 +1771,17 @@ printf 'Provider: %s\n' "$KASEKI_PROVIDER"
 printf 'Model: %s\n' "$KASEKI_MODEL"
 printf 'Pi version: %s\n' "$PI_VERSION"
 
+# Run preflight health check for GitHub operations if enabled
+if [ "$GITHUB_APP_ENABLED" = "1" ]; then
+  printf '\n==> github operations preflight health check\n'
+  if ! check_github_operations_health; then
+    printf 'ERROR: GitHub operations preflight health check failed\n' >&2
+    printf 'GitHub App is enabled but configuration or dependencies are missing.\n' >&2
+    printf 'Proceeding with kaseki run, but GitHub operations will be skipped or fail.\n' >&2
+    emit_error_event "github_preflight_failed" "GitHub operations health check failed; check /results/github-health-check.log for details" "continue"
+  fi
+fi
+
 openrouter_api_key=""
 openrouter_api_key_source=""
 if [ -n "${OPENROUTER_API_KEY:-}" ]; then

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanautomation/kaseki-agent",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "description": "Ephemeral coding-agent runner: orchestrates Pi CLI via Docker for automated code modifications with validation",
   "type": "module",
   "license": "MIT",

package/scripts/kaseki-diagnose-github-failure.sh

@@ -0,0 +1,143 @@
+#!/usr/bin/env bash
+# kaseki-diagnose-github-failure.sh
+# Diagnostic script to analyze github operations failures in kaseki run artifacts
+# Usage: ./kaseki-diagnose-github-failure.sh /agents/kaseki-results/kaseki-N
+
+set -eo pipefail
+
+RESULTS_DIR="${1:-.}"
+SCRIPT_NAME="$(basename "$0")"
+
+if [ ! -d "$RESULTS_DIR" ]; then
+  printf 'ERROR: Results directory not found: %s\n' "$RESULTS_DIR" >&2
+  exit 1
+fi
+
+if [ ! -f "$RESULTS_DIR/metadata.json" ] || [ ! -f "$RESULTS_DIR/failure.json" ]; then
+  printf 'ERROR: metadata.json or failure.json not found in %s\n' "$RESULTS_DIR" >&2
+  exit 1
+fi
+
+# Helper to extract JSON values
+json_value() {
+  local file="$1"
+  local key="$2"
+  grep "\"$key\"" "$file" | head -1 | sed 's/.*"'$key'":\s*"\?//; s/".*$//'
+}
+
+# Read key fields from metadata
+INSTANCE="$(json_value "$RESULTS_DIR/metadata.json" "instance")"
+STAGE="$(json_value "$RESULTS_DIR/metadata.json" "current_stage")"
+EXIT_CODE="$(json_value "$RESULTS_DIR/metadata.json" "exit_code")"
+GITHUB_PUSH_EXIT="$(json_value "$RESULTS_DIR/metadata.json" "github_push_exit_code")"
+GITHUB_PR_EXIT="$(json_value "$RESULTS_DIR/metadata.json" "github_pr_exit_code")"
+GITHUB_API_ERROR_TYPE="$(json_value "$RESULTS_DIR/metadata.json" "github_api_error_type")"
+GITHUB_API_ERROR_MESSAGE="$(json_value "$RESULTS_DIR/metadata.json" "github_api_error_message")"
+GITHUB_API_HTTP_STATUS="$(json_value "$RESULTS_DIR/metadata.json" "github_api_http_status")"
+
+printf '# GitHub Operations Failure Diagnostic Report\n\n'
+printf '**Instance:** %s\n' "$INSTANCE"
+printf '**Results directory:** %s\n' "$RESULTS_DIR"
+printf '**Overall exit code:** %s\n\n' "$EXIT_CODE"
+
+# ===== Stage-level diagnosis =====
+printf '## Stage Status\n\n'
+if [ "$STAGE" = "github operations" ]; then
+  printf '- Current stage: github operations (failure occurred in this stage)\n'
+else
+  printf '- Current stage: %s (failure occurred before github operations)\n' "$STAGE"
+fi
+printf '- GitHub push exit code: %s\n' "$GITHUB_PUSH_EXIT"
+printf '- GitHub PR exit code: %s\n' "$GITHUB_PR_EXIT"
+
+# ===== Detailed diagnosis =====
+printf '\n## Diagnosis\n\n'
+
+# Check if failure occurred in github operations stage
+if [ "$STAGE" != "github operations" ]; then
+  printf '**Failure occurred before github operations stage.**\n'
+  printf '\nGithub operations was never attempted. Check earlier stages:\n'
+  if [ -f "$RESULTS_DIR/stage-timings.tsv" ]; then
+    printf '\n```\n'
+    cat "$RESULTS_DIR/stage-timings.tsv"
+    printf '```\n'
+  fi
+  exit 0
+fi
+
+# Now we know stage is github operations
+if [ "$GITHUB_PUSH_EXIT" -ne 0 ] && [ "$GITHUB_PR_EXIT" -eq 0 ]; then
+  printf '**Git push failed (exit code: %s)**\n\n' "$GITHUB_PUSH_EXIT"
+  printf 'The git push operation failed. Check git-push.log for details:\n'
+  if [ -f "$RESULTS_DIR/git-push.log" ]; then
+    printf '\n```\n'
+    tail -20 "$RESULTS_DIR/git-push.log"
+    printf '```\n'
+  fi
+elif [ "$GITHUB_PR_EXIT" -ne 0 ]; then
+  printf '**GitHub PR creation failed (exit code: %s)**\n\n' "$GITHUB_PR_EXIT"
+  
+  if [ -n "$GITHUB_API_ERROR_TYPE" ]; then
+    printf 'API error type: %s\n' "$GITHUB_API_ERROR_TYPE"
+  fi
+  if [ -n "$GITHUB_API_ERROR_MESSAGE" ]; then
+    printf 'API error message: %s\n' "$GITHUB_API_ERROR_MESSAGE"
+  fi
+  if [ -n "$GITHUB_API_HTTP_STATUS" ]; then
+    printf 'HTTP status: %s\n' "$GITHUB_API_HTTP_STATUS"
+  fi
+  
+  printf '\nAPI error details from git-push.log:\n'
+  if [ -f "$RESULTS_DIR/git-push.log" ]; then
+    printf '\n```\n'
+    tail -30 "$RESULTS_DIR/git-push.log"
+    printf '```\n'
+  fi
+elif [ "$GITHUB_PUSH_EXIT" -eq 0 ] && [ "$GITHUB_PR_EXIT" -eq 0 ]; then
+  printf '**GitHub operations completed successfully, but overall exit code is non-zero.**\n\n'
+  printf 'This suggests the failure occurred in the finish() trap handler or post-github-ops cleanup.\n'
+  printf 'Check the following:\n\n'
+  
+  if [ -f "$RESULTS_DIR/last-command.log" ]; then
+    printf '- Last command log exists at: %s\n' "$RESULTS_DIR/last-command.log"
+    printf '\n```\n'
+    cat "$RESULTS_DIR/last-command.log"
+    printf '```\n'
+  fi
+  
+  if [ -f "$RESULTS_DIR/github-health-check.log" ]; then
+    printf '\n- GitHub health check log:\n\n```\n'
+    cat "$RESULTS_DIR/github-health-check.log"
+    printf '```\n'
+  fi
+  
+  if [ -f "$RESULTS_DIR/restoration-errors.log" ]; then
+    printf '\n- Restoration errors:\n\n```\n'
+    cat "$RESULTS_DIR/restoration-errors.log"
+    printf '```\n'
+  fi
+else
+  printf '**Unknown failure pattern.**\n\n'
+  printf 'Push exit: %s, PR exit: %s\n' "$GITHUB_PUSH_EXIT" "$GITHUB_PR_EXIT"
+fi
+
+# ===== Check for subprocess errors =====
+printf '\n## Node.js Subprocess Errors\n\n'
+if [ -f "$RESULTS_DIR/git-push.log" ] && grep -q '\[node-subprocess-error\]' "$RESULTS_DIR/git-push.log"; then
+  printf 'Node.js subprocess errors detected:\n\n'
+  printf '```\n'
+  grep '\[node-subprocess-error\]' "$RESULTS_DIR/git-push.log" | head -20
+  printf '```\n'
+else
+  printf 'No Node.js subprocess errors detected.\n'
+fi
+
+# ===== Helpful references =====
+printf '\n## Helpful Resources\n\n'
+printf '- **Exit codes reference:** See docs/EXIT_CODES.md\n'
+printf '- **Git-push.log:** Full GitHub operations details at %s/git-push.log\n' "$RESULTS_DIR"
+printf '- **Metadata:** Complete run metadata at %s/metadata.json\n' "$RESULTS_DIR"
+printf '- **Failure details:** See %s/failure.json\n' "$RESULTS_DIR"
+
+printf '\n---\n\n'
+printf '**Generated by %s**\n' "$SCRIPT_NAME"