@oar-sh/oar 0.9.0

package/server/services/drives-path-helpers.mjs

@@ -0,0 +1,66 @@
+import path from 'node:path';
+
+import { normalizeDriveLetterOnlyPath } from './workspace-root-path-policy.mjs';
+
+// ---------------------------------------------------------------------------
+// Windows drive path helpers
+// ---------------------------------------------------------------------------
+
+export function normalizeDriveAbsolutePath(rawPath) {
+  const value = String(rawPath || '').trim();
+  if (!value) return '';
+  let decoded = value;
+  try {
+    decoded = decodeURIComponent(value);
+  } catch {
+    return '';
+  }
+  const withoutNulls = decoded.replace(/\0/g, '');
+  let normalized = withoutNulls
+    .replace(/\//g, '\\')
+    .replace(/\\+/g, '\\')
+    .trim();
+  if (!normalized) return '';
+  normalized = normalizeDriveLetterOnlyPath(normalized);
+  if (!/^[A-Za-z]:\\/.test(normalized)) return '';
+  normalized = path.win32.normalize(normalized);
+  if (!/^[A-Za-z]:\\/.test(normalized)) return '';
+  const drive = `${normalized.slice(0, 1).toUpperCase()}:`;
+  const rest = normalized.slice(3).replace(/^\\+/, '');
+  return rest ? `${drive}\\${rest}` : `${drive}\\`;
+}
+
+export function driveRootFromAbsolutePath(absolutePath) {
+  const normalized = normalizeDriveAbsolutePath(absolutePath);
+  if (!normalized) return '';
+  return `${normalized.slice(0, 1).toUpperCase()}:\\`;
+}
+
+export function toDriveWebPath(absolutePath) {
+  const normalized = normalizeDriveAbsolutePath(absolutePath);
+  if (!normalized) return '';
+  const drive = `${normalized.slice(0, 1).toUpperCase()}:`;
+  const rest = normalized.slice(3).replace(/\\/g, '/');
+  return rest ? `${drive}/${rest}` : drive;
+}
+
+// ---------------------------------------------------------------------------
+// Linux absolute path helper
+// ---------------------------------------------------------------------------
+
+export function normalizeLinuxAbsolutePath(rawPath) {
+  const value = String(rawPath || '').trim();
+  if (!value) return '';
+  let decoded = value;
+  try {
+    decoded = decodeURIComponent(value);
+  } catch {
+    return '';
+  }
+  const withoutNulls = decoded.replace(/\0/g, '');
+  // path.posix.normalize resolves any '..' segments; we only need to ensure
+  // the result is absolute (i.e. still under '/').
+  const normalized = path.posix.normalize(withoutNulls.replace(/\\/g, '/'));
+  if (!normalized.startsWith('/')) return '';
+  return normalized;
+}

package/server/services/fixtures/claude-auth-stub.sh

@@ -0,0 +1,62 @@
+#!/bin/sh
+# Stand-in for the `claude` CLI auth subcommands, injected through
+# COPILOT_WEB_RELAY_CLAUDE_AUTH_BIN so the auth service can be exercised without
+# touching the host's real Claude login.
+#
+# Mirrors the shapes observed on CLI 2.1.247:
+#   auth status --json -> one line of JSON
+#   auth login         -> browser notice, an OSC-8 + SGR wrapped authorize URL,
+#                         then `Paste code here if prompted > ` and a blocking read
+#   auth logout        -> removes the credentials file
+#
+# Fake credentials file path comes from CLAUDE_AUTH_STUB_CRED_FILE; "logged in"
+# means that file exists.
+
+CRED_FILE="${CLAUDE_AUTH_STUB_CRED_FILE:-}"
+AUTH_URL="${CLAUDE_AUTH_STUB_URL:-https://claude.com/oauth/authorize?code=true&client_id=stub-client&code_challenge=Xk3nQ7pLm2vB8sT1wY6zR0aC5dF9gH4jK7lN2oP3qS8&redirect_uri=https%3A%2F%2Fplatform.claude.com%2Foauth%2Fcode%2Fcallback}"
+
+command="$1 $2"
+
+case "$command" in
+  "auth status")
+    if [ -n "$CRED_FILE" ] && [ -f "$CRED_FILE" ]; then
+      printf '{"loggedIn":true,"authMethod":"claudeai","apiProvider":null,"email":"stub@example.com","orgId":"org_stub","orgName":"Stub Org","subscriptionType":"max"}\n'
+    else
+      printf '{"loggedIn":false,"authMethod":null,"apiProvider":null,"email":null,"orgId":null,"orgName":null,"subscriptionType":null}\n'
+    fi
+    exit 0
+    ;;
+  "auth login")
+    printf 'Opening browser to sign in…\n'
+    # OSC-8 hyperlink (target + visible label) wrapped in SGR colour codes, the
+    # exact shape the real CLI emits under a PTY.
+    printf 'If the browser did not open, visit: \033]8;;%s\033\\\033[4;34m%s\033[0m\033]8;;\033\\\n' "$AUTH_URL" "$AUTH_URL"
+    printf '\033[2mPaste code here if prompted > \033[0m'
+    if ! read -r submitted_code; then
+      printf '\nAborted.\n'
+      exit 1
+    fi
+    if [ "$submitted_code" = "goodcode" ]; then
+      if [ -n "$CRED_FILE" ]; then
+        # Deliberately short fake tokens: anything with 20+ characters after
+        # `sk-ant-` trips the secret scanner in server/test-hygiene.test.mjs.
+        printf '{"claudeAiOauth":{"accessToken":"sk-ant-oat01-stub","refreshToken":"sk-ant-ort01-stub"}}\n' > "$CRED_FILE"
+      fi
+      printf '\nLogin successful. Logged in as stub@example.com\n'
+      exit 0
+    fi
+    printf '\nOAuth error: invalid_grant - the authorization code is invalid or has expired.\n' >&2
+    exit 1
+    ;;
+  "auth logout")
+    if [ -n "$CRED_FILE" ]; then
+      rm -f "$CRED_FILE"
+    fi
+    printf 'Logged out.\n'
+    exit 0
+    ;;
+  *)
+    printf 'claude-auth-stub: unsupported command: %s\n' "$*" >&2
+    exit 2
+    ;;
+esac

