@loicngr/kobo 1.11.26 → 1.11.28

package/dist/server/services/agent/turn-liveness.js

@@ -11,6 +11,7 @@ export function createTurnLiveness(input) {
     let active = false;
     let paused = false;
     let timedOut = false;
+    let currentTimeoutMs = input.timeoutMs;
     const arm = () => {
         if (!active || paused || timedOut)
             return;
@@ -22,7 +23,8 @@ export function createTurnLiveness(input) {
                 return;
             timedOut = true;
             input.onTimeout();
-        }, input.timeoutMs);
+        }, currentTimeoutMs);
+        timer.unref?.();
     };
     return {
         start() {
@@ -53,5 +55,14 @@ export function createTurnLiveness(input) {
                 clearTimeout(timer);
             timer = undefined;
         },
+        setTimeoutMs(ms) {
+            if (ms === currentTimeoutMs)
+                return;
+            currentTimeoutMs = ms;
+            // Re-arm only if a deadline is currently pending; a paused/stopped
+            // liveness picks the new duration up on its next arm().
+            if (timer)
+                arm();
+        },
     };
 }

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

@@ -5,6 +5,7 @@ import { slugifyProjectName } from '../utils/project-slug.js';
 import { resolveWorkspaceWorktreePath } from '../utils/worktree-paths.js';
 import * as orchestrator from './agent/orchestrator.js';
 import * as cleanupScriptService from './cleanup-script-service.js';
+import * as lifecycleHookService from './lifecycle-hook-service.js';
 import * as settingsService from './settings-service.js';
 import { getSuitePrompts } from './skill-suite-prompts.js';
 import { emit, emitEphemeral } from './websocket-service.js';
