vibe-coding-master 0.2.4 → 0.2.6

package/README.md

@@ -16,6 +16,7 @@ Each role runs as a real Claude Code process inside an embedded terminal. The GU
 - GUI-first task workspace.
 - Collapsible sidebar with repository connection, settings, harness status, task creation, and task list.
 - Recent repository path dropdown, stored locally with the five most recent paths.
+- Connected repository status for the base repo, including branch, upstream status, commit hash, dirty state, and fast-forward-only pull.
 - Embedded Claude Code terminals powered by `node-pty` and `xterm.js`.
 - One Claude Code session per role, with role tabs in the task header.
 - Role session recovery through persisted Claude session ids and `claude --resume`.
@@ -186,7 +187,7 @@ When a task is complete, VCM provides a red `Close Task` action. Closing a task
 The left sidebar is intentionally compact and collapsible:
 
 - `Repository Path`: path input on one row; `Recent` and `Connect` on the next row.
-- `Repository`: connected path, branch, and working tree state. `Working tree: uncommitted changes` means `git status --porcelain` is not empty.
+- `Connected Repository`: connected base repo path, branch, upstream/ahead-behind status, commit hash, working tree state, and a `Pull` button.
 - `Settings`: `Theme`, `Flow pause alert`, `Try alert`, `Messages`, and `Events`.
 - `VCM Harness`: fixed-install status, bootstrap completion checks, and the bootstrap terminal when one is running.
 - `New Task`: one `task name` input.
@@ -194,6 +195,13 @@ The left sidebar is intentionally compact and collapsible:
 
 All sidebar sections are collapsed by default. When no task is selected, `Repository Path` opens by default.
 
+Opening `Connected Repository` refreshes the base repo status through the
+backend. VCM does not poll it continuously. The `Pull` button runs
+`git pull --ff-only` against the connected base repo only. It is disabled when
+the base repo has uncommitted changes, when the current branch has no upstream,
+or when the active task is an inline task using the base repo directly. It does
+not stash, merge, or mutate task worktrees.
+
 When VCM is connected to an active task, the bottom of the sidebar shows a task status dock. It stays outside the collapsible groups and shows the task title, task status, start time, total elapsed time, total flow-round count, and Claude Code active runtime. If a flow round is currently active or settling, the dock also shows that round's start time and Claude Code active runtime.
 
 ## Translation
@@ -212,7 +220,7 @@ The same file stores recent repository paths. The translation API key is stored
 
 The sidebar `Settings` section also stores the UI theme preference in this file. The default is `system`, which follows the OS/browser color-scheme preference; users can cycle between `System`, `Light`, and `Dark`.
 
-The same sidebar also has a `Flow pause alert` toggle. It is on by default and controls the local alert that fires when VCM detects that the current role flow has stopped advancing. Short flows use a weak reminder: the soft two-note chime plays 3 times, 1.4 seconds apart. Flows lasting 10 minutes or longer use a strong reminder: VCM shows an alert dialog and repeats the chime until the user confirms it. The alert sound reuses one browser audio context so repeated reminders remain reliable in stricter browsers such as Safari. Safari users may still need to manually set `Safari > Website Settings > Auto-Play > Allow All Auto-Play`; Chrome is recommended for the most reliable alert sound behavior. The `Try alert` button always triggers the strong reminder for testing.
+The same sidebar also has a `Flow pause alert` toggle. It is on by default and controls the local alert that fires when VCM detects that the current role flow has stopped advancing. Short flows use a weak reminder: the soft two-note chime plays 3 times, 1.4 seconds apart. Flows lasting 2 minutes or longer use a strong reminder: VCM shows an alert dialog and repeats the chime until the user confirms it. The alert sound reuses one browser audio context so repeated reminders remain reliable in stricter browsers such as Safari. Safari users may still need to manually set `Safari > Website Settings > Auto-Play > Allow All Auto-Play`; Chrome is recommended for the most reliable alert sound behavior. The `Try alert` button always triggers the strong reminder for testing.
 
 Translation behavior:
 
@@ -384,7 +392,7 @@ When a `Stop` hook fires, VCM marks the round as settling for 10 seconds. If ano
 
 The normal path is timer-driven: `Stop` starts a backend settle timer, and `UserPromptSubmit` cancels it. Reading the round state also checks expired deadlines as a recovery fallback after process restarts, sleep, or missed timers.
 
