@0xmaxma/claude-gateway 1.6.4 → 1.6.5

package/dist/apps/installer.js

@@ -44,6 +44,22 @@ const node_child_process_1 = require("node:child_process");
 const compose_generator_1 = require("./compose-generator");
 // ─── Constants ────────────────────────────────────────────────────────────────
 const DEFAULT_APPS_DIR = path.join(os.homedir(), '.claude-gateway', 'apps');
+// Backups live under `<appsDir>/.backups/<app>/`. A dot-prefixed dir here is
+// never mistaken for an installed app (the registry is driven by `apps.json`,
+// not by enumerating the apps directory), and — being a sibling of each app's
+// own dir rather than inside it — the archive survives that app's uninstall,
+// which removes only `<appsDir>/<app>/`.
+const APP_BACKUPS_DIRNAME = '.backups';
+// Default per-app backup ceiling when config omits it. The N most recent are
+// kept; older archives are pruned after each successful backup.
+const DEFAULT_BACKUP_RETENTION = 10;
+// Wall-clock ceiling for a single helper-container tar (backup or restore) of
+// one volume. A few hundred MB tars in seconds; this only bounds a pathological
+// hang so a stuck helper never wedges a backup job forever.
+const VOLUME_TAR_TIMEOUT_MS = 300000;
+// OCI image used for the throwaway tar helper. Small, ubiquitous, already a
+// transitive dependency of most stacks, so it is almost always cache-warm.
+const BACKUP_HELPER_IMAGE = 'alpine';
 // Per-app ceiling for the boot-time `compose up --wait` during restore. Runs in
 // the background (non-blocking), so this only bounds how long a hung container
 // keeps its child process alive — not the gateway's responsiveness. Shorter than
