@loicngr/kobo 1.11.27 → 1.11.28

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),
+    });
+}

package/dist/server/services/network-access-service.js

@@ -11,19 +11,200 @@ export function isLoopbackAddress(address) {
 export function resolveBindHost(enabled) {
     return enabled ? undefined : '127.0.0.1';
 }
-/** Non-internal IPv4 URLs for the running server, for display + QR. */
+/**
+ * Non-internal addresses of the running server, one per LAN interface. Both
+ * families: with network access on, the server binds every interface, so an
+ * IPv6 address is as legitimate a way to reach it as an IPv4 one. A scoped
+ * link-local address (`fe80::1%eth0`) loses its zone, which is the form a URL
+ * carries.
+ */
+export function getLanHostnames() {
+    return collectLanAddresses(null);
+}
+/**
+ * Non-internal IPv4 URLs for the running server, for display + QR. IPv4 only:
+ * these are meant to be read off a screen or scanned from a phone, and an IPv6
+ * literal is neither.
+ */
 export function getLanUrls(port) {
-    const urls = [];
+    return collectLanAddresses('IPv4').map((address) => `http://${address}:${port}`);
+}
+function collectLanAddresses(family) {
+    const addresses = [];
     for (const infos of Object.values(os.networkInterfaces())) {
         if (!infos)
             continue;
         for (const info of infos) {
-            if (info.family === 'IPv4' && !info.internal) {
-                urls.push(`http://${info.address}:${port}`);
-            }
+            if (info.internal)
+                continue;
+            if (family !== null && info.family !== family)
+                continue;
+            // A scoped link-local address (`fe80::1%eth0`) loses its zone, which is
+            // the form a URL carries.
+            addresses.push(info.address.split('%')[0]);
         }
     }
-    return urls;
+    return addresses;
+}
+/**
+ * Hostnames that always designate the host machine itself. A request or a page
+ * carrying one of these is, by construction, already running on the user's own
+ * machine, whatever port it came from — which is what keeps the Quasar dev
+ * server (localhost:8080 proxying to localhost:3000) working.
+ */
+// `::ffff:7f00:1` is what the URL parser normalises `::ffff:127.0.0.1` into,
+// so both spellings of the IPv4-mapped loopback land here. `0.0.0.0` and `::`
+// name the wildcard bind rather than a host, but Linux routes them to loopback
+// and `http://0.0.0.0:3000` is a common bookmark; a rebinding page can never
+// produce them, since the browser puts its own domain in the Host.
+const LOCAL_HOSTNAMES = new Set(['localhost', '127.0.0.1', '::1', '::ffff:127.0.0.1', '::ffff:7f00:1', '0.0.0.0', '::']);
+/**
+ * Hostname carried by a raw `Host` or `Origin` header, or null when the value
+ * cannot be parsed. `Host` arrives bare (`127.0.0.1:3000`), `Origin` with a
+ * scheme (`http://127.0.0.1:3000`); adding a scheme when none is present runs
+ * both through the same URL rules, including the bracketed IPv6 form.
+ */
+function headerHostname(value) {
+    try {
+        const hostname = new URL(value.includes('://') ? value : `http://${value}`).hostname;
+        if (!hostname)
+            return null;
+        // The URL parser keeps IPv6 hostnames bracketed; compare on the bare address.
+        return hostname.startsWith('[') && hostname.endsWith(']') ? hostname.slice(1, -1) : hostname;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * True when a raw `Host`/`Origin` value names the machine itself. Always
+ * allowed, whatever the settings say, which lets a caller settle the common
+ * case without reading the settings file or listing the network interfaces —
+ * both synchronous, and this runs on every request.
+ */
+export function isLocalRequestHost(value) {
+    if (!value)
+        return false;
+    const hostname = headerHostname(value);
+    return hostname !== null && LOCAL_HOSTNAMES.has(hostname);
+}
+function isAllowedHostname(hostname, enabled, lanHostnames) {
+    if (!hostname)
+        return false;
+    if (LOCAL_HOSTNAMES.has(hostname))
+        return true;
+    return enabled && lanHostnames.includes(hostname);
+}
+/**
+ * Guards against DNS rebinding: a page on `evil.com` whose domain re-resolves
+ * to 127.0.0.1 reaches this server with `Host: evil.com`, and the browser then
+ * treats every response as same-origin. Only the names by which the machine is
+ * legitimately reachable are accepted — its own loopback names, plus its LAN
+ * addresses once network access is enabled.
+ *
+ * Behind a reverse proxy the Host is whatever domain the operator chose. When
+ * they declare it via `KOBO_NETWORK_ACCESS_PROXY_HOST` it is enforced like any
+ * other name; without it we cannot tell their domain from an attacker's, so
+ * anything is accepted. That mode also turns off the loopback exemption, so
+ * every `/api/*` request has to carry the token.
+ *
+ * Residual risk when the hostname is left undeclared: the SPA shell is served
+ * outside `/api/*` and therefore behind no token, so a rebinding page can be
+ * handed the real interface and ask the user to paste their token into it.
+ * Declaring the hostname closes that; otherwise, authenticate at the proxy.
+ */
+export function isAllowedRequestHost(params) {
+    if (!params.host)
+        return false;
+    const hostname = headerHostname(params.host);
+    if (params.behindProxy) {
+        // No declared hostname means we cannot tell the operator's domain from an
+        // attacker's, so anything goes — the historical behaviour.
+        if (!params.proxyHostname)
+            return true;
+        return hostname === params.proxyHostname || (hostname !== null && LOCAL_HOSTNAMES.has(hostname));
+    }
+    return isAllowedHostname(hostname, params.enabled, params.lanHostnames);
+}
+/**
+ * Hostname declared via `KOBO_NETWORK_ACCESS_PROXY_HOST`, or null when unset.
+ *
+ * Behind a reverse proxy we otherwise have to accept any Host, which leaves the
+ * door open to a rebinding page being served the real interface and asking the
+ * user to paste their token into it. Declaring the domain the proxy serves
+ * closes that, and costs one environment variable in the compose file where
+ * the other network-access settings already live.
+ */
+export function resolveProxyHostname(env = process.env) {
+    const raw = env.KOBO_NETWORK_ACCESS_PROXY_HOST?.trim();
+    if (!raw)
+        return null;
+    return headerHostname(raw);
+}
+/**
+ * Names the site a request was driven from. Guards two things.
+ *
+ * The WebSocket upgrade: WebSockets are exempt from the same-origin policy and
+ * send no preflight, so without this any page the user visits could open
+ * `/ws/terminal/<id>` and drive a real shell on the host.
+ *
+ * And cross-site writes: a page on another site reaching `http://localhost:3000`
+ * sends a perfectly legitimate `Host: localhost:3000` — the browser puts it
+ * there — so the Host check cannot see it. Reading the reply is already blocked
+ * (we send no CORS headers), but the write would still land, because Hono parses
+ * a JSON body whatever the Content-Type: a `text/plain` POST is a CORS simple
+ * request and needs no preflight.
+ *
+ * A missing Origin is allowed. Browsers attach one to every WebSocket handshake
+ * and every state-changing request, so its absence means a non-browser caller —
+ * curl, or Kōbō's own MCP server calling back into the API. Such a caller on
+ * loopback already has the machine, and over the LAN still needs the token.
+ *
+ * The rule is that the page must have been served by us: its authority has to
+ * match the Host this very request carries. That survives a port remap
+ * (`docker -p 3001:3000`, `ssh -L`) which a fixed port list would break, while
+ * still rejecting a page on another loopback port — including the per-workspace
+ * dev servers Kōbō itself spawns, serving whatever code an agent just wrote.
+ *
+ * Matching the Host is not a defense on its own, since a rebinding page matches
+ * it too. The Host check above is what rejects that one; this must simply not
+ * undo it.
+ */
+export function isAllowedOrigin(params) {
+    if (params.origin === undefined)
+        return true;
+    const origin = authority(params.origin);
+    if (origin === null)
+        return false;
+    if (params.behindProxy) {
+        if (!params.proxyHostname)
+            return true;
+        return headerHostname(params.origin) === params.proxyHostname;
+    }
+    // `quasar dev` proxies to the backend with changeOrigin, so it rewrites the
+    // Host to ours while the browser stays on the Quasar port. The two cannot
+    // match there, hence the explicit declaration.
+    if (params.devOrigin && origin === authority(params.devOrigin))
+        return true;
+    return params.requestHost !== undefined && origin === authority(params.requestHost);
+}
+/** Host and port of a raw `Host`/`Origin` value, or null when unparseable. */
+function authority(value) {
+    try {
+        return new URL(value.includes('://') ? value : `http://${value}`).host || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Origin the development client is served from, declared by the `dev` script
+ * via `KOBO_DEV_CLIENT_ORIGIN`. Never set in a published build, so it cannot
+ * widen anything in production.
+ */
+export function resolveDevClientOrigin(env = process.env) {
+    const raw = env.KOBO_DEV_CLIENT_ORIGIN?.trim();
+    return raw ? raw : null;
 }
 /** ~32-char url-safe random token. */
 export function generateToken() {

package/dist/server/services/pr-watcher-service.js

@@ -1,10 +1,12 @@
 import fs from 'node:fs';
 import { fetchSourceBranchAsync, isGitWorktree } from '../utils/git-ops.js';
 import { withGitRepoLock } from '../utils/git-repo-lock.js';
+import { hasController } from './agent/orchestrator.js';
 import { stopDevServer } from './dev-server-service.js';
 import { getForgeProvider } from './forge/registry.js';
 import { resolveForge } from './forge/resolve.js';
 import { computeGitStats } from './git-stats-service.js';
+import * as lifecycleHookService from './lifecycle-hook-service.js';
 import { getGlobalSettings } from './settings-service.js';
 import { destroyTerminal } from './terminal-service.js';
 import { emitEphemeral } from './websocket-service.js';
@@ -21,6 +23,8 @@ import { purgeWorktree } from './worktree-purge-service.js';
 const POLL_INTERVAL_MS = 30 * 1000; // 30 seconds
 const WORKSPACE_CHECK_CONCURRENCY = 4;
 let timer = null;
+/** Latched by `stopPrWatcher` so a tick already in flight does not re-arm. */
+let stopped = false;
 let checking = false;
 async function runBounded(items, concurrency, worker) {
     let nextIndex = 0;
@@ -186,16 +190,28 @@ export async function checkPrStatuses() {
             // Archive on a transition FROM OPEN to CLOSED/MERGED. Skips the
             // base-change detection below — archiving wins.
             if (prev?.state === 'OPEN' && (pr.state === 'MERGED' || pr.state === 'CLOSED')) {
+                // Started here, awaited just before the purge below: the worktree is
+                // still on disk at this point, and a hook that deploys or tags from it
+                // must not have the ground removed under it by auto-purge.
+                let prMergedHook = Promise.resolve();
                 if (pr.state === 'MERGED') {
                     emitEphemeral(ws.id, 'pr:merged', {
                         prNumber: pr.number,
                         prUrl: pr.url,
                     });
+                    prMergedHook = lifecycleHookService.onPrMerged(ws.id, { prNumber: pr.number, prUrl: pr.url });
                 }
-                if (['extracting', 'brainstorming', 'executing'].includes(ws.status)) {
+                if (['extracting', 'brainstorming', 'executing'].includes(ws.status) || hasController(ws.id)) {
                     // Agent is working — update the cache but skip auto-archive.
                     // (The defensive base preservation from the no-base branch doesn't apply here
                     // because we ARE in the OPEN→MERGED/CLOSED branch which always has a base.)
+                    //
+                    // The status list alone is not enough: `awaiting-user` is a live
+                    // session parked on a tool approval, and a controller can still be
+                    // draining while the status already reads idle or error. Unlike the
+                    // manual archive route and purge-worktree, this path never stops the
+                    // agent, so archiving under one orphans its pending question and
+                    // leaves it writing into a workspace the UI now shows as archived.
                     lastKnownPr.set(ws.id, pr);
                     return;
                 }
@@ -226,6 +242,9 @@ export async function checkPrStatuses() {
                     try {
                         const { autoPurgeOnPrMerged } = getGlobalSettings();
                         if (autoPurgeOnPrMerged) {
+                            // `onPrMerged` never rejects and is capped by the script-runner's
+                            // own timeout, so this cannot hang the watcher indefinitely.
+                            await prMergedHook;
                             void purgeWorktree(ws.id)
                                 .then((result) => {
                                 // Auto-purge runs with nobody watching: without this trace an
@@ -360,6 +379,11 @@ async function runOneCheck() {
 function scheduleNext() {
     timer = setTimeout(async () => {
         await runOneCheck();
+        // A stop can land while the tick above is awaiting a `gh` call, which takes
+        // seconds. Without this the loop re-arms itself after shutdown was asked
+        // for, and `startPrWatcher`'s `if (timer) return` then sees a live timer.
+        if (stopped)
+            return;
         scheduleNext();
     }, POLL_INTERVAL_MS);
     timer.unref?.();
@@ -368,6 +392,7 @@ function scheduleNext() {
 export function startPrWatcher() {
     if (timer)
         return;
+    stopped = false;
     // Kick off an immediate check so the front-end has fresh PR data on boot
     // without waiting for the first 30s tick. Fire-and-forget; the recurring
     // loop is scheduled independently and the `checking` guard prevents overlap.
@@ -376,6 +401,7 @@ export function startPrWatcher() {
 }
 /** Stop the PR watcher polling loop. */
 export function stopPrWatcher() {
+    stopped = true;
     if (timer) {
         clearTimeout(timer);
         timer = null;

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

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { WORKTREES_PATH } from '../../shared/consts.js';
+import { MASK_CHARACTER, MASKED_SECRET, SECRET_GLOBAL_KEYS, WORKTREES_PATH } from '../../shared/consts.js';
 import { isValidProjectColor } from '../../shared/project-colors.js';
 import { isValidSkillSuite } from '../../shared/skill-suite-prompts.js';
 import { DEFAULT_WHIP_SHORTCUT, isValidWhipShortcut } from '../../shared/whip-shortcut.js';
@@ -853,6 +853,36 @@ const settingsMigrations = [
             }
         },
     },
+    {
+        version: 55,
+        name: 'add-lifecycle-hook-scripts',
+        migrate: ({ global, projects }) => {
+            // Seeded empty everywhere: a hook runs arbitrary shell on the user's
+            // machine, so it only ever exists because the user wrote it.
+            for (const key of ['sessionEndedScript', 'prMergedScript', 'autoLoopDisabledScript']) {
+                if (typeof global[key] !== 'string')
+                    global[key] = '';
+                for (const p of projects) {
+                    if (typeof p[key] !== 'string')
+                        p[key] = '';
+                }
+            }
+        },
+    },
+    {
+        version: 56,
+        name: 'add-awaiting-user-reminder',
+        migrate: ({ global }) => {
+            // Seeded off. Same reasoning as the retention window: a feature that
+            // spends the user's attention without being asked is not a default.
+            if (typeof global.awaitingUserReminderMinutes !== 'number' ||
+                !Number.isInteger(global.awaitingUserReminderMinutes) ||
+                global.awaitingUserReminderMinutes < 0 ||
+                global.awaitingUserReminderMinutes > 1440) {
+                global.awaitingUserReminderMinutes = 0;
+            }
+        },
+    },
 ];
 /** Current settings schema version — always equals the highest migration version. */
 export const SETTINGS_SCHEMA_VERSION = settingsMigrations.length > 0 ? settingsMigrations[settingsMigrations.length - 1].version : 0;
@@ -875,6 +905,8 @@ function ensureSettingsPathInitialized() {
 /** Override the settings file path (used by tests). */
 export function _setSettingsPath(p) {
     settingsFilePath = p;
+    // Pointing at a different file must not serve the previous one's contents.
+    invalidateSettingsCache();
 }
 function defaultSettings() {
     return {
@@ -895,11 +927,16 @@ function defaultSettings() {
             cleanupScriptOnlyOnChanges: false,
             archiveScript: '',
             changeSourceBranchScript: DEFAULT_CHANGE_SOURCE_BRANCH_SCRIPT,
+            sessionEndedScript: '',
+            prMergedScript: '',
+            autoLoopDisabledScript: '',
             editorCommand: '',
             fileManagerCommand: '',
             terminalCommand: '',
             autoPurgeOnPrMerged: false,
             autoLoopMaxRetries: 5,
+            awaitingUserReminderMinutes: 0,
+            maxConcurrentAgents: 0,
             wsEventsRetentionDays: 0,
             wsEventsKeepPerWorkspace: 0,
             networkAccessEnabled: false,
@@ -998,6 +1035,9 @@ function defaultProjectSettings(projectPath) {
         cleanupScriptMode: '',
         archiveScript: '',
         changeSourceBranchScript: '',
+        sessionEndedScript: '',
+        prMergedScript: '',
+        autoLoopDisabledScript: '',
         devServer: {
             startCommand: '',
             stopCommand: '',
@@ -1043,7 +1083,47 @@ export function runSettingsMigrations(raw) {
     current.schemaVersion = version;
     return current;
 }
+/**
+ * Parsed settings, kept between calls. `getGlobalSettings` runs on every HTTP
+ * request through the auth middleware and 50-odd other call sites, while
+ * `readSettings` below does existsSync + readFileSync + JSON.parse + the whole
+ * migration chain — all synchronous, on the event loop that also drives the
+ * WebSocket streams.
+ *
+ * The file stays hand-editable (CONFIGURATION.md says so), so the cache is
+ * keyed on the file's mtime and size rather than held blindly: an external edit
+ * is picked up on the very next call, and the check costs one stat instead of a
+ * full parse and migration pass.
+ */
+let settingsCache = null;
+/** Drop the cached settings, so the next read goes back to disk. */
+function invalidateSettingsCache() {
+    settingsCache = null;
+}
+/** Identity of the settings file on disk, or null when it is unreadable. */
+function settingsFileStamp() {
+    try {
+        const stat = fs.statSync(settingsFilePath);
+        return { mtimeMs: stat.mtimeMs, size: stat.size };
+    }
+    catch {
+        return null;
+    }
+}
 function readSettings() {
+    ensureSettingsPathInitialized();
+    const stamp = settingsFileStamp();
+    if (stamp && settingsCache && settingsCache.mtimeMs === stamp.mtimeMs && settingsCache.size === stamp.size) {
+        return settingsCache.value;
+    }
+    const settings = readSettingsFromDisk();
+    // Re-stat: readSettingsFromDisk writes the file when it was missing or
+    // corrupt, so the stamp taken above would be stale.
+    const after = settingsFileStamp();
+    settingsCache = after ? { value: settings, ...after } : null;
+    return settings;
+}
+function readSettingsFromDisk() {
     ensureSettingsPathInitialized();
     if (!fs.existsSync(settingsFilePath)) {
         const defaults = defaultSettings();
@@ -1124,6 +1204,8 @@ function createSettingsBackupIfPresent() {
     pruneSettingsBackups(dir);
 }
 function writeSettings(settings, options) {
+    // Our own writes must be visible at once, whatever the TTL says.
+    invalidateSettingsCache();
     ensureSettingsPathInitialized();
     const tmpPath = `${settingsFilePath}.tmp`;
     const dir = path.dirname(settingsFilePath);
@@ -1140,8 +1222,29 @@ function writeSettings(settings, options) {
 export function getSettings() {
     return readSettings();
 }
-/** Keys stripped from exports — secrets that should stay on the machine. */
-const SECRET_GLOBAL_KEYS = ['notionMcpKey', 'sentryMcpKey', 'networkAccessToken', 'bitbucketToken'];
+/** True for a value made of nothing but mask characters (never a real token). */
+function isMaskOnly(value) {
+    return typeof value === 'string' && value.length > 0 && [...value].every((c) => c === MASK_CHARACTER);
+}
+/**
+ * Copy of the global settings safe to hand to a client: every stored credential
+ * becomes `MASKED_SECRET`, an unset one stays empty so the UI can tell "not
+ * configured" from "configured, hidden". The caller's object is left alone.
+ *
+ * The credentials are of no use to the settings screen — it only ever shows
+ * them in a password field — but they are very useful to anything else that
+ * gets to read a response: a paired device on the LAN, a proxy log, a
+ * screenshot. `updateGlobalSettings` reads the mask back as "keep the stored
+ * value", so a round-trip through the form is lossless.
+ */
+export function redactGlobalSecrets(global) {
+    const redacted = { ...global };
+    for (const key of SECRET_GLOBAL_KEYS) {
+        if (redacted[key])
+            redacted[key] = MASKED_SECRET;
+    }
+    return redacted;
+}
 /** Build an export bundle with settings + templates. MCP keys are stripped. */
 export function exportConfigBundle(templates) {
     const settings = readSettings();
@@ -1235,6 +1338,9 @@ export function getEffectiveSettings(projectPath) {
             cleanupScriptOnlyOnChanges: settings.global.cleanupScriptOnlyOnChanges,
             archiveScript: settings.global.archiveScript,
             changeSourceBranchScript: settings.global.changeSourceBranchScript,
+            sessionEndedScript: settings.global.sessionEndedScript,
+            prMergedScript: settings.global.prMergedScript,
+            autoLoopDisabledScript: settings.global.autoLoopDisabledScript,
             notionStatusProperty: settings.global.notionStatusProperty,
             notionInProgressStatus: settings.global.notionInProgressStatus,
         };
@@ -1262,13 +1368,32 @@ export function getEffectiveSettings(projectPath) {
         cleanupScriptOnlyOnChanges: settings.global.cleanupScriptOnlyOnChanges,
         archiveScript: project.archiveScript || settings.global.archiveScript,
         changeSourceBranchScript: project.changeSourceBranchScript || settings.global.changeSourceBranchScript,
+        sessionEndedScript: project.sessionEndedScript || settings.global.sessionEndedScript,
+        prMergedScript: project.prMergedScript || settings.global.prMergedScript,
+        autoLoopDisabledScript: project.autoLoopDisabledScript || settings.global.autoLoopDisabledScript,
         notionStatusProperty: settings.global.notionStatusProperty,
         notionInProgressStatus: settings.global.notionInProgressStatus,
     };
 }
 /** Merge partial updates into global settings and persist. */
-export function updateGlobalSettings(data) {
+export function updateGlobalSettings(input) {
     const settings = readSettings();
+    // Work on a copy: the validation below drops keys, and mutating the caller's
+    // object would be a surprise (the route hands us its parsed request body).
+    const data = { ...input };
+    // A client only ever sees the mask in place of a stored credential, so it
+    // hands the mask back on every save. Dropping the key preserves the stored
+    // value (same "drop it and keep the previous one" pattern as below), while a
+    // real value still overwrites and an empty one still clears.
+    //
+    // Any run of mask characters counts, not just the exact sentinel: a stray
+    // Backspace in the field leaves a shorter run, and writing that as the new
+    // credential would break the integration silently, long after the fact. No
+    // real token is made of nothing but bullets.
+    for (const key of SECRET_GLOBAL_KEYS) {
+        if (isMaskOnly(data[key]))
+            delete data[key];
+    }
     // Validate skillSuite before merging: drop invalid values so the previous
     // value is preserved (same pattern as `upsertProject`'s color validation).
     if ('skillSuite' in data) {
@@ -1293,6 +1418,16 @@ export function updateGlobalSettings(data) {
             delete data.autoLoopMaxRetries;
         }
     }
+    // 0 is a legitimate value here — it means "never remind me" — so the floor is
+    // 0, not 1. The ceiling of a day keeps a typo from arming a reminder that
+    // never fires and looks like a broken feature.
+    if ('awaitingUserReminderMinutes' in data) {
+        const value = data.awaitingUserReminderMinutes;
+        if (typeof value !== 'number' || !Number.isInteger(value) || value < 0 || value > 1440) {
+            console.warn(`[settings] Invalid awaitingUserReminderMinutes value rejected: ${value}`);
+            delete data.awaitingUserReminderMinutes;
+        }
+    }
     // Same shape as the autoLoopMaxRetries guard above: an invalid value is
     // dropped so the stored one survives. Retention deletes history — a bad write
     // here would delete more than the user ever asked for. `0` is NOT invalid:
@@ -1323,11 +1458,16 @@ export function updateGlobalSettings(data) {
         'cleanupScriptOnlyOnChanges',
         'archiveScript',
         'changeSourceBranchScript',
+        'sessionEndedScript',
+        'prMergedScript',
+        'autoLoopDisabledScript',
         'editorCommand',
         'fileManagerCommand',
         'terminalCommand',
         'autoPurgeOnPrMerged',
         'autoLoopMaxRetries',
+        'awaitingUserReminderMinutes',
+        'maxConcurrentAgents',
         'wsEventsRetentionDays',
         'wsEventsKeepPerWorkspace',
         'browserNotifications',
@@ -1532,6 +1672,9 @@ export function upsertProject(projectPath, data) {
         'cleanupScriptMode',
         'archiveScript',
         'changeSourceBranchScript',
+        'sessionEndedScript',
+        'prMergedScript',
+        'autoLoopDisabledScript',
         'devServer',
         'e2e',
         'finalization',