@@ -91,6 +92,13 @@ export function disable(workspaceId, reason) {
     console.info(`[auto-loop] disabled workspace '${workspaceId}' reason=${reason}` +
         ` pending=${diagnostic.tasksPending} streak=${diagnostic.noProgressStreak} status=${diagnostic.status}`);
     emitEphemeral(workspaceId, 'autoloop:disabled', diagnostic);
+    // The user's own hook, if they wrote one. Deliberately fired for EVERY
+    // reason, not only 'completed' like the cleanup script below: a loop that
+    // stalled is precisely the case worth being told about.
+    void lifecycleHookService.onAutoLoopDisabled(workspaceId, {
+        reason,
+        tasksPending: diagnostic.tasksPending,
+    });
     // The loop finished every task — run the project's cleanup script. Other
     // disable reasons (stall / error / user-action) leave tasks unfinished, so
     // they intentionally skip the cleanup.
@@ -262,6 +270,51 @@ function computeIterationNumber(workspaceId) {
  * Worktree-missing edge: if the worktree directory has been deleted on disk,
  * `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.
+ */
+function hasFreeAgentSlot() {
+    const limit = settingsService.getGlobalSettings().maxConcurrentAgents;
+    if (!limit || limit <= 0)
+        return true;
+    return orchestrator.runningAgentCount() < limit;
+}
+/**
+ * Give every auto-loop workspace parked on "waiting for a free agent slot"
+ * another chance. Called by the orchestrator after ANY session ends: a parked
+ * workspace has no session of its own to end, so nothing else would ever ask
+ * spawnNextIteration on its behalf again.
+ *
+ * Stops as soon as the slots are full again, so with three parked and one
+ * free, exactly one starts and the other two keep waiting rather than each
+ * re-announcing that they wait.
+ */
+export function resumeWaitingWorkspaces() {
+    const db = getDb();
+    const rows = db
+        .prepare(`SELECT id, status FROM workspaces
+        WHERE auto_loop = 1 AND auto_loop_ready = 1 AND archived_at IS NULL
+        ORDER BY updated_at ASC`)
+        .all();
+    for (const row of rows) {
+        if (!hasFreeAgentSlot())
+            return;
+        if (orchestrator.hasController(row.id))
+            continue;
+        // Same guards as spawnNextIteration's own callers: a quota backoff or a
+        // pending question owns the next start of that workspace.
+        if (row.status === 'awaiting-user' || row.status === 'quota')
+            continue;
+        try {
+            spawnNextIteration(row.id);
+        }
+        catch (err) {
+            console.error(`[auto-loop] resume after slot freed failed for workspace '${row.id}':`, err);
+        }
+    }
+}
 function spawnNextIteration(workspaceId, opts = {}) {
     const row = getRow(workspaceId);
     if (!row)
@@ -274,6 +327,18 @@ function spawnNextIteration(workspaceId, opts = {}) {
         disable(workspaceId, 'completed');
         return;
     }
+    // Hold off rather than pile on. Ten auto-loop workspaces waking together
+    // hammer the same rate limit and each land in their own backoff, so nobody
+    // gets through. The loop stays enabled: the next session to end anywhere
+    // calls back in here, and by then a slot has freed.
+    if (!hasFreeAgentSlot()) {
+        console.log(`[auto-loop] workspace '${workspaceId}' is waiting for a free agent slot`);
+        emitEphemeral(workspaceId, 'autoloop:waiting-for-slot', {
+            running: orchestrator.runningAgentCount(),
+            limit: settingsService.getGlobalSettings().maxConcurrentAgents,
+        });
+        return;
+    }
     const iterationNumber = computeIterationNumber(workspaceId);
     // Override block: replaces the standard iteration prompt body when the task
     // title carries a recognized prefix (case-sensitive, trailing space required).

package/dist/server/services/awaiting-user-reminder-service.js

@@ -0,0 +1,115 @@
+import { getDb } from '../db/index.js';
+import { getGlobalSettings } from './settings-service.js';
+import { broadcastAll } from './websocket-service.js';
+/** How often the reminder loop looks at the clock. */
+const TICK_INTERVAL_MS = 60_000;
+/**
+ * Which waiting workspaces are owed a reminder now.
+ *
+ * `state` is updated in place: entries appear when a workspace starts waiting
+ * and disappear when it stops, so answering a question resets its clock.
+ *
+ * Pure apart from that mutation, which is what makes the interval arithmetic
+ * — the part that is easy to get wrong — testable without a timer or a DB.
+ */
+export function computeDueReminders(params) {
+    const { awaiting, now, intervalMs, state } = params;
+    // Disabled. Clear the state too: re-enabling later should start from now,
+    // not from a clock that kept running while the feature was off.
+    if (intervalMs <= 0) {
+        state.clear();
+        return [];
+    }
+    const stillWaiting = new Set(awaiting.map((w) => w.id));
+    for (const id of state.keys()) {
+        if (!stillWaiting.has(id))
+            state.delete(id);
+    }
+    const due = [];
+    for (const workspace of awaiting) {
+        const existing = state.get(workspace.id);
+        if (!existing) {
+            // First sight. The question was just asked, so nothing is overdue yet.
+            state.set(workspace.id, { firstSeenAt: now, lastRemindedAt: null, remindersSent: 0 });
+            continue;
+        }
+        // Measured from the LAST reminder (or the first sighting), not as a
+        // multiple of the interval since the start: that way a change of interval
+        // applies from the next reminder, and a laptop waking from sleep owing
+        // four reminders sends one, not four, for the same unanswered question.
+        const since = existing.lastRemindedAt ?? existing.firstSeenAt;
+        if (now - since < intervalMs)
+            continue;
+        existing.lastRemindedAt = now;
+        existing.remindersSent += 1;
+        due.push({
+            id: workspace.id,
+            name: workspace.name,
+            waitingMs: now - existing.firstSeenAt,
+            reminderNumber: existing.remindersSent,
+        });
+    }
+    return due;
+}
+const reminderState = new Map();
+let timer = null;
+function listAwaitingWorkspaces() {
+    return getDb()
+        .prepare(`SELECT id, name FROM workspaces WHERE status = 'awaiting-user' AND archived_at IS NULL`)
+        .all();
+}
+/**
+ * One pass of the reminder loop. Broadcast rather than emitted to the
+ * workspace's subscribers: the whole point is to reach the user who is looking
+ * at something else, or at nothing.
+ *
+ * Never throws — it runs on a timer nobody is watching, and an exception here
+ * would silently end the loop for the rest of the process's life.
+ */
+export function runReminderTick(now = Date.now()) {
+    try {
+        const minutes = getGlobalSettings().awaitingUserReminderMinutes;
+        // The API refuses more than a day; a hand-edited settings.json gets the
+        // same ceiling here rather than a reminder that fires next week.
+        const intervalMs = typeof minutes === 'number' && minutes > 0 ? Math.min(minutes, 1440) * 60_000 : 0;
+        if (intervalMs <= 0) {
+            reminderState.clear();
+            return;
+        }
+        for (const reminder of computeDueReminders({
+            awaiting: listAwaitingWorkspaces(),
+            now,
+            intervalMs,
+            state: reminderState,
+        })) {
+            broadcastAll('workspace:awaiting-reminder', {
+                workspaceId: reminder.id,
+                workspaceName: reminder.name,
+                waitingMinutes: Math.round(reminder.waitingMs / 60_000),
+                reminderNumber: reminder.reminderNumber,
+            });
+        }
+    }
+    catch (err) {
+        console.error('[awaiting-user-reminder] tick failed:', err);
+    }
+}
+/** Start the reminder loop. Idempotent. */
+export function startAwaitingUserReminder() {
+    if (timer)
+        return;
+    timer = setInterval(() => runReminderTick(), TICK_INTERVAL_MS);
+    timer.unref?.();
+}
+/** Stop the reminder loop. */
+export function stopAwaitingUserReminder() {
+    if (timer) {
+        clearInterval(timer);
+        timer = null;
+    }
+}
+/** @internal */
+export function _resetForTest() {
+    stopAwaitingUserReminder();
+    reminderState.clear();
+}

package/dist/server/services/change-source-branch-service.js

@@ -109,7 +109,7 @@ async function runBuiltInStrategy(workspaceId, worktreePath, workingBranch, proj
     // the branchExists check below is the authoritative gate for the new base
     // (it throws a clean error, mapped to a 400, rather than a raw fetch error).
     try {
-        gitOps.fetchAllBranches(worktreePath);
+        await gitOps.fetchAllBranchesAsync(worktreePath);
     }
     catch {
         // offline / no remote — proceed with local refs

package/dist/server/services/file-editor-service.js

@@ -1,7 +1,6 @@
 import { createHash } from 'node:crypto';
-import { realpathSync } from 'node:fs';
-import * as path from 'node:path';
 import { getFileContent, writeFileInWorktree } from '../utils/git-ops.js';
+import { resolvePathInside } from '../utils/safe-path.js';
 const MAX_FILE_BYTES = 1024 * 1024;
 export function shaOf(content) {
     return createHash('sha256').update(content, 'utf8').digest('hex');
@@ -12,7 +11,7 @@ export function shaOf(content) {
  * escapes the worktree (including via symlinks), or when content exceeds 1 MB.
  */
 export function saveWorkspaceFile(worktreePath, relativePath, content, baseSha) {
-    const absPath = resolveSafe(worktreePath, relativePath);
+    const absPath = resolvePathInside(worktreePath, relativePath);
     if (Buffer.byteLength(content, 'utf8') > MAX_FILE_BYTES) {
         throw new Error(`File too large (max ${MAX_FILE_BYTES / 1024 / 1024} MB)`);
     }
@@ -24,46 +23,3 @@ export function saveWorkspaceFile(worktreePath, relativePath, content, baseSha)
     writeFileInWorktree(absPath, content);
     return { status: 'saved' };
 }
-function resolveSafe(worktreePath, relativePath) {
-    const abs = path.resolve(worktreePath, relativePath);
-    const lexicalRoot = path.resolve(worktreePath);
-    // Lexical containment check FIRST: a path that escapes the worktree via `..`
-    // (or an absolute path) must be reported as an escape deterministically —
-    // independent of whether the traversal happens to land on a directory that
-    // exists on disk. Without this, `../../etc/passwd` surfaces as "parent
-    // directory does not exist" instead of "escapes the worktree" whenever the
-    // worktree sits deep enough that the `..` chain lands on a missing dir.
-    if (abs !== lexicalRoot && !abs.startsWith(lexicalRoot + path.sep)) {
-        throw new Error(`Path '${relativePath}' escapes the worktree`);
-    }
-    const root = realpathSync(lexicalRoot);
-    const rootWithSep = root + path.sep;
-    // Resolve the parent's realpath (parent must exist; if it doesn't, the path
-    // is invalid anyway and we surface that). Then join the lexical basename so
-    // a non-existent leaf doesn't trigger ENOENT.
-    let realParent;
-    try {
-        realParent = realpathSync(path.dirname(abs));
-    }
-    catch {
-        throw new Error(`Path '${relativePath}' is invalid (parent directory does not exist)`);
-    }
-    const realAbs = path.join(realParent, path.basename(abs));
-    if (realAbs !== root && !realAbs.startsWith(rootWithSep)) {
-        throw new Error(`Path '${relativePath}' escapes the worktree`);
-    }
-    // If the leaf exists and is itself a symlink, follow it and re-check
-    // containment so we never write through a symlink that escapes the worktree.
-    try {
-        const leafReal = realpathSync(realAbs);
-        if (leafReal !== root && !leafReal.startsWith(rootWithSep)) {
-            throw new Error(`Path '${relativePath}' escapes the worktree`);
-        }
-        return leafReal;
-    }
-    catch (err) {
-        if (err.code === 'ENOENT')
-            return realAbs;
-        throw err;
-    }
-}

package/dist/server/services/forge/bitbucket/provider.js

@@ -1,6 +1,7 @@
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { getGlobalSettings } from '../../settings-service.js';
+import { parseCliJson } from '../parse-cli-json.js';
 import { deriveReadyToMerge } from '../types.js';
 const execFileAsync = promisify(execFile);
 function record(value) {
@@ -233,14 +234,14 @@ async function resolveTarget(repoPath) {
     if (bktEnv().BKT_TOKEN)
         return { ...target, context: null };
     const { stdout: contextOutput } = await execFileAsync('bkt', ['context', 'list', '--json'], bktOptions(repoPath));
-    const contexts = record(JSON.parse(contextOutput)).contexts;
+    const contexts = record(parseCliJson(contextOutput, 'bkt context list')).contexts;
     const existing = (Array.isArray(contexts) ? contexts : [])
         .map(record)
         .find((context) => string(context.workspace) === target.workspace && string(context.default_repo) === target.repo);
     if (existing && string(existing.name))
         return { ...target, context: string(existing.name) };
     const { stdout: authOutput } = await execFileAsync('bkt', ['auth', 'status', '--json'], bktOptions(repoPath));
-    const hosts = record(JSON.parse(authOutput)).hosts;
+    const hosts = record(parseCliJson(authOutput, 'bkt auth status')).hosts;
     const host = (Array.isArray(hosts) ? hosts : []).map(record).find((item) => string(item.kind) === 'cloud');
     const hostKey = string(host?.key);
     if (!hostKey)
@@ -255,7 +256,7 @@ function targetArgs(target) {
 async function fetchCi(repoPath, number, target) {
     try {
         const { stdout } = await execFileAsync('bkt', bktArgs(target, ['pr', 'checks', String(number), ...targetArgs(target), '--json']), bktOptions(repoPath));
-        const statuses = record(JSON.parse(stdout)).statuses;
+        const statuses = record(parseCliJson(stdout, 'bkt pr checks')).statuses;
         const checks = (Array.isArray(statuses) ? statuses : []).map(mapCheck);
         const rollup = checks.length === 0
             ? null
@@ -286,7 +287,7 @@ export const bitbucketProvider = {
     async isAvailable(repoPath) {
         try {
             const { stdout } = await execFileAsync('bkt', ['auth', 'status', '--json'], bktOptions(repoPath));
-            const status = record(JSON.parse(stdout));
+            const status = record(parseCliJson(stdout, 'bkt auth status'));
             const hosts = status.hosts;
             if ((Array.isArray(hosts) && hosts.length > 0) || bktEnv().BKT_TOKEN)
                 return { available: true };
@@ -304,7 +305,7 @@ export const bitbucketProvider = {
             // branch deletion, so do not stop at OPEN requests.
             for (const state of ['OPEN', 'MERGED', 'DECLINED']) {
                 const { stdout: listOutput } = await execFileAsync('bkt', bktArgs(target, ['pr', 'list', '--state', state, '--limit', '50', ...targetArgs(target), '--json']), bktOptions(repoPath));
-                const pullRequests = record(JSON.parse(listOutput)).pull_requests;
+                const pullRequests = record(parseCliJson(listOutput, 'bkt pr list')).pull_requests;
                 match = (Array.isArray(pullRequests) ? pullRequests : [])
                     .map(record)
                     .find((pullRequest) => branch(pullRequest, 'source', 'fromRef') === branchName);
@@ -314,7 +315,7 @@ export const bitbucketProvider = {
             if (!match)
                 return null;
             const { stdout: viewOutput } = await execFileAsync('bkt', bktArgs(target, ['pr', 'view', String(number(match.id)), ...targetArgs(target), '--json']), bktOptions(repoPath));
-            const raw = record(record(JSON.parse(viewOutput)).pull_request);
+            const raw = record(record(parseCliJson(viewOutput, 'bkt pr view')).pull_request);
             if (!number(raw.id))
                 return null;
             const ci = await fetchCi(repoPath, number(raw.id), target);
@@ -340,7 +341,7 @@ export const bitbucketProvider = {
             ...targetArgs(target),
             '--json',
         ]), bktOptions(repoPath));
-        const raw = record(JSON.parse(stdout));
+        const raw = record(parseCliJson(stdout, 'bkt pr create'));
         const prNumber = number(raw.id);
         const prUrl = string(raw.url);
         if (!prNumber || !prUrl)
@@ -363,7 +364,7 @@ export const bitbucketProvider = {
         if (opts.cursor)
             args.push('--page', opts.cursor);
         const { stdout } = await execFileAsync('bkt', bktArgs(target, args), bktOptions(repoPath));
-        const page = mapBitbucketPage(JSON.parse(stdout || '{}'));
+        const page = mapBitbucketPage(parseCliJson(stdout || '{}', 'bkt pr list'));
         if (opts.filter === 'all' && !opts.search?.trim())
             return page;
         const currentUser = getGlobalSettings().bitbucketUsername || undefined;

package/dist/server/services/forge/github/provider.js

@@ -1,6 +1,7 @@
 // src/server/services/forge/github/provider.ts
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
+import { parseCliJson } from '../parse-cli-json.js';
 import { deriveReadyToMerge } from '../types.js';
 const execFileAsync = promisify(execFile);
 const CLI_TIMEOUT_MS = 30_000;
@@ -174,7 +175,7 @@ export const githubProvider = {
             const raw = stdout.trim();
             if (!raw)
                 return null;
-            return mapGhPrToSnapshot(JSON.parse(raw));
+            return mapGhPrToSnapshot(parseCliJson(raw, 'gh pr view'));
         }
         catch {
             return null;
@@ -198,7 +199,7 @@ export const githubProvider = {
     },
     async listPullRequests(repoPath, opts) {
         const { stdout: repoJson } = await execFileAsync('gh', ['repo', 'view', '--json', 'nameWithOwner'], cliOptions(repoPath));
-        const nameWithOwner = String(JSON.parse(repoJson).nameWithOwner ?? '');
+        const nameWithOwner = String(parseCliJson(repoJson, 'gh repo view').nameWithOwner ?? '');
         if (!nameWithOwner)
             throw new Error('Could not determine the GitHub repository for this path');
         const args = [
@@ -214,6 +215,6 @@ export const githubProvider = {
         if (opts.cursor)
             args.push('-f', `after=${opts.cursor}`);
         const { stdout } = await execFileAsync('gh', args, cliOptions(repoPath));
-        return mapGithubSearchPage(JSON.parse(stdout));
+        return mapGithubSearchPage(parseCliJson(stdout, 'gh api graphql (list PRs)'));
     },
 };

package/dist/server/services/forge/gitlab/provider.js

@@ -1,6 +1,7 @@
 // src/server/services/forge/gitlab/provider.ts
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
+import { parseCliJson } from '../parse-cli-json.js';
 import { deriveReadyToMerge } from '../types.js';
 const execFileAsync = promisify(execFile);
 const CLI_TIMEOUT_MS = 30_000;
@@ -108,7 +109,7 @@ async function fetchGlabCi(repoPath, branch) {
         const raw = stdout.trim();
         if (!raw)
             return { rollup: null, checks: [] };
-        const pipeline = JSON.parse(raw);
+        const pipeline = parseCliJson(raw, 'glab ci get');
         return {
             rollup: mapPipelineRollup(pipeline.status),
             checks: (pipeline.jobs ?? []).map(mapGlabJobToCheck),
@@ -192,7 +193,7 @@ export const gitlabProvider = {
             const raw = stdout.trim();
             if (!raw)
                 return null;
-            const snapshot = mapGlabMrToSnapshot(JSON.parse(raw));
+            const snapshot = mapGlabMrToSnapshot(parseCliJson(raw, 'glab mr view'));
             snapshot.ci = await fetchGlabCi(repoPath, branch);
             snapshot.readyToMerge = deriveReadyToMerge(snapshot);
             return snapshot;
@@ -231,6 +232,6 @@ export const gitlabProvider = {
     },
     async listPullRequests(repoPath, opts) {
         const { stdout } = await execFileAsync('glab', buildGitlabListArgs(opts), cliOptions(repoPath));
-        return mapGitlabPage(JSON.parse(stdout || '[]'), opts);
+        return mapGitlabPage(parseCliJson(stdout || '[]', 'glab mr list'), opts);
     },
 };

package/dist/server/services/forge/parse-cli-json.js

@@ -0,0 +1,14 @@
+/** JSON.parse with a message a user can act on: a truncated or non-JSON CLI
+ *  response otherwise surfaces as a raw "Unexpected token…" 500. */
+export function parseCliJson(raw, context) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        // Keep the diagnostic trail: the user-facing message stays terse, but the
+        // original parse error and a sample of the offending output land in the
+        // server log so "unparsable output" reports can actually be investigated.
+        console.error(`[forge] ${context} returned unparsable output:`, err, raw.slice(0, 200));
+        throw new Error(`${context} returned unparsable output`);
+    }
+}

package/dist/server/services/forge/resolve.js

@@ -18,12 +18,30 @@ function readRemoteUrl(projectPath) {
         return execFileSync('git', ['remote', 'get-url', 'origin'], {
             cwd: projectPath,
             encoding: 'utf-8',
+            // Without a bound, a git hanging on a network filesystem blocks the whole
+            // event loop: this runs synchronously, and the pr-watcher calls it for
+            // every workspace on every tick.
+            timeout: 5_000,
         }).trim();
     }
     catch {
         return '';
     }
 }
+/**
+ * Auto-detected forge per project path. The remote of a checkout does not
+ * change while Kōbō runs, and resolving it costs a synchronous subprocess that
+ * the pr-watcher would otherwise pay per workspace, per 30 s tick, twice.
+ * Bounded by TTL so a remote that is added or repointed is picked up without a
+ * restart, and only the `auto` path is cached — an explicit setting is already
+ * free to read.
+ */
+const autoForgeCache = new Map();
+const AUTO_FORGE_TTL_MS = 5 * 60_000;
+/** Drop the cached auto-detection. Exported for tests. */
+export function _clearForgeCache() {
+    autoForgeCache.clear();
+}
 /**
  * Resolve the forge for a project: the explicit per-project setting wins;
  * `auto` (the default) classifies the origin remote URL.
@@ -33,5 +51,15 @@ export function resolveForge(projectPath) {
     if (setting === 'github' || setting === 'gitlab' || setting === 'bitbucket-community' || setting === 'none') {
         return setting;
     }
-    return forgeFromRemoteUrl(readRemoteUrl(projectPath));
+    const cached = autoForgeCache.get(projectPath);
+    if (cached && Date.now() - cached.readAt < AUTO_FORGE_TTL_MS)
+        return cached.forge;
+    const remoteUrl = readRemoteUrl(projectPath);
+    const forge = forgeFromRemoteUrl(remoteUrl);
+    // A read that failed (git timing out on a network mount, a transient lock)
+    // is not knowledge: caching it would disable PR actions for five minutes on
+    // a project that has a perfectly good remote.
+    if (remoteUrl)
+        autoForgeCache.set(projectPath, { forge, readAt: Date.now() });
+    return forge;
 }

package/dist/server/services/lifecycle-hook-service.js

@@ -0,0 +1,114 @@
+import fs from 'node:fs';
+import { getDb } from '../db/index.js';
+import { slugifyProjectName } from '../utils/project-slug.js';
+import { runScript } from '../utils/script-runner.js';
+import { resolveWorkspaceWorktreePath } from '../utils/worktree-paths.js';
+import { getEffectiveSettings, getGlobalSettings, getProjectSettings } from './settings-service.js';
+/** Which effective-settings key holds the script for each event. */
+const SCRIPT_KEY = {
+    'session-ended': 'sessionEndedScript',
+    'pr-merged': 'prMergedScript',
+    'autoloop-disabled': 'autoLoopDisabledScript',
+};
+function getRow(workspaceId) {
+    const row = getDb()
+        .prepare(`SELECT id, name, project_path, working_branch, source_branch, worktree_path
+       FROM workspaces WHERE id = ?`)
+        .get(workspaceId);
+    return row ?? null;
+}
+/**
+ * Run the user's hook for `event`, if they configured one.
+ *
+ * Resolves to `null` when there is nothing to run — no script, unknown
+ * workspace, or a worktree that is no longer on disk — and to the script's exit
+ * code otherwise. Never rejects: the caller is always in the middle of a
+ * lifecycle transition that must complete regardless.
+ */
+export async function runLifecycleHook(event, workspaceId, extraEnv) {
+    try {
+        const row = getRow(workspaceId);
+        if (!row)
+            return null;
+        const script = getEffectiveSettings(row.project_path)[SCRIPT_KEY[event]];
+        // Empty (or blank) means the user never wrote one. Hooks are opt-in: they
+        // run arbitrary shell, so absence of configuration is absence of a hook.
+        if (!script.trim())
+            return null;
+        const global = getGlobalSettings();
+        const projectSettings = getProjectSettings(row.project_path);
+        const projectSlug = global.worktreesPrefixByProject
+            ? slugifyProjectName(projectSettings?.displayName ?? '', row.project_path)
+            : undefined;
+        const worktreePath = row.worktree_path ??
+            resolveWorkspaceWorktreePath(row.project_path, row.working_branch, global.worktreesPath, projectSlug);
+        // A purged or manually deleted worktree has no cwd to spawn in. Routine
+        // for `pr-merged` once auto-purge has run; for the other events it means
+        // the user's script silently did not run, which deserves a line in the log.
+        if (!fs.existsSync(worktreePath)) {
+            if (event !== 'pr-merged') {
+                console.warn(`[lifecycle-hook] '${event}' hook skipped for workspace '${workspaceId}': worktree missing at ${worktreePath}`);
+            }
+            return null;
+        }
+        return await runScript({
+            workspaceId,
+            worktreePath,
+            script,
+            // Namespaced per event: three hooks streaming into one `hook:output` feed
+            // would be indistinguishable in the UI.
+            eventPrefix: `hook:${event}`,
+            tmpFileName: `.hook-${event}.tmp`,
+            env: {
+                workspaceName: row.name,
+                branchName: row.working_branch,
+                sourceBranch: row.source_branch,
+                projectPath: row.project_path,
+            },
+            extraEnv: { ...extraEnv, KOBO_HOOK_EVENT: event },
+        });
+    }
+    catch (err) {
+        console.error(`[lifecycle-hook] '${event}' hook failed for workspace '${workspaceId}':`, err);
+        return null;
+    }
+}
+/**
+ * An agent session ended. Fires for every real end — clean finish, error, user
+ * stop, watchdog kill — and lets the script tell them apart via
+ * `KOBO_SESSION_END_REASON`. Typical use: run the test suite, or notify.
+ */
+export async function onSessionEnded(workspaceId, outcome) {
+    await runLifecycleHook('session-ended', workspaceId, {
+        KOBO_SESSION_ID: outcome.sessionId,
+        KOBO_SESSION_END_REASON: outcome.reason,
+        // A missing exit code is an empty variable, not the string 'null': a shell
+        // script testing `-z "$KOBO_SESSION_EXIT_CODE"` should see nothing there.
+        KOBO_SESSION_EXIT_CODE: outcome.exitCode === null ? '' : String(outcome.exitCode),
+        KOBO_SESSION_STOP_CAUSE: outcome.stopCause ?? '',
+        // A hook that runs the test suite should know the next iteration may
+        // already be editing the same files.
+        KOBO_AUTOLOOP_ACTIVE: outcome.autoLoopActive ? '1' : '0',
+    });
+}
+/**
+ * A PR was merged. Runs before the workspace is archived or purged, so the
+ * worktree is still on disk and the script can act on it (deploy, tag, notify).
+ */
+export async function onPrMerged(workspaceId, pr) {
+    await runLifecycleHook('pr-merged', workspaceId, {
+        KOBO_PR_NUMBER: String(pr.prNumber),
+        KOBO_PR_URL: pr.prUrl,
+    });
+}
+/**
+ * Auto-loop turned itself off. `KOBO_AUTOLOOP_REASON` separates the loop
+ * finishing its work from it stalling or erroring out — the difference between
+ * a notification worth celebrating and one worth investigating.
+ */
+export async function onAutoLoopDisabled(workspaceId, info) {
+    await runLifecycleHook('autoloop-disabled', workspaceId, {
+        KOBO_AUTOLOOP_REASON: info.reason,
+        KOBO_TASKS_PENDING: String(info.tasksPending),
+    });
+}