Merge branch 'worktree-llm-dynamic-config' into worktree-llm-web-config

# Conflicts:
#	docs/cordis-catalog/services.md
#	docs/core-data-structures/core.i18n.yaml
#	docs/event-producer-consumer.md
#	examples/headless-agent/tests/headless.snapshot.ts
#	examples/headless-agent/tests/snapshots/missing-credential/stream-json.expected.jsonl
#	packages/llm/llm-deepseek/README.i18n.yaml
#	packages/llm/llm-deepseek/src/index.ts
#	packages/llm/llm-pi-ai/README.i18n.yaml
#	packages/llm/llm-pi-ai/src/index.ts
#	packages/llm/llm/README.i18n.yaml
#	packages/llm/llm/src/index.ts

packages/settings/settings-local/src/index.ts

@@ -10,10 +10,10 @@
 import { Context, Service } from 'cordis'
 import z from 'schemastery'
 import { watch as chokidarWatch } from 'chokidar'
-import { mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises'
+import { mkdir, readFile } from 'node:fs/promises'
 import { dirname, extname, join, resolve } from 'node:path'
 import { Document, parseDocument } from 'yaml'
-import { writeFileAtomic } from '@deepseek-ai/dsh-atomic-write'
+import { withFileLock, writeFileAtomic } from '@deepseek-ai/dsh-atomic-write'
 import { resolveDshHome } from '@deepseek-ai/dsh-paths'
 import { Settings, deepEqualJson, type SettingsNamespace } from '@deepseek-ai/dsh-settings'
 
@@ -96,23 +96,6 @@ function isENOENT(error: unknown): boolean {
   return (error as NodeJS.ErrnoException | null)?.code === 'ENOENT'
 }
 
-/** Whether an exclusive create failed because the path already exists. */
-function isEEXIST(error: unknown): boolean {
-  return (error as NodeJS.ErrnoException | null)?.code === 'EEXIST'
-}
-
-/**
- * Writer-lock protocol constants. These are robustness invariants of the
- * cross-process write protocol, not deployment tunables: a holder rewrites one
- * small document in milliseconds, so contention resolves well inside the
- * retry deadline, and a lock older than the stale age can only belong to a
- * crashed holder.
- */
-const LOCK_RETRY_INITIAL_MS = 20
-const LOCK_RETRY_MAX_MS = 200
-const LOCK_TIMEOUT_MS = 2_000
-const LOCK_STALE_MS = 5_000
-
 /** File-backed settings provider (`settings.yaml`/`.json`). */
 export class SettingsLocal extends Settings {
   static Config: z<Config> = z.object({
@@ -199,8 +182,9 @@ export class SettingsLocal extends Settings {
   private async persistSection(ns: SettingsNamespace, section: Record<string, unknown>): Promise<void> {
     // The writer lock's exclusive create needs the parent to exist before
     // writeFileAtomic gets its own chance to create it.
-    await mkdir(dirname(this.spec.filename), { recursive: true })
-    await this.withWriterLock(async () => {
+    // 0700: the harness home holds user-private documents.
+    await mkdir(dirname(this.spec.filename), { recursive: true, mode: 0o700 })
+    await withFileLock(this.spec.filename, async () => {
       // Read-modify-write: fold in any on-disk state this process has not
       // observed yet — an external edit still inside the watcher debounce
       // window, a change the watcher missed, or another process's write — so
@@ -212,59 +196,13 @@ export class SettingsLocal extends Settings {
         ? this.renderYaml(ns, section)
         : this.renderJson(ns, section)
       // 0600: a document that may hold personal values is never world-readable.
-      await writeFileAtomic(this.spec.filename, output, { mode: 0o600 })
+      await writeFileAtomic(this.spec.filename, output, { mode: 0o600, dirMode: 0o700 })
       this.text = output
-    })
-  }
-
-  /**
-   * Hold the cross-process writer lock around one read-render-rename cycle.
-   * The lock is a `wx`-created sibling (`<file>.lock`); the rename-based
-   * commit keeps readers lock-free, so only writers contend. A lock older
-   * than {@link LOCK_STALE_MS} is a crashed holder and is broken with a
-   * warning; a live holder past {@link LOCK_TIMEOUT_MS} fails the write.
-   */
-  private async withWriterLock<T>(operation: () => Promise<T>): Promise<T> {
-    const lockPath = `${this.spec.filename}.lock`
-    const deadline = Date.now() + LOCK_TIMEOUT_MS
-    let delay = LOCK_RETRY_INITIAL_MS
-    for (;;) {
-      try {
-        await writeFile(lockPath, `${process.pid}\n`, { mode: 0o600, flag: 'wx' })
-        break
-      } catch (error) {
-        if (!isEEXIST(error)) throw error
-      }
-      const ageMs = await this.lockAgeMs(lockPath)
-      // The holder released between the failed create and the stat: the lock
-      // is free right now, so retry without burning backoff or deadline.
-      if (ageMs === undefined) continue
-      if (ageMs > LOCK_STALE_MS) {
+    }, {
+      onStaleBreak: (lockPath) => {
         this.ctx.logger.warn('settings-local: breaking a stale writer lock at %s', lockPath)
-        await rm(lockPath, { force: true })
-        continue
-      }
-      if (Date.now() >= deadline) {
-        throw new Error(`settings-local: timed out waiting for the writer lock at ${lockPath}`)
-      }
-      await new Promise(resolve => setTimeout(resolve, delay))
-      delay = Math.min(delay * 2, LOCK_RETRY_MAX_MS)
-    }
-    try {
-      return await operation()
-    } finally {
-      await rm(lockPath, { force: true })
-    }
-  }
-
-  /** Age of the writer lock, or `undefined` when it vanished after a failed create. */
-  private async lockAgeMs(lockPath: string): Promise<number | undefined> {
-    try {
-      return Date.now() - (await stat(lockPath)).mtimeMs
-    } catch (error) {
-      if (!isENOENT(error)) throw error
-      return undefined
-    }
+      },
+    })
   }
 
   override async* [Service.init](): AsyncGenerator<() => Promise<void> | void, void, void> {

packages/settings/settings/src/index.ts

@@ -590,6 +590,20 @@ export abstract class Settings extends Service {
   }
 }
 
+/**
+ * Value mirror of the `FiberState` members {@link isUnloading} compares
+ * against: a const enum has no runtime object to import, and the value is
+ * needed at runtime (same rationale as the CLI boot driver's mirror).
+ */
+const FIBER_DISPOSED = 4
+const FIBER_UNLOADING = 5
+
+/** Whether the consumer's own fiber is tearing down (not just losing the settings service). */
+function isUnloading(ctx: Context): boolean {
+  const state: number = ctx.fiber.state
+  return state === FIBER_UNLOADING || state === FIBER_DISPOSED
+}
+
 /** Hooks a consumer hands to {@link installSettingsSection}. */
 export interface SettingsSectionHooks<T> {
   /**
@@ -630,6 +644,13 @@ export function installSettingsSection<T>(
     const scope = sctx.settings.register(ns, schema, { base: entry })
     hooks.setSource(() => scope.get())
     sctx.effect(() => () => {
+      // This disposer runs for two different reasons. A settings provider
+      // detaching leaves the consumer running, so it must fall back to its
+      // composition entry and re-judge what it derived. The consumer's own
+      // unload runs it too — and there `onChange` would re-register routes
+      // and touch resources the teardown is releasing, so the fallback is
+      // pointless and the notification actively harmful.
+      if (isUnloading(ctx)) return
       hooks.setSource(() => entry)
       hooks.onChange()
     })

packages/settings/settings/tests/settings.spec.ts

@@ -694,4 +694,34 @@ describe('installSettingsSection', () => {
     })
     expect(current()).toEqual({ theme: 'entry' })
   })
+
+  it('stays silent when the consumer itself unloads', async () => {
+    const { ctx } = await boot({ doc: { 'helper-ns': { theme: 'user' } } })
+    const entry = { theme: 'entry' }
+    let current: () => { theme: string } = () => entry
+    const changes: string[] = []
+    const consumer = ctx.plugin({
+      inject: ['settings'],
+      apply: (child: Context) => {
+        installSettingsSection(child, settingsNamespace('helper-ns'), HelperSchema, entry, {
+          setSource: (source) => {
+            current = source
+          },
+          onChange: () => {
+            changes.push(current().theme)
+          },
+        })
+      },
+    })
+    await consumer
+    await vi.waitFor(() => {
+      expect(changes).toEqual(['user'])
+    })
+
+    // The consumer's own teardown must not re-derive anything: an onChange
+    // here would re-register routes and touch resources being released.
+    await consumer.dispose()
+    await new Promise(resolve => setTimeout(resolve, 20))
+    expect(changes).toEqual(['user'])
+  })
 })