internaltool-mcp 1.6.19 → 1.6.22

package/index.js

@@ -397,10 +397,16 @@ Set confirmed=false first to preview, then confirmed=true to execute everything.
         cursorRulesCleared = deleteCursorRulesFile(task.key, repoPath)
       }
 
+      // ── #9 Capture last commit for handoff metadata ───────────────────────
+      const lastCommit = getLastCommitMeta(repoRoot)
+
       return text({
         parked: true,
         task:   { key: task?.key, title: task?.title, branch: task?.github?.headBranch || null },
         autoPushed: pushed ? `${unpushedCount} commit(s) pushed to origin/${currentBranch}` : 'No push needed',
+        lastCommit: lastCommit
+          ? { sha: lastCommit.sha, subject: lastCommit.subject, author: lastCommit.author, date: lastCommit.date }
+          : null,
         cursorRulesCleared: cursorRulesCleared ? `Deleted ${cursorRulesCleared}` : null,
         commentPosted: true,
         teamNotified:  true,
@@ -427,8 +433,9 @@ Set confirmed=false first to read everything, then confirmed=true to execute.`,
       taskId:    z.string().describe("Task's MongoDB ObjectId"),
       confirmed: z.boolean().optional().default(false).describe('Set true to execute after reviewing the park note'),
       repoPath:  z.string().optional().describe('Absolute path to the local git repo (defaults to MCP process working directory).'),
+      autoStash: z.boolean().optional().default(false).describe('Auto-stash dirty working tree before switching branches instead of blocking. Stash is labelled with the task key for easy recovery.'),
     },
-    async ({ taskId, confirmed = false, repoPath }) => {
+    async ({ taskId, confirmed = false, repoPath, autoStash = false }) => {
       const taskRes = await api.get(`/api/tasks/${taskId}`)
       const task    = taskRes?.data?.task
       const branch  = task?.github?.headBranch || null
@@ -480,6 +487,35 @@ Set confirmed=false first to read everything, then confirmed=true to execute.`,
       const repoRoot = findRepoRoot(cwd)
       let gitResult  = null
 
+      // ── #1/#2 Preflight: repo readiness guard + autoStash ─────────────────
+      if (repoRoot && branch) {
+        try {
+          const porcelain = runGit('status --porcelain=v1', repoRoot)
+          const { localState, modified } = parseGitStatus(porcelain)
+          const currentBranchNow = runGit('branch --show-current', repoRoot).trim()
+          if (localState === 'modified') {
+            if (autoStash) {
+              // Auto-stash with a clear label so it can be recovered later
+              const stashLabel = `auto-stash(${task?.key?.toLowerCase() || 'unpark'}): changes on ${currentBranchNow} before switching to ${branch}`
+              runGit(`stash push -m "${stashLabel}"`, repoRoot)
+            } else {
+              return text({
+                blocked:      true,
+                reason:       `Working tree has ${modified.length} modified file(s) on "${currentBranchNow}" — cannot switch branches safely.`,
+                modifiedFiles: modified,
+                choices: {
+                  stash:  `git stash push -m "wip: before unpark ${task?.key || ''} on ${currentBranchNow}"`,
+                  commit: `git add . && git commit -m "wip(${task?.key?.toLowerCase() || 'task'}): before unpark"`,
+                  autoStash: `Call unpark_task again with autoStash=true — MCP will stash automatically with a labelled entry`,
+                  cancel: 'Review and handle your changes, then retry',
+                },
+                message: 'Handle the working tree before switching branches. Tip: use autoStash=true to let MCP do it automatically.',
+              })
+            }
+          }
+        } catch { /* non-fatal — proceed with checkout anyway */ }
+      }
+
       if (repoRoot && branch) {
         try {
           runGit('fetch origin', repoRoot)
@@ -516,10 +552,15 @@ Set confirmed=false first to read everything, then confirmed=true to execute.`,
         cursorRulesFile = writeCursorRulesFile(task.key, task.cursorRules, repoPath)
       }
 
+      // ── #9 Last commit metadata for handoff context ───────────────────────
+      const lastCommit = getLastCommitMeta(repoRoot)
+
       return text({
         unparked: true,
         task:     { key: task?.key, title: task?.title },
         git:      gitResult || { switched: false, reason: 'No branch linked or repo not found' },
+        autoStashed: autoStash ? 'Changes were auto-stashed before branch switch. Run: git stash list to see them.' : null,
+        lastCommit: lastCommit || null,
         cursorRules: cursorRulesFile ? { restored: true, path: cursorRulesFile } : { restored: false },
         commentPosted:       true,
         previousDevNotified: true,
@@ -530,6 +571,482 @@ Set confirmed=false first to read everything, then confirmed=true to execute.`,
       })
     }
   )
