@loicngr/kobo 1.11.45 → 2.1.0

package/dist/server/routes/health.js

@@ -5,6 +5,7 @@ import { Hono } from 'hono';
 import { getDb } from '../db/index.js';
 import { SCHEMA_VERSION } from '../db/migrations.js';
 import { resolveCodexBinary } from '../services/agent/engines/codex/spawn.js';
+import { hasIntegrationMcpConfig } from '../services/agent/integration-mcp.js';
 import { getGlobalSettings, getProjectSettings, SETTINGS_SCHEMA_VERSION } from '../services/settings-service.js';
 import { readRecentLogs } from '../utils/logger.js';
 import { getDbPath, getKoboHome, getPackageVersion } from '../utils/paths.js';
@@ -12,6 +13,14 @@ import { slugifyProjectName } from '../utils/project-slug.js';
 import { resolveWorkspaceWorktreePath } from '../utils/worktree-paths.js';
 const app = new Hono();
 const execFileAsync = promisify(execFileCb);
+function integrationConfigured(integration, key) {
+    try {
+        return hasIntegrationMcpConfig(integration, key);
+    }
+    catch {
+        return false;
+    }
+}
 async function checkCli(binary) {
     try {
         const { stdout } = await execFileAsync(binary, ['--version'], { encoding: 'utf-8', timeout: 2_000 });
@@ -182,8 +191,14 @@ app.get('/report', async (c) => {
         },
         agentSessions: { orphaned },
         integrations: {
-            notion: { configured: Boolean(healthGlobalSettings.notionMcpKey), enabled: healthGlobalSettings.notionEnabled },
-            sentry: { configured: Boolean(healthGlobalSettings.sentryMcpKey), enabled: healthGlobalSettings.sentryEnabled },
+            notion: {
+                configured: integrationConfigured('notion', healthGlobalSettings.notionMcpKey),
+                enabled: healthGlobalSettings.notionEnabled,
+            },
+            sentry: {
+                configured: integrationConfigured('sentry', healthGlobalSettings.sentryMcpKey),
+                enabled: healthGlobalSettings.sentryEnabled,
+            },
             editor: { configured: Boolean(healthGlobalSettings.editorCommand) },
         },
         active: {

package/dist/server/routes/integrations.js

@@ -0,0 +1,29 @@
+import { Hono } from 'hono';
+import { bodyLimit } from 'hono/body-limit';
+import { getIntegrationStatus, saveIntegrationConfig, } from '../services/integration-config-service.js';
+const app = new Hono();
+app.use('*', bodyLimit({ maxSize: 64 * 1024 }));
+app.use('/:integration', async (c, next) => {
+    if (!['notion', 'sentry'].includes(c.req.param('integration') ?? ''))
+        return c.json({ error: 'Unknown integration' }, 404);
+    await next();
+});
+app.get('/:integration', (c) => {
+    try {
+        return c.json(getIntegrationStatus(c.req.param('integration')));
+    }
+    catch {
+        return c.json({ error: 'Integration configuration is unavailable' }, 503);
+    }
+});
+app.put('/:integration', async (c) => {
+    try {
+        const value = await c.req.json();
+        saveIntegrationConfig(c.req.param('integration'), value);
+        return c.json(getIntegrationStatus(c.req.param('integration')));
+    }
+    catch {
+        return c.json({ error: 'Cannot save integration configuration; check the connection fields and local storage' }, 400);
+    }
+});
+export default app;

package/dist/server/routes/settings.js

@@ -1,5 +1,6 @@
 import { Hono } from 'hono';
 import { isValidSkillSuite } from '../../shared/skill-suite-prompts.js';
+import { isWorkflowPolicy } from '../../shared/workflow-policy.js';
 import { getDb } from '../db/index.js';
 import { getBackendPort } from '../services/agent/orchestrator.js';
 import { DEFAULT_NOTION_INITIAL_PROMPT, DEFAULT_SENTRY_INITIAL_PROMPT, } from '../services/initial-prompt-template-service.js';
@@ -163,6 +164,8 @@ app.put('/global', async (c) => {
         // must answer 400 rather than do that.
         if (!body)
             return c.json({ error: 'Invalid JSON body' }, 400);
+        if (body.workflowPolicy !== undefined && !isWorkflowPolicy(body.workflowPolicy))
+            return c.json({ error: 'Invalid workflowPolicy' }, 400);
         const updated = settingsService.updateGlobalSettings(body);
         // The client assigns this response straight into its store, so echoing the
         // real credentials back would undo the masking on GET the first time
@@ -211,6 +214,8 @@ app.put('/projects/:encodedPath', async (c) => {
         // `{}` CREATES a project entry with defaults; a malformed body must not.
         if (!body)
             return c.json({ error: 'Invalid JSON body' }, 400);
+        if (body.workflowPolicy !== undefined && !isWorkflowPolicy(body.workflowPolicy))
+            return c.json({ error: 'Invalid workflowPolicy' }, 400);
         const project = settingsService.upsertProject(projectPath, body);
         return c.json(project);
     }

package/dist/server/routes/sounds.js

@@ -0,0 +1,60 @@
+import fs from 'node:fs';
+import { Hono } from 'hono';
+import { bodyLimit } from 'hono/body-limit';
+import { MAX_CUSTOM_SOUND_BYTES } from '../../shared/notification-assets.js';
+import { CustomSoundError, deleteCustomSound, listCustomSounds, readCustomSound, saveCustomSound, } from '../services/custom-sound-service.js';
+/** Multipart framing and the field name add a small, bounded overhead. */
+const MAX_REQUEST_BYTES = MAX_CUSTOM_SOUND_BYTES + 64 * 1024;
+const app = new Hono();
+// `listCustomSounds` degrades a damaged manifest to an empty list; it never throws.
+app.get('/', (c) => c.json({ sounds: listCustomSounds() }));
+app.post('/', bodyLimit({ maxSize: MAX_REQUEST_BYTES }), async (c) => {
+    let form;
+    try {
+        form = await c.req.raw.formData();
+    }
+    catch {
+        return c.json({ error: 'Invalid multipart body' }, 400);
+    }
+    const files = form.getAll('sound');
+    if (files.length !== 1 || !(files[0] instanceof File))
+        return c.json({ error: 'Expected one sound file' }, 400);
+    try {
+        return c.json(await saveCustomSound(files[0]), 201);
+    }
+    catch (error) {
+        // Only the stable code crosses the boundary: a filesystem error may carry
+        // the layout of the user's home directory.
+        if (error instanceof CustomSoundError)
+            return c.json({ error: 'Invalid sound file', code: error.code }, 400);
+        return c.json({ error: 'Cannot store the sound file' }, 500);
+    }
+});
+app.delete('/:id', (c) => {
+    try {
+        return deleteCustomSound(c.req.param('id')) ? c.body(null, 204) : c.json({ error: 'Sound not found' }, 404);
+    }
+    catch {
+        return c.json({ error: 'Cannot remove the sound file' }, 500);
+    }
+});
+// An unknown or deleted sound answers 404; the client then falls back to a bundled tone.
+app.get('/:id/file', async (c) => {
+    const sound = readCustomSound(c.req.param('id'));
+    if (!sound)
+        return c.json({ error: 'Sound not found' }, 404);
+    let content;
+    try {
+        content = await fs.promises.readFile(sound.filePath);
+    }
+    catch {
+        // The file vanished between the manifest lookup and the read.
+        return c.json({ error: 'Sound not found' }, 404);
+    }
+    c.header('Content-Type', sound.contentType);
+    // Content-addressed by a generated id: the bytes behind an id never change.
+    c.header('Cache-Control', 'private, max-age=3600, immutable');
+    c.header('X-Content-Type-Options', 'nosniff');
+    return c.body(new Uint8Array(content));
+});
+export default app;

package/dist/server/routes/workspaces.js

@@ -1,11 +1,12 @@
 import { execFile as execFileCb, execFileSync, spawn } from 'node:child_process';
 import { promisify } from 'node:util';
 import { nanoid } from 'nanoid';
+import { isWorkflowPolicy, resolveWorkflowPolicy, WORKFLOW_ACTIONS, } from '../../shared/workflow-policy.js';
 import { getSearchIndexStatus, searchEvents } from '../services/search-service.js';
 import { createSessionHandoff, decideSessionHandoff, getCurrentSessionHandoff, SessionHandoffError, submitSessionHandoff, waitForSessionHandoff, } from '../services/session-handoff-service.js';
 import { AgentStopError, assertAgentStopped } from '../utils/agent-stop-result.js';
 import { withGitRepoLock } from '../utils/git-repo-lock.js';
-import { workspaceLifecycleReason } from '../utils/workspace-lifecycle-guard.js';
+import { isWorkspaceLifecycleBusy, workspaceLifecycleReason } from '../utils/workspace-lifecycle-guard.js';
 import autoLoopMessagesRoutes from './auto-loop-messages.js';
 const execFileAsync = promisify(execFileCb);
 import fs from 'node:fs';
@@ -62,6 +63,15 @@ import { WorkspaceLifecycleBusyError, withWorkspaceLifecycleGuard } from '../uti
 import { resolveExtractedName } from '../utils/workspace-name.js';
 import { resolveSiblingWorkspaceWorktreePath } from '../utils/worktree-paths.js';
 /** Lifecycle conflicts can be retried once the current owner has stopped. */
+/** Symlink-resolved path, or the lexically resolved one when it does not exist. */
+function realPathOrResolved(p) {
+    try {
+        return fs.realpathSync(p);
+    }
+    catch {
+        return path.resolve(p);
+    }
+}
 function workspaceErrorStatus(err) {
     return err instanceof AgentStopError || err instanceof WorkspaceLifecycleBusyError ? 409 : 500;
 }
@@ -452,6 +462,8 @@ app.post('/', migrationGuard, creationBodyLimit, async (c) => {
     let setupScriptConfigured = false;
     try {
         const { body, attachments } = await readWorkspaceCreationRequest(c.req.raw);
+        if (body.workflowPolicy !== undefined && !isWorkflowPolicy(body.workflowPolicy))
+            return c.json({ error: 'Invalid workflowPolicy' }, 400);
         // workingBranch is derived from git when worktreePath is provided, so
         // it's not required in that flow. The other 3 fields stay mandatory.
         if (!body.name || !body.projectPath || !body.sourceBranch) {
@@ -552,11 +564,10 @@ app.post('/', migrationGuard, creationBodyLimit, async (c) => {
                 return c.json({ error: failure, step: 'inspect-worktree' }, 422);
             }
             try {
-                const commonDir = execFileSync('git', ['-C', body.worktreePath, 'rev-parse', '--git-common-dir'], {
-                    encoding: 'utf-8',
-                }).trim();
-                const expectedCommonDir = path.join(body.projectPath, '.git');
-                if (path.resolve(commonDir) !== path.resolve(expectedCommonDir)) {
+                const commonDir = execFileSync('git', ['-C', body.worktreePath, 'rev-parse', '--path-format=absolute', '--git-common-dir'], { encoding: 'utf-8' }).trim();
+                // Git reports the common dir symlink-resolved while the project path may be
+                // reached through a link (macOS temp dirs: /var -> /private/var).
+                if (realPathOrResolved(commonDir) !== realPathOrResolved(path.join(body.projectPath, '.git'))) {
                     const failure = `Worktree '${body.worktreePath}' belongs to a different repository`;
                     emitCreateFailed(creationId, 'inspect-worktree', failure);
                     return c.json({ error: failure, step: 'inspect-worktree' }, 422);
@@ -794,6 +805,7 @@ app.post('/', migrationGuard, creationBodyLimit, async (c) => {
                 model: body.model,
                 brainstormModel: body.brainstormModel,
                 reasoningEffort: body.reasoningEffort,
+                workflowPolicy: resolveWorkflowPolicy(globalSettings.workflowPolicy, projectSettings?.workflowPolicy, body.workflowPolicy),
                 agentPermissionMode: resolveCreateAgentPermissionMode(body.agentPermissionMode, body.projectPath, globalSettings, body.engine ?? 'claude-code'),
                 engine: body.engine,
                 // Set by the engine-comparison flow, which posts here once per engine
@@ -1109,9 +1121,9 @@ app.post('/', migrationGuard, creationBodyLimit, async (c) => {
                     `## Additional Context\n${extra}\n\n` +
                     `## MCP Tools for deeper analysis\n` +
                     `If you need more context, the following Sentry MCP tools are available:\n` +
-                    `- \`mcp__sentry__get_sentry_resource(url, resourceType)\` — fetch the issue, breadcrumbs, replay, or trace\n` +
-                    `- \`mcp__sentry__search_issue_events(organizationSlug, issueId='${sentryContent.issueId}')\` — recent events for this issue\n` +
-                    `- \`mcp__sentry__get_issue_tag_values(organizationSlug, issueId='${sentryContent.issueId}', key)\` — filter by tag (environment, user, browser, …)\n`;
+                    `- \`get_sentry_resource(url, resourceType) [use the Kōbō-managed Sentry namespace supplied for this session]\` — fetch the issue, breadcrumbs, replay, or trace\n` +
+                    `- \`search_issue_events(organizationSlug, issueId='${sentryContent.issueId}')\` — recent events for this issue\n` +
+                    `- \`get_issue_tag_values(organizationSlug, issueId='${sentryContent.issueId}', key)\` — filter by tag (environment, user, browser, …)\n`;
                 fs.writeFileSync(sentryFilePath, md, 'utf-8');
                 workspaceService.createTask(workspace.id, {
                     title: `Fix: ${sentryContent.title || sentryContent.issueId || `Sentry #${sentryContent.issueNumericId}`}`,
@@ -1232,9 +1244,9 @@ app.post('/', migrationGuard, creationBodyLimit, async (c) => {
                         `5. Confirm the test passes, run related tests\n` +
                         `6. Commit referencing the Sentry Short-ID (e.g. "fix(scope): description (${sentryContent.issueId})") — Sentry auto-closes the issue when the commit is merged\n` +
                         `\nIf you need more context, Sentry MCP tools are available:\n` +
-                        `- mcp__sentry__get_sentry_resource(url, resourceType) — fetch the issue, breadcrumbs, replay or trace\n` +
-                        `- mcp__sentry__search_issue_events(organizationSlug, issueId='${sentryContent.issueId}') — recent events\n` +
-                        `- mcp__sentry__get_issue_tag_values(organizationSlug, issueId='${sentryContent.issueId}', key) — filter by tag\n`;
+                        `- get_sentry_resource(url, resourceType) [use the Kōbō-managed Sentry namespace supplied for this session] — fetch the issue, breadcrumbs, replay or trace\n` +
+                        `- search_issue_events(organizationSlug, issueId='${sentryContent.issueId}') — recent events\n` +
+                        `- get_issue_tag_values(organizationSlug, issueId='${sentryContent.issueId}', key) — filter by tag\n`;
                 if (sentryTpl.trim().length > 0) {
                     const renderedSentry = renderSentryInitialPrompt(sentryTpl, {
                         issueId: sentryContent.issueId,
@@ -1680,6 +1692,13 @@ app.get('/auto-loop-states', (c) => {
 });
 app.route('/', autoLoopMessagesRoutes);
 // GET /api/workspaces/:id/auto-loop — current auto-loop status for one workspace.
+// Admission inspection never changes deadlines, pending schedules or lifecycle state.
+app.get('/:id/automatic-admission', (c) => {
+    const id = c.req.param('id');
+    if (!workspaceService.getWorkspace(id))
+        return c.json({ error: 'Workspace not found' }, 404);
+    return c.json(autoLoopService.getAutomaticAdmissionStatus(id));
+});
 app.get('/:id/auto-loop', (c) => {
     try {
         const id = c.req.param('id');
@@ -2708,6 +2727,20 @@ app.patch('/:id', migrationGuard, async (c) => {
         if ('agent_description' in body) {
             return c.json({ error: 'agent_description must be set via the agent MCP tool, not via the API' }, 400);
         }
+        if (body.workflowPolicy !== undefined && !isWorkflowPolicy(body.workflowPolicy))
+            return c.json({ error: 'Invalid workflowPolicy' }, 400);
+        if (body.workflowPolicy !== undefined) {
+            const policy = resolveWorkflowPolicy(workspace.workflowPolicy, body.workflowPolicy);
+            const changed = WORKFLOW_ACTIONS.some((action) => policy[action] !== workspace.workflowPolicy[action]);
+            // A live engine already received its policy. Persisting a different one cannot
+            // revoke that prompt; wait for confirmed closure before accepting the change.
+            if (changed && (agentManager.hasController(id) || isWorkspaceLifecycleBusy(id))) {
+                return c.json({
+                    error: 'Stop the agent and wait for workspace operations to finish before changing workflow preferences.',
+                    code: 'workspace-busy',
+                }, 409);
+            }
+        }
         if (body.model !== undefined && (typeof body.model !== 'string' || !body.model.trim())) {
             return c.json({ error: 'model must be a non-empty string' }, 400);
         }
@@ -2749,6 +2782,7 @@ app.patch('/:id', migrationGuard, async (c) => {
             }
         }
         if (body.status === undefined &&
+            body.workflowPolicy === undefined &&
             body.model === undefined &&
             body.reasoningEffort === undefined &&
             body.agentPermissionMode === undefined &&

package/dist/server/services/agent/engines/codex/options-builder.js

@@ -54,6 +54,7 @@ export function buildCodexOptions(input) {
         const mcpServersConfig = {};
         for (const srv of input.mcpServers) {
             mcpServersConfig[srv.name] = {
+                enabled: true,
                 command: srv.command,
                 args: srv.args,
                 env: srv.env,

package/dist/server/services/agent/engines/codex/spawn.js

@@ -1,5 +1,6 @@
 import { spawn as nodeSpawn } from 'node:child_process';
 import { createRequire } from 'node:module';
+import path from 'node:path';
 const requireFn = createRequire(import.meta.url);
 export function resolveCodexBinary() {
     try {
@@ -7,8 +8,7 @@ export function resolveCodexBinary() {
         const pkg = requireFn(pkgPath);
         const binRel = typeof pkg.bin === 'string' ? pkg.bin : pkg.bin?.codex;
         if (binRel) {
-            const url = new URL(binRel, `file://${pkgPath}`);
-            return url.pathname;
+            return path.resolve(path.dirname(pkgPath), binRel);
         }
     }
     catch {

package/dist/server/services/agent/integration-mcp.js

@@ -0,0 +1,49 @@
+import { nanoid } from 'nanoid';
+import { readClaudeMcpEntry } from '../../utils/mcp-client.js';
+import { getIntegrationConfig } from '../integration-config-service.js';
+import { buildNotionMcpConfig } from '../notion-service.js';
+import { readSentryMcpConfig } from '../sentry-service.js';
+/** Availability only: no provider process or credential-bearing response. */
+export function hasIntegrationMcpConfig(integration, selectedKey) {
+    if (getIntegrationConfig(integration))
+        return true;
+    if (integration === 'notion' &&
+        (process.env.NOTION_API_TOKEN || process.env.NOTION_TOKEN || process.env.OPENAPI_MCP_HEADERS))
+        return true;
+    const key = selectedKey?.trim();
+    return Boolean(readClaudeMcpEntry((name) => key ? name === key : integration === 'notion' ? name === 'notion' : /sentry/i.test(name)));
+}
+/** Resolve at every launch/resume; never write credentials into a project file. */
+export function buildIntegrationMcpServers(settings, onUnavailable) {
+    const servers = [];
+    // Fresh names avoid Codex recursively merging stale native config fields.
+    const launch = nanoid(12);
+    for (const integration of ['notion', 'sentry']) {
+        if (!settings[`${integration}Enabled`])
+            continue;
+        try {
+            const key = settings[`${integration}McpKey`];
+            if (!hasIntegrationMcpConfig(integration, key))
+                continue;
+            const config = integration === 'notion' ? buildNotionMcpConfig(key, false) : readSentryMcpConfig(key, false);
+            servers.push({ name: `kobo-${integration}-${launch}`, ...config });
+        }
+        catch {
+            // Optional connections cannot block ordinary missions. Never expose raw
+            // config/parse errors, which may contain credential material.
+            onUnavailable?.(integration);
+        }
+    }
+    return servers;
+}
+export function integrationMcpPrompt(servers, unavailable = []) {
+    if (!servers.length && !unavailable.length)
+        return '';
+    return [
+        '[Kōbō managed integrations]',
+        ...unavailable.map((name) => `${name}: Kōbō could not load this connection. Ask the user to check Settings if needed; do not silently substitute personal credentials.`),
+        'For these integrations, use the MCP servers listed below, configured in Kōbō Settings. Prefer them over personal/native servers and namespaces from earlier turns. Discover their available tools; do not assume all servers implement the same tools. If unavailable, report the connection problem instead of silently switching credentials.',
+        ...servers.map((server) => `${server.name.startsWith('kobo-notion-') ? 'Notion' : 'Sentry'}: ${server.name}`),
+        'These connections do not grant permission to modify remote data. Follow the user request and engine permissions.',
+    ].join('\n');
+}

package/dist/server/services/agent/orchestrator.js

@@ -1,5 +1,6 @@
 import { readFileSync, writeFileSync } from 'node:fs';
 import { nanoid } from 'nanoid';
+import { renderWorkflowPolicy } from '../../../shared/workflow-policy.js';
 import { getDb } from '../../db/index.js';
 import { assertAgentStopped } from '../../utils/agent-stop-result.js';
 import { ensureKoboHome, getCompiledMcpServerPath, getDbPath, getKoboHome, getMcpServerSourcePath, getSettingsPath, getSkillsPath, } from '../../utils/paths.js';
@@ -23,6 +24,7 @@ import { getWorkspace as getWs, markWorkspaceUnread, updateWorkspaceStatus, } fr
 import { resolveEngine } from './engines/registry.js';
 import { AGENT_NO_LONGER_RUNNING_TEXT, } from './engines/types.js';
 import { routeEvent } from './event-router.js';
+import { buildIntegrationMcpServers, integrationMcpPrompt } from './integration-mcp.js';
 import { SessionController } from './session-controller.js';
 export class InterruptAgentError extends Error {
     code;
@@ -1371,10 +1373,12 @@ export function startAgent(workspaceId, workingDir, prompt, model, resume = fals
     activateSession(workspaceId, agentSessionId);
     captureTaskProgressBaseline(workspaceId, agentSessionId);
     const settings = ws ? readEffectiveSettingsSafe(ws.projectPath) : readEffectiveSettingsSafe(workingDir);
+    const unavailableIntegrations = [];
+    const integrationServers = buildIntegrationMcpServers(getGlobalSettings(), (name) => unavailableIntegrations.push(name));
     const options = {
         workspaceId,
         workingDir,
-        prompt: buildAgentPrompt(prompt, ws?.projectPath),
+        prompt: buildAgentPrompt(`${ws ? renderWorkflowPolicy(ws.workflowPolicy) : ''}\n${integrationMcpPrompt(integrationServers, unavailableIntegrations)}\n${prompt}`, ws?.projectPath),
         model,
         effort: reasoningEffort,
         // Cascade: explicit caller override → workspace setting → 'bypass'.
@@ -1390,7 +1394,7 @@ export function startAgent(workspaceId, workingDir, prompt, model, resume = fals
             }
         })(),
         settings,
-        mcpServers: buildMcpServers(workspaceId, launch?.mcpEnv),
+        mcpServers: [...buildMcpServers(workspaceId, launch?.mcpEnv), ...integrationServers],
         env: ws ? buildAgentEnv(ws.projectPath) : undefined,
     };
     beforeDispatch?.();

package/dist/server/services/auto-loop-service.js

@@ -83,22 +83,41 @@ export function block(workspaceId, reason) {
     quotaBackoffService.cancel(workspaceId, 'completed');
     setRuntime(workspaceId, { state: 'blocked', reason });
 }
-/** Shared admission gate for all unattended starts. */
-export function canStartAutomatically(workspaceId) {
+/** Read-only explanation of the shared admission gate; does not consume or reschedule work. */
+export function getAutomaticAdmissionStatus(workspaceId) {
     const row = getRow(workspaceId);
-    return (!!row &&
-        !row.archived_at &&
-        !row.worktree_purged_at &&
-        !orchestrator.isShuttingDown() &&
-        !isWorkspaceLifecycleBusy(workspaceId) &&
-        !orchestrator.hasController(workspaceId) &&
-        !['awaiting-user', 'compacting'].includes(row.status) &&
-        // A manual workspace keeps its quota status after expiry. Its explicit
-        // wakeup/cron may resume then; an enabled loop still belongs to quota recovery.
-        !(row.status === 'quota' && row.auto_loop === 1) &&
-        !quotaBackoffService.getPending(workspaceId) &&
-        getRuntime(workspaceId).state !== 'blocked' &&
-        hasFreeAgentSlot());
+    const running = orchestrator.runningAgentCount();
+    const configuredLimit = settingsService.getGlobalSettings().maxConcurrentAgents;
+    const limit = typeof configuredLimit === 'number' && configuredLimit > 0 ? configuredLimit : 0;
+    let reason = null;
+    if (!row)
+        reason = 'not-found';
+    else if (row.archived_at)
+        reason = 'archived';
+    else if (row.worktree_purged_at)
+        reason = 'purged';
+    else if (orchestrator.isShuttingDown())
+        reason = 'shutdown';
+    else if (isWorkspaceLifecycleBusy(workspaceId))
+        reason = 'lifecycle';
+    else if (orchestrator.hasController(workspaceId))
+        reason = 'active-session';
+    else if (row.status === 'awaiting-user')
+        reason = 'awaiting-user';
+    else if (row.status === 'compacting')
+        reason = 'compacting';
+    // Manual schedules can resume an expired quota; active loops remain owned by quota recovery.
+    else if ((row.status === 'quota' && row.auto_loop === 1) || quotaBackoffService.getPending(workspaceId))
+        reason = 'quota';
+    else if (getRuntime(workspaceId).state === 'blocked')
+        reason = 'blocked';
+    else if (limit > 0 && running >= limit)
+        reason = 'capacity';
+    return { allowed: reason === null, reason, running, limit };
+}
+/** Shared admission gate for all unattended starts. Manual launches remain exempt. */
+export function canStartAutomatically(workspaceId) {
+    return getAutomaticAdmissionStatus(workspaceId).allowed;
 }
 /**
  * Enable auto-loop for the workspace. Spawns immediately if idle + pending
@@ -375,9 +394,9 @@ function ensureFinalVerification(workspaceId) {
  * `orchestrator.startAgent` throws during engine.start — caught below.
  */
 /**
- * Whether another unattended session may start right now. `0` — the default —
- * means no limit. Only the auto-loop consults this: a session the user starts
- * by hand always goes through.
+ * Whether another unattended session may start right now. Fresh installs use
+ * a limit of 2; an explicit 0 means unlimited. Auto-loop, cron and wakeup
+ * launches share admission, while manual launches remain exempt.
  */
 function hasFreeAgentSlot() {
     const limit = settingsService.getGlobalSettings().maxConcurrentAgents;
@@ -501,13 +520,14 @@ ${prompt}`;
         : undefined;
     const worktreePath = row.worktree_path ??
         resolveWorkspaceWorktreePath(row.project_path, row.working_branch, globalSettings.worktreesPath, projectSlug);
-    // Plan mode would deadlock the loop (blocks MCP + edits) — promote to bypass.
-    // Other modes (bypass/strict/interactive) are honored.
-    const stored = (row.agent_permission_mode ?? 'bypass');
-    const agentPermissionMode = stored === 'plan' ? 'bypass' : stored;
-    if (stored === 'plan') {
-        console.warn(`[auto-loop-service] Promoting plan → bypass for workspace ${workspaceId} — auto-loop cannot run in plan mode`);
-        emitEphemeral(workspaceId, 'autoloop:permission-overridden', { from: 'plan', to: 'bypass' });
+    const storedMode = row.agent_permission_mode;
+    const agentPermissionMode = storedMode === 'bypass' || storedMode === 'strict' || storedMode === 'interactive' ? storedMode : 'plan';
+    if (!grooming && agentPermissionMode === 'plan') {
+        const message = 'Execution requires an explicit permission choice. Change this workspace from Plan to an execution mode (strict, interactive where supported, or bypass), then resume auto-loop. Permissions were not changed.';
+        block(workspaceId, message);
+        if (opts.throwOnStartAgentError)
+            throw new Error(message);
+        return;
     }
     // Pre-check: if the worktree directory is gone (user `rm -rf`-ed it),
     // fail loudly rather than letting startAgent throw a deep engine error.

package/dist/server/services/environment-check-service.js

@@ -0,0 +1,125 @@
+import { execFile } from 'node:child_process';
+import { constants } from 'node:fs';
+import { access, stat } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { getKoboHome } from '../utils/paths.js';
+import { resolveWorktreesRoot } from '../utils/worktree-paths.js';
+import { detectPlatform, resolveClaudeBinaryPath } from './agent/engines/claude-code/resolve-binary.js';
+import { resolveCodexBinary } from './agent/engines/codex/spawn.js';
+import { getGlobalSettings } from './settings-service.js';
+const runFile = promisify(execFile);
+const require = createRequire(import.meta.url);
+/** Probe the nearest existing parent without creating directories or test files. */
+async function writableDirectory(directory, allowMissing = false) {
+    let current = path.resolve(directory);
+    for (;;) {
+        try {
+            const info = await stat(current);
+            if (!info.isDirectory())
+                return false;
+            await access(current, constants.W_OK | constants.X_OK);
+            return true;
+        }
+        catch (error) {
+            if (!allowMissing || error.code !== 'ENOENT')
+                return false;
+            const parent = path.dirname(current);
+            if (parent === current)
+                return false;
+            current = parent;
+        }
+    }
+}
+function liveProbe() {
+    return {
+        platform: process.platform,
+        nodeVersion: process.versions.node,
+        dataDirectory: getKoboHome(),
+        run: async (command, args) => {
+            const { stdout } = await runFile(command, args, {
+                timeout: 3_000,
+                killSignal: 'SIGKILL',
+                maxBuffer: 16_384,
+                encoding: 'utf8',
+                env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+            });
+            return stdout.trim();
+        },
+        writableDirectory,
+        claudeBinary: () => {
+            const binary = resolveClaudeBinaryPath();
+            if (binary)
+                return binary;
+            const platform = detectPlatform();
+            try {
+                if (platform.platform === 'darwin')
+                    return require.resolve(`@anthropic-ai/claude-agent-sdk-darwin-${platform.arch}/claude`);
+                if (platform.platform === 'linux' && !platform.isGlibc)
+                    return require.resolve(`@anthropic-ai/claude-agent-sdk-linux-${platform.arch}-musl/claude`);
+            }
+            catch {
+                /* The SDK may support another layout: do not claim it is executable. */
+            }
+            return undefined;
+        },
+        worktreesDirectory: (project) => resolveWorktreesRoot(project, getGlobalSettings().worktreesPath),
+        codexBinary: resolveCodexBinary,
+    };
+}
+/** No credential files, provider calls, generated prompts, or raw process errors in this report. */
+export async function checkEnvironment(request, probe = liveProbe()) {
+    const [major, minor] = probe.nodeVersion.split('.').map(Number);
+    const checks = [
+        { code: 'node', status: major > 24 || (major === 24 && minor >= 15) ? 'ok' : 'error' },
+        { code: 'platform', status: ['linux', 'darwin'].includes(probe.platform) ? 'ok' : 'error' },
+    ];
+    const commandAvailable = async (command, args) => {
+        try {
+            await probe.run(command, args);
+            return 'ok';
+        }
+        catch (error) {
+            return error.code === 'ENOENT' ? 'missing' : 'error';
+        }
+    };
+    const binary = request.engine === 'codex' ? probe.codexBinary() : probe.claudeBinary();
+    const [git, shell, storage, runtime] = await Promise.all([
+        commandAvailable('git', ['--version']),
+        commandAvailable('bash', ['--version']),
+        probe.writableDirectory(probe.dataDirectory, true),
+        binary ? commandAvailable(binary, ['--version']) : Promise.resolve('unknown'),
+    ]);
+    checks.push({ code: 'git', status: git }, { code: 'shell', status: shell }, { code: 'storage', status: storage ? 'ok' : 'error' }, { code: 'runtime', status: runtime }, { code: 'authentication', status: 'unknown' }, { code: 'model', status: 'unknown' });
+    if (request.projectPath) {
+        const args = ['-C', path.resolve(request.projectPath)];
+        let repository = false;
+        try {
+            repository = (await probe.run('git', [...args, 'rev-parse', '--is-inside-work-tree'])) === 'true';
+        }
+        catch {
+            // No stderr is returned: it may contain a private path or remote URL.
+        }
+        const [commit, writable, worktrees] = await Promise.all([
+            repository ? commandAvailable('git', [...args, 'rev-parse', '--verify', 'HEAD']) : false,
+            probe.writableDirectory(request.projectPath),
+            probe.writableDirectory(probe.worktreesDirectory(request.projectPath), true),
+        ]);
+        checks.push({ code: 'repository', status: repository ? 'ok' : 'error' }, { code: 'firstCommit', status: commit === 'ok' ? 'ok' : 'missing' }, { code: 'projectWritable', status: writable ? 'ok' : 'error' }, { code: 'worktrees', status: worktrees ? 'ok' : 'error' });
+    }
+    return { engine: request.engine, checkedAt: new Date().toISOString(), checks };
+}
+const pending = new Map();
+/** Coalesce tabs checking the same target; do not retain private paths after completion. */
+export function getEnvironmentReport(request) {
+    const key = JSON.stringify(request);
+    const existing = pending.get(key);
+    if (existing)
+        return existing;
+    if (pending.size >= 8)
+        return Promise.reject(new Error('ENVIRONMENT_BUSY'));
+    const result = checkEnvironment(request).finally(() => pending.delete(key));
+    pending.set(key, result);
+    return result;
+}