package/server/services/fixtures/cli-install-stub.sh

@@ -0,0 +1,75 @@
+#!/bin/sh
+# Stand-in for a vendor CLI installer, injected through
+# COPILOT_WEB_RELAY_CLI_INSTALL_COMMAND so the install flow can be exercised end
+# to end without ever fetching from x.ai / claude.ai or writing to the host's
+# real bin directories.
+#
+# The install service calls it as:  cli-install-stub.sh <provider> <action>
+# (both values come from the frozen descriptor table, never from a request
+# body). It prints installer-shaped progress, then writes a fake binary into
+# CLI_INSTALL_STUB_BIN_DIR — which the relay is pointed at through
+# COPILOT_WEB_RELAY_CLI_BIN_DIR — so the resolve -> bind -> broadcast chain runs
+# against something real.
+#
+#   CLI_INSTALL_STUB_BIN_DIR   where the fake binary lands (required)
+#   CLI_INSTALL_STUB_VERSION   version the fake binary reports (default 9.9.9)
+#   CLI_INSTALL_STUB_FAIL      non-empty -> print an error and exit 1
+#   CLI_INSTALL_STUB_SLEEP     seconds to stall mid-install (cancel/timeout tests)
+
+provider="$1"
+action="$2"
+bin_dir="${CLI_INSTALL_STUB_BIN_DIR:-}"
+version="${CLI_INSTALL_STUB_VERSION:-9.9.9}"
+
+printf 'Installing %s (%s)…\n' "$provider" "$action"
+printf 'Resolving latest release for linux-x86_64\n'
+
+if [ -n "${CLI_INSTALL_STUB_SLEEP:-}" ]; then
+  sleep "$CLI_INSTALL_STUB_SLEEP"
+fi
+
+if [ -n "${CLI_INSTALL_STUB_FAIL:-}" ]; then
+  printf 'error: download failed (stub)\n' >&2
+  exit 1
+fi
+
+if [ -z "$bin_dir" ]; then
+  printf 'cli-install-stub: CLI_INSTALL_STUB_BIN_DIR is not set\n' >&2
+  exit 2
+fi
+
+mkdir -p "$bin_dir"
+target="$bin_dir/$provider"
+
+# The fake binary answers exactly the probes cli-install-service runs: the
+# version banner in each descriptor's shape, `update --check --json` for Grok,
+# and `doctor` for Claude.
+cat > "$target" <<STUB
+#!/bin/sh
+case "\$1 \$2" in
+  "--version ")
+    case "$provider" in
+      grok)    printf 'grok %s (stubcommit) [stable]\n' "$version" ;;
+      claude)  printf '%s (Claude Code)\n' "$version" ;;
+      *)       printf '%s\n' "$version" ;;
+    esac
+    exit 0
+    ;;
+  "update --check")
+    printf '{"currentVersion":"%s","latestVersion":"%s","updateAvailable":false,"installer":"internal","channel":"stable","autoUpdate":null,"error":null}\n' "$version" "$version"
+    exit 0
+    ;;
+  "doctor ")
+    printf 'Running: native (%s)\n' "$version"
+    printf 'Path: %s\n' "$target"
+    printf 'Auto-updates: enabled\n'
+    exit 0
+    ;;
+esac
+printf 'cli-stub: unsupported command: %s\n' "\$*" >&2
+exit 2
+STUB
+chmod +x "$target"
+
+printf 'Installed %s %s to %s\n' "$provider" "$version" "$target"
+exit 0