+
+  // ── review_pr ────────────────────────────────────────────────────────────────
+  server.tool(
+    'review_pr',
+    `Fetch everything needed to do a thorough PR review: PR details, full code diff, CI status, and the task's implementation plan.
+
+Returns the diff file-by-file (filename, additions, deletions, patch hunks), the task's README spec, acceptance criteria, and CI check results so you can verify code against the plan.
+
+Call this FIRST before post_pr_review. Use it when the developer asks "review PR", "check the PR for TASK-X", or "is this PR ready to merge".`,
+    {
+      taskId:    z.string().describe("Task's MongoDB ObjectId (used to find the project + PR number)"),
+    },
+    async ({ taskId }) => {
+      const taskRes = await apiWithRetry(() => api.get(`/api/tasks/${taskId}`))
+      if (!taskRes?.success) return errorText('Task not found')
+      const task = taskRes.data.task
+
+      const prNumber = task.github?.prNumber
+      if (!prNumber) return errorText('No PR linked to this task. The developer must raise_pr first.')
+
+      const projectId = task.project?._id || task.project
+      const res = await apiWithRetry(() => api.get(`/api/projects/${projectId}/github/pull-requests/${prNumber}`))
+      if (!res?.success) return errorText(res?.message || 'Could not fetch PR from GitHub')
+
+      const { pr, files, checks, task: linkedTask } = res.data
+
+      // Build a reviewer checklist from the implementation plan
+      const hasReadme = linkedTask?.readmeMarkdown?.trim()
+      const checklist = [
+        '[ ] Code matches the implementation plan (README)',
+        '[ ] All subtasks/acceptance criteria covered',
+        '[ ] No obvious bugs or edge cases missed',
+        '[ ] No hardcoded secrets or credentials',
+        '[ ] Error handling is in place where needed',
+        '[ ] No console.log / debug code left in',
+        checks?.anyFailed  ? '[ ] ⚠️  CI checks are failing — investigate before approving' : '[ ] CI checks passing ✅',
+        pr.changesRequested > 0 ? `[ ] ⚠️  ${pr.changesRequested} reviewer(s) already requested changes` : null,
+      ].filter(Boolean)
+
+      return text({
+        pr: {
+          number:         pr.number,
+          title:          pr.title,
+          author:         pr.author,
+          headBranch:     pr.headBranch,
+          baseBranch:     pr.baseBranch,
+          state:          pr.state,
+          approvals:      pr.approvals,
+          changesRequested: pr.changesRequested,
+          mergeable:      pr.mergeable,
+          mergeableState: pr.mergeableState,
+          url:            pr.htmlUrl,
+        },
+        ci: checks || { runs: [], allPassed: null, note: 'Could not fetch CI checks' },
+        diff: {
+          totalFiles:     files.length,
+          totalAdditions: files.reduce((s, f) => s + f.additions, 0),
+          totalDeletions: files.reduce((s, f) => s + f.deletions, 0),
+          files: files.map(f => ({
+            filename:  f.filename,
+            status:    f.status,
+            additions: f.additions,
+            deletions: f.deletions,
+            patch:     f.patch || '(binary or no diff)',
+          })),
+        },
+        spec: {
+          taskKey:            linkedTask?.key,
+          taskTitle:          linkedTask?.title,
+          implementationPlan: hasReadme ? linkedTask.readmeMarkdown : '⚠️  No implementation plan — review code against description only.',
+          description:        linkedTask?.description || null,
+        },
+        reviewChecklist: checklist,
+        nextStep: pr.approvals > 0 && !pr.changesRequested
+          ? `PR has ${pr.approvals} approval(s) and no changes requested. Call merge_pr with taskId="${taskId}" when ready.`
+          : `Review the diff above against the spec, then call post_pr_review with taskId="${taskId}" to post your verdict.`,
+      })
+    }
+  )
+
+  // ── post_pr_review ────────────────────────────────────────────────────────────
+  server.tool(
+    'post_pr_review',
+    `Post a GitHub PR review after analyzing the code diff.
+
+Supports three actions:
+- APPROVE         — Approves the PR. Notifies the developer they can merge.
+- REQUEST_CHANGES — Blocks merge. Developer gets notified. Task board updated.
+- COMMENT         — Leaves a comment without approving or blocking.
+
+Always call review_pr first to get the diff and spec context. Then call this with your verdict and reasoning.
+
+IMPORTANT: This posts a real GitHub review and updates the InternalTool board. The human must confirm before this runs — always show the review body to the user and ask for approval before calling with confirmed=true.`,
+    {
+      taskId:    z.string().describe("Task's MongoDB ObjectId"),
+      event:     z.enum(['APPROVE', 'REQUEST_CHANGES', 'COMMENT']).describe('Review action'),
+      body:      z.string().describe('Review summary — be specific: what was good, what needs fixing, which files/lines'),
+      confirmed: z.boolean().optional().default(false).describe('Set true only after the human has read and approved the review text'),
+    },
+    async ({ taskId, event, body: reviewBody, confirmed = false }) => {
+      const taskRes = await apiWithRetry(() => api.get(`/api/tasks/${taskId}`))
+      if (!taskRes?.success) return errorText('Task not found')
+      const task = taskRes.data.task
+
+      const prNumber  = task.github?.prNumber
+      const projectId = task.project?._id || task.project
+      if (!prNumber) return errorText('No PR linked to this task.')
+
+      // Always preview first — human must confirm
+      if (!confirmed) {
+        return text({
+          preview: {
+            action:    event,
+            prNumber,
+            taskKey:   task.key,
+            taskTitle: task.title,
+            reviewBody,
+          },
+          warning: event === 'APPROVE'
+            ? '✅ This will APPROVE the PR on GitHub and notify the developer they can merge.'
+            : event === 'REQUEST_CHANGES'
+            ? '⚠️  This will REQUEST CHANGES — the developer will be blocked from merging until they fix the issues and you re-approve.'
+            : 'ℹ️  This will post a comment on the PR without approving or blocking.',
+          requiresConfirmation: true,
+          message: `Show the review body above to the user and ask them to confirm. Then call post_pr_review again with confirmed=true.`,
+        })
+      }
+
+      const res = await api.post(
+        `/api/projects/${projectId}/github/pull-requests/${prNumber}/reviews`,
+        { event, body: reviewBody }
+      )
+      if (!res?.success) return errorText(res?.message || 'Could not post review')
+
+      return text({
+        posted:    true,
+        event,
+        prNumber,
+        taskKey:   task.key,
+        message:   event === 'APPROVE'
+          ? `✅ PR #${prNumber} approved. Developer has been notified and can now merge.`
+          : event === 'REQUEST_CHANGES'
+          ? `⚠️  Changes requested on PR #${prNumber}. Developer has been notified. Task board updated.`
+          : `💬 Comment posted on PR #${prNumber}.`,
+        nextStep: event === 'APPROVE'
+          ? `Call merge_pr with taskId="${taskId}" to merge, or wait for the developer to merge.`
+          : event === 'REQUEST_CHANGES'
+          ? `Wait for the developer to push fixes. They'll call fix_pr_feedback, then re-push. You'll get notified.`
+          : null,
+      })
+    }
+  )
+
+  // ── merge_pr ─────────────────────────────────────────────────────────────────
+  server.tool(
+    'merge_pr',
+    `Merge a pull request after human approval. Runs safety checks before executing.
+
+Safety checks (pre-merge):
+- PR must be open and not already merged
+- No pending change requests
+- CI checks must be passing (pass skipChecks=true to override)
+
+Human approval gate:
+- confirmed=false (default): shows safety check results and asks for confirmation
+- confirmed=true:            executes the merge
+
+The task moves to Done automatically via the existing GitHub webhook. A final comment is posted on the task.
+
+Use this when the reviewer says "merge it", "looks good, ship it", or "merge the PR for TASK-X".`,
+    {
+      taskId:      z.string().describe("Task's MongoDB ObjectId"),
+      confirmed:   z.boolean().optional().default(false).describe('Set true only after the human has reviewed the safety checks and approved the merge'),
+      mergeMethod: z.enum(['squash', 'merge', 'rebase']).optional().default('squash').describe('Merge strategy (default: squash)'),
+      commitTitle: z.string().optional().describe('Override the merge commit title. Defaults to PR title (#number).'),
+      skipChecks:  z.boolean().optional().default(false).describe('Skip CI check gate — use only when checks are informational or flaky'),
+    },
+    async ({ taskId, confirmed = false, mergeMethod = 'squash', commitTitle, skipChecks = false }) => {
+      const taskRes = await apiWithRetry(() => api.get(`/api/tasks/${taskId}`))
+      if (!taskRes?.success) return errorText('Task not found')
+      const task = taskRes.data.task
+
+      const prNumber  = task.github?.prNumber
+      const projectId = task.project?._id || task.project
+      if (!prNumber) return errorText(`No PR linked to task ${task.key}. The developer must raise_pr first.`)
+
+      // Fetch current PR state + checks for the preview
+      const prContextRes = await api.get(`/api/projects/${projectId}/github/pull-requests/${prNumber}`)
+      if (!prContextRes?.success) return errorText('Could not fetch PR details from GitHub')
+      const { pr, checks } = prContextRes.data
+
+      if (pr.merged) {
+        return text({ alreadyMerged: true, message: `PR #${prNumber} is already merged. Task should be in Done.` })
+      }
+      if (pr.state !== 'open') {
+        return text({ blocked: true, reason: `PR #${prNumber} is ${pr.state} — cannot merge a closed PR.` })
+      }
+
+      // Build safety check summary
+      const safetyChecks = [
+        { check: 'PR is open',             pass: pr.state === 'open' },
+        { check: 'Not already merged',     pass: !pr.merged },
+        { check: 'No change requests',     pass: pr.changesRequested === 0,
+          note: pr.changesRequested > 0 ? `${pr.changesRequested} reviewer(s) requested changes` : null },
+        { check: `CI checks (${checks?.total ?? 0} runs)`,
+          pass: skipChecks ? null : (checks?.allPassed ?? null),
+          note: skipChecks ? 'Skipped by request' : checks?.anyFailed ? 'Some checks failed' : checks?.allPassed ? 'All passing' : 'No checks found' },
+        { check: 'Has at least one approval', pass: pr.approvals > 0,
+          note: pr.approvals === 0 ? 'No approvals yet — consider running post_pr_review first' : `${pr.approvals} approval(s)` },
+      ]
+
+      const hardBlocks = safetyChecks.filter(c => c.pass === false && c.check !== `CI checks (${checks?.total ?? 0} runs)`)
+      const ciBlocked  = !skipChecks && checks?.anyFailed
+
+      if (!confirmed) {
+        return text({
+          pr: {
+            number:      pr.number,
+            title:       pr.title,
+            author:      pr.author,
+            headBranch:  pr.headBranch,
+            approvals:   pr.approvals,
+            url:         pr.htmlUrl,
+          },
+          safetyChecks,
+          mergeStrategy: mergeMethod,
+          blocked: hardBlocks.length > 0 || ciBlocked,
+          blockers: [
+            ...hardBlocks.map(c => c.note || c.check),
+            ciBlocked ? 'CI checks are failing (pass skipChecks=true to override)' : null,
+          ].filter(Boolean),
+          requiresConfirmation: hardBlocks.length === 0 && !ciBlocked,
+          message: hardBlocks.length > 0 || ciBlocked
+            ? `⚠️  Merge blocked. Resolve the issues above before merging.`
+            : `Show the safety checks above to the user and ask them to confirm the merge. Then call merge_pr again with confirmed=true.`,
+        })
+      }
+
+      // Hard-block even on confirmed=true if there are unresolved change requests
+      if (pr.changesRequested > 0) {
+        return text({
+          blocked: true,
+          reason:  `Cannot merge: ${pr.changesRequested} reviewer(s) have requested changes. They must approve before merging.`,
+        })
+      }
+
+      // Execute merge
+      const mergeRes = await api.put(
+        `/api/projects/${projectId}/github/pull-requests/${prNumber}/merge`,
+        { mergeMethod, commitTitle: commitTitle || undefined, skipChecks }
+      )
+      if (!mergeRes?.success) return errorText(mergeRes?.message || 'Merge failed')
+
+      if (mergeRes.data?.alreadyMerged) {
+        return text({ merged: true, message: 'PR was already merged.' })
+      }
+
+      return text({
+        merged:      true,
+        sha:         mergeRes.data?.sha,
+        prNumber,
+        taskKey:     task.key,
+        mergeMethod,
+        message:     `✅ PR #${prNumber} merged via ${mergeMethod}. Task "${task.key}" will move to Done automatically.`,
+        nextStep:    `The GitHub webhook will update the board. If the task doesn't move to Done within a minute, call update_task with column="done" manually.`,
+      })
+    }
+  )
+
+  // ── resume_task ───────────────────────────────────────────────────────────────
+  server.tool(
+    'resume_task',
+    `One-click safe resume for a task you previously worked on.
+
+Combines: context fetch + dirty-tree check + optional auto-stash + checkout + pull + readiness summary.
+
+Use this when the developer says "resume task", "get back to task X", "continue my work on", or
+"switch back to TASK-KEY". Prefer this over manually running git commands.
+
+Flow:
+1. confirmed=false (default) → shows full context: park note, last commits, working-tree state, what will happen
+2. confirmed=true            → executes: stash (if needed + autoStash=true), checkout, pull, restore cursor rules, return readiness summary`,
+    {
+      taskId:    z.string().describe("Task's MongoDB ObjectId"),
+      confirmed: z.boolean().optional().default(false).describe('Set true after reviewing the context to execute the resume'),
+      repoPath:  z.string().optional().describe('Absolute path to the local git repo. Defaults to MCP process working directory.'),
+      autoStash: z.boolean().optional().default(false).describe('If working tree is dirty, auto-stash before switching. Labelled with task key.'),
+    },
+    async ({ taskId, confirmed = false, repoPath, autoStash = false }) => {
+      // ── Fetch task ────────────────────────────────────────────────────────
+      let taskRes
+      try { taskRes = await apiWithRetry(() => api.get(`/api/tasks/${taskId}`)) }
+      catch (e) { return errorText(`Could not fetch task: ${e.message}`) }
+      if (!taskRes?.success) return errorText(taskRes?.message || 'Task not found')
+      const task   = taskRes.data.task
+      const branch = task?.github?.headBranch || null
+
+      // ── Fetch recent comments ─────────────────────────────────────────────
+      let recentComments = []
+      try {
+        const commentsRes = await api.get(`/api/tasks/${taskId}/comments`)
+        recentComments = (commentsRes?.data?.comments || []).slice(-5).map(c => ({
+          author: c.author?.name || c.author?.email || 'unknown',
+          body:   c.body?.slice(0, 300),
+          at:     c.createdAt,
+        }))
+      } catch { /* non-fatal */ }
+
+      // ── Fetch recent commits on branch ────────────────────────────────────
+      let recentCommits = []
+      if (branch) {
+        try {
+          const commitsRes = await api.get(`/api/projects/${task.project}/github/commits?per_page=5&branch=${branch}`)
+          recentCommits = (commitsRes?.data?.commits || []).map(c => ({
+            sha:     c.sha?.slice(0, 7),
+            message: c.commit?.message?.split('\n')[0],
+            author:  c.commit?.author?.name,
+            date:    c.commit?.author?.date,
+          }))
+        } catch { /* non-fatal */ }
+      }
+
+      // ── Inspect local repo state ──────────────────────────────────────────
+      const repoRoot = findRepoRoot(repoPath || process.cwd())
+      let localState = 'clean'
+      let modified   = []
+      let currentBranch = null
+      let alreadyOnBranch = false
+
+      if (repoRoot) {
+        try {
+          const porcelain = runGit('status --porcelain=v1', repoRoot)
+          const parsed    = parseGitStatus(porcelain)
+          localState      = parsed.localState
+          modified        = parsed.modified
+          currentBranch   = runGit('branch --show-current', repoRoot).trim()
+          alreadyOnBranch = branch && currentBranch === branch
+        } catch { /* non-fatal */ }
+      }
+
+      // ── Preview ───────────────────────────────────────────────────────────
+      if (!confirmed) {
+        const willStash   = localState === 'modified' && !alreadyOnBranch
+        const stashBlocks = willStash && !autoStash
+
+        return text({
+          task: {
+            key:      task.key,
+            title:    task.title,
+            column:   task.column,
+            priority: task.priority,
+            branch:   branch || '(no branch)',
+          },
+          parkNote:      task.parkNote || null,
+          recentCommits: recentCommits.length ? recentCommits : ['No remote commits found'],
+          recentComments,
+          localRepo: repoRoot ? {
+            root:          repoRoot,
+            currentBranch,
+            alreadyOnBranch,
+            workingTree:   localState,
+            modifiedFiles: modified.length ? modified : null,
+          } : { found: false, note: 'No git repo found at ' + (repoPath || process.cwd()) },
+          willDo: branch && !alreadyOnBranch ? [
+            willStash && autoStash ? `git stash push -m "auto-stash(${task.key?.toLowerCase()}): changes on ${currentBranch} before resuming"` : null,
+            `git fetch origin`,
+            `git checkout ${branch}`,
+            `git pull origin ${branch}`,
+            task?.cursorRules?.trim() ? `Restore .cursor/rules/${task.key?.toLowerCase()}.mdc` : null,
+          ].filter(Boolean) : alreadyOnBranch ? [`git pull origin ${branch} (already on branch)`] : ['No branch to switch to'],
+          blocked: stashBlocks ? {
+            reason:  `Working tree is dirty (${modified.length} file(s) modified) and you are not on the task branch.`,
+            choices: {
+              autoStash: `Call resume_task again with autoStash=true — MCP stashes automatically`,
+              manual:    `git stash push -m "wip: before resuming ${task.key}"`,
+              cancel:    `Commit or discard your current changes first`,
+            },
+          } : null,
+          requiresConfirmation: !stashBlocks,
+          message: stashBlocks
+            ? `Working tree is dirty — resolve or pass autoStash=true, then call resume_task with confirmed=true.`
+            : `Review the context above, then call resume_task again with confirmed=true to switch branches and resume.`,
+        })
+      }
+
+      // ── Execute ───────────────────────────────────────────────────────────
+      if (!branch) {
+        return text({
+          resumed: false,
+          reason:  'No branch linked to this task yet.',
+          nextStep: `Call create_branch with taskId="${taskId}" to create one.`,
+        })
+      }
+
+      // Handle dirty tree
+      if (localState === 'modified' && !alreadyOnBranch) {
+        if (autoStash) {
+          try {
+            const stashLabel = `auto-stash(${task.key?.toLowerCase()}): changes on ${currentBranch} before resuming ${branch}`
+            runGit(`stash push -m "${stashLabel}"`, repoRoot)
+          } catch (e) {
+            return text({
+              resumed:  false,
+              reason:   `Auto-stash failed: ${e.message.split('\n')[0]}`,
+              nextStep: `Manually run: git stash push -m "wip" then retry.`,
+            })
+          }
+        } else {
+          return text({
+            blocked:  true,
+            reason:   `Working tree has ${modified.length} modified file(s). Cannot switch branches safely.`,
+            choices: {
+              autoStash: `Call resume_task again with confirmed=true and autoStash=true`,
+              manual:    `git stash push -m "wip: before resuming ${task.key}"`,
+              cancel:    `Commit or discard your changes first`,
+            },
+          })
+        }
+      }
+
+      // Switch branch + pull
+      let gitResult = null
+      if (repoRoot) {
+        if (alreadyOnBranch) {
+          try {
+            const pullOut = runGit(`pull origin ${branch}`, repoRoot)
+            gitResult = { switched: false, alreadyOnBranch: true, pulled: true, pullOutput: pullOut.slice(0, 200) }
+          } catch (e) {
+            gitResult = { switched: false, alreadyOnBranch: true, pulled: false, error: e.message.split('\n')[0] }
+          }
+        } else {
+          try {
+            runGit('fetch origin', repoRoot)
+            runGit(`checkout ${branch}`, repoRoot)
+            const pullOut = runGit(`pull origin ${branch}`, repoRoot)
+            gitResult = { switched: true, branch, pulled: true, pullOutput: pullOut.slice(0, 200) }
+          } catch (e) {
+            gitResult = {
+              switched: false,
+              error:    e.message.split('\n')[0],
+              manualSteps: [`git fetch origin`, `git checkout ${branch}`, `git pull origin ${branch}`],
+            }
+          }
+        }
+      }
+
+      // Restore cursor rules
+      let cursorRulesFile = null
+      if (task?.cursorRules?.trim() && repoRoot) {
+        cursorRulesFile = writeCursorRulesFile(task.key, task.cursorRules, repoPath)
+      }
+
+      // Last commit metadata
+      const lastCommit = getLastCommitMeta(repoRoot)
+
+      return text({
+        resumed:     true,
+        task:        { key: task.key, title: task.title, column: task.column },
+        git:         gitResult || { switched: false, reason: 'No repo found' },
+        autoStashed: autoStash && localState === 'modified' && !alreadyOnBranch
+          ? `Changes stashed before switch. Run: git stash list to see them.`
+          : null,
+        lastCommit:  lastCommit || null,
+        parkNote:    task.parkNote || null,
+        cursorRules: cursorRulesFile ? { restored: true, path: cursorRulesFile } : { restored: false },
+        message: gitResult?.switched || gitResult?.alreadyOnBranch
+          ? `You are on branch "${branch}". Ready to resume coding.`
+          : `Branch switch failed — see git.manualSteps.`,
+        nextStep: task.column === 'in_review'
+          ? `Task is in review. Check if PR feedback needs addressing — call fix_pr_feedback if needed.`
+          : task.parkNote?.remaining
+            ? `Remaining: ${task.parkNote.remaining}`
+            : `Continue coding on "${branch}".`,
+      })
+    }
+  )
 }
 
 // ── Standup activity formatter ────────────────────────────────────────────────
