@yeaft/webchat-agent 1.0.330 → 1.0.332

package/cli.js

@@ -6,13 +6,13 @@
 import { assertNodeVersion } from './check-node-version.js';
 assertNodeVersion({ component: '@yeaft/webchat-agent' });
 
-import { execSync, spawn } from 'child_process';
+import { execFileSync, execSync, spawn } from 'child_process';
 import { createInterface } from 'readline/promises';
 import { stdin as input, stdout as output } from 'process';
-import { readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { readFileSync, mkdirSync } from 'fs';
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
-import { platform, homedir } from 'os';
+import { platform } from 'os';
 import {
   addOrUpdateProvider,
   formatLlmConfig,
@@ -29,12 +29,22 @@ import {
   discoverOpenAICompatibleModels,
   GITHUB_COPILOT_PROVIDER,
 } from './llm-model-discovery.js';
-import { applyAgentIdentityToEnv, warnDeprecatedInstanceArg } from './service/config.js';
+import {
+  DEFAULT_INSTANCE_ID,
+  applyAgentIdentityToEnv,
+  getConfigDir,
+  getPm2AppName,
+  resolveServiceInstanceId,
+  warnDeprecatedInstanceArg,
+} from './service/config.js';
 import {
   buildUpgradeInstallCommand,
   buildUpgradeMetadataUrl,
   buildUpgradeVersionCommand,
   launchWindowsUpgradeScript,
+  prepareWindowsUpgradeRunner,
+  resolveWindowsNpmCliPath,
+  resolveWindowsPm2CliPath,
 } from './upgrade-command.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -60,7 +70,7 @@ if (command === 'doctor') {
     process.exit(1);
   }
 } else if (command === 'upgrade') {
-  await upgrade();
+  await upgrade(subArgs);
 } else if (command === '--version' || command === '-v') {
   console.log(pkg.version);
 } else if (command === '--help' || command === '-h') {
@@ -88,7 +98,7 @@ function printHelp() {
     yeaft-agent logs [options]         View service logs (follow mode)
     yeaft-agent doctor                 Diagnose service configuration
     yeaft-agent llm <command>          Configure local Yeaft LLM providers/models
-    yeaft-agent upgrade                Upgrade to latest version
+    yeaft-agent upgrade [--name <id>]  Upgrade and restart the selected service
     yeaft-agent --version              Show version
 
   Options:
@@ -486,7 +496,9 @@ async function checkForUpdates() {
   }
 }
 
-async function upgrade() {
+async function upgrade(args = []) {
+  warnDeprecatedInstanceArg(args);
+  const instanceId = resolveServiceInstanceId(args, process.env, { management: true });
   console.log(`Current version: ${pkg.version}`);
   console.log('Checking for updates...');
 
@@ -500,9 +512,9 @@ async function upgrade() {
 
     if (platform() === 'win32') {
       // On Windows, the current process locks its own files. npm cannot overwrite
-      // them while this process is running. Spawn a detached bat script that waits
-      // for us to exit, then runs npm install, then optionally restarts the service.
-      await upgradeWindows(latest);
+      // them while this process is running. Spawn a detached Node runner that waits
+      // for us to exit, then runs npm install and optionally restarts the service.
+      await upgradeWindows(latest, instanceId);
     } else {
       execSync(buildUpgradeInstallCommand(`${pkg.name}@${latest}`), { stdio: 'inherit' });
       console.log(`Successfully upgraded to ${latest}`);
@@ -526,114 +538,72 @@ async function upgrade() {
   }
 }
 
-async function upgradeWindows(latestVersion) {
-  const configDir = join(process.env.APPDATA || join(homedir(), 'AppData', 'Roaming'), 'yeaft-agent');
-  mkdirSync(configDir, { recursive: true });
+async function upgradeWindows(latestVersion, instanceId = DEFAULT_INSTANCE_ID) {
+  const configDir = getConfigDir(instanceId);
+  const upgradeDir = join(configDir, 'upgrade-runtime');
   const logDir = join(configDir, 'logs');
   mkdirSync(logDir, { recursive: true });
-  const batPath = join(configDir, 'upgrade-cli.bat');
-  const handoffPath = join(configDir, 'upgrade-cli.started');
+
+  const runnerPath = join(upgradeDir, 'windows-upgrade-runner.js');
+  const commandPath = join(upgradeDir, 'upgrade-command.js');
+  const payloadPath = join(upgradeDir, 'payload.json');
+  const handoffPath = join(upgradeDir, 'started');
   const logPath = join(logDir, 'upgrade.log');
-  const pid = process.pid;
-  const pkgSpec = `${pkg.name}@${latestVersion}`;
+  const ecosystemPath = join(configDir, 'ecosystem.config.cjs');
+  const pm2AppName = getPm2AppName(instanceId);
+  const npmCliPath = resolveWindowsNpmCliPath(process.execPath);
+  if (!npmCliPath) throw new Error('npm JavaScript CLI entry point could not be resolved');
+  const pm2CliPath = resolveWindowsPm2CliPath(process.execPath);
 
-  // Detect PM2 now, but do not delete it until the updater confirms handoff.
   let isPm2 = false;
-  const ecoPath = join(configDir, 'ecosystem.config.cjs');
-  try {
-    const pm2List = execSync('pm2 jlist', { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
-    const apps = JSON.parse(pm2List);
-    isPm2 = Array.isArray(apps) && apps.some(app => app.name === 'yeaft-agent');
-  } catch {
-    // PM2 not installed or not managing yeaft-agent — continue
-  }
-
-  const batLines = [
-    '@echo off',
-    'setlocal',
-    `set PID=${pid}`,
-    `set PKG=${pkgSpec}`,
-    `set LOGFILE=${logPath}`,
-    `set HANDOFF=${handoffPath}`,
-    `set MAX_WAIT=30`,
-    `set COUNT=0`,
-    '',
-    ':: Change to temp dir to avoid EBUSY on cwd',
-    'cd /d "%TEMP%"',
-    '',
-    'echo started>"%HANDOFF%"',
-    'echo [Upgrade] Started at %date% %time% > "%LOGFILE%"',
-    `echo [Upgrade] Version: ${pkg.version} -> ${latestVersion} >> "%LOGFILE%"`,
-    `echo [Upgrade] PM2 managed: ${isPm2 ? 'yes (deleted pre-exit)' : 'no'} >> "%LOGFILE%"`,
-    'echo [Upgrade] Waiting for CLI process (PID %PID%) to exit... >> "%LOGFILE%"',
-    '',
-    ':WAIT_LOOP',
-    'tasklist /FI "PID eq %PID%" /NH 2>NUL | findstr /C:"%PID%" >NUL',
-    'if errorlevel 1 goto PID_EXITED',
-    'set /A COUNT+=1',
-    'if %COUNT% GEQ %MAX_WAIT% (',
-    '  echo [Upgrade] Timeout waiting for PID %PID% to exit after %MAX_WAIT%s >> "%LOGFILE%"',
-    '  goto PID_EXITED',
-    ')',
-    'ping -n 3 127.0.0.1 >NUL',
-    'goto WAIT_LOOP',
-    ':PID_EXITED',
-    '',
-    ':: Extra wait for file locks to release',
-    'echo [Upgrade] Process exited at %time%, waiting for file locks... >> "%LOGFILE%"',
-    'ping -n 5 127.0.0.1 >NUL',
-    '',
-    'echo [Upgrade] Running npm install -g %PKG%... >> "%LOGFILE%"',
-    `call ${buildUpgradeInstallCommand('%PKG%')} >> "%LOGFILE%" 2>&1`,
-    'if not "%errorlevel%"=="0" (',
-    '  echo [Upgrade] npm install failed with exit code %errorlevel% at %time% >> "%LOGFILE%"',
-    '  goto PM2_RESTART',
-    ')',
-    'echo [Upgrade] npm install succeeded at %time% >> "%LOGFILE%"',
-  ];
-
-  // PM2 re-registration after successful upgrade
-  batLines.push(
-    '',
-    ':PM2_RESTART',
-  );
-  if (isPm2) {
-    batLines.push(
-      'echo [Upgrade] Re-registering agent via PM2... >> "%LOGFILE%"',
-      `if exist "${ecoPath}" (`,
-      `  call pm2 start "${ecoPath}" >> "%LOGFILE%" 2>&1`,
-      '  call pm2 save >> "%LOGFILE%" 2>&1',
-      '  echo [Upgrade] PM2 app re-registered at %time% >> "%LOGFILE%"',
-      ') else (',
-      '  echo [Upgrade] WARNING: ecosystem.config.cjs not found, PM2 not restarted >> "%LOGFILE%"',
-      ')',
-    );
+  if (pm2CliPath) {
+    try {
+      const apps = JSON.parse(execFileSync(process.execPath, [pm2CliPath, 'jlist'], { encoding: 'utf8' }));
+      isPm2 = Array.isArray(apps) && apps.some(app => app.name === pm2AppName);
+    } catch {}
   }
 
-  batLines.push(
-    '',
-    'echo [Upgrade] Finished at %time% >> "%LOGFILE%"',
-    ':CLEANUP',
-    'del /F /Q "%HANDOFF%" 2>NUL',
-    `del /F /Q "${batPath}" 2>NUL`,
-  );
-
-  writeFileSync(batPath, batLines.join('\r\n'));
+  const payload = {
+    parentPid: process.pid,
+    packageSpec: `${pkg.name}@${latestVersion}`,
+    globalInstall: true,
+    installDir: dirname(dirname(__dirname)),
+    logPath,
+    handoffPath,
+    runnerPath,
+    commandPath,
+    payloadPath,
+    nodePath: process.execPath,
+    npmCliPath,
+    pm2CliPath: isPm2 ? pm2CliPath : null,
+    ecosystemPath: isPm2 ? ecosystemPath : null,
+  };
+  prepareWindowsUpgradeRunner({
+    sourceRunnerPath: join(__dirname, 'windows-upgrade-runner.js'),
+    sourceCommandPath: join(__dirname, 'upgrade-command.js'),
+    runnerPath,
+    commandPath,
+    payloadPath,
+    payload,
+  });
 
   const launcher = await launchWindowsUpgradeScript({
-    batPath,
+    nodePath: process.execPath,
+    runnerPath,
+    payloadPath,
+    logPath,
     handoffPath,
     spawnProcess: spawn,
     onHandoff: isPm2
       ? () => {
-          execSync('pm2 delete yeaft-agent', { stdio: 'pipe' });
-          console.log('PM2 app deleted after upgrade handoff.');
+          execFileSync(process.execPath, [pm2CliPath, 'delete', pm2AppName], { stdio: 'pipe' });
+          console.log(`PM2 app ${pm2AppName} deleted after upgrade handoff.`);
         }
       : undefined,
   });
 
-  console.log(`Upgrade script spawned via ${launcher}.`);
-  console.log(`This process will exit now. The upgrade will proceed after exit.`);
+  console.log(`Upgrade runner spawned via ${launcher}.`);
+  console.log('This process will exit now. The upgrade will proceed after exit.');
   console.log(`Check upgrade log: ${logPath}`);
   process.exit(0);
 }

package/connection/upgrade.js

@@ -1,5 +1,6 @@
 import { execFile, execFileSync, spawn } from 'child_process';
 import { writeFileSync, mkdirSync, existsSync } from 'fs';
+import { fileURLToPath } from 'url';
 import { join, dirname } from 'path';
 import { platform, homedir } from 'os';
 import ctx from '../context.js';
@@ -7,8 +8,10 @@ import { getConfigDir, getServiceName, getPm2AppName, getLaunchdPlistPath, DEFAU
 import {
   buildUpgradeInstallCommand,
   buildUpgradeMetadataArgs,
-  buildUpgradeUpdateCommand,
   launchWindowsUpgradeScript,
+  prepareWindowsUpgradeRunner,
+  resolveWindowsNpmCliPath,
+  resolveWindowsPm2CliPath,
 } from '../upgrade-command.js';
 import { sendToServer } from './buffer.js';
 import { stopAgentHeartbeat } from './heartbeat.js';
@@ -53,11 +56,6 @@ export function isUpgradeAvailable(currentVersion, latestVersion) {
   return cmpTuple(latest, current) > 0;
 }
 
-/** Build the detached Windows npm invocation used after the Agent exits. */
-export function buildWindowsUpgradeCommand() {
-  return `call ${buildUpgradeUpdateCommand('%PKG%')}`;
-}
-
 // Shared cleanup logic for restart/upgrade
 function cleanupAndExit(exitCode) {
   setTimeout(async () => {
@@ -268,115 +266,65 @@ export async function handleUpgradeAgent() {
 }
 
 async function spawnWindowsUpgradeScript(pkgName, installDir, isGlobalInstall, latestVersion, instanceId = DEFAULT_INSTANCE_ID) {
-  const pid = process.pid;
   const configDir = getConfigDir(instanceId);
-  mkdirSync(configDir, { recursive: true });
+  const upgradeDir = join(configDir, 'upgrade-runtime');
   const logDir = join(configDir, 'logs');
   mkdirSync(logDir, { recursive: true });
-  const batPath = join(configDir, 'upgrade.bat');
-  const handoffPath = join(configDir, 'upgrade.started');
+
+  const runnerPath = join(upgradeDir, 'windows-upgrade-runner.js');
+  const commandPath = join(upgradeDir, 'upgrade-command.js');
+  const payloadPath = join(upgradeDir, 'payload.json');
+  const handoffPath = join(upgradeDir, 'started');
   const logPath = join(logDir, 'upgrade.log');
+  const ecosystemPath = join(configDir, 'ecosystem.config.cjs');
+  const npmCliPath = resolveWindowsNpmCliPath(process.execPath);
+  if (!npmCliPath) throw new Error('npm JavaScript CLI entry point could not be resolved');
   const isPm2 = !!process.env.pm_id;
-  const installDirWin = installDir.replace(/\//g, '\\');
-  const ecoPath = join(configDir, 'ecosystem.config.cjs').replace(/\//g, '\\');
-
-  const pm2Win = pm2Path.replace(/\//g, '\\');
-
-  const batLines = [
-    '@echo off',
-    'setlocal',
-    `set PID=${pid}`,
-    `set PKG=${pkgName}`,
-    `set INSTALL_DIR=${installDirWin}`,
-    `set LOGFILE=${logPath}`,
-    `set HANDOFF=${handoffPath}`,
-    `set MAX_WAIT=30`,
-    `set COUNT=0`,
-    '',
-    ':: Change to temp dir to avoid EBUSY on cwd',
-    'cd /d "%TEMP%"',
-    '',
-    'echo started>"%HANDOFF%"',
-    'echo [Upgrade] Started at %date% %time% > "%LOGFILE%"',
-    `echo [Upgrade] Version: ${ctx.agentVersion} -> ${latestVersion} >> "%LOGFILE%"`,
-    `echo [Upgrade] PM2 managed: ${isPm2 ? 'yes (deleted pre-exit)' : 'no'} >> "%LOGFILE%"`,
-    `echo [Upgrade] Install dir: ${installDirWin} >> "%LOGFILE%"`,
-  ];
-
-  // Wait for old process to exit (PM2 already deleted before exit, so no auto-restart race)
-  batLines.push(
-    'echo [Upgrade] Waiting for PID %PID% to exit... >> "%LOGFILE%"',
-    ':WAIT_LOOP',
-    'tasklist /FI "PID eq %PID%" /NH 2>NUL | findstr /C:"%PID%" >NUL',
-    'if errorlevel 1 goto PID_EXITED',
-    'set /A COUNT+=1',
-    'if %COUNT% GEQ %MAX_WAIT% (',
-    '  echo [Upgrade] Timeout waiting for PID %PID% to exit after %MAX_WAIT%s >> "%LOGFILE%"',
-    '  goto PID_EXITED',
-    ')',
-    'ping -n 3 127.0.0.1 >NUL',
-    'goto WAIT_LOOP',
-    ':PID_EXITED',
-  );
-
-  // No need to pm2 stop — PM2 app was already deleted before process exit.
-  // Wait extra time for file locks to fully release.
-  batLines.push(
-    'echo [Upgrade] Process exited at %time%, waiting for file locks... >> "%LOGFILE%"',
-    'ping -n 5 127.0.0.1 >NUL',
-  );
-
-  // Run npm only after the Agent has released its package files. The old
-  // package-copy worker performed a second dependency install, hid failures,
-  // and bypassed npm's supported global-update transaction.
-  batLines.push(
-    'echo [Upgrade] Running npm update at %time%... >> "%LOGFILE%"',
-    `${buildWindowsUpgradeCommand()} >> "%LOGFILE%" 2>&1`,
-    'if not "%errorlevel%"=="0" (',
-    '  echo [Upgrade] npm update failed with exit code %errorlevel% at %time% >> "%LOGFILE%"',
-    '  goto RESTART_SERVICE',
-    ')',
-    'echo [Upgrade] npm update succeeded at %time% >> "%LOGFILE%"',
-  );
-
-  batLines.push(':RESTART_SERVICE');
-
-  if (isPm2) {
-    // Re-register and start via ecosystem config (PM2 app was deleted pre-exit)
-    batLines.push(
-      'echo [Upgrade] Re-registering agent via PM2... >> "%LOGFILE%"',
-      `if exist "${ecoPath}" (`,
-      `  call "${pm2Win}" start "${ecoPath}" >> "%LOGFILE%" 2>&1`,
-      `  call "${pm2Win}" save >> "%LOGFILE%" 2>&1`,
-      '  echo [Upgrade] PM2 app re-registered at %time% >> "%LOGFILE%"',
-      ') else (',
-      '  echo [Upgrade] WARNING: ecosystem.config.cjs not found, PM2 not restarted >> "%LOGFILE%"',
-      ')',
-    );
+  const pm2CliPath = isPm2 ? resolveWindowsPm2CliPath(process.execPath) : null;
+  if (isPm2 && !pm2CliPath) {
+    throw new Error('PM2 manages this Agent, but its JavaScript CLI entry point could not be resolved');
   }
 
-  batLines.push(
-    '',
-    'echo [Upgrade] Finished at %time% >> "%LOGFILE%"',
-    'del /F /Q "%HANDOFF%" 2>NUL',
-    `del /F /Q "${batPath}"`,
-  );
-
-  writeFileSync(batPath, batLines.join('\r\n'));
+  const payload = {
+    parentPid: process.pid,
+    packageSpec: `${pkgName}@${latestVersion}`,
+    globalInstall: isGlobalInstall,
+    installDir,
+    logPath,
+    handoffPath,
+    runnerPath,
+    commandPath,
+    payloadPath,
+    nodePath: process.execPath,
+    npmCliPath,
+    pm2CliPath,
+    ecosystemPath: isPm2 ? ecosystemPath : null,
+  };
+  prepareWindowsUpgradeRunner({
+    sourceRunnerPath: fileURLToPath(new URL('../windows-upgrade-runner.js', import.meta.url)),
+    sourceCommandPath: fileURLToPath(new URL('../upgrade-command.js', import.meta.url)),
+    runnerPath,
+    commandPath,
+    payloadPath,
+    payload,
+  });
 
   const launcher = await launchWindowsUpgradeScript({
-    batPath,
+    nodePath: process.execPath,
+    runnerPath,
+    payloadPath,
+    logPath,
     handoffPath,
     spawnProcess: spawn,
     onHandoff: isPm2
       ? () => {
-          execFileSync(pm2Path, ['delete', getPm2AppName(instanceId)], { stdio: 'pipe', env: safeEnv, ...shellOpt });
+          execFileSync(process.execPath, [pm2CliPath, 'delete', getPm2AppName(instanceId)], { stdio: 'pipe', env: safeEnv });
           console.log('[Agent] PM2 app deleted after upgrade handoff');
         }
       : undefined,
   });
 
-  console.log(`[Agent] Spawned upgrade via ${launcher} (PID wait for ${pid}, pm2=${isPm2}, dir=${installDir}): ${batPath}`);
+  console.log(`[Agent] Spawned Windows upgrade runner via ${launcher} (pm2=${isPm2}, dir=${installDir})`);
   await sendToServer({ type: 'upgrade_agent_ack', success: true, version: latestVersion, pendingRestart: true });
 }
 

package/local-runtime/server/db/session-ui-metadata-db.js

@@ -1,5 +1,41 @@
 import { stmts, transaction } from './connection.js';
 
+export function applySessionUiMetadataUpdates(userId, updates, now = Date.now()) {
+  if (!userId || !Array.isArray(updates) || updates.length === 0) return false;
+  for (const update of updates) {
+    if (!update?.catalogKey) throw new Error('Catalog metadata update requires catalogKey');
+    stmts.upsertSessionUiMetadata.run(
+      userId,
+      update.catalogKey,
+      update.pinned === true ? 1 : 0,
+      Number.isFinite(update.sortRank) ? update.sortRank : null,
+      now,
+    );
+    if (update.runtimeProvider === 'yeaft') {
+      const result = stmts.setYeaftSessionPinnedForAgent.run(
+        update.pinned === true ? 1 : 0,
+        now,
+        update.sessionId,
+        userId,
+        update.agentId,
+      );
+      if (result.changes !== 1) throw new Error('Yeaft Session identity changed during metadata update');
+    } else if (update.runtimeProvider === 'claude-code' || update.runtimeProvider === 'copilot') {
+      const result = stmts.updateSessionPinnedForRoute.run(
+        update.pinned === true ? 1 : 0,
+        now,
+        update.sessionId,
+        update.agentId,
+        userId,
+      );
+      if (result.changes !== 1) throw new Error('Chat Session identity changed during metadata update');
+    } else {
+      throw new Error('Unknown Session runtime provider during metadata update');
+    }
+  }
+  return true;
+}
+
 function mapRow(row) {
   if (!row) return null;
   return {
@@ -36,39 +72,7 @@ export const sessionUiMetadataDb = {
 
   applyBatch(userId, updates) {
     if (!userId || !Array.isArray(updates) || updates.length === 0) return false;
-    return transaction(() => {
-      const now = Date.now();
-      for (const update of updates) {
-        if (!update?.catalogKey) throw new Error('Catalog metadata update requires catalogKey');
-        stmts.upsertSessionUiMetadata.run(
-          userId,
-          update.catalogKey,
-          update.pinned === true ? 1 : 0,
-          Number.isFinite(update.sortRank) ? update.sortRank : null,
-          now,
-        );
-        if (update.runtimeProvider === 'yeaft') {
-          const result = stmts.setYeaftSessionPinnedForAgent.run(
-            update.pinned === true ? 1 : 0,
-            now,
-            update.sessionId,
-            userId,
-            update.agentId,
-          );
-          if (result.changes !== 1) throw new Error('Yeaft Session identity changed during metadata update');
-        } else if (update.runtimeProvider === 'claude-code' || update.runtimeProvider === 'copilot') {
-          const result = stmts.updateSessionPinnedForRoute.run(
-            update.pinned === true ? 1 : 0,
-            now,
-            update.sessionId,
-            update.agentId,
-            userId,
-          );
-          if (result.changes !== 1) throw new Error('Chat Session identity changed during metadata update');
-        }
-      }
-      return true;
-    })();
+    return transaction(() => applySessionUiMetadataUpdates(userId, updates))();
   },
 
   delete(userId, catalogKey) {

package/local-runtime/server/db/yeaft-project-db.js

@@ -1,5 +1,6 @@
 import { randomUUID } from 'crypto';
 import { stmts, transaction } from './connection.js';
+import { applySessionUiMetadataUpdates } from './session-ui-metadata-db.js';
 
 export class YeaftProjectDbError extends Error {
   constructor(code, message) {
@@ -137,7 +138,12 @@ export const yeaftProjectDb = {
     return { projectId: id };
   },
 
-  moveSession(userId, { agentId, sessionId, projectId = null } = {}) {
+  moveSession(userId, {
+    agentId,
+    sessionId,
+    projectId = null,
+    catalogUpdates = null,
+  } = {}) {
     const ownerId = requireUserId(userId);
     const targetAgentId = requireId(agentId, 'invalid_agent_id', 'Agent id');
     const targetSessionId = requireId(sessionId, 'invalid_session_id', 'Session id');
@@ -145,8 +151,12 @@ export const yeaftProjectDb = {
       ? null
       : requireId(projectId, 'invalid_project_id', 'Project id');
     if (targetProjectId) requireProject(ownerId, targetProjectId);
+    if (catalogUpdates !== null && (!Array.isArray(catalogUpdates) || catalogUpdates.length === 0)) {
+      throw new YeaftProjectDbError('invalid_catalog_order', 'Complete catalog order is required');
+    }
 
-    transaction(() => {
+    return transaction(() => {
+      const now = Date.now();
       stmts.deleteYeaftProjectSessionMembership.run(ownerId, targetAgentId, targetSessionId);
       if (targetProjectId) {
         stmts.insertYeaftProjectSessionMembership.run(
@@ -154,11 +164,12 @@ export const yeaftProjectDb = {
           targetProjectId,
           targetAgentId,
           targetSessionId,
-          Date.now(),
+          now,
         );
       }
+      if (catalogUpdates) applySessionUiMetadataUpdates(ownerId, catalogUpdates, now);
+      return { agentId: targetAgentId, sessionId: targetSessionId, projectId: targetProjectId };
     })();
-    return { agentId: targetAgentId, sessionId: targetSessionId, projectId: targetProjectId };
   },
 
   reconcileAgentSessions(userId, agentId, sessionIds) {

package/local-runtime/server/handlers/client-conversation.js

@@ -11,7 +11,7 @@ import {
 import { agents, pendingFiles, trackUserTurn, webClients } from '../context.js';
 import {
   sendToWebClient, forwardToAgent,
-  broadcastAgentList, broadcastSessionCatalog,
+  broadcastAgentList, broadcastSessionCatalog, buildSessionCatalog,
   verifyConversationOwnership, verifyAgentOwnership
 } from '../ws-utils.js';
 import { routeSessionPin } from './session-pin-router.js';
@@ -100,6 +100,35 @@ function persistSessionPin(userId, routeRef, pinned) {
   }]);
 }
 
+function catalogOrderUpdates(client, items) {
+  if (!client?.userId || !Array.isArray(items) || items.length === 0) return null;
+  const canonical = buildSessionCatalog(client.userId, client.role);
+  if (canonical.length !== items.length) return null;
+  const canonicalByKey = new Map(canonical.map(row => [row.catalogKey, row]));
+  if (canonicalByKey.size !== canonical.length) return null;
+
+  const seen = new Set();
+  const updates = [];
+  for (const [sortRank, item] of items.entries()) {
+    const row = canonicalByKey.get(item?.catalogKey);
+    const routeRef = item?.routeRef;
+    if (!row || seen.has(item.catalogKey)
+        || routeRef?.runtimeProvider !== row.routeRef?.runtimeProvider
+        || routeRef?.agentId !== row.routeRef?.agentId
+        || routeRef?.sessionId !== row.routeRef?.sessionId) return null;
+    seen.add(item.catalogKey);
+    updates.push({
+      catalogKey: row.catalogKey,
+      runtimeProvider: row.routeRef.runtimeProvider,
+      agentId: row.routeRef.agentId,
+      sessionId: row.routeRef.sessionId,
+      pinned: row.pinned === true,
+      sortRank,
+    });
+  }
+  return seen.size === canonical.length ? updates : null;
+}
+
 export function groupOnlineYeaftSessions(rows, agentRegistry = agents) {
   const byAgent = {};
   for (const row of Array.isArray(rows) ? rows : []) {
@@ -522,43 +551,9 @@ export async function handleClientConversation(clientId, client, msg, checkAgent
 
     case 'reorder_session_catalog': {
       if (!client.userId || !Array.isArray(msg.sessions)) break;
-      const updates = [];
-      for (const [index, item] of msg.sessions.entries()) {
-        const routeRef = item?.routeRef;
-        if (!item?.catalogKey || !routeRef?.runtimeProvider) { updates.length = 0; break; }
-        const { runtimeProvider, agentId, sessionId } = routeRef;
-        let expectedCatalogKey = null;
-        if (runtimeProvider === 'yeaft') {
-          if (!agentId || !sessionId || !yeaftSessionDb.getForAgent(client.userId, agentId, sessionId)) {
-            updates.length = 0;
-            break;
-          }
-          expectedCatalogKey = yeaftCatalogKey(agentId, sessionId);
-        } else if (runtimeProvider === 'claude-code' || runtimeProvider === 'copilot') {
-          if (!agentId || !sessionId
-            || (!CONFIG.skipAuth && !verifyConversationOwnership(sessionId, client.userId, client.role))) {
-            updates.length = 0;
-            break;
-          }
-          const row = sessionDb.get(sessionId);
-          if (!row || row.agent_id !== agentId || (row.provider || 'claude-code') !== runtimeProvider) {
-            updates.length = 0;
-            break;
-          }
-          expectedCatalogKey = chatCatalogKey(sessionId);
-        }
-        if (expectedCatalogKey !== item.catalogKey) { updates.length = 0; break; }
-        updates.push({
-          catalogKey: expectedCatalogKey,
-          runtimeProvider,
-          agentId,
-          sessionId,
-          pinned: item.pinned === true,
-          sortRank: index,
-        });
-      }
+      const updates = catalogOrderUpdates(client, msg.sessions);
       let persisted = false;
-      if (updates.length === msg.sessions.length && updates.length > 0) {
+      if (updates) {
         try {
           persisted = sessionUiMetadataDb.applyBatch(client.userId, updates);
           if (persisted) await broadcastSessionCatalog(client.userId);
@@ -1340,10 +1335,19 @@ export async function handleClientConversation(clientId, client, msg, checkAgent
             error.code = 'session_archived';
             throw error;
           }
+          const catalogUpdates = msg.catalogOrder === undefined
+            ? null
+            : catalogOrderUpdates(client, msg.catalogOrder);
+          if (msg.catalogOrder !== undefined && !catalogUpdates) {
+            const error = new Error('Complete canonical catalog order is required');
+            error.code = 'invalid_catalog_order';
+            throw error;
+          }
           result = yeaftProjectDb.moveSession(client.userId, {
             agentId,
             sessionId,
             projectId: msg.projectId || null,
+            catalogUpdates,
           });
         } else {
           throw new Error('Unknown Project operation');