package/server/services/fixtures/grok-stub.sh

@@ -0,0 +1,86 @@
+#!/bin/sh
+# Stand-in for the `grok` CLI, injected through GROK_CLI_COMMAND so the auth
+# service (and the CLI install/probe path) can be exercised without touching the
+# host's real Grok login.
+#
+# Mirrors the shapes probed live on Grok Build 1.0.13 (2026-08-31):
+#   --version            -> `grok 1.0.13 (5e9a58528b76)`
+#   update --check --json-> the machine-readable update payload
+#   login --device-auth  -> a device URL carrying the code, the code again on its
+#                           own line, one grey (SGR 90) warning line, then
+#                           `Waiting for authorization...` and a poll loop. No
+#                           TTY, no stdin read: the real CLI ignores stdin and
+#                           exits by itself once the browser authorises.
+#   logout               -> removes the fake auth.json
+#
+# The poll loop stands in for the browser: it exits 0 when GROK_STUB_SUCCESS_SENTINEL
+# appears (writing the fake auth store) and non-zero when GROK_STUB_FAILURE_SENTINEL
+# does. "Logged in" means GROK_STUB_AUTH_FILE exists, matching what
+# readGrokCliAuthKey() actually looks at.
+
+set -u
+
+VERSION="${GROK_STUB_VERSION:-1.0.13}"
+AUTH_FILE="${GROK_STUB_AUTH_FILE:-}"
+DEVICE_CODE="${GROK_STUB_DEVICE_CODE:-D7SV-M4TR}"
+DEVICE_URL="${GROK_STUB_DEVICE_URL:-https://accounts.x.ai/oauth2/device?user_code=${DEVICE_CODE}}"
+SUCCESS_SENTINEL="${GROK_STUB_SUCCESS_SENTINEL:-}"
+FAILURE_SENTINEL="${GROK_STUB_FAILURE_SENTINEL:-}"
+TIMEOUT_SECONDS="${GROK_STUB_TIMEOUT_SECONDS:-60}"
+POLL_SECONDS="${GROK_STUB_POLL_SECONDS:-0.2}"
+UPDATE_AVAILABLE="${GROK_STUB_UPDATE_AVAILABLE:-false}"
+LATEST_VERSION="${GROK_STUB_LATEST_VERSION:-$VERSION}"
+
+command="${1:-} ${2:-}"
+
+case "$command" in
+  "--version "*|"--version")
+    printf 'grok %s (5e9a58528b76)\n' "$VERSION"
+    exit 0
+    ;;
+  "update --check")
+    printf '{"currentVersion":"%s","latestVersion":"%s","updateAvailable":%s,"installer":"internal","channel":"stable","autoUpdate":null,"error":null}\n' \
+      "$VERSION" "$LATEST_VERSION" "$UPDATE_AVAILABLE"
+    exit 0
+    ;;
+  "login --device-auth")
+    # Byte-for-byte the banner the real CLI printed under piped stdio, including
+    # the blank lines and the one grey warning line — the escape-stripping in the
+    # URL/code scrape is tested against exactly this.
+    printf '\nTo sign in, open this URL in your browser:\n\n  %s\n\n' "$DEVICE_URL"
+    printf '  (Could not open browser automatically — open the URL above manually.)\n\n'
+    printf 'Confirm this code in your browser:\n\n  %s\n\n' "$DEVICE_CODE"
+    printf '\033[90mOnly continue with a code you requested. Do not share it with anyone.\033[0m\n\n'
+    printf 'Waiting for authorization...\n'
+    deadline=$(( $(date +%s) + TIMEOUT_SECONDS ))
+    while [ "$(date +%s)" -le "$deadline" ]; do
+      if [ -n "$FAILURE_SENTINEL" ] && [ -f "$FAILURE_SENTINEL" ]; then
+        printf '\nAuthorization failed: the device code expired.\n' >&2
+        exit 1
+      fi
+      if [ -n "$SUCCESS_SENTINEL" ] && [ -f "$SUCCESS_SENTINEL" ]; then
+        if [ -n "$AUTH_FILE" ]; then
+          # Deliberately short fake key: anything 32+ characters long trips the
+          # secret scanner in server/test-hygiene.test.mjs.
+          printf '{"https://auth.x.ai::stub":{"key":"grok-stub-key","create_time":"2026-08-31T00:00:00Z","expires_at":"2099-01-01T00:00:00Z"}}\n' > "$AUTH_FILE"
+        fi
+        printf '\nSigned in.\n'
+        exit 0
+      fi
+      sleep "$POLL_SECONDS"
+    done
+    printf '\nTimed out waiting for authorization.\n' >&2
+    exit 1
+    ;;
+  "logout "*|"logout")
+    if [ -n "$AUTH_FILE" ]; then
+      rm -f "$AUTH_FILE"
+    fi
+    printf 'Signed out.\n'
+    exit 0
+    ;;
+  *)
+    printf 'grok-stub: unsupported command: %s\n' "$*" >&2
+    exit 2
+    ;;
+esac