-When `Flow pause alert` is enabled, the frontend polls the task round state and deduplicates each paused round so the same paused state does not alert on every poll. Flow duration is measured from the first `UserPromptSubmit` to `pausedAt`, falling back to the last `Stop` when needed. If the paused flow lasted less than 10 minutes, it plays the local chime 3 times at 1.4 second intervals. If the paused flow lasted 10 minutes or longer, it shows a modal `Flow paused` alert and repeats the local chime until the user clicks `Confirm`. A pause can mean normal completion, user decision needed, dispatch failure, or another workflow interruption; the point is to get the user to look with the right amount of urgency.
+When `Flow pause alert` is enabled, the frontend polls the task round state and deduplicates each paused round so the same paused state does not alert on every poll. Flow duration is measured from the first `UserPromptSubmit` to `pausedAt`, falling back to the last `Stop` when needed. If the paused flow lasted less than 2 minutes, it plays the local chime 3 times at 1.4 second intervals. If the paused flow lasted 2 minutes or longer, it shows a modal `Flow paused` alert and repeats the local chime until the user clicks `Confirm`. A pause can mean normal completion, user decision needed, dispatch failure, or another workflow interruption; the point is to get the user to look with the right amount of urgency.
 
 ## Resume Behavior
 

package/dist/backend/adapters/claude-adapter.js

@@ -17,19 +17,26 @@ export function createClaudeAdapter(runner) {
             }
             return result.stdout.trim();
         },
-        buildRoleStartCommand(role, command = "claude", permissionMode = "default", claudeSessionId, resume = false) {
+        buildRoleStartCommand(role, command = "claude", permissionMode = "default", claudeSessionId, resume = false, model = "default") {
             const args = ["--agent", role];
             if (claudeSessionId) {
                 args.push(resume ? "--resume" : "--session-id", claudeSessionId);
             }
+            args.push("--model", model);
             if (permissionMode === "bypassPermissions") {
                 args.push("--permission-mode", "bypassPermissions");
             }
             return {
                 command,
                 args,
-                display: `${command} ${args.join(" ")}`
+                display: [command, ...args].map(formatDisplayArg).join(" ")
             };
         }
     };
 }
+function formatDisplayArg(value) {
+    if (/^[A-Za-z0-9_./:=@+-]+$/.test(value)) {
+        return value;
+    }
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}

package/dist/backend/adapters/git-adapter.js

@@ -21,6 +21,51 @@ export function createGitAdapter(runner) {
             }
             return result.stdout.trim() || "detached";
         },
+        async getHeadCommit(repoRoot) {
+            const result = await runGit(runner, repoRoot, ["rev-parse", "HEAD"]);
+            if (result.exitCode !== 0) {
+                throw new VcmError({
+                    code: "GIT_ERROR",
+                    message: "Unable to read current Git commit.",
+                    statusCode: 400,
+                    hint: result.stderr
+                });
+            }
+            return result.stdout.trim();
+        },
+        async getUpstreamBranch(repoRoot) {
+            const result = await runGit(runner, repoRoot, [
+                "rev-parse",
+                "--abbrev-ref",
+                "--symbolic-full-name",
+                "@{u}"
+            ]);
+            if (result.exitCode !== 0) {
+                return null;
+            }
+            return result.stdout.trim() || null;
+        },
+        async getAheadBehind(repoRoot, upstreamBranch) {
+            const result = await runGit(runner, repoRoot, [
+                "rev-list",
+                "--left-right",
+                "--count",
+                `HEAD...${upstreamBranch}`
+            ]);
+            if (result.exitCode !== 0) {
+                throw new VcmError({
+                    code: "GIT_ERROR",
+                    message: "Unable to read Git ahead/behind status.",
+                    statusCode: 400,
+                    hint: result.stderr
+                });
+            }
+            const [aheadValue, behindValue] = result.stdout.trim().split(/\s+/).map((value) => Number.parseInt(value, 10));
+            return {
+                ahead: Number.isFinite(aheadValue) ? aheadValue : 0,
+                behind: Number.isFinite(behindValue) ? behindValue : 0
+            };
+        },
         async isDirty(repoRoot) {
             return (await this.getStatusPorcelain(repoRoot)).trim().length > 0;
         },
@@ -110,6 +155,21 @@ export function createGitAdapter(runner) {
                     hint: result.stderr
                 });
             }
