@imdeadpool/guardex 7.0.41 → 7.1.0

package/src/pr-review.js

@@ -0,0 +1,264 @@
+const {
+  fs,
+  path,
+  os,
+  GH_BIN,
+} = require('./context');
+const { run } = require('./core/runtime');
+
+const TOOL_PREFIX = '[gitguardex]';
+const VALID_SEVERITIES = new Set(['low', 'medium', 'high', 'critical']);
+
+function normalizeProvider(raw) {
+  const provider = String(raw || 'codex').trim().toLowerCase();
+  if (!['codex', 'claude'].includes(provider)) {
+    throw new Error(`Invalid provider: ${raw}`);
+  }
+  return provider;
+}
+
+function commandForProvider(provider, prompt) {
+  if (provider === 'claude') {
+    return { cmd: 'claude', args: ['-p', prompt] };
+  }
+  return { cmd: 'codex', args: ['exec', prompt] };
+}
+
+function compactReviewPrompt(diff) {
+  return [
+    'You are gitguardex-code-assist, a PR review runner.',
+    'Review this GitHub PR diff for correctness bugs, regressions, security issues, and missing tests.',
+    'Return JSON only. Shape:',
+    '{"findings":[{"path":"file","line":123,"severity":"low|medium|high|critical","message":"concise finding","suggestion":"optional replacement or fix"}]}',
+    'Rules: path and line must point to changed lines in the diff. Use an empty findings array when nothing is worth commenting.',
+    '',
+    'PR diff:',
+    diff,
+  ].join('\n');
+}
+
+function extractJsonPayload(text) {
+  const raw = String(text || '').trim();
+  if (!raw) return { findings: [] };
+  const fenced = raw.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  const candidate = fenced ? fenced[1].trim() : raw;
+  try {
+    return JSON.parse(candidate);
+  } catch (_error) {
+    const objectStart = candidate.indexOf('{');
+    const objectEnd = candidate.lastIndexOf('}');
+    if (objectStart >= 0 && objectEnd > objectStart) {
+      return JSON.parse(candidate.slice(objectStart, objectEnd + 1));
+    }
+    const arrayStart = candidate.indexOf('[');
+    const arrayEnd = candidate.lastIndexOf(']');
+    if (arrayStart >= 0 && arrayEnd > arrayStart) {
+      return { findings: JSON.parse(candidate.slice(arrayStart, arrayEnd + 1)) };
+    }
+    throw new Error('Review provider did not return parseable JSON findings');
+  }
+}
+
+function normalizeFinding(rawFinding) {
+  const pathValue = String(rawFinding?.path || '').trim();
+  const line = Number.parseInt(String(rawFinding?.line || ''), 10);
+  const severity = String(rawFinding?.severity || 'medium').trim().toLowerCase();
+  const message = String(rawFinding?.message || '').trim();
+  const suggestion = String(rawFinding?.suggestion || '').trim();
+  if (!pathValue || !Number.isInteger(line) || line <= 0 || !message) {
+    return null;
+  }
+  return {
+    path: pathValue,
+    line,
+    severity: VALID_SEVERITIES.has(severity) ? severity : 'medium',
+    message,
+    suggestion,
+  };
+}
+
+function normalizeFindings(providerOutput) {
+  const payload = extractJsonPayload(providerOutput);
+  const rawFindings = Array.isArray(payload) ? payload : payload.findings;
+  if (!Array.isArray(rawFindings)) {
+    throw new Error('Review provider JSON must contain a findings array');
+  }
+  return rawFindings.map(normalizeFinding).filter(Boolean);
+}
+
+function findingBody(finding) {
+  const lines = [`**${finding.severity.toUpperCase()}** ${finding.message}`];
+  if (finding.suggestion) {
+    lines.push('', 'Suggested fix:', '```suggestion', finding.suggestion, '```');
+  }
+  return lines.join('\n');
+}
+
+function renderMarkdownReview({ pr, provider, findings }) {
+  const lines = [
+    `# GitGuardex PR Review`,
+    '',
+    `- PR: #${pr}`,
+    `- Provider: ${provider}`,
+    `- Findings: ${findings.length}`,
+    '',
+  ];
+  if (findings.length === 0) {
+    lines.push('No findings.');
+  } else {
+    for (const finding of findings) {
+      lines.push(`## ${finding.severity.toUpperCase()} ${finding.path}:${finding.line}`);
+      lines.push('');
+      lines.push(finding.message);
+      if (finding.suggestion) {
+        lines.push('', '```suggestion', finding.suggestion, '```');
+      }
+      lines.push('');
+    }
+  }
+  return `${lines.join('\n').replace(/\n{3,}/g, '\n\n')}\n`;
+}
+
+function defaultArtifactPath(repoRoot, pr) {
+  return path.join(repoRoot, '.gitguardex', 'pr-reviews', `pr-${pr}.md`);
+}
+
+function writeArtifact(repoRoot, artifactPath, payload) {
+  const outputPath = artifactPath
+    ? path.resolve(repoRoot, artifactPath)
+    : defaultArtifactPath(repoRoot, payload.pr);
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.writeFileSync(outputPath, renderMarkdownReview(payload), 'utf8');
+  return outputPath;
+}
+
+function githubAuthAvailable(env = process.env, runner = run) {
+  if (env.GITHUB_TOKEN || env.GH_TOKEN) return true;
+  const result = runner(GH_BIN, ['auth', 'status'], { timeout: 15_000 });
+  return result.status === 0;
+}
+
+function fetchPrDiff(pr, repoRoot, runner = run) {
+  const result = runner(GH_BIN, ['pr', 'diff', String(pr)], { cwd: repoRoot, timeout: 120_000 });
+  if (result.status !== 0) {
+    throw new Error(`gh pr diff ${pr} failed${result.stderr ? `\n${result.stderr.trim()}` : ''}`);
+  }
+  return result.stdout || '';
+}
+
+function runProviderReview(provider, diff, repoRoot, timeoutMs, runner = run) {
+  const prompt = compactReviewPrompt(diff);
+  const command = commandForProvider(provider, prompt);
+  const result = runner(command.cmd, command.args, { cwd: repoRoot, timeout: timeoutMs });
+  if (result.status !== 0) {
+    throw new Error(`${provider} review failed${result.stderr ? `\n${result.stderr.trim()}` : ''}`);
+  }
+  // A compliant provider always emits the findings JSON object (empty array when
+  // nothing is wrong). Empty stdout means the review did NOT run — fail closed so
+  // a silent no-op is never mistaken for "clean" by the merge gate.
+  if (!(result.stdout || '').trim()) {
+    throw new Error(`${provider} review returned no output (review did not run)`);
+  }
+  return normalizeFindings(result.stdout || '');
+}
+
+function postGithubReview(pr, findings, repoRoot, runner = run) {
+  const comments = findings.map((finding) => ({
+    path: finding.path,
+    line: finding.line,
+    side: 'RIGHT',
+    body: findingBody(finding),
+  }));
+  const body = findings.length > 0
+    ? `GitGuardex code-assist found ${findings.length} issue(s).`
+    : 'GitGuardex code-assist found no issues worth inline comments.';
+  const payload = {
+    event: 'COMMENT',
+    body,
+    comments,
+  };
+  const inputPath = path.join(os.tmpdir(), `gitguardex-pr-review-${process.pid}-${Date.now()}.json`);
+  fs.writeFileSync(inputPath, JSON.stringify(payload), 'utf8');
+  try {
+    const result = runner(GH_BIN, [
+      'api',
+      `repos/:owner/:repo/pulls/${pr}/reviews`,
+      '--method',
+      'POST',
+      '--input',
+      inputPath,
+    ], { cwd: repoRoot, timeout: 120_000 });
+    if (result.status !== 0) {
+      throw new Error(`gh api review post failed${result.stderr ? `\n${result.stderr.trim()}` : ''}`);
+    }
+    return result;
+  } finally {
+    try {
+      fs.unlinkSync(inputPath);
+    } catch (_error) {
+      // best effort cleanup for temp API payload
+    }
+  }
+}
+
+function runPrReview(options, deps = {}) {
+  const runner = deps.run || run;
+  const repoRoot = path.resolve(options.target || process.cwd());
+  const provider = normalizeProvider(options.provider);
+  const pr = String(options.pr);
+  const diff = fetchPrDiff(pr, repoRoot, runner);
+  const findings = runProviderReview(provider, diff, repoRoot, options.timeoutMs, runner);
+  const payload = { pr, provider, findings };
+
+  if (!options.post) {
+    const artifactPath = writeArtifact(repoRoot, options.artifact, payload);
+    return { posted: false, artifactPath, findings };
+  }
+
+  if (!githubAuthAvailable(process.env, runner)) {
+    const artifactPath = writeArtifact(repoRoot, options.artifact, payload);
+    return { posted: false, artifactPath, findings, reason: 'github-auth-unavailable' };
+  }
+
+  postGithubReview(pr, findings, repoRoot, runner);
+  return { posted: true, artifactPath: '', findings };
+}
+
+/**
+ * Decide whether a set of review findings clears the merge gate. Blocks on any
+ * finding whose severity is in `blockSeverities` (high + critical by default;
+ * low/medium are advisory). Pure + synchronous so it is trivially testable.
+ *
+ * Fail-closed semantics live in the CALLER: an absent/empty `findings` here is
+ * treated as clean, so the caller must independently treat a review that did
+ * NOT run (provider threw / timed out) as a block, never as clean.
+ */
+function evaluateReviewGate(findings, { blockSeverities = ['high', 'critical'] } = {}) {
+  const block = new Set(blockSeverities.map((s) => String(s).toLowerCase()));
+  const list = Array.isArray(findings) ? findings : [];
+  const blocking = list.filter((f) => f && block.has(String(f.severity).toLowerCase()));
+  return { clean: blocking.length === 0, blocking };
+}
+
+function printPrReviewResult(result) {
+  if (result.posted) {
+    console.log(`${TOOL_PREFIX} Posted PR review with ${result.findings.length} finding(s).`);
+    return;
+  }
+  if (result.reason === 'github-auth-unavailable') {
+    console.log(`${TOOL_PREFIX} GitHub auth unavailable; wrote PR review artifact: ${result.artifactPath}`);
+    return;
+  }
+  console.log(`${TOOL_PREFIX} Wrote PR review artifact: ${result.artifactPath}`);
+}
+
+module.exports = {
+  compactReviewPrompt,
+  commandForProvider,
+  extractJsonPayload,
+  normalizeFindings,
+  renderMarkdownReview,
+  runPrReview,
+  evaluateReviewGate,
+  printPrReviewResult,
+};