package/server/services/generated-image-cleanup-service.mjs

@@ -0,0 +1,114 @@
+'use strict';
+
+import fs from 'fs';
+import path from 'path';
+
+function normalizeStorageSegment(value, fallback = 'item') {
+  const text = String(value || '').trim();
+  const compact = text.replace(/[^a-zA-Z0-9_-]+/g, '-').replace(/^-+|-+$/g, '');
+  return compact.slice(0, 96) || fallback;
+}
+
+function parseMessageAttachments(rawAttachments, { parseAttachments, hydrateAttachment } = {}) {
+  let attachments = [];
+  if (typeof parseAttachments === 'function') {
+    attachments = parseAttachments(rawAttachments);
+  } else {
+    try {
+      attachments = JSON.parse(rawAttachments || '[]');
+    } catch {
+      attachments = [];
+    }
+  }
+  if (!Array.isArray(attachments)) return [];
+  if (typeof hydrateAttachment !== 'function') return attachments.filter(Boolean);
+  return attachments.map((entry) => hydrateAttachment(entry)).filter(Boolean);
+}
+
+function resolveGeneratedImagePath({
+  root,
+  sessionId,
+  relativePath,
+} = {}) {
+  const normalizedRoot = String(root || '').trim();
+  const safeSession = normalizeStorageSegment(sessionId || '', '');
+  const rawRelative = String(relativePath || '').replace(/\\/g, '/').trim();
+  if (!normalizedRoot || !safeSession || !rawRelative) return null;
+  const normalizedRelative = path.posix.normalize(rawRelative).replace(/^\/+/, '');
+  if (!normalizedRelative || normalizedRelative.startsWith('..') || normalizedRelative.includes('/../')) return null;
+  const baseDir = path.resolve(path.join(normalizedRoot, safeSession, 'generated-images'));
+  const candidate = path.resolve(path.join(baseDir, normalizedRelative));
+  if (!(candidate === baseDir || candidate.startsWith(`${baseDir}${path.sep}`))) return null;
+  return candidate;
+}
+
+function resolveGeneratedImageConversationDir({
+  root,
+  sessionId,
+  conversationId,
+} = {}) {
+  const normalizedRoot = String(root || '').trim();
+  const safeSession = normalizeStorageSegment(sessionId || '', '');
+  const safeConversation = normalizeStorageSegment(conversationId || '', '');
+  if (!normalizedRoot || !safeSession || !safeConversation) return null;
+  const baseDir = path.resolve(path.join(normalizedRoot, safeSession, 'generated-images'));
+  const candidate = path.resolve(path.join(baseDir, safeConversation));
+  if (!(candidate === baseDir || candidate.startsWith(`${baseDir}${path.sep}`))) return null;
+  return candidate;
+}
+
+export function cleanupGeneratedImagesForConversation({
+  conversationId,
+  sdkSessionId = null,
+  messageRows = [],
+  parseAttachments = null,
+  hydrateAttachment = null,
+  resolveSessionStateRoot = null,
+} = {}) {
+  if (typeof resolveSessionStateRoot !== 'function') return;
+  const root = String(resolveSessionStateRoot() || '').trim();
+  const normalizedConversationId = String(conversationId || '').trim();
+  if (!root || !normalizedConversationId) return;
+
+  const candidateSessionIds = new Set();
+  const filesToDelete = new Set();
+  const normalizedSdkSessionId = String(sdkSessionId || '').trim();
+  if (normalizedSdkSessionId) candidateSessionIds.add(normalizedSdkSessionId);
+  candidateSessionIds.add(normalizedConversationId);
+
+  for (const row of Array.isArray(messageRows) ? messageRows : []) {
+    const attachments = parseMessageAttachments(row?.attachments, { parseAttachments, hydrateAttachment });
+    for (const attachment of attachments) {
+      const generatedImage = attachment?.generatedImage;
+      if (!generatedImage || typeof generatedImage !== 'object') continue;
+      const sessionId = String(generatedImage.sessionId || '').trim();
+      const relativePath = String(generatedImage.relativePath || '').trim();
+      if (sessionId) candidateSessionIds.add(sessionId);
+      const filePath = resolveGeneratedImagePath({
+        root,
+        sessionId: sessionId || normalizedSdkSessionId || normalizedConversationId,
+        relativePath,
+      });
+      if (!filePath) continue;
+      filesToDelete.add(filePath);
+    }
+  }
+
+  for (const filePath of filesToDelete) {
+    try {
+      fs.rmSync(filePath, { force: true });
+    } catch {}
+  }
+
+  for (const sessionId of candidateSessionIds) {
+    const conversationDir = resolveGeneratedImageConversationDir({
+      root,
+      sessionId,
+      conversationId: normalizedConversationId,
+    });
+    if (!conversationDir) continue;
+    try {
+      fs.rmSync(conversationDir, { recursive: true, force: true });
+    } catch {}
+  }
+}