@@ -542,9 +1059,10 @@ function formatActivityLine(a) {
     case 'task.moved':      return `Moved from ${m.from} → ${m.to}`
     case 'task.branch_linked': return `Branch linked: ${m.headBranch}`
     case 'comment.created': return 'Comment posted'
-    case 'approval.submitted': return `Sent for approval → ${m.reviewerName || 'reviewer'}`
-    case 'approval.approved':  return `Plan approved${m.note ? ': ' + m.note : ''}`
-    case 'approval.rejected':  return `Plan rejected${m.note ? ': ' + m.note : ''}`
+    case 'approval.submitted':   return `Sent for approval → ${m.reviewerName || 'reviewer'}`
+    case 'approval.approved':    return `Plan approved${m.note ? ': ' + m.note : ''}`
+    case 'approval.rejected':    return `Plan rejected${m.note ? ': ' + m.note : ''}`
+    case 'approval.ai_reviewed': return `AI review submitted by ${m.agentName || 'AI'} — ${m.recommendation || 'needs_work'}`
     case 'task.merged_from_github':      return `PR #${m.prNumber} merged → done`
     case 'task.pr_opened_to_review':     return `PR #${m.prNumber} opened — moved to in_review`
     case 'task.pr_linked_in_review':     return `PR #${m.prNumber} linked (already in review)`
@@ -1053,8 +1571,9 @@ Use this when a developer says "start task", "brief me on", or "what do I need t
       const subtasksTotal = subtasks.length
 
       // ── Preview: show the full plan before touching anything ──
-      const approvalState = task.approval?.state || 'none'
-      const approvalBlocks = ['backlog', 'todo'].includes(task.column) && approvalState !== 'approved'
+      const pendingApv = (task.approvals || []).find(a => a.state === 'pending') || null
+      const hasApprovedApv = (task.approvals || []).some(a => a.state === 'approved')
+      const approvalBlocks = ['backlog', 'todo'].includes(task.column) && !hasApprovedApv
 
       // Build the next-step roadmap so developer knows exactly what comes after reading the plan
       let workflowRoadmap
@@ -1087,35 +1606,87 @@ Use this when a developer says "start task", "brief me on", or "what do I need t
       }
 
       // ── Simultaneous work lock ──────────────────────────────────────────────────
