@loicngr/kobo 2.1.22 → 2.1.23

package/AGENTS.md

@@ -279,6 +279,26 @@ Two emit flavors in `websocket-service.ts`:
 
 ## External integrations
 
+### Graceful shutdown and development services
+
+`stopDevServersOnShutdown` is a global boolean, default `true` (JSON settings
+migration v66). Shutdown first rejects new dev-server starts and stops tracked
+local processes/agents. Disabling the setting skips configured dev stop commands
+and Compose teardown, preserving independent Docker services; manual Stop and
+workspace deletion/purge remain unchanged. Status recovery uses the existing
+instance-file and exact Compose-label inspection, never a duplicate startup.
+
+`shutdownScript` follows the global/project script cascade: empty inherits,
+whitespace disables. The `kobo-shutdown` lifecycle hook runs once per persisted
+workspace with an existing, non-purged worktree (including archived workspaces),
+after local writers stop and before optional Docker teardown. Skip unconfirmed
+agent stops. Each hook has a 1-minute timeout, and the outer shutdown deadline
+is 150 seconds (supervisors need at least 180 seconds). Inject `PROJECT_NAME` from
+the workspace instance config, empty if unavailable, and `INSTANCE`; never guess
+a Compose project. User hooks may explicitly remove Docker resources even when
+automatic shutdown is disabled. Preserve hook outputs and keep SQLite open until
+hooks settle. Do not run scripts on abrupt exits or claim they survive SIGKILL.
+
 ### VPS deployment tooling
 
 `docker-compose.vps.yml` is the standalone fresh-instance example for an existing
@@ -381,6 +401,33 @@ expand tool permissions. Initial writable auto-loop launches seed tasks and end;
 manual launches implement under the workflow policy. Preserve custom templates
 and frozen migration text when changing generated guidance.
 
+Prefer dedicated managed MCP operations and require checking their results.
+Writable launches synchronize task progress and blockers during work using only
+supported statuses; restricted launches must not receive task mutation guidance.
+Delegation passes the objective, worktree path, constraints, permissions, test
+runtime and applicable MCP/reporting rules explicitly. Keep final reporting
+evidence-based and phase-aware: distinguish actual checks, delegated results,
+blocked/unverified work and jobs still running. Reuse the shared progress lifecycle
+instead of duplicating it or finishing ongoing work at the end of a turn.
+
+Dev-server lifecycle guidance must cover backend/integration dependencies as well
+as frontend/E2E checks. Agents and delegates inspect/reuse the managed instance,
+start/stop only through its MCP tools under writable launch permissions, and
+report unavailable tools/configuration or startup failures instead of bypassing
+Kōbō with direct shell startup commands. Keep tool descriptions in sync.
+Distinguish the agent runtime from project containers, running status from
+application readiness, and interrupted reporting from terminated work. Keep
+readiness probes bounded and do not suggest bypassing failed MCP authentication
+or replaying an ambiguous mutation without checking its outcome.
+
+Launch guidance explicitly directs agents to consult injected Kōbō
+memory before targeted retrieval, and to save confirmed reusable facts through
+`remember` only under the current mode/permissions. Preserve retrieval budgets,
+scope selection and Hybrid proposal semantics; native provider memory is not a
+replacement for this shared store.
+Keep detailed workflow guidance in the application launch instructions: the
+separate mode-specific memory bootstrap has a strict total retrieval budget.
+
 The engine's `onPromptPrepared` callback supplies only its textual Kōbō prefix and
 system append. Initial creation and pending initial retries opt into a single
 session-scoped `user:message` with `sender: system-prompt`, displayed as Kōbō

package/CHANGELOG.md

@@ -4,6 +4,10 @@ All notable changes to Kōbō are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/). Each release is an `## <version>`
 section — the in-app "What's new" dialog reads this file.
 
+## 2.1.23
+
+- feat: configure shutdown hooks and improve agent guidance
+
 ## 2.1.22
 
 - feat(settings): make agent watchdogs opt-in and progress bars configurable

package/CONFIGURATION.md