package/src/pr.js

@@ -0,0 +1,381 @@
+// PR-from-worktree helpers.
+//
+// Centralizes the operations that the agent + worktree flow needs to drive a
+// pull request: detecting the PR for the current branch, opening one
+// idempotently, pushing + syncing, enabling auto-merge, and polling CI / merge
+// state. The agent-branch-finish.sh script historically owned most of this;
+// these helpers expose the same primitives to the JS CLI so `gx pr ...` can be
+// driven without invoking the shell flow.
+
+const { GH_BIN } = require('./context');
+const { run } = require('./core/runtime');
+const {
+  resolveRepoRoot,
+  currentBranchName,
+  hasOriginRemote,
+  detectDefaultBaseBranch,
+} = require('./git');
+
+const DEFAULT_POLL_INTERVAL_MS = 5_000;
+const DEFAULT_POLL_TIMEOUT_MS = 10 * 60 * 1000;
+
+class PrError extends Error {
+  constructor(message, { code = 'pr-error', cause = null } = {}) {
+    super(message);
+    this.name = 'PrError';
+    this.code = code;
+    if (cause) this.cause = cause;
+  }
+}
+
+function ghAvailable() {
+  const result = run(GH_BIN, ['--version'], { allowFailure: true });
+  return result.status === 0;
+}
+
+function ghAuthStatus() {
+  const result = run(GH_BIN, ['auth', 'status'], { allowFailure: true });
+  return {
+    authenticated: result.status === 0,
+    output: ((result.stdout || '') + (result.stderr || '')).trim(),
+  };
+}
+
+function ghJson(repoRoot, args) {
+  const result = run(GH_BIN, args, { cwd: repoRoot, allowFailure: true });
+  if (result.status !== 0) {
+    return { ok: false, error: (result.stderr || result.stdout || '').trim(), data: null };
+  }
+  const raw = (result.stdout || '').trim();
+  if (!raw) return { ok: true, data: null, error: null };
+  try {
+    return { ok: true, data: JSON.parse(raw), error: null };
+  } catch (error) {
+    return { ok: false, data: null, error: `gh JSON parse: ${error.message}` };
+  }
+}
+
+/**
+ * Resolve the PR for `branch` if any exists on the origin remote.
+ * Returns null when no PR is open (or any are merged / closed only).
+ */
+function findOpenPrForBranch(repoRoot, branch) {
+  const result = ghJson(repoRoot, [
+    'pr', 'list',
+    '--head', branch,
+    '--state', 'open',
+    '--json', 'number,url,state,isDraft,mergeable,mergeStateStatus,reviewDecision,headRefName,baseRefName,title,statusCheckRollup',
+    '--limit', '5',
+  ]);
+  if (!result.ok) {
+    throw new PrError(`gh pr list failed: ${result.error}`, { code: 'gh-list-failed' });
+  }
+  const items = Array.isArray(result.data) ? result.data : [];
+  if (items.length === 0) return null;
+  return items[0];
+}
+
+/**
+ * Resolve the most recent PR for `branch` regardless of state. Useful when
+ * the agent has already merged a previous PR for this branch.
+ */
+function findLatestPrForBranch(repoRoot, branch) {
+  const result = ghJson(repoRoot, [
+    'pr', 'list',
+    '--head', branch,
+    '--state', 'all',
+    '--json', 'number,url,state,isDraft,mergedAt,headRefName,baseRefName,title',
+    '--limit', '5',
+  ]);
+  if (!result.ok) {
+    throw new PrError(`gh pr list failed: ${result.error}`, { code: 'gh-list-failed' });
+  }
+  const items = Array.isArray(result.data) ? result.data : [];
+  if (items.length === 0) return null;
+  return items[0];
+}
+
+/**
+ * List ALL open PRs for the repo on origin in a single gh call, so callers can
+ * correlate many branches to their PRs without one gh round-trip per branch.
+ * Best-effort: never throws. Returns `{ prs, error }` so callers can tell a
+ * genuine "no open PRs" (`error: null`) from a failed lookup (gh missing /
+ * unauthenticated / offline → `error` set, `prs: []`).
+ * NB: `limit` (default 100) bounds correlation COVERAGE, not just payload size —
+ * a repo with more than `limit` open PRs may leave some lanes showing pr:null.
+ */
+function listOpenPrsForRepo(repoRoot, { limit = 100 } = {}) {
+  const result = ghJson(repoRoot, [
+    'pr', 'list',
+    '--state', 'open',
+    '--json', 'number,url,state,isDraft,mergeable,mergeStateStatus,reviewDecision,headRefName,baseRefName,title',
+    '--limit', String(limit),
+  ]);
+  if (!result.ok) return { prs: [], error: result.error || 'gh pr list failed' };
+  if (!Array.isArray(result.data)) return { prs: [], error: null };
+  return { prs: result.data, error: null };
+}
+
+function pushBranch(repoRoot, branch, { setUpstream = true } = {}) {
+  const args = ['push'];
+  if (setUpstream) args.push('-u');
+  args.push('origin', branch);
+  const result = run('git', args, { cwd: repoRoot, allowFailure: true });
+  return {
+    ok: result.status === 0,
+    output: ((result.stdout || '') + (result.stderr || '')).trim(),
+  };
+}
+
+function defaultPrTitleFromCommit(repoRoot, branch) {
+  const result = run('git', ['log', '-1', '--pretty=%s', branch], {
+    cwd: repoRoot, allowFailure: true,
+  });
+  if (result.status !== 0) return branch;
+  const subject = (result.stdout || '').trim();
+  return subject || branch;
+}
+
+function defaultPrBodyFromCommits(repoRoot, branch, baseBranch) {
+  const result = run('git', [
+    'log',
+    `${baseBranch}..${branch}`,
+    '--pretty=format:- %s',
+  ], { cwd: repoRoot, allowFailure: true });
+  const list = (result.stdout || '').trim();
+  return [
+    '## Summary',
+    list || '- (no commits between base and branch yet)',
+    '',
+    '## Test plan',
+    '- [ ] verified locally',
+  ].join('\n');
+}
+
+/**
+ * Create (or fetch existing) PR for the current worktree branch. Idempotent:
+ * if an open PR is already associated with the branch, returns it without
+ * creating a duplicate.
+ *
+ * @param {object} options
+ * @param {string} options.repoRoot
+ * @param {string} options.branch
+ * @param {string} [options.base]
+ * @param {string} [options.title]
+ * @param {string} [options.body]
+ * @param {boolean} [options.draft]
+ * @param {boolean} [options.push]
+ */
+function openPullRequest(options) {
+  const repoRoot = options.repoRoot;
+  const branch = options.branch;
+  if (!repoRoot) throw new PrError('repoRoot required', { code: 'bad-arg' });
+  if (!branch) throw new PrError('branch required', { code: 'bad-arg' });
+
+  if (!ghAvailable()) {
+    throw new PrError('gh CLI not installed. Install from https://cli.github.com/', {
+      code: 'gh-missing',
+    });
+  }
+  const auth = ghAuthStatus();
+  if (!auth.authenticated) {
+    throw new PrError(
+      `GitHub CLI is not authenticated. Run 'gh auth login' or set GITHUB_TOKEN.\n${auth.output}`,
+      { code: 'gh-unauthenticated' },
+    );
+  }
+  if (!hasOriginRemote(repoRoot)) {
+    throw new PrError('No `origin` remote configured for this repo', {
+      code: 'no-origin',
+    });
+  }
+
+  // Try to find an existing open PR first.
+  const existing = findOpenPrForBranch(repoRoot, branch);
+  if (existing) {
+    return { created: false, pr: existing };
+  }
+
+  if (options.push !== false) {
+    const push = pushBranch(repoRoot, branch);
+    if (!push.ok) {
+      throw new PrError(`git push failed:\n${push.output}`, { code: 'push-failed' });
+    }
+  }
+
+  const base = options.base || detectDefaultBaseBranch(repoRoot);
+  const title = options.title || defaultPrTitleFromCommit(repoRoot, branch);
+  const body = options.body || defaultPrBodyFromCommits(repoRoot, branch, base);
+
+  const args = [
+    'pr', 'create',
+    '--base', base,
+    '--head', branch,
+    '--title', title,
+    '--body', body,
+  ];
+  if (options.draft !== false) args.push('--draft');
+
+  const result = run(GH_BIN, args, { cwd: repoRoot, allowFailure: true });
+  if (result.status !== 0) {
+    throw new PrError(
+      `gh pr create failed:\n${(result.stderr || result.stdout || '').trim()}`,
+      { code: 'gh-create-failed' },
+    );
+  }
+
+  const created = findOpenPrForBranch(repoRoot, branch);
+  if (!created) {
+    throw new PrError('PR appears to have been created but could not be located on origin', {
+      code: 'pr-lookup-failed',
+    });
+  }
+  return { created: true, pr: created };
+}
+
+/**
+ * Fetch the live status of the PR for `branch`. Returns null when no open PR
+ * exists. Status checks are summarized.
+ */
+function getPullRequestStatus(repoRoot, branch) {
+  const pr = findOpenPrForBranch(repoRoot, branch);
+  if (!pr) return null;
+
+  const checks = Array.isArray(pr.statusCheckRollup) ? pr.statusCheckRollup : [];
+  const summary = checks.reduce(
+    (acc, check) => {
+      const state = String(check?.conclusion || check?.status || '').toUpperCase();
+      if (state === 'SUCCESS') acc.success += 1;
+      else if (state === 'FAILURE' || state === 'ERROR' || state === 'TIMED_OUT') acc.failed += 1;
+      else if (state === 'PENDING' || state === 'IN_PROGRESS' || state === 'QUEUED') acc.pending += 1;
+      else if (state === 'CANCELLED') acc.cancelled += 1;
+      else acc.other += 1;
+      return acc;
+    },
+    { success: 0, failed: 0, pending: 0, cancelled: 0, other: 0, total: checks.length },
+  );
+
+  return {
+    number: pr.number,
+    url: pr.url,
+    state: pr.state,
+    isDraft: pr.isDraft,
+    mergeable: pr.mergeable,
+    mergeStateStatus: pr.mergeStateStatus,
+    reviewDecision: pr.reviewDecision,
+    title: pr.title,
+    head: pr.headRefName,
+    base: pr.baseRefName,
+    checks: summary,
+  };
+}
+
+function enableAutoMerge(repoRoot, prNumber, { strategy = 'squash' } = {}) {
+  const flag = strategy === 'merge'
+    ? '--merge'
+    : strategy === 'rebase' ? '--rebase' : '--squash';
+  const result = run(GH_BIN, [
+    'pr', 'merge', String(prNumber),
+    '--auto', flag, '--delete-branch',
+  ], { cwd: repoRoot, allowFailure: true });
+  return {
+    ok: result.status === 0,
+    output: ((result.stdout || '') + (result.stderr || '')).trim(),
+  };
+}
+
+function markPullRequestReady(repoRoot, prNumber) {
+  const result = run(GH_BIN, ['pr', 'ready', String(prNumber)], {
+    cwd: repoRoot, allowFailure: true,
+  });
+  return {
+    ok: result.status === 0,
+    output: ((result.stdout || '') + (result.stderr || '')).trim(),
+  };
+}
+
+/**
+ * Watch a PR's CI + merge state until it merges, fails, or times out.
+ *
+ * Returns a structured result; does not throw on non-success states. Used by
+ * `gx pr watch`. `onEvent` is called for every poll tick with the current
+ * status snapshot, so callers can render progress.
+ */
+async function watchPullRequest(options) {
+  const {
+    repoRoot,
+    branch,
+    intervalMs = DEFAULT_POLL_INTERVAL_MS,
+    timeoutMs = DEFAULT_POLL_TIMEOUT_MS,
+    onEvent = () => {},
+  } = options;
+
+  const deadline = Date.now() + timeoutMs;
+
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    // Check open PRs first.
+    const open = findOpenPrForBranch(repoRoot, branch);
+    if (!open) {
+      const latest = findLatestPrForBranch(repoRoot, branch);
+      if (latest && latest.state === 'MERGED') {
+        onEvent({ phase: 'merged', pr: latest });
+        return { status: 'merged', pr: latest };
+      }
+      if (latest && latest.state === 'CLOSED') {
+        onEvent({ phase: 'closed', pr: latest });
+        return { status: 'closed', pr: latest };
+      }
+      onEvent({ phase: 'no-pr', pr: null });
+      return { status: 'no-pr', pr: null };
+    }
+
+    const snapshot = getPullRequestStatus(repoRoot, branch);
+    onEvent({ phase: 'polling', pr: snapshot });
+
+    if (snapshot && snapshot.checks.failed > 0) {
+      return { status: 'checks-failed', pr: snapshot };
+    }
+    if (
+      snapshot
+      && !snapshot.isDraft
+      && snapshot.mergeable === 'MERGEABLE'
+      && snapshot.checks.pending === 0
+      && snapshot.checks.failed === 0
+      && snapshot.checks.total > 0
+    ) {
+      // CI is green and PR is non-draft + mergeable; the merge itself will be
+      // driven by auto-merge or a separate `gh pr merge` invocation.
+      onEvent({ phase: 'ready', pr: snapshot });
+    }
+
+    if (Date.now() >= deadline) {
+      return { status: 'timeout', pr: snapshot };
+    }
+    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+  }
+}
+
+function resolveRepoAndBranch(target) {
+  const repoRoot = resolveRepoRoot(target || process.cwd());
+  const branch = currentBranchName(repoRoot);
+  return { repoRoot, branch };
+}
+
+module.exports = {
+  PrError,
+  ghAvailable,
+  ghAuthStatus,
+  findOpenPrForBranch,
+  findLatestPrForBranch,
+  listOpenPrsForRepo,
+  pushBranch,
+  openPullRequest,
+  getPullRequestStatus,
+  enableAutoMerge,
+  markPullRequestReady,
+  watchPullRequest,
+  resolveRepoAndBranch,
+  defaultPrTitleFromCommit,
+  defaultPrBodyFromCommits,
+};