-      // If the task is already in_progress with a branch, warn before proceeding.
-      // This prevents two developers from unknowingly working on the same task.
       const alreadyActive = task.column === 'in_progress' && !!task.github?.headBranch
-      const activeAssignees = (task.assignees || []).map(a => a.name || a.email || a.toString())
 
       if (!confirmed && alreadyActive) {
+        // Determine the active owner precisely:
+        // currentOwner = whoever last unparked (actively working now)
+        // parkedBy     = whoever parked (task is idle, waiting for pickup)
+        // fallback     = assignees list
+        const currentOwner = task.parkNote?.currentOwner
+        const parkedBy     = task.parkNote?.parkedBy
+        const isParked     = !!task.parkNote?.parkedAt
+
+        const activeOwnerName = currentOwner
+          ? (currentOwner.name || currentOwner.email || currentOwner.toString())
+          : null
+        const parkedByName = parkedBy
+          ? (parkedBy.name || parkedBy.email || parkedBy.toString())
+          : null
+        const assigneeNames = (task.assignees || []).map(a => a.name || a.email || a.toString())
+
+        // Who is actively coding right now?
+        let activeWorker, situation, advice
+        if (isParked) {
+          activeWorker = null
+          situation = `Task is parked by ${parkedByName || 'a developer'} — no one is actively coding. Safe to pick up via unpark_task.`
+          advice = `Call unpark_task with taskId="${taskId}" to take ownership and continue from where ${parkedByName || 'they'} left off.`
+        } else if (activeOwnerName) {
+          activeWorker = activeOwnerName
+          situation = `${activeOwnerName} is actively working on this task right now.`
+          advice = `Contact ${activeOwnerName} directly before taking over. Do NOT push to branch "${task.github.headBranch}" — it will cause a conflict.`
+        } else if (assigneeNames.length) {
+          activeWorker = assigneeNames.join(', ')
+          situation = `${assigneeNames.join(' and ')} ${assigneeNames.length > 1 ? 'are' : 'is'} assigned to this task and it is in progress.`
+          advice = `Check with ${assigneeNames.join(', ')} before taking over.`
+        } else {
+          activeWorker = null
+          situation = `Task is in progress with no clear owner.`
+          advice = `Check the branch "${task.github.headBranch}" before starting fresh.`
+        }
+
+        // Notify all project members that someone attempted to take an active task
+        try {
+          const projectRes = await api.get(`/api/projects/${task.project}`)
+          const members = projectRes?.data?.project?.members || []
+          const meRes = await api.get('/api/auth/me')
+          const meName = meRes?.data?.user?.name || meRes?.data?.name || 'Someone'
+          const meId   = meRes?.data?.user?._id  || meRes?.data?._id  || ''
+          for (const memberId of members) {
+            const id = memberId._id || memberId.toString()
+            if (id !== meId) {
+              await api.post('/api/notifications/task-event', {
+                recipient: id,
+                type:      'task_assigned',
+                title:     `👀 ${meName} tried to start ${task.key}`,
+                body:      `${meName} attempted to kick off "${task.title}" which is already active${activeOwnerName ? ` (owned by ${activeOwnerName})` : ''}.`,
+                link:      `/projects/${task.project}/tasks/${taskId}`,
+                taskId,
+              }).catch(() => {/* non-fatal */})
+            }
+          }
+        } catch { /* non-fatal — don't block the warning */ }
+
         return text({
           warning: {
-            type:       'simultaneous_work_detected',
-            message:    `⚠️ This task is already in progress on branch "${task.github.headBranch}".`,
-            assignees:  activeAssignees.length ? activeAssignees : ['(unassigned)'],
-            branch:     task.github.headBranch,
-            parkNote:   task.parkNote || null,
-            advice:     activeAssignees.length
-              ? `Check with ${activeAssignees.join(', ')} before taking over. If they have parked this task their changes are pushed — checkout their branch instead of starting fresh.`
-              : `Someone may have been working on this. Check the branch before starting fresh.`,
+            type:        'simultaneous_work_detected',
+            situation,
+            activeWorker: activeWorker || '(unknown)',
+            isParked,
+            branch:      task.github.headBranch,
+            parkNote:    isParked ? task.parkNote : null,
+            advice,
             checkoutSteps: [
               'git fetch origin',
               `git checkout ${task.github.headBranch}`,
               `git pull origin ${task.github.headBranch}`,
             ],
           },
-          brief: {
-            key:         task.key,
-            title:       task.title,
-            priority:    task.priority,
-          },
+          brief: { key: task.key, title: task.title, priority: task.priority },
           requiresConfirmation: true,
-          message: `Task is already in progress. Read the warning above. If you still want to take over, call kickoff_task again with confirmed=true.`,
+          message: isParked
+            ? `Task is parked. Use unpark_task instead of kickoff_task to continue safely.`
+            : `⚠️ ${activeWorker || 'Someone'} is actively working on this. Do not take over without coordinating first. Call kickoff_task with confirmed=true only if you have confirmed with them.`,
         })
       }
 