@@ -59,17 +75,26 @@ const APP_NAME_RE = /^[a-z0-9][a-z0-9-]{1,63}$/;
 const GITHUB_URL_RE = /^https:\/\/github\.com\/(?!.*\.\.)[A-Za-z0-9][A-Za-z0-9_.-]*\/[A-Za-z0-9][A-Za-z0-9_.-]*(\.git)?$/;
 // ─── Installer ────────────────────────────────────────────────────────────────
 class AppInstaller {
-    constructor(registry, registryClient, callbacks, spawn = defaultSpawn, appsDir, agentManager, spawnAsync = defaultAsyncSpawn) {
+    constructor(registry, registryClient, callbacks, spawn = defaultSpawn, appsDir, agentManager, spawnAsync = defaultAsyncSpawn, housekeepingConfig = {}, appBackupConfig, backupsDir) {
         this.registry = registry;
         this.registryClient = registryClient;
         this.callbacks = callbacks;
         this.spawn = spawn;
         this.agentManager = agentManager;
         this.spawnAsync = spawnAsync;
+        this.housekeepingConfig = housekeepingConfig;
         this.jobs = new Map();
         /** Tracks app names currently being installed to prevent concurrent installs of the same name. */
         this.installingNames = new Set();
         this.appsDir = appsDir ?? DEFAULT_APPS_DIR;
+        this.backupsDir = backupsDir ?? path.join(this.appsDir, APP_BACKUPS_DIRNAME);
+        this.appBackupConfig = {
+            retention: appBackupConfig?.retention !== undefined && appBackupConfig.retention >= 0
+                ? Math.floor(appBackupConfig.retention)
+                : DEFAULT_BACKUP_RETENTION,
+            autoBackupBeforeUninstall: appBackupConfig?.autoBackupBeforeUninstall ?? true,
+            autoBackupBeforeUpdate: appBackupConfig?.autoBackupBeforeUpdate ?? true,
+        };
     }
     // ─── Public API ───────────────────────────────────────────────────────────
     /** Start an async install job. Returns jobId immediately. */
@@ -161,6 +186,7 @@ class AppInstaller {
                 commit,
                 secretKeys: generated.secretKeys,
                 generatedKeys: generated.generatedKeys,
+                secretDefaults: generated.secretDefaults,
                 ports: generated.ports,
                 agentDeclaration: generated.agentDeclaration,
                 warnings: generated.warnings,
@@ -254,6 +280,17 @@ class AppInstaller {
             return;
         }
         const appDir = entry.installPath;
+        // Safety hook: snapshot the app's data before tearing it down, so an
+        // accidental or regretted uninstall has a restore point. Best-effort — a
+        // backup failure must never block the uninstall the operator asked for.
+        if (this.appBackupConfig.autoBackupBeforeUninstall && fs.existsSync(appDir)) {
+            try {
+                await this.performBackup(entry);
+            }
+            catch (err) {
+                console.warn(`[apps] auto-backup before uninstall of "${appName}" failed (continuing): ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
         // docker compose down --rmi all (graceful fallback if dir is already gone)
         if (fs.existsSync(appDir)) {
             try {
@@ -291,6 +328,431 @@ class AppInstaller {
         }
         await this.registry.remove(appName);
     }
+    // ─── Backup / Restore ───────────────────────────────────────────────────────
+    /**
+     * Start an async backup job. Returns jobId immediately; poll {@link getJob}.
+     * A backup is a permission-safe snapshot of the app's Docker named volumes +
+     * config (`.env`/`app.yaml`/compose) into a single archive under
+     * `<backupsDir>/<app>/`. The app is stopped for the snapshot and restarted
+     * afterwards (see {@link performBackup}).
+     */
+    backup(appName) {
+        this.pruneOldJobs();
+        if (this.installingNames.has(appName)) {
+            throw new Error(`App "${appName}" is busy (install/update/backup in progress)`);
+        }
+        this.installingNames.add(appName);
+        const jobId = crypto.randomUUID();
+        const job = {
+            id: jobId,
+            status: 'pending',
+            logs: [],
+            startedAt: Date.now(),
+            updatedAt: Date.now(),
+        };
+        this.jobs.set(jobId, job);
+        void this.runBackup(job, appName)
+            .catch((err) => this.failJob(job, err instanceof Error ? err.message : String(err)))
+            .finally(() => this.installingNames.delete(appName));
+        return jobId;
+    }
+    /**
+     * Start an async restore job. Returns jobId immediately; poll {@link getJob}.
+     * Restores the app's volumes + config from a prior backup, then starts it.
+     */
+    restore(appName, backupId) {
+        this.pruneOldJobs();
+        if (this.installingNames.has(appName)) {
+            throw new Error(`App "${appName}" is busy (install/update/backup in progress)`);
+        }
+        this.installingNames.add(appName);
+        const jobId = crypto.randomUUID();
+        const job = {
+            id: jobId,
+            status: 'pending',
+            logs: [],
+            startedAt: Date.now(),
+            updatedAt: Date.now(),
+        };
+        this.jobs.set(jobId, job);
+        void this.runRestore(job, appName, backupId)
+            .catch((err) => this.failJob(job, err instanceof Error ? err.message : String(err)))
+            .finally(() => this.installingNames.delete(appName));
+        return jobId;
+    }
+    /** List an app's backups, newest first. Reads the sidecar manifests. */
+    listBackups(appName) {
+        const dir = this.appBackupDir(appName);
+        if (!fs.existsSync(dir))
+            return [];
+        const infos = [];
+        for (const file of fs.readdirSync(dir)) {
+            if (!file.endsWith('.json'))
+                continue;
+            try {
+                const meta = JSON.parse(fs.readFileSync(path.join(dir, file), 'utf-8'));
+                // Only surface a backup whose archive is actually present.
+                if (!fs.existsSync(path.join(dir, `${meta.id}.tar.gz`)))
+                    continue;
+                infos.push({
+                    id: meta.id,
+                    createdAt: meta.createdAt,
+                    sizeBytes: meta.sizeBytes,
+                    appVersion: meta.appVersion,
+                });
+            }
+            catch {
+                /* skip malformed manifest */
+            }
+        }
+        return infos.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+    }
+    /** Delete one backup (archive + sidecar). Idempotent. */
+    deleteBackup(appName, backupId) {
+        if (!/^[\w.-]+$/.test(backupId))
+            throw new Error(`Invalid backup id "${backupId}"`);
+        const dir = this.appBackupDir(appName);
+        for (const ext of ['.tar.gz', '.json']) {
+            const p = path.join(dir, `${backupId}${ext}`);
+            try {
+                fs.rmSync(p, { force: true });
+            }
+            catch {
+                /* best-effort */
+            }
+        }
+    }
+    async runBackup(job, appName) {
+        job.status = 'running';
+        const entry = await this.registry.get(appName);
+        if (!entry)
+            throw new Error(`App "${appName}" is not installed`);
+        const info = await this.performBackup(entry, (m) => this.log(job, m));
+        job.backup = info;
+        job.status = 'completed';
+        job.updatedAt = Date.now();
+    }
+    async runRestore(job, appName, backupId) {
+        job.status = 'running';
+        const entry = await this.registry.get(appName);
+        if (!entry)
+            throw new Error(`App "${appName}" is not installed`);
+        const info = await this.performRestore(entry, backupId, (m) => this.log(job, m));
+        job.backup = info;
+        job.status = 'completed';
+        job.updatedAt = Date.now();
+    }
+    /**
+     * Core backup routine (shared by the job path and the auto-backup hooks).
+     *
+     * Consistency: a running app is stopped for the snapshot so no writes land
+     * mid-tar, then ALWAYS restarted in a `finally` — a backup that throws never
+     * leaves the app stuck stopped.
+     *
+     * Permission safety: each named volume is tarred inside a throwaway root
+     * container (`docker run … tar czf`), so uid/gid/mode are preserved in the
+     * archive and no host `cp`/`chown`/sudo ever touches the volume data.
+     */
+    async performBackup(entry, logSink) {
+        const log = (m) => logSink?.(m);
+        const appName = entry.name;
+        const appDir = entry.installPath;
+        if (!fs.existsSync(appDir)) {
+            throw new Error(`App "${appName}" directory is gone — cannot back up`);
+        }
+        const volumes = this.discoverVolumes(appName, appDir);
+        const bindMounts = this.discoverBindMounts(appName, appDir);
+        const wasRunning = (await this.queryRuntimeStatus(entry)) === 'running';
+        const staging = fs.mkdtempSync(path.join(os.tmpdir(), `bkp-${appName}-`));
+        try {
+            if (wasRunning) {
+                log(`Stopping "${appName}" for a consistent snapshot`);
+                this.run(['docker', 'compose', '-p', appName, 'stop'], appDir, 120000);
+            }
+            const volDir = path.join(staging, 'volumes');
+            fs.mkdirSync(volDir, { recursive: true });
+            for (const vol of volumes) {
+                log(`Archiving volume "${vol}"`);
+                this.run([
+                    'docker', 'run', '--rm',
+                    '-v', `${appName}_${vol}:/data:ro`,
+                    '-v', `${volDir}:/backup`,
+                    BACKUP_HELPER_IMAGE,
+                    'tar', 'czf', `/backup/${vol}.tar.gz`, '-C', '/data', '.',
+                ], undefined, VOLUME_TAR_TIMEOUT_MS);
+            }
+            // Bind-mount data dirs under the app dir (not Docker named volumes).
+            // Archive each with the same root-helper tar so ownership (e.g. the
+            // postgres uid) survives without host-side cp/sudo. Indexed filenames
+            // avoid collisions between paths that flatten to the same name.
+            const bindDir = path.join(staging, 'binds');
+            fs.mkdirSync(bindDir, { recursive: true });
+            const capturedBinds = [];
+            for (const rel of bindMounts) {
+                const abs = path.join(appDir, rel);
+                if (!fs.existsSync(abs)) {
+                    log(`Bind mount "${rel}" missing on disk — skipping`);
+                    continue;
+                }
+                log(`Archiving bind mount "${rel}"`);
+                this.run([
+                    'docker', 'run', '--rm',
+                    '-v', `${abs}:/data:ro`,
+                    '-v', `${bindDir}:/backup`,
+                    BACKUP_HELPER_IMAGE,
+                    'tar', 'czf', `/backup/bind-${capturedBinds.length}.tar.gz`, '-C', '/data', '.',
+                ], undefined, VOLUME_TAR_TIMEOUT_MS);
+                capturedBinds.push(rel);
+            }
+            // Config (owned by the gateway user, copied on the host).
+            const cfgDir = path.join(staging, 'config');
+            fs.mkdirSync(cfgDir, { recursive: true });
+            for (const f of ['.env', 'app.yaml', 'docker-compose.yml']) {
+                this.copyIfExists(path.join(appDir, f), path.join(cfgDir, f));
+            }
+            const id = `${new Date().toISOString().replace(/[:.]/g, '-')}-${crypto
+                .randomUUID()
+                .slice(0, 8)}`;
+            const meta = {
+                id,
+                appName,
+                appVersion: entry.version,
+                createdAt: new Date().toISOString(),
+                volumes,
+                bindMounts: capturedBinds,
+                sizeBytes: 0,
+            };
+            fs.writeFileSync(path.join(staging, 'metadata.json'), JSON.stringify(meta, null, 2));
+            const outDir = this.appBackupDir(appName);
+            fs.mkdirSync(outDir, { recursive: true });
+            const archivePath = path.join(outDir, `${id}.tar.gz`);
+            // The gateway host tars the staging tree. Volume tarballs written by the
+            // root helper are world-readable (0644), so this read succeeds without sudo.
+            this.run(['tar', 'czf', archivePath, '-C', staging, '.'], undefined, VOLUME_TAR_TIMEOUT_MS);
+            let sizeBytes = 0;
+            try {
+                sizeBytes = fs.statSync(archivePath).size;
+            }
+            catch {
+                /* archive stat failed — leave size 0 */
+            }
+            meta.sizeBytes = sizeBytes;
+            fs.writeFileSync(path.join(outDir, `${id}.json`), JSON.stringify(meta, null, 2));
+            this.pruneBackups(appName);
+            log(`Backup "${id}" complete (${sizeBytes} bytes, ${volumes.length} volume(s), ` +
+                `${capturedBinds.length} bind mount(s))`);
+            return { id, createdAt: meta.createdAt, sizeBytes, appVersion: meta.appVersion };
+        }
+        finally {
+            try {
+                this.rmrf(staging);
+            }
+            catch {
+                /* best-effort staging cleanup */
+            }
+            if (wasRunning) {
+                try {
+                    log(`Restarting "${appName}"`);
+                    this.composeUp(appName, appDir);
+                }
+                catch (restartErr) {
+                    log(`WARNING: failed to restart "${appName}" after backup: ${restartErr instanceof Error ? restartErr.message : String(restartErr)}`);
+                }
+            }
+        }
+    }
+    /**
+     * Core restore routine. Extracts the archive, wipes+repopulates each volume
+     * via the root helper (preserving inner ownership), restores `.env`, and
+     * starts the app on the restored data. Restoring across a differing
+     * appVersion is allowed but warns (possible schema/migration mismatch).
+     */
+    async performRestore(entry, backupId, logSink) {
+        const log = (m) => logSink?.(m);
+        if (!/^[\w.-]+$/.test(backupId))
+            throw new Error(`Invalid backup id "${backupId}"`);
+        const appName = entry.name;
+        const appDir = entry.installPath;
+        const archivePath = path.join(this.appBackupDir(appName), `${backupId}.tar.gz`);
+        if (!fs.existsSync(archivePath)) {
+            throw new Error(`Backup "${backupId}" not found for app "${appName}"`);
+        }
+        const staging = fs.mkdtempSync(path.join(os.tmpdir(), `rst-${appName}-`));
+        try {
+            this.run(['tar', 'xzf', archivePath, '-C', staging], undefined, VOLUME_TAR_TIMEOUT_MS);
+            const meta = JSON.parse(fs.readFileSync(path.join(staging, 'metadata.json'), 'utf-8'));
+            if (meta.appVersion !== entry.version) {
+                log(`WARNING: restoring backup from version "${meta.appVersion}" onto installed "${entry.version}" — possible schema/migration mismatch`);
+            }
+            log(`Stopping "${appName}" before restore`);
+            try {
+                this.run(['docker', 'compose', '-p', appName, 'stop'], appDir, 120000);
+            }
+            catch {
+                /* may already be stopped */
+            }
+            const volDir = path.join(staging, 'volumes');
+            for (const vol of meta.volumes) {
+                const tarball = path.join(volDir, `${vol}.tar.gz`);
+                if (!fs.existsSync(tarball)) {
+                    log(`WARNING: volume "${vol}" missing from backup — skipping`);
+                    continue;
+                }
+                log(`Restoring volume "${vol}"`);
+                this.run([
+                    'docker', 'run', '--rm',
+                    '-v', `${appName}_${vol}:/data`,
+                    '-v', `${volDir}:/backup`,
+                    BACKUP_HELPER_IMAGE,
+                    'sh', '-c',
+                    // Wipe the live volume, then untar the snapshot (uid/gid preserved).
+                    `rm -rf /data/* /data/..?* 2>/dev/null; tar xzf /backup/${vol}.tar.gz -C /data`,
+                ], undefined, VOLUME_TAR_TIMEOUT_MS);
+            }
+            // Restore bind-mount data dirs under the app dir. Indexed filenames match
+            // performBackup's capture order. Each restored path is re-checked to stay
+            // under the app dir (defense-in-depth against a tampered metadata path).
+            const bindDir = path.join(staging, 'binds');
+            const bindMounts = meta.bindMounts ?? [];
+            bindMounts.forEach((rel, i) => {
+                const abs = path.resolve(appDir, rel);
+                const base = appDir.endsWith(path.sep) ? appDir : appDir + path.sep;
+                if (abs !== appDir && !abs.startsWith(base)) {
+                    log(`WARNING: bind mount "${rel}" escapes the app dir — skipping`);
+                    return;
+                }
+                const tarball = path.join(bindDir, `bind-${i}.tar.gz`);
+                if (!fs.existsSync(tarball)) {
+                    log(`WARNING: bind mount "${rel}" missing from backup — skipping`);
+                    return;
+                }
+                log(`Restoring bind mount "${rel}"`);
+                this.run([
+                    'docker', 'run', '--rm',
+                    '-v', `${abs}:/data`,
+                    '-v', `${bindDir}:/backup`,
+                    BACKUP_HELPER_IMAGE,
+                    'sh', '-c',
+                    // Wipe the live bind dir, then untar the snapshot (uid/gid preserved).
+                    `rm -rf /data/* /data/..?* 2>/dev/null; tar xzf /backup/bind-${i}.tar.gz -C /data`,
+                ], undefined, VOLUME_TAR_TIMEOUT_MS);
+            });
+            // Restore config that carries generated secrets, so the app boots with the
+            // same credentials the volume data was created under.
+            this.copyIfExists(path.join(staging, 'config', '.env'), path.join(appDir, '.env'));
+            log(`Starting "${appName}" on restored data`);
+            this.composeUp(appName, appDir);
+            await this.registry.updateStatus(appName, 'running').catch(() => { });
+            log(`Restore of "${backupId}" complete`);
+            return {
+                id: meta.id,
+                createdAt: meta.createdAt,
+                sizeBytes: meta.sizeBytes,
+                appVersion: meta.appVersion,
+            };
+        }
+        finally {
+            try {
+                this.rmrf(staging);
+            }
+            catch {
+                /* best-effort */
+            }
+        }
+    }
+    /**
+     * List an app's compose-level named volumes (the top-level `volumes:` keys).
+     * Returns [] when the app declares none or the query fails — a config-only
+     * backup is still useful (it captures `.env`).
+     */
+    discoverVolumes(appName, appDir) {
+        try {
+            const { stdout } = this.run(['docker', 'compose', '-p', appName, 'config', '--volumes'], appDir, 30000);
+            return stdout
+                .split('\n')
+                .map((s) => s.trim())
+                .filter((s) => s.length > 0);
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Discover bind-mount source directories that live **under the app dir**
+     * (e.g. `./data/photos` → `data/photos`). These hold app-owned data that is
+     * not a Docker named volume, so {@link discoverVolumes} never reports them —
+     * yet they are deleted on uninstall and must be captured in a backup.
+     *
+     * Returns app-dir-relative POSIX paths, deduped and sorted. Bind mounts whose
+     * source resolves outside the app dir (shared host resources such as a
+     * read-only `~/.claude/projects`) are intentionally excluded. Best-effort:
+     * returns `[]` on any failure, mirroring {@link discoverVolumes}.
+     */
+    discoverBindMounts(appName, appDir) {
+        try {
+            const { stdout } = this.run(['docker', 'compose', '-p', appName, 'config', '--format', 'json'], appDir, 30000);
+            const parsed = JSON.parse(stdout);
+            // Local-dev installs symlink the app dir into appsDir, and the generated
+            // compose resolves bind sources against the symlink's *realpath*. Match a
+            // source that sits under either the symlink path or its target, so those
+            // bind mounts are not wrongly excluded.
+            const bases = [appDir];
+            try {
+                const real = fs.realpathSync(appDir);
+                if (real !== appDir)
+                    bases.push(real);
+            }
+            catch {
+                /* app dir unreadable — fall back to the literal path */
+            }
+            const rels = new Set();
+            for (const svc of Object.values(parsed.services ?? {})) {
+                for (const vol of svc.volumes ?? []) {
+                    if (vol.type !== 'bind' || typeof vol.source !== 'string')
+                        continue;
+                    const abs = path.resolve(appDir, vol.source);
+                    const matched = bases.find((b) => abs === b || abs.startsWith(b + path.sep));
+                    if (!matched)
+                        continue; // outside the app dir
+                    const rel = path.relative(matched, abs);
+                    if (rel.length > 0)
+                        rels.add(rel.split(path.sep).join('/'));
+                }
+            }
+            return Array.from(rels).sort();
+        }
+        catch {
+            return [];
+        }
+    }
+    /** Keep the N most recent backups per app (by createdAt); prune older. */
+    pruneBackups(appName) {
+        const retention = this.appBackupConfig.retention;
+        if (retention <= 0)
+            return; // 0 = unbounded
+        const all = this.listBackups(appName); // newest first
+        for (const stale of all.slice(retention)) {
+            this.deleteBackup(appName, stale.id);
+        }
+    }
+    appBackupDir(appName) {
+        // Never trust the name reaching the filesystem: an unvalidated value (e.g.
+        // a `%2F`-smuggled `../../x` from a route param) would let path.join escape
+        // the backups tree. Every backup op funnels through here, so this one guard
+        // covers backup/restore/list/delete.
+        if (!APP_NAME_RE.test(appName))
+            throw new Error(`Invalid app name "${appName}"`);
+        return path.join(this.backupsDir, appName);
+    }
+    copyIfExists(src, dest) {
+        try {
+            if (fs.existsSync(src))
+                fs.copyFileSync(src, dest);
+        }
+        catch {
+            /* best-effort — a missing/unreadable optional file is not fatal */
+        }
+    }
     async startStopRestart(appName, action) {
         const entry = await this.registry.get(appName);
         if (!entry)
@@ -570,8 +1032,21 @@ class AppInstaller {
                 this.log(job, `Warning: ${w}`);
             }
             // ── Write .env ────────────────────────────────────────────────────────
+            // Carry over an existing .env before writing, but ONLY for a local
+            // (symlinked) install. A local install can re-point at a source tree that
+            // still holds a prior .env alongside persisted data (e.g. a postgres pgdata
+            // bind mount). writeEnvFile treats an already-present generated secret as
+            // pinned, so reusing the existing .env keeps DB_PASSWORD/etc. stable and
+            // lets the app reconnect to that data instead of failing auth (mirrors the
+            // reconfigure path). This is deliberately scoped to `source === 'local'`:
+            // a registry/GitHub install checks out into appDir, and a repo that
+            // committed a `.env` would otherwise get its secrets pinned to committed
+            // values — so for those sources we ignore any checked-out .env and generate
+            // fresh, unchanged from before. Operator-supplied envVars still win.
             this.log(job, 'Writing .env');
-            const generatedNames = this.writeEnvFile(appDir, appName, generated, options.envVars ?? {});
+            const existingEnv = source === 'local' ? this.readEnvFile(appDir) : {};
+            const mergedEnv = { ...existingEnv, ...(options.envVars ?? {}) };
+            const generatedNames = this.writeEnvFile(appDir, appName, generated, mergedEnv);
             if (generatedNames.length > 0) {
                 this.log(job, `Generated secrets: ${generatedNames.join(', ')}`);
             }
@@ -665,6 +1140,9 @@ class AppInstaller {
             // ── Update status to running ──────────────────────────────────────────
             await this.registry.updateStatus(appName, 'running');
             this.log(job, 'Containers healthy');
+            // ── Housekeeping: reclaim leaked build cache + dangling images ────────
+            // Best-effort, config-gated, after the new stack is up (issue #302).
+            this.pruneAfterBuild(job);
             // ── Register proxy routes ─────────────────────────────────────────────
             this.callbacks.registerRoutes(appName, generated.ports);
             // ── Build result ──────────────────────────────────────────────────────
@@ -743,6 +1221,17 @@ class AppInstaller {
             return;
         }
         this.log(job, `Updating ${appName} ${entry.commit.slice(0, 8)} → ${target.newCommit.slice(0, 8)}`);
+        // Safety hook: snapshot before the update so a bad new image can be rolled
+        // back. Best-effort — a backup failure must not block the update.
+        if (this.appBackupConfig.autoBackupBeforeUpdate) {
+            try {
+                const info = await this.performBackup(entry, (m) => this.log(job, m));
+                this.log(job, `Pre-update backup "${info.id}" created`);
+            }
+            catch (err) {
+                this.log(job, `WARNING: pre-update backup failed (continuing): ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
         const tmpDir = path.join(os.tmpdir(), `cg-update-${appName}-${crypto.randomUUID()}`);
         try {
             // ── Shallow fetch of specific commit into tmp dir ─────────────────────
@@ -802,6 +1291,9 @@ class AppInstaller {
             // we can reclaim exactly those images after the update — without a
             // `compose down` that would collide with the new stack (issue #283).
             const oldImageIds = this.captureComposeImageIds(appName, entry.installPath);
+            // Also capture the app's declared image refs (repo:tag) so a superseded
+            // *pulled* tag can be reclaimed after the update (issue #302).
+            const oldImageRefs = this.captureComposeImageRefs(appName, entry.installPath);
             // ── Bring old containers down (keeps images for rollback) ─────────────
             this.log(job, 'Stopping old containers');
             this.run(['docker', 'compose', '-p', appName, 'down'], entry.installPath, 120000);
@@ -840,6 +1332,7 @@ class AppInstaller {
             // below never removes an image the new containers depend on (e.g. when the
             // old and new versions happen to share a base/image).
             const newImageIds = this.captureComposeImageIds(appName, tmpDir);
+            const newImageRefs = this.captureComposeImageRefs(appName, tmpDir);
             // ── Swap dirs ─────────────────────────────────────────────────────────
             // Swap in place at the recorded install path — NOT path.join(appsDir, appName).
             // For legacy installs the on-disk dir is named after the source repo/URL
@@ -892,7 +1385,14 @@ class AppInstaller {
                 }
                 catch { /* still in use or already gone — non-fatal */ }
             }
+            // Reclaim a superseded *pulled* tag the image-ID reclaim above can't
+            // (a pulled image with >1 repo tag isn't removable by ID) — only this
+            // app's own prior refs the new stack no longer uses (issue #302).
+            this.reclaimSupersededTags(job, oldImageRefs, newImageRefs);
             this.safeRmrf(oldBackupDir, job, 'old backup dir');
+            // ── Housekeeping: reclaim leaked build cache + dangling images ────────
+            // Best-effort, config-gated, after the image reclaim (issue #302).
+            this.pruneAfterBuild(job);
             // ── Build result ──────────────────────────────────────────────────────
             const proxyUrls = {};
             for (const p of generated.ports) {
@@ -1143,9 +1643,16 @@ class AppInstaller {
             }
         }
         const envLines = [];
+        const secretDefaults = generated.secretDefaults ?? {};
         for (const key of generated.secretKeys) {
-            const val = (merged[key] ?? '').replace(/[\r\n]/g, '');
-            envLines.push(`${key}=${val}`);
+            // Precedence: operator-supplied value → declared default → empty. An
+            // empty operator value (UI always sends the field, possibly blank) falls
+            // through to the default, matching how generated keys treat '' as unset.
+            const provided = merged[key];
+            const raw = provided !== undefined && provided !== ''
+                ? provided
+                : secretDefaults[key] ?? '';
+            envLines.push(`${key}=${raw.replace(/[\r\n]/g, '')}`);
         }
         const generatedKeySet = new Set(generated.generatedKeys.map((g) => g.key));
         const generatedNames = [];
@@ -1453,6 +1960,152 @@ class AppInstaller {
             return [];
         }
     }
+    /**
+     * Image references (repo:tag) an app's compose file declares, e.g.
+     * "ghcr.io/x/monitor:1.1". Used to reclaim a superseded *pulled* tag on
+     * update — a tag bump the image-ID reclaim misses, because a pulled image
+     * carrying more than one repo tag cannot be removed by ID (issue #302).
+     * Best-effort — returns [] on any error.
+     */
+    captureComposeImageRefs(appName, dir) {
+        try {
+            const { stdout } = this.run(['docker', 'compose', '-p', appName, 'config', '--images'], dir, 15000);
+            return [...new Set(stdout.trim().split('\n').map((s) => s.trim()).filter(Boolean))];
+        }
+        catch {
+            return [];
+        }
+    }
+    // ─── Docker housekeeping (issue #302) ───────────────────────────────────────
+    /** Resolve the housekeeping toggles against their conservative defaults. */
+    resolveHousekeeping() {
+        const hk = this.housekeepingConfig ?? {};
+        return {
+            buildCachePrune: hk.buildCachePrune ?? true,
+            buildCacheMaxAgeHours: hk.buildCacheMaxAgeHours ?? 168,
+            danglingImagePrune: hk.danglingImagePrune ?? true,
+        };
+    }
+    /**
+     * Best-effort Docker housekeeping after a successful build (install + update).
+     * Reclaims ONLY provably-unreferenced junk:
+     *   - build cache older than the configured window — time-filtered on purpose
+     *     so a concurrent build's fresh layers are never evicted;
+     *   - dangling `<none>` images with no container (safe by definition).
+     * Gated by config (all toggles off ⇒ no prune calls). Every prune is wrapped
+     * so a failure NEVER fails the parent install/update. Enforces the safety
+     * floor: no `-a`, no `system prune`, no volume prune (issue #302).
+     */
+    pruneAfterBuild(job) {
+        const hk = this.resolveHousekeeping();
+        if (hk.buildCachePrune) {
+            try {
+                this.run(['docker', 'builder', 'prune', '-f', '--filter', `until=${hk.buildCacheMaxAgeHours}h`], os.tmpdir(), 120000);
+                this.log(job, `Build cache pruned (older than ${hk.buildCacheMaxAgeHours}h)`);
+            }
+            catch (err) {
+                this.log(job, `Build-cache prune skipped (non-fatal): ${err.message}`);
+            }
+        }
+        if (hk.danglingImagePrune) {
+            try {
+                // `image prune -f` (NEVER `-a`) — removes only untagged <none> layers
+                // with no container, so tagged images of other stopped apps survive.
+                this.run(['docker', 'image', 'prune', '-f'], os.tmpdir(), 120000);
+                this.log(job, 'Dangling images pruned');
+            }
+            catch (err) {
+                this.log(job, `Dangling-image prune skipped (non-fatal): ${err.message}`);
+            }
+        }
+    }
+    /**
+     * Reclaim this app's own superseded pulled tags after an update (issue #302).
+     * The image-ID reclaim misses a pulled-tag bump (e.g. monitor:1.1 → :1.2.0):
+     * a pulled image with more than one repo tag can't be removed by ID. Remove
+     * exactly the app's prior refs that the NEW stack no longer references.
+     * `image rm <ref>` fails safely (and is caught) when a container still uses
+     * the image, so an in-use image is never yanked. Only this app's own tags are
+     * ever touched — never a blanket prune.
+     */
+    reclaimSupersededTags(job, oldImageRefs, newImageRefs) {
+        const newRefSet = new Set(newImageRefs);
+        for (const ref of oldImageRefs) {
+            if (newRefSet.has(ref))
+                continue; // still used by new stack — keep
+            try {
+                this.run(['docker', 'image', 'rm', ref], os.tmpdir(), 60000);
+                this.log(job, `Reclaimed superseded image tag ${ref}`);
+            }
+            catch {
+                /* in use / already gone — non-fatal */
+            }
+        }
+    }
+    /** Read-only reclaim report (issue #302). Best-effort; never mutates state. */
+    housekeepingReport() {
+        return this.buildHousekeepingReport();
+    }
+    /**
+     * Execute the SAFE reclaim (build cache + dangling images only) and return a
+     * fresh report. This is an explicit operator action, so it runs regardless of
+     * the auto-path config toggles — but it still honors the fixed safety floor:
+     * never `-a`, never `system prune`, never a volume/auto delete. The build-cache
+     * window uses the configured value (default 168h).
+     */
+    housekeepingPrune() {
+        const hk = this.resolveHousekeeping();
+        const pruned = { buildCache: false, danglingImages: false };
+        try {
+            this.run(['docker', 'builder', 'prune', '-f', '--filter', `until=${hk.buildCacheMaxAgeHours}h`], os.tmpdir(), 120000);
+            pruned.buildCache = true;
+        }
+        catch {
+            /* best-effort */
+        }
+        try {
+            this.run(['docker', 'image', 'prune', '-f'], os.tmpdir(), 120000);
+            pruned.danglingImages = true;
+        }
+        catch {
+            /* best-effort */
+        }
+        return { mode: 'prune', pruned, report: this.buildHousekeepingReport() };
+    }
+    buildHousekeepingReport() {
+        return {
+            buildCacheReclaimable: this.readBuildCacheReclaimable(),
+            danglingImageCount: this.splitLines(this.safeRunStdout(['docker', 'image', 'ls', '--filter', 'dangling=true', '--quiet'])).length,
+            orphanVolumes: this.splitLines(this.safeRunStdout(['docker', 'volume', 'ls', '--filter', 'dangling=true', '--quiet'])),
+        };
+    }
+    /** `docker` stdout, or '' on any error (report helpers must never throw). */
+    safeRunStdout(args, timeoutMs = 30000) {
+        try {
+            return this.run(args, os.tmpdir(), timeoutMs).stdout;
+        }
+        catch {
+            return '';
+        }
+    }
+    splitLines(s) {
+        return s.trim().split('\n').map((x) => x.trim()).filter(Boolean);
+    }
+    /** Reclaimable build-cache size from the `docker system df` "Build Cache" row. */
+    readBuildCacheReclaimable() {
+        const out = this.safeRunStdout([
+            'docker', 'system', 'df', '--format', '{{.Type}}\t{{.Reclaimable}}',
+        ]);
+        for (const line of this.splitLines(out)) {
+            const tab = line.indexOf('\t');
+            if (tab < 0)
+                continue;
+            const type = line.slice(0, tab).trim().toLowerCase();
+            if (type.includes('build cache'))
+                return line.slice(tab + 1).trim();
+        }
+        return '';
+    }
     run(args, cwd, timeoutMs = 30000) {
         const opts = {
             encoding: 'utf-8',