package/src/sandbox/index.js

@@ -13,6 +13,14 @@ const {
   gitRefExists,
   ensureRepoBranch,
 } = require('../git');
+const { prepareAgentWorktree } = require('../scaffold/agent-worktree-prep');
+
+function formatWorktreePrepOps(operations) {
+  if (!operations || operations.length === 0) return '';
+  return operations
+    .map((op) => `[agent-branch-start] worktree-prep ${op.status} ${op.file}${op.note ? ' — ' + op.note : ''}`)
+    .join('\n') + '\n';
+}
 
 function hasGuardexBootstrapFiles(repoRoot) {
   const required = [
@@ -195,6 +203,7 @@ function startProtectedBaseSandboxFallback(blocked, sandboxSuffix) {
     }
   }
 
+  const prepOps = prepareAgentWorktree(blocked.repoRoot, selectedWorktreePath);
   return {
     metadata: {
       branch: selectedBranch,
@@ -202,7 +211,8 @@ function startProtectedBaseSandboxFallback(blocked, sandboxSuffix) {
     },
     stdout:
       `[agent-branch-start] Created branch: ${selectedBranch}\n` +
-      `[agent-branch-start] Worktree: ${selectedWorktreePath}\n`,
+      `[agent-branch-start] Worktree: ${selectedWorktreePath}\n` +
+      formatWorktreePrepOps(prepOps),
     stderr: addResult.stderr || '',
   };
 }
@@ -246,9 +256,10 @@ function startProtectedBaseSandbox(blocked, { taskName, sandboxSuffix }) {
     return startProtectedBaseSandboxFallback(blocked, sandboxSuffix);
   }
 
+  const prepOps = prepareAgentWorktree(blocked.repoRoot, worktreePath);
   return {
     metadata,
-    stdout: startResult.stdout || '',
+    stdout: (startResult.stdout || '') + formatWorktreePrepOps(prepOps),
     stderr: startResult.stderr || '',
   };
 }