@@ -234,6 +234,8 @@ Projects override a subset of global settings. Anything you set here takes prece
 | `taskPromptTemplate` | `string` | Prompt used to prefill the mission description when this project is selected. Empty leaves the description without a project-provided prompt. |
 | `forge` | `'auto' \| 'github' \| 'gitlab' \| 'bitbucket-community' \| 'none'` | Which forge provides PR/MR features. `auto` detects from the git remote URL. See [Forge integration](#forge-integration). |
 | `devServer.startCommand` / `stopCommand` | `string` | Per-workspace dev server commands. Docker, npm, or any shell-startable process. See [Dev server](#dev-server) for the status/URL contract. |
+| `stopDevServersOnShutdown` | `boolean` | Global, default `true`. Disable to leave Docker services running when Kōbō exits or updates. Tracked local processes always stop. Explicit Stop and workspace teardown still stop services. |
+| `shutdownScript` | `string` | Optional global/per-project shutdown hook, run in each existing workspace worktree before automatic Docker teardown. Empty project value inherits; whitespace disables. See [Kōbō shutdown](#kōbō-shutdown). |
 | `e2e.framework` | `'cypress' \| 'playwright' \| 'jest' \| 'vitest' \| 'other' \| ''` | E2E framework auto-loop grooming should target. |
 | `e2e.skill` | `string` | Optional skill name injected into the E2E grooming prompt. |
 | `e2e.prompt` | `string` | Free-form prompt appended to every `[E2E] ` sub-task. |
@@ -1597,6 +1599,48 @@ logs contract does not provide general process health monitoring.
 **No instance file at all**: Start/Stop run your commands; the panel uses the
 saved status when available, otherwise `unknown`, with no URL or Docker logs.
 
+### Kōbō shutdown
+
+In **Settings → Scripts**, **Stop development servers when Kōbō exits** defaults
+to enabled. Disable it to preserve independently running Docker containers during
+an update/restart. Kōbō still terminates its tracked local processes, including
+startup commands. Use detached Docker services (`docker compose up -d`); a
+foreground Compose process or a custom signal trap can itself stop containers.
+After restart, the existing instance-file/Compose-label contract lets the panel
+inspect those containers and recover their URL and logs without starting them.
+The setting does not change manual Stop, workspace deletion/purge, or user hooks.
+
+The optional **Hook: Kōbō shutdown** uses the global script by default. A project
+script replaces it; an empty project field inherits and whitespace disables it.
+It runs **once per workspace, in that workspace's worktree**, including archived
+workspaces with an existing checkout. Purged/missing worktrees and workspaces
+whose agent stop is unconfirmed are skipped. Scripts run after tracked agent/local
+process shutdown and before automatic Docker teardown, even when automatic Docker
+shutdown is disabled. Each script has a **1-minute timeout**; failures are logged
+and do not cancel shutdown. Output is recorded under `hook:kobo-shutdown`.
+
+Available variables include `WORKSPACE_ID`, `WORKSPACE_NAME`, `BRANCH_NAME`,
+`SOURCE_BRANCH`, `PROJECT_PATH`, `KOBO_HOOK_EVENT=kobo-shutdown`, and
+`KOBO_SHUTDOWN_SIGNAL` (`SIGTERM`, `SIGINT`, etc.). `INSTANCE` and `PROJECT_NAME`
+come from that workspace's dev-server instance configuration. `PROJECT_NAME` is
+empty when no matching Docker instance is known; never guess a shared stack name.
+
+For explicit destructive cleanup of the workspace's Compose resources:
+
+```bash
+docker compose -p "${PROJECT_NAME:?Missing Docker project}" down --remove-orphans --volumes --rmi local
+```
+
+This removes Compose-managed volumes and images without custom tags; external
+volumes and tagged images remain. It can stop containers **even with automatic
+Docker shutdown disabled**, because the hook is an explicit user command. Supply
+any `-f` or `--env-file` arguments your project's Compose setup requires.
+
+These hooks require a graceful Kōbō shutdown; they cannot run after `SIGKILL`,
+a host power loss or a crash that bypasses teardown. Kōbō's total shutdown deadline
+is 150 seconds. Allow at least 180 seconds in a container/process supervisor
+(`stop_grace_period: 180s` in the Compose examples).
+
 ### Example: the full convention end-to-end
 
 The reference implementation is the `sekur` project. Its Kōbō `startCommand` is effectively `make dev-docker`, where the `Makefile` calls `./sh/dev-docker.sh $(INSTANCE)` and `$(INSTANCE)` reads the `INSTANCE` env var Kōbō injects. The script:
@@ -2184,6 +2228,51 @@ Notion token environment overrides are applied consistently to both token variab
 
 New workspaces receive the mission, repository context, current permissions, current phase and expected result. Agents first consult the available managed MCP tool descriptions and schemas, then prefer relevant Kōbō tools for workspace operations. This is not a request to call every tool or poll. Long tasks and delegated work use labeled progress bars; dismissing a bar hides only that activity and does not cancel its work.
 
+For tasks, development services, shared memory, workspace messages and state,
+agents prefer the dedicated managed MCP tool and check its result. Writable
+launches keep existing tasks current during work: `in_progress` when starting,
+blockers promptly reported in the conversation with the affected task, and done
+only after required checks pass. Task requirements and evidence are preserved.
+Blocked tasks stay unfinished; no unsupported field or status is invented.
+Delegates receive the objective, exact worktree path, user constraints, launch
+permissions, test runtime and applicable MCP/reporting rules. When a delegate
+lacks the tools, its parent coordinates the operation under the same permissions.
+The final report identifies changes/findings, checks actually executed and their
+results, and remaining blockers or ongoing work. Delegated results are attributed;
+progress bars finish only for activities with a known outcome, and completing a
+phase or review does not imply the whole mission is done.
+
+Agents explicitly use Kōbō internal memory for shared knowledge across sessions,
+workspaces and engines. At task start/resume, they consult injected facts before
+targeted retrieval of missing decisions, conventions and known pitfalls. When
+permitted, they save confirmed reusable facts through `remember` in the narrowest
+scope, updating existing entries rather than duplicating them. Native provider
+memory does not replace this shared store. Retrieval budgets, Manual/read-only
+restrictions and Hybrid approval requirements still apply; secrets, raw logs and
+routine progress are not memory entries.
+
+Development services have an explicit managed lifecycle rule: before backend,
+frontend, integration or E2E checks that need workspace services, inspect
+`get_dev_server_status` and reuse the existing instance. Authorized writable
+launches start/stop it through the Kōbō MCP tools, never by invoking the startup
+script, `make dev-docker` or Docker Compose directly. Diagnose failures with
+`get_dev_server_logs`; unavailable tools or configuration are reported as blockers.
+Delegates follow the same rule. Read-only launches cannot start/stop services;
+test execution inside an existing container still follows current permissions.
+
+Agents choose test commands and runtimes from the project Makefile, scripts and
+documentation. Missing dependencies in the agent environment do not establish a
+project configuration defect when tests belong in a service container. A running
+dev server is not proof of application readiness: dependent checks require a
+documented health check or non-mutating URL probe with a timeout and bounded
+retries. Independent unit tests need not wait for application readiness.
+
+After interruption/resume, agents verify relevant task/Git state and ongoing
+jobs, tests and containers before repeating work. MCP failures must be reported
+as failures, with safe diagnostics; authentication/permission errors never justify
+modifying credentials or Kōbō storage to bypass the tools. Ambiguous mutation
+outcomes require checking available status/receipts before retrying.
+
 Plan launches remain conversation-only. Writable auto-loop launches prepare the plan and task list before returning control to the loop; writable manual launches implement after plan approval, under the configured Git policy. Custom brainstorming, Notion and Sentry templates are preserved; they cannot expand launch permissions or authorize commits automatically. Review returns and handoff reports remain read-only, with only their scoped report and operational progress tools allowed. Plan approval does not change permissions; explicitly select an execution mode in Kōbō and start a new launch to implement.
 
 The expandable **Kōbō instructions** chat entry records the application-owned text prepared by the engine builder for the initial launch or a pending initial-prompt retry, including progress guidance, continuation rules, workflow policy and managed integration notices. The pending initial mission is retained until this entry is durably recorded, so a failure during asynchronous launch preparation remains retryable. A later replacement mission is never cleared by an earlier launch. Preparation is not proof of provider delivery. The provider's own system preset is not included. Retrieved memory bodies and capability tokens are not copied to chat; memory usage remains visible separately in the Memory panel. Existing historical prompt entries retain their original content. Ordinary resumes receive current instructions without creating another initial-prompt entry.

package/dist/mcp-server/kobo-tasks-server.js

@@ -408,25 +408,25 @@ const WORKSPACE_SCOPED_TOOLS = [
     },
     {
         name: 'get_dev_server_status',
-        description: 'CALL BEFORE asking the user whether the app is running, or when your change is dev-server-sensitive. Returns `not_configured` when this project has no dev server: do not start one manually in that case. Otherwise returns running/stopped/starting/error + URL, port, container names.',
+        description: 'CALL BEFORE backend, frontend, integration or E2E tests that need workspace services, or before asking the user whether the app is running. Reuse the existing instance and its returned URL/container names. Returns `not_configured` when this project has no dev server: report the blocker, do not launch one manually. Otherwise returns running/stopped/starting/error + URL, port, container names. Running is lifecycle status, not application readiness: use the documented health check with bounded retries before dependent tests.',
         inputSchema: { type: 'object', properties: {}, required: [] },
         annotations: { readOnlyHint: true, openWorldHint: false },
     },
     {
         name: 'start_dev_server',
-        description: 'CALL WHEN the user asks you to test the running app and the dev server is stopped.',
+        description: 'CALL WHEN an authorized task needs workspace services for app checks or backend/frontend/integration/E2E tests and get_dev_server_status reports stopped. Kōbō runs the configured startup command and tracks the instance. Use this tool instead of shell lifecycle commands such as make dev-docker, sh/dev-docker.sh, docker compose up or npm run dev. Respect launch permissions; read-only sessions cannot start services. On failure, inspect get_dev_server_logs and report the blocker, without a manual shell fallback.',
         inputSchema: { type: 'object', properties: {}, required: [] },
         annotations: { destructiveHint: false, openWorldHint: false },
     },
     {
         name: 'stop_dev_server',
-        description: 'CALL WHEN the user explicitly asks to stop the dev server, or before destructive operations that require a clean boot.',
+        description: 'CALL WHEN the user explicitly asks to stop the dev server, or when an authorized operation requires a restart. Use this tool instead of shell shutdown commands such as docker compose down or killing the server process directly. Respect launch permissions; read-only sessions cannot stop services. Do not stop a shared workspace instance merely because your tests finished.',
         inputSchema: { type: 'object', properties: {}, required: [] },
         annotations: { destructiveHint: false, openWorldHint: false },
     },
     {
         name: 'get_dev_server_logs',
-        description: 'CALL WHEN debugging a runtime issue the user describes as happening in the running app. Returns the last N lines of logs (default 200). Cheaper than asking the user to paste them.',
+        description: 'CALL WHEN diagnosing a dev-server startup failure or a runtime issue during app checks or tests. Returns the last N lines of logs (default 200). Use these logs with get_dev_server_status before reporting a blocker; do not bypass a failed managed startup with a shell launch.',
         inputSchema: {
             type: 'object',
             properties: {

package/dist/server/index.js

@@ -37,13 +37,14 @@ import voiceRouter from './routes/voice.js';
 import workspaceMessagesRouter from './routes/workspace-messages.js';
 import workspaceTemplatesRouter from './routes/workspace-templates.js';
 import workspacesRouter from './routes/workspaces.js';
-import { getAvailableSkills, reconcileOrphanSessions, restoreRetryCountsFromDb, resumePendingReviewReturns, setBackendPort, startAgent, startWatchdog, stopAgentAndWait, stopAllAgents, stopWatchdog, } from './services/agent/orchestrator.js';
+import { getActiveSessionId, getAvailableSkills, reconcileOrphanSessions, restoreRetryCountsFromDb, resumePendingReviewReturns, setBackendPort, startAgent, startWatchdog, stopAgentAndWait, stopAllAgents, stopWatchdog, } from './services/agent/orchestrator.js';
 import * as autoLoopService from './services/auto-loop-service.js';
 import { startAwaitingUserReminder, stopAwaitingUserReminder } from './services/awaiting-user-reminder-service.js';
 import { runContentMigrationIfNeeded } from './services/content-migration-service.js';
 import * as cronService from './services/cron-service.js';
 import { createDailyDbBackupIfNeeded, createPreMigrationBackup, startDailyDbBackupScheduler, } from './services/db-backup-service.js';
-import { startDevServer, stopAllDevServers, stopDevServer } from './services/dev-server-service.js';
+import { beginDevServerShutdown, startDevServer, stopAllDevServers, stopDevServer, } from './services/dev-server-service.js';
+import { onKoboShutdown } from './services/lifecycle-hook-service.js';
 import { reconcileMessageRequests } from './services/mcp-message-request-service.js';
 import { reconcileMemoryContextsOnStartup } from './services/memory-context-service.js';
 import { authorizeWsUpgrade, generateToken, getLanHostnames, getLanUrls, isAllowedOrigin, isAllowedRequestHost, resolveBindHost, resolveDevClientOrigin, resolveNetworkAccessEnvOverrides, resolveProxyHostname, } from './services/network-access-service.js';
@@ -422,13 +423,15 @@ async function gracefulShutdown(signal, exitCode = 0) {
     if (isShuttingDown)
         return;
     isShuttingDown = true;
+    beginDevServerShutdown();
+    const stopDevServersOnShutdown = getGlobalSettings().stopDevServersOnShutdown !== false;
     stopUpdateChecker();
     const groupMessagesStopped = stopGroupMessageBatches();
     console.log(`\n[kobo] Received ${signal}, shutting down gracefully…`);
     const forceExitTimer = setTimeout(() => {
         console.error('[kobo] Graceful shutdown timed out; forcing exit');
         process.exit(1);
-    }, 5_000);
+    }, 150_000);
     forceExitTimer.unref();
     // Ask WebSocket clients to leave so their upgraded HTTP connections do not
     // keep server.close() waiting indefinitely.
@@ -469,14 +472,26 @@ async function gracefulShutdown(signal, exitCode = 0) {
         // Best-effort
     }
     clearInterval(retentionTimer);
-    // Stop managed agents and both direct/Docker dev servers before closing DB.
+    // Stop local writers before user hooks, leaving Docker available to those hooks.
     try {
-        await Promise.all([stopAllAgents(), stopAllDevServers()]);
-        console.log('[kobo] Agents and dev servers stopped');
+        await Promise.all([stopAllAgents(), stopAllDevServers({ preserveDocker: true })]);
+        await onKoboShutdown(signal, (workspaceId) => getActiveSessionId(workspaceId) !== undefined);
     }
     catch {
         // Best-effort
     }
+    try {
+        if (stopDevServersOnShutdown) {
+            await stopAllDevServers();
+            console.log('[kobo] Dev servers stopped');
+        }
+        else {
+            console.log('[kobo] Local dev processes stopped; Docker services left to the configured shutdown hooks');
+        }
+    }
+    catch (err) {
+        console.error('[kobo] Dev-server shutdown failed:', err);
+    }
     // Stop accepting new HTTP/WS work, then let in-flight handlers finish before
     // closing SQLite. Closing the DB earlier makes those handlers fail midway.
     try {

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

@@ -486,6 +486,7 @@ function readEffectiveSettingsSafe(projectPath) {
             archiveScript: '',
             changeSourceBranchScript: '',
             sessionEndedScript: '',
+            shutdownScript: '',
             prMergedScript: '',
             autoLoopDisabledScript: '',
             notionStatusProperty: '',

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

@@ -26,11 +26,16 @@ function runCommand(command, args, options = {}) {
 const trackedProcesses = new Map();
 const stoppingProcesses = new Map();
 const generations = new Map();
+let shuttingDown = false;
+export function beginDevServerShutdown() {
+    shuttingDown = true;
+}
 /** Test-only: clear the tracked-processes map between tests. */
 export function _resetTrackedProcessesForTests() {
     trackedProcesses.clear();
     stoppingProcesses.clear();
     generations.clear();
+    shuttingDown = false;
 }
 // ── Pure helpers ───────────────────────────────────────────────────────────────
 /**
@@ -177,6 +182,8 @@ export async function getStatus(projectPath, workingBranch, workspaceId) {
  * Start the dev-server for a workspace.
  */
 export function startDevServer(workspaceId) {
+    if (shuttingDown)
+        throw new Error('Kōbō is shutting down');
     assertWorkspaceLifecycleAvailable(workspaceId);
     const workspace = getWorkspace(workspaceId);
     if (!workspace) {
@@ -231,7 +238,7 @@ export function startDevServer(workspaceId) {
                     return;
                 trackedProcesses.delete(workspaceId);
                 const currentStatus = await getStatus(workspace.projectPath, workspace.workingBranch);
-                if (generations.get(workspaceId) !== generation || stoppingProcesses.has(workspaceId))
+                if (shuttingDown || generations.get(workspaceId) !== generation || stoppingProcesses.has(workspaceId))
                     return;
                 updateDevServerStatus(workspaceId, currentStatus.status);
                 emitEphemeral(workspaceId, 'devserver:status', currentStatus);
@@ -244,7 +251,7 @@ export function startDevServer(workspaceId) {
             console.error(`[dev-server] Process exited with code ${code} for workspace ${workspaceId}`);
     });
     proc.on('error', (err) => {
-        if (trackedProcesses.get(workspaceId) !== proc)
+        if (shuttingDown || trackedProcesses.get(workspaceId) !== proc || generations.get(workspaceId) !== generation)
             return;
         // A signal failure is also an 'error' event; it does not prove process exit.
         if (!proc.pid)
@@ -373,6 +380,16 @@ function signalAndWait(proc, signal, timeoutMs) {
         }
     });
 }
+async function stopTrackedProcess(workspaceId) {
+    const tracked = trackedProcesses.get(workspaceId);
+    if (!tracked)
+        return;
+    const exited = (await signalAndWait(tracked, 'SIGTERM', 3_000)) || (await signalAndWait(tracked, 'SIGKILL', 1_000));
+    if (!exited)
+        throw new Error('Dev server stop is not confirmed; retry after the process exits');
+    if (trackedProcesses.get(workspaceId) === tracked)
+        trackedProcesses.delete(workspaceId);
+}
 async function stopDevServerOwned(workspaceId) {
     const workspace = getWorkspace(workspaceId);
     if (!workspace) {
@@ -383,14 +400,7 @@ async function stopDevServerOwned(workspaceId) {
     const worktreePath = workspace.worktreePath;
     const cwd = worktreePath && existsSync(worktreePath) ? worktreePath : workspace.projectPath;
     // Kill tracked process first (covers Node servers and any spawned process)
-    const tracked = trackedProcesses.get(workspaceId);
-    if (tracked) {
-        const exited = (await signalAndWait(tracked, 'SIGTERM', 3_000)) || (await signalAndWait(tracked, 'SIGKILL', 1_000));
-        if (!exited)
-            throw new Error('Dev server stop is not confirmed; retry after the process exits');
-        if (trackedProcesses.get(workspaceId) === tracked)
-            trackedProcesses.delete(workspaceId);
-    }
+    await stopTrackedProcess(workspaceId);
     const settings = getProjectSettings(workspace.projectPath);
     let stopError;
     let customStopSucceeded = false;
@@ -448,12 +458,30 @@ async function stopDevServerOwned(workspaceId) {
     emitEphemeral(workspaceId, 'devserver:status', status);
     return status;
 }
-/** Stop direct and Docker dev servers for every persisted workspace. */
-export async function stopAllDevServers() {
+/** Shut down local processes; optionally leave independently running Docker services alone. */
+export async function stopAllDevServers(options = {}) {
+    beginDevServerShutdown();
     const workspaceIds = new Set([...listWorkspaces(true).map((workspace) => workspace.id), ...trackedProcesses.keys()]);
     await Promise.all([...workspaceIds].map(async (workspaceId) => {
         try {
-            await stopDevServer(workspaceId);
+            if (!options.preserveDocker) {
+                await stopDevServer(workspaceId);
+            }
+            else {
+                // A stop already requested by the user must still finish.
+                const stopping = stoppingProcesses.get(workspaceId);
+                if (stopping) {
+                    await stopping;
+                    return;
+                }
+                const hadProcess = trackedProcesses.has(workspaceId);
+                await stopTrackedProcess(workspaceId);
+                const workspace = getWorkspace(workspaceId);
+                // Preserve Docker state; getStatus re-inspects Compose after restart.
+                if (hadProcess && workspace && !resolveInstance(workspace.projectPath, workspace.workingBranch)) {
+                    updateDevServerStatus(workspaceId, 'stopped');
+                }
+            }
         }
         catch (err) {
             console.error(`[dev-server] Failed to stop '${workspaceId}' during shutdown:`, err);

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

@@ -3,12 +3,16 @@ 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 { resolveInstance, sanitizeBranchName } from './dev-server-service.js';
 import { getEffectiveSettings, getGlobalSettings, getProjectSettings } from './settings-service.js';
+import { listWorkspaces } from './workspace-service.js';
+export const SHUTDOWN_SCRIPT_TIMEOUT_MS = 60_000;
 /** Which effective-settings key holds the script for each event. */
 const SCRIPT_KEY = {
     'session-ended': 'sessionEndedScript',
     'pr-merged': 'prMergedScript',
     'autoloop-disabled': 'autoLoopDisabledScript',
+    'kobo-shutdown': 'shutdownScript',
 };
 function getRow(workspaceId) {
     const row = getDb()
@@ -33,7 +37,7 @@ export async function runLifecycleHook(event, workspaceId, extraEnv) {
         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())
+        if (!script?.trim())
             return null;
         const global = getGlobalSettings();
         const projectSettings = getProjectSettings(row.project_path);
@@ -51,19 +55,27 @@ export async function runLifecycleHook(event, workspaceId, extraEnv) {
             }
             return null;
         }
+        const instance = event === 'kobo-shutdown' ? resolveInstance(row.project_path, row.working_branch) : null;
         return await runScript({
             workspaceId,
             worktreePath,
             script,
-            // Namespaced per event: three hooks streaming into one `hook:output` feed
+            // Namespaced per event: multiple hooks streaming into one `hook:output` feed
             // would be indistinguishable in the UI.
             eventPrefix: `hook:${event}`,
             tmpFileName: `.hook-${event}.tmp`,
+            ...(event === 'kobo-shutdown' ? { timeoutMs: SHUTDOWN_SCRIPT_TIMEOUT_MS } : {}),
             env: {
                 workspaceName: row.name,
                 branchName: row.working_branch,
                 sourceBranch: row.source_branch,
                 projectPath: row.project_path,
+                ...(event === 'kobo-shutdown'
+                    ? {
+                        projectName: instance?.projectName ?? '',
+                        instanceName: instance?.instanceName ?? sanitizeBranchName(row.working_branch),
+                    }
+                    : {}),
             },
             extraEnv: { ...extraEnv, KOBO_HOOK_EVENT: event },
         });
@@ -73,6 +85,21 @@ export async function runLifecycleHook(event, workspaceId, extraEnv) {
         return null;
     }
 }
+/** Called once by graceful shutdown, after stopping writers and before Docker teardown. */
+export async function onKoboShutdown(signal, isAgentStillRunning) {
+    await Promise.all(listWorkspaces(true)
+        .filter((workspace) => !workspace.worktreePurgedAt)
+        .map(async (workspace) => {
+        if (isAgentStillRunning(workspace.id)) {
+            console.warn(`[lifecycle-hook] 'kobo-shutdown' skipped for '${workspace.id}': agent stop unconfirmed`);
+            return;
+        }
+        const result = await runLifecycleHook('kobo-shutdown', workspace.id, { KOBO_SHUTDOWN_SIGNAL: signal });
+        if (result && result.exitCode !== 0) {
+            console.error(`[lifecycle-hook] 'kobo-shutdown' failed for '${workspace.id}' with code ${result.exitCode}`);
+        }
+    }));
+}
 /**
  * An agent session ended. Fires for every real end — clean finish, error, user
  * stop, watchdog kill — and lets the script tell them apart via

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

@@ -996,6 +996,20 @@ const settingsMigrations = [
                 global.showProgressBars = true;
         },
     },
+    {
+        version: 66,
+        name: 'shutdown-services-and-hooks',
+        migrate: ({ global, projects }) => {
+            if (typeof global.stopDevServersOnShutdown !== 'boolean')
+                global.stopDevServersOnShutdown = true;
+            if (typeof global.shutdownScript !== 'string')
+                global.shutdownScript = '';
+            for (const project of projects) {
+                if (typeof project.shutdownScript !== 'string')
+                    project.shutdownScript = '';
+            }
+        },
+    },
 ];
 /** Current settings schema version — always equals the highest migration version. */
 export const SETTINGS_SCHEMA_VERSION = settingsMigrations.length > 0 ? settingsMigrations[settingsMigrations.length - 1].version : 0;
@@ -1044,6 +1058,7 @@ function defaultSettings() {
             archiveScript: '',
             changeSourceBranchScript: DEFAULT_CHANGE_SOURCE_BRANCH_SCRIPT,
             sessionEndedScript: '',
+            shutdownScript: '',
             prMergedScript: '',
             autoLoopDisabledScript: '',
             editorCommand: '',
@@ -1053,6 +1068,7 @@ function defaultSettings() {
             autoLoopMaxRetries: 5,
             agentWatchdogEnabled: false,
             showProgressBars: true,
+            stopDevServersOnShutdown: true,
             awaitingUserReminderMinutes: 0,
             activityDigestEnabled: true,
             maxConcurrentAgents: 2,
@@ -1156,6 +1172,7 @@ function defaultProjectSettings(projectPath) {
         archiveScript: '',
         changeSourceBranchScript: '',
         sessionEndedScript: '',
+        shutdownScript: '',
         prMergedScript: '',
         autoLoopDisabledScript: '',
         devServer: {
@@ -1203,9 +1220,15 @@ export function runSettingsMigrations(raw) {
         current.global.memoryMode = 'hybrid';
     if (typeof current.global.showProgressBars !== 'boolean')
         current.global.showProgressBars = true;
+    if (typeof current.global.stopDevServersOnShutdown !== 'boolean')
+        current.global.stopDevServersOnShutdown = true;
+    if (typeof current.global.shutdownScript !== 'string')
+        current.global.shutdownScript = '';
     if (typeof current.global.agentWatchdogEnabled !== 'boolean')
         current.global.agentWatchdogEnabled = false;
     for (const project of current.projects) {
+        if (typeof project.shutdownScript !== 'string')
+            project.shutdownScript = '';
         if (!isWorkflowPolicy(project.workflowPolicy))
             project.workflowPolicy = {};
     }
@@ -1478,6 +1501,7 @@ export function getEffectiveSettings(projectPath) {
             archiveScript: settings.global.archiveScript,
             changeSourceBranchScript: settings.global.changeSourceBranchScript,
             sessionEndedScript: settings.global.sessionEndedScript,
+            shutdownScript: settings.global.shutdownScript,
             prMergedScript: settings.global.prMergedScript,
             autoLoopDisabledScript: settings.global.autoLoopDisabledScript,
             notionStatusProperty: settings.global.notionStatusProperty,
@@ -1508,6 +1532,7 @@ export function getEffectiveSettings(projectPath) {
         archiveScript: project.archiveScript || settings.global.archiveScript,
         changeSourceBranchScript: project.changeSourceBranchScript || settings.global.changeSourceBranchScript,
         sessionEndedScript: project.sessionEndedScript || settings.global.sessionEndedScript,
+        shutdownScript: project.shutdownScript || settings.global.shutdownScript,
         prMergedScript: project.prMergedScript || settings.global.prMergedScript,
         autoLoopDisabledScript: project.autoLoopDisabledScript || settings.global.autoLoopDisabledScript,
         notionStatusProperty: settings.global.notionStatusProperty,
@@ -1557,6 +1582,12 @@ export function updateGlobalSettings(input) {
             delete data.autoLoopMaxRetries;
         }
     }
+    if ('shutdownScript' in data && typeof data.shutdownScript !== 'string') {
+        delete data.shutdownScript;
+    }
+    if ('stopDevServersOnShutdown' in data && typeof data.stopDevServersOnShutdown !== 'boolean') {
+        delete data.stopDevServersOnShutdown;
+    }
     if ('showProgressBars' in data && typeof data.showProgressBars !== 'boolean') {
         delete data.showProgressBars;
     }
@@ -1619,6 +1650,7 @@ export function updateGlobalSettings(input) {
         'archiveScript',
         'changeSourceBranchScript',
         'sessionEndedScript',
+        'shutdownScript',
         'prMergedScript',
         'autoLoopDisabledScript',
         'editorCommand',
@@ -1628,6 +1660,7 @@ export function updateGlobalSettings(input) {
         'autoLoopMaxRetries',
         'agentWatchdogEnabled',
         'showProgressBars',
+        'stopDevServersOnShutdown',
         'awaitingUserReminderMinutes',
         'activityDigestEnabled',
         'maxConcurrentAgents',
@@ -1823,6 +1856,8 @@ export function upsertProject(projectPath, data) {
     }
     if ('workflowPolicy' in data && !isWorkflowPolicy(data.workflowPolicy))
         throw new Error('Invalid workflowPolicy');
+    if ('shutdownScript' in data && typeof data.shutdownScript !== 'string')
+        throw new Error('Invalid shutdownScript');
     const allowedProjectKeys = [
         'workflowPolicy',
         'displayName',
@@ -1842,6 +1877,7 @@ export function upsertProject(projectPath, data) {
         'archiveScript',
         'changeSourceBranchScript',
         'sessionEndedScript',
+        'shutdownScript',
         'prMergedScript',
         'autoLoopDisabledScript',
         'devServer',

package/dist/server/utils/script-runner.js

@@ -49,6 +49,8 @@ export function runScript(opts) {
                 BRANCH_NAME: env?.branchName ?? '',
                 SOURCE_BRANCH: env?.sourceBranch ?? '',
                 PROJECT_PATH: env?.projectPath ?? '',
+                ...(env?.projectName !== undefined ? { PROJECT_NAME: env.projectName } : {}),
+                ...(env?.instanceName !== undefined ? { INSTANCE: env.instanceName } : {}),
             },
             stdio: ['ignore', 'pipe', 'pipe'],
             // Detached so this is the leader of its own process group: a script
@@ -74,7 +76,7 @@ export function runScript(opts) {
             proc.stdout?.destroy();
             proc.stderr?.destroy();
             wsService.emit(workspaceId, `${eventPrefix}:output`, {
-                text: `[kobo] Script timed out after ${Math.round(timeoutMs / 60000)} minutes`,
+                text: `[kobo] Script timed out after ${timeoutMs < 60000 ? `${Math.round(timeoutMs / 1000)} seconds` : `${Math.round(timeoutMs / 60000)} minutes`}`,
             });
             // SIGKILL on the process group gives a running `git commit` no chance to
             // release its index lock. Name the file here, while the user is looking