ubume 0.1.0

package/src/core/providers/registry.ts

@@ -0,0 +1,21 @@
+import { AVAILABLE_BACKENDS, DEFAULT_BACKEND } from "../../config/settings.js";
+import { codexSubprocessProvider } from "./codexSubprocess.js";
+import { openaiNativeProvider } from "./openaiNative.js";
+import type { BackendProvider } from "./types.js";
+
+export const BACKEND_PROVIDERS: BackendProvider[] = [
+  codexSubprocessProvider,
+  openaiNativeProvider,
+];
+
+export function getBackendProvider(id: string): BackendProvider {
+  return (
+    BACKEND_PROVIDERS.find((provider) => provider.id === id) ??
+    BACKEND_PROVIDERS.find((provider) => provider.id === DEFAULT_BACKEND) ??
+    codexSubprocessProvider
+  );
+}
+
+export function listBackendSummaries(): string {
+  return AVAILABLE_BACKENDS.map((backend, index) => `  ${index + 1}. ${backend.label} (${backend.id})`).join("\n");
+}

package/src/core/providers/types.ts

@@ -0,0 +1,91 @@
+import type { AvailableBackend } from "../../config/settings.js";
+import type { ResolvedRuntimeConfig } from "../../config/runtimeConfig.js";
+import type { ProjectInstructions } from "../workspace/projectInstructions.js";
+import type { RunProgressSource, RunToolActivity } from "../../session/types.js";
+import type { ConversationContextCheckpoint, ConversationMessage, LocalHarnessSessionMetadata } from "../workspace/conversationStore.js";
+import type { ProviderImageAttachment } from "../providerRuntime/types.js";
+
+export interface ProviderContextUsage {
+  inputTokens: number;
+  outputTokens: number;
+  contextTokens: number;
+  contextWindow: number | null;
+  exact: boolean;
+  compacted?: boolean;
+}
+
+export interface BackendProgressUpdate {
+  id: string;
+  source: RunProgressSource;
+  text: string;
+}
+
+export type ToolApprovalDecision = "allow-once" | "allow-for-run" | "deny";
+
+export interface ToolApprovalRequest {
+  tool: string;
+  signature: string;
+  command?: string;
+  paths: string[];
+}
+
+export type BackendAuthState = "delegated" | "api-key-required" | "coming-soon";
+
+export interface BackendRunHandlers {
+  onResponse: (response: string) => void;
+  onError: (message: string, rawOutput?: string) => void;
+  /** Called with each new structured thinking/progress update while the process is still running. */
+  onProgress?: (update: BackendProgressUpdate) => void;
+  /** Called with each new assistant content delta while the process is still running. */
+  onAssistantDelta?: (chunk: string) => void;
+  /** Called when the backend indicates the final assistant answer is complete and visible. */
+  onFinalAnswerObserved?: (response: string) => void;
+  /** Called when the backend starts or finishes a tool/shell action during a run. */
+  onToolActivity?: (activity: RunToolActivity) => void;
+  /** Requests consent before a local model performs a mutating action. */
+  onToolApproval?: (request: ToolApprovalRequest) => Promise<ToolApprovalDecision>;
+  /** Persists invisible rolling memory used only by Local context-window rollover. */
+  onLocalContextCheckpoint?: (checkpoint: ConversationContextCheckpoint) => void;
+  /** Persists the opaque DeepSeek Harness session backing a Local conversation. */
+  onLocalHarnessSession?: (session: LocalHarnessSessionMetadata | null, sessionId: string) => void;
+  /** Reports authoritative provider token usage when available. */
+  onContextUsage?: (usage: ProviderContextUsage) => void;
+  /** Called around backend child-process lifecycle boundaries. */
+  onProcessLifecycle?: (event: "before-spawn" | "spawned" | "exit" | "error" | "cleanup") => void;
+  /** Lightweight hooks used only by headless benchmark diagnostics. */
+  benchmarkHooks?: {
+    onProviderPromptPrepared?: (context: { policy: "raw" | "wrapped"; characterCount: number }) => void;
+    onProviderPrepStart?: () => void;
+    onProviderPrepComplete?: () => void;
+    onCodexProcessSpawned?: (context: { executable: string; argv: string[] }) => void;
+    onFirstStdout?: (observed?: boolean) => void;
+    onFirstStderr?: (observed?: boolean) => void;
+    onCodexProcessExit?: (exitCode: number | null) => void;
+    onCleanupStart?: () => void;
+    onCleanupComplete?: (context: { skipped: boolean }) => void;
+  };
+}
+
+export interface BackendProvider {
+  id: AvailableBackend;
+  label: string;
+  description: string;
+  authState: BackendAuthState;
+  authLabel: string;
+  statusMessage: string;
+  supportsModels: (model: string) => boolean;
+  run?: (
+    prompt: string,
+    options: {
+      runtime: ResolvedRuntimeConfig;
+      workspaceRoot: string;
+      projectInstructions?: ProjectInstructions | null;
+      promptPolicy?: "raw" | "wrapped";
+      runIntent?: "normal" | "plan" | "approved-execution";
+      conversationHistory?: readonly ConversationMessage[];
+      localContextCheckpoint?: ConversationContextCheckpoint;
+      imageAttachments?: readonly ProviderImageAttachment[];
+    },
+    handlers: BackendRunHandlers,
+  ) => () => void;
+}