@@ -1158,6 +1729,32 @@ Use this when a developer says "start task", "brief me on", or "what do I need t
         })
       }
 
+      // ── #1 Preflight: check dirty tree before writing cursor rules / moving task ──
+      {
+        const pCwd  = repoPath || process.cwd()
+        const pRoot = findRepoRoot(pCwd)
+        if (pRoot) {
+          try {
+            const porcelain = runGit('status --porcelain=v1', pRoot)
+            const { localState, modified } = parseGitStatus(porcelain)
+            const currentBranchNow = runGit('branch --show-current', pRoot).trim()
+            if (localState === 'modified' && task.github?.headBranch && currentBranchNow !== task.github.headBranch) {
+              return text({
+                blocked:      true,
+                reason:       `You are on "${currentBranchNow}" with ${modified.length} modified file(s), but this task's branch is "${task.github.headBranch}".`,
+                modifiedFiles: modified,
+                choices: {
+                  stash:   `git stash push -m "wip: before kickoff ${task.key} on ${currentBranchNow}"`,
+                  autoSwitch: `Switch to ${task.github.headBranch}: git stash && git checkout ${task.github.headBranch} && git stash pop`,
+                  cancel:  'Review your changes first, then retry kickoff_task',
+                },
+                message: 'Resolve the working tree before kicking off this task to avoid cross-task pollution.',
+              })
+            }
+          } catch { /* non-fatal */ }
+        }
+      }
+
       // ── Confirmed: move to in_progress and fetch recent commits ──
       let recentCommits = []
       try {
@@ -1340,25 +1937,162 @@ function registerIssueTools(server) {
 function registerApprovalTools(server) {
   server.tool(
     'submit_task_for_approval',
-    'Submit a task implementation plan for review. README must be at least 80 characters.',
+    'Create and submit a new approval request on a task. Each request has its own title, plan/readme, and reviewer. Only one request can be pending at a time.',
     {
       taskId:     z.string().describe("Task's MongoDB ObjectId"),
+      title:      z.string().describe('Short title for this approval request, e.g. "Experiment: Add caching layer"'),
+      readme:     z.string().describe('The plan/markdown describing what you want to do and why (min 80 chars)'),
       reviewerId: z.string().describe('User ID of the reviewer'),
     },
-    async ({ taskId, reviewerId }) =>
-      call(() => api.post(`/api/tasks/${taskId}/approval/submit`, { reviewerId }))
+    async ({ taskId, title, readme, reviewerId }) =>
+      call(() => api.post(`/api/tasks/${taskId}/approvals`, { title, readme, reviewerId }))
   )
 
   server.tool(
     'decide_task_approval',
-    'Approve or reject a task plan. Only the designated reviewer can call this.',
+    'Approve or reject a specific approval request by approvalId. Only the designated reviewer can call this.',
     {
-      taskId:   z.string().describe("Task's MongoDB ObjectId"),
-      decision: z.enum(['approve', 'reject']),
-      note:     z.string().optional().describe('Reason for the decision'),
+      taskId:     z.string().describe("Task's MongoDB ObjectId"),
+      approvalId: z.string().describe("Approval request's MongoDB ObjectId (from the task's approvals array)"),
+      decision:   z.enum(['approve', 'reject']),
+      note:       z.string().optional().describe('Reason for the decision'),
+    },
+    async ({ taskId, approvalId, decision, note }) =>
+      call(() => api.post(`/api/tasks/${taskId}/approvals/${approvalId}/decide`, { decision, note }))
+  )
+}
+
+function registerAIReviewTools(server) {
+  server.tool(
+    'list_pending_reviews',
+    `List all tasks currently pending your review across all your projects.
+
+Returns task key, title, plan length, who submitted, how long it has been waiting, and whether a PR is linked.
+Call this when you want to know "what needs reviewing?" or to start a review session.`,
+    {},
+    async () => {
+      const projectsRes = await api.get('/api/projects')
+      const projects = projectsRes?.data?.projects || []
+
+      const boards = await Promise.all(
+        projects.map(async p => {
+          try {
+            const r = await api.get(`/api/projects/${p._id}`)
+            return { project: r?.data?.project, tasks: r?.data?.tasks || [] }
+          } catch { return null }
+        })
+      )
+
+      const meRes = await api.get('/api/auth/me')
+      const meId = meRes?.data?.user?._id || ''
+
+      const pending = []
+      const now = Date.now()
+      for (const board of boards.filter(Boolean)) {
+        for (const t of board.tasks) {
+          const pendingApv = (t.approvals || []).find(a => a.state === 'pending')
+          if (!pendingApv) continue
+          const reviewerId = pendingApv?.reviewer?._id || pendingApv?.reviewer
+          if (meId && reviewerId && String(reviewerId) !== String(meId)) continue
+          const waitingMs = pendingApv?.requestedAt ? now - new Date(pendingApv.requestedAt).getTime() : 0
+          const waitingHours = Math.round(waitingMs / (1000 * 60 * 60) * 10) / 10
+          pending.push({
+            taskId:         t._id,
+            approvalId:     pendingApv._id,
+            approvalTitle:  pendingApv.title || '',
+            key:            t.key,
+            title:          t.title,
+            project:        board.project?.name || '',
+            priority:       t.priority,
+            submittedBy:    pendingApv?.requestedBy?.name || pendingApv?.requestedBy?.email || 'unknown',
+            waitingHours,
+            planChars:      (pendingApv.readme || '').length,
+            hasPR:          !!(t.github?.prNumber),
+            prUrl:          t.github?.prUrl || null,
+            hasAIReview:    !!pendingApv?.aiReview,
+            aiRecommendation: pendingApv?.aiReview?.recommendation || null,
+          })
+        }
+      }
+
+      pending.sort((a, b) => b.waitingHours - a.waitingHours)
+
+      return text({
+        count: pending.length,
+        pendingReviews: pending,
+        message: pending.length === 0
+          ? 'No tasks pending your review.'
+          : `${pending.length} task(s) awaiting review. Call get_review_bundle with a taskId to start reviewing.`,
+      })
+    }
+  )
+
+  server.tool(
+    'get_review_bundle',
+    `Get everything needed to review a task as an AI code reviewer.
+
+Returns:
+- plan: full implementation README (what the developer planned to build)
+- prFiles: list of changed files in the PR with unified diffs (the actual code written)
+- recentCommits: last 20 commits on the task branch
+- comments: recent discussion on the task
+- openIssues: any open bugs logged on the task
+- approval: current approval state and any prior AI review
+
+After calling this, analyze the plan vs the code diff and call submit_ai_review with your findings.`,
+    {
+      taskId: z.string().describe("Task's MongoDB ObjectId"),
     },
-    async ({ taskId, decision, note }) =>
-      call(() => api.post(`/api/tasks/${taskId}/approval/decide`, { decision, note }))
+    async ({ taskId }) => call(() => api.get(`/api/tasks/${taskId}/review-bundle`))
+  )
+
+  server.tool(
+    'submit_ai_review',
+    `Submit a structured AI code review opinion on a specific approval request pending review.
+
+This does NOT override the human reviewer's decision — it attaches your analysis so the
+human reviewer can approve/reject faster with full AI context.
+
+Your review should cover:
+1. Does the experiment plan make sense and is it safe to implement?
+2. Are there security concerns, performance issues, or bugs in linked PR code?
+3. Is the plan clear and actionable?
+4. Are edge cases covered?
+
+Workflow:
+1. Call list_pending_reviews to find tasks awaiting review (returns taskId + approvalId)
+2. Call get_review_bundle to get the full context (plan + PR diff + commits)
+3. Analyze everything thoroughly
+4. Call submit_ai_review with your structured findings`,
+    {
+      taskId:     z.string().describe("Task's MongoDB ObjectId"),
+      approvalId: z.string().describe("Approval request's MongoDB ObjectId (from list_pending_reviews)"),
+      agentName:  z.string().optional().default('Claude Code').describe('Name of the AI agent doing the review'),
+      summary:    z.string().describe(
+        'Overall review narrative (2-5 paragraphs). Cover: plan quality, code quality, security, correctness.'
+      ),
+      recommendation: z.enum(['approve', 'reject', 'needs_work']).describe(
+        '"approve" = plan is solid; "needs_work" = minor issues; "reject" = significant problems'
+      ),
+      confidence: z.number().min(0).max(100).describe(
+        'How confident are you in this recommendation? 0 = very uncertain, 100 = very certain'
+      ),
+      checklist: z.array(z.object({
+        item:   z.string().describe('What was checked (e.g. "Error handling in API calls")'),
+        passed: z.boolean().describe('Did it pass?'),
+        note:   z.string().optional().describe('Brief explanation'),
+      })).describe('Structured checklist of what was reviewed'),
+      issues: z.array(z.object({
+        severity:    z.enum(['low', 'medium', 'high', 'critical']),
+        description: z.string().describe('What the issue is'),
+        suggestion:  z.string().optional().describe('How to fix it'),
+      })).optional().describe('Specific issues found in the code'),
+    },
+    async ({ taskId, approvalId, agentName, summary, recommendation, confidence, checklist, issues }) =>
+      call(() => api.post(`/api/tasks/${taskId}/approvals/${approvalId}/ai-review`, {
+        agentName, summary, recommendation, confidence, checklist,
+        issues: issues || [],
+      }))
   )
 }
 
@@ -1508,6 +2242,49 @@ function deleteCursorRulesFile(taskKey, startPath) {
   }
 }
 
+// ── #3 Better failure recovery: API call with auto-retry + structured cause ───
+async function apiWithRetry(fn, maxRetries = 2, initialDelay = 500) {
+  let lastErr
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await fn()
+    } catch (e) {
+      lastErr = e
+      const msg = (e.message || '').toLowerCase()
+      // Never retry auth / client errors
+      if (msg.includes('401') || msg.includes('403') || msg.includes('unauthorized') || msg.includes('forbidden')) {
+        throw Object.assign(e, { _cause: 'auth' })
+      }
+      if (msg.includes('404') || msg.includes('400') || msg.includes('422') || msg.includes('409')) {
+        throw Object.assign(e, { _cause: 'client' })
+      }
+      if (attempt < maxRetries) {
+        await new Promise(r => setTimeout(r, initialDelay * (attempt + 1)))
+      }
+    }
+  }
+  const msg = (lastErr?.message || '').toLowerCase()
+  const cause = (msg.includes('econnref') || msg.includes('network') || msg.includes('fetch failed') || msg.includes('enotfound'))
+    ? 'network'
+    : msg.includes('timeout') ? 'timeout' : 'server'
+  lastErr._cause = cause
+  throw lastErr
+}
+
+function wrapApiError(e) {
+  return { error: true, cause: e._cause || 'unknown', message: e.message?.split('\n')[0] }
+}
+
+// ── #9 Get last git commit metadata ──────────────────────────────────────────
+function getLastCommitMeta(repoRoot) {
+  if (!repoRoot) return null
+  try {
+    const raw = runGit('log -1 --format=%H%x09%s%x09%an%x09%ae%x09%ad --date=short', repoRoot)
+    const [sha, subject, authorName, authorEmail, date] = raw.split('\t')
+    return { sha: sha?.slice(0, 7), subject: subject?.trim(), author: authorName || authorEmail, date }
+  } catch { return null }
+}
+
 function parseGitStatus(porcelain) {
   const lines = porcelain.split('\n').filter(Boolean)
   const staged     = lines.filter(l => !' ?!'.includes(l[0])).map(l => ({ xy: l.slice(0, 2), file: l.slice(3) }))
@@ -1623,18 +2400,24 @@ The developer does not need to run any commands manually — this tool reads loc
   server.tool(
     'list_my_tasks',
     `List your assigned tasks sorted by priority (critical → high → medium → low).
-Each task includes a suggested next git action so Claude can guide you step by step.
+Each task includes a suggested next git action, ownership status (who currently owns / parked it),
+and branch consistency warnings so Claude can guide you step by step.
 Use this at the start of a session or when switching tasks.`,
     {
       includeColumns: z.array(
         z.enum(['backlog', 'todo', 'in_progress', 'in_review', 'done'])
       ).optional().default(['todo', 'in_progress', 'in_review'])
        .describe('Which columns to include. Default excludes backlog and done.'),
+      repoPath: z.string().optional().describe('Absolute path to local repo — used for branch consistency checks'),
     },
-    async ({ includeColumns = ['todo', 'in_progress', 'in_review'] } = {}) => {
+    async ({ includeColumns = ['todo', 'in_progress', 'in_review'], repoPath } = {}) => {
       const res = await api.get('/api/users/me/tasks')
       if (!res?.success) return errorText('Could not fetch tasks')
 
+      // #4 Local repo for branch consistency checks
+      const cwd      = repoPath || process.cwd()
+      const repoRoot = findRepoRoot(cwd)
+
       // Server already sorts by priority (critical → low) then updatedAt — just filter and annotate
       const tasks = (res.data.tasks || [])
         .filter(t => includeColumns.includes(t.column))
@@ -1649,6 +2432,44 @@ Use this at the start of a session or when switching tasks.`,
           } else if (t.column === 'in_review') {
             suggestedAction = `PR #${t.github?.prNumber || '?'} is open — waiting for reviewer feedback`
           }
+
+          // ── #6 Ownership visibility ───────────────────────────────────────
+          const currentOwner = t.parkNote?.currentOwner
+          const parkedBy     = t.parkNote?.parkedBy
+          const ownership = {
+            currentOwner: currentOwner
+              ? (currentOwner.name || currentOwner.email || String(currentOwner))
+              : null,
+            parkedBy: parkedBy
+              ? (parkedBy.name || parkedBy.email || String(parkedBy))
+              : null,
+            parkedAt:      t.parkNote?.parkedAt || null,
+            parkedSummary: t.parkNote?.summary  || null,
+          }
+
+          // ── #4 Branch consistency check ───────────────────────────────────
+          let branchConsistency = null
+          if (t.column === 'in_progress' && t.github?.headBranch && repoRoot) {
+            try {
+              let localExists = false, remoteExists = false
+              try { runGit(`rev-parse --verify ${t.github.headBranch}`, repoRoot); localExists = true } catch { /* not local */ }
+              try { runGit(`rev-parse --verify origin/${t.github.headBranch}`, repoRoot); remoteExists = true } catch { /* not remote */ }
+              if (!localExists && !remoteExists) {
+                branchConsistency = {
+                  warning: 'branch_not_found',
+                  message: `Branch "${t.github.headBranch}" does not exist locally or remotely.`,
+                  fixAction: `git fetch origin && git checkout ${t.github.headBranch}  — or use create_branch if it was never pushed`,
+                }
+              } else if (!localExists && remoteExists) {
+                branchConsistency = {
+                  warning: 'branch_remote_only',
+                  message: `Branch "${t.github.headBranch}" exists on remote but not locally.`,
+                  fixAction: `git fetch origin && git checkout ${t.github.headBranch}`,
+                }
+              }
+            } catch { /* non-fatal */ }
+          }
+
           return {
             id:             t._id,
             key:            t.key,
@@ -1658,11 +2479,193 @@ Use this at the start of a session or when switching tasks.`,
             project:        t.project?.name || t.project,
             github:         t.github ? { headBranch: t.github.headBranch, prNumber: t.github.prNumber, mergedAt: t.github.mergedAt } : null,
             parked:         !!t.parkNote?.parkedAt,
+            ownership,
+            branchConsistency,
             suggestedAction,
           }
         })
 
-      return text({ tasks, count: tasks.length })
+      const consistencyIssues = tasks.filter(t => t.branchConsistency).map(t => ({ key: t.key, ...t.branchConsistency }))
+
+      return text({
+        tasks,
+        count: tasks.length,
+        consistencyIssues: consistencyIssues.length ? consistencyIssues : null,
+      })
+    }
+  )
+
+  // ── #7 find_repo ─────────────────────────────────────────────────────────────
+  server.tool(
+    'find_repo',
+    `Scan the file system to find git repositories near a given path.
+
+Use this when the user says "I can't find my repo", points to a parent folder,
+or when create_branch / unpark_task fail because repoPath is wrong.
+
+Returns all git repos found within 2 directory levels, along with their current branch
+and whether they contain a .cursor/mcp.json (indicating InternalTool is configured there).`,
+    {
+      searchPath: z.string().optional().describe('Directory to scan from. Defaults to the MCP process working directory.'),
+    },
+    async ({ searchPath } = {}) => {
+      const base = searchPath || process.cwd()
+      const candidates = []
+
+      function tryRepo(dir) {
+        try {
+          const root = runGit('rev-parse --show-toplevel', dir)
+          if (candidates.some(c => c.repoRoot === root)) return  // already found
+          let currentBranch = null, hasMcpConfig = false
+          try { currentBranch = runGit('branch --show-current', root).trim() } catch { /* ok */ }
+          try { hasMcpConfig = existsSync(join(root, '.cursor', 'mcp.json')) } catch { /* ok */ }
+          candidates.push({ repoRoot: root, currentBranch, hasMcpConfig })
+        } catch { /* not a git repo */ }
+      }
+
+      // Level 0: the path itself
+      tryRepo(base)
+
+      // Level 1: immediate subdirectories
+      try {
+        const entries = readdirSync(base, { withFileTypes: true })
+        for (const e of entries) {
+          if (!e.isDirectory() || e.name.startsWith('.')) continue
+          const sub = join(base, e.name)
+          tryRepo(sub)
+          // Level 2: one more level deep
+          try {
+            const sub2Entries = readdirSync(sub, { withFileTypes: true })
+            for (const e2 of sub2Entries) {
+              if (!e2.isDirectory() || e2.name.startsWith('.')) continue
+              tryRepo(join(sub, e2.name))
+            }
+          } catch { /* ok */ }
+        }
+      } catch { /* ok */ }
+
+      if (!candidates.length) {
+        return text({
+          found: false,
+          searchedFrom: base,
+          message: `No git repositories found within 2 levels of "${base}". Try passing a searchPath closer to your project.`,
+        })
+      }
+
+      return text({
+        found:        true,
+        searchedFrom: base,
+        repos:        candidates,
+        count:        candidates.length,
+        tip: candidates.length === 1
+          ? `Use repoPath="${candidates[0].repoRoot}" in create_branch / unpark_task / park_task.`
+          : `Multiple repos found. Pass the correct one as repoPath to git workflow tools.`,
+      })
+    }
+  )
+
+  // ── #8 validate_mcp_config ───────────────────────────────────────────────────
+  server.tool(
+    'validate_mcp_config',
+    `Validate the .cursor/mcp.json configuration for InternalTool.
+
+Checks for common issues:
+- File not found or not valid JSON
+- Missing required fields (command, args, env.INTERNALTOOL_TOKEN)
+- Trailing spaces or wrong separators in the --url value
+- Token not starting with "ilt_"
+- Mismatched project URL vs server URL
+
+Use this when the MCP connection seems wrong or tools return unexpected auth errors.`,
+    {
+      repoPath: z.string().optional().describe('Path to search for .cursor/mcp.json (defaults to MCP working directory)'),
+    },
+    async ({ repoPath } = {}) => {
+      const cwd  = repoPath || process.cwd()
+      const root = findRepoRoot(cwd) || cwd
+
+      const configPath = join(root, '.cursor', 'mcp.json')
+      const issues = []
+      const fixes  = []
+
+      if (!existsSync(configPath)) {
+        return text({
+          valid: false,
+          configPath,
+          issues: ['File not found: .cursor/mcp.json does not exist in this repo'],
+          fixes: [
+            `Create it at: ${configPath}`,
+            `Minimal content:\n{\n  "mcpServers": {\n    "internaltool": {\n      "command": "npx",\n      "args": ["-y", "internaltool-mcp", "--url", "http://localhost:5001"],\n      "env": { "INTERNALTOOL_TOKEN": "ilt_your_token_here" }\n    }\n  }\n}`,
+          ],
+        })
+      }
+
+      let parsed = null
+      try {
+        const { readFileSync: rfs } = await import('fs')
+        const raw = rfs(configPath, 'utf8')
+        // Check for trailing space in path (a common copy-paste mistake on macOS)
+        if (configPath.includes(' ')) {
+          issues.push(`Path contains a space: "${configPath}" — rename the folder to remove it`)
+          fixes.push(`mv "${root}" "${root.replace(/ /g, '_')}"`)
+        }
+        parsed = JSON.parse(raw)
+      } catch (e) {
+        return text({
+          valid: false,
+          configPath,
+          issues: [`Invalid JSON: ${e.message}`],
+          fixes:  ['Open .cursor/mcp.json and fix the JSON syntax. Use jsonlint.com to validate.'],
+        })
+      }
+
+      const servers = parsed?.mcpServers || {}
+      const serverNames = Object.keys(servers)
+      if (!serverNames.length) {
+        issues.push('mcpServers object is empty — no server configured')
+        fixes.push('Add an "internaltool" entry under mcpServers')
+      }
+
+      for (const name of serverNames) {
+        const cfg = servers[name]
+        if (!cfg.command) { issues.push(`"${name}": missing "command" field`); fixes.push(`Set "command": "npx"`) }
+        const args = cfg.args || []
+        if (!args.includes('internaltool-mcp') && !args.some(a => a.includes('internaltool-mcp'))) {
+          issues.push(`"${name}": args do not include "internaltool-mcp"`)
+          fixes.push(`args should be: ["-y", "internaltool-mcp", "--url", "<your-server-url>"]`)
+        }
+        const urlIdx = args.indexOf('--url')
+        if (urlIdx === -1) {
+          issues.push(`"${name}": --url flag missing from args`)
+          fixes.push(`Add "--url", "http://localhost:5001" to args`)
+        } else {
+          const urlVal = args[urlIdx + 1] || ''
+          if (urlVal.endsWith(' ') || urlVal.startsWith(' ')) {
+            issues.push(`"${name}": --url value has leading/trailing space: "${urlVal}"`)
+            fixes.push(`Remove spaces: "${urlVal.trim()}"`)
+          }
+          if (!urlVal.startsWith('http://') && !urlVal.startsWith('https://')) {
+            issues.push(`"${name}": --url value looks invalid: "${urlVal}"`)
+            fixes.push(`Should start with http:// or https://`)
+          }
+        }
+        const token = cfg.env?.INTERNALTOOL_TOKEN
+        if (!token) {
+          issues.push(`"${name}": INTERNALTOOL_TOKEN not set in env`)
+          fixes.push(`Add: "env": { "INTERNALTOOL_TOKEN": "ilt_your_token" }`)
+        } else if (!token.startsWith('ilt_')) {
+          issues.push(`"${name}": INTERNALTOOL_TOKEN does not start with "ilt_" — may be wrong`)
+          fixes.push(`Regenerate your token in InternalTool → Settings → API Keys`)
+        }
+      }
+
+      return text({
+        valid:      issues.length === 0,
+        configPath,
+        serverNames,
+        issues:     issues.length ? issues : ['None — config looks correct'],
+        fixes:      fixes.length  ? fixes  : ['No fixes needed'],
+      })
     }
   )
 
