@yeaft/webchat-agent 0.1.493 → 0.1.495

package/connection/message-router.js

@@ -24,8 +24,8 @@ import {
 import { sendToServer, flushMessageBuffer } from './buffer.js';
 import { handleRestartAgent, handleUpgradeAgent } from './upgrade.js';
 import { loadMcpServers, updateMcpConfig } from '../mcp.js';
-import { getLlmConfig, updateLlmConfig } from '../unify/config-api.js';
-import { handleUnifyChat, handleUnifyModeSwitch, handleUnifyModelSwitch, resetUnifySession, handleUnifyLoadHistory, handleUnifyMergeThread } from '../unify/web-bridge.js';
+import { getLlmConfig, updateLlmConfig, getUnifySettings, updateUnifySettings } from '../unify/config-api.js';
+import { handleUnifyChat, handleUnifyModeSwitch, handleUnifyModelSwitch, resetUnifySession, handleUnifyLoadHistory, handleUnifyMergeThread, handleUnifyForkThread } from '../unify/web-bridge.js';
 
 export async function handleMessage(msg) {
   switch (msg.type) {
@@ -320,6 +320,30 @@ export async function handleMessage(msg) {
       break;
     }
 
+    // task-318: Unify runtime settings (thread concurrency + auto-archive).
+    // Read/write the nested `unify` section of config.json — LLM fields
+    // untouched. On update we broadcast a `unify_settings_updated` event
+    // so the UI reflects the new values and in-process consumers
+    // (ThreadEngineRegistry, ThreadStore) can reload their caps.
+    case 'get_unify_settings': {
+      const settings = getUnifySettings(ctx.CONFIG?.yeaftDir);
+      sendToServer({ type: 'unify_settings', ...settings });
+      break;
+    }
+
+    case 'update_unify_settings': {
+      const result = updateUnifySettings(msg.settings || msg.config || {}, ctx.CONFIG?.yeaftDir);
+      // Let live consumers pick up the new caps without a session restart.
+      // The registry/store are created per-session; we update the exported
+      // accessors so subsequent dispatches see the new values.
+      if (!result.error && ctx.unifyRuntimeSettings) {
+        ctx.unifyRuntimeSettings.maxConcurrentThreads = result.maxConcurrentThreads;
+        ctx.unifyRuntimeSettings.autoArchiveIdleDays = result.autoArchiveIdleDays;
+      }
+      sendToServer({ type: 'unify_settings_updated', ...result });
+      break;
+    }
+
     // Unify — independent chat via Engine
     case 'unify_chat':
       await handleUnifyChat(msg);
@@ -345,6 +369,10 @@ export async function handleMessage(msg) {
       handleUnifyMergeThread(msg);
       break;
 
+    case 'unify_fork_thread':
+      handleUnifyForkThread(msg);
+      break;
+
     // Expert roles definition (for ExpertPanel detail view)
     case 'get_expert_roles': {
       const { getExpertRolesDefinition } = await import('../expert-roles.js');

package/context.js

@@ -30,4 +30,9 @@ export default {
   sendToServer: null,
   // 由 index.js 注册的配置保存函数
   saveConfig: null,
+  // task-318: live Unify runtime caps. Mutated in-place by
+  // `update_unify_settings` so in-process consumers (web-bridge) can
+  // pick up the new values without a session restart. `null` until the
+  // Unify session has finished loading.
+  unifyRuntimeSettings: null,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "0.1.493",
+  "version": "0.1.495",
   "description": "Remote agent for Yeaft WebChat — connects worker machines to the central server",
   "main": "index.js",
   "type": "module",

package/unify/config-api.js

@@ -12,6 +12,7 @@ import { existsSync, readFileSync, writeFileSync } from 'fs';
 import { join } from 'path';
 import { DEFAULT_YEAFT_DIR } from './init.js';
 import { normalizeProviderModels, serializeModelForPersistence } from './models.js';
+import { normaliseUnifySection } from './config.js';
 
 /**
  * Read the LLM-relevant portion of config.json.
@@ -126,3 +127,91 @@ export function updateLlmConfig(update, dir) {
     language: existing.language || 'en',
   };
 }
+
+// ─── Unify runtime settings (task-318) ────────────────────────────
+
+/**
+ * Read the Unify-section of config.json. Returns defaults when the file
+ * or section is absent. Callers (UI, registry, ThreadStore) rely on a
+ * stable shape — `normaliseUnifySection` guarantees that.
+ *
+ * @param {string} [dir] — Yeaft data directory
+ * @returns {{ maxConcurrentThreads: number, autoArchiveIdleDays: number } | { error: string }}
+ */
+export function getUnifySettings(dir) {
+  const root = dir || process.env.YEAFT_DIR || DEFAULT_YEAFT_DIR;
+  const configPath = join(root, 'config.json');
+  if (!existsSync(configPath)) return normaliseUnifySection(null);
+  try {
+    const raw = readFileSync(configPath, 'utf8');
+    const json = JSON.parse(raw);
+    return normaliseUnifySection(json.unify);
+  } catch (e) {
+    return { error: `Failed to read config.json: ${e.message}` };
+  }
+}
+
+/**
+ * Update the Unify-section of config.json. Merges into existing config
+ * (LLM provider / model fields are untouched) and validates each field:
+ * `maxConcurrentThreads` must be 1..50, `autoArchiveIdleDays` must be
+ * 1..3650. Invalid values are rejected outright so the UI sees an error
+ * rather than silently reverting — a silent revert would make "I set it
+ * to 100 and nothing happened" impossible to debug.
+ *
+ * @param {{ maxConcurrentThreads?: number, autoArchiveIdleDays?: number }} update
+ * @param {string} [dir]
+ * @returns {{ maxConcurrentThreads: number, autoArchiveIdleDays: number } | { error: string }}
+ */
+export function updateUnifySettings(update, dir) {
+  const root = dir || process.env.YEAFT_DIR || DEFAULT_YEAFT_DIR;
+  const configPath = join(root, 'config.json');
+
+  if (!update || typeof update !== 'object') {
+    return { error: 'update payload required' };
+  }
+
+  // Validate before touching the file. We enforce the same clamp bounds
+  // that `normaliseUnifySection` uses for reads so round-trip is stable.
+  if (update.maxConcurrentThreads !== undefined) {
+    const n = Number(update.maxConcurrentThreads);
+    if (!Number.isFinite(n) || n < 1 || n > 50) {
+      return { error: 'maxConcurrentThreads must be between 1 and 50' };
+    }
+  }
+  if (update.autoArchiveIdleDays !== undefined) {
+    const n = Number(update.autoArchiveIdleDays);
+    if (!Number.isFinite(n) || n < 1 || n > 3650) {
+      return { error: 'autoArchiveIdleDays must be between 1 and 3650' };
+    }
+  }
+
+  // Read existing config (preserve LLM and other top-level fields).
+  let existing = {};
+  if (existsSync(configPath)) {
+    try {
+      existing = JSON.parse(readFileSync(configPath, 'utf8'));
+    } catch {
+      existing = {};
+    }
+  }
+
+  const prev = normaliseUnifySection(existing.unify);
+  const merged = {
+    maxConcurrentThreads: update.maxConcurrentThreads !== undefined
+      ? Math.floor(Number(update.maxConcurrentThreads))
+      : prev.maxConcurrentThreads,
+    autoArchiveIdleDays: update.autoArchiveIdleDays !== undefined
+      ? Math.floor(Number(update.autoArchiveIdleDays))
+      : prev.autoArchiveIdleDays,
+  };
+  existing.unify = merged;
+
+  try {
+    writeFileSync(configPath, JSON.stringify(existing, null, 2) + '\n', 'utf8');
+  } catch (e) {
+    return { error: `Failed to write config.json: ${e.message}` };
+  }
+
+  return merged;
+}

package/unify/config.js

@@ -33,6 +33,15 @@ const DEFAULTS = {
   maxOutputTokens: 16384,
   messageTokenBudget: 8192,
   maxContinueTurns: 3,
+  // task-318: Unify-specific runtime caps. `maxConcurrentThreads` gates
+  // how many ThreadEngineRegistry instances may be live at once; dispatch
+  // refuses new threads beyond this. The count INCLUDES the always-on
+  // `main` thread, so the default 6 gives users 5 user-initiated threads
+  // on top of main. `autoArchiveIdleDays` is consumed by ThreadStore's
+  // idle-archive pass (task-317 will wire the pass itself; here we just
+  // plumb the knob through so the UI can set it).
+  unifyMaxConcurrentThreads: 6,
+  unifyAutoArchiveIdleDays: 30,
 };
 
 // ─── config.json reader ─────────────────────────────────────────
@@ -134,6 +143,52 @@ function isTruthy(val) {
   return val === '1' || val === 'true' || val === 'yes';
 }
 
+/**
+ * Clamp and normalise the `unify` config section. Missing / non-numeric
+ * inputs fall back to the DEFAULTS; numeric-but-out-of-range inputs are
+ * *clamped* to the valid range rather than silently reverting to the
+ * default. This keeps the read path aligned with `updateUnifySettings`,
+ * which rejects out-of-range writes up front — a hand-edited
+ * `config.json` with `maxConcurrentThreads: 100` now loads as 50 (the
+ * nearest valid value) instead of collapsing back to 5.
+ *
+ * Exported for tests and for `config-api.js` to share the same clamp
+ * bounds via `clampUnifyField`.
+ *
+ * @param {any} raw — jsonConfig.unify (may be undefined / malformed)
+ * @returns {{ maxConcurrentThreads: number, autoArchiveIdleDays: number }}
+ */
+export function normaliseUnifySection(raw) {
+  const out = {
+    maxConcurrentThreads: DEFAULTS.unifyMaxConcurrentThreads,
+    autoArchiveIdleDays: DEFAULTS.unifyAutoArchiveIdleDays,
+  };
+  if (!raw || typeof raw !== 'object') return out;
+  const mc = clampUnifyField(raw.maxConcurrentThreads, 'maxConcurrentThreads');
+  if (mc !== null) out.maxConcurrentThreads = mc;
+  const ad = clampUnifyField(raw.autoArchiveIdleDays, 'autoArchiveIdleDays');
+  if (ad !== null) out.autoArchiveIdleDays = ad;
+  return out;
+}
+
+/**
+ * Clamp a single unify field to its valid range. Returns `null` if the
+ * input is not a finite number (so callers can treat it as "not set" and
+ * keep the previous value). Centralises the bounds used on both read
+ * (`normaliseUnifySection`) and write (`updateUnifySettings` validation).
+ *
+ * @param {unknown} v
+ * @param {'maxConcurrentThreads'|'autoArchiveIdleDays'} field
+ * @returns {number | null}
+ */
+export function clampUnifyField(v, field) {
+  if (v === null || v === undefined) return null;
+  const n = Number(v);
+  if (!Number.isFinite(n)) return null;
+  const [lo, hi] = field === 'maxConcurrentThreads' ? [1, 50] : [1, 3650];
+  return Math.min(hi, Math.max(lo, Math.floor(n)));
+}
+
 /**
  * Build config from legacy config.md + .env + env vars.
  * @deprecated — used only when config.json doesn't exist.
@@ -160,6 +215,8 @@ function loadLegacyConfig(dir, overrides) {
     maxOutputTokens: overrides.maxOutputTokens ?? fileConfig.maxOutputTokens ?? DEFAULTS.maxOutputTokens,
     messageTokenBudget: overrides.messageTokenBudget ?? (env.YEAFT_MESSAGE_TOKEN_BUDGET ? parseInt(env.YEAFT_MESSAGE_TOKEN_BUDGET, 10) : null) ?? fileConfig.messageTokenBudget ?? DEFAULTS.messageTokenBudget,
     maxContinueTurns: overrides.maxContinueTurns ?? fileConfig.maxContinueTurns ?? DEFAULTS.maxContinueTurns,
+    // task-318: legacy path never had the `unify` section — defaults.
+    unify: normaliseUnifySection(null),
     providers: null,
     primaryModel: null,
     fastModel: null,
@@ -252,6 +309,10 @@ export function loadConfig(overrides = {}) {
     messageTokenBudget: overrides.messageTokenBudget ?? jsonConfig.messageTokenBudget ?? DEFAULTS.messageTokenBudget,
     maxContinueTurns: overrides.maxContinueTurns ?? jsonConfig.maxContinueTurns ?? DEFAULTS.maxContinueTurns,
 
+    // task-318: Unify runtime caps. `unify` is a nested section so we
+    // don't pollute the flat config namespace used by chat/crew code.
+    unify: normaliseUnifySection(jsonConfig.unify),
+
     // Legacy fields (null when using config.json)
     apiKey: overrides.apiKey || null,
     openaiApiKey: null,

package/unify/conversation/persist.js

@@ -175,7 +175,8 @@ export class ConversationStore {
   #coldDir;     // ~/.yeaft/conversation/cold
   #indexPath;   // ~/.yeaft/conversation/index.md
   #compactPath; // ~/.yeaft/conversation/compact.md
-  #nextSeq;     // next message sequence number
+  #nextSeq;     // next message sequence number (global, legacy)
+  #nextSeqByThread; // Map<threadId, number> — per-thread counters (task-314)
 
   /**
    * @param {string} dir — Yeaft root directory (e.g. ~/.yeaft)
@@ -188,6 +189,7 @@ export class ConversationStore {
     this.#indexPath = join(dir, 'conversation', 'index.md');
     this.#compactPath = join(dir, 'conversation', 'compact.md');
     this.#nextSeq = null;
+    this.#nextSeqByThread = new Map();
 
     // Ensure directories exist (graceful on permission errors)
     for (const d of [this.#convDir, this.#msgDir, this.#coldDir]) {
@@ -523,6 +525,201 @@ export class ConversationStore {
     return rewritten;
   }
 
+  /**
+   * Copy every message on `sourceId` whose sequence id is <= `atMessageId`
+   * into new message files stamped with `threadId: targetId` and
+   * `sourceThreadId: sourceId` (symmetric with reassignThread's pill).
+   *
+   * Implementation notes:
+   *  - Scans both hot (`messages/`) and cold (`cold/`) directories so a
+   *    fork off a partially-compacted thread still works.
+   *  - Copies are appended via `append()` so they receive fresh globally
+   *    unique ids (m{NNNN}) — chronological order is preserved because we
+   *    sort by filename before copying.
+   *  - The source is NEVER modified. This is the key invariant separating
+   *    fork from merge.
+   *  - Returns the number of messages copied. `atMessageId` is inclusive.
+   *
+   * @param {string} sourceId
+   * @param {string} targetId
+   * @param {string} atMessageId — e.g. "m0007"; copy stops after this id
+   * @returns {number} copied count
+   */
+  copyThreadUpTo(sourceId, targetId, atMessageId) {
+    if (!sourceId || !targetId || sourceId === targetId) return 0;
+    if (!atMessageId || typeof atMessageId !== 'string') return 0;
+    // task-314 (rev-2 feedback): the target (forked) thread owns its own
+    // per-thread id namespace restarting at m0001. Source files are never
+    // touched, so there is no id-collision across threads (each thread
+    // loads from its own directory or by threadId filter on the shared
+    // legacy dir).
+    const targetDir = this.#threadMsgDir(targetId);
+    try {
+      if (!existsSync(targetDir)) mkdirSync(targetDir, { recursive: true, mode: 0o755 });
+    } catch (err) {
+      if (isPermissionError(err)) return 0;
+      throw err;
+    }
+
+    // Collect source-thread candidate files from both hot + cold dirs.
+    const candidates = [];
+    for (const dir of [this.#coldDir, this.#msgDir]) {
+      if (!existsSync(dir)) continue;
+      let files;
+      try {
+        files = readdirSync(dir).filter(f => f.endsWith('.md'));
+      } catch (err) {
+        if (isPermissionError(err)) continue;
+        throw err;
+      }
+      for (const f of files) candidates.push(join(dir, f));
+    }
+    // Also pick up any already-forked sub-thread dir (chain fork).
+    const sourceSubDir = this.#threadMsgDir(sourceId);
+    if (existsSync(sourceSubDir)) {
+      try {
+        for (const f of readdirSync(sourceSubDir).filter(x => x.endsWith('.md'))) {
+          candidates.push(join(sourceSubDir, f));
+        }
+      } catch (err) {
+        if (!isPermissionError(err)) throw err;
+      }
+    }
+    // Sort by the "m{NNNN}" basename. For chain-fork, sub-thread ids also
+    // restart at m0001 so sorting by basename alone is ambiguous across
+    // dirs; but a given source thread stores messages in exactly ONE place
+    // (either legacy flat dir OR its sub-dir — see below), so ties never
+    // arise. Sorting by (path, seq) is still well-defined.
+    candidates.sort((a, b) => {
+      const ma = a.match(/m(\d+)\.md$/);
+      const mb = b.match(/m(\d+)\.md$/);
+      if (!ma || !mb) return 0;
+      return parseInt(ma[1], 10) - parseInt(mb[1], 10);
+    });
+    const cutoffMatch = atMessageId.match(/^m?(\d+)$/);
+    if (!cutoffMatch) return 0;
+    const cutoffSeq = parseInt(cutoffMatch[1], 10);
+
+    let copied = 0;
+    for (const path of candidates) {
+      const fileMatch = path.match(/m(\d+)\.md$/);
+      if (!fileMatch) continue;
+      const seq = parseInt(fileMatch[1], 10);
+      if (seq > cutoffSeq) continue; // do not break — sub-thread dir mixed in may interleave
+      let raw;
+      try {
+        raw = readFileSync(path, 'utf8');
+      } catch (err) {
+        if (isPermissionError(err)) continue;
+        throw err;
+      }
+      const msg = parseMessage(raw);
+      if (!msg || msg.threadId !== sourceId) continue;
+      // Mint a fresh per-thread id restarting at m0001 under the target
+      // thread's own namespace.
+      const nextSeq = this.#getNextThreadSeq(targetId);
+      const newId = `m${String(nextSeq).padStart(4, '0')}`;
+      const { id: _id, ...rest } = msg;
+      const copy = {
+        ...rest,
+        id: newId,
+        threadId: targetId,
+        sourceThreadId: msg.sourceThreadId || sourceId,
+        time: rest.time || new Date().toISOString(),
+        tokens_est: rest.tokens_est || estimateTokens(rest.content || ''),
+      };
+      const filePath = join(targetDir, `${newId}.md`);
+      try {
+        writeFileSync(filePath, serializeMessage(copy), { encoding: 'utf8', mode: 0o644 });
+        this.#nextSeqByThread.set(targetId, nextSeq + 1);
+        copied += 1;
+      } catch (err) {
+        if (isPermissionError(err)) continue;
+        throw err;
+      }
+    }
+    return copied;
+  }
+
+  /**
+   * Load messages for a specific thread. Reads from the per-thread subdir
+   * (created by forkThread via copyThreadUpTo) if present, otherwise
+   * filters the legacy flat `messages/` + `cold/` dirs by `threadId`.
+   * Results are sorted chronologically by file sequence number.
+   *
+   * @param {string} threadId
+   * @returns {object[]}
+   */
+  load(threadId) {
+    if (!threadId) return [];
+    const subDir = this.#threadMsgDir(threadId);
+    if (existsSync(subDir)) {
+      // Per-thread namespace: just load the whole dir, filtered by
+      // threadId for safety (guards against hand-edited files).
+      const out = [];
+      for (const f of readdirSync(subDir).filter(x => x.endsWith('.md')).sort()) {
+        try {
+          const raw = readFileSync(join(subDir, f), 'utf8');
+          const msg = parseMessage(raw);
+          if (msg && msg.threadId === threadId) out.push(msg);
+        } catch (err) {
+          if (!isPermissionError(err)) throw err;
+        }
+      }
+      return out;
+    }
+    // Legacy: messages live in the flat dir stamped with threadId.
+    const collected = [];
+    for (const dir of [this.#coldDir, this.#msgDir]) {
+      if (!existsSync(dir)) continue;
+      for (const f of readdirSync(dir).filter(x => x.endsWith('.md'))) {
+        try {
+          const raw = readFileSync(join(dir, f), 'utf8');
+          const msg = parseMessage(raw);
+          if (msg && msg.threadId === threadId) collected.push({ msg, f });
+        } catch (err) {
+          if (!isPermissionError(err)) throw err;
+        }
+      }
+    }
+    collected.sort((a, b) => {
+      const ma = a.f.match(/m(\d+)\.md$/);
+      const mb = b.f.match(/m(\d+)\.md$/);
+      return (parseInt(ma?.[1] || '0', 10)) - (parseInt(mb?.[1] || '0', 10));
+    });
+    return collected.map(x => x.msg);
+  }
+
+  // task-314: per-thread sub-directory for forked threads.
+  #threadMsgDir(threadId) {
+    return join(this.#convDir, 'threads', threadId, 'messages');
+  }
+
+  // task-314: next per-thread sequence number, restarting at 1 for each
+  // new thread. Scans the per-thread sub-dir (not the global flat dir).
+  #getNextThreadSeq(threadId) {
+    const cached = this.#nextSeqByThread.get(threadId);
+    if (cached != null) return cached;
+    const dir = this.#threadMsgDir(threadId);
+    let maxSeq = 0;
+    if (existsSync(dir)) {
+      try {
+        for (const f of readdirSync(dir)) {
+          const m = f.match(/^m(\d+)\.md$/);
+          if (m) {
+            const s = parseInt(m[1], 10);
+            if (s > maxSeq) maxSeq = s;
+          }
+        }
+      } catch (err) {
+        if (!isPermissionError(err)) throw err;
+      }
+    }
+    const next = maxSeq + 1;
+    this.#nextSeqByThread.set(threadId, next);
+    return next;
+  }
+
   /**
    * Load messages from a directory, sorted by filename, limited.
    * @param {string} dir

package/unify/session.js

@@ -131,7 +131,13 @@ export async function loadSession(options = {}) {
   // ─── 5b. Initialize thread store (task-299 Phase 1) ────
   //         task-307a: now file-backed under ~/.yeaft/threads/. Passing the
   //         yeaftDir switches on disk persistence; read-only mode is honoured.
-  initThreadStore(yeaftDir, { readOnly: config._readOnly || false, force: true });
+  //         task-318: forward the Unify autoArchiveIdleDays knob so the
+  //         archive pass (owned by task-317) can read it off the store.
+  initThreadStore(yeaftDir, {
+    readOnly: config._readOnly || false,
+    force: true,
+    idleArchiveDays: config.unify?.autoArchiveIdleDays ?? 0,
+  });
 
   // ─── 6. Load skills ────────────────────────────────────
   let skillManager;
@@ -187,6 +193,8 @@ export async function loadSession(options = {}) {
     skillManager,
     mcpManager,
     yeaftDir,
+    // task-318: concurrent-thread cap (UI-adjustable via Settings).
+    maxConcurrent: config.unify?.maxConcurrentThreads ?? null,
   });
   // Seed the main-thread instance so listActive() is non-empty from T=0.
   engineRegistry.ensure(MAIN_THREAD_ID);
@@ -254,6 +262,11 @@ export async function loadSession(options = {}) {
     toolRegistry,
     trace,
     yeaftDir,
+    // task-318 rev-1 fix: expose the live ThreadStore handle so callers
+    // (web-bridge, message-router via ctx) can invoke setIdleArchiveDays()
+    // on the exact instance that's wired into the dispatcher. Without this
+    // export the setter was effectively dead code.
+    threadStore: getThreadStore(),
     status,
     shutdown,
   };

package/unify/threads/engine-registry.js

@@ -29,6 +29,17 @@
 import { MAIN_THREAD_ID } from './store.js';
 import { createEngineInstance } from './engine-instance.js';
 
+/**
+ * Coerce a maxConcurrent input to either a positive integer or null
+ * (meaning "no cap"). Keeps the cap logic branch-free elsewhere.
+ */
+function normaliseMaxConcurrent(n) {
+  if (n === null || n === undefined) return null;
+  const v = Number(n);
+  if (!Number.isFinite(v) || v <= 0) return null;
+  return Math.floor(v);
+}
+
 export class ThreadEngineRegistry {
   /** @type {Map<string, import('./engine-instance.js').EngineInstance>} */
   #instances;
@@ -39,18 +50,33 @@ export class ThreadEngineRegistry {
   /** @type {string} */
   #currentThreadId;
 
+  /**
+   * task-318: soft cap on concurrent live engine instances. When set,
+   * `ensure()` refuses to spawn a new instance beyond this many live
+   * entries. Already-live instances continue to serve query()s — the
+   * cap only gates net-new thread creation. Can be mutated at runtime
+   * by `setMaxConcurrent()` so the Settings UI takes effect without a
+   * session restart.
+   *
+   * Null / 0 / negative → unlimited (treat as "no cap").
+   * @type {number | null}
+   */
+  #maxConcurrent;
+
   /**
    * @param {{
    *   factory: (threadId: string, opts?: object) => import('./engine-instance.js').EngineInstance,
+   *   maxConcurrent?: number | null,
    * }} params
    */
-  constructor({ factory } = {}) {
+  constructor({ factory, maxConcurrent } = {}) {
     if (typeof factory !== 'function') {
       throw new Error('ThreadEngineRegistry: factory function is required');
     }
     this.#instances = new Map();
     this.#factory = factory;
     this.#currentThreadId = MAIN_THREAD_ID;
+    this.#maxConcurrent = normaliseMaxConcurrent(maxConcurrent);
   }
 
   /** @returns {string} */
@@ -83,6 +109,22 @@ export class ThreadEngineRegistry {
     }
     const existing = this.#instances.get(threadId);
     if (existing && !existing.terminated) return existing;
+    // task-318: enforce concurrency cap before spawning a net-new
+    // instance. Replacing a terminated slot for the same threadId does
+    // NOT count against the cap — it's the same thread resuming.
+    if (!existing && this.#maxConcurrent !== null) {
+      const live = this.#countLive();
+      if (live >= this.#maxConcurrent) {
+        const err = new Error(
+          `ThreadEngineRegistry: concurrent thread limit reached (${live}/${this.#maxConcurrent}). ` +
+          `Archive or terminate an existing thread before starting a new one.`
+        );
+        err.code = 'ERR_MAX_CONCURRENT_THREADS';
+        err.limit = this.#maxConcurrent;
+        err.live = live;
+        throw err;
+      }
+    }
     const instance = this.#factory(threadId, opts);
     if (!instance || typeof instance.query !== 'function') {
       throw new Error(`ThreadEngineRegistry.ensure: factory did not return an EngineInstance for ${threadId}`);
@@ -91,6 +133,31 @@ export class ThreadEngineRegistry {
     return instance;
   }
 
+  /**
+   * Count currently non-terminated instances — the denominator for the
+   * concurrency cap. O(n) scan, n is small (≤ 50 in practice).
+   * @returns {number}
+   */
+  #countLive() {
+    let n = 0;
+    for (const inst of this.#instances.values()) {
+      if (!inst.terminated) n += 1;
+    }
+    return n;
+  }
+
+  /**
+   * task-318: read or update the concurrency cap. `setMaxConcurrent(null)`
+   * disables the cap entirely. Existing live instances are NOT terminated
+   * if the cap is lowered below their count — the cap only gates new
+   * `ensure()` calls going forward.
+   * @returns {number | null}
+   */
+  get maxConcurrent() { return this.#maxConcurrent; }
+  setMaxConcurrent(n) {
+    this.#maxConcurrent = normaliseMaxConcurrent(n);
+  }
+
   /**
    * Set the current thread marker. Does not lazy-create — caller must
    * ensure() if they want an instance for an unseen thread.
@@ -188,5 +255,6 @@ export function createThreadEngineRegistry(deps) {
       ...opts,
       threadId,
     }),
+    maxConcurrent: deps?.maxConcurrent ?? null,
   });
 }

package/unify/threads/store.js

@@ -52,6 +52,18 @@ export const MAIN_THREAD_ID = 'main';
 /** Valid thread status values. Mirrors design doc §5. */
 export const THREAD_STATUSES = ['active', 'idle', 'archived'];
 
+/**
+ * task-318: Coerce an idle-archive days input to a non-negative integer
+ * (0 disables the feature). Anything invalid falls through to 0 so a
+ * malformed config can never silently enable auto-archive.
+ */
+function normaliseIdleDays(n) {
+  if (n === null || n === undefined) return 0;
+  const v = Number(n);
+  if (!Number.isFinite(v) || v <= 0) return 0;
+  return Math.floor(v);
+}
+
 /** Debounce window for grouped disk writes. Kept short so tests don't hang. */
 const FLUSH_DEBOUNCE_MS = 8;
 
@@ -68,6 +80,7 @@ const FLUSH_DEBOUNCE_MS = 8;
  * @returns {string}
  */
 function serializeThread(t) {
+  const forkedFrom = serializeForkedFrom(t.forkedFrom);
   const fm = [
     '---',
     `id: ${t.id}`,
@@ -77,6 +90,7 @@ function serializeThread(t) {
     `status: ${t.status}`,
     `archived: ${t.archived ? 'true' : 'false'}`,
     `mergedInto: ${t.mergedInto == null ? 'null' : t.mergedInto}`,
+    `forkedFrom: ${forkedFrom}`,
     `messageCount: ${t.messageCount | 0}`,
     `lastMessageAt: ${t.lastMessageAt == null ? 'null' : t.lastMessageAt}`,
     `lastActivityAt: ${t.lastActivityAt == null ? 'null' : t.lastActivityAt}`,
@@ -91,6 +105,31 @@ function serializeThread(t) {
   return fm.join('\n') + '\n';
 }
 
+/**
+ * Serialise `forkedFrom` as a single-line scalar so the YAML stays flat.
+ * Shape: `{threadId}|{messageId}|{timestamp}`. Null becomes literal `null`.
+ */
+function serializeForkedFrom(ff) {
+  if (!ff || typeof ff !== 'object') return 'null';
+  if (!ff.threadId || !ff.messageId) return 'null';
+  const ts = Number.isFinite(ff.timestamp) ? ff.timestamp : 0;
+  return `${ff.threadId}|${ff.messageId}|${ts}`;
+}
+
+function parseForkedFrom(raw) {
+  if (!raw || raw === 'null') return null;
+  const parts = String(raw).split('|');
+  if (parts.length < 2) return null;
+  const [threadId, messageId, tsStr] = parts;
+  if (!threadId || !messageId) return null;
+  const ts = parseInt(tsStr || '0', 10);
+  return {
+    threadId,
+    messageId,
+    timestamp: Number.isFinite(ts) ? ts : 0,
+  };
+}
+
 function escapeScalar(v) {
   if (v == null) return '';
   // Keep on one physical line; any embedded newline becomes a space so YAML
@@ -134,6 +173,8 @@ function parseThread(raw) {
   if (!THREAD_STATUSES.includes(record.status)) record.status = 'active';
   record.archived = record.status === 'archived';
   if (!('mergedInto' in record)) record.mergedInto = null;
+  // forkedFrom is a packed scalar — decode back to {threadId, messageId, timestamp}.
+  record.forkedFrom = parseForkedFrom(record.forkedFrom);
   record.messageCount = Number.isFinite(record.messageCount) ? record.messageCount : 0;
   record.unread = Number.isFinite(record.unread) ? record.unread : 0;
   record.preview = body;
@@ -246,10 +287,12 @@ export class ThreadStore {
   #dirtyAttachments;
   /** @type {any} NodeJS.Timeout */
   #flushTimer;
+  /** @type {number} task-318: days of inactivity before auto-archive (0 = disabled) */
+  #idleArchiveDays;
 
   /**
    * @param {string} [yeaftDir] — Base ~/.yeaft directory. Omit for in-memory mode.
-   * @param {{ readOnly?: boolean }} [opts]
+   * @param {{ readOnly?: boolean, idleArchiveDays?: number }} [opts]
    */
   constructor(yeaftDir, opts = {}) {
     this.#threads = new Map();
@@ -261,6 +304,11 @@ export class ThreadStore {
     this.#flushTimer = null;
 
     this.#readOnly = !!opts.readOnly;
+    // task-318: idle-archive threshold (days). Consumed by the archive
+    // pass in task-317; here we just accept + expose the knob so the
+    // config plumbing is testable end-to-end today. A value ≤ 0 means
+    // "no auto-archive" (feature disabled).
+    this.#idleArchiveDays = normaliseIdleDays(opts.idleArchiveDays);
     if (yeaftDir) {
       this.#dir = join(yeaftDir, 'threads');
       this.#indexPath = join(this.#dir, 'index.md');
@@ -311,6 +359,7 @@ export class ThreadStore {
       lastActivityAt: null,
       archived: false,
       mergedInto: null,
+      forkedFrom: null,
       unread: 0,
       preview: '',
       ...base,
@@ -457,6 +506,18 @@ export class ThreadStore {
   get currentId() { return this.#currentId; }
   get size() { return this.#threads.size; }
 
+  /**
+   * task-318: idle-archive threshold (days). 0 disables auto-archive.
+   * The actual archive pass is owned by task-317 — this accessor is the
+   * contract between config and that future consumer, plus a write path
+   * so the Settings UI takes effect without restarting the session.
+   * @returns {number}
+   */
+  get idleArchiveDays() { return this.#idleArchiveDays; }
+  setIdleArchiveDays(days) {
+    this.#idleArchiveDays = normaliseIdleDays(days);
+  }
+
   get(id) { return this.#threads.get(id) || null; }
   list() { return [...this.#threads.values()]; }
   has(id) { return this.#threads.has(id); }
@@ -625,6 +686,56 @@ export class ThreadStore {
     return { source, target };
   }
 
+  /**
+   * Fork a new thread from an existing one at a specific message cursor.
+   * ThreadStore only creates the new thread record (with `forkedFrom`
+   * pointing at source + message + timestamp); the actual copying of
+   * messages up to `atMessageId` is done by ConversationStore.copyThreadUpTo
+   * — this keeps the two stores' responsibilities separate.
+   *
+   * Validation:
+   *  - source must exist
+   *  - source must not be archived (forking a dead thread is confusing)
+   *  - atMessageId must be a non-empty string (actual existence check is
+   *    the caller's responsibility, since ThreadStore doesn't own messages)
+   *  - source may itself be a fork (chain is supported)
+   *
+   * @param {string} sourceId
+   * @param {string} atMessageId
+   * @param {{ name?: string, title?: string, timestamp?: number }} [opts]
+   * @returns {Thread} the newly created forked thread record
+   */
+  forkThread(sourceId, atMessageId, opts = {}) {
+    if (!sourceId) throw new Error('forkThread: sourceId required');
+    if (!atMessageId || typeof atMessageId !== 'string') {
+      throw new Error('forkThread: atMessageId required');
+    }
+    const source = this.#threads.get(sourceId);
+    if (!source) throw new Error(`thread not found: ${sourceId}`);
+    if (source.archived || source.status === 'archived') {
+      throw new Error(`forkThread: cannot fork an archived thread (${sourceId})`);
+    }
+    const now = Date.now();
+    const id = `thr-${randomUUID().slice(0, 8)}`;
+    const defaultName = source.id === MAIN_THREAD_ID ? 'inbox-fork' : `${source.name}-fork`;
+    const thread = this.#newThreadRecord({
+      id,
+      name: (opts.name && opts.name.trim()) || defaultName,
+      goal: source.goal || '',
+      parentThreadId: sourceId,
+      createdAt: now,
+      updatedAt: now,
+      forkedFrom: {
+        threadId: sourceId,
+        messageId: atMessageId,
+        timestamp: Number.isFinite(opts.timestamp) ? opts.timestamp : now,
+      },
+    });
+    this.#threads.set(id, thread);
+    this.#markDirty(id);
+    return thread;
+  }
+
   setStatus(id, status) {
     if (!THREAD_STATUSES.includes(status)) {
       throw new Error(`invalid status: ${status}`);

package/unify/web-bridge.js

@@ -73,6 +73,38 @@ function sendUnifyEvent(event) {
   });
 }
 
+/**
+ * task-318 rev-1 fix: install live-setter bridge between the session's
+ * runtime handles (engineRegistry + threadStore) and `ctx.unifyRuntimeSettings`,
+ * which message-router's `update_unify_settings` branch reads. Previously
+ * that object was null and the setters were dead code. Now every
+ * `update_unify_settings` mutation pushes the new caps into the live
+ * session within the same tick — no reload required.
+ *
+ * Exported so tests can drive the same wiring with a mock session.
+ *
+ * @param {import('./session.js').Session} s
+ */
+export function installUnifyRuntimeBridge(s) {
+  if (!s) return;
+  const initialMax = s.engineRegistry?.maxConcurrent ?? null;
+  const initialIdle = s.threadStore?.idleArchiveDays ?? 0;
+  ctx.unifyRuntimeSettings = {
+    get maxConcurrentThreads() { return s.engineRegistry?.maxConcurrent ?? initialMax; },
+    set maxConcurrentThreads(v) {
+      if (typeof s.engineRegistry?.setMaxConcurrent === 'function') {
+        s.engineRegistry.setMaxConcurrent(v);
+      }
+    },
+    get autoArchiveIdleDays() { return s.threadStore?.idleArchiveDays ?? initialIdle; },
+    set autoArchiveIdleDays(v) {
+      if (typeof s.threadStore?.setIdleArchiveDays === 'function') {
+        s.threadStore.setIdleArchiveDays(v);
+      }
+    },
+  };
+}
+
 /**
  * task-301 Part 2: push the full thread list snapshot to the web client.
  * Called after any ThreadStore-mutating tool completes and at turn_end so
@@ -391,6 +423,14 @@ export async function handleUnifyChat(msg) {
         skipSkills: false,
       });
 
+      // task-318 rev-1 fix: expose live setters on ctx so message-router's
+      // update_unify_settings branch can push the new caps into the
+      // registry + thread store without a session reload. Previously this
+      // object was null and setMaxConcurrent/setIdleArchiveDays were dead
+      // code — the config file was updated on disk but the running
+      // session continued with the old caps until next restart.
+      installUnifyRuntimeBridge(session);
+
       // Create a stable conversationId for the Unify session
       unifyConversationId = `unify-${Date.now()}`;
 
@@ -626,6 +666,75 @@ export function handleUnifyMergeThread(msg) {
   sendThreadListUpdate();
 }
 
+/**
+ * task-314: fork a new thread from an existing one at a specific message.
+ * Copies every message up to (and including) `atMessageId` from the source
+ * thread onto a fresh thread, stamps `forkedFrom` on the new thread record,
+ * and broadcasts `thread_forked` + refreshed thread list. The source is not
+ * modified.
+ *
+ * @param {{ sourceThreadId: string, atMessageId: string, name?: string }} msg
+ */
+export function handleUnifyForkThread(msg) {
+  if (!session) {
+    console.warn('[Unify] unify_fork_thread received before session init — ignored');
+    return;
+  }
+  const { sourceThreadId, atMessageId, name } = msg || {};
+  if (!sourceThreadId || !atMessageId) {
+    sendUnifyEvent({
+      type: 'thread_fork_failed',
+      sourceThreadId,
+      atMessageId,
+      error: 'sourceThreadId and atMessageId required',
+    });
+    return;
+  }
+
+  let copied = 0;
+  let newThread;
+  try {
+    // 1. Create the fork record on ThreadStore (sets forkedFrom pointer).
+    const store = session.threadStore || getThreadStore();
+    newThread = store.forkThread(sourceThreadId, atMessageId, { name });
+    // 2. Copy messages up to the cursor (inclusive) into the new thread.
+    if (session.conversationStore && typeof session.conversationStore.copyThreadUpTo === 'function') {
+      copied = session.conversationStore.copyThreadUpTo(
+        sourceThreadId,
+        newThread.id,
+        atMessageId,
+      );
+    }
+    // 3. Roll cached counters on the new thread so the sidebar shows the
+    // copied messages without needing a rebuild pass.
+    if (copied > 0) {
+      newThread.messageCount = copied;
+      newThread.lastMessageAt = Date.now();
+      newThread.lastActivityAt = newThread.lastMessageAt;
+    }
+    // 4. Flush so the new thread is durable before the UI refreshes.
+    if (typeof store.flush === 'function') store.flush();
+  } catch (err) {
+    sendUnifyEvent({
+      type: 'thread_fork_failed',
+      sourceThreadId,
+      atMessageId,
+      error: err?.message || String(err),
+    });
+    return;
+  }
+
+  // 5. Broadcast the fork + refreshed thread list.
+  sendUnifyEvent({
+    type: 'thread_forked',
+    sourceThreadId,
+    targetThreadId: newThread.id,
+    forkedAtMessageId: atMessageId,
+    copiedMessages: copied,
+  });
+  sendThreadListUpdate();
+}
+
 /**
  * Handle model switch from the web UI.
  * Updates Engine's config so the next query uses the new model.
@@ -668,6 +777,8 @@ export async function handleUnifyLoadHistory(msg) {
       skipMCP: false,
       skipSkills: false,
     });
+    // task-318 rev-1 fix: wire live setters; see handleUnifyChat.
+    installUnifyRuntimeBridge(session);
 
     unifyConversationId = `unify-${Date.now()}`;
 
@@ -742,6 +853,8 @@ export async function resetUnifySession() {
       skipMCP: false,
       skipSkills: false,
     });
+    // task-318 rev-1 fix: wire live setters; see handleUnifyChat.
+    installUnifyRuntimeBridge(session);
 
     unifyConversationId = `unify-${Date.now()}`;