+        },
+        async pullFastForward(repoRoot) {
+            const result = await runGit(runner, repoRoot, ["pull", "--ff-only"]);
+            if (result.exitCode !== 0) {
+                throw new VcmError({
+                    code: "GIT_PULL_FAILED",
+                    message: "Unable to pull connected repository with fast-forward only.",
+                    statusCode: 409,
+                    hint: result.stderr || result.stdout
+                });
+            }
+            return {
+                stdout: result.stdout,
+                stderr: result.stderr
+            };
         }
     };
 }

package/dist/backend/api/claude-hook-routes.js

@@ -5,4 +5,11 @@ export function registerClaudeHookRoutes(app, deps) {
     app.post("/api/hooks/claude-code/stop", async (request) => {
         return deps.claudeHookService.handleStopHook(request.body);
     });
+    app.post("/api/hooks/claude-code/permission-request", async (request, reply) => {
+        const result = await deps.claudeHookService.handlePermissionRequestHook(request.body);
+        if (!result) {
+            return reply.code(204).send();
+        }
+        return result;
+    });
 }

package/dist/backend/api/project-routes.js

@@ -9,4 +9,7 @@ export function registerProjectRoutes(app, deps) {
     app.get("/api/projects/current", async () => {
         return deps.projectService.getCurrentProject();
     });
+    app.post("/api/projects/current/pull", async () => {
+        return deps.projectService.pullCurrentProject();
+    });
 }

package/dist/backend/server.js