@@ -1677,10 +2680,15 @@ Use this when returning to a task after a break, or when Claude needs the full p
       repoPath: z.string().optional().describe('Absolute path to the local git repo (defaults to MCP process working directory)'),
     },
     async ({ taskId, repoPath }) => {
-      const [taskRes, activityRes] = await Promise.all([
-        api.get(`/api/tasks/${taskId}`),
-        api.get(`/api/tasks/${taskId}/activity`).catch(() => null),
-      ])
+      let taskRes, activityRes
+      try {
+        [taskRes, activityRes] = await Promise.all([
+          apiWithRetry(() => api.get(`/api/tasks/${taskId}`)),
+          apiWithRetry(() => api.get(`/api/tasks/${taskId}/activity`)).catch(() => null),
+        ])
+      } catch (e) {
+        return text({ error: true, ...wrapApiError(e), message: `Could not fetch task context — ${wrapApiError(e).cause} error. Retry in a moment.` })
+      }
       if (!taskRes?.success) return errorText('Task not found')
       const task = taskRes.data.task
       const recentActivity = (activityRes?.data?.activity || []).slice(-10)
@@ -1794,8 +2802,9 @@ If you have uncommitted tracked changes, it will tell you exactly what to do bef
       fromRef:   z.string().optional().describe("Base ref to branch from (default: project's default branch)"),
       confirmed: z.boolean().optional().default(false).describe('Set true after reviewing the preview to create the branch'),
       repoPath:  z.string().optional().describe('Absolute path to the local git repo (defaults to MCP process working directory)'),
+      autoStash: z.boolean().optional().default(false).describe('Auto-stash modified files before creating the branch instead of blocking. Stash is labelled for easy recovery.'),
     },
