@openpome/local-gateway 0.34.0-alpha.0 → 0.38.0-alpha.0

package/dist/index.js

@@ -9,6 +9,7 @@ import { promisify } from "node:util";
 import { defaultConfig } from "@openpome/configuration";
 import { createCredentialStore, getJsonCredential, setJsonCredential } from "@openpome/credentials";
 import { groupWorkItemsByType } from "@openpome/work-items";
+import { getLocalPersistenceInfo, openSessionSnapshotStore } from "@openpome/persistence";
 import { buildPlanningPrompt } from "@openpome/prompt-engine";
 import { rankWorkspaceCandidates } from "@openpome/workspaces";
 import { createDefaultWorkItemSourceRegistry, createJiraCloudOAuthLogin, exchangeJiraCloudOAuthCode, refreshJiraCloudOAuthToken } from "./connectors/work-item-registry.js";
@@ -40,7 +41,7 @@ const maxWorkspaceScanRepositories = 200;
 export function getGatewayHealth() {
     return {
         status: "ok",
-        version: "0.34.0-alpha.0"
+        version: "0.38.0-alpha.0"
     };
 }
 export async function initOpenPome() {
@@ -231,6 +232,11 @@ export async function runDoctor(env = process.env) {
             name: "Model provider",
             status: activeModel?.configured ? "ok" : "attention",
             detail: activeModel?.detail ?? "Run `pome auth ai status` to inspect AI setup."
+        },
+        {
+            name: "Telemetry",
+            status: "ok",
+            detail: "Disabled by default. OpenPome does not send analytics, prompts, source code, diffs, or crash data."
         }
     ];
     return {
@@ -534,9 +540,11 @@ export async function getAssistantDecision() {
     if (!status.aiPatchProposal && !status.diffSummary) {
         const model = await getModelProviderStatus();
         const activeModel = model.providers.find((provider) => provider.active);
-        const blockers = activeModel && activeModel.configured ? collectPlanReadinessWarnings(status) : [
+        const aiCanProposePatch = activeModel?.provider !== "manual-copy" && Boolean(activeModel?.configured);
+        const blockers = aiCanProposePatch ? collectPlanReadinessWarnings(status) : [
             activeModel?.detail ?? "No AI provider is active.",
-            "Connect Claude CLI, Claude API, or OpenAI for AI patch proposals."
+            "Connect Claude CLI, Claude API, or OpenAI before AI patch proposals.",
+            "Run `pome auth ai claude-cli`, `pome auth ai claude`, or `pome auth ai openai`."
         ];
         return buildAssistantDecision(status, "propose_patch", "Ask AI for the smallest safe patch", "OpenPome will collect bounded repo context, ask the active AI provider for changes, and prepare an approval checkpoint.", [
             "pome next",
@@ -635,11 +643,13 @@ function getLatestTestRunAfterStatus(status, since) {
 export async function stopTaskSession() {
     const paths = getOpenPomePaths();
     const persisted = await readActiveTaskSessionIfPresent(paths.homeDirectory);
+    const databaseFile = getSessionDatabaseFile(paths.homeDirectory);
     if (!persisted) {
         return {
             active: false,
             sessionFile: getActiveTaskSessionFile(paths.homeDirectory),
             historyFile: getTaskSessionHistoryFile(paths.homeDirectory),
+            databaseFile,
             message: "No active task session to stop."
         };
     }
@@ -666,6 +676,7 @@ export async function stopTaskSession() {
         active: false,
         sessionFile: getActiveTaskSessionFile(paths.homeDirectory),
         historyFile: getTaskSessionHistoryFile(paths.homeDirectory),
+        databaseFile,
         session,
         message: "Stopped active task session and archived it locally."
     };
@@ -673,22 +684,25 @@ export async function stopTaskSession() {
 export async function resumeTaskSession(sessionId) {
     const paths = getOpenPomePaths();
     const active = await readActiveTaskSessionIfPresent(paths.homeDirectory);
+    const databaseFile = getSessionDatabaseFile(paths.homeDirectory);
     if (active) {
         return {
             active: true,
             sessionFile: getActiveTaskSessionFile(paths.homeDirectory),
             historyFile: getTaskSessionHistoryFile(paths.homeDirectory),
+            databaseFile,
             session: active.session,
             message: "Active task session is already available."
         };
     }
     const history = await readTaskSessionHistoryIfPresent(paths.homeDirectory);
-    const archived = selectArchivedTaskSession(history?.sessions ?? [], sessionId);
+    const archived = selectArchivedTaskSession(await listArchivedTaskSessions(paths.homeDirectory, history?.sessions ?? []), sessionId);
     if (!archived) {
         return {
             active: false,
             sessionFile: getActiveTaskSessionFile(paths.homeDirectory),
             historyFile: getTaskSessionHistoryFile(paths.homeDirectory),
+            databaseFile,
             message: sessionId ? `No archived task session found: ${sessionId}` : "No archived task session is available to resume."
         };
     }
@@ -714,6 +728,7 @@ export async function resumeTaskSession(sessionId) {
         active: true,
         sessionFile: getActiveTaskSessionFile(paths.homeDirectory),
         historyFile: getTaskSessionHistoryFile(paths.homeDirectory),
+        databaseFile,
         session,
         message: "Resumed archived task session."
     };
@@ -721,11 +736,13 @@ export async function resumeTaskSession(sessionId) {
 export async function resetTaskSession() {
     const paths = getOpenPomePaths();
     const persisted = await readActiveTaskSessionIfPresent(paths.homeDirectory);
+    const databaseFile = getSessionDatabaseFile(paths.homeDirectory);
     if (!persisted) {
         return {
             active: false,
             sessionFile: getActiveTaskSessionFile(paths.homeDirectory),
             historyFile: getTaskSessionHistoryFile(paths.homeDirectory),
+            databaseFile,
             message: "No active task session to reset."
         };
     }
@@ -752,10 +769,21 @@ export async function resetTaskSession() {
         active: false,
         sessionFile: getActiveTaskSessionFile(paths.homeDirectory),
         historyFile: getTaskSessionHistoryFile(paths.homeDirectory),
+        databaseFile,
         session,
         message: "Reset active task session and archived it locally."
     };
 }
+export async function getTaskSessionHistory(limit = 25) {
+    const paths = getOpenPomePaths();
+    const history = await readTaskSessionHistoryIfPresent(paths.homeDirectory);
+    const sessions = await listArchivedTaskSessions(paths.homeDirectory, history?.sessions ?? [], limit);
+    return {
+        historyFile: getTaskSessionHistoryFile(paths.homeDirectory),
+        databaseFile: getSessionDatabaseFile(paths.homeDirectory),
+        sessions: sessions.map(summarizeTaskSessionHistory)
+    };
+}
 export async function createTaskSessionPlan() {
     const paths = getOpenPomePaths();
     const persisted = await refreshActiveTaskSessionWorkItem(paths.homeDirectory);
@@ -1053,7 +1081,7 @@ export async function discoverTestCommands() {
     }
     const workspace = persisted.workspaceCandidate?.workspace;
     const discoveredAt = new Date().toISOString();
-    const candidates = workspace?.path ? await discoverTestCommandCandidates(workspace.path) : getFallbackTestCommandCandidates();
+    const candidates = workspace?.path ? await discoverTestCommandCandidates(workspace.path, persisted) : getFallbackTestCommandCandidates();
     await writeActiveTaskSession(paths.homeDirectory, {
         ...persisted,
         testCommandCandidates: candidates,
@@ -1083,7 +1111,7 @@ export async function approveTestCommand(command) {
     const candidates = persisted.testCommandCandidates?.length
         ? persisted.testCommandCandidates
         : persisted.workspaceCandidate?.workspace.path
-            ? await discoverTestCommandCandidates(persisted.workspaceCandidate.workspace.path)
+            ? await discoverTestCommandCandidates(persisted.workspaceCandidate.workspace.path, persisted)
             : getFallbackTestCommandCandidates();
     const selected = selectTestCommandCandidate(candidates, command);
     if (!selected) {
@@ -1311,16 +1339,16 @@ export async function createGitHubDeviceLogin(env = process.env) {
         client_id: clientId,
         scope
     });
-    const response = await fetch("https://github.com/login/device/code", {
+    const response = await fetchGitHub("https://github.com/login/device/code", {
         method: "POST",
         headers: {
             Accept: "application/json",
             "Content-Type": "application/x-www-form-urlencoded"
         },
         body
-    });
+    }, "start browser login");
     if (!response.ok) {
-        throw new Error(`GitHub device login failed: ${response.status} ${response.statusText}`);
+        throw new Error(await getGitHubStatusGuidance(response, "start browser login"));
     }
     const payload = (await response.json());
     if (!payload.device_code || !payload.user_code || !payload.verification_uri) {
@@ -1484,7 +1512,7 @@ export async function createPullRequest(options = {}) {
     }
     await runGitStrict(workspacePath, ["add", "-A"]);
     await runGitStrict(workspacePath, ["commit", "-m", commitMessage]);
-    await runGitStrict(workspacePath, ["push", "-u", "origin", branch]);
+    await pushPullRequestBranch(workspacePath, branch);
     const storedGitHubToken = github.tokenSource === "openpome" ? await readStoredGitHubOAuth() : undefined;
     const prProvider = storedGitHubToken?.accessToken ? "github-api" : "github-cli";
     const prUrl = storedGitHubToken?.accessToken
@@ -1875,15 +1903,15 @@ async function isGitHubCliAuthenticated() {
     }
 }
 async function fetchGitHubAuthenticatedUser(accessToken) {
-    const response = await fetch("https://api.github.com/user", {
+    const response = await fetchGitHub("https://api.github.com/user", {
         headers: {
             Accept: "application/vnd.github+json",
             Authorization: `Bearer ${accessToken}`,
             "X-GitHub-Api-Version": "2022-11-28"
         }
-    });
+    }, "verify authenticated user");
     if (!response.ok) {
-        throw new Error(`GitHub user lookup failed: ${response.status} ${response.statusText}`);
+        throw new Error(await getGitHubStatusGuidance(response, "verify authenticated user"));
     }
     const payload = (await response.json());
     if (!payload.login) {
@@ -1896,7 +1924,7 @@ async function fetchGitHubAuthenticatedUser(accessToken) {
     };
 }
 async function pollGitHubDeviceAccessToken(clientId, deviceCode) {
-    const response = await fetch("https://github.com/login/oauth/access_token", {
+    const response = await fetchGitHub("https://github.com/login/oauth/access_token", {
         method: "POST",
         headers: {
             Accept: "application/json",
@@ -1907,11 +1935,11 @@ async function pollGitHubDeviceAccessToken(clientId, deviceCode) {
             device_code: deviceCode,
             grant_type: "urn:ietf:params:oauth:grant-type:device_code"
         })
-    });
+    }, "complete browser login");
     if (!response.ok) {
         return {
             status: "error",
-            detail: `GitHub device token polling failed: ${response.status} ${response.statusText}`
+            detail: await getGitHubStatusGuidance(response, "complete browser login")
         };
     }
     const payload = (await response.json());
@@ -1949,6 +1977,48 @@ function parseGitHubScopes(scope) {
         .map((value) => value.trim())
         .filter((value) => value.length > 0);
 }
+async function fetchGitHub(input, init, action) {
+    try {
+        return await fetch(input, init);
+    }
+    catch (error) {
+        throw new Error(getGitHubNetworkGuidance(action, error));
+    }
+}
+async function getGitHubStatusGuidance(response, action) {
+    const body = await safeResponseText(response);
+    const detail = body ? ` Detail: ${summarizeProviderBody(body)}` : "";
+    if (response.status === 401) {
+        return `GitHub ${action} was unauthorized (401). Run \`pome auth github login\` again, or \`gh auth login\` if you use the GitHub CLI fallback.${detail}`;
+    }
+    if (response.status === 403) {
+        return `GitHub ${action} was forbidden (403). Check repository permission, organization SSO, token scopes, branch protection, and whether the token has \`repo\` access.${detail}`;
+    }
+    if (response.status === 404) {
+        return `GitHub ${action} could not find the repository or resource (404). Check the git remote, repository visibility, GitHub Enterprise host, and account access.${detail}`;
+    }
+    if (response.status === 422) {
+        return `GitHub ${action} was rejected (422). Check whether the branch already has an open PR, base/head branch names are valid, and the repo allows PRs.${detail}`;
+    }
+    if (response.status === 429 || response.headers.get("x-ratelimit-remaining") === "0") {
+        const reset = response.headers.get("x-ratelimit-reset");
+        const resetDetail = reset ? ` Rate limit resets at ${new Date(Number(reset) * 1000).toISOString()}.` : "";
+        return `GitHub rate limit reached while trying to ${action}.${resetDetail} Wait and retry, or use a token with the right organization access.${detail}`;
+    }
+    if (response.status >= 500) {
+        return `GitHub ${action} failed with ${response.status} ${response.statusText}. GitHub may be unavailable, blocked by a proxy, or unreachable from this network.${detail}`;
+    }
+    return `GitHub ${action} failed: ${response.status} ${response.statusText}.${detail}`;
+}
+function getGitHubNetworkGuidance(action, error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    return [
+        `GitHub ${action} could not reach GitHub.`,
+        "Check internet access, VPN split tunneling, proxy/firewall rules, corporate certificate trust, and GitHub Enterprise host configuration.",
+        "Run `pome auth github status` after fixing network access.",
+        `Detail: ${detail}`
+    ].join(" ");
+}
 function summarizeUnknownError(error) {
     return error instanceof Error ? error.message : String(error);
 }
@@ -1997,7 +2067,11 @@ function getOpenPomePaths() {
 async function readConfigIfPresent(configFile) {
     try {
         const content = await readFile(configFile, "utf8");
-        return JSON.parse(content);
+        return {
+            ...defaultConfig,
+            ...JSON.parse(content),
+            telemetryEnabled: false
+        };
     }
     catch (error) {
         if (error instanceof Error && "code" in error && error.code === "ENOENT") {
@@ -2544,6 +2618,7 @@ async function readActiveTaskSessionIfPresent(homeDirectory) {
 async function writeActiveTaskSession(homeDirectory, session) {
     await mkdir(homeDirectory, { recursive: true });
     await writeFile(getActiveTaskSessionFile(homeDirectory), `${JSON.stringify(session, null, 2)}\n`, "utf8");
+    persistTaskSessionSnapshot(homeDirectory, session, true);
 }
 async function removeActiveTaskSession(homeDirectory) {
     await rm(getActiveTaskSessionFile(homeDirectory), { force: true });
@@ -2571,6 +2646,88 @@ async function archiveTaskSession(homeDirectory, session) {
     };
     await mkdir(homeDirectory, { recursive: true });
     await writeFile(getTaskSessionHistoryFile(homeDirectory), `${JSON.stringify(history, null, 2)}\n`, "utf8");
+    persistTaskSessionSnapshot(homeDirectory, session, false);
+}
+async function listArchivedTaskSessions(homeDirectory, jsonSessions, limit = 25) {
+    const sqliteSessions = tryListSessionSnapshots(homeDirectory, limit);
+    if (sqliteSessions.length > 0) {
+        return sqliteSessions;
+    }
+    return jsonSessions.slice(0, limit);
+}
+function persistTaskSessionSnapshot(homeDirectory, session, active) {
+    try {
+        const store = openSessionSnapshotStore(homeDirectory);
+        store.upsertSessionSnapshot(buildSessionSnapshotInput(session, active));
+    }
+    catch {
+        // JSON active/history files remain the alpha compatibility fallback. SQLite
+        // persistence must improve resume reliability without blocking daily work.
+    }
+}
+function tryListSessionSnapshots(homeDirectory, limit) {
+    try {
+        const store = openSessionSnapshotStore(homeDirectory);
+        return store.listSessionSnapshots(limit)
+            .map((record) => record.snapshot)
+            .filter(isPersistedTaskSession);
+    }
+    catch {
+        return [];
+    }
+}
+function buildSessionSnapshotInput(session, active) {
+    const latestEvent = session.events?.[session.events.length - 1];
+    const latestTestRun = session.testRunEvidence?.[session.testRunEvidence.length - 1];
+    return {
+        sessionId: session.session.id,
+        workItemKey: session.workItem.key,
+        workItemTitle: session.workItem.title,
+        status: session.session.status,
+        updatedAt: session.session.updatedAt,
+        active,
+        workspaceName: session.workspaceCandidate?.workspace.name,
+        workspacePath: session.workspaceCandidate?.workspace.path,
+        latestEventTitle: latestEvent?.title,
+        latestEventAt: latestEvent?.createdAt,
+        latestTestStatus: latestTestRun?.status,
+        latestTestCommand: latestTestRun?.command,
+        latestPatchAppliedAt: session.aiPatchProposal?.appliedAt,
+        prUrl: session.prCreation?.prUrl,
+        jiraCommentId: session.workItemUpdatePost?.commentId,
+        snapshot: session
+    };
+}
+function summarizeTaskSessionHistory(session) {
+    const latestEvent = session.events?.[session.events.length - 1];
+    const latestTestRun = session.testRunEvidence?.[session.testRunEvidence.length - 1];
+    return {
+        sessionId: session.session.id,
+        active: session.session.status !== "completed" && session.session.status !== "blocked",
+        workItemKey: session.workItem.key,
+        workItemTitle: session.workItem.title,
+        status: session.session.status,
+        updatedAt: session.session.updatedAt,
+        workspaceName: session.workspaceCandidate?.workspace.name,
+        workspacePath: session.workspaceCandidate?.workspace.path,
+        latestEventTitle: latestEvent?.title,
+        latestEventAt: latestEvent?.createdAt,
+        latestTestStatus: latestTestRun?.status,
+        latestTestCommand: latestTestRun?.command,
+        latestPatchAppliedAt: session.aiPatchProposal?.appliedAt,
+        prUrl: session.prCreation?.prUrl,
+        jiraCommentId: session.workItemUpdatePost?.commentId
+    };
+}
+function isPersistedTaskSession(value) {
+    return typeof value === "object"
+        && value !== null
+        && "version" in value
+        && "session" in value
+        && "workItem" in value;
+}
+function getSessionDatabaseFile(homeDirectory) {
+    return getLocalPersistenceInfo(homeDirectory).databaseFile;
 }
 function selectArchivedTaskSession(sessions, sessionId) {
     if (sessionId) {
@@ -2580,28 +2737,39 @@ function selectArchivedTaskSession(sessions, sessionId) {
 }
 function buildPlanningContext(session) {
     const workspace = session.workspaceCandidate?.workspace;
+    const missingRequirementSignals = detectMissingRequirementSignals(session.workItem);
     const context = [
         `Work item type: ${session.workItem.type}`,
         `Status: ${session.workItem.status}`,
         session.workItem.priority ? `Priority: ${session.workItem.priority}` : undefined,
+        session.workItem.description ? `Description length: ${session.workItem.description.length} characters` : "Description: not provided",
         hasExplicitAcceptanceCriteria(session.workItem)
             ? "Acceptance criteria: detected in work item text"
             : "Acceptance criteria: not explicit; identify missing acceptance criteria before implementation",
+        missingRequirementSignals.length ? `Missing requirement signals: ${missingRequirementSignals.join("; ")}` : undefined,
         session.workItem.labels?.length ? `Labels: ${session.workItem.labels.join(", ")}` : undefined,
         session.workItem.components?.length ? `Components: ${session.workItem.components.join(", ")}` : undefined,
+        session.workItem.links?.length ? `Linked references: ${session.workItem.links.map((link) => `${link.kind}:${link.title ?? link.url}`).join("; ")}` : undefined,
+        session.workItem.subtasks?.length ? `Subtasks: ${session.workItem.subtasks.map((subtask) => `${subtask.key} ${subtask.status} ${subtask.title}`).join("; ")}` : undefined,
         workspace ? `Workspace: ${workspace.name}` : "Workspace: unresolved",
         workspace?.path ? `Workspace path: ${workspace.path}` : undefined,
         session.workspaceCandidate ? `Workspace confidence: ${Math.round(session.workspaceCandidate.confidence * 100)}%` : undefined,
-        session.workspaceCandidate?.reasons.length ? `Workspace reasons: ${session.workspaceCandidate.reasons.join("; ")}` : undefined
+        session.workspaceCandidate?.reasons.length ? `Workspace reasons: ${session.workspaceCandidate.reasons.join("; ")}` : undefined,
+        workspace?.packageNames?.length ? `Workspace packages: ${workspace.packageNames.slice(0, 8).join(", ")}` : undefined,
+        workspace?.readmeKeywords?.length ? `README signals: ${workspace.readmeKeywords.slice(0, 12).join(", ")}` : undefined,
+        workspace?.codeownersKeywords?.length ? `Ownership signals: ${workspace.codeownersKeywords.slice(0, 12).join(", ")}` : undefined,
+        workspace?.recentBranches?.length ? `Recent branches: ${workspace.recentBranches.slice(0, 8).join(", ")}` : undefined,
+        workspace?.recentCommitRefs?.length ? `Recent work refs: ${workspace.recentCommitRefs.slice(0, 12).join(", ")}` : undefined
     ];
     return context.filter((item) => Boolean(item));
 }
 function buildInitialImplementationPlan(workItem, workspaceCandidate) {
     const workspace = workspaceCandidate?.workspace;
     const hasWorkspace = Boolean(workspace?.path);
+    const missingRequirementSignals = detectMissingRequirementSignals(workItem);
     const missingInfo = [
         hasWorkspace ? undefined : "No workspace candidate is selected yet.",
-        hasExplicitAcceptanceCriteria(workItem) ? undefined : "Acceptance criteria are not explicit in the work item."
+        ...missingRequirementSignals
     ].filter((item) => Boolean(item));
     return {
         summary: `Prepare implementation for ${workItem.key}: ${workItem.title}`,
@@ -2647,7 +2815,36 @@ function buildInitialImplementationPlan(workItem, workspaceCandidate) {
 }
 function hasExplicitAcceptanceCriteria(workItem) {
     const text = [workItem.title, workItem.description].filter(Boolean).join("\n").toLowerCase();
-    return /\b(acceptance criteria|acceptance|criteria|given\b.*\bwhen\b.*\bthen|expected result|definition of done|done when|should)\b/su.test(text);
+    return /\b(acceptance criteria|acceptance|criteria|given\b.*\bwhen\b.*\bthen|expected result|definition of done|done when|should|expected behavior|success criteria|verify|validation)\b/su.test(text);
+}
+function detectMissingRequirementSignals(workItem) {
+    const text = [workItem.title, workItem.description].filter(Boolean).join("\n").trim();
+    const lower = text.toLowerCase();
+    const signals = [];
+    if (!workItem.description || workItem.description.trim().length < 40) {
+        signals.push("Clarify the exact scope because the work item description is short.");
+    }
+    if (!hasExplicitAcceptanceCriteria(workItem)) {
+        signals.push("Ask what acceptance criteria prove this story is complete.");
+    }
+    if (workItem.type === "bug") {
+        const hasExpected = /\b(expected|should happen|desired behavior|correct behavior)\b/u.test(lower);
+        const hasActual = /\b(actual|currently|observed|happens now|error|failure|failed)\b/u.test(lower);
+        const hasRepro = /\b(steps to reproduce|repro|reproduce|given\b.*\bwhen\b.*\bthen)\b/su.test(lower);
+        if (!hasExpected || !hasActual) {
+            signals.push("Ask for clear expected behavior and actual behavior for this bug.");
+        }
+        if (!hasRepro) {
+            signals.push("Ask for reproduction steps or a failing scenario for this bug.");
+        }
+    }
+    if (!workItem.labels?.length && !workItem.components?.length) {
+        signals.push("Ask which component, service, or package owns this change.");
+    }
+    if (!workItem.links?.some((link) => link.kind === "code" || link.kind === "pull_request" || link.kind === "document")) {
+        signals.push("Ask whether there is linked code, a prior pull request, design doc, or reference issue.");
+    }
+    return Array.from(new Set(signals)).slice(0, 6);
 }
 async function buildImplementationPlan(persisted, prompt) {
     const config = await readConfigIfPresent(getOpenPomePaths().configFile);
@@ -2674,7 +2871,7 @@ async function completeModelText(provider, prompt) {
     return completeClaudeCliText(prompt);
 }
 async function completeOpenAIText(prompt, apiKey) {
-    const response = await fetch("https://api.openai.com/v1/responses", {
+    const response = await fetchModelProvider("OpenAI", "https://api.openai.com/v1/responses", {
         method: "POST",
         headers: {
             "authorization": `Bearer ${apiKey}`,
@@ -2686,7 +2883,7 @@ async function completeOpenAIText(prompt, apiKey) {
         })
     });
     if (!response.ok) {
-        throw new Error(`OpenAI request failed: ${response.status} ${response.statusText}`);
+        throw new Error(await getModelProviderStatusGuidance("OpenAI", response, "generate a plan or patch"));
     }
     const body = await response.json();
     if (typeof body.output_text === "string") {
@@ -2700,7 +2897,7 @@ async function completeOpenAIText(prompt, apiKey) {
         .join("\n");
 }
 async function completeAnthropicText(prompt, apiKey) {
-    const response = await fetch("https://api.anthropic.com/v1/messages", {
+    const response = await fetchModelProvider("Claude", "https://api.anthropic.com/v1/messages", {
         method: "POST",
         headers: {
             "x-api-key": apiKey,
@@ -2719,7 +2916,7 @@ async function completeAnthropicText(prompt, apiKey) {
         })
     });
     if (!response.ok) {
-        throw new Error(`Claude request failed: ${response.status} ${response.statusText}`);
+        throw new Error(await getModelProviderStatusGuidance("Claude", response, "generate a plan or patch"));
     }
     const body = await response.json();
     const content = Array.isArray(body.content) ? body.content : [];
@@ -2761,12 +2958,50 @@ async function completeClaudeCliText(prompt) {
         throw new Error(`Claude CLI request failed: ${summarizeExecError(error) || String(error)}`);
     }
 }
+async function fetchModelProvider(provider, input, init) {
+    try {
+        return await fetch(input, init);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Error(`${provider} could not be reached. Check internet/VPN/proxy access, corporate certificate trust, and provider allowlists. Use \`pome auth ai status\` to verify setup. Detail: ${detail}`);
+    }
+}
+async function getModelProviderStatusGuidance(provider, response, action) {
+    const body = await safeResponseText(response);
+    const detail = body ? ` Detail: ${summarizeProviderBody(body)}` : "";
+    const authCommand = provider === "OpenAI" ? "pome auth ai openai" : "pome auth ai claude";
+    if (response.status === 401) {
+        return `${provider} ${action} was unauthorized (401). Reconnect with \`${authCommand}\` or verify the provider API key in your OS credential store/environment.${detail}`;
+    }
+    if (response.status === 403) {
+        return `${provider} ${action} was forbidden (403). Check organization policy, model access, provider project permissions, and corporate egress rules.${detail}`;
+    }
+    if (response.status === 404) {
+        return `${provider} ${action} could not find the configured model or endpoint (404). Check OPENPOME_${provider === "OpenAI" ? "OPENAI_MODEL" : "ANTHROPIC_MODEL"} and provider access.${detail}`;
+    }
+    if (response.status === 408 || response.status === 409 || response.status === 429) {
+        return `${provider} is busy or rate limited (${response.status}). Wait and retry, or choose a smaller model/context. OpenPome has not written files.${detail}`;
+    }
+    if (response.status >= 500) {
+        return `${provider} failed with ${response.status} ${response.statusText}. Provider service may be unavailable or blocked by your network/proxy. Retry later.${detail}`;
+    }
+    return `${provider} ${action} failed: ${response.status} ${response.statusText}.${detail}`;
+}
 function buildStructuredPlanPrompt(prompt) {
     return [
         "You are OpenPome's planning engine.",
+        "Plan like a senior developer assistant working from a live corporate work item.",
+        "Prefer the smallest repo-aware change that satisfies the work item. Call out unclear scope instead of inventing requirements.",
+        "Use workspace metadata, labels, linked references, ownership signals, and recent branch/commit refs to rank likely files.",
+        "Suggest targeted validation commands before broad commands when the work item points to a specific component.",
         "Return only compact JSON with this exact shape:",
         "{\"summary\":\"...\",\"assumptions\":[\"...\"],\"steps\":[{\"id\":\"1\",\"title\":\"...\",\"detail\":\"...\"}],\"filesLikelyChanged\":[\"...\"],\"commandsToRun\":[\"...\"],\"risks\":[\"...\"],\"missingInfo\":[\"...\"]}",
-        "Do not include source code, full diffs, secrets, or markdown fences.",
+        "Rules:",
+        "- Do not include source code, full diffs, secrets, or markdown fences.",
+        "- Put missing acceptance criteria, missing repro steps, unclear expected behavior, and missing code links in missingInfo.",
+        "- Keep filesLikelyChanged to relative paths or package/module hints when exact files are unknown.",
+        "- Keep commandsToRun executable from the selected workspace.",
         "",
         prompt
     ].join("\n");
@@ -2825,33 +3060,65 @@ const modelProviderTimeoutMs = 120_000;
 const modelProviderMaxBufferBytes = 2 * 1024 * 1024;
 const sensitivePathFragments = [
     ".env",
+    ".env.local",
+    ".env.production",
+    ".env.development",
     ".npmrc",
+    ".yarnrc",
+    ".pnpmrc",
     ".pypirc",
     ".netrc",
     ".ssh",
     ".aws",
     ".gcp",
     ".azure",
+    ".kube",
+    ".docker",
+    "credentials",
+    "credential",
+    "secrets",
+    "secret",
+    "private-key",
+    "private_key",
     "id_rsa",
     "id_dsa",
-    "id_ed25519"
+    "id_ed25519",
+    ".pem",
+    ".key",
+    ".crt",
+    ".p12",
+    ".pfx"
+];
+const sensitiveContentPatterns = [
+    /-----BEGIN (?:RSA |DSA |EC |OPENSSH |PGP )?PRIVATE KEY-----/u,
+    /\b(?:OPENAI_API_KEY|ANTHROPIC_API_KEY|OPENPOME_JIRA_API_TOKEN|OPENPOME_GITHUB_TOKEN|GITHUB_TOKEN|NPM_TOKEN)\s*=\s*['"]?[^'"\s]+/iu,
+    /\b(?:api[_-]?key|access[_-]?token|refresh[_-]?token|client[_-]?secret|private[_-]?key)\s*[:=]\s*['"][^'"]{12,}['"]/iu,
+    /\b(?:ghp|github_pat|npm|sk|sk-ant|xox[baprs])-?[A-Za-z0-9_=-]{20,}\b/u
 ];
 async function collectPatchContextFiles(workspacePath, session) {
     const candidates = [];
     for (const filePath of session.plan?.filesLikelyChanged ?? []) {
         const normalized = normalizeWorkspaceRelativePath(workspacePath, filePath, "skip");
         if (normalized && normalized !== ".") {
-            candidates.push(normalized);
+            candidates.push({
+                filePath: normalized,
+                score: 80,
+                reason: "AI plan marked this file as likely impacted."
+            });
         }
     }
-    candidates.push("package.json", "README.md", "AGENTS.md");
+    candidates.push({ filePath: "package.json", score: 24, reason: "Package metadata helps infer scripts, package boundaries, and runtime." }, { filePath: "README.md", score: 18, reason: "README gives repository purpose and local validation hints." }, { filePath: "AGENTS.md", score: 18, reason: "Agent instructions constrain safe implementation style." }, { filePath: "CODEOWNERS", score: 14, reason: "Ownership metadata helps identify relevant domains and review paths." });
     const trackedFiles = await listTrackedWorkspaceFiles(workspacePath);
     const tokens = tokenizePatchSearchText([
         session.workItem.key,
         session.workItem.title,
         session.workItem.description,
+        session.plan?.summary,
+        ...(session.plan?.steps.map((step) => `${step.title} ${step.detail ?? ""}`) ?? []),
         ...(session.workItem.labels ?? []),
-        ...(session.workItem.components ?? [])
+        ...(session.workItem.components ?? []),
+        ...(session.workspaceCandidate?.workspace.packageNames ?? []),
+        ...(session.workspaceCandidate?.workspace.readmeKeywords ?? [])
     ].filter((value) => Boolean(value)).join(" "));
     const planHints = new Set((session.plan?.filesLikelyChanged ?? [])
         .map((filePath) => normalizeWorkspaceRelativePath(workspacePath, filePath, "skip"))
@@ -2859,12 +3126,13 @@ async function collectPatchContextFiles(workspacePath, session) {
     const rankedTrackedFiles = trackedFiles
         .map((filePath) => ({
         filePath,
-        score: scorePatchContextFile(filePath, tokens, planHints)
+        score: scorePatchContextFile(filePath, tokens, planHints),
+        reason: describePatchContextReason(filePath, tokens, planHints)
     }))
         .filter((candidate) => candidate.score > 0)
         .sort((left, right) => right.score - left.score || left.filePath.localeCompare(right.filePath));
     for (const candidate of rankedTrackedFiles.slice(0, 40)) {
-        candidates.push(candidate.filePath);
+        candidates.push(candidate);
     }
     const selected = [];
     const seen = new Set();
@@ -2873,7 +3141,7 @@ async function collectPatchContextFiles(workspacePath, session) {
         if (selected.length >= maxPatchContextFiles || totalBytes >= maxPatchContextTotalBytes) {
             break;
         }
-        const relativePath = normalizeWorkspaceRelativePath(workspacePath, candidate, "skip");
+        const relativePath = normalizeWorkspaceRelativePath(workspacePath, candidate.filePath, "skip");
         if (!relativePath || seen.has(relativePath) || isSensitiveWorkspacePath(relativePath)) {
             continue;
         }
@@ -2881,7 +3149,7 @@ async function collectPatchContextFiles(workspacePath, session) {
         const absolutePath = resolve(workspacePath, relativePath);
         try {
             const content = await readFile(absolutePath, "utf8");
-            if (content.includes("\u0000")) {
+            if (content.includes("\u0000") || containsSensitiveContent(content)) {
                 continue;
             }
             const remainingBytes = maxPatchContextTotalBytes - totalBytes;
@@ -2891,7 +3159,9 @@ async function collectPatchContextFiles(workspacePath, session) {
             selected.push({
                 path: relativePath,
                 content: sliced,
-                truncated: Buffer.byteLength(content, "utf8") > Buffer.byteLength(sliced, "utf8")
+                truncated: Buffer.byteLength(content, "utf8") > Buffer.byteLength(sliced, "utf8"),
+                score: candidate.score,
+                reason: candidate.reason
             });
         }
         catch {
@@ -2902,12 +3172,45 @@ async function collectPatchContextFiles(workspacePath, session) {
 }
 async function listTrackedWorkspaceFiles(workspacePath) {
     const output = await runGit(workspacePath, ["ls-files"]);
-    return output
+    const trackedFiles = output
         .split(/\r?\n/u)
         .map((line) => line.trim())
         .filter(Boolean)
         .filter((filePath) => !isSensitiveWorkspacePath(filePath))
         .slice(0, 1000);
+    return trackedFiles.length > 0 ? trackedFiles : listWorkspaceFilesFallback(workspacePath);
+}
+async function listWorkspaceFilesFallback(workspacePath) {
+    const collected = [];
+    const queue = ["."];
+    const ignoredDirectories = new Set([".git", "node_modules", "dist", "build", "coverage", ".next", ".turbo", ".cache", "vendor"]);
+    while (queue.length > 0 && collected.length < 1000) {
+        const current = queue.shift() ?? ".";
+        const absoluteCurrent = resolve(workspacePath, current);
+        let directory;
+        try {
+            directory = await opendir(absoluteCurrent);
+        }
+        catch {
+            continue;
+        }
+        for await (const entry of directory) {
+            const relativePath = current === "." ? entry.name : `${current}/${entry.name}`;
+            if (entry.isDirectory()) {
+                if (!ignoredDirectories.has(entry.name) && !isSensitiveWorkspacePath(relativePath)) {
+                    queue.push(relativePath);
+                }
+                continue;
+            }
+            if (entry.isFile() && !isSensitiveWorkspacePath(relativePath)) {
+                collected.push(relativePath);
+                if (collected.length >= 1000) {
+                    break;
+                }
+            }
+        }
+    }
+    return collected;
 }
 function tokenizePatchSearchText(value) {
     return Array.from(new Set(value.toLowerCase().split(/[^a-z0-9]+/u).filter((token) => token.length >= 3))).slice(0, 20);
@@ -2916,7 +3219,7 @@ function scorePatchContextFile(filePath, tokens, planHints) {
     const lower = filePath.toLowerCase();
     let score = 0;
     if (planHints.has(filePath)) {
-        score += 20;
+        score += 40;
     }
     for (const token of tokens) {
         if (lower.includes(token)) {
@@ -2926,32 +3229,64 @@ function scorePatchContextFile(filePath, tokens, planHints) {
     if (/\.(ts|tsx|js|jsx|mjs|cjs|py|java|kt|go|rs|rb|php|cs|swift)$/u.test(lower)) {
         score += 4;
     }
+    if (/(src|app|lib|packages|services|connectors|components|routes|api)\//u.test(lower)) {
+        score += 4;
+    }
     if (/(test|spec|__tests__|tests)\b/u.test(lower)) {
-        score += 3;
+        score += 5;
     }
     if (/(readme|package\.json|codeowners|agents\.md|tsconfig|vite|jest|vitest|pytest|gradle|pom\.xml|go\.mod|cargo\.toml)/u.test(lower)) {
         score += 2;
     }
-    if (/(dist|build|coverage|node_modules|vendor|generated|\.lock$|lockfile)/u.test(lower)) {
-        score -= 10;
+    if (/(dist|build|coverage|node_modules|vendor|generated|\.lock$|lockfile|\.min\.)/u.test(lower)) {
+        score -= 16;
+    }
+    if (/(snapshot|snapshots|fixtures|fixture|mock|mocks)\//u.test(lower)) {
+        score -= 2;
     }
     return score;
 }
+function describePatchContextReason(filePath, tokens, planHints) {
+    const lower = filePath.toLowerCase();
+    const reasons = [
+        planHints.has(filePath) ? "named by the approved plan" : undefined,
+        tokens.filter((token) => lower.includes(token)).slice(0, 4).length
+            ? `matches task token(s): ${tokens.filter((token) => lower.includes(token)).slice(0, 4).join(", ")}`
+            : undefined,
+        /(test|spec|__tests__|tests)\b/u.test(lower) ? "is a related validation file" : undefined,
+        /(package\.json|tsconfig|vite|jest|vitest|pytest|gradle|pom\.xml|go\.mod|cargo\.toml)/u.test(lower) ? "contains project or test configuration" : undefined,
+        /(readme|codeowners|agents\.md)/u.test(lower) ? "contains repository guidance" : undefined,
+        /\.(ts|tsx|js|jsx|mjs|cjs|py|java|kt|go|rs|rb|php|cs|swift)$/u.test(lower) ? "is source code in a supported language" : undefined
+    ].filter((reason) => Boolean(reason));
+    return reasons.length ? reasons.join("; ") : "ranked from repository metadata and work item text";
+}
 function buildStructuredPatchPrompt(session, workspacePath, contextFiles) {
     const plan = session.plan;
     const context = contextFiles.map((file) => [
         `FILE: ${file.path}${file.truncated ? " (truncated)" : ""}`,
+        `RANK: ${file.score}`,
+        `WHY_INCLUDED: ${file.reason}`,
         "```",
         file.content,
         "```"
     ].join("\n")).join("\n\n");
     const failedTestContext = getFailedTestContextAfterLatestPatch(session);
+    const missingRequirementSignals = Array.from(new Set([
+        ...detectMissingRequirementSignals(session.workItem),
+        ...(plan?.missingInfo ?? [])
+    ])).slice(0, 8);
+    const workspace = session.workspaceCandidate?.workspace;
     return [
         "You are OpenPome's implementation engine.",
+        failedTestContext.length
+            ? "This is a retry after approved validation failed. Repair only the failure using the evidence below."
+            : "This is the first implementation patch for the approved plan.",
         "Return only compact JSON. Do not include markdown fences outside JSON.",
         "Only propose a minimal safe file patch for the approved work item.",
         "Do not include secrets, credentials, generated dependency folders, lockfile rewrites, or unrelated refactors.",
         "Use full replacement file content for each proposed file.",
+        "If requirements are unclear, prefer a small diagnostic or guardrail change over a speculative broad rewrite.",
+        "Keep existing style, imports, formatting, and public contracts unless the work item clearly requires a change.",
         "Allowed JSON shape:",
         "{\"summary\":\"...\",\"files\":[{\"path\":\"relative/path\",\"action\":\"create|update\",\"content\":\"full file content\"}],\"risks\":[\"...\"]}",
         "",
@@ -2964,7 +3299,11 @@ function buildStructuredPatchPrompt(session, workspacePath, contextFiles) {
         session.workItem.priority ? `- Priority: ${session.workItem.priority}` : undefined,
         session.workItem.labels?.length ? `- Labels: ${session.workItem.labels.join(", ")}` : undefined,
         session.workItem.components?.length ? `- Components: ${session.workItem.components.join(", ")}` : undefined,
+        session.workItem.links?.length ? `- Links: ${session.workItem.links.map((link) => `${link.kind}:${link.title ?? link.url}`).join("; ")}` : undefined,
         "",
+        missingRequirementSignals.length ? "Known missing or unclear requirements:" : undefined,
+        ...missingRequirementSignals.map((signal) => `- ${signal}`),
+        missingRequirementSignals.length ? "" : undefined,
         "Approved plan:",
         plan?.summary ? `- Summary: ${plan.summary}` : "- Summary: unavailable",
         ...(plan?.steps.map((step) => `- ${step.title}${step.detail ? `: ${step.detail}` : ""}`) ?? []),
@@ -2975,7 +3314,13 @@ function buildStructuredPatchPrompt(session, workspacePath, contextFiles) {
         failedTestContext.length ? "" : undefined,
         "Workspace:",
         `- Path: ${workspacePath}`,
-        session.workspaceCandidate?.workspace.name ? `- Name: ${session.workspaceCandidate.workspace.name}` : undefined,
+        workspace?.name ? `- Name: ${workspace.name}` : undefined,
+        workspace?.currentBranch ? `- Current branch: ${workspace.currentBranch}` : undefined,
+        workspace?.packageNames?.length ? `- Packages: ${workspace.packageNames.slice(0, 8).join(", ")}` : undefined,
+        workspace?.readmeKeywords?.length ? `- README signals: ${workspace.readmeKeywords.slice(0, 12).join(", ")}` : undefined,
+        workspace?.codeownersKeywords?.length ? `- Ownership signals: ${workspace.codeownersKeywords.slice(0, 12).join(", ")}` : undefined,
+        workspace?.recentBranches?.length ? `- Recent branches: ${workspace.recentBranches.slice(0, 8).join(", ")}` : undefined,
+        workspace?.recentCommitRefs?.length ? `- Recent work refs: ${workspace.recentCommitRefs.slice(0, 12).join(", ")}` : undefined,
         "",
         "Readable context files:",
         context || "No source files were safely included. You may propose small new files only if the task clearly asks for them."
@@ -2986,14 +3331,41 @@ function getFailedTestContextAfterLatestPatch(session) {
     if (!failedRun) {
         return [];
     }
+    const rootCauseHint = inferFailedTestRootCause(failedRun);
     return [
         `- Command: ${failedRun.command}`,
         `- Exit code: ${failedRun.exitCode}`,
+        rootCauseHint ? `- Root cause hint: ${rootCauseHint}` : undefined,
         failedRun.cwd ? `- Working directory: ${failedRun.cwd}` : undefined,
         ...failedRun.stdoutSummary.map((line) => `- stdout: ${line}`),
         ...failedRun.stderrSummary.map((line) => `- stderr: ${line}`)
     ].filter((line) => Boolean(line)).slice(0, 48);
 }
+function inferFailedTestRootCause(run) {
+    const text = [...run.stdoutSummary, ...run.stderrSummary].join("\n").toLowerCase();
+    if (!text.trim()) {
+        return undefined;
+    }
+    if (/\b(assertionerror|expected .* received|expected .* got|toequal|tobe|assert)\b/su.test(text)) {
+        return "Assertion mismatch; inspect the changed behavior and expected output before editing more files.";
+    }
+    if (/\b(type error|ts\d{4}|typescript|cannot find name|property .* does not exist)\b/su.test(text)) {
+        return "Type or compile failure; prefer the smallest type-safe fix in the impacted file.";
+    }
+    if (/\b(module not found|cannot find module|enoent|no such file|import .* not found)\b/su.test(text)) {
+        return "Missing module/file/import; verify paths, exports, and package boundaries.";
+    }
+    if (/\b(timeout|timed out|exceeded timeout|deadline)\b/su.test(text)) {
+        return "Timeout or hanging validation; inspect async flow, retries, and long-running operations.";
+    }
+    if (/\b(permission denied|eacces|forbidden|unauthorized)\b/su.test(text)) {
+        return "Permission or environment failure; avoid code changes until credentials, filesystem access, or network access are confirmed.";
+    }
+    if (/\b(snapshot|snapshots)\b/su.test(text)) {
+        return "Snapshot mismatch; inspect whether output changed intentionally before updating snapshots.";
+    }
+    return "Validation failed; use the command output to target a narrow repair patch.";
+}
 function parseAIPatchProposal(value, session, provider, workspacePath, createdAt) {
     const json = extractJsonObject(value);
     if (!json) {
@@ -3022,7 +3394,7 @@ function parseAIPatchProposal(value, session, provider, workspacePath, createdAt
         const relativePath = normalizeWorkspaceRelativePath(workspacePath, maybe.path, "throw");
         const action = maybe.action === "create" ? "create" : "update";
         const content = maybe.content;
-        if (!relativePath || isSensitiveWorkspacePath(relativePath) || content.includes("\u0000")) {
+        if (!relativePath || isSensitiveWorkspacePath(relativePath) || content.includes("\u0000") || containsSensitiveContent(content)) {
             return undefined;
         }
         if (Buffer.byteLength(content, "utf8") > maxPatchProposalBytesPerFile) {
@@ -3070,6 +3442,9 @@ function isSensitiveWorkspacePath(filePath) {
     }
     return sensitivePathFragments.some((fragment) => lower === fragment || lower.includes(`/${fragment}`) || lower.endsWith(fragment));
 }
+function containsSensitiveContent(content) {
+    return sensitiveContentPatterns.some((pattern) => pattern.test(content));
+}
 async function applyPatchFiles(workspacePath, files) {
     for (const file of files) {
         const relativePath = normalizeWorkspaceRelativePath(workspacePath, file.path, "throw");
@@ -3081,7 +3456,7 @@ async function applyPatchFiles(workspacePath, files) {
         await writeFile(absolutePath, file.content, "utf8");
     }
 }
-async function discoverTestCommandCandidates(workspacePath) {
+async function discoverTestCommandCandidates(workspacePath, session) {
     const scripts = await readPackageScripts(join(workspacePath, "package.json"));
     const packageManager = detectPackageManager(workspacePath);
     const candidates = [];
@@ -3097,6 +3472,17 @@ async function discoverTestCommandCandidates(workspacePath) {
             cwd: workspacePath
         });
     }
+    const relatedTestFiles = session ? await findRelatedTestFiles(workspacePath, session) : [];
+    const testScript = scripts["test"] ? buildPackageScriptCommand(packageManager, "test") : undefined;
+    for (const testFile of relatedTestFiles.slice(0, 5)) {
+        candidates.push({
+            id: `related_${createHash("sha256").update(testFile).digest("hex").slice(0, 8)}`,
+            command: testScript ? `${testScript} -- ${quoteShellArg(testFile)}` : buildLanguageSpecificTestCommand(packageManager, testFile),
+            source: "related_file",
+            reason: `Related test file matched likely impacted work: ${testFile}.`,
+            cwd: workspacePath
+        });
+    }
     if (candidates.length > 0) {
         return candidates;
     }
@@ -3113,6 +3499,74 @@ async function discoverTestCommandCandidates(workspacePath) {
     }
     return getFallbackTestCommandCandidates(workspacePath);
 }
+async function findRelatedTestFiles(workspacePath, session) {
+    let trackedFiles = [];
+    try {
+        trackedFiles = await listTrackedWorkspaceFiles(workspacePath);
+    }
+    catch {
+        return [];
+    }
+    const impactHints = new Set([
+        ...(session.plan?.filesLikelyChanged ?? [])
+            .map((filePath) => normalizeWorkspaceRelativePath(workspacePath, filePath, "skip"))
+            .filter((filePath) => Boolean(filePath))
+            .flatMap((filePath) => [filePath, basename(filePath).replace(/\.[^.]+$/u, "")]),
+        ...tokenizePatchSearchText([
+            session.workItem.key,
+            session.workItem.title,
+            session.workItem.description,
+            ...(session.workItem.labels ?? []),
+            ...(session.workItem.components ?? []),
+            session.plan?.summary
+        ].filter((value) => Boolean(value)).join(" "))
+    ]);
+    return trackedFiles
+        .filter((filePath) => isTestLikeFile(filePath))
+        .map((filePath) => ({
+        filePath,
+        score: scoreRelatedTestFile(filePath, impactHints)
+    }))
+        .filter((candidate) => candidate.score > 0)
+        .sort((left, right) => right.score - left.score || left.filePath.localeCompare(right.filePath))
+        .map((candidate) => candidate.filePath);
+}
+function isTestLikeFile(filePath) {
+    return /(^|\/)(__tests__|tests?|specs?)\//u.test(filePath.toLowerCase())
+        || /\.(test|spec)\.(ts|tsx|js|jsx|mjs|cjs|py|java|kt|go|rs|rb|php|cs)$/u.test(filePath.toLowerCase());
+}
+function scoreRelatedTestFile(filePath, impactHints) {
+    const lower = filePath.toLowerCase();
+    let score = 0;
+    for (const hint of impactHints) {
+        const normalized = hint.toLowerCase();
+        if (normalized.length >= 3 && lower.includes(normalized)) {
+            score += normalized.includes("/") ? 10 : 4;
+        }
+    }
+    if (score === 0) {
+        return 0;
+    }
+    if (/\.(test|spec)\./u.test(lower)) {
+        score += 3;
+    }
+    if (/(__tests__|tests?)\//u.test(lower)) {
+        score += 2;
+    }
+    if (/(snapshot|fixtures|mocks)\//u.test(lower)) {
+        score -= 2;
+    }
+    return score;
+}
+function buildLanguageSpecificTestCommand(packageManager, testFile) {
+    if (/\.(py)$/u.test(testFile)) {
+        return `python -m pytest ${quoteShellArg(testFile)}`;
+    }
+    if (/\.(go)$/u.test(testFile)) {
+        return "go test ./...";
+    }
+    return `${buildPackageScriptCommand(packageManager, "test")} -- ${quoteShellArg(testFile)}`;
+}
 function detectPackageManager(workspacePath) {
     if (existsSync(join(workspacePath, "pnpm-lock.yaml"))) {
         return "pnpm";
@@ -3137,6 +3591,9 @@ function buildPackageScriptCommand(packageManager, scriptName) {
     }
     return `pnpm ${scriptName}`;
 }
+function quoteShellArg(value) {
+    return `'${value.replace(/'/gu, "'\\''")}'`;
+}
 function getFallbackTestCommandCandidates(cwd) {
     return [
         {
@@ -3237,6 +3694,14 @@ async function ensurePullRequestBranch(workspacePath, branch) {
     }
     return branch;
 }
+async function pushPullRequestBranch(workspacePath, branch) {
+    try {
+        await runGitStrict(workspacePath, ["push", "-u", "origin", branch]);
+    }
+    catch (error) {
+        throw new Error(getGitHubCliGuidance("push pull request branch", error));
+    }
+}
 async function createGitHubPullRequestWithCli(workspacePath, draft, branch, draftPr) {
     const ghArgs = [
         "pr",
@@ -3253,14 +3718,19 @@ async function createGitHubPullRequestWithCli(workspacePath, draft, branch, draf
     if (draftPr) {
         ghArgs.push("--draft");
     }
-    return (await execFileStrict("gh", ghArgs, workspacePath)).trim();
+    try {
+        return (await execFileStrict("gh", ghArgs, workspacePath)).trim();
+    }
+    catch (error) {
+        throw new Error(getGitHubCliGuidance("create pull request", error));
+    }
 }
 async function createGitHubPullRequestWithApi(accessToken, draft, branch, draftPr) {
     const repository = parseGitHubRepositoryCoordinates(draft.remoteUrl);
     if (!repository) {
         throw new Error("Unable to determine GitHub owner/repo from the workspace remote URL.");
     }
-    const response = await fetch(`${getGitHubApiBaseUrl()}/repos/${encodeURIComponent(repository.owner)}/${encodeURIComponent(repository.repo)}/pulls`, {
+    const response = await fetchGitHub(`${getGitHubApiBaseUrl()}/repos/${encodeURIComponent(repository.owner)}/${encodeURIComponent(repository.repo)}/pulls`, {
         method: "POST",
         headers: {
             Accept: "application/vnd.github+json",
@@ -3275,14 +3745,22 @@ async function createGitHubPullRequestWithApi(accessToken, draft, branch, draftP
             base: draft.baseBranch,
             draft: draftPr
         })
-    });
+    }, "create pull request");
     if (!response.ok) {
-        const body = await safeResponseText(response);
-        throw new Error(`GitHub PR creation failed: ${response.status} ${response.statusText}${body ? `: ${body}` : ""}`);
+        throw new Error(await getGitHubStatusGuidance(response, "create pull request"));
     }
     const payload = (await response.json());
     return payload.html_url ?? `https://github.com/${repository.owner}/${repository.repo}/pull/${payload.number ?? ""}`;
 }
+function getGitHubCliGuidance(action, error) {
+    const detail = summarizeExecError(error) ?? String(error);
+    return [
+        `GitHub ${action} failed.`,
+        "Check repository write permission, organization SSO authorization, branch protection, remote URL, and whether your token/SSH key can push to origin.",
+        "Run `pome auth github status` and `git remote -v` to verify the account and repository.",
+        `Detail: ${detail}`
+    ].join(" ");
+}
 function parseGitHubRepositoryCoordinates(remoteUrl) {
     if (!remoteUrl) {
         return undefined;
@@ -3331,6 +3809,33 @@ async function safeResponseText(response) {
         return "";
     }
 }
+function summarizeProviderBody(value) {
+    const trimmed = value.trim();
+    if (!trimmed) {
+        return "";
+    }
+    try {
+        const parsed = JSON.parse(trimmed);
+        const errorObject = typeof parsed.error === "object" && parsed.error
+            ? parsed.error
+            : undefined;
+        const messages = [
+            typeof parsed.message === "string" ? parsed.message : undefined,
+            typeof parsed.error === "string" ? parsed.error : undefined,
+            typeof errorObject?.message === "string" ? errorObject.message : undefined,
+            typeof errorObject?.type === "string" ? `type=${errorObject.type}` : undefined,
+            typeof errorObject?.code === "string" ? `code=${errorObject.code}` : undefined,
+            typeof parsed.documentation_url === "string" ? parsed.documentation_url : undefined
+        ].filter((item) => Boolean(item));
+        if (messages.length) {
+            return messages.join("; ").slice(0, 500);
+        }
+    }
+    catch {
+        // Fall through to plain-text summary.
+    }
+    return trimmed.replace(/\s+/gu, " ").slice(0, 500);
+}
 async function hasWorkspaceChanges(workspacePath) {
     const output = await runGit(workspacePath, ["status", "--porcelain"]);
     return output.trim().length > 0;