package/server/services/git-changes-service.mjs

@@ -0,0 +1,195 @@
+'use strict';
+
+import { execFile as nodeExecFile } from 'child_process';
+
+// Read-only-ish git integration for the "Git changes" modal: status (branch,
+// ahead/behind, changed files), a full-context per-file diff, and pull.
+// The service never receives paths from the client directly — routes resolve
+// the workspace root server-side and validate file paths before calling in.
+
+const GIT_COMMAND_TIMEOUT_MS = 15_000;
+const GIT_PULL_TIMEOUT_MS = 120_000;
+const GIT_MAX_BUFFER_BYTES = 32 * 1024 * 1024;
+// Large enough that hunks always include the whole file, so the client can
+// render both "full file" and "changes only" views from one patch.
+const FULL_CONTEXT_LINES = 999_999;
+
+function normalizeGitPath(value) {
+  const text = String(value || '');
+  if (!text) return '';
+  // Porcelain quotes paths with special characters ("path with\ttab").
+  if (text.startsWith('"') && text.endsWith('"') && text.length >= 2) {
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text.slice(1, -1);
+    }
+  }
+  return text;
+}
+
+export function parseGitStatusBranchHeader(headerLine) {
+  const result = { branch: '', upstream: '', ahead: 0, behind: 0, detached: false, initial: false };
+  const text = String(headerLine || '').trim();
+  if (!text.startsWith('##')) return result;
+  let body = text.slice(2).trim();
+  if (!body) return result;
+  if (body.startsWith('No commits yet on ')) {
+    result.branch = body.slice('No commits yet on '.length).trim();
+    result.initial = true;
+    return result;
+  }
+  if (body === 'HEAD (no branch)') {
+    result.branch = 'HEAD';
+    result.detached = true;
+    return result;
+  }
+  const bracketStart = body.lastIndexOf(' [');
+  if (bracketStart !== -1 && body.endsWith(']')) {
+    const tracking = body.slice(bracketStart + 2, -1);
+    body = body.slice(0, bracketStart);
+    const aheadMatch = tracking.match(/ahead (\d+)/);
+    const behindMatch = tracking.match(/behind (\d+)/);
+    if (aheadMatch) result.ahead = Number(aheadMatch[1]);
+    if (behindMatch) result.behind = Number(behindMatch[1]);
+  }
+  const ellipsis = body.indexOf('...');
+  if (ellipsis !== -1) {
+    result.branch = body.slice(0, ellipsis);
+    result.upstream = body.slice(ellipsis + 3);
+  } else {
+    result.branch = body;
+  }
+  return result;
+}
+
+// Parses `git status --porcelain=v1 -z --branch` output. NUL-separated
+// entries; renames/copies carry a second NUL-separated original path.
+export function parseGitStatusPorcelain(stdout) {
+  const entries = String(stdout || '').split('\0').filter((entry) => entry.length > 0);
+  const summary = { branch: '', upstream: '', ahead: 0, behind: 0, detached: false, initial: false };
+  const files = [];
+  let index = 0;
+  while (index < entries.length) {
+    const entry = entries[index];
+    index += 1;
+    if (entry.startsWith('## ') || entry === '##') {
+      Object.assign(summary, parseGitStatusBranchHeader(entry));
+      continue;
+    }
+    if (entry.length < 4) continue;
+    const indexStatus = entry[0];
+    const worktreeStatus = entry[1];
+    const rawPath = entry.slice(3);
+    let origPath = '';
+    if (indexStatus === 'R' || indexStatus === 'C' || worktreeStatus === 'R' || worktreeStatus === 'C') {
+      origPath = normalizeGitPath(entries[index] || '');
+      index += 1;
+    }
+    const untracked = indexStatus === '?' && worktreeStatus === '?';
+    const deleted = indexStatus === 'D' || worktreeStatus === 'D';
+    const statusCode = untracked
+      ? 'U'
+      : (worktreeStatus !== ' ' && worktreeStatus !== '?' ? worktreeStatus : indexStatus);
+    files.push({
+      path: normalizeGitPath(rawPath).replace(/\\/g, '/'),
+      origPath: origPath ? origPath.replace(/\\/g, '/') : '',
+      indexStatus,
+      worktreeStatus,
+      status: statusCode,
+      untracked,
+      deleted,
+      renamed: indexStatus === 'R' || worktreeStatus === 'R',
+    });
+  }
+  files.sort((a, b) => a.path.localeCompare(b.path));
+  return { ...summary, files };
+}
+
+function isNotARepositoryError(error) {
+  const text = `${error?.message || ''}\n${error?.stderr || ''}`.toLowerCase();
+  return text.includes('not a git repository');
+}
+
+export function createGitChangesService({ execFileImpl = nodeExecFile } = {}) {
+  function runGit(rootPath, args, { timeoutMs = GIT_COMMAND_TIMEOUT_MS, okExitCodes = [0] } = {}) {
+    return new Promise((resolve, reject) => {
+      execFileImpl('git', args, {
+        cwd: rootPath,
+        timeout: timeoutMs,
+        maxBuffer: GIT_MAX_BUFFER_BYTES,
+        windowsHide: true,
+      }, (error, stdout, stderr) => {
+        if (error && !okExitCodes.includes(Number(error.code))) {
+          const failure = new Error(String(stderr || error.message || 'git command failed').trim());
+          failure.stderr = String(stderr || '');
+          failure.code = error.code;
+          return reject(failure);
+        }
+        resolve({ stdout: String(stdout || ''), stderr: String(stderr || '') });
+      });
+    });
+  }
+
+  async function getStatus(rootPath) {
+    try {
+      const { stdout } = await runGit(rootPath, ['status', '--porcelain=v1', '-z', '--branch']);
+      return { ok: true, isRepo: true, ...parseGitStatusPorcelain(stdout) };
+    } catch (error) {
+      if (isNotARepositoryError(error)) {
+        return { ok: true, isRepo: false, branch: '', upstream: '', ahead: 0, behind: 0, files: [] };
+      }
+      return { ok: false, error: error?.message || 'Failed to read git status' };
+    }
+  }
+
+  async function getDiff(rootPath, relativePath, { untracked = false } = {}) {
+    const gitPath = String(relativePath || '').replace(/\\/g, '/');
+    if (!gitPath) return { ok: false, error: 'Missing file path' };
+    try {
+      let patch = '';
+      if (untracked) {
+        // --no-index exits 1 when the files differ; that is the success case.
+        const { stdout } = await runGit(
+          rootPath,
+          ['diff', '--no-index', `-U${FULL_CONTEXT_LINES}`, '--', '/dev/null', gitPath],
+          { okExitCodes: [0, 1] },
+        );
+        patch = stdout;
+      } else {
+        const { stdout } = await runGit(
+          rootPath,
+          ['diff', 'HEAD', `-U${FULL_CONTEXT_LINES}`, '--', gitPath],
+        );
+        patch = stdout;
+        if (!patch.trim()) {
+          // Fall back for files that only differ in the index vs worktree edge
+          // cases (e.g. intent-to-add) where `diff HEAD` came back empty.
+          const fallback = await runGit(
+            rootPath,
+            ['diff', '--no-index', `-U${FULL_CONTEXT_LINES}`, '--', '/dev/null', gitPath],
+            { okExitCodes: [0, 1] },
+          );
+          patch = fallback.stdout;
+        }
+      }
+      return { ok: true, path: gitPath, patch };
+    } catch (error) {
+      if (isNotARepositoryError(error)) {
+        return { ok: false, error: 'Not a git repository' };
+      }
+      return { ok: false, error: error?.message || 'Failed to read git diff' };
+    }
+  }
+
+  async function pull(rootPath) {
+    try {
+      const { stdout, stderr } = await runGit(rootPath, ['pull'], { timeoutMs: GIT_PULL_TIMEOUT_MS });
+      return { ok: true, output: `${stdout}${stderr}`.trim() };
+    } catch (error) {
+      return { ok: false, error: error?.message || 'git pull failed' };
+    }
+  }
+
+  return { getStatus, getDiff, pull };
+}