@@ -180,7 +180,8 @@ export function createDefaultServerDeps(options = {}) {
         sessionService,
         messageService,
         roundService,
-        translationService
+        translationService,
+        appSettings
     });
     return {
         appSettings,

package/dist/backend/services/app-settings-service.js

@@ -1,6 +1,9 @@
 import path from "node:path";
 import { homedir } from "node:os";
 import { createHash } from "node:crypto";
+import { ROLE_NAMES } from "../../shared/constants.js";
+import { createDefaultLaunchTemplate } from "../../shared/types/app-settings.js";
+import { CLAUDE_MODEL_OPTIONS } from "../../shared/types/session.js";
 const MAX_RECENT_REPOSITORIES = 5;
 export function createAppSettingsService(deps) {
     const settingsPath = deps.settingsPath ?? path.join(homedir(), ".vcm", "settings.json");
@@ -184,7 +187,9 @@ function normalizePreferences(input) {
         : candidate.roundCompletionAlerts;
     return {
         themeMode: normalizeThemeMode(candidate.themeMode),
-        flowPauseAlerts: rawFlowPauseAlerts !== false
+        flowPauseAlerts: rawFlowPauseAlerts !== false,
+        permissionRequestMode: normalizePermissionRequestMode(candidate.permissionRequestMode),
+        launchTemplate: normalizeLaunchTemplate(candidate.launchTemplate)
     };
 }
 function normalizeThemeMode(input) {
@@ -193,6 +198,49 @@ function normalizeThemeMode(input) {
     }
     return "system";
 }
+function normalizePermissionRequestMode(input) {
+    if (input === "allowAll") {
+        return input;
+    }
+    return "off";
+}
+function normalizeLaunchTemplate(input) {
+    const defaults = createDefaultLaunchTemplate();
+    if (!isObject(input)) {
+        return defaults;
+    }
+    const rawRoles = isObject(input.roles) ? input.roles : {};
+    const roles = {};
+    for (const role of ROLE_NAMES) {
+        roles[role] = normalizeRoleLaunchTemplateEntry(rawRoles[role], defaults.roles[role]);
+    }
+    return {
+        version: 1,
+        roles,
+        autoOrchestration: input.autoOrchestration !== false,
+        translationEnabled: input.translationEnabled !== false
+    };
+}
+function normalizeRoleLaunchTemplateEntry(input, fallback) {
+    const candidate = isObject(input) ? input : {};
+    return {
+        permissionMode: normalizeClaudePermissionMode(candidate.permissionMode, fallback.permissionMode),
+        model: normalizeClaudeModel(candidate.model, fallback.model)
+    };
+}
+function normalizeClaudePermissionMode(input, fallback) {
+    if (input === "bypassPermissions" || input === "default") {
+        return input;
+    }
+    return fallback;
+}
+function normalizeClaudeModel(input, fallback) {
+    if (typeof input !== "string") {
+        return fallback;
+    }
+    const model = CLAUDE_MODEL_OPTIONS.find((option) => option.value === input);
+    return model?.value ?? fallback;
+}
 function normalizeTranslationConfig(input) {
     if (!input || typeof input !== "object") {
         return undefined;

package/dist/backend/services/claude-hook-service.js

@@ -86,6 +86,23 @@ export function createClaudeHookService(deps) {
             throwUnsupportedEvent(eventName);
         }
         const context = await getHookContext(input);
+        const scopedRouteDispatchInput = {
+            repoRoot: context.project.repoRoot,
+            taskRepoRoot: context.taskRepoRoot,
+            stateRepoRoot: context.taskRepoRoot,
+            stateRoot: context.config.stateRoot,
+            handoffDir: context.task.handoffDir,
+            taskSlug: input.taskSlug,
+            stoppedRole: input.role
+        };
+        const settleRouteDispatchInput = {
+            repoRoot: context.project.repoRoot,
+            taskRepoRoot: context.taskRepoRoot,
+            stateRepoRoot: context.taskRepoRoot,
+            stateRoot: context.config.stateRoot,
+            handoffDir: context.task.handoffDir,
+            taskSlug: input.taskSlug
+        };
         const session = await deps.sessionService.recordClaudeHookEvent(context.project.repoRoot, {
             taskSlug: input.taskSlug,
             role: input.role,
@@ -99,7 +116,17 @@ export function createClaudeHookService(deps) {
             stateRoot: context.config.stateRoot,
             taskSlug: input.taskSlug,
             role: input.role,
-            eventName
+            eventName,
+            settleGuard: async () => {
+                const pending = await deps.messageService.listPendingRouteFiles(settleRouteDispatchInput);
+                if (pending.length === 0) {
+                    return { action: "pause" };
+                }
+                const retried = await deps.messageService.scanAndDispatchPendingRouteFiles(settleRouteDispatchInput);
+                return retried.some((result) => result.delivered)
+                    ? { action: "continue", reason: "pending route message dispatched" }
+                    : { action: "pause" };
+            }
         });
         if (session) {
             await deps.translationService.recordConversationBoundary({
@@ -112,15 +139,7 @@ export function createClaudeHookService(deps) {
                 occurredAt: session.lastStopAt ?? session.updatedAt
             });
         }
-        const dispatched = await deps.messageService.scanAndDispatchPendingRouteFiles({
-            repoRoot: context.project.repoRoot,
-            taskRepoRoot: context.taskRepoRoot,
-            stateRepoRoot: context.taskRepoRoot,
-            stateRoot: context.config.stateRoot,
-            handoffDir: context.task.handoffDir,
-            taskSlug: input.taskSlug,
-            stoppedRole: input.role
-        });
+        const dispatched = await deps.messageService.scanAndDispatchPendingRouteFiles(scopedRouteDispatchInput);
         return {
             ok: true,
             eventName,
@@ -130,6 +149,36 @@ export function createClaudeHookService(deps) {
             dispatchedCount: dispatched.filter((result) => result.delivered).length
         };
     }
+    async function handlePermissionRequestHook(input) {
+        if (!isRoleName(input.role)) {
+            throw new VcmError({
+                code: "HOOK_ROLE_INVALID",
+                message: `Unknown hook role: ${input.role}`,
+                statusCode: 400
+            });
+        }
+        const eventName = input.event.hook_event_name;
+        if (eventName !== "PermissionRequest") {
+            throw new VcmError({
+                code: "HOOK_EVENT_UNSUPPORTED",
+                message: `Unsupported Claude Code permission hook event: ${String(eventName)}`,
+                statusCode: 400,
+                hint: "Use this endpoint for Claude Code PermissionRequest hooks only."
+            });
+        }
+        const preferences = await deps.appSettings.getPreferences();
+        if (preferences.permissionRequestMode !== "allowAll") {
+            return undefined;
+        }
+        return {
+            hookSpecificOutput: {
+                hookEventName: "PermissionRequest",
+                decision: {
+                    behavior: "allow"
+                }
+            }
+        };
+    }
     return {
         async handleHook(input) {
             const eventName = parseHookEvent(input.event.hook_event_name);
@@ -138,7 +187,8 @@ export function createClaudeHookService(deps) {
             }
             return handleStopHook(input);
         },
-        handleStopHook
+        handleStopHook,
+        handlePermissionRequestHook
     };
 }
 function parseHookEvent(value) {

package/dist/backend/services/harness-service.js

@@ -26,7 +26,8 @@ const MANAGED_BLOCK_PATTERN = /<!-- VCM:BEGIN(?:\s+version=(\d+))? -->[\s\S]*?<!
 const HASH_MANAGED_BLOCK_PATTERN = /# VCM:BEGIN(?:\s+version=(\d+))?\n[\s\S]*?# VCM:END/m;
 const CLAUDE_SETTINGS_PATH = ".claude/settings.json";
 const VCM_HOOK_COMMAND = `sh -c 'if [ -z "\${VCM_TASK_SLUG:-}" ] || [ -z "\${VCM_ROLE:-}" ] || [ -z "\${VCM_API_URL:-}" ]; then exit 0; fi; node -e '"'"'let s="";process.stdin.setEncoding("utf8");process.stdin.on("data",d=>s+=d);process.stdin.on("end",()=>{let event={};try{event=s.trim()?JSON.parse(s):{};}catch{event={raw:s};}process.stdout.write(JSON.stringify({taskSlug:process.env.VCM_TASK_SLUG,role:process.env.VCM_ROLE,event}));});'"'"' | curl -fsS --max-time 2 -X POST "\${VCM_API_URL}/api/hooks/claude-code" -H "content-type: application/json" --data-binary @- >/dev/null || true'`;
-const VCM_HOOK_EVENTS = ["UserPromptSubmit", "Stop"];
+const VCM_PERMISSION_REQUEST_HOOK_COMMAND = `sh -c 'if [ -z "\${VCM_TASK_SLUG:-}" ] || [ -z "\${VCM_ROLE:-}" ] || [ -z "\${VCM_API_URL:-}" ]; then exit 0; fi; node -e '"'"'let s="";process.stdin.setEncoding("utf8");process.stdin.on("data",d=>s+=d);process.stdin.on("end",()=>{let event={};try{event=s.trim()?JSON.parse(s):{};}catch{event={raw:s};}process.stdout.write(JSON.stringify({taskSlug:process.env.VCM_TASK_SLUG,role:process.env.VCM_ROLE,event}));});'"'"' | curl -fsS --max-time 5 -X POST "\${VCM_API_URL}/api/hooks/claude-code/permission-request" -H "content-type: application/json" --data-binary @- || true'`;
+const VCM_HOOK_EVENTS = ["UserPromptSubmit", "Stop", "PermissionRequest"];
 const HARNESS_FILES = [
     {
         kind: "root-claude",
@@ -397,7 +398,7 @@ async function analyzeClaudeSettingsFile(fs, repoRoot) {
                 path: CLAUDE_SETTINGS_PATH,
                 action,
                 reason: exists
-                    ? "Claude Code hook settings do not contain the VCM UserPromptSubmit/Stop hook bridge."
+                    ? "Claude Code hook settings do not contain the VCM hook bridge."
                     : "Claude Code hook settings are missing; VCM will create them."
             },
         nextContent: action === "ok" ? undefined : nextContent
@@ -432,7 +433,7 @@ function withVcmClaudeHooks(settings) {
             : [];
         hooks[eventName] = [
             ...existingMatchers.filter((entry) => !isVcmHookMatcher(entry)),
-            createVcmHookMatcher()
+            createVcmHookMatcher(eventName)
         ];
     }
     return {
@@ -440,12 +441,12 @@ function withVcmClaudeHooks(settings) {
         hooks
     };
 }
-function createVcmHookMatcher() {
+function createVcmHookMatcher(eventName) {
     return {
         hooks: [
             {
                 type: "command",
-                command: VCM_HOOK_COMMAND,
+                command: eventName === "PermissionRequest" ? VCM_PERMISSION_REQUEST_HOOK_COMMAND : VCM_HOOK_COMMAND,
                 timeout: 5
             }
         ]

package/dist/backend/services/project-service.js

@@ -33,38 +33,43 @@ export function createProjectService(deps) {
             await deps.fs.ensureDir(path.join(this.getProjectDataRoot(repoRoot), "tasks"));
             await deps.fs.ensureDir(path.join(repoRoot, ".claude", "worktrees"));
             await this.saveConfig(config, true);
-            const warnings = [];
-            let branch = "unknown";
-            let isDirty = false;
-            try {
-                branch = await deps.git.getCurrentBranch(repoRoot);
-            }
-            catch (caught) {
-                warnings.push(`Unable to read current Git branch. ${getErrorHint(caught)}`);
-            }
-            try {
-                isDirty = await deps.git.isDirty(repoRoot);
-            }
-            catch (caught) {
-                warnings.push(`Unable to read Git dirty status. ${getErrorHint(caught)}`);
-            }
-            if (branch === "main" || branch === "master") {
-                warnings.push(`You are on ${branch}. Consider creating a task branch before coding.`);
-            }
-            if (!(await deps.claude.isAvailable(config.claudeCommand))) {
-                warnings.push("Claude Code command is not available. You can still inspect artifacts, but sessions will not start.");
-            }
-            currentProject = {
-                repoRoot,
-                branch,
-                isDirty,
-                config,
-                warnings
-            };
+            currentProject = await readConnectedProjectSummary(repoRoot, config);
             await deps.appSettings.recordRecentRepositoryPath(repoRoot);
             return currentProject;
         },
         async getCurrentProject() {
+            if (currentProject) {
+                currentProject = await readConnectedProjectSummary(currentProject.repoRoot, currentProject.config);
+            }
+            return currentProject;
+        },
+        async pullCurrentProject() {
+            if (!currentProject) {
+                throw new VcmError({
+                    code: "NO_PROJECT",
+                    message: "No connected repository.",
+                    statusCode: 409
+                });
+            }
+            const beforePull = await readConnectedProjectSummary(currentProject.repoRoot, currentProject.config);
+            if (beforePull.isDirty) {
+                throw new VcmError({
+                    code: "BASE_REPO_DIRTY",
+                    message: "The connected repository has uncommitted changes.",
+                    statusCode: 409,
+                    hint: "Commit, stash, or discard base repository changes before pulling."
+                });
+            }
+            if (!beforePull.upstreamBranch) {
+                throw new VcmError({
+                    code: "NO_UPSTREAM",
+                    message: "The connected repository branch has no upstream.",
+                    statusCode: 409,
+                    hint: "Set an upstream branch before using Pull."
+                });
+            }
+            await deps.git.pullFastForward(currentProject.repoRoot);
+            currentProject = await readConnectedProjectSummary(currentProject.repoRoot, currentProject.config);
             return currentProject;
         },
         async getRecentRepositoryPaths() {
@@ -92,6 +97,77 @@ export function createProjectService(deps) {
             return path.dirname(deps.appSettings.getProjectConfigPath(repoRoot));
         }
     };
+    async function readConnectedProjectSummary(repoRoot, config) {
+        const warnings = [];
+        let branch = "unknown";
+        let isDirty = false;
+        let headCommit = "unknown";
+        let upstreamBranch = null;
+        let ahead = null;
+        let behind = null;
+        try {
+            branch = await deps.git.getCurrentBranch(repoRoot);
+        }
+        catch (caught) {
+            warnings.push(`Unable to read current Git branch. ${getErrorHint(caught)}`);
+        }
+        try {
+            isDirty = await deps.git.isDirty(repoRoot);
+        }
+        catch (caught) {
+            warnings.push(`Unable to read Git dirty status. ${getErrorHint(caught)}`);
+        }
+        try {
+            headCommit = await deps.git.getHeadCommit(repoRoot);
+        }
+        catch (caught) {
+            warnings.push(`Unable to read current Git commit. ${getErrorHint(caught)}`);
+        }
+        try {
+            upstreamBranch = await deps.git.getUpstreamBranch(repoRoot);
+        }
+        catch (caught) {
+            warnings.push(`Unable to read Git upstream branch. ${getErrorHint(caught)}`);
+        }
+        if (upstreamBranch) {
+            try {
+                const status = await deps.git.getAheadBehind(repoRoot, upstreamBranch);
+                ahead = status.ahead;
+                behind = status.behind;
+            }
+            catch (caught) {
+                warnings.push(`Unable to read Git ahead/behind status. ${getErrorHint(caught)}`);
+            }
+        }
+        if (!(await deps.claude.isAvailable(config.claudeCommand))) {
+            warnings.push("Claude Code command is not available. You can still inspect artifacts, but sessions will not start.");
+        }
+        const pullDisabledReason = getPullDisabledReason({ isDirty, upstreamBranch });
+        return {
+            repoRoot,
+            branch,
+            isDirty,
+            headCommit,
+            shortHeadCommit: headCommit === "unknown" ? "unknown" : headCommit.slice(0, 12),
+            upstreamBranch,
+            ahead,
+            behind,
+            canPull: !pullDisabledReason,
+            pullDisabledReason,
+            checkedAt: new Date().toISOString(),
+            config,
+            warnings
+        };
+    }
+}
+function getPullDisabledReason(input) {
+    if (input.isDirty) {
+        return "Base repository has uncommitted changes.";
+    }
+    if (!input.upstreamBranch) {
+        return "Current branch has no upstream.";
+    }
+    return undefined;
 }
 function getErrorHint(caught) {
     if (caught instanceof VcmError) {

package/dist/backend/services/round-service.js

@@ -51,7 +51,7 @@ export function createRoundService(deps) {
         await save(input, next);
         return next;
     }
-    async function settleIfStillCurrent(input, roundId, settleDeadlineAt) {
+    async function settleIfStillCurrent(input, roundId, settleDeadlineAt, settleGuard) {
         await withTaskLock(input, async () => {
             const state = await load(input);
             const current = state.currentRound;
@@ -60,7 +60,30 @@ export function createRoundService(deps) {
                 current.settleDeadlineAt !== settleDeadlineAt) {
                 return;
             }
-            await settleIfNeeded(input, state, settleDeadlineAt);
+            const timestamp = maxIsoTimestamp(now(), settleDeadlineAt);
+            if (settleGuard) {
+                const decision = await runSettleGuard(settleGuard, {
+                    ...input,
+                    role: current.activeRole,
+                    roundId,
+                    settleDeadlineAt
+                });
+                if (decision.action === "continue") {
+                    const nextRound = {
+                        ...current,
+                        settleDeadlineAt: addMilliseconds(timestamp, settleMs)
+                    };
+                    const next = {
+                        ...state,
+                        currentRound: nextRound,
+                        updatedAt: timestamp
+                    };
+                    await save(input, next);
+                    scheduleSettleTimer(input, nextRound, timestamp, settleGuard);
+                    return;
+                }
+            }
+            await settleIfNeeded(input, state, timestamp);
         });
     }
     function clearSettleTimer(input) {
@@ -81,7 +104,7 @@ export function createRoundService(deps) {
             settleTimers.delete(key);
         }
     }
-    function scheduleSettleTimer(input, round, timestamp) {
+    function scheduleSettleTimer(input, round, timestamp, settleGuard) {
         if (round.status !== "settling" || !round.settleDeadlineAt) {
             clearSettleTimer(input);
             return;
@@ -90,7 +113,7 @@ export function createRoundService(deps) {
         const delayMs = Math.max(0, new Date(round.settleDeadlineAt).getTime() - new Date(timestamp).getTime());
         const timer = setTimer(() => {
             settleTimers.delete(getRoundStatePath(input));
-            void settleIfStillCurrent(input, round.id, round.settleDeadlineAt ?? "").catch(() => undefined);
+            void settleIfStillCurrent(input, round.id, round.settleDeadlineAt ?? "", settleGuard).catch(() => undefined);
         }, delayMs);
         settleTimers.set(getRoundStatePath(input), timer);
     }
@@ -112,8 +135,7 @@ export function createRoundService(deps) {
         async getTaskRoundState(input) {
             return withTaskLock(input, async () => {
                 const timestamp = now();
-                const state = await settleIfNeeded(input, await load(input), timestamp);
-                return toTaskRoundState(state, timestamp);
+                return toTaskRoundState(await load(input), timestamp);
             });
         },
         async recordClaudeHookEvent(input) {
@@ -136,7 +158,7 @@ export function createRoundService(deps) {
                     clearSettleTimer(input);
                 }
                 else if (next.currentRound) {
-                    scheduleSettleTimer(input, next.currentRound, timestamp);
+                    scheduleSettleTimer(input, next.currentRound, timestamp, input.settleGuard);
                 }
                 return toTaskRoundState(next, timestamp);
             });
@@ -314,6 +336,17 @@ function appendUniqueRole(roles, role) {
 function addMilliseconds(value, milliseconds) {
     return new Date(new Date(value).getTime() + milliseconds).toISOString();
 }
+function maxIsoTimestamp(left, right) {
+    return Date.parse(left) >= Date.parse(right) ? left : right;
+}
+async function runSettleGuard(settleGuard, input) {
+    try {
+        return await settleGuard(input);
+    }
+    catch {
+        return { action: "pause" };
+    }
+}
 function getDurationMs(start, end) {
     const startMs = Date.parse(start);
     const endMs = Date.parse(end);