package/src/core/shared/attachments.ts

@@ -0,0 +1,101 @@
+import { access, copyFile, mkdir, stat, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import {
+  isSkippedExternalDependencyPath,
+  normalizeDiagnosticPath,
+} from "../workspace/workspaceGuard.js";
+
+export const IMAGE_EXTENSIONS = new Set([
+  ".png",
+  ".jpg",
+  ".jpeg",
+  ".gif",
+  ".webp",
+  ".bmp",
+  ".tiff",
+  ".tif",
+  ".svg",
+]);
+
+export function isImageFile(filePath: string): boolean {
+  return IMAGE_EXTENSIONS.has(path.extname(filePath).toLowerCase());
+}
+
+async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function resolveAttachmentDestPath(
+  srcPath: string,
+  attachmentsDir: string,
+): Promise<string> {
+  const ext = path.extname(srcPath);
+  const base = path.basename(srcPath, ext);
+  let dest = path.join(attachmentsDir, `${base}${ext}`);
+  let counter = 1;
+  while (await fileExists(dest)) {
+    dest = path.join(attachmentsDir, `${base}-${counter}${ext}`);
+    counter++;
+  }
+  return dest;
+}
+
+export async function importExternalFile(
+  srcPath: string,
+  attachmentsDir: string,
+): Promise<string | null> {
+  const normalized = normalizeDiagnosticPath(srcPath);
+
+  if (isSkippedExternalDependencyPath(normalized)) {
+    return null;
+  }
+
+  try {
+    if (!existsSync(normalized)) {
+      return null;
+    }
+    const s = await stat(normalized);
+    if (!s.isFile()) {
+      return null;
+    }
+  } catch {
+    return null;
+  }
+
+  await mkdir(attachmentsDir, { recursive: true });
+  const destPath = await resolveAttachmentDestPath(normalized, attachmentsDir);
+  await copyFile(normalized, destPath);
+  return destPath;
+}
+
+export async function saveClipboardImage(data: Uint8Array, attachmentsDir: string): Promise<string> {
+  await mkdir(attachmentsDir, { recursive: true });
+  const destPath = await resolveAttachmentDestPath("clipboard-image.png", attachmentsDir);
+  await writeFile(destPath, data, { mode: 0o600 });
+  return destPath;
+}
+
+export function rewritePromptWithImportedPaths(
+  prompt: string,
+  replacements: Array<{ rawPath: string; replacementPath: string }>,
+): string {
+  let result = prompt;
+  for (const { rawPath, replacementPath } of replacements) {
+    const needsQuotes = /\s/.test(replacementPath);
+    const quotedReplacement = needsQuotes
+      ? `"${replacementPath}"`
+      : replacementPath;
+    // Replace quoted forms first so the unquoted pass doesn't double-replace
+    result = result.split(`"${rawPath}"`).join(quotedReplacement);
+    result = result.split(`'${rawPath}'`).join(quotedReplacement);
+    // Replace any remaining unquoted occurrences
+    result = result.split(rawPath).join(quotedReplacement);
+  }
+  return result;
+}

package/src/core/shared/cleanupFastFail.ts

@@ -0,0 +1,67 @@
+import type { RunToolActivity } from "../../session/types.js";
+
+const DELETE_COMMAND_PATTERN =
+  /(?:^|[\s;&|])(?:remove-item|rm|rmdir|del|erase|unlink)\b/i;
+
+const BLOCKED_DELETE_CAUSE_PATTERNS: Array<{ pattern: RegExp; label: string }> = [
+  { pattern: /(?:^|[\\/])\.git[\\/][^\s"'`]*\.lock\b|(?:^|[\\/])?config\.lock\b|\.lock\b/i, label: "lock artifact" },
+  { pattern: /\bEACCES\b/i, label: "access denied" },
+  { pattern: /\bEPERM\b/i, label: "permission denied" },
+  { pattern: /\bEBUSY\b/i, label: "file is busy or locked" },
+  { pattern: /access(?:\s+to\s+the\s+path)?\s+.*?\s+denied|access is denied/i, label: "access denied" },
+  { pattern: /permission denied|operation not permitted/i, label: "permission denied" },
+  { pattern: /being used by another process|file is in use|resource busy|text file busy|device or resource busy/i, label: "file is locked or in use" },
+];
+
+const PATH_PATTERNS = [
+  /Access to the path ['"]([^'"]+)['"] is denied/i,
+  /(?:EPERM|EACCES|EBUSY)[^,\n\r]*,\s*(?:unlink|rmdir|rm|open|scandir)\s+['"]?([^'"\n\r]+)['"]?/i,
+  /(?:cannot|can't|failed to|unable to)\s+(?:remove|delete|unlink|rmdir)[^'"\n\r]*['"]([^'"]+)['"]/i,
+  /(?:being used by another process|file is in use|permission denied|access is denied)[^'"\n\r]*['"]([^'"]+)['"]/i,
+  /((?:\.git[\\/])?[^\s"'`]+\.lock)\b/i,
+];
+
+function normalizeText(value: string | null | undefined): string {
+  return (value ?? "").replace(/\r\n/g, "\n").replace(/\r/g, "\n").trim();
+}
+
+function isDeleteCommand(command: string): boolean {
+  return DELETE_COMMAND_PATTERN.test(command);
+}
+
+function findCause(text: string): string | null {
+  for (const { pattern, label } of BLOCKED_DELETE_CAUSE_PATTERNS) {
+    if (pattern.test(text)) return label;
+  }
+  return null;
+}
+
+function findBlockedPath(text: string): string | null {
+  for (const pattern of PATH_PATTERNS) {
+    const match = pattern.exec(text);
+    const path = match?.[1]?.trim();
+    if (path) return path.replace(/[.,;:]+$/g, "");
+  }
+  return null;
+}
+
+export function getBlockedCleanupFailure(activity: RunToolActivity): string | null {
+  if (activity.status !== "failed") return null;
+
+  const command = normalizeText(activity.command);
+  const summary = normalizeText(activity.summary);
+  const combined = [command, summary].filter(Boolean).join("\n");
+  if (!command || !isDeleteCommand(command)) return null;
+
+  const cause = findCause(combined);
+  if (!cause) return null;
+
+  const blockedPath = findBlockedPath(combined);
+  const target = blockedPath ? `\nBlocked item: ${blockedPath}` : "";
+  return [
+    "Cleanup stopped because a safe generated artifact could not be deleted.",
+    `Cause: ${cause}.`,
+    target,
+    "Ubume stopped after the first clear blocked-delete signal to avoid retrying a doomed cleanup.",
+  ].filter(Boolean).join("\n");
+}

package/src/core/shared/clipboard.ts

@@ -0,0 +1,24 @@
+import { spawn } from "child_process";
+import { platform } from "os";
+
+function trySpawn(cmd: string, args: string[], text: string): Promise<boolean> {
+  return new Promise((resolve) => {
+    const proc = spawn(cmd, args, { stdio: ["pipe", "ignore", "ignore"] });
+    proc.on("error", () => resolve(false));
+    proc.on("close", (code) => resolve(code === 0));
+    proc.stdin?.write(text);
+    proc.stdin?.end();
+  });
+}
+
+export async function copyToClipboard(text: string): Promise<boolean> {
+  const os = platform();
+
+  if (os === "win32") return trySpawn("clip", [], text);
+  if (os === "darwin") return trySpawn("pbcopy", [], text);
+
+  // Linux: try xclip, fall back to xsel
+  const ok = await trySpawn("xclip", ["-selection", "clipboard"], text);
+  if (ok) return true;
+  return trySpawn("xsel", ["--clipboard", "--input"], text);
+}

package/src/core/shared/clipboardImage.ts

@@ -0,0 +1,111 @@
+import { execFile } from "node:child_process";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+export const MAX_CLIPBOARD_IMAGE_BYTES = 20 * 1024 * 1024;
+
+export interface ClipboardImage {
+  data: Buffer;
+  mediaType: "image/png";
+}
+
+type CommandRunner = (file: string, args: string[]) => Promise<Buffer>;
+
+function runBuffer(file: string, args: string[]): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    execFile(file, args, { encoding: "buffer", maxBuffer: MAX_CLIPBOARD_IMAGE_BYTES + 1024 }, (error, stdout) => {
+      if (error) reject(error);
+      else resolve(Buffer.from(stdout));
+    });
+  });
+}
+
+function isPng(data: Buffer): boolean {
+  return data.length >= 8 && data.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]));
+}
+
+function validatePng(data: Buffer): ClipboardImage {
+  if (!isPng(data)) throw new Error("The clipboard does not contain a supported PNG image.");
+  if (data.length > MAX_CLIPBOARD_IMAGE_BYTES) throw new Error("The clipboard image exceeds the 20 MiB limit.");
+  return { data, mediaType: "image/png" };
+}
+
+async function firstSuccessful(attempts: Array<() => Promise<Buffer>>): Promise<Buffer> {
+  for (const attempt of attempts) {
+    try {
+      const data = await attempt();
+      if (data.length > 0) return data;
+    } catch {
+      // Try the next platform-appropriate clipboard bridge.
+    }
+  }
+  throw new Error("No PNG image is available on the system clipboard.");
+}
+
+async function readMacClipboard(run: CommandRunner): Promise<Buffer> {
+  try {
+    return await run("pngpaste", ["-"]);
+  } catch {
+    const tempDir = await mkdtemp(join(tmpdir(), "ubume-clipboard-"));
+    const outputPath = join(tempDir, "clipboard.png");
+    const applePath = outputPath.replace(/\\/g, "\\\\").replace(/\"/g, '\\"');
+    try {
+      await run("osascript", [
+        "-e", "set imageData to the clipboard as «class PNGf»",
+        "-e", `set imageFile to open for access POSIX file \"${applePath}\" with write permission`,
+        "-e", "set eof imageFile to 0",
+        "-e", "write imageData to imageFile",
+        "-e", "close access imageFile",
+      ]);
+      return await readFile(outputPath);
+    } finally {
+      await rm(tempDir, { recursive: true, force: true });
+    }
+  }
+}
+
+const WINDOWS_CLIPBOARD_SCRIPT = [
+  "Add-Type -AssemblyName System.Windows.Forms;",
+  "Add-Type -AssemblyName System.Drawing;",
+  "$image=[System.Windows.Forms.Clipboard]::GetImage();",
+  "if ($null -eq $image) { exit 2 };",
+  "$stream=New-Object System.IO.MemoryStream;",
+  "$image.Save($stream,[System.Drawing.Imaging.ImageFormat]::Png);",
+  "[Console]::Out.Write([Convert]::ToBase64String($stream.ToArray()));",
+].join("");
+
+async function readWindowsClipboard(run: CommandRunner, executable = "powershell.exe"): Promise<Buffer> {
+  const encoded = await run(executable, ["-NoProfile", "-NonInteractive", "-STA", "-Command", WINDOWS_CLIPBOARD_SCRIPT]);
+  return Buffer.from(encoded.toString("utf8").trim(), "base64");
+}
+
+export async function readClipboardImage(options: {
+  platform?: NodeJS.Platform;
+  env?: NodeJS.ProcessEnv;
+  run?: CommandRunner;
+} = {}): Promise<ClipboardImage> {
+  const targetPlatform = options.platform ?? process.platform;
+  const env = options.env ?? process.env;
+  const run = options.run ?? runBuffer;
+  let data: Buffer;
+
+  if (targetPlatform === "win32") {
+    data = await readWindowsClipboard(run);
+  } else if (targetPlatform === "darwin") {
+    data = await readMacClipboard(run);
+  } else if (env.WSL_DISTRO_NAME || env.WSL_INTEROP) {
+    data = await firstSuccessful([
+      () => readWindowsClipboard(run),
+      () => run("wl-paste", ["--no-newline", "--type", "image/png"]),
+      () => run("xclip", ["-selection", "clipboard", "-t", "image/png", "-o"]),
+    ]);
+  } else {
+    data = await firstSuccessful([
+      () => run("wl-paste", ["--no-newline", "--type", "image/png"]),
+      () => run("xclip", ["-selection", "clipboard", "-t", "image/png", "-o"]),
+    ]);
+  }
+
+  return validatePng(data);
+}

package/src/core/shared/githubDiagnostics.ts

@@ -0,0 +1,222 @@
+import { execSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+export interface RepoIdentity {
+  owner: string;
+  repo: string;
+  provider: "github" | "other";
+  remoteUrl: string;
+}
+
+export interface DiagnosticResult {
+  path: string;
+  status: "PASS" | "FAIL" | "PARTIAL";
+  evidence: string;
+  blocker: string | null;
+  recommendedUse: boolean;
+}
+
+export interface DiagnosticsReport {
+  repo: RepoIdentity | null;
+  defaultBranch: string | null;
+  ghCliUser: string | null;
+  connectorUser: string | null;
+  paths: {
+    ghCli: DiagnosticResult;
+    localGit: DiagnosticResult;
+    localGitWrite: DiagnosticResult;
+    connector: DiagnosticResult;
+  };
+  recommendedFlow:
+    | "Local Git + GH CLI"
+    | "Local Git + connector PR creation"
+    | "Connector-only"
+    | "Cannot publish yet";
+}
+
+export function parseRepoIdentity(remoteUrl: string | undefined | null): RepoIdentity | null {
+  if (!remoteUrl) return null;
+
+  const url = remoteUrl.trim();
+
+  // HTTPS: https://github.com/owner/repo.git or https://github.com/owner/repo
+  const httpsMatch = url.match(/^https?:\/\/(?:www\.)?github\.com\/([^/]+)\/([^/.]+?)(?:\.git)?\/?$/i);
+  if (httpsMatch) {
+    return {
+      owner: httpsMatch[1],
+      repo: httpsMatch[2],
+      provider: "github",
+      remoteUrl: url,
+    };
+  }
+
+  // SSH: git@github.com:owner/repo.git or ssh://git@github.com/owner/repo.git
+  const sshMatch = url.match(/^(?:ssh:\/\/)?git@github\.com[:\/]([^/]+)\/([^/.]+?)(?:\.git)?\/?$/i);
+  if (sshMatch) {
+    return {
+      owner: sshMatch[1],
+      repo: sshMatch[2],
+      provider: "github",
+      remoteUrl: url,
+    };
+  }
+
+  return {
+    owner: "",
+    repo: "",
+    provider: "other",
+    remoteUrl: url,
+  };
+}
+
+export function getLocalGitRemoteUrl(): string | null {
+  try {
+    return execSync("git remote get-url origin", { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+  } catch {
+    return null;
+  }
+}
+
+export function checkGhCli(): DiagnosticResult {
+  const result: DiagnosticResult = {
+    path: "GH CLI",
+    status: "FAIL",
+    evidence: "",
+    blocker: null,
+    recommendedUse: false,
+  };
+
+  try {
+    const version = execSync("gh --version", { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).split("\n")[0];
+    result.evidence = version ?? "Unknown version";
+  } catch {
+    result.blocker = "gh CLI not installed or not in PATH";
+    return result;
+  }
+
+  try {
+    // gh auth status output format is not structured JSON; pattern-match on known strings.
+    const authStatus = execSync("gh auth status", { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+    result.evidence += " | Authenticated";
+    if (authStatus.includes("Token scopes")) {
+      const scopes = authStatus.match(/Token scopes: (.*)/)?.[1];
+      if (scopes && !scopes.includes("repo")) {
+        result.status = "PARTIAL";
+        result.blocker = "Token missing 'repo' scope";
+      } else {
+        result.status = "PASS";
+      }
+    } else {
+      result.status = "PASS";
+    }
+  } catch {
+    result.blocker = "Not logged in to GitHub CLI";
+  }
+
+  return result;
+}
+
+export function checkLocalGitRemote(): DiagnosticResult {
+  const result: DiagnosticResult = {
+    path: "Local git remote",
+    status: "FAIL",
+    evidence: "",
+    blocker: null,
+    recommendedUse: false,
+  };
+
+  try {
+    const remote = execSync("git remote -v", { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).split("\n")[0];
+    result.evidence = remote ?? "No remote found";
+
+    execSync("git ls-remote origin HEAD", { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+    result.status = "PASS";
+  } catch {
+    result.blocker = "Cannot reach origin remote (check connectivity or remote URL)";
+  }
+
+  return result;
+}
+
+export function checkLocalGitWrite(): DiagnosticResult {
+  const result: DiagnosticResult = {
+    path: "Local .git write",
+    status: "FAIL",
+    evidence: "",
+    blocker: null,
+    recommendedUse: false,
+  };
+
+  const indexLock = join(".git", "index.lock");
+  if (existsSync(indexLock)) {
+    result.blocker = ".git/index.lock exists (git process might be running)";
+    return result;
+  }
+
+  try {
+    execSync("git update-ref refs/heads/ubume-diagnostic-lock-test HEAD", { stdio: "ignore" });
+    execSync("git update-ref -d refs/heads/ubume-diagnostic-lock-test", { stdio: "ignore" });
+    result.status = "PASS";
+    result.evidence = "Can create/delete refs";
+  } catch (error) {
+    result.blocker = "Failed to create/delete ref lock (permission denied?)";
+    result.evidence = error instanceof Error ? error.message : String(error);
+  }
+
+  return result;
+}
+
+export function classifyDiagnostics(
+  repo: RepoIdentity | null,
+  ghCli: DiagnosticResult,
+  localGit: DiagnosticResult,
+  localGitWrite: DiagnosticResult,
+  connector: DiagnosticResult
+): DiagnosticsReport["recommendedFlow"] {
+  const isGitHub = repo?.provider === "github";
+  if (!isGitHub) return "Cannot publish yet";
+
+  const ghCliOk = ghCli.status === "PASS";
+  const gitRemoteOk = localGit.status === "PASS";
+  const gitWriteOk = localGitWrite.status === "PASS";
+  const connectorOk = connector.status === "PASS" || (connector.status === "PARTIAL" && !connector.blocker?.includes("auth"));
+
+  if (ghCliOk && gitRemoteOk && gitWriteOk) {
+    return "Local Git + GH CLI";
+  }
+
+  if (connectorOk) {
+    if (gitWriteOk && gitRemoteOk) {
+      return "Local Git + connector PR creation";
+    }
+    return "Connector-only";
+  }
+
+  return "Cannot publish yet";
+}
+
+export function printDiagnosticsTable(report: DiagnosticsReport) {
+  const rows = [
+    report.paths.ghCli,
+    report.paths.localGit,
+    report.paths.localGitWrite,
+    report.paths.connector,
+  ];
+
+  console.log("\nPath                | Status  | Evidence                      | Blocker");
+  console.log("--------------------|---------|-------------------------------|---------------------------");
+  for (const row of rows) {
+    const p = row.path.padEnd(20);
+    const s = row.status.padEnd(8);
+    const e = (row.evidence || "").substring(0, 30).padEnd(30);
+    const b = row.blocker || "";
+    console.log(`${p}| ${s}| ${e}| ${b}`);
+  }
+
+  console.log(`\nResolved repo: ${report.repo ? `${report.repo.owner}/${report.repo.repo}` : "Unknown"}`);
+  console.log(`Default branch: ${report.defaultBranch || "Unknown"}`);
+  console.log(`Authenticated GH CLI user: ${report.ghCliUser || "Unknown"}`);
+  console.log(`Authenticated connector user: ${report.connectorUser || "Unknown"}`);
+  console.log(`Recommended PR flow: ${report.recommendedFlow}`);
+}

package/src/core/shared/hollowResponseFormat.ts

@@ -0,0 +1,39 @@
+import type { HollowResponseResult } from "../codex/codexPrompt.js";
+
+const MESSAGES: Record<string, [string, string]> = {
+  greeting: [
+    "Task not executed — backend returned a generic greeting.",
+    "Retry with a more specific instruction.",
+  ],
+  filler: [
+    "Task not executed — backend acknowledged without acting.",
+    "Retry with a more specific instruction.",
+  ],
+  clarification: [
+    "Task not executed — backend asked for clarification instead of acting.",
+    "Rephrase with more detail, or switch to suggest mode.",
+  ],
+  "short-no-action": [
+    "No action confirmed — response too brief for a write-intent prompt.",
+    "Verify workspace files manually, or retry.",
+  ],
+};
+
+export function formatHollowResponse(
+  result: HollowResponseResult,
+  rawResponse?: string,
+  verbose?: boolean,
+): string {
+  const lines = MESSAGES[result.kind] ?? [
+    "Task not executed — unexpected backend response.",
+    "Retry with a more specific instruction.",
+  ];
+
+  let output = lines.join("\n");
+
+  if (verbose && rawResponse) {
+    output += `\n\nBackend response: ${rawResponse}`;
+  }
+
+  return output;
+}