@loicngr/kobo 1.7.13 → 1.7.15

package/dist/server/db/migrations.js

@@ -332,6 +332,39 @@ export function runMigrations(db) {
             db.prepare('INSERT INTO schema_migrations (version, name, applied_at) VALUES (?, ?, ?)').run(m.version, m.name, new Date().toISOString());
         }
     }
+    // Soft downgrade guard: if the database carries a migration version this
+    // build doesn't know about, it was migrated by a newer Kōbō. Forward-only
+    // migrations have no `down` step — warn loudly but let the app continue.
+    const maxVersion = db.prepare('SELECT MAX(version) AS v FROM schema_migrations').get().v ?? 0;
+    if (maxVersion > SCHEMA_VERSION) {
+        console.warn(`[kobo] ⚠ Database schema version (${maxVersion}) is higher than this Kōbō build supports ` +
+            `(${SCHEMA_VERSION}). The database was migrated by a newer version of Kōbō — running an older ` +
+            `build may cause errors. Update Kōbō, or restore a pre-downgrade backup from the Kōbō home directory.`);
+    }
+}
+/**
+ * Return the versions of registered migrations not yet applied to `db`, without
+ * applying them. Used to decide whether a pre-migration backup is warranted.
+ * Returns `[]` for a fresh / uninitialised database — there is no data at risk.
+ */
+export function getPendingMigrations(db) {
+    const tableExists = (name) => db.prepare("SELECT count(*) AS c FROM sqlite_master WHERE type='table' AND name=?").get(name).c > 0;
+    let applied;
+    if (tableExists('schema_migrations')) {
+        applied = new Set(db.prepare('SELECT version FROM schema_migrations').all().map((r) => r.version));
+    }
+    else if (tableExists('schema_version')) {
+        // Legacy single-row table: every version up to the stored one is applied.
+        const legacy = db.prepare('SELECT version FROM schema_version LIMIT 1').get()?.version ?? 0;
+        applied = new Set();
+        for (let v = 1; v <= legacy; v++)
+            applied.add(v);
+    }
+    else {
+        // Fresh / uninitialised DB — initSchema bootstraps it, nothing to back up.
+        return [];
+    }
+    return migrations.filter((m) => !applied.has(m.version)).map((m) => m.version);
 }
 /** Return the full migration history (for diagnostics / admin UI). */
 export function getMigrationHistory(db) {

package/dist/server/index.js

@@ -5,10 +5,13 @@ import { serve } from '@hono/node-server';
 import { Hono } from 'hono';
 import WebSocket, { WebSocketServer } from 'ws';
 import { closeDb, getDb } from './db/index.js';
-import { runMigrations } from './db/migrations.js';
+import { getPendingMigrations, runMigrations } from './db/migrations.js';
+import changelogRouter from './routes/changelog.js';
 import devServerRouter from './routes/dev-server.js';
 import documentsRouter from './routes/documents.js';
 import { enginesRouter } from './routes/engines.js';
+import exportRouter from './routes/export.js';
+import fsRouter from './routes/fs.js';
 import gitRouter from './routes/git.js';
 import healthRouter from './routes/health.js';
 import imagesRouter from './routes/images.js';
@@ -25,7 +28,7 @@ import { getAvailableSkills, reconcileOrphanSessions, restoreRetryCountsFromDb,
 import * as autoLoopService from './services/auto-loop-service.js';
 import { runContentMigrationIfNeeded } from './services/content-migration-service.js';
 import * as cronService from './services/cron-service.js';
-import { createDailyDbBackupIfNeeded } from './services/db-backup-service.js';
+import { createDailyDbBackupIfNeeded, createPreMigrationBackup } from './services/db-backup-service.js';
 import { startDevServer, stopDevServer } from './services/dev-server-service.js';
 import { startPrWatcher, stopPrWatcher } from './services/pr-watcher-service.js';
 import * as quotaBackoffService from './services/quota-backoff-service.js';
@@ -39,6 +42,19 @@ import { initProcessCleanup, killAll as killAllTrackedProcesses } from './utils/
 console.log(`[kobo] Kōbō home: ${getKoboHome()}`);
 // Initialize DB + run migrations
 const db = getDb();
+// Pre-migration backup: snapshot the DB before applying any pending schema
+// migration so a botched upgrade can be rolled back manually. Best-effort —
+// a backup failure must not block boot (the daily backup is a second net).
+try {
+    const pending = getPendingMigrations(db);
+    if (pending.length > 0) {
+        const result = await createPreMigrationBackup(db, getDbPath(), `v${pending[pending.length - 1]}`);
+        console.log(`[kobo] Pre-migration backup before applying ${pending.length} migration(s): ${result.created}`);
+    }
+}
+catch (err) {
+    console.error('[kobo] Pre-migration backup failed (continuing — daily backup remains as fallback):', err);
+}
 runMigrations(db);
 // Daily DB backup (best-effort, fire-and-forget — never blocks boot).
 // Creates a WAL-safe snapshot alongside kobo.db if no backup exists in the
@@ -75,11 +91,14 @@ app.route('/api/workspaces', imagesRouter);
 app.route('/api/notion', notionRouter);
 app.route('/api/sentry', sentryRouter);
 app.route('/api/git', gitRouter);
+app.route('/api/fs', fsRouter);
+app.route('/api/changelog', changelogRouter);
 app.route('/api/settings', settingsRouter);
 app.route('/api/dev-server', devServerRouter);
 app.route('/api/templates', templatesRouter);
 app.route('/api/usage', usageRoutes);
 app.route('/api/workspaces', documentsRouter);
+app.route('/api/workspaces', exportRouter);
 app.route('/api/search', searchRouter);
 app.route('/api/health', healthRouter);
 app.route('/api/engines', enginesRouter);

package/dist/server/routes/changelog.js

@@ -0,0 +1,47 @@
+import fs from 'node:fs';
+import { Hono } from 'hono';
+import { getChangelogPath, getPackageVersion } from '../utils/paths.js';
+/** Hono sub-router for the in-app "What's new" dialog. */
+const app = new Hono();
+/**
+ * Parse a Keep-a-Changelog markdown file into ordered version sections. Each
+ * `## <version>` heading starts a new entry; everything until the next heading
+ * is its notes. A leading `v` on the version is stripped.
+ */
+export function parseChangelog(markdown) {
+    const entries = [];
+    let current = null;
+    for (const line of markdown.split('\n')) {
+        const heading = line.match(/^##\s+v?(\d+\.\d+\.\d+[\w.-]*)\s*$/);
+        if (heading) {
+            if (current)
+                entries.push({ version: current.version, notes: current.lines.join('\n').trim() });
+            current = { version: heading[1], lines: [] };
+        }
+        else if (current) {
+            current.lines.push(line);
+        }
+    }
+    if (current)
+        entries.push({ version: current.version, notes: current.lines.join('\n').trim() });
+    return entries;
+}
+// GET /api/changelog — current app version + parsed CHANGELOG.md sections,
+// powering the "What's new" dialog shown after an update.
+app.get('/', (c) => {
+    try {
+        let versions = [];
+        try {
+            versions = parseChangelog(fs.readFileSync(getChangelogPath(), 'utf-8'));
+        }
+        catch {
+            // No CHANGELOG.md shipped (or unreadable) — degrade to an empty list.
+        }
+        return c.json({ currentVersion: getPackageVersion(), versions });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return c.json({ error: message }, 500);
+    }
+});
+export default app;

package/dist/server/routes/export.js

@@ -0,0 +1,71 @@
+import { Hono } from 'hono';
+import { getDb } from '../db/index.js';
+import * as workspaceService from '../services/workspace-service.js';
+/** Hono sub-router for workspace data exports (mounted on /api/workspaces). */
+const app = new Hono();
+/** Quote a CSV cell when it contains a delimiter, quote, or newline (RFC 4180). */
+function csvCell(value) {
+    return /[",\r\n]/.test(value) ? `"${value.replace(/"/g, '""')}"` : value;
+}
+function csvRow(values) {
+    return values.map(csvCell).join(',');
+}
+/**
+ * Best-effort extraction of a human-readable text from an event payload.
+ * Different event types carry their text under different keys; the full
+ * payload is exported alongside, so this is a convenience column only.
+ */
+function extractText(payload) {
+    try {
+        const parsed = JSON.parse(payload);
+        if (!parsed || typeof parsed !== 'object')
+            return '';
+        const obj = parsed;
+        for (const key of ['text', 'content', 'message']) {
+            const v = obj[key];
+            if (typeof v === 'string')
+                return v;
+        }
+    }
+    catch {
+        /* malformed payload — leave the text column empty */
+    }
+    return '';
+}
+/** Filesystem-safe slug for the download filename. */
+function slugify(name) {
+    const slug = name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    return slug || 'workspace';
+}
+// GET /api/workspaces/:id/events.csv — export every ws_event of the workspace
+// (all sessions, chronological) as a CSV file.
+app.get('/:id/events.csv', (c) => {
+    try {
+        const id = c.req.param('id');
+        const workspace = workspaceService.getWorkspace(id);
+        if (!workspace) {
+            return c.json({ error: `Workspace '${id}' not found` }, 404);
+        }
+        const rows = getDb()
+            .prepare('SELECT session_id, type, payload, created_at FROM ws_events WHERE workspace_id = ? ORDER BY rowid ASC')
+            .all(id);
+        const lines = [csvRow(['created_at', 'session_id', 'type', 'text', 'payload'])];
+        for (const r of rows) {
+            lines.push(csvRow([r.created_at, r.session_id ?? '', r.type, extractText(r.payload), r.payload]));
+        }
+        // Leading BOM so Excel reads UTF-8 correctly; CRLF line endings per RFC 4180.
+        const csv = `${lines.join('\r\n')}\r\n`;
+        return c.body(csv, 200, {
+            'Content-Type': 'text/csv; charset=utf-8',
+            'Content-Disposition': `attachment; filename="${slugify(workspace.name)}-events.csv"`,
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return c.json({ error: message }, 500);
+    }
+});
+export default app;

package/dist/server/routes/fs.js

@@ -0,0 +1,49 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { Hono } from 'hono';
+/** Hono sub-router for local filesystem browsing (project folder picker). */
+const app = new Hono();
+// GET /api/fs/list-dirs?path=<dir> — list the immediate subdirectories of a
+// directory. Defaults to the user's home directory when `path` is omitted.
+// Local single-user dev tool: the user browses their own filesystem.
+app.get('/list-dirs', (c) => {
+    try {
+        const requested = c.req.query('path');
+        const target = path.resolve(requested?.trim() ? requested : os.homedir());
+        let stat;
+        try {
+            stat = fs.statSync(target);
+        }
+        catch {
+            return c.json({ error: `Directory not found: ${target}` }, 404);
+        }
+        if (!stat.isDirectory()) {
+            return c.json({ error: `Not a directory: ${target}` }, 400);
+        }
+        let dirents;
+        try {
+            dirents = fs.readdirSync(target, { withFileTypes: true });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return c.json({ error: `Cannot read directory: ${message}` }, 403);
+        }
+        // Directories only, hidden ones excluded, sorted case-insensitively.
+        const entries = dirents
+            .filter((d) => d.isDirectory() && !d.name.startsWith('.'))
+            .map((d) => ({ name: d.name, path: path.join(target, d.name) }))
+            .sort((a, b) => a.name.toLowerCase().localeCompare(b.name.toLowerCase()));
+        const parent = path.dirname(target);
+        return c.json({
+            path: target,
+            parent: parent === target ? null : parent,
+            entries,
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return c.json({ error: message }, 500);
+    }
+});
+export default app;

package/dist/server/routes/git.js

@@ -1,7 +1,7 @@
 import { Hono } from 'hono';
 import { getDb } from '../db/index.js';
 import { listOrphanWorktrees } from '../services/worktree-service.js';
-import { listBranches, listRemoteBranches } from '../utils/git-ops.js';
+import { listBranches, listRemoteBranches, listWorktreeFiles } from '../utils/git-ops.js';
 /** Hono sub-router for git-related endpoints (branch listing). */
 const app = new Hono();
 // GET /api/git/branches?path=<repoPath> — list branches for a repo
@@ -20,6 +20,21 @@ app.get('/branches', (c) => {
         return c.json({ error: message }, 500);
     }
 });
+// GET /api/git/files?path=<worktreePath> — list a worktree's files (tracked +
+// untracked-but-not-ignored) for the chat's `@file` autocomplete.
+app.get('/files', (c) => {
+    try {
+        const repoPath = c.req.query('path');
+        if (!repoPath) {
+            return c.json({ error: 'Missing required query parameter: path' }, 400);
+        }
+        return c.json({ files: listWorktreeFiles(repoPath) });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return c.json({ error: message }, 500);
+    }
+});
 // GET /api/git/orphan-worktrees?projectPath=<path> — list worktrees of a
 // project that are NOT attached to any Kōbō workspace yet.
 app.get('/orphan-worktrees', (c) => {

package/dist/server/routes/health.js

@@ -5,7 +5,7 @@ import { getDb } from '../db/index.js';
 import { SCHEMA_VERSION } from '../db/migrations.js';
 import { resolveCodexBinary } from '../services/agent/engines/codex/spawn.js';
 import { getGlobalSettings, getProjectSettings, SETTINGS_SCHEMA_VERSION } from '../services/settings-service.js';
-import { getDbPath, getKoboHome } from '../utils/paths.js';
+import { getDbPath, getKoboHome, getPackageVersion } from '../utils/paths.js';
 import { slugifyProjectName } from '../utils/project-slug.js';
 import { resolveWorkspaceWorktreePath } from '../utils/worktree-paths.js';
 const app = new Hono();
@@ -146,6 +146,7 @@ app.get('/report', (c) => {
     const settingsRow = db.prepare('SELECT COUNT(*) as n FROM workspaces').get();
     const archivedRow = db.prepare('SELECT COUNT(*) as n FROM workspaces WHERE archived_at IS NOT NULL').get();
     const report = {
+        version: getPackageVersion(),
         koboHome: home,
         db: {
             path: dbPath,

package/dist/server/routes/workspaces.js

@@ -9,6 +9,7 @@ import { getDb } from '../db/index.js';
 import { migrationGuard } from '../middleware/migration-guard.js';
 import { listEngines } from '../services/agent/engines/registry.js';
 import * as agentManager from '../services/agent/orchestrator.js';
+import * as archiveScriptService from '../services/archive-script-service.js';
 import * as autoLoopService from '../services/auto-loop-service.js';
 import * as cronService from '../services/cron-service.js';
 import * as devServerService from '../services/dev-server-service.js';
@@ -1694,6 +1695,8 @@ app.post('/:id/archive', migrationGuard, (c) => {
         }
         const updated = workspaceService.archiveWorkspace(id);
         wsService.emitEphemeral(id, 'workspace:archived', { workspace: updated });
+        // Run the project's archive script (best-effort — never blocks the archive).
+        archiveScriptService.onWorkspaceArchived(id);
         return c.json(updated);
     }
     catch (err) {
@@ -1721,86 +1724,126 @@ app.post('/:id/unarchive', migrationGuard, (c) => {
         return c.json({ error: message }, 500);
     }
 });
-// DELETE /api/workspaces/:id — delete workspace
-app.delete('/:id', migrationGuard, async (c) => {
+// Shared teardown for a single workspace: stops the agent, destroys the
+// terminal, removes the owned worktree, optionally deletes local/remote
+// branches, then deletes the DB row (cascades to tasks/sessions/events).
+// Every side-effect is best-effort — failures are collected as warnings
+// rather than thrown, so a bulk delete never aborts mid-batch. Returns the
+// list of user-facing warning messages (empty when everything was clean).
+function deleteWorkspaceWithSideEffects(workspace, opts) {
+    // Stop agent if running (best-effort)
     try {
-        const id = c.req.param('id');
-        const workspace = workspaceService.getWorkspace(id);
-        if (!workspace) {
-            return c.json({ error: `Workspace '${id}' not found` }, 404);
-        }
-        // Parse optional body for branch deletion options
-        const body = await c.req
-            .json()
-            .catch(() => ({}));
-        // Stop agent if running (best-effort)
+        agentManager.stopAgent(workspace.id);
+    }
+    catch {
+        // Agent may not be running — ignore
+    }
+    try {
+        terminalService.destroyTerminal(workspace.id);
+    }
+    catch {
+        // Terminal may not exist — ignore
+    }
+    // Collected best-effort warnings: the DB deletion always proceeds, but
+    // side-effects (worktree, local/remote branches) can fail independently.
+    // We surface a user-friendly message per failure so the UI can show a
+    // sticky toast with a copy-pasteable recovery command — common case:
+    // Docker leaves root-owned files inside the worktree, git worktree
+    // remove fails with EACCES.
+    const warnings = [];
+    // Remove worktree (only if owned — for attached external worktrees we
+    // never created the dir, so we must not delete it on the user's behalf).
+    const worktreePath = workspace.worktreePath;
+    if (workspace.worktreeOwned) {
         try {
-            agentManager.stopAgent(id);
+            worktreeService.removeWorktree(workspace.projectPath, worktreePath);
         }
-        catch {
-            // Agent may not be running — ignore
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.error(`[workspaces] Failed to remove worktree: ${message}`);
+            warnings.push(`Failed to remove worktree directory '${worktreePath}'. The git entry may still reference it. ` +
+                `Fix manually:\n` +
+                `  sudo rm -rf '${worktreePath}'\n` +
+                `  cd '${workspace.projectPath}' && git worktree prune\n` +
+                `Reason: ${message}`);
         }
+    }
+    else {
+        console.log(`[workspaces] keeping reused worktree on delete: ${worktreePath}`);
+    }
+    // Delete local branch if requested
+    if (opts.deleteLocalBranch) {
         try {
-            terminalService.destroyTerminal(id);
+            gitOps.deleteLocalBranch(workspace.projectPath, workspace.workingBranch);
         }
-        catch {
-            // Terminal may not exist — ignore
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.error(`[workspaces] Failed to delete local branch: ${message}`);
+            warnings.push(`Failed to delete local branch '${workspace.workingBranch}'. Fix manually:\n` +
+                `  cd '${workspace.projectPath}' && git branch -D '${workspace.workingBranch}'\n` +
+                `Reason: ${message}`);
         }
-        // Collected best-effort warnings: the DB deletion always proceeds, but
-        // side-effects (worktree, local/remote branches) can fail independently.
-        // We surface a user-friendly message per failure so the UI can show a
-        // sticky toast with a copy-pasteable recovery command — common case:
-        // Docker leaves root-owned files inside the worktree, git worktree
-        // remove fails with EACCES.
-        const warnings = [];
-        // Remove worktree (only if owned — for attached external worktrees we
-        // never created the dir, so we must not delete it on the user's behalf).
-        const worktreePath = workspace.worktreePath;
-        if (workspace.worktreeOwned) {
-            try {
-                worktreeService.removeWorktree(workspace.projectPath, worktreePath);
-            }
-            catch (err) {
-                const message = err instanceof Error ? err.message : String(err);
-                console.error(`[workspaces] Failed to remove worktree: ${message}`);
-                warnings.push(`Failed to remove worktree directory '${worktreePath}'. The git entry may still reference it. ` +
-                    `Fix manually:\n` +
-                    `  sudo rm -rf '${worktreePath}'\n` +
-                    `  cd '${workspace.projectPath}' && git worktree prune\n` +
-                    `Reason: ${message}`);
-            }
+    }
+    // Delete remote branch if requested
+    if (opts.deleteRemoteBranch) {
+        try {
+            gitOps.deleteRemoteBranch(workspace.projectPath, workspace.workingBranch);
         }
-        else {
-            console.log(`[workspaces] keeping reused worktree on delete: ${worktreePath}`);
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.error(`[workspaces] Failed to delete remote branch: ${message}`);
+            warnings.push(`Failed to delete remote branch '${workspace.workingBranch}'. Fix manually:\n` +
+                `  cd '${workspace.projectPath}' && git push origin --delete '${workspace.workingBranch}'\n` +
+                `Reason: ${message}`);
         }
-        // Delete local branch if requested
-        if (body.deleteLocalBranch) {
+    }
+    // Delete workspace from DB (cascades to tasks, sessions, events)
+    workspaceService.deleteWorkspace(workspace.id);
+    return warnings;
+}
+// DELETE /api/workspaces/archived — bulk-delete every archived workspace.
+// Must be declared BEFORE `DELETE /:id` or the dynamic segment captures it.
+// Each workspace teardown is isolated: an error on one is swallowed into the
+// warnings list and never aborts the batch.
+app.delete('/archived', migrationGuard, async (c) => {
+    try {
+        const body = await c.req
+            .json()
+            .catch(() => ({}));
+        const archived = workspaceService.listArchivedWorkspaces();
+        const warnings = [];
+        let deleted = 0;
+        for (const workspace of archived) {
             try {
-                gitOps.deleteLocalBranch(workspace.projectPath, workspace.workingBranch);
+                warnings.push(...deleteWorkspaceWithSideEffects(workspace, body));
+                deleted++;
             }
             catch (err) {
                 const message = err instanceof Error ? err.message : String(err);
-                console.error(`[workspaces] Failed to delete local branch: ${message}`);
-                warnings.push(`Failed to delete local branch '${workspace.workingBranch}'. Fix manually:\n` +
-                    `  cd '${workspace.projectPath}' && git branch -D '${workspace.workingBranch}'\n` +
-                    `Reason: ${message}`);
+                console.error(`[workspaces] Failed to delete archived workspace '${workspace.id}': ${message}`);
+                warnings.push(`Failed to delete workspace '${workspace.name}': ${message}`);
             }
         }
-        // Delete remote branch if requested
-        if (body.deleteRemoteBranch) {
-            try {
-                gitOps.deleteRemoteBranch(workspace.projectPath, workspace.workingBranch);
-            }
-            catch (err) {
-                const message = err instanceof Error ? err.message : String(err);
-                console.error(`[workspaces] Failed to delete remote branch: ${message}`);
-                warnings.push(`Failed to delete remote branch '${workspace.workingBranch}'. Fix manually:\n` +
-                    `  cd '${workspace.projectPath}' && git push origin --delete '${workspace.workingBranch}'\n` +
-                    `Reason: ${message}`);
-            }
+        return c.json({ ok: true, deleted, warnings }, 200);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return c.json({ error: message }, 500);
+    }
+});
+// DELETE /api/workspaces/:id — delete workspace
+app.delete('/:id', migrationGuard, async (c) => {
+    try {
+        const id = c.req.param('id');
+        const workspace = workspaceService.getWorkspace(id);
+        if (!workspace) {
+            return c.json({ error: `Workspace '${id}' not found` }, 404);
         }
-        // Delete workspace from DB (cascades to tasks, sessions, events)
-        workspaceService.deleteWorkspace(id);
+        // Parse optional body for branch deletion options
+        const body = await c.req
+            .json()
+            .catch(() => ({}));
+        const warnings = deleteWorkspaceWithSideEffects(workspace, body);
         // When everything worked cleanly we keep the legacy 204 response so
         // existing clients aren't surprised by a JSON body. Warnings promote the
         // response to 200 so the body is readable.

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

@@ -4,6 +4,7 @@ import { getDb } from '../../db/index.js';
 import { ensureKoboHome, getCompiledMcpServerPath, getDbPath, getKoboHome, getMcpServerSourcePath, getSettingsPath, getSkillsPath, } from '../../utils/paths.js';
 import { unregisterProcess } from '../../utils/process-tracker.js';
 import * as autoLoopService from '../auto-loop-service.js';
+import * as cleanupScriptService from '../cleanup-script-service.js';
 import * as cronService from '../cron-service.js';
 import * as quotaBackoffService from '../quota-backoff-service.js';
 import { getEffectiveSettings } from '../settings-service.js';
@@ -308,6 +309,10 @@ function readEffectiveSettingsSafe(projectPath) {
             sourceBranch: 'main',
             devServer: null,
             setupScript: '',
+            cleanupScript: '',
+            cleanupScriptMode: 'no-tasks',
+            cleanupScriptOnlyOnChanges: false,
+            archiveScript: '',
             notionStatusProperty: '',
             notionInProgressStatus: '',
         };
@@ -531,7 +536,12 @@ function handleEvent(workspaceId, agentSessionId, ev) {
         // cleared, next iteration will start fresh) — report 'completed' to
         // auto-loop so it continues.
         const effectiveReason = isResumeFailed ? 'completed' : ev.reason;
+        // Capture the auto-loop flag BEFORE autoLoopService.onSessionEnded —
+        // disable() clears it, and the cleanup hook needs to know whether this was
+        // a mid-loop session (never cleans) or a standalone one.
+        const wasAutoLoop = autoLoopService.getStatus(workspaceId).auto_loop;
         autoLoopService.onSessionEnded(workspaceId, effectiveReason, delta);
+        cleanupScriptService.onSessionEnded(workspaceId, effectiveReason, { wasAutoLoop });
     }
     if (ev.kind === 'session:user-input-requested') {
         if (ev.requestKind === 'question') {

package/dist/server/services/archive-script-service.js

@@ -0,0 +1,65 @@
+import fs from 'node:fs';
+import { getDb } from '../db/index.js';
+import { slugifyProjectName } from '../utils/project-slug.js';
+import { runScript, SCRIPT_TIMEOUT_MS } from '../utils/script-runner.js';
+import { resolveWorkspaceWorktreePath } from '../utils/worktree-paths.js';
+import { getEffectiveSettings, getGlobalSettings, getProjectSettings } from './settings-service.js';
+function getRow(workspaceId) {
+    const db = getDb();
+    const row = db
+        .prepare(`SELECT id, name, project_path, working_branch, source_branch, worktree_path
+       FROM workspaces WHERE id = ?`)
+        .get(workspaceId);
+    return row ?? null;
+}
+/** Execute the archive script in a worktree, streaming `archive:*` WS events. */
+export function runArchiveScript(workspaceId, worktreePath, script, env) {
+    return runScript({
+        workspaceId,
+        worktreePath,
+        script,
+        eventPrefix: 'archive',
+        tmpFileName: '.archive-script.tmp',
+        env,
+        timeoutMs: SCRIPT_TIMEOUT_MS,
+    });
+}
+/**
+ * Hook for the `POST /api/workspaces/:id/archive` route — runs the project's
+ * archive script (if configured) after a workspace is archived. The worktree is
+ * still on disk at archive time (archiving is a soft-delete). Best-effort: never
+ * blocks or fails the archive operation.
+ */
+export function onWorkspaceArchived(workspaceId) {
+    try {
+        const row = getRow(workspaceId);
+        if (!row)
+            return;
+        const effective = getEffectiveSettings(row.project_path);
+        const script = effective.archiveScript;
+        if (!script.trim())
+            return; // empty = disabled
+        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);
+        if (!fs.existsSync(worktreePath)) {
+            console.warn(`[archive-script-service] worktree missing, skipping archive script: ${worktreePath}`);
+            return;
+        }
+        void runArchiveScript(workspaceId, worktreePath, script, {
+            workspaceName: row.name,
+            branchName: row.working_branch,
+            sourceBranch: row.source_branch,
+            projectPath: row.project_path,
+        }).catch((err) => {
+            console.error('[archive-script-service] runArchiveScript failed:', err);
+        });
+    }
+    catch (err) {
+        console.error('[archive-script-service] onWorkspaceArchived failed:', err);
+    }
+}

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

@@ -4,6 +4,7 @@ import { getDb } from '../db/index.js';
 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 settingsService from './settings-service.js';
 import { getSuitePrompts } from './skill-suite-prompts.js';
 import { emit, emitEphemeral } from './websocket-service.js';
@@ -82,6 +83,12 @@ export function disable(workspaceId, reason) {
     const db = getDb();
     db.prepare('UPDATE workspaces SET auto_loop = 0 WHERE id = ?').run(workspaceId);
     emitEphemeral(workspaceId, 'autoloop:disabled', { reason });
+    // 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.
+    if (reason === 'completed') {
+        cleanupScriptService.onAutoLoopCompleted(workspaceId);
+    }
 }
 /**
  * Route a `session:ended` event into the auto-loop state machine.