code review, lockfiles, and other fixes

Author: shuv1337

.github/workflows/config.yml

@@ -0,0 +1,31 @@
+name: config-changes
+
+on:
+  push:
+    paths:
+      - "packages/opencode/src/config/**"
+      - "packages/opencode/test/config/**"
+      - "docs/config-hot-reload.md"
+  pull_request:
+    paths:
+      - "packages/opencode/src/config/**"
+      - "packages/opencode/test/config/**"
+      - "docs/config-hot-reload.md"
+  workflow_dispatch:
+
+jobs:
+  config:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: ./.github/actions/setup-bun
+
+      - name: Run config validations
+        env:
+          CI: true
+        run: |
+          bun test packages/opencode/test/config/*
+          bun run --cwd packages/opencode typecheck

IMPLEMENTATION_SUMMARY.md

@@ -31,6 +31,12 @@ INFO  service=config.invalidation scope=global directory=/tmp/theme-only-oMAT6r
 
 - That reduces invalidation fan-out from 4+ subsystems down to one, eliminating roughly 75% of the work for theme edits. The improvement is enforced by the updated test suite (`bun test packages/opencode/test/config/write.test.ts packages/opencode/test/config/hot-reload.test.ts`).
 
+### Backup Retention Cleanup
+
+- Added `cleanupOldBackups` in `packages/opencode/src/config/backup.ts`, which deletes `.bak-*` files older than a configurable TTL (default 7 days via `OPENCODE_CONFIG_BACKUP_TTL_DAYS`).
+- The cleanup routine runs during instance bootstrap and after every successful `Config.update`, ensuring disk usage stays bounded.
+- Logged deletion counts make it easy to monitor retention behavior; see `packages/opencode/test/config/backup.test.ts` for TTL enforcement coverage.
+
 ## What Was Implemented
 
 ### Phase 0: State System Enhancements
@@ -133,10 +139,15 @@ INFO  service=config.invalidation scope=global directory=/tmp/theme-only-oMAT6r
 
 - **Type**: Boolean (`"true"` | `"false"`)
 - **Default**: `"false"`
-- **Purpose**: Debug flag (not yet fully implemented)
+- **Purpose**: Debug telemetry for targeted invalidation
 - **Behavior**:
-  - `"true"`: Log complete diff objects for troubleshooting
-  - `"false"`: Log only diff section names
+  - `"true"`: Emit `config.invalidate.diff` debug records with the full diff payload plus scope/directory so every config write can be correlated with its invalidation targets.
+  - `"false"`: Continue logging only section and target names through the existing `config.invalidate.start/complete` info lines.
+
+## Documentation
+
+- Authored `docs/config-hot-reload.md` to describe each feature flag, backup TTL, distributed locking strategy, and the `config.invalidate.diff` toggle so operators know how to interpret logs and adjust retention.
+- Updated `README.md` configuration guidance to cover automatic backup cleanup decisions, highlight the hot-reload feature, and link to the new document for deeper guidance.
 
 ## Usage
 
@@ -218,6 +229,11 @@ bun test test/config/hot-reload.test.ts
 bun run --cwd packages/opencode typecheck
 ```
 
+## CI
+
+- Added `.github/workflows/config.yml`, which runs on pushes or pull requests that touch `packages/opencode/src/config/**`, `packages/opencode/test/config/**`, or `docs/config-hot-reload.md`.
+- The workflow executes `bun test packages/opencode/test/config/*` and `bun run --cwd packages/opencode typecheck` so config changes receive the extra validation steps required before merging.
+
 ## What's Not Yet Implemented (Future Work)
 
 According to the original plan, the following are not yet complete:

bun.lock

@@ -0,0 +1,49 @@
+# Config Hot Reload
+
+This document summarizes the configuration, locking, backup, and observability story around `packages/opencode/src/config`, so you can safely exercise hot reload in development and production.
+
+## Overview
+
+With `OPENCODE_CONFIG_HOT_RELOAD=true` OpenCode switches from a full `Instance.dispose()` restart to a targeted invalidation sweep that touches only the subsystems named in `ConfigInvalidation.apply`. That lets editors, providers, the MCP bus, and language services keep running while only `config`, `provider`, `lsp`, `plugin`, `tool-registry`, and other affected states refresh.
+
+Hot reload is gated by feature flags so you can stage it gradually.
+
+## Feature Flags
+
+- `OPENCODE_CONFIG_HOT_RELOAD` (default `"false"`): Enable targeted invalidation across project/global updates. Set this before launching the server or CLI.
+- `OPENCODE_FULL_DISPOSE_ON_CONFIG_UPDATE` (default `"false"`): Force the legacy `Instance.dispose()` behaviour even when hot reload is enabled, useful for troubleshooting.
+- `OPENCODE_CONFIG_INVALIDATION_LOG_DIFF` (default `"false"`): Emit `config.invalidate.diff` debug logs that include `scope`, `directory`, and the raw `ConfigDiff` so you can inspect which sections changed before the invalidation tasks run.
+- `OPENCODE_CONFIG_BACKUP_TTL_DAYS` (default `7`): How long `.bak-<timestamp>` files should be retained. Shorten if disk space is tight, or extend for longer history.
+
+## Backup Cleanup
+
+Every config update writes a timestamped `.bak-<iso-timestamp>` backup next to the target config file. The cleanup routine in `packages/opencode/src/config/backup.ts` runs during bootstrap and immediately after each successful `Config.update`, deleting backups older than `OPENCODE_CONFIG_BACKUP_TTL_DAYS`. This keeps disk growth bounded without manual maintenance.
+
+## Locking & Concurrency
+
+Writes are protected by `proper-lockfile` in `packages/opencode/src/config/lock.ts`. Before acquiring a lock OpenCode ensures the lock file exists and configures retries (`retries`, `minTimeout`, `maxTimeout`) with stale detection (`stale = 5s`, `update = stale / 2`). On startup `cleanupStaleLocks` scans for residual `.lock` directories, verifies `lockfile.check`, and removes orphaned directories while logging the cleanup. The same lock is reused for project/global config writes, so simultaneous `Config.update` calls serialize safely.
+
+## Updating Config
+
+Apply config changes via `PATCH /config` (defaults to project scope) or `PATCH /config?scope=global` (for global overrides). Example:
+
+```bash
+export OPENCODE_CONFIG_HOT_RELOAD=true
+
+curl -X PATCH http://localhost:4096/config \
+  -H "Content-Type: application/json" \
+  -d '{"model": "anthropic/claude-3-5-sonnet"}'
+```
+
+The API merges the payload with the existing `Info` schema, emits `config.updated` via `Bus`, and publishes a `ConfigDiff` that `ConfigInvalidation.apply` uses to derive invalidation targets.
+
+## Logs & Diagnostics
+
+- `config.invalidate.stateRefreshed` fires whenever a new `Instance` context loads the latest config.
+- `config.invalidate.start`/`config.invalidate.complete` include `scope`, `directory`, `sections`, and `targets`.
+- Enable `OPENCODE_CONFIG_INVALIDATION_LOG_DIFF=true` to capture `config.invalidate.diff`, which adds the entire diff object to the log entry so you can see every changed section before invalidation begins.
+- Any fallback to the JSONC writer still logs warnings via `config.write.fallback`, and backup cleanup emits `config.backup.cleanup` with deletion counts.
+
+## Testing & CI
+
+Config updates now have dedicated regression suites in `packages/opencode/test/config`. The new `.github/workflows/config.yml` workflow runs `bun test packages/opencode/test/config/*` and `bun run --cwd packages/opencode typecheck` whenever config sources, docs, or tests change, ensuring the hot reload story is fully exercised before merging.

docs/config-hot-reload.md

@@ -50,6 +50,7 @@
   },
   "devDependencies": {
     "@tsconfig/bun": "catalog:",
+    "@types/proper-lockfile": "4.1.4",
     "husky": "9.1.7",
     "prettier": "3.6.2",
     "sst": "3.17.23",

package.json

@@ -75,6 +75,7 @@
     "minimatch": "10.0.3",
     "open": "10.1.2",
     "partial-json": "0.1.7",
+    "proper-lockfile": "4.1.2",
     "remeda": "catalog:",
     "solid-js": "catalog:",
     "strip-ansi": "7.1.2",

packages/opencode/package.json

@@ -1,4 +1,25 @@
 import fs from "fs/promises"
+import path from "path"
+import { Log } from "@/util/log"
+
+const log = Log.create({ service: "config.backup" })
+const DAY_MS = 24 * 60 * 60 * 1000
+const DEFAULT_TTL_DAYS = 7
+
+const envTtlDays = Number(process.env.OPENCODE_CONFIG_BACKUP_TTL_DAYS)
+const CONFIG_BACKUP_TTL_MS =
+  Number.isFinite(envTtlDays) && envTtlDays > 0 ? envTtlDays * DAY_MS : DEFAULT_TTL_DAYS * DAY_MS
+
+interface CleanupOptions {
+  ttlMs?: number
+}
+
+function resolveTtlMs(override?: number) {
+  if (typeof override === "number" && Number.isFinite(override) && override > 0) {
+    return override
+  }
+  return CONFIG_BACKUP_TTL_MS
+}
 
 export async function createBackup(filepath: string): Promise<string> {
   const timestamp = new Date().toISOString().replace(/[:.]/g, "-")
@@ -15,3 +36,47 @@ export async function restoreBackup(backupPath: string, targetPath: string): Pro
   await fs.copyFile(backupPath, targetPath)
   await fs.unlink(backupPath)
 }
+
+export async function cleanupOldBackups(filepath: string, options?: CleanupOptions): Promise<number> {
+  const ttlMs = resolveTtlMs(options?.ttlMs)
+  const directory = path.dirname(filepath)
+  const base = path.basename(filepath)
+  const entries = await fs.readdir(directory).catch(() => [])
+  const now = Date.now()
+  let deleted = 0
+
+  for (const entry of entries) {
+    if (!entry.startsWith(`${base}.bak-`)) {
+      continue
+    }
+
+    const candidate = path.join(directory, entry)
+    const stats = await fs.stat(candidate).catch(() => undefined)
+    if (!stats) {
+      continue
+    }
+
+    if (now - stats.mtimeMs <= ttlMs) {
+      continue
+    }
+
+    try {
+      await fs.unlink(candidate)
+      deleted += 1
+    } catch (error) {
+      log.warn("backup.cleanup.unlinkFailed", {
+        backupPath: candidate,
+        error: String(error),
+      })
+    }
+  }
+
+  if (deleted > 0) {
+    log.info("backup.cleanup.completed", {
+      filepath,
+      deleted,
+    })
+  }
+
+  return deleted
+}