-    async ({ taskId, projectId, fromRef, confirmed = false, repoPath }) => {
+    async ({ taskId, projectId, fromRef, confirmed = false, repoPath, autoStash = false }) => {
       if (scopedProjectId && projectId !== scopedProjectId) {
         return errorText(`Access denied: session is scoped to project ${scopedProjectId}`)
       }
@@ -1807,9 +2816,9 @@ If you have uncommitted tracked changes, it will tell you exactly what to do bef
       // ── Approval gate check ───────────────────────────────────────────────────
       // The server blocks non-admins from moving todo → in_progress without approval.
       // Detect this early and guide the developer instead of failing silently after branch creation.
-      const approvalState = task.approval?.state || 'none'
+      const hasApprovedApv2 = (task.approvals || []).some(a => a.state === 'approved')
       const PLANNING_COLS = ['backlog', 'todo']
-      const needsApproval = PLANNING_COLS.includes(task.column) && approvalState !== 'approved'
+      const needsApproval = PLANNING_COLS.includes(task.column) && !hasApprovedApv2
       if (needsApproval && !confirmed) {
         const isFix2 = /\b(fix|bug|hotfix|patch)\b/i.test(task.title + ' ' + (task.description || ''))
         const slug2 = task.title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 35)
@@ -1913,18 +2922,32 @@ If you have uncommitted tracked changes, it will tell you exactly what to do bef
         })
       }
 
