@loicngr/kobo 1.11.45 → 2.1.1

package/dist/server/services/wakeup-service.js

@@ -45,11 +45,11 @@ const failedRetries = new Map();
 /** Keep a claimed wakeup durable while the session is still unavailable. */
 function defer(workspaceId, row) {
     const targetAt = new Date(Date.now() + ACTIVE_SESSION_RETRY_MS).toISOString();
-    getDb().prepare('UPDATE pending_wakeups SET target_at = ? WHERE workspace_id = ?').run(targetAt, workspaceId);
+    getDb().prepare('UPDATE pending_wakeups SET retry_at = ? WHERE workspace_id = ?').run(targetAt, workspaceId);
     const timeout = setTimeout(() => fire(workspaceId), ACTIVE_SESSION_RETRY_MS);
     timeout.unref?.();
     timers.set(workspaceId, timeout);
-    emitEphemeral(workspaceId, 'wakeup:scheduled', { targetAt, reason: row.reason ?? undefined });
+    emitEphemeral(workspaceId, 'wakeup:scheduled', { targetAt: row.target_at, reason: row.reason ?? undefined });
 }
 /** Schedule a wakeup for the given workspace. Replaces any existing pending wakeup. */
 export function schedule(workspaceId, delaySeconds, prompt, reason, agentSessionId) {
@@ -124,7 +124,7 @@ export function getPending(workspaceId) {
 export function isWakeupScheduled(workspaceId) {
     return getPending(workspaceId) !== null;
 }
-/** Re-register timers for rows persisted across restart. Skips stale entries. */
+/** Re-register persisted timers. Previously deferred work survives downtime; only never-attempted stale wakeups expire. */
 export function rehydrate() {
     suspendForShutdown();
     suspended = false;
@@ -134,14 +134,16 @@ export function rehydrate() {
         const now = Date.now();
         for (const row of rows) {
             try {
-                const target = new Date(row.target_at).getTime();
+                const target = new Date(row.retry_at ?? row.target_at).getTime();
                 const delay = target - now;
                 if (delay > 0) {
                     const timeout = setTimeout(() => fire(row.workspace_id), delay);
                     timeout.unref?.();
                     timers.set(row.workspace_id, timeout);
                 }
-                else if (-delay <= STALE_WAKEUP_GRACE_MS) {
+                else if (row.retry_at != null || -delay <= STALE_WAKEUP_GRACE_MS) {
+                    // Admission deferred this wakeup after its deadline. Downtime does not
+                    // revoke the pending instruction; retry through the same admission gate.
                     const timeout = setTimeout(() => fire(row.workspace_id), 0);
                     timeout.unref?.();
                     timers.set(row.workspace_id, timeout);

package/dist/server/services/workspace-service.js

@@ -1,5 +1,6 @@
 import { nanoid } from 'nanoid';
 import { parseTaskVerification } from '../../shared/task-verification.js';
+import { isWorkflowPolicy, LEGACY_WORKFLOW_POLICY, resolveWorkflowPolicy, } from '../../shared/workflow-policy.js';
 import { getDb } from '../db/index.js';
 import { isValidBranchName } from '../utils/git-ops.js';
 import { resolveWorkspaceWorktreePath } from '../utils/worktree-paths.js';
@@ -54,7 +55,17 @@ function coerceAgentPermissionMode(raw) {
     return 'bypass';
 }
 function mapWorkspace(row) {
+    let workflowPolicy = { ...LEGACY_WORKFLOW_POLICY };
+    if (row.workflow_policy) {
+        try {
+            workflowPolicy = resolveWorkflowPolicy(JSON.parse(row.workflow_policy));
+        }
+        catch {
+            workflowPolicy = resolveWorkflowPolicy();
+        }
+    }
     return {
+        workflowPolicy,
         id: row.id,
         name: row.name,
         projectPath: row.project_path,
@@ -128,6 +139,9 @@ export function createWorkspace(data) {
     const id = nanoid();
     const computedWorktreePath = data.worktreePath ?? resolveWorkspaceWorktreePath(data.projectPath, data.workingBranch, data.worktreesPath);
     const owned = data.worktreeOwned ?? true;
+    if (data.workflowPolicy !== undefined && !isWorkflowPolicy(data.workflowPolicy))
+        throw new Error('Invalid workflowPolicy');
+    const workflowPolicy = resolveWorkflowPolicy(data.workflowPolicy);
     // Mirror the unified mode into the legacy columns so older readers (in-flight
     // requests during deploy, external scripts) still see a sane value.
     const unifiedMode = data.agentPermissionMode ?? 'bypass';
@@ -137,12 +151,12 @@ export function createWorkspace(data) {
     INSERT INTO workspaces (
       id, name, project_path, source_branch, working_branch, status,
       notion_url, notion_page_id, sentry_url, pr_url, worktree_path, worktree_owned,
-      model, brainstorm_model, reasoning_effort, permission_mode, permission_profile, agent_permission_mode, engine, comparison_id, created_at, updated_at
-    ) VALUES (?, ?, ?, ?, ?, 'created', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      model, brainstorm_model, reasoning_effort, permission_mode, permission_profile, agent_permission_mode, engine, comparison_id, created_at, updated_at, workflow_policy
+    ) VALUES (?, ?, ?, ?, ?, 'created', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
   `).run(id, data.name, data.projectPath, data.sourceBranch, data.workingBranch, data.notionUrl ?? null, data.notionPageId ?? null, data.sentryUrl ?? null, data.prUrl ?? null, computedWorktreePath, owned ? 1 : 0, data.model ?? 'claude-opus-4-8', data.brainstormModel ?? null, data.reasoningEffort ?? 'auto', legacyMode, legacyProfile, unifiedMode, data.engine ?? 'claude-code', 
     // Empty string is not a group: it would silently gather every workspace
     // created with a blank id into one comparison.
-    data.comparisonId?.trim() ? data.comparisonId : null, now, now);
+    data.comparisonId?.trim() ? data.comparisonId : null, now, now, JSON.stringify(workflowPolicy));
     return getWorkspace(id);
 }
 /** Fetch a single workspace by ID, or null if not found. */
@@ -162,7 +176,8 @@ export function listComparisonMembers(comparisonId) {
     if (!comparisonId.trim())
         return [];
     const rows = getDb()
-        .prepare('SELECT * FROM workspaces WHERE comparison_id = ? ORDER BY created_at, id')
+        // rowid breaks created_at ties in insertion order; the nanoid id is random.
+        .prepare('SELECT * FROM workspaces WHERE comparison_id = ? ORDER BY created_at, rowid')
         .all(comparisonId);
     return rows.map(mapWorkspace);
 }
@@ -389,6 +404,12 @@ export function updateWorkspaceFields(id, fields) {
         throw new Error(`Workspace '${id}' not found`);
     const assignments = [];
     const values = [];
+    if (fields.workflowPolicy !== undefined) {
+        if (!isWorkflowPolicy(fields.workflowPolicy))
+            throw new Error('Invalid workflowPolicy');
+        assignments.push('workflow_policy = ?');
+        values.push(JSON.stringify(resolveWorkflowPolicy(workspace.workflowPolicy, fields.workflowPolicy)));
+    }
     if (fields.model !== undefined) {
         if (typeof fields.model !== 'string' || !fields.model.trim())
             throw new Error('model must be a non-empty string');

package/dist/server/services/worktree-service.js

@@ -450,8 +450,10 @@ export async function restoreWorktreeCheckoutUnlocked(input) {
             };
         }
         const registrations = await restoreRegistrations(projectPath);
+        // The destination is missing, so resolve its parent: git registers resolved paths.
+        const canonicalTarget = path.join(await canonicalize(path.dirname(worktreePath)), path.basename(worktreePath));
         // Do not globally prune: another missing checkout may still need its registration.
-        if (registrations.some((entry) => path.resolve(entry.path) === worktreePath)) {
+        if (registrations.some((entry) => path.resolve(entry.path) === canonicalTarget)) {
             throw new WorktreeCheckoutError('path-conflict', 'Git still registers the missing destination. Repair that worktree registration before retrying.');
         }
         if (registrations.some((entry) => entry.branch === `refs/heads/${workingBranch}`)) {

package/dist/server/utils/git-repo-lock.js

@@ -1,4 +1,5 @@
 import { execFile } from 'node:child_process';
+import { realpath } from 'node:fs/promises';
 import path from 'node:path';
 import { promisify } from 'node:util';
 /**
@@ -14,7 +15,10 @@ const execFileAsync = promisify(execFile);
 // out of order. This queue covers resolution only, never the locked operation.
 let registrations = Promise.resolve();
 /**
- * Absolute path of the git directory shared by every worktree of a repository.
+ * Absolute, symlink-resolved path of the git directory shared by every worktree
+ * of a repository. Git reports worktree paths resolved, so an unresolved key
+ * would split one repository into two locks when it is reached through a link
+ * (e.g. macOS temp dirs under /var -> /private/var).
  *
  * Falls back to the resolved input path when git cannot answer (not a
  * repository, git missing): a wrong key only costs parallelism, never
@@ -22,14 +26,14 @@ let registrations = Promise.resolve();
  */
 export async function resolveGitCommonDir(repoPath) {
     try {
-        const { stdout } = await execFileAsync('git', ['rev-parse', '--git-common-dir'], {
+        const { stdout } = await execFileAsync('git', ['rev-parse', '--path-format=absolute', '--git-common-dir'], {
             cwd: repoPath,
             encoding: 'utf-8',
             timeout: 10_000,
             killSignal: 'SIGKILL',
             env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
         });
-        return path.resolve(repoPath, stdout.replace(/\n$/, ''));
+        return await realpath(stdout.replace(/\n$/, ''));
     }
     catch {
         return path.resolve(repoPath);

package/dist/server/utils/mcp-client.js

@@ -1,5 +1,6 @@
 import { spawn } from 'node:child_process';
 import { readFileSync } from 'node:fs';
+import { stopMcpProcess } from './mcp-process.js';
 import { getPackageVersion } from './paths.js';
 function getClaudeConfigPath() {
     const homedir = process.env.HOME ?? process.env.USERPROFILE ?? '';
@@ -52,7 +53,7 @@ const nextRpcId = (() => {
 /**
  * Spawn an MCP server process given explicit command, args, and env.
  * The caller is responsible for constructing the full env (including auth headers).
- * stderr is consumed silently; set DEBUG_MCP_STDERR=1 to print it.
+ * stderr content is never logged: integrations may print credentials. Debug mode reports byte counts only.
  */
 export function spawnMcpProcess(command, args, env) {
     const mcpProcess = spawn(command, args, {
@@ -67,12 +68,12 @@ export function spawnMcpProcess(command, args, env) {
     // without any listener crashes the whole Node process (Unhandled 'error').
     // Callers may attach their own listener for typed handling — listeners are
     // additive on EventEmitter so this default never blocks them.
-    mcpProcess.on('error', (err) => {
-        console.error(`[mcp] spawn '${command}' failed: ${err.message}`);
+    mcpProcess.on('error', () => {
+        console.error('[mcp] Failed to start configured server; check executable and connection settings');
     });
     mcpProcess.stderr?.on('data', (data) => {
         if (process.env.DEBUG_MCP_STDERR) {
-            console.error('[mcp stderr]', data.toString());
+            console.error('[mcp] stderr received (content withheld)', data.length);
         }
     });
     return mcpProcess;
@@ -101,7 +102,7 @@ export async function initializeMcp(mcpProcess) {
         const initTimeoutMs = Number(process.env.KOBO_MCP_INIT_TIMEOUT_MS) || 30_000;
         const timeout = setTimeout(() => {
             mcpProcess.stdout?.removeListener('data', onData);
-            mcpProcess.kill();
+            stopMcpProcess(mcpProcess);
             reject(new Error(`initializeMcp timed out after ${initTimeoutMs}ms`));
         }, initTimeoutMs);
         const onData = (chunk) => {
@@ -117,6 +118,10 @@ export async function initializeMcp(mcpProcess) {
                     if (parsed.id === id) {
                         clearTimeout(timeout);
                         mcpProcess.stdout?.removeListener('data', onData);
+                        if (parsed.error) {
+                            reject(new Error('MCP initialization failed; check integration configuration'));
+                            return;
+                        }
                         const initialized = JSON.stringify({
                             jsonrpc: '2.0',
                             method: 'notifications/initialized',
@@ -130,10 +135,10 @@ export async function initializeMcp(mcpProcess) {
                 }
             }
         };
-        const onError = (err) => {
+        const onError = () => {
             clearTimeout(timeout);
             mcpProcess.stdout?.removeListener('data', onData);
-            reject(err);
+            reject(new Error('MCP transport failed'));
         };
         mcpProcess.stdout.on('data', onData);
         mcpProcess.stdout.once('error', onError);
@@ -158,7 +163,7 @@ export async function callMcpTool(mcpProcess, toolName, args) {
         const timeout = setTimeout(() => {
             mcpProcess.stdout?.removeListener('data', onData);
             mcpProcess.stdout?.removeListener('error', onError);
-            mcpProcess.kill();
+            stopMcpProcess(mcpProcess);
             reject(new Error(`callMcpTool('${toolName}') timed out after 30s`));
         }, 30_000);
         const onData = (chunk) => {
@@ -176,10 +181,17 @@ export async function callMcpTool(mcpProcess, toolName, args) {
                         mcpProcess.stdout?.removeListener('data', onData);
                         mcpProcess.stdout?.removeListener('error', onError);
                         if (parsed.error) {
-                            reject(new Error(`MCP tool '${toolName}' error: ${parsed.error.message} (code: ${parsed.error.code})`));
+                            reject(new Error(`MCP tool failed (code: ${Number.isInteger(parsed.error.code) ? parsed.error.code : 'unknown'})`));
                         }
                         else {
-                            resolve(parsed.result);
+                            if (parsed.result &&
+                                typeof parsed.result === 'object' &&
+                                'isError' in parsed.result &&
+                                parsed.result.isError === true) {
+                                reject(new Error('MCP tool reported a failure; check integration credentials and access'));
+                            }
+                            else
+                                resolve(parsed.result);
                         }
                     }
                 }
@@ -188,10 +200,10 @@ export async function callMcpTool(mcpProcess, toolName, args) {
                 }
             }
         };
-        const onError = (err) => {
+        const onError = () => {
             clearTimeout(timeout);
             mcpProcess.stdout?.removeListener('data', onData);
-            reject(err);
+            reject(new Error('MCP transport failed'));
         };
         mcpProcess.stdout.on('data', onData);
         mcpProcess.stdout.once('error', onError);
@@ -206,6 +218,8 @@ export async function callMcpTool(mcpProcess, toolName, args) {
 export function unwrapMcpResult(result) {
     if (result && typeof result === 'object') {
         const obj = result;
+        if (obj.isError === true)
+            throw new Error('MCP tool reported a failure; check integration credentials and access');
         if (Array.isArray(obj.content)) {
             const first = obj.content[0];
             if (first?.type === 'text' && first.text) {

package/dist/server/utils/mcp-process.js

@@ -0,0 +1,25 @@
+/** MCP commands run in their own process group, including wrapper descendants. */
+export function stopMcpProcess(child) {
+    child.stdin?.end();
+    const pid = child.pid;
+    const signal = (value) => {
+        try {
+            if (pid && process.platform !== 'win32')
+                process.kill(-pid, value);
+            else
+                child.kill(value);
+        }
+        catch {
+            try {
+                child.kill(value);
+            }
+            catch {
+                /* Already gone. */
+            }
+        }
+    };
+    signal('SIGTERM');
+    // Keep the group cleanup even when a wrapper exits before its descendants.
+    const force = setTimeout(() => signal('SIGKILL'), 1000);
+    force.unref();
+}

package/dist/server/utils/node-pty-spawn-helper.js

@@ -0,0 +1,31 @@
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+function nodePtyRoot() {
+    return path.dirname(createRequire(import.meta.url).resolve('node-pty/package.json'));
+}
+/**
+ * node-pty 1.1.0 publishes its macOS `spawn-helper` prebuilds without the
+ * execute bit, so every spawn fails with `posix_spawnp failed` (a blank
+ * terminal in Kōbō). Restore the bit at runtime rather than in an install
+ * script, which `--ignore-scripts` installs would skip.
+ *
+ * Returns the helper it made executable, or `null` when there is nothing to do.
+ * Throws when the helper cannot be changed (e.g. a root-owned global install).
+ */
+export function ensureSpawnHelperExecutable({ platform = process.platform, arch = process.arch, root, } = {}) {
+    if (platform !== 'darwin')
+        return null;
+    const helper = path.join(root ?? nodePtyRoot(), 'prebuilds', `darwin-${arch}`, 'spawn-helper');
+    let mode;
+    try {
+        mode = fs.statSync(helper).mode;
+    }
+    catch {
+        return null; // Built from source: node-gyp output is already executable.
+    }
+    if ((mode & 0o111) !== 0)
+        return null;
+    fs.chmodSync(helper, (mode & 0o777) | 0o111);
+    return helper;
+}

package/dist/server/utils/paths.js

@@ -101,6 +101,13 @@ export function getTemplatesPath() {
 export function getWorkspaceTemplatesPath() {
     return path.join(getKoboHome(), 'workspace-templates.json');
 }
+/**
+ * Directory holding the user's imported notification sounds and their manifest.
+ * Separate from the bundled tones shipped inside the SPA under `/sounds`.
+ */
+export function getCustomSoundsDir() {
+    return path.join(getKoboHome(), 'sounds');
+}
 /**
  * Absolute path to the compiled MCP server entry (shipped in the published
  * package as dist/mcp-server/kobo-tasks-server.js). Returns null if not

package/dist/shared/auto-loop-prompts.js

@@ -48,7 +48,9 @@ export function buildAutoLoopGroomingSteps(e2e, finalization) {
     ];
     let nextNum = 4;
     if (e2e.framework) {
-        const skillHint = e2e.skill ? `Use the \`${e2e.skill}\` skill for this task. ` : '';
+        const skillHint = e2e.skill
+            ? `Use the \`${e2e.skill}\` skill for this task if available; otherwise use the existing project test tools directly. `
+            : '';
         const promptHint = e2e.prompt ? `Additional guidance: ${e2e.prompt}` : '';
         steps.push(`${nextNum}. **E2E review**: walk the task list and identify which tasks produce user-visible behavior (UI flows, form submissions, page renders, etc.). For each one that warrants regression coverage, INSERT a follow-up sub-task with title prefixed \`[E2E] \` describing the test to write. Use \`after_task_id\` to insert it directly after the parent task; \`list_tasks\` exposes \`sort_order\` so you can verify ordering. Skip tasks that don't produce user-visible behavior (refactors, infra, internal services) and briefly justify your choices in chat. The project uses \`${e2e.framework}\`. ${skillHint}${promptHint}`.trim());
         nextNum++;
@@ -84,7 +86,9 @@ Read kobo__list_tasks again. If any work or criterion remains open, or any requi
 export function buildE2eIterationBlock(e2e) {
     if (!e2e.framework)
         return '';
-    const skillLine = e2e.skill ? `Use the \`${e2e.skill}\` skill for this task.\n` : '';
+    const skillLine = e2e.skill
+        ? `Use the \`${e2e.skill}\` skill for this task if available; otherwise use the existing project test tools directly.\n`
+        : '';
     const promptLine = e2e.prompt ? `Additional guidance: ${e2e.prompt}\n` : '';
     return `
 This is an **E2E regression test** task.

package/dist/shared/automatic-admission.js

@@ -0,0 +1 @@
+export {};

package/dist/shared/environment.js

@@ -0,0 +1 @@
+export {};

package/dist/shared/notification-assets.js

@@ -0,0 +1,73 @@
+/** Only original, reproducible sounds are included in the public distribution. */
+export const PUBLIC_NOTIFICATION_SOUNDS = ['neutral.wav', 'ready.wav'];
+export const DEFAULT_PUBLIC_NOTIFICATION_SOUND = PUBLIC_NOTIFICATION_SOUNDS[0];
+/**
+ * User-imported sounds live in `KOBO_HOME/sounds/` and are referenced as
+ * `custom:<id>`. The id is generated server-side, so a reference never carries
+ * a user-supplied filename and can never become a path segment on its own.
+ */
+export const CUSTOM_SOUND_PREFIX = 'custom:';
+export const CUSTOM_SOUND_ID_LENGTH = 12;
+const CUSTOM_SOUND_ID_PATTERN = new RegExp(`^[A-Za-z0-9_-]{${CUSTOM_SOUND_ID_LENGTH}}$`);
+export const CUSTOM_SOUND_EXTENSIONS = ['.wav', '.mp3', '.ogg', '.webm'];
+/** Formats every browser Kōbō targets can decode. */
+export const CUSTOM_SOUND_CONTENT_TYPES = {
+    '.wav': 'audio/wav',
+    '.mp3': 'audio/mpeg',
+    '.ogg': 'audio/ogg',
+    '.webm': 'audio/webm',
+};
+export const CUSTOM_SOUND_ACCEPT = [...Object.values(CUSTOM_SOUND_CONTENT_TYPES), ...CUSTOM_SOUND_EXTENSIONS].join(',');
+/** A notification is short: the largest removed bundled sound was 207 KB. */
+export const MAX_CUSTOM_SOUND_BYTES = 2 * 1024 * 1024;
+export const MAX_CUSTOM_SOUNDS = 20;
+export function customSoundReference(id) {
+    return `${CUSTOM_SOUND_PREFIX}${id}`;
+}
+export function isCustomNotificationSound(value) {
+    return (typeof value === 'string' &&
+        value.startsWith(CUSTOM_SOUND_PREFIX) &&
+        CUSTOM_SOUND_ID_PATTERN.test(value.slice(CUSTOM_SOUND_PREFIX.length)));
+}
+/** Returns the bare id of a well-formed reference, or an empty string. */
+export function customSoundId(value) {
+    return isCustomNotificationSound(value) ? value.slice(CUSTOM_SOUND_PREFIX.length) : '';
+}
+/** Browsers label audio MIME types inconsistently, so the extension decides. */
+export function customSoundExtension(name) {
+    const extension = /\.[^.\\/]+$/.exec(name)?.[0]?.toLowerCase() ?? '';
+    return CUSTOM_SOUND_EXTENSIONS.includes(extension) ? extension : null;
+}
+/**
+ * A custom reference is kept on its shape alone: settings migrations run before
+ * the catalogue is readable, and both the client and the file route already fall
+ * back to the bundled tone when the file is gone.
+ */
+export function normalizePublicNotificationSound(value, allowSentinel = true) {
+    if (allowSentinel && (value === 'inherit' || value === 'none'))
+        return value;
+    if (isCustomNotificationSound(value))
+        return value;
+    return typeof value === 'string' && PUBLIC_NOTIFICATION_SOUNDS.includes(value)
+        ? value
+        : DEFAULT_PUBLIC_NOTIFICATION_SOUND;
+}
+export const NOTIFICATION_SOUND_KEYS = [
+    'audioNotificationSound',
+    'audioQuestionSound',
+    'audioWorkspaceCreatedSound',
+    'audioAgentErrorSound',
+    'audioPrCiFailedSound',
+    'audioPrCiRecoveredSound',
+    'audioPrChangesRequestedSound',
+    'audioPrApprovedSound',
+    'audioPrMergeConflictSound',
+    'audioPrReadyToMergeSound',
+    'audioPrMergedSound',
+];
+export function normalizePublicSounds(settings) {
+    for (const key of NOTIFICATION_SOUND_KEYS) {
+        if (key in settings)
+            settings[key] = normalizePublicNotificationSound(settings[key], key !== 'audioNotificationSound');
+    }
+}

package/dist/shared/skill-suite-prompts.js

@@ -1,6 +1,7 @@
 // src/shared/skill-suite-prompts.ts
 export function isValidSkillSuite(value) {
-    return (value === 'superpowers' ||
+    return (value === 'standard' ||
+        value === 'superpowers' ||
         value === 'gstack' ||
         value === 'ecc' ||
         value === 'superpowers+gstack' ||
@@ -24,7 +25,7 @@ const REVIEW_BODY = `## Scope
 
 Review ALL changes — both committed and uncommitted in the working tree:
 - \`git diff {{base_commit}}..HEAD\` — committed changes on this branch
-- \`git status\` and \`git diff\` — uncommitted changes (staged + unstaged)
+- \`git status\` and \`git diff\` / \`git diff --cached\` — unstaged / staged changes; inspect untracked files too
 
 ## Diff summary
 {{diff_stats}}
@@ -47,7 +48,7 @@ If no review skill is available, structure your reply as:
 export const AGNOSTIC_REVIEW_TEMPLATE = REVIEW_HEADER +
     'If a code-review skill is available in this environment, invoke it to drive this audit. Otherwise follow the manual checklist below.\n\n' +
     REVIEW_BODY;
-export const AGNOSTIC_AUTO_LOOP_REVIEW_GATE = 'Code review gate — BEFORE marking the task done, run whichever code-review skill is configured in this environment. Brief it with: what you just implemented, the task title, and the commit SHA (via `git rev-parse HEAD`). Ask specifically whether the change matches the task scope, whether edge cases are handled, and whether the commit is clean. If no review skill is available, do a manual self-review against the same criteria.';
+export const AGNOSTIC_AUTO_LOOP_REVIEW_GATE = 'Code review gate — BEFORE marking the task done, run whichever code-review skill is configured in this environment. Brief it with: what you just implemented, the task title, and the commit SHA (via `git rev-parse HEAD`). Ask specifically whether the change matches the task scope, whether edge cases are handled, and whether all committed and uncommitted changes are correct. Include staged, unstaged and untracked files. If no review skill is available, do a manual self-review against the same criteria.';
 export const AGNOSTIC_AUTO_LOOP_GROOMING_INTRO = 'You are preparing this workspace for Kōbō auto-loop mode. This is a GROOMING session only — DO NOT implement anything, DO NOT write or edit code, DO NOT run tests or builds, DO NOT invoke any implementation, planning, or release skill (your environment may have several). Your ONLY job is to curate the Kōbō task list via MCP tools.';
 export const AGNOSTIC_QA_PROMPT_TEMPLATE = 'QA pass for workspace "{{workspace_name}}" in project {{project_name}}.\n\nBranch: {{branch_name}}\nStaging URL: {{staging_url}}\n\nIf a QA skill is configured in this environment, invoke it on {{staging_url}}. Otherwise, manually exercise the staging URL against the workspace\'s acceptance criteria and report findings.';
 export const AGNOSTIC_BRAINSTORMING_INSTRUCTION = 'Brainstorm the implementation approach. Explore the codebase to understand the existing structure. Ask clarifying questions if needed. When you have a clear, user-approved plan, save it as a plan file in the project.';
@@ -65,6 +66,8 @@ export const GROOMING_INTRO_ALL = 'You are preparing this workspace for Kōbō a
  * user-provided override is used (or AGNOSTIC if the override is empty/blank).
  */
 export function getGroomingIntro(suite, customOverride) {
+    if (suite === 'standard')
+        return AGNOSTIC_AUTO_LOOP_GROOMING_INTRO;
     if (suite === 'custom') {
         const trimmed = (customOverride ?? '').trim();
         return trimmed || AGNOSTIC_AUTO_LOOP_GROOMING_INTRO;

package/dist/shared/workflow-policy.js

@@ -0,0 +1,25 @@
+export const WORKFLOW_ACTIONS = ['commit', 'push', 'publish'];
+export const MANUAL_WORKFLOW_POLICY = { commit: 'manual', push: 'manual', publish: 'manual' };
+/** Existing installations keep their previous autonomous workflow; explicit user constraints still win. */
+export const LEGACY_WORKFLOW_POLICY = {
+    commit: 'automatic',
+    push: 'automatic',
+    publish: 'automatic',
+};
+export function isWorkflowPolicy(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value) &&
+        Object.entries(value).every(([key, mode]) => WORKFLOW_ACTIONS.includes(key) && (mode === 'manual' || mode === 'automatic')));
+}
+export function resolveWorkflowPolicy(...layers) {
+    const result = { ...MANUAL_WORKFLOW_POLICY };
+    for (const layer of layers) {
+        if (isWorkflowPolicy(layer))
+            Object.assign(result, layer);
+    }
+    return result;
+}
+export function renderWorkflowPolicy(policy = MANUAL_WORKFLOW_POLICY) {
+    return `[Kōbō workflow preferences]\n${WORKFLOW_ACTIONS.map((action) => `- ${action}: ${policy[action]}`).join('\n')}\nManual means require explicit user authorization for that action; an explicit request authorizes that operation only, not future operations. Automatic means the configured preference supplies the authorization requested by built-in workflow prompts for that action when necessary for this mission. Always follow more restrictive user instructions (including no commits, no push or no publication), repository constraints and actual tool permissions. Publish covers creating or updating PR/MR descriptions and comments. Never merge a PR/MR based on these preferences; merging needs separate explicit authorization. These preferences are instructions, not an OS sandbox or a guarantee against arbitrary commands. Do not change sandbox or approval settings to satisfy a preference.\n`;
+}

package/docs/getting-started.md

@@ -0,0 +1,47 @@
+# Your first Kōbō workspace
+
+Kōbō is a local, single-user application that runs Claude Code or OpenAI Codex in Git worktrees. Each user installs their own instance and supplies their own provider account. A shared network token is not a multi-user account system.
+
+## Requirements
+
+- Node.js 24.15 or later, Git and Bash, with a writable local Git repository containing at least one commit.
+- A working login or API credential for the engine you choose. Kōbō ships neither credentials nor a provider subscription. Provider usage can incur charges.
+- Linux is the locally exercised platform for this readiness change. CI is configured to exercise Linux and macOS; a configured job is not a completed compatibility test. Windows users need a Linux environment such as WSL; native Windows and WSL have not been validated in this release rehearsal.
+
+No skill plugin, forge CLI, Docker, Notion, Sentry or voice software is needed for a basic mission. A repository without a remote works; choose forge `none` to disable PR/MR features.
+
+## Start
+
+```bash
+npx @loicngr/kobo@latest
+```
+
+This installs the latest published version, which may precede changes on `develop`. To try an unreleased checkout, follow [Contributing](../CONTRIBUTING.md), run `npm run build`, and start with a disposable home:
+
+```bash
+KOBO_HOME="/tmp/kobo-first-run" npm start
+```
+
+Open <http://localhost:3000>. The server binds to loopback by default. Do not expose it to a network just to complete setup.
+
+## Create a mission
+
+1. In the first-run panel, choose an engine and the path of your local Git repository.
+2. Run **Check environment**. Resolve missing Git, Bash, runtime, or write access before continuing. Authentication and model availability remain **unverified**: diagnostics do not contact a paid model or read your credentials.
+3. Continue to the creation form. Name the mission and describe a small change, including its acceptance criteria.
+4. Keep **Standard** and **Plan** for the first review. Standard requires no external skill suite. Plan does not silently become unrestricted when you prepare or enable auto-loop.
+5. Review the plan, explicitly select an execution permission mode when you are ready, and send the implementation instruction. Review the resulting diff before committing or publishing.
+
+New installations use manual commit, push and PR/MR publication preferences, disable audio and optional ticket integrations, and admit at most two concurrent unattended starts. Manual sessions can exceed that threshold. Agent workflow preferences are instructions; the engine permission mode supplies the actual sandbox and approval behavior.
+
+You can skip setup and reopen it from **Help → First-run setup**. Setup checks do not start a mission automatically.
+
+## Optional features
+
+Configure integrations only when you need them, in their Settings tabs. Notion and Sentry support direct command, JSON arguments and JSON environment configuration without a Claude installation; credentials are stored locally outside settings exports. Connection tests run only when explicitly requested. Forge actions use your authenticated forge CLI or configured Bitbucket credentials. See [Configuration](../CONFIGURATION.md) and [Security](../SECURITY.md).
+
+## Existing installations
+
+Upgrades preserve customized prompts, plugin selection, integration toggles, permission modes and resource limits. Existing installations retain legacy automatic Git workflow preferences; review them in Settings if you prefer manual authorization. Existing workspaces receive a snapshot of that historical policy, while new workspaces snapshot the effective global/project/create policy. Changing a global policy does not rewrite existing missions.
+
+Known shipped prompt text and retired sound selections are migrated; custom prompt text is preserved. Audio enablement and volume are retained. Take a complete backup before an upgrade; see [Troubleshooting](./troubleshooting.md).

package/docs/troubleshooting.md

@@ -0,0 +1,49 @@
+# Troubleshooting
+
+## Environment check
+
+Open the first-run setup from Help and run the check again after changing the selected engine or project. Reports show stable status codes and do not include raw command output or credentials.
+
+| Check | Action |
+|---|---|
+| Node | Use Node 24.15 or later; contributors should use `.nvmrc`. |
+| Git / Bash | Install the missing executable and make it available on the server's `PATH`. |
+| Project | Select a writable Git repository containing at least one commit. |
+| Storage / worktrees | Check permissions on `KOBO_HOME`, the project and configured worktree root. |
+| Engine executable | Reinstall the package dependencies and check the chosen runtime installation. |
+| Authentication / model: unknown | Authenticate with the selected provider, select a model available to that account, then run a small mission. The diagnostic deliberately makes no provider request. |
+
+## Native dependency installation fails
+
+Some platforms compile `node-pty` locally and need Python, make and a C++ compiler. During this rehearsal, node-gyp failed to find Node headers when its cache path contained spaces. Keep the build cache/home path free of spaces, or configure a separate node-gyp development cache before reinstalling. Application installation and Kōbō data directories with spaces and accented characters passed the Linux tarball test with a space-free build cache. This does not establish native Windows or WSL compatibility.
+
+## The agent stays in Plan
+
+Kōbō preserves your permission choice. Auto-loop can prepare a mission in Plan, but execution/finalization requires you to choose an execution mode explicitly. A plugin, prompt or workflow preference does not authorize an automatic permission escalation.
+
+Commit, push and publication are independent preferences. Manual means an explicit request is needed for that action. More restrictive instructions such as “no commits” still win over automatic preferences. These prompt instructions do not replace a sandbox.
+
+## Scheduled work waits
+
+The concurrent-agent setting controls unattended admission, including auto-loop, scheduled work and quota retries. Running manual sessions count against capacity, but starting a manual session is exempt. A terminating agent owns its slot until its process is confirmed closed. Waiting does not mean the scheduled instruction has run. Inspect the schedule/loop status, quota reset and current sessions before retrying.
+
+## Notion or Sentry fails
+
+Enable the feature, save a direct connection or configure the legacy Claude MCP entry, and explicitly run Test connection. Check command availability, JSON arguments/environment, provider access and page/project permissions. Saving a connection replaces the complete private configuration; stored secrets are not returned to the browser. Clearing it restores legacy lookup if a legacy entry exists.
+
+Kōbō hides MCP error text and stderr because third-party errors can include credentials. Inspect the MCP's configuration locally without pasting credentials into an issue. For Notion, server token environment variables override stored token variables; explicit `OPENAPI_MCP_HEADERS` remain authoritative for compatibility.
+
+## Backup and restore
+
+Daily and pre-migration SQLite snapshots are not a backup of settings, private integration configuration, repositories or uncommitted worktree changes.
+
+1. Stop Kōbō and its agents cleanly. Copy the complete `KOBO_HOME` directory and separately preserve the project/worktree directories. Keep this backup private.
+2. Before restoring, retain a copy of the current home. Use a separate directory for the restoration test and a matching application version. Never overwrite your only copy.
+3. Copy the selected SQLite snapshot to `kobo.db` in that separate home. Remove only stale `kobo.db-wal`/`kobo.db-shm` files from the separate restore copy while no server is using it. Restore matching settings and other JSON files from the full backup.
+4. Start with `KOBO_HOME` pointing at that separate directory. Confirm missions, conversations and settings before replacing production data. Old absolute worktree paths must still be available; starting an agent may write to them.
+
+Migrations move forward. Running an older binary on a newly migrated database is not a supported rollback. Restore a compatible backup instead.
+
+## Report a problem
+
+Use GitHub Issues for reproducible bugs; include OS/architecture, Node and Kōbō versions, chosen engine, steps and expected/actual behavior. Remove prompts, repository paths, tokens and personal data from attachments. Do not upload `kobo.db`, your complete data home, integration configuration or raw conversation exports. Report vulnerabilities privately via [Security](../SECURITY.md).