-      // Step 2 — block automatically if there are tracked changes
+      // Step 2 — block or auto-stash if there are tracked changes
       if (gitState?.localState === 'modified') {
-        return text({
-          blocked: true,
-          reason: `You have ${gitState.modified.length} modified tracked file(s). Creating a branch while tracked changes are present can carry them onto the new branch.`,
-          modifiedFiles: gitState.modified,
-          fixOptions: {
-            stash:  `git stash push -m "wip: switching to ${branchName}"`,
-            commit: 'git add . && git commit -m "chore: wip"',
-          },
-          message: 'Stash or commit your changes, then call create_branch again with confirmed=true.',
-        })
+        if (autoStash) {
+          try {
+            const stashLabel = `auto-stash(${task.key?.toLowerCase()}): before create_branch ${branchName}`
+            runGit(`stash push -m "${stashLabel}"`, cwd)
+          } catch (stashErr) {
+            return text({
+              blocked: true,
+              reason: `autoStash failed: ${stashErr.message.split('\n')[0]}`,
+              message: 'Stash your changes manually and retry.',
+            })
+          }
+        } else {
+          return text({
+            blocked: true,
+            reason: `You have ${gitState.modified.length} modified tracked file(s). Creating a branch while tracked changes are present can carry them onto the new branch.`,
+            modifiedFiles: gitState.modified,
+            fixOptions: {
+              stash:     `git stash push -m "wip: switching to ${branchName}"`,
+              commit:    'git add . && git commit -m "chore: wip"',
+              autoStash: `Call create_branch again with autoStash=true — MCP will stash automatically`,
+            },
+            message: 'Stash or commit your changes, then call create_branch again with confirmed=true.',
+          })
+        }
       }
 
       // Step 3 — create branch on GitHub (or confirm it already exists), then link + move
@@ -2261,10 +3284,27 @@ Set confirmed=false first to preview the full PR content, then confirmed=true to
         return errorText(`Access denied: session is scoped to project ${scopedProjectId}`)
       }
 
-      const taskRes = await api.get(`/api/tasks/${taskId}`)
+      let taskRes
+      try { taskRes = await apiWithRetry(() => api.get(`/api/tasks/${taskId}`)) }
+      catch (e) { return text({ error: true, ...wrapApiError(e), message: `Could not fetch task — ${wrapApiError(e).cause} error. Retry raise_pr in a moment.` }) }
       if (!taskRes?.success) return errorText('Task not found')
       const task = taskRes.data.task
 
+      // ── #5 Idempotent: return existing PR instead of trying to recreate ─────
+      if (task.github?.prUrl && task.github?.prNumber) {
+        const msg = confirmed
+          ? `PR #${task.github.prNumber} already exists for ${task.key} — no duplicate created.`
+          : `PR #${task.github.prNumber} already exists for this branch. No action needed.`
+        return text({
+          prAlreadyExists: true,
+          prNumber:  task.github.prNumber,
+          prUrl:     task.github.prUrl,
+          headBranch: task.github.headBranch || headBranch,
+          message: msg,
+          nextStep: `PR is live at ${task.github.prUrl}. The GitHub webhook tracks review status automatically.`,
+        })
+      }
+
       const prTitle = `[${task.key}] ${task.title}`
       const bodyParts = [
         `## ${task.key}: ${task.title}`,
@@ -2799,6 +3839,7 @@ async function main() {
   registerProductivityTools(server)
   registerIssueTools(server)
   registerApprovalTools(server)
+  registerAIReviewTools(server)
   registerCommentTools(server)
   registerNotificationTools(server)
   registerGithubTools(server, ctx)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "internaltool-mcp",
-  "version": "1.6.19",
+  "version": "1.6.22",
   "description": "MCP server for InternalTool — connect AI assistants (Claude Code, Cursor) to your project and task management platform",
   "type": "module